@astrosheep/keiyaku 2.8.4 → 2.9.0

package/build/agents/harness/outcome.js

@@ -0,0 +1,141 @@
+import { StringTailBuffer } from "../string-tail-buffer.js";
+import { SUBAGENT_SESSION_VERSION, } from "../session.js";
+import { SubagentFailure, } from "../types.js";
+import { renderCapturedText } from "./runtime.js";
+export function createOutcomeState(maxCaptureChars) {
+    return {
+        outputBuffer: new StringTailBuffer(maxCaptureChars),
+        diagnosticsBuffer: new StringTailBuffer(maxCaptureChars),
+        warnings: [],
+    };
+}
+function mintOutcome(draft) {
+    return draft;
+}
+export function restoreOutcome(record) {
+    return { ...record };
+}
+export function processEvent(state, event) {
+    switch (event.type) {
+        case "diagnostic":
+            state.diagnosticsBuffer.append(event.text);
+            return;
+        case "message":
+            state.finalMessageCandidate = event.text;
+            return;
+        case "warning":
+            state.warnings.push(event.warning);
+            return;
+        case "done":
+            state.doneEvent = event;
+            state.session = event.session;
+            if (event.finalMessage !== undefined) {
+                state.finalMessageCandidate = event.finalMessage;
+            }
+            return;
+        case "fail":
+            state.failEvent = event;
+            if (event.diagnostics) {
+                state.diagnosticsBuffer.append(event.diagnostics);
+            }
+            return;
+        case "activity":
+        case "unknown":
+        case "turn":
+        case "usage":
+        case "thought":
+        case "plan":
+        case "truncation":
+            return;
+    }
+}
+export function failFromFailEvent(shared, state, failEvent) {
+    const code = failEvent.code === "PROJECTION_STATE_ERROR" || failEvent.code === undefined
+        ? "SUBAGENT_EXEC_ERROR"
+        : failEvent.code;
+    const diagnostics = failEvent.code === "PROJECTION_STATE_ERROR"
+        ? [renderCapturedText(state.diagnosticsBuffer), "PROJECTION_STATE_ERROR"].filter(Boolean).join("\n")
+        : renderCapturedText(state.diagnosticsBuffer);
+    return failWithError(shared, state, {
+        code,
+        message: failEvent.message,
+        timeoutMs: null,
+        exitCode: failEvent.exitCode ?? null,
+    }, state.finalMessageCandidate, failEvent.diagnostics ?? diagnostics);
+}
+export function classifyFailure(shared, state, error, idleTimedOut) {
+    if (shared.dismissed || shared.externallyAborted) {
+        return mintOutcome({
+            status: "dismissed",
+            finalMessage: state.finalMessageCandidate ?? "",
+            output: renderCapturedText(state.outputBuffer),
+            diagnostics: renderCapturedText(state.diagnosticsBuffer),
+            session: state.session ?? fallbackSession(shared),
+            warnings: [...state.warnings],
+        });
+    }
+    if (idleTimedOut) {
+        return failWithError(shared, state, {
+            code: "SUBAGENT_TIMEOUT",
+            message: `${shared.terms.provider} exec idle timed out`,
+            timeoutMs: shared.terms.idleTimeoutMs,
+            exitCode: null,
+        }, state.finalMessageCandidate);
+    }
+    if (error instanceof SubagentFailure) {
+        return failWithError(shared, state, {
+            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));
+    }
+    const message = error instanceof Error ? error.message : `Unknown ${shared.terms.provider} exec error`;
+    appendThrownMessage(state.diagnosticsBuffer, message);
+    return failWithError(shared, state, {
+        code: "SUBAGENT_EXEC_ERROR",
+        message,
+        timeoutMs: null,
+        exitCode: null,
+    }, state.finalMessageCandidate ?? message);
+}
+export function failWithError(shared, state, error, finalMessage, diagnostics = renderCapturedText(state.diagnosticsBuffer), output = renderCapturedText(state.outputBuffer)) {
+    return mintOutcome({
+        status: "failed",
+        error,
+        finalMessage: finalMessage ?? error.message,
+        output,
+        diagnostics,
+        session: state.session ?? fallbackSession(shared),
+        warnings: [...state.warnings],
+    });
+}
+export function completeOutcome(shared, state, finalMessage, session) {
+    return mintOutcome({
+        status: "completed",
+        finalMessage,
+        output: renderCapturedText(state.outputBuffer),
+        diagnostics: renderCapturedText(state.diagnosticsBuffer),
+        session,
+        warnings: [...state.warnings],
+    });
+}
+export function fallbackSession(shared) {
+    return shared.reviveTerms?.session ?? {
+        provider: shared.terms.provider,
+        version: SUBAGENT_SESSION_VERSION,
+        handle: null,
+    };
+}
+function appendThrownMessage(buffer, message) {
+    if (message.length === 0)
+        return;
+    const snapshot = buffer.snapshot().text;
+    if (snapshot.length > 0 && !snapshot.endsWith("\n")) {
+        buffer.append("\n");
+    }
+    buffer.append(message);
+}
+export function renderOutcomeCapturedText(buffer) {
+    return renderCapturedText(buffer);
+}

package/build/agents/harness/projection.js

@@ -0,0 +1,310 @@
+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 { startLiveProjection } from "./router.js";
+import { createAbortError } from "./runtime.js";
+export function call(terms, options) {
+    return createProjection(terms, undefined, options);
+}
+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);
+    }
+}
+function createSteerableProjection(terms, reviveTerms, options) {
+    const shared = createProjectionState(terms, reviveTerms, options);
+    const pendingTells = [];
+    let flushActive = false;
+    const flushPendingTells = async () => {
+        const initialEnqueue = shared.live?.enqueue;
+        if (flushActive || shared.terminal || !initialEnqueue)
+            return;
+        flushActive = true;
+        try {
+            while (!shared.terminal && pendingTells.length > 0) {
+                const enqueue = shared.live?.enqueue;
+                if (!enqueue)
+                    break;
+                const nextTell = pendingTells.shift();
+                if (!nextTell)
+                    break;
+                await enqueue(nextTell);
+            }
+        }
+        finally {
+            flushActive = false;
+            if (!shared.terminal && pendingTells.length > 0 && shared.live?.enqueue) {
+                void flushPendingTells();
+            }
+        }
+    };
+    shared.onLive = (live) => {
+        shared.live = live;
+        void flushPendingTells();
+    };
+    const outcome = settleProjection(shared);
+    return {
+        mode: "steerable",
+        get id() {
+            return shared.id;
+        },
+        get events() {
+            return shared.publicEvents.iterable;
+        },
+        get outcome() {
+            return outcome;
+        },
+        tell(tell) {
+            if (shared.terminal)
+                return;
+            pendingTells.push(tell);
+            void flushPendingTells();
+        },
+        recallTells() {
+            return pendingTells.splice(0, pendingTells.length);
+        },
+        abort(mode) {
+            return abortProjection(shared, mode);
+        },
+        dismiss() {
+            dismissProjection(shared);
+        },
+    };
+}
+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(),
+        terms,
+        reviveTerms,
+        publicEvents: createEventChannel({
+            createOverflowMarker: overflowMarkerFromDropped,
+        }),
+        lifecycleAbort: new AbortController(),
+        dismissed: false,
+        externallyAborted: false,
+        explicitlyAborted: false,
+        terminal: false,
+        forceWaiters: new Set(),
+        onLive() { },
+        observer: options?.observer,
+    };
+    if (terms.signal) {
+        const listener = () => {
+            shared.externallyAborted = true;
+            if (!shared.lifecycleAbort.signal.aborted) {
+                shared.lifecycleAbort.abort(terms.signal?.reason);
+            }
+        };
+        terms.signal.addEventListener("abort", listener, { once: true });
+        if (terms.signal.aborted) {
+            listener();
+        }
+    }
+    return shared;
+}
+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);
+}
+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");
+        return;
+    }
+    shared.forceAbort ??= (async () => {
+        const live = shared.live ?? (shared.terminal ? undefined : await new Promise((resolve) => {
+            shared.forceWaiters.add(resolve);
+        }));
+        await live?.abort("force");
+    })();
+    await shared.forceAbort;
+}
+function resolveForceWaiters(shared, live) {
+    for (const resolve of shared.forceWaiters)
+        resolve(live);
+    shared.forceWaiters.clear();
+}
+function requestDismissAbort(live) {
+    if (!live)
+        return;
+    void Promise.resolve()
+        .then(() => live.abort("graceful"))
+        .catch(() => undefined);
+}
+function deliverDriverEvent(shared, state, live, event, refreshIdleTimeout, observerEnabled) {
+    const prepared = prepareAgentEventForPersistence(event);
+    if (observerEnabled.value && shared.observer) {
+        try {
+            shared.observer.onEvent(prepared);
+        }
+        catch (error) {
+            observerEnabled.value = false;
+            const diagnostic = live.mintEvent({
+                type: "diagnostic",
+                text: `event persistence degraded: ${String(error)}`,
+            });
+            if (diagnostic) {
+                shared.publicEvents.push(diagnostic);
+                processEvent(state, diagnostic);
+            }
+        }
+    }
+    shared.publicEvents.push(event);
+    refreshIdleTimeout();
+    processEvent(state, event);
+}
+async function settleProjection(shared) {
+    const state = createOutcomeState(shared.terms.maxCaptureChars);
+    let idleTimedOut = false;
+    let abortRequested = false;
+    const observerEnabled = { value: shared.observer !== undefined };
+    let idleTimeout;
+    const refreshIdleTimeout = () => {
+        if (idleTimeout)
+            clearTimeout(idleTimeout);
+        idleTimeout = setTimeout(() => {
+            idleTimedOut = true;
+            shared.lifecycleAbort.abort(createAbortError(`${shared.terms.provider} exec idle timed out`));
+        }, shared.terms.idleTimeoutMs);
+        idleTimeout.unref?.();
+    };
+    refreshIdleTimeout();
+    const requestLiveAbort = () => {
+        if (shared.explicitlyAborted)
+            return;
+        if (abortRequested)
+            return;
+        abortRequested = true;
+        requestDismissAbort(shared.live);
+    };
+    shared.lifecycleAbort.signal.addEventListener("abort", requestLiveAbort, { once: true });
+    try {
+        const live = await startLiveProjection(shared.terms, shared.lifecycleAbort.signal, shared.reviveTerms, refreshIdleTimeout, shared.observer);
+        shared.onLive(live);
+        resolveForceWaiters(shared, live);
+        if (shared.lifecycleAbort.signal.aborted) {
+            requestLiveAbort();
+        }
+        try {
+            for await (const event of live.events) {
+                deliverDriverEvent(shared, state, live, event, refreshIdleTimeout, observerEnabled);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.code === "PROJECTION_STATE_ERROR") {
+                const event = live.mintEvent({
+                    type: "fail",
+                    code: "PROJECTION_STATE_ERROR",
+                    message: error.message,
+                });
+                if (event)
+                    deliverDriverEvent(shared, state, live, event, refreshIdleTimeout, observerEnabled);
+            }
+            else {
+                const event = live.mintEvent({
+                    type: "diagnostic",
+                    text: `pump error: ${String(error)}`,
+                });
+                if (event)
+                    deliverDriverEvent(shared, state, live, event, refreshIdleTimeout, observerEnabled);
+            }
+        }
+        const completionResult = await live.completion.then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }));
+        const completionOutcome = completionResult.ok ? completionResult.value : undefined;
+        if (state.failEvent) {
+            return failFromFailEvent(shared, state, state.failEvent);
+        }
+        if (!completionResult.ok) {
+            return classifyFailure(shared, state, completionResult.error, idleTimedOut);
+        }
+        if (shared.lifecycleAbort.signal.aborted) {
+            return classifyFailure(shared, state, shared.lifecycleAbort.signal.reason, idleTimedOut);
+        }
+        if (!state.doneEvent && !completionOutcome) {
+            return failWithError(shared, state, {
+                code: "SUBAGENT_EXEC_ERROR",
+                message: `${shared.terms.provider} exec ended before completion`,
+                timeoutMs: null,
+                exitCode: null,
+            }, state.finalMessageCandidate);
+        }
+        const finalMessage = state.doneEvent?.finalMessage ??
+            completionOutcome?.finalMessage ??
+            state.finalMessageCandidate ??
+            renderOutcomeCapturedText(state.outputBuffer).trim();
+        const session = state.doneEvent?.session ?? completionOutcome?.session;
+        if (!session) {
+            return failWithError(shared, state, {
+                code: "SUBAGENT_EXEC_ERROR",
+                message: `${shared.terms.provider} exec ended without a session handle`,
+                timeoutMs: null,
+                exitCode: null,
+            }, finalMessage);
+        }
+        return completeOutcome(shared, state, finalMessage, session);
+    }
+    catch (error) {
+        if (error instanceof FlowError) {
+            throw error;
+        }
+        return classifyFailure(shared, state, error, idleTimedOut);
+    }
+    finally {
+        if (idleTimeout)
+            clearTimeout(idleTimeout);
+        shared.lifecycleAbort.signal.removeEventListener("abort", requestLiveAbort);
+        shared.terminal = true;
+        resolveForceWaiters(shared, undefined);
+        shared.publicEvents.close();
+    }
+}
+function assertNever(_value) {
+    throw new Error("Unhandled provider");
+}

package/build/agents/harness/router.js

@@ -0,0 +1,201 @@
+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");
+}
+export async function startLiveProjection(terms, signal, reviveTerms, onIngress, observer) {
+    const onSyncCheckpoint = observer
+        ? (control, checkpoint) => {
+            observer.onCheckpoint(control, checkpoint);
+        }
+        : "onCheckpoint" in terms
+            ? terms.onCheckpoint
+            : undefined;
+    const onDeliveryOpportunity = observer
+        ? (control) => {
+            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);
+    }
+}

package/build/agents/harness/runtime.js

@@ -63,9 +63,10 @@ export function linkAbortSignal(signal, controller, onAbort) {
     }
     return () => signal.removeEventListener("abort", handler);
 }
-export function buildSubagentEnv() {
+export function buildSubagentEnv(instanceEnv) {
     return {
         ...getConfig().runtimeEnv,
+        ...(instanceEnv ?? {}),
         [DISABLE_SUBAGENT_SPAWN_ENV_KEY]: "1",
     };
 }