diff --git a/docs/adr/0012-interactive-replay.md b/docs/adr/0012-interactive-replay.md index 5cce34c76a..b7beb86c10 100644 --- a/docs/adr/0012-interactive-replay.md +++ b/docs/adr/0012-interactive-replay.md @@ -91,7 +91,8 @@ The report carries a bounded `screen`, ranked `suggestions`, one `repairHint` en - Capture failure never replaces or conceals the original replay cause. - Serialized ceilings are 8/24/64 KiB for the compact, default, and full response levels. Overflow goes to a redacted session-scoped artifact. - Entered text is never serialized. Native `.ad` replay replaces expanded variable values with `` in human-readable divergence fields. -- Every surface (daemon text, JSON, Node client `AppError`, MCP `structuredContent`) preserves the structured error. No surface may reduce divergence to text and discard repair data. +- Every surface (daemon text, JSON, Node client `AppError`, MCP text, and MCP `structuredContent` on a structured server) preserves the repair data. No surface may reduce divergence to text that discards it. The default MCP server returns text only, so its error text carries the step, the repair hint (with the concrete resume command when `resume.allowed` is true), the screen, and the suggestions. + Why: clients that receive `structuredContent` show the model that JSON and drop the text, so a default `structuredContent` error replaced the compact report with the larger JSON. A client that reads errors as data opts in with `agent-device mcp --structured`. Resume is `replay --from N --plan-digest `. `N` is a 1-based index into the fully expanded executable plan. @@ -183,6 +184,7 @@ The [divergence construction contract](../../packages/replay-port/docs/replay-di - **An absolute rect tolerance in identity.** No measured drift distribution justifies any constant. - **A publish lock that protects only complete healed files.** It adds lock, lease, and reclaim races for a partial file. Exclusive `linkSync` decides the winner instead. - **Infer a corrective read from its position relative to the later `--from`.** The daemon records actions immediately and cannot know their future resume role, so the inference would retrospectively reinterpret intent. `--record` marks the corrective read explicitly. +- **Keep `structuredContent` on default MCP errors.** Clients that receive it show the model the JSON instead of the compact repair report; data clients opt in with `agent-device mcp --structured`. - **One flag helper with an `allowRecord` policy argument.** A changed literal could let a mutating reader forward `--record` with no schema change. Two named helpers make the capability the helper's name. ## Consequences diff --git a/packages/ad-replay/docs/divergence-and-resume.md b/packages/ad-replay/docs/divergence-and-resume.md index a31e245486..471a3f107e 100644 --- a/packages/ad-replay/docs/divergence-and-resume.md +++ b/packages/ad-replay/docs/divergence-and-resume.md @@ -39,7 +39,7 @@ The daemon computes it under ADR 0012 decision 6, R3. Every divergence includes it, with `manual` when no safer route is proven. It is never absent or null. Its small fixed size permits inclusion at every response level, including `--level digest`. -It must survive these four projections unchanged: daemon text summary, JSON, Node client `AppError`, and MCP `structuredContent`. +It must survive these projections unchanged: daemon text summary, JSON, Node client `AppError`, MCP text, and MCP `structuredContent` where MCP returns it. `screen` has two discriminated forms. `{ state: "available", refsGeneration, refs, truncated }` is a fresh healthy snapshot digest. @@ -96,7 +96,10 @@ All surfaces preserve the daemon error. The Node client rejects with `AppError` and retains `details.divergence`. CLI exits nonzero. Text shows a compact report; JSON includes the complete structured error. -MCP returns `isError: true`, the object in `structuredContent`, and the same compact text summary. +MCP returns `isError: true` and the same compact text summary. +The default MCP server returns that text only, so the text carries the repair fields: step, repair hint, screen refs, and suggestions. +The repair hint includes the concrete resume command when `resume.allowed` is true. +Only `agent-device mcp --structured` and data hosts, such as the AI SDK adapter, also return the object in `structuredContent`. MCP treats divergence as a ref-issuing result, including on the error path. Before return, it merges and pins every `screen` ref with `refsGeneration`. CLI and direct clients receive the daemon error's unpinned refs and generation. @@ -232,8 +235,9 @@ Successful text replay prints one line with replayed count and wall time. - Divergence reports: compact/default/full field and byte ceilings; digest output includes `suggestionCount` without entries; redaction, overflow artifacts, artifact-write failure, available/sparse/capture-failed screens, and original-cause preservation. - Resume: digest emission and rejection after script/include/expansion changes; `resume.allowed` reasons, `--from` indexing, variable-output rejection, control-flow rejection, and `test --from` rejection. - Surfaces: daemon/client/CLI/MCP tests prove typed divergence survives failure. - JSON and MCP structured output retain it. + JSON and MCP structured output (`--structured` and data hosts) retain it. + Default MCP error text carries the repair fields, and MCP pins its screen refs in both modes. MCP pins only actionable error-path refs. No text-only path discards the report. - `repairHint` is present and identical in text, JSON, client `AppError`, and MCP `structuredContent`, including compact `--level digest`. + `repairHint` is present and identical in text, JSON, client `AppError`, MCP text, and MCP `structuredContent` where returned, including compact `--level digest`. - `--update` retirement: no source-file rewrite; suggestions remain bounded, ranked, and deduplicated under the suggestion total order. diff --git a/packages/command-output/src/index.ts b/packages/command-output/src/index.ts index a6eb3f893d..6d97693b8e 100644 --- a/packages/command-output/src/index.ts +++ b/packages/command-output/src/index.ts @@ -13,7 +13,7 @@ export { } from './output-common.ts'; export { colorize, supportsColor } from './output/color.ts'; export type { ColorStream } from './output/color.ts'; -export { formatErrorCandidateViews, formatHumanError } from './output/error.ts'; +export { formatHumanError } from './output/error.ts'; export { formatDeliveredArtifactLines, serializeDevice } from './output/result-serialization.ts'; /** Renders a command's result through the family formatters; the formatter tables load on first call. */ diff --git a/packages/command-output/src/output/error.ts b/packages/command-output/src/output/error.ts index a130d6ddf6..6df70954d7 100644 --- a/packages/command-output/src/output/error.ts +++ b/packages/command-output/src/output/error.ts @@ -170,7 +170,7 @@ function withFullStop(text: string): string { return /[.!?…]$/.test(text) ? text : `${text}.`; } -export function formatErrorCandidateViews(views: ErrorCandidateView[]): string[] { +function formatErrorCandidateViews(views: ErrorCandidateView[]): string[] { return views.flatMap((view) => { if (view.kind === 'element-match') { const remaining = view.matches - view.candidates.length; diff --git a/packages/command-registry/src/flag-definitions-connection.ts b/packages/command-registry/src/flag-definitions-connection.ts index 9a02452cbb..6850d78990 100644 --- a/packages/command-registry/src/flag-definitions-connection.ts +++ b/packages/command-registry/src/flag-definitions-connection.ts @@ -94,6 +94,16 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ projectConfig: false, recorded: false, }, + { + key: 'mcpStructured', + names: ['--structured'], + type: 'boolean', + usageLabel: '--structured', + usageDescription: + 'MCP: advertise tool output schemas and return structuredContent; results are text only by default', + projectConfig: false, + recorded: false, + }, { key: 'tenant', names: ['--tenant'], diff --git a/packages/command-surface/src/schema/command-overrides.ts b/packages/command-surface/src/schema/command-overrides.ts index b85a5930af..7181017f13 100644 --- a/packages/command-surface/src/schema/command-overrides.ts +++ b/packages/command-surface/src/schema/command-overrides.ts @@ -152,8 +152,9 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = { text: { summary: 'Start MCP server', description: - 'Start the official stdio MCP server. It exposes structured command tools backed by the agent-device client. It accepts no flags or arguments other than --help and --version; configure it with AGENT_DEVICE_* environment variables or AGENT_DEVICE_CONFIG.', + 'Start the official stdio MCP server. It exposes command tools backed by the agent-device client. Tool results are compact text by default; mcpOutputFormat: "json", a non-default responseLevel, or includeCost returns JSON text. With --structured, tools also advertise output schemas and return structuredContent, including errors, for clients that read results as data. It accepts no other flags or arguments besides --structured, --help, and --version; configure it with AGENT_DEVICE_* environment variables or AGENT_DEVICE_CONFIG.', }, + allowedFlags: ['mcpStructured'], }, proxy: { text: { diff --git a/packages/contracts/src/cli-flags.ts b/packages/contracts/src/cli-flags.ts index f233bb82a2..a30fe6ae91 100644 --- a/packages/contracts/src/cli-flags.ts +++ b/packages/contracts/src/cli-flags.ts @@ -43,6 +43,7 @@ export type CliFlags = CloudProviderProfileFields & daemonServerMode?: DaemonServerMode; proxyHost?: string; proxyPort?: number; + mcpStructured?: boolean; tenant?: string; sessionIsolation?: SessionIsolationMode; runId?: string; diff --git a/packages/kernel/src/errors-code-policy.test.ts b/packages/kernel/src/errors-code-policy.test.ts index 8fe1a68d7d..e3687782bb 100644 --- a/packages/kernel/src/errors-code-policy.test.ts +++ b/packages/kernel/src/errors-code-policy.test.ts @@ -174,7 +174,7 @@ const EXPECTED_HINT_BY_CODE: Record = { UNAUTHORIZED: 'Refresh daemon metadata and retry the command.', AMBIGUOUS_MATCH: 'Multiple candidates matched. Narrow the query or pass an exact identifier.', REPLAY_DIVERGENCE: - 'Read the divergence report (details.divergence) for the screen and selector suggestions to repair the step.', + 'Repair the step from the divergence report: its screen and selector suggestions.', REPAIR_SESSION_EXPIRED: 'The --save-script repair session was reaped before it was finalized; re-run replay