@noetic-tools/core 0.2.0 → 0.3.0

package/dist/memory/layers/working-memory.js

@@ -1,92 +0,0 @@
-import { z } from 'zod';
-import { Slot } from '../../types/memory.js';
-import { createMessage, estimateTokens } from '../../util/message-helpers.js';
-import { findFunctionCall } from '../function-call-utils.js';
-import { layerData, layerFn } from '../layer-provides.js';
-function safeMerge(state, args) {
-    const { __proto__: _p, constructor: _c, ...safeArgs } = args;
-    if (typeof state === 'object' && state !== null) {
-        return {
-            ...state,
-            ...safeArgs,
-        };
-    }
-    return safeArgs;
-}
-/**
- * Creates a mutable working memory layer that the model can update via the `working-memory/update` tool.
- *
- * @public
- * @param config - Optional configuration for scope, Zod schema, template, and read-only mode.
- * @returns A `MemoryLayer` providing scratchpad state the model can read and write.
- */
-export function workingMemory(config) {
-    const scope = config?.scope ?? 'thread';
-    return {
-        id: 'working-memory',
-        name: 'Working Memory',
-        slot: Slot.WORKING_MEMORY,
-        scope,
-        budget: {
-            min: 200,
-            max: 1_500,
-        },
-        provides: {
-            snapshot: layerData({
-                read: (state) => state,
-            }),
-            update: layerFn({
-                description: 'Update the agent working memory with new key-value pairs.',
-                input: z.record(z.string(), z.unknown()),
-                output: z.void(),
-                execute: async (args, state) => ({
-                    result: undefined,
-                    state: safeMerge(state, args),
-                }),
-            }),
-        },
-        hooks: {
-            async init({ storage }) {
-                const saved = await storage.get('state');
-                const state = saved ?? (config?.schema ? {} : '');
-                return {
-                    state,
-                };
-            },
-            async recall({ state }) {
-                if (!state || (typeof state === 'object' && Object.keys(state).length === 0)) {
-                    return null;
-                }
-                const text = typeof state === 'string' ? state : JSON.stringify(state, null, 2);
-                const content = `<working_memory>\n${text}\n</working_memory>`;
-                return {
-                    items: [
-                        createMessage(content, 'developer'),
-                    ],
-                    tokenCount: estimateTokens(content),
-                };
-            },
-            async store({ newItems, state }) {
-                if (config?.readOnly) {
-                    return;
-                }
-                // Backward compat: detect implicit updateWorkingMemory calls from LLMs
-                const args = findFunctionCall(newItems, 'updateWorkingMemory');
-                if (!args) {
-                    return;
-                }
-                return {
-                    state: safeMerge(state, args),
-                };
-            },
-            async onSpawn({ parentState }) {
-                if (scope === 'resource') {
-                    return {
-                        childState: structuredClone(parentState),
-                    };
-                }
-                return null;
-            },
-        },
-    };
-}

package/dist/memory/projector.d.ts

@@ -1,10 +0,0 @@
-import type { Item } from '../types/items.js';
-import type { ProjectionPolicy } from '../types/memory.js';
-interface AssembleViewParams {
-    systemPromptItems: Item[];
-    layerOutputItems: Item[];
-    historyItems: Item[];
-    policy?: ProjectionPolicy;
-}
-export declare function assembleView({ systemPromptItems, layerOutputItems, historyItems, policy, }: AssembleViewParams): Item[];
-export {};

package/dist/memory/projector.js

@@ -1,19 +0,0 @@
-//#endregion
-//#region Public API
-export function assembleView({ systemPromptItems, layerOutputItems, historyItems, policy, }) {
-    const view = [];
-    // Add system prompt items
-    view.push(...systemPromptItems);
-    // Add layer output items (sorted by slot already from recall)
-    view.push(...layerOutputItems);
-    // Add history items (with overflow handling if policy specified)
-    if (policy?.overflow === 'sliding_window' && policy.windowSize) {
-        const windowItems = historyItems.slice(-policy.windowSize);
-        view.push(...windowItems);
-    }
-    else {
-        view.push(...historyItems);
-    }
-    return view;
-}
-//#endregion

package/dist/memory/scope.d.ts

@@ -1,3 +0,0 @@
-import type { ExecutionContext, MemoryScope, ScopedStorage, StorageAdapter } from '../types/memory.js';
-export declare function resolveScopeKey(scope: MemoryScope, ctx: ExecutionContext): string;
-export declare function createScopedStorage(storage: StorageAdapter, layerId: string, scopeKey: string): ScopedStorage;

package/dist/memory/scope.js

@@ -1,31 +0,0 @@
-export function resolveScopeKey(scope, ctx) {
-    switch (scope) {
-        case 'thread':
-            return ctx.threadId;
-        case 'resource':
-            return ctx.resourceId ?? ctx.threadId;
-        case 'global':
-            return '__global__';
-        case 'execution':
-            return ctx.executionId;
-    }
-}
-export function createScopedStorage(storage, layerId, scopeKey) {
-    const prefix = `layers/${layerId}/${scopeKey}/`;
-    return {
-        async get(key) {
-            return storage.get(`${prefix}${key}`);
-        },
-        async set(key, value) {
-            return storage.set(`${prefix}${key}`, value);
-        },
-        async delete(key) {
-            return storage.delete(`${prefix}${key}`);
-        },
-        async list(keyPrefix) {
-            const fullPrefix = keyPrefix ? `${prefix}${keyPrefix}` : prefix;
-            const keys = await storage.list(fullPrefix);
-            return keys.map((k) => (k.startsWith(prefix) ? k.slice(prefix.length) : k));
-        },
-    };
-}

package/dist/memory/strip-unresolved.d.ts

@@ -1,13 +0,0 @@
-/**
- * Drop dangling tool-call state from an item list. A `function_call` without a
- * matching `function_call_output` (or vice-versa) wedges the model on the next
- * round (it typically fabricates an output), so we filter both sides of any
- * incomplete pair. Order-preserving and pure — safe to run after a slice.
- *
- * Mirrors Claude Code's `filterUnresolvedToolUses`. Used by the CLI's
- * session-resume path to drop dangling pairs left by a crash, and by the
- * `historyWindow` memory layer to clean orphans at the slice boundary.
- */
-import type { Item } from '../types/items.js';
-/** @public */
-export declare function stripUnresolvedToolCalls(items: ReadonlyArray<Item>): Item[];

package/dist/memory/strip-unresolved.js

@@ -1,35 +0,0 @@
-/**
- * Drop dangling tool-call state from an item list. A `function_call` without a
- * matching `function_call_output` (or vice-versa) wedges the model on the next
- * round (it typically fabricates an output), so we filter both sides of any
- * incomplete pair. Order-preserving and pure — safe to run after a slice.
- *
- * Mirrors Claude Code's `filterUnresolvedToolUses`. Used by the CLI's
- * session-resume path to drop dangling pairs left by a crash, and by the
- * `historyWindow` memory layer to clean orphans at the slice boundary.
- */
-/** @public */
-export function stripUnresolvedToolCalls(items) {
-    const outputCallIds = new Set();
-    const callCallIds = new Set();
-    for (const item of items) {
-        if (item.type === 'function_call_output') {
-            outputCallIds.add(item.callId);
-            continue;
-        }
-        if (item.type === 'function_call') {
-            callCallIds.add(item.callId);
-        }
-    }
-    const keep = [];
-    for (const item of items) {
-        if (item.type === 'function_call' && !outputCallIds.has(item.callId)) {
-            continue;
-        }
-        if (item.type === 'function_call_output' && !callCallIds.has(item.callId)) {
-            continue;
-        }
-        keep.push(item);
-    }
-    return keep;
-}

package/dist/schemas/item.d.ts

@@ -1,35 +0,0 @@
-/**
- * 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.js';
-/** @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

@@ -1,155 +0,0 @@
-/**
- * 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,
-});

package/dist/types/channel.d.ts

@@ -1,29 +0,0 @@
-import type { ZodType } from 'zod';
-/**
- * A typed communication channel between steps within an execution tree.
- * @public
- */
-export interface Channel<T> {
-    /** Channel name for identification and debugging. */
-    readonly name: string;
-    /** Zod schema used to validate every message sent through the channel. */
-    readonly schema: ZodType<T>;
-    /** Delivery semantics: `'value'` (last-write-wins), `'queue'` (FIFO), `'topic'` (pub/sub). */
-    readonly mode: 'value' | 'queue' | 'topic';
-    /** Buffer size for queue mode (default: 1000). Ignored for value/topic modes. */
-    readonly capacity?: number;
-}
-/**
- * A channel that is writable from outside the execution tree (e.g. user input).
- * @public
- */
-export interface ExternalChannel<T> extends Channel<T> {
-    /** Marker indicating the channel accepts writes from external callers. */
-    readonly external: true;
-}
-/** @public Handle for sending messages to a channel and checking its closed state. */
-export interface ChannelHandle<T> {
-    send(value: T): void;
-    readonly closed: boolean;
-    readonly channel: Channel<T>;
-}

package/dist/types/channel.js

@@ -1 +0,0 @@
-export {};

package/dist/types/common.d.ts

@@ -1,68 +0,0 @@
-import type { FunctionCallItem, Item } from './items.js';
-/**
- * Policy controlling automatic retry behavior on step failure.
- * @public
- */
-export interface RetryPolicy {
-    /** Maximum number of execution attempts (including the initial try). */
-    maxAttempts: number;
-    /** Backoff strategy between retries. */
-    backoff: 'fixed' | 'linear' | 'exponential';
-    /** Delay in ms before the first retry. */
-    initialDelay: number;
-    /** Upper bound in ms for the computed delay (caps exponential/linear growth). */
-    maxDelay?: number;
-}
-/**
- * Optional parameters forwarded to the model provider during an LLM step.
- * @public
- */
-export interface ModelParams {
-    /** Sampling temperature (0 = deterministic, higher = more creative). */
-    temperature?: number;
-    /** Nucleus sampling threshold (alternative to temperature). */
-    topP?: number;
-    /** Maximum number of tokens the model may generate. */
-    maxTokens?: number;
-    /** Sequences that cause the model to stop generating. */
-    stopSequences?: string[];
-}
-/** @public Aggregate token counts for an execution (input, output, total, cached). */
-export interface TokenUsage {
-    input: number;
-    output: number;
-    total: number;
-    cached?: number;
-}
-/** @public Metadata captured from the most recent step execution. */
-export interface StepMeta {
-    toolCalls?: FunctionCallItem[];
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        cachedTokens?: number;
-    };
-    cost?: number;
-    responseItems?: ReadonlyArray<Item>;
-}
-/** @public Structured response returned by a model adapter after an LLM call. */
-export interface LLMResponse {
-    items: Item[];
-    usage: {
-        inputTokens: number;
-        outputTokens: number;
-        cachedTokens?: number;
-    };
-    cost?: number;
-}
-/** @public Configuration for the LLM provider used by the agent harness. */
-export interface LlmProviderConfig {
-    provider: 'openrouter';
-    apiKey?: string;
-    /**
-     * When true, sends the `X-OpenRouter-Cache: true` request header on every
-     * model call. OpenRouter then serves identical requests from cache without
-     * re-billing — useful for deterministic re-runs (evals, regression suites).
-     */
-    cache?: boolean;
-}

package/dist/types/common.js

@@ -1 +0,0 @@
-export {};

package/dist/types/context-parts/item-log.d.ts

@@ -1,6 +0,0 @@
-import type { Item } from '../items.js';
-/** @public Append-only log of conversation items accumulated during execution. */
-export interface ItemLog {
-    readonly items: ReadonlyArray<Item>;
-    append(item: Item): void;
-}

package/dist/types/context-parts/item-log.js

@@ -1 +0,0 @@
-export {};

package/dist/types/context-parts/layer-usage.d.ts

@@ -1,18 +0,0 @@
-import type { Item } from '../items.js';
-/** @public Per-layer contribution to the context window on the most recent LLM call. */
-export interface LayerUsageEntry {
-    readonly layerId: string;
-    readonly tokenCount: number;
-    /** Items this layer contributed to the context view for the last LLM call. */
-    readonly items: ReadonlyArray<Item>;
-}
-/** @public Breakdown of the context window as of the most recent LLM call in an execution. */
-export interface LastLayerUsage {
-    readonly executionId: string;
-    readonly modelId: string;
-    readonly layers: ReadonlyArray<LayerUsageEntry>;
-    readonly systemPromptTokens: number;
-    readonly toolsTokens: number;
-    readonly historyTokens: number;
-    readonly totalUsedTokens: number;
-}

package/dist/types/context-parts/layer-usage.js

@@ -1 +0,0 @@
-export {};