@noetic-tools/types 3.2.2 → 3.4.0

package/dist/index.d.ts

@@ -16,9 +16,11 @@ export * from './types/context-layer.js';
 export * from './types/context-parts/item-log.js';
 export * from './types/context-parts/layer-usage.js';
 export * from './types/context-scope.js';
+export * from './types/decide.js';
 export * from './types/detached.js';
 export * from './types/error.js';
 export * from './types/fs-adapter.js';
+export * from './types/harness-judgment.js';
 export * from './types/harness-result.js';
 export * from './types/items.js';
 export * from './types/observability.js';

package/dist/index.js

@@ -16,9 +16,11 @@ export * from './types/context-layer.js';
 export * from './types/context-parts/item-log.js';
 export * from './types/context-parts/layer-usage.js';
 export * from './types/context-scope.js';
+export * from './types/decide.js';
 export * from './types/detached.js';
 export * from './types/error.js';
 export * from './types/fs-adapter.js';
+export * from './types/harness-judgment.js';
 export * from './types/harness-result.js';
 export * from './types/items.js';
 export * from './types/observability.js';

package/dist/schemas/workflow.d.ts

@@ -9,6 +9,8 @@
  * document back into live `Step` objects via the existing builders.
  */
 import { z } from 'zod';
+import type { DecideQuestion } from '../types/decide.js';
+import type { DecideView } from '../types/step.js';
 interface UntilAnyPredicate {
     kind: 'any';
     predicates: UntilPredicate[];
@@ -234,6 +236,27 @@ export interface ConditionalWorkflowNode extends WorkflowNodeBase {
     routes: ConditionalRoute[];
     default?: WorkflowNode;
 }
+/** A node that asks typed questions of a decision model. See spec 32. */
+export interface DecideWorkflowNode extends WorkflowNodeBase {
+    kind: 'decide';
+    model?: string;
+    instructions?: string;
+    questions: Record<string, DecideQuestion>;
+    view?: DecideView;
+    samples?: number;
+}
+/** A node that routes to a case by one question of a decision. See spec 32. */
+export interface RouteSwitchWorkflowNode extends WorkflowNodeBase {
+    kind: 'routeSwitch';
+    decide: DecideWorkflowNode;
+    /** Question id to route by. */
+    on: string;
+    /** One case per outcome of the `on` question. */
+    cases: Record<string, WorkflowNode>;
+    minConfidence?: number;
+    /** Taken on refusal, or when confidence is below `minConfidence`. */
+    uncertain: WorkflowNode;
+}
 export interface InParallelWorkflowNode extends WorkflowNodeBase {
     kind: 'inParallel';
     mode: 'race' | 'all' | 'settle';
@@ -326,7 +349,7 @@ export interface SubflowWorkflowNode extends WorkflowNodeBase {
     input?: string;
 }
 /** @public Discriminated union of all JSON-serialisable workflow node kinds. */
-export type WorkflowNode = CallModelWorkflowNode | InvokeToolWorkflowNode | RunCodeWorkflowNode | ConditionalWorkflowNode | InParallelWorkflowNode | SpawnWorkflowNode | WithContextWorkflowNode | LoopWorkflowNode | SequenceWorkflowNode | ScheduleWorkflowNode | SubflowWorkflowNode | AcpAgentWorkflowNode;
+export type WorkflowNode = CallModelWorkflowNode | InvokeToolWorkflowNode | RunCodeWorkflowNode | ConditionalWorkflowNode | DecideWorkflowNode | RouteSwitchWorkflowNode | InParallelWorkflowNode | SpawnWorkflowNode | WithContextWorkflowNode | LoopWorkflowNode | SequenceWorkflowNode | ScheduleWorkflowNode | SubflowWorkflowNode | AcpAgentWorkflowNode;
 /** @public Zod schema validating a single `WorkflowNode` (any JSON-safe kind). */
 export declare const WorkflowNodeSchema: z.ZodType<WorkflowNode>;
 /** @public Top-level envelope for a JSON workflow definition. */

package/dist/schemas/workflow.js

@@ -9,6 +9,7 @@
  * document back into live `Step` objects via the existing builders.
  */
 import { z } from 'zod';
+import { DecideQuestionsSchema, routeOutcomes } from '../types/decide.js';
 //#endregion
 //#region Until Predicate Schemas
 const MaxStepsPredicateSchema = z.object({
@@ -245,6 +246,56 @@ const ConditionalNodeSchema = z.object({
     routes: z.array(ConditionalRouteSchema).min(1),
     default: WorkflowNodeRef.optional(),
 });
+const DecideNodeSchema = z.object({
+    kind: z.literal('decide'),
+    ...SHARED_FIELDS,
+    model: z.string().min(1).optional(),
+    instructions: z.string().min(1).optional(),
+    questions: DecideQuestionsSchema,
+    view: z
+        .enum([
+        'full',
+        'layers',
+        'none',
+    ])
+        .optional(),
+    samples: z.number().int().positive().optional(),
+});
+const RouteSwitchNodeSchema = z
+    .object({
+    kind: z.literal('routeSwitch'),
+    ...SHARED_FIELDS,
+    decide: DecideNodeSchema,
+    on: z.string().min(1),
+    cases: z.record(z.string().min(1), WorkflowNodeRef),
+    minConfidence: z.number().min(0).max(1).optional(),
+    uncertain: WorkflowNodeRef,
+})
+    .superRefine((node, issue) => {
+    const question = Object.hasOwn(node.decide.questions, node.on)
+        ? node.decide.questions[node.on]
+        : undefined;
+    if (!question) {
+        issue.addIssue({
+            code: 'custom',
+            path: [
+                'on',
+            ],
+            message: `routeSwitch 'on' names no question of its decide node: '${node.on}'.`,
+        });
+        return;
+    }
+    const missing = routeOutcomes(question).filter((o) => !Object.hasOwn(node.cases, o));
+    if (missing.length > 0) {
+        issue.addIssue({
+            code: 'custom',
+            path: [
+                'cases',
+            ],
+            message: `routeSwitch cases miss outcomes of '${node.on}': ${missing.join(', ')}.`,
+        });
+    }
+});
 const InParallelNodeSchema = z
     .object({
     kind: z.literal('inParallel'),
@@ -332,6 +383,8 @@ export const WorkflowNodeSchema = z
     InvokeToolNodeSchema,
     RunCodeNodeSchema,
     ConditionalNodeSchema,
+    DecideNodeSchema,
+    RouteSwitchNodeSchema,
     InParallelNodeSchema,
     SpawnNodeSchema,
     WithContextNodeSchema,
@@ -390,6 +443,12 @@ function childNodes(node) {
             }
             return children;
         }
+        case 'routeSwitch':
+            return [
+                node.decide,
+                ...Object.values(node.cases),
+                node.uncertain,
+            ];
         case 'subflow':
             // A named ref is a static leaf: the target document is only known at
             // hydration time, so walk/graph/depth cannot see through it.

package/dist/types/common.d.ts

@@ -1,3 +1,4 @@
+import type { DecisionMeta } from './decide.js';
 import type { FunctionCallItem, Item } from './items.js';
 /**
  * Policy controlling automatic retry behavior on step failure.
@@ -90,6 +91,8 @@ export interface StepMeta {
      * `max_turn_requests`) from a complete one — both return normally.
      */
     acpStopReason?: string;
+    /** Set by `decide` steps. */
+    decision?: DecisionMeta;
 }
 /** @public Structured response returned by a model adapter after an LLM call. */
 export interface LLMResponse {

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

@@ -3,7 +3,8 @@ import type { Channel, ChannelHandle, ExternalChannel } from './channel.js';
 import type { LLMResponse, ModelParams } from './common.js';
 import type { Context, CwdState, RestoreContextOptions } from './context.js';
 import type { ContextCacheConfig, ContextCacheStore } from './context-cache.js';
-import type { ContextData, ContextLayer, ProjectionPolicy, StorageAdapter } from './context-layer.js';
+import type { ContextData, ContextLayer, ProjectionPolicy, RecallOptions, StorageAdapter } from './context-layer.js';
+import type { DecideRequest, DecideResponse, DecisionRecord } from './decide.js';
 import type { DetachedHandle } from './detached.js';
 import type { FsAdapter } from './fs-adapter.js';
 import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result.js';
@@ -42,8 +43,10 @@ interface ContextCallModelRequestWithTools extends ContextCallModelRequestBase {
 }
 interface ContextCallModelRequestWithoutTools extends ContextCallModelRequestBase {
     tools?: undefined;
-    ctx?: undefined;
-    layers?: undefined;
+    /** Accepted without tools — it carries the broadcaster for streaming (see `CallModelRequestWithoutTools`). */
+    ctx?: Context;
+    layers?: ContextLayer[];
+    allowedToolNames?: undefined;
 }
 export type ContextCallModelRequest = ContextCallModelRequestWithTools | ContextCallModelRequestWithoutTools;
 export interface ContextDetachedSpawnOverrides {
@@ -74,6 +77,10 @@ export type ContextStep<TContext = ContextData, I = unknown, O = unknown> = {
     readonly kind: 'callModel';
     readonly id: string;
     readonly output?: StandardSchemaV1<unknown, O>;
+} | {
+    readonly kind: 'decide';
+    readonly id: string;
+    readonly _answers?: O;
 } | {
     readonly kind: 'loop';
     readonly id: string;
@@ -92,12 +99,17 @@ export interface ContextHarness {
         readonly projection?: ProjectionPolicy;
         /** Tuning for prompt-cache anchoring. */
         readonly contextCache?: ContextCacheConfig;
+        /** Default model for `decide` steps. */
+        readonly decisionModel?: string;
     };
     readonly fs: FsAdapter;
     readonly shell: ShellAdapter;
     readonly subprocess: SubprocessAdapter;
     readonly rootCwdState: CwdState;
     callModel(request: ContextCallModelRequest): Promise<LLMResponse>;
+    decide(request: DecideRequest): Promise<DecideResponse>;
+    /** Run every layer's `onDecision` hook, in slot order. */
+    notifyDecision(layers: ContextLayer[], record: DecisionRecord, ctx: Context): Promise<void>;
     execute(input: ExecuteInput, options?: unknown): Promise<void>;
     getAgentResponse(scope?: unknown): Promise<HarnessResponse>;
     getItemStream(scope?: unknown): AsyncIterable<StreamingItem>;
@@ -118,14 +130,14 @@ export interface ContextHarness {
     setRootCwd(nextCwd: string): void;
     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>;
     runAppendPipeline(layers: ContextLayer[], items: Item[], ctx: Context): Promise<ContextAppendPipelineResult>;
     /** Pinned anchor output and epoch bookkeeping for prompt-cache anchoring. Absent on a harness that predates it. */
     readonly contextCache?: ContextCacheStore;
     recallLayers(layers: ContextLayer[], input: string, ctx: Context): Promise<ContextRecallLayerOutput[]>;
-    recallLayersAtomic(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<ContextRecallLayerOutput[]>;
-    recallLayersEventual(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<ContextRecallLayerOutput[]>;
+    recallLayersAtomic(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>, opts?: RecallOptions): Promise<ContextRecallLayerOutput[]>;
+    recallLayersEventual(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>, opts?: RecallOptions): Promise<ContextRecallLayerOutput[]>;
     projectHistory(layers: ContextLayer[], items: ReadonlyArray<Item>, ctx: Context): Promise<ReadonlyArray<Item>>;
     storeLayers(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<void>;
     previewRequestItems(scope?: unknown): Promise<ReadonlyArray<Item>>;

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

@@ -2,6 +2,7 @@ import type { ZodType } from 'zod';
 import type { LLMResponse } from './common.js';
 import type { ItemLog } from './context-parts/item-log.js';
 import type { ContextScope, ExecutionContext, ExecutionOutcome } from './context-scope.js';
+import type { DecisionRecord } from './decide.js';
 import type { Item, ItemSchemaExtensions } from './items.js';
 import type { AfterModelCallParams, AfterModelCallResult, BeforeToolCallParams, BeforeToolCallResult } from './steering.js';
 /** @public Isolation scope controlling how a context layer's state is keyed and shared. */
@@ -22,6 +23,7 @@ export interface LayerTimeouts {
     afterModelCall?: number;
     onItemAppend?: number;
     projectHistory?: number;
+    onDecision?: number;
 }
 /** @public A read-only data projection from layer state, accessible via `ctx.context['layerId'].prop`. */
 export interface LayerDataDecl<T = unknown, TState = unknown> {
@@ -301,6 +303,21 @@ export interface OnItemAppendResult<TState> {
     /** Which layers to re-recall (default: 'slot-after'). */
     scope?: RerenderScope;
 }
+/** @public Options for a recall pass. */
+export interface RecallOptions {
+    /**
+     * Render without leaving a trace: returned state is not committed and
+     * eventual-layer output is not cached. A `decide` step peeks so that it never
+     * drains state (such as queued steering guidance) meant for the next model call.
+     */
+    peek?: boolean;
+}
+/** @public Parameters for the `onDecision` hook. */
+export interface OnDecisionParams<TState> {
+    state: TState;
+    record: DecisionRecord;
+    ctx: ExecutionContext;
+}
 /** @public Lifecycle hook implementations for a context layer. Method syntax enables bivariant assignability for typed layers. */
 export interface ContextLayerHooks<TState = unknown> {
     init?(params: InitParams): Promise<InitResult<TState>>;
@@ -343,6 +360,13 @@ export interface ContextLayerHooks<TState = unknown> {
      * a row. Never called for layers in the `'live'` band, which re-render anyway.
      */
     renderDelta?(params: RenderDeltaParams<TState>): Promise<string | null>;
+    /**
+     * Called after every `decide` step completes, in slot order. Return new state
+     * to record the decision.
+     */
+    onDecision?(params: OnDecisionParams<TState>): Promise<undefined | {
+        state: TState;
+    }>;
 }
 /**
  * A composable context layer that participates in the recall/store lifecycle.
@@ -372,6 +396,16 @@ export interface ContextLayer<TState = unknown> {
      *   (its `recall`/`store`/etc. are skipped). Opt in only for non-critical layers.
      */
     onInitError?: 'throw' | 'disable';
+    /**
+     * What a failed `beforeToolCall` hook (throw or timeout) means for the
+     * pending tool call.
+     * - `'abstain'` (default): log a diagnostic and let the remaining layers /
+     *   the default decide — correct for observational layers, where a bug must
+     *   not block every tool.
+     * - `'deny'`: the call is denied — correct for permission GATES, where a
+     *   failed check must fail closed rather than silently approving.
+     */
+    onBeforeToolCallError?: 'abstain' | 'deny';
     /**
      * Recall mode controlling whether this layer's `recall()` blocks the model call.
      * - `'atomic'` (default): recall runs synchronously in the hot path; the

package/dist/types/decide.d.ts

@@ -0,0 +1,270 @@
+import type { ZodError, ZodType } from 'zod';
+import { z } from 'zod';
+import type { Span } from './observability.js';
+/** @public A yes/no question. The answer's `value` is `probability >= threshold`. */
+export interface BooleanQuestion {
+    type: 'boolean';
+    instructions?: string;
+    /** What yes and no mean. Required when `instructions` is absent. */
+    criteria?: {
+        true?: string;
+        false?: string;
+    };
+    /** Probability at or above which `value` is `true`. Default 0.5. */
+    threshold?: number;
+}
+/** @public Pick one of a set of unordered options. */
+export interface ChoiceQuestion<K extends string = string> {
+    type: 'choice';
+    instructions?: string;
+    /** 1–255 options: bare values, or values mapped to descriptions. */
+    choices: readonly K[] | Readonly<Record<K, string>>;
+}
+/** @public A level on an ordered scale. */
+export interface ScoreLevel<L extends string = string> {
+    label: L;
+    description?: string;
+}
+/**
+ * @public Place the state on an ordered scale. Levels run lowest first, and are
+ * an array because a record cannot carry order: JavaScript sorts integer-like
+ * keys ahead of all others.
+ */
+export interface ScoreQuestion<L extends string = string> {
+    type: 'score';
+    instructions?: string;
+    /** 2–10 levels, lowest first. */
+    levels: readonly L[] | ReadonlyArray<ScoreLevel<L>>;
+}
+/** @public Any decide question. */
+export type DecideQuestion = BooleanQuestion | ChoiceQuestion | ScoreQuestion;
+/** @public Question map keyed by question id. */
+export type DecideQuestions = Readonly<Record<string, DecideQuestion>>;
+/** @public Answer to a boolean question. */
+export interface BooleanAnswer {
+    type: 'boolean';
+    /** `probability >= threshold`. */
+    value: boolean;
+    /** Probability of yes, in `[0, 1]`. */
+    probability: number;
+}
+/** @public Answer to a choice question. */
+export interface ChoiceAnswer<K extends string = string> {
+    type: 'choice';
+    /** The most probable choice. */
+    value: K;
+    /** The provider's own certainty measure — not the top probability. */
+    confidence: number;
+    probabilities: Readonly<Record<K, number>>;
+}
+/** @public Answer to a score question. */
+export interface ScoreAnswer<L extends string = string> {
+    type: 'score';
+    /** Probability-weighted level index, 0 = lowest. */
+    value: number;
+    /** The most probable level. Not `value` rounded: a split distribution can differ. */
+    level: L;
+    /** The provider's own certainty measure — not the top probability. */
+    confidence: number;
+    probabilities: Readonly<Record<L, number>>;
+}
+/** @public The model declined to answer this question. */
+export interface Refusal {
+    type: 'refusal';
+}
+/** @public Any answer, untyped by question. */
+export type DecideAnswer = BooleanAnswer | ChoiceAnswer | ScoreAnswer | Refusal;
+/** @public Choice values declared by a choice question's `choices`. */
+export type ChoiceValues<C> = C extends readonly (infer K extends string)[] ? K : C extends Readonly<Record<infer K extends string | number, string>> ? `${K}` : never;
+/** @public Level labels declared by a score question's `levels`. */
+export type LevelLabels<L> = L extends readonly (infer E)[] ? E extends string ? E : E extends {
+    label: infer K extends string;
+} ? K : never : never;
+/** @public The answer type a question produces, refusal excluded. */
+export type AnswerFor<Q> = Q extends {
+    type: 'boolean';
+} ? BooleanAnswer : Q extends {
+    type: 'choice';
+    choices: infer C;
+} ? ChoiceAnswer<ChoiceValues<C>> : Q extends {
+    type: 'score';
+    levels: infer L;
+} ? ScoreAnswer<LevelLabels<L>> : never;
+/** @public Typed answers for a question map. Any question may be refused. */
+export type DecideAnswers<Q extends DecideQuestions> = {
+    readonly [K in keyof Q]: AnswerFor<Q[K]> | Refusal;
+};
+/** @public Case keys a question routes to: its choices, `'true' | 'false'`, or its level labels. */
+export type CaseKeyOf<Q> = Q extends {
+    type: 'boolean';
+} ? 'true' | 'false' : Q extends {
+    type: 'choice';
+    choices: infer C;
+} ? ChoiceValues<C> : Q extends {
+    type: 'score';
+    levels: infer L;
+} ? LevelLabels<L> : never;
+/** @public Typed answers with refusals removed. */
+export type AnsweredAll<Q extends DecideQuestions> = {
+    readonly [K in keyof Q]: AnswerFor<Q[K]>;
+};
+/** @public One piece of the state a decision is made against. */
+export type DecideStatePart = {
+    type: 'text';
+    text: string;
+    name?: string;
+} | {
+    type: 'json';
+    name: string;
+    value: unknown;
+} | {
+    type: 'image';
+    imageUrl: string;
+};
+/**
+ * @public `native`: a decision model's own distribution. `estimated`: a chat
+ * model's self-reported probabilities, which are not calibrated.
+ */
+export type DecisionSource = 'native' | 'estimated';
+/** @public Request for `harness.decide()`, in Noetic's vocabulary. Adapters translate it per provider. */
+export interface DecideRequest {
+    model: string;
+    instructions?: string;
+    state: ReadonlyArray<DecideStatePart>;
+    questions: DecideQuestions;
+    /** Runs averaged on the estimated path. Ignored on the native path. Default 1. */
+    samples?: number;
+    signal?: AbortSignal;
+    /** @internal Parent span for the decide-call span. */
+    parentSpan?: Span;
+}
+/** @public Response from `harness.decide()`. */
+export interface DecideResponse {
+    answers: Readonly<Record<string, DecideAnswer>>;
+    source: DecisionSource;
+    /** Model that answered, as reported by the provider. */
+    modelId: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    cost?: number;
+}
+/** @public Decision metadata recorded on `ctx.lastStepMeta.decision`. */
+export interface DecisionMeta {
+    modelId: string;
+    source: DecisionSource;
+    /** Ids of refused questions. */
+    refused: readonly string[];
+}
+/** @public One completed decision, as layers see it through `onDecision`. */
+export interface DecisionRecord {
+    stepId: string;
+    /** Epoch ms. */
+    at: number;
+    modelId: string;
+    source: DecisionSource;
+    answers: Readonly<Record<string, DecideAnswer>>;
+}
+/**
+ * A chat model's estimate did not match the requested shape. The interpreter
+ * turns it into `model_parse_error`, which needs the step id this layer lacks.
+ * @public
+ */
+export declare class DecideOutputError extends Error {
+    readonly raw: string;
+    readonly schema: ZodType;
+    readonly zodError: ZodError;
+    /** Tokens the failed estimate still cost, so the step can count them. */
+    readonly usage?: DecideResponse['usage'];
+    readonly cost?: number;
+    constructor(opts: {
+        raw: string;
+        schema: ZodType;
+        zodError: ZodError;
+        usage?: DecideResponse['usage'];
+        cost?: number;
+    });
+}
+/** Choice and level limits shared by the OpenAI and TypeSafe decision APIs. */
+export declare const DECIDE_LIMITS: {
+    readonly maxChoices: 255;
+    readonly minLevels: 2;
+    readonly maxLevels: 10;
+};
+/** @public Zod schema for a boolean question. */
+export declare const BooleanQuestionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+    instructions: z.ZodOptional<z.ZodString>;
+    criteria: z.ZodOptional<z.ZodObject<{
+        true: z.ZodOptional<z.ZodString>;
+        false: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    threshold: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** @public Zod schema for a choice question. */
+export declare const ChoiceQuestionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"choice">;
+    instructions: z.ZodOptional<z.ZodString>;
+    choices: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodString>]>;
+}, z.core.$strip>;
+/** @public Zod schema for a score question. */
+export declare const ScoreQuestionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"score">;
+    instructions: z.ZodOptional<z.ZodString>;
+    levels: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>;
+}, z.core.$strip>;
+/** @public Zod schema for any decide question. */
+export declare const DecideQuestionSchema: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+    instructions: z.ZodOptional<z.ZodString>;
+    criteria: z.ZodOptional<z.ZodObject<{
+        true: z.ZodOptional<z.ZodString>;
+        false: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    threshold: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"choice">;
+    instructions: z.ZodOptional<z.ZodString>;
+    choices: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodString>]>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"score">;
+    instructions: z.ZodOptional<z.ZodString>;
+    levels: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>;
+}, z.core.$strip>]>;
+/** @public Zod schema for a question map: at least one question. */
+export declare const DecideQuestionsSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+    instructions: z.ZodOptional<z.ZodString>;
+    criteria: z.ZodOptional<z.ZodObject<{
+        true: z.ZodOptional<z.ZodString>;
+        false: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    threshold: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"choice">;
+    instructions: z.ZodOptional<z.ZodString>;
+    choices: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodString>]>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"score">;
+    instructions: z.ZodOptional<z.ZodString>;
+    levels: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>;
+}, z.core.$strip>]>>;
+/** @public Choice values in declaration order. */
+export declare function choiceValues(choices: ChoiceQuestion['choices']): string[];
+/** @public Score levels, lowest first, in object form. */
+export declare function scoreLevels(levels: ScoreQuestion['levels']): ScoreLevel[];
+/**
+ * @public Case keys a question routes to: its choices, `'true'`/`'false'`, or
+ * its level labels.
+ */
+export declare function routeOutcomes(question: DecideQuestion): string[];

package/dist/types/decide.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+//#endregion
+/**
+ * A chat model's estimate did not match the requested shape. The interpreter
+ * turns it into `model_parse_error`, which needs the step id this layer lacks.
+ * @public
+ */
+export class DecideOutputError extends Error {
+    raw;
+    schema;
+    zodError;
+    /** Tokens the failed estimate still cost, so the step can count them. */
+    usage;
+    cost;
+    constructor(opts) {
+        super(`decision estimate did not match its schema: ${opts.zodError.message}`);
+        this.name = 'DecideOutputError';
+        this.raw = opts.raw;
+        this.schema = opts.schema;
+        this.zodError = opts.zodError;
+        this.usage = opts.usage;
+        this.cost = opts.cost;
+    }
+}
+//#endregion
+//#region Schemas
+/** Choice and level limits shared by the OpenAI and TypeSafe decision APIs. */
+export const DECIDE_LIMITS = {
+    maxChoices: 255,
+    minLevels: 2,
+    maxLevels: 10,
+};
+const InstructionsSchema = z.string().min(1).optional();
+/** @public Zod schema for a boolean question. */
+export const BooleanQuestionSchema = z
+    .object({
+    type: z.literal('boolean'),
+    instructions: InstructionsSchema,
+    criteria: z
+        .object({
+        true: z.string().min(1).optional(),
+        false: z.string().min(1).optional(),
+    })
+        .optional(),
+    threshold: z.number().min(0).max(1).optional(),
+})
+    .refine((q) => q.instructions !== undefined || q.criteria?.true || q.criteria?.false, {
+    message: 'boolean question needs `instructions` or a `criteria` description.',
+});
+/** @public Zod schema for a choice question. */
+export const ChoiceQuestionSchema = z
+    .object({
+    type: z.literal('choice'),
+    instructions: InstructionsSchema,
+    choices: z.union([
+        z.array(z.string().min(1)).min(1).max(DECIDE_LIMITS.maxChoices),
+        z.record(z.string().min(1), z.string()),
+    ]),
+})
+    .refine((q) => choiceValues(q.choices).length >= 1, {
+    message: 'choice question needs at least one choice.',
+})
+    .refine((q) => choiceValues(q.choices).length <= DECIDE_LIMITS.maxChoices, {
+    message: `choice question allows at most ${DECIDE_LIMITS.maxChoices} choices.`,
+})
+    .refine((q) => unique(choiceValues(q.choices)), {
+    message: 'choice values must be unique.',
+});
+/** @public Zod schema for a score question. */
+export const ScoreQuestionSchema = z
+    .object({
+    type: z.literal('score'),
+    instructions: InstructionsSchema,
+    levels: z
+        .union([
+        z.array(z.string().min(1)),
+        z.array(z.object({
+            label: z.string().min(1),
+            description: z.string().optional(),
+        })),
+    ])
+        .refine((l) => l.length >= DECIDE_LIMITS.minLevels && l.length <= DECIDE_LIMITS.maxLevels, {
+        message: `score question needs ${DECIDE_LIMITS.minLevels}–${DECIDE_LIMITS.maxLevels} levels.`,
+    }),
+})
+    .refine((q) => unique(levelLabels(q.levels)), {
+    message: 'score level labels must be unique.',
+});
+/** @public Zod schema for any decide question. */
+export const DecideQuestionSchema = z.union([
+    BooleanQuestionSchema,
+    ChoiceQuestionSchema,
+    ScoreQuestionSchema,
+]);
+/** @public Zod schema for a question map: at least one question. */
+export const DecideQuestionsSchema = z
+    .record(z.string().min(1), DecideQuestionSchema)
+    .refine((q) => Object.keys(q).length > 0, {
+    message: 'decide needs at least one question.',
+});
+//#endregion
+//#region Helpers
+/** @public Choice values in declaration order. */
+export function choiceValues(choices) {
+    return Array.isArray(choices)
+        ? [
+            ...choices,
+        ]
+        : Object.keys(choices);
+}
+/** @public Score levels, lowest first, in object form. */
+export function scoreLevels(levels) {
+    return levels.map((l) => typeof l === 'string'
+        ? {
+            label: l,
+        }
+        : l);
+}
+/**
+ * @public Case keys a question routes to: its choices, `'true'`/`'false'`, or
+ * its level labels.
+ */
+export function routeOutcomes(question) {
+    switch (question.type) {
+        case 'boolean':
+            return [
+                'true',
+                'false',
+            ];
+        case 'choice':
+            return choiceValues(question.choices);
+        case 'score':
+            return levelLabels(question.levels);
+    }
+}
+function levelLabels(levels) {
+    return scoreLevels(levels).map((l) => l.label);
+}
+function unique(values) {
+    return new Set(values).size === values.length;
+}
+//#endregion

package/dist/types/harness-judgment.d.ts

@@ -0,0 +1,18 @@
+import type { LLMResponse } from './common.js';
+import type { Context } from './context.js';
+import type { ContextLayer } from './context-layer.js';
+import type { DecideRequest, DecideResponse, DecisionRecord } from './decide.js';
+import type { SteeringDecision } from './steering.js';
+/**
+ * @public The judgment calls an agent harness makes for a step: the steering
+ * hooks around tool and model calls, and typed decisions. Part of
+ * `AgentHarnessContract`.
+ */
+export interface HarnessJudgmentContract {
+    /** Answer typed questions with a decision model, or estimate with a chat model. See spec 32. */
+    decide(request: DecideRequest): Promise<DecideResponse>;
+    /** Run every layer's `onDecision` hook, in slot order. */
+    notifyDecision(layers: ContextLayer[], record: DecisionRecord, ctx: Context): Promise<void>;
+    beforeToolCall(layers: ContextLayer[], toolName: string, toolArgs: unknown, ctx: Context, callId?: string): Promise<SteeringDecision>;
+    afterModelCall(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
+}

package/dist/types/harness-judgment.js

@@ -0,0 +1 @@
+export {};

package/dist/types/runtime.d.ts

@@ -3,14 +3,14 @@ import type { Channel, ChannelHandle, ExternalChannel } from './channel.js';
 import type { LLMResponse, ModelParams, ServerToolSpec } from './common.js';
 import type { Context, CwdState, RestoreContextOptions } from './context.js';
 import type { ContextCacheConfig, ContextCacheStore } from './context-cache.js';
-import type { ContextData, ContextLayer, ProjectionPolicy, StorageAdapter } from './context-layer.js';
+import type { ContextData, ContextLayer, ProjectionPolicy, RecallOptions, StorageAdapter } from './context-layer.js';
 import type { DetachedHandle } from './detached.js';
 import type { FsAdapter } from './fs-adapter.js';
+import type { HarnessJudgmentContract } from './harness-judgment.js';
 import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result.js';
 import type { ExecuteInput, Item, ItemSchemaExtensions } from './items.js';
 import type { Span, TraceExporter } from './observability.js';
 import type { ShellAdapter } from './shell-adapter.js';
-import type { SteeringDecision } from './steering.js';
 import type { Step } from './step.js';
 import type { SubprocessAdapter } from './subprocess-adapter.js';
 import type { Tool } from './tool.js';
@@ -40,6 +40,8 @@ export interface AgentConfig<TParams extends Record<string, unknown> = Record<st
     forceAtomicRecall?: boolean;
     /** Tuning for prompt-cache anchoring. See `ContextCacheConfig` for the defaults. */
     contextCache?: ContextCacheConfig;
+    /** Default model for `decide` steps. */
+    decisionModel?: string;
 }
 /** @public How a message submitted during an active turn is delivered to the model.
  *
@@ -101,12 +103,17 @@ interface CallModelRequestWithTools extends CallModelRequestBase {
     /** When set, restricts which tools the model may invoke for this call. */
     allowedToolNames?: string[];
 }
-/** @public Request shape when no tools are provided — ctx is only needed for tool
- *  execution callbacks in convertTools, so it is omitted here. */
+/**
+ * @public Request shape when no tools are provided. `ctx` is still accepted —
+ * it carries the session broadcaster, without which a tool-less call streams
+ * nothing to `getFullStream`/`getTextStream` — it just isn't *required* the
+ * way the tools variant needs it for execution callbacks.
+ */
 interface CallModelRequestWithoutTools extends CallModelRequestBase {
     tools?: undefined;
-    ctx?: undefined;
-    layers?: undefined;
+    ctx?: Context;
+    layers?: ContextLayer[];
+    allowedToolNames?: undefined;
 }
 /** @public Request object for `AgentHarnessContract.callModel()`. Encapsulates all parameters needed for an LLM call using only Noetic types. */
 export type CallModelRequest = CallModelRequestWithTools | CallModelRequestWithoutTools;
@@ -117,6 +124,13 @@ export interface ExecuteOptions {
     state?: unknown;
     /** Context layers to apply to the execution context. Overrides harness-level layers if provided. */
     contextLayers?: ContextLayer[];
+    /**
+     * Additional context layers appended AFTER the effective layer set
+     * (harness-level layers, or `contextLayers` when that override is given).
+     * Use this to inject a per-turn layer — a permission gate, an observer —
+     * without discarding the layers the harness was built with.
+     */
+    extraContextLayers?: ContextLayer[];
     /** Override the harness's default delivery mode for this message only. */
     deliveryMode?: DeliveryMode;
     /**
@@ -158,7 +172,7 @@ export interface SessionScope {
     threadId?: string;
 }
 /** @public Type-level contract for the agent runtime. Used for type annotations throughout the interpreter, context layers, and context. Implemented by `AgentHarness`. */
-export interface AgentHarnessContract<TParams extends Record<string, unknown> = Record<string, unknown>> {
+export interface AgentHarnessContract<TParams extends Record<string, unknown> = Record<string, unknown>> extends HarnessJudgmentContract {
     readonly config: AgentConfig<TParams>;
     /** Filesystem adapter for virtual or real filesystem access. */
     readonly fs: FsAdapter;
@@ -244,6 +258,8 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
         threadId?: string;
         resourceId?: string;
         contextLayers?: ContextLayer[];
+        /** Additional layers appended AFTER the effective layer set (see `ExecuteOptions.extraContextLayers`). */
+        extraContextLayers?: ContextLayer[];
         /** Override the new context's initial cwd. */
         cwdInit?: string;
     }): Context;
@@ -284,9 +300,9 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     initLayers(layers: ContextLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
     recallLayers(layers: ContextLayer[], input: string, ctx: Context): Promise<RecallLayerOutput[]>;
     /** Recall only atomic layers (or all layers when the harness forces atomic recall). Blocks until complete. */
-    recallLayersAtomic(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[]>;
     /** Recall eventual layers from cache (non-blocking); returns nothing when the harness forces atomic recall. */
-    recallLayersEventual(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<RecallLayerOutput[]>;
+    recallLayersEventual(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>, opts?: RecallOptions): Promise<RecallLayerOutput[]>;
     /**
      * Compute the items that would be sent to the model on the next turn for a
      * session — its accumulated history plus the harness's context-layer recall
@@ -318,8 +334,6 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     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>;
-    afterModelCall(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
     /**
      * Project the history items through every layer's `projectHistory` hook in
      * slot order. Pure read-side projection — `itemLog` is never mutated.

package/dist/types/steering.d.ts

@@ -42,6 +42,15 @@ export interface LedgerEntry {
 export interface BeforeToolCallParams<TState = unknown> {
     toolName: string;
     toolArgs: unknown;
+    /**
+     * Correlation id of the pending call — the same id carried by the
+     * `tool_call_started` framework event (the model's `callId` on model-driven
+     * calls, the step id on a direct `invokeTool`). Lets a gating layer tie its
+     * decision to the call it is reported as, e.g. when forwarding the request
+     * to an external approver. Optional because a custom caller of the gate may
+     * have no call identity; every built-in tool-executing path supplies it.
+     */
+    callId?: string;
     ctx: ExecutionContext;
     state: TState;
 }

package/dist/types/step.d.ts

@@ -4,6 +4,7 @@ import type { Channel } from './channel.js';
 import type { ModelParams, RetryPolicy, ServerToolSpec, StepMeta } from './common.js';
 import type { Context } from './context.js';
 import type { ContextConfig, ContextData, ContextLayer, ProjectionPolicy } from './context-layer.js';
+import type { DecideAnswers, DecideQuestions } from './decide.js';
 import type { NoeticError } from './error.js';
 import type { OutputCodec } from './output-codec.js';
 import type { SubprocessAdapter } from './subprocess-adapter.js';
@@ -73,7 +74,7 @@ export interface SettleResult<O> {
     error?: NoeticError;
 }
 /** @public Discriminated union of all step kinds that can be composed into an execution tree. */
-export type Step<TContext = ContextData, I = unknown, O = unknown> = StepRunCode<TContext, I, O> | StepCallModel<TContext, I, O> | StepAcpAgent<TContext, I, O> | StepInvokeTool<TContext, I, O> | StepConditional<TContext, I, O> | StepInParallel<TContext, I, O> | StepSpawn<TContext, I, O> | StepWithContext<TContext, I, O> | StepLoop<TContext, I, O> | StepSchedule<TContext, I, O>;
+export type Step<TContext = ContextData, I = unknown, O = unknown> = StepRunCode<TContext, I, O> | StepCallModel<TContext, I, O> | StepAcpAgent<TContext, I, O> | StepInvokeTool<TContext, I, O> | StepDecide<TContext, I, O> | StepConditional<TContext, I, O> | StepInParallel<TContext, I, O> | StepSpawn<TContext, I, O> | StepWithContext<TContext, I, O> | StepLoop<TContext, I, O> | StepSchedule<TContext, I, O>;
 /** @public A step that executes arbitrary async logic via a user-supplied function. */
 export interface StepRunCode<TContext = ContextData, I = unknown, O = unknown> {
     kind: 'runCode';
@@ -173,12 +174,63 @@ export interface StepInvokeTool<_TContext = ContextData, I = unknown, O = unknow
     tool: Tool<StandardSchemaV1<unknown, I>, StandardSchemaV1<unknown, O>>;
     args?: Partial<I>;
 }
+/**
+ * A step that asks a model typed questions about the current context and returns
+ * typed answers with probabilities. It reads the conversation but never appends
+ * to it, and runs no steering hooks. See spec 32.
+ * @public
+ */
+export interface StepDecide<TContext = ContextData, _I = unknown, O = unknown> {
+    kind: 'decide';
+    /** Phantom field carrying the answers type for inference. Never set at runtime. */
+    readonly _answers?: O;
+    id: string;
+    /** Decision model id. Falls back to `harness.config.decisionModel`. */
+    model?: Lazy<string, TContext>;
+    /** Shared framing for every question. */
+    instructions?: Lazy<string | undefined, TContext>;
+    questions: DecideQuestions;
+    /** Which part of the assembled view the model sees. */
+    view: DecideView;
+    /** Typed state read from context layers, sent as named state entries. */
+    context?: (ctx: Context<TContext>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /** Budget for the decision's view. Defaults to `DECISION_PROJECTION`. */
+    projection?: ProjectionPolicy;
+    /** Runs averaged on the estimated path. Ignored on the native path. */
+    samples: number;
+    /** Controls framework event emission for this step. Defaults to `true`. */
+    emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
+}
+/**
+ * A decide step that keeps its literal question map, so `routeSwitch` can infer
+ * the questions, choices, and levels it routes by.
+ * @public
+ */
+export type DecideStep<TContext, I, Q extends DecideQuestions> = StepDecide<TContext, I, DecideAnswers<Q>> & {
+    readonly questions: Q;
+};
+/**
+ * What a decide step sees: `full` = layer recall + history, `layers` = layer
+ * recall only, `none` = only the input, instructions, and context selector.
+ * @public
+ */
+export type DecideView = 'full' | 'layers' | 'none';
 /** @public A step that dynamically selects and executes one of several possible sub-steps. */
 export interface StepConditional<TContext = ContextData, I = unknown, O = unknown> {
     kind: 'conditional';
     id: string;
-    route: (input: I, ctx: Context<TContext>) => Step<TContext, I, O> | null | Promise<Step<TContext, I, O> | null>;
+    /**
+     * Picks the step to run. `run` executes a step through the interpreter, for
+     * routes that must run a step (such as a decision) to choose.
+     */
+    route: (input: I, ctx: Context<TContext>, run: ExecuteStepFn) => Step<TContext, I, O> | null | Promise<Step<TContext, I, O> | null>;
     _optimizable?: Step<TContext>[];
+    /**
+     * @internal Rebuild this step around new `_optimizable` children, for
+     * conditionals whose route closes over them (`routeSwitch`). The optimizer calls
+     * it so a mutated child is the one that runs.
+     */
+    _rebuild?: (children: Step<TContext>[]) => StepConditional<TContext, I, O>;
 }
 /** @public Union of inParallel step variants (`race`, `all`, `settle`) for concurrent path execution. */
 export type StepInParallel<TContext = ContextData, I = unknown, O = unknown> = StepInParallelRace<TContext, I, O> | StepInParallelAll<TContext, I, O> | StepInParallelSettle<TContext, I, O>;

package/dist/types/tool.d.ts

@@ -1,4 +1,5 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { AcpToolKind } from './acp.js';
 import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, ToolResultExtensionItem } from './items.js';
 import type { InferSchemaOutput } from './schema.js';
 type ToolExecutionResult<O extends StandardSchemaV1> = Promise<InferSchemaOutput<O>> | AsyncGenerator<unknown, InferSchemaOutput<O>>;
@@ -50,6 +51,33 @@ export interface ToolUiDeclaration<I extends StandardSchemaV1 = StandardSchemaV1
     /** Replaces the tool's region when execution throws. */
     error?(err: unknown, args: InferSchemaOutput<I>): UiFragment | null;
 }
+/**
+ * How a tool call presents in an ACP client's UI when the harness is served
+ * as an ACP agent (`toAcpAgent`/`serveAcp` in `@noetic-tools/acp`).
+ *
+ * Presentation only — it never gates anything. An undeclared tool falls back
+ * to kind `other` with its name as the title. Declared as methods (bivariant
+ * params) for the same reason as `ToolUiDeclaration`.
+ * @public
+ */
+export interface ToolAcpDeclaration<I extends StandardSchemaV1 = StandardSchemaV1> {
+    /** ACP tool kind (`read`, `edit`, `execute`, …) for editor rendering. */
+    kind?: AcpToolKind;
+    /** Human-readable title; a function receives the call's parsed args. */
+    title?: string | ToolAcpTitleFn<I>;
+    /** File paths the call affects, surfaced as ACP `locations`. */
+    locations?(args: InferSchemaOutput<I>): string[];
+}
+/**
+ * Bivariant function type for `ToolAcpDeclaration.title` — a union member
+ * cannot use method syntax, so the method-bearing object type is indexed to
+ * recover the same bivariance `ToolUiDeclaration`'s methods get, keeping a
+ * concretely-typed tool assignable to the erased `Tool` form.
+ * @public
+ */
+export type ToolAcpTitleFn<I extends StandardSchemaV1 = StandardSchemaV1> = {
+    bivariant(args: InferSchemaOutput<I>): string;
+}['bivariant'];
 /**
  * A tool definition that an LLM can invoke during execution.
  *
@@ -105,5 +133,7 @@ export interface Tool<I extends StandardSchemaV1 = StandardSchemaV1, O extends S
     context?: ToolContextDeclaration;
     /** Optional UI declaration — the runtime emits the rendered fragments at call/progress/result points. */
     ui?: ToolUiDeclaration<I, O>;
+    /** Optional ACP presentation — how the call renders in an ACP client when the harness is served as an agent. */
+    acp?: ToolAcpDeclaration<I>;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "3.2.2",
+  "version": "3.4.0",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",
@@ -41,11 +41,11 @@
     "access": "public"
   },
   "devDependencies": {
-    "@openrouter/agent": "^0.6.0",
+    "@openrouter/agent": "^0.11.0",
     "bun-types": "latest"
   },
   "peerDependencies": {
-    "@openrouter/agent": "^0.6.0",
+    "@openrouter/agent": "^0.11.0",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
@@ -54,7 +54,7 @@
     }
   },
   "dependencies": {
-    "@openrouter/agent": "^0.6.0",
+    "@openrouter/agent": "^0.11.0",
     "@standard-schema/spec": "1.1.0",
     "@zed-industries/agent-client-protocol": "^0.4.5",
     "zod": "^4.0.0"