@noetic-tools/core 0.0.1 → 0.1.1

package/dist/types/checkpoint.d.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+/**
+ * @public
+ * Literal schema version stamped on every `CheckpointSnapshot`. Bumped when a
+ * backward-incompatible change lands. `restore()` refuses to load snapshots
+ * whose version is not recognised and surfaces a typed `NoeticConfigError`
+ * (`code === 'CHECKPOINT_SCHEMA_MISMATCH'`) so hosts can discard cleanly.
+ */
+export declare const CheckpointSchemaVersion = 1;
+/**
+ * @public
+ * One entry in the execution frontier — a pointer to a step currently in
+ * flight on the parent's stack, plus the input/state snapshot required to
+ * resume it.
+ *
+ * The frontier is intentionally lenient: frame `state` is treated as an
+ * opaque JSON value because step `state` is user-defined. Parse/validate at
+ * the call site when specific shape guarantees are needed.
+ */
+export declare const FrontierFrameSchema: z.ZodObject<{
+    stepId: z.ZodString;
+    input: z.ZodUnknown;
+    state: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/** @public Shape of a single frontier frame serialised inside a snapshot. */
+export type FrontierFrame = z.infer<typeof FrontierFrameSchema>;
+/**
+ * @public
+ * Working-directory snapshot captured at checkpoint time. `current` is the
+ * active cwd; `previous` records the last value for parity with
+ * `CwdState.previousCwd` which tools use for `cd -`.
+ */
+export declare const CwdSnapshotSchema: z.ZodObject<{
+    current: z.ZodNullable<z.ZodString>;
+    previous: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** @public Cwd portion of a checkpoint snapshot. */
+export type CwdSnapshot = z.infer<typeof CwdSnapshotSchema>;
+/**
+ * @public
+ * Shape of an ask-user record that was pending at snapshot time. The actual
+ * schema is owned by the code-agent `AskUserService`; we only need the outer
+ * envelope here so the host can replay the queue into a restarted TUI modal.
+ */
+export declare const PendingAskUserSnapshotSchema: z.ZodObject<{
+    id: z.ZodString;
+    input: z.ZodUnknown;
+    createdAt: z.ZodNumber;
+}, z.core.$strip>;
+/** @public Pending ask-user record captured in a snapshot. */
+export type PendingAskUserSnapshot = z.infer<typeof PendingAskUserSnapshotSchema>;
+/**
+ * @public
+ * Item log state captured in a snapshot. We store the ordered list of items
+ * directly — the `ItemLogImpl` is append-only so the list is its own cursor.
+ *
+ * Items are carried as `unknown` here and re-parsed on restore via the
+ * harness's `ItemSchemaRegistry`, which is the same gate production traffic
+ * passes through.
+ */
+export declare const ItemLogSnapshotSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strip>;
+/** @public Item log portion of a snapshot. */
+export type ItemLogSnapshot = z.infer<typeof ItemLogSnapshotSchema>;
+/**
+ * @public
+ * Top-level checkpoint payload persisted through a `CheckpointStore`. Carries
+ * a schema version so forward-incompatible changes can be rejected cleanly
+ * instead of producing a silently corrupt restored context.
+ */
+export declare const CheckpointSnapshotSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    executionId: z.ZodString;
+    threadId: z.ZodOptional<z.ZodString>;
+    resourceId: z.ZodOptional<z.ZodString>;
+    frontier: z.ZodArray<z.ZodObject<{
+        stepId: z.ZodString;
+        input: z.ZodUnknown;
+        state: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+    layers: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    cwd: z.ZodNullable<z.ZodObject<{
+        current: z.ZodNullable<z.ZodString>;
+        previous: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    askUser: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        input: z.ZodUnknown;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>>;
+    itemLog: z.ZodObject<{
+        items: z.ZodArray<z.ZodUnknown>;
+    }, z.core.$strip>;
+    capturedAt: z.ZodString;
+}, z.core.$strip>;
+/** @public Snapshot of an execution suitable for `CheckpointStore.save()`. */
+export type CheckpointSnapshot = z.infer<typeof CheckpointSnapshotSchema>;

package/dist/types/checkpoint.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+//#region Schema
+/**
+ * @public
+ * Literal schema version stamped on every `CheckpointSnapshot`. Bumped when a
+ * backward-incompatible change lands. `restore()` refuses to load snapshots
+ * whose version is not recognised and surfaces a typed `NoeticConfigError`
+ * (`code === 'CHECKPOINT_SCHEMA_MISMATCH'`) so hosts can discard cleanly.
+ */
+export const CheckpointSchemaVersion = 1;
+/**
+ * @public
+ * One entry in the execution frontier — a pointer to a step currently in
+ * flight on the parent's stack, plus the input/state snapshot required to
+ * resume it.
+ *
+ * The frontier is intentionally lenient: frame `state` is treated as an
+ * opaque JSON value because step `state` is user-defined. Parse/validate at
+ * the call site when specific shape guarantees are needed.
+ */
+export const FrontierFrameSchema = z.object({
+    /** Stable id of the step this frame represents. */
+    stepId: z.string(),
+    /** Serialisable input delivered to the step when it started. */
+    input: z.unknown(),
+    /** Optional per-frame state snapshot. */
+    state: z.unknown().optional(),
+});
+/**
+ * @public
+ * Working-directory snapshot captured at checkpoint time. `current` is the
+ * active cwd; `previous` records the last value for parity with
+ * `CwdState.previousCwd` which tools use for `cd -`.
+ */
+export const CwdSnapshotSchema = z.object({
+    current: z.string().nullable(),
+    previous: z.string().nullish(),
+});
+/**
+ * @public
+ * Shape of an ask-user record that was pending at snapshot time. The actual
+ * schema is owned by the code-agent `AskUserService`; we only need the outer
+ * envelope here so the host can replay the queue into a restarted TUI modal.
+ */
+export const PendingAskUserSnapshotSchema = z.object({
+    id: z.string(),
+    input: z.unknown(),
+    createdAt: z.number(),
+});
+/**
+ * @public
+ * Item log state captured in a snapshot. We store the ordered list of items
+ * directly — the `ItemLogImpl` is append-only so the list is its own cursor.
+ *
+ * Items are carried as `unknown` here and re-parsed on restore via the
+ * harness's `ItemSchemaRegistry`, which is the same gate production traffic
+ * passes through.
+ */
+export const ItemLogSnapshotSchema = z.object({
+    items: z.array(z.unknown()),
+});
+/**
+ * @public
+ * Top-level checkpoint payload persisted through a `CheckpointStore`. Carries
+ * a schema version so forward-incompatible changes can be rejected cleanly
+ * instead of producing a silently corrupt restored context.
+ */
+export const CheckpointSnapshotSchema = z.object({
+    schemaVersion: z.literal(CheckpointSchemaVersion),
+    executionId: z.string(),
+    threadId: z.string().optional(),
+    resourceId: z.string().optional(),
+    frontier: z.array(FrontierFrameSchema),
+    layers: z.record(z.string(), z.unknown()),
+    cwd: CwdSnapshotSchema.nullable(),
+    askUser: z.array(PendingAskUserSnapshotSchema),
+    itemLog: ItemLogSnapshotSchema,
+    /** ISO-8601 timestamp of when the snapshot was taken. */
+    capturedAt: z.string(),
+});
+//#endregion

package/dist/types/common.d.ts

@@ -1,7 +1,4 @@
-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>>;
+import type { FunctionCallItem, Item } from './items.js';
 /**
  * Policy controlling automatic retry behavior on step failure.
  * @public
@@ -30,51 +27,6 @@ export interface ModelParams {
     /** 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;
@@ -108,4 +60,3 @@ export interface LlmProviderConfig {
     provider: 'openrouter';
     apiKey?: string;
 }
-export {};

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

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

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

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

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

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

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

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

package/dist/types/context.d.ts

@@ -1,18 +1,19 @@
-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;
-}
+import type { ZodType } from 'zod';
+import type { ItemSchemaRegistry } from '../schemas/item.js';
+import type { Channel, ChannelHandle, ExternalChannel } from './channel.js';
+import type { LLMResponse, ModelParams, StepMeta, TokenUsage } from './common.js';
+import type { ItemLog } from './context-parts/item-log.js';
+import type { LastLayerUsage } from './context-parts/layer-usage.js';
+import type { DetachedHandle } from './detached.js';
+import type { FsAdapter } from './fs-adapter.js';
+import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result.js';
+import type { ExecuteInput } from './items.js';
+import type { ContextMemory, MemoryLayer, StorageAdapter } from './memory.js';
+import type { Span } from './observability.js';
+import type { ShellAdapter } from './shell-adapter.js';
+import type { SteeringDecision } from './steering.js';
+import type { SubprocessAdapter } from './subprocess-adapter.js';
+import type { Tool } from './tool.js';
 /**
  * @public Mutable working-directory state shared among the tools attached to a
  * single Context. The reference is fixed for the Context's lifetime; mutate
@@ -24,22 +25,129 @@ 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>;
+export type ContextHarnessStatus = {
+    readonly kind: 'idle';
+} | {
+    readonly kind: 'generating';
+    readonly startedAt: number;
+    readonly turnId: string;
+} | {
+    readonly kind: 'aborting';
+    readonly turnId: string;
+};
+interface ContextCallModelRequestBase {
+    model: string;
+    items: ReadonlyArray<import('./items.js').Item>;
+    instructions?: string;
+    params?: ModelParams;
+    outputSchema?: ZodType;
+    emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
+    signal?: AbortSignal;
+}
+interface ContextCallModelRequestWithTools extends ContextCallModelRequestBase {
+    tools: Tool[];
+    ctx: Context;
+    layers?: MemoryLayer[];
+    allowedToolNames?: string[];
+}
+interface ContextCallModelRequestWithoutTools extends ContextCallModelRequestBase {
+    tools?: undefined;
+    ctx?: undefined;
+    layers?: undefined;
+}
+export type ContextCallModelRequest = ContextCallModelRequestWithTools | ContextCallModelRequestWithoutTools;
+export interface ContextDetachedSpawnOverrides {
+    threadId?: string;
+    resourceId?: string;
+    cwdInit?: string;
 }
-/** @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;
+export interface ContextRerenderRequest {
+    layerId: string;
+    slot: number;
+    timing: 'immediate' | 'batched';
+    scope: 'self' | 'slot-after' | 'all';
+}
+export interface ContextAppendPipelineResult {
+    readonly items: import('./items.js').Item[];
+    readonly rerenderRequests: ContextRerenderRequest[];
+}
+export interface ContextRecallLayerOutput {
+    layerId: string;
+    items: import('./items.js').Item[];
+    tokenCount: number;
+}
+export type ContextStep<TMemory = ContextMemory, I = unknown, O = unknown> = {
+    readonly kind: 'run';
+    readonly id: string;
+    readonly execute: (input: I, ctx: Context<TMemory>) => Promise<O>;
+} | {
+    readonly kind: 'llm';
+    readonly id: string;
+    readonly output?: ZodType<O>;
+} | {
+    readonly kind: 'loop';
+    readonly id: string;
+    readonly steps: ReadonlyArray<ContextStep<TMemory, I, O>>;
+    readonly prepareNext?: (output: O, verdict: unknown, ctx: Context<TMemory>) => I;
+} | {
+    readonly kind: string;
+    readonly id: string;
+};
+/** @public Runtime surface exposed on Context without coupling Context's definition to the runtime type module. */
+export interface ContextHarness {
+    readonly config: {
+        readonly name: string;
+        readonly params: Record<string, unknown>;
+    };
+    readonly fs: FsAdapter;
+    readonly shell: ShellAdapter;
+    readonly subprocess: SubprocessAdapter;
+    readonly rootCwdState: CwdState;
+    callModel(request: ContextCallModelRequest): Promise<LLMResponse>;
+    execute(input: ExecuteInput, options?: unknown): Promise<void>;
+    getAgentResponse(scope?: unknown): Promise<HarnessResponse>;
+    getItemStream(scope?: unknown): AsyncIterable<StreamingItem>;
+    getTextStream(scope?: unknown): AsyncIterable<string>;
+    getReasoningStream(scope?: unknown): AsyncIterable<string>;
+    getFullStream(scope?: unknown): AsyncIterable<StreamEvent>;
+    run<I, O>(step: ContextStep<ContextMemory, I, O>, input: I, ctx: Context): Promise<O>;
+    detachedSpawn<I, O>(step: unknown, input: I, parentCtx: Context, overrides?: ContextDetachedSpawnOverrides): DetachedHandle<O>;
+    createContext(opts?: {
+        parent?: Context;
+        items?: import('./items.js').Item[];
+        state?: unknown;
+        threadId?: string;
+        resourceId?: string;
+        memory?: MemoryLayer[];
+        cwdInit?: string;
+    }): Context;
+    setRootCwd(nextCwd: string): void;
+    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>;
+    runAppendPipeline(layers: MemoryLayer[], items: import('./items.js').Item[], ctx: Context): Promise<ContextAppendPipelineResult>;
+    recallLayers(layers: MemoryLayer[], input: string, ctx: Context): Promise<ContextRecallLayerOutput[]>;
+    projectHistory(layers: MemoryLayer[], items: ReadonlyArray<import('./items.js').Item>, ctx: Context): Promise<ReadonlyArray<import('./items.js').Item>>;
+    storeLayers(layers: MemoryLayer[], response: LLMResponse, ctx: Context): Promise<void>;
+    previewRequestItems(scope?: unknown): Promise<ReadonlyArray<import('./items.js').Item>>;
+    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>;
+    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;
+    abort(scope?: unknown): Promise<void>;
+    getStatus(scope?: unknown): ContextHarnessStatus;
+    getQueueSize(scope?: unknown): number;
+    seedSessionHistory(threadId: string, items: ReadonlyArray<import('./items.js').Item>): void;
+    executeRerender(requests: ContextRerenderRequest[], layers: MemoryLayer[], ctx: Context, budgets: Map<string, number>, query?: string): Promise<ContextRecallLayerOutput[]>;
 }
 /** @public Execution context threaded through every step, carrying state, metrics, and channels. */
 export interface Context<TMemory = ContextMemory, TState = unknown> {
@@ -58,7 +166,7 @@ export interface Context<TMemory = ContextMemory, TState = unknown> {
     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;
+    readonly harness: ContextHarness;
     /** Filesystem adapter for virtual or real filesystem access. */
     readonly fs: FsAdapter;
     /** Shell adapter for virtual or real shell command execution. */
@@ -91,3 +199,4 @@ export interface Context<TMemory = ContextMemory, TState = unknown> {
     readonly abortReason?: string;
     abort(reason?: string): void;
 }
+export {};

package/dist/types/error.d.ts

@@ -48,4 +48,19 @@ export type NoeticError = {
 } | {
     kind: 'steering_denied';
     guidance?: string;
+} | {
+    /**
+     * Raised by `DetachedHandle.await()` when the adapter persistently
+     * returns `null` for a handle that was previously spawned — the
+     * handle has been evicted from the adapter's registry, either by
+     * a restart-after-stop-without-restore flow or by a storage
+     * inconsistency. This guards against an otherwise-infinite poll
+     * loop that would hold the promise open forever. A short grace
+     * period tolerates transient nulls (e.g. the in-memory adapter
+     * briefly returning null between spawn and first microtask yield).
+     */
+    kind: 'handle_evicted';
+    handleId: string;
+    stepId: string;
+    gracePeriodMs: number;
 };

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

@@ -1,5 +1,5 @@
-import type { LastLayerUsage } from './context';
-import type { Item } from './items';
+import type { LastLayerUsage } from './context-parts/layer-usage.js';
+import type { Item } from './items.js';
 /** @public SDK-originated event from the OpenResponses streaming API. */
 export interface SdkStreamEvent {
     readonly source: 'sdk';

package/dist/types/items.d.ts

@@ -29,12 +29,28 @@ export interface InputTextPart {
     readonly type: 'input_text';
     readonly text: string;
 }
+/** @public User image input content. */
+export interface InputImagePart {
+    readonly type: 'input_image';
+    readonly imageUrl: string;
+    readonly detail?: 'auto' | 'low' | 'high';
+}
+/** @public User file input content. */
+export interface InputFilePart {
+    readonly type: 'input_file';
+    readonly fileData?: string;
+    readonly fileId?: string | null;
+    readonly fileUrl?: string;
+    readonly filename?: string;
+}
 /** @public Reasoning trace content. */
 export type ReasoningTextPart = ReasoningTextContent;
 /** @public Reasoning summary content. */
 export type SummaryTextPart = ReasoningSummaryText;
+/** @public User/developer input content variants. */
+export type InputContentPart = InputTextPart | InputImagePart | InputFilePart;
 /** @public Content part variants for message items. */
-export type ContentPart = OutputTextPart | RefusalPart | InputTextPart;
+export type ContentPart = OutputTextPart | RefusalPart | InputContentPart;
 /** @public Assistant message output item. */
 export type MessageItem = ResponsesOutputMessage;
 /** @public Function call requested by the model. */
@@ -68,7 +84,7 @@ export interface InputMessageItem {
     readonly type: 'message';
     readonly role: 'user' | 'system' | 'developer';
     readonly status: 'in_progress' | 'completed' | 'incomplete' | 'failed';
-    readonly content: InputTextPart[];
+    readonly content: InputContentPart[];
 }
 /**
  * @public Tool execution output created by the harness during the tool loop.

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

@@ -0,0 +1,39 @@
+import type { LLMResponse } from './common.js';
+import type { FsAdapter } from './fs-adapter.js';
+import type { Item } from './items.js';
+import type { ShellAdapter } from './shell-adapter.js';
+/** @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 {};