@noetic-tools/core 5.4.2 → 5.6.0

package/dist/conditions/conditions.js

@@ -1,5 +1,5 @@
 import { storageGetMany } from '@noetic-tools/context';
-import { createMessage, extractAssistantText, trackUsage } from '@noetic-tools/types';
+import { DecideOutputError, isNoeticError, NoeticErrorImpl, trackUsage } from '@noetic-tools/types';
 import { z } from 'zod';
 import { cosineSimilarity } from './cosine-similarity.js';
 //#endregion
@@ -234,41 +234,100 @@ export function allCondition(...conditions) {
 }
 //#endregion
 //#region aiCondition
-const AiConditionResponseSchema = z.object({
-    answer: z.boolean(),
-});
 /**
- * Creates a condition that uses an LLM to classify the input as true or false.
+ * Creates a condition that asks a model a yes/no question about the input — a
+ * one-question `decide`. Works with decision models natively and with chat
+ * models through estimated probabilities.
  *
  * @public
- * @param opts - Configuration with model identifier and classification prompt.
- * @returns A `Condition` that delegates boolean classification to the model.
+ * @param opts.model - Decision or chat model id.
+ * @param opts.prompt - The yes/no question.
+ * @param opts.threshold - Probability of yes at or above which the condition holds. Default 0.5.
+ * @returns A `Condition` that is true when the model answers yes. A refusal counts as no.
+ * @throws `NoeticError` `model_parse_error` when the response is not a boolean answer.
  */
 export function aiCondition(opts) {
     return async (input, ctx) => {
-        const text = serializeInput(input);
-        const systemPrompt = `You are a boolean classifier. Given the user's input, answer the following question with JSON: {"answer": true} or {"answer": false}.\n\nQuestion: ${opts.prompt}`;
-        const items = [
-            createMessage(systemPrompt, 'developer'),
-            createMessage(text, 'user'),
-        ];
-        const response = await ctx.harness.callModel({
+        const response = await askDecide(ctx, {
             model: opts.model,
-            items,
-            params: {
-                temperature: 0,
+            state: [
+                {
+                    type: 'text',
+                    name: 'input',
+                    text: serializeInput(input),
+                },
+            ],
+            questions: {
+                answer: {
+                    type: 'boolean',
+                    instructions: opts.prompt,
+                    threshold: opts.threshold,
+                },
             },
         });
-        trackUsage(ctx, response);
-        const responseText = extractAssistantText(response.items);
-        try {
-            const parsed = JSON.parse(responseText);
-            const validated = AiConditionResponseSchema.parse(parsed);
-            return validated.answer;
-        }
-        catch {
+        trackUsage(ctx, {
+            items: [],
+            usage: response.usage,
+            cost: response.cost,
+        });
+        const answer = response.answers.answer;
+        if (answer?.type === 'refusal') {
             return false;
         }
+        const parsed = AiConditionAnswerSchema.safeParse(answer);
+        if (!parsed.success) {
+            throw new NoeticErrorImpl({
+                kind: 'model_parse_error',
+                stepId: 'aiCondition',
+                raw: JSON.stringify(answer),
+                schema: AiConditionAnswerSchema,
+                zodError: parsed.error,
+            });
+        }
+        return parsed.data.value;
     };
 }
+async function askDecide(ctx, request) {
+    try {
+        return await ctx.harness.decide(request);
+    }
+    catch (e) {
+        if (isNoeticError(e)) {
+            throw e;
+        }
+        if (ctx.aborted) {
+            throw new NoeticErrorImpl({
+                kind: 'cancelled',
+                reason: ctx.abortReason ?? 'context aborted',
+            });
+        }
+        if (e instanceof DecideOutputError) {
+            if (e.usage) {
+                trackUsage(ctx, {
+                    items: [],
+                    usage: e.usage,
+                    cost: e.cost,
+                });
+            }
+            throw new NoeticErrorImpl({
+                kind: 'model_parse_error',
+                stepId: 'aiCondition',
+                raw: e.raw,
+                schema: e.schema,
+                zodError: e.zodError,
+            });
+        }
+        throw new NoeticErrorImpl({
+            kind: 'step_failed',
+            stepId: 'aiCondition',
+            cause: e instanceof Error ? e : new Error(String(e)),
+            retriesExhausted: false,
+        });
+    }
+}
+const AiConditionAnswerSchema = z.object({
+    type: z.literal('boolean'),
+    value: z.boolean(),
+    probability: z.number().min(0).max(1),
+});
 //#endregion

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

@@ -3,7 +3,7 @@ import { AcpSessionStore } from '../runtime/acp-session-store.js';
 import type { LayerStateStore, RecallCache } from './deps/context.js';
 import type { DetachedSpawnOverrides } from './deps/interpreter.js';
 import type { CheckpointStore, EventBroadcaster, RestoreCheckpointOptions, StepLedgerRetention, StepLedgerStore } from './deps/runtime.js';
-import type { AcpLiveSession, AcpSessionInfo, AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextCacheConfig, ContextCacheStore, ContextData, ContextLayer, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaConfig, LLMResponse, LlmProviderConfig, ProjectionPolicy, RecallLayerOutput, SessionScope, SessionUsage, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
+import type { AcpLiveSession, AcpSessionInfo, AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextCacheConfig, ContextCacheStore, ContextData, ContextLayer, CwdState, DecideRequest, DecideResponse, DecisionRecord, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaConfig, LLMResponse, LlmProviderConfig, ProjectionPolicy, RecallLayerOutput, RecallOptions, SessionScope, SessionUsage, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
 export { createStreamIdleWatchdog } from './model-call.js';
 /**
  * Storage-scoped environment configuration for `AgentHarness`.
@@ -87,8 +87,12 @@ interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<stri
      * those produced by spawn/fork. Defaults to `process.cwd()`.
      */
     initialCwd?: string;
+    /** Default model for `decide` steps. */
+    decisionModel?: string;
     /** @internal Test-only escape hatch to inject a mock callModel implementation. */
     _testCallModel?: (request: CallModelRequest) => Promise<LLMResponse>;
+    /** @internal Test-only escape hatch to inject a mock decide implementation. */
+    _testDecide?: (request: DecideRequest) => Promise<DecideResponse>;
 }
 /** Env vars consulted when resolving the LLM client (read defensively so the
  *  harness also works in runtimes without a `process` global, e.g. the browser). */
@@ -154,6 +158,11 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      *  without friend-class gymnastics. Do not access from outside core. */
     readonly _contextLayers?: ContextLayer[];
     private readonly client?;
+    /** SDK 1.x client for the decisions endpoint; the agent's client predates it. */
+    private readonly decisionsClient?;
+    private readonly decideOverride?;
+    /** Model id → whether it answers natively as a decision model. */
+    private readonly decisionModels;
     private readonly channelStore;
     /** Re-entrant `run()` depth per root context id — see `executeClosingChannels`. */
     private readonly rootRunDepth;
@@ -207,6 +216,8 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      * `ctx.id` (the layer-state store's executionId).
      */
     private readonly initializedExecutions;
+    /** Executions restored from a checkpoint: their first layer init keeps the restored state. */
+    private readonly restoredExecutions;
     readonly traceExporter: TraceExporter;
     /**
      * Long-lived shared cwd state. The same reference is seeded into every
@@ -242,6 +253,8 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     private getOrCreateSession;
     private requireSession;
     callModel(request: CallModelRequest): Promise<LLMResponse>;
+    decide(request: DecideRequest): Promise<DecideResponse>;
+    notifyDecision(layers: ContextLayer[], record: DecisionRecord, ctx: Context): Promise<void>;
     run<I, O>(s: Step<ContextData, 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. */
@@ -271,6 +284,8 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
         threadId?: string;
         resourceId?: string;
         contextLayers?: ContextLayer[];
+        /** Additional layers appended AFTER the effective set — never replaces it. */
+        extraContextLayers?: ContextLayer[];
         /**
          * Initial cwd for the new context. When set, takes precedence over both
          * the parent snapshot and the harness root cwd — used by worktree
@@ -293,8 +308,8 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     recallLayers(layers: ContextLayer[], input: string, ctx: Context): Promise<RecallLayerOutput[]>;
     /** Allocate per-layer recall budgets from the harness projection policy. */
     private layerBudgets;
-    recallLayersAtomic(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<RecallLayerOutput[]>;
-    recallLayersEventual(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<RecallLayerOutput[]>;
+    recallLayersAtomic(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>, opts?: RecallOptions): Promise<RecallLayerOutput[]>;
+    recallLayersEventual(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>, opts?: RecallOptions): Promise<RecallLayerOutput[]>;
     /**
      * Compute the items array that would be sent to the model on the next turn —
      * the same arrangement `executeLLM` builds: harness-level context layers'
@@ -393,7 +408,7 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     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: ContextLayer[], toolName: string, toolArgs: unknown, ctx: Context): Promise<SteeringDecision>;
+    beforeToolCall(layers: ContextLayer[], toolName: string, toolArgs: unknown, ctx: Context, callId?: string): Promise<SteeringDecision>;
     afterModelCall(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
     projectHistory(layers: ContextLayer[], items: ReadonlyArray<Item>, ctx: Context): Promise<ReadonlyArray<Item>>;
     runAppendPipeline(layers: ContextLayer[], items: Item[], ctx: Context): Promise<{

package/dist/harness/agent-harness.js

@@ -2,8 +2,9 @@ import { frameworkCast, ItemSchemaRegistry, NoeticConfigError } from '@noetic-to
 import { SpanImpl } from '../observability/span-impl.js';
 import { NoopExporter } from '../observability/trace-exporter.js';
 import { AcpSessionStore } from '../runtime/acp-session-store.js';
-import { createInMemoryFsAdapter, createInMemoryShellAdapter, createInMemorySubprocessAdapter, OpenRouter, } from './deps/adapters.js';
-import { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createContextCacheStore, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from './deps/context.js';
+import { callDecide } from './decide-call.js';
+import { createInMemoryFsAdapter, createInMemoryShellAdapter, createInMemorySubprocessAdapter, OpenRouter, OpenRouterSdk, } from './deps/adapters.js';
+import { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createContextCacheStore, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, notifyDecision, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from './deps/context.js';
 import { collectAllTools, deduplicateTools, dispatchStepThroughAdapter, execute, prepareBandedView, } from './deps/interpreter.js';
 import { buildItemStream, ChannelStore, ContextImpl, captureCheckpoint, clearCheckpoint, collectContextTree, createInMemoryStorage, createStepLedgerStore, filterReasoningStream, filterTextStream, resolveStepLedgerRetention, restoreFromCheckpoint, SessionRunner, StepLedger, snapshotCwdState, } from './deps/runtime.js';
 import { SteeringAction } from './deps/types.js';
@@ -144,6 +145,16 @@ function createClient(config, contextCache) {
         },
     });
 }
+function createDecisionsClient(config) {
+    const resolved = resolveLlmClient(config, readLlmEnv());
+    if (!resolved) {
+        return undefined;
+    }
+    return new OpenRouterSdk({
+        apiKey: resolved.apiKey,
+        serverURL: resolved.serverURL,
+    });
+}
 //#region AgentHarness
 /**
  * Default agent harness for executing agent steps with built-in channel, context, and trace support.
@@ -186,6 +197,11 @@ export class AgentHarness {
      *  without friend-class gymnastics. Do not access from outside core. */
     _contextLayers;
     client;
+    /** SDK 1.x client for the decisions endpoint; the agent's client predates it. */
+    decisionsClient;
+    decideOverride;
+    /** Model id → whether it answers natively as a decision model. */
+    decisionModels = new Map();
     channelStore;
     /** Re-entrant `run()` depth per root context id — see `executeClosingChannels`. */
     rootRunDepth = new Map();
@@ -252,6 +268,8 @@ export class AgentHarness {
      * `ctx.id` (the layer-state store's executionId).
      */
     initializedExecutions = new Set();
+    /** Executions restored from a checkpoint: their first layer init keeps the restored state. */
+    restoredExecutions = new Set();
     traceExporter;
     /**
      * Long-lived shared cwd state. The same reference is seeded into every
@@ -276,6 +294,7 @@ export class AgentHarness {
             projection: opts.projection,
             forceAtomicRecall: opts.forceAtomicRecall,
             contextCache: opts.contextCache,
+            decisionModel: opts.decisionModel,
         };
         this.fs = environment?.fs ?? createInMemoryFsAdapter();
         this.shell = environment?.shell ?? createInMemoryShellAdapter();
@@ -294,6 +313,10 @@ export class AgentHarness {
         this.client = opts._testCallModel
             ? undefined
             : createClient(opts.callModelDefaults, opts.contextCache);
+        this.decideOverride = opts._testDecide;
+        this.decisionsClient = opts._testCallModel
+            ? undefined
+            : createDecisionsClient(opts.callModelDefaults);
         this.channelStore = new ChannelStore();
         this.traceExporter = opts.traceExporter ?? new NoopExporter();
         this.layerStateStore =
@@ -439,6 +462,7 @@ export class AgentHarness {
                         resourceId: perTurnOptions.resourceId,
                         state: perTurnOptions.state,
                         contextLayers: perTurnOptions.contextLayers,
+                        extraContextLayers: perTurnOptions.extraContextLayers,
                         _broadcaster: session.runner.broadcaster,
                     });
                     const ext = frameworkCast(ctx);
@@ -509,6 +533,27 @@ export class AgentHarness {
         }).callModel(request);
     }
     //#endregion
+    //#region decide
+    async decide(request) {
+        if (this.decideOverride) {
+            return this.decideOverride(request);
+        }
+        return callDecide(request, {
+            client: this.decisionsClient,
+            callModel: (r) => this.callModel(r),
+            nativeModels: this.decisionModels,
+        });
+    }
+    async notifyDecision(layers, record, ctx) {
+        await notifyDecision({
+            layers,
+            record,
+            ctx: this.toExecCtx(ctx),
+            store: this.layerStateStore,
+            recallCache: this.recallCache,
+        });
+    }
+    //#endregion
     async run(s, input, ctx) {
         // Populate the unified tool pool when an embedder drives a step directly on
         // a bare `createContext()` context (the turn pipeline does this per turn).
@@ -583,7 +628,14 @@ export class AgentHarness {
             return;
         }
         this.initializedExecutions.add(ctx.id);
-        await this.initLayers(layers, ctx, storage);
+        const keep = this.restoredExecutions.delete(ctx.id);
+        await initLayers({
+            layers,
+            ctx: this.toExecCtx(ctx),
+            storage,
+            store: this.layerStateStore,
+            keep,
+        });
     }
     detachedSpawn(s, input, parentCtx, overrides) {
         /* NOT a checkpoint boundary, despite spec 23 listing one here: a DetachedHandle's
@@ -596,8 +648,14 @@ export class AgentHarness {
         const resolved = opts ?? {};
         // `ContextImpl` takes the layers as `layers`, so the option spelling is
         // dropped from `rest` rather than spread through under the wrong name.
-        const { contextLayers, cwdInit, ...rest } = resolved;
-        const effectiveLayers = contextLayers ?? this._contextLayers;
+        const { contextLayers, extraContextLayers, cwdInit, ...rest } = resolved;
+        const baseLayers = contextLayers ?? this._contextLayers;
+        const effectiveLayers = extraContextLayers && extraContextLayers.length > 0
+            ? [
+                ...(baseLayers ?? []),
+                ...extraContextLayers,
+            ]
+            : baseLayers;
         const itemSchemas = buildItemSchemaRegistry({
             base: this.itemSchemas,
             layers: effectiveLayers,
@@ -700,7 +758,7 @@ export class AgentHarness {
             a.allocated,
         ]));
     }
-    async recallLayersAtomic(layers, input, ctx, budgets) {
+    async recallLayersAtomic(layers, input, ctx, budgets, opts) {
         return recallLayersAtomic({
             layers,
             query: input,
@@ -710,9 +768,10 @@ export class AgentHarness {
             store: this.layerStateStore,
             itemSchemas: this.itemSchemas,
             forceAtomic: this.config.forceAtomicRecall,
+            peek: opts?.peek,
         });
     }
-    async recallLayersEventual(layers, input, ctx, budgets) {
+    async recallLayersEventual(layers, input, ctx, budgets, opts) {
         return recallLayersEventual({
             layers,
             query: input,
@@ -723,6 +782,7 @@ export class AgentHarness {
             itemSchemas: this.itemSchemas,
             forceAtomic: this.config.forceAtomicRecall,
             cache: this.recallCache,
+            peek: opts?.peek,
         });
     }
     /**
@@ -861,7 +921,11 @@ export class AgentHarness {
      * whose `id` is already the original `executionId`.
      */
     async restore(executionId, opts) {
-        return restoreFromCheckpoint(this, executionId, opts);
+        const ctx = await restoreFromCheckpoint(this, executionId, opts);
+        if (ctx) {
+            this.restoredExecutions.add(ctx.id);
+        }
+        return ctx;
     }
     /**
      * Discard everything `restore(executionId)` would have used — the snapshot *and* the
@@ -948,7 +1012,7 @@ export class AgentHarness {
     setLayerState(executionId, layerId, state) {
         this.layerStateStore.set(executionId, layerId, state);
     }
-    async beforeToolCall(layers, toolName, toolArgs, ctx) {
+    async beforeToolCall(layers, toolName, toolArgs, ctx, callId) {
         const hasHook = layers.some((l) => l.hooks.beforeToolCall);
         if (!hasHook) {
             return {
@@ -959,6 +1023,7 @@ export class AgentHarness {
             layers,
             toolName,
             toolArgs,
+            callId,
             ctx: this.toExecCtx(ctx),
             store: this.layerStateStore,
         });

package/dist/harness/decide-call.d.ts

@@ -0,0 +1,19 @@
+import type { CallModelRequest, DecideRequest, DecideResponse, LLMResponse } from '@noetic-tools/types';
+import type { OpenRouter } from '@openrouter/sdk';
+/** @internal The slice of the SDK client the decide caller uses. */
+export type DecisionsClient = Pick<OpenRouter, 'alpha' | 'models'>;
+/** @internal */
+export interface DecideCallerDeps {
+    client?: DecisionsClient;
+    callModel: (request: CallModelRequest) => Promise<LLMResponse>;
+    /** Per-harness cache: model id → whether it is a decision model (`undefined` while unknown). */
+    nativeModels: Map<string, Promise<boolean | undefined>>;
+}
+/**
+ * Answer a decide request. Decision models (those whose OpenRouter output
+ * modality is `decisions`) answer natively with their own distributions; any
+ * other model answers through a structured-output call that estimates them.
+ *
+ * @internal
+ */
+export declare function callDecide(request: DecideRequest, deps: DecideCallerDeps): Promise<DecideResponse>;