@noetic-tools/core 0.0.1 → 0.1.1

package/dist/harness/model-call.js

@@ -0,0 +1,694 @@
+import { z } from 'zod';
+import { convertTools, executeToolCall, extractOutputItems, extractSystemInstruction, extractUsage, itemsToInput, sanitizeToolNameForWire, } from '../adapters/openrouter.js';
+import { NoeticConfigError } from '../errors/noetic-config-error.js';
+import { isFunctionCall } from '../interpreter/typeguards.js';
+import { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
+import { frameworkCast } from '../util/framework-cast.js';
+import { buildItemSchemaRegistry, createToolResultItem } from './model-schema.js';
+const MAX_TOOL_ROUNDS = 32;
+const MAX_RECOVERY_CONTINUATIONS = 3;
+const EPHEMERAL_CONTINUE_INPUT = 'continue';
+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');
+}
+function prepareModelRequest(request, agentName) {
+    const { instructions: extractedInstructions, remaining } = extractSystemInstruction(request.items);
+    const instructions = [
+        request.instructions,
+        extractedInstructions,
+    ]
+        .filter(Boolean)
+        .join('\n\n') || undefined;
+    const broadcaster = getBroadcaster(request.ctx);
+    const filteredTools = filterAllowedTools(request);
+    return {
+        instructions,
+        remaining,
+        broadcaster,
+        sdkTools: filteredTools && filteredTools.length > 0
+            ? convertTools({
+                tools: filteredTools,
+            })
+            : undefined,
+        emitIfAllowed(eventType, data) {
+            if (!shouldEmit(request.emit, eventType, data)) {
+                return;
+            }
+            emitFrameworkEvent({
+                broadcaster,
+                agentName,
+                eventType,
+                data,
+            });
+        },
+    };
+}
+function filterAllowedTools(request) {
+    if (!request.tools) {
+        return undefined;
+    }
+    if (!('allowedToolNames' in request) || !request.allowedToolNames) {
+        return request.tools;
+    }
+    const allowedNames = new Set(request.allowedToolNames);
+    return request.tools.filter((tool) => allowedNames.has(tool.name));
+}
+export class AgentHarnessModelCaller {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async callOverriddenModel(request) {
+        if (!this.opts.callModelOverride) {
+            throw new Error('No callModel override configured.');
+        }
+        const response = await this.opts.callModelOverride(request);
+        const itemSchemas = buildItemSchemaRegistry({
+            base: this.opts.itemSchemas,
+            layers: request.layers,
+            tools: request.tools,
+        });
+        return {
+            ...response,
+            items: itemSchemas.parseMany(response.items),
+        };
+    }
+    requireModelClient() {
+        if (this.opts.client) {
+            return this.opts.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.',
+        });
+    }
+    async callModel(request) {
+        if (this.opts.callModelOverride) {
+            return this.callOverriddenModel(request);
+        }
+        const client = this.requireModelClient();
+        const prepared = prepareModelRequest(request, this.opts.agentName);
+        const allItems = [];
+        const totalUsage = {
+            inputTokens: 0,
+            outputTokens: 0,
+            cachedTokens: 0,
+        };
+        let totalCost = 0;
+        const conversationInput = itemsToInput(prepared.remaining);
+        const textFormat = request.outputSchema ? buildTextFormat(request.outputSchema) : undefined;
+        let round = 0;
+        let invalidRecoveryContinuations = 0;
+        let toolLimitRecoveryContinuations = 0;
+        let useEphemeralContinue = false;
+        while (!request.signal?.aborted) {
+            const recoveryContinuation = useEphemeralContinue;
+            useEphemeralContinue = false;
+            if (round > 0 && request.ctx && hasSessionQueue(request.ctx)) {
+                this.injectBetweenRoundMessages(request.ctx, conversationInput, round, prepared.emitIfAllowed);
+            }
+            const roundController = new AbortController();
+            const roundSignal = request.signal
+                ? AbortSignal.any([
+                    request.signal,
+                    roundController.signal,
+                ])
+                : roundController.signal;
+            let firstEventSeen = false;
+            let idleStalled = false;
+            const watchdog = createStreamIdleWatchdog(this.opts.streamIdleTimeoutMs, roundController, () => {
+                idleStalled = true;
+                prepared.emitIfAllowed('llm_call_stalled', {
+                    round,
+                    idleTimeoutMs: this.opts.streamIdleTimeoutMs,
+                });
+            });
+            const modelInput = recoveryContinuation
+                ? withEphemeralContinueInput(conversationInput)
+                : frameworkCast(conversationInput);
+            prepared.emitIfAllowed('llm_call_started', {
+                round,
+                messageCount: modelInput.length,
+                toolCount: prepared.sdkTools?.length ?? 0,
+                recoveryContinuation,
+            });
+            const callResult = client.callModel({
+                model: request.model,
+                input: modelInput,
+                instructions: prepared.instructions,
+                tools: prepared.sdkTools,
+                temperature: request.params?.temperature,
+                maxOutputTokens: request.params?.maxTokens,
+                topP: request.params?.topP,
+                ...(textFormat
+                    ? {
+                        text: textFormat,
+                    }
+                    : {}),
+            }, {
+                signal: roundSignal,
+            });
+            const pipePromise = pipeStreamEventsToBroadcaster({
+                stream: callResult.getFullResponsesStream(),
+                broadcaster: prepared.broadcaster,
+                agentName: this.opts.agentName,
+                signal: roundSignal,
+                onEvent: () => {
+                    watchdog.reset();
+                    if (!firstEventSeen) {
+                        firstEventSeen = true;
+                        prepared.emitIfAllowed('llm_call_first_event', {
+                            round,
+                        });
+                    }
+                },
+            });
+            let sdkResponse;
+            try {
+                sdkResponse = await awaitWithAbort(callResult.getResponse(), roundSignal);
+                watchdog.stop();
+                await awaitWithAbort(pipePromise, roundSignal);
+            }
+            catch (err) {
+                if (idleStalled) {
+                    throw roundSignal.reason instanceof Error
+                        ? roundSignal.reason
+                        : new Error(`llm stream idle timeout after ${this.opts.streamIdleTimeoutMs}ms`);
+                }
+                if (request.signal?.aborted) {
+                    break;
+                }
+                throw err;
+            }
+            finally {
+                watchdog.stop();
+            }
+            if (request.signal?.aborted) {
+                break;
+            }
+            const recovery = this.handleModelRecovery({
+                sdkResponse,
+                round,
+                invalidRecoveryContinuations,
+                emitIfAllowed: prepared.emitIfAllowed,
+            });
+            if (recovery.kind === 'continue') {
+                invalidRecoveryContinuations = recovery.invalidRecoveryContinuations;
+                useEphemeralContinue = true;
+                continue;
+            }
+            const roundItemSchemas = buildItemSchemaRegistry({
+                base: this.opts.itemSchemas,
+                layers: request.layers,
+                tools: request.tools,
+            });
+            const roundItems = roundItemSchemas.parseMany(extractOutputItems(sdkResponse));
+            const outputRecovery = this.handleEmptyOutputRecovery({
+                sdkResponse,
+                roundItems,
+                round,
+                invalidRecoveryContinuations,
+                emitIfAllowed: prepared.emitIfAllowed,
+            });
+            if (outputRecovery.kind === 'continue') {
+                invalidRecoveryContinuations = outputRecovery.invalidRecoveryContinuations;
+                useEphemeralContinue = true;
+                continue;
+            }
+            invalidRecoveryContinuations = 0;
+            prepared.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;
+            }
+            await this.executeToolRound({
+                functionCalls,
+                request,
+                roundItemSchemas,
+                allItems,
+                conversationInput,
+                round,
+                emitIfAllowed: prepared.emitIfAllowed,
+            });
+            round += 1;
+            const limitRecovery = this.handleToolRoundLimit({
+                round,
+                toolLimitRecoveryContinuations,
+                emitIfAllowed: prepared.emitIfAllowed,
+            });
+            if (limitRecovery.kind === 'continue') {
+                toolLimitRecoveryContinuations = limitRecovery.toolLimitRecoveryContinuations;
+                useEphemeralContinue = true;
+            }
+        }
+        return {
+            items: allItems,
+            usage: totalUsage,
+            cost: totalCost > 0 ? totalCost : undefined,
+        };
+    }
+    injectBetweenRoundMessages(ctx, conversationInput, round, emitIfAllowed) {
+        const injected = this.drainBetweenRoundsMessages(ctx._sessionQueue);
+        if (injected.length === 0) {
+            return;
+        }
+        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,
+                    },
+                ],
+            });
+            ctx.itemLog.append(userItem);
+        }
+        emitIfAllowed('inbox_injected', {
+            round,
+            count: injected.length,
+            messageIds: injected.map((i) => i.id),
+        });
+    }
+    handleModelRecovery(params) {
+        const terminalError = providerTerminalError(params.sdkResponse);
+        if (!terminalError) {
+            return {
+                kind: 'ok',
+            };
+        }
+        params.emitIfAllowed('llm_call_failed', {
+            round: params.round,
+            status: terminalError.status,
+            error: terminalError.message,
+            recoverable: params.invalidRecoveryContinuations < MAX_RECOVERY_CONTINUATIONS,
+        });
+        if (params.invalidRecoveryContinuations >= MAX_RECOVERY_CONTINUATIONS) {
+            throw new Error(terminalError.message);
+        }
+        const next = params.invalidRecoveryContinuations + 1;
+        params.emitIfAllowed('llm_call_recovery_continue', {
+            round: params.round,
+            status: terminalError.status,
+            attempt: next,
+            maxAttempts: MAX_RECOVERY_CONTINUATIONS,
+        });
+        return {
+            kind: 'continue',
+            invalidRecoveryContinuations: next,
+        };
+    }
+    handleEmptyOutputRecovery(params) {
+        if (hasUsableResponseOutput(params.sdkResponse, params.roundItems)) {
+            return {
+                kind: 'ok',
+            };
+        }
+        const message = 'LLM response completed with no output items';
+        params.emitIfAllowed('llm_call_failed', {
+            round: params.round,
+            status: 'completed',
+            error: message,
+            recoverable: params.invalidRecoveryContinuations < MAX_RECOVERY_CONTINUATIONS,
+        });
+        if (params.invalidRecoveryContinuations >= MAX_RECOVERY_CONTINUATIONS) {
+            throw new Error(message);
+        }
+        const next = params.invalidRecoveryContinuations + 1;
+        params.emitIfAllowed('llm_call_recovery_continue', {
+            round: params.round,
+            status: 'completed',
+            attempt: next,
+            maxAttempts: MAX_RECOVERY_CONTINUATIONS,
+        });
+        return {
+            kind: 'continue',
+            invalidRecoveryContinuations: next,
+        };
+    }
+    async executeToolRound(params) {
+        const { functionCalls, request, roundItemSchemas, allItems, conversationInput } = params;
+        params.emitIfAllowed('tool_round_started', {
+            round: params.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 (request.signal?.aborted) {
+                break;
+            }
+            await this.executeFunctionCall({
+                fc,
+                request,
+                roundItemSchemas,
+                allItems,
+                conversationInput,
+                emitIfAllowed: params.emitIfAllowed,
+            });
+        }
+        params.emitIfAllowed('tool_round_completed', {
+            round: params.round,
+            toolCount: functionCalls.length,
+        });
+    }
+    async executeFunctionCall(params) {
+        const { fc, request, roundItemSchemas, allItems, conversationInput } = params;
+        params.emitIfAllowed('tool_call_started', {
+            name: fc.name,
+            callId: fc.callId,
+        });
+        let parsedArgs;
+        try {
+            parsedArgs = JSON.parse(fc.arguments);
+        }
+        catch {
+            this.recordMalformedToolCall({
+                fc,
+                request,
+                roundItemSchemas,
+                allItems,
+                conversationInput,
+                emitIfAllowed: params.emitIfAllowed,
+            });
+            return;
+        }
+        if (!request.tools) {
+            throw new Error(`executeFunctionCall invoked without tools on CallModelRequest (tool name: ${fc.name}).`);
+        }
+        const toolForCall = request.tools.find((tool) => tool.name === fc.name || sanitizeToolNameForWire(tool.name) === fc.name);
+        const toolResult = await executeToolCall({
+            toolName: fc.name,
+            args: parsedArgs,
+            tools: request.tools,
+            context: request.ctx,
+            harness: this.opts.harness,
+            layers: request.layers,
+        });
+        const outputItem = createToolResultItem({
+            output: toolResult.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: toolResult.output,
+        });
+        params.emitIfAllowed('tool_call_completed', {
+            name: fc.name,
+            callId: fc.callId,
+            error: false,
+        });
+    }
+    recordMalformedToolCall(params) {
+        const { fc, request, roundItemSchemas, allItems, conversationInput } = params;
+        const errorOutput = `Error: malformed JSON in tool arguments: ${fc.arguments}`;
+        const toolForCall = request.tools?.find((tool) => tool.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,
+        });
+        params.emitIfAllowed('tool_call_completed', {
+            name: fc.name,
+            callId: fc.callId,
+            error: true,
+        });
+    }
+    handleToolRoundLimit(params) {
+        if (params.round < MAX_TOOL_ROUNDS) {
+            return {
+                kind: 'ok',
+            };
+        }
+        params.emitIfAllowed('tool_round_limit_exceeded', {
+            maxToolRounds: MAX_TOOL_ROUNDS,
+            attempt: params.toolLimitRecoveryContinuations + 1,
+            maxAttempts: MAX_RECOVERY_CONTINUATIONS,
+        });
+        if (params.toolLimitRecoveryContinuations >= MAX_RECOVERY_CONTINUATIONS) {
+            throw new Error(`LLM exceeded maximum tool rounds (${MAX_TOOL_ROUNDS})`);
+        }
+        return {
+            kind: 'continue',
+            toolLimitRecoveryContinuations: params.toolLimitRecoveryContinuations + 1,
+        };
+    }
+    /** @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 [];
+        }
+        queue.drainAll();
+        for (const msg of keep) {
+            queue.enqueue(msg);
+        }
+        return toInject;
+    }
+}
+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');
+}

package/dist/harness/model-schema.d.ts

@@ -0,0 +1,19 @@
+import type { ItemSchemaRegistry } from '../schemas/item.js';
+import type { Item } from '../types/items.js';
+import type { MemoryLayer } from '../types/memory.js';
+import type { Tool } from '../types/tool.js';
+export declare function buildItemSchemaRegistry({ base, layers, tools, }: {
+    base: ItemSchemaRegistry;
+    layers?: ReadonlyArray<MemoryLayer>;
+    tools?: ReadonlyArray<Tool>;
+}): ItemSchemaRegistry;
+export declare function createToolResultItem({ output, callId, roundItemSchemas, tool, callItem, args, result, error, }: {
+    output: string;
+    callId: string;
+    roundItemSchemas: ItemSchemaRegistry;
+    tool?: Tool;
+    callItem?: Item;
+    args?: unknown;
+    result?: unknown;
+    error?: boolean;
+}): Item;