@akagilnc/pi-workflow-roles 0.1.3837 → 0.1.3873

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

@@ -0,0 +1,172 @@
+/**
+ * Middle external-host role-turn loop (#820 / ADR 0082).
+ * One copy: serial, prior-native, abort merge/race, 8-round closeRound retry,
+ * host-aborted, round-limit. Last hop = ExternalHostTurnDriver (four verbs).
+ */
+import type {
+  RoleTurnHost,
+  RoleTurnKnownFailure,
+  RoleTurnRequest,
+  RoleTurnResult,
+} from "./host-contracts.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 ExternalHostRoundOutcome =
+  | { readonly status: "delivered"; readonly stderr?: string }
+  | { readonly status: "terminal"; readonly result: RoleTurnResult };
+
+export type ExternalHostTurnDriver = Readonly<{
+  readonly roundLimitName: string;
+  currentSessionId(): string | undefined;
+  runRound(input: {
+    readonly prompt: string;
+    readonly abortSignal: AbortSignal | undefined;
+    readonly attempt: number;
+  }): Promise<ExternalHostRoundOutcome>;
+  afterAccepted?(): Promise<void>;
+  afterRetry?(): void;
+}>;
+
+export function mergeRoleTurnAbortSignals(
+  prepared: AbortSignal | undefined,
+  request: AbortSignal | undefined,
+): AbortSignal | undefined {
+  if (request === undefined) return prepared;
+  if (prepared === undefined) return request;
+  return AbortSignal.any([prepared, request]);
+}
+
+export function promptWithPriorNativePaths(basePrompt: string, request: RoleTurnRequest): string {
+  if (request.continuation.kind !== "resume") return basePrompt;
+  const paths = request.hostTransition?.priorNativePaths;
+  if (paths === undefined || paths.length === 0) return basePrompt;
+  return `${basePrompt}\n${paths.join("\n")}`;
+}
+
+export function isHostAbortedError(error: unknown): boolean {
+  return typeof error === "object" && error !== null && (error as { code?: unknown }).code === "host-aborted";
+}
+
+export function hostAbortedError(message = "host aborted"): Error & { readonly code: "host-aborted" } {
+  return Object.assign(new Error(message), { code: "host-aborted" as const });
+}
+
+/** Race host work against envelope/parent abort (#593). */
+export function raceAgainstHostAbort<T>(
+  work: Promise<T>,
+  abortSignal: AbortSignal | undefined,
+  message = "host aborted",
+): Promise<T> {
+  if (abortSignal?.aborted) return Promise.reject(hostAbortedError(message));
+  if (abortSignal === undefined) return work;
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const onAbort = (): void => {
+      if (settled) return;
+      settled = true;
+      work.catch(() => {});
+      reject(hostAbortedError(message));
+    };
+    abortSignal.addEventListener("abort", onAbort, { once: true });
+    work.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        abortSignal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        if (settled) return;
+        settled = true;
+        abortSignal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+function asFailure(knownFailure: RoleTurnKnownFailure, stderr = ""): RoleTurnResult {
+  return { code: null, stderr, timedOut: false, knownFailure };
+}
+
+async function settleHostAborted(
+  prepared: ExternalPreparedTurn,
+  sessionId: string | undefined,
+): Promise<RoleTurnResult> {
+  const closure = await prepared.closeRound();
+  if ("failure" in closure) return asFailure(closure.failure);
+  return asFailure({
+    cause: "session",
+    identity: { name: "HostAborted", code: "host-aborted" },
+    ...(sessionId === undefined ? {} : { details: { sessionId } }),
+  });
+}
+
+/** Shared external-host retry/resume loop. Caller owns session open + teardown. */
+export async function driveExternalRoleTurnRounds(
+  prepared: ExternalPreparedTurn,
+  request: RoleTurnRequest,
+  driver: ExternalHostTurnDriver,
+): Promise<RoleTurnResult> {
+  let prompt = promptWithPriorNativePaths(prepared.prompt, request);
+  const abortSignal = mergeRoleTurnAbortSignals(prepared.abortSignal, request.signal);
+
+  for (let attempt = 0; attempt < EXTERNAL_ROLE_TURN_ROUND_LIMIT; attempt += 1) {
+    if (abortSignal?.aborted) return settleHostAborted(prepared, driver.currentSessionId());
+
+    let round: ExternalHostRoundOutcome;
+    try {
+      round = await driver.runRound({ prompt, abortSignal, attempt });
+    } catch (error) {
+      if (isHostAbortedError(error)) return settleHostAborted(prepared, driver.currentSessionId());
+      throw error;
+    }
+    if (round.status === "terminal") return round.result;
+
+    const closure = await prepared.closeRound();
+    if (closure.accepted) {
+      await driver.afterAccepted?.();
+      return { code: 0, stderr: "", timedOut: false };
+    }
+    if ("failure" in closure) return asFailure(closure.failure, round.stderr ?? "");
+    prompt = closure.retry.message;
+    driver.afterRetry?.();
+  }
+
+  return asFailure({
+    cause: "output",
+    identity: { name: driver.roundLimitName, code: "round-retry-limit" },
+    ...(driver.currentSessionId() === undefined ? {} : { details: { sessionId: driver.currentSessionId() } }),
+  });
+}
+
+export function createSerializedRoleTurnHost(
+  execute: (request: RoleTurnRequest) => Promise<RoleTurnResult>,
+): RoleTurnHost {
+  let serial = Promise.resolve();
+  return {
+    executeTurn(request) {
+      const execution = serial.then(() => execute(request));
+      serial = execution.then(() => undefined, () => undefined);
+      return execution;
+    },
+  };
+}

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

@@ -12,9 +12,9 @@
 import { randomUUID } from "node:crypto";
 
 import type { DurablePrincipalAuthority, RoleTurnHost } from "../host-contracts.ts";
-import { createAcpRoleRuntimeDependencies } from "../acp-host/production-host.ts";
-import { prepareAcpRoleEnvelope } from "../acp-host/role-envelope.ts";
-import { createAcpSessionIdentityAuthority } from "../acp-host/session-identity.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 { createHeadlessRoleTurnHost } from "./role-turn-host.ts";
 
@@ -22,6 +22,8 @@ export type ProductionHeadlessHostOptions = Readonly<{
   packageRoot: string;
   principalAuthority: DurablePrincipalAuthority;
   description: HeadlessHostDescription;
+  /** Seat-table host key (e.g. claude). */
+  hostName: string;
 }>;
 
 /**
@@ -32,16 +34,17 @@ export type ProductionHeadlessHostOptions = Readonly<{
 export function createProductionHeadlessRoleTurnHost(
   options: ProductionHeadlessHostOptions,
 ): RoleTurnHost {
-  const { packageRoot, principalAuthority, description } = options;
-  const sessionIdentity = createAcpSessionIdentityAuthority(
+  const { packageRoot, principalAuthority, description, hostName } = options;
+  const sessionIdentity = createSessionIdentityAuthority(
     principalAuthority,
     description.sessionBindingFile,
   );
-  const roleRuntimeDependencies = createAcpRoleRuntimeDependencies(packageRoot);
+  const roleRuntimeDependencies = createRoleRuntimeDependencies(packageRoot);
 
   const innerFor = (operatorHome: string): RoleTurnHost =>
     createHeadlessRoleTurnHost({
       description,
+      hostName,
       sessionIdentity,
       binary: resolveHeadlessBinary(description, operatorHome),
       env: {
@@ -49,7 +52,7 @@ export function createProductionHeadlessRoleTurnHost(
         AK_PACKAGE_ROOT: packageRoot,
       },
       prepare: (request) =>
-        prepareAcpRoleEnvelope({
+        prepareRoleEnvelope({
           request,
           dependencies: roleRuntimeDependencies,
           sessionFile: sessionIdentity.resolveSessionFile(request.principal),