@noetic-tools/core 0.0.1 → 0.1.1

package/dist/runtime/detached-handle.d.ts

@@ -1,14 +1,62 @@
-import type { DetachedHandle } from '../types/detached';
-import { DetachedStatus } from '../types/detached';
+import type { DetachedHandle } from '../types/detached.js';
+import { DetachedStatus } from '../types/detached.js';
+import type { SubprocessAdapter, SubprocessHandle } from '../types/subprocess-adapter.js';
+interface DetachedHandleOpts {
+    /** Id surfaced to callers — usually the execution id (childCtx.id in
+     *  `detachedSpawn`) so consumers can correlate it with their own state. */
+    id: string;
+    /** Step id — used when the adapter surfaces a generic failure and we need
+     *  to produce a `NoeticError` with a meaningful `stepId`. */
+    stepId: string;
+    /** Adapter that produced the handle. */
+    adapter: SubprocessAdapter;
+    /**
+     * Promise that resolves to the adapter-assigned handle. `detachedSpawn`
+     * passes the in-flight `adapter.spawn(request)` promise here so `.await()`
+     * is reachable even before the spawn itself has settled.
+     */
+    spawnPromise: Promise<SubprocessHandle>;
+}
+/**
+ * @public
+ * Thin wrapper over a `SubprocessHandle` that implements the `DetachedHandle`
+ * contract. Polls the adapter until the handle reaches a terminal status,
+ * then reads the result (or error) off `handle.metadata`.
+ *
+ * The polling cadence starts at 10ms and ramps to 100ms after the first
+ * second — responsive for short-lived in-memory steps without burning cycles
+ * on long-running ones.
+ */
 export declare class DetachedHandleImpl<O> implements DetachedHandle<O> {
     readonly id: string;
+    private readonly _stepId;
+    private readonly _adapter;
+    private readonly _spawnPromise;
+    private readonly _startTime;
     private _status;
     private _result;
     private _error;
-    private readonly promise;
-    constructor(id: string, promise: Promise<O>);
+    private _settlementPromise;
+    constructor(opts: DetachedHandleOpts);
     get status(): DetachedStatus;
     get result(): O | undefined;
     get error(): string | undefined;
+    /**
+     * Wait for the underlying handle to settle, up to an optional timeout.
+     * On settlement, the cached status/result/error are updated before
+     * returning — so a caller that inspects `status` after `await()` resolves
+     * observes the final value.
+     */
     await(timeout?: number): Promise<O>;
+    /**
+     * Start (or return the cached) polling promise that resolves on the first
+     * terminal status the adapter reports for this handle.
+     *
+     * A single settlement promise is shared across all `.await()` callers so
+     * repeated calls don't spawn parallel polling loops.
+     */
+    private getOrStartSettlement;
+    private pollUntilSettled;
+    private finalise;
 }
+export {};

package/dist/runtime/detached-handle.js

@@ -1,19 +1,125 @@
-import { NoeticErrorImpl } from '../errors/noetic-error';
-import { DetachedStatus } from '../types/detached';
+import { NoeticErrorImpl } from '../errors/noetic-error.js';
+import { DetachedStatus } from '../types/detached.js';
+import { frameworkCast } from '../util/framework-cast.js';
+//#endregion
+//#region Helpers
+const INITIAL_POLL_MS = 10;
+const MAX_POLL_MS = 100;
+const POLL_RAMP_AFTER_MS = 1_000;
+/** Upper bound on microtask yields before falling back to timer-based
+ *  polling. Chosen empirically: in-memory step bodies settle within a
+ *  handful of microtasks, and 64 gives plenty of headroom for chained
+ *  awaits inside complex step trees without busy-spinning. */
+const MAX_MICROTASK_YIELDS = 64;
+/** Grace period before treating persistent null `adapter.get(handleId)`
+ *  results as an eviction. Tolerates transient nulls from adapters that
+ *  register the handle asynchronously relative to the spawn promise
+ *  settling, but bounds the worst case so a corrupt adapter doesn't
+ *  produce an infinite poll. */
+const HANDLE_EVICTED_GRACE_MS = 500;
+/**
+ * Yield control to the timer queue so the adapter has a chance to
+ * transition the handle before we issue the next `adapter.get()` call.
+ * Using a timer (even 0ms) ensures we don't spin-lock when the adapter
+ * schedules its completion on a later microtask.
+ */
+function sleep(ms) {
+    if (ms <= 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isTerminalStatus(status) {
+    return (status === 'completed' || status === 'failed' || status === 'stopped' || status === 'stale');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isNoeticErrorPayload(value) {
+    return isRecord(value) && typeof value.kind === 'string';
+}
+/** Rehydrate a thrown error from the handle metadata. Preserves the
+ *  structured NoeticError shape when present so type-guards like
+ *  `isNoeticError` keep working on the consumer side. */
+function rehydrateError(payload, stepId) {
+    if (!payload) {
+        return new NoeticErrorImpl({
+            kind: 'step_failed',
+            stepId,
+            cause: new Error('Detached spawn failed without an error payload'),
+            retriesExhausted: false,
+        });
+    }
+    if (isNoeticErrorPayload(payload.noeticError)) {
+        return new NoeticErrorImpl(payload.noeticError);
+    }
+    const err = new Error(payload.message);
+    if (payload.name) {
+        err.name = payload.name;
+    }
+    if (payload.stack) {
+        err.stack = payload.stack;
+    }
+    return err;
+}
+function extractResult(metadata) {
+    if (!metadata || metadata.result === undefined) {
+        return undefined;
+    }
+    return frameworkCast(metadata.result);
+}
+function extractError(metadata) {
+    if (!metadata || metadata.error === undefined) {
+        return undefined;
+    }
+    const raw = metadata.error;
+    if (!isRecord(raw)) {
+        return {
+            message: String(raw),
+        };
+    }
+    const message = typeof raw.message === 'string' ? raw.message : 'unknown error';
+    const name = typeof raw.name === 'string' ? raw.name : undefined;
+    const stack = typeof raw.stack === 'string' ? raw.stack : undefined;
+    return {
+        message,
+        name,
+        stack,
+        noeticError: raw.noeticError,
+    };
+}
+//#endregion
 //#region DetachedHandleImpl
+/**
+ * @public
+ * Thin wrapper over a `SubprocessHandle` that implements the `DetachedHandle`
+ * contract. Polls the adapter until the handle reaches a terminal status,
+ * then reads the result (or error) off `handle.metadata`.
+ *
+ * The polling cadence starts at 10ms and ramps to 100ms after the first
+ * second — responsive for short-lived in-memory steps without burning cycles
+ * on long-running ones.
+ */
 export class DetachedHandleImpl {
     id;
+    _stepId;
+    _adapter;
+    _spawnPromise;
+    _startTime;
     _status = DetachedStatus.Running;
     _result;
     _error;
-    promise;
-    constructor(id, promise) {
-        this.id = id;
-        this.promise = promise;
-        promise.then((value) => {
-            this._status = DetachedStatus.Completed;
-            this._result = value;
-        }, (err) => {
+    _settlementPromise;
+    constructor(opts) {
+        this.id = opts.id;
+        this._stepId = opts.stepId;
+        this._adapter = opts.adapter;
+        this._spawnPromise = opts.spawnPromise;
+        this._startTime = Date.now();
+        // Observe spawn failure eagerly so `.error` is populated even if the
+        // caller never invokes `.await()`. We intentionally swallow the
+        // rejection here — `.await()` surfaces it to the caller.
+        this._spawnPromise.catch((err) => {
             this._status = DetachedStatus.Failed;
             this._error = err instanceof Error ? err.message : String(err);
         });
@@ -27,16 +133,23 @@ export class DetachedHandleImpl {
     get error() {
         return this._error;
     }
+    /**
+     * Wait for the underlying handle to settle, up to an optional timeout.
+     * On settlement, the cached status/result/error are updated before
+     * returning — so a caller that inspects `status` after `await()` resolves
+     * observes the final value.
+     */
     async await(timeout) {
+        const settlement = this.getOrStartSettlement();
         if (timeout === undefined || timeout <= 0) {
-            return this.promise;
+            return settlement;
         }
         let timerId;
         const timeoutPromise = new Promise((_resolve, reject) => {
             timerId = setTimeout(() => {
                 reject(new NoeticErrorImpl({
                     kind: 'step_failed',
-                    stepId: this.id,
+                    stepId: this._stepId,
                     cause: new Error(`Detached spawn timed out after ${timeout}ms`),
                     retriesExhausted: false,
                 }));
@@ -44,13 +157,104 @@ export class DetachedHandleImpl {
         });
         try {
             return await Promise.race([
-                this.promise,
+                settlement,
                 timeoutPromise,
             ]);
         }
         finally {
-            clearTimeout(timerId);
+            if (timerId !== undefined) {
+                clearTimeout(timerId);
+            }
+        }
+    }
+    /**
+     * Start (or return the cached) polling promise that resolves on the first
+     * terminal status the adapter reports for this handle.
+     *
+     * A single settlement promise is shared across all `.await()` callers so
+     * repeated calls don't spawn parallel polling loops.
+     */
+    getOrStartSettlement() {
+        if (this._settlementPromise) {
+            return this._settlementPromise;
+        }
+        this._settlementPromise = this.pollUntilSettled();
+        return this._settlementPromise;
+    }
+    async pollUntilSettled() {
+        // Wait for the spawn itself to succeed before we start polling —
+        // otherwise we'd be polling with an undefined handle id.
+        const initialHandle = await this._spawnPromise;
+        if (isTerminalStatus(initialHandle.status)) {
+            return this.finalise(initialHandle);
+        }
+        // Track when the adapter persistently returns null for this handle.
+        // Transient nulls are tolerated for `HANDLE_EVICTED_GRACE_MS`; after
+        // that we raise `handle_evicted` instead of looping forever. A
+        // non-null observation resets the grace window.
+        let firstNullAt = null;
+        const observeNull = () => {
+            if (firstNullAt === null) {
+                firstNullAt = Date.now();
+                return;
+            }
+            if (Date.now() - firstNullAt >= HANDLE_EVICTED_GRACE_MS) {
+                throw new NoeticErrorImpl({
+                    kind: 'handle_evicted',
+                    handleId: initialHandle.id,
+                    stepId: this._stepId,
+                    gracePeriodMs: HANDLE_EVICTED_GRACE_MS,
+                });
+            }
+        };
+        const observeHandle = (h) => {
+            if (h === null) {
+                observeNull();
+                return null;
+            }
+            firstNullAt = null;
+            return h;
+        };
+        // Fast path: yield through the microtask queue first. The in-memory
+        // adapter schedules completion on a microtask, so a handful of yields
+        // typically resolves the handle in sub-millisecond time. This keeps the
+        // interpreter's "route through adapter" overhead negligible.
+        for (let i = 0; i < MAX_MICROTASK_YIELDS; i++) {
+            const handle = observeHandle(await this._adapter.get(initialHandle.id));
+            if (handle && isTerminalStatus(handle.status)) {
+                return this.finalise(handle);
+            }
+            await Promise.resolve();
+        }
+        // Slow path: fall back to timer-based polling for genuinely long-running
+        // handles (out-of-process adapters, async work that doesn't resolve on
+        // the microtask queue).
+        let delay = INITIAL_POLL_MS;
+        for (;;) {
+            const handle = observeHandle(await this._adapter.get(initialHandle.id));
+            if (handle && isTerminalStatus(handle.status)) {
+                return this.finalise(handle);
+            }
+            await sleep(delay);
+            if (Date.now() - this._startTime >= POLL_RAMP_AFTER_MS) {
+                delay = MAX_POLL_MS;
+            }
+        }
+    }
+    finalise(handle) {
+        const metadata = handle.metadata;
+        if (handle.status === 'completed') {
+            const value = extractResult(metadata);
+            this._status = DetachedStatus.Completed;
+            this._result = value;
+            return frameworkCast(value);
         }
+        // Failed / stopped / stale — all map to Failed from the caller's view.
+        const errorPayload = extractError(metadata);
+        const err = rehydrateError(errorPayload, this._stepId);
+        this._status = DetachedStatus.Failed;
+        this._error = err.message;
+        throw err;
     }
 }
 //#endregion

package/dist/runtime/durable/checkpoint-store.d.ts

@@ -0,0 +1,38 @@
+import type { CheckpointSnapshot } from '../../types/checkpoint.js';
+import type { StorageAdapter } from '../../types/memory.js';
+export declare const CheckpointKeys: {
+    readonly ExecPrefix: "execution:";
+    readonly SnapshotSuffix: ":snapshot";
+    readonly FrontierSuffix: ":frontier";
+    readonly LayersSuffix: ":layers:";
+    readonly CwdSuffix: ":cwd";
+    readonly AskUserSuffix: ":askUser";
+    readonly ItemLogSuffix: ":itemLog";
+};
+/**
+ * @public
+ * Typed wrapper around a `StorageAdapter` that owns the key layout for
+ * checkpoint snapshots and validates every read with the canonical Zod
+ * schema.
+ *
+ * Corruption or schema-version drift is surfaced as `NoeticConfigError`
+ * (`code === 'CHECKPOINT_SCHEMA_MISMATCH'`) so callers can discard the
+ * offending snapshot without crashing the host.
+ */
+export interface CheckpointStore {
+    /** Persist a snapshot. Later calls for the same `executionId` overwrite. */
+    save(snapshot: CheckpointSnapshot): Promise<void>;
+    /** Load the snapshot for an execution, or `null` if none is recorded. */
+    load(executionId: string): Promise<CheckpointSnapshot | null>;
+    /** List every `executionId` that has a persisted snapshot. */
+    list(): Promise<ReadonlyArray<{
+        executionId: string;
+    }>>;
+    /** Remove the snapshot for `executionId`. No-op when the key is absent. */
+    clear(executionId: string): Promise<void>;
+}
+/** @public Options for `createCheckpointStore`. */
+export interface CreateCheckpointStoreOptions {
+    storage: StorageAdapter;
+}
+export declare function createCheckpointStore(options: CreateCheckpointStoreOptions): CheckpointStore;

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

@@ -0,0 +1,101 @@
+import { NoeticConfigError } from '../../errors/noetic-config-error.js';
+import { CheckpointSnapshotSchema } from '../../types/checkpoint.js';
+//#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.js';
+import type { ItemSchemaRegistry } from '../../schemas/item.js';
+import type { Context } from '../../types/context.js';
+import type { Item } from '../../types/items.js';
+import type { MemoryLayer } from '../../types/memory.js';
+import type { CheckpointStore } from './checkpoint-store.js';
+/**
+ * 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>;