@noetic-tools/core 5.7.0 → 5.9.0

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

@@ -1,5 +1,6 @@
 import type { LayerStateStore } from '@noetic-tools/context';
 import type { Context, Item, ItemSchemaRegistry, RestoreContextOptions } from '@noetic-tools/types';
+import type { ChannelStore } from '../channel-store.js';
 import type { EventBroadcaster } from '../event-broadcaster.js';
 import type { CheckpointStore } from './checkpoint-store.js';
 import type { StepLedgerRetention, StepLedgerStore } from './step-ledger.js';
@@ -28,6 +29,7 @@ export interface CheckpointHarnessHandle {
     readonly stepLedgerStore?: StepLedgerStore;
     readonly stepLedgerRetention?: StepLedgerRetention;
     readonly layerStateStore: LayerStateStore;
+    readonly channelStore: Pick<ChannelStore, 'snapshot' | 'restore'>;
     readonly itemSchemas: ItemSchemaRegistry;
     createContext(opts?: RestoreCheckpointOptions & {
         items?: Item[];
@@ -47,27 +49,42 @@ export interface CheckpointHarnessHandle {
  */
 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 context projectors.
+ * What `restoreFromCheckpoint` rebuilt. `fromSnapshot` is false for a ledger-only
+ * restore, whose layer state was never recovered — the harness must then let layer
+ * `init` hydrate normally instead of keeping restored state.
  *
- * `opts` carries the host's own context wiring (broadcaster, parent, state,
- * layer overrides) into the rebuilt context. A snapshot cannot round-trip live
- * objects, so a host that decorated the original context has to hand the same
- * decoration back here — otherwise the resumed run gets a bare context and
- * whatever depended on that wiring stops working silently. Snapshot-owned
- * fields always win: identity, item log, and cwd come from the persisted
- * record, never from `opts`.
+ * @internal
+ */
+export interface RestoredExecution {
+    ctx: Context;
+    fromSnapshot: boolean;
+}
+/**
+ * Rebuild a `Context` for `executionId` from what a previous run recorded: the
+ * checkpoint snapshot and the step-completion ledger. Either is enough. Returns
+ * `null` only when neither exists, so the caller starts a fresh execution.
+ *
+ * - With a snapshot, the item log, layer state, channel state, cwd, and thread/resource
+ *   ids come from it. Layer state is replayed into `layerStateStore` under the original
+ *   id; channel values and queued items refill the channel store for channels with no
+ *   live state.
+ * - Without one, the context starts like `createContext(opts)` would — empty item
+ *   log, no layer or channel state, the harness's root cwd, fresh thread id — and only
+ *   its identity and ledger are recovered. Recorded steps replay; the rest run fresh.
+ *
+ * `opts` carries the host's own context wiring (broadcaster, parent, state, layer
+ * overrides). A snapshot cannot round-trip live objects, so a host that decorated
+ * the original context has to hand the same decoration back here. Snapshot-owned
+ * fields always win: identity, item log, and cwd come from the persisted record,
+ * never from `opts`.
  *
- * Preserves the original executionId on the returned context via
- * `Object.defineProperty` — adapter correlation across crash/restart
- * requires a stable id.
+ * A snapshot whose schema version is unknown throws
+ * `NoeticConfigError(CHECKPOINT_SCHEMA_MISMATCH)` from the store; the ledger is not
+ * used as a fallback, because resuming onto it would drop state the snapshot held.
  *
  * @internal
  */
-export declare function restoreFromCheckpoint(h: CheckpointHarnessHandle, executionId: string, opts?: RestoreCheckpointOptions): Promise<Context | null>;
+export declare function restoreFromCheckpoint(h: CheckpointHarnessHandle, executionId: string, opts?: RestoreCheckpointOptions): Promise<RestoredExecution | null>;
 /**
  * Discard every recovery record for one execution: the snapshot and the completion
  * ledger. Clearing the snapshot alone would strand the ledger's shards under

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

@@ -1,5 +1,5 @@
 import { CheckpointSchemaVersion } from '../../types/checkpoint.js';
-import { ContextImpl } from '../context-impl.js';
+import { ContextImpl, rootIdOf } from '../context-impl.js';
 import { StepLedger } from './step-ledger.js';
 //#endregion
 //#region captureCheckpoint
@@ -47,6 +47,9 @@ export async function captureCheckpoint(h, ctx) {
                 ...ctx.itemLog.items,
             ],
         },
+        // Channel state belongs to the root execution, so a child checkpoint
+        // carries the channels its root used.
+        channels: h.channelStore.snapshot(rootIdOf(ctx)),
         capturedAt: new Date().toISOString(),
     };
     try {
@@ -56,26 +59,28 @@ export async function captureCheckpoint(h, ctx) {
         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 context projectors.
+ * Rebuild a `Context` for `executionId` from what a previous run recorded: the
+ * checkpoint snapshot and the step-completion ledger. Either is enough. Returns
+ * `null` only when neither exists, so the caller starts a fresh execution.
+ *
+ * - With a snapshot, the item log, layer state, channel state, cwd, and thread/resource
+ *   ids come from it. Layer state is replayed into `layerStateStore` under the original
+ *   id; channel values and queued items refill the channel store for channels with no
+ *   live state.
+ * - Without one, the context starts like `createContext(opts)` would — empty item
+ *   log, no layer or channel state, the harness's root cwd, fresh thread id — and only
+ *   its identity and ledger are recovered. Recorded steps replay; the rest run fresh.
  *
- * `opts` carries the host's own context wiring (broadcaster, parent, state,
- * layer overrides) into the rebuilt context. A snapshot cannot round-trip live
- * objects, so a host that decorated the original context has to hand the same
- * decoration back here — otherwise the resumed run gets a bare context and
- * whatever depended on that wiring stops working silently. Snapshot-owned
- * fields always win: identity, item log, and cwd come from the persisted
- * record, never from `opts`.
+ * `opts` carries the host's own context wiring (broadcaster, parent, state, layer
+ * overrides). A snapshot cannot round-trip live objects, so a host that decorated
+ * the original context has to hand the same decoration back here. Snapshot-owned
+ * fields always win: identity, item log, and cwd come from the persisted record,
+ * never from `opts`.
  *
- * Preserves the original executionId on the returned context via
- * `Object.defineProperty` — adapter correlation across crash/restart
- * requires a stable id.
+ * A snapshot whose schema version is unknown throws
+ * `NoeticConfigError(CHECKPOINT_SCHEMA_MISMATCH)` from the store; the ledger is not
+ * used as a fallback, because resuming onto it would drop state the snapshot held.
  *
  * @internal
  */
@@ -85,52 +90,69 @@ export async function restoreFromCheckpoint(h, executionId, opts) {
         return null;
     }
     const snapshot = await store.load(executionId);
-    if (!snapshot) {
+    const recovered = await h.stepLedgerStore?.load(executionId);
+    if (!snapshot && (!recovered || recovered.entries.size === 0)) {
         return null;
     }
+    const ctx = snapshot ? contextFromSnapshot(h, snapshot, opts) : h.createContext(opts);
+    if (ctx instanceof ContextImpl) {
+        adoptExecution({
+            h,
+            ctx,
+            executionId,
+            recovered,
+        });
+    }
+    return {
+        ctx,
+        fromSnapshot: snapshot !== null,
+    };
+}
+/** Replay a snapshot's layer and channel state and build the context its item log and cwd describe. */
+function contextFromSnapshot(h, snapshot, opts) {
     for (const [layerId, state] of Object.entries(snapshot.layers)) {
-        h.layerStateStore.set(executionId, layerId, state);
+        h.layerStateStore.set(snapshot.executionId, layerId, state);
     }
-    const items = h.itemSchemas.parseMany(snapshot.itemLog.items);
-    const cwdInit = snapshot.cwd?.current ?? undefined;
+    h.channelStore.restore(snapshot.executionId, snapshot.channels ?? []);
     /* Caller wiring first, snapshot second: a host may legitimately swap the context
      * layers or hang the restored execution under a new parent, but it must never be
      * able to override the identity/history the snapshot is the record of. */
-    const ctx = h.createContext({
+    return h.createContext({
         ...opts,
-        items,
+        items: h.itemSchemas.parseMany(snapshot.itemLog.items),
         threadId: snapshot.threadId,
         resourceId: snapshot.resourceId,
-        cwdInit,
+        cwdInit: snapshot.cwd?.current ?? undefined,
     });
-    if (ctx instanceof ContextImpl) {
-        Object.defineProperty(ctx, 'id', {
-            value: executionId,
-            configurable: false,
-            writable: false,
-            enumerable: true,
-        });
-        /* Attach the recovered completion ledger. `createContext` already built a fresh
-         * one keyed to a throwaway id; the restored context needs the entries recorded
-         * under THIS execution, or `execute()` would replay nothing and re-run the whole
-         * tree. Assigned the same way `id` is, to keep `createContext`'s public options
-         * free of resume-only fields. */
-        if (h.stepLedgerStore) {
-            const recovered = await h.stepLedgerStore.load(executionId);
-            Object.defineProperty(ctx, 'ledger', {
-                value: new StepLedger({
-                    executionId,
-                    store: h.stepLedgerStore,
-                    recovered,
-                    retention: h.stepLedgerRetention,
-                }),
-                configurable: false,
-                writable: false,
-                enumerable: true,
-            });
-        }
+}
+/**
+ * Give `ctx` the original execution id and the ledger recorded under it.
+ * `createContext` already built a fresh ledger keyed to a throwaway id; without the
+ * recovered one `execute()` would replay nothing and re-run the whole tree. Both are
+ * assigned with `defineProperty` to keep `createContext`'s public options free of
+ * resume-only fields — adapter correlation across a restart needs the stable id.
+ */
+function adoptExecution({ h, ctx, executionId, recovered, }) {
+    Object.defineProperty(ctx, 'id', {
+        value: executionId,
+        configurable: false,
+        writable: false,
+        enumerable: true,
+    });
+    if (!h.stepLedgerStore || !recovered) {
+        return;
     }
-    return ctx;
+    Object.defineProperty(ctx, 'ledger', {
+        value: new StepLedger({
+            executionId,
+            store: h.stepLedgerStore,
+            recovered,
+            retention: h.stepLedgerRetention,
+        }),
+        configurable: false,
+        writable: false,
+        enumerable: true,
+    });
 }
 //#endregion
 //#region clearCheckpoint

package/dist/runtime/durable/step-ledger.d.ts

@@ -2,7 +2,7 @@
  * The step completion ledger: what a resumed execution replays instead of re-running.
  *
  * The frontier records which steps were IN FLIGHT at snapshot time; it says nothing
- * about which ones finished, and a finished step leaves no trace once `leaveStep` pops
+ * about which ones finished, and a finished step leaves no trace once `leaveStep` drops
  * it. Resume therefore needs a separate record — and it must carry each step's OUTPUT,
  * not merely a "done" flag: steps consume the previous step's value, and a `callModel` step
  * re-run to catch up produces a different one than the rest of the run already saw.
@@ -11,6 +11,12 @@
  * into the single `execution:<id>:snapshot` key would rewrite a growing blob on every
  * step — O(n²) bytes over a run.
  *
+ * An entry's key is one of two forms (spec 23a § Identity). By default it is the step's
+ * execution path (`ContextImpl.currentPath()`): positional, so a resumed run lines up
+ * recorded outputs with steps by where they ran. A step with a `replayKey` is keyed
+ * `key:<replayKey>` instead: content-addressed, so it finds its output wherever it
+ * runs. A `durable: false` step has no key and is never recorded.
+ *
  * Sharding bounds the cost of one append but not the total, so retention is bounded on
  * two axes (`StepLedgerRetention`): an oversized entry is dropped rather than written,
  * and past `maxEntries` the oldest entry is evicted. Both degradations are safe by
@@ -19,7 +25,9 @@
  */
 import type { StorageAdapter } from '@noetic-tools/context';
 import { z } from 'zod';
-/** @public One completed step, keyed by its execution path. */
+/** Marks a ledger key as a step's `replayKey` rather than its execution path. */
+export declare const REPLAY_KEY_PREFIX = "key:";
+/** @public One completed step, keyed by its execution path or its `key:` replay key. */
 export declare const StepLedgerEntrySchema: z.ZodObject<{
     path: z.ZodString;
     stepId: z.ZodString;
@@ -153,9 +161,11 @@ export declare class StepLedger {
     get stats(): StepLedgerStats;
     /**
      * The recorded output for `path`, when a previous run completed the same step there.
-     * A divergence (different step id or kind at this path) discards the entry and every
-     * entry recorded beneath it, then returns undefined so the step runs fresh — the
-     * subtree's recorded outputs belong to a branch that no longer exists.
+     * A divergence (different step id or kind at this key) returns undefined so the step
+     * runs fresh. At a positional path it also discards every entry recorded beneath it —
+     * the subtree's recorded outputs belong to a branch that no longer exists. A `key:`
+     * entry discards only itself: its children are keyed by their own paths or keys, not
+     * nested under it.
      */
     take(path: string, step: {
         id: string;

package/dist/runtime/durable/step-ledger.js

@@ -2,7 +2,7 @@
  * The step completion ledger: what a resumed execution replays instead of re-running.
  *
  * The frontier records which steps were IN FLIGHT at snapshot time; it says nothing
- * about which ones finished, and a finished step leaves no trace once `leaveStep` pops
+ * about which ones finished, and a finished step leaves no trace once `leaveStep` drops
  * it. Resume therefore needs a separate record — and it must carry each step's OUTPUT,
  * not merely a "done" flag: steps consume the previous step's value, and a `callModel` step
  * re-run to catch up produces a different one than the rest of the run already saw.
@@ -11,6 +11,12 @@
  * into the single `execution:<id>:snapshot` key would rewrite a growing blob on every
  * step — O(n²) bytes over a run.
  *
+ * An entry's key is one of two forms (spec 23a § Identity). By default it is the step's
+ * execution path (`ContextImpl.currentPath()`): positional, so a resumed run lines up
+ * recorded outputs with steps by where they ran. A step with a `replayKey` is keyed
+ * `key:<replayKey>` instead: content-addressed, so it finds its output wherever it
+ * runs. A `durable: false` step has no key and is never recorded.
+ *
  * Sharding bounds the cost of one append but not the total, so retention is bounded on
  * two axes (`StepLedgerRetention`): an oversized entry is dropped rather than written,
  * and past `maxEntries` the oldest entry is evicted. Both degradations are safe by
@@ -21,9 +27,14 @@ import { storageGetMany } from '@noetic-tools/context';
 import { NoeticConfigError } from '@noetic-tools/types';
 import { z } from 'zod';
 //#region Entry
-/** @public One completed step, keyed by its execution path. */
+/** Marks a ledger key as a step's `replayKey` rather than its execution path. */
+export const REPLAY_KEY_PREFIX = 'key:';
+/** @public One completed step, keyed by its execution path or its `key:` replay key. */
 export const StepLedgerEntrySchema = z.object({
-    /** Execution path key — see `ContextImpl.currentPath()`. Unique per dispatch. */
+    /**
+     * Ledger key: the execution path (`ContextImpl.currentPath()`, unique per dispatch)
+     * or `key:<replayKey>` for a step that sets `replayKey`.
+     */
     path: z.string().min(1),
     stepId: z.string(),
     kind: z.string(),
@@ -197,9 +208,11 @@ export class StepLedger {
     }
     /**
      * The recorded output for `path`, when a previous run completed the same step there.
-     * A divergence (different step id or kind at this path) discards the entry and every
-     * entry recorded beneath it, then returns undefined so the step runs fresh — the
-     * subtree's recorded outputs belong to a branch that no longer exists.
+     * A divergence (different step id or kind at this key) returns undefined so the step
+     * runs fresh. At a positional path it also discards every entry recorded beneath it —
+     * the subtree's recorded outputs belong to a branch that no longer exists. A `key:`
+     * entry discards only itself: its children are keyed by their own paths or keys, not
+     * nested under it.
      */
     take(path, step) {
         const entry = this.replayable.get(path);
@@ -207,6 +220,10 @@ export class StepLedger {
             return undefined;
         }
         if (entry.stepId !== step.id || entry.kind !== step.kind) {
+            if (path.startsWith(REPLAY_KEY_PREFIX)) {
+                this.replayable.delete(path);
+                return undefined;
+            }
             this.discardSubtree(path);
             return undefined;
         }

package/dist/schemas/workflow.d.ts

@@ -3,5 +3,5 @@
  * consumers can validate workflow documents without importing core.
  * This barrel keeps core's public and intra-core import paths unchanged.
  */
-export type { AcpAgentWorkflowNode, CallModelWorkflowNode, ConditionalRoute, ConditionalWorkflowNode, DecideWorkflowNode, InParallelWorkflowNode, InvokeToolWorkflowNode, LoopWorkflowNode, OutputCodecRef, RouteSwitchWorkflowNode, RunCodeWorkflowNode, ScheduleWorkflowNode, SequenceWorkflowNode, SpawnWorkflowNode, SubflowWorkflowNode, UntilPredicate, WithContextWorkflowNode, WorkflowDocument, WorkflowGraph, WorkflowNode, } from '@noetic-tools/types';
+export type { AcpAgentWorkflowNode, CallModelWorkflowNode, ConditionalRoute, ConditionalWorkflowNode, DecideWorkflowNode, InParallelWorkflowNode, InvokeToolWorkflowNode, LoopWorkflowNode, OutputCodecRef, RouteSwitchWorkflowNode, RunCodeWorkflowNode, ScheduleWorkflowNode, SequenceWorkflowNode, SpawnWorkflowNode, SubflowWorkflowNode, UntilPredicate, WithContextWorkflowNode, WorkflowDocument, WorkflowGraph, WorkflowNode, WorkflowReplayKey, } from '@noetic-tools/types';
 export { MergeStrategy, MergeStrategySchema, UntilPredicateSchema, validateWorkflow, WorkflowDocumentSchema, WorkflowNodeSchema, walkWorkflow, workflowDepth, workflowGraph, } from '@noetic-tools/types';

package/dist/types/checkpoint.d.ts

@@ -72,6 +72,26 @@ export declare const ItemLogSnapshotSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** @public Item log portion of a snapshot. */
 export type ItemLogSnapshot = z.infer<typeof ItemLogSnapshotSchema>;
+/**
+ * @public
+ * Channel state an execution used, captured so a restored execution sees the
+ * same values and queued items. Only stored data is kept — parked receivers,
+ * parked senders, and subscribers are live promises that cannot round-trip.
+ * Topic channels hold no stored data, so they never appear.
+ */
+export declare const ChannelSnapshotSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    name: z.ZodString;
+    mode: z.ZodLiteral<"value">;
+    value: z.ZodOptional<z.ZodUnknown>;
+    hasValue: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    mode: z.ZodLiteral<"queue">;
+    capacity: z.ZodNumber;
+    queue: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strip>], "mode">;
+/** @public One channel's stored state inside a checkpoint snapshot. */
+export type ChannelSnapshot = z.infer<typeof ChannelSnapshotSchema>;
 /**
  * @public
  * Top-level checkpoint payload persisted through a `CheckpointStore`. Carries
@@ -101,6 +121,17 @@ export declare const CheckpointSnapshotSchema: z.ZodObject<{
     itemLog: z.ZodObject<{
         items: z.ZodArray<z.ZodUnknown>;
     }, z.core.$strip>;
+    channels: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        name: z.ZodString;
+        mode: z.ZodLiteral<"value">;
+        value: z.ZodOptional<z.ZodUnknown>;
+        hasValue: z.ZodBoolean;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodString;
+        mode: z.ZodLiteral<"queue">;
+        capacity: z.ZodNumber;
+        queue: z.ZodArray<z.ZodUnknown>;
+    }, z.core.$strip>], "mode">>>;
     capturedAt: z.ZodString;
 }, z.core.$strip>;
 /** @public Snapshot of an execution suitable for `CheckpointStore.save()`. */

package/dist/types/checkpoint.js

@@ -68,6 +68,29 @@ export const PendingAskUserSnapshotSchema = z.object({
 export const ItemLogSnapshotSchema = z.object({
     items: z.array(z.unknown()),
 });
+/**
+ * @public
+ * Channel state an execution used, captured so a restored execution sees the
+ * same values and queued items. Only stored data is kept — parked receivers,
+ * parked senders, and subscribers are live promises that cannot round-trip.
+ * Topic channels hold no stored data, so they never appear.
+ */
+export const ChannelSnapshotSchema = z.discriminatedUnion('mode', [
+    z.object({
+        name: z.string(),
+        mode: z.literal('value'),
+        /** The last value written. Absent when the channel was never written. */
+        value: z.unknown().optional(),
+        hasValue: z.boolean(),
+    }),
+    z.object({
+        name: z.string(),
+        mode: z.literal('queue'),
+        capacity: z.number(),
+        /** Queued items, oldest first. */
+        queue: z.array(z.unknown()),
+    }),
+]);
 /**
  * @public
  * Top-level checkpoint payload persisted through a `CheckpointStore`. Carries
@@ -84,6 +107,12 @@ export const CheckpointSnapshotSchema = z.object({
     cwd: CwdSnapshotSchema.nullable(),
     askUser: z.array(PendingAskUserSnapshotSchema),
     itemLog: ItemLogSnapshotSchema,
+    /**
+     * Stored state of every channel the execution used. Optional so snapshots
+     * written before channels were captured still load (they restore with no
+     * channel state).
+     */
+    channels: z.array(ChannelSnapshotSchema).optional(),
     /** ISO-8601 timestamp of when the snapshot was taken. */
     capturedAt: z.string(),
 });

package/dist/until/combinators.d.ts

@@ -2,6 +2,11 @@ import type { Until } from '@noetic-tools/types';
 /**
  * Combines predicates with OR semantics; stops the loop when any predicate says stop.
  *
+ * Predicates run in order and the first stop verdict short-circuits, so it is
+ * returned as is. When none stops, the combined verdict carries every
+ * predicate's `reason` (joined with `'; '`) and `feedback` (joined with `'\n'`),
+ * so a failing `until.verified()` still hands its feedback to `prepareNext`.
+ *
  * @public
  * @param predicates - Until predicates to evaluate.
  * @returns A combined `Until` that short-circuits on the first stop verdict.
@@ -10,6 +15,11 @@ export declare function any(...predicates: Until[]): Until;
 /**
  * Combines predicates with AND semantics; stops the loop only when all predicates say stop.
  *
+ * Predicates run in order and the first continue verdict short-circuits, so it
+ * is returned as is. When all stop, the combined verdict carries every
+ * predicate's `reason` (joined with `'; '`, default `'All predicates
+ * satisfied'`) and `feedback` (joined with `'\n'`).
+ *
  * @public
  * @param predicates - Until predicates to evaluate.
  * @returns A combined `Until` that requires all predicates to be satisfied.

package/dist/until/combinators.js

@@ -1,26 +1,36 @@
 /**
  * Combines predicates with OR semantics; stops the loop when any predicate says stop.
  *
+ * Predicates run in order and the first stop verdict short-circuits, so it is
+ * returned as is. When none stops, the combined verdict carries every
+ * predicate's `reason` (joined with `'; '`) and `feedback` (joined with `'\n'`),
+ * so a failing `until.verified()` still hands its feedback to `prepareNext`.
+ *
  * @public
  * @param predicates - Until predicates to evaluate.
  * @returns A combined `Until` that short-circuits on the first stop verdict.
  */
 export function any(...predicates) {
     return async (snapshot) => {
+        const verdicts = [];
         for (const pred of predicates) {
             const verdict = await pred(snapshot);
             if (verdict.stop) {
                 return verdict;
             }
+            verdicts.push(verdict);
         }
-        return {
-            stop: false,
-        };
+        return merge(false, verdicts);
     };
 }
 /**
  * Combines predicates with AND semantics; stops the loop only when all predicates say stop.
  *
+ * Predicates run in order and the first continue verdict short-circuits, so it
+ * is returned as is. When all stop, the combined verdict carries every
+ * predicate's `reason` (joined with `'; '`, default `'All predicates
+ * satisfied'`) and `feedback` (joined with `'\n'`).
+ *
  * @public
  * @param predicates - Until predicates to evaluate.
  * @returns A combined `Until` that requires all predicates to be satisfied.
@@ -30,20 +40,34 @@ export function all(...predicates) {
         const verdicts = [];
         for (const pred of predicates) {
             const verdict = await pred(snapshot);
-            verdicts.push(verdict);
             if (!verdict.stop) {
-                return {
-                    stop: false,
-                };
+                return verdict;
             }
+            verdicts.push(verdict);
         }
-        const reasons = verdicts
-            .map((v) => v.reason)
-            .filter(Boolean)
-            .join('; ');
+        const merged = merge(true, verdicts);
         return {
-            stop: true,
-            reason: reasons || 'All predicates satisfied',
+            ...merged,
+            reason: merged.reason ?? 'All predicates satisfied',
         };
     };
 }
+/** Folds the verdicts that decided a combinator into one, leaving out empty fields. */
+function merge(stop, verdicts) {
+    const verdict = {
+        stop,
+    };
+    const reason = join(verdicts.map((v) => v.reason), '; ');
+    if (reason !== undefined) {
+        verdict.reason = reason;
+    }
+    const feedback = join(verdicts.map((v) => v.feedback), '\n');
+    if (feedback !== undefined) {
+        verdict.feedback = feedback;
+    }
+    return verdict;
+}
+function join(parts, separator) {
+    const present = parts.filter((p) => p !== undefined && p !== '');
+    return present.length === 0 ? undefined : present.join(separator);
+}

package/dist/until/predicates.js

@@ -18,7 +18,9 @@ export const until = {
     maxCost(usd) {
         return (snap) => ({
             stop: snap.cost >= usd,
-            reason: snap.cost >= usd ? `Reached max cost ($${usd})` : undefined,
+            reason: snap.cost >= usd
+                ? `Cost $${snap.cost.toFixed(2)} exceeded budget $${usd.toFixed(2)}`
+                : undefined,
         });
     },
     /** Stops the loop when elapsed time reaches `ms` milliseconds. @public */
@@ -52,7 +54,7 @@ export const until = {
             const result = await fn(snap.lastOutput);
             return {
                 stop: result.pass,
-                reason: result.pass ? 'Verification passed' : undefined,
+                reason: result.pass ? 'Verification passed' : 'Verification failed',
                 feedback: result.feedback,
             };
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "5.7.0",
+  "version": "5.9.0",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and context layer contract for Noetic agents.",
   "license": "Apache-2.0",
@@ -68,8 +68,8 @@
     }
   },
   "dependencies": {
-    "@noetic-tools/context": "^1.4.0",
-    "@noetic-tools/types": "^3.5.0",
+    "@noetic-tools/context": "^1.6.0",
+    "@noetic-tools/types": "^3.7.0",
     "@openrouter/agent": "^0.11.0",
     "@openrouter/sdk": "1.4.25",
     "zod": "^4.0.0"