@noetic-tools/core 0.0.1 → 0.1.0

package/dist/builders/workflow-hydrator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Converts a validated `WorkflowDocument` into a live `Step` tree.
+ *
+ * Each node kind maps to the corresponding builder (`step.llm`, `fork`,
+ * `loop`, etc.) so hydrated steps are indistinguishable from programmatic
+ * ones — they register in the step registry, carry retry policies, etc.
+ */
+import type { WorkflowDocument, WorkflowNode } from '../schemas/workflow';
+import type { ContextMemory, MemoryLayer } from '../types/memory';
+import type { ExecuteStepFn, Step } from '../types/step';
+import type { Tool } from '../types/tool';
+/** @public Context required to hydrate a JSON workflow into live steps. */
+export interface HydrationContext {
+    tools: ReadonlyMap<string, Tool>;
+    executeStep: ExecuteStepFn;
+    layers?: ReadonlyMap<string, MemoryLayer>;
+}
+/**
+ * Hydrates a single `WorkflowNode` into a live `Step`.
+ *
+ * @public
+ * @param node - Validated workflow node.
+ * @param ctx - Hydration context with tool registry and step executor.
+ * @returns A live `Step` ready for execution.
+ * @throws `NoeticConfigError` with code `UNKNOWN_NODE_KIND` if the node kind is unrecognised.
+ * @throws `NoeticConfigError` with code `UNKNOWN_TOOL_REFERENCE` if a tool name cannot be resolved.
+ * @throws `NoeticConfigError` with code `UNKNOWN_UNTIL_PREDICATE` if an until predicate kind is unrecognised.
+ */
+export declare function hydrateNode(node: WorkflowNode, ctx: HydrationContext): Step<ContextMemory, string, string>;
+/**
+ * Hydrates a complete `WorkflowDocument` into a live `Step` tree.
+ *
+ * @public
+ * @param doc - Validated workflow document (version 1).
+ * @param ctx - Hydration context with tool registry and step executor.
+ * @returns The root `Step` of the hydrated workflow.
+ */
+export declare function hydrateWorkflow(doc: WorkflowDocument, ctx: HydrationContext): Step<ContextMemory, string, string>;

package/dist/builders/workflow-hydrator.js

@@ -0,0 +1,336 @@
+/**
+ * Converts a validated `WorkflowDocument` into a live `Step` tree.
+ *
+ * Each node kind maps to the corresponding builder (`step.llm`, `fork`,
+ * `loop`, etc.) so hydrated steps are indistinguishable from programmatic
+ * ones — they register in the step registry, carry retry policies, etc.
+ */
+import { NoeticConfigError } from '../errors/noetic-config-error';
+import { all, any } from '../until/combinators';
+import { until } from '../until/predicates';
+import { frameworkCast } from '../util/framework-cast';
+import { branch, fork } from './control-flow-builders';
+import { every } from './every';
+import { loop } from './loop-builder';
+import { provide } from './provide-builder';
+import { spawn } from './spawn-builder';
+import { step } from './step-builders';
+//#endregion
+//#region Until Predicate Hydration
+function hydrateUntilPredicate(pred) {
+    switch (pred.kind) {
+        case 'maxSteps':
+            return until.maxSteps(pred.n);
+        case 'maxCost':
+            return until.maxCost(pred.usd);
+        case 'maxDuration':
+            return until.maxDuration(pred.ms);
+        case 'noToolCalls':
+            return until.noToolCalls();
+        case 'outputContains':
+            return until.outputContains(pred.marker);
+        case 'outputEquals':
+            return until.outputEquals(pred.sentinel);
+        case 'converged':
+            return until.converged({
+                threshold: pred.threshold,
+            });
+        case 'any':
+            return any(...pred.predicates.map(hydrateUntilPredicate));
+        case 'all':
+            return all(...pred.predicates.map(hydrateUntilPredicate));
+        default:
+            throw new NoeticConfigError({
+                code: 'UNKNOWN_UNTIL_PREDICATE',
+                message: `Unknown until predicate kind: '${frameworkCast(pred).kind}'.`,
+                hint: 'Supported kinds: maxSteps, maxCost, maxDuration, noToolCalls, outputContains, outputEquals, converged, any, all.',
+            });
+    }
+}
+//#endregion
+//#region Node Hydrators
+function hydrateLlmNode(node, ctx) {
+    if (node.kind !== 'llm') {
+        return frameworkCast(undefined);
+    }
+    const resolvedTools = resolveTools(node.tools, ctx.tools);
+    return step.llm({
+        id: node.id,
+        model: node.model ?? 'openai/gpt-4o',
+        instructions: node.instructions,
+        tools: resolvedTools.length > 0 ? resolvedTools : undefined,
+        params: node.params,
+    });
+}
+function hydrateToolNode(node, ctx) {
+    if (node.kind !== 'tool') {
+        return frameworkCast(undefined);
+    }
+    const resolved = ctx.tools.get(node.toolName);
+    if (!resolved) {
+        throw new NoeticConfigError({
+            code: 'UNKNOWN_TOOL_REFERENCE',
+            message: `Tool '${node.toolName}' referenced in workflow node '${node.id}' is not registered.`,
+            hint: `Available tools: ${[
+                ...ctx.tools.keys(),
+            ].join(', ') || '(none)'}`,
+        });
+    }
+    return frameworkCast(step.run({
+        id: node.id,
+        execute: async (_input, execCtx) => {
+            const args = node.args ?? {};
+            const callId = `call-${node.id}-${Date.now()}`;
+            const callItem = {
+                id: callId,
+                type: 'function_call',
+                status: 'completed',
+                name: node.toolName,
+                callId,
+                arguments: JSON.stringify(args),
+            };
+            execCtx.itemLog.append(callItem);
+            const toolCtx = {
+                ctx: execCtx,
+                harness: execCtx.harness,
+                fs: execCtx.fs,
+                shell: execCtx.shell,
+                memory: {
+                    get: (_layerId) => undefined,
+                    set: (_layerId, _state) => { },
+                },
+                assembledView: execCtx.itemLog.items,
+                lastStepMeta: execCtx.lastStepMeta,
+            };
+            const result = await resolved.execute(args, toolCtx);
+            return stringifyResult(result);
+        },
+    }));
+}
+function hydrateBranchNode(node, ctx) {
+    if (node.kind !== 'branch') {
+        return frameworkCast(undefined);
+    }
+    const hydratedRoutes = node.routes.map((r) => ({
+        match: r.match,
+        target: hydrateNode(r.target, ctx),
+    }));
+    const defaultTarget = node.default ? hydrateNode(node.default, ctx) : null;
+    const allTargets = hydratedRoutes.map((r) => r.target);
+    if (defaultTarget) {
+        allTargets.push(defaultTarget);
+    }
+    return branch({
+        id: node.id,
+        route: (input) => {
+            const trimmed = input.trim().toLowerCase();
+            for (const r of hydratedRoutes) {
+                if (trimmed.includes(r.match.toLowerCase())) {
+                    return r.target;
+                }
+            }
+            return defaultTarget;
+        },
+        _optimizable: frameworkCast(allTargets),
+    });
+}
+function hydrateForkNode(node, ctx) {
+    if (node.kind !== 'fork') {
+        return frameworkCast(undefined);
+    }
+    const hydratedPaths = node.paths.map((p) => hydrateNode(p, ctx));
+    if (node.mode === 'race') {
+        return fork({
+            id: node.id,
+            mode: 'race',
+            paths: () => hydratedPaths,
+            concurrency: node.concurrency,
+            _optimizable: frameworkCast(hydratedPaths),
+        });
+    }
+    const mergeFn = buildMerge(node.merge ?? 'last');
+    if (node.mode === 'settle') {
+        return fork({
+            id: node.id,
+            mode: 'settle',
+            paths: () => hydratedPaths,
+            merge: (results) => {
+                const values = results.filter((r) => r.status === 'fulfilled').map((r) => r.value ?? '');
+                return mergeFn(values);
+            },
+            concurrency: node.concurrency,
+            _optimizable: frameworkCast(hydratedPaths),
+        });
+    }
+    return fork({
+        id: node.id,
+        mode: 'all',
+        paths: () => hydratedPaths,
+        merge: mergeFn,
+        concurrency: node.concurrency,
+        _optimizable: frameworkCast(hydratedPaths),
+    });
+}
+function hydrateSpawnNode(node, ctx) {
+    if (node.kind !== 'spawn') {
+        return frameworkCast(undefined);
+    }
+    return spawn({
+        id: node.id,
+        child: hydrateNode(node.child, ctx),
+        timeout: node.timeout,
+    });
+}
+function hydrateProvideNode(node, ctx) {
+    if (node.kind !== 'provide') {
+        return frameworkCast(undefined);
+    }
+    const resolvedLayers = ctx.layers
+        ? node.layers.map((name) => {
+            const layer = ctx.layers?.get(name);
+            if (!layer) {
+                throw new NoeticConfigError({
+                    code: 'UNKNOWN_LAYER_REFERENCE',
+                    message: `Memory layer '${name}' referenced in provide node '${node.id}' is not registered.`,
+                    hint: `Available layers: ${[
+                        ...(ctx.layers?.keys() ?? []),
+                    ].join(', ') || '(none)'}. Pass named layers via HydrationContext.layers.`,
+                });
+            }
+            return layer;
+        })
+        : [];
+    return provide({
+        id: node.id,
+        child: hydrateNode(node.child, ctx),
+        memory: resolvedLayers,
+    });
+}
+function hydrateLoopNode(node, ctx) {
+    if (node.kind !== 'loop') {
+        return frameworkCast(undefined);
+    }
+    return loop({
+        id: node.id,
+        steps: [
+            hydrateNode(node.body, ctx),
+        ],
+        until: hydrateUntilPredicate(node.until),
+        maxIterations: node.maxIterations,
+    });
+}
+function hydrateSequenceNode(node, ctx) {
+    if (node.kind !== 'sequence') {
+        return frameworkCast(undefined);
+    }
+    const children = node.steps.map((s) => hydrateNode(s, ctx));
+    return frameworkCast(step.run({
+        id: node.id,
+        execute: async (input, execCtx) => {
+            let current = input;
+            for (const child of children) {
+                const childInput = stringifyResult(current);
+                current = await ctx.executeStep(child, childInput, execCtx);
+            }
+            return stringifyResult(current);
+        },
+    }));
+}
+function hydrateEveryNode(node, ctx) {
+    if (node.kind !== 'every') {
+        return frameworkCast(undefined);
+    }
+    return every({
+        id: node.id,
+        step: hydrateNode(node.step, ctx),
+        ms: node.ms,
+        onError: node.onError,
+    });
+}
+//#endregion
+//#region Handler Registry
+const NODE_HYDRATORS = {
+    llm: hydrateLlmNode,
+    tool: hydrateToolNode,
+    branch: hydrateBranchNode,
+    fork: hydrateForkNode,
+    spawn: hydrateSpawnNode,
+    provide: hydrateProvideNode,
+    loop: hydrateLoopNode,
+    sequence: hydrateSequenceNode,
+    every: hydrateEveryNode,
+};
+//#endregion
+//#region Helpers
+function resolveTools(toolNames, registry) {
+    if (!toolNames || toolNames.length === 0) {
+        return [];
+    }
+    return toolNames.map((name) => {
+        const resolved = registry.get(name);
+        if (!resolved) {
+            throw new NoeticConfigError({
+                code: 'UNKNOWN_TOOL_REFERENCE',
+                message: `Tool '${name}' referenced in workflow is not registered.`,
+                hint: `Available tools: ${[
+                    ...registry.keys(),
+                ].join(', ') || '(none)'}`,
+            });
+        }
+        return resolved;
+    });
+}
+function buildMerge(strategy) {
+    if (strategy === 'first') {
+        return (r) => r[0] ?? '';
+    }
+    if (strategy === 'concat') {
+        return (r) => r.join('\n');
+    }
+    return (r) => r[r.length - 1] ?? '';
+}
+function stringifyResult(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value === null || value === undefined) {
+        return '';
+    }
+    return JSON.stringify(value);
+}
+//#endregion
+//#region Public API
+/**
+ * Hydrates a single `WorkflowNode` into a live `Step`.
+ *
+ * @public
+ * @param node - Validated workflow node.
+ * @param ctx - Hydration context with tool registry and step executor.
+ * @returns A live `Step` ready for execution.
+ * @throws `NoeticConfigError` with code `UNKNOWN_NODE_KIND` if the node kind is unrecognised.
+ * @throws `NoeticConfigError` with code `UNKNOWN_TOOL_REFERENCE` if a tool name cannot be resolved.
+ * @throws `NoeticConfigError` with code `UNKNOWN_UNTIL_PREDICATE` if an until predicate kind is unrecognised.
+ */
+export function hydrateNode(node, ctx) {
+    const hydrator = NODE_HYDRATORS[node.kind];
+    if (!hydrator) {
+        throw new NoeticConfigError({
+            code: 'UNKNOWN_NODE_KIND',
+            message: `Unknown workflow node kind: '${node.kind}'.`,
+            hint: `Supported kinds: ${Object.keys(NODE_HYDRATORS).join(', ')}.`,
+        });
+    }
+    return hydrator(node, ctx);
+}
+/**
+ * Hydrates a complete `WorkflowDocument` into a live `Step` tree.
+ *
+ * @public
+ * @param doc - Validated workflow document (version 1).
+ * @param ctx - Hydration context with tool registry and step executor.
+ * @returns The root `Step` of the hydrated workflow.
+ */
+export function hydrateWorkflow(doc, ctx) {
+    return hydrateNode(doc.root, ctx);
+}
+//#endregion

package/dist/conditions/conditions.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { createMessage, extractAssistantText, trackUsage } from '../interpreter/message-helpers';
+import { createMessage, extractAssistantText, trackUsage } from '../util/message-helpers';
 import { cosineSimilarity } from './cosine-similarity';
 //#endregion
 //#region Helpers

package/dist/errors/noetic-error.js

@@ -43,6 +43,8 @@ function formatMessage(error) {
             return `Budget exceeded: ${error.field} limit ${error.limit}, actual ${error.actual}`;
         case 'steering_denied':
             return `Steering denied${error.guidance ? `: ${error.guidance}` : ''}`;
+        case 'handle_evicted':
+            return `Subprocess handle '${error.handleId}' evicted (step '${error.stepId}'): adapter returned null for ${error.gracePeriodMs}ms`;
         default: {
             const _exhaustive = error;
             void _exhaustive;

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';
+import type { DetachedSpawnOverrides } from './deps/interpreter';
+import type { LayerStateStore } from './deps/memory';
+import type { CheckpointStore, EventBroadcaster } from './deps/runtime';
+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';
+export { createStreamIdleWatchdog } from './model-call';
 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 {};