@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/decision/PreparedSteps.js

@@ -0,0 +1,147 @@
+import { randomUUID } from 'node:crypto';
+import { redactSecrets } from '../memory/redaction.js';
+import { DecisionPolicy } from './DecisionPolicy.js';
+export const PREPARE_STEPS = 'prepare_steps';
+export const PREPARED_TRIGGERS = ['success', 'failure', 'always'];
+const kinds = ['investigate', 'retry', 'change_strategy', 'verify', 'complete'];
+const triggerKinds = new Set(['investigate', 'verify']);
+const forbidden = new Set([PREPARE_STEPS, 'complete_agent', 'update_todos', 'ask_user', 'spawn_subagent']);
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+export function boundedDecisionText(text, bytes) {
+    const value = redactSecrets(text).text;
+    let used = 0, result = '';
+    for (const point of value) {
+        const length = Buffer.byteLength(point, 'utf8');
+        if (used + length > bytes)
+            break;
+        result += point;
+        used += length;
+    }
+    return result;
+}
+/** Deliberately narrower than tool families: no automatic retry of shell, browser or writes. */
+export function retrySafe(tool) {
+    return !!tool && ['Read', 'Glob', 'Grep', 'read', 'ls', 'find', 'grep', 'read_file', 'list_files', 'search_files', 'repo_explore', 'memory_search', 'read_artifact', 'git_read'].includes(tool.name)
+        && (!tool.capability || tool.capability === 'git.read' || tool.capability === 'github.read');
+}
+/** Invocation-local concrete actions authored by the coding model; Jev may only select IDs. */
+export class PreparedSteps {
+    steps = [];
+    clear() { this.steps = []; }
+    candidates() {
+        return this.steps.flatMap(step => {
+            const description = step.completion
+                ? JSON.stringify({ condition: step.description, proposedAnswer: { ...step.completion, tests: [] } })
+                : JSON.stringify({ condition: step.description, tool: step.tool.name });
+            // Completion selection must see the entire proposed answer, never just its author's label.
+            const redacted = redactSecrets(description).text;
+            if (step.completion && (redacted !== description || Buffer.byteLength(description) > 512))
+                return [];
+            return [{ id: step.id, kind: step.kind, description: boundedDecisionText(redacted, 512) }];
+        });
+    }
+    take(id) {
+        const step = this.steps.find(item => item.id === id);
+        this.steps = this.steps.filter(item => item.id !== id);
+        return step;
+    }
+    /** How many steps are held; a cleared set reports zero. */
+    get size() { return this.steps.length; }
+    /**
+     * The first declared step whose trigger matches the batch outcome, removed from the set. The
+     * declaration order is the model's preference order; no scoring happens here.
+     */
+    takeTriggered(outcome) {
+        const step = this.steps.find(item => item.when !== undefined && (item.when === 'always' || item.when === outcome));
+        if (!step)
+            return undefined;
+        this.steps = this.steps.filter(item => item !== step);
+        return step;
+    }
+    tool(catalog, options = {}) {
+        const continuations = options.continuations === true;
+        const properties = {
+            id: { type: 'string', pattern: '^[a-z][a-z0-9_]{0,63}$' }, kind: { type: 'string', enum: kinds }, description: { type: 'string', maxLength: 512 },
+            tool: { type: 'object', properties: { name: { type: 'string' }, arguments: { type: 'object' } }, required: ['name', 'arguments'], additionalProperties: false },
+            completion: { type: 'object', properties: { summary: { type: 'string' }, tests: { type: 'array', items: { type: 'string' } }, outcome: { type: 'string' }, output: { type: 'object' }, artifacts: { type: 'array', items: { type: 'object' } } }, required: ['summary', 'tests'], additionalProperties: false },
+            ...(continuations ? { when: { type: 'string', enum: [...PREPARED_TRIGGERS], description: 'investigate/verify only: run right after this batch when its calls succeed, fail, or always; no decision request' } } : {}),
+        };
+        const allowedKeys = ['id', 'kind', 'description', 'tool', 'completion', ...(continuations ? ['when'] : [])];
+        return {
+            name: PREPARE_STEPS, executionMode: 'sequential',
+            description: 'Prepare up to 8 concrete alternative next steps so Jev can choose after tool results without another coding-model turn. Each step has id, kind, description and either tool {name, arguments} or completion {summary, tests}. Only prepare actions whose exact arguments are already known. Descriptions must state the evidence required to select them. Completion must already answer the task without unseen data; normal completion validation still applies. Call this first in the same tool-call batch as the initial observation/action. Steps expire when the coding model resumes. This replaces earlier steps. Do not prepare retries of shell or writes. Jev cannot generate arguments or answers.',
+            parameters: { type: 'object', properties: { steps: { type: 'array', maxItems: 8, items: { type: 'object', properties,
+                            required: ['id', 'kind', 'description'], additionalProperties: false } } }, required: ['steps'], additionalProperties: false },
+            execute: async (args, context) => {
+                context.signal.throwIfAborted();
+                this.clear();
+                if (Object.keys(args).some(key => key !== 'steps') || !Array.isArray(args.steps) || args.steps.length > 8 || Buffer.byteLength(JSON.stringify(args)) > 16_384)
+                    throw new Error('Invalid prepared steps; maximum 8 steps and 16 KiB');
+                const ids = new Set();
+                let triggers = 0;
+                const next = args.steps.map((value) => {
+                    if (!object(value) || Object.keys(value).some(key => !allowedKeys.includes(key))
+                        || typeof value.id !== 'string' || !/^[a-z][a-z0-9_]{0,63}$/.test(value.id) || ['llm', 'constructor', 'prototype', '__proto__'].includes(value.id) || ids.has(value.id)
+                        || typeof value.kind !== 'string' || !kinds.includes(value.kind) || typeof value.description !== 'string' || !value.description.trim() || Buffer.byteLength(value.description) > 512)
+                        throw new Error('Invalid prepared step');
+                    if (value.when !== undefined) {
+                        if (!continuations || typeof value.when !== 'string' || !PREPARED_TRIGGERS.includes(value.when) || !triggerKinds.has(value.kind))
+                            throw new Error('A when trigger is only accepted on investigate or verify steps');
+                        triggers++;
+                    }
+                    ids.add(value.id);
+                    if (value.kind === 'complete') {
+                        if (value.tool !== undefined || !object(value.completion) || typeof value.completion.summary !== 'string' || !value.completion.summary.trim() || !Array.isArray(value.completion.tests) || value.completion.tests.some(t => typeof t !== 'string'))
+                            throw new Error('Complete step requires a prepared completion');
+                    }
+                    else {
+                        if (value.completion !== undefined || !object(value.tool) || Object.keys(value.tool).some(key => !['name', 'arguments'].includes(key)) || typeof value.tool.name !== 'string' || !object(value.tool.arguments))
+                            throw new Error('Action step requires concrete tool arguments');
+                        const toolName = value.tool.name;
+                        const tool = catalog.find(tool => tool.name === toolName);
+                        if (!tool || forbidden.has(tool.name) || (value.kind === 'retry' && !retrySafe(tool)))
+                            throw new Error('Prepared action is not allowed');
+                    }
+                    return structuredClone(value);
+                });
+                this.steps = next;
+                options.onDeclared?.({ steps: next.length, chars: JSON.stringify(args).length, triggers });
+                return JSON.stringify({ prepared: next.map(({ id, kind }) => ({ id, kind })) });
+            },
+        };
+    }
+}
+export function permittedContinuation(step, batch) {
+    const yes = (id) => DecisionPolicy.boolean(batch, id) === true;
+    if (step.kind === 'complete')
+        return yes('likely_complete') && yes('result_answered_question')
+            && ['needs_more_investigation', 'should_retry', 'strategy_should_change', 'ready_for_verification'].every(id => DecisionPolicy.boolean(batch, id) === false);
+    if (step.kind === 'retry')
+        return yes('should_retry') && DecisionPolicy.boolean(batch, 'strategy_should_change') === false;
+    if (step.kind === 'change_strategy')
+        return yes('strategy_should_change');
+    if (step.kind === 'verify')
+        return yes('ready_for_verification');
+    return yes('needs_more_investigation');
+}
+export function preparedResponse(step, verification) {
+    return step.completion ? { text: JSON.stringify({ ...step.completion, tests: verification }), toolCalls: [] }
+        : { text: '', toolCalls: [{ id: randomUUID(), name: step.tool.name, arguments: JSON.stringify(step.tool.arguments) }] };
+}
+export function postToolGuidance(batch) {
+    const directives = [];
+    const yes = (id) => DecisionPolicy.boolean(batch, id) === true;
+    if (yes('strategy_should_change'))
+        directives.push('Change investigation strategy; do not repeat the same failed approach.');
+    else if (yes('should_retry'))
+        directives.push('A retry may help; reuse only safe actions and respect the repeated-failure limit.');
+    if (yes('needs_more_investigation'))
+        directives.push('Gather the missing evidence before completing.');
+    if (yes('ready_for_verification'))
+        directives.push('Execute the required verification now.');
+    if (yes('result_answered_question'))
+        directives.push('The latest result appears to answer the current question; reuse that evidence instead of rediscovering it.');
+    if (yes('likely_complete'))
+        directives.push('Check the existing completion contract against observed evidence and complete if satisfied; do not claim unperformed checks.');
+    return directives.length ? `Runtime Jev decisions (subject to task and graph requirements):\n${directives.join('\n')}` : '';
+}

package/dist/src/decision/applyToolMenu.d.ts

@@ -0,0 +1,3 @@
+import type { HardenedRunOptions } from '../react-runtime.js';
+/** Optional boundary optimization; the existing executor still owns every permission and call. */
+export declare function applyToolMenu(options: HardenedRunOptions): Promise<HardenedRunOptions>;

package/dist/src/decision/applyToolMenu.js

@@ -0,0 +1,61 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { toolFamily } from './toolFamilies.js';
+import { clipFactText } from './facts.js';
+import { selectToolMenu } from './toolMenu.js';
+/** Optional boundary optimization; the existing executor still owns every permission and call. */
+export async function applyToolMenu(options) {
+    const mode = options.efficiency?.toolMenuRouting?.mode ?? 'off';
+    const manager = options.decisionManager;
+    if (mode === 'off' || !manager?.toolMenuEnabled)
+        return options;
+    const task = options.decisionTask ?? options.task;
+    const control = options.context.runControl;
+    const revision = control?.revision;
+    const permission = () => JSON.stringify([options.context.yolo, options.context.permissions ?? null,
+        options.context.approvalMode ?? null, control?.permissions ?? null, control?.yolo ?? null]);
+    const permittedUnder = permission();
+    const pause = control?.signal;
+    const signal = pause ? AbortSignal.any([options.context.signal, pause]) : options.context.signal;
+    const previous = options.resumeMessages ?? options.previousConversation?.messages ?? [];
+    const historical = [...new Set([...previous.flatMap(message => (message.toolCalls ?? []).map(call => call.name)), ...(options.efficiency?.toolMenuRouting?.pinnedTools ?? [])])];
+    const identity = { runId: options.runId ?? randomUUID(), nodeId: options.nodeId ?? 'engineer', invocationId: randomUUID() };
+    const emit = async (data) => {
+        try {
+            await options.onEvent?.({ type: 'efficiency.tool_menu', time: new Date().toISOString(), data: { ...identity, mode, ...data } });
+        }
+        catch { /* Optional optimization telemetry cannot change execution. */ }
+    };
+    try {
+        const selected = await selectToolMenu({
+            tools: options.tools.map(tool => ({ ...tool, family: toolFamily(tool) })), task,
+            projectedTask: clipFactText(task, 3000), historical, mode,
+            topK: options.efficiency?.toolMenuRouting?.topK,
+            minSavingsChars: options.efficiency?.toolMenuRouting?.minSavingsChars,
+            signal, fresh: () => permission() === permittedUnder && control?.revision === revision,
+            classify: (request, aborted) => manager.toolMenu(request, identity, aborted, options.onEvent),
+        });
+        // Do not add an awaited telemetry gap after the final freshness check.
+        options.context.signal.throwIfAborted();
+        if (pause?.aborted || permission() !== permittedUnder || control?.revision !== revision)
+            return options;
+        void emit({ reason: selected.reason, receipt: selected.receipt, omitted: selected.omitted.length,
+            requestHash: selected.request ? createHash('sha256').update(JSON.stringify({ toolMenu: selected.request })).digest('hex') : undefined,
+            requestChars: selected.request ? JSON.stringify({ toolMenu: selected.request }).length : 0 });
+        if (!selected.omitted.length)
+            return options;
+        const kept = new Set(selected.tools.map(tool => tool.name));
+        // Preserve the exact Tool objects and current narrowed definitions. Never replace a tool
+        // with an older, wider descriptor merely because that descriptor exists in recoverTools.
+        const recover = new Map((options.recoverTools ?? []).map(tool => [tool.name, tool]));
+        for (const tool of options.tools)
+            recover.set(tool.name, tool);
+        return { ...options, tools: options.tools.filter(tool => kept.has(tool.name)), recoverTools: [...recover.values()],
+            systemPrompt: [options.systemPrompt,
+                `Optional, already-permitted tool schemas are available through restore_tools: ${JSON.stringify(selected.omitted.map(tool => tool.name))}. Restore a schema when required; this grants no permission and bypasses no approval.`].filter(Boolean).join('\n\n') };
+    }
+    catch (error) {
+        options.context.signal.throwIfAborted();
+        await emit({ reason: pause?.aborted ? 'paused' : 'routing_unavailable', omitted: 0 });
+        return options;
+    }
+}

package/dist/src/decision/checks.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Every check runner a shell command line contains, each as the command that would run on its own.
+ * Control flow is unwrapped (`if`, `then`, `do`, `else`, braces, parentheses), so a runner nested in
+ * a conditional is never missed. Undefined when anything else is in the line (`cd sub`, `FOO=1 npm
+ * test`, a standalone assertion, another program): the runners' standalone results would then not
+ * say what the line verified.
+ */
+export declare function checkRunners(line: string): string[] | undefined;
+export declare function commandLine(args: unknown): string | undefined;
+export declare function isCheckCall(name: string, family: string | undefined, args: unknown): boolean;
+export declare function isReplaySafeCheck(name: string, family: string | undefined, args: unknown): boolean;
+/** A check that can establish a pass on the final workspace, not merely contain a check. */
+export declare function isVerificationCheck(name: string, family: string | undefined, args: unknown): boolean;

package/dist/src/decision/checks.js

@@ -0,0 +1,104 @@
+/** Recognition is deliberately broader than replay/verification authority. */
+const RUNNER = String.raw `(?:node\s+--test\b|(?:python3?\s+-m\s+)?(?:pytest|unittest|mypy)\b|(?:npx\s+)?(?:jest|vitest|tsc|eslint|mocha|ava|ruff|ctest)\b|npx\s+playwright\s+test\b|(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:test|build|lint|typecheck|type-check|check|verify)\b|cargo\s+(?:test|build|check|clippy)\b|go\s+(?:test|build|vet)\b|dotnet\s+(?:test|build)\b|mvn\s+(?:test|verify)\b|\.?[\\/]?gradlew?(?:\.bat)?\s+(?:test|build|check)\b|make\s+(?:test|check)\b)`;
+const AT_START = new RegExp(`^${RUNNER}`, 'i');
+/**
+ * Glue that can sit between runners without changing what they verify: messages, exit, block ends,
+ * output filters, and a test only as the condition of if/elif/while/until. On its own a test is an
+ * assertion (`[ -f dist/cli.js ]`) whose failure must count.
+ */
+function inert(part, condition) {
+    if (!part || /^(?:fi|done|esac|then|do|else)$/i.test(part) || outputFilter(part))
+        return true;
+    if (/^(?:exit(?:\s+\S+)?|(?:echo|printf|Write-Host|Write-Output)\b.*)$/i.test(part))
+        return true;
+    return condition && /^(?:\[\[?\s.*\]\]?|\$LASTEXITCODE\b.*|\$\?.*|-not\s+\$\?.*)$/i.test(part);
+}
+/**
+ * Every check runner a shell command line contains, each as the command that would run on its own.
+ * Control flow is unwrapped (`if`, `then`, `do`, `else`, braces, parentheses), so a runner nested in
+ * a conditional is never missed. Undefined when anything else is in the line (`cd sub`, `FOO=1 npm
+ * test`, a standalone assertion, another program): the runners' standalone results would then not
+ * say what the line verified.
+ */
+export function checkRunners(line) {
+    const runners = [];
+    let guard = false; // The previous fragment was a bare if/elif/while/until, as in PowerShell's `if (...)`.
+    for (const raw of line.split(/&&|\|\||[;|\n\r{}()]/)) {
+        const condition = guard || /^(?:if|elif|while|until)\s/i.test(raw.trim());
+        guard = false;
+        let part = raw.trim().replace(/^(?:(?:if|elif|while|until|then|do|else)\s+)+/i, '').trim();
+        if (/^(?:if|elif|while|until)$/i.test(part)) {
+            guard = true;
+            continue;
+        }
+        const negated = /^!\s*/.test(part);
+        part = part.replace(/^!\s*/, '');
+        // `! npm run build` expects a failure: a standalone pass of the same command cannot stand in for it.
+        if (AT_START.test(part)) {
+            if (negated)
+                return undefined;
+            runners.push(part);
+        }
+        else if (!inert(part, condition))
+            return undefined;
+    }
+    return runners;
+}
+const QA = new Set(['qa.fast', 'qa.test', 'qa.deep', 'qa.security', 'qa.browser']);
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+export function commandLine(args) {
+    if (!object(args))
+        return undefined;
+    if (typeof args.command === 'string')
+        return args.command;
+    if (typeof args.cmd === 'string')
+        return args.cmd;
+    if (typeof args.program === 'string' && Array.isArray(args.args) && args.args.every(a => typeof a === 'string')) {
+        return [args.program, ...args.args].join(' ');
+    }
+    return undefined;
+}
+export function isCheckCall(name, family, args) {
+    if (name.startsWith('qa.'))
+        return QA.has(name);
+    if (family !== 'shell' || !object(args) || 'action' in args)
+        return false;
+    const line = commandLine(args);
+    return !!line && line.split(/&&|\|\||[;|\n\r]/).some(part => AT_START.test(part.trim()));
+}
+/** Closed, argument-aware output filters. In particular, sort -o and sort /O write files. */
+function outputFilter(stage) {
+    return /^(?:tail\s+(?:-\d+|-n\s+\d+)|select-object\s+-last\s+\d+|out-string(?:\s+-width\s+\d+)?)$/i.test(stage.trim());
+}
+export function isReplaySafeCheck(name, family, args) {
+    if (name.startsWith('qa.'))
+        return QA.has(name);
+    if (!isCheckCall(name, family, args) || !object(args))
+        return false;
+    const line = commandLine(args);
+    if (!line)
+        return false;
+    // Check runners can have explicitly mutating modes. They remain model-executable, not replayable.
+    if (/(?:^|\s)(?:--(?:fix|write|update(?:-snapshots?)?|eval|require|import)(?:[=\s]|$)|-u(?:\s|$))/.test(line))
+        return false;
+    if (typeof args.program === 'string' && args.command === undefined && args.cmd === undefined) {
+        return Array.isArray(args.args) && args.args.every(a => typeof a === 'string') && AT_START.test(line.trim());
+    }
+    const folded = line.replace(/2>&1/g, ' ').trim();
+    if (/[;\n\r`<>$&(){}]|\|\|/.test(folded))
+        return false;
+    const [check, ...stages] = folded.split('|').map(s => s.trim());
+    return AT_START.test(check) && stages.every(outputFilter);
+}
+/** A check that can establish a pass on the final workspace, not merely contain a check. */
+export function isVerificationCheck(name, family, args) {
+    if (!isReplaySafeCheck(name, family, args))
+        return false;
+    if (name.startsWith('qa.'))
+        return true;
+    if (object(args) && typeof args.program === 'string' && args.command === undefined && args.cmd === undefined)
+        return true;
+    // A shell pipeline may hide the runner's exit status. It can be replayed, but cannot authorize
+    // automatic completion; let the model inspect it or use a plain/native check instead.
+    return !commandLine(args)?.replace(/2>&1/g, '').includes('|');
+}

package/dist/src/decision/facts.d.ts

@@ -0,0 +1,64 @@
+export type FactId = 'task_needs_checks' | 'checks_passed' | 'temporary_failure';
+export declare const FACT_IDS: readonly FactId[];
+export interface FactToolResult {
+    tool: string;
+    command: string;
+    succeeded: boolean;
+    output: string;
+}
+export interface FactFailedCall {
+    tool: string;
+    command: string;
+    error: string;
+}
+export type FactRequest = {
+    id: 'task_needs_checks';
+    state: {
+        task: string;
+    };
+} | {
+    id: 'checks_passed';
+    state: {
+        tool_results: FactToolResult[];
+    };
+} | {
+    id: 'temporary_failure';
+    state: {
+        failed_call: FactFailedCall[];
+    };
+};
+export declare const FACT_WORDING: Record<FactId, {
+    instructions: string;
+    criteria: {
+        true: string;
+        false: string;
+    };
+}>;
+/**
+ * The bar each fact must reach before the runtime acts on it: yes at p >= bar, no at p <= 1 - bar.
+ * "Checks passed" can end a run, so it keeps the strict 0.95 the CLI already applies to post-tool
+ * answers; a wrong answer to the other two costs at most one extra check or one skipped retry.
+ */
+export declare const FACT_THRESHOLDS: Record<FactId, number>;
+export declare function factAnswer(id: FactId, probability: number | undefined): boolean | undefined;
+/** Field limits, in UTF-8 bytes, for what one fact request may carry (the hosted body is capped at 32 KiB). */
+export declare const FACT_LIMITS: {
+    readonly task: 3000;
+    readonly command: 512;
+    readonly output: 2000;
+    readonly error: 1500;
+    readonly entries: 8;
+};
+/**
+ * Keep 70% head and 30% tail, as the hosted provider's routing snapshot does and as the prompt eval
+ * measured: a test summary ("ℹ fail 0", "Tests: 3 failed") sits at the end of its output.
+ */
+export declare function clipFactText(text: string, bytes: number): string;
+/**
+ * The text "does the task ask for checks" is judged on: the task (a confirmed handoff's instruction
+ * when there is one) and the node's own instruction, which can require checks the user never named.
+ * Each part is clipped on its own so a long task cannot crowd the instruction out.
+ */
+export declare function factTaskText(task: string, nodeInstruction?: string): string;
+/** Validate an answer at the provider boundary: a probability in [0, 1] or nothing. */
+export declare function factProbability(value: unknown): number;

package/dist/src/decision/facts.js

@@ -0,0 +1,90 @@
+/**
+ * Literal facts Jev answers after a tool batch, one request per fact with only the state it needs.
+ *
+ * Whole-decision questions ("is the task likely complete?") stayed below 77% confident-and-right on
+ * real sessions because their answer depends on what the agent will do next. These facts are visible
+ * in the state, so Jev answers them at p >= 0.95 or <= 0.05, and rightly, on 97.1% of held-out decision points
+ * (eval/jev-prompt/FINDINGS.md). The runtime answers everything it knows exactly itself (a call
+ * failed, files were written, a command is a check) and combines the facts in code.
+ *
+ * The hosted proxy owns the wording it sends (infra/andorra-auth/proxy.py FACTS); this copy is what a
+ * direct provider sends, and the two are kept identical.
+ */
+import { redactSecrets } from '../memory/redaction.js';
+import { boundedDecisionText } from './PreparedSteps.js';
+export const FACT_IDS = ['task_needs_checks', 'checks_passed', 'temporary_failure'];
+export const FACT_WORDING = {
+    task_needs_checks: {
+        instructions: 'The `task` asks for tests, a build, a type check or another check to be run.',
+        criteria: {
+            true: 'The task asks for something to be run to confirm the work, for example "run the test suite", "make sure it passes", or "verify by starting the server and issuing requests".',
+            false: 'The task asks only for a change, an answer, a document, a plan, research, browsing or logging in to a site, and never asks for anything to be run to confirm the work. Writing a test plan or locating tests is not running them, and a task that says not to run tests is no.',
+        },
+    },
+    checks_passed: {
+        instructions: 'These tool results include a test, build, type-check or QA run that reports zero failures.',
+        criteria: {
+            true: 'A test, build, type-check or QA output here shows everything passed, for example "fail 0", only ✔ marks, PASSED, "verdict":"clean", or a build that finished without errors.',
+            false: 'No output here is a test, build, type-check or QA run with a pass or fail result, or one of them reports a failure, an error or a non-zero exit code. File listings, git output, server logs, todo updates, browser snapshots or session status, saved artifacts and plain command output do not count as checks.',
+        },
+    },
+    temporary_failure: {
+        instructions: 'The error message reports a temporary network or service problem, or a resource that was busy or locked.',
+        criteria: {
+            true: 'The message names a timeout (ETIMEDOUT, "timed out" while connecting or reading), a dropped or reset connection (ECONNRESET, "socket hang up"), a refused connection to a server that was only just started, a rate limit or HTTP 429, a server error such as HTTP 500, 502, 503 or 504, a DNS lookup failure (EAI_AGAIN, ENOTFOUND while online), or a lock or busy resource (index.lock exists, SQLITE_BUSY, EBUSY).',
+            false: 'The message reports a problem with the call itself or the workspace: a validation or usage error, a wrong parameter, a missing file, path or module, a failing test, build or type check, a permission or policy refusal, a limit, or something unavailable or misconfigured.',
+        },
+    },
+};
+/**
+ * The bar each fact must reach before the runtime acts on it: yes at p >= bar, no at p <= 1 - bar.
+ * "Checks passed" can end a run, so it keeps the strict 0.95 the CLI already applies to post-tool
+ * answers; a wrong answer to the other two costs at most one extra check or one skipped retry.
+ */
+export const FACT_THRESHOLDS = { checks_passed: 0.95, task_needs_checks: 0.9, temporary_failure: 0.9 };
+export function factAnswer(id, probability) {
+    if (probability === undefined || !Number.isFinite(probability))
+        return undefined;
+    // Answers arrive with two decimals; the tolerance keeps 1 - 0.9 (0.0999…) from missing 0.1.
+    const bar = FACT_THRESHOLDS[id], tolerance = 1e-9;
+    return probability >= bar - tolerance ? true : probability <= 1 - bar + tolerance ? false : undefined;
+}
+/** Field limits, in UTF-8 bytes, for what one fact request may carry (the hosted body is capped at 32 KiB). */
+export const FACT_LIMITS = { task: 3000, command: 512, output: 2000, error: 1500, entries: 8 };
+const CLIP_MARKER = '\n…[Jev routing context clipped]…\n';
+/**
+ * Keep 70% head and 30% tail, as the hosted provider's routing snapshot does and as the prompt eval
+ * measured: a test summary ("ℹ fail 0", "Tests: 3 failed") sits at the end of its output.
+ */
+export function clipFactText(text, bytes) {
+    // Redact before clipping so neither the head nor the tail can carry a secret.
+    const normalized = redactSecrets(text).text.replace(/\r\n?/g, '\n').replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+    if (Buffer.byteLength(normalized, 'utf8') <= bytes)
+        return normalized;
+    const room = bytes - Buffer.byteLength(CLIP_MARKER, 'utf8');
+    if (room <= 0)
+        return boundedDecisionText(normalized, bytes);
+    const head = boundedDecisionText(normalized, Math.ceil(room * 0.7));
+    const tailBudget = room - Buffer.byteLength(head, 'utf8');
+    const raw = Buffer.from(normalized, 'utf8');
+    let start = raw.length - tailBudget;
+    while (start < raw.length && (raw[start] & 0xc0) === 0x80)
+        start++;
+    return head + CLIP_MARKER + raw.subarray(start).toString('utf8');
+}
+/**
+ * The text "does the task ask for checks" is judged on: the task (a confirmed handoff's instruction
+ * when there is one) and the node's own instruction, which can require checks the user never named.
+ * Each part is clipped on its own so a long task cannot crowd the instruction out.
+ */
+export function factTaskText(task, nodeInstruction) {
+    if (!nodeInstruction?.trim())
+        return clipFactText(task, FACT_LIMITS.task);
+    return `${clipFactText(task, 1900)}\n\nNode instruction (also part of the task):\n${clipFactText(nodeInstruction, 1000)}`;
+}
+/** Validate an answer at the provider boundary: a probability in [0, 1] or nothing. */
+export function factProbability(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1)
+        throw new Error('invalid_response');
+    return value;
+}

package/dist/src/decision/guidancePolicy.d.ts

@@ -0,0 +1,3 @@
+import type { DecisionBatch } from './types.js';
+export declare function markFactGuidance(batch: DecisionBatch): DecisionBatch;
+export declare function hasFactGuidance(batch: DecisionBatch): boolean;

package/dist/src/decision/guidancePolicy.js

@@ -0,0 +1,10 @@
+/** Runtime-owned metadata, never a provider answer or part of the wire/telemetry payload. */
+const FACT_GUIDANCE = Symbol('fact-guidance');
+export function markFactGuidance(batch) {
+    const marked = { ...batch };
+    Object.defineProperty(marked, FACT_GUIDANCE, { value: true });
+    return marked;
+}
+export function hasFactGuidance(batch) {
+    return batch[FACT_GUIDANCE] === true;
+}

package/dist/src/decision/hostedPolicy.d.ts

@@ -0,0 +1,14 @@
+import type { Membership } from '../membership.js';
+import { DecisionManager } from './DecisionManager.js';
+import type { DecisionConfig } from './types.js';
+/**
+ * The decision service a run may use. Every service, the hosted one and a local one this
+ * installation configured, needs a signed-in account, and the installation-wide switch stays
+ * authoritative over either.
+ */
+export declare function resolveDecisionConfig(membership: Membership, enabled?: boolean, decisions?: DecisionConfig): DecisionConfig;
+/** CLI policy: account entitlement is fetched from the hosted service for each run. */
+export declare function hostedDecisionPolicy(membership: Membership, enabled?: boolean, decisions?: DecisionConfig): {
+    decisionManager: DecisionManager;
+    decisionNodeOptIn: boolean;
+};

package/dist/src/decision/hostedPolicy.js

@@ -0,0 +1,21 @@
+import { DecisionManager } from './DecisionManager.js';
+/**
+ * The decision service a run may use. Every service, the hosted one and a local one this
+ * installation configured, needs a signed-in account, and the installation-wide switch stays
+ * authoritative over either.
+ */
+export function resolveDecisionConfig(membership, enabled = true, decisions) {
+    if (!enabled || !membership.subject)
+        return { provider: 'none', mode: 'off' };
+    if (decisions && decisions.provider !== 'andorra')
+        return decisions;
+    return { ...decisions, provider: 'andorra', mode: decisions?.mode ?? 'active', requestTimeoutMs: decisions?.requestTimeoutMs ?? 15000 };
+}
+/** CLI policy: account entitlement is fetched from the hosted service for each run. */
+export function hostedDecisionPolicy(membership, enabled = true, decisions) {
+    return {
+        decisionManager: new DecisionManager({ config: resolveDecisionConfig(membership, enabled, decisions) }),
+        // Only Agent nodes that turn Jev on receive the run's decision service.
+        decisionNodeOptIn: true,
+    };
+}

package/dist/src/decision/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './DecisionEngine.js';
+export * from './DecisionManager.js';
+export * from './DecisionPolicy.js';
+export * from './facts.js';
+export * from './providers/NoOpDecisionProvider.js';

package/dist/src/decision/index.js

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './DecisionEngine.js';
+export * from './DecisionManager.js';
+export * from './DecisionPolicy.js';
+export * from './facts.js';
+export * from './providers/NoOpDecisionProvider.js';

package/dist/src/decision/optimizationPolicy.d.ts

@@ -0,0 +1,26 @@
+/** Host-only optimization eligibility. These predicates never authorize a tool. */
+export declare function answerOnlyTask(task: string): boolean;
+export interface PreflightConsumers {
+    /** Must reflect available, unpinned, configured alternatives for this attempt. */
+    adaptiveRouting?: boolean;
+    answerOnly?: boolean;
+}
+export declare function actionablePreflightQuestion(id: string, facts: boolean, consumers: PreflightConsumers | undefined, availability: {
+    codeGraphAvailable: boolean;
+    memoryAvailable: boolean;
+}, roles: readonly string[]): boolean;
+/** No semantic classification unless a different, configured model can actually be selected. */
+export declare function hasAdaptiveAlternative(routing: {
+    enabled?: boolean;
+    tiers?: Record<string, {
+        provider: string;
+        model?: string;
+    } | undefined>;
+}, baseline: {
+    provider: string;
+    model: string;
+}, configured: readonly {
+    id: string;
+    model?: string;
+    models?: readonly string[];
+}[]): boolean;

package/dist/src/decision/optimizationPolicy.js

@@ -0,0 +1,38 @@
+/** Host-only optimization eligibility. These predicates never authorize a tool. */
+export function answerOnlyTask(task) {
+    // Only explicit constraints, not a learned classifier or guessed task complexity.
+    return /\b(?:do not|don't|never)\s+(?:use|call|invoke|run)\s+(?:any\s+)?tools?\b|\bwithout\s+(?:using\s+)?(?:any\s+)?tools?\b|\bno\s+tool\s+calls?\b/i.test(task);
+}
+export function actionablePreflightQuestion(id, facts, consumers, availability, roles) {
+    if (consumers?.answerOnly)
+        return false;
+    if (id === 'needs_codegraph')
+        return availability.codeGraphAvailable;
+    if (id === 'needs_memory')
+        return availability.memoryAvailable;
+    if (!facts)
+        return true; // Keep explicitly selected legacy questions mode compatible.
+    if (id.startsWith('tool_family_') || ['needs_external_docs', 'verification_tier'].includes(id))
+        return false;
+    if (['task_complexity', 'security_sensitive', 'architecture_affecting'].includes(id))
+        return consumers?.adaptiveRouting === true;
+    if (id === 'needs_delegation' || id === 'delegation_role')
+        return roles.length > 0;
+    return true;
+}
+/** No semantic classification unless a different, configured model can actually be selected. */
+export function hasAdaptiveAlternative(routing, baseline, configured) {
+    if (!routing.enabled || !routing.tiers)
+        return false;
+    return Object.values(routing.tiers).some(target => {
+        if (!target)
+            return false;
+        const provider = configured.find(item => item.id === target.provider);
+        const model = target.model ?? provider?.model;
+        if (!provider || !model)
+            return false;
+        if (target.model !== undefined && provider.models?.length && !provider.models.includes(model) && provider.model !== model)
+            return false;
+        return provider.id !== baseline.provider || model !== baseline.model;
+    });
+}