@noetic-tools/core 0.0.1

package/dist/patterns/react.js

@@ -0,0 +1,39 @@
+import { loop } from '../builders/loop-builder';
+import { spawn } from '../builders/spawn-builder';
+import { step } from '../builders/step-builders';
+import { any } from '../until/combinators';
+import { until } from '../until/predicates';
+/**
+ * Creates a ReAct (Reason + Act) agent loop: an LLM step with tools iterated until no tool calls or limits are hit.
+ *
+ * @public
+ * @param opts - Model, tools, optional instructions, step/cost limits, and memory layers.
+ * @returns A `StepLoop` (no memory) or `StepSpawn` wrapping a loop (with memory).
+ */
+export function react(opts) {
+    const llmStep = step.llm({
+        id: 'react-step',
+        model: opts.model,
+        instructions: opts.instructions,
+        tools: opts.tools,
+    });
+    const loopStep = loop({
+        id: 'react-loop',
+        steps: [
+            llmStep,
+        ],
+        until: any(until.noToolCalls(), until.maxSteps(opts.maxSteps ?? 10), ...(opts.maxCost
+            ? [
+                until.maxCost(opts.maxCost),
+            ]
+            : [])),
+    });
+    if (!opts.memory) {
+        return loopStep;
+    }
+    return spawn({
+        id: 'react-agent',
+        child: loopStep,
+        memory: opts.memory,
+    });
+}

package/dist/portable.d.ts

@@ -0,0 +1,26 @@
+/** @public */
+export { createInMemoryFsAdapter } from './adapters/in-memory-fs-adapter';
+/** @public */
+export { createInMemoryShellAdapter } from './adapters/in-memory-shell-adapter';
+/** @public */
+export { createInMemorySubprocessAdapter } from './adapters/in-memory-subprocess-adapter';
+/** @public */
+export { step } from './builders/step-builders';
+/** @public */
+export { tool, toolWithGenerator } from './builders/tool-builder';
+/** @public */
+export { durableTaskState } from './memory/layers/durable-task-state';
+/** @public */
+export { historyWindow } from './memory/layers/history-window';
+/** @public */
+export { observationalMemory } from './memory/layers/observational-memory';
+/** @public */
+export { planMemory } from './memory/layers/plan';
+/** @public */
+export { toolMemoryLayer } from './memory/layers/tool-memory-layer';
+/** @public */
+export { workingMemory } from './memory/layers/working-memory';
+/** @public */
+export { AgentHarness } from './runtime/agent-harness';
+/** @public */
+export { createInMemoryStorage } from './runtime/in-memory-storage';

package/dist/portable.js

@@ -0,0 +1,34 @@
+//#region Portable Adapters
+/** @public */
+export { createInMemoryFsAdapter } from './adapters/in-memory-fs-adapter';
+/** @public */
+export { createInMemoryShellAdapter } from './adapters/in-memory-shell-adapter';
+/** @public */
+export { createInMemorySubprocessAdapter } from './adapters/in-memory-subprocess-adapter';
+//#endregion
+//#region Builders
+/** @public */
+export { step } from './builders/step-builders';
+/** @public */
+export { tool, toolWithGenerator } from './builders/tool-builder';
+//#endregion
+//#region Memory Layers
+/** @public */
+export { durableTaskState } from './memory/layers/durable-task-state';
+/** @public */
+export { historyWindow } from './memory/layers/history-window';
+/** @public */
+export { observationalMemory } from './memory/layers/observational-memory';
+/** @public */
+export { planMemory } from './memory/layers/plan';
+/** @public */
+export { toolMemoryLayer } from './memory/layers/tool-memory-layer';
+/** @public */
+export { workingMemory } from './memory/layers/working-memory';
+//#endregion
+//#region Runtime
+/** @public */
+export { AgentHarness } from './runtime/agent-harness';
+/** @public */
+export { createInMemoryStorage } from './runtime/in-memory-storage';
+//#endregion

package/dist/runtime/agent-harness.d.ts

@@ -0,0 +1,206 @@
+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';
+interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    initialStep?: Step<ContextMemory, string, string>;
+    /** Default memory layers applied to every context created via `createContext()` / `execute()`. */
+    memory?: MemoryLayer[];
+    storage?: StorageAdapter;
+    hooks?: AgentHooks;
+    params: TParams;
+    paramsSchema?: ZodType<TParams>;
+    /** Filesystem adapter. Defaults to local node:fs when not provided. */
+    fs?: FsAdapter;
+    /** Shell adapter. Defaults to local sh when not provided. */
+    shell?: ShellAdapter;
+    /** Subprocess adapter. Defaults to an in-memory, same-process adapter. */
+    subprocess?: SubprocessAdapter;
+    llm?: LlmProviderConfig;
+    /** Harness-wide item schema extensions. */
+    itemSchemas?: ItemSchemaExtensions;
+    /** Whether unknown extension item types must match a registered schema. Defaults to true. */
+    strictItemSchemas?: boolean;
+    traceExporter?: TraceExporter;
+    layerStateStore?: LayerStateStore;
+    /** Default delivery mode for messages that don't specify one. Defaults to `next-turn`. */
+    defaultDeliveryMode?: DeliveryMode;
+    /**
+     * Abort the in-flight model call if the provider stream emits no events for this
+     * many milliseconds. Defaults to `DEFAULT_STREAM_IDLE_TIMEOUT_MS` (120s).
+     * Pass `0` or a negative number to disable the watchdog.
+     */
+    streamIdleTimeoutMs?: number;
+    /**
+     * Initial working directory for the harness. Used as the seed value for the
+     * shared `cwdState.cwd` on every Context this harness creates, including
+     * those produced by spawn/fork. Defaults to `process.cwd()`.
+     */
+    initialCwd?: string;
+    /** @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.
+ *
+ * Messages submitted via `execute()` are enqueued on a per-thread session and
+ * processed by a `SessionRunner`. Consumers observe responses via the session-
+ * scoped accessors: `getAgentResponse`, `getItemStream`, etc.
+ *
+ * @public
+ */
+export declare class AgentHarness<TParams extends Record<string, unknown> = Record<string, unknown>> implements AgentHarnessContract<TParams> {
+    readonly config: AgentConfig<TParams>;
+    readonly fs: FsAdapter;
+    readonly shell: ShellAdapter;
+    readonly subprocess: SubprocessAdapter;
+    private readonly initialStep?;
+    private readonly _memory?;
+    private readonly client?;
+    private readonly channelStore;
+    private readonly callModelOverride?;
+    private readonly defaultDeliveryMode;
+    private readonly streamIdleTimeoutMs;
+    private readonly sessions;
+    readonly layerStateStore: LayerStateStore;
+    readonly traceExporter: TraceExporter;
+    /**
+     * Long-lived shared cwd state. The same reference is seeded into every
+     * root Context this harness creates, so successive `run()` calls — and the
+     * TUI — observe each other's `cd`s.
+     */
+    readonly rootCwdState: CwdState;
+    private readonly itemSchemas;
+    constructor(opts: AgentHarnessOpts<TParams>);
+    /**
+     * Update the harness-wide root cwd. The TUI calls this in response to a
+     * user-issued `! cd`, so the next root Context (and any tool inspecting
+     * `harness.rootCwdState.cwd`) observes the new value. Caller is responsible
+     * for passing an absolute, validated path.
+     */
+    setRootCwd(nextCwd: string): void;
+    execute(input: ExecuteInput, options?: ExecuteOptions): Promise<void>;
+    getAgentResponse(scope?: SessionScope): Promise<HarnessResponse>;
+    getItemStream(scope?: SessionScope): AsyncIterable<StreamingItem>;
+    getTextStream(scope?: SessionScope): AsyncIterable<string>;
+    getReasoningStream(scope?: SessionScope): AsyncIterable<string>;
+    getFullStream(scope?: SessionScope): AsyncIterable<StreamEvent>;
+    abort(scope?: SessionScope & {
+        reason?: string;
+    }): Promise<void>;
+    getStatus(scope?: SessionScope): HarnessStatus;
+    getQueueSize(scope?: SessionScope): number;
+    seedSessionHistory(threadId: string, items: ReadonlyArray<Item>): void;
+    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>;
+    createContext(opts?: {
+        parent?: Context;
+        items?: Item[];
+        state?: unknown;
+        threadId?: string;
+        resourceId?: string;
+        memory?: MemoryLayer[];
+        /**
+         * Initial cwd for the new context. When set, takes precedence over both
+         * the parent snapshot and the harness root cwd — used by worktree
+         * isolation to root a child agent at the worktree path.
+         */
+        cwdInit?: string;
+        _broadcaster?: EventBroadcaster;
+    }): Context;
+    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>;
+    /** Resolves layer-provided tools and merges with step tools into ctx.unifiedTools. */
+    private setUnifiedTools;
+    private toExecCtx;
+    initLayers(layers: MemoryLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
+    recallLayers(layers: MemoryLayer[], input: string, ctx: Context): Promise<RecallLayerOutput[]>;
+    /**
+     * Compute the items array that would be sent to the model on the next turn —
+     * the same arrangement `executeLLM` builds: harness-level memory layers'
+     * recall outputs concatenated with the session's accumulated history.
+     *
+     * Read-mostly: `recallLayers` writes layer-state snapshots to
+     * `layerStateStore` exactly as a real turn would, so successive previews
+     * remain consistent with what the next real turn produces.
+     */
+    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>;
+    cancel(_ctx: Context, _reason?: string): Promise<void>;
+    createSpan(name: string, parent: Span | null): Span;
+    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>;
+    projectHistory(layers: MemoryLayer[], items: ReadonlyArray<Item>, ctx: Context): Promise<ReadonlyArray<Item>>;
+    runAppendPipeline(layers: MemoryLayer[], items: Item[], ctx: Context): Promise<{
+        items: Item[];
+        rerenderRequests: {
+            layerId: string;
+            slot: number;
+            timing: 'immediate' | 'batched';
+            scope: 'self' | 'slot-after' | 'all';
+        }[];
+    }>;
+    executeRerender(requests: {
+        layerId: string;
+        slot: number;
+        timing: 'immediate' | 'batched';
+        scope: 'self' | 'slot-after' | 'all';
+    }[], layers: MemoryLayer[], ctx: Context, budgets: Map<string, number>, query?: string): Promise<{
+        layerId: string;
+        items: Item[];
+        tokenCount: number;
+    }[]>;
+}
+export {};