@noetic-tools/core 0.0.1

package/dist/types/memory.d.ts

@@ -0,0 +1,336 @@
+import type { ZodType } from 'zod';
+import type { LLMResponse } from './common';
+import type { ItemLog } from './context';
+import type { FsAdapter } from './fs-adapter';
+import type { Item, ItemSchemaExtensions } from './items';
+import type { CallModelRequest } from './runtime';
+import type { ShellAdapter } from './shell-adapter';
+import type { AfterModelCallParams, AfterModelCallResult, BeforeToolCallParams, BeforeToolCallResult } from './steering';
+/** @public A read-only data projection from layer state, accessible via `ctx.memory['layerId'].prop`. */
+export interface LayerDataDecl<T = unknown, TState = unknown> {
+    kind: 'data';
+    /** Project a value from the layer's current state. Method syntax enables bivariant assignability. */
+    read(state: TState): T;
+}
+/** @public A callable function backed by layer state, accessible via `ctx.memory['layerId'].fn()` or as an LLM tool. */
+export interface LayerFunctionDecl<TInput = unknown, TOutput = unknown, TState = unknown> {
+    kind: 'function';
+    /** Human-readable description (used as tool description when exposed to LLM). */
+    description: string;
+    /** Zod schema for input arguments. */
+    input: ZodType<TInput>;
+    /** Zod schema for return value. */
+    output: ZodType<TOutput>;
+    /** Execute the function with the layer's current state. Return optional state update. */
+    execute(args: TInput, state: TState, ctx: ExecutionContext): Promise<{
+        result: TOutput;
+        state?: TState;
+    }>;
+}
+/** @public Map of named data and function declarations exposed by a memory layer. */
+export type LayerProvides = Record<string, LayerDataDecl | LayerFunctionDecl>;
+/**
+ * Mapped type that produces a flat handle from a layer's `provides` declaration.
+ * Data entries become direct property reads; function entries become callable async methods.
+ * @public
+ */
+export type LayerHandle<T extends MemoryLayer> = T extends {
+    provides: infer P;
+} ? {
+    [K in keyof P]: P[K] extends LayerDataDecl<infer D, unknown> ? D : P[K] extends LayerFunctionDecl<infer I, infer O, unknown> ? (args: I) => Promise<O> : never;
+} : Record<string, never>;
+/** @public Object keyed by layer ID, where each value is a resolved handle for that layer's provides. */
+export type ContextMemory = Readonly<Record<string, Record<string, unknown>>>;
+/**
+ * Maps a tuple of memory layers to a typed object keyed by layer ID.
+ * Each layer's `provides` is flattened: data → value type, function → async callable.
+ * @public
+ */
+export type InferMemoryShape<T extends readonly MemoryLayer[]> = {
+    [L in T[number] as L extends {
+        readonly id: infer Id extends string;
+    } ? Id : never]: L extends {
+        provides: infer P;
+    } ? {
+        [K in keyof P]: P[K] extends LayerDataDecl<infer D, unknown> ? D : P[K] extends LayerFunctionDecl<infer I, infer O, unknown> ? (args: I) => Promise<O> : never;
+    } : Record<string, never>;
+};
+/**
+ * Typed wrapper around a tuple of memory layers. Preserves individual layer types
+ * for compile-time inference via `InferMemory<typeof config>`.
+ * @public
+ */
+export interface MemoryConfig<TLayers extends readonly MemoryLayer[] = readonly MemoryLayer[]> {
+    readonly layers: TLayers;
+    /** 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'];
+/** @public Well-known ordering slots for positioning memory layers in the recall/store pipeline. */
+export declare const Slot: {
+    readonly REMINDER: 80;
+    readonly STEERING: 90;
+    readonly WORKING_MEMORY: 100;
+    readonly ENTITY: 150;
+    readonly OBSERVATIONS: 200;
+    readonly PROCEDURAL: 250;
+    readonly EPISODIC: 300;
+    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>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+}
+/** @public Scope-namespaced storage interface provided to memory layer init hooks. */
+export interface ScopedStorage {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+}
+/** @public Parameters passed to a memory layer's `init` hook. */
+export interface InitParams {
+    storage: ScopedStorage;
+    scopeKey: string;
+    ctx: ExecutionContext;
+}
+/** @public Value returned by a memory layer's `init` hook, carrying the initial state. */
+export interface InitResult<TState> {
+    state: TState;
+}
+/** @public Parameters passed to a memory layer's `recall` hook before each LLM call. */
+export interface RecallParams<TState> {
+    log: ItemLog;
+    query: string;
+    ctx: ExecutionContext;
+    state: TState;
+    budget: number;
+}
+/** @public Value returned by a memory layer's `recall` hook, containing items and token count. */
+export interface RecallResult<TState = unknown> {
+    items: Item[];
+    tokenCount: number;
+    state?: TState;
+}
+/** @public Parameters passed to a memory layer's `store` hook after each LLM response. */
+export interface StoreParams<TState> {
+    newItems: Item[];
+    log: ItemLog;
+    response: LLMResponse;
+    ctx: ExecutionContext;
+    state: TState;
+}
+/** @public Value returned by a memory layer's `store` hook, carrying the updated state. */
+export interface StoreResult<TState> {
+    state: TState;
+}
+/** @public Parameters passed to a memory layer's `onSpawn` hook when a child execution starts. */
+export interface SpawnParams<TState> {
+    parentState: TState;
+    childCtx: ExecutionContext;
+}
+/** @public Value returned by a memory layer's `onSpawn` hook with the child's initial state. */
+export interface SpawnResult<TState> {
+    childState: TState | null;
+    items?: Item[];
+}
+/** @public Parameters passed to a memory layer's `onReturn` hook when a child execution completes. */
+export interface ReturnParams<TState> {
+    childState: TState;
+    childLog: ItemLog;
+    parentState: TState;
+    result: unknown;
+}
+/** @public Value returned by a memory layer's `onReturn` hook with the merged parent state. */
+export interface ReturnResult<TState> {
+    parentState: TState;
+    result?: unknown;
+}
+/** @public Parameters passed to a memory layer's `onComplete` hook at execution end. */
+export interface CompleteParams<TState> {
+    log: ItemLog;
+    ctx: ExecutionContext;
+    state: TState;
+    outcome: ExecutionOutcome;
+}
+/** @public Parameters passed to a memory layer's `dispose` hook during teardown. */
+export interface DisposeParams<TState> {
+    state: TState;
+}
+/** @public Parameters passed to a memory layer's `projectHistory` hook to project the history portion of the LLM context window. */
+export interface ProjectHistoryParams<TState> {
+    /** Full historical items from the item log, uncapped. */
+    items: ReadonlyArray<Item>;
+    /** Current execution context. */
+    ctx: ExecutionContext;
+    /** Layer's current state snapshot. */
+    state: TState;
+}
+/** @public Value returned by a memory layer's `projectHistory` hook, carrying the projected items. */
+export interface ProjectHistoryResult {
+    /** Items to send to the LLM as history. Typically a subset of the input. */
+    items: ReadonlyArray<Item>;
+}
+/** @public Controls which layers re-run recall() when a re-render is triggered. */
+export type RerenderScope = 'self' | 'slot-after' | 'all';
+/** @public Parameters passed to a memory layer's `onItemAppend` hook when input items are about to be appended. */
+export interface OnItemAppendParams<TState> {
+    /** Items to be appended (may have been transformed by prior layers in the pipeline). */
+    items: Item[];
+    /** Full item log (read-only). */
+    log: ItemLog;
+    /** Current execution context. */
+    ctx: ExecutionContext;
+    /** Layer's current state snapshot. */
+    state: TState;
+}
+/** @public Value returned by a memory layer's `onItemAppend` hook. */
+export interface OnItemAppendResult<TState> {
+    /**
+     * Items to actually append to the log.
+     * - Return original items unchanged to pass through
+     * - Return modified items to transform
+     * - Return empty array to filter/drop items
+     * - Return additional items to inject extras
+     */
+    items: Item[];
+    /** Updated layer state. */
+    state?: TState;
+    /** Request context re-render. */
+    rerender?: boolean;
+    /** When to apply re-render (default: layer's configured `rerenderTiming`). */
+    timing?: 'immediate' | 'batched';
+    /** Which layers to re-recall (default: 'slot-after'). */
+    scope?: RerenderScope;
+}
+/** @public Lifecycle hook implementations for a memory layer. Method syntax enables bivariant assignability for typed layers. */
+export interface MemoryHooks<TState = unknown> {
+    init?(params: InitParams): Promise<InitResult<TState>>;
+    recall?(params: RecallParams<TState>): Promise<RecallResult<TState> | string | null>;
+    store?(params: StoreParams<TState>): Promise<StoreResult<TState> | undefined>;
+    onSpawn?(params: SpawnParams<TState>): Promise<SpawnResult<TState> | null>;
+    onReturn?(params: ReturnParams<TState>): Promise<ReturnResult<TState> | undefined>;
+    onComplete?(params: CompleteParams<TState>): Promise<undefined | {
+        state: TState;
+    }>;
+    dispose?(params: DisposeParams<TState>): Promise<void>;
+    beforeToolCall?(params: BeforeToolCallParams<TState>): Promise<BeforeToolCallResult<TState>>;
+    afterModelCall?(params: AfterModelCallParams<TState>): Promise<AfterModelCallResult<TState>>;
+    /**
+     * Called when input items (user messages, tool outputs) are about to be appended.
+     * Returns items to append — enables filtering, transformation, and injection.
+     *
+     * Pipeline: items flow through layers in slot order. Each layer receives
+     * the output of the previous layer (or original items for first layer).
+     *
+     * NOT called for LLM response items — use `store()` for those.
+     */
+    onItemAppend?(params: OnItemAppendParams<TState>): Promise<OnItemAppendResult<TState>>;
+    /**
+     * Called once per LLM step to project (cap, transform) the history portion
+     * of the context window before assembleView. Layers compose in slot order:
+     * each receives the output of the previous layer. Storage (`itemLog`) is
+     * NOT mutated — this is a read-side projection only.
+     *
+     * Use for: capping history, summarising old turns, redacting items.
+     */
+    projectHistory?(params: ProjectHistoryParams<TState>): Promise<ProjectHistoryResult>;
+}
+/**
+ * A composable memory layer that participates in the recall/store lifecycle.
+ * @public
+ */
+export interface MemoryLayer<TState = unknown> {
+    /** Unique identifier for this layer instance. */
+    id: string;
+    /** Human-readable name for debugging and trace output. */
+    name?: string;
+    /** Ordering slot (lower = recalled first). Use `Slot` constants for well-known positions. */
+    slot: number;
+    /** Scope controlling state isolation: `'thread'`, `'resource'`, `'global'`, or `'execution'`. */
+    scope: MemoryScope;
+    /** Token budget: a fixed number, a `{ min, max }` range, or `'auto'` for dynamic allocation. */
+    budget?: BudgetConfig;
+    /** Lifecycle hooks invoked by the runtime at each phase (init, recall, store, etc.). */
+    hooks: MemoryHooks<TState>;
+    /** Per-hook timeout overrides in ms. */
+    timeouts?: Partial<LayerTimeouts>;
+    /** Typed functions and data exposed to code steps via `ctx.memory['layerId']` and automatically as LLM tools. */
+    provides?: LayerProvides;
+    /** Optional item schemas contributed by this layer, primarily for developer-role memory items. */
+    itemSchemas?: Pick<ItemSchemaExtensions, 'developerMessages' | 'items'>;
+    /** Default re-render timing when `onItemAppend` requests a re-render. */
+    rerenderTiming?: 'immediate' | 'batched';
+}
+/** @public Configuration for how the runtime projects conversation items into the model's context window. */
+export interface ProjectionPolicy {
+    tokenBudget: number;
+    responseReserve: number;
+    overflow: 'truncate' | 'summarize' | 'sliding_window';
+    overflowModel?: string;
+    windowSize?: number;
+}

package/dist/types/memory.js

@@ -0,0 +1,13 @@
+//#endregion
+/** @public Well-known ordering slots for positioning memory layers in the recall/store pipeline. */
+export const Slot = {
+    REMINDER: 80,
+    STEERING: 90,
+    WORKING_MEMORY: 100,
+    ENTITY: 150,
+    OBSERVATIONS: 200,
+    PROCEDURAL: 250,
+    EPISODIC: 300,
+    RAG: 350,
+    SEMANTIC_RECALL: 400,
+};

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

@@ -0,0 +1,13 @@
+import type { StepMeta, TokenUsage } from './common';
+import type { Context } from './context';
+import type { ContextMemory } from './memory';
+/**
+ * Internal-only interface for interpreter code that needs to mutate Context fields.
+ * NOT exported from the package public API.
+ */
+export interface MutableContext extends Context<ContextMemory> {
+    stepCount: number;
+    tokens: TokenUsage;
+    cost: number;
+    lastStepMeta: StepMeta | null;
+}

package/dist/types/mutable-context.js

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

package/dist/types/observability.d.ts

@@ -0,0 +1,30 @@
+/** @public A trace span representing a unit of work within the observability pipeline. */
+export interface Span {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId: string | null;
+    setAttribute(key: string, value: string | number | boolean): void;
+    addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+    end(): void;
+}
+/** @public Backend that receives and persists completed trace spans. */
+export interface TraceExporter {
+    export(spans: Span[]): Promise<void>;
+}
+/** @public Diagnostic span recording a single memory layer hook invocation and its outcome. */
+export interface MemoryTraceSpan {
+    layerId: string;
+    hook: 'init' | 'recall' | 'store' | 'onSpawn' | 'onReturn' | 'onComplete' | 'dispose';
+    durationMs: number;
+    status: 'ok' | 'error' | 'timeout' | 'skipped';
+    budget?: {
+        allocated: number;
+        used: number;
+        yielded: number;
+    };
+    itemCount?: number;
+    error?: {
+        message: string;
+        stack?: string;
+    };
+}

package/dist/types/observability.js

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

package/dist/types/runtime.d.ts

@@ -0,0 +1,255 @@
+import type { ZodType } from 'zod';
+import type { Channel, ChannelHandle, ExternalChannel } from './channel';
+import type { LLMResponse, ModelParams, Tool } from './common';
+import type { Context, CwdState } from './context';
+import type { DetachedHandle } from './detached';
+import type { FsAdapter } from './fs-adapter';
+import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result';
+import type { ExecuteInput, Item, ItemSchemaExtensions } from './items';
+import type { ContextMemory, MemoryLayer, StorageAdapter } from './memory';
+import type { Span } from './observability';
+import type { ShellAdapter } from './shell-adapter';
+import type { SteeringDecision } from './steering';
+import type { Step } from './step';
+import type { SubprocessAdapter } from './subprocess-adapter';
+/** @public Optional lifecycle hooks invoked before and after each step execution. */
+export interface AgentHooks {
+    beforeStep?: (step: Step, ctx: Context) => Promise<void>;
+    afterStep?: (step: Step, result: unknown, ctx: Context) => Promise<void>;
+}
+/** @public Top-level configuration object that defines an agent's model, tools, memory, and behavior. */
+export interface AgentConfig<TParams extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    storage?: StorageAdapter;
+    hooks?: AgentHooks;
+    params: TParams;
+    /** Harness-wide item schema extensions used to validate emitted and returned items. */
+    itemSchemas?: ItemSchemaExtensions;
+    /** Whether unknown extension item types must match a registered schema. Defaults to true. */
+    strictItemSchemas?: boolean;
+}
+/** @public How a message submitted during an active turn is delivered to the model.
+ *
+ *  - `next-turn` (default): queue the message; it becomes a new user turn after
+ *    the current turn completes.
+ *  - `between-rounds`: inject the message as an additional user item before the
+ *    next tool-round LLM call within the same turn. The model sees it partway
+ *    through. Mirrors Claude Code's inbox-attachment behaviour.
+ *  - `interrupt`: cancel the in-flight LLM stream, append the message, and
+ *    restart the turn from the merged history.
+ */
+export type DeliveryMode = 'next-turn' | 'between-rounds' | 'interrupt';
+/** @public Base fields shared by all callModel requests. */
+interface CallModelRequestBase {
+    model: string;
+    items: ReadonlyArray<Item>;
+    instructions?: string;
+    params?: ModelParams;
+    /** When provided, the harness sends a JSON Schema constraint to the model so it returns structured JSON. */
+    outputSchema?: ZodType;
+    /** Controls framework event emission. Defaults to `true`. Passed through from `StepLLM.emit`. */
+    emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
+    /** Optional signal for cancelling the in-flight call (used by session abort). */
+    signal?: AbortSignal;
+}
+/** @public Request shape when tools are provided — ctx is required for tool execution callbacks. */
+interface CallModelRequestWithTools extends CallModelRequestBase {
+    tools: Tool[];
+    ctx: Context;
+    layers?: MemoryLayer[];
+    /** When set, restricts which tools the model may invoke for this call. */
+    allowedToolNames?: string[];
+}
+/** @public Request shape when no tools are provided — ctx is only needed for tool
+ *  execution callbacks in convertTools, so it is omitted here. */
+interface CallModelRequestWithoutTools extends CallModelRequestBase {
+    tools?: undefined;
+    ctx?: undefined;
+    layers?: undefined;
+}
+/** @public Request object for `AgentHarnessContract.callModel()`. Encapsulates all parameters needed for an LLM call using only Noetic types. */
+export type CallModelRequest = CallModelRequestWithTools | CallModelRequestWithoutTools;
+/** @public Options for `AgentHarness.execute()` to configure the execution context. */
+export interface ExecuteOptions {
+    threadId?: string;
+    resourceId?: string;
+    state?: unknown;
+    /** Memory layers to apply to the execution context. Overrides harness-level memory if provided. */
+    memory?: MemoryLayer[];
+    /** Override the harness's default delivery mode for this message only. */
+    deliveryMode?: DeliveryMode;
+    /**
+     * Stable id used for the enqueued message. When provided, this id is emitted
+     * in the `turn_started` framework event (`messageIds`), allowing callers to
+     * correlate their own UI state (e.g. flipping a `queued` indicator to
+     * `sent`) with the message they submitted. A random id is generated when
+     * omitted.
+     */
+    messageId?: string;
+}
+/** @public Snapshot of a session's runtime state. */
+export type HarnessStatus = {
+    readonly kind: 'idle';
+} | {
+    readonly kind: 'generating';
+    readonly startedAt: number;
+    readonly turnId: string;
+} | {
+    readonly kind: 'aborting';
+    readonly turnId: string;
+};
+/** @public Identifies which session the accessor targets. All methods fall back to the harness's default thread when omitted. */
+export interface SessionScope {
+    threadId?: string;
+}
+/** @public Type-level contract for the agent runtime. Used for type annotations throughout the interpreter, memory layers, and context. Implemented by `AgentHarness`. */
+export interface AgentHarnessContract<TParams extends Record<string, unknown> = Record<string, unknown>> {
+    readonly config: AgentConfig<TParams>;
+    /** 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;
+    callModel(request: CallModelRequest): Promise<LLMResponse>;
+    /**
+     * Submit input to the agent. The message is enqueued on the session identified
+     * by `options.threadId` (or the default thread) and processed by the session
+     * runner according to the effective `DeliveryMode`.
+     *
+     * Returns once the message has been accepted into the queue — NOT when the
+     * model responds. Use `getAgentResponse()` or `getItemStream()` to observe
+     * the response.
+     */
+    execute(input: ExecuteInput, options?: ExecuteOptions): Promise<void>;
+    /**
+     * Resolves with the accumulated response once the session has finished
+     * processing its queue (status returns to `idle` with no pending messages).
+     */
+    getAgentResponse(scope?: SessionScope): Promise<HarnessResponse>;
+    /** Yields cumulative Item snapshots with isComplete flag across all turns in the session. */
+    getItemStream(scope?: SessionScope): AsyncIterable<StreamingItem>;
+    /** Yields text deltas as they arrive from the model, across all turns. */
+    getTextStream(scope?: SessionScope): AsyncIterable<string>;
+    /** Yields reasoning token deltas from reasoning-capable models, across all turns. */
+    getReasoningStream(scope?: SessionScope): AsyncIterable<string>;
+    /** Yields all raw stream events (SDK + framework) for the session. */
+    getFullStream(scope?: SessionScope): AsyncIterable<StreamEvent>;
+    /**
+     * Cancel the in-flight turn, if any. Queued messages are preserved — the
+     * runner re-kicks from the queue once abort completes.
+     */
+    abort(scope?: SessionScope & {
+        reason?: string;
+    }): Promise<void>;
+    /** Current runtime status of a session. */
+    getStatus(scope?: SessionScope): HarnessStatus;
+    /** Number of messages currently queued on a session. */
+    getQueueSize(scope?: SessionScope): number;
+    /**
+     * Pre-populate a session's accumulated history with prior items so the next
+     * `execute()` turn sees them as established context. Used by resume flows to
+     * seed a freshly-constructed session from a persisted transcript without
+     * re-running the prior turns. Creates the session lazily if it does not
+     * already exist. Replaces any previously-accumulated items for the session.
+     */
+    seedSessionHistory(threadId: string, items: ReadonlyArray<Item>): void;
+    run<I, O>(step: Step<ContextMemory, I, O>, input: I, ctx: Context): Promise<O>;
+    /**
+     * Launch `step` as a fire-and-forget background execution.
+     *
+     * The returned `DetachedHandle` exposes status / result / error and an
+     * `await()` for callers that want to block on settlement. The child runs
+     * concurrently with the caller; pass `overrides.threadId` to give the child
+     * its own session-scoped item log so background work does not pollute the
+     * parent's accumulated turn history.
+     *
+     * @param step Step to execute in a fresh child context.
+     * @param input Initial input passed to `step`.
+     * @param parentCtx Parent context (the child inherits memory layers and,
+     * by default, threadId/resourceId).
+     * @param overrides Optional: override threadId or resourceId on the child.
+     */
+    detachedSpawn<I, O>(step: Step<ContextMemory, I, O>, input: I, parentCtx: Context, overrides?: {
+        threadId?: string;
+        resourceId?: string;
+        /** Override the child's initial cwd. Used by worktree isolation to root the child at the worktree path. */
+        cwdInit?: string;
+    }): DetachedHandle<O>;
+    createContext(opts?: {
+        parent?: Context;
+        items?: Item[];
+        state?: unknown;
+        threadId?: string;
+        resourceId?: string;
+        memory?: MemoryLayer[];
+        /** Override the new context's initial cwd. */
+        cwdInit?: string;
+    }): Context;
+    /** Long-lived shared cwd state seeded into root contexts created by this harness. */
+    readonly rootCwdState: CwdState;
+    /** Update the harness root cwd. Used by the TUI when the user issues a `! cd`. */
+    setRootCwd(nextCwd: string): void;
+    send<T>(channel: Channel<T>, value: T, ctx: Context): void;
+    recv<T>(channel: Channel<T>, ctx: Context, opts?: {
+        timeout?: number;
+    }): Promise<T>;
+    tryRecv<T>(channel: Channel<T>, ctx: Context): T | null;
+    getChannelHandle<T>(channel: ExternalChannel<T>, executionId: string): ChannelHandle<T>;
+    initLayers(layers: MemoryLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
+    recallLayers(layers: MemoryLayer[], input: string, ctx: Context): Promise<RecallLayerOutput[]>;
+    /**
+     * Compute the items that would be sent to the model on the next turn for a
+     * session — its accumulated history plus the harness's memory-layer recall
+     * outputs assembled in the same order `executeLLM` produces.
+     */
+    previewRequestItems(scope?: SessionScope): Promise<ReadonlyArray<Item>>;
+    storeLayers(layers: MemoryLayer[], response: LLMResponse, ctx: Context): Promise<void>;
+    disposeLayers(layers: MemoryLayer[], ctx: Context): Promise<void>;
+    checkpoint(ctx: Context): Promise<void>;
+    restore(executionId: string): Promise<Context | null>;
+    cancel(ctx: Context, reason?: string): Promise<void>;
+    createSpan(name: string, parent: Span | null): Span;
+    getLayerState<T>(executionId: string, layerId: string): T | undefined;
+    setLayerState<T>(executionId: string, layerId: string, state: T): void;
+    beforeToolCall(layers: MemoryLayer[], toolName: string, toolArgs: unknown, ctx: Context): Promise<SteeringDecision>;
+    afterModelCall(layers: MemoryLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
+    /**
+     * Project the history items through every layer's `projectHistory` hook in
+     * slot order. Pure read-side projection — `itemLog` is never mutated.
+     * Returns the input unchanged if no layer registers the hook.
+     */
+    projectHistory(layers: MemoryLayer[], items: ReadonlyArray<Item>, ctx: Context): Promise<ReadonlyArray<Item>>;
+    /**
+     * Run items through the onItemAppend pipeline before appending.
+     * Each layer can filter, transform, or inject items.
+     * Returns final items to append and any re-render requests.
+     */
+    runAppendPipeline(layers: MemoryLayer[], items: Item[], ctx: Context): Promise<AppendPipelineResult>;
+    /**
+     * Execute re-render based on collected requests.
+     * Determines which layers need re-recall based on scope and runs them.
+     */
+    executeRerender(requests: RerenderRequest[], layers: MemoryLayer[], ctx: Context, budgets: Map<string, number>, query?: string): Promise<RecallLayerOutput[]>;
+}
+/** @public Output from a single memory layer's recall phase, including items and token budget used. */
+export interface RecallLayerOutput {
+    layerId: string;
+    items: Item[];
+    tokenCount: number;
+}
+/** @public A request to re-render the context window, collected from onItemAppend hooks. */
+export interface RerenderRequest {
+    layerId: string;
+    slot: number;
+    timing: 'immediate' | 'batched';
+    scope: 'self' | 'slot-after' | 'all';
+}
+/** @public Result of running items through the onItemAppend pipeline. */
+export interface AppendPipelineResult {
+    /** Final items to append after all transformations. */
+    items: Item[];
+    /** Re-render requests collected from layers. */
+    rerenderRequests: RerenderRequest[];
+}
+export {};

package/dist/types/runtime.js

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