@noetic-tools/core 5.5.0 → 5.6.0

package/dist/harness/decide-call.js

@@ -0,0 +1,483 @@
+import { choiceValues, createMessage, DecideOutputError, extractAssistantText, frameworkCast, scoreLevels, } from '@noetic-tools/types';
+import { z } from 'zod';
+import { statusOf } from '../util/status-code.js';
+//#endregion
+//#region Public API
+/**
+ * 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 async function callDecide(request, deps) {
+    if (deps.client && (await isDecisionModel(request.model, deps))) {
+        return callNative(request, deps.client);
+    }
+    return callEstimated(request, deps);
+}
+//#endregion
+//#region Model detection
+function isDecisionModel(model, deps) {
+    const cached = deps.nativeModels.get(model);
+    if (cached) {
+        return cached.then((native) => native ?? false);
+    }
+    const lookup = lookupDecisionModel(model, deps.client);
+    deps.nativeModels.set(model, lookup);
+    // A failed lookup says nothing about the model, so the next call asks again.
+    void lookup.then((native) => {
+        if (native === undefined) {
+            deps.nativeModels.delete(model);
+        }
+    });
+    return lookup.then((native) => native ?? false);
+}
+/** `undefined` when the lookup itself failed, as opposed to the model not being one. */
+async function lookupDecisionModel(model, client) {
+    const slash = model.indexOf('/');
+    if (!client || slash <= 0) {
+        return false;
+    }
+    try {
+        const { data } = await client.models.get({
+            author: model.slice(0, slash),
+            slug: model.slice(slash + 1),
+        });
+        return data.architecture.outputModalities.includes('decisions');
+    }
+    catch (e) {
+        // An unknown model is not a decision model: the estimated path surfaces the
+        // provider's own error for it. Anything else may pass, so it is not cached.
+        return statusOf(e) === 404 ? false : undefined;
+    }
+}
+//#endregion
+//#region Native path
+async function callNative(request, client) {
+    const questions = {};
+    for (const [id, question] of Object.entries(request.questions)) {
+        questions[id] = toNativeQuestion(question);
+    }
+    const response = await client.alpha.decisions.create({
+        decisionsRequest: {
+            model: request.model,
+            state: toNativeState(request.instructions, request.state),
+            questions,
+        },
+    }, {
+        signal: request.signal,
+    });
+    const answers = {};
+    for (const [id, question] of Object.entries(request.questions)) {
+        const answer = fromNativeAnswer(question, response.answers[id]);
+        if (answer) {
+            answers[id] = answer;
+        }
+    }
+    return {
+        answers,
+        source: 'native',
+        modelId: response.model,
+        usage: {
+            inputTokens: response.usage.inputTokens,
+            outputTokens: response.usage.outputTokens,
+        },
+        cost: response.usage.cost,
+    };
+}
+/**
+ * The native APIs require `instructions` on every question, while Noetic lets a
+ * boolean question carry its meaning in `criteria` alone; and TypeSafe needs
+ * both criteria sides or neither.
+ */
+function toNativeQuestion(question) {
+    switch (question.type) {
+        case 'boolean':
+            return toNativeBoolean(question);
+        case 'choice': {
+            const criteria = {};
+            for (const value of choiceValues(question.choices)) {
+                criteria[value] = describeChoice(question, value) ?? null;
+            }
+            return {
+                type: 'choice',
+                instructions: question.instructions ?? 'Pick the option that best fits the state.',
+                criteria,
+            };
+        }
+        case 'score':
+            return {
+                type: 'score',
+                instructions: question.instructions ?? 'Place the state on this scale.',
+                criteria: scoreLevels(question.levels).map((l) => l.description ? `${l.label}: ${l.description}` : l.label),
+            };
+    }
+}
+function toNativeBoolean(question) {
+    const yes = question.criteria?.true;
+    const no = question.criteria?.false;
+    if (yes && no) {
+        const instructions = question.instructions ?? yes;
+        return {
+            type: 'noul',
+            instructions,
+            criteria: {
+                true: yes,
+                false: no,
+            },
+        };
+    }
+    // One side alone cannot be sent as criteria, so it joins the instructions.
+    const side = yes ? `Yes means: ${yes}` : no ? `No means: ${no}` : '';
+    return {
+        type: 'noul',
+        instructions: [
+            question.instructions,
+            side,
+        ]
+            .filter(Boolean)
+            .join(' '),
+    };
+}
+function describeChoice(question, value) {
+    if (Array.isArray(question.choices)) {
+        return undefined;
+    }
+    return frameworkCast(question.choices)[value];
+}
+/** Named parts become keys; unnamed text and images run in order under `conversation`. */
+function toNativeState(instructions, parts) {
+    const state = {};
+    if (instructions) {
+        state.instructions = instructions;
+    }
+    const conversation = [];
+    for (const part of parts) {
+        if (part.type === 'image') {
+            conversation.push({
+                type: 'image_url',
+                image_url: {
+                    url: part.imageUrl,
+                },
+            });
+            continue;
+        }
+        if (part.type === 'json') {
+            state[part.name] = part.value;
+            continue;
+        }
+        if (part.name) {
+            state[part.name] = part.text;
+            continue;
+        }
+        conversation.push(part.text);
+    }
+    if (conversation.length > 0) {
+        state.conversation = conversation;
+    }
+    return state;
+}
+/**
+ * Map one provider answer. Only an explicit `refusal` becomes a `Refusal`; a
+ * missing or mistyped answer comes back `undefined` so validation raises
+ * `model_parse_error` instead of passing a provider fault off as the model
+ * declining.
+ */
+function fromNativeAnswer(question, answer) {
+    if (isRefusal(answer)) {
+        return {
+            type: 'refusal',
+        };
+    }
+    if (question.type === 'boolean' && answer?.type === 'noul') {
+        return booleanAnswer(question, answer.noul);
+    }
+    if (question.type === 'choice' && answer?.type === 'choice') {
+        const probabilities = everyOutcome(choiceValues(question.choices), answer.probabilities ?? {
+            [answer.choice]: 1,
+        });
+        return {
+            type: 'choice',
+            value: answer.choice,
+            confidence: answer.confidence ?? top(probabilities),
+            probabilities,
+        };
+    }
+    if (question.type === 'score' && answer?.type === 'score') {
+        const labels = scoreLevels(question.levels).map((l) => l.label);
+        const rounded = labels[Math.round(answer.score)] ?? '';
+        // Score probabilities arrive keyed by level index ('0', '1', …). Without
+        // a distribution, all the weight goes on the level the score rounds to.
+        const byIndex = answer.probabilities ?? {
+            [String(Math.round(answer.score))]: 1,
+        };
+        const probabilities = everyOutcome(labels, Object.fromEntries(labels.map((label, i) => [
+            label,
+            byIndex[String(i)] ?? 0,
+        ])));
+        return {
+            type: 'score',
+            value: answer.score,
+            level: answer.probabilities ? (argmax(probabilities) ?? rounded) : rounded,
+            confidence: answer.confidence ?? top(probabilities),
+            probabilities,
+        };
+    }
+    return undefined;
+}
+//#endregion
+//#region Estimated path
+/**
+ * Ask a chat model for a probability per outcome, `samples` times, and average.
+ * Self-reported probabilities are not calibrated — fit for routing thresholds,
+ * not for measurement.
+ */
+async function callEstimated(request, deps) {
+    const schema = estimateSchema(request.questions);
+    const samples = Math.max(1, request.samples ?? 1);
+    const settled = await Promise.allSettled(Array.from({
+        length: samples,
+    }, () => deps.callModel({
+        model: request.model,
+        instructions: estimateInstructions(request),
+        items: [
+            stateMessage(request.state),
+        ],
+        // Averaging only helps when the runs can differ.
+        params: {
+            temperature: samples > 1 ? 0.7 : 0,
+        },
+        outputSchema: schema,
+        signal: request.signal,
+        parentSpan: request.parentSpan,
+    })));
+    const runs = settled.flatMap((r) => r.status === 'fulfilled'
+        ? [
+            r.value,
+        ]
+        : []);
+    const failed = settled.find((r) => r.status === 'rejected');
+    if (runs.length === 0 && failed) {
+        throw failed.reason;
+    }
+    const usage = {
+        inputTokens: sum(runs.map((r) => r.usage.inputTokens)),
+        outputTokens: sum(runs.map((r) => r.usage.outputTokens)),
+    };
+    const cost = runs.some((r) => r.cost !== undefined)
+        ? sum(runs.map((r) => r.cost ?? 0))
+        : undefined;
+    // Samples run hot, so one bad reply should cost only itself; fail only when none parse.
+    const results = runs.map((run) => parseEstimate(schema, extractAssistantText(run.items)));
+    const parsed = results.filter((r) => !(r instanceof DecideOutputError));
+    const firstError = results.find((r) => r instanceof DecideOutputError);
+    if (parsed.length === 0 && firstError) {
+        throw new DecideOutputError({
+            raw: firstError.raw,
+            schema: firstError.schema,
+            zodError: firstError.zodError,
+            usage,
+            cost,
+        });
+    }
+    const answers = {};
+    for (const [id, question] of Object.entries(request.questions)) {
+        answers[id] = averageAnswer(question, parsed.map((p) => p[id]));
+    }
+    return {
+        answers,
+        source: 'estimated',
+        modelId: request.model,
+        usage,
+        cost,
+    };
+}
+function parseEstimate(schema, raw) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        json = undefined;
+    }
+    const result = schema.safeParse(json);
+    if (!result.success) {
+        return new DecideOutputError({
+            raw,
+            schema,
+            zodError: result.error,
+        });
+    }
+    return result.data;
+}
+function estimateSchema(questions) {
+    const shape = {};
+    for (const [id, question] of Object.entries(questions)) {
+        const keys = outcomeKeys(question);
+        shape[id] = z.object(Object.fromEntries(keys.map((k) => [
+            k,
+            z.number().min(0).max(1),
+        ])));
+    }
+    return frameworkCast(z.object(shape));
+}
+/** Booleans estimate `{ yes }`; choices and scores estimate one probability per outcome. */
+function outcomeKeys(question) {
+    switch (question.type) {
+        case 'boolean':
+            return [
+                'yes',
+            ];
+        case 'choice':
+            return choiceValues(question.choices);
+        case 'score':
+            return scoreLevels(question.levels).map((l) => l.label);
+    }
+}
+function estimateInstructions(request) {
+    const lines = [
+        'You answer questions about the state you are given. For each question, return a probability for every outcome.',
+        'For a yes/no question, return the probability of yes. For other questions, the probabilities should sum to 1.',
+    ];
+    if (request.instructions) {
+        lines.push('', request.instructions);
+    }
+    lines.push('', 'Questions:');
+    for (const [id, question] of Object.entries(request.questions)) {
+        lines.push(`- ${id}: ${describeQuestion(question)}`);
+    }
+    return lines.join('\n');
+}
+function describeQuestion(question) {
+    const ask = question.instructions ?? '';
+    switch (question.type) {
+        case 'boolean': {
+            const yes = question.criteria?.true ? ` Yes means: ${question.criteria.true}.` : '';
+            const no = question.criteria?.false ? ` No means: ${question.criteria.false}.` : '';
+            return `(yes/no) ${ask}${yes}${no}`.trim();
+        }
+        case 'choice': {
+            const options = choiceValues(question.choices).map((v) => {
+                const description = describeChoice(question, v);
+                return description ? `${v} (${description})` : v;
+            });
+            return `(one of: ${options.join('; ')}) ${ask}`.trim();
+        }
+        case 'score':
+            return `(scale, lowest first: ${describeLevels(question)}) ${ask}`.trim();
+    }
+}
+function describeLevels(question) {
+    return scoreLevels(question.levels)
+        .map((l) => (l.description ? `${l.label} (${l.description})` : l.label))
+        .join('; ');
+}
+function stateMessage(parts) {
+    const content = parts.map((part) => {
+        if (part.type === 'image') {
+            return {
+                type: 'input_image',
+                imageUrl: part.imageUrl,
+            };
+        }
+        if (part.type === 'json') {
+            return {
+                type: 'input_text',
+                text: `${part.name}: ${JSON.stringify(part.value)}`,
+            };
+        }
+        return {
+            type: 'input_text',
+            text: part.name ? `${part.name}: ${part.text}` : part.text,
+        };
+    });
+    return {
+        ...createMessage('', 'user'),
+        content,
+    };
+}
+function averageAnswer(question, samples) {
+    const present = samples.filter((s) => s !== undefined);
+    if (present.length === 0) {
+        return {
+            type: 'refusal',
+        };
+    }
+    const keys = outcomeKeys(question);
+    const mean = {};
+    for (const key of keys) {
+        mean[key] = sum(present.map((s) => s[key] ?? 0)) / present.length;
+    }
+    if (question.type === 'boolean') {
+        return booleanAnswer(question, mean.yes ?? 0);
+    }
+    const probabilities = normalize(mean);
+    const best = argmax(probabilities) ?? keys[0] ?? '';
+    if (question.type === 'choice') {
+        return {
+            type: 'choice',
+            value: best,
+            confidence: top(probabilities),
+            probabilities,
+        };
+    }
+    return {
+        type: 'score',
+        value: sum(keys.map((k, i) => i * (probabilities[k] ?? 0))),
+        level: best,
+        confidence: top(probabilities),
+        probabilities,
+    };
+}
+//#endregion
+//#region Helpers
+function booleanAnswer(question, probability) {
+    return {
+        type: 'boolean',
+        value: probability >= (question.threshold ?? 0.5),
+        probability,
+    };
+}
+/** The SDK surfaces answer types it does not model as `UNKNOWN`, keeping the payload in `raw`. */
+function isRefusal(answer) {
+    if (answer?.type !== 'UNKNOWN' || !('raw' in answer)) {
+        return false;
+    }
+    const raw = answer.raw;
+    return typeof raw === 'object' && raw !== null && 'type' in raw && raw.type === 'refusal';
+}
+/** One entry per outcome, so a caller can index any choice or level; missing ones read 0. */
+function everyOutcome(outcomes, given) {
+    return Object.fromEntries(outcomes.map((o) => [
+        o,
+        Object.hasOwn(given, o) ? (given[o] ?? 0) : 0,
+    ]));
+}
+function normalize(probabilities) {
+    const keys = Object.keys(probabilities);
+    const total = sum(Object.values(probabilities));
+    const out = {};
+    for (const key of keys) {
+        out[key] = total > 0 ? (probabilities[key] ?? 0) / total : 1 / keys.length;
+    }
+    return out;
+}
+function argmax(probabilities) {
+    let best;
+    let bestP = -1;
+    for (const [key, p] of Object.entries(probabilities)) {
+        if (p > bestP) {
+            best = key;
+            bestP = p;
+        }
+    }
+    return best;
+}
+function top(probabilities) {
+    return Math.max(0, ...Object.values(probabilities));
+}
+function sum(values) {
+    return values.reduce((a, b) => a + b, 0);
+}
+//#endregion

package/dist/harness/deps/adapters.d.ts

@@ -1,4 +1,5 @@
 export { OpenRouter } from '@openrouter/agent';
+export { OpenRouter as OpenRouterSdk } from '@openrouter/sdk';
 export { createInMemoryFsAdapter } from '../../adapters/in-memory-fs-adapter.js';
 export { createInMemoryShellAdapter } from '../../adapters/in-memory-shell-adapter.js';
 export { createInMemorySubprocessAdapter } from '../../adapters/in-memory-subprocess-adapter.js';

package/dist/harness/deps/adapters.js

@@ -1,4 +1,5 @@
 export { OpenRouter } from '@openrouter/agent';
+export { OpenRouter as OpenRouterSdk } from '@openrouter/sdk';
 export { createInMemoryFsAdapter } from '../../adapters/in-memory-fs-adapter.js';
 export { createInMemoryShellAdapter } from '../../adapters/in-memory-shell-adapter.js';
 export { createInMemorySubprocessAdapter } from '../../adapters/in-memory-subprocess-adapter.js';

package/dist/harness/deps/context.d.ts

@@ -1,2 +1,2 @@
 export type { LayerStateStore, RecallCache } from '@noetic-tools/context';
-export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createContextCacheStore, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/context';
+export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createContextCacheStore, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, notifyDecision, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/context';

package/dist/harness/deps/context.js

@@ -1 +1 @@
-export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createContextCacheStore, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/context';
+export { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createContextCacheStore, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, notifyDecision, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from '@noetic-tools/context';

package/dist/harness/deps/types.d.ts

@@ -1,4 +1,4 @@
 export type { ContextCacheConfig, ContextCacheStore, ContextData, ContextLayer, ExecutionContext, ProjectionPolicy, StorageAdapter, } from '@noetic-tools/context';
-export type { AcpKeepAlive, AcpLiveSession, AcpSessionInfo, AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaConfig, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, RecallLayerOutput, SessionScope, SessionUsage, ShellAdapter, Span, SteeringDecision, Step, StreamEvent, StreamingItem, SubprocessAdapter, Tool, TraceExporter, } from '@noetic-tools/types';
+export type { AcpKeepAlive, AcpLiveSession, AcpSessionInfo, AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, CwdState, DecideRequest, DecideResponse, DecisionRecord, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaConfig, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, RecallLayerOutput, RecallOptions, SessionScope, SessionUsage, ShellAdapter, Span, SteeringDecision, Step, StreamEvent, StreamingItem, SubprocessAdapter, Tool, TraceExporter, } from '@noetic-tools/types';
 export { SteeringAction } from '@noetic-tools/types';
 export type { ZodType } from 'zod';

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export { context } from './builders/context-builder.js';
 /** @public */
 export { conditional, inParallel } from './builders/control-flow-builders.js';
 /** @public */
+export { decide, routeSwitch } from './builders/decide-builders.js';
+/** @public */
 export type { ScheduleOptions } from './builders/every.js';
 /** @public */
 export { schedule } from './builders/every.js';
@@ -65,7 +67,7 @@ export { execute } from './interpreter/execute.js';
 /** @public */
 /** @public */
 /** @public */
-export type { FactExtractor, FactSearcher, HistoryConfig, ObservationsConfig, ObservationsState, PlanConfig, PlanEnterSessionCallback, PlanExecutionEntry, PlanExitCallback, PlanState, ScratchpadConfig, ScratchpadState, TaskState, TemporalConfig, TemporalFact, TemporalSearchResult, } from '@noetic-tools/context';
+export type { DecisionsHistoryConfig, DecisionsHistoryLayer, DecisionsHistoryState, FactExtractor, FactSearcher, HistoryConfig, ObservationsConfig, ObservationsState, PlanConfig, PlanEnterSessionCallback, PlanExecutionEntry, PlanExitCallback, PlanState, ScratchpadConfig, ScratchpadState, TaskState, TemporalConfig, TemporalFact, TemporalSearchResult, } from '@noetic-tools/context';
 /** @public */
 /** @public */
 /** @public */
@@ -78,7 +80,7 @@ export type { FactExtractor, FactSearcher, HistoryConfig, ObservationsConfig, Ob
 /** @public */
 /** @public */
 /** @public */
-export { filesystem, findFunctionCall, history, instructions, observations, PlanPhase, PlanStyle, plan, scratchpad, steering, storageGetMany, stripUnresolvedToolCalls, taskState, temporal, toolCalls, } from '@noetic-tools/context';
+export { DECISION_PROJECTION, decisionsHistoryLayer, filesystem, findFunctionCall, history, instructions, observations, PlanPhase, PlanStyle, plan, scratchpad, steering, storageGetMany, stripUnresolvedToolCalls, taskState, temporal, toolCalls, } from '@noetic-tools/context';
 /** @public */
 export { createMessage, estimateTokens } from '@noetic-tools/types';
 /** @public */
@@ -104,7 +106,7 @@ export { getRegistry, lookupStep, registerStep } from './runtime/step-registry.j
 /** @public */
 export { defaultItemSchemaRegistry, ItemSchema, ItemSchemaRegistry } from '@noetic-tools/types';
 /** @public */
-export type { AcpAgentWorkflowNode, CallModelWorkflowNode, ConditionalRoute, ConditionalWorkflowNode, InParallelWorkflowNode, InvokeToolWorkflowNode, LoopWorkflowNode, MergeStrategy, ScheduleWorkflowNode, SequenceWorkflowNode, SpawnWorkflowNode, SubflowWorkflowNode, UntilPredicate, WithContextWorkflowNode, WorkflowDocument, WorkflowNode, } from './schemas/workflow.js';
+export type { AcpAgentWorkflowNode, CallModelWorkflowNode, ConditionalRoute, ConditionalWorkflowNode, DecideWorkflowNode, InParallelWorkflowNode, InvokeToolWorkflowNode, LoopWorkflowNode, MergeStrategy, RouteSwitchWorkflowNode, ScheduleWorkflowNode, SequenceWorkflowNode, SpawnWorkflowNode, SubflowWorkflowNode, UntilPredicate, WithContextWorkflowNode, WorkflowDocument, WorkflowNode, } from './schemas/workflow.js';
 /** @public */
 export { MergeStrategySchema, UntilPredicateSchema, validateWorkflow, WorkflowDocumentSchema, WorkflowNodeSchema, walkWorkflow, workflowDepth, } from './schemas/workflow.js';
 /** @public */
@@ -145,7 +147,7 @@ export type { LayerTraceSpan, Span, TraceExporter } from '@noetic-tools/types';
 /** @public */
 export type { FrameworkStreamEvent, HarnessResponse, SdkStreamEvent, StreamEvent, StreamingItem, } from '@noetic-tools/types';
 /** @public */
-export type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, ContextCacheConfig, ContextCacheStore, ContextEpoch, DeliveryMode, ExecuteOptions, HarnessStatus, ItemSchemaConfig, ReanchorReason, RecallLayerOutput, SessionScope, SessionUsage, } from '@noetic-tools/types';
+export type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, ContextCacheConfig, ContextCacheStore, ContextEpoch, DeliveryMode, ExecuteOptions, HarnessJudgmentContract, HarnessStatus, ItemSchemaConfig, ReanchorReason, RecallLayerOutput, SessionScope, SessionUsage, } from '@noetic-tools/types';
 /** @public */
 export type { AfterModelCallParams, AfterModelCallResult, BeforeToolCallParams, BeforeToolCallResult, LedgerEntry, SteeringConfig, SteeringDecision, SteeringRule, SteeringState, } from '@noetic-tools/types';
 /** @public */
@@ -153,6 +155,12 @@ export { LedgerEntryKind, SteeringAction } from '@noetic-tools/types';
 /** @public */
 export type { ExecuteStepFn, SettleResult, Snapshot, Step, StepAcpAgent, StepCallModel, StepConditional, StepInParallel, StepInParallelAll, StepInParallelRace, StepInParallelSettle, StepInvokeTool, StepLoop, StepRunCode, StepSpawn, StepWithContext, Until, Verdict, } from '@noetic-tools/types';
 /** @public */
+export type { AnsweredAll, AnswerFor, BooleanAnswer, BooleanQuestion, CaseKeyOf, ChoiceAnswer, ChoiceQuestion, ChoiceValues, DecideAnswer, DecideAnswers, DecideQuestion, DecideQuestions, DecideRequest, DecideResponse, DecideStatePart, DecideStep, DecideView, DecisionMeta, DecisionRecord, DecisionSource, LevelLabels, OnDecisionParams, RecallOptions, ScoreAnswer, ScoreLevel, ScoreQuestion, StepDecide, } from '@noetic-tools/types';
+/** @public */
+export { BooleanQuestionSchema, ChoiceQuestionSchema, choiceValues, DECIDE_LIMITS, DecideOutputError, DecideQuestionSchema, DecideQuestionsSchema, routeOutcomes, ScoreQuestionSchema, scoreLevels, } from '@noetic-tools/types';
+/** @public */
+export type { RouteSwitchByFunctionOpts, RouteSwitchByKeyOpts, StepDecideOpts, StepInput, StepOutput, } from './builders/decide-builders.js';
+/** @public */
 export type { AcpAgent, AcpAgentCapabilities, AcpAgentConnection, AcpAuthMethod, AcpAvailableCommand, AcpBoundPermissionHandler, AcpClientCapabilityConfig, AcpClientHost, AcpConnectOptions, AcpContentBlock, AcpKeepAlive, AcpLiveSession, AcpLoadSessionOptions, AcpMcpServer, AcpNewSessionOptions, AcpPermissionHandler, AcpPermissionOption, AcpPermissionOutcome, AcpPermissionPolicy, AcpPermissionRequestInfo, AcpPermissionRule, AcpPermissionSteerer, AcpPlanEntry, AcpPromptCapabilities, AcpPromptOptions, AcpRequestPermissionRequest, AcpSession, AcpSessionDisposer, AcpSessionInfo, AcpSessionMode, AcpSessionModeState, AcpSessionNotification, AcpSessionPolicy, AcpStopReason, AcpToolCallContent, AcpToolCallStatus, AcpToolKind, AcpTransport, AcpTransportFactory, AcpTransportOptions, AcpTurnResult, } from '@noetic-tools/types';
 /** @public */
 export { ACP_AGENT_STEP_KIND, AcpCapabilityError, AcpConnectError, AcpPermissionDecision, isAcpCapabilityError, isAcpConnectError, } from '@noetic-tools/types';

package/dist/index.js

@@ -16,6 +16,8 @@ export { context } from './builders/context-builder.js';
 /** @public */
 export { conditional, inParallel } from './builders/control-flow-builders.js';
 /** @public */
+export { decide, routeSwitch } from './builders/decide-builders.js';
+/** @public */
 export { schedule } from './builders/every.js';
 /** @public */
 export { layerData, layerFunction } from './builders/layer-provides-builders.js';
@@ -60,7 +62,7 @@ export { execute } from './interpreter/execute.js';
 /** @public */
 /** @public */
 /** @public */
-export { filesystem, findFunctionCall, history, instructions, observations, PlanPhase, PlanStyle, plan, scratchpad, steering, storageGetMany, stripUnresolvedToolCalls, taskState, temporal, toolCalls, } from '@noetic-tools/context';
+export { DECISION_PROJECTION, decisionsHistoryLayer, filesystem, findFunctionCall, history, instructions, observations, PlanPhase, PlanStyle, plan, scratchpad, steering, storageGetMany, stripUnresolvedToolCalls, taskState, temporal, toolCalls, } from '@noetic-tools/context';
 //#endregion
 //#region Message Utilities
 /** @public */
@@ -100,6 +102,8 @@ export { Slot } from '@noetic-tools/context';
 /** @public */
 export { LedgerEntryKind, SteeringAction } from '@noetic-tools/types';
 /** @public */
+export { BooleanQuestionSchema, ChoiceQuestionSchema, choiceValues, DECIDE_LIMITS, DecideOutputError, DecideQuestionSchema, DecideQuestionsSchema, routeOutcomes, ScoreQuestionSchema, scoreLevels, } from '@noetic-tools/types';
+/** @public */
 export { ACP_AGENT_STEP_KIND, AcpCapabilityError, AcpConnectError, AcpPermissionDecision, isAcpCapabilityError, isAcpConnectError, } from '@noetic-tools/types';
 /** @public */
 export { TIMEOUT_ERROR_PREFIX } from '@noetic-tools/types';

package/dist/interpreter/action-deps.d.ts

@@ -1,5 +1,5 @@
 export type { LayerServeInfo, LayerStateStore } from '@noetic-tools/context';
-export { allocateBudgets, assembleView, churnFor, churnRate, commitLayerUsage, computeLayerUsage, contextToExecCtx, createContextCacheStore, DEFAULT_PROJECTION, lineageKey, noteCacheOutcome, openEpoch, pin, pinKey, reanchorReason, resolveCacheConfig, resolveLayerTools, returnLayers, spawnLayers, } from '@noetic-tools/context';
+export { allocateBudgets, assembleView, churnFor, churnRate, commitLayerUsage, computeLayerUsage, contextToExecCtx, createContextCacheStore, DECISION_PROJECTION, DEFAULT_PROJECTION, lineageKey, noteCacheOutcome, openEpoch, pin, pinKey, reanchorReason, resolveCacheConfig, resolveLayerTools, returnLayers, spawnLayers, } from '@noetic-tools/context';
 export type { ItemSchemaRegistry } from '@noetic-tools/types';
 export { defaultItemSchemaRegistry } from '@noetic-tools/types';
 export { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';

package/dist/interpreter/action-deps.js

@@ -1,4 +1,4 @@
-export { allocateBudgets, assembleView, churnFor, churnRate, commitLayerUsage, computeLayerUsage, contextToExecCtx, createContextCacheStore, DEFAULT_PROJECTION, lineageKey, noteCacheOutcome, openEpoch, pin, pinKey, reanchorReason, resolveCacheConfig, resolveLayerTools, returnLayers, spawnLayers, } from '@noetic-tools/context';
+export { allocateBudgets, assembleView, churnFor, churnRate, commitLayerUsage, computeLayerUsage, contextToExecCtx, createContextCacheStore, DECISION_PROJECTION, DEFAULT_PROJECTION, lineageKey, noteCacheOutcome, openEpoch, pin, pinKey, reanchorReason, resolveCacheConfig, resolveLayerTools, returnLayers, spawnLayers, } from '@noetic-tools/context';
 export { defaultItemSchemaRegistry } from '@noetic-tools/types';
 export { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
 export { ContextImpl } from '../runtime/context-impl.js';

package/dist/interpreter/action-types.d.ts

@@ -1,3 +1,3 @@
 export type { ContextConfig, ContextData, ContextLayer, ExecutionContext, } from '@noetic-tools/context';
-export type { AgentHarnessContract, CallModelRequest, Context, ContextRerenderRequest, ExecuteStepFn, FunctionCallItem, InputMessageItem, Item, LLMResponse, ProjectionPolicy, RecallLayerOutput, RetryPolicy, ServerToolSpec, StepCallModel, StepInvokeTool, StepMeta, StepRunCode, StepSpawn, StepWithContext, Tool, } from '@noetic-tools/types';
+export type { AgentHarnessContract, CallModelRequest, Context, ContextRerenderRequest, ExecuteStepFn, FunctionCallItem, InputMessageItem, Item, LLMResponse, ProjectionPolicy, RecallLayerOutput, RetryPolicy, ServerToolSpec, StepCallModel, StepDecide, StepInvokeTool, StepMeta, StepRunCode, StepSpawn, StepWithContext, Tool, } from '@noetic-tools/types';
 export { isServerToolSpec, SteeringAction } from '@noetic-tools/types';

package/dist/interpreter/collect-tools.js

@@ -43,6 +43,8 @@ function walkStep(step, out) {
             return;
         case 'runCode':
         case 'invokeTool':
+        // Decide steps ask questions; they never call tools.
+        case 'decide':
         // An ACP agent runs its own tools inside the external agent process; it
         // contributes nothing to the host unified tool set.
         case 'acp-agent':

package/dist/interpreter/execute-control.js

@@ -9,7 +9,7 @@ import { cloneWithGuard } from './clone-guard.js';
 import { getContextChannelStore, isContextImpl, isMutableContext } from './typeguards.js';
 //#region conditional
 export async function executeConditional(step, input, ctx, executeStep) {
-    const selected = await step.route(input, ctx);
+    const selected = await step.route(input, ctx, executeStep);
     if (selected === null) {
         // Requires I assignable to O for null route — when no route is selected,
         // the input passes through. Callers must ensure I is compatible with O.

package/dist/interpreter/execute-decide.d.ts

@@ -0,0 +1,10 @@
+import type { Context, ContextLayer, StepDecide } from './action-types.js';
+/**
+ * Run a `decide` step: build state from the input, the context view, and the
+ * step's context selector; ask the harness; validate; record. The conversation
+ * is read, never written — no item-log appends, no steering, no layer `store()`.
+ * Layers hear about the decision through `onDecision`.
+ *
+ * @internal
+ */
+export declare function executeDecide<TContext, I, O>(step: StepDecide<TContext, I, O>, input: I, ctx: Context<TContext>, layers?: ContextLayer[]): Promise<O>;