yarramate 1.25.1 → 1.26.0

package/README.md

@@ -163,8 +163,12 @@ diff — merging is the human acceptance step, not yours.
   verdicts, and attestations, with a `path:line` citation per cell.
 - `init` writes the discovery pointer into both `AGENTS.md` and
   `CLAUDE.md`, so this section finds you rather than the reverse.
-- `yarramate-mcp` exposes four read-only tools (ask/design/check/reconcile)
-  over MCP stdio.
+- `yarramate-mcp` exposes the whole loop over MCP stdio: `yarramate_ask`,
+  `yarramate_design`, `yarramate_apply`, `yarramate_check`,
+  `yarramate_reconcile` and `yarramate_export`. Every tool call runs the same
+  CLI; `apply` is the one write and lands the same atomic batch. Start it
+  inside the repository, or anywhere with `--workspace <path>`, and the
+  `workspace` argument becomes optional (#514).
 - In Claude Code, this repository is its own plugin marketplace:
 
   ```sh

package/dist/adapters/mcp-cli.d.ts

@@ -5,5 +5,49 @@ interface JsonRpcRequest {
     readonly method: string;
     readonly params?: Record<string, unknown>;
 }
-export declare const handleRequest: (request: JsonRpcRequest) => void;
+/**
+ * Where a tool call resolves its workspace when the call names none
+ * (#514). In order: the `--workspace` the server was started with, then the
+ * conventional `.yarramate/workspace.yaml` under the working directory. A
+ * desktop app starts the server from a directory that is not the repository,
+ * so the first is the one that matters there; a terminal agent runs it from
+ * the repository, so the second is what it gets for free.
+ */
+export interface ServerOptions {
+    readonly workspace?: string;
+}
+/** What a tool call needs from the server beyond its own arguments. */
+export interface ToolContext {
+    readonly cwd: string;
+    readonly workspace: string | undefined;
+}
+/**
+ * The loop, in two sentences, on every tool. A desktop-app agent connecting
+ * for the first time has never seen the skill file; the tool list is the only
+ * place it learns that design asks, apply lands, and design asks again.
+ */
+export declare const LOOP = "The loop: call yarramate_design for the top open question, answer it with the person, land the answer with yarramate_apply, then call yarramate_design again. Every tool takes the same optional `workspace`; omit it to use the workspace this server was started with, or .yarramate/workspace.yaml under its working directory.";
+export declare const resolveWorkspace: (input: Record<string, unknown>, context: ToolContext) => string | undefined;
+/**
+ * The CLI runs inside the repository: a manifest's globs resolve against the
+ * manifest, but a record's contracts, coverage and evidence name files by
+ * their repository-root path, which is the directory that holds `.yarramate`.
+ * A desktop app starts this server anywhere, so a workspace given as a path
+ * from elsewhere is run as the CLI would be run by a person standing in that
+ * repository: working directory at the root, manifest path relative to it.
+ */
+export declare const workingDirectoryFor: (workspace: string, cwd: string) => {
+    readonly cwd: string;
+    readonly workspace: string;
+};
+/** The tool list a client sees; exported so a test can read it without stdio. */
+export declare const toolCatalogue: {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}[];
+export declare const handleRequest: (request: JsonRpcRequest, context?: ToolContext) => void;
+/** `yarramate-mcp [--workspace <path>]`; anything else is refused with usage. */
+export declare const parseServerOptions: (argv: readonly string[]) => ServerOptions | undefined;
+export declare const serverUsage = "Usage:\n  yarramate-mcp [--workspace <workspace.yaml>]\n  yarramate-mcp --version\n";
 export {};

package/dist/adapters/mcp-cli.js

@@ -1,20 +1,95 @@
 #!/usr/bin/env node
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { isMainModule, packageVersion, versionResult, } from '../cli-support.js';
 import { runCli } from '../cli.js';
+/**
+ * The loop, in two sentences, on every tool. A desktop-app agent connecting
+ * for the first time has never seen the skill file; the tool list is the only
+ * place it learns that design asks, apply lands, and design asks again.
+ */
+export const LOOP = 'The loop: call yarramate_design for the top open question, answer it with the person, land the answer with yarramate_apply, then call yarramate_design again. Every tool takes the same optional `workspace`; omit it to use the workspace this server was started with, or .yarramate/workspace.yaml under its working directory.';
 const workspaceProperty = {
     workspace: {
         type: 'string',
-        description: 'Path to the explicit workspace manifest, for example .yarramate/workspace.yaml',
+        description: "Path to the workspace manifest, for example .yarramate/workspace.yaml. Optional: defaults to the server's --workspace, then to .yarramate/workspace.yaml under the working directory. Desktop apps start the server outside the repository, so give the full path there.",
     },
 };
+const CONVENTIONAL_WORKSPACE = join('.yarramate', 'workspace.yaml');
+/** The one refusal that is the server's own rather than the CLI's. */
+const noWorkspace = () => ({
+    exitCode: 2,
+    stdout: '',
+    stderr: 'No workspace to work on. Pass `workspace` (the path to workspace.yaml) in the call, or start yarramate-mcp with --workspace <path>; a server started inside a repository that holds .yarramate/workspace.yaml needs neither.\n',
+});
+export const resolveWorkspace = (input, context) => {
+    if (typeof input.workspace === 'string' && input.workspace.length > 0) {
+        return input.workspace;
+    }
+    if (context.workspace !== undefined)
+        return context.workspace;
+    return existsSync(resolve(context.cwd, CONVENTIONAL_WORKSPACE))
+        ? CONVENTIONAL_WORKSPACE
+        : undefined;
+};
+/**
+ * The CLI runs inside the repository: a manifest's globs resolve against the
+ * manifest, but a record's contracts, coverage and evidence name files by
+ * their repository-root path, which is the directory that holds `.yarramate`.
+ * A desktop app starts this server anywhere, so a workspace given as a path
+ * from elsewhere is run as the CLI would be run by a person standing in that
+ * repository: working directory at the root, manifest path relative to it.
+ */
+export const workingDirectoryFor = (workspace, cwd) => {
+    const manifest = resolve(cwd, workspace);
+    const holder = dirname(manifest);
+    const root = basename(holder) === '.yarramate' ? dirname(holder) : holder;
+    return { cwd: root, workspace: relative(root, manifest) };
+};
+const withWorkspace = (input, context, run) => {
+    const named = resolveWorkspace(input, context);
+    if (named === undefined)
+        return noWorkspace();
+    const { cwd, workspace } = workingDirectoryFor(named, context.cwd);
+    return run(workspace, cwd);
+};
+/**
+ * A scratch directory for one call, removed before the answer goes back.
+ * `apply` reads its operations from a path and `export` writes some kinds only
+ * to a directory; an MCP call carries neither, so the adapter lends both a
+ * place on disk for the duration of the call and nothing longer.
+ */
+const withScratch = (use) => {
+    const directory = mkdtempSync(join(tmpdir(), 'yarramate-mcp-'));
+    try {
+        return use(directory);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+};
+const operationsText = (operations) => {
+    if (typeof operations === 'string')
+        return operations;
+    if (typeof operations === 'object' && operations !== null) {
+        // JSON is YAML; the CLI's parser reads it unchanged.
+        return JSON.stringify(operations, null, 2);
+    }
+    return undefined;
+};
+const refuse = (message) => ({
+    exitCode: 2,
+    stdout: '',
+    stderr: `${message}\n`,
+});
 const tools = [
     {
         name: 'yarramate_ask',
-        description: 'The consumed-now read surface. Without a query: orientation — check verdict, drift summary, open-question count, and the backlog in dependency order. With a query: free text matches concept ids, names, and descriptions and returns the connected slice; exact subject ids (document-id#local-id) and projection paths address precisely. Set mode for the roster (subjects), declarable vocabulary (kinds), build order (next), or the full open-questions report (open).',
+        description: `The consumed-now read surface. Without a query: orientation — check verdict, drift summary, open-question count, and the backlog in dependency order. With a query: free text matches concept ids, names, and descriptions and returns the connected slice; exact subject ids (document-id#local-id) and projection paths address precisely. Set mode for the roster (subjects), declarable vocabulary (kinds), build order (next), or the full open-questions report (open). ${LOOP}`,
         inputSchema: {
             type: 'object',
-            required: ['workspace'],
             properties: {
                 ...workspaceProperty,
                 query: {
@@ -33,26 +108,24 @@ const tools = [
                 },
             },
         },
-        arguments: (input) => {
-            const workspace = String(input.workspace);
+        run: (input, context) => withWorkspace(input, context, (workspace, cwd) => {
             if (typeof input.mode === 'string') {
-                return ['ask', workspace, `--${input.mode}`, '--json'];
+                return runCli(['ask', workspace, `--${input.mode}`, '--json'], cwd);
             }
             if (typeof input.query === 'string' && input.query.length > 0) {
                 const budget = typeof input.budget === 'number'
                     ? ['--budget', String(input.budget)]
                     : ['--json'];
-                return ['ask', workspace, input.query, ...budget];
+                return runCli(['ask', workspace, input.query, ...budget], cwd);
             }
-            return ['ask', workspace, '--json'];
-        },
+            return runCli(['ask', workspace, '--json'], cwd);
+        }),
     },
     {
         name: 'yarramate_design',
-        description: 'The design interview, one stateless step: the top open question with its subject slice, materiality, and progress. Read-only — answers land through the CLI apply command in the repository, not through this server.',
+        description: `The design interview, one stateless step: the top open question with its subject slice, materiality, progress, and the operations skeleton that would answer it. Ask the person, land their answer with yarramate_apply, then call this again; the next question is computed from the record, never remembered. A question whose authority is human is for the person to decide, not the agent. ${LOOP}`,
         inputSchema: {
             type: 'object',
-            required: ['workspace'],
             properties: {
                 ...workspaceProperty,
                 subject: {
@@ -61,61 +134,203 @@ const tools = [
                 },
             },
         },
-        arguments: (input) => [
+        run: (input, context) => withWorkspace(input, context, (workspace, cwd) => runCli([
             'design',
-            String(input.workspace),
+            workspace,
             ...(typeof input.subject === 'string'
                 ? ['--subject', input.subject]
                 : []),
             '--json',
-        ],
+        ], cwd)),
+    },
+    {
+        name: 'yarramate_apply',
+        description: `Lands answers in the record: one yarramate/operations/v1 document, applied as an atomic batch by the same CLI command a person runs. Any invalid operation refuses the whole batch and nothing is written; the result names each diagnostic with its source location. Writes are spliced into the native documents, never re-serialized, so the diff is exactly the answer. ${LOOP}`,
+        inputSchema: {
+            type: 'object',
+            required: ['operations'],
+            properties: {
+                ...workspaceProperty,
+                operations: {
+                    description: 'The operations document: `format: yarramate/operations/v1` with an `operations` list. Each operation names its `op` and its `document` (the native document path, for example .yarramate/architecture/main.yaml) and nests the record under the key its op names: add-concept carries `concept: { id, kind, name, description?, status?, ... }`, add-relationship carries `relationship: { id, kind, from, to, description? }`, update-concept and update-relationship carry the same key with only the fields that change, delete-* and rename-* carry the id (and `to` for a rename). Shape, as JSON: {"format":"yarramate/operations/v1","operations":[{"op":"add-concept","document":".yarramate/architecture/main.yaml","concept":{"id":"ops-portal","kind":"applicationComponent","name":"Operations portal"}}]}. YAML or JSON text, or the equivalent JSON object.',
+                    oneOf: [{ type: 'string' }, { type: 'object' }],
+                },
+            },
+        },
+        run: (input, context) => withWorkspace(input, context, (workspace, cwd) => {
+            const text = operationsText(input.operations);
+            if (text === undefined) {
+                return refuse('yarramate_apply needs `operations`: a yarramate/operations/v1 document as YAML or JSON text, or as an object.');
+            }
+            return withScratch((directory) => {
+                const path = join(directory, 'operations.yaml');
+                writeFileSync(path, text, 'utf8');
+                return runCli(['apply', path, workspace, '--json'], cwd);
+            });
+        }),
     },
     {
         name: 'yarramate_check',
-        description: 'Deterministic correctness check of a workspace; returns the machine-readable check result. Never a quality or completeness judgement.',
+        description: `Deterministic correctness check of a workspace; returns the machine-readable check result. Never a quality or completeness judgement. Run it after every apply. ${LOOP}`,
         inputSchema: {
             type: 'object',
-            required: ['workspace'],
             properties: workspaceProperty,
         },
-        arguments: (input) => ['check', String(input.workspace), '--json'],
+        run: (input, context) => withWorkspace(input, context, (workspace, cwd) => runCli(['check', workspace, '--json'], cwd)),
     },
     {
         name: 'yarramate_reconcile',
-        description: 'Compare declared architecture with evaluated evidence; returns the reconciliation report with contradicted, unknown, and not-observed findings.',
+        description: `Compare declared architecture with evaluated evidence; returns the reconciliation report with contradicted, unknown, and not-observed findings. ${LOOP}`,
         inputSchema: {
             type: 'object',
-            required: ['workspace'],
             properties: workspaceProperty,
         },
-        arguments: (input) => ['reconcile', String(input.workspace)],
+        run: (input, context) => withWorkspace(input, context, (workspace, cwd) => runCli(['reconcile', workspace], cwd)),
+    },
+    {
+        name: 'yarramate_export',
+        description: `Derives a deliverable from the record and returns it as text: markdown (a projection rendered as prose; needs projection), rtm (the requirements traceability matrix), graph (the compiled semantic graph as JSON), briefs (one brief per subject of a projection; needs projection). xlsx and likec4 write binary or multi-file output, so they need out (and likec4 needs project) and return what was written. ${LOOP}`,
+        inputSchema: {
+            type: 'object',
+            required: ['kind'],
+            properties: {
+                ...workspaceProperty,
+                kind: {
+                    type: 'string',
+                    enum: ['markdown', 'rtm', 'graph', 'briefs', 'xlsx', 'likec4'],
+                },
+                projection: {
+                    type: 'string',
+                    description: 'Projection path, relative to the repository root unless absolute; required for markdown, briefs and xlsx',
+                },
+                out: {
+                    type: 'string',
+                    description: 'Where to write, relative to the repository root (the directory that holds .yarramate) unless absolute: a file for markdown, graph and xlsx; a directory for rtm, briefs and likec4. Optional for the text kinds, which then return the text instead.',
+                },
+                project: {
+                    type: 'string',
+                    description: 'The likec4-project.yaml, required for likec4',
+                },
+                budget: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Approximate token budget per brief (briefs only)',
+                },
+            },
+        },
+        run: (input, context) => withWorkspace(input, context, (workspace, cwd) => {
+            const kind = typeof input.kind === 'string' ? input.kind : '';
+            const projection = typeof input.projection === 'string' ? input.projection : undefined;
+            const out = typeof input.out === 'string' ? input.out : undefined;
+            const budget = typeof input.budget === 'number'
+                ? ['--budget', String(input.budget)]
+                : [];
+            if (kind === 'markdown' || kind === 'graph') {
+                if (kind === 'markdown' && projection === undefined) {
+                    return refuse('yarramate_export markdown needs `projection`: the path of the view to render.');
+                }
+                return runCli([
+                    'export',
+                    kind,
+                    ...(projection === undefined ? [] : [projection]),
+                    workspace,
+                    ...(out === undefined ? [] : ['--out', out]),
+                ], cwd);
+            }
+            if (kind === 'rtm') {
+                if (out !== undefined) {
+                    return runCli(['export', 'rtm', workspace, '--out', out], cwd);
+                }
+                return withScratch((directory) => {
+                    const result = runCli(['export', 'rtm', workspace, '--out', directory], cwd);
+                    if (result.exitCode !== 0)
+                        return result;
+                    return {
+                        exitCode: 0,
+                        stdout: readFileSync(join(directory, 'RTM.md'), 'utf8'),
+                        stderr: '',
+                    };
+                });
+            }
+            if (kind === 'briefs') {
+                if (projection === undefined) {
+                    return refuse('yarramate_export briefs needs `projection`: the path of the view whose subjects get a brief each.');
+                }
+                if (out !== undefined) {
+                    return runCli([
+                        'export',
+                        'briefs',
+                        projection,
+                        workspace,
+                        '--out',
+                        out,
+                        ...budget,
+                    ], cwd);
+                }
+                return withScratch((directory) => {
+                    const result = runCli([
+                        'export',
+                        'briefs',
+                        projection,
+                        workspace,
+                        '--out',
+                        directory,
+                        ...budget,
+                    ], cwd);
+                    if (result.exitCode !== 0)
+                        return result;
+                    const files = readdirSync(directory).sort();
+                    return {
+                        exitCode: 0,
+                        stdout: files
+                            .map((file) => `<!-- ${file} -->\n${readFileSync(join(directory, file), 'utf8')}`)
+                            .join('\n'),
+                        stderr: '',
+                    };
+                });
+            }
+            if (kind === 'xlsx') {
+                if (projection === undefined || out === undefined) {
+                    return refuse('yarramate_export xlsx needs `projection` and `out`: the view to export and the .xlsx path to write; a workbook is binary and cannot come back as text.');
+                }
+                return runCli(['export', 'xlsx', projection, workspace, '--out', out], cwd);
+            }
+            if (kind === 'likec4') {
+                const project = typeof input.project === 'string' ? input.project : undefined;
+                if (project === undefined || out === undefined) {
+                    return refuse('yarramate_export likec4 needs `project` (the likec4-project.yaml) and `out` (the directory to write).');
+                }
+                return runCli(['export', 'likec4', project, out, workspace], cwd);
+            }
+            return refuse('yarramate_export needs `kind`: one of markdown, rtm, graph, briefs, xlsx, likec4.');
+        }),
     },
 ];
+/** The tool list a client sees; exported so a test can read it without stdio. */
+export const toolCatalogue = tools.map(({ name, description, inputSchema }) => ({
+    name,
+    description,
+    inputSchema,
+}));
 const respond = (id, result) => {
     process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`);
 };
 const respondError = (id, code, message) => {
     process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } })}\n`);
 };
-export const handleRequest = (request) => {
+export const handleRequest = (request, context = { cwd: process.cwd(), workspace: undefined }) => {
     const id = request.id ?? null;
     if (request.method === 'initialize') {
         respond(id, {
             protocolVersion: '2025-06-18',
             capabilities: { tools: {} },
             serverInfo: { name: 'yarramate', version: packageVersion },
-            instructions: 'Read-only architecture context for YarraMate workspaces. The native documents in the repository remain canonical; this server never mutates them.',
+            instructions: `The architecture record of a YarraMate workspace. The native documents in the repository are canonical; every read renders them, and yarramate_apply is the one write, the same atomic batch the CLI lands. ${LOOP}`,
         });
         return;
     }
     if (request.method === 'tools/list') {
-        respond(id, {
-            tools: tools.map(({ name, description, inputSchema }) => ({
-                name,
-                description,
-                inputSchema,
-            })),
-        });
+        respond(id, { tools: toolCatalogue });
         return;
     }
     if (request.method === 'tools/call') {
@@ -129,7 +344,7 @@ export const handleRequest = (request) => {
         const input = typeof params.arguments === 'object' && params.arguments !== null
             ? params.arguments
             : {};
-        const result = runCli([...tool.arguments(input)], process.cwd());
+        const result = tool.run(input, context);
         respond(id, {
             content: [
                 {
@@ -147,6 +362,27 @@ export const handleRequest = (request) => {
         respondError(id, -32601, `Method "${request.method}" not found`);
     }
 };
+/** `yarramate-mcp [--workspace <path>]`; anything else is refused with usage. */
+export const parseServerOptions = (argv) => {
+    let workspace;
+    for (let index = 0; index < argv.length; index += 1) {
+        const option = argv[index];
+        if (option === '--workspace') {
+            const value = argv[index + 1];
+            if (value === undefined ||
+                value.startsWith('-') ||
+                workspace !== undefined) {
+                return undefined;
+            }
+            workspace = value;
+            index += 1;
+            continue;
+        }
+        return undefined;
+    }
+    return { workspace };
+};
+export const serverUsage = 'Usage:\n  yarramate-mcp [--workspace <workspace.yaml>]\n  yarramate-mcp --version\n';
 if (isMainModule(import.meta.url, process.argv[1])) {
     if (process.argv[2] === '--version') {
         const result = versionResult('yarramate-mcp');
@@ -154,25 +390,36 @@ if (isMainModule(import.meta.url, process.argv[1])) {
         process.exitCode = result.exitCode;
     }
     else {
-        const lines = createInterface({ input: process.stdin });
-        lines.on('line', (line) => {
-            const text = line.trim();
-            if (text.length === 0)
-                return;
-            let request;
-            try {
-                request = JSON.parse(text);
-            }
-            catch {
-                respondError(null, -32700, 'Parse error');
-                return;
-            }
-            try {
-                handleRequest(request);
-            }
-            catch (error) {
-                respondError(request.id ?? null, -32603, error instanceof Error ? error.message : String(error));
-            }
-        });
+        const options = parseServerOptions(process.argv.slice(2));
+        if (options === undefined) {
+            process.stderr.write(serverUsage);
+            process.exitCode = 2;
+        }
+        else {
+            const context = {
+                cwd: process.cwd(),
+                workspace: options.workspace,
+            };
+            const lines = createInterface({ input: process.stdin });
+            lines.on('line', (line) => {
+                const text = line.trim();
+                if (text.length === 0)
+                    return;
+                let request;
+                try {
+                    request = JSON.parse(text);
+                }
+                catch {
+                    respondError(null, -32700, 'Parse error');
+                    return;
+                }
+                try {
+                    handleRequest(request, context);
+                }
+                catch (error) {
+                    respondError(request.id ?? null, -32603, error instanceof Error ? error.message : String(error));
+                }
+            });
+        }
     }
 }

package/dist/adapters/visual/protocol-contract.d.ts

@@ -118,6 +118,29 @@ export interface VisualChoiceSelectedPayload {
     readonly choiceId: string;
     readonly optionId: string;
 }
+/**
+ * The reviewer hands one open question to the agent (#515, ADR 0151). The
+ * phrasing rides along so the transcript, the journal and the agent read the
+ * same words; the agent still computes the step from the record, because the
+ * question is a reading of the model at one moment and the model may have
+ * moved since the row was drawn.
+ */
+export interface VisualQuestionDelegatePayload {
+    readonly questionId: string;
+    /** Null for a workspace-scoped question, which names no subject. */
+    readonly subjectId: string | null;
+    readonly question: string;
+}
+/**
+ * The agent's answer to a delegated question: operations it PROPOSES, which
+ * the browser stages into the reviewer's changeset and the reviewer commits
+ * (ADR 0151). The agent never writes (ADR 0084, ADR 0088); this is how it
+ * answers without doing so. `note` is the line the transcript shows.
+ */
+export interface VisualOperationsProposePayload {
+    readonly note: string;
+    readonly operations: readonly YarramateOperation[];
+}
 export interface VisualViewNavigatePayload {
     readonly viewId: string;
     readonly requiresAttention: boolean;
@@ -410,6 +433,10 @@ export type VisualBrowserInput = {
     readonly type: "session.end";
     readonly lastAcknowledgedSequence: number;
     readonly payload: VisualBrowserSessionEndPayload;
+} | {
+    readonly type: "question.delegate";
+    readonly lastAcknowledgedSequence: number;
+    readonly payload: VisualQuestionDelegatePayload;
 };
 interface VisualEventEnvelope<Type extends string, Payload> {
     readonly format: "yarramate/visual-event/v1";
@@ -420,7 +447,7 @@ interface VisualEventEnvelope<Type extends string, Payload> {
     readonly timestamp: string;
     readonly payload: Payload;
 }
-export type VisualEvent = VisualEventEnvelope<"chat.message", VisualChatMessagePayload> | VisualEventEnvelope<"choice.selected", VisualChoiceSelectedPayload> | VisualEventEnvelope<"view.navigate", VisualViewNavigatePayload> | VisualEventEnvelope<"session.end", VisualSessionEndPayload> | VisualEventEnvelope<"browser.connected", VisualBrowserConnectedPayload> | VisualEventEnvelope<"browser.disconnected", VisualBrowserDisconnectedPayload> | VisualEventEnvelope<"filter.query", VisualFilterQueryPayload> | VisualEventEnvelope<"changeset.commit", VisualChangesetCommitPayload> | VisualEventEnvelope<"layout.save", VisualLayoutSavePayload>;
+export type VisualEvent = VisualEventEnvelope<"chat.message", VisualChatMessagePayload> | VisualEventEnvelope<"choice.selected", VisualChoiceSelectedPayload> | VisualEventEnvelope<"question.delegate", VisualQuestionDelegatePayload> | VisualEventEnvelope<"view.navigate", VisualViewNavigatePayload> | VisualEventEnvelope<"session.end", VisualSessionEndPayload> | VisualEventEnvelope<"browser.connected", VisualBrowserConnectedPayload> | VisualEventEnvelope<"browser.disconnected", VisualBrowserDisconnectedPayload> | VisualEventEnvelope<"filter.query", VisualFilterQueryPayload> | VisualEventEnvelope<"changeset.commit", VisualChangesetCommitPayload> | VisualEventEnvelope<"layout.save", VisualLayoutSavePayload>;
 /**
  * The filter a chat turn resolved to. The agent states `query` and nothing
  * else: the runtime evaluates it against the same graph a `filter.query`
@@ -499,7 +526,7 @@ interface VisualResponseEnvelope<Type extends string, Payload> {
     readonly timestamp: string;
     readonly payload: Payload;
 }
-export type VisualResponse = VisualResponseEnvelope<"chat.response", VisualChatResponsePayload> | VisualResponseEnvelope<"agent.status", VisualAgentStatusPayload> | VisualResponseEnvelope<"choice.present", VisualChoicePresentPayload> | VisualResponseEnvelope<"handoff.complete", VisualHandoffSummary> | VisualResponseEnvelope<"diagnostic", VisualDiagnosticPayload>;
+export type VisualResponse = VisualResponseEnvelope<"chat.response", VisualChatResponsePayload> | VisualResponseEnvelope<"agent.status", VisualAgentStatusPayload> | VisualResponseEnvelope<"choice.present", VisualChoicePresentPayload> | VisualResponseEnvelope<"operations.propose", VisualOperationsProposePayload> | VisualResponseEnvelope<"handoff.complete", VisualHandoffSummary> | VisualResponseEnvelope<"diagnostic", VisualDiagnosticPayload>;
 export type VisualHandoffDecision = "completed" | "cancelled" | "failed";
 export type VisualTerminationReason = "user-ended" | "child-failed" | "browser-timeout" | "main-cancelled" | "server-failed" | "compiler-failed";
 export interface VisualHandoff extends VisualHandoffSummary {

package/dist/adapters/visual/session-server.js

@@ -72,6 +72,7 @@ const CONTENT_TYPES = {
 const TURN_COMPLETING = {
     "chat.response": true,
     "choice.present": true,
+    "operations.propose": true,
     "handoff.complete": true,
     diagnostic: true,
 };
@@ -272,6 +273,8 @@ const eventFrom = (input, envelope) => {
             return { ...envelope, type: input.type, payload: input.payload };
         case "choice.selected":
             return { ...envelope, type: input.type, payload: input.payload };
+        case "question.delegate":
+            return { ...envelope, type: input.type, payload: input.payload };
         case "view.navigate":
             return { ...envelope, type: input.type, payload: input.payload };
         case "session.end":
@@ -836,7 +839,9 @@ export const startVisualServer = async (options) => {
     const recordEvent = (event) => {
         // A session on its way out waits on nobody, and asking past the question
         // is how a reviewer declines to answer it.
-        if (event.type === "chat.message" || event.type === "session.end") {
+        if (event.type === "chat.message" ||
+            event.type === "question.delegate" ||
+            event.type === "session.end") {
             pendingChoice = null;
         }
         if (event.type === "session.end")
@@ -849,6 +854,15 @@ export const startVisualServer = async (options) => {
             });
             return;
         }
+        if (event.type === "question.delegate") {
+            // The line the reviewer sees for handing a question over (#515).
+            transcript.push({
+                id: event.eventId,
+                speaker: "reviewer",
+                text: `Answer via your agent: ${event.payload.question}`,
+            });
+            return;
+        }
         if (event.type !== "choice.selected")
             return;
         if (pendingChoice?.choiceId === event.payload.choiceId)
@@ -874,9 +888,11 @@ export const startVisualServer = async (options) => {
         }
         const text = response.type === "chat.response"
             ? response.payload.text
-            : response.type === "handoff.complete"
-                ? response.payload.summary
-                : undefined;
+            : response.type === "operations.propose"
+                ? response.payload.note
+                : response.type === "handoff.complete"
+                    ? response.payload.summary
+                    : undefined;
         if (text === undefined)
             return;
         transcript.push({ id: response.responseId, speaker: "agent", text });
@@ -1157,7 +1173,10 @@ export const startVisualServer = async (options) => {
             }
             // A session that was started without a conversation has no chat and no
             // choices to make; the diagram, and moving around it, is all it granted.
-            const granted = input.value.type === "chat.message"
+            // Delegating a question is a chat turn by another door (#515): it
+            // needs the same agent the composer needs.
+            const granted = input.value.type === "chat.message" ||
+                input.value.type === "question.delegate"
                 ? capabilities.chat
                 : input.value.type === "choice.selected"
                     ? capabilities.choices
@@ -1677,7 +1696,9 @@ export const startVisualServer = async (options) => {
         // The agent cannot hold a conversation a diagram-only session never
         // offered; the browser has nowhere to show one.
         if (!capabilities.chat &&
-            (response.type === "chat.response" || response.type === "choice.present")) {
+            (response.type === "chat.response" ||
+                response.type === "choice.present" ||
+                response.type === "operations.propose")) {
             respondJson(server, 409, {
                 accepted: false,
                 diagnostics: [