@noetic-tools/core 0.0.1

package/dist/types/channel.d.ts

@@ -0,0 +1,29 @@
+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

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

package/dist/types/common.d.ts

@@ -0,0 +1,111 @@
+import type { ZodTypeAny, z } from 'zod';
+import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, ToolResultExtensionItem } from './items';
+import type { ToolExecutionContext } from './tool-context';
+type ToolExecutionResult<O extends ZodTypeAny> = Promise<z.infer<O>> | AsyncGenerator<unknown, z.infer<O>>;
+/**
+ * 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[];
+}
+/**
+ * Declares tool-owned memory that the runtime materializes into a MemoryLayer.
+ * @public
+ */
+export interface ToolMemoryDeclaration<TState = unknown> {
+    /** Shared id — tools with the same id share state. Defaults to `tool.name`. */
+    id?: string;
+    /** Factory for the initial state. */
+    init: () => TState;
+    /** Project state into the LLM context. Return null to omit. */
+    recall: (state: TState) => string | null;
+}
+/**
+ * A tool definition that an LLM can invoke during execution.
+ * @public
+ */
+export interface Tool<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny = ZodTypeAny> {
+    /** Unique tool name used by the LLM for selection. */
+    name: string;
+    /** Human-readable description shown to the LLM. */
+    description: string;
+    /** Zod schema validating tool input arguments. */
+    input: I;
+    /** Zod schema validating tool return value. */
+    output: O;
+    /** Optional Zod schema validating streaming events yielded during execution. */
+    event?: ZodTypeAny;
+    /** Optional item schemas contributed by this tool for tool call/result extensions. */
+    itemSchemas?: Pick<ItemSchemaExtensions, 'toolCalls' | 'toolResults' | 'items'>;
+    /** Decorate the harness-created tool result item before it is appended/emitted. */
+    decorateResultItem?(params: {
+        baseItem: FunctionCallOutputItem;
+        callItem: FunctionCallItem;
+        args: z.infer<I>;
+        result: z.infer<O> | undefined;
+        output: string;
+        error?: boolean;
+    }): Item | ToolResultExtensionItem;
+    /** Async function that performs the tool's work. */
+    execute(args: z.infer<I>, toolCtx: ToolExecutionContext): ToolExecutionResult<O>;
+    /** When true, execution pauses for human approval before running. */
+    needsApproval?: boolean;
+    /** Optional memory declaration — the runtime generates a MemoryLayer from this. */
+    memory?: ToolMemoryDeclaration;
+}
+/** @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;
+}
+export {};

package/dist/types/common.js

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

package/dist/types/context.d.ts

@@ -0,0 +1,93 @@
+import type { ItemSchemaRegistry } from '../schemas/item';
+import type { Channel } from './channel';
+import type { StepMeta, TokenUsage, Tool } from './common';
+import type { FsAdapter } from './fs-adapter';
+import type { Item } from './items';
+import type { ContextMemory, MemoryLayer } from './memory';
+import type { Span } from './observability';
+import type { AgentHarnessContract } from './runtime';
+import type { ShellAdapter } from './shell-adapter';
+import type { SubprocessAdapter } from './subprocess-adapter';
+/** @public Append-only log of conversation items accumulated during execution. */
+export interface ItemLog {
+    readonly items: ReadonlyArray<Item>;
+    append(item: Item): void;
+}
+/**
+ * @public Mutable working-directory state shared among the tools attached to a
+ * single Context. The reference is fixed for the Context's lifetime; mutate
+ * via `setToolCwd` so that all tools observe the new value at execution time.
+ *
+ * Spawned children receive a snapshot — child mutations do not affect the parent.
+ */
+export interface CwdState {
+    cwd: string;
+    previousCwd?: string;
+}
+/** @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;
+}
+/** @public Execution context threaded through every step, carrying state, metrics, and channels. */
+export interface Context<TMemory = ContextMemory, TState = unknown> {
+    readonly id: string;
+    readonly stepCount: number;
+    readonly tokens: TokenUsage;
+    readonly elapsed: number;
+    readonly cost: number;
+    state: TState;
+    readonly parent: Context<ContextMemory> | null;
+    readonly depth: number;
+    readonly span: Span;
+    readonly threadId: string;
+    readonly resourceId?: string;
+    readonly itemLog: ItemLog;
+    readonly lastStepMeta: StepMeta | null;
+    /** Per-layer breakdown of the context window as of the most recent callModel. Undefined until the first LLM call completes. */
+    readonly lastLayerUsage?: LastLayerUsage;
+    readonly harness: AgentHarnessContract;
+    /** Filesystem adapter for virtual or real filesystem access. */
+    readonly fs: FsAdapter;
+    /** Shell adapter for virtual or real shell command execution. */
+    readonly shell: ShellAdapter;
+    /** Subprocess adapter for virtual, same-process, or host process execution. */
+    readonly subprocess: SubprocessAdapter;
+    /**
+     * Mutable cwd state shared with the tools bound to this context. Tools
+     * resolve relative paths from `cwdState.cwd` at execution time so that an
+     * agent `cd` propagates to subsequent tool calls.
+     */
+    readonly cwdState: CwdState;
+    readonly layers?: MemoryLayer[];
+    /** Layer provides keyed by layer ID. Access data/functions via `ctx.memory['layerId'].prop`. */
+    readonly memory: TMemory;
+    /** Unified tool set collected from all LLM steps in the step tree before execution. */
+    readonly unifiedTools?: ReadonlyArray<Tool>;
+    /** Runtime item schema registry active for this context. */
+    readonly itemSchemas?: ItemSchemaRegistry;
+    recv<T>(channel: Channel<T>, opts?: {
+        timeout?: number;
+    }): Promise<T>;
+    send<T>(channel: Channel<T>, value: T): void;
+    tryRecv<T>(channel: Channel<T>): T | null;
+    checkpoint(): Promise<void>;
+    complete<T>(value: T): void;
+    readonly completed: boolean;
+    readonly completionValue: unknown;
+    readonly aborted: boolean;
+    readonly abortReason?: string;
+    abort(reason?: string): void;
+}

package/dist/types/context.js

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

package/dist/types/detached.d.ts

@@ -0,0 +1,17 @@
+/** @public Lifecycle states for a detached (background) execution. */
+declare const DetachedStatus: {
+    readonly Running: "running";
+    readonly Completed: "completed";
+    readonly Failed: "failed";
+};
+type DetachedStatus = (typeof DetachedStatus)[keyof typeof DetachedStatus];
+/** @public Handle returned by `detachedSpawn`, used to poll or await a background execution. */
+interface DetachedHandle<O> {
+    readonly id: string;
+    readonly status: DetachedStatus;
+    readonly result: O | undefined;
+    readonly error: string | undefined;
+    await(timeout?: number): Promise<O>;
+}
+export type { DetachedHandle };
+export { DetachedStatus };

package/dist/types/detached.js

@@ -0,0 +1,7 @@
+/** @public Lifecycle states for a detached (background) execution. */
+const DetachedStatus = {
+    Running: 'running',
+    Completed: 'completed',
+    Failed: 'failed',
+};
+export { DetachedStatus };

package/dist/types/embed.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Batch embedding function — maps N texts to N vectors.
+ * @public
+ */
+export type EmbedFn = (texts: readonly string[]) => Promise<readonly number[][]>;

package/dist/types/embed.js

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

package/dist/types/error.d.ts

@@ -0,0 +1,51 @@
+import type { ZodError, ZodType } from 'zod';
+/** @public Discriminated union of all structured error kinds raised by the runtime. */
+export type NoeticError = {
+    kind: 'step_failed';
+    stepId: string;
+    cause: Error;
+    retriesExhausted: boolean;
+} | {
+    kind: 'llm_refused';
+    stepId: string;
+    refusal: string;
+} | {
+    kind: 'llm_parse_error';
+    stepId: string;
+    raw: string;
+    schema: ZodType;
+    zodError: ZodError;
+} | {
+    kind: 'llm_rate_limit';
+    stepId: string;
+    retryAfter?: number;
+} | {
+    kind: 'fork_partial';
+    stepId: string;
+    succeeded: Array<{
+        stepId: string;
+        value: unknown;
+    }>;
+    failed: Array<{
+        stepId: string;
+        error: NoeticError;
+    }>;
+} | {
+    kind: 'channel_timeout';
+    channelName: string;
+    timeout: number;
+} | {
+    kind: 'channel_closed';
+    channelName: string;
+} | {
+    kind: 'cancelled';
+    reason?: string;
+} | {
+    kind: 'budget_exceeded';
+    field: 'cost' | 'steps' | 'duration';
+    limit: number;
+    actual: number;
+} | {
+    kind: 'steering_denied';
+    guidance?: string;
+};

package/dist/types/error.js

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

package/dist/types/fs-adapter.d.ts

@@ -0,0 +1,51 @@
+/** @public Minimal stat result returned by the filesystem adapter. */
+export interface FsStats {
+    size: number;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    isFile(): boolean;
+}
+/** @public Filesystem abstraction for agent runtime operations. */
+export interface FsAdapter {
+    /** Read file contents as a Buffer. */
+    readFile(path: string): Promise<Buffer>;
+    /** Read file contents as a UTF-8 string. */
+    readFileText(path: string): Promise<string>;
+    /** Write string content to a file (UTF-8). */
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Write raw bytes to a file. Use this when content may not be valid
+     * UTF-8 (binary attachments, images, etc.). Round-tripping through
+     * `writeFile` corrupts non-UTF-8 sequences.
+     */
+    writeFileBytes(path: string, content: Buffer): Promise<void>;
+    /**
+     * Append string content to a file (UTF-8). Creates the file if it does
+     * not exist. On POSIX, the underlying write uses `O_APPEND`, which is
+     * atomic for sub-`PIPE_BUF` writes — multiple concurrent writers can
+     * append without interleaving as long as each call's payload stays
+     * under that ceiling (4 KiB on Linux/macOS).
+     */
+    appendFile(path: string, content: string): Promise<void>;
+    /** Create directories recursively. */
+    mkdir(dir: string): Promise<void>;
+    /**
+     * Atomically rename a file or directory. On POSIX, this is the atomic
+     * swap used by write-temp + rename to publish a new file version
+     * without exposing readers to a half-written state.
+     */
+    rename(oldPath: string, newPath: string): Promise<void>;
+    /** Remove a file or directory. With `recursive: true`, removes a directory tree. */
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    /** Check file accessibility (throws on failure). */
+    access(path: string, mode?: number): Promise<void>;
+    /** Get file/directory stats (follows symlinks). */
+    stat(path: string): Promise<FsStats>;
+    /** Get file/directory stats (does NOT follow symlinks). */
+    lstat(path: string): Promise<FsStats>;
+    /** Read directory entries (file names). */
+    readdir(path: string): Promise<string[]>;
+}

package/dist/types/fs-adapter.js

@@ -0,0 +1,3 @@
+//#region Types
+export {};
+//#endregion

package/dist/types/harness-result.d.ts

@@ -0,0 +1,43 @@
+import type { LastLayerUsage } from './context';
+import type { Item } from './items';
+/** @public SDK-originated event from the OpenResponses streaming API. */
+export interface SdkStreamEvent {
+    readonly source: 'sdk';
+    /** OpenResponses SSE event type string (e.g., 'response.output_text.delta'). */
+    readonly type: string;
+    readonly data: Record<string, unknown>;
+    readonly outputIndex?: number;
+    readonly contentIndex?: number;
+}
+/** @public Framework-originated event, prefixed with the harness config.name. */
+export interface FrameworkStreamEvent {
+    readonly source: 'framework';
+    /** Prefixed event type (e.g., 'myagent:step_started'). */
+    readonly type: `${string}:${string}`;
+    readonly data: Record<string, unknown>;
+}
+/** @public Union of all stream event types emitted during execution. */
+export type StreamEvent = SdkStreamEvent | FrameworkStreamEvent;
+/** @public Final accumulated result of an execution, including all items, usage, cost, and extracted text.
+ *
+ *  Returned from `AgentHarness.getAgentResponse()`. Resolves once the session's
+ *  message queue drains and the runner goes idle. When multiple turns run in a
+ *  burst (e.g. queued inbox messages), the response covers the span from the
+ *  last-idle point through the point at which idle is reached again.
+ */
+export interface HarnessResponse {
+    readonly items: ReadonlyArray<Item>;
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly cachedTokens?: number;
+    };
+    readonly cost?: number;
+    readonly text: string;
+    /** Per-memory-layer context window breakdown captured at the last callModel of this execution. */
+    readonly lastLayerUsage?: LastLayerUsage;
+}
+/** @public An Item snapshot with a completion flag, emitted from getItemStream(). */
+export type StreamingItem = Item & {
+    readonly isComplete: boolean;
+};

package/dist/types/harness-result.js

@@ -0,0 +1,2 @@
+export {};
+//#endregion

package/dist/types/items.d.ts

@@ -0,0 +1,115 @@
+import type * as OpenRouterAgent from '@openrouter/agent';
+import type { ZodTypeAny, z } from 'zod';
+type ResponseOutputText = OpenRouterAgent.ResponseOutputText;
+type ResponsesImageGenerationCall = OpenRouterAgent.OutputImageGenerationCallItem;
+type ResponsesOutputItemFileSearchCall = OpenRouterAgent.OutputFileSearchCallItem;
+type ResponsesOutputItemFunctionCall = OpenRouterAgent.OutputFunctionCallItem;
+type ResponsesOutputItemReasoning = OpenRouterAgent.OutputReasoningItem;
+type ResponsesOutputMessage = OpenRouterAgent.OutputMessage;
+type ResponsesWebSearchCallOutput = OpenRouterAgent.OutputWebSearchCallItem;
+type ResponsesServerToolOutput = Exclude<OpenRouterAgent.OpenResponsesResult['output'][number], OpenRouterAgent.OutputMessage | OpenRouterAgent.OutputFunctionCallItem | OpenRouterAgent.OutputReasoningItem | OpenRouterAgent.OutputWebSearchCallItem | OpenRouterAgent.OutputFileSearchCallItem | OpenRouterAgent.OutputImageGenerationCallItem>;
+type OutputMessageContentPart = OpenRouterAgent.OutputMessage['content'][number];
+type OpenAIResponsesRefusalContent = Extract<OutputMessageContentPart, {
+    type: 'refusal';
+}>;
+type ReasoningContentPart = NonNullable<OpenRouterAgent.OutputReasoningItem['content']>[number];
+type SummaryContentPart = NonNullable<OpenRouterAgent.OutputReasoningItem['summary']>[number];
+type ReasoningTextContent = Extract<ReasoningContentPart, {
+    type: 'reasoning_text';
+}>;
+type ReasoningSummaryText = Extract<SummaryContentPart, {
+    type: 'summary_text';
+}>;
+/** @public Model-generated text content with optional annotations and logprobs. */
+export type OutputTextPart = ResponseOutputText;
+/** @public Model refusal content. */
+export type RefusalPart = OpenAIResponsesRefusalContent;
+/** @public User/developer input text (framework-created, not from SDK). */
+export interface InputTextPart {
+    readonly type: 'input_text';
+    readonly text: string;
+}
+/** @public Reasoning trace content. */
+export type ReasoningTextPart = ReasoningTextContent;
+/** @public Reasoning summary content. */
+export type SummaryTextPart = ReasoningSummaryText;
+/** @public Content part variants for message items. */
+export type ContentPart = OutputTextPart | RefusalPart | InputTextPart;
+/** @public Assistant message output item. */
+export type MessageItem = ResponsesOutputMessage;
+/** @public Function call requested by the model. */
+export type FunctionCallItem = ResponsesOutputItemFunctionCall;
+/** @public Reasoning trace from the model. */
+export type ReasoningItem = ResponsesOutputItemReasoning;
+/** @public Web search call result. */
+export type WebSearchItem = ResponsesWebSearchCallOutput;
+/** @public File search call result. */
+export type FileSearchItem = ResponsesOutputItemFileSearchCall;
+/** @public Image generation call result. */
+export type ImageGenerationItem = ResponsesImageGenerationCall;
+/**
+ * @public Server tool output (vendor-prefixed type like `openrouter:datetime`).
+ * Constrains provider output items to the vendor-prefixed subset so discriminant narrowing works in Item unions.
+ */
+export type ServerToolItem = Omit<ResponsesServerToolOutput, 'type'> & {
+    readonly type: `${string}:${string}`;
+};
+/** @public Base shape required for framework and extension items. */
+export interface ItemBase {
+    readonly type: string;
+}
+/**
+ * @public Input message created by the framework (user, system, or developer role).
+ * Status includes `failed` as a Noetic extension beyond the Open Responses spec
+ * (which only defines `in_progress | completed | incomplete` for items).
+ */
+export interface InputMessageItem {
+    readonly id: string;
+    readonly type: 'message';
+    readonly role: 'user' | 'system' | 'developer';
+    readonly status: 'in_progress' | 'completed' | 'incomplete' | 'failed';
+    readonly content: InputTextPart[];
+}
+/**
+ * @public Tool execution output created by the harness during the tool loop.
+ * This is an input-only item type in Open Responses (sent by the developer, not the model).
+ */
+export interface FunctionCallOutputItem {
+    readonly id: string;
+    readonly type: 'function_call_output';
+    readonly status: 'in_progress' | 'completed' | 'incomplete' | 'failed';
+    readonly callId: string;
+    readonly output: string;
+}
+/** @public Item produced by an extension schema registered by a tool, memory layer, or harness. */
+export type ExtensionItem = ItemBase & Record<string, unknown>;
+/** @public Developer-role message item refined by a memory-layer extension schema. */
+export type DeveloperMessageExtensionItem = InputMessageItem & {
+    readonly role: 'developer';
+} & Record<string, unknown>;
+/** @public Function-call item refined by a tool extension schema. */
+export type ToolCallExtensionItem = FunctionCallItem & Record<string, unknown>;
+/** @public Function-call output item refined by a tool extension schema. */
+export type ToolResultExtensionItem = FunctionCallOutputItem & Record<string, unknown>;
+/** @public Zod schemas that extend the runtime `Item` union. */
+export interface ItemSchemaExtensions {
+    /** Harness-wide schemas. Any item matching one of these schemas is accepted. */
+    readonly items?: ReadonlyArray<ZodTypeAny>;
+    /** Schemas for memory-layer developer message items. */
+    readonly developerMessages?: ReadonlyArray<ZodTypeAny>;
+    /** Schemas for tool call items emitted by the model or a harness adapter. */
+    readonly toolCalls?: ReadonlyArray<ZodTypeAny>;
+    /** Schemas for tool result items emitted by the harness or a tool adapter. */
+    readonly toolResults?: ReadonlyArray<ZodTypeAny>;
+}
+/** @public Type inferred from an `ItemSchemaExtensions` declaration. */
+export type InferExtendedItem<TExtensions extends ItemSchemaExtensions | undefined> = TExtensions extends ItemSchemaExtensions ? (TExtensions['items'] extends ReadonlyArray<infer S extends ZodTypeAny> ? z.infer<S> : never) | (TExtensions['developerMessages'] extends ReadonlyArray<infer S extends ZodTypeAny> ? z.infer<S> : never) | (TExtensions['toolCalls'] extends ReadonlyArray<infer S extends ZodTypeAny> ? z.infer<S> : never) | (TExtensions['toolResults'] extends ReadonlyArray<infer S extends ZodTypeAny> ? z.infer<S> : never) : never;
+/** @public Item union extended by a concrete `ItemSchemaExtensions` declaration. */
+export type ExtendedItem<TExtensions extends ItemSchemaExtensions | undefined> = Item | InferExtendedItem<TExtensions>;
+/** @public All output item types from the model (Open Responses compliant). */
+export type OutputItem = MessageItem | FunctionCallItem | ReasoningItem | WebSearchItem | FileSearchItem | ImageGenerationItem | ServerToolItem;
+/** @public All item types that can appear in an ItemLog. */
+export type Item = OutputItem | InputMessageItem | FunctionCallOutputItem;
+/** @public Accepted input types for `AgentHarness.execute()`: a plain string, a single Item, or an array of Items. */
+export type ExecuteInput = string | Item | Item[];
+export {};

package/dist/types/items.js

@@ -0,0 +1,2 @@
+export {};
+//#endregion