proposal: kickstart via desktop app (electron)

[sabbour-squad-lead]

Summary

This draft PR moves the Electron Desktop design proposal into the repository as a committed markdown file (docs/design/electron-desktop-dp.md). The DP covers:

• Provider matrix: P0 BYOK / P1 Copilot SDK strategy
• Auth wizard: Three-path authentication (Azure CLI, GitHub Copilot, BYOK)
• Interop analysis: OpenAI Agents vs Copilot SDK compatibility
• Dual-runtime strategy: Option 1 vs Option 3 (shim) comparison
• SDK validation: Node.js SDK source validation (§18.9)

Status

🚧 Work in progress (rev 6). Additive deployment — SWA + Functions contract is frozen. Filed as an in-repo DP rather than a GitHub issue so edits flow through normal PR review.

This is WIP — still iterating on Option 1 vs Option 3 (shim) verdict. Round 5 re-evaluation pending and will land as a follow-up commit.

Design Decisions

See .squad/decisions.md for prior decisions related to this effort.

---

🤖 Created by sabbour-squad-lead

[github-actions]

👀 Squad review trail

Current head: 155d694
Last update: New commits landed; the visible trail now points at the current head.
Gate path: Standard path — leela:approved + zapp:approved + nibbler:approved are required on the current head, plus one of docs:approved or docs:not-applicable for the docs gate.
Gate snapshot: ⏳ Missing docs marker (one of docs:approved or docs:not-applicable) on the current head, plus leela:approved + nibbler:approved + zapp:approved.
Reviewer labels

• Leela: ⏳ awaiting leela:approved
• Zapp: ⏳ awaiting zapp:approved
• Nibbler: ⏳ awaiting nibbler:approved
• Docs: ⏳ awaiting docs:approved or docs:not-applicable
  Active labels
• No active squad review labels.

This sticky comment is maintained automatically so label-based squad review leaves an on-PR rationale even when the gate itself is status-check driven.

[sabbour-squad-lead]

Rev 7 — §18.10 Option 3 Revisited (Round 5 Complete)

Verdict: RECOMMEND Option 3 (KickstartRunner shim) ✅

Key Changes

Round 5 re-evaluated the shim option with the corrected Node.js SDK facts from Round 4. Four of the six "leaky abstraction" surfaces identified in rev 5 are now eliminated by native Copilot SDK features:

Leakage Surface	Rev 5 Status	Rev 6-7 Status
Handoff model mismatch	LEAKS	ELIMINATED — customAgents[] with native lifecycle
Tool param format (Zod vs JSON Schema)	LEAKS	ELIMINATED — SDK auto-converts
outputType (structured output)	LEAKS	REDUCED — resolveOutputText() fallback handles it
Streaming event model	LEAKS	REDUCED — assistant.message_delta identified
Agent construction	LEAKS	ELIMINATED — direct customAgents mapping
OTel bridge	LEAKS	REDUCED — SDK handles internally

Surface area: 6 → 2 real leaks.

Architecture Impact

• Shim total: ~700 lines (vs ~1,160 for Option 1)
• Pack tool changes: Zero — no new pack-side work
• Maintenance: Lower in 6 of 8 scenarios
• Day 1 value: Ahmed's requirement IS two simultaneous runtimes (SWA + Electron); shim pays off immediately, not speculatively

Key Finding

Rev 5 rejected the shim as "premature abstraction that only pays off with a 3rd runtime." That was wrong — the dual-runtime requirement exists today, so the abstraction is justified from day 1.

Full details: See §18.10 in the DP (architectecture diagram, AgentBackend interface spec, OpenAIBackend / CopilotBackend implementation outlines, 2-week implementation sequence).

---

🤖 Posted by sabbour-squad-lead

[sabbour-squad-lead]

Electron DP — Rev 8: Reconciliation + Mermaid Architecture Diagram

Commit: 155d6947dc91e1ab5b6c71e3059a69b1842d7eff

What changed

Part 1 — Reconciled DP with repo code

Re-surveyed every critical file referenced in the DP against the actual codebase:

Claim	Finding	Action
agents-otel-bridge.ts = 262 lines	Actually 277 lines (+15 from Nibbler B3 fix)	Fixed inline
Runner.run() starts at line 316	Actually line 319 (316 = class declaration)	Fixed inline
§2 table: telemetry = applicationinsights	API layer migrated to pure OTel via @azure/monitor-opentelemetry; classic SDK banned by ESLint	Reconciliation sub-note added
§3.5 desktop telemetry: applicationinsights SDK	Should reference OTel-first approach matching server-side	Reconciliation sub-note added
20 handlers in packages/web/api/src/functions/	✅ Confirmed: 20 handler files (non-test)	No change
3 agents, 2 handoff edges	✅ Confirmed: triage→codesmith, triage→reviewer	No change
buildModelProvider() at runner.ts:54-72	✅ Exact match	No change
runner.ts = 597 lines	✅ Confirmed	No change
emit_ui pattern + A2UI drain	✅ Accurate	No change
No packages/desktop/ conflict	✅ No existing package	No change
Bicep: SWA + KV + AI + LAW	✅ Confirmed	No change

0 verdict-threatening findings. Option 3 (KickstartRunner shim) recommendation stands.

Part 2 — Mermaid architecture diagram (§1.1)

Added to top of DP (new §1.1):

flowchart TB
    subgraph web["🌐 Web — SWA (existing, frozen)"]
        swa_fe["React 19 + A2UI"]
        swa_fn["Azure Functions v4"]
        swa_fe -->|"HTTP / SSE"| swa_fn
    end
    subgraph electron["🖥️ Electron — Desktop (new)"]
        e_renderer["BrowserWindow"]
        e_server["Local HTTP"]
        e_renderer -->|"HTTP / SSE"| e_server
    end
    subgraph shared["🔷 Shared Runtime"]
        runner["KickstartRunner"]
        seam["AgentBackend Interface"]
        oai["OpenAIBackend"] --> seam
        cop["CopilotBackend"] --> seam
    end
    swa_fn --> runner
    e_server --> runner
    runner --> seam

Loading

(Full diagram in the DP includes subgraphs for above/below the backend seam, auth providers, styling legend, and a sequence diagram for the Electron turn lifecycle.)

Drift score: 2 inline fixes, 2 reconciliation sub-notes, 0 verdict-threatening

🤖 Posted by sabbour-squad-lead