@noetic-tools/core 0.0.1 → 0.1.0

package/dist/runtime/durable/checkpoint-store.js

@@ -0,0 +1,101 @@
+import { NoeticConfigError } from '../../errors/noetic-config-error';
+import { CheckpointSnapshotSchema } from '../../types/checkpoint';
+//#region Keys
+/**
+ * Typed key constants for the checkpoint namespace. Every execution snapshot
+ * lives under a single key so `save`/`load` are cheap single `get`/`set`
+ * calls, while a `list` prefix enumeration exposes every known execution id
+ * to the restart/reattach path. Auxiliary suffixes exist so future sharded
+ * storage schemes can still co-locate snapshot fragments under a shared
+ * execution prefix without bumping schemaVersion.
+ *
+ * @internal
+ */
+const EXEC_KEY_PREFIX = 'execution:';
+const SNAPSHOT_SUFFIX = ':snapshot';
+const FRONTIER_SUFFIX = ':frontier';
+const LAYERS_SUFFIX = ':layers:';
+const CWD_SUFFIX = ':cwd';
+const ASK_USER_SUFFIX = ':askUser';
+const ITEM_LOG_SUFFIX = ':itemLog';
+export const CheckpointKeys = {
+    ExecPrefix: EXEC_KEY_PREFIX,
+    SnapshotSuffix: SNAPSHOT_SUFFIX,
+    FrontierSuffix: FRONTIER_SUFFIX,
+    LayersSuffix: LAYERS_SUFFIX,
+    CwdSuffix: CWD_SUFFIX,
+    AskUserSuffix: ASK_USER_SUFFIX,
+    ItemLogSuffix: ITEM_LOG_SUFFIX,
+};
+//#endregion
+//#region Helpers
+function snapshotKey(executionId) {
+    return `${EXEC_KEY_PREFIX}${executionId}${SNAPSHOT_SUFFIX}`;
+}
+function executionIdFromSnapshotKey(key) {
+    if (!key.startsWith(EXEC_KEY_PREFIX) || !key.endsWith(SNAPSHOT_SUFFIX)) {
+        return null;
+    }
+    const start = EXEC_KEY_PREFIX.length;
+    const end = key.length - SNAPSHOT_SUFFIX.length;
+    if (end <= start) {
+        return null;
+    }
+    return key.slice(start, end);
+}
+function isJsonRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function parseSnapshot(raw, executionId) {
+    const parsed = CheckpointSnapshotSchema.safeParse(raw);
+    if (parsed.success) {
+        return parsed.data;
+    }
+    const observedVersion = isJsonRecord(raw) && 'schemaVersion' in raw ? raw.schemaVersion : 'unknown';
+    throw new NoeticConfigError({
+        code: 'CHECKPOINT_SCHEMA_MISMATCH',
+        message: `Checkpoint snapshot for execution "${executionId}" failed schema validation (observed schemaVersion=${String(observedVersion)}).`,
+        hint: 'The snapshot was produced by a different runtime version. Clear the snapshot via CheckpointStore.clear() and restart the execution.',
+    });
+}
+//#endregion
+//#region Factory
+export function createCheckpointStore(options) {
+    const { storage } = options;
+    async function save(snapshot) {
+        // Persisted shape is the validated snapshot. The adapter is free to
+        // JSON-encode it internally; `InMemoryStorage` stores by reference which
+        // is fine because `CheckpointSnapshotSchema.parse` is deep-immutable.
+        await storage.set(snapshotKey(snapshot.executionId), snapshot);
+    }
+    async function load(executionId) {
+        const raw = await storage.get(snapshotKey(executionId));
+        if (raw === null) {
+            return null;
+        }
+        return parseSnapshot(raw, executionId);
+    }
+    async function list() {
+        const keys = await storage.list(EXEC_KEY_PREFIX);
+        const out = [];
+        for (const key of keys) {
+            const id = executionIdFromSnapshotKey(key);
+            if (id !== null) {
+                out.push({
+                    executionId: id,
+                });
+            }
+        }
+        return out;
+    }
+    async function clear(executionId) {
+        await storage.delete(snapshotKey(executionId));
+    }
+    return {
+        save,
+        load,
+        list,
+        clear,
+    };
+}
+//#endregion

package/dist/runtime/durable/detached-signal.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Deferred-style, single-shot signal used to wire a detached child — a
+ * terminal tool, an IPC handler, an external watchdog — back to the
+ * parent that awaits its outcome.
+ *
+ * The pattern is intentionally minimal: the parent awaits `signal.done`
+ * while the child calls `signal.resolve(outcome)` (or `signal.reject(err)`)
+ * when it has produced the final value. Any subsequent `resolve` /
+ * `reject` calls are silently dropped so a late-arriving duplicate
+ * settlement never overwrites the first.
+ *
+ * This is the canonical primitive the `runnableLoop` (and the task
+ * runner scripts that use it) build on. Keeping it in core means every
+ * out-of-process worker / detached step shares one signal shape rather
+ * than each reinventing the single-shot-deferred.
+ */
+/** Single-shot deferred signal the caller awaits via `.done`. */
+export interface DetachedSignal<TOutcome> {
+    readonly done: Promise<TOutcome>;
+    /**
+     * Settle the signal with a success outcome. Only the first call has
+     * effect; subsequent calls (from retry logic, duplicate terminal
+     * tool invocations, external signal handlers) are dropped silently.
+     */
+    resolve(outcome: TOutcome): void;
+    /**
+     * Settle the signal with a failure. Only the first call has effect;
+     * a `resolve` that races with a `reject` wins by whichever runs
+     * first — both further attempts are dropped.
+     */
+    reject(err: unknown): void;
+}
+/**
+ * Construct a fresh single-shot `DetachedSignal<TOutcome>`. The returned
+ * signal's `done` Promise resolves/rejects at most once.
+ */
+export declare function createDetachedSignal<TOutcome>(): DetachedSignal<TOutcome>;

package/dist/runtime/durable/detached-signal.js

@@ -0,0 +1,52 @@
+/**
+ * Deferred-style, single-shot signal used to wire a detached child — a
+ * terminal tool, an IPC handler, an external watchdog — back to the
+ * parent that awaits its outcome.
+ *
+ * The pattern is intentionally minimal: the parent awaits `signal.done`
+ * while the child calls `signal.resolve(outcome)` (or `signal.reject(err)`)
+ * when it has produced the final value. Any subsequent `resolve` /
+ * `reject` calls are silently dropped so a late-arriving duplicate
+ * settlement never overwrites the first.
+ *
+ * This is the canonical primitive the `runnableLoop` (and the task
+ * runner scripts that use it) build on. Keeping it in core means every
+ * out-of-process worker / detached step shares one signal shape rather
+ * than each reinventing the single-shot-deferred.
+ */
+//#endregion
+//#region Public API
+/**
+ * Construct a fresh single-shot `DetachedSignal<TOutcome>`. The returned
+ * signal's `done` Promise resolves/rejects at most once.
+ */
+export function createDetachedSignal() {
+    let resolveFn = null;
+    let rejectFn = null;
+    const done = new Promise((resolve, reject) => {
+        resolveFn = resolve;
+        rejectFn = reject;
+    });
+    return {
+        done,
+        resolve(outcome) {
+            if (resolveFn === null) {
+                return;
+            }
+            const fn = resolveFn;
+            resolveFn = null;
+            rejectFn = null;
+            fn(outcome);
+        },
+        reject(err) {
+            if (rejectFn === null) {
+                return;
+            }
+            const fn = rejectFn;
+            resolveFn = null;
+            rejectFn = null;
+            fn(err);
+        },
+    };
+}
+//#endregion

package/dist/runtime/durable/harness-checkpoints.d.ts

@@ -0,0 +1,51 @@
+import type { LayerStateStore } from '../../memory/layer-lifecycle';
+import type { ItemSchemaRegistry } from '../../schemas/item';
+import type { Context } from '../../types/context';
+import type { Item } from '../../types/items';
+import type { MemoryLayer } from '../../types/memory';
+import type { CheckpointStore } from './checkpoint-store';
+/**
+ * Minimum harness surface `captureCheckpoint` / `restoreFromCheckpoint`
+ * require. `AgentHarness` already satisfies this shape via its
+ * `@internal` readonly fields — defining it structurally keeps the free
+ * functions loosely coupled to the harness implementation.
+ *
+ * @internal
+ */
+export interface CheckpointHarnessHandle {
+    readonly checkpointStore?: CheckpointStore;
+    readonly layerStateStore: LayerStateStore;
+    readonly itemSchemas: ItemSchemaRegistry;
+    readonly _memory?: MemoryLayer[];
+    createContext(opts?: {
+        items?: Item[];
+        threadId?: string;
+        resourceId?: string;
+        cwdInit?: string;
+        memory?: MemoryLayer[];
+    }): Context;
+}
+/**
+ * Snapshot the execution state at a checkpoint boundary. No-op when no
+ * `CheckpointStore` is configured — zero-config harnesses preserve
+ * ephemeral semantics. Save failures are logged rather than thrown,
+ * because a checkpoint failing must never abort an otherwise-successful
+ * step.
+ *
+ * @internal
+ */
+export declare function captureCheckpoint(h: CheckpointHarnessHandle, ctx: Context): Promise<void>;
+/**
+ * Rebuild a `Context` from a previously-persisted snapshot. Returns
+ * `null` if no snapshot is recorded for `executionId`. Layer state is
+ * replayed into `layerStateStore` keyed by the original executionId so
+ * the restored context observes the pre-crash state through
+ * `readLayerState` and the memory projectors.
+ *
+ * Preserves the original executionId on the returned context via
+ * `Object.defineProperty` — adapter correlation across crash/restart
+ * requires a stable id.
+ *
+ * @internal
+ */
+export declare function restoreFromCheckpoint(h: CheckpointHarnessHandle, executionId: string): Promise<Context | null>;

package/dist/runtime/durable/harness-checkpoints.js

@@ -0,0 +1,104 @@
+import { CheckpointSchemaVersion } from '../../types/checkpoint';
+import { ContextImpl } from '../context-impl';
+//#endregion
+//#region captureCheckpoint
+/**
+ * Snapshot the execution state at a checkpoint boundary. No-op when no
+ * `CheckpointStore` is configured — zero-config harnesses preserve
+ * ephemeral semantics. Save failures are logged rather than thrown,
+ * because a checkpoint failing must never abort an otherwise-successful
+ * step.
+ *
+ * @internal
+ */
+export async function captureCheckpoint(h, ctx) {
+    const store = h.checkpointStore;
+    if (!store) {
+        return;
+    }
+    const impl = ctx instanceof ContextImpl ? ctx : null;
+    const frontier = impl ? impl.serialiseFrontier() : [];
+    const layers = {};
+    for (const layer of ctx.layers ?? []) {
+        const state = h.layerStateStore.get(ctx.id, layer.id);
+        if (state !== undefined) {
+            layers[layer.id] = state;
+        }
+    }
+    const snapshot = {
+        schemaVersion: CheckpointSchemaVersion,
+        executionId: ctx.id,
+        threadId: ctx.threadId,
+        resourceId: ctx.resourceId,
+        frontier,
+        layers,
+        cwd: {
+            current: ctx.cwdState.cwd,
+            previous: ctx.cwdState.previousCwd,
+        },
+        // Ask-user queue snapshot is empty at the core layer — the code-agent
+        // host is responsible for pushing pending prompts through this store
+        // via `AskUserService` integration. Carrying the shape from day one
+        // means future producers don't bump the schema version.
+        askUser: [],
+        itemLog: {
+            items: [
+                ...ctx.itemLog.items,
+            ],
+        },
+        capturedAt: new Date().toISOString(),
+    };
+    try {
+        await store.save(snapshot);
+    }
+    catch (err) {
+        console.warn(`AgentHarness.checkpoint: failed to persist snapshot for execution "${ctx.id}":`, err);
+    }
+}
+//#endregion
+//#region restoreFromCheckpoint
+/**
+ * Rebuild a `Context` from a previously-persisted snapshot. Returns
+ * `null` if no snapshot is recorded for `executionId`. Layer state is
+ * replayed into `layerStateStore` keyed by the original executionId so
+ * the restored context observes the pre-crash state through
+ * `readLayerState` and the memory projectors.
+ *
+ * Preserves the original executionId on the returned context via
+ * `Object.defineProperty` — adapter correlation across crash/restart
+ * requires a stable id.
+ *
+ * @internal
+ */
+export async function restoreFromCheckpoint(h, executionId) {
+    const store = h.checkpointStore;
+    if (!store) {
+        return null;
+    }
+    const snapshot = await store.load(executionId);
+    if (!snapshot) {
+        return null;
+    }
+    for (const [layerId, state] of Object.entries(snapshot.layers)) {
+        h.layerStateStore.set(executionId, layerId, state);
+    }
+    const items = h.itemSchemas.parseMany(snapshot.itemLog.items);
+    const cwdInit = snapshot.cwd?.current ?? undefined;
+    const ctx = h.createContext({
+        items,
+        threadId: snapshot.threadId,
+        resourceId: snapshot.resourceId,
+        cwdInit,
+        memory: h._memory,
+    });
+    if (ctx instanceof ContextImpl) {
+        Object.defineProperty(ctx, 'id', {
+            value: executionId,
+            configurable: false,
+            writable: false,
+            enumerable: true,
+        });
+    }
+    return ctx;
+}
+//#endregion

package/dist/runtime/durable/index.d.ts

@@ -0,0 +1,10 @@
+export type { CheckpointStore, CreateCheckpointStoreOptions } from './checkpoint-store';
+export { CheckpointKeys, createCheckpointStore } from './checkpoint-store';
+export type { DetachedSignal } from './detached-signal';
+export { createDetachedSignal } from './detached-signal';
+export type { AfterFirstTurnContext, RunnableLoopHarness, RunnableLoopOpts } from './runnable-loop';
+export { runnableLoop } from './runnable-loop';
+export type { SessionSeedHarness } from './session-seed';
+export { seedFromItems } from './session-seed';
+export type { CreateNudgeMessageOpts, StallNudgeOpts } from './stall-nudge';
+export { createNudgeMessage, createStallNudgeHook, DEFAULT_NUDGE_MESSAGE_TEXT, } from './stall-nudge';

package/dist/runtime/durable/index.js

@@ -0,0 +1,5 @@
+export { CheckpointKeys, createCheckpointStore } from './checkpoint-store';
+export { createDetachedSignal } from './detached-signal';
+export { runnableLoop } from './runnable-loop';
+export { seedFromItems } from './session-seed';
+export { createNudgeMessage, createStallNudgeHook, DEFAULT_NUDGE_MESSAGE_TEXT, } from './stall-nudge';

package/dist/runtime/durable/runnable-loop.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Drive a generic agent-harness chat session for a detached runner.
+ *
+ * The loop is intentionally minimal. A "runnable" is any harness
+ * driven through the standard `execute()` path plus a single-shot
+ * `DetachedSignal` its terminal tool resolves:
+ *
+ *   1. **Resume spawn** — when `priorItems` is non-empty, seed the
+ *      session history and hand control straight to the caller's
+ *      signal. The agent's prior turns are already on record; the next
+ *      turn comes from external input (IPC `send` frame, autopilot
+ *      respawn, etc.) rather than being re-kicked here.
+ *   2. **Fresh spawn** — when `priorItems` is empty (or omitted) and
+ *      an `initialMessage` is supplied, execute that framing message
+ *      as the first turn. The harness's own stream pumps persist the
+ *      emitted items via whatever session store the caller wired up.
+ *   3. **Post-turn hook** — if `afterFirstTurn` is supplied, run it
+ *      once the first turn has settled microtasks. The hook sees
+ *      whether the signal already resolved during the turn so it can
+ *      short-circuit its own logic (e.g. the stall-nudge helper skips
+ *      its nudge when the agent already called a terminal tool).
+ *   4. **Await outcome** — finally, return `signal.done`. If no
+ *      terminal tool ever resolves it, the signal rejects externally
+ *      (SIGTERM handler, process abort) or simply never settles — the
+ *      caller owns that concern.
+ *
+ * The loop has no opinions about where `priorItems` come from, how the
+ * `initialMessage` is built, or what the terminal outcome looks like.
+ * Task-specific logic (chat.jsonl reads, role framing, stall
+ * escalation) lives in the caller and composes via the `afterFirstTurn`
+ * hook.
+ */
+import type { HarnessResponse } from '../../types/harness-result';
+import type { ExecuteInput, Item } from '../../types/items';
+import type { ExecuteOptions, SessionScope } from '../../types/runtime';
+import type { DetachedSignal } from './detached-signal';
+/**
+ * Minimum harness surface the loop calls into. Defining this
+ * structurally keeps the loop loosely coupled — the concrete
+ * `AgentHarness<P>` already satisfies the shape, as does a test stub
+ * that only stands up `seedSessionHistory` + `execute` + `getAgentResponse`.
+ *
+ * `getAgentResponse` is REQUIRED because `execute()` only enqueues a
+ * message and returns before the turn actually runs. The loop awaits
+ * `getAgentResponse(scope)` to observe real turn completion before
+ * handing to `afterFirstTurn` — without this, stall detection fires
+ * before the agent has produced any output and flags every run as
+ * stalled.
+ */
+export interface RunnableLoopHarness {
+    seedSessionHistory(threadId: string, items: ReadonlyArray<Item>): void;
+    execute(input: ExecuteInput, options?: ExecuteOptions): Promise<void>;
+    getAgentResponse(scope?: SessionScope): Promise<HarnessResponse>;
+}
+/**
+ * Read-only view the `afterFirstTurn` hook uses to decide whether the
+ * signal settled during the turn it just observed. Consumers call
+ * `signalSettled()` (not a direct property read) so a late-settle
+ * caused by microtask ordering still propagates.
+ */
+export interface AfterFirstTurnContext {
+    /** True if `signal.done` has resolved or rejected. */
+    signalSettled(): boolean;
+}
+export interface RunnableLoopOpts<TOutcome> {
+    readonly harness: RunnableLoopHarness;
+    readonly threadId: string;
+    /**
+     * Prior session items to seed before the first turn. When non-empty
+     * the loop skips `initialMessage` entirely (resume path); when empty
+     * or omitted it proceeds with the fresh-spawn sequence.
+     */
+    readonly priorItems?: ReadonlyArray<Item>;
+    /**
+     * Developer-role framing message that kicks off a fresh run. Omit to
+     * run the loop in "seed + wait" mode where the first turn is driven
+     * externally (e.g. by an IPC client's `send` frame).
+     */
+    readonly initialMessage?: ExecuteInput;
+    readonly signal: DetachedSignal<TOutcome>;
+    /**
+     * Optional post-turn hook. Only runs on the fresh-spawn path once
+     * `initialMessage` has settled microtasks. Receives a context whose
+     * `signalSettled()` query reflects whether the signal is already
+     * resolved/rejected so the hook can no-op when the agent already
+     * produced its terminal outcome.
+     */
+    readonly afterFirstTurn?: (ctx: AfterFirstTurnContext) => Promise<void>;
+}
+/**
+ * Execute the runnable-loop lifecycle and return the final outcome by
+ * awaiting the caller-provided signal. See the module doc for the full
+ * sequence; short version:
+ *
+ *   - `priorItems` present → seed + wait on signal.
+ *   - `initialMessage` present → seed (if any) + execute first turn +
+ *     run `afterFirstTurn` (if any) + wait on signal.
+ *   - Neither present → just wait on signal (pure listener mode).
+ */
+export declare function runnableLoop<TOutcome>(opts: RunnableLoopOpts<TOutcome>): Promise<TOutcome>;

package/dist/runtime/durable/runnable-loop.js

@@ -0,0 +1,90 @@
+/**
+ * Drive a generic agent-harness chat session for a detached runner.
+ *
+ * The loop is intentionally minimal. A "runnable" is any harness
+ * driven through the standard `execute()` path plus a single-shot
+ * `DetachedSignal` its terminal tool resolves:
+ *
+ *   1. **Resume spawn** — when `priorItems` is non-empty, seed the
+ *      session history and hand control straight to the caller's
+ *      signal. The agent's prior turns are already on record; the next
+ *      turn comes from external input (IPC `send` frame, autopilot
+ *      respawn, etc.) rather than being re-kicked here.
+ *   2. **Fresh spawn** — when `priorItems` is empty (or omitted) and
+ *      an `initialMessage` is supplied, execute that framing message
+ *      as the first turn. The harness's own stream pumps persist the
+ *      emitted items via whatever session store the caller wired up.
+ *   3. **Post-turn hook** — if `afterFirstTurn` is supplied, run it
+ *      once the first turn has settled microtasks. The hook sees
+ *      whether the signal already resolved during the turn so it can
+ *      short-circuit its own logic (e.g. the stall-nudge helper skips
+ *      its nudge when the agent already called a terminal tool).
+ *   4. **Await outcome** — finally, return `signal.done`. If no
+ *      terminal tool ever resolves it, the signal rejects externally
+ *      (SIGTERM handler, process abort) or simply never settles — the
+ *      caller owns that concern.
+ *
+ * The loop has no opinions about where `priorItems` come from, how the
+ * `initialMessage` is built, or what the terminal outcome looks like.
+ * Task-specific logic (chat.jsonl reads, role framing, stall
+ * escalation) lives in the caller and composes via the `afterFirstTurn`
+ * hook.
+ */
+//#endregion
+//#region Public API
+/**
+ * Execute the runnable-loop lifecycle and return the final outcome by
+ * awaiting the caller-provided signal. See the module doc for the full
+ * sequence; short version:
+ *
+ *   - `priorItems` present → seed + wait on signal.
+ *   - `initialMessage` present → seed (if any) + execute first turn +
+ *     run `afterFirstTurn` (if any) + wait on signal.
+ *   - Neither present → just wait on signal (pure listener mode).
+ */
+export async function runnableLoop(opts) {
+    const prior = opts.priorItems;
+    if (prior !== undefined && prior.length > 0) {
+        opts.harness.seedSessionHistory(opts.threadId, prior);
+        return opts.signal.done;
+    }
+    if (opts.initialMessage === undefined) {
+        return opts.signal.done;
+    }
+    // Track signal settlement without blocking so the `afterFirstTurn`
+    // hook can detect a synchronous resolve that fired during `execute()`
+    // without racing the deferred.
+    let signalSettled = false;
+    void opts.signal.done.then(() => {
+        signalSettled = true;
+    }, () => {
+        signalSettled = true;
+    });
+    await opts.harness.execute(opts.initialMessage, {
+        threadId: opts.threadId,
+    });
+    // `execute()` only enqueues the framing message; the turn itself runs
+    // asynchronously through the session runner. Await `getAgentResponse`
+    // to observe REAL turn completion before dispatching `afterFirstTurn`.
+    // Without this the stall-nudge hook fires before any turn output and
+    // always classifies the run as stalled. We race against `signal.done`
+    // so a terminal tool that resolves the signal mid-turn still short-
+    // circuits the wait — in that case `getAgentResponse` may not have
+    // settled yet and we skip the post-turn hook entirely since the
+    // terminal outcome has already fired.
+    await Promise.race([
+        opts.harness
+            .getAgentResponse({
+            threadId: opts.threadId,
+        })
+            .catch(() => undefined),
+        opts.signal.done.catch(() => undefined),
+    ]);
+    if (opts.afterFirstTurn !== undefined) {
+        await opts.afterFirstTurn({
+            signalSettled: () => signalSettled,
+        });
+    }
+    return opts.signal.done;
+}
+//#endregion

package/dist/runtime/durable/session-seed.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Seed an agent harness's session history from a pre-parsed `Item[]`.
+ *
+ * Callers who have chat history on disk (JSONL, DB, etc.) read + parse
+ * the persisted format into `Item[]` themselves — this helper is
+ * deliberately path-free so it composes with any storage layer.
+ *
+ * The helper is a thin typed wrapper around `harness.seedSessionHistory`
+ * and exists so the runnable-loop (and any other caller that wants to
+ * restore a prior session) has one documented, named entrypoint rather
+ * than reaching for the harness method inline.
+ */
+import type { Item } from '../../types/items';
+/**
+ * Minimum harness surface `seedFromItems` requires. Defined structurally
+ * so tests (and out-of-process children) can pass a stub without casts;
+ * `AgentHarness<P>` from core satisfies the shape directly.
+ */
+export interface SessionSeedHarness {
+    seedSessionHistory(threadId: string, items: ReadonlyArray<Item>): void;
+}
+/**
+ * Seed `harness`'s session for `threadId` with the given items so the
+ * next `execute()` call sees them in the item log. No-op when `items`
+ * is empty (the harness call itself is also safe to make with an empty
+ * array; short-circuiting here keeps the intent crisp).
+ */
+export declare function seedFromItems(harness: SessionSeedHarness, threadId: string, items: ReadonlyArray<Item>): void;

package/dist/runtime/durable/session-seed.js

@@ -0,0 +1,27 @@
+/**
+ * Seed an agent harness's session history from a pre-parsed `Item[]`.
+ *
+ * Callers who have chat history on disk (JSONL, DB, etc.) read + parse
+ * the persisted format into `Item[]` themselves — this helper is
+ * deliberately path-free so it composes with any storage layer.
+ *
+ * The helper is a thin typed wrapper around `harness.seedSessionHistory`
+ * and exists so the runnable-loop (and any other caller that wants to
+ * restore a prior session) has one documented, named entrypoint rather
+ * than reaching for the harness method inline.
+ */
+//#endregion
+//#region Public API
+/**
+ * Seed `harness`'s session for `threadId` with the given items so the
+ * next `execute()` call sees them in the item log. No-op when `items`
+ * is empty (the harness call itself is also safe to make with an empty
+ * array; short-circuiting here keeps the intent crisp).
+ */
+export function seedFromItems(harness, threadId, items) {
+    if (items.length === 0) {
+        return;
+    }
+    harness.seedSessionHistory(threadId, items);
+}
+//#endregion