@astrosheep/keiyaku 2.9.2 → 2.9.4

package/build/agents/harness/outcome.js

@@ -1,6 +1,7 @@
 import { StringTailBuffer } from "../string-tail-buffer.js";
 import { SUBAGENT_SESSION_VERSION, } from "../session.js";
-import { SubagentFailure, } from "../types.js";
+import { OUTCOME_ERROR_VERSION, SubagentFailure, } from "../types.js";
+import { isProviderTerminalError, } from "./provider-adapter.js";
 import { renderCapturedText } from "./runtime.js";
 export function createOutcomeState(maxCaptureChars) {
     return {
@@ -82,13 +83,55 @@ export function classifyFailure(shared, state, error, idleTimedOut) {
             exitCode: null,
         }, state.finalMessageCandidate);
     }
+    return classifyExecutionFailure(shared, state, error);
+}
+/**
+ * A rejected graceful settlement is terminal evidence, not an outcome intent.
+ * In particular, dismiss/external-cancel intent must not downgrade it to a
+ * clean dismissed result.
+ */
+export function classifySettlementFailure(shared, state, error) {
+    return classifyExecutionFailure(shared, state, error);
+}
+function classifyFromFailureFact(shared, state, fact) {
+    return failWithError(shared, state, {
+        code: fact.code,
+        message: fact.message,
+        timeoutMs: fact.timeoutMs,
+        exitCode: fact.exitCode,
+        ...(fact.publicCause ? { publicCause: fact.publicCause } : {}),
+    }, state.finalMessageCandidate ?? fact.message, fact.diagnostics || renderCapturedText(state.diagnosticsBuffer), fact.output || renderCapturedText(state.outputBuffer));
+}
+function classifyFromAbortFact(shared, state, fact) {
+    // Abort without dismiss/external-cancel remains failed truth (historical bytes).
+    appendThrownMessage(state.diagnosticsBuffer, fact.message);
+    return failWithError(shared, state, {
+        code: "SUBAGENT_EXEC_ERROR",
+        message: fact.message,
+        timeoutMs: null,
+        exitCode: null,
+    }, state.finalMessageCandidate ?? fact.message);
+}
+function classifyExecutionFailure(shared, state, error) {
+    if (isProviderTerminalError(error)) {
+        if (error.fact.kind === "aborted") {
+            return classifyFromAbortFact(shared, state, error.fact);
+        }
+        return classifyFromFailureFact(shared, state, error.fact);
+    }
     if (error instanceof SubagentFailure) {
-        return failWithError(shared, state, {
+        return classifyFromFailureFact(shared, state, {
+            kind: "failed",
             code: error.code,
             message: error.message,
             timeoutMs: error.timeoutMs,
             exitCode: error.exitCode,
-        }, state.finalMessageCandidate ?? error.message, error.diagnostics || renderCapturedText(state.diagnosticsBuffer), error.output || renderCapturedText(state.outputBuffer));
+            diagnostics: error.diagnostics,
+            output: error.output,
+        });
+    }
+    if (error instanceof Error && error.name === "AbortError") {
+        return classifyFromAbortFact(shared, state, { kind: "aborted", message: error.message });
     }
     const message = error instanceof Error ? error.message : `Unknown ${shared.terms.provider} exec error`;
     appendThrownMessage(state.diagnosticsBuffer, message);
@@ -102,7 +145,7 @@ export function classifyFailure(shared, state, error, idleTimedOut) {
 export function failWithError(shared, state, error, finalMessage, diagnostics = renderCapturedText(state.diagnosticsBuffer), output = renderCapturedText(state.outputBuffer)) {
     return mintOutcome({
         status: "failed",
-        error,
+        error: { version: OUTCOME_ERROR_VERSION, ...error },
         finalMessage: finalMessage ?? error.message,
         output,
         diagnostics,

package/build/agents/harness/projection.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { FlowError } from "../../flow-error.js";
 import { createEventChannel } from "./event-channel.js";
 import { overflowMarkerFromDropped, prepareAgentEventForPersistence, } from "./execution-handle.js";
-import { classifyFailure, completeOutcome, createOutcomeState, failFromFailEvent, failWithError, processEvent, renderOutcomeCapturedText, } from "./outcome.js";
+import { classifyFailure, classifySettlementFailure, completeOutcome, createOutcomeState, failFromFailEvent, failWithError, processEvent, renderOutcomeCapturedText, } from "./outcome.js";
 import { startLiveProjection } from "./router.js";
 import { createAbortError } from "./runtime.js";
 export function call(terms, options) {
@@ -12,17 +12,7 @@ export function revive(terms, options) {
     return createProjection(terms, terms, options);
 }
 function createProjection(terms, reviveTerms, options) {
-    switch (terms.provider) {
-        case "pi":
-        case "claude-agent-sdk":
-        case "codex-app-server":
-        case "opencode-sdk":
-            return createSteerableProjection(terms, reviveTerms, options);
-        case "codex-sdk":
-            return createReplayProjection(terms, reviveTerms, options);
-        default:
-            return assertNever(terms);
-    }
+    return createSteerableProjection(terms, reviveTerms, options);
 }
 function createSteerableProjection(terms, reviveTerms, options) {
     const shared = createProjectionState(terms, reviveTerms, options);
@@ -84,31 +74,6 @@ function createSteerableProjection(terms, reviveTerms, options) {
         },
     };
 }
-function createReplayProjection(terms, reviveTerms, options) {
-    const shared = createProjectionState(terms, reviveTerms, options);
-    shared.onLive = (live) => {
-        shared.live = live;
-    };
-    const outcome = settleProjection(shared);
-    return {
-        mode: "replay",
-        get id() {
-            return shared.id;
-        },
-        get events() {
-            return shared.publicEvents.iterable;
-        },
-        get outcome() {
-            return outcome;
-        },
-        abort(mode) {
-            return abortProjection(shared, mode);
-        },
-        dismiss() {
-            dismissProjection(shared);
-        },
-    };
-}
 function createProjectionState(terms, reviveTerms, options) {
     const shared = {
         id: randomUUID(),
@@ -129,9 +94,7 @@ function createProjectionState(terms, reviveTerms, options) {
     if (terms.signal) {
         const listener = () => {
             shared.externallyAborted = true;
-            if (!shared.lifecycleAbort.signal.aborted) {
-                shared.lifecycleAbort.abort(terms.signal?.reason);
-            }
+            requestControlledGracefulAbort(shared, terms.signal?.reason);
         };
         terms.signal.addEventListener("abort", listener, { once: true });
         if (terms.signal.aborted) {
@@ -144,20 +107,17 @@ function dismissProjection(shared) {
     if (shared.dismissed || shared.terminal)
         return;
     shared.dismissed = true;
-    if (!shared.lifecycleAbort.signal.aborted) {
-        shared.lifecycleAbort.abort(createAbortError(`${shared.terms.provider} exec dismissed`));
-    }
-    requestDismissAbort(shared.live);
+    requestControlledGracefulAbort(shared, createAbortError(`${shared.terms.provider} exec dismissed`));
 }
 async function abortProjection(shared, mode = "graceful") {
     shared.explicitlyAborted = true;
-    if (!shared.lifecycleAbort.signal.aborted) {
-        shared.lifecycleAbort.abort(createAbortError(`${shared.terms.provider} exec cancelled by client`));
-    }
     if (mode !== "force") {
-        await shared.live?.abort("graceful");
+        await requestControlledGracefulAbort(shared, createAbortError(`${shared.terms.provider} exec cancelled by client`));
         return;
     }
+    if (!shared.lifecycleAbort.signal.aborted) {
+        shared.lifecycleAbort.abort(createAbortError(`${shared.terms.provider} exec cancelled by client`));
+    }
     shared.forceAbort ??= (async () => {
         const live = shared.live ?? (shared.terminal ? undefined : await new Promise((resolve) => {
             shared.forceWaiters.add(resolve);
@@ -171,12 +131,28 @@ function resolveForceWaiters(shared, live) {
         resolve(live);
     shared.forceWaiters.clear();
 }
-function requestDismissAbort(live) {
-    if (!live)
-        return;
-    void Promise.resolve()
-        .then(() => live.abort("graceful"))
-        .catch(() => undefined);
+function requestControlledGracefulAbort(shared, reason) {
+    if (shared.gracefulAbort)
+        return shared.gracefulAbort;
+    const live = shared.live;
+    if (!live) {
+        if (!shared.lifecycleAbort.signal.aborted)
+            shared.lifecycleAbort.abort(reason);
+        return Promise.resolve();
+    }
+    shared.gracefulAbort = (async () => {
+        try {
+            await live.abort("graceful");
+        }
+        finally {
+            if (!shared.lifecycleAbort.signal.aborted)
+                shared.lifecycleAbort.abort(reason);
+        }
+    })();
+    // Dismiss, timeout, and external cancellation are outcome-driven controls;
+    // keep their rejection observed while explicit abort still receives it.
+    shared.gracefulAbort.catch(() => undefined);
+    return shared.gracefulAbort;
 }
 function deliverDriverEvent(shared, state, live, event, refreshIdleTimeout, observerEnabled) {
     const prepared = prepareAgentEventForPersistence(event);
@@ -211,7 +187,7 @@ async function settleProjection(shared) {
             clearTimeout(idleTimeout);
         idleTimeout = setTimeout(() => {
             idleTimedOut = true;
-            shared.lifecycleAbort.abort(createAbortError(`${shared.terms.provider} exec idle timed out`));
+            requestControlledGracefulAbort(shared, createAbortError(`${shared.terms.provider} exec idle timed out`));
         }, shared.terms.idleTimeoutMs);
         idleTimeout.unref?.();
     };
@@ -222,7 +198,7 @@ async function settleProjection(shared) {
         if (abortRequested)
             return;
         abortRequested = true;
-        requestDismissAbort(shared.live);
+        requestControlledGracefulAbort(shared, shared.lifecycleAbort.signal.reason);
     };
     shared.lifecycleAbort.signal.addEventListener("abort", requestLiveAbort, { once: true });
     try {
@@ -258,6 +234,16 @@ async function settleProjection(shared) {
         }
         const completionResult = await live.completion.then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }));
         const completionOutcome = completionResult.ok ? completionResult.value : undefined;
+        // Outcome classification is the terminal publication boundary. A
+        // controlled abort may let the provider run settle before its graceful
+        // cleanup promise does, so prove that shared settlement before publishing
+        // dismissed, failed-for-another-reason, or completed truth.
+        const gracefulResult = shared.gracefulAbort
+            ? await shared.gracefulAbort.then(() => ({ ok: true }), (error) => ({ ok: false, error }))
+            : undefined;
+        if (gracefulResult && !gracefulResult.ok) {
+            return classifySettlementFailure(shared, state, gracefulResult.error);
+        }
         if (state.failEvent) {
             return failFromFailEvent(shared, state, state.failEvent);
         }
@@ -305,6 +291,3 @@ async function settleProjection(shared) {
         shared.publicEvents.close();
     }
 }
-function assertNever(_value) {
-    throw new Error("Unhandled provider");
-}

package/build/agents/harness/provider-adapter.js

@@ -0,0 +1,58 @@
+import { SubagentFailure, } from "../types.js";
+/**
+ * Typed rejection carrier for failed/aborted adapter settlement.
+ * Abort keeps name "AbortError" so existing name checks and CLI exit codes hold.
+ */
+export class ProviderTerminalError extends Error {
+    fact;
+    constructor(fact, options) {
+        super(fact.message, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.name = fact.kind === "aborted" ? "AbortError" : "ProviderTerminalError";
+        this.fact = fact;
+    }
+}
+export function isProviderTerminalError(error) {
+    return error instanceof ProviderTerminalError;
+}
+export function createProviderFailure(message, options = {}) {
+    return new ProviderTerminalError({
+        kind: "failed",
+        code: options.code ?? "SUBAGENT_EXEC_ERROR",
+        message,
+        timeoutMs: options.timeoutMs ?? null,
+        exitCode: options.exitCode ?? null,
+        ...(options.diagnostics !== undefined ? { diagnostics: options.diagnostics } : {}),
+        ...(options.output !== undefined ? { output: options.output } : {}),
+        ...(options.publicCause !== undefined ? { publicCause: options.publicCause } : {}),
+    }, options.cause === undefined ? undefined : { cause: options.cause });
+}
+/**
+ * Abort-fact constructor. Abort semantics for every live adapter:
+ * - abort("graceful") requests provider-native interrupt and keeps local signals
+ *   open until native settlement proof (or bounded abort-settlement timeout);
+ * - abort("force") must establish zero later provider side effects or reject;
+ * - run settlement for a requested abort exits as kind "aborted" (name AbortError).
+ */
+export function createAbortError(message, cause) {
+    return new ProviderTerminalError({ kind: "aborted", message }, cause === undefined ? undefined : { cause });
+}
+/** Normalize any thrown value into the typed failure/abort egress fact. */
+export function toProviderTerminalError(error) {
+    if (error instanceof ProviderTerminalError)
+        return error;
+    if (error instanceof SubagentFailure) {
+        return new ProviderTerminalError({
+            kind: "failed",
+            code: error.code,
+            message: error.message,
+            timeoutMs: error.timeoutMs,
+            exitCode: error.exitCode,
+            diagnostics: error.diagnostics,
+            output: error.output,
+        }, { cause: error });
+    }
+    if (error instanceof Error && error.name === "AbortError") {
+        return new ProviderTerminalError({ kind: "aborted", message: error.message }, { cause: error });
+    }
+    return createProviderFailure(error instanceof Error ? error.message : String(error), { cause: error instanceof Error ? error : undefined });
+}

package/build/agents/harness/router.js

@@ -1,30 +1,4 @@
-import { FlowError } from "../../flow-error.js";
-import { SUBAGENT_SESSION_VERSION, subagentSessionEnvelopeSchema, } from "../session.js";
-import { startClaudeAgentSdk, claudeSessionSchema, } from "../providers/claude-agent-sdk/adapter.js";
-import { startCodexAppServer, codexAppServerSessionSchema, } from "../providers/codex-app-server/adapter.js";
-import { startCodexSdk, codexThreadSchema, } from "../providers/codex-sdk.js";
-import { startOpencode, opencodeSessionSchema, } from "../providers/opencode-sdk/adapter.js";
-import { startPi, piSessionSchema, } from "../providers/pi/adapter.js";
-function admitResumeShape(provider, schema, session, resumePath) {
-    const envelopeResult = subagentSessionEnvelopeSchema.safeParse(session);
-    if (!envelopeResult.success) {
-        throw new FlowError("INVALID_RESPONSE_PATH", `Resume path file '${resumePath}' includes an invalid session envelope.`);
-    }
-    if (session.provider !== provider) {
-        throw new FlowError("INVALID_RESPONSE_PATH", `Resume path file '${resumePath}' was created with provider '${session.provider}', but the selected subagent resolves to '${provider}'. Cross-provider resume is not supported.`);
-    }
-    if (session.version !== SUBAGENT_SESSION_VERSION) {
-        throw new FlowError("INVALID_RESPONSE_PATH", `Resume path file '${resumePath}' uses unsupported session version '${session.version}' for provider '${session.provider}'.`);
-    }
-    const shapeResult = schema.safeParse(session.handle);
-    if (!shapeResult.success) {
-        throw new FlowError("INVALID_RESPONSE_PATH", `Resume path file '${resumePath}' includes an invalid session handle for provider '${session.provider}'.`);
-    }
-    return shapeResult.data;
-}
-function assertNever(_value) {
-    throw new Error("Unhandled provider");
-}
+import { getProviderRegistration } from "../providers/registry.js";
 export async function startLiveProjection(terms, signal, reviveTerms, onIngress, observer) {
     const onSyncCheckpoint = observer
         ? (control, checkpoint) => {
@@ -38,164 +12,14 @@ export async function startLiveProjection(terms, signal, reviveTerms, onIngress,
             observer.onDeliveryOpportunity(control);
         }
         : undefined;
-    switch (terms.provider) {
-        case "pi": {
-            if (reviveTerms) {
-                const session = admitResumeShape("pi", piSessionSchema, reviveTerms.session, reviveTerms.resumePath);
-                return startPi(terms.prompt, terms.workdir, {
-                    model: terms.model,
-                    thinkingLevel: terms.thinkingLevel,
-                    signal,
-                    sessionFile: session.sessionFile,
-                    appendSystemPromptOverride: terms.appendSystemPromptOverride,
-                    onSyncCheckpoint,
-                    onEvidence: terms.onEvidence,
-                    onIngress,
-                    initialTurn: terms.initialTurn,
-                    loader: terms.loader,
-                });
-            }
-            return startPi(terms.prompt, terms.workdir, {
-                model: terms.model,
-                thinkingLevel: terms.thinkingLevel,
-                signal,
-                appendSystemPromptOverride: terms.appendSystemPromptOverride,
-                onSyncCheckpoint,
-                onEvidence: terms.onEvidence,
-                onIngress,
-                initialTurn: terms.initialTurn,
-                loader: terms.loader,
-            });
-        }
-        case "claude-agent-sdk": {
-            const claudeOptions = {
-                model: terms.model,
-                executable: terms.executable,
-                effort: terms.effort,
-                env: terms.env,
-                signal,
-                permissionMode: terms.permissionMode,
-                settingSources: terms.settingSources,
-                allowDangerouslySkipPermissions: terms.allowDangerouslySkipPermissions,
-                disallowedTools: terms.disallowedTools,
-                systemPrompt: terms.systemPrompt,
-                onSyncCheckpoint,
-                onEvidence: terms.onEvidence,
-                onIngress,
-                initialTurn: terms.initialTurn,
-                loader: terms.loader,
-            };
-            if (reviveTerms) {
-                const session = admitResumeShape("claude-agent-sdk", claudeSessionSchema, reviveTerms.session, reviveTerms.resumePath);
-                return startClaudeAgentSdk(terms.prompt, terms.workdir, {
-                    ...claudeOptions,
-                    sessionId: session.sessionId,
-                });
-            }
-            return startClaudeAgentSdk(terms.prompt, terms.workdir, claudeOptions);
-        }
-        case "codex-app-server": {
-            if (reviveTerms) {
-                const session = admitResumeShape("codex-app-server", codexAppServerSessionSchema, reviveTerms.session, reviveTerms.resumePath);
-                return startCodexAppServer(terms.prompt, terms.workdir, {
-                    model: terms.model,
-                    effort: terms.effort,
-                    profile: terms.profile,
-                    config: terms.config,
-                    sandboxPolicy: terms.sandboxPolicy,
-                    approvalPolicy: terms.approvalPolicy,
-                    executable: terms.executable,
-                    env: terms.env,
-                    signal,
-                    threadId: session.threadId,
-                    codexHome: session.codexHome,
-                    developerInstructions: terms.developerInstructions,
-                    onSyncCheckpoint,
-                    onDeliveryOpportunity,
-                    onEvidence: terms.onEvidence,
-                    onIngress,
-                    initialTurn: terms.initialTurn,
-                });
-            }
-            return startCodexAppServer(terms.prompt, terms.workdir, {
-                model: terms.model,
-                effort: terms.effort,
-                profile: terms.profile,
-                config: terms.config,
-                sandboxPolicy: terms.sandboxPolicy,
-                approvalPolicy: terms.approvalPolicy,
-                executable: terms.executable,
-                env: terms.env,
-                signal,
-                developerInstructions: terms.developerInstructions,
-                onSyncCheckpoint,
-                onDeliveryOpportunity,
-                onEvidence: terms.onEvidence,
-                onIngress,
-                initialTurn: terms.initialTurn,
-            });
-        }
-        case "codex-sdk": {
-            if (reviveTerms) {
-                const session = admitResumeShape("codex-sdk", codexThreadSchema, reviveTerms.session, reviveTerms.resumePath);
-                return startCodexSdk(terms.prompt, terms.workdir, {
-                    model: terms.model,
-                    profile: terms.profile,
-                    config: terms.config,
-                    threadOptions: terms.threadOptions,
-                    executable: terms.executable,
-                    signal,
-                    threadId: session.threadId,
-                    onEvidence: terms.onEvidence,
-                    onIngress,
-                    initialTurn: terms.initialTurn,
-                    codexConstructor: terms.codexConstructor,
-                });
-            }
-            return startCodexSdk(terms.prompt, terms.workdir, {
-                model: terms.model,
-                profile: terms.profile,
-                config: terms.config,
-                threadOptions: terms.threadOptions,
-                executable: terms.executable,
-                signal,
-                onEvidence: terms.onEvidence,
-                onIngress,
-                initialTurn: terms.initialTurn,
-                codexConstructor: terms.codexConstructor,
-            });
-        }
-        case "opencode-sdk": {
-            if (reviveTerms) {
-                const session = admitResumeShape("opencode-sdk", opencodeSessionSchema, reviveTerms.session, reviveTerms.resumePath);
-                return startOpencode(terms.prompt, terms.workdir, {
-                    model: terms.model,
-                    effort: terms.effort,
-                    executable: terms.executable,
-                    env: terms.env,
-                    signal,
-                    sessionId: session.sessionId,
-                    onSyncCheckpoint,
-                    onDeliveryOpportunity,
-                    onEvidence: terms.onEvidence,
-                    onIngress,
-                    initialTurn: terms.initialTurn,
-                });
-            }
-            return startOpencode(terms.prompt, terms.workdir, {
-                model: terms.model,
-                effort: terms.effort,
-                executable: terms.executable,
-                env: terms.env,
-                signal,
-                onSyncCheckpoint,
-                onDeliveryOpportunity,
-                onEvidence: terms.onEvidence,
-                onIngress,
-                initialTurn: terms.initialTurn,
-            });
-        }
-        default:
-            return assertNever(terms);
-    }
+    const registration = getProviderRegistration(terms.provider);
+    return registration.startLive({
+        terms,
+        signal,
+        reviveTerms,
+        onSyncCheckpoint,
+        onDeliveryOpportunity,
+        onIngress,
+        observer,
+    });
 }

package/build/agents/harness/runtime.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { getConfig } from "../../config/env.js";
 import { DISABLE_SUBAGENT_SPAWN_ENV_KEY } from "../../config/env-keys.js";
+export const PROVIDER_ABORT_SETTLEMENT_TIMEOUT_MS = 5_000;
 export function sha256Utf8(value) {
     const bytes = Buffer.from(value, "utf8");
     return { sha256: createHash("sha256").update(bytes).digest("hex"), byteLength: bytes.byteLength };
@@ -33,10 +34,22 @@ export function emitProviderEvidence(callback, evidence, diagnostic) {
         reportFailure();
     }
 }
-export function createAbortError(message) {
-    const error = new Error(message);
-    error.name = "AbortError";
-    return error;
+export { createAbortError } from "./provider-adapter.js";
+export async function awaitProviderAbortSettlement(provider, settlement, operation = "graceful abort could not prove provider terminal settlement") {
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`${provider} ${operation} within ${PROVIDER_ABORT_SETTLEMENT_TIMEOUT_MS}ms`));
+        }, PROVIDER_ABORT_SETTLEMENT_TIMEOUT_MS);
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([settlement, deadline]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
 }
 export function coerceString(value) {
     return typeof value === "string" && value.trim().length > 0 ? value : undefined;

package/build/agents/harness/session.js

@@ -0,0 +1,15 @@
+import { isSubagentProvider } from "../../keiyaku.js";
+import { SUBAGENT_SESSION_VERSION, subagentSessionEnvelopeSchema, } from "../session.js";
+import { getProviderRegistration } from "../providers/registry.js";
+/** Validate a continuation envelope through its owning provider schema. */
+export function isRecoverableSessionEnvelope(provider, value) {
+    if (!isSubagentProvider(provider))
+        return false;
+    const envelope = subagentSessionEnvelopeSchema.safeParse(value);
+    if (!envelope.success)
+        return false;
+    if (envelope.data.provider !== provider || envelope.data.version !== SUBAGENT_SESSION_VERSION) {
+        return false;
+    }
+    return getProviderRegistration(provider).sessionSchema.safeParse(envelope.data.handle).success;
+}