@akagilnc/pi-workflow-roles 0.1.3771 → 0.1.3789

package/dist/public-cli/option-definitions.js

@@ -483,8 +483,8 @@ const COLLECTOR_OPTIONS = [
         repeatable: false,
         form: "option",
         description: {
-            en: "Optional request manifest JSON path ({requests:[{id,body}]}).",
-            zh: "可选 request manifest JSON 路径（{requests:[{id,body}]}）。",
+            en: "Optional request manifest JSON path ({requests:[{id,body}]}). Role may also decide request bodies from handbook/field activity without this file.",
+            zh: "可选 request manifest JSON 路径（{requests:[{id,body}]}）。角色亦可依手册/现场自行判定请求正文，不必依赖本文件。",
         },
     },
 ];

package/dist/public-role-summons.js

@@ -99,9 +99,9 @@ async function createSummonEnv(options) {
   const hostName = options.seat.host ?? "pi";
   let roleTurnHost = piHost;
   if (hostName !== "pi") {
-    const { lookupHostDescription } = await import("./host-descriptions.js");
-    const { loadProductionAcpHostFactory } = await import("./public-cli/load-production-acp-host.js");
-    if (lookupHostDescription(hostName) === void 0) {
+    const { lookupHostFamily } = await import("./host-descriptions.js");
+    const { loadProductionExternalHostFactory } = await import("./public-cli/load-production-external-host.js");
+    if (lookupHostFamily(hostName) === void 0) {
       throw new Error(
         `public role summons host unregistered: host=${hostName} seat=${options.role}`
       );
@@ -109,7 +109,7 @@ async function createSummonEnv(options) {
     let hostPromise;
     roleTurnHost = {
       executeTurn: async (request) => {
-        hostPromise ??= loadProductionAcpHostFactory(options.packageRoot, hostName).then(
+        hostPromise ??= loadProductionExternalHostFactory(options.packageRoot, hostName).then(
           (create) => create({
             packageRoot: options.packageRoot,
             principalAuthority
@@ -151,7 +151,8 @@ async function summonPublicRole(options) {
   } = await import("./public-cli/config.js");
   const credentials = options.credentials ?? await loadCredentialProviders(agentDir);
   const config = await loadPublicCliConfig(home);
-  const seat = resolveEffectiveSeat(config, options.role, credentials);
+  const invocation = options.host === void 0 ? void 0 : { host: options.host };
+  const seat = resolveEffectiveSeat(config, options.role, credentials, invocation);
   const env = {
     ...await createSummonEnv({
       role: options.role,
@@ -263,6 +264,38 @@ async function summonPublicRole(options) {
     ...stderr === void 0 || stderr === "" ? {} : { stderr }
   };
 }
+async function parentInvocationHost(sourceRunDirectory) {
+  const { readFile } = await import("node:fs/promises");
+  const path = join(sourceRunDirectory, "invocation.json");
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    const code = error instanceof Error && "code" in error ? error.code : void 0;
+    throw new Error(
+      `parent invocation.json required for gate source run at ${path}: ${code ?? (error instanceof Error ? error.message : String(error))}`,
+      { cause: error }
+    );
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    throw new Error(
+      `parent invocation.json unreadable at ${path}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`parent invocation.json has non-object shape at ${path}`);
+  }
+  const host = raw.host;
+  if (host === void 0) return void 0;
+  if (typeof host !== "string" || host.trim() === "") {
+    throw new Error(`parent invocation.json host must be a non-empty string at ${path}`);
+  }
+  return host;
+}
 async function summonGateOfficer(options) {
   let home = options.home;
   if (home === void 0) {
@@ -276,6 +309,7 @@ async function summonGateOfficer(options) {
       submission: options.submission
     });
   }
+  const parentHost = await parentInvocationHost(options.sourceRunDirectory);
   const common = {
     cwd: options.cwd,
     ...home === void 0 ? {} : { home },
@@ -284,6 +318,7 @@ async function summonGateOfficer(options) {
     ...options.signal === void 0 ? {} : { signal: options.signal },
     ...options.reask === void 0 ? {} : { reviewReask: options.reask },
     ...gateReviewInstruction === void 0 ? {} : { gateReviewInstruction },
+    ...parentHost === void 0 ? {} : { host: parentHost },
     ...options.roleTurnHost === void 0 ? {} : { roleTurnHost: options.roleTurnHost },
     ...options.createRunId === void 0 ? {} : { createRunId: options.createRunId }
   };

package/dist/role-runtime.js

@@ -1223,6 +1223,9 @@ export function createRoleRuntimeExtension(dependencies) {
             ...(dependencies.createCollectorClock === undefined
                 ? {}
                 : { createClock: dependencies.createCollectorClock }),
+            ...(dependencies.loadCollectorHandbookSeed === undefined
+                ? {}
+                : { loadHandbookSeed: dependencies.loadCollectorHandbookSeed }),
         }, hostActions);
         // #676 J1: business tools + tool_call gate register only behind admission/activation.
         // before_agent_start / tool_result collector branches live on the shared envelope hooks above.

package/extensions/role-runtime.ts

@@ -40,6 +40,7 @@ import { loadGatekeeperSessionMaterials, loadMainRoleSessionMaterials } from "..
 const extensionPath = fileURLToPath(import.meta.url);
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const navigatorRoutePlaybookPath = fileURLToPath(new URL("../resources/navigator-route-playbook.md", import.meta.url));
+const collectorHandbookSeedPath = fileURLToPath(new URL("../resources/collector-bot-handbook.md", import.meta.url));
 // #675: nested public summons (gate/auditor) resolve root via env under jiti.
 if (process.env.AK_ROLE_PACKAGE_ROOT === undefined || process.env.AK_ROLE_PACKAGE_ROOT.trim() === "") {
   process.env.AK_ROLE_PACKAGE_ROOT = packageRoot;
@@ -122,6 +123,7 @@ export default function roleRuntime(pi: ExtensionAPI): void {
     createReviewerPinnedGitReader: () => createReviewerPinnedGitReader(),
     createReviewerIssueFetcher: () => createGhIssueSoftFetcher(),
     loadCollectorSoul: () => loadMainRoleSessionMaterials("collector"),
+    loadCollectorHandbookSeed: () => readFile(collectorHandbookSeedPath, "utf8"),
     createCollectorTransport: () => createGhCollectorGitHubTransport(),
     loadDoctorSoul: () => loadMainRoleSessionMaterials("doctor"),
     loadDoctorCase,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.3771",
+  "version": "0.1.3789",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/resources/collector-bot-handbook.md

@@ -0,0 +1,33 @@
+# 通进司 bot 工作记忆（通用）
+
+薄手册：触发方式、自动/手动条件、完成与不可继续的识别线索、官方出处。
+内容是角色阅读与修正的工作记忆，不是代码状态规则；临时额度/故障不得固化为永久行为。
+参与者依本仓使用与现场活动辨认，不把下列名称当作全仓固定名单。
+
+## Codex（hosted GitHub connector）
+
+- 官方：https://learn.chatgpt.com/docs/third-party/github
+- 常见主动请求：`@codex review`
+- 新建 PR 常有自动评审；是否已在审当前提交以现场 reviews/comments 为准
+
+## CodeRabbit
+
+- 官方：https://docs.coderabbit.ai/configuration/auto-review
+- 命令：https://docs.coderabbit.ai/guides/commands
+- 常见主动请求：`@coderabbitai review`；全量：`@coderabbitai full review`
+- 默认常为增量；本仓实际自动/暂停以现场与仓库差异条为准
+
+## Sourcery
+
+- 官方：https://docs.sourcery.ai/reviews/ 与 https://docs.sourcery.ai/reviews/commands/
+- 新建/更新与主动请求依文档与本仓现场
+
+## Cursor Bugbot / 自动化
+
+- 官方：https://prod.cursor.com/help/ai-features/bugbot 与 automations 文档
+- 内置 Bugbot 与同账号自定义任务须区分；某任务额度耗尽不推断其他任务失效
+
+## 修正规则
+
+- 优先引用官方文档；现场差异记入仓库差异条并附 PR/证据指针
+- 未知或暂未响应 ≠ 通过或确定死亡

package/scripts/build-package.mjs

@@ -114,6 +114,33 @@ export async function buildAcpProductionHost(
   );
 }
 
+/**
+ * Deferred generic headless production host artifact (#645). Same peer-free
+ * selection face as ACP: loaded only when a headless description-table row is
+ * selected.
+ */
+export async function buildHeadlessProductionHost(
+  outfile = "dist/headless-host/production-host.js",
+) {
+  await mkdir(dirname(outfile), { recursive: true });
+  await build({
+    entryPoints: ["src/headless-host/production-host.ts"],
+    outfile,
+    format: "esm",
+    platform: "node",
+    target: "node20",
+    bundle: true,
+    packages: "external",
+    logLevel: "silent",
+  });
+  // Shared envelope resolves ./mcp-relay.mjs from import.meta.url of the bundle
+  // (#645 headless reuses the ACP relay for AK tools under --mcp-config).
+  await copyFile(
+    resolve("src/acp-host/mcp-relay.mjs"),
+    join(dirname(outfile), "mcp-relay.mjs"),
+  );
+}
+
 export async function buildPackageArtifacts() {
   await build({
     entryPoints: entries.map((name) => `src/${name}.ts`),
@@ -139,6 +166,7 @@ export async function buildPackageArtifacts() {
   }
   await buildPublicAkRoleBin();
   await buildAcpProductionHost();
+  await buildHeadlessProductionHost();
 }
 
 const isMain =

package/src/acp-host/production-host.ts

@@ -39,6 +39,9 @@ export type ProductionAcpHostOptions = Readonly<{
 const navigatorRoutePlaybookPath = fileURLToPath(
   new URL("../../resources/navigator-route-playbook.md", import.meta.url),
 );
+const collectorHandbookSeedPath = fileURLToPath(
+  new URL("../../resources/collector-bot-handbook.md", import.meta.url),
+);
 
 /** Host-neutral packaged role runtime deps for the ACP parent-process envelope. */
 export function createAcpRoleRuntimeDependencies(packageRoot: string): RoleRuntimeDependencies {
@@ -55,6 +58,7 @@ export function createAcpRoleRuntimeDependencies(packageRoot: string): RoleRunti
     createReviewerPinnedGitReader: () => createReviewerPinnedGitReader(),
     createReviewerIssueFetcher: () => createGhIssueSoftFetcher(),
     loadCollectorSoul: () => loadMainRoleSessionMaterials("collector"),
+    loadCollectorHandbookSeed: () => readFile(collectorHandbookSeedPath, "utf8"),
     createCollectorTransport: () => createGhCollectorGitHubTransport(),
     loadDoctorSoul: () => loadMainRoleSessionMaterials("doctor"),
     loadDoctorCase,

package/src/acp-host/role-envelope.ts

@@ -15,7 +15,7 @@ import type {
   RoleTurnKnownFailure,
   RoleTurnRequest,
 } from "../host-contracts.ts";
-import { packagedRoleInputFlag, packagedRolePhaseFlag } from "../packaged-role-registry.ts";
+import { packagedRoleInputFlag, packagedRoleOutputTool, packagedRolePhaseFlag } from "../packaged-role-registry.ts";
 import { stripSkillFrontmatter } from "../package-resources/method-skill.ts";
 import {
   createRoleRuntimeExtension,
@@ -131,10 +131,33 @@ export function createComposedAcpRoleTurnHost(
   });
 }
 
+/** JSON Schema draft-07 document for host-native `--json-schema` (headless). */
+export function terminatingToolJsonSchema(parameters: unknown): Readonly<Record<string, unknown>> {
+  const cloned = JSON.parse(JSON.stringify(parameters)) as Record<string, unknown>;
+  // $schema last so a newer declaration on the tool parameters cannot override draft-07.
+  return Object.freeze({
+    ...cloned,
+    $schema: "http://json-schema.org/draft-07/schema#",
+  });
+}
+
 export async function prepareAcpRoleEnvelope(options: {
   readonly request: RoleTurnRequest;
   readonly dependencies: RoleRuntimeDependencies;
+  /**
+   * MCP unix socket path for the protocol-relay child. Always required — AK tools
+   * ride this single MCP path; headless structured_output reuses the same
+   * terminating-tool ledger path without listing the terminating tool on MCP.
+   */
   readonly socketPath: string;
+  /**
+   * Whether MCP `tools/list` advertises the role terminating tool.
+   * ACP keeps it listed (session-tool receipt). Headless hides it so the host
+   * native `--json-schema` / structured_output is the sole schema channel
+   * (#750 submission-tool-is-schema-channel) and empty MCP probes cannot
+   * pre-empt a later structured_output.
+   */
+  readonly listTerminatingToolOnMcp?: boolean;
   /**
    * Durable principal session path (header layout only).
    * Production passes DurablePrincipalAuthority.decode(principal).sessionFile so
@@ -143,6 +166,14 @@ export async function prepareAcpRoleEnvelope(options: {
   readonly sessionFile?: string;
 }): Promise<AcpPreparedTurn> {
   const { request } = options;
+  if (options.socketPath === "") {
+    throw new Error("prepareAcpRoleEnvelope requires socketPath");
+  }
+  const listTerminatingToolOnMcp = options.listTerminatingToolOnMcp !== false;
+  const earlyTerminatingTool = packagedRoleOutputTool(request.activation.role);
+  if (earlyTerminatingTool === undefined) {
+    throw new Error(`role has no terminating tool: ${request.activation.role}`);
+  }
   const flags = projectAcpActivationFlags(request);
   const tools = new Map<string, HostToolDefinition>();
   const handlers = new Map<string, Handler[]>();
@@ -403,6 +434,87 @@ export async function prepareAcpRoleEnvelope(options: {
     await emit("tool_execution_end", { toolCallId, toolName, isError: projected.isError });
     return projected;
   }
+  /**
+   * Shared terminating/support tool path for MCP relay and headless structured_output.
+   * Books the call, runs execute, projects tool_result; does not emit turn_end (closeRound).
+   */
+  async function invokeAkTool(name: string, args: unknown): Promise<{
+    content: ContentPart[];
+    isError: boolean;
+    blocked?: true;
+  }> {
+    const tool = tools.get(name);
+    if (tool === undefined) throw new Error(`Unknown AK tool: ${name}`);
+    const toolCallId = randomUUID();
+    calls.push({ toolCallId, toolName: name });
+    // First-record-then-audit: book the tool-call leaf in memory before execute so
+    // judge/doctor subject gates see the candidate on parent session books.
+    sessionEntries.push({
+      type: "message",
+      message: {
+        role: "assistant" as const,
+        content: [{
+          type: "toolCall",
+          id: toolCallId,
+          name,
+          arguments: args ?? {},
+        }],
+      },
+    });
+    try {
+      await emit("tool_execution_start", { toolCallId, toolName: name });
+      const blocked = (await emit("tool_call", { toolCallId, toolName: name, input: (args ?? {}) as Record<string, unknown> }))
+        .some((value) => typeof value === "object" && value !== null && "block" in value && value.block === true);
+      if (blocked) {
+        // Lawful seatbelt/block stays bare rejection — not infrastructure (#593 r3).
+        return { content: [{ type: "text", text: `AK tool blocked: ${name}` }], isError: true, blocked: true };
+      }
+    } catch (error) {
+      // Pre-execution emit failure shares the non-correctable infra pathway (#593 r3).
+      const declared = declareRoundInfrastructureFailure(error);
+      try {
+        const projected = await projectToolResult(toolCallId, name, {
+          content: declared.content,
+          details: declared.details,
+          isError: true,
+        });
+        return { content: projected.content, isError: true };
+      } catch {
+        return { content: declared.content, isError: true };
+      }
+    }
+    try {
+      const result = await tool.execute(toolCallId, (args ?? {}) as never, undefined, undefined, context);
+      const projected = await projectToolResult(toolCallId, name, {
+        content: result.content,
+        details: result.details,
+        isError: false,
+      });
+      // Candidate only: seal waits for closeRound after the host round boundary.
+      return { content: projected.content, isError: projected.isError };
+    } catch (error) {
+      let content: ContentPart[];
+      let details: Record<string, unknown>;
+      if (isCorrectableExecuteError(error)) {
+        const projected = projectCorrectableExecuteRejection(error);
+        content = [{ type: "text", text: projected.diagnostic }];
+        details = projected.details;
+      } else {
+        // Slot-before-abort; projectToolResult may still project durable details.
+        ({ content, details } = declareRoundInfrastructureFailure(error));
+      }
+      // The shared envelope's tool_result handler is the sole classifier:
+      // it projects either the structured submission non-pass (correctable
+      // rejection) or the typed infrastructure fact onto the reply.
+      const projected = await projectToolResult(toolCallId, name, {
+        content,
+        details,
+        isError: true,
+      });
+      return { content: projected.content, isError: projected.isError };
+    }
+  }
+
   function reply(socket: Socket, id: number, result?: unknown, error?: unknown): void {
     const rpcError = error instanceof Error
       ? { code: "ak-relay-failure", name: error.name, message: error.message }
@@ -424,7 +536,9 @@ export async function prepareAcpRoleEnvelope(options: {
           if (rpc.token !== token) { reply(socket, rpc.id, undefined, "unauthorized relay"); return; }
           try {
             if (rpc.method === "tools/list") {
-              reply(socket, rpc.id, { tools: [...tools.values()].map((tool) => {
+              const listed = [...tools.values()].filter((tool) =>
+                listTerminatingToolOnMcp || tool.name !== earlyTerminatingTool);
+              reply(socket, rpc.id, { tools: listed.map((tool) => {
                 return { name: tool.name, description: tool.description, inputSchema: tool.parameters };
               }) });
               return;
@@ -433,95 +547,24 @@ export async function prepareAcpRoleEnvelope(options: {
             const params = rpc.params as ToolCallParams | undefined;
             const name = params?.name;
             if (typeof name !== "string") throw new Error("MCP tool name is missing");
-            const tool = tools.get(name);
-            if (tool === undefined) throw new Error(`Unknown AK tool: ${name}`);
-            const toolCallId = randomUUID();
-            calls.push({ toolCallId, toolName: name });
-            // First-record-then-audit: book the tool-call leaf in memory before execute so
-            // judge/doctor subject gates see the candidate on parent session books.
-            {
-              const message = {
-                role: "assistant" as const,
-                content: [{
-                  type: "toolCall",
-                  id: toolCallId,
-                  name,
-                  arguments: params?.arguments ?? {},
-                }],
-              };
-              sessionEntries.push({ type: "message", message });
+            // Headless schema channel owns the terminating receipt — refuse MCP
+            // terminating calls so an empty probe cannot book a non-sealable candidate.
+            if (!listTerminatingToolOnMcp && name === earlyTerminatingTool) {
+              throw new Error(`terminating tool ${name} is schema-channel only on this host`);
             }
-            try {
-              await emit("tool_execution_start", { toolCallId, toolName: name });
-              const blocked = (await emit("tool_call", { toolCallId, toolName: name, input: params?.arguments ?? {} }))
-                .some((value) => typeof value === "object" && value !== null && "block" in value && value.block === true);
-              if (blocked) {
-                // Lawful seatbelt/block stays bare RPC rejection — not infrastructure (#593 r3).
-                reply(socket, rpc.id, undefined, new Error(`AK tool blocked: ${name}`));
-                return;
-              }
-            } catch (error) {
-              // Pre-execution emit failure (e.g. observation writer) shares the same
-              // non-correctable infra pathway as execute throws (#593 r3).
-              const declared = declareRoundInfrastructureFailure(error);
-              try {
-                const projected = await projectToolResult(toolCallId, name, {
-                  content: declared.content,
-                  details: declared.details,
-                  isError: true,
-                });
-                reply(socket, rpc.id, {
-                  content: projected.content,
-                  isError: true,
-                });
-              } catch {
-                // Slot already filled; durable projection may have partially failed.
-                reply(socket, rpc.id, {
-                  content: declared.content,
-                  isError: true,
-                });
-              }
+            const outcome = await invokeAkTool(name, params?.arguments ?? {});
+            if (outcome.blocked === true) {
+              reply(socket, rpc.id, undefined, new Error(outcome.content.map((p) => p.type === "text" ? p.text : "").join("")));
               return;
             }
-            try {
-              const result = await tool.execute(toolCallId, (params?.arguments ?? {}) as never, undefined, undefined, context);
-              const projected = await projectToolResult(toolCallId, name, {
-                content: result.content,
-                details: result.details,
-                isError: false,
-              });
-              // Candidate only: do not emit turn_end here. Seal waits for the typed ACP
-              // round boundary (closeRound after session/prompt), so delayed siblings stay
-              // in the same round instead of becoming silent post-seal anomalies.
-              reply(socket, rpc.id, { content: projected.content, ...(projected.isError ? { isError: true } : {}) });
-            } catch (error) {
-              let content: ContentPart[];
-              let details: Record<string, unknown>;
-              if (isCorrectableExecuteError(error)) {
-                const projected = projectCorrectableExecuteRejection(error);
-                content = [{ type: "text", text: projected.diagnostic }];
-                details = projected.details;
-              } else {
-                // Slot-before-abort; projectToolResult may still project durable details.
-                ({ content, details } = declareRoundInfrastructureFailure(error));
-              }
-              // The shared envelope's tool_result handler is the sole classifier:
-              // it projects either the structured submission non-pass (correctable
-              // rejection) or the typed infrastructure fact onto the reply.
-              const projected = await projectToolResult(toolCallId, name, {
-                content,
-                details,
-                isError: true,
-              });
-              reply(socket, rpc.id, { content: projected.content, ...(projected.isError ? { isError: true } : {}) });
-            }
+            reply(socket, rpc.id, { content: outcome.content, ...(outcome.isError ? { isError: true } : {}) });
           } catch (error) { reply(socket, rpc.id, undefined, error); }
         })();
       }
     });
   }
-  await listen(server, options.socketPath);
   const relay = fileURLToPath(new URL("./mcp-relay.mjs", import.meta.url));
+  await listen(server, options.socketPath);
   let disposed = false;
   // Tools execute in this process (relay is protocol-only). Mirror Pi's child-env
   // AK_ROLE_RUN_DIR / AK_ROLE_COURT_ATTEMPT injection onto the parent so ledger
@@ -552,8 +595,6 @@ export async function prepareAcpRoleEnvelope(options: {
     } catch (error) {
       cleanupFailures.push(error);
     }
-    // Server closure is unconditional: a shutdown-handler failure must not leave
-    // the listening MCP server keeping the completed invocation alive.
     try {
       const closeAll = (server as unknown as { closeAllConnections?: () => void }).closeAllConnections;
       if (typeof closeAll === "function") closeAll.call(server);
@@ -571,6 +612,14 @@ export async function prepareAcpRoleEnvelope(options: {
     }
   };
 
+  const terminatingToolName: string = earlyTerminatingTool;
+  async function ingestStructuredOutput(params: unknown): Promise<void> {
+    // MCP path may already have invoked the terminating tool this round; skip the
+    // duplicate so structured_output + tool-call does not arm non-sole.
+    if (calls.some((call) => call.toolName === terminatingToolName)) return;
+    await invokeAkTool(terminatingToolName, params ?? {});
+  }
+
   const closeRound: AcpPreparedTurn["closeRound"] = async () => {
     // Typed round boundary: hand the complete call list to the shared ledger once.
     if (calls.length > 0) {
@@ -654,6 +703,11 @@ export async function prepareAcpRoleEnvelope(options: {
     else process.env.AK_ROLE_COURT_ATTEMPT = request.courtAttemptId;
     runDirInjected = true;
 
+    const terminating = tools.get(terminatingToolName);
+    if (terminating === undefined) {
+      throw new Error(`terminating tool not registered after activation: ${terminatingToolName}`);
+    }
+    const jsonSchema = terminatingToolJsonSchema(terminating.parameters);
     return {
       mcpServers: [{
         name: `ak-${request.activation.role}`,
@@ -669,6 +723,9 @@ export async function prepareAcpRoleEnvelope(options: {
       abortSignal: hostAbort.signal,
       closeRound,
       dispose,
+      jsonSchema,
+      terminatingToolName,
+      ingestStructuredOutput,
     };
   } catch (error) {
     // listen already succeeded; dispose is not yet caller-owned. Release the

package/src/acp-host/role-turn-host.ts

@@ -43,6 +43,18 @@ export type AcpPreparedTurn = Readonly<{
     | { readonly accepted: false; readonly failure: RoleTurnKnownFailure }
   >;
   dispose?(): Promise<void>;
+  /**
+   * Headless CLI family (#645): role terminating-tool schema for host-native
+   * `--json-schema`. Present for every prepared turn; ACP ignores it.
+   */
+  jsonSchema: Readonly<Record<string, unknown>>;
+  /** Terminating tool name whose schema is `jsonSchema`. */
+  terminatingToolName: string;
+  /**
+   * Headless CLI family: feed host-native `structured_output` through the same
+   * terminating-tool path the MCP relay uses (ledger + gates). ACP ignores it.
+   */
+  ingestStructuredOutput(params: unknown): Promise<void>;
 }>;
 
 /** Fold structured system-prompt authority into the provider-visible ACP override. */