@noetic-tools/core 5.5.0 → 5.7.0

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. */
@@ -266,6 +279,8 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     detachedSpawn<I, O>(s: Step<ContextData, I, O>, input: I, parentCtx: Context, overrides?: DetachedSpawnOverrides): DetachedHandle<O>;
     createContext(opts?: {
         parent?: Context;
+        /** Charge this context's usage to `parent` as it is spent. Default `true`. */
+        rollUpUsage?: boolean;
         items?: Item[];
         state?: unknown;
         threadId?: string;
@@ -295,8 +310,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'

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 =
@@ -510,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).
@@ -584,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
@@ -707,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,
@@ -717,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,
@@ -730,6 +782,7 @@ export class AgentHarness {
             itemSchemas: this.itemSchemas,
             forceAtomic: this.config.forceAtomicRecall,
             cache: this.recallCache,
+            peek: opts?.peek,
         });
     }
     /**
@@ -868,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

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>;