@noetic-tools/core 0.0.1 → 0.1.1

package/dist/runtime/agent-harness.js

@@ -1,1170 +0,0 @@
-import { OpenRouter } from '@openrouter/agent';
-import { z } from 'zod';
-import { createInMemoryFsAdapter } from '../adapters/in-memory-fs-adapter';
-import { createInMemoryShellAdapter } from '../adapters/in-memory-shell-adapter';
-import { createInMemorySubprocessAdapter } from '../adapters/in-memory-subprocess-adapter';
-import { convertTools, executeToolCall, extractOutputItems, extractSystemInstruction, extractUsage, itemsToInput, } from '../adapters/openrouter';
-import { NoeticConfigError } from '../errors/noetic-config-error';
-import { collectAllTools, deduplicateTools } from '../interpreter/collect-tools';
-import { execute } from '../interpreter/execute';
-import { frameworkCast } from '../interpreter/framework-cast';
-import { isFunctionCall } from '../interpreter/typeguards';
-import { resolveLayerTools } from '../memory/layer-api';
-import { afterModelCallLayers, beforeToolCallLayers, createLayerStateStore, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, resolveLayerBudgets, runAppendPipeline, storeLayers, } from '../memory/layer-lifecycle';
-import { assembleView } from '../memory/projector';
-import { SpanImpl } from '../observability/span-impl';
-import { NoopExporter } from '../observability/trace-exporter';
-import { ItemSchemaRegistry, mergeExtensions } from '../schemas/item';
-import { SteeringAction } from '../types/steering';
-import { emitFrameworkEvent, getBroadcaster, shouldEmit } from './broadcaster-utils';
-import { ChannelStore } from './channel-store';
-import { ContextImpl } from './context-impl';
-import { snapshotCwdState } from './cwd-helpers';
-import { DetachedHandleImpl } from './detached-handle';
-import { contextToExecCtx } from './exec-context-factory';
-import { createInMemoryStorage } from './in-memory-storage';
-import { SessionRunner } from './session-runner';
-import { buildItemStream, filterReasoningStream, filterTextStream } from './session-streams';
-//#endregion
-const MAX_TOOL_ROUNDS = 32;
-const MAX_RECOVERY_CONTINUATIONS = 3;
-const EPHEMERAL_CONTINUE_INPUT = 'continue';
-const DEFAULT_THREAD_ID = '__default__';
-/** Default idle-timeout for a single model call's streaming response. Chosen to be
- *  long enough that slow models aren't falsely aborted, but short enough that a
- *  stalled SSE becomes a visible error rather than a silent hang. */
-const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 120e3;
-//#region Helpers
-/**
- * Pick the right `cwdState` for a new Context.
- *
- * - `cwdInit` explicitly overrides everything (worktree isolation).
- * - Parent snapshot if present (snapshot, not shared reference — child `cd`
- *   does not leak to parent).
- * - Otherwise share the harness `rootCwdState` reference so successive root
- *   contexts see TUI/agent `cd`s carry across runs.
- */
-function resolveContextCwdState(rootCwdState, parent, cwdInit) {
-    if (cwdInit !== undefined) {
-        return {
-            cwd: cwdInit,
-        };
-    }
-    if (parent) {
-        return snapshotCwdState(parent);
-    }
-    return rootCwdState;
-}
-function createClient(config) {
-    const processValue = 'process' in globalThis ? globalThis.process : undefined;
-    const envValue = typeof processValue === 'object' && processValue !== null && 'env' in processValue
-        ? processValue.env
-        : undefined;
-    const openRouterApiKey = typeof envValue === 'object' && envValue !== null && 'OPENROUTER_API_KEY' in envValue
-        ? envValue.OPENROUTER_API_KEY
-        : undefined;
-    const apiKey = config?.apiKey ?? (typeof openRouterApiKey === 'string' ? openRouterApiKey : undefined);
-    if (!apiKey) {
-        return undefined;
-    }
-    return new OpenRouter({
-        apiKey,
-    });
-}
-function mergeItemSchemaExtensions(extensions) {
-    let result = {
-        items: [],
-        developerMessages: [],
-        toolCalls: [],
-        toolResults: [],
-    };
-    for (const ext of extensions) {
-        if (ext) {
-            result = mergeExtensions(result, ext);
-        }
-    }
-    return result;
-}
-function collectLayerItemSchemaExtensions(layers) {
-    return mergeItemSchemaExtensions(layers?.map((layer) => layer.itemSchemas) ?? []);
-}
-function collectToolItemSchemaExtensions(tools) {
-    return mergeItemSchemaExtensions(tools?.map((tool) => tool.itemSchemas) ?? []);
-}
-function buildItemSchemaRegistry({ base, layers, tools, }) {
-    return base
-        .extend(collectLayerItemSchemaExtensions(layers))
-        .extend(collectToolItemSchemaExtensions(tools));
-}
-function createToolResultItem({ output, callId, roundItemSchemas, tool, callItem, args, result, error, }) {
-    const baseItem = {
-        id: crypto.randomUUID(),
-        status: 'completed',
-        type: 'function_call_output',
-        callId,
-        output,
-    };
-    const decorated = tool?.decorateResultItem && callItem?.type === 'function_call'
-        ? tool.decorateResultItem({
-            baseItem,
-            callItem,
-            args,
-            result,
-            output,
-            error,
-        })
-        : baseItem;
-    return roundItemSchemas.parseWithCategory(decorated, 'toolResults');
-}
-function buildTextFormat(schema) {
-    const jsonSchema = z.toJSONSchema(schema);
-    return {
-        format: {
-            type: 'json_schema',
-            name: 'output',
-            schema: jsonSchema,
-        },
-    };
-}
-function isStreamRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
-function providerTerminalError(response) {
-    if (!isStreamRecord(response) || response.status === undefined) {
-        return null;
-    }
-    const status = String(response.status);
-    if (status === 'completed') {
-        return null;
-    }
-    if (status === 'incomplete') {
-        const details = response.incompleteDetails;
-        const reason = isStreamRecord(details) && typeof details.reason === 'string' ? `: ${details.reason}` : '';
-        return {
-            status,
-            message: `LLM response incomplete${reason}`,
-        };
-    }
-    if (status === 'failed') {
-        const error = response.error;
-        const message = isStreamRecord(error) && typeof error.message === 'string' ? `: ${error.message}` : '';
-        return {
-            status,
-            message: `LLM response failed${message}`,
-        };
-    }
-    return {
-        status,
-        message: `LLM response ended with status '${status}'`,
-    };
-}
-function hasUsableResponseOutput(response, items) {
-    if (items.length > 0) {
-        return true;
-    }
-    return (isStreamRecord(response) &&
-        typeof response.outputText === 'string' &&
-        response.outputText.length > 0);
-}
-function withEphemeralContinueInput(input) {
-    return [
-        ...frameworkCast(input),
-        frameworkCast({
-            type: 'message',
-            role: 'user',
-            content: EPHEMERAL_CONTINUE_INPUT,
-        }),
-    ];
-}
-/** Race a promise against an AbortSignal so callers (e.g. `SessionRunner.abort`)
- *  can break out of a long `await` without waiting for the underlying call to
- *  settle. When the signal fires, the returned promise rejects with
- *  `signal.reason` (an `Error`) or a generic `Error('aborted')` fallback. */
-function awaitWithAbort(p, signal) {
-    if (!signal) {
-        return p;
-    }
-    if (signal.aborted) {
-        return Promise.reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
-    }
-    return new Promise((resolve, reject) => {
-        const onAbort = () => {
-            reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
-        };
-        signal.addEventListener('abort', onAbort, {
-            once: true,
-        });
-        p.then((v) => {
-            signal.removeEventListener('abort', onAbort);
-            resolve(v);
-        }, (e) => {
-            signal.removeEventListener('abort', onAbort);
-            reject(e);
-        });
-    });
-}
-async function pipeStreamEventsToBroadcaster(opts) {
-    const { stream, broadcaster, agentName, signal, onEvent } = opts;
-    try {
-        for await (const event of stream) {
-            if (signal?.aborted) {
-                return;
-            }
-            onEvent?.();
-            if (!isStreamRecord(event)) {
-                continue;
-            }
-            broadcaster?.emit({
-                source: 'sdk',
-                type: typeof event.type === 'string' ? event.type : 'unknown',
-                data: event,
-                outputIndex: typeof event.outputIndex === 'number' ? event.outputIndex : undefined,
-                contentIndex: typeof event.contentIndex === 'number' ? event.contentIndex : undefined,
-            });
-        }
-    }
-    catch (err) {
-        if (broadcaster) {
-            emitFrameworkEvent({
-                broadcaster,
-                agentName,
-                eventType: 'stream_pipe_error',
-                data: {
-                    error: err instanceof Error ? err.message : String(err),
-                },
-            });
-        }
-        throw err;
-    }
-}
-/** @internal Create a watchdog that aborts `controller` when no
- *  {@link StreamIdleWatchdog.reset reset} is called within `timeoutMs`. When
- *  `timeoutMs <= 0`, returns an inert no-op so callers can always call `.reset()`
- *  / `.stop()` without a branch. Starts armed: the caller is responsible for
- *  `.stop()` in a `finally`. `onTimeout` runs before the abort so observers can
- *  emit a framework event with the original cause. Exported only for unit tests. */
-export function createStreamIdleWatchdog(timeoutMs, controller, onTimeout) {
-    if (timeoutMs <= 0) {
-        return {
-            reset: () => { },
-            stop: () => { },
-        };
-    }
-    let timer;
-    let stopped = false;
-    const arm = () => {
-        timer = setTimeout(() => {
-            if (stopped) {
-                return;
-            }
-            const reason = new Error(`llm stream idle timeout after ${timeoutMs}ms`);
-            onTimeout?.();
-            controller.abort(reason);
-        }, timeoutMs);
-    };
-    arm();
-    return {
-        reset: () => {
-            if (stopped || !timer) {
-                return;
-            }
-            clearTimeout(timer);
-            arm();
-        },
-        stop: () => {
-            stopped = true;
-            if (timer) {
-                clearTimeout(timer);
-                timer = undefined;
-            }
-        },
-    };
-}
-function hasSessionQueue(ctx) {
-    const maybe = frameworkCast(ctx);
-    return (maybe._sessionBetweenRounds === true &&
-        maybe._sessionQueue !== undefined &&
-        typeof maybe._sessionRunnerAgentName === 'string');
-}
-//#endregion
-//#region AgentHarness
-/**
- * Default agent harness for executing agent steps with built-in channel, memory, and trace support.
- * Provides channel store, memory layer lifecycle, and trace export with no external dependencies.
- *
- * Messages submitted via `execute()` are enqueued on a per-thread session and
- * processed by a `SessionRunner`. Consumers observe responses via the session-
- * scoped accessors: `getAgentResponse`, `getItemStream`, etc.
- *
- * @public
- */
-export class AgentHarness {
-    config;
-    fs;
-    shell;
-    subprocess;
-    initialStep;
-    _memory;
-    client;
-    channelStore;
-    callModelOverride;
-    defaultDeliveryMode;
-    streamIdleTimeoutMs;
-    sessions = new Map();
-    layerStateStore;
-    traceExporter;
-    /**
-     * Long-lived shared cwd state. The same reference is seeded into every
-     * root Context this harness creates, so successive `run()` calls — and the
-     * TUI — observe each other's `cd`s.
-     */
-    rootCwdState;
-    itemSchemas;
-    constructor(opts) {
-        const validatedParams = opts.paramsSchema ? opts.paramsSchema.parse(opts.params) : opts.params;
-        this.config = {
-            name: opts.name,
-            storage: opts.storage ?? createInMemoryStorage(),
-            hooks: opts.hooks,
-            params: validatedParams,
-            itemSchemas: opts.itemSchemas,
-            strictItemSchemas: opts.strictItemSchemas ?? true,
-        };
-        this.fs = opts.fs ?? createInMemoryFsAdapter();
-        this.shell = opts.shell ?? createInMemoryShellAdapter();
-        this.subprocess = opts.subprocess ?? createInMemorySubprocessAdapter();
-        this.initialStep = opts.initialStep;
-        this._memory = opts.memory;
-        this.callModelOverride = opts._testCallModel;
-        this.client = opts._testCallModel ? undefined : createClient(opts.llm);
-        this.channelStore = new ChannelStore();
-        this.traceExporter = opts.traceExporter ?? new NoopExporter();
-        this.layerStateStore = opts.layerStateStore ?? createLayerStateStore();
-        this.defaultDeliveryMode = opts.defaultDeliveryMode ?? 'next-turn';
-        this.streamIdleTimeoutMs = opts.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
-        this.itemSchemas = new ItemSchemaRegistry(opts.itemSchemas, {
-            strictUnknownExtensions: opts.strictItemSchemas ?? true,
-        });
-        this.rootCwdState = {
-            cwd: opts.initialCwd ?? '/',
-        };
-    }
-    /**
-     * Update the harness-wide root cwd. The TUI calls this in response to a
-     * user-issued `! cd`, so the next root Context (and any tool inspecting
-     * `harness.rootCwdState.cwd`) observes the new value. Caller is responsible
-     * for passing an absolute, validated path.
-     */
-    setRootCwd(nextCwd) {
-        if (nextCwd === this.rootCwdState.cwd) {
-            return;
-        }
-        this.rootCwdState.previousCwd = this.rootCwdState.cwd;
-        this.rootCwdState.cwd = nextCwd;
-    }
-    //#region Session Accessors
-    execute(input, options) {
-        if (!this.initialStep) {
-            return Promise.reject(new NoeticConfigError({
-                code: 'NO_STEP_CONFIGURED',
-                message: 'No initialStep configured on this harness.',
-                hint: 'Pass `initialStep` in constructor options, or use run() directly.',
-            }));
-        }
-        const threadId = options?.threadId ?? DEFAULT_THREAD_ID;
-        const deliveryMode = options?.deliveryMode ?? this.defaultDeliveryMode;
-        const session = this.getOrCreateSession(threadId);
-        const message = {
-            id: options?.messageId ?? `msg-${crypto.randomUUID()}`,
-            input,
-            deliveryMode,
-            options: options ?? {},
-            enqueuedAt: Date.now(),
-        };
-        if (deliveryMode === 'interrupt' && session.runner.getStatus().kind === 'generating') {
-            session.runner.queue.prepend(message);
-            // Abort kicks the runner via queue subscription after the in-flight turn settles.
-            void session.runner.abort('interrupt');
-            return Promise.resolve();
-        }
-        session.runner.queue.enqueue(message);
-        return Promise.resolve();
-    }
-    getAgentResponse(scope) {
-        const session = this.requireSession(scope);
-        return session.runner.getAgentResponse();
-    }
-    getItemStream(scope) {
-        const session = this.requireSession(scope);
-        return buildItemStream(session.runner.broadcaster, this.itemSchemas);
-    }
-    getTextStream(scope) {
-        const session = this.requireSession(scope);
-        return filterTextStream(session.runner.broadcaster);
-    }
-    getReasoningStream(scope) {
-        const session = this.requireSession(scope);
-        return filterReasoningStream(session.runner.broadcaster);
-    }
-    getFullStream(scope) {
-        const session = this.requireSession(scope);
-        return session.runner.broadcaster;
-    }
-    async abort(scope) {
-        const threadId = scope?.threadId ?? DEFAULT_THREAD_ID;
-        const session = this.sessions.get(threadId);
-        if (!session) {
-            return;
-        }
-        await session.runner.abort(scope?.reason);
-    }
-    getStatus(scope) {
-        const threadId = scope?.threadId ?? DEFAULT_THREAD_ID;
-        const session = this.sessions.get(threadId);
-        if (!session) {
-            return {
-                kind: 'idle',
-            };
-        }
-        return session.runner.getStatus();
-    }
-    getQueueSize(scope) {
-        const threadId = scope?.threadId ?? DEFAULT_THREAD_ID;
-        const session = this.sessions.get(threadId);
-        return session ? session.runner.queue.size : 0;
-    }
-    seedSessionHistory(threadId, items) {
-        const session = this.getOrCreateSession(threadId);
-        session.accumulatedItems = [
-            ...items,
-        ];
-    }
-    getOrCreateSession(threadId) {
-        const existing = this.sessions.get(threadId);
-        if (existing) {
-            return existing;
-        }
-        const session = {
-            accumulatedItems: [],
-            runner: new SessionRunner({
-                threadId,
-                agentName: this.config.name,
-                // The first queued message in a batch establishes `resourceId` /
-                // `state` / `memory` for the turn. If multiple messages are drained
-                // together (queue flush), later messages' values for these fields
-                // are ignored. `deliveryMode` is resolved per-message at enqueue
-                // time and doesn't apply here.
-                createContext: (items, _turnId, messages) => {
-                    const perTurnOptions = messages[0]?.options ?? {};
-                    const allItems = [
-                        ...session.accumulatedItems,
-                        ...items,
-                    ];
-                    const ctx = this.createContext({
-                        items: allItems,
-                        threadId,
-                        resourceId: perTurnOptions.resourceId,
-                        state: perTurnOptions.state,
-                        memory: perTurnOptions.memory,
-                        _broadcaster: session.runner.broadcaster,
-                    });
-                    const ext = frameworkCast(ctx);
-                    ext._sessionQueue = session.runner.queue;
-                    ext._sessionBetweenRounds = true;
-                    ext._sessionRunnerAgentName = this.config.name;
-                    if (this.initialStep) {
-                        this.setUnifiedTools(ctx, collectAllTools(this.initialStep));
-                    }
-                    return ctx;
-                },
-                runTurn: async (ctx, _turn, signal) => {
-                    if (!this.initialStep) {
-                        throw new NoeticConfigError({
-                            code: 'NO_STEP_CONFIGURED',
-                            message: 'No initialStep configured on this harness.',
-                            hint: 'Pass `initialStep` in constructor options.',
-                        });
-                    }
-                    // Wire signal-abort to context-abort so the interpreter bails cleanly.
-                    if (signal.aborted) {
-                        ctx.abort(signal.reason ? String(signal.reason) : 'aborted');
-                    }
-                    else {
-                        signal.addEventListener('abort', () => {
-                            ctx.abort(signal.reason ? String(signal.reason) : 'aborted');
-                        }, {
-                            once: true,
-                        });
-                    }
-                    const result = await this.initAndRun(this.initialStep, '', ctx);
-                    // Snapshot final items into session history for the next turn.
-                    session.accumulatedItems = [
-                        ...ctx.itemLog.items,
-                    ];
-                    return result;
-                },
-            }),
-        };
-        this.sessions.set(threadId, session);
-        return session;
-    }
-    requireSession(scope) {
-        const threadId = scope?.threadId ?? DEFAULT_THREAD_ID;
-        let session = this.sessions.get(threadId);
-        if (session) {
-            return session;
-        }
-        // Lazily create so consumers can attach stream listeners before the first execute.
-        session = this.getOrCreateSession(threadId);
-        return session;
-    }
-    //#endregion
-    //#region callModel
-    async callModel(request) {
-        if (this.callModelOverride) {
-            const response = await this.callModelOverride(request);
-            const itemSchemas = buildItemSchemaRegistry({
-                base: this.itemSchemas,
-                layers: request.layers,
-                tools: request.tools,
-            });
-            return {
-                ...response,
-                items: itemSchemas.parseMany(response.items),
-            };
-        }
-        if (!this.client) {
-            throw new NoeticConfigError({
-                code: 'NO_LLM_PROVIDER',
-                message: 'No LLM provider configured on this harness.',
-                hint: 'Pass `llm: { provider: "openrouter", apiKey: "..." }` in constructor options or set OPENROUTER_API_KEY.',
-            });
-        }
-        const { instructions: extractedInstructions, remaining } = extractSystemInstruction(request.items);
-        const instructions = [
-            request.instructions,
-            extractedInstructions,
-        ]
-            .filter(Boolean)
-            .join('\n\n') || undefined;
-        const broadcaster = getBroadcaster(request.ctx);
-        const agentName = this.config.name;
-        const signal = request.signal;
-        const emitIfAllowed = (eventType, data) => {
-            if (shouldEmit(request.emit, eventType, data)) {
-                emitFrameworkEvent({
-                    broadcaster,
-                    agentName,
-                    eventType,
-                    data,
-                });
-            }
-        };
-        const allowedNamesSet = request.tools && 'allowedToolNames' in request && request.allowedToolNames
-            ? new Set(request.allowedToolNames)
-            : undefined;
-        const filteredTools = allowedNamesSet
-            ? request.tools?.filter((t) => allowedNamesSet.has(t.name))
-            : request.tools;
-        let sdkTools;
-        if (filteredTools && filteredTools.length > 0) {
-            sdkTools = convertTools({
-                tools: filteredTools,
-            });
-        }
-        const allItems = [];
-        const totalUsage = {
-            inputTokens: 0,
-            outputTokens: 0,
-            cachedTokens: 0,
-        };
-        let totalCost = 0;
-        const conversationInput = itemsToInput(remaining);
-        const textFormat = request.outputSchema ? buildTextFormat(request.outputSchema) : undefined;
-        let round = 0;
-        let invalidRecoveryContinuations = 0;
-        let toolLimitRecoveryContinuations = 0;
-        let useEphemeralContinue = false;
-        while (!signal?.aborted) {
-            const recoveryContinuation = useEphemeralContinue;
-            useEphemeralContinue = false;
-            // Inject between-rounds inbox messages (mode: 'between-rounds') before
-            // the next LLM call. Mirrors Claude Code's teammate-attachment path.
-            // Also append to ctx.itemLog so the session's post-turn snapshot
-            // carries the injected messages into next turn's history.
-            if (round > 0 && request.ctx && hasSessionQueue(request.ctx)) {
-                const injected = this.drainBetweenRoundsMessages(request.ctx._sessionQueue);
-                if (injected.length > 0) {
-                    for (const msg of injected) {
-                        const text = itemToText(msg);
-                        const userItem = {
-                            id: `user-${crypto.randomUUID()}`,
-                            type: 'message',
-                            role: 'user',
-                            status: 'completed',
-                            content: [
-                                {
-                                    type: 'input_text',
-                                    text,
-                                },
-                            ],
-                        };
-                        conversationInput.push({
-                            type: 'message',
-                            role: 'user',
-                            content: [
-                                {
-                                    type: 'input_text',
-                                    text,
-                                },
-                            ],
-                        });
-                        request.ctx.itemLog.append(userItem);
-                    }
-                    emitIfAllowed('inbox_injected', {
-                        round,
-                        count: injected.length,
-                        messageIds: injected.map((i) => i.id),
-                    });
-                }
-            }
-            // Build a round-scoped controller that also aborts when the caller's
-            // signal fires — `AbortSignal.any` handles listener lifecycle for us
-            // (no manual cleanup required on normal completion).
-            const roundController = new AbortController();
-            const roundSignal = signal
-                ? AbortSignal.any([
-                    signal,
-                    roundController.signal,
-                ])
-                : roundController.signal;
-            let firstEventSeen = false;
-            let idleStalled = false;
-            const watchdog = createStreamIdleWatchdog(this.streamIdleTimeoutMs, roundController, () => {
-                idleStalled = true;
-                emitIfAllowed('llm_call_stalled', {
-                    round,
-                    idleTimeoutMs: this.streamIdleTimeoutMs,
-                });
-            });
-            const modelInput = recoveryContinuation
-                ? withEphemeralContinueInput(conversationInput)
-                : frameworkCast(conversationInput);
-            emitIfAllowed('llm_call_started', {
-                round,
-                messageCount: modelInput.length,
-                toolCount: sdkTools?.length ?? 0,
-                recoveryContinuation,
-            });
-            const callResult = this.client.callModel({
-                model: request.model,
-                input: modelInput,
-                instructions,
-                tools: sdkTools,
-                temperature: request.params?.temperature,
-                maxOutputTokens: request.params?.maxTokens,
-                topP: request.params?.topP,
-                ...(textFormat
-                    ? {
-                        text: textFormat,
-                    }
-                    : {}),
-            }, {
-                signal: roundSignal,
-            });
-            const onStreamEvent = () => {
-                watchdog.reset();
-                if (!firstEventSeen) {
-                    firstEventSeen = true;
-                    emitIfAllowed('llm_call_first_event', {
-                        round,
-                    });
-                }
-            };
-            // Always consume the SDK stream so the watchdog gets reset per event
-            // even when no broadcaster is attached (headless / test harness runs).
-            // Emission into the broadcaster is optional inside the pipe function.
-            const pipePromise = pipeStreamEventsToBroadcaster({
-                stream: callResult.getFullResponsesStream(),
-                broadcaster,
-                agentName,
-                signal: roundSignal,
-                onEvent: onStreamEvent,
-            });
-            let sdkResponse;
-            try {
-                sdkResponse = await awaitWithAbort(callResult.getResponse(), roundSignal);
-                // Stop the watchdog synchronously the instant the response resolves,
-                // closing the race where a pending setTimeout could fire in the
-                // microtask gap between this await and the `finally` below.
-                watchdog.stop();
-                await awaitWithAbort(pipePromise, roundSignal);
-            }
-            catch (err) {
-                if (idleStalled) {
-                    // roundSignal.reason is the Error the watchdog passed to controller.abort().
-                    throw roundSignal.reason instanceof Error
-                        ? roundSignal.reason
-                        : new Error(`llm stream idle timeout after ${this.streamIdleTimeoutMs}ms`);
-                }
-                // Parent signal cancelled the round — exit gracefully rather than
-                // propagating the abort error as an exception.
-                if (signal?.aborted) {
-                    break;
-                }
-                throw err;
-            }
-            finally {
-                watchdog.stop();
-            }
-            if (signal?.aborted) {
-                break;
-            }
-            const terminalError = providerTerminalError(sdkResponse);
-            if (terminalError) {
-                emitIfAllowed('llm_call_failed', {
-                    round,
-                    status: terminalError.status,
-                    error: terminalError.message,
-                    recoverable: invalidRecoveryContinuations < MAX_RECOVERY_CONTINUATIONS,
-                });
-                if (invalidRecoveryContinuations >= MAX_RECOVERY_CONTINUATIONS) {
-                    throw new Error(terminalError.message);
-                }
-                invalidRecoveryContinuations += 1;
-                useEphemeralContinue = true;
-                emitIfAllowed('llm_call_recovery_continue', {
-                    round,
-                    status: terminalError.status,
-                    attempt: invalidRecoveryContinuations,
-                    maxAttempts: MAX_RECOVERY_CONTINUATIONS,
-                });
-                continue;
-            }
-            const roundItemSchemas = buildItemSchemaRegistry({
-                base: this.itemSchemas,
-                layers: request.layers,
-                tools: request.tools,
-            });
-            const roundItems = roundItemSchemas.parseMany(extractOutputItems(sdkResponse));
-            if (!hasUsableResponseOutput(sdkResponse, roundItems)) {
-                const message = 'LLM response completed with no output items';
-                emitIfAllowed('llm_call_failed', {
-                    round,
-                    status: 'completed',
-                    error: message,
-                    recoverable: invalidRecoveryContinuations < MAX_RECOVERY_CONTINUATIONS,
-                });
-                if (invalidRecoveryContinuations >= MAX_RECOVERY_CONTINUATIONS) {
-                    throw new Error(message);
-                }
-                invalidRecoveryContinuations += 1;
-                useEphemeralContinue = true;
-                emitIfAllowed('llm_call_recovery_continue', {
-                    round,
-                    status: 'completed',
-                    attempt: invalidRecoveryContinuations,
-                    maxAttempts: MAX_RECOVERY_CONTINUATIONS,
-                });
-                continue;
-            }
-            invalidRecoveryContinuations = 0;
-            emitIfAllowed('llm_call_completed', {
-                round,
-                itemCount: sdkResponse.output?.length ?? 0,
-            });
-            const roundUsage = extractUsage(sdkResponse.usage);
-            totalUsage.inputTokens += roundUsage.inputTokens;
-            totalUsage.outputTokens += roundUsage.outputTokens;
-            totalUsage.cachedTokens += roundUsage.cachedTokens ?? 0;
-            totalCost += sdkResponse.usage?.cost ?? 0;
-            allItems.push(...roundItems);
-            const functionCalls = roundItems.filter(isFunctionCall);
-            if (functionCalls.length === 0 || !request.tools) {
-                break;
-            }
-            emitIfAllowed('tool_round_started', {
-                round,
-                toolCount: functionCalls.length,
-            });
-            for (const fc of functionCalls) {
-                conversationInput.push({
-                    type: 'function_call',
-                    callId: fc.callId,
-                    id: fc.id ?? crypto.randomUUID(),
-                    name: fc.name,
-                    arguments: fc.arguments,
-                });
-            }
-            for (const fc of functionCalls) {
-                if (signal?.aborted) {
-                    break;
-                }
-                emitIfAllowed('tool_call_started', {
-                    name: fc.name,
-                    callId: fc.callId,
-                });
-                let parsedArgs;
-                try {
-                    parsedArgs = JSON.parse(fc.arguments);
-                }
-                catch {
-                    const errorOutput = `Error: malformed JSON in tool arguments: ${fc.arguments}`;
-                    const toolForCall = request.tools.find((t) => t.name === fc.name);
-                    const outputItem = createToolResultItem({
-                        output: errorOutput,
-                        callId: fc.callId,
-                        roundItemSchemas,
-                        tool: toolForCall,
-                        callItem: fc,
-                        error: true,
-                    });
-                    allItems.push(outputItem);
-                    conversationInput.push({
-                        type: 'function_call_output',
-                        callId: fc.callId,
-                        output: errorOutput,
-                    });
-                    emitIfAllowed('tool_call_completed', {
-                        name: fc.name,
-                        callId: fc.callId,
-                        error: true,
-                    });
-                    continue;
-                }
-                const toolForCall = request.tools.find((t) => t.name === fc.name);
-                const toolResult = await executeToolCall({
-                    toolName: fc.name,
-                    args: parsedArgs,
-                    tools: request.tools,
-                    context: request.ctx,
-                    harness: this,
-                    layers: request.layers,
-                });
-                const { output } = toolResult;
-                const outputItem = createToolResultItem({
-                    output,
-                    callId: fc.callId,
-                    roundItemSchemas,
-                    tool: toolForCall,
-                    callItem: fc,
-                    args: parsedArgs,
-                    result: toolResult.result,
-                    error: toolResult.error,
-                });
-                allItems.push(outputItem);
-                conversationInput.push({
-                    type: 'function_call_output',
-                    callId: fc.callId,
-                    output,
-                });
-                emitIfAllowed('tool_call_completed', {
-                    name: fc.name,
-                    callId: fc.callId,
-                    error: false,
-                });
-            }
-            emitIfAllowed('tool_round_completed', {
-                round,
-                toolCount: functionCalls.length,
-            });
-            round += 1;
-            if (round >= MAX_TOOL_ROUNDS) {
-                emitIfAllowed('tool_round_limit_exceeded', {
-                    maxToolRounds: MAX_TOOL_ROUNDS,
-                    attempt: toolLimitRecoveryContinuations + 1,
-                    maxAttempts: MAX_RECOVERY_CONTINUATIONS,
-                });
-                if (toolLimitRecoveryContinuations >= MAX_RECOVERY_CONTINUATIONS) {
-                    throw new Error(`LLM exceeded maximum tool rounds (${MAX_TOOL_ROUNDS})`);
-                }
-                toolLimitRecoveryContinuations += 1;
-                useEphemeralContinue = true;
-            }
-        }
-        return {
-            items: allItems,
-            usage: totalUsage,
-            cost: totalCost > 0 ? totalCost : undefined,
-        };
-    }
-    /** @internal Drain only messages tagged `between-rounds` from the queue. */
-    drainBetweenRoundsMessages(queue) {
-        const pending = queue.peekAll();
-        const toInject = [];
-        const keep = [];
-        for (const msg of pending) {
-            if (msg.deliveryMode === 'between-rounds') {
-                toInject.push(msg);
-                continue;
-            }
-            keep.push(msg);
-        }
-        if (toInject.length === 0) {
-            return [];
-        }
-        // Replace queue contents: re-prepend kept messages in order after draining.
-        queue.drainAll();
-        for (const msg of keep) {
-            queue.enqueue(msg);
-        }
-        return toInject;
-    }
-    //#endregion
-    async run(s, input, ctx) {
-        return execute(s, input, ctx);
-    }
-    /** Run all layer `init` hooks before the first step executes. Per spec 11,
-     *  init MUST complete before any recall fires so layer state is populated. */
-    async initAndRun(s, input, ctx) {
-        const layers = ctx.layers;
-        const storage = this.config.storage;
-        if (layers && layers.length > 0 && storage) {
-            await this.initLayers(layers, ctx, storage);
-        }
-        return execute(s, input, ctx);
-    }
-    detachedSpawn(s, input, parentCtx, overrides) {
-        const childCtx = this.createContext({
-            parent: parentCtx,
-            threadId: overrides?.threadId ?? parentCtx.threadId,
-            resourceId: overrides?.resourceId ?? parentCtx.resourceId,
-            cwdInit: overrides?.cwdInit,
-        });
-        const promise = this.run(s, input, childCtx);
-        return new DetachedHandleImpl(childCtx.id, promise);
-    }
-    createContext(opts) {
-        const { memory: memoryLayers, cwdInit, ...rest } = opts ?? {};
-        const effectiveMemory = memoryLayers ?? this._memory;
-        const itemSchemas = buildItemSchemaRegistry({
-            base: this.itemSchemas,
-            layers: effectiveMemory,
-        });
-        return new ContextImpl({
-            ...rest,
-            harness: this,
-            channelStore: this.channelStore,
-            layers: effectiveMemory,
-            itemSchemas,
-            cwdState: resolveContextCwdState(this.rootCwdState, opts?.parent, cwdInit),
-        });
-    }
-    send(channel, value, _ctx) {
-        this.channelStore.send(channel, value);
-    }
-    recv(channel, _ctx, opts) {
-        return this.channelStore.recv(channel, opts?.timeout);
-    }
-    tryRecv(channel, _ctx) {
-        return this.channelStore.tryRecv(channel);
-    }
-    getChannelHandle(channel, executionId) {
-        return this.channelStore.getHandle(channel, executionId);
-    }
-    /** Resolves layer-provided tools and merges with step tools into ctx.unifiedTools. */
-    setUnifiedTools(ctx, stepTools) {
-        const layers = ctx.layers;
-        const layerTools = layers && layers.length > 0 ? resolveLayerTools(layers, this, ctx) : [];
-        const allTools = deduplicateTools([
-            ...stepTools,
-            ...layerTools,
-        ]);
-        if (allTools.length > 0) {
-            const impl = frameworkCast(ctx);
-            impl.unifiedTools = allTools;
-        }
-    }
-    toExecCtx(ctx) {
-        return contextToExecCtx(ctx, {
-            callModel: (request) => this.callModel(request),
-        });
-    }
-    async initLayers(layers, ctx, storage) {
-        await initLayers({
-            layers,
-            ctx: this.toExecCtx(ctx),
-            storage,
-            store: this.layerStateStore,
-        });
-    }
-    async recallLayers(layers, input, ctx) {
-        return recallLayers({
-            layers,
-            query: input,
-            ctx: this.toExecCtx(ctx),
-            log: ctx.itemLog,
-            budgets: resolveLayerBudgets(layers),
-            store: this.layerStateStore,
-            itemSchemas: this.itemSchemas,
-        });
-    }
-    /**
-     * Compute the items array that would be sent to the model on the next turn —
-     * the same arrangement `executeLLM` builds: harness-level memory layers'
-     * recall outputs concatenated with the session's accumulated history.
-     *
-     * Read-mostly: `recallLayers` writes layer-state snapshots to
-     * `layerStateStore` exactly as a real turn would, so successive previews
-     * remain consistent with what the next real turn produces.
-     */
-    async previewRequestItems(scope) {
-        const threadId = scope?.threadId ?? DEFAULT_THREAD_ID;
-        // Read-only: if the session doesn't exist, treat history as empty rather
-        // than allocating a SessionRunner for a debug/preview call.
-        const existingSession = this.sessions.get(threadId);
-        const historyItems = existingSession
-            ? [
-                ...existingSession.accumulatedItems,
-            ]
-            : [];
-        const ctx = this.createContext({
-            items: historyItems,
-            threadId,
-            memory: this._memory,
-        });
-        const layers = ctx.layers ?? [];
-        if (layers.length === 0) {
-            return historyItems;
-        }
-        const recallResults = await this.recallLayers(layers, '', ctx);
-        const layerOutputItems = recallResults.flatMap((r) => r.items);
-        if (layerOutputItems.length === 0) {
-            return historyItems;
-        }
-        return assembleView({
-            systemPromptItems: [],
-            layerOutputItems,
-            historyItems,
-        });
-    }
-    async storeLayers(layers, response, ctx) {
-        const storage = this.config.storage;
-        if (!storage) {
-            return;
-        }
-        await storeLayers({
-            layers,
-            response,
-            ctx: this.toExecCtx(ctx),
-            log: ctx.itemLog,
-            store: this.layerStateStore,
-            storage,
-        });
-    }
-    async disposeLayers(layers, ctx) {
-        await disposeLayers({
-            layers,
-            ctx: this.toExecCtx(ctx),
-            store: this.layerStateStore,
-        });
-    }
-    async checkpoint(_ctx) { }
-    async restore(_executionId) {
-        return null;
-    }
-    async cancel(_ctx, _reason) { }
-    createSpan(name, parent) {
-        return new SpanImpl(name, parent);
-    }
-    getLayerState(executionId, layerId) {
-        return this.layerStateStore.get(executionId, layerId);
-    }
-    setLayerState(executionId, layerId, state) {
-        this.layerStateStore.set(executionId, layerId, state);
-    }
-    async beforeToolCall(layers, toolName, toolArgs, ctx) {
-        const hasHook = layers.some((l) => l.hooks.beforeToolCall);
-        if (!hasHook) {
-            return {
-                action: SteeringAction.Allow,
-            };
-        }
-        return beforeToolCallLayers({
-            layers,
-            toolName,
-            toolArgs,
-            ctx: this.toExecCtx(ctx),
-            store: this.layerStateStore,
-        });
-    }
-    async afterModelCall(layers, response, ctx) {
-        const hasHook = layers.some((l) => l.hooks.afterModelCall);
-        if (!hasHook) {
-            return {
-                action: SteeringAction.Allow,
-            };
-        }
-        return afterModelCallLayers({
-            layers,
-            response,
-            ctx: this.toExecCtx(ctx),
-            store: this.layerStateStore,
-        });
-    }
-    async projectHistory(layers, items, ctx) {
-        const hasHook = layers.some((l) => l.hooks.projectHistory);
-        if (!hasHook) {
-            return items;
-        }
-        return projectHistoryLayers({
-            layers,
-            items,
-            ctx: this.toExecCtx(ctx),
-            store: this.layerStateStore,
-        });
-    }
-    async runAppendPipeline(layers, items, ctx) {
-        const hasHook = layers.some((l) => l.hooks.onItemAppend);
-        if (!hasHook) {
-            return {
-                items,
-                rerenderRequests: [],
-            };
-        }
-        return runAppendPipeline({
-            layers,
-            items,
-            ctx: this.toExecCtx(ctx),
-            log: ctx.itemLog,
-            store: this.layerStateStore,
-        });
-    }
-    async executeRerender(requests, layers, ctx, budgets, query) {
-        return executeRerender({
-            requests,
-            layers,
-            ctx: this.toExecCtx(ctx),
-            log: ctx.itemLog,
-            budgets,
-            store: this.layerStateStore,
-            query,
-            itemSchemas: this.itemSchemas,
-        });
-    }
-}
-//#endregion
-//#region Text extraction helper
-function itemToText(msg) {
-    if (typeof msg.input === 'string') {
-        return msg.input;
-    }
-    const items = Array.isArray(msg.input)
-        ? msg.input
-        : [
-            msg.input,
-        ];
-    const texts = [];
-    for (const item of items) {
-        if (item.type !== 'message') {
-            continue;
-        }
-        for (const part of item.content) {
-            if (part.type === 'input_text' || part.type === 'output_text') {
-                texts.push(part.text);
-            }
-        }
-    }
-    return texts.join('\n');
-}
-//#endregion