@noetic-tools/core 0.0.1 → 0.1.0

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

@@ -0,0 +1,39 @@
+import type { LLMResponse } from './common';
+import type { FsAdapter } from './fs-adapter';
+import type { Item } from './items';
+import type { ShellAdapter } from './shell-adapter';
+/** @public Isolation scope controlling how a memory layer's state is keyed and shared. */
+export type MemoryScope = 'thread' | 'resource' | 'global' | 'execution';
+/** @public Terminal outcome of an execution run, reported to memory layers on completion. */
+export type ExecutionOutcome = 'success' | 'failure' | 'aborted';
+/** @public Minimal model-call surface exposed to memory-layer hooks. */
+export interface MemoryCallModelRequest {
+    model: string;
+    items: ReadonlyArray<Item>;
+    instructions?: string;
+}
+/** @public Runtime metadata available to memory layer hooks during each lifecycle phase. */
+export interface ExecutionContext {
+    executionId: string;
+    threadId: string;
+    resourceId?: string;
+    depth: number;
+    stepNumber: number;
+    tokenUsage: {
+        input: number;
+        output: number;
+    };
+    cost: number;
+    /** Filesystem adapter for virtual or real filesystem access. */
+    fs: FsAdapter;
+    /** Shell adapter for virtual or real shell command execution. */
+    shell: ShellAdapter;
+    callModel?: (request: MemoryCallModelRequest) => Promise<LLMResponse>;
+    tokenize(text: string): number;
+    trace: {
+        setAttribute(key: string, value: string | number | boolean): void;
+        addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+    };
+    /** Snapshot a sibling memory layer's state by its `layer.id`. */
+    readLayerState<T>(layerId: string): T | undefined;
+}

package/dist/types/memory-context.js

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

package/dist/types/memory.d.ts

@@ -1,11 +1,29 @@
 import type { ZodType } from 'zod';
 import type { LLMResponse } from './common';
-import type { ItemLog } from './context';
-import type { FsAdapter } from './fs-adapter';
+import type { ItemLog } from './context-parts/item-log';
 import type { Item, ItemSchemaExtensions } from './items';
-import type { CallModelRequest } from './runtime';
-import type { ShellAdapter } from './shell-adapter';
+import type { ExecutionContext, ExecutionOutcome, MemoryScope } from './memory-context';
 import type { AfterModelCallParams, AfterModelCallResult, BeforeToolCallParams, BeforeToolCallResult } from './steering';
+export type { ExecutionContext, ExecutionOutcome, MemoryCallModelRequest, MemoryScope, } from './memory-context';
+/** @public Isolation scope controlling how a memory layer's state is keyed and shared. */
+export type BudgetConfig = number | {
+    min: number;
+    max: number;
+} | 'auto';
+/** @public Per-hook timeout overrides in milliseconds for a memory layer. */
+export interface LayerTimeouts {
+    init?: number;
+    recall?: number;
+    store?: number;
+    onSpawn?: number;
+    onReturn?: number;
+    onComplete?: number;
+    dispose?: number;
+    beforeToolCall?: number;
+    afterModelCall?: number;
+    onItemAppend?: number;
+    projectHistory?: number;
+}
 /** @public A read-only data projection from layer state, accessible via `ctx.memory['layerId'].prop`. */
 export interface LayerDataDecl<T = unknown, TState = unknown> {
     kind: 'data';
@@ -65,8 +83,19 @@ export interface MemoryConfig<TLayers extends readonly MemoryLayer[] = readonly
     /** Phantom field carrying the inferred memory shape. Never accessed at runtime. */
     readonly _shape: InferMemoryShape<TLayers>;
 }
-/** @public Extract the typed memory shape from a MemoryConfig. Usage: `type Mem = InferMemory<typeof config>` */
-export type InferMemory<T extends MemoryConfig> = T['_shape'];
+/**
+ * Extract the typed memory shape from a MemoryConfig.
+ * Constrains structurally on the phantom `_shape` field rather than on
+ * `MemoryConfig` itself: `MemoryConfig` is invariant in `TLayers` (the `_shape`
+ * field carries it in an invariant position), so a concrete
+ * `MemoryConfig<readonly [SomeLayer]>` does not satisfy the defaulted
+ * `MemoryConfig<readonly MemoryLayer[]>`. Since `InferMemory` only reads
+ * `_shape`, this constraint accepts any config the `memory()` builder produces.
+ * @public Usage: `type Mem = InferMemory<typeof config>`
+ */
+export type InferMemory<T extends {
+    readonly _shape: unknown;
+}> = T['_shape'];
 /** @public Well-known ordering slots for positioning memory layers in the recall/store pipeline. */
 export declare const Slot: {
     readonly REMINDER: 80;
@@ -79,65 +108,6 @@ export declare const Slot: {
     readonly RAG: 350;
     readonly SEMANTIC_RECALL: 400;
 };
-/** @public Isolation scope controlling how a memory layer's state is keyed and shared. */
-export type MemoryScope = 'thread' | 'resource' | 'global' | 'execution';
-/** @public Token budget specification for a memory layer: fixed number, min/max range, or automatic. */
-export type BudgetConfig = number | {
-    min: number;
-    max: number;
-} | 'auto';
-/** @public Per-hook timeout overrides in milliseconds for a memory layer. */
-export interface LayerTimeouts {
-    init?: number;
-    recall?: number;
-    store?: number;
-    onSpawn?: number;
-    onReturn?: number;
-    onComplete?: number;
-    dispose?: number;
-    beforeToolCall?: number;
-    afterModelCall?: number;
-    onItemAppend?: number;
-    projectHistory?: number;
-}
-/** @public Terminal outcome of an execution run, reported to memory layers on completion. */
-export type ExecutionOutcome = 'success' | 'failure' | 'aborted';
-/** @public Runtime metadata available to memory layer hooks during each lifecycle phase. */
-export interface ExecutionContext {
-    executionId: string;
-    threadId: string;
-    resourceId?: string;
-    depth: number;
-    stepNumber: number;
-    tokenUsage: {
-        input: number;
-        output: number;
-    };
-    cost: number;
-    /** Filesystem adapter for virtual or real filesystem access. */
-    fs: FsAdapter;
-    /** Shell adapter for virtual or real shell command execution. */
-    shell: ShellAdapter;
-    callModel?: (request: CallModelRequest) => Promise<LLMResponse>;
-    tokenize(text: string): number;
-    trace: {
-        setAttribute(key: string, value: string | number | boolean): void;
-        addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
-    };
-    /**
-     * Snapshot a sibling memory layer's state by its `layer.id`.
-     * Returns `undefined` if no layer with that ID has stored state in this execution.
-     * Enables cross-layer coordination (e.g., a reminder layer reading a planning layer's mode flag).
-     *
-     * **Type safety:** The generic `T` is an author-assertion — it is NOT
-     * runtime-validated. Any layer may register under the queried id with an
-     * arbitrary state shape, so callers MUST add a runtime shape guard (e.g.
-     * `Array.isArray`, a Zod parse, or a narrow `typeof` check) before
-     * dereferencing fields. See `reminder-triggers.ts` (`hasSources`) in
-     * `@noetic/cli` for the canonical pattern.
-     */
-    readLayerState<T>(layerId: string): T | undefined;
-}
 /** @public Low-level key-value persistence backend used by scoped storage and memory layers. */
 export interface StorageAdapter {
     get<T>(key: string): Promise<T | null>;

package/dist/types/runtime.d.ts

@@ -1,6 +1,6 @@
 import type { ZodType } from 'zod';
 import type { Channel, ChannelHandle, ExternalChannel } from './channel';
-import type { LLMResponse, ModelParams, Tool } from './common';
+import type { LLMResponse, ModelParams } from './common';
 import type { Context, CwdState } from './context';
 import type { DetachedHandle } from './detached';
 import type { FsAdapter } from './fs-adapter';
@@ -12,6 +12,7 @@ import type { ShellAdapter } from './shell-adapter';
 import type { SteeringDecision } from './steering';
 import type { Step } from './step';
 import type { SubprocessAdapter } from './subprocess-adapter';
+import type { Tool } from './tool';
 /** @public Optional lifecycle hooks invoked before and after each step execution. */
 export interface AgentHooks {
     beforeStep?: (step: Step, ctx: Context) => Promise<void>;

package/dist/types/steering.d.ts

@@ -1,5 +1,5 @@
 import type { LLMResponse } from './common';
-import type { ExecutionContext, MemoryScope } from './memory';
+import type { ExecutionContext, MemoryScope } from './memory-context';
 /** @public Enumeration of actions a steering rule can take on a tool call or model response. */
 export declare const SteeringAction: {
     Allow: string;

package/dist/types/step-registrar.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `StepRegistrar` is the layer-safe indirection that lets builders
+ * (in `core-primitives`) register steps without importing the runtime
+ * registry directly (which lives in `core-runtime`, a lower layer).
+ *
+ * The runtime provides the concrete implementation via
+ * `setDefaultRegistrar()` on module load. Until then a no-op fallback
+ * is active so builders constructed outside a harness (e.g. in unit
+ * tests that never touch the interpreter) don't throw.
+ *
+ * The registry itself lives in `packages/core/src/runtime/step-registry.ts`
+ * and is consulted only by `packages/core/src/harness/step-bootstrap.ts`
+ * when an out-of-process child needs to look up a step by id. In-process
+ * execution walks the step tree directly and never touches either side.
+ */
+import type { Step } from './step';
+/**
+ * @public
+ * Registers a step under its `id` so the subprocess adapter can later
+ * look it up by name from an out-of-process child. Implementations
+ * typically call the runtime's underlying `registerStep` function.
+ */
+export interface StepRegistrar {
+    register<TMemory, I, O>(step: Step<TMemory, I, O>): void;
+}
+/**
+ * @public
+ * Returns the active registrar. Called by every step builder to register
+ * the step it just constructed. Default is a no-op; the runtime installs
+ * the real implementation via `setDefaultRegistrar()` on module load.
+ */
+export declare function getDefaultRegistrar(): StepRegistrar;
+/**
+ * @public
+ * Installs a registrar implementation. Called exactly once by the
+ * runtime on module load; tests that want per-case isolation can
+ * install a throwing or counting registrar and restore the default
+ * with `resetDefaultRegistrar()` in their teardown.
+ */
+export declare function setDefaultRegistrar(registrar: StepRegistrar): void;
+/**
+ * @public
+ * Restores the no-op registrar. Primarily a test helper — production
+ * code paths rely on the runtime having installed the real registrar.
+ */
+export declare function resetDefaultRegistrar(): void;

package/dist/types/step-registrar.js

@@ -0,0 +1,56 @@
+/**
+ * `StepRegistrar` is the layer-safe indirection that lets builders
+ * (in `core-primitives`) register steps without importing the runtime
+ * registry directly (which lives in `core-runtime`, a lower layer).
+ *
+ * The runtime provides the concrete implementation via
+ * `setDefaultRegistrar()` on module load. Until then a no-op fallback
+ * is active so builders constructed outside a harness (e.g. in unit
+ * tests that never touch the interpreter) don't throw.
+ *
+ * The registry itself lives in `packages/core/src/runtime/step-registry.ts`
+ * and is consulted only by `packages/core/src/harness/step-bootstrap.ts`
+ * when an out-of-process child needs to look up a step by id. In-process
+ * execution walks the step tree directly and never touches either side.
+ */
+//#endregion
+//#region Module state
+/**
+ * No-op registrar used until the runtime installs the real one. Keeps
+ * builder-only callsites (e.g. tests that construct a step without
+ * instantiating `AgentHarness`) non-throwing.
+ */
+const noopRegistrar = {
+    register: () => undefined,
+};
+let currentRegistrar = noopRegistrar;
+//#endregion
+//#region Public API
+/**
+ * @public
+ * Returns the active registrar. Called by every step builder to register
+ * the step it just constructed. Default is a no-op; the runtime installs
+ * the real implementation via `setDefaultRegistrar()` on module load.
+ */
+export function getDefaultRegistrar() {
+    return currentRegistrar;
+}
+/**
+ * @public
+ * Installs a registrar implementation. Called exactly once by the
+ * runtime on module load; tests that want per-case isolation can
+ * install a throwing or counting registrar and restore the default
+ * with `resetDefaultRegistrar()` in their teardown.
+ */
+export function setDefaultRegistrar(registrar) {
+    currentRegistrar = registrar;
+}
+/**
+ * @public
+ * Restores the no-op registrar. Primarily a test helper — production
+ * code paths rely on the runtime having installed the real registrar.
+ */
+export function resetDefaultRegistrar() {
+    currentRegistrar = noopRegistrar;
+}
+//#endregion

package/dist/types/step.d.ts

@@ -1,9 +1,11 @@
 import type { ZodType } from 'zod';
 import type { Channel } from './channel';
-import type { ModelParams, RetryPolicy, StepMeta, Tool } from './common';
+import type { ModelParams, RetryPolicy, StepMeta } from './common';
 import type { Context } from './context';
 import type { NoeticError } from './error';
 import type { ContextMemory, MemoryConfig, MemoryLayer } from './memory';
+import type { SubprocessAdapter } from './subprocess-adapter';
+import type { Tool } from './tool';
 /**
  * Cumulative execution snapshot passed to loop `until` predicates.
  * @public
@@ -46,6 +48,13 @@ export interface Verdict {
 }
 /** @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
@@ -68,14 +77,24 @@ export interface StepRun<TMemory = ContextMemory, I = unknown, O = unknown> {
     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> {
+export interface StepLLM<TMemory = ContextMemory, _I = unknown, O = unknown> {
     kind: 'llm';
     id: string;
-    model: string;
-    instructions?: string;
-    tools?: Tool[];
+    /** 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`. */
@@ -145,6 +164,12 @@ export interface StepSpawn<TMemory = ContextMemory, I = unknown, O = unknown> {
     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.

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

@@ -1,20 +1,107 @@
+/** @public Lifecycle states for a subprocess handle. */
 export type SubprocessStatus = 'starting' | 'running' | 'paused' | 'completed' | 'failed' | 'stopped' | 'stale';
-export interface SubprocessRequest {
+/**
+ * @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;
-    metadata?: Record<string, unknown>;
 }
+/** @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?: Record<string, unknown>;
+    metadata?: SubprocessHandleMetadata;
 }
+/** @public Outcome of `pause` / `resume` calls on a subprocess handle. */
 export type SubprocessControlResult = {
     kind: 'ok';
     handle: SubprocessHandle;
@@ -26,16 +113,45 @@ export type SubprocessControlResult = {
     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 +1,3 @@
+//#region Status
 export {};
+//#endregion

package/dist/types/tool.d.ts

@@ -0,0 +1,64 @@
+import type { ZodTypeAny, z } from 'zod';
+import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, ToolResultExtensionItem } from './items';
+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

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

package/dist/unstable.d.ts

@@ -6,8 +6,6 @@
  * They are intended for authors of custom memory layers, runtime backends,
  * and other framework extensions. Do not depend on them in application code.
  */
-/** @unstable Unsafe cast utility for bridging internal type boundaries. */
-export { frameworkCast } from './interpreter/framework-cast';
 /** @unstable Budget allocation algorithm for memory layer token budgets. */
 export type { BudgetAllocation, BudgetLimits } from './memory/budget';
 /** @unstable Budget allocation and checking utilities. */
@@ -26,3 +24,5 @@ export { createScopedStorage } from './memory/scope';
  * the public surface — call sites must hold exclusive use of the parent ctx.
  */
 export { retargetCwdForSpawn } from './runtime/cwd-helpers';
+/** @unstable Unsafe cast utility for bridging internal type boundaries. */
+export { frameworkCast } from './util/framework-cast';

package/dist/unstable.js

@@ -6,8 +6,6 @@
  * They are intended for authors of custom memory layers, runtime backends,
  * and other framework extensions. Do not depend on them in application code.
  */
-/** @unstable Unsafe cast utility for bridging internal type boundaries. */
-export { frameworkCast } from './interpreter/framework-cast';
 /** @unstable Budget allocation and checking utilities. */
 export { allocateBudgets, checkBudget } from './memory/budget';
 /** @unstable Factory for creating layer state stores. */
@@ -22,3 +20,5 @@ export { createScopedStorage } from './memory/scope';
  * the public surface — call sites must hold exclusive use of the parent ctx.
  */
 export { retargetCwdForSpawn } from './runtime/cwd-helpers';
+/** @unstable Unsafe cast utility for bridging internal type boundaries. */
+export { frameworkCast } from './util/framework-cast';

package/dist/until/predicates.d.ts

@@ -38,6 +38,15 @@ export declare const until: {
     converged(opts: ConvergeConfig): Until;
     /** Stops the loop when the last output text contains the given marker string. @public */
     outputContains(marker: string): Until;
+    /**
+     * Stops the loop when the last output text exactly equals the given
+     * sentinel string. Prefer this over `outputContains` when the marker is a
+     * dedicated exit sentinel produced by a terminator step — exact equality
+     * avoids substring collisions with unrelated step output that happens to
+     * quote the sentinel.
+     * @public
+     */
+    outputEquals(sentinel: string): Until;
     /** Wraps an arbitrary `Until` function as a named predicate. @public */
     custom(fn: Until): Until;
 };

package/dist/until/predicates.js

@@ -119,6 +119,20 @@ export const until = {
             reason: snap.lastText.includes(marker) ? `Output contains marker: ${marker}` : undefined,
         });
     },
+    /**
+     * Stops the loop when the last output text exactly equals the given
+     * sentinel string. Prefer this over `outputContains` when the marker is a
+     * dedicated exit sentinel produced by a terminator step — exact equality
+     * avoids substring collisions with unrelated step output that happens to
+     * quote the sentinel.
+     * @public
+     */
+    outputEquals(sentinel) {
+        return (snap) => ({
+            stop: snap.lastText === sentinel,
+            reason: snap.lastText === sentinel ? `Output matched sentinel: ${sentinel}` : undefined,
+        });
+    },
     /** Wraps an arbitrary `Until` function as a named predicate. @public */
     custom(fn) {
         return fn;