@noetic-tools/core 0.2.1 → 1.0.0

package/dist/runtime/durable/stall-nudge.js

@@ -5,11 +5,14 @@
  * and without the agent asking for external input — i.e. the agent
  * stopped without calling either a terminal tool or an ask-user-style
  * tool. That's a soft failure: rather than wait forever, we nudge the
- * agent once to remind it of its options. If the second turn also
- * ends in the same stalled shape we escalate: the caller-supplied
- * `onStall` callback records the escalation (task pause, metrics,
- * whatever the domain demands) and we settle the signal ourselves with
- * a canonical "stalled" outcome so the parent unwinds cleanly.
+ * agent once to remind it of its options and wait for the nudged turn
+ * to actually complete (`harness.execute` is enqueue-only, so the hook
+ * awaits `getAgentResponse` — raced against the signal — before
+ * re-checking). If the second turn also ends in the same stalled shape
+ * we escalate: the caller-supplied `onStall` callback records the
+ * escalation (task pause, metrics, whatever the domain demands) and we
+ * settle the signal ourselves with a canonical "stalled" outcome so
+ * the parent unwinds cleanly.
  *
  * The helper factors the state machine out of the loop so callers can
  * opt in per-runner. Task-specific concerns (how "pending external
@@ -55,10 +58,14 @@ export function createNudgeMessage(opts) {
  *   - the caller reports pending external input (`hasPendingExternal`
  *     returns true — e.g. an outstanding ask-user request).
  *
- * Otherwise it sends the nudge message via `harness.execute`, waits
- * for microtasks to flush, and re-checks the same two conditions. If
- * the agent still hasn't progressed, the hook fires `onStall` and
- * resolves the signal with `buildStalledOutcome()`.
+ * Otherwise it sends the nudge message via `harness.execute` and waits
+ * for the nudged turn to actually complete. `execute()` only enqueues
+ * the message — the turn runs asynchronously through the session
+ * runner — so the hook awaits `harness.getAgentResponse(threadId)`
+ * (raced against `signal.done` so a terminal tool that settles the
+ * signal mid-turn short-circuits the wait) before re-checking the same
+ * two conditions. If the agent still hasn't progressed, the hook fires
+ * `onStall` and resolves the signal with `buildStalledOutcome()`.
  */
 export function createStallNudgeHook(opts) {
     return async (ctx) => {
@@ -72,7 +79,19 @@ export function createStallNudgeHook(opts) {
         await opts.harness.execute(opts.nudgeMessage, {
             threadId: opts.threadId,
         });
-        await Promise.resolve();
+        // Wait for the nudged turn to genuinely finish. A one-microtask wait
+        // would escalate before the agent's LLM round trip even starts —
+        // `execute()` resolves as soon as the message is enqueued. Errors from
+        // `getAgentResponse` are swallowed: a failed response fetch must not
+        // crash the hook, it just means we proceed to the stall re-check.
+        await Promise.race([
+            opts.harness
+                .getAgentResponse({
+                threadId: opts.threadId,
+            })
+                .catch(() => undefined),
+            opts.signal.done.then(() => undefined, () => undefined),
+        ]);
         if (ctx.signalSettled()) {
             return;
         }

package/dist/runtime/event-broadcaster.d.ts

@@ -1,4 +1,4 @@
-import type { StreamEvent } from '../types/harness-result.js';
+import type { StreamEvent } from '@noetic-tools/types';
 interface EventBroadcasterOpts {
     maxBufferSize?: number;
 }
@@ -45,7 +45,13 @@ export declare class EventBroadcaster {
 }
 declare class BroadcastIterator implements AsyncIterator<StreamEvent> {
     private cursor;
-    private waiter?;
+    /**
+     * Parked `next()` calls, FIFO. The AsyncIterator protocol allows pipelined
+     * `next()` calls (calling again before the previous promise settles), so a
+     * single waiter slot would orphan all but the latest call — the overwritten
+     * promises would never settle. `notify()` drains in arrival order.
+     */
+    private readonly waiters;
     private returned;
     private readonly broadcaster;
     constructor(broadcaster: EventBroadcaster);
@@ -54,6 +60,8 @@ declare class BroadcastIterator implements AsyncIterator<StreamEvent> {
     /** Called by the broadcaster when new data or completion is available. */
     notify(): void;
     next(): Promise<IteratorResult<StreamEvent>>;
+    /** Settle every parked waiter with `{ done: true }` — used on early exit. */
+    private settleWaiters;
     throw(err: Error): Promise<IteratorResult<StreamEvent>>;
     return(): Promise<IteratorResult<StreamEvent>>;
     private tryRead;

package/dist/runtime/event-broadcaster.js

@@ -101,7 +101,13 @@ export class EventBroadcaster {
 //#region BroadcastIterator
 class BroadcastIterator {
     cursor = 0;
-    waiter;
+    /**
+     * Parked `next()` calls, FIFO. The AsyncIterator protocol allows pipelined
+     * `next()` calls (calling again before the previous promise settles), so a
+     * single waiter slot would orphan all but the latest call — the overwritten
+     * promises would never settle. `notify()` drains in arrival order.
+     */
+    waiters = [];
     returned = false;
     broadcaster;
     constructor(broadcaster) {
@@ -113,20 +119,22 @@ class BroadcastIterator {
     }
     /** Called by the broadcaster when new data or completion is available. */
     notify() {
-        if (!this.waiter) {
-            return;
-        }
-        const w = this.waiter;
-        this.waiter = undefined;
-        try {
-            const result = this.tryRead();
-            if (result) {
-                w.resolve(result);
+        while (this.waiters.length > 0) {
+            let result;
+            try {
+                result = this.tryRead();
             }
-        }
-        catch (err) {
-            // Reject the waiter's promise so the error propagates through the async iterator
-            w.reject(err);
+            catch (err) {
+                // Reject so the error propagates through the async iterator. The
+                // broadcaster stays finished-with-error, so the loop drains every
+                // remaining waiter with the same rejection.
+                this.waiters.shift().reject(err);
+                continue;
+            }
+            if (!result) {
+                return;
+            }
+            this.waiters.shift().resolve(result);
         }
     }
     async next() {
@@ -136,25 +144,41 @@ class BroadcastIterator {
                 value: undefined,
             };
         }
-        const result = this.tryRead();
-        if (result) {
-            return result;
+        // Only read ahead when no one is parked — a pipelined next() must queue
+        // BEHIND earlier calls so events are handed out in FIFO order.
+        if (this.waiters.length === 0) {
+            const result = this.tryRead();
+            if (result) {
+                return result;
+            }
         }
         return new Promise((resolve, reject) => {
-            this.waiter = {
+            this.waiters.push({
                 resolve,
                 reject,
-            };
+            });
         });
     }
+    /** Settle every parked waiter with `{ done: true }` — used on early exit. */
+    settleWaiters() {
+        const drained = this.waiters.splice(0, this.waiters.length);
+        for (const waiter of drained) {
+            waiter.resolve({
+                done: true,
+                value: undefined,
+            });
+        }
+    }
     async throw(err) {
         this.returned = true;
         this.broadcaster.removeIterator(this);
+        this.settleWaiters();
         throw err;
     }
     async return() {
         this.returned = true;
         this.broadcaster.removeIterator(this);
+        this.settleWaiters();
         return {
             done: true,
             value: undefined,

package/dist/runtime/in-memory-storage.d.ts

@@ -1,4 +1,4 @@
-import type { StorageAdapter } from '../types/memory.js';
+import type { StorageAdapter } from '@noetic-tools/memory';
 /**
  * @public Process-local, Map-backed StorageAdapter.
  *

package/dist/runtime/in-memory-storage.js

@@ -1,4 +1,4 @@
-import { frameworkCast } from '../util/framework-cast.js';
+import { frameworkCast } from '@noetic-tools/types';
 //#region Public API
 /**
  * @public Process-local, Map-backed StorageAdapter.

package/dist/runtime/item-log-impl.d.ts

@@ -1,6 +1,4 @@
-import type { ItemSchemaRegistry } from '../schemas/item.js';
-import type { ItemLog } from '../types/context-parts/item-log.js';
-import type { Item } from '../types/items.js';
+import type { Item, ItemLog, ItemSchemaRegistry } from '@noetic-tools/types';
 export declare class ItemLogImpl implements ItemLog {
     private readonly itemSchemas;
     private readonly _items;

package/dist/runtime/item-log-impl.js

@@ -1,4 +1,4 @@
-import { defaultItemSchemaRegistry } from '../schemas/item.js';
+import { defaultItemSchemaRegistry } from '@noetic-tools/types';
 export class ItemLogImpl {
     itemSchemas;
     _items = [];

package/dist/runtime/message-queue.d.ts

@@ -1,5 +1,4 @@
-import type { ExecuteInput } from '../types/items.js';
-import type { DeliveryMode, ExecuteOptions } from '../types/runtime.js';
+import type { DeliveryMode, ExecuteInput, ExecuteOptions } from '@noetic-tools/types';
 /** @internal A message accepted by `AgentHarness.execute()` and held until the
  *  session runner processes it. The effective `DeliveryMode` is resolved at
  *  enqueue time so the runner never has to look at harness defaults again. */

package/dist/runtime/session-runner.d.ts

@@ -1,7 +1,4 @@
-import type { Context } from '../types/context.js';
-import type { HarnessResponse } from '../types/harness-result.js';
-import type { Item } from '../types/items.js';
-import type { HarnessStatus } from '../types/runtime.js';
+import type { Context, HarnessResponse, HarnessStatus, Item } from '@noetic-tools/types';
 import { EventBroadcaster } from './event-broadcaster.js';
 import type { QueuedMessage } from './message-queue.js';
 import { MessageQueue } from './message-queue.js';

package/dist/runtime/session-streams.d.ts

@@ -1,5 +1,4 @@
-import type { ItemSchemaRegistry } from '../schemas/item.js';
-import type { StreamingItem } from '../types/harness-result.js';
+import type { ItemSchemaRegistry, StreamingItem } from '@noetic-tools/types';
 import type { EventBroadcaster } from './event-broadcaster.js';
 /** @internal Yield text deltas from the session broadcaster. */
 export declare function filterTextStream(broadcaster: EventBroadcaster): AsyncIterable<string>;

package/dist/runtime/session-streams.js

@@ -1,4 +1,4 @@
-import { defaultItemSchemaRegistry } from '../schemas/item.js';
+import { defaultItemSchemaRegistry } from '@noetic-tools/types';
 //#endregion
 //#region Helpers
 function isItemRecord(value) {

package/dist/runtime/step-registry.d.ts

@@ -1,5 +1,5 @@
-import type { ContextMemory } from '../types/memory.js';
-import type { Step } from '../types/step.js';
+import type { ContextMemory } from '@noetic-tools/memory';
+import type { Step } from '@noetic-tools/types';
 /** Registry-wide step type — stored at the widest generic parameters so
  *  callers can register steps with narrower input/output types without
  *  fighting variance. The public `Step` default already uses `unknown` for

package/dist/runtime/step-registry.js

@@ -1,6 +1,5 @@
-import { NoeticConfigError } from '../errors/noetic-config-error.js';
+import { frameworkCast, NoeticConfigError } from '@noetic-tools/types';
 import { setDefaultRegistrar } from '../types/step-registrar.js';
-import { frameworkCast } from '../util/framework-cast.js';
 //#endregion
 //#region Module state
 const registry = new Map();

package/dist/runtime/tool-memory.d.ts

@@ -1,6 +1,4 @@
+import type { AgentHarnessContract, Context, ToolExecutionContext, ToolMemory } from '@noetic-tools/types';
 import type { TurnContext } from '@openrouter/agent';
-import type { Context } from '../types/context.js';
-import type { AgentHarnessContract } from '../types/runtime.js';
-import type { ToolExecutionContext, ToolMemory } from '../types/tool-context.js';
 export declare function buildToolMemory(harness: AgentHarnessContract, ctx: Context): ToolMemory;
 export declare function buildToolExecutionContext(ctx: Context, harness: AgentHarnessContract, turnContext?: TurnContext): ToolExecutionContext;

package/dist/types/mutable-context.d.ts

@@ -1,6 +1,5 @@
-import type { StepMeta, TokenUsage } from './common.js';
-import type { Context } from './context.js';
-import type { ContextMemory } from './memory.js';
+import type { ContextMemory } from '@noetic-tools/memory';
+import type { Context, StepMeta, TokenUsage } from '@noetic-tools/types';
 /**
  * Internal-only interface for interpreter code that needs to mutate Context fields.
  * NOT exported from the package public API.

package/dist/types/step-registrar.d.ts

@@ -13,7 +13,7 @@
  * when an out-of-process child needs to look up a step by id. In-process
  * execution walks the step tree directly and never touches either side.
  */
-import type { Step } from './step.js';
+import type { Step } from '@noetic-tools/types';
 /**
  * @public
  * Registers a step under its `id` so the subprocess adapter can later

package/dist/unstable.d.ts

@@ -7,22 +7,18 @@
  * and other framework extensions. Do not depend on them in application code.
  */
 /** @unstable Budget allocation algorithm for memory layer token budgets. */
-export type { BudgetAllocation, BudgetLimits } from './memory/budget.js';
-/** @unstable Budget allocation and checking utilities. */
-export { allocateBudgets, checkBudget } from './memory/budget.js';
 /** @unstable Layer state store type for managing per-layer state during execution. */
-export type { LayerStateStore } from './memory/layer-lifecycle.js';
+export type { BudgetAllocation, BudgetLimits, LayerStateStore } from '@noetic-tools/memory';
+/** @unstable Budget allocation and checking utilities. */
 /** @unstable Factory for creating layer state stores. */
-export { createLayerStateStore } from './memory/layer-lifecycle.js';
 /** @unstable View assembly algorithm that converges memory layer outputs into the LLM context. */
-export { assembleView } from './memory/projector.js';
 /** @unstable Factory for creating scoped storage wrappers around a StorageAdapter. */
-export { createScopedStorage } from './memory/scope.js';
+export { allocateBudgets, assembleView, checkBudget, createLayerStateStore, createScopedStorage, } from '@noetic-tools/memory';
+/** @unstable Unsafe cast utility for bridging internal type boundaries. */
+export { frameworkCast } from '@noetic-tools/types';
 /**
  * @unstable Internal helper used by sync agent-spawn paths (worktree isolation)
  * to seed a child's cwd snapshot without touching `previousCwd`. Not part of
  * the public surface — call sites must hold exclusive use of the parent ctx.
  */
 export { retargetCwdForSpawn } from './runtime/cwd-helpers.js';
-/** @unstable Unsafe cast utility for bridging internal type boundaries. */
-export { frameworkCast } from './util/framework-cast.js';

package/dist/unstable.js

@@ -7,18 +7,15 @@
  * and other framework extensions. Do not depend on them in application code.
  */
 /** @unstable Budget allocation and checking utilities. */
-export { allocateBudgets, checkBudget } from './memory/budget.js';
 /** @unstable Factory for creating layer state stores. */
-export { createLayerStateStore } from './memory/layer-lifecycle.js';
 /** @unstable View assembly algorithm that converges memory layer outputs into the LLM context. */
-export { assembleView } from './memory/projector.js';
 /** @unstable Factory for creating scoped storage wrappers around a StorageAdapter. */
-export { createScopedStorage } from './memory/scope.js';
+export { allocateBudgets, assembleView, checkBudget, createLayerStateStore, createScopedStorage, } from '@noetic-tools/memory';
+/** @unstable Unsafe cast utility for bridging internal type boundaries. */
+export { frameworkCast } from '@noetic-tools/types';
 /**
  * @unstable Internal helper used by sync agent-spawn paths (worktree isolation)
  * to seed a child's cwd snapshot without touching `previousCwd`. Not part of
  * the public surface — call sites must hold exclusive use of the parent ctx.
  */
 export { retargetCwdForSpawn } from './runtime/cwd-helpers.js';
-/** @unstable Unsafe cast utility for bridging internal type boundaries. */
-export { frameworkCast } from './util/framework-cast.js';

package/dist/until/combinators.d.ts

@@ -1,4 +1,4 @@
-import type { Until } from '../types/step.js';
+import type { Until } from '@noetic-tools/types';
 /**
  * Combines predicates with OR semantics; stops the loop when any predicate says stop.
  *

package/dist/until/never.d.ts

@@ -1,4 +1,4 @@
-import type { Until } from '../types/step.js';
+import type { Until } from '@noetic-tools/types';
 /**
  * Termination predicate that never stops the loop. Use with `every`-like
  * forever-loops or with explicit cancellation paths.

package/dist/until/predicates.d.ts

@@ -1,6 +1,6 @@
+import type { StorageAdapter } from '@noetic-tools/memory';
+import type { Until } from '@noetic-tools/types';
 import type { EmbedFn } from '../types/embed.js';
-import type { StorageAdapter } from '../types/memory.js';
-import type { Until } from '../types/step.js';
 import { never } from './never.js';
 /** @public Async verification function that checks loop output and optionally returns feedback. */
 export type VerifyFn = (output: unknown) => Promise<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "0.2.1",
+  "version": "1.0.0",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and memory layer contract for Noetic agents.",
   "license": "Apache-2.0",
@@ -64,13 +64,15 @@
     }
   },
   "dependencies": {
+    "@noetic-tools/memory": "^1.0.1",
+    "@noetic-tools/types": "^1.0.0",
     "@openrouter/agent": "^0.6.0",
     "zod": "^4.0.0"
   },
   "scripts": {
     "build": "bunx tsc -p tsconfig.build.json && bun scripts/add-js-extensions.ts",
     "verify:esm": "bun scripts/verify-node-esm.ts",
-    "prepublishOnly": "rm -rf dist && bun run build && bun run verify:esm",
+    "prepublishOnly": "rm -rf dist && bun run build && bun run verify:esm && bun scripts/pin-workspace-deps.ts && bun scripts/strip-dev-conditions.ts",
     "test": "bun test",
     "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov",
     "test:ci": "bun test --coverage --coverage-reporter=lcov",

package/dist/errors/noetic-config-error.d.ts

@@ -1,41 +0,0 @@
-/**
- * @public
- * Configuration-time error thrown during construction and setup.
- *
- * `NoeticConfigError` is separate from `NoeticError`. The two are never interchangeable:
- * - `NoeticError` — thrown during execution (LLM failures, fork failures, budget exceeded).
- * - `NoeticConfigError` — thrown during construction (invalid step config, missing env vars, runtime misconfiguration).
- *
- * @example
- * ```ts
- * try {
- *   loop({ id: '', steps: [], until: until.maxSteps(10) });
- * } catch (e) {
- *   if (isNoeticConfigError(e)) {
- *     console.error(e.code, e.hint);
- *   }
- * }
- * ```
- */
-export declare class NoeticConfigError extends Error {
-    /** SCREAMING_SNAKE_CASE code uniquely identifying this error condition. */
-    readonly code: string;
-    /** Complete sentence describing what the user should do next. */
-    readonly hint: string;
-    /** Link to the relevant docs page, if available. */
-    readonly docsUrl?: string;
-    constructor(opts: {
-        code: string;
-        message: string;
-        hint: string;
-        docsUrl?: string;
-    });
-}
-/**
- * @public
- * Type guard for `NoeticConfigError`.
- *
- * @param e - Value to check.
- * @returns `true` if `e` is a `NoeticConfigError`.
- */
-export declare function isNoeticConfigError(e: unknown): e is NoeticConfigError;

package/dist/errors/noetic-config-error.js

@@ -1,44 +0,0 @@
-/**
- * @public
- * Configuration-time error thrown during construction and setup.
- *
- * `NoeticConfigError` is separate from `NoeticError`. The two are never interchangeable:
- * - `NoeticError` — thrown during execution (LLM failures, fork failures, budget exceeded).
- * - `NoeticConfigError` — thrown during construction (invalid step config, missing env vars, runtime misconfiguration).
- *
- * @example
- * ```ts
- * try {
- *   loop({ id: '', steps: [], until: until.maxSteps(10) });
- * } catch (e) {
- *   if (isNoeticConfigError(e)) {
- *     console.error(e.code, e.hint);
- *   }
- * }
- * ```
- */
-export class NoeticConfigError extends Error {
-    /** SCREAMING_SNAKE_CASE code uniquely identifying this error condition. */
-    code;
-    /** Complete sentence describing what the user should do next. */
-    hint;
-    /** Link to the relevant docs page, if available. */
-    docsUrl;
-    constructor(opts) {
-        super(opts.message);
-        this.name = 'NoeticConfigError';
-        this.code = opts.code;
-        this.hint = opts.hint;
-        this.docsUrl = opts.docsUrl;
-    }
-}
-/**
- * @public
- * Type guard for `NoeticConfigError`.
- *
- * @param e - Value to check.
- * @returns `true` if `e` is a `NoeticConfigError`.
- */
-export function isNoeticConfigError(e) {
-    return e instanceof NoeticConfigError;
-}

package/dist/errors/noetic-error.d.ts

@@ -1,18 +0,0 @@
-import type { NoeticError } from '../types/error.js';
-/**
- * Runtime error thrown during step execution (LLM failures, fork failures, budget exceeded, etc.).
- *
- * @public
- */
-export declare class NoeticErrorImpl extends Error {
-    readonly noeticError: NoeticError;
-    constructor(error: NoeticError);
-}
-/**
- * Type guard for `NoeticErrorImpl`.
- *
- * @public
- * @param e - Value to check.
- * @returns `true` if `e` is a `NoeticErrorImpl`.
- */
-export declare function isNoeticError(e: unknown): e is NoeticErrorImpl;

package/dist/errors/noetic-error.js

@@ -1,54 +0,0 @@
-/**
- * Runtime error thrown during step execution (LLM failures, fork failures, budget exceeded, etc.).
- *
- * @public
- */
-export class NoeticErrorImpl extends Error {
-    noeticError;
-    constructor(error) {
-        super(formatMessage(error));
-        this.name = 'NoeticError';
-        this.noeticError = error;
-    }
-}
-/**
- * Type guard for `NoeticErrorImpl`.
- *
- * @public
- * @param e - Value to check.
- * @returns `true` if `e` is a `NoeticErrorImpl`.
- */
-export function isNoeticError(e) {
-    return e instanceof NoeticErrorImpl;
-}
-function formatMessage(error) {
-    switch (error.kind) {
-        case 'step_failed':
-            return `Step '${error.stepId}' failed: ${error.cause.message}`;
-        case 'llm_refused':
-            return `LLM refused at step '${error.stepId}': ${error.refusal}`;
-        case 'llm_parse_error':
-            return `LLM parse error at step '${error.stepId}': failed to parse output`;
-        case 'llm_rate_limit':
-            return `LLM rate limited at step '${error.stepId}'${error.retryAfter ? ` (retry after ${error.retryAfter}ms)` : ''}`;
-        case 'fork_partial':
-            return `Fork '${error.stepId}' partial failure: ${error.succeeded.length} succeeded, ${error.failed.length} failed`;
-        case 'channel_timeout':
-            return `Channel '${error.channelName}' timed out after ${error.timeout}ms`;
-        case 'channel_closed':
-            return `Channel '${error.channelName}' is closed`;
-        case 'cancelled':
-            return `Cancelled${error.reason ? `: ${error.reason}` : ''}`;
-        case 'budget_exceeded':
-            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;
-            return 'NoeticError: unknown kind';
-        }
-    }
-}

package/dist/memory/budget.d.ts

@@ -1,23 +0,0 @@
-import type { Context } from '../types/context.js';
-import type { MemoryLayer } from '../types/memory.js';
-export interface BudgetAllocation {
-    layerId: string;
-    allocated: number;
-}
-interface AllocateBudgetsOpts {
-    layers: MemoryLayer[];
-    totalBudget: number;
-    systemPromptTokens: number;
-    responseReserve: number;
-}
-export declare function allocateBudgets({ layers, totalBudget, systemPromptTokens, responseReserve, }: AllocateBudgetsOpts): {
-    allocations: BudgetAllocation[];
-    historyBudget: number;
-};
-export interface BudgetLimits {
-    maxCost?: number;
-    maxSteps?: number;
-    maxDuration?: number;
-}
-export declare function checkBudget(ctx: Context, limits: BudgetLimits): void;
-export {};