feat(extensions): extension platform — host user-authored apps inside Agent Code

[Juliusolsson05]

Builds the platform for user-authored workflow tools that live inside Agent Code —
installed by the user, invoked from the command palette, opening their own page, backed
by a documented app API.

Reference case is a timer app. The timer is the forcing function, not the goal; the goal
is app-integrated extensions that can see and act on workspace, session, and git state
without anyone editing core app source.

This PR holds the full implementation. The first commit is investigation evidence, not
the plan — the plan file lands once the architecture decision is settled.

Status

• Read-only investigation of every integration surface
• Architecture decision (4 consultants running)
• Spike: verify the chosen loading path in dev and a packaged build
• Plan file
• Implementation

What the investigation found

packages/workflow-mcp is already a complete extension host. Discovery, acorn
metadata parsing without execution, SHA-256 integrity, an approval store keyed to
canonicalIdentity + sourceHash, a node:vm sandbox, and a separate utilityProcess with
heartbeats and timeouts — all shipping today. What it has no story for is UI.

So the open question is narrower than it looked: not how to host user code, but how
user-authored UI reaches the screen.

Three candidates, unresolved:

	Effort	Satisfies "install from Settings"?
A compiled-in src/apps/<id>/	1–2 days	❌ needs a rebuild
B runtime-loaded bundle	2–4 weeks	✅
C iframe on a custom scheme	1.5–3 weeks	✅

The constraints that decide it are in
docs/superpowers/specs/2026-07-20-extension-platform-investigation.md §3–§8. The two
non-obvious ones:

• Interaction ownership is a DOM attribute query and paint order is DOM sibling
  index — neither survives a frame boundary, which is a direct cost against C.
• B's real blocker is a stable injected host ABI, not CSP. React cannot be imported
  twice and app chunks are content-hashed, so every host object must be passed in.

Notes

• window.api is never handed to an extension — 153 flat methods, no namespacing, no
  sender validation. Extensions get a narrow zod-validated bridge instead, following the
  remote protocol's "the union is the allow-list" principle.
• Extension settings must not go in the zustand-persist Settings store; forgetting the
  version bump shipped a black-screen launch bug twice (Add settings for command picker visibility #249).
• Related to but distinct from Host user-authored MCP servers as Agent Code extensions #244, which hosts user-authored MCP servers — that gives
  extensions agent capabilities, this gives them app capabilities.

🤖 Generated with Claude Code

[Juliusolsson05]

Architecture settled — Stage 1 plan pushed

Four consultants ran under orchestration run extension-platform-consult. Both Claude
consultants were given opposing briefs — one to steelman compiled-in, one to steelman
runtime-loaded — and independently converged on the same staging. That convergence is the
main reason to trust it.

Decision: Stage 1 is compiled-in, built as Stage 2's substrate.

What changed from the investigation's assumptions

Stage 2's loader is one line, not a multi-week problem. out/renderer/assets/editor.main-*.js
already contains a fully runtime-variable import() that Rollup passed through untouched, and
92 Monaco language chunks load via ESM dynamic import from file:// in production. Both halves
of the loading risk are empirically retired — by code already shipping.

Two objections to the iframe option were refuted. Paint order survives (the iframe wrapper
is a normal registry sibling), and interaction ownership survives with a marker on the host shell
(~1–10 LOC, fixes all seven consumers). The perf-baseline objection was also wrong — it only
colors a number yellow. What is genuinely broken is keyboard: every host shortcut dies while
focus is inside a frame, and Cmd+W closes the window rather than the pane. Full iframe bridge
priced at ~350–650 LOC.

The API is transport-independent. Same schemas for compiled-in, runtime-loaded, utility-process
and iframe — only bootstrap, serialization, mounting and teardown differ. So AgentCodeApiV1 gets
built now and used even while apps are compiled in.

The two rules that make Stage 2 a swap

1. An app imports nothing from @renderer/* and receives one prop, api: AgentCodeApiV1.
2. Every host call returns a Promise, including ones that could be synchronous — postMessage
   cannot be made sync later, and widening those signatures afterwards touches every call site in
   every app.

The plan ends with the grep that proves rule 1 held. If it fails, Stage 1 built something Stage 2
would tear out — and that is worth finding while there is exactly one app.

Stage 2 is conditional, not scheduled

Trigger: extensions shipping to people who run packaged releases. The owner runs npm start
against a local build and rebuilds routinely, so Stage 1 is sufficient for personal use
indefinitely.

📄 docs/superpowers/plans/2026-07-20-extension-platform-stage1.md

[Juliusolsson05]

Stage 1 implemented — all six tasks

Six commits, 28 files, +2668. Host built before its first consumer so the
infrastructure could not be shaped around one app's needs; Timer landed last.

npm run typecheck	✅
npm test	✅ 209 files / 1187 tests
npm run build	✅
portability grep	✅

What's in it

• src/main/extensions/storage.ts — per-app JSON under STATE_DIR/extensions/<id>/,
  atomic temp+rename. Ids are validated and rejected, not sanitized: an id becomes a
  directory name, so a permissive id is a traversal primitive — and sanitizing silently
  collapses ../timer and timer onto one directory.
• apps/api/types.ts — AgentCodeApiV1. Tier 0 only (storage, close, toast, theme
  tokens). Every method returns a Promise even where it is synchronous internally,
  because postMessage cannot be made sync later.
• apps/surfaces/AppHostSurface.tsx — one surface entry, appended last in
  modalSurfaces. Apps mount inside DialogContent so they inherit the
  interaction-ownership marker that seven consumers query synchronously.
• apps/commands/appCommands.ts — commands derived by .map(APPS), so an app
  cannot ship without an opener.
• Settings → Apps — fourth instance of the existing self-subscribing marker pattern.
• Timer — SVG progress ring, presets, pause/resume, deadline-based countdown.

The test that matters

$ grep -rn "@renderer/" src/renderer/src/apps/timer/
apps/timer/index.ts:      import type { AppDefinition } from '@renderer/apps/types'
apps/timer/index.ts:      import { TimerApp } from '@renderer/apps/timer/ui/TimerApp'
apps/timer/ui/TimerApp.tsx: import type { AgentCodeApiV1 } from '@renderer/apps/api/types'

Only the ABI types and its own file. The Timer directory should lift into its own repo in
Stage 2 unchanged — that claim is currently under adversarial audit.

Deviations from the plan, both found by reading

• uiShell actions are declared in app-state/types.ts (UiShellSlice), not
  uiShell/types.ts as the plan assumed. State field went in the latter, actions in the
  former.
• Timer styling is inline style={{ }} with var(--theme-*) rather than Tailwind
  utilities — the utilities are a build-time binding that will not exist out-of-tree.

Still open

Two reviewers running (extension-platform-review): correctness/integration, and an
adversarial audit of the Stage-2 migration claim. Findings to follow.

No manual smoke run yet — npm start verification pending.

[Juliusolsson05]

Full extension platform — Phase B complete

16 commits, 42 files, +5528. typecheck ✅ · 1187 tests ✅ · build ✅

The compiled-in app approach was removed; this is now a real VS Code-style
extension system — install from a repository, declare contributions, activate lazily.

Phase B

B1	agent-code-ext:// scheme + CSP	✅
B2	Host runtime global	✅
B3	Manifest contributions + activation events	✅
B4	Extension host — import, activate, disposables	✅
B5	View bridge	✅
B6	Declarations → palette / Settings	✅
B7	Four review defects	✅

Verified, not assumed

Scheme spike — real built renderer, real CSP, file:// origin:

document origin       file:            dynamic import        activate() OK
missing extension     404              relative ./sibling.js resolved
../../../.ssh         404 blocked      ..%2f..%2f encoded    404 blocked

Install — the real installer against a real repository:

id timer · ref v0.1.0 · sha256 1fb05a80… · 194 KB on disk · exports activate

Plus error paths: unknown repo, private repo, malformed input.

Manifest — the real timer manifest accepted, and nine rejection cases
including foreign-namespace ids, duplicate ids, dangling keybindings, unknown
activation events, and traversal entries.

Production build — __agentCodeHost and agent-code-ext:// both present in
the shipped renderer bundle.

First real extension

Juliusolsson05/agent-code-timer v0.1.0 —
ported from focus-flow-timer, restructured so a headless engine owns the session
and the view is a subscriber. Closing the window does not stop the timer; a
wall-clock deadline means it survives an app restart too.

It is already installed on this machine and will appear on next launch.

Two bugs found by building the real thing

• The contribution-id regex demanded kebab-case and rejected timer.inheritTheme.
  Caught by running the schema against the real manifest.
• GlobalToast sat at z-50, under the dialog scrim at z-[1100] — every toast
  raised from inside a modal was invisible. Harmless while all callers were
  non-modal chrome; fatal for an extension whose reminders fire as toasts.

Not verified

Nobody has launched the app and clicked it. Everything above is automated
verification of the pieces. The end-to-end run is the remaining gap.