@astrosheep/keiyaku 0.1.87 → 1.0.0

package/build/agents/providers/claude-agent-sdk.js

@@ -0,0 +1,529 @@
+import { z } from "zod";
+import { appendDebugLog } from "../../telemetry/debug-log.js";
+import { SUBAGENT_SESSION_VERSION } from "../session.js";
+import { coerceString } from "../index.js";
+import { createProjectionDriver } from "../harness/execution-handle.js";
+import { buildSubagentEnv, createAbortError, emitProviderEvidence, linkAbortSignal, sha256Utf8 } from "../harness/runtime.js";
+export const claudeSessionSchema = z.object({ sessionId: z.string().trim().min(1) });
+const CLAUDE_AGENT_SDK_PROVIDER = "claude-agent-sdk";
+let claudeAgentSdkLoader;
+/** Sentinel for IteratorResult<SDKUserMessage> done=true returns.
+ * The SDK's AsyncIterator protocol requires the value field even when done=true.
+ * Consumers never read it, but TypeScript needs the type to match. */
+const DONE_SENTINEL = undefined;
+function extractMessageText(content) {
+    if (!Array.isArray(content))
+        return undefined;
+    const text = content
+        .map((block) => {
+        if (typeof block !== "object" || block === null || !("text" in block))
+            return "";
+        const candidate = block.text;
+        return typeof candidate === "string" ? candidate : "";
+    })
+        .join("")
+        .trim();
+    return text || undefined;
+}
+function extractAssistantMessage(event) {
+    return extractMessageText(event.message.content);
+}
+function extractAssistantMessageModel(event) {
+    return coerceString(event.message.model);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isClaudeModelRefusalFallbackEvent(event) {
+    return event.type === "system" && event.subtype === "model_refusal_fallback";
+}
+function isClaudeModelRefusalNoFallbackEvent(event) {
+    return event.type === "system" && event.subtype === "model_refusal_no_fallback";
+}
+function extractFallbackRequestId(value) {
+    if (value === null)
+        return null;
+    return coerceString(value);
+}
+function extractOverloadFallbackWarning(event) {
+    if (!isRecord(event) || event.type !== "fallback") {
+        return undefined;
+    }
+    const originalModel = coerceString(event.original_model);
+    const fallbackModel = coerceString(event.fallback_model);
+    const direction = coerceString(event.direction);
+    const requestId = extractFallbackRequestId(event.request_id);
+    return {
+        reason: "overload",
+        ...(originalModel ? { originalModel } : {}),
+        ...(fallbackModel ? { fallbackModel } : {}),
+        ...(direction ? { direction } : {}),
+        ...(requestId !== undefined ? { requestId } : {}),
+    };
+}
+function extractResumeToken(event) {
+    return coerceString(event.session_id);
+}
+function extractResultText(event) {
+    if (event.subtype === "success") {
+        return coerceString(event.result);
+    }
+    const errorText = event.errors.join("\n").trim();
+    return errorText || undefined;
+}
+async function loadClaudeAgentSdk() {
+    if (claudeAgentSdkLoader) {
+        return claudeAgentSdkLoader();
+    }
+    return (await import("@anthropic-ai/claude-agent-sdk"));
+}
+export function setClaudeAgentSdkLoaderForTests(loader) {
+    claudeAgentSdkLoader = loader;
+}
+export function resetClaudeAgentSdkLoaderForTests() {
+    claudeAgentSdkLoader = undefined;
+}
+function createMessageAck() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    // Prevent unhandled rejection if nobody awaits before reject-on-end.
+    promise.catch(() => undefined);
+    const ack = {
+        settled: false,
+        settleResolve() {
+            if (ack.settled)
+                return;
+            ack.settled = true;
+            resolve();
+        },
+        settleReject(error) {
+            if (ack.settled)
+                return;
+            ack.settled = true;
+            reject(error);
+        },
+        wait() {
+            return promise;
+        },
+    };
+    return ack;
+}
+/**
+ * Long-lived push source for Claude Query.
+ * Submitted fence is per-yield: entering next() first acknowledges the previously
+ * yielded message, then yields the next item. That next-entry after a yield is the
+ * post-yield ack (transport.write completed for the prior yield).
+ */
+export function createPushableUserMessageStream(onYield) {
+    const queue = [];
+    const waiters = [];
+    /** Ack for the message most recently yielded; resolved on the subsequent next() entry. */
+    let pendingYieldAck;
+    let closed = false;
+    let failure;
+    let pullCount = 0;
+    const terminalError = (error) => error ?? new Error(`${CLAUDE_AGENT_SDK_PROVIDER} input stream ended before submitted ack`);
+    const rejectUnresolvedAcks = (error) => {
+        const err = terminalError(error);
+        if (pendingYieldAck) {
+            pendingYieldAck.settleReject(err);
+            pendingYieldAck = undefined;
+        }
+        while (queue.length > 0) {
+            queue.shift().ack.settleReject(err);
+        }
+    };
+    /** First action on every next() entry: post-yield ack for the prior yield. */
+    const acknowledgePreviousYield = () => {
+        if (!pendingYieldAck)
+            return;
+        pendingYieldAck.settleResolve();
+        pendingYieldAck = undefined;
+    };
+    const yieldQueued = (entry) => {
+        pullCount += 1;
+        pendingYieldAck = entry.ack;
+        onYield?.(entry.message);
+        return { value: entry.message, done: false };
+    };
+    return {
+        get pullCount() {
+            return pullCount;
+        },
+        get queueLength() {
+            return queue.length;
+        },
+        push(message) {
+            const ack = createMessageAck();
+            if (closed || failure !== undefined) {
+                ack.settleReject(terminalError(failure));
+                return { waitSubmitted: () => ack.wait() };
+            }
+            const waiter = waiters.shift();
+            if (waiter) {
+                // Consumer is already inside next() (previous yield already acked at entry).
+                pullCount += 1;
+                pendingYieldAck = ack;
+                onYield?.(message);
+                waiter.resolve({ value: message, done: false });
+                return { waitSubmitted: () => ack.wait() };
+            }
+            queue.push({ message, ack });
+            return { waitSubmitted: () => ack.wait() };
+        },
+        end(error) {
+            if (closed)
+                return;
+            closed = true;
+            if (error !== undefined) {
+                failure = error;
+                // Failure: reject every unresolved ack (yielded + still queued) so enqueue cannot hang.
+                rejectUnresolvedAcks(error);
+                while (waiters.length > 0) {
+                    waiters.shift().reject(failure);
+                }
+                return;
+            }
+            // Clean end: leave queued messages readable for a late consumer drain.
+            // Only reject a yielded-but-not-post-acked message (no further next() will ack it
+            // if the consumer has already stopped). If a consumer is parked, they get done
+            // after any remaining queue is taken on subsequent next() calls — parked waiters
+            // here mean queue is empty, so resolve done.
+            if (pendingYieldAck) {
+                pendingYieldAck.settleReject(terminalError());
+                pendingYieldAck = undefined;
+            }
+            while (waiters.length > 0) {
+                waiters.shift().resolve({ value: DONE_SENTINEL, done: true });
+            }
+        },
+        iterable: {
+            [Symbol.asyncIterator]() {
+                return {
+                    next() {
+                        // Per-yield submitted fence: next entry acks the previously yielded message.
+                        acknowledgePreviousYield();
+                        if (queue.length > 0) {
+                            return Promise.resolve(yieldQueued(queue.shift()));
+                        }
+                        if (failure !== undefined) {
+                            return Promise.reject(failure);
+                        }
+                        if (closed) {
+                            return Promise.resolve({ value: DONE_SENTINEL, done: true });
+                        }
+                        return new Promise((resolve, reject) => {
+                            waiters.push({ resolve, reject });
+                        });
+                    },
+                };
+            },
+        },
+    };
+}
+function toUserMessage(text) {
+    return {
+        type: "user",
+        message: {
+            role: "user",
+            content: text,
+        },
+        parent_tool_use_id: null,
+        session_id: "",
+    };
+}
+export async function startClaudeAgentSdk(prompt, cwd, options) {
+    const sessionId = options.sessionId?.trim();
+    let liveQuery;
+    let pendingEvidenceDiagnostics = 0;
+    let builderDiagnostic = () => {
+        pendingEvidenceDiagnostics += 1;
+        appendDebugLog("provider evidence callback failed before Claude driver start", {
+            cwd,
+            section: CLAUDE_AGENT_SDK_PROVIDER,
+        });
+    };
+    let inputStream;
+    let queryActive = false;
+    let queryEnded = false;
+    let completedResultOrdinal = 0;
+    let openSteerCount = 0;
+    let sawSuccessfulResult = false;
+    const activeWaiters = new Set();
+    const notifyActive = () => {
+        for (const resolve of [...activeWaiters]) {
+            activeWaiters.delete(resolve);
+            resolve();
+        }
+    };
+    const waitUntilQueryActive = async () => {
+        if (queryActive && inputStream && liveQuery)
+            return;
+        if (queryEnded) {
+            throw new Error(`${CLAUDE_AGENT_SDK_PROVIDER} cannot enqueue: query ended`);
+        }
+        await new Promise((resolve) => {
+            activeWaiters.add(resolve);
+        });
+        if (!queryActive || !inputStream || !liveQuery) {
+            throw new Error(`${CLAUDE_AGENT_SDK_PROVIDER} cannot enqueue: query is not active`);
+        }
+    };
+    const bumpResultOrdinal = () => {
+        completedResultOrdinal += 1;
+    };
+    const rejectPendingEnqueueWaiters = (_error) => {
+        for (const resolve of [...activeWaiters]) {
+            activeWaiters.delete(resolve);
+            resolve();
+        }
+    };
+    const maybeEndInputStream = () => {
+        if (!inputStream)
+            return;
+        if (openSteerCount > 0)
+            return;
+        if (inputStream.queueLength > 0)
+            return;
+        if (!sawSuccessfulResult)
+            return;
+        inputStream.end();
+    };
+    appendDebugLog(`startClaudeAgentSdk: executable=${options.executable} model=${options.model ?? "default"} mode=${sessionId ? "resume" : "fresh"}`, { cwd, section: CLAUDE_AGENT_SDK_PROVIDER });
+    const enqueue = async (message) => {
+        // Reserve the stream before awaiting activation so the result checkpoint's
+        // deferred close cannot race a mailbox delivery queued in that checkpoint.
+        openSteerCount += 1;
+        try {
+            // Projection may be returned before run() arms the long-lived Query; wait, do not race-fail.
+            await waitUntilQueryActive();
+            if (!inputStream || !liveQuery || queryEnded) {
+                throw new Error(`${CLAUDE_AGENT_SDK_PROVIDER} cannot enqueue: query ended before yield`);
+            }
+            if (message.effort) {
+                await liveQuery.applyFlagSettings({ effortLevel: message.effort === "max" ? "xhigh" : message.effort });
+            }
+            // The pump calls enqueue at a successful result checkpoint. Push now;
+            // waiting for another result before pushing would deadlock the next turn.
+            // text is already core-rendered; send byte-for-byte. id is for the frame only (inside text).
+            const submitted = inputStream.push(toUserMessage(message.text));
+            // submitted = NEXT source next() after this tell is yielded (not the yield pull itself).
+            await submitted.waitSubmitted();
+            // 落账：记录提交时越过的 result ordinal（generation fence 落点）。
+            const submittedAfterResultOrdinal = completedResultOrdinal;
+            if (options.onEvidence)
+                emitProviderEvidence(options.onEvidence, { type: "ack", provider: CLAUDE_AGENT_SDK_PROVIDER, fence: { kind: "ordinal", ordinal: submittedAfterResultOrdinal }, outbound: "steer" }, builderDiagnostic);
+            return { fence: { kind: "ordinal", ordinal: submittedAfterResultOrdinal } };
+        }
+        finally {
+            openSteerCount -= 1;
+            maybeEndInputStream();
+        }
+    };
+    return createProjectionDriver({
+        steerMode: "mid-execution",
+        enqueue,
+        async abort() {
+            queryEnded = true;
+            queryActive = false;
+            const abortError = createAbortError(`${CLAUDE_AGENT_SDK_PROVIDER} exec cancelled by client`);
+            try {
+                await liveQuery?.interrupt();
+            }
+            catch {
+                // interrupt is best-effort acceleration for dismiss/abort only
+            }
+            liveQuery?.close();
+            inputStream?.end(abortError);
+            rejectPendingEnqueueWaiters(abortError);
+        },
+        async run(builder) {
+            builderDiagnostic = (text) => builder.emit({ type: "diagnostic", text });
+            while (pendingEvidenceDiagnostics > 0) {
+                pendingEvidenceDiagnostics -= 1;
+                builderDiagnostic("provider evidence callback failed");
+            }
+            const sdk = await loadClaudeAgentSdk();
+            const queryAbortController = new AbortController();
+            const unlinkBuilderAbort = linkAbortSignal(builder.signal, queryAbortController, () => undefined);
+            const unlinkOuterAbort = linkAbortSignal(options.signal, queryAbortController, () => undefined);
+            try {
+                const initialMessage = toUserMessage(prompt);
+                inputStream = createPushableUserMessageStream((message) => {
+                    if (!options.onEvidence)
+                        return;
+                    if (message === initialMessage)
+                        return;
+                    const content = message.message.content;
+                    const text = typeof content === "string"
+                        ? content
+                        : content.map((block) => typeof block === "object" && block !== null && "text" in block && typeof block.text === "string" ? block.text : "").join("");
+                    if (text)
+                        emitProviderEvidence(options.onEvidence, { type: "outbound", provider: CLAUDE_AGENT_SDK_PROVIDER, direction: "input", kind: "steer", ...sha256Utf8(text) }, (text) => builder.emit({ type: "diagnostic", text }));
+                });
+                inputStream.push(initialMessage);
+                const queryOptions = {
+                    cwd,
+                    model: options.model,
+                    permissionMode: options.permissionMode,
+                    allowDangerouslySkipPermissions: options.permissionMode === "bypassPermissions",
+                    settingSources: [...options.settingSources],
+                    resume: sessionId,
+                    env: buildSubagentEnv(),
+                    abortController: queryAbortController,
+                    persistSession: true,
+                    ...(options.systemPrompt ? { systemPrompt: options.systemPrompt } : {}),
+                    stderr: (data) => {
+                        builder.emit({ type: "diagnostic", text: data });
+                    },
+                };
+                const execPathKey = `pathToClaudeCode${"Ex"}ecutable`;
+                queryOptions[execPathKey] = options.executable;
+                if (options.effort !== undefined) {
+                    queryOptions.effort = options.effort;
+                }
+                // Long-lived push-AsyncIterable: one stream for the whole Query lifetime (Tier 1).
+                // Never mount short per-tell streams (that would endInput and break stdin).
+                if (options.onEvidence && options.systemPrompt)
+                    emitProviderEvidence(options.onEvidence, { type: "outbound", provider: CLAUDE_AGENT_SDK_PROVIDER, direction: "input", kind: "system-prompt", ...sha256Utf8(options.systemPrompt.append) }, (text) => builder.emit({ type: "diagnostic", text }));
+                const query = sdk.query({
+                    prompt: inputStream.iterable,
+                    options: queryOptions,
+                });
+                liveQuery = query;
+                queryActive = true;
+                notifyActive();
+                let resumedSessionId = sessionId;
+                let finalMessage;
+                let latestAssistantMessageModel;
+                for await (const event of query) {
+                    builder.emit({ type: "output", value: event });
+                    resumedSessionId = extractResumeToken(event) ?? resumedSessionId;
+                    const overloadWarning = extractOverloadFallbackWarning(event);
+                    if (overloadWarning) {
+                        builder.emit({ type: "warning", warning: overloadWarning });
+                    }
+                    if (isClaudeModelRefusalFallbackEvent(event)) {
+                        builder.emit({
+                            type: "warning",
+                            warning: {
+                                reason: "refusal",
+                                originalModel: event.original_model,
+                                fallbackModel: event.fallback_model,
+                                direction: event.direction,
+                                requestId: event.request_id,
+                                ...(latestAssistantMessageModel ? { signerModel: latestAssistantMessageModel } : {}),
+                            },
+                        });
+                    }
+                    else if (isClaudeModelRefusalNoFallbackEvent(event)) {
+                        builder.emit({
+                            type: "warning",
+                            warning: {
+                                reason: "refusal",
+                                originalModel: event.original_model,
+                                requestId: event.request_id,
+                                ...(latestAssistantMessageModel ? { signerModel: latestAssistantMessageModel } : {}),
+                            },
+                        });
+                    }
+                    switch (event.type) {
+                        case "assistant": {
+                            latestAssistantMessageModel = extractAssistantMessageModel(event) ?? latestAssistantMessageModel;
+                            finalMessage = extractAssistantMessage(event) ?? finalMessage;
+                            if (finalMessage) {
+                                builder.emit({ type: "message", text: finalMessage });
+                            }
+                            break;
+                        }
+                        case "result": {
+                            const resultText = extractResultText(event);
+                            if (event.subtype === "success") {
+                                finalMessage = resultText ?? finalMessage;
+                                if (finalMessage) {
+                                    builder.emit({ type: "message", text: finalMessage });
+                                }
+                                sawSuccessfulResult = true;
+                                // Advance generation fence BEFORE maybe-ending the stream so gated tells can yield.
+                                bumpResultOrdinal();
+                                const checkpoint = {
+                                    fence: { kind: "ordinal", ordinal: completedResultOrdinal },
+                                };
+                                // Record the native result before the synchronous pump can
+                                // consume any tell fenced to an earlier result.
+                                if (options.onEvidence) {
+                                    emitProviderEvidence(options.onEvidence, {
+                                        type: "checkpoint",
+                                        provider: CLAUDE_AGENT_SDK_PROVIDER,
+                                        ...checkpoint,
+                                        source: "response",
+                                    }, (text) => builder.emit({ type: "diagnostic", text }));
+                                }
+                                // Sync checkpoint: claim inbox tells and deliver them via steer control.
+                                options.onSyncCheckpoint?.({ enqueue }, checkpoint);
+                                // Defer end so concurrent enqueue after this result can register openSteerCount.
+                                queueMicrotask(() => maybeEndInputStream());
+                                break;
+                            }
+                            bumpResultOrdinal();
+                            if (resultText) {
+                                builder.emit({ type: "diagnostic", text: resultText });
+                            }
+                            const message = resultText ?? `${CLAUDE_AGENT_SDK_PROVIDER} exec failed`;
+                            builder.emit({ type: "fail", message });
+                            inputStream.end();
+                            throw new Error(message);
+                        }
+                        default:
+                            break;
+                    }
+                }
+                if (queryAbortController.signal.aborted) {
+                    throw createAbortError(`${CLAUDE_AGENT_SDK_PROVIDER} exec cancelled by client`);
+                }
+                if (!resumedSessionId) {
+                    const message = `${CLAUDE_AGENT_SDK_PROVIDER} exec could not determine session id`;
+                    builder.emit({ type: "fail", message });
+                    throw new Error(message);
+                }
+                const session = {
+                    provider: "claude-agent-sdk",
+                    version: SUBAGENT_SESSION_VERSION,
+                    handle: { sessionId: resumedSessionId },
+                };
+                if (options.onEvidence)
+                    emitProviderEvidence(options.onEvidence, { type: "session", provider: CLAUDE_AGENT_SDK_PROVIDER, sessionId: resumedSessionId }, (text) => builder.emit({ type: "diagnostic", text }));
+                const resolvedFinal = finalMessage ?? "";
+                builder.emit({
+                    type: "done",
+                    finalMessage: resolvedFinal,
+                    session,
+                });
+                // Clean end on success: do not reject the stream (that would poison completion).
+                // Any still-pending enqueue waiters are rejected below as "query ended".
+                inputStream?.end();
+                return { finalMessage: resolvedFinal, session };
+            }
+            finally {
+                unlinkBuilderAbort?.();
+                unlinkOuterAbort?.();
+                queryEnded = true;
+                queryActive = false;
+                liveQuery = undefined;
+                // Unblock any mid-flight enqueue/generation waiters without throwing from run().
+                const endError = new Error(`${CLAUDE_AGENT_SDK_PROVIDER} query ended`);
+                if (inputStream) {
+                    // If abort/failure already ended with an error, this is a no-op (closed).
+                    // If success path already clean-ended, also a no-op.
+                    // If we exited via throw before clean end, reject unresolved post-yield acks.
+                    inputStream.end(endError);
+                }
+                rejectPendingEnqueueWaiters(endError);
+            }
+        },
+    });
+}