npm - @astrale-os/cli - Versions diffs - 0.4.0-alpha.13 - Mend

@astrale-os/cli 0.4.0-alpha.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (219) hide show

package/.check-workspace.cjs +40 -0
package/README.md +151 -0
package/dist/astrale.js +59749 -0
package/package.json +90 -0
package/src/command.ts +40 -0
package/src/commands/__tests__/admin-instance.test.ts +73 -0
package/src/commands/__tests__/auth-login.test.ts +178 -0
package/src/commands/__tests__/auth-token.test.ts +223 -0
package/src/commands/__tests__/call.test.ts +72 -0
package/src/commands/__tests__/domain-list.test.ts +74 -0
package/src/commands/__tests__/help-contract.test.ts +136 -0
package/src/commands/__tests__/install-identity-override.test.ts +65 -0
package/src/commands/__tests__/instance-bookmark.test.ts +101 -0
package/src/commands/__tests__/instance-create-hosts.test.ts +29 -0
package/src/commands/__tests__/instance-list-rows.test.ts +63 -0
package/src/commands/__tests__/logs.test.ts +117 -0
package/src/commands/__tests__/ls.test.ts +25 -0
package/src/commands/__tests__/setup-plan.test.ts +61 -0
package/src/commands/admin/status.ts +61 -0
package/src/commands/admin/use.ts +77 -0
package/src/commands/auth/login.ts +82 -0
package/src/commands/auth/logout.ts +50 -0
package/src/commands/auth/status.ts +86 -0
package/src/commands/auth/token.ts +162 -0
package/src/commands/browser.ts +207 -0
package/src/commands/call.ts +300 -0
package/src/commands/describe.ts +182 -0
package/src/commands/domain/install.ts +420 -0
package/src/commands/domain/list.ts +154 -0
package/src/commands/domain/publish.ts +155 -0
package/src/commands/get.ts +60 -0
package/src/commands/identity/create.ts +26 -0
package/src/commands/identity/delete.ts +18 -0
package/src/commands/identity/export.ts +66 -0
package/src/commands/identity/import.ts +101 -0
package/src/commands/identity/list.ts +56 -0
package/src/commands/identity/register.ts +170 -0
package/src/commands/identity/sync.ts +32 -0
package/src/commands/identity/unsync.ts +24 -0
package/src/commands/identity/use.ts +18 -0
package/src/commands/identity/whoami.ts +34 -0
package/src/commands/idp/add.ts +150 -0
package/src/commands/idp/list.ts +57 -0
package/src/commands/idp/refresh.ts +38 -0
package/src/commands/idp/remove.ts +36 -0
package/src/commands/idp/show.ts +29 -0
package/src/commands/instance/active.ts +64 -0
package/src/commands/instance/bookmark.ts +72 -0
package/src/commands/instance/create.ts +69 -0
package/src/commands/instance/delete.ts +72 -0
package/src/commands/instance/forget.ts +26 -0
package/src/commands/instance/list.ts +149 -0
package/src/commands/instance/status.ts +42 -0
package/src/commands/instance/use.ts +210 -0
package/src/commands/logs.ts +347 -0
package/src/commands/ls.ts +229 -0
package/src/commands/query.ts +32 -0
package/src/commands/setup.ts +54 -0
package/src/commands/status.ts +60 -0
package/src/commands/studio.ts +401 -0
package/src/commands/token.ts +77 -0
package/src/commands/update.ts +267 -0
package/src/commands/use.ts +87 -0
package/src/errors.ts +65 -0
package/src/kernel/__tests__/auth.test.ts +77 -0
package/src/kernel/__tests__/errors.test.ts +43 -0
package/src/kernel/__tests__/remote-routing.test.ts +70 -0
package/src/kernel/auth.ts +234 -0
package/src/kernel/ca-fetch.ts +119 -0
package/src/kernel/client.ts +191 -0
package/src/kernel/errors.ts +280 -0
package/src/kernel/expand.ts +217 -0
package/src/kernel/index.ts +14 -0
package/src/kernel/options.ts +22 -0
package/src/kernel/remote-routing.ts +88 -0
package/src/kernel/run.ts +63 -0
package/src/kernel/types.ts +14 -0
package/src/lib/__tests__/admin-target.test.ts +112 -0
package/src/lib/__tests__/binary.test.ts +56 -0
package/src/lib/__tests__/command-dx.test.ts +58 -0
package/src/lib/__tests__/concurrency.test.ts +62 -0
package/src/lib/__tests__/config.test.ts +53 -0
package/src/lib/__tests__/design.test.ts +99 -0
package/src/lib/__tests__/domain-identity.test.ts +60 -0
package/src/lib/__tests__/format.test.ts +22 -0
package/src/lib/__tests__/fs-atomic.test.ts +104 -0
package/src/lib/__tests__/identity.test.ts +79 -0
package/src/lib/__tests__/idp-session.driver.ts +53 -0
package/src/lib/__tests__/idp-session.test.ts +357 -0
package/src/lib/__tests__/idp.test.ts +385 -0
package/src/lib/__tests__/instance-candidates.test.ts +73 -0
package/src/lib/__tests__/instance-target.test.ts +183 -0
package/src/lib/__tests__/instance.test.ts +136 -0
package/src/lib/__tests__/keys.test.ts +129 -0
package/src/lib/__tests__/local-status.test.ts +202 -0
package/src/lib/__tests__/output.test.ts +150 -0
package/src/lib/__tests__/panel.test.ts +40 -0
package/src/lib/__tests__/port.test.ts +44 -0
package/src/lib/__tests__/prompt.test.ts +25 -0
package/src/lib/__tests__/sdk-deps.test.ts +68 -0
package/src/lib/__tests__/self.test.ts +272 -0
package/src/lib/__tests__/studio-server-deps.test.ts +74 -0
package/src/lib/__tests__/table.test.ts +53 -0
package/src/lib/__tests__/update.test.ts +246 -0
package/src/lib/__tests__/use-target.test.ts +56 -0
package/src/lib/__tests__/validation.test.ts +34 -0
package/src/lib/admin-domain.ts +25 -0
package/src/lib/admin-instance.ts +26 -0
package/src/lib/admin-target.ts +217 -0
package/src/lib/binary.ts +131 -0
package/src/lib/browser.ts +150 -0
package/src/lib/command-dx.ts +161 -0
package/src/lib/concurrency.ts +31 -0
package/src/lib/config.ts +45 -0
package/src/lib/domain-identity.ts +49 -0
package/src/lib/env.ts +49 -0
package/src/lib/format.ts +4 -0
package/src/lib/fs-atomic.ts +126 -0
package/src/lib/identity.ts +256 -0
package/src/lib/idp-session.ts +134 -0
package/src/lib/idp.ts +876 -0
package/src/lib/instance-candidates.ts +49 -0
package/src/lib/instance-target.ts +182 -0
package/src/lib/instance.ts +395 -0
package/src/lib/keys.ts +294 -0
package/src/lib/local-status.ts +152 -0
package/src/lib/log.ts +116 -0
package/src/lib/login-flow.ts +164 -0
package/src/lib/meta.ts +86 -0
package/src/lib/output.ts +222 -0
package/src/lib/panel.ts +61 -0
package/src/lib/paths.ts +11 -0
package/src/lib/port.ts +41 -0
package/src/lib/proc.ts +82 -0
package/src/lib/prompt.ts +136 -0
package/src/lib/provision-instance.ts +170 -0
package/src/lib/sdk-deps.ts +104 -0
package/src/lib/self.ts +166 -0
package/src/lib/skills.ts +171 -0
package/src/lib/table.ts +62 -0
package/src/lib/update.ts +315 -0
package/src/lib/use-target.ts +24 -0
package/src/lib/validation.ts +59 -0
package/src/program.ts +200 -0
package/src/registry.ts +59 -0
package/src/setup/__tests__/util.test.ts +29 -0
package/src/setup/engine.ts +83 -0
package/src/setup/render.ts +109 -0
package/src/setup/steps/admin.ts +78 -0
package/src/setup/steps/agent-browser.ts +81 -0
package/src/setup/steps/auth.ts +54 -0
package/src/setup/steps/domain.ts +68 -0
package/src/setup/steps/index.ts +18 -0
package/src/setup/steps/instance.ts +119 -0
package/src/setup/steps/skills-bridge.ts +70 -0
package/src/setup/steps/skills.ts +59 -0
package/src/setup/types.ts +61 -0
package/src/setup/util.ts +34 -0
package/src/test-utils.ts +18 -0
package/studio/client/dist/assets/index-DOwzZAEK.css +1 -0
package/studio/client/dist/assets/index-wtU0Zxhy.js +183 -0
package/studio/client/dist/index.html +13 -0
package/studio/package.json +62 -0
package/studio/server/agent/ask.ts +68 -0
package/studio/server/agent/bridge-mcp.ts +182 -0
package/studio/server/agent/bridge.ts +188 -0
package/studio/server/agent/claude.ts +666 -0
package/studio/server/agent/mock.ts +186 -0
package/studio/server/agent/prompt.ts +202 -0
package/studio/server/agent/registry.ts +29 -0
package/studio/server/agent/runner.ts +484 -0
package/studio/server/agent/schema-map.ts +112 -0
package/studio/server/agent/types.ts +120 -0
package/studio/server/api.ts +574 -0
package/studio/server/cache.ts +138 -0
package/studio/server/detect.ts +81 -0
package/studio/server/domain.ts +70 -0
package/studio/server/index.ts +136 -0
package/studio/server/introspect/anatomy-extras.ts +398 -0
package/studio/server/introspect/anatomy.ts +108 -0
package/studio/server/introspect/bundle.ts +57 -0
package/studio/server/introspect/core-extractor.ts +119 -0
package/studio/server/introspect/core.ts +44 -0
package/studio/server/introspect/diff.ts +133 -0
package/studio/server/introspect/extractor.ts +102 -0
package/studio/server/introspect/hash.ts +21 -0
package/studio/server/introspect/overlay-tsmorph.ts +874 -0
package/studio/server/introspect/overlay.ts +57 -0
package/studio/server/introspect/runtime.ts +99 -0
package/studio/server/introspect/schema-refs.ts +46 -0
package/studio/server/lifecycle.ts +38 -0
package/studio/server/sse.ts +57 -0
package/studio/server/state/baseline.ts +211 -0
package/studio/server/state/catalog.ts +117 -0
package/studio/server/state/comments.ts +321 -0
package/studio/server/state/context.ts +167 -0
package/studio/server/state/copy.ts +156 -0
package/studio/server/state/create.ts +156 -0
package/studio/server/state/documents.ts +70 -0
package/studio/server/state/env.ts +161 -0
package/studio/server/state/git.ts +75 -0
package/studio/server/state/handoff.ts +55 -0
package/studio/server/state/harness-gateway.ts +181 -0
package/studio/server/state/harness-token.ts +0 -0
package/studio/server/state/instance.ts +244 -0
package/studio/server/state/integrations.ts +55 -0
package/studio/server/state/layout.ts +55 -0
package/studio/server/state/settings.ts +39 -0
package/studio/server/state/store.ts +97 -0
package/studio/server/state/updates.ts +63 -0
package/studio/server/state/usage.ts +37 -0
package/studio/server/state/views.ts +138 -0
package/studio/server/state/visibility.ts +33 -0
package/studio/server/watch.ts +81 -0
package/studio/server/workspace-state.ts +26 -0
package/studio/server/workspace-watch.ts +101 -0
package/studio/shared/types.ts +873 -0
package/studio/tsconfig.json +23 -0
package/tsconfig.json +14 -0

package/studio/client/dist/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en" class="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Domain Studio</title>
+    <script type="module" crossorigin src="/assets/index-wtU0Zxhy.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DOwzZAEK.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/studio/package.json ADDED Viewed

@@ -0,0 +1,62 @@
+{
+  "name": "@astrale-os/studio",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Astrale Domain Studio — local GUI for authoring/inspecting a domain (launched by `astrale studio`)",
+  "bin": {
+    "astrale-studio": "./server/index.ts"
+  },
+  "files": [
+    "server",
+    "shared",
+    "client/dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "start": "bun server/index.ts",
+    "dev:client": "vite",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@astrale-os/shell": ">=0.1.1 <1.0.0",
+    "@dagrejs/dagre": "^3.0.0",
+    "@radix-ui/react-collapsible": "^1.1.0",
+    "@radix-ui/react-dialog": "^1.1.6",
+    "@radix-ui/react-dropdown-menu": "^2.1.6",
+    "@radix-ui/react-hover-card": "^1.1.0",
+    "@radix-ui/react-popover": "^1.1.0",
+    "@radix-ui/react-scroll-area": "^1.2.3",
+    "@radix-ui/react-separator": "^1.1.2",
+    "@radix-ui/react-slot": "^1.1.2",
+    "@radix-ui/react-tabs": "^1.1.3",
+    "@radix-ui/react-tooltip": "^1.1.8",
+    "@tanstack/react-query": "^5.66.0",
+    "@xyflow/react": "^12.4.4",
+    "chokidar": "^4.0.3",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "elkjs": "^0.11.1",
+    "lucide-react": "^0.475.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "sonner": "^2.0.1",
+    "tailwind-merge": "^3.0.1",
+    "ts-morph": "^25.0.1",
+    "zustand": "^5.0.3"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.6",
+    "@types/node": "^20.19.43",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^5.0.0",
+    "bun-types": "^1.3.14",
+    "tailwindcss": "^4.0.6",
+    "typescript": "^5.7.3",
+    "vite": "^7.0.0"
+  }
+}

package/studio/server/agent/ask.ts ADDED Viewed

@@ -0,0 +1,68 @@
+/**
+ * agent/ask.ts — the "side question" channel. A quick, EPHEMERAL aside about one
+ * element: it FORKS the domain's live conversation (so it inherits the full context
+ * the main loop built up) but writes nothing back to the parent transcript — the
+ * main thread, its session, and comments.json are all untouched. Streams the
+ * answer; nothing is persisted.
+ *
+ * It deliberately bypasses the single-run-per-domain lock (the fork is isolated
+ * from the parent conversation) so you can ask while a main agent turn is running.
+ */
+import type { AnchorRef } from '../../shared/types'
+import type { DomainHandle } from '../domain'
+import type { AskResult } from './types'
+import { getBundle } from '../cache'
+import { resolveHarnessEnv } from '../state/harness-gateway'
+import { readSettings } from '../state/settings'
+import { buildAskPrompt, buildAskSystemPrompt } from './prompt'
+import { getHarness } from './registry'
+import { forkableSession } from './runner'
+export interface AskRequest {
+  anchor?: AnchorRef
+  excerpt?: string
+  question: string
+}
+export async function runAsk(
+  handle: DomainHandle,
+  body: AskRequest,
+  signal: AbortSignal,
+  onDelta: (text: string) => void,
+): Promise<AskResult> {
+  const harness = getHarness()
+  if (!harness.ask)
+    return {
+      text: '',
+      isError: true,
+      errorMessage: `${harness.label} does not support side questions`,
+    }
+  const question = String(body?.question ?? '').trim()
+  if (!question) return { text: '', isError: true, errorMessage: 'question is required' }
+  const ref = body.anchor?.ref ?? '(no target)'
+  const bundle = await getBundle(handle.id)
+  const prompt = buildAskPrompt({
+    anchorRef: ref,
+    excerpt: body.excerpt || ref,
+    question,
+    ir: bundle?.ir ?? null,
+    overlay: bundle?.overlay,
+  })
+  const settings = readSettings(handle.root)
+  const envResult = await resolveHarnessEnv(handle.root)
+  if (!envResult.ok)
+    return { text: '', isError: true, errorMessage: `model gateway auth failed — ${envResult.error}` }
+  return harness.ask({
+    root: handle.root,
+    prompt,
+    appendSystemPrompt: buildAskSystemPrompt(),
+    sessionId: forkableSession(handle.id), // fork the live conversation (undefined ⇒ fresh)
+    effort: settings.agentEffort,
+    env: envResult.env,
+    signal,
+    onDelta,
+  })
+}

package/studio/server/agent/bridge-mcp.ts ADDED Viewed

@@ -0,0 +1,182 @@
+#!/usr/bin/env bun
+/**
+ * bridge-mcp.ts — a minimal stdio MCP server the harness spawns (via the
+ * generated --mcp-config). It exposes the Domain Studio write-back tools and
+ * forwards each call to the token-guarded HTTP bridge (api → agent/bridge/*),
+ * so an agent can reply to comment threads and post progress AS IT WORKS.
+ *
+ * Transport: newline-delimited JSON-RPC 2.0 on stdin/stdout. Nothing but
+ * protocol messages may touch stdout; diagnostics go to stderr.
+ */
+const BASE = process.env.DOMAIN_STUDIO_BRIDGE_URL || ''
+const TOKEN = process.env.DOMAIN_STUDIO_BRIDGE_TOKEN || ''
+const TOOLS = [
+  {
+    name: 'list_open_threads',
+    description:
+      'List the open comment threads that are awaiting your reply (id, anchor, file, latest message). Call this first to see what to address.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    route: 'threads',
+  },
+  {
+    name: 'reply_to_thread',
+    description:
+      'Post a reply to one comment thread so the user sees it live. Say what you changed, answer a question, or ask one back. Pass `options` (a short list of concrete choices) to turn the reply into a multiple-choice question the user can pick from (or answer freely). Set resolve=true with a short closeNote ONLY when fully handled — never resolve a question you just asked.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        commentId: { type: 'string', description: 'the thread id from list_open_threads' },
+        text: {
+          type: 'string',
+          description: 'your reply (concise — a framing line when offering options)',
+        },
+        options: {
+          type: 'array',
+          items: { type: 'string' },
+          description: '2–5 short choices for the user to pick from; they may also answer freely',
+        },
+        resolve: { type: 'boolean', description: 'close the thread when done (not when asking)' },
+        closeNote: { type: 'string', description: 'one-line summary when resolving' },
+      },
+      required: ['commentId', 'text'],
+      additionalProperties: false,
+    },
+    route: 'reply',
+  },
+  {
+    name: 'resolve_thread',
+    description: 'Mark a comment thread resolved (closed) with an optional closeNote.',
+    inputSchema: {
+      type: 'object',
+      properties: { commentId: { type: 'string' }, closeNote: { type: 'string' } },
+      required: ['commentId'],
+      additionalProperties: false,
+    },
+    route: 'resolve',
+  },
+  {
+    name: 'post_progress',
+    description:
+      'Post a short progress note shown in the studio activity panel (not tied to a thread).',
+    inputSchema: {
+      type: 'object',
+      properties: { text: { type: 'string' } },
+      required: ['text'],
+      additionalProperties: false,
+    },
+    route: 'progress',
+  },
+  {
+    name: 'raise_question',
+    description:
+      'Open a NEW question thread anchored to a schema element (ref like "class.Monitor.property.url") when you need the user to decide something. Pass `options` for a multiple-choice question — the user picks one or answers freely.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ref: {
+          type: 'string',
+          description: 'anchor ref, e.g. "class.Order" or "module.inventory/inventory"',
+        },
+        text: {
+          type: 'string',
+          description: 'the question (one framing line when offering options)',
+        },
+        file: { type: 'string' },
+        options: {
+          type: 'array',
+          items: { type: 'string' },
+          description: '2–5 short choices the user can pick from',
+        },
+      },
+      required: ['ref', 'text'],
+      additionalProperties: false,
+    },
+    route: 'raise_question',
+  },
+] as const
+function send(msg: unknown): void {
+  process.stdout.write(`${JSON.stringify(msg)}\n`)
+}
+function reply(id: unknown, result: unknown): void {
+  send({ jsonrpc: '2.0', id, result })
+}
+function replyError(id: unknown, code: number, message: string): void {
+  send({ jsonrpc: '2.0', id, error: { code, message } })
+}
+async function callBridge(route: string, args: Record<string, unknown>): Promise<string> {
+  if (!BASE || !TOKEN) return 'bridge not configured'
+  try {
+    const res = await fetch(`${BASE}/${route}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ token: TOKEN, ...args }),
+    })
+    const text = await res.text()
+    return res.ok ? text || 'ok' : `error ${res.status}: ${text}`
+  } catch (e: any) {
+    return `bridge call failed: ${e?.message ?? e}`
+  }
+}
+async function handle(req: any): Promise<void> {
+  const { id, method, params } = req
+  switch (method) {
+    case 'initialize':
+      reply(id, {
+        protocolVersion: params?.protocolVersion || '2025-06-18',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'domain-studio', version: '0.1.0' },
+      })
+      return
+    case 'notifications/initialized':
+    case 'initialized':
+      return // notification, no response
+    case 'ping':
+      reply(id, {})
+      return
+    case 'tools/list':
+      reply(id, {
+        tools: TOOLS.map(({ name, description, inputSchema }) => ({
+          name,
+          description,
+          inputSchema,
+        })),
+      })
+      return
+    case 'tools/call': {
+      const tool = TOOLS.find((t) => t.name === params?.name)
+      if (!tool) {
+        replyError(id, -32602, `unknown tool: ${params?.name}`)
+        return
+      }
+      const out = await callBridge(tool.route, (params?.arguments ?? {}) as Record<string, unknown>)
+      reply(id, { content: [{ type: 'text', text: out }] })
+      return
+    }
+    default:
+      if (id !== undefined) replyError(id, -32601, `method not found: ${method}`)
+  }
+}
+let buf = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk: string) => {
+  buf += chunk
+  let nl: number
+  while ((nl = buf.indexOf('\n')) >= 0) {
+    const line = buf.slice(0, nl).trim()
+    buf = buf.slice(nl + 1)
+    if (!line) continue
+    let req: any
+    try {
+      req = JSON.parse(line)
+    } catch {
+      continue
+    }
+    void handle(req)
+  }
+})
+process.stdin.on('end', () => process.exit(0))

package/studio/server/agent/bridge.ts ADDED Viewed

@@ -0,0 +1,188 @@
+/**
+ * agent/bridge.ts — the per-run write-back channel. Lets the agent reply to
+ * threads LIVE (mid-turn) instead of only at end-of-turn. Two halves:
+ *
+ *   1. startBridge() mints a scoped token + writes an MCP config the harness
+ *      loads (`--mcp-config`). The MCP server (bridge-mcp.ts) is a thin stdio
+ *      proxy: each tool call POSTs to the token-guarded routes below.
+ *   2. handleBridge() applies those calls to the SAME state the GUI reads
+ *      (comments.json), so replies appear in the threads immediately over SSE.
+ *
+ * This is additive: the runner ALSO merges the agent's end-of-turn machine-state
+ * block, and mergeReply dedupes by text so a live reply is never duplicated.
+ */
+import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+import type { StudioEvent } from '../../shared/types'
+import type { DomainHandle } from '../domain'
+import { addThreadEntry, readComments, setStatus, upsertComment } from '../state/comments'
+import { removeState, statePath, writeJson } from '../state/store'
+export interface Bridge {
+  enabled: boolean
+  mcpConfigPath?: string
+  onReply(cb: (commentId: string, text: string) => void): void
+  onProgress(cb: (text: string) => void): void
+  dispose(): void
+}
+interface RunBridge {
+  domainId: string
+  root: string
+  onReply: (commentId: string, text: string) => void
+  onProgress: (text: string) => void
+}
+const bridges = new Map<string, RunBridge>() // token → bridge
+let studioPort = Number(process.env.PORT) || 4319
+/** index.ts calls this once the server is listening so the MCP proxy knows where to POST. */
+export function setBridgePort(port: number): void {
+  studioPort = port
+}
+const MCP_SERVER = join(import.meta.dir, 'bridge-mcp.ts')
+// the studio runs under bun, so process.execPath is the absolute bun binary —
+// robust when `bun` is only a shell function on the agent's PATH.
+const BIN = process.env.DOMAIN_STUDIO_BRIDGE_BUN || process.execPath
+export function startBridge(
+  handle: DomainHandle,
+  _getRunId: () => string,
+  _notify: (e: StudioEvent) => void,
+): Bridge {
+  const token = randomUUID()
+  const holder: RunBridge = {
+    domainId: handle.id,
+    root: handle.root,
+    onReply: () => {},
+    onProgress: () => {},
+  }
+  bridges.set(token, holder)
+  const base = `http://127.0.0.1:${studioPort}/api/domain/${encodeURIComponent(handle.id)}/agent/bridge`
+  const mcpRel = `.cache/agent/mcp-${token}.json`
+  writeJson(handle.root, mcpRel, {
+    mcpServers: {
+      'domain-studio': {
+        command: BIN,
+        args: [MCP_SERVER],
+        env: { DOMAIN_STUDIO_BRIDGE_URL: base, DOMAIN_STUDIO_BRIDGE_TOKEN: token },
+      },
+    },
+  })
+  const mcpConfigPath = statePath(handle.root, mcpRel)
+  return {
+    enabled: true,
+    mcpConfigPath,
+    onReply: (cb) => {
+      holder.onReply = cb
+    },
+    onProgress: (cb) => {
+      holder.onProgress = cb
+    },
+    dispose: () => {
+      bridges.delete(token)
+      try {
+        removeState(handle.root, mcpRel)
+      } catch {
+        /* best-effort */
+      }
+    },
+  }
+}
+function ok(data: unknown): Response {
+  return new Response(JSON.stringify(data), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+function err(message: string, status = 400): Response {
+  return new Response(JSON.stringify({ error: message }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+/** Routes under /api/domain/:id/agent/bridge/<sub>. Token in the body, scoped to the run. */
+export async function handleBridge(
+  handle: DomainHandle,
+  sub: string,
+  _req: Request,
+  body: any,
+  notify: (e: StudioEvent) => void,
+): Promise<Response> {
+  const token = String(body?.token ?? '')
+  const bridge = bridges.get(token)
+  if (!bridge || bridge.domainId !== handle.id) return err('invalid or expired bridge token', 401)
+  const root = handle.root
+  switch (sub) {
+    case 'threads': {
+      const open = readComments(root).comments.filter(
+        (c) => c.status === 'open' && c.thread.at(-1)?.role !== 'author',
+      )
+      return ok({
+        threads: open.map((c) => ({
+          id: c.id,
+          kind: c.kind,
+          anchor: c.anchorRefs?.[0]?.ref ?? null,
+          file: c.anchorRefs?.[0]?.file ?? null,
+          latest: c.thread.at(-1)?.text ?? '',
+        })),
+      })
+    }
+    case 'reply': {
+      const commentId = String(body.commentId ?? '')
+      const text = String(body.text ?? '').trim()
+      if (!commentId || !text) return err('commentId and text are required')
+      const c = addThreadEntry(root, commentId, {
+        role: 'author',
+        type: body.options ? 'choice' : 'text',
+        text,
+        options: body.options,
+        answer: body.answer,
+      })
+      if (!c) return err('unknown commentId', 404)
+      if (body.resolve) setStatus(root, commentId, 'closed', body.closeNote)
+      bridge.onReply(commentId, text)
+      notify({ type: 'comments', domainId: handle.id })
+      return ok({ ok: true, resolved: !!body.resolve })
+    }
+    case 'resolve': {
+      const commentId = String(body.commentId ?? '')
+      if (!commentId) return err('commentId is required')
+      const c = setStatus(root, commentId, 'closed', body.closeNote)
+      if (!c) return err('unknown commentId', 404)
+      bridge.onReply(commentId, body.closeNote ? `resolved: ${body.closeNote}` : 'resolved')
+      notify({ type: 'comments', domainId: handle.id })
+      return ok({ ok: true })
+    }
+    case 'progress': {
+      const text = String(body.text ?? '').trim()
+      if (text) bridge.onProgress(text)
+      return ok({ ok: true })
+    }
+    case 'raise_question': {
+      const ref = String(body.ref ?? '')
+      const text = String(body.text ?? '').trim()
+      if (!ref || !text) return err('ref and text are required')
+      const c = upsertComment(root, {
+        anchors: [body.label ?? ref],
+        anchorRefs: [{ ref, kind: (body.kind ?? 'schema') as any, file: body.file }],
+        text,
+        firstRole: 'author',
+        type: body.options ? 'choice' : 'text',
+        options: body.options,
+      })
+      notify({ type: 'comments', domainId: handle.id })
+      return ok({ ok: true, id: c.id })
+    }
+    default:
+      return err('unknown bridge route', 404)
+  }
+}