@noetic-tools/core 0.0.1 → 0.1.1

package/dist/{runtime → harness}/agent-harness.d.ts

@@ -1,20 +1,9 @@
-import type { ZodType } from 'zod';
-import type { LayerStateStore } from '../memory/layer-lifecycle';
-import type { Channel, ChannelHandle, ExternalChannel } from '../types/channel';
-import type { LLMResponse, LlmProviderConfig } from '../types/common';
-import type { Context, CwdState } from '../types/context';
-import type { DetachedHandle } from '../types/detached';
-import type { FsAdapter } from '../types/fs-adapter';
-import type { HarnessResponse, StreamEvent, StreamingItem } from '../types/harness-result';
-import type { ExecuteInput, Item, ItemSchemaExtensions } from '../types/items';
-import type { ContextMemory, MemoryLayer, StorageAdapter } from '../types/memory';
-import type { Span, TraceExporter } from '../types/observability';
-import type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, DeliveryMode, ExecuteOptions, HarnessStatus, RecallLayerOutput, SessionScope } from '../types/runtime';
-import type { ShellAdapter } from '../types/shell-adapter';
-import type { SteeringDecision } from '../types/steering';
-import type { Step } from '../types/step';
-import type { SubprocessAdapter } from '../types/subprocess-adapter';
-import type { EventBroadcaster } from './event-broadcaster';
+import { ItemSchemaRegistry } from '../schemas/item.js';
+import type { DetachedSpawnOverrides } from './deps/interpreter.js';
+import type { LayerStateStore } from './deps/memory.js';
+import type { CheckpointStore, EventBroadcaster } from './deps/runtime.js';
+import type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextMemory, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, MemoryLayer, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
+export { createStreamIdleWatchdog } from './model-call.js';
 interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<string, unknown>> {
     name: string;
     initialStep?: Step<ContextMemory, string, string>;
@@ -22,6 +11,13 @@ interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<stri
     memory?: MemoryLayer[];
     storage?: StorageAdapter;
     hooks?: AgentHooks;
+    /**
+     * Harness-wide tool pool. Merged (identity-deduplicated) with tools
+     * collected from `initialStep` to form every context's `unifiedTools`.
+     * Use this when the workflow step tree is static and tools are supplied
+     * per harness instance rather than baked into individual `step.llm` calls.
+     */
+    tools?: Tool[];
     params: TParams;
     paramsSchema?: ZodType<TParams>;
     /** Filesystem adapter. Defaults to local node:fs when not provided. */
@@ -30,6 +26,13 @@ interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<stri
     shell?: ShellAdapter;
     /** Subprocess adapter. Defaults to an in-memory, same-process adapter. */
     subprocess?: SubprocessAdapter;
+    /**
+     * Checkpoint store used by `harness.checkpoint(ctx)` / `harness.restore()`.
+     * When absent, checkpoint/restore are no-ops — a zero-config harness keeps
+     * its current ephemeral semantics. Construct with `createCheckpointStore`
+     * to enable durable execution.
+     */
+    checkpointStore?: CheckpointStore;
     llm?: LlmProviderConfig;
     /** Harness-wide item schema extensions. */
     itemSchemas?: ItemSchemaExtensions;
@@ -54,19 +57,6 @@ interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<stri
     /** @internal Test-only escape hatch to inject a mock callModel implementation. */
     _testCallModel?: (request: CallModelRequest) => Promise<LLMResponse>;
 }
-interface StreamIdleWatchdog {
-    /** Bump the deadline because a stream event just arrived. */
-    reset: () => void;
-    /** Clear the pending timer. Safe to call multiple times. */
-    stop: () => void;
-}
-/** @internal Create a watchdog that aborts `controller` when no
- *  {@link StreamIdleWatchdog.reset reset} is called within `timeoutMs`. When
- *  `timeoutMs <= 0`, returns an inert no-op so callers can always call `.reset()`
- *  / `.stop()` without a branch. Starts armed: the caller is responsible for
- *  `.stop()` in a `finally`. `onTimeout` runs before the abort so observers can
- *  emit a framework event with the original cause. Exported only for unit tests. */
-export declare function createStreamIdleWatchdog(timeoutMs: number, controller: AbortController, onTimeout?: () => void): StreamIdleWatchdog;
 /**
  * Default agent harness for executing agent steps with built-in channel, memory, and trace support.
  * Provides channel store, memory layer lifecycle, and trace export with no external dependencies.
@@ -82,8 +72,19 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     readonly fs: FsAdapter;
     readonly shell: ShellAdapter;
     readonly subprocess: SubprocessAdapter;
+    /**
+     * Optional durable-execution store. When present, `checkpoint(ctx)` writes
+     * a `CheckpointSnapshot`; when absent, it's a no-op.
+     * @internal
+     */
+    readonly checkpointStore?: CheckpointStore;
     private readonly initialStep?;
-    private readonly _memory?;
+    /** Harness-wide tool pool merged into every context's `unifiedTools`. */
+    private readonly harnessTools;
+    /** @internal Memory layers configured for this harness. Exposed non-private
+     *  so free functions in `runtime/durable/` (checkpoint/restore) can read it
+     *  without friend-class gymnastics. Do not access from outside core. */
+    readonly _memory?: MemoryLayer[];
     private readonly client?;
     private readonly channelStore;
     private readonly callModelOverride?;
@@ -98,7 +99,10 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      * TUI — observe each other's `cd`s.
      */
     readonly rootCwdState: CwdState;
-    private readonly itemSchemas;
+    /** @internal Item schema registry. Exposed non-private so free functions
+     *  in `runtime/durable/` (restore) can parse persisted items. Do not
+     *  access from outside core. */
+    readonly itemSchemas: ItemSchemaRegistry;
     constructor(opts: AgentHarnessOpts<TParams>);
     /**
      * Update the harness-wide root cwd. The TUI calls this in response to a
@@ -122,20 +126,11 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     private getOrCreateSession;
     private requireSession;
     callModel(request: CallModelRequest): Promise<LLMResponse>;
-    /** @internal Drain only messages tagged `between-rounds` from the queue. */
-    private drainBetweenRoundsMessages;
     run<I, O>(s: Step<ContextMemory, I, O>, input: I, ctx: Context): Promise<O>;
     /** Run all layer `init` hooks before the first step executes. Per spec 11,
      *  init MUST complete before any recall fires so layer state is populated. */
     private initAndRun;
-    detachedSpawn<I, O>(s: Step<ContextMemory, I, O>, input: I, parentCtx: Context, overrides?: {
-        /** Override the child's thread id. Default inherits from `parentCtx.threadId`. */
-        threadId?: string;
-        /** Override the child's resource id. Default inherits from `parentCtx.resourceId`. */
-        resourceId?: string;
-        /** Override the child's initial cwd. Used by worktree isolation to root the child at the worktree path. */
-        cwdInit?: string;
-    }): DetachedHandle<O>;
+    detachedSpawn<I, O>(s: Step<ContextMemory, I, O>, input: I, parentCtx: Context, overrides?: DetachedSpawnOverrides): DetachedHandle<O>;
     createContext(opts?: {
         parent?: Context;
         items?: Item[];
@@ -174,8 +169,34 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     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>;
+    /**
+     * Snapshot the execution state at a checkpoint boundary.
+     *
+     * Fires at four well-defined points on the happy path:
+     *   1. End of every `execute()` that mutated the item log — so a crash
+     *      between turns lands on a snapshot that includes the user/assistant
+     *      items that actually flowed.
+     *   2. After `detachedSpawn()` settles (success or failure) — the parent's
+     *      record of running/completed children stays consistent with the
+     *      adapter's handle manifest.
+     *   3. After an ask-user enqueue — a restart can replay the pending modal
+     *      to the TUI.
+     *   4. After `runAppendPipeline` — layer state can mutate as items land,
+     *      so the snapshot must follow the mutation.
+     *
+     * Delegates to `captureCheckpoint` / `restoreFromCheckpoint` in
+     * `runtime/durable/harness-checkpoints` so the ~140 lines of snapshot
+     * logic live beside the other durability machinery.
+     */
+    checkpoint(ctx: Context): Promise<void>;
+    /**
+     * Rebuild a `Context` from a previously-persisted snapshot. Returns `null`
+     * if no snapshot is recorded for `executionId`. Surface a typed
+     * `NoeticConfigError(CHECKPOINT_SCHEMA_MISMATCH)` when the snapshot's
+     * schema version is unrecognised — the caller is expected to discard the
+     * checkpoint via `CheckpointStore.clear()` and start a fresh execution.
+     */
+    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;
@@ -203,4 +224,3 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
         tokenCount: number;
     }[]>;
 }
-export {};