@noetic-tools/core 0.2.1 → 0.3.0

package/dist/types/steering.d.ts

@@ -1,89 +0,0 @@
-import type { LLMResponse } from './common.js';
-import type { ExecutionContext, MemoryScope } from './memory-context.js';
-/** @public Enumeration of actions a steering rule can take on a tool call or model response. */
-export declare const SteeringAction: {
-    Allow: string;
-    Deny: string;
-    Guide: string;
-};
-export type SteeringAction = (typeof SteeringAction)[keyof typeof SteeringAction];
-/** @public Discriminator for ledger entry types recorded during steering evaluation. */
-export declare const LedgerEntryKind: {
-    ToolCall: string;
-    ModelTurn: string;
-    Custom: string;
-};
-export type LedgerEntryKind = (typeof LedgerEntryKind)[keyof typeof LedgerEntryKind];
-/** @public Result of evaluating steering rules: an action and optional guidance message. */
-export interface SteeringDecision {
-    action: SteeringAction;
-    guidance?: string;
-}
-/** @public A single entry in the steering ledger, recording a tool call, model turn, or custom event. */
-export interface LedgerEntry {
-    kind: LedgerEntryKind;
-    timestamp: number;
-    toolName?: string;
-    toolArgs?: unknown;
-    success?: boolean;
-    durationMs?: number;
-    model?: string;
-    tokenUsage?: {
-        input: number;
-        output: number;
-    };
-    custom?: Record<string, unknown>;
-    ruleId?: string;
-    action?: SteeringAction;
-    guidance?: string;
-}
-/** @public Parameters passed to a steering rule's `beforeToolCall` evaluation. */
-export interface BeforeToolCallParams<TState = unknown> {
-    toolName: string;
-    toolArgs: unknown;
-    ctx: ExecutionContext;
-    state: TState;
-}
-/** @public Value returned by a `beforeToolCall` steering hook with a decision and optional state update. */
-export interface BeforeToolCallResult<TState = unknown> {
-    decision: SteeringDecision;
-    state?: TState;
-}
-/** @public Parameters passed to a steering rule's `afterModelCall` evaluation. */
-export interface AfterModelCallParams<TState = unknown> {
-    response: LLMResponse;
-    ctx: ExecutionContext;
-    state: TState;
-}
-/** @public Value returned by an `afterModelCall` steering hook with a decision and optional state update. */
-export interface AfterModelCallResult<TState = unknown> {
-    decision: SteeringDecision;
-    state?: TState;
-}
-/** @public A named rule evaluated by the steering layer before tool calls or after model responses. */
-export interface SteeringRule {
-    id: string;
-    name?: string;
-    appliesTo: ('beforeToolCall' | 'afterModelCall')[];
-    predicate?: (params: BeforeToolCallParams | AfterModelCallParams) => SteeringDecision;
-    llmEval?: {
-        mode: 'sync' | 'async';
-        prompt: string;
-        model?: string;
-    };
-}
-/** @public Top-level configuration for the steering subsystem, including rules and limits. */
-export interface SteeringConfig {
-    rules: SteeringRule[];
-    maxLedgerEntries?: number;
-    maxRetries?: number;
-    scope?: MemoryScope;
-}
-/** @public Mutable runtime state maintained by the steering layer across an execution. */
-export interface SteeringState {
-    ledger: LedgerEntry[];
-    pendingAsync: Array<{
-        ruleId: string;
-        guidance: string;
-    }>;
-}

package/dist/types/steering.js

@@ -1,14 +0,0 @@
-//#region Enums
-/** @public Enumeration of actions a steering rule can take on a tool call or model response. */
-export const SteeringAction = {
-    Allow: 'allow',
-    Deny: 'deny',
-    Guide: 'guide',
-};
-/** @public Discriminator for ledger entry types recorded during steering evaluation. */
-export const LedgerEntryKind = {
-    ToolCall: 'tool_call',
-    ModelTurn: 'model_turn',
-    Custom: 'custom',
-};
-//#endregion

package/dist/types/step.d.ts

@@ -1,231 +0,0 @@
-import type { ZodType } from 'zod';
-import type { Channel } from './channel.js';
-import type { ModelParams, RetryPolicy, StepMeta } from './common.js';
-import type { Context } from './context.js';
-import type { NoeticError } from './error.js';
-import type { ContextMemory, MemoryConfig, MemoryLayer } from './memory.js';
-import type { SubprocessAdapter } from './subprocess-adapter.js';
-import type { Tool } from './tool.js';
-/**
- * Cumulative execution snapshot passed to loop `until` predicates.
- * @public
- */
-export interface Snapshot {
-    /** Number of loop iterations completed so far. */
-    stepCount: number;
-    /** Aggregate token usage across all iterations. */
-    tokens: {
-        input: number;
-        output: number;
-        total: number;
-    };
-    /** Wall-clock time in ms since the loop started. */
-    elapsed: number;
-    /** Cumulative cost across all iterations. */
-    cost: number;
-    /** Raw output of the most recent iteration. */
-    lastOutput: unknown;
-    /** Stringified text of the most recent iteration output. */
-    lastText: string;
-    /** Array of all prior iteration outputs (bounded by `maxHistorySize`). */
-    history: unknown[];
-    /** Nesting depth of the current execution context. */
-    depth: number;
-    /** Metadata from the most recent step execution (token usage, tool calls, etc.). */
-    lastStepMeta?: StepMeta | null;
-}
-/**
- * Decision returned by a loop `until` predicate.
- * @public
- */
-export interface Verdict {
-    /** When true, the loop terminates after this iteration. */
-    stop: boolean;
-    /** Human-readable explanation of why the loop stopped (logged in traces). */
-    reason?: string;
-    /** Feedback string injected into the next iteration's context (ignored when `stop` is true). */
-    feedback?: string;
-}
-/** @public Predicate function evaluated after each loop iteration to decide whether to stop. */
-export type Until = (snapshot: Snapshot) => Verdict | Promise<Verdict>;
-/**
- * Field type that accepts either an eager value or a `(ctx) => value` getter.
- * Used by `step.llm` for params that may vary per execution (model, instructions,
- * tool list). The getter runs at step execution time with the live context.
- * @public
- */
-export type Lazy<T, TMemory = ContextMemory> = T | ((ctx: Context<TMemory>) => T | Promise<T>);
-/**
- * Outcome of a single path in a `settle`-mode fork (mirrors `Promise.allSettled`).
- * @public
- */
-export interface SettleResult<O> {
-    /** Id of the step that produced this result. */
-    stepId: string;
-    /** Whether the path completed successfully or threw. */
-    status: 'fulfilled' | 'rejected';
-    /** The path's return value (present when `status` is `'fulfilled'`). */
-    value?: O;
-    /** The error that caused rejection (present when `status` is `'rejected'`). */
-    error?: NoeticError;
-}
-/** @public Discriminated union of all step kinds that can be composed into an execution tree. */
-export type Step<TMemory = ContextMemory, I = unknown, O = unknown> = StepRun<TMemory, I, O> | StepLLM<TMemory, I, O> | StepTool<TMemory, I, O> | StepBranch<TMemory, I, O> | StepFork<TMemory, I, O> | StepSpawn<TMemory, I, O> | StepProvide<TMemory, I, O> | StepLoop<TMemory, I, O> | StepEvery<TMemory, I, O>;
-/** @public A step that executes arbitrary async logic via a user-supplied function. */
-export interface StepRun<TMemory = ContextMemory, I = unknown, O = unknown> {
-    kind: 'run';
-    id: string;
-    execute: (input: I, ctx: Context<TMemory>) => Promise<O>;
-    retry?: RetryPolicy;
-    /**
-     * Per-step subprocess adapter override. When set, the interpreter
-     * dispatches this step through the given adapter instead of the harness
-     * default. Resolution order at dispatch is
-     * `detachedSpawn-overrides.subprocess ?? step.subprocess ?? harness.subprocess`.
-     */
-    subprocess?: SubprocessAdapter;
-}
-/** @public A step that sends a prompt to a language model and returns its response. */
-export interface StepLLM<TMemory = ContextMemory, _I = unknown, O = unknown> {
-    kind: 'llm';
-    id: string;
-    /** Model id. Accepts either an eager string or a `(ctx) => string` getter. */
-    model: Lazy<string, TMemory>;
-    /** System instructions. Eager string or `(ctx) => string | undefined` getter. */
-    instructions?: Lazy<string | undefined, TMemory>;
-    /** Tools exposed to the LLM. Eager array or `(ctx) => Tool[] | undefined` getter. Function-form tools do not contribute to the pre-computed `ctx.unifiedTools`; they are resolved per execution. */
-    tools?: Lazy<Tool[] | undefined, TMemory>;
-    output?: ZodType<O>;
-    params?: ModelParams;
-    /** Controls framework event emission for this step. Defaults to `true`. Set `false` to suppress all framework events. A filter function receives `(eventType, data)` and returns `boolean`. */
-    emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
-}
-/** @public A step that invokes a single tool directly, bypassing the LLM. */
-export interface StepTool<_TMemory = ContextMemory, I = unknown, O = unknown> {
-    kind: 'tool';
-    id: string;
-    tool: Tool<ZodType<I>, ZodType<O>>;
-    args?: Partial<I>;
-}
-/** @public A step that dynamically selects and executes one of several possible sub-steps. */
-export interface StepBranch<TMemory = ContextMemory, I = unknown, O = unknown> {
-    kind: 'branch';
-    id: string;
-    route: (input: I, ctx: Context<TMemory>) => Step<TMemory, I, O> | null | Promise<Step<TMemory, I, O> | null>;
-    _optimizable?: Step<TMemory>[];
-}
-/** @public Union of fork step variants (`race`, `all`, `settle`) for concurrent path execution. */
-export type StepFork<TMemory = ContextMemory, I = unknown, O = unknown> = StepForkRace<TMemory, I, O> | StepForkAll<TMemory, I, O> | StepForkSettle<TMemory, I, O>;
-/** @public A fork step that returns the result of the first path to complete. */
-export interface StepForkRace<TMemory = ContextMemory, I = unknown, O = unknown> {
-    kind: 'fork';
-    id: string;
-    mode: 'race';
-    paths: (input: I, ctx: Context<TMemory>) => Step<TMemory, I, O>[];
-    concurrency?: number;
-    _optimizable?: Step<TMemory>[];
-}
-/** @public A fork step that runs all paths and merges their results. */
-export interface StepForkAll<TMemory = ContextMemory, I = unknown, O = unknown> {
-    kind: 'fork';
-    id: string;
-    mode: 'all';
-    paths: (input: I, ctx: Context<TMemory>) => Step<TMemory, I, O>[];
-    merge: (results: O[], ctx: Context<TMemory>) => O;
-    concurrency?: number;
-    _optimizable?: Step<TMemory>[];
-}
-/** @public A fork step that runs all paths and collects fulfilled/rejected outcomes. */
-export interface StepForkSettle<TMemory = ContextMemory, I = unknown, O = unknown> {
-    kind: 'fork';
-    id: string;
-    mode: 'settle';
-    paths: (input: I, ctx: Context<TMemory>) => Step<TMemory, I, O>[];
-    merge: (results: SettleResult<O>[], ctx: Context<TMemory>) => O;
-    concurrency?: number;
-    _optimizable?: Step<TMemory>[];
-}
-/**
- * A step that provides memory layers to its child without creating an isolated context.
- * Like React's Context.Provider — layers are available to all descendant steps.
- * Spawn and detachedSpawn break the inheritance chain.
- * @public
- */
-export interface StepProvide<TMemory = ContextMemory, I = unknown, O = unknown> {
-    kind: 'provide';
-    id: string;
-    child: Step<TMemory, I, O>;
-    memory: MemoryConfig | MemoryLayer[];
-}
-/** @public A step that launches a child execution with its own memory scope. */
-export interface StepSpawn<TMemory = ContextMemory, I = unknown, O = unknown> {
-    kind: 'spawn';
-    id: string;
-    child: Step<TMemory, I, O>;
-    memory?: MemoryConfig | MemoryLayer[];
-    timeout?: number;
-    /**
-     * Per-step subprocess adapter override applied when the interpreter
-     * dispatches this spawn. Resolution order is
-     * `detachedSpawn-overrides.subprocess ?? step.subprocess ?? harness.subprocess`.
-     */
-    subprocess?: SubprocessAdapter;
-}
-/**
- * A loop step that iterates a body step until a termination predicate is satisfied.
- * @public
- */
-export interface StepLoop<TMemory = ContextMemory, I = unknown, O = unknown> {
-    kind: 'loop';
-    /** Unique step identifier used in traces and error messages. */
-    id: string;
-    /** Steps to execute sequentially on each iteration. */
-    steps: ReadonlyArray<Step<TMemory, I, O>>;
-    /** Termination predicate evaluated after each iteration with a cumulative snapshot. */
-    until: Until;
-    /** Hard safety cap on iterations (default: 1000). */
-    maxIterations?: number;
-    /** Maximum number of entries kept in the snapshot history array. */
-    maxHistorySize?: number;
-    /** Optional channel for injecting messages into the loop mid-execution. */
-    inbox?: Channel<string>;
-    /** Ms to wait on inbox before the loop parks itself (default: 0 = no parking). */
-    parkTimeout?: number;
-    /** Transforms the previous iteration's output into the next iteration's input. */
-    prepareNext?: (output: O, verdict: Verdict, ctx: Context<TMemory>) => I;
-    /** Per-iteration error handler: retry the iteration, skip it, or abort the loop. */
-    onError?: (error: NoeticError, ctx: Context<TMemory>) => 'retry' | 'skip' | 'abort';
-}
-/**
- * Error policy for the `every` operator when its body step throws.
- * - `'continue'` (default): emit a span event recording the error and continue parking.
- * - `'fail'`: re-throw, terminating the operator.
- * @public
- */
-export type EveryErrorPolicy = 'continue' | 'fail';
-/**
- * A step that runs a body step on a fixed-interval schedule, optionally woken
- * sooner by a wake channel. Runs forever until the executing context is cancelled.
- *
- * The operator output is `void` — `every` does not accumulate iteration outputs.
- * The `O` type parameter exists only to anchor the body step's output type.
- *
- * @public
- */
-export interface StepEvery<TMemory = ContextMemory, I = unknown, O = unknown> {
-    kind: 'every';
-    /** Unique step identifier used in traces and error messages. */
-    id: string;
-    /** Body step executed on each iteration. */
-    step: Step<TMemory, I, O>;
-    /** Park duration between iterations in milliseconds. Must be >= 0. */
-    ms: number;
-    /** Optional channel that wakes the parking interval when any value arrives. */
-    wakeOn?: Channel<unknown>;
-    /** Behavior when `step` throws. Defaults to `'continue'`. */
-    onError?: EveryErrorPolicy;
-    /** Random jitter applied to the park duration in milliseconds. Must be >= 0. Default 0. */
-    jitter?: number;
-}
-/** @public Function signature used by the interpreter to recursively execute a step. */
-export type ExecuteStepFn = <TMemory, I, O>(step: Step<TMemory, I, O>, input: I, ctx: Context<TMemory>) => Promise<O>;

package/dist/types/step.js

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

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

@@ -1,157 +0,0 @@
-/** @public Lifecycle states for a subprocess handle. */
-export type SubprocessStatus = 'starting' | 'running' | 'paused' | 'completed' | 'failed' | 'stopped' | 'stale';
-/**
- * @public
- * Plain-object shape used to transport an error from a subprocess back to the
- * parent via `SubprocessHandle.metadata.error`. Non-serialisable fields (e.g.
- * `Error.cause` chains with functions or cyclic data) are dropped at the
- * producer boundary.
- */
-export interface SerializedError {
-    /** Human-readable message; always present. */
-    message: string;
-    /** Constructor `name` of the underlying error (`Error`, `NoeticError`, etc.). */
-    name?: string;
-    /** Best-effort stack trace, when the producing runtime retained one. */
-    stack?: string;
-    /**
-     * Structured `NoeticError` payload carried through for in-process
-     * transport. Consumers may reconstruct `NoeticErrorImpl` from this when
-     * they need typed error kinds.
-     */
-    noeticError?: unknown;
-}
-/** @public Fields common to every subprocess request variant. */
-interface SubprocessRequestBase {
-    metadata?: Record<string, unknown>;
-}
-/**
- * @public
- * Launches an OS-level child process. This is the classic variant used by the
- * tasks runner to spawn planner / implementer children.
- *
- * When `kind` is omitted the request is treated as a process request — this
- * preserves backward compatibility with callers that predate the
- * `StepSubprocessRequest` variant.
- */
-export interface ProcessSubprocessRequest extends SubprocessRequestBase {
-    kind?: 'process';
-    command: string;
-    args?: ReadonlyArray<string>;
-    cwd?: string;
-    env?: Record<string, string | undefined>;
-    detached?: boolean;
-    stdin?: string;
-}
-/** @public Overrides applied to the child context when executing a step request. */
-export interface StepSubprocessOverrides {
-    /** Override the child's thread id. */
-    threadId?: string;
-    /** Override the child's resource id. */
-    resourceId?: string;
-    /** Override the child's initial cwd. */
-    cwdInit?: string;
-}
-/**
- * @public
- * Dispatches a step through the adapter. `stepId` resolves against the shared
- * step registry — the in-memory adapter invokes the in-process execute pipeline,
- * while out-of-process adapters spawn a child runtime that re-imports the same
- * registry via a configured entry point.
- */
-export interface StepSubprocessRequest extends SubprocessRequestBase {
-    kind: 'step';
-    stepId: string;
-    /** Serialisable input for the step. Stored in `handle.metadata` when needed. */
-    serializedInput: unknown;
-    /** Stable id for the execution — used for handle lookup and durable checkpointing. */
-    executionId: string;
-    /** Child-context overrides (thread, resource, cwd). */
-    overrides: StepSubprocessOverrides;
-    /**
-     * @internal
-     * Closure used by the default in-memory adapter to run the step in the same
-     * process as the caller. Non-serialisable — adapters that cross a process
-     * boundary MUST ignore this field. Framework-internal callers set it; public
-     * consumers should not.
-     */
-    _localExecutor?: () => Promise<unknown>;
-}
-/** @public Discriminated union covering every shape `SubprocessAdapter.spawn()` accepts. */
-export type SubprocessRequest = ProcessSubprocessRequest | StepSubprocessRequest;
-/**
- * @public
- * Well-known keys carried on `SubprocessHandle.metadata`. Adapters populate
- * these during their lifecycle; consumers read them via the helpers exported
- * alongside the adapter types.
- */
-export interface SubprocessHandleMetadata extends Record<string, unknown> {
-    /** Awaited step result, stored when a step request completes successfully. */
-    result?: unknown;
-    /** Serialised error, stored when a step request fails. */
-    error?: SerializedError;
-    /** Execution id echoed from the originating `StepSubprocessRequest`. */
-    executionId?: string;
-}
-/** @public Handle returned by `SubprocessAdapter.spawn()` — a durable reference to a child. */
-export interface SubprocessHandle {
-    id: string;
-    status: SubprocessStatus;
-    startedAt: string;
-    updatedAt?: string;
-    metadata?: SubprocessHandleMetadata;
-}
-/** @public Outcome of `pause` / `resume` calls on a subprocess handle. */
-export type SubprocessControlResult = {
-    kind: 'ok';
-    handle: SubprocessHandle;
-} | {
-    kind: 'unsupported';
-    handle: SubprocessHandle;
-    message: string;
-} | {
-    kind: 'not_found';
-    handleId: string;
-};
-/** @public Outcome of a `stop()` call on a subprocess handle. */
-export interface SubprocessStopResult {
-    kind: 'stopped' | 'not_found';
-    handleId: string;
-    handle?: SubprocessHandle;
-}
-/**
- * @public
- * Contract for dispatching and managing subprocess-style executions — both
- * OS-level child processes and in-process step runs. Implementations own the
- * lifecycle of every handle they return, including persistence when they opt
- * into durable execution via `reattach` / `listLive`.
- */
-export interface SubprocessAdapter {
-    /** Dispatches a new request and returns its handle. */
-    spawn(request: SubprocessRequest): Promise<SubprocessHandle>;
-    /** Fetches the current handle by id, or `null` when unknown. */
-    get(handleId: string): Promise<SubprocessHandle | null>;
-    /** Requests cancellation of a running handle. */
-    stop(handleId: string, reason?: string): Promise<SubprocessStopResult>;
-    /** Pauses a running handle (when the adapter supports it). */
-    pause(handleId: string): Promise<SubprocessControlResult>;
-    /** Resumes a paused handle (when the adapter supports it). */
-    resume(handleId: string): Promise<SubprocessControlResult>;
-    /** Returns true when the underlying execution is still alive. */
-    isAlive(handle: SubprocessHandle): Promise<boolean>;
-    /**
-     * Rebinds to a handle persisted across a host restart. Returns `null` when
-     * no manifest exists for the given id. Durability is an adapter-level
-     * concern — the in-memory adapter returns `null` by default (handles are
-     * ephemeral), while the local adapter consults its storage.
-     */
-    reattach(handleId: string): Promise<SubprocessHandle | null>;
-    /**
-     * Lists every handle the adapter currently treats as live. Used by host
-     * recovery to rediscover running children on startup. The in-memory adapter
-     * returns the set of active in-process handles; the local adapter scans its
-     * persisted manifest.
-     */
-    listLive(): Promise<ReadonlyArray<SubprocessHandle>>;
-}
-export {};

package/dist/types/subprocess-adapter.js

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

package/dist/types/tool-context.d.ts

@@ -1,34 +0,0 @@
-import type { TurnContext } from '@openrouter/agent';
-import type { StepMeta } from './common.js';
-import type { Context } from './context.js';
-import type { FsAdapter } from './fs-adapter.js';
-import type { Item } from './items.js';
-import type { AgentHarnessContract } from './runtime.js';
-import type { ShellAdapter } from './shell-adapter.js';
-/** @public Accessor for reading and writing per-layer state from within a tool execution. */
-export interface ToolMemory {
-    get<T>(layerId: string): T | undefined;
-    set<T>(layerId: string, state: T): void;
-}
-/**
- * Context provided to a tool's `execute` function at invocation time.
- * @public
- */
-export interface ToolExecutionContext {
-    /** The current step execution context (access to item log, parent id, etc.). */
-    readonly ctx: Context;
-    /** The harness instance executing this tool. */
-    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;
-    /** Per-layer memory accessor for reading/writing tool-specific state. */
-    readonly memory: ToolMemory;
-    /** The fully assembled conversation view at the point of tool invocation. */
-    readonly assembledView: ReadonlyArray<Item>;
-    /** Metadata from the most recent step execution (token usage, tool calls, etc.). */
-    readonly lastStepMeta: StepMeta | null;
-    /** OpenRouter turn context, when using the OpenRouter SDK adapter. */
-    readonly turnContext?: TurnContext;
-}

package/dist/types/tool-context.js

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

package/dist/types/tool.d.ts

@@ -1,64 +0,0 @@
-import type { ZodTypeAny, z } from 'zod';
-import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, ToolResultExtensionItem } from './items.js';
-type ToolExecutionResult<O extends ZodTypeAny> = Promise<z.infer<O>> | AsyncGenerator<unknown, z.infer<O>>;
-/**
- * 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.
-     * Declared as a method (bivariant params) so a concrete
-     * `ToolMemoryDeclaration<MyState>` assigns to the erased
-     * `ToolMemoryDeclaration` the `tool()` builder and runtime consume.
-     */
-    recall(state: TState): string | null;
-}
-/**
- * A tool definition that an LLM can invoke during execution.
- *
- * The runtime passes a `ToolExecutionContext` (from `./tool-context`) as
- * the second argument to `execute`. Callers that need the concrete type
- * should import `Tool` from the package root (`@noetic-tools/core`), which
- * re-exports it with `ToolExecutionContext` substituted in.
- * @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. `toolCtx` is a
-     * `ToolExecutionContext` at runtime — typed as `unknown` here to keep
-     * this type a dependency leaf. Use `tool()` from `builders/` or cast at
-     * the call site to get a typed handle.
-     */
-    execute(args: z.infer<I>, toolCtx: unknown): 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;
-}
-export {};

package/dist/types/tool.js

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

package/dist/util/framework-cast.d.ts

@@ -1,10 +0,0 @@
-/**
- * Explicit cast for framework boundaries where TypeScript's type system
- * cannot express the relationship between input and output types.
- *
- * Used for: pass-through returns (branch null route, loop feedback),
- * raw LLM text output, type-erased collections, and cross-library bridges.
- *
- * This is the single approved location for unsafe type coercion in the codebase.
- */
-export declare function frameworkCast<T>(value: unknown): T;

package/dist/util/framework-cast.js

@@ -1,16 +0,0 @@
-/**
- * Explicit cast for framework boundaries where TypeScript's type system
- * cannot express the relationship between input and output types.
- *
- * Used for: pass-through returns (branch null route, loop feedback),
- * raw LLM text output, type-erased collections, and cross-library bridges.
- *
- * This is the single approved location for unsafe type coercion in the codebase.
- */
-// Declared return type differs from the parameter type intentionally —
-// callers specify T to bridge a framework type gap that TypeScript cannot express.
-// The runtime value is returned unchanged (identity function).
-export function frameworkCast(value) {
-    // @ts-expect-error — intentional unsafe coercion at framework boundary
-    return value;
-}

package/dist/util/message-helpers.d.ts

@@ -1,17 +0,0 @@
-import type { LLMResponse } from '../types/common.js';
-import type { Context } from '../types/context.js';
-import type { InputMessageItem, Item, MessageItem } from '../types/items.js';
-export declare function isAssistantMessage(item: unknown): item is MessageItem;
-export declare function isUserMessage(item: unknown): item is MessageItem;
-export declare function isOutputText(part: {
-    type: string;
-}): part is {
-    type: 'output_text';
-    text: string;
-};
-export declare function createMessage(text: string, role: 'user' | 'developer'): InputMessageItem;
-export declare function extractAssistantText(items: ReadonlyArray<Item>): string;
-/** Naive token estimate: ~4 chars per token */
-export declare function estimateTokens(text: string): number;
-/** Accumulate token usage and cost from an LLM response onto a mutable context. */
-export declare function trackUsage(ctx: Context, response: LLMResponse): void;