@akagilnc/pi-workflow-roles 0.1.5307 → 0.1.5312

package/package.json

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

package/src/acp-host/description.ts

@@ -4,13 +4,10 @@
  * optional seat-profile soul — is data here; the lifecycle in role-turn-host.ts
  * stays one copy (#732).
  */
-import { join } from "node:path";
-
+import type { HostIdentityDescription } from "../host-descriptions.ts";
 import type { SeatProfileSoul } from "./seat-profile-soul.ts";
 
-export type AcpHostDescription = Readonly<{
-  /** Binary path segments relative to the operator home. */
-  binaryFromHome: readonly string[];
+export type AcpHostDescription = HostIdentityDescription & Readonly<{
   argv: Readonly<{
     prefix: readonly string[];
     suffix: readonly string[];
@@ -26,8 +23,6 @@ export type AcpHostDescription = Readonly<{
    *   `provider:model` (hermes).
    */
   modelPassing: "argv" | "set_model";
-  /** Durable ACP binding filename written beside the session principal. */
-  sessionBindingFile: string;
   /**
    * When set, the production factory ensures a seat profile whose SOUL.md is a
    * symlink to the packaged role soul, and prefixes argv with `flag <name>`.
@@ -36,11 +31,6 @@ export type AcpHostDescription = Readonly<{
   seatProfileSoul?: SeatProfileSoul;
 }>;
 
-/** Absolute agent binary for one operator home. */
-export function resolveAcpBinary(description: AcpHostDescription, operatorHome: string): string {
-  return join(operatorHome, ...description.binaryFromHome);
-}
-
 /** Stdio argv: optional profile flag, thinking flag, prefix, model, suffix. */
 export function acpStdioArgs(
   description: AcpHostDescription,

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

@@ -9,11 +9,12 @@
 import { randomUUID } from "node:crypto";
 
 import type { DurablePrincipalAuthority, RoleTurnHost, RoleTurnRequest } from "../host-contracts.ts";
+import { resolveHostBinary } from "../host-descriptions.ts";
 import { prepareRoleEnvelope } from "../role-envelope.ts";
 import type { RoleRuntimeDependencies } from "../role-runtime.ts";
 import { createRoleRuntimeDependencies } from "../role-runtime-dependencies.ts";
 import { createSessionIdentityAuthority } from "../session-identity.ts";
-import { acpStdioArgs, resolveAcpBinary, type AcpHostDescription } from "./description.ts";
+import { acpStdioArgs, type AcpHostDescription } from "./description.ts";
 import {
   connectAcpStdio,
   createAcpRoleTurnHost,
@@ -74,7 +75,7 @@ export function createProductionAcpRoleTurnHost(options: ProductionAcpHostOption
           role: request.activation.role,
         });
       return connectAcpStdio({
-        binary: resolveAcpBinary(description, request.home),
+        binary: resolveHostBinary(description, request.home),
         args: acpStdioArgs(
           description,
           request.model,

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

@@ -2,11 +2,13 @@ import { join } from "node:path";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 
-import type { RoleTurnHost, RoleTurnKnownFailure, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
+import type { RoleTurnHost, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
 import {
   createSerializedRoleTurnHost,
   driveExternalRoleTurnRounds,
+  externalHostFailure as failure,
   raceAgainstHostAbort,
+  withExternalHostCleanupFailure,
 } from "../external-host-turn-loop.ts";
 
 import {
@@ -19,6 +21,7 @@ import {
 } from "../package-contracts/navigator-output.ts";
 import {
   renderSystemPromptOverride,
+  resolveBoundHostSessionId,
   type PreparedRoleTurn,
   type SessionIdentityAuthority,
 } from "../prepared-role-turn.ts";
@@ -96,41 +99,6 @@ export type AcpRoleTurnHostConfig = Readonly<{
   prepare(request: RoleTurnRequest): Promise<PreparedRoleTurn>;
 }>;
 
-function failure(
-  cause: "activation" | "session" | "output",
-  name: string,
-  code: string,
-  details?: Readonly<Record<string, unknown>>,
-  diagnostic?: string,
-): RoleTurnResult {
-  return {
-    code: null,
-    stderr: "",
-    timedOut: false,
-    knownFailure: {
-      cause,
-      identity: { name, code },
-      ...(diagnostic === undefined ? {} : { diagnostic }),
-      ...(details === undefined ? {} : { details }),
-    },
-  };
-}
-
-/** Success→dispose failure; existing failure keeps primary cause + cleanup detail. */
-function withCleanupFailure(outcome: RoleTurnResult, cleanupError: unknown): RoleTurnResult {
-  const message = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
-  if (outcome.knownFailure === undefined) {
-    return failure("session", "AcpDisposeFailure", "dispose-failed", { cleanupError: message }, message);
-  }
-  return {
-    ...outcome,
-    knownFailure: {
-      ...outcome.knownFailure,
-      details: { ...(outcome.knownFailure.details ?? {}), cleanupError: message },
-    },
-  };
-}
-
 type RpcReply = { readonly id?: unknown; readonly method?: unknown; readonly params?: unknown; readonly result?: unknown; readonly error?: unknown };
 
 function acpError(code: string, message: string, cause?: unknown): Error & { readonly code: string } {
@@ -259,7 +227,7 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
     let sessionOpened = false;
     let accepted = false;
     const sessionParent = config.sessionIdentity.resolveSessionFile(request.principal);
-    // Mutable so dispose failure can outrank a clean turn (headless withCleanupFailure face).
+    // Mutable so dispose failure can outrank a clean turn.
     let outcome: RoleTurnResult = failure("session", "AcpNoOutcome", "no-outcome");
     try {
       if (prepared.mcpServers.length === 0) {
@@ -324,10 +292,7 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
         };
         let sessionReady = true;
         if (request.continuation.kind === "resume") {
-          const explicitHostSessionId = request.continuation.hostSessionId;
-          const boundSessionId = explicitHostSessionId !== undefined && explicitHostSessionId !== ""
-            ? explicitHostSessionId
-            : await config.sessionIdentity.load(request.principal);
+          const boundSessionId = await resolveBoundHostSessionId(request, config.sessionIdentity);
           if (boundSessionId !== undefined && boundSessionId !== "") {
             sessionId = boundSessionId;
             sessionId = await loadSession(boundSessionId);
@@ -446,7 +411,7 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
       try {
         await prepared.dispose?.();
       } catch (cleanupError) {
-        outcome = withCleanupFailure(outcome, cleanupError);
+        outcome = withExternalHostCleanupFailure(outcome, cleanupError, "AcpDisposeFailure");
       }
     }
     return outcome;

package/src/external-host-turn-loop.ts

@@ -9,25 +9,11 @@ import type {
   RoleTurnRequest,
   RoleTurnResult,
 } from "./host-contracts.ts";
+import type { PreparedRoleTurn } from "./prepared-role-turn.ts";
 
 export const EXTERNAL_ROLE_TURN_ROUND_LIMIT = 8 as const;
 
-export type ExternalPreparedTurn = Readonly<{
-  readonly prompt: string;
-  readonly abortSignal?: AbortSignal;
-  closeRound(): Promise<
-    | { readonly accepted: true }
-    | {
-      readonly accepted: false;
-      readonly retry: {
-        readonly code: string;
-        readonly toolCallIds: readonly string[];
-        readonly message: string;
-      };
-    }
-    | { readonly accepted: false; readonly failure: RoleTurnKnownFailure }
-  >;
-}>;
+export type ExternalPreparedTurn = Pick<PreparedRoleTurn, "prompt" | "abortSignal" | "closeRound">;
 
 export type ExternalHostRoundOutcome =
   | { readonly status: "delivered"; readonly stderr?: string }
@@ -96,6 +82,40 @@ export function raceAgainstHostAbort<T>(
   });
 }
 
+export function externalHostFailure(
+  cause: NonNullable<RoleTurnKnownFailure["cause"]>,
+  name: string,
+  code: string,
+  details?: Readonly<Record<string, unknown>>,
+  diagnostic?: string,
+): RoleTurnResult {
+  return asFailure({
+    cause,
+    identity: { name, code },
+    ...(diagnostic === undefined ? {} : { diagnostic }),
+    ...(details === undefined ? {} : { details }),
+  });
+}
+
+/** A dispose failure replaces success; a primary failure retains its cause. */
+export function withExternalHostCleanupFailure(
+  outcome: RoleTurnResult,
+  cleanupError: unknown,
+  name: string,
+): RoleTurnResult {
+  const message = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+  if (outcome.knownFailure === undefined) {
+    return externalHostFailure("session", name, "dispose-failed", { cleanupError: message }, message);
+  }
+  return {
+    ...outcome,
+    knownFailure: {
+      ...outcome.knownFailure,
+      details: { ...(outcome.knownFailure.details ?? {}), cleanupError: message },
+    },
+  };
+}
+
 function asFailure(knownFailure: RoleTurnKnownFailure, stderr = ""): RoleTurnResult {
   return { code: null, stderr, timedOut: false, knownFailure };
 }

package/src/headless-host/description.ts

@@ -4,17 +4,10 @@
  * Claude print-mode and codex exec differ enough that #752 host-specific
  * assembly lives here as sibling helpers — not a third unified abstraction.
  */
-import { join } from "node:path";
-
-type HeadlessHostBase = Readonly<{
-  /** Binary path segments relative to the operator home. */
-  binaryFromHome: readonly string[];
-  /** Durable session-id binding filename beside the session principal. */
-  sessionBindingFile: string;
-}>;
+import type { HostIdentityDescription } from "../host-descriptions.ts";
 
 /** Claude Code print-mode (#645). */
-export type ClaudePrintHostDescription = HeadlessHostBase & Readonly<{
+export type ClaudePrintHostDescription = HostIdentityDescription & Readonly<{
   protocol: "claude-print";
   /**
    * Host-native print-mode flags that never change per turn (no prompt).
@@ -48,7 +41,7 @@ export type ClaudePrintHostDescription = HeadlessHostBase & Readonly<{
  * Protocol differences (JSONL, resume subcommand, schema file, `-c` MCP) stay
  * in codex-specific helpers — description only carries identity + binary path.
  */
-export type CodexExecHostDescription = HeadlessHostBase & Readonly<{
+export type CodexExecHostDescription = HostIdentityDescription & Readonly<{
   protocol: "codex-exec";
 }>;
 
@@ -66,14 +59,6 @@ export function isCodexExecDescription(
   return description.protocol === "codex-exec";
 }
 
-/** Absolute agent binary for one operator home. */
-export function resolveHeadlessBinary(
-  description: HeadlessHostDescription,
-  operatorHome: string,
-): string {
-  return join(operatorHome, ...description.binaryFromHome);
-}
-
 /**
  * Build one Claude print-mode argv for a single process turn.
  * Shape: `<promptFlag> <fixedArgs…> <system/schema/mcp/model/effort/session…>`.

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

@@ -12,10 +12,11 @@
 import { randomUUID } from "node:crypto";
 
 import type { DurablePrincipalAuthority, RoleTurnHost } from "../host-contracts.ts";
+import { resolveHostBinary } from "../host-descriptions.ts";
 import { createRoleRuntimeDependencies } from "../role-runtime-dependencies.ts";
 import { prepareRoleEnvelope } from "../role-envelope.ts";
 import { createSessionIdentityAuthority } from "../session-identity.ts";
-import { resolveHeadlessBinary, type HeadlessHostDescription } from "./description.ts";
+import type { HeadlessHostDescription } from "./description.ts";
 import { createHeadlessRoleTurnHost } from "./role-turn-host.ts";
 
 export type ProductionHeadlessHostOptions = Readonly<{
@@ -46,7 +47,7 @@ export function createProductionHeadlessRoleTurnHost(
       description,
       hostName,
       sessionIdentity,
-      binary: resolveHeadlessBinary(description, operatorHome),
+      binary: resolveHostBinary(description, operatorHome),
       env: {
         ...process.env,
         AK_PACKAGE_ROOT: packageRoot,

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

@@ -13,11 +13,14 @@ import type { RoleTurnHost, RoleTurnRequest, RoleTurnResult } from "../host-cont
 import {
   createSerializedRoleTurnHost,
   driveExternalRoleTurnRounds,
+  externalHostFailure as failure,
   hostAbortedError,
   isHostAbortedError,
+  withExternalHostCleanupFailure,
 } from "../external-host-turn-loop.ts";
 import {
   renderSystemPromptOverride,
+  resolveBoundHostSessionId,
   type PreparedRoleTurn,
   type SessionIdentityAuthority,
 } from "../prepared-role-turn.ts";
@@ -48,26 +51,6 @@ export type HeadlessRoleTurnHostConfig = Readonly<{
   env?: NodeJS.ProcessEnv;
 }>;
 
-function failure(
-  cause: "activation" | "session" | "output" | "provider",
-  name: string,
-  code: string,
-  details?: Readonly<Record<string, unknown>>,
-  diagnostic?: string,
-): RoleTurnResult {
-  return {
-    code: null,
-    stderr: "",
-    timedOut: false,
-    knownFailure: {
-      cause,
-      identity: { name, code },
-      ...(diagnostic === undefined ? {} : { diagnostic }),
-      ...(details === undefined ? {} : { details }),
-    },
-  };
-}
-
 /** One headless CLI result envelope (stream-json last line, or single json doc). */
 export type HeadlessCliResult = Readonly<{
   session_id?: string;
@@ -93,39 +76,18 @@ function isHeadlessResultCandidate(value: unknown): value is HeadlessCliResult {
 }
 
 /**
- * Parse Claude host stdout into the result envelope.
- * Production uses `--output-format stream-json` (#811 live records); last-result
- * line is the typed receipt. A single-document `json` body still parses so a
- * misconfigured description yields a typed miss rather than a silent empty parse.
- * Callers must not retain the full stream — only the rolling result candidate.
+ * Parse the rolling result-candidate line retained by spawnHeadlessTurn.
+ * The full stream is delivered live, not passed to this parser.
  */
 export function parseHeadlessCliStdout(stdout: string): HeadlessCliResult | undefined {
   const trimmed = stdout.trim();
   if (trimmed === "") return undefined;
   try {
-    const single = JSON.parse(trimmed) as unknown;
-    if (isHeadlessResultCandidate(single)) return single;
+    const value = JSON.parse(trimmed) as unknown;
+    return isHeadlessResultCandidate(value) ? value : undefined;
   } catch {
-    // fall through
-  }
-  // stream-json: keep the last result line (structured_output / is_error live here).
-  let last: HeadlessCliResult | undefined;
-  for (const line of trimmed.split("\n")) {
-    const text = line.trim();
-    if (text === "") continue;
-    try {
-      const value = JSON.parse(text) as unknown;
-      if (!isPlainObject(value)) continue;
-      const record = value as HeadlessCliResult & { type?: unknown };
-      // Multi-line stream: only explicit result / structured_output lines (not bare objects).
-      if (record.type === "result" || record.structured_output !== undefined) {
-        last = record;
-      }
-    } catch {
-      // skip non-JSON noise lines
-    }
+    return undefined;
   }
-  return last;
 }
 
 /**
@@ -380,21 +342,6 @@ function spawnHeadlessTurn(options: {
   });
 }
 
-/** Success→dispose failure; existing failure keeps primary cause + cleanup detail. */
-function withCleanupFailure(outcome: RoleTurnResult, cleanupError: unknown): RoleTurnResult {
-  const message = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
-  if (outcome.knownFailure === undefined) {
-    return failure("session", "HeadlessDisposeFailure", "dispose-failed", { cleanupError: message }, message);
-  }
-  return {
-    ...outcome,
-    knownFailure: {
-      ...outcome.knownFailure,
-      details: { ...(outcome.knownFailure.details ?? {}), cleanupError: message },
-    },
-  };
-}
-
 function terminalFromSpawned(
   spawned: { code: number | null; stderr: string; timedOut: boolean },
   knownFailure: NonNullable<RoleTurnResult["knownFailure"]>,
@@ -469,12 +416,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
     try {
       // Claude mints a package UUID for --session-id; codex waits for thread.started.
       // Public explicit resume already read the stored native id. Auto-resume omits it.
-      const explicitHostSessionId = request.continuation.kind === "resume"
-        ? request.continuation.hostSessionId
-        : undefined;
-      let sessionId = explicitHostSessionId !== undefined && explicitHostSessionId !== ""
-        ? explicitHostSessionId
-        : await config.sessionIdentity.load(request.principal);
+      let sessionId = await resolveBoundHostSessionId(request, config.sessionIdentity);
       if (request.continuation.kind === "resume" && (sessionId === undefined || sessionId === "")) {
         outcome = failure(
           "session",
@@ -821,7 +763,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
       try {
         await prepared.dispose?.();
       } catch (cleanupError) {
-        outcome = withCleanupFailure(outcome, cleanupError);
+        outcome = withExternalHostCleanupFailure(outcome, cleanupError, "HeadlessDisposeFailure");
       }
     }
     return outcome;

package/src/host-descriptions.ts

@@ -6,9 +6,27 @@
  * pi is the in-process default, not a row.
  * Unregistered names fail closed (#510); these tables do not fallback.
  */
+import { join } from "node:path";
+
 import type { AcpHostDescription } from "./acp-host/description.ts";
 import type { HeadlessHostDescription } from "./headless-host/description.ts";
 
+/** Shared identity fields consumed by both external host families. */
+export type HostIdentityDescription = Readonly<{
+  /** Binary path segments relative to the operator home. */
+  binaryFromHome: readonly string[];
+  /** Durable host session binding filename beside the session principal. */
+  sessionBindingFile: string;
+}>;
+
+/** Resolve a host description's agent binary under the operator home. */
+export function resolveHostBinary(
+  description: HostIdentityDescription,
+  operatorHome: string,
+): string {
+  return join(operatorHome, ...description.binaryFromHome);
+}
+
 export const DEFAULT_ROLE_TURN_HOST = "pi" as const;
 
 export type HostFamily = "acp" | "headless";

package/src/prepared-role-turn.ts

@@ -60,6 +60,14 @@ export function renderSystemPromptOverride(authority: {
   return renderAgentStartMaterials(authority.body, authority.materials);
 }
 
+export async function resolveBoundHostSessionId(
+  request: RoleTurnRequest,
+  identity: SessionIdentityAuthority,
+): Promise<string | undefined> {
+  const explicit = request.continuation.kind === "resume" ? request.continuation.hostSessionId : undefined;
+  return explicit !== undefined && explicit !== "" ? explicit : identity.load(request.principal);
+}
+
 export type SessionIdentityAuthority = Readonly<{
   load(principal: RoleTurnRequest["principal"]): Promise<string | undefined>;
   bind(principal: RoleTurnRequest["principal"], sessionId: string): Promise<void>;

package/src/public-cli/machine-method-skills.ts

@@ -2,7 +2,7 @@ import { accessSync, constants, statSync } from "node:fs";
 import { lstat, mkdir, symlink } from "node:fs/promises";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
-import { HEADLESS_HOST_DESCRIPTIONS, HOST_DESCRIPTIONS } from "../host-descriptions.ts";
+import { HEADLESS_HOST_DESCRIPTIONS, HOST_DESCRIPTIONS, resolveHostBinary } from "../host-descriptions.ts";
 import { packagedMethodSkillNames } from "../packaged-role-registry.ts";
 
 /** Install source only. Which names are required comes from the role registry. */
@@ -126,11 +126,11 @@ export async function runMachineSkillSetup(home: string, stdout: (text: string)
 
   for (const host of ["claude-code", "hermes"] as const) {
     const root = linkedSkillRoot(home, host)!;
-    const binaryFromHome = host === "claude-code"
-      ? HEADLESS_HOST_DESCRIPTIONS.claude!.binaryFromHome
-      : HOST_DESCRIPTIONS.hermes!.binaryFromHome;
+    const description = host === "claude-code"
+      ? HEADLESS_HOST_DESCRIPTIONS.claude!
+      : HOST_DESCRIPTIONS.hermes!;
     try {
-      accessSync(join(home, ...binaryFromHome), constants.X_OK);
+      accessSync(resolveHostBinary(description, home), constants.X_OK);
     } catch (error) {
       if (["ENOENT", "ENOTDIR", "EACCES"].includes((error as NodeJS.ErrnoException).code ?? "")) continue;
       throw error;