@akagilnc/pi-workflow-roles 0.1.3558 → 0.1.3572

package/src/{grok → acp-host}/role-turn-host.ts

@@ -3,9 +3,10 @@ import { createInterface } from "node:readline";
 
 import type { RoleTurnHost, RoleTurnKnownFailure, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
 import { renderAgentStartMaterials } from "../agent-start-materials.ts";
+import type { AcpHostDescription } from "./description.ts";
 
-/** ACP v1 surface used by the Grok adapter. Protocol details stay in this module. */
-export interface GrokAcpConnection {
+/** ACP v1 surface used by the generic ACP adapter. Protocol details stay in this module. */
+export interface AcpConnection {
   request(method: string, params: Readonly<Record<string, unknown>>): Promise<Readonly<Record<string, unknown>>>;
   notify(method: string, params: Readonly<Record<string, unknown>>): void;
   /** Subscribe to agent→client notifications (session/update stream, etc.). */
@@ -15,7 +16,7 @@ export interface GrokAcpConnection {
 
 /** The shared envelope, prepared before session/new (systemPrompt delivery) and
  * able to observe the host's real builtin tool surface once it arrives post-session. */
-export type GrokPreparedTurn = Readonly<{
+export type AcpPreparedTurn = Readonly<{
   mcpServers: readonly Readonly<Record<string, unknown>>[];
   /**
    * Structured system-prompt authority. `body` is the provider-facing prompt
@@ -45,24 +46,26 @@ export type GrokPreparedTurn = Readonly<{
 }>;
 
 /** Fold structured system-prompt authority into the provider-visible ACP override. */
-export function renderGrokSystemPromptOverride(authority: {
+export function renderAcpSystemPromptOverride(authority: {
   readonly body: string;
   readonly materials: readonly unknown[];
 }): string {
   return renderAgentStartMaterials(authority.body, authority.materials);
 }
 
-export type GrokSessionIdentityAuthority = Readonly<{
+export type AcpSessionIdentityAuthority = Readonly<{
   load(principal: RoleTurnRequest["principal"]): Promise<string | undefined>;
   bind(principal: RoleTurnRequest["principal"], sessionId: string): Promise<void>;
   /** Durable principal session path for layout ownership / isAvailable — not a rebuild source (#617 DK-4). */
   resolveSessionFile(principal: RoleTurnRequest["principal"]): string;
 }>;
 
-export type GrokRoleTurnHostConfig = Readonly<{
-  sessionIdentity: GrokSessionIdentityAuthority;
-  connect(request: RoleTurnRequest): Promise<GrokAcpConnection>;
-  prepare(request: RoleTurnRequest): Promise<GrokPreparedTurn>;
+export type AcpRoleTurnHostConfig = Readonly<{
+  sessionIdentity: AcpSessionIdentityAuthority;
+  /** Whether a bound resume reuses the native session or mints a fresh one. */
+  boundResume: AcpHostDescription["boundResume"];
+  connect(request: RoleTurnRequest): Promise<AcpConnection>;
+  prepare(request: RoleTurnRequest): Promise<AcpPreparedTurn>;
 }>;
 
 function failure(cause: "activation" | "session" | "output", name: string, code: string, details?: Readonly<Record<string, unknown>>): RoleTurnResult {
@@ -81,7 +84,7 @@ function failure(cause: "activation" | "session" | "output", name: string, code:
 type RpcReply = { readonly id?: unknown; readonly method?: unknown; readonly params?: unknown; readonly result?: unknown; readonly error?: unknown };
 
 function hostAbortedError(): Error & { readonly code: "host-aborted" } {
-  return Object.assign(new Error("Grok host aborted"), { code: "host-aborted" as const });
+  return Object.assign(new Error("ACP host aborted"), { code: "host-aborted" as const });
 }
 
 function acpError(code: string, message: string, cause?: unknown): Error & { readonly code: string } {
@@ -89,23 +92,14 @@ function acpError(code: string, message: string, cause?: unknown): Error & { rea
 }
 
 /** One ACP JSON-RPC stdio process. Natural close/SIGTERM are its only lifecycle exits. */
-export function connectGrokAcpStdio(options: {
+export function connectAcpStdio(options: {
   readonly binary: string;
+  readonly args: readonly string[];
   readonly cwd: string;
   readonly env: NodeJS.ProcessEnv;
-  readonly model?: string;
-  readonly toolset?: string;
   readonly onNotification?: (method: string, params: Readonly<Record<string, unknown>>) => void;
-}): Promise<GrokAcpConnection> {
-  const args = [
-    "agent",
-    ...(options.model === undefined ? [] : ["--model", options.model]),
-    "stdio",
-  ];
-  const env = options.toolset === undefined
-    ? options.env
-    : { ...options.env, GROK_CONFIG: JSON.stringify({ toolset: options.toolset }) };
-  const child = spawn(options.binary, args, { cwd: options.cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+}): Promise<AcpConnection> {
+  const child = spawn(options.binary, [...options.args], { cwd: options.cwd, env: options.env, stdio: ["pipe", "pipe", "pipe"] });
   const pending = new Map<number, { resolve(value: Readonly<Record<string, unknown>>): void; reject(error: Error): void }>();
   const notificationHandlers: Array<(method: string, params: Readonly<Record<string, unknown>>) => void> = [];
   if (options.onNotification !== undefined) notificationHandlers.push(options.onNotification);
@@ -128,12 +122,12 @@ export function connectGrokAcpStdio(options: {
     child.kill("SIGTERM");
   };
   child.stderr.setEncoding("utf8").on("data", (chunk: string) => { stderr += chunk; });
-  child.on("error", (error) => settleClosed(acpError("acp-process-error", `Grok ACP process error: ${error.message}`, error)));
+  child.on("error", (error) => settleClosed(acpError("acp-process-error", `ACP process error: ${error.message}`, error)));
   createInterface({ input: child.stdout }).on("line", (line) => {
     let message: RpcReply;
     try { message = JSON.parse(line) as RpcReply; }
     catch (error) {
-      terminate(acpError("acp-invalid-json", `Invalid Grok ACP JSON: ${String(error)}`, error));
+      terminate(acpError("acp-invalid-json", `Invalid ACP JSON: ${String(error)}`, error));
       return;
     }
     if (typeof message.method === "string") {
@@ -142,14 +136,14 @@ export function connectGrokAcpStdio(options: {
       for (const handler of notificationHandlers) handler(message.method, params);
       if (typeof message.id === "number") {
         if (message.method !== "session/request_permission") {
-          terminate(acpError("acp-unsupported-client-request", `Unsupported Grok ACP client request: ${message.method}`));
+          terminate(acpError("acp-unsupported-client-request", `Unsupported ACP client request: ${message.method}`));
           return;
         }
         const choices = Array.isArray(params.options) ? params.options : [];
         const selected = choices.find((value) =>
           typeof value === "object" && value !== null && (value as { kind?: unknown }).kind === "allow_once") as { optionId?: unknown } | undefined;
         if (typeof selected?.optionId !== "string") {
-          terminate(acpError("acp-permission-missing-allow-once", "Grok ACP permission request omitted allow_once"));
+          terminate(acpError("acp-permission-missing-allow-once", "ACP permission request omitted allow_once"));
           return;
         }
         child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, result: { outcome: { outcome: "selected", optionId: selected.optionId } } })}\n`);
@@ -160,13 +154,13 @@ export function connectGrokAcpStdio(options: {
     const waiter = pending.get(message.id);
     if (waiter === undefined) return;
     pending.delete(message.id);
-    if (message.error !== undefined) waiter.reject(acpError("acp-upstream-error", `Grok ACP error: ${JSON.stringify(message.error)}`));
+    if (message.error !== undefined) waiter.reject(acpError("acp-upstream-error", `ACP error: ${JSON.stringify(message.error)}`));
     else waiter.resolve((message.result ?? {}) as Readonly<Record<string, unknown>>);
   });
-  child.on("close", (code) => settleClosed(acpError("acp-closed", `Grok ACP closed (${String(code)}): ${stderr}`)));
+  child.on("close", (code) => settleClosed(acpError("acp-closed", `ACP closed (${String(code)}): ${stderr}`)));
   return Promise.resolve({
     request(method, params) {
-      if (closed) return Promise.reject(terminalError ?? acpError("acp-connection-closed", "Grok ACP connection is closed"));
+      if (closed) return Promise.reject(terminalError ?? acpError("acp-connection-closed", "ACP connection is closed"));
       const id = ++nextId;
       return new Promise((resolve, reject) => {
         pending.set(id, { resolve, reject });
@@ -175,12 +169,12 @@ export function connectGrokAcpStdio(options: {
           const waiter = pending.get(id);
           if (waiter === undefined) return;
           pending.delete(id);
-          waiter.reject(acpError("acp-write-failed", `Grok ACP write failed: ${error.message}`, error));
+          waiter.reject(acpError("acp-write-failed", `ACP write failed: ${error.message}`, error));
         });
       });
     },
     notify(method, params) {
-      if (closed) throw terminalError ?? acpError("acp-connection-closed", "Grok ACP connection is closed");
+      if (closed) throw terminalError ?? acpError("acp-connection-closed", "ACP connection is closed");
       child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
     },
     onNotification(handler) {
@@ -188,7 +182,7 @@ export function connectGrokAcpStdio(options: {
     },
     async close() {
       if (closed) return;
-      settleClosed(acpError("acp-connection-closed", "Grok ACP connection is closed"));
+      settleClosed(acpError("acp-connection-closed", "ACP connection is closed"));
       child.stdin.end();
       child.kill("SIGTERM");
       await new Promise<void>((resolve) => child.once("close", () => resolve()));
@@ -197,23 +191,23 @@ export function connectGrokAcpStdio(options: {
 }
 
 /**
- * Main-session Grok adapter. The injected composition callbacks are the shared
+ * Main-session ACP adapter. The injected composition callbacks are the shared
  * envelope boundary: this module owns ACP lifecycle, never role policy.
  */
-export function createGrokRoleTurnHost(config: GrokRoleTurnHostConfig): RoleTurnHost {
+export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHost {
   let serial = Promise.resolve();
   return {
     executeTurn(request) {
       const execution = serial.then(async (): Promise<RoleTurnResult> => {
         const continuation = request.continuation;
         const prepared = await config.prepare(request);
-        let connection: GrokAcpConnection | undefined;
+        let connection: AcpConnection | undefined;
         let sessionId: string | undefined;
         let accepted = false;
         try {
           // AK injection proof is prepared MCP composition (envelope).
           if (prepared.mcpServers.length === 0) {
-            return failure("activation", "UncontrolledGrokSession", "ak-config-missing");
+            return failure("activation", "UncontrolledAcpSession", "ak-config-missing");
           }
           connection = await config.connect(request);
           const initialized = await connection.request("initialize", {
@@ -227,60 +221,47 @@ export function createGrokRoleTurnHost(config: GrokRoleTurnHostConfig): RoleTurn
           const availableModels = Array.isArray(modelState?.availableModels) ? modelState.availableModels : undefined;
           if (request.model !== undefined && availableModels !== undefined && !availableModels.some((entry) =>
             typeof entry === "object" && entry !== null && (entry as { modelId?: unknown }).modelId === request.model?.model)) {
-            return failure("activation", "GrokHostModelMismatch", "host-model-mismatch", {
+            return failure("activation", "AcpHostModelMismatch", "host-model-mismatch", {
               provider: request.model.provider,
               model: request.model.model,
             });
           }
 
-          // #617 DK-7: hand Pi session path once; Grok reads the file itself.
+          // #617 DK-7 / #732: hand the projected prior-native session paths once,
+          // whichever record family they came from; the host reads the files itself.
           const priorNativePaths =
             continuation.kind === "resume"
-            && request.hostTransition?.previousHost === "pi"
-              ? request.hostTransition.priorNativePaths
+              ? request.hostTransition?.priorNativePaths
               : undefined;
-          if (continuation.kind === "resume") {
+          if (continuation.kind === "resume" && config.boundResume === "session/load") {
+            // Same-host resume reuses the native ACP session via session/load.
             const boundSessionId = await config.sessionIdentity.load(request.principal);
             if (boundSessionId !== undefined && boundSessionId !== "") {
-              // Same-host Grok resume reuses native ACP session via session/load.
               const loaded = await connection.request("session/load", {
                 sessionId: boundSessionId,
                 cwd: request.cwd,
                 mcpServers: prepared.mcpServers,
-                _meta: { systemPromptOverride: renderGrokSystemPromptOverride(prepared.systemPrompt), yoloMode: false },
+                _meta: { systemPromptOverride: renderAcpSystemPromptOverride(prepared.systemPrompt), yoloMode: false },
               });
               sessionId = typeof loaded.sessionId === "string" && loaded.sessionId !== ""
                 ? loaded.sessionId
                 : boundSessionId;
-            } else {
-              // Unbound resume (cross-host or lost binding): session/new + bind.
-              const session = await connection.request(
-                "session/new",
-                {
-                  cwd: request.cwd,
-                  mcpServers: prepared.mcpServers,
-                  _meta: { systemPromptOverride: renderGrokSystemPromptOverride(prepared.systemPrompt), yoloMode: false },
-                },
-              );
-              sessionId = typeof session.sessionId === "string" ? session.sessionId : undefined;
-              if (sessionId === undefined || sessionId === "") {
-                return failure("session", "GrokAcpSessionFailure", "session-id-missing");
-              }
-              await config.sessionIdentity.bind(request.principal, sessionId);
             }
-          } else {
-            // Initial run: session/new + bind.
+          }
+          if (sessionId === undefined) {
+            // Initial run, unbound resume (cross-host / lost binding), or a host
+            // whose bound resume is session/new: mint the session and bind it.
             const session = await connection.request(
               "session/new",
               {
                 cwd: request.cwd,
                 mcpServers: prepared.mcpServers,
-                _meta: { systemPromptOverride: renderGrokSystemPromptOverride(prepared.systemPrompt), yoloMode: false },
+                _meta: { systemPromptOverride: renderAcpSystemPromptOverride(prepared.systemPrompt), yoloMode: false },
               },
             );
             sessionId = typeof session.sessionId === "string" ? session.sessionId : undefined;
             if (sessionId === undefined || sessionId === "") {
-              return failure("session", "GrokAcpSessionFailure", "session-id-missing");
+              return failure("session", "AcpSessionFailure", "session-id-missing");
             }
             await config.sessionIdentity.bind(request.principal, sessionId);
           }
@@ -353,7 +334,7 @@ export function createGrokRoleTurnHost(config: GrokRoleTurnHostConfig): RoleTurn
               throw error;
             }
             if (result.stopReason === "refusal") {
-              return failure("output", "GrokAcpRefusal", "refusal", { sessionId });
+              return failure("output", "AcpRefusal", "refusal", { sessionId });
             }
             // session/prompt resolution is the sole typed round boundary before seal
             // when the turn ends without host abort; abort path closes above.
@@ -370,7 +351,7 @@ export function createGrokRoleTurnHost(config: GrokRoleTurnHostConfig): RoleTurn
             }
             prompt = `The prior terminal submission was rejected (${closure.retry.code}). Resubmit it as the sole terminal tool call. Rejected call ids: ${closure.retry.toolCallIds.join(", ") || "none"}.`;
           }
-          return failure("output", "GrokAcpRoundLimit", "round-retry-limit", { sessionId });
+          return failure("output", "AcpRoundLimit", "round-retry-limit", { sessionId });
         } finally {
           if (connection !== undefined) {
             if (sessionId !== undefined && !accepted) {
@@ -389,19 +370,3 @@ export function createGrokRoleTurnHost(config: GrokRoleTurnHostConfig): RoleTurn
     },
   };
 }
-
-const PRIVATE_COMPAT_ENV = Object.fromEntries(
-  ["CLAUDE", "CURSOR", "CODEX"].flatMap((vendor) =>
-    ["SKILLS", "RULES", "AGENTS", "MCPS", "HOOKS", "SESSIONS"].map((kind) =>
-      [`GROK_${vendor}_${kind}_ENABLED`, "false"] as const)),
-);
-
-/** Child environment shared by ACP agent processes. */
-export function controlledGrokChildEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
-  return {
-    ...base,
-    ...PRIVATE_COMPAT_ENV,
-    GROK_MEMORY: "0",
-    GROK_SUBAGENTS: "0",
-  };
-}

package/src/{grok → acp-host}/session-identity.ts

@@ -2,15 +2,15 @@ import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import type { DurablePrincipal, DurablePrincipalAuthority } from "../host-contracts.ts";
-import type { GrokSessionIdentityAuthority } from "./role-turn-host.ts";
-
-/** ACP binding filename written only by the grok host on initial bind. */
-export const GROK_ACP_SESSION_BINDING = "grok-acp-session.json";
+import type { AcpSessionIdentityAuthority } from "./role-turn-host.ts";
 
 /** Durable ACP binding stored beside the host-owned session principal. */
-export function createGrokSessionIdentityAuthority(authority: DurablePrincipalAuthority): GrokSessionIdentityAuthority {
+export function createAcpSessionIdentityAuthority(
+  authority: DurablePrincipalAuthority,
+  sessionBindingFile: string,
+): AcpSessionIdentityAuthority {
   const bindingPath = (principal: DurablePrincipal): string =>
-    join(authority.decode(principal).sessionDirectory, GROK_ACP_SESSION_BINDING);
+    join(authority.decode(principal).sessionDirectory, sessionBindingFile);
   return {
     resolveSessionFile(principal) {
       return authority.decode(principal).sessionFile;
@@ -19,7 +19,7 @@ export function createGrokSessionIdentityAuthority(authority: DurablePrincipalAu
       try {
         const value: unknown = JSON.parse(await readFile(bindingPath(principal), "utf8"));
         if (typeof value !== "object" || value === null || typeof (value as { sessionId?: unknown }).sessionId !== "string") {
-          throw new Error("durable Grok ACP session binding is invalid");
+          throw new Error("durable ACP session binding is invalid");
         }
         return (value as { sessionId: string }).sessionId;
       } catch (error) {

package/src/diarist-contracts.ts

@@ -0,0 +1,88 @@
+/**
+ * Public 起居郎 (diarist) terminating receipt contracts — ADR 0075 `diarist-is-role`.
+ * Lawful explicit release: completed, with empty or nonempty selections.
+ * Machine facts about the volume come from the mechanical sitian seam, never
+ * from model self-report (锚定宪法); this module owns the receipt shape only.
+ */
+
+export const DIARIST_OUTPUT_TOOL_NAME = "ak_diarist_output";
+export const DIARIST_ACCEPTED_TEXT = "起居郎回执已接受";
+
+/** Internal transport: frozen candidate-catalog path for this turn's ticket. */
+export const DIARIST_SOURCES_FLAG = {
+  name: "ak-diarist-sources",
+  definition: {
+    description: "Frozen per-ticket source catalog the diarist selects from",
+    type: "string" as const,
+  },
+} as const;
+
+/** One selected block reference into the frozen candidate catalog. */
+export type DiaristSelection = {
+  /** Index into the catalog the diarist received. */
+  readonly candidateIndex: number;
+  /** Quotes claimed verbatim from that block (reverse-verified mechanically). */
+  readonly quotes: readonly string[];
+  /** Human-facing note (relation to this case). Not a machine gate. */
+  readonly note?: string;
+};
+
+export type DiaristOutput = {
+  readonly status: "completed";
+  readonly selections: readonly DiaristSelection[];
+};
+
+export function validateRecordedDiaristOutput(value: unknown): DiaristOutput {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Diarist output has no execution discriminator");
+  }
+  let status: unknown;
+  try {
+    status = (value as Record<string, unknown>).status;
+  } catch {
+    throw new Error("Diarist output has no execution discriminator");
+  }
+  if (status === "completed") {
+    return value as DiaristOutput;
+  }
+  throw new Error("Diarist output has no execution discriminator");
+}
+
+/**
+ * Lenient projection of submitted selections (第 0 条: shape is not an admission
+ * gate). Rows that carry no usable candidateIndex are dropped from the commit,
+ * never bounced back at the role.
+ */
+export function projectDiaristSelections(value: unknown): DiaristSelection[] {
+  const rows = (value as { selections?: unknown } | null)?.selections;
+  if (!Array.isArray(rows)) return [];
+  const out: DiaristSelection[] = [];
+  for (const row of rows) {
+    if (row === null || typeof row !== "object" || Array.isArray(row)) continue;
+    const record = row as Record<string, unknown>;
+    const index = record.candidateIndex;
+    if (typeof index !== "number" || !Number.isInteger(index) || index < 0) continue;
+    const quotes = Array.isArray(record.quotes)
+      ? record.quotes.filter((q): q is string => typeof q === "string" && q.length > 0)
+      : [];
+    out.push({
+      candidateIndex: index,
+      quotes,
+      ...(typeof record.note === "string" ? { note: record.note } : {}),
+    });
+  }
+  return out;
+}
+
+/** Machine-facing facts from an accepted receipt. Submitted rows retained as-is. */
+export function diaristDecisiveFacts(
+  output: DiaristOutput,
+): Record<string, unknown> {
+  const facts: Record<string, unknown> = { status: output.status };
+  const selections = (output as { selections?: unknown }).selections;
+  if (Array.isArray(selections)) facts.selections = selections;
+  // Mechanical sitian facts recorded by the envelope at accept time.
+  const sitian = (output as { sitian?: unknown }).sitian;
+  if (sitian !== undefined) facts.sitian = sitian;
+  return facts;
+}

package/src/diarist-role.ts

@@ -0,0 +1,60 @@
+import type { Static } from "typebox";
+import { Type } from "typebox";
+
+import { openToolObject } from "./open-tool-schema.ts";
+import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.ts";
+import {
+  DIARIST_OUTPUT_TOOL_NAME,
+  validateRecordedDiaristOutput,
+  type DiaristOutput,
+} from "./diarist-contracts.ts";
+
+export {
+  DIARIST_ACCEPTED_TEXT,
+  DIARIST_OUTPUT_TOOL_NAME,
+} from "./diarist-contracts.ts";
+export type { DiaristOutput };
+export { validateRecordedDiaristOutput };
+
+/** 起居郎交卷形状；形状指引，非 schema 闸。 */
+export const diaristOutputSchema = withInfrastructureFailureDeclaration(
+  openToolObject(
+    Type.Object({
+      status: Type.Unknown({
+        description: "completed — 形状指引，非 schema 闸",
+      }),
+      selections: Type.Array(
+        Type.Object(
+          {
+            candidateIndex: Type.Number({ description: "候选目录中的整块序号" }),
+            quotes: Type.Array(Type.String(), {
+              description: "该块 transcript 内的连续原文；机械反验",
+            }),
+            note: Type.Optional(
+              Type.String({ description: "该材料与本案的关系（人读）" }),
+            ),
+          },
+          { additionalProperties: true, description: "一条入录选择" },
+        ),
+        { description: "入录选择；空列表合法完局" },
+      ),
+    }),
+  ),
+);
+
+export type DiaristOutputParameters = Static<typeof diaristOutputSchema>;
+
+export type DiaristRuntimeDependencies = {
+  loadSoul(): Promise<string>;
+};
+
+/**
+ * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
+ */
+export const DIARIST_TOOL_SPEC = {
+  name: DIARIST_OUTPUT_TOOL_NAME,
+  label: "起居郎输出",
+  description: "起居郎入录选择。",
+  promptSnippet: "起居郎入录选择",
+  parameters: diaristOutputSchema,
+} as const;