@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/grep-regex-worker.d.ts

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

package/dist/src/grep-regex-worker.js

@@ -0,0 +1,20 @@
+import { parentPort, workerData } from 'node:worker_threads';
+// Only evaluate supplied strings. File discovery, reads and permissions remain
+// on the caller; this worker never receives paths or launches host helpers.
+try {
+    const regex = new RegExp(workerData.pattern, workerData.flags);
+    parentPort.on('message', ({ lines, count }) => {
+        const matches = [];
+        for (let index = 0; index < lines.length; index++) {
+            regex.lastIndex = 0;
+            if (regex.test(lines[index])) {
+                matches.push({ index, count: count ? (lines[index].match(regex)?.length ?? 0) : 1 });
+            }
+        }
+        parentPort.postMessage({ matches });
+    });
+    parentPort.postMessage({ ready: true });
+}
+catch (error) {
+    parentPort.postMessage({ error: `Invalid Grep regular expression: ${error instanceof Error ? error.message : 'invalid pattern'}` });
+}

package/dist/src/grep-regex.d.ts

@@ -0,0 +1,11 @@
+type Match = {
+    index: number;
+    count: number;
+};
+type Scan = (lines: string[], count: boolean) => Promise<Match[]>;
+/** A search has one worker and a five-second total budget, including startup.
+ * Termination can interrupt backtracking; an AbortSignal alone cannot do that
+ * when RegExp runs on the caller's event loop. Always await worker cleanup.
+ */
+export declare function withGrepRegex<T>(pattern: string, flags: string, signal: AbortSignal, run: (scan: Scan, searchSignal: AbortSignal) => Promise<T>): Promise<T>;
+export {};

package/dist/src/grep-regex.js

@@ -0,0 +1,64 @@
+import { Worker } from 'node:worker_threads';
+/** A search has one worker and a five-second total budget, including startup.
+ * Termination can interrupt backtracking; an AbortSignal alone cannot do that
+ * when RegExp runs on the caller's event loop. Always await worker cleanup.
+ */
+export async function withGrepRegex(pattern, flags, signal, run) {
+    signal.throwIfAborted();
+    const search = new AbortController();
+    let rejectSearch;
+    const stopped = new Promise((_, reject) => { rejectSearch = reject; });
+    // Startup can fail before the operation race is installed.
+    void stopped.catch(() => { });
+    const worker = new Worker(new URL('./grep-regex-worker.js', import.meta.url), {
+        workerData: { pattern, flags }, execArgv: [],
+        resourceLimits: { maxOldGenerationSizeMb: 32, maxYoungGenerationSizeMb: 8 },
+    });
+    let failure;
+    let pending;
+    let termination;
+    const stop = (error) => {
+        failure ??= error;
+        search.abort(failure);
+        rejectSearch(failure);
+        pending?.reject(failure);
+        pending = undefined;
+        termination ??= worker.terminate();
+    };
+    const abort = () => stop(signal.reason instanceof Error ? signal.reason : new Error('Grep cancelled'));
+    const timer = setTimeout(() => stop(new Error('Grep regular expression exceeded the 5-second search budget; narrow the path or simplify the pattern.')), 5_000);
+    signal.addEventListener('abort', abort, { once: true });
+    worker.on('error', stop);
+    worker.on('exit', code => stop(new Error(`Grep regular expression worker exited (${code})`)));
+    worker.on('message', (message) => {
+        if (message.error) {
+            stop(new Error(message.error));
+            return;
+        }
+        const current = pending;
+        pending = undefined;
+        current?.resolve(message.matches ?? []);
+    });
+    try {
+        // Worker messages cannot be delivered until this synchronous setup finishes.
+        await new Promise((resolve, reject) => { pending = { resolve, reject }; });
+        const result = await Promise.race([stopped, run((lines, count) => {
+                if (failure)
+                    return Promise.reject(failure);
+                signal.throwIfAborted();
+                return new Promise((resolve, reject) => {
+                    pending = { resolve, reject };
+                    worker.postMessage({ lines, count });
+                });
+            }, search.signal)]);
+        if (failure)
+            throw failure;
+        return result;
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', abort);
+        termination ??= worker.terminate();
+        await termination;
+    }
+}

package/dist/src/handoffs.d.ts

@@ -0,0 +1,34 @@
+import type { Graph, GraphNode } from './graphs.js';
+export interface JsonSchema {
+    type: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    additionalProperties?: boolean;
+    format?: 'artifact';
+}
+/** The model's output contract remains per-copy; routes consume the aggregate. */
+export declare function nodeOutputSchema(node: GraphNode): JsonSchema | undefined;
+export type ValueExpression = string | {
+    constant: unknown;
+};
+export interface ValueScope {
+    source?: {
+        output?: unknown;
+        artifacts?: unknown;
+    };
+    run: {
+        input: Record<string, unknown>;
+        state: Record<string, unknown>;
+        loop?: {
+            iteration: number;
+        };
+    };
+}
+/** Inspect raw constants before structuredClone can normalize their object shapes. */
+export declare function validateMappingConstants(graph: unknown): void;
+export declare function validateSchema(schema: unknown, path?: string, depth?: number): asserts schema is JsonSchema;
+export declare function validateValue(schema: JsonSchema, value: unknown, path?: string): void;
+export declare function resolveValue(expression: ValueExpression, scope: ValueScope): unknown;
+export declare function schemaAt(schema: JsonSchema | undefined, keys: string[], label: string, requirePresent?: boolean): JsonSchema | undefined;
+export declare function validateMappings(graph: Graph): void;

package/dist/src/handoffs.js

@@ -0,0 +1,229 @@
+/** The model's output contract remains per-copy; routes consume the aggregate. */
+export function nodeOutputSchema(node) {
+    if (node.modifiers?.parallel?.mode !== 'copies')
+        return node.outputSchema;
+    return { type: 'object', properties: { results: { type: 'array', items: { type: 'object', properties: {
+                        outcome: { type: 'string' }, summary: { type: 'string' }, tests: { type: 'array', items: { type: 'string' } },
+                        ...(node.outputSchema ? { output: node.outputSchema } : {}),
+                    }, required: ['outcome', 'summary', 'tests', 'output'] } } }, required: ['results'] };
+}
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+function schemaProperties(schema) {
+    return { ...(schema.format === 'artifact' ? { type: { type: 'string' }, ref: { type: 'string' } } : {}), ...schema.properties };
+}
+/** Constants must survive JSON persistence without losing or changing values. */
+function validateJsonConstant(value, path, ancestors = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value))
+        return;
+    const invalid = () => new Error(`${path}: constant must contain only JSON values (finite numbers, strings, booleans, null, arrays and plain objects)`);
+    if (typeof value !== 'object' || ancestors.has(value))
+        throw invalid();
+    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+        throw invalid();
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+        if (Reflect.ownKeys(value).length !== value.length + 1)
+            throw invalid();
+        for (let i = 0; i < value.length; i++) {
+            const property = Object.getOwnPropertyDescriptor(value, String(i));
+            if (!property || !('value' in property) || !property.enumerable)
+                throw invalid();
+            validateJsonConstant(property.value, `${path}[${i}]`, ancestors);
+        }
+    }
+    else
+        for (const key of Reflect.ownKeys(value)) {
+            const property = Object.getOwnPropertyDescriptor(value, key);
+            if (typeof key !== 'string' || !property.enumerable || !('value' in property))
+                throw invalid();
+            validateJsonConstant(property.value, `${path}.${key}`, ancestors);
+        }
+    ancestors.delete(value);
+}
+/** Inspect raw constants before structuredClone can normalize their object shapes. */
+export function validateMappingConstants(graph) {
+    if (!object(graph))
+        return;
+    const check = (mapping, path) => {
+        if (!object(mapping))
+            return;
+        for (const [key, expression] of Object.entries(mapping))
+            if (object(expression) && Object.hasOwn(expression, 'constant')) {
+                const property = Object.getOwnPropertyDescriptor(expression, 'constant');
+                if (!('value' in property))
+                    throw new Error(`${path}.${key}: constant must contain only JSON values; accessors are unsupported`);
+                validateJsonConstant(property.value, `${path}.${key}`);
+            }
+    };
+    if (object(graph.nodes))
+        for (const [id, node] of Object.entries(graph.nodes))
+            if (object(node))
+                check(node.inputs, `node ${id} input`);
+    if (Array.isArray(graph.edges))
+        for (const [index, edge] of graph.edges.entries())
+            if (object(edge))
+                check(edge.inputMapping, `edge ${index} input`);
+}
+export function validateSchema(schema, path = 'schema', depth = 0) {
+    if (depth > 20 || !object(schema) || !['object', 'array', 'string', 'number', 'integer', 'boolean', 'null'].includes(schema.type))
+        throw new Error(`${path}: use a supported JSON Schema type (maximum depth 20)`);
+    if (Object.keys(schema).some(k => !['type', 'properties', 'required', 'items', 'additionalProperties', 'format'].includes(k)))
+        throw new Error(`${path}: unsupported schema keyword`);
+    if (schema.format !== undefined && (schema.format !== 'artifact' || schema.type !== 'object'))
+        throw new Error(`${path}: only artifact format is supported`);
+    if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== 'boolean')
+        throw new Error(`${path}: additionalProperties must be boolean`);
+    if (schema.properties !== undefined) {
+        if (schema.type !== 'object' || !object(schema.properties))
+            throw new Error(`${path}: properties requires an object schema`);
+        for (const [key, s] of Object.entries(schema.properties)) {
+            if (['__proto__', 'constructor', 'prototype'].includes(key))
+                throw new Error(`${path}: unsafe property name`);
+            validateSchema(s, `${path}.${key}`, depth + 1);
+        }
+    }
+    if (schema.format === 'artifact' && ['type', 'ref'].some(key => schema.properties && schema.properties[key] && schema.properties[key].type !== 'string'))
+        throw new Error(`${path}: artifact type and ref properties must be strings`);
+    if (schema.required !== undefined && (!Array.isArray(schema.required) || schema.required.some(k => typeof k !== 'string' || !Object.hasOwn(schema.properties ?? {}, k)) || new Set(schema.required).size !== schema.required.length))
+        throw new Error(`${path}: required must list unique declared properties`);
+    if (schema.items !== undefined) {
+        if (schema.type !== 'array')
+            throw new Error(`${path}: items requires an array schema`);
+        validateSchema(schema.items, `${path}.items`, depth + 1);
+    }
+}
+export function validateValue(schema, value, path = 'value') {
+    const valid = schema.type === 'null' ? value === null : schema.type === 'array' ? Array.isArray(value) : schema.type === 'object' ? object(value) : schema.type === 'integer' ? Number.isSafeInteger(value) : schema.type === 'number' ? typeof value === 'number' && Number.isFinite(value) : typeof value === schema.type;
+    if (!valid)
+        throw new Error(`${path}: expected ${schema.type}`);
+    if (schema.format === 'artifact' && (!object(value) || typeof value.type !== 'string' || typeof value.ref !== 'string' || !/^artifact:\/\/[^/]+\/[^/]+$/.test(value.ref)))
+        throw new Error(`${path}: expected an artifact reference object with type and artifact:// ref`);
+    if (schema.type === 'object') {
+        const v = value;
+        for (const key of schema.required ?? [])
+            if (!Object.hasOwn(v, key))
+                throw new Error(`${path}.${key}: required input is missing; configure an explicit mapping`);
+        for (const [key, item] of Object.entries(v)) {
+            const p = schemaProperties(schema)[key];
+            if (p)
+                validateValue(p, item, `${path}.${key}`);
+            else if (schema.additionalProperties === false)
+                throw new Error(`${path}.${key}: undeclared property`);
+        }
+    }
+    if (schema.type === 'array' && schema.items)
+        for (const [i, item] of value.entries())
+            validateValue(schema.items, item, `${path}[${i}]`);
+}
+export function resolveValue(expression, scope) {
+    if (object(expression) && Object.keys(expression).length === 1 && Object.hasOwn(expression, 'constant'))
+        return structuredClone(expression.constant);
+    if (typeof expression !== 'string' || !/^\$(source\.(output|artifacts)|run\.(input|state|loop))(\.[a-zA-Z0-9_-]+)*$/.test(expression))
+        throw new Error('Invalid input expression: use $source.output.field, $source.artifacts, $run.input.field, $run.state.field, $run.loop.iteration or {constant: value}');
+    let value = scope;
+    for (const key of expression.slice(1).split('.')) {
+        if (['__proto__', 'constructor', 'prototype'].includes(key) || (!object(value) && !Array.isArray(value)) || !Object.hasOwn(value, key))
+            throw new Error(`Input mapping ${expression}: referenced value is missing`);
+        value = value[key];
+    }
+    return structuredClone(value);
+}
+export function schemaAt(schema, keys, label, requirePresent = false) {
+    let current = schema;
+    for (const key of keys) {
+        if (!current)
+            return undefined;
+        if (current.type === 'array' && /^\d+$/.test(key)) {
+            if (requirePresent)
+                throw new Error(`${label}: array element is not guaranteed; use a guaranteed field or make the destination input optional`);
+            current = current.items;
+        }
+        else {
+            if (current.type !== 'object')
+                throw new Error(`${label}: cannot select field ${key} from ${current.type}`);
+            const next = schemaProperties(current)[key];
+            if (requirePresent && next && !current.required?.includes(key) && !(current.format === 'artifact' && ['type', 'ref'].includes(key)))
+                throw new Error(`${label}: source field ${key} is optional; require it in the source schema or make the destination input optional`);
+            if (!next && current.additionalProperties === false)
+                throw new Error(`${label}: nonexistent declared output/input field ${key}; correct the mapping`);
+            current = next;
+        }
+    }
+    return current;
+}
+/** Reject statically known incompatible values while leaving open/unknown fields to runtime validation. */
+function assertAssignable(source, destination, path) {
+    if (source.type !== destination.type && !(source.type === 'integer' && destination.type === 'number'))
+        throw new Error(`${path}: mapping type ${source.type} does not match ${destination.type}`);
+    if (destination.format === 'artifact' && source.format !== 'artifact')
+        throw new Error(`${path}: artifact destination requires a source schema with format: artifact; declare the artifact contract on the source`);
+    if (source.type === 'array' && destination.type === 'array' && source.items && destination.items)
+        assertAssignable(source.items, destination.items, `${path}[]`);
+    if (source.type !== 'object' || destination.type !== 'object')
+        return;
+    const sourceProperties = schemaProperties(source);
+    const destinationProperties = schemaProperties(destination);
+    const required = new Set([...(destination.required ?? []), ...(destination.format === 'artifact' ? ['type', 'ref'] : [])]);
+    const sourceRequired = new Set([...(source.required ?? []), ...(source.format === 'artifact' ? ['type', 'ref'] : [])]);
+    for (const key of required)
+        if (!sourceRequired.has(key) && (Object.hasOwn(sourceProperties, key) || source.additionalProperties === false))
+            throw new Error(`${path}.${key}: mapping source cannot guarantee required destination property; add it to source properties and required`);
+    for (const [key, schema] of Object.entries(sourceProperties)) {
+        const target = destinationProperties[key];
+        if (target)
+            assertAssignable(schema, target, `${path}.${key}`);
+        else if (destination.additionalProperties === false)
+            throw new Error(`${path}.${key}: declared source property is not allowed by the destination schema; remove it or allow it in the destination`);
+    }
+}
+export function validateMappings(graph) {
+    const check = (mapping, source, target) => {
+        if (mapping === undefined)
+            return;
+        if (!object(mapping))
+            throw new Error(`node ${target}: input mapping must be an object`);
+        for (const [key, expression] of Object.entries(mapping)) {
+            if (['__proto__', 'constructor', 'prototype'].includes(key))
+                throw new Error(`node ${target}: unsafe input mapping key`);
+            const destination = graph.nodes[target].inputSchema?.properties?.[key];
+            if (!destination && graph.nodes[target].inputSchema?.additionalProperties === false)
+                throw new Error(`node ${target}: mapping targets undeclared input ${key}`);
+            if (object(expression) && Object.keys(expression).length === 1 && Object.hasOwn(expression, 'constant')) {
+                validateJsonConstant(expression.constant, `node ${target} input ${key}`);
+                if (destination)
+                    validateValue(destination, expression.constant, `node ${target} input ${key}`);
+                continue;
+            }
+            if (typeof expression !== 'string' || !/^\$(source\.(output|artifacts)|run\.(input|state|loop))(\.[a-zA-Z0-9_-]+)*$/.test(expression))
+                throw new Error(`node ${target}: invalid input mapping; use an explicit $source/$run reference or {constant: value}`);
+            const parts = expression.slice(1).split('.');
+            const schema = parts[0] === 'source' ? parts[1] === 'output' ? source ? nodeOutputSchema(graph.nodes[source]) : undefined : { type: 'array' } : parts[1] === 'input' ? graph.inputSchema ? { ...graph.inputSchema, required: [...(graph.inputSchema.required ?? []), 'task'] } : undefined : parts[1] === 'state' ? graph.stateSchema : { type: 'object', properties: { iteration: { type: 'integer' } }, required: ['iteration'] };
+            if (parts[0] === 'source' && !source)
+                throw new Error(`node ${target}: $source is only available on edge mappings; use $run for node inputs`);
+            const selected = schemaAt(schema, parts.slice(2), `node ${target} mapping ${expression}`, graph.nodes[target].inputSchema?.required?.includes(key));
+            if (selected && destination)
+                assertAssignable(selected, destination, `node ${target} input ${key}`);
+        }
+    };
+    for (const node of Object.values(graph.nodes))
+        check(node.inputs, undefined, node.id);
+    for (const edge of graph.edges)
+        check(edge.inputMapping, edge.source, edge.target);
+    for (const node of Object.values(graph.nodes)) {
+        const incoming = graph.edges.filter(e => e.target === node.id);
+        const required = node.inputSchema?.required ?? [];
+        for (const key of required) {
+            if (Object.hasOwn(node.inputs ?? {}, key))
+                continue;
+            if (node.id === graph.entry)
+                throw new Error(`node ${node.id}: required input ${key} has no entry mapping; add it to node inputs for the initial visit`);
+            const bootstrap = incoming.filter(edge => edge.bootstrap);
+            if (bootstrap.some(edge => !Object.hasOwn(edge.inputMapping ?? {}, key)))
+                throw new Error(`node ${node.id}: bootstrap must provide required input ${key} independently; map it on the intake edge or node inputs`);
+            const regular = incoming.filter(edge => !edge.bootstrap);
+            const has = node.type === 'join' && node.join?.mode === 'all' ? regular.some(e => Object.hasOwn(e.inputMapping ?? {}, key)) : incoming.length > 0 && incoming.every(e => Object.hasOwn(e.inputMapping ?? {}, key));
+            if (!has)
+                throw new Error(`node ${node.id}: required input ${key} has no mapping; add it to every incoming edge or node inputs`);
+        }
+    }
+}

package/dist/src/hardened-runtime.d.ts

@@ -0,0 +1,14 @@
+import { type HardenedRunOptions } from './react-runtime.js';
+import type { RunResult } from './runtime.js';
+export type { HardenedRunOptions, ToolExecutionMode, BeforeToolCallContext, BeforeToolCallResult, AfterToolCallContext, AfterToolCallResult } from './react-runtime.js';
+/**
+ * Facts select concrete continuations at the coding-adapter boundary; the one React engine still
+ * validates and executes every call, hook, approval, budget and completion contract. A synthetic
+ * continuation returns requests: 0 and never invokes the actual coding adapter or its onRequest.
+ * Questions mode retains its existing implementation in the same engine.
+ */
+export declare class AndorraAgentEngine {
+    execute(options: HardenedRunOptions): Promise<RunResult>;
+}
+export { AndorraAgentEngine as HardenedReActAgentExecutor };
+export declare function createAgentEngine(): AndorraAgentEngine;

package/dist/src/hardened-runtime.js

@@ -0,0 +1,264 @@
+import { randomUUID } from 'node:crypto';
+import { applyToolMenu } from './decision/applyToolMenu.js';
+import { answerOnlyTask } from './decision/optimizationPolicy.js';
+import { AndorraAgentEngine as ReactEngine } from './react-runtime.js';
+import { completionTool } from './completion.js';
+import { TodoStore } from './todos.js';
+import { retrySafe } from './decision/PreparedSteps.js';
+import { toolFamily } from './decision/toolFamilies.js';
+import { redactSecrets } from './memory/redaction.js';
+import { factTaskText } from './decision/facts.js';
+import { isVerificationCheck } from './decision/checks.js';
+import { FactContinuations, FACT_CONTINUATION_GUIDANCE, PREPARE_FINISH, taskConstraints, localCheckResult, prepareFinishArguments, prepareFinishDescription } from './decision/FactContinuations.js';
+import { bypassGeneration } from './decision/ContinuationAdapter.js';
+/**
+ * Facts select concrete continuations at the coding-adapter boundary; the one React engine still
+ * validates and executes every call, hook, approval, budget and completion contract. A synthetic
+ * continuation returns requests: 0 and never invokes the actual coding adapter or its onRequest.
+ * Questions mode retains its existing implementation in the same engine.
+ */
+export class AndorraAgentEngine {
+    async execute(options) {
+        const runId = options.runId ?? randomUUID();
+        options = await applyToolMenu({ ...options, runId });
+        const manager = options.decisionManager;
+        const answerOnly = answerOnlyTask(options.decisionTask ?? options.task);
+        const localEnabled = options.efficiency?.deterministicContinuations ?? (manager?.factsEnabled === true);
+        const remoteFactsEnabled = manager?.factsEnabled === true && options.efficiency?.jevFactInterpretation !== false;
+        if (!localEnabled || answerOnly)
+            return new ReactEngine().execute({ ...options,
+                // An explicit opt-out must not reactivate the older facts policy in the underlying engine.
+                decisionManager: answerOnly || manager?.factsEnabled ? undefined : manager });
+        const nodeId = options.nodeId ?? 'engineer';
+        const todoStore = options.todoStore ?? new TodoStore();
+        let invocationId = '';
+        let activeSignal = options.context.signal;
+        let calls = [];
+        let automatic;
+        let acceptedAutomatic;
+        let liveProvider = options.provider, liveModel = options.model;
+        let task = options.decisionTask ?? options.task;
+        let steered = false;
+        // Opaque/signed continuation protocols cannot accept synthetic assistant turns without
+        // provider-specific replay support. Never strip signatures to manufacture a bypass.
+        let opaqueProtocol = ['anthropic', 'claude', 'codex'].includes(options.telemetryIdentity?.providerType ?? '');
+        let controlRevision = options.context.runControl?.revision ?? 0;
+        const observed = new Map();
+        const permission = () => JSON.stringify([options.context.yolo, options.context.permissions ?? null,
+            options.context.approvalMode ?? null, options.context.runControl?.permissions ?? null, options.context.runControl?.yolo ?? null]);
+        const permitted = [...options.tools, ...(options.recoverTools ?? [])].filter(t => t.providerVisible !== false && t.name !== PREPARE_FINISH);
+        const catalog = (name) => permitted.find(t => t.name === name);
+        const emit = async (type, data = {}) => {
+            await options.onEvent?.({ type, time: new Date().toISOString(), data: { runId, nodeId, invocationId,
+                    ...(options.subagentId ? { subagentId: options.subagentId } : {}), ...data } });
+        };
+        const router = new FactContinuations({
+            task, nodeInstruction: options.nodeInstruction, workspaceInstructions: options.instructions,
+            permission, remoteFactsEnabled, todos: () => todoStore.snapshot(),
+            catalog: name => { const t = catalog(name); return t ? { family: toolFamily(t), readOnly: retrySafe(t) } : undefined; },
+            fact: (input, signal) => !remoteFactsEnabled || !manager ? Promise.resolve(undefined) : manager.fact(input.id === 'task_needs_checks'
+                ? { ...input, state: { task: factTaskText(redactSecrets(task).text, options.nodeInstruction ? redactSecrets(options.nodeInstruction).text : undefined) } }
+                : input, { runId, nodeId, invocationId }, signal, options.onEvent),
+            emit,
+        });
+        // The shell the model actually has, for the description's example and bare-command repair.
+        const shell = permitted.find(t => t.exitZeroOnReturn)?.name ?? catalog('shell')?.name;
+        const prepareFinish = {
+            name: PREPARE_FINISH, executionMode: 'sequential',
+            description: prepareFinishDescription(shell),
+            prepareArguments: args => prepareFinishArguments(args, { has: name => !!catalog(name), shell }),
+            parameters: { type: 'object', properties: {
+                    checks: { type: 'array', maxItems: 8, items: { type: 'object', properties: { name: { type: 'string' }, arguments: { type: 'object' } }, required: ['name', 'arguments'], additionalProperties: false } },
+                    completion: completionTool(options).parameters,
+                    verificationTodoIds: { type: 'array', maxItems: 32, items: { type: 'string' }, description: 'Existing verification-only todo ids to complete after every declared check passes; never implementation items.' },
+                }, required: ['checks', 'completion'], additionalProperties: false },
+            execute: async (args, context) => {
+                context.signal.throwIfAborted();
+                router.stage(args, calls.at(-1)?.name === PREPARE_FINISH && calls.filter(c => c.name === PREPARE_FINISH).length === 1);
+                return 'Finish plan prepared, not completed. Required checks and normal completion validation still have to succeed.';
+            },
+        };
+        const wrapAdapter = (adapter) => ({
+            ...(adapter.listModels ? { listModels: adapter.listModels.bind(adapter) } : {}),
+            generate: bypassGeneration(async (request) => {
+                if (!request.tools.some(t => t.name === 'complete_agent'))
+                    return adapter.generate(request);
+                const finishing = !steered && !opaqueProtocol && router.finishing;
+                if (steered || opaqueProtocol)
+                    request = { ...request, tools: request.tools.filter(t => t.name !== PREPARE_FINISH) };
+                router.modelResumed();
+                const response = await adapter.generate(finishing ? {
+                    ...request,
+                    // Keep schemas stable for prefix caching. This is guidance, not a claimed bypass.
+                    messages: [...request.messages, { role: 'user', content: 'Runtime: the recorded required checks passed on the current workspace and no todo is open. Complete now using complete_agent; reopen a todo only for genuinely unfinished required work. Do not add discretionary QA.' }],
+                    mutableTail: (request.mutableTail ?? 0) + 1,
+                } : request);
+                calls = response.toolCalls;
+                return response;
+            }, async (request) => {
+                // Auxiliary summaries and explicitly configured goal verifiers are never replaced.
+                if (!request.tools.some(t => t.name === 'complete_agent'))
+                    return undefined;
+                request.signal.throwIfAborted();
+                if (request.messages.some(message => message.providerContinuation))
+                    opaqueProtocol = true;
+                if (opaqueProtocol) {
+                    automatic = undefined;
+                    router.invalidate('opaque_provider_protocol');
+                    return undefined;
+                }
+                activeSignal = request.signal;
+                invocationId = request.context?.invocationId ?? invocationId;
+                observed.clear();
+                automatic = router.take(new Set(request.tools.map(t => t.name)));
+                if (!automatic)
+                    return undefined;
+                const next = automatic;
+                await emit('efficiency.facts.action', { action: next.kind });
+                await emit('efficiency.prepared.selected', { reason: 'fact_selected', kind: next.kind, evidenceSource: next.evidenceSource });
+                request.signal.throwIfAborted();
+                const response = next.completion
+                    ? { text: JSON.stringify(next.completion), toolCalls: [], usage: { requests: 0 } }
+                    : { text: '', toolCalls: [{ id: next.id, name: next.tool.name, arguments: JSON.stringify(next.tool.arguments) }], usage: { requests: 0 } };
+                calls = response.toolCalls;
+                return response;
+            }),
+        });
+        const onEvent = async (event) => {
+            const d = event.data;
+            if (d.nodeId === nodeId && (d.subagentId ?? undefined) === options.subagentId && typeof d.invocationId === 'string')
+                invocationId ||= d.invocationId;
+            const ours = d.nodeId === nodeId && (!d.invocationId || d.invocationId === invocationId)
+                && (d.subagentId ?? undefined) === options.subagentId;
+            if (ours && event.type === 'agent.messages.injected') {
+                steered = true;
+                automatic = undefined;
+                acceptedAutomatic = undefined;
+                const control = options.context.runControl;
+                const directions = control?.messagesSince(controlRevision) ?? [];
+                if (control)
+                    controlRevision = control.revision;
+                const update = directions.join('\n');
+                if (update)
+                    task += `\nLatest task update:\n${update}`;
+                router.invalidate('steering', update || undefined);
+            }
+            if (ours && event.type === 'agent.model.changed')
+                router.invalidate('model_changed');
+            if (ours && event.type === 'agent.completion.rejected') {
+                router.invalidate('completion_rejected');
+                automatic = undefined;
+            }
+            if (ours && event.type === 'agent.completion.accepted' && automatic?.kind === 'complete') {
+                acceptedAutomatic = automatic;
+                router.completionAccepted();
+            }
+            if (ours && ['node.tool.completed', 'node.tool.failed', 'node.tool.skipped'].includes(event.type) && typeof d.toolCallId === 'string' && !observed.has(d.toolCallId)) {
+                const call = calls.find(c => c.id === d.toolCallId);
+                if (call) {
+                    let args = {};
+                    try {
+                        args = JSON.parse(call.arguments);
+                    }
+                    catch { /* Invalid arguments stay unsuccessful. */ }
+                    const tool = catalog(call.name);
+                    observed.set(call.id, { call, args, output: typeof d.output === 'string' ? d.output : '',
+                        isError: event.type !== 'node.tool.completed', executionSucceeded: false,
+                        family: tool && toolFamily(tool), readOnly: retrySafe(tool) });
+                }
+            }
+            // Preserve lifecycle events for clients, but distinguish a logical automatic turn from
+            // actual inference. Provider request/token counters remain zero for the synthetic turn.
+            await options.onEvent?.(ours && event.type === 'agent.model.completed' && automatic
+                ? { ...event, data: { ...d, synthetic: true, source: 'fact_selected', evidenceSource: automatic.evidenceSource, modelRequests: 0 } } : event);
+            if (ours && event.type === 'agent.turn.completed' && Number(d.toolCalls) > 0) {
+                const batch = calls.map(c => observed.get(c.id)).filter((o) => o !== undefined);
+                if (automatic?.tool) {
+                    const outcome = batch.find(o => o.call.id === automatic.id);
+                    if (outcome?.executionSucceeded && !outcome.isError) {
+                        await emit('efficiency.prepared.executed', { kind: automatic.kind, succeeded: true });
+                        await emit('decision.turn_bypassed', { kind: automatic.kind, selection: 'fact_selected', evidenceSource: automatic.evidenceSource, accounting: 'observed_bypass_not_net_savings' });
+                    }
+                    else
+                        await emit('efficiency.prepared.rejected', { kind: automatic.kind, reason: 'execution_not_confirmed' });
+                }
+                if (!opaqueProtocol)
+                    await router.observe(batch, activeSignal);
+                observed.clear();
+            }
+        };
+        const wrapQueue = (poll) => poll && (async (signal) => {
+            const messages = await poll(signal);
+            if (messages.length) {
+                steered = true;
+                const update = messages.map(m => m.content).join('\n');
+                task += `\nLatest task update:\n${update}`;
+                router.invalidate('steering', update);
+            }
+            return messages;
+        });
+        await emit('decision.ready', { style: 'facts', policy: 'call-bypass-v2', localEnabled, remoteFactsEnabled });
+        const result = await new ReactEngine().execute({
+            ...options, runId, todoStore,
+            // Preflight already ran in agent-execution. Avoid the old facts policy running a second time.
+            decisionManager: undefined,
+            tools: [...options.tools.filter(t => t.name !== PREPARE_FINISH), prepareFinish],
+            recoverTools: options.recoverTools?.filter(t => t.name !== PREPARE_FINISH),
+            instructions: [options.instructions, FACT_CONTINUATION_GUIDANCE].filter(Boolean).join('\n'),
+            adapter: wrapAdapter(options.adapter), onEvent,
+            getSteeringMessages: wrapQueue(options.getSteeringMessages), getFollowUpMessages: wrapQueue(options.getFollowUpMessages),
+            getLiveModel: options.getLiveModel && (async (...args) => {
+                const next = await options.getLiveModel(...args);
+                if (!next)
+                    return undefined;
+                if (next.provider !== liveProvider || next.model !== liveModel) {
+                    router.invalidate('model_changed');
+                    liveProvider = next.provider;
+                    liveModel = next.model;
+                }
+                return { ...next, adapter: wrapAdapter(next.adapter) };
+            }),
+            beforeToolCall: async (call, signal) => {
+                if (automatic && automatic.permission !== permission())
+                    return { block: true, reason: 'Prepared continuation invalidated by changed permissions.' };
+                const constraints = taskConstraints(task, options.nodeInstruction);
+                if (automatic && ((constraints.noChecks && /^qa\.(?:fast|test|deep|security|browser)$/.test(call.tool.name))
+                    || (constraints.noTests && /^qa\.(?:fast|test|deep)$/.test(call.tool.name))))
+                    return { block: true, reason: 'The user explicitly excluded these checks.' };
+                return options.beforeToolCall?.(call, signal);
+            },
+            afterToolCall: async (call, signal) => {
+                const after = await options.afterToolCall?.(call, signal);
+                const output = after?.output ?? call.output;
+                // Respect existing privacy projections. Only bounded, redacted outputs can go to Jev.
+                const projected = !call.isError ? call.tool.eventOutput?.(output) ?? output : output;
+                const safe = redactSecrets(projected).text;
+                const clipped = output.length > 24_000 || /\[(?:output|Tool output) truncated|routing context clipped|output clipped/i.test(output);
+                const observation = { call: call.toolCall, args: call.args, output: safe,
+                    isError: after?.isError ?? call.isError, executionSucceeded: !call.isError,
+                    truncated: safe !== projected || projected !== output || clipped,
+                    family: toolFamily(call.tool), readOnly: retrySafe(call.tool) };
+                // Structured QA status is exact local evidence even when its privacy projection omits
+                // source details. Only the projected, redacted form may ever be sent to Jev.
+                if (isVerificationCheck(call.tool.name, observation.family, call.args)) {
+                    const exitCode = !observation.isError && call.tool.exitZeroOnReturn ? 0 : undefined;
+                    observation.localCheckStatus = localCheckResult({ ...observation, output, truncated: clipped, exitCode });
+                }
+                observed.set(call.toolCall.id, observation);
+                return after;
+            },
+            completionGuard: completion => {
+                if (automatic?.kind === 'complete' && automatic.permission !== permission())
+                    return 'Prepared completion invalidated by changed permissions.';
+                return options.completionGuard?.(completion);
+            },
+        });
+        // Count completion only when the normal engine actually accepted and returned success.
+        if (result.status === 'succeeded' && acceptedAutomatic) {
+            await emit('decision.turn_bypassed', { kind: 'complete', selection: 'fact_selected', evidenceSource: acceptedAutomatic.evidenceSource, accounting: 'observed_bypass_not_net_savings' });
+        }
+        return result;
+    }
+}
+export { AndorraAgentEngine as HardenedReActAgentExecutor };
+export function createAgentEngine() { return new AndorraAgentEngine(); }