@noetic-tools/core 0.0.1

package/dist/runtime/session-runner.js

@@ -0,0 +1,253 @@
+import { emitFrameworkEvent } from './broadcaster-utils';
+import { EventBroadcaster } from './event-broadcaster';
+import { MessageQueue } from './message-queue';
+//#endregion
+//#region Helpers
+function inputToItems(input) {
+    if (typeof input === 'string') {
+        if (input.length === 0) {
+            return [];
+        }
+        const item = {
+            id: `user-${crypto.randomUUID()}`,
+            type: 'message',
+            role: 'user',
+            status: 'completed',
+            content: [
+                {
+                    type: 'input_text',
+                    text: input,
+                },
+            ],
+        };
+        return [
+            item,
+        ];
+    }
+    if (Array.isArray(input)) {
+        return input;
+    }
+    return [
+        input,
+    ];
+}
+function mergeInputsToItems(messages) {
+    const items = [];
+    for (const msg of messages) {
+        items.push(...inputToItems(msg.input));
+    }
+    return items;
+}
+//#endregion
+//#region SessionRunner
+/**
+ * @internal
+ *
+ * Per-thread runner. Drains the MessageQueue and drives turns on the shared
+ * session broadcaster. Emits `turn_started` / `turn_completed` /
+ * `inbox_injected` framework events so consumers can correlate queued
+ * messages with the turn that delivered them.
+ *
+ * Abort semantics: when `abort()` is called, the current AbortController is
+ * fired (cancelling the in-flight LLM call) and a flag is set so the runner
+ * does NOT auto-restart from the queue until the caller re-kicks. For the
+ * ESC-restart UX, callers typically enqueue the new message first, then
+ * abort — the new message is the head of the queue when the runner wakes.
+ */
+export class SessionRunner {
+    threadId;
+    broadcaster = new EventBroadcaster();
+    queue = new MessageQueue();
+    agentName;
+    runTurn;
+    createContext;
+    status = {
+        kind: 'idle',
+    };
+    currentController;
+    currentCtx;
+    loopPromise;
+    lastResponse;
+    lastError;
+    responseWaiters = [];
+    constructor(opts) {
+        this.threadId = opts.threadId;
+        this.agentName = opts.agentName;
+        this.runTurn = opts.runTurn;
+        this.createContext = opts.createContext;
+        this.queue.subscribe(() => {
+            this.kick();
+        });
+    }
+    getStatus() {
+        return this.status;
+    }
+    /** Resolves once the queue has been drained and the runner is idle with a
+     *  response available. If nothing has run yet, waits for the first turn.
+     *
+     *  The cached `lastError` is only surfaced when the session is genuinely
+     *  idle with no pending work. If a new turn is running or a message is
+     *  queued, the caller is asking about the NEXT response — we must wait
+     *  for that turn rather than reject with the stale error. */
+    getAgentResponse() {
+        if (this.status.kind === 'idle' && this.queue.size === 0 && this.lastResponse) {
+            return Promise.resolve(this.lastResponse);
+        }
+        if (this.status.kind === 'idle' && this.queue.size === 0 && this.lastError) {
+            return Promise.reject(this.lastError);
+        }
+        return new Promise((resolve, reject) => {
+            this.responseWaiters.push({
+                resolve,
+                reject,
+            });
+        });
+    }
+    /** Cancel the in-flight turn. Does NOT re-kick — callers that want restart
+     *  behaviour should enqueue a message before/after calling abort. */
+    async abort(reason) {
+        if (this.status.kind !== 'generating') {
+            return;
+        }
+        const turnId = this.status.turnId;
+        this.status = {
+            kind: 'aborting',
+            turnId,
+        };
+        const ctx = this.currentCtx;
+        if (ctx) {
+            ctx.abort(reason);
+        }
+        this.currentController?.abort(reason);
+        await this.loopPromise?.catch(() => {
+            // The abort surfaces as a rejection; we swallow it here because callers
+            // observe it via the broadcaster / lastError, not the abort() return.
+        });
+    }
+    /** Start the drain loop if not already running. Safe to call many times. */
+    kick() {
+        if (this.loopPromise) {
+            return;
+        }
+        if (this.queue.size === 0) {
+            return;
+        }
+        this.loopPromise = this.drain().finally(() => {
+            this.loopPromise = undefined;
+            // If messages arrived during finally, run again.
+            if (this.queue.size > 0) {
+                this.kick();
+            }
+        });
+    }
+    async drain() {
+        while (this.queue.size > 0) {
+            const messages = this.queue.drainAll();
+            if (messages.length === 0) {
+                break;
+            }
+            await this.runOneTurn(messages);
+        }
+    }
+    async runOneTurn(messages) {
+        const turnId = crypto.randomUUID();
+        const startedAt = Date.now();
+        this.status = {
+            kind: 'generating',
+            startedAt,
+            turnId,
+        };
+        const controller = new AbortController();
+        this.currentController = controller;
+        // The runner is the single point of ExecuteInput → Item[] conversion —
+        // the harness's createContext callback receives Item[] directly and
+        // seeds the context without re-converting.
+        const items = mergeInputsToItems(messages);
+        const ctx = this.createContext(items, turnId, messages);
+        this.currentCtx = ctx;
+        emitFrameworkEvent({
+            broadcaster: this.broadcaster,
+            agentName: this.agentName,
+            eventType: 'turn_started',
+            data: {
+                turnId,
+                messageIds: messages.map((m) => m.id),
+            },
+        });
+        const turn = {
+            turnId,
+            session: this,
+        };
+        try {
+            const text = await this.runTurn(ctx, turn, controller.signal);
+            const response = buildResponse(text, ctx);
+            this.lastResponse = response;
+            this.lastError = undefined;
+            emitFrameworkEvent({
+                broadcaster: this.broadcaster,
+                agentName: this.agentName,
+                eventType: 'turn_completed',
+                data: {
+                    turnId,
+                    durationMs: Date.now() - startedAt,
+                },
+            });
+            // Only resolve waiters when the queue is fully drained; otherwise let
+            // the next turn's completion surface the final response. This matches
+            // `getAgentResponse`'s contract: "once the session has finished
+            // processing its queue".
+            if (this.queue.size === 0) {
+                this.resolveWaiters(response);
+            }
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.lastError = error;
+            emitFrameworkEvent({
+                broadcaster: this.broadcaster,
+                agentName: this.agentName,
+                eventType: 'turn_aborted',
+                data: {
+                    turnId,
+                    reason: error.message,
+                },
+            });
+            this.rejectWaiters(error);
+        }
+        finally {
+            this.currentCtx = undefined;
+            this.currentController = undefined;
+            this.status = {
+                kind: 'idle',
+            };
+        }
+    }
+    resolveWaiters(response) {
+        const pending = this.responseWaiters.splice(0, this.responseWaiters.length);
+        for (const w of pending) {
+            w.resolve(response);
+        }
+    }
+    rejectWaiters(err) {
+        const pending = this.responseWaiters.splice(0, this.responseWaiters.length);
+        for (const w of pending) {
+            w.reject(err);
+        }
+    }
+}
+//#endregion
+//#region buildResponse
+function buildResponse(text, ctx) {
+    return {
+        items: ctx.itemLog.items,
+        usage: {
+            inputTokens: ctx.tokens.input,
+            outputTokens: ctx.tokens.output,
+            cachedTokens: ctx.tokens.cached && ctx.tokens.cached > 0 ? ctx.tokens.cached : undefined,
+        },
+        cost: ctx.cost > 0 ? ctx.cost : undefined,
+        text,
+        lastLayerUsage: ctx.lastLayerUsage,
+    };
+}
+//#endregion

package/dist/runtime/session-streams.d.ts

@@ -0,0 +1,11 @@
+import type { ItemSchemaRegistry } from '../schemas/item';
+import type { StreamingItem } from '../types/harness-result';
+import type { EventBroadcaster } from './event-broadcaster';
+/** @internal Yield text deltas from the session broadcaster. */
+export declare function filterTextStream(broadcaster: EventBroadcaster): AsyncIterable<string>;
+/** @internal Yield reasoning-token deltas from the session broadcaster. */
+export declare function filterReasoningStream(broadcaster: EventBroadcaster): AsyncIterable<string>;
+/** @internal Yield cumulative StreamingItem snapshots. Uses roundOffset keyed by
+ *  response.created so accumulators across multiple tool rounds and across
+ *  multiple turns within a session don't collide. */
+export declare function buildItemStream(broadcaster: EventBroadcaster, itemSchemas?: ItemSchemaRegistry): AsyncIterable<StreamingItem>;

package/dist/runtime/session-streams.js

@@ -0,0 +1,204 @@
+import { defaultItemSchemaRegistry } from '../schemas/item';
+//#endregion
+//#region Helpers
+function isItemRecord(value) {
+    return typeof value === 'object' && value !== null && 'type' in value;
+}
+function appendText(part, delta) {
+    Object.assign(part, {
+        text: part.text + delta,
+    });
+}
+function createAccumulatorFromItemAdded(event, itemSchemas) {
+    if (event.source !== 'sdk' || event.type !== 'response.output_item.added') {
+        return null;
+    }
+    if (!isItemRecord(event.data.item)) {
+        return null;
+    }
+    const itemData = event.data.item;
+    const id = typeof itemData.id === 'string' ? itemData.id : crypto.randomUUID();
+    if (itemData.type === 'message') {
+        return {
+            id,
+            item: {
+                id,
+                type: 'message',
+                role: 'assistant',
+                status: 'in_progress',
+                content: [
+                    {
+                        type: 'output_text',
+                        text: '',
+                    },
+                ],
+            },
+            isComplete: false,
+        };
+    }
+    if (itemData.type === 'function_call') {
+        const parsed = itemSchemas.parse(itemData);
+        return {
+            id,
+            item: {
+                ...parsed,
+                id,
+                type: 'function_call',
+                status: 'in_progress',
+                callId: typeof itemData.callId === 'string' ? itemData.callId : '',
+                name: typeof itemData.name === 'string' ? itemData.name : '',
+                arguments: '',
+            },
+            isComplete: false,
+        };
+    }
+    const parsed = itemSchemas.parse(itemData);
+    return {
+        id,
+        item: parsed,
+        isComplete: false,
+    };
+}
+function updateMessageAccumulator(acc, event) {
+    if (event.source !== 'sdk') {
+        return;
+    }
+    if (event.type === 'response.output_text.delta' && typeof event.data.delta === 'string') {
+        const msg = acc.item;
+        if (msg.type !== 'message' || !('content' in msg)) {
+            return;
+        }
+        const lastPart = msg.content[msg.content.length - 1];
+        if (lastPart && 'text' in lastPart && typeof lastPart.text === 'string') {
+            appendText(lastPart, event.data.delta);
+        }
+    }
+    if (event.type === 'response.output_text.done') {
+        acc.isComplete = true;
+    }
+}
+function updateFunctionCallAccumulator(acc, event) {
+    if (event.source !== 'sdk') {
+        return;
+    }
+    if (event.type === 'response.function_call_arguments.delta' &&
+        typeof event.data.delta === 'string') {
+        const fc = acc.item;
+        if (fc.type !== 'function_call' || !('arguments' in fc) || typeof fc.arguments !== 'string') {
+            return;
+        }
+        fc.arguments += event.data.delta;
+    }
+    if (event.type === 'response.function_call_arguments.done') {
+        acc.isComplete = true;
+    }
+}
+/** Compute a composite key from round offset and output index to avoid collisions across tool rounds. */
+function accumulatorKey(roundOffset, outputIndex) {
+    return `${roundOffset}:${outputIndex}`;
+}
+function completeStreamingItem(item) {
+    if ('status' in item) {
+        return {
+            ...item,
+            status: 'completed',
+            isComplete: true,
+        };
+    }
+    return {
+        ...item,
+        isComplete: true,
+    };
+}
+//#endregion
+//#region Public stream filters
+/** @internal Yield text deltas from the session broadcaster. */
+export async function* filterTextStream(broadcaster) {
+    for await (const event of broadcaster) {
+        if (event.source !== 'sdk' || event.type !== 'response.output_text.delta') {
+            continue;
+        }
+        const delta = event.data.delta;
+        if (typeof delta === 'string') {
+            yield delta;
+        }
+    }
+}
+/** @internal Yield reasoning-token deltas from the session broadcaster. */
+export async function* filterReasoningStream(broadcaster) {
+    for await (const event of broadcaster) {
+        if (event.source !== 'sdk' || event.type !== 'response.reasoning.delta') {
+            continue;
+        }
+        const delta = event.data.delta;
+        if (typeof delta === 'string') {
+            yield delta;
+        }
+    }
+}
+/** @internal Yield cumulative StreamingItem snapshots. Uses roundOffset keyed by
+ *  response.created so accumulators across multiple tool rounds and across
+ *  multiple turns within a session don't collide. */
+export async function* buildItemStream(broadcaster, itemSchemas = defaultItemSchemaRegistry) {
+    const accumulators = new Map();
+    let roundOffset = 0;
+    for await (const event of broadcaster) {
+        if (event.source !== 'sdk') {
+            continue;
+        }
+        if (event.type === 'response.created') {
+            roundOffset++;
+            continue;
+        }
+        if (event.type === 'response.output_item.added') {
+            const outputIndex = typeof event.outputIndex === 'number' ? event.outputIndex : accumulators.size;
+            const key = accumulatorKey(roundOffset, outputIndex);
+            const acc = createAccumulatorFromItemAdded(event, itemSchemas);
+            if (acc) {
+                accumulators.set(key, acc);
+                yield {
+                    ...acc.item,
+                    isComplete: false,
+                };
+            }
+            continue;
+        }
+        if (event.type === 'response.output_item.done') {
+            const outputIndex = typeof event.outputIndex === 'number' ? event.outputIndex : -1;
+            const key = accumulatorKey(roundOffset, outputIndex);
+            const acc = accumulators.get(key);
+            if (acc) {
+                acc.isComplete = true;
+                yield completeStreamingItem(acc.item);
+            }
+            continue;
+        }
+        if (event.type === 'response.output_text.delta' || event.type === 'response.output_text.done') {
+            const outputIndex = typeof event.outputIndex === 'number' ? event.outputIndex : 0;
+            const key = accumulatorKey(roundOffset, outputIndex);
+            const acc = accumulators.get(key);
+            if (acc) {
+                updateMessageAccumulator(acc, event);
+                yield {
+                    ...acc.item,
+                    isComplete: acc.isComplete,
+                };
+            }
+            continue;
+        }
+        if (event.type === 'response.function_call_arguments.delta' ||
+            event.type === 'response.function_call_arguments.done') {
+            const outputIndex = typeof event.outputIndex === 'number' ? event.outputIndex : 0;
+            const key = accumulatorKey(roundOffset, outputIndex);
+            const acc = accumulators.get(key);
+            if (acc) {
+                updateFunctionCallAccumulator(acc, event);
+                yield {
+                    ...acc.item,
+                    isComplete: acc.isComplete,
+                };
+            }
+        }
+    }
+}
+//#endregion

package/dist/runtime/tool-memory.d.ts

@@ -0,0 +1,6 @@
+import type { TurnContext } from '@openrouter/agent';
+import type { Context } from '../types/context';
+import type { AgentHarnessContract } from '../types/runtime';
+import type { ToolExecutionContext, ToolMemory } from '../types/tool-context';
+export declare function buildToolMemory(harness: AgentHarnessContract, ctx: Context): ToolMemory;
+export declare function buildToolExecutionContext(ctx: Context, harness: AgentHarnessContract, turnContext?: TurnContext): ToolExecutionContext;

package/dist/runtime/tool-memory.js

@@ -0,0 +1,22 @@
+export function buildToolMemory(harness, ctx) {
+    return {
+        get(layerId) {
+            return harness.getLayerState(ctx.id, layerId);
+        },
+        set(layerId, state) {
+            harness.setLayerState(ctx.id, layerId, state);
+        },
+    };
+}
+export function buildToolExecutionContext(ctx, harness, turnContext) {
+    return {
+        ctx,
+        harness,
+        fs: harness.fs,
+        shell: harness.shell,
+        memory: buildToolMemory(harness, ctx),
+        assembledView: ctx.itemLog.items,
+        lastStepMeta: ctx.lastStepMeta,
+        turnContext,
+    };
+}

package/dist/schemas/item.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Runtime schema for the `Item` union.
+ *
+ * The `Item` type is a discriminated union of framework-created items
+ * (`InputMessageItem`, `FunctionCallOutputItem`) and provider-shaped items
+ * from `@openrouter/agent` whose shapes are defined by the SDK's generated
+ * types. Mirroring those provider shapes as Zod schemas would drift as the
+ * SDK evolves, so the runtime schema validates only the structural invariant
+ * every `Item` shares: an object with a non-empty string `type` discriminant.
+ *
+ * Use this at trust boundaries (loading persisted session files, accepting
+ * externally-supplied transcripts) where we need to reject garbage JSON but
+ * don't need to re-validate every provider field TypeScript already types.
+ */
+import { z } from 'zod';
+import type { Item, ItemSchemaExtensions } from '../types/items';
+/** @public Structural validator for `Item`. Asserts non-empty string `type` discriminant. */
+export declare const ItemSchema: z.ZodCustom<Item, Item>;
+type ItemSchemaCategory = keyof Required<ItemSchemaExtensions>;
+export declare function mergeExtensions(a: ItemSchemaExtensions | undefined, b: ItemSchemaExtensions | undefined): ItemSchemaExtensions;
+/** @public Runtime item validator with optional tool, memory-layer, and harness extension schemas. */
+export declare class ItemSchemaRegistry {
+    readonly extensions: ItemSchemaExtensions;
+    readonly strictUnknownExtensions: boolean;
+    constructor(extensions?: ItemSchemaExtensions, opts?: {
+        strictUnknownExtensions?: boolean;
+    });
+    extend(extensions?: ItemSchemaExtensions): ItemSchemaRegistry;
+    parse(value: unknown): Item;
+    parseMany(values: Iterable<unknown>): Item[];
+    parseWithCategory(value: unknown, category: ItemSchemaCategory): Item;
+}
+/** @public Default item schema registry. */
+export declare const defaultItemSchemaRegistry: ItemSchemaRegistry;
+export {};

package/dist/schemas/item.js

@@ -0,0 +1,155 @@
+/**
+ * Runtime schema for the `Item` union.
+ *
+ * The `Item` type is a discriminated union of framework-created items
+ * (`InputMessageItem`, `FunctionCallOutputItem`) and provider-shaped items
+ * from `@openrouter/agent` whose shapes are defined by the SDK's generated
+ * types. Mirroring those provider shapes as Zod schemas would drift as the
+ * SDK evolves, so the runtime schema validates only the structural invariant
+ * every `Item` shares: an object with a non-empty string `type` discriminant.
+ *
+ * Use this at trust boundaries (loading persisted session files, accepting
+ * externally-supplied transcripts) where we need to reject garbage JSON but
+ * don't need to re-validate every provider field TypeScript already types.
+ */
+import { z } from 'zod';
+function isItemLike(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if (!('type' in value)) {
+        return false;
+    }
+    const { type } = value;
+    return typeof type === 'string' && type.length > 0;
+}
+/** @public Structural validator for `Item`. Asserts non-empty string `type` discriminant. */
+export const ItemSchema = z.custom(isItemLike, {
+    message: 'Expected an Item object with a non-empty string "type" discriminant.',
+});
+function hasSchemas(extensions) {
+    return Boolean(extensions.items?.length ||
+        extensions.developerMessages?.length ||
+        extensions.toolCalls?.length ||
+        extensions.toolResults?.length);
+}
+export function mergeExtensions(a, b) {
+    return {
+        items: [
+            ...(a?.items ?? []),
+            ...(b?.items ?? []),
+        ],
+        developerMessages: [
+            ...(a?.developerMessages ?? []),
+            ...(b?.developerMessages ?? []),
+        ],
+        toolCalls: [
+            ...(a?.toolCalls ?? []),
+            ...(b?.toolCalls ?? []),
+        ],
+        toolResults: [
+            ...(a?.toolResults ?? []),
+            ...(b?.toolResults ?? []),
+        ],
+    };
+}
+function schemasForCategory(extensions, category) {
+    return extensions[category] ?? [];
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function relevantCategories(value) {
+    const categories = [
+        'items',
+    ];
+    if (isRecord(value) && value.type === 'message' && value.role === 'developer') {
+        categories.push('developerMessages');
+    }
+    if (isRecord(value) && value.type === 'function_call') {
+        categories.push('toolCalls');
+    }
+    if (isRecord(value) && value.type === 'function_call_output') {
+        categories.push('toolResults');
+    }
+    return categories;
+}
+function isKnownBaseType(type) {
+    return (type === 'message' ||
+        type === 'function_call' ||
+        type === 'function_call_output' ||
+        type === 'reasoning' ||
+        type === 'web_search_call' ||
+        type === 'file_search_call' ||
+        type === 'image_generation_call' ||
+        type.startsWith('openrouter:'));
+}
+function schemaMismatch(category) {
+    return new z.ZodError([
+        {
+            code: 'custom',
+            message: `Item did not match any registered ${category} extension schema.`,
+            path: [],
+        },
+    ]);
+}
+/** @public Runtime item validator with optional tool, memory-layer, and harness extension schemas. */
+export class ItemSchemaRegistry {
+    extensions;
+    strictUnknownExtensions;
+    constructor(extensions, opts) {
+        this.extensions = mergeExtensions(undefined, extensions);
+        this.strictUnknownExtensions = opts?.strictUnknownExtensions ?? true;
+    }
+    extend(extensions) {
+        if (!extensions || !hasSchemas(extensions)) {
+            return this;
+        }
+        return new ItemSchemaRegistry(mergeExtensions(this.extensions, extensions), {
+            strictUnknownExtensions: this.strictUnknownExtensions,
+        });
+    }
+    parse(value) {
+        const base = ItemSchema.parse(value);
+        const categories = relevantCategories(base);
+        const schemas = categories.flatMap((category) => schemasForCategory(this.extensions, category));
+        for (const schema of schemas) {
+            const parsed = schema.safeParse(value);
+            if (parsed.success) {
+                return ItemSchema.parse(parsed.data);
+            }
+        }
+        if (this.strictUnknownExtensions && !isKnownBaseType(base.type)) {
+            throw new z.ZodError([
+                {
+                    code: 'custom',
+                    message: `Item type '${base.type}' did not match any registered item extension schema.`,
+                    path: [
+                        'type',
+                    ],
+                },
+            ]);
+        }
+        return base;
+    }
+    parseMany(values) {
+        return Array.from(values, (value) => this.parse(value));
+    }
+    parseWithCategory(value, category) {
+        const schemas = schemasForCategory(this.extensions, category);
+        if (schemas.length === 0) {
+            return this.parse(value);
+        }
+        for (const schema of schemas) {
+            const parsed = schema.safeParse(value);
+            if (parsed.success) {
+                return ItemSchema.parse(parsed.data);
+            }
+        }
+        throw schemaMismatch(category);
+    }
+}
+/** @public Default item schema registry. */
+export const defaultItemSchemaRegistry = new ItemSchemaRegistry(undefined, {
+    strictUnknownExtensions: true,
+});