@andorra-labs/code 0.0.0-stage → 0.1.5

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

@@ -0,0 +1,7 @@
+import type { Tool, ToolFamily } from '../types.js';
+import type { DecisionBatch } from './types.js';
+export declare function toolFamily(tool: Tool): ToolFamily | undefined;
+export declare function toolFamilies(tools: Tool[]): ToolFamily[];
+export declare function routeToolFamilies(tools: Tool[], decisions: DecisionBatch): Tool[];
+/** Questions retain their legacy guidance. Facts use runtime actions, not extra advisory work. */
+export declare function decisionExecutionGuidance(decisions: DecisionBatch, availableRoles: string[]): string;

package/dist/src/decision/toolFamilies.js

@@ -0,0 +1,55 @@
+import { DecisionPolicy } from './DecisionPolicy.js';
+import { hasFactGuidance } from './guidancePolicy.js';
+const families = { Read: 'filesystem-read', Glob: 'code-search', Grep: 'code-search', Write: 'filesystem-write', Edit: 'filesystem-write', Bash: 'shell', PowerShell: 'shell', NativeExec: 'shell', AsyncProcess: 'shell', PowerShellFast: 'shell', ShellMetrics: 'shell', read: 'filesystem-read', ls: 'filesystem-read', find: 'code-search', grep: 'code-search', write: 'filesystem-write', edit: 'filesystem-write', powershell: 'shell', bash: 'shell', read_file: 'filesystem-read', list_files: 'filesystem-read', write_file: 'filesystem-write', edit_file: 'filesystem-write', apply_patch: 'filesystem-write', search_files: 'code-search', repo_explore: 'codegraph', git_read: 'git', pull_request: 'git', shell: 'shell', memory_search: 'memory', spawn_subagent: 'subagents', read_artifact: 'artifact', write_artifact: 'artifact' };
+const protectedTools = new Set(['complete_agent', 'complete', 'complete_task', 'submit_completion', 'update_todos', 'ask_user', 'load_project_skill', 'restore_tools', 'prepare_steps', 'prepare_finish']);
+export function toolFamily(tool) { return tool.family ?? families[tool.name]; }
+export function toolFamilies(tools) { return [...new Set(tools.map(toolFamily).filter((family) => family !== undefined))]; }
+export function routeToolFamilies(tools, decisions) {
+    return tools.filter(tool => {
+        if (protectedTools.has(tool.name))
+            return true;
+        const family = toolFamily(tool);
+        if (!family)
+            return true;
+        if (DecisionPolicy.boolean(decisions, `tool_family_${family.replaceAll('-', '_')}`) === false)
+            return false;
+        if (family === 'web' && DecisionPolicy.boolean(decisions, 'needs_external_docs') === false)
+            return false;
+        if (family === 'subagents' && DecisionPolicy.boolean(decisions, 'needs_delegation') === false)
+            return false;
+        return true;
+    });
+}
+/** Questions retain their legacy guidance. Facts use runtime actions, not extra advisory work. */
+export function decisionExecutionGuidance(decisions, availableRoles) {
+    if (hasFactGuidance(decisions))
+        return '';
+    const directives = [];
+    const docs = DecisionPolicy.boolean(decisions, 'needs_external_docs');
+    if (docs === true)
+        directives.push('Consult relevant primary external documentation using permitted web/browser tools when available before relying on unstable facts.');
+    const delegation = DecisionPolicy.boolean(decisions, 'needs_delegation');
+    const role = DecisionPolicy.choice(decisions, 'delegation_role');
+    if (delegation === true && role && role !== 'none' && availableRoles.includes(role))
+        directives.push(`For an independent bounded subtask, prefer the configured delegation role ${JSON.stringify(role)} when delegation is useful. Do not create arbitrary roles or bypass delegation limits.`);
+    else if (delegation === false || role === 'none')
+        directives.push('Prefer completing this task in the current agent; delegate only if later evidence or user instructions require it.');
+    const risk = DecisionPolicy.boolean(decisions, 'security_sensitive') === true || DecisionPolicy.boolean(decisions, 'architecture_affecting') === true;
+    const complexity = DecisionPolicy.score(decisions, 'task_complexity');
+    const tier = risk || (complexity !== undefined && complexity >= .8) ? 'full-tests' : DecisionPolicy.choice(decisions, 'verification_tier');
+    const verification = {
+        none: 'No additional discretionary verification was selected. Still execute every check required by the task, workspace instructions, and graph completion contract.',
+        targeted: 'Run focused tests that exercise the behavior changed by this task and report their results.',
+        lint: 'Run the applicable lint and static checks and report their results.',
+        'targeted+lint': 'Run focused tests for the changed behavior plus applicable lint/static checks and report their results.',
+        build: 'Build the affected application/package and report the build result, in addition to required targeted checks.',
+        'full-tests': 'Run the affected full test suite, build, and applicable static checks. Investigate failures and report remaining gaps explicitly.',
+    };
+    if (tier && Object.hasOwn(verification, tier))
+        directives.push(verification[tier]);
+    if (risk)
+        directives.push('Treat this task as security-sensitive or architecture-affecting: inspect trust boundaries, compatibility, and failure paths; preserve approvals and capability restrictions.');
+    if (complexity !== undefined && complexity >= .8)
+        directives.push('Break this complex task into explicit milestones and verify integration between changed components.');
+    return directives.length ? `Runtime decision guidance (never overrides explicit user instructions, workspace/graph requirements, capabilities, or approvals):\n${directives.join('\n')}` : '';
+}

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

@@ -0,0 +1,35 @@
+import { type RouteDescriptor, type ToolRouteRequest, type ToolRouteReceipt } from './routeTools.js';
+/** Structural interface: no executable handler or full schema ever crosses the JEV seam. */
+export interface MenuTool {
+    name: string;
+    family?: string;
+    description: string;
+    parameters: unknown;
+    providerVisible?: boolean;
+}
+export interface ToolMenu {
+    catalog: RouteDescriptor[];
+    members: Map<string, string[]>;
+}
+/** Unknown tools remain in the core. Routing never guesses a capability from its name. */
+export declare function buildToolMenu(tools: readonly MenuTool[], task: string, historical?: readonly string[]): ToolMenu;
+export interface MenuSelection<T> {
+    tools: T[];
+    omitted: T[];
+    receipt?: ToolRouteReceipt;
+    reason: string;
+    request?: ToolRouteRequest;
+}
+/** One boundary decision. Shadow and failure always return the original menu. */
+export declare function selectToolMenu<T extends MenuTool>(options: {
+    tools: readonly T[];
+    task: string;
+    projectedTask: string;
+    historical?: readonly string[];
+    mode: 'off' | 'shadow' | 'lean';
+    topK?: number;
+    minSavingsChars?: number;
+    signal: AbortSignal;
+    fresh?: () => boolean;
+    classify: (request: ToolRouteRequest, signal: AbortSignal) => Promise<unknown>;
+}): Promise<MenuSelection<T>>;

package/dist/src/decision/toolMenu.js

@@ -0,0 +1,73 @@
+import { answerOnlyTask } from './optimizationPolicy.js';
+import { DEFAULT_TOOL_ROUTE_POLICY, makeToolRouteRequest, routeTools } from './routeTools.js';
+const OPTIONAL = Object.freeze({
+    git: 'Inspect repository history, branches and diffs, or perform an explicitly requested version-control operation.',
+    codegraph: 'Explore source relationships, symbols and callers using the repository code graph.',
+    memory: 'Retrieve prior repository decisions or conventions from persistent memory.',
+    web: 'Research external documentation or current information from the web.',
+    browser: 'Inspect or verify an application through the interactive browser.',
+    subagents: 'Delegate an independent bounded task to an already-configured subagent.',
+    artifact: 'Read or record existing run artifacts and structured work products.',
+});
+const escape = (name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** Unknown tools remain in the core. Routing never guesses a capability from its name. */
+export function buildToolMenu(tools, task, historical = []) {
+    if (new Set(tools.map(tool => tool.name)).size !== tools.length)
+        throw new Error('Duplicate permitted tool');
+    const members = new Map([['core', []]]);
+    const pinned = new Set(['core']);
+    for (const tool of tools) {
+        const id = tool.family && Object.hasOwn(OPTIONAL, tool.family) && tool.providerVisible !== false ? tool.family : 'core';
+        const names = members.get(id) ?? [];
+        names.push(tool.name);
+        members.set(id, names);
+        if (historical.includes(tool.name) || new RegExp(`(?:^|[^a-zA-Z0-9_])${escape(tool.name)}(?:$|[^a-zA-Z0-9_])`).test(task))
+            pinned.add(id);
+    }
+    const catalog = [...members].map(([id, names]) => ({
+        id, description: id === 'core'
+            ? 'Complete the requested local coding or answer task using core read, search, edit, shell and completion capabilities, without optional integrations.'
+            : OPTIONAL[id],
+        schemaChars: tools.filter(tool => names.includes(tool.name) && tool.providerVisible !== false)
+            .reduce((sum, { name, description, parameters }) => sum + JSON.stringify({ name, description, parameters }).length, 0),
+        // Every optional root retains core prerequisites. Subagent outputs may refer to artifacts.
+        requires: id === 'core' ? [] : id === 'subagents' && members.has('artifact') ? ['core', 'artifact'] : ['core'],
+        pinned: pinned.has(id),
+    }));
+    return { catalog, members };
+}
+/** One boundary decision. Shadow and failure always return the original menu. */
+export async function selectToolMenu(options) {
+    const original = () => [...options.tools];
+    const unchanged = (reason) => ({ tools: original(), omitted: [], reason });
+    options.signal.throwIfAborted();
+    if (options.mode === 'off' || answerOnlyTask(options.task))
+        return unchanged('not_applicable');
+    const menu = buildToolMenu(options.tools, options.task, options.historical);
+    const minSavingsChars = options.minSavingsChars ?? DEFAULT_TOOL_ROUTE_POLICY.minSavingsChars;
+    const potentiallyOmitted = menu.catalog.filter(item => !item.pinned);
+    // Include conservative room for the restore_tools schema and omitted-name notice.
+    const recoveryAllowance = 512 + JSON.stringify(potentiallyOmitted.flatMap(item => menu.members.get(item.id) ?? [])).length * 2;
+    if (menu.catalog.length < 2 || potentiallyOmitted.reduce((sum, item) => sum + item.schemaChars, 0) < minSavingsChars + recoveryAllowance)
+        return unchanged('insufficient_optional_catalog');
+    if (options.fresh && !options.fresh())
+        return unchanged('stale_context');
+    const request = makeToolRouteRequest(options.projectedTask, menu.catalog);
+    let evidence;
+    try {
+        evidence = await options.classify(request, options.signal);
+    }
+    catch {
+        options.signal.throwIfAborted();
+        return unchanged('provider_unavailable');
+    }
+    options.signal.throwIfAborted();
+    if (options.fresh && !options.fresh())
+        return unchanged('stale_context');
+    const receipt = routeTools(menu.catalog, evidence, { ...DEFAULT_TOOL_ROUTE_POLICY,
+        topK: options.topK ?? DEFAULT_TOOL_ROUTE_POLICY.topK, minSavingsChars: minSavingsChars + recoveryAllowance });
+    if (options.mode === 'shadow' || receipt.outcome !== 'selected')
+        return { ...unchanged(options.mode === 'shadow' ? 'shadow' : receipt.reason), receipt, request };
+    const kept = new Set(receipt.selectedIds.flatMap(id => menu.members.get(id) ?? []));
+    return { tools: options.tools.filter(tool => kept.has(tool.name)), omitted: options.tools.filter(tool => !kept.has(tool.name)), receipt, request, reason: receipt.reason };
+}

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

@@ -0,0 +1,99 @@
+export interface DecisionConfig {
+    mode?: 'off' | 'shadow' | 'active';
+    provider?: 'none' | 'jev' | 'laya' | 'andorra';
+    endpoint?: string;
+    model?: string;
+    apiKeyEnv?: string;
+    requestTimeoutMs?: number;
+    features?: Partial<Record<'toolRouting' | 'codeGraphRouting' | 'memoryRouting' | 'webRouting' | 'delegationRouting' | 'verificationRouting' | 'riskClassification' | 'resultRouting', boolean>>;
+    /**
+     * How a run uses Jev after tool batches. `facts` (the default): literal facts on minimal state,
+     * combined in code into runtime actions, with no Jev-driven tool trimming. `questions`: the earlier
+     * post-tool questions that add guidance lines and select prepared steps.
+     */
+    style?: 'facts' | 'questions';
+}
+export declare const DECISION_DEFAULTS: {
+    readonly mode: "off";
+    readonly provider: "none";
+    readonly requestTimeoutMs: 1000;
+};
+export type DecisionQuestion = {
+    id: string;
+    type: 'noul';
+} | {
+    id: string;
+    type: 'choice';
+    choices: string[];
+} | {
+    id: string;
+    type: 'score';
+    min: number;
+    max: number;
+};
+export type DecisionResult = {
+    type: 'noul';
+    probability: number;
+} | {
+    type: 'choice';
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence: number;
+} | {
+    type: 'score';
+    score: number;
+    confidence: number;
+};
+export type DecisionBatch = Record<string, DecisionResult>;
+export interface DecisionRouting {
+    codeGraph: boolean;
+    memory: boolean;
+    decisions?: DecisionBatch;
+}
+export interface DecisionCandidate {
+    id: string;
+    kind: 'investigate' | 'retry' | 'change_strategy' | 'verify' | 'complete';
+    description: string;
+}
+export interface AgentDecisionState {
+    /** Local-only actionability; stripped before provider egress. */
+    consumers?: import('./optimizationPolicy.js').PreflightConsumers;
+    task: string;
+    node: {
+        id: string;
+        role?: string;
+        instruction?: string;
+    };
+    repository: {
+        codeGraphAvailable: boolean;
+        memoryAvailable: boolean;
+    };
+    capabilities: {
+        toolFamilies: string[];
+        subagentRoles: string[];
+        skills?: {
+            id: string;
+            description: string;
+        }[];
+    };
+    run: {
+        iteration?: number;
+    };
+    postTool?: {
+        results: {
+            name: string;
+            family?: string;
+            succeeded: boolean;
+            truncated: boolean;
+            summary: string;
+        }[];
+        candidates: DecisionCandidate[];
+        recentFailures?: string[];
+    };
+}
+export type DecisionState = AgentDecisionState;
+export interface DecisionIdentity {
+    runId: string;
+    nodeId: string;
+    invocationId: string;
+}

package/dist/src/decision/types.js

@@ -0,0 +1 @@
+export const DECISION_DEFAULTS = { mode: 'off', provider: 'none', requestTimeoutMs: 1000 };

package/dist/src/diff-preview.d.ts

@@ -0,0 +1,6 @@
+export interface FileChangePreview {
+    text: string;
+    detail?: string;
+}
+/** Proposed tool arguments only: writes may overwrite an existing file. */
+export declare function formatFileChange(name: string, args: Record<string, unknown>): FileChangePreview | undefined;

package/dist/src/diff-preview.js

@@ -0,0 +1,120 @@
+import { stripVTControlCharacters } from 'node:util';
+import { clipText } from './text.js';
+import { canonicalToolName } from './tool-names.js';
+import { andorraCreateEditTool } from '../vendor/engine/runtime/coding-agent/core/tools/edit.js';
+const PREVIEW_LINES = 12;
+const DETAIL_LINES = 200;
+const LINE_WIDTH = 300;
+// Construction only defines metadata. Previewing never invokes the tool executor.
+const prepareEditArguments = andorraCreateEditTool('.').prepareArguments;
+/** Keep file content from controlling the terminal or disguising diff markers. */
+function printable(value) {
+    return stripVTControlCharacters(value)
+        .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, '')
+        .replace(/\t/g, '    ');
+}
+function numbered(value, marker) {
+    if (!value)
+        return [];
+    const lines = value.replace(/\r\n/g, '\n').split('\n');
+    // A final line terminator does not introduce an extra content line.
+    if (lines.at(-1) === '')
+        lines.pop();
+    const width = String(lines.length).length;
+    return lines.map((line, index) => {
+        const clean = printable(line);
+        const shown = clean.length > LINE_WIDTH ? `${clipText(clean, LINE_WIDTH)} … [line truncated]` : clean;
+        return `${marker} ${String(index + 1).padStart(width)} | ${shown}`;
+    });
+}
+/** Shared snippet rendering for every edit contract (canonical and adopted). */
+function renderEdits(edits) {
+    return edits.flatMap((edit, index) => {
+        const replacement = [...numbered(edit.oldText, '-'), ...numbered(edit.newText, '+')];
+        return [
+            ...(edits.length > 1 ? [`Replacement ${index + 1}:`] : []),
+            ...(replacement.length ? replacement : ['(empty replacement)']),
+        ];
+    });
+}
+function render(header, lines, limit) {
+    const shown = lines.slice(0, limit);
+    if (lines.length > limit)
+        shown.push(`… ${lines.length - limit} more lines (preview truncated)`);
+    return [header, ...shown].join('\n');
+}
+/** Proposed tool arguments only: writes may overwrite an existing file. */
+export function formatFileChange(name, args) {
+    const canonical = canonicalToolName(name);
+    if (canonical !== 'Write' && canonical !== 'Edit')
+        return undefined;
+    // Canonical tool spelling carries file_path; every adopted Pi/Andorra spelling carries path.
+    const usesFilePath = name === 'Write' || name === 'Edit';
+    const rawPath = usesFilePath ? args.file_path : args.path;
+    if (typeof rawPath !== 'string')
+        return undefined;
+    const path = clipText(printable(rawPath.replace(/[\r\n]/g, ' ')), LINE_WIDTH);
+    let header;
+    let lines;
+    if (canonical === 'Write') {
+        if (typeof args.content !== 'string')
+            return undefined;
+        header = `Proposed content: ${path} (may create or overwrite)`;
+        lines = numbered(args.content, '+');
+        if (!lines.length)
+            lines = ['(empty file)'];
+    }
+    else if (usesFilePath) {
+        let edits = [];
+        if (Array.isArray(args.edits)) {
+            // The canonical Edit rejects an empty batch and an empty old_string, so previewing one
+            // would advertise a call that can only fail.
+            if (!args.edits.length)
+                return undefined;
+            for (const edit of args.edits) {
+                if (!edit || typeof edit !== 'object' || Array.isArray(edit)
+                    || typeof edit.old_string !== 'string'
+                    || !edit.old_string
+                    || typeof edit.new_string !== 'string')
+                    return undefined;
+                edits.push({ oldText: String(edit.old_string), newText: String(edit.new_string) });
+            }
+        }
+        else if (typeof args.old_string === 'string' && args.old_string && typeof args.new_string === 'string') {
+            edits = [{ oldText: args.old_string, newText: args.new_string }];
+        }
+        else
+            return undefined;
+        header = `Proposed replacement: ${path}${args.replace_all === true ? ' (all exact matches)' : ''}`;
+        lines = renderEdits(edits);
+    }
+    else if (name === 'edit') {
+        // Started events contain raw provider arguments. Use the executor's normalizer,
+        // but copy the envelope because it can replace edits while parsing JSON input.
+        if (prepareEditArguments)
+            args = prepareEditArguments({ ...args });
+        if (!Array.isArray(args.edits) || !args.edits.length)
+            return undefined;
+        const edits = [];
+        for (const edit of args.edits) {
+            if (!edit || typeof edit !== 'object' || Array.isArray(edit)
+                || typeof edit.oldText !== 'string' || typeof edit.newText !== 'string')
+                return undefined;
+            edits.push(edit);
+        }
+        header = `Proposed replacement: ${path} (line numbers relative to each snippet)`;
+        lines = renderEdits(edits);
+    }
+    else {
+        if (typeof args.old_text !== 'string' || typeof args.new_text !== 'string')
+            return undefined;
+        header = `Proposed replacement: ${path} (line numbers relative to each snippet)`;
+        lines = renderEdits([{ oldText: args.old_text, newText: args.new_text }]);
+        if (!lines.length)
+            lines = ['(empty replacement)'];
+    }
+    return {
+        text: render(header, lines, PREVIEW_LINES),
+        ...(lines.length > PREVIEW_LINES ? { detail: render(header, lines, DETAIL_LINES) } : {}),
+    };
+}

package/dist/src/duration.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Timing helpers for tool-call telemetry and user-facing surfaces (transcripts, status lines).
+ *
+ * Dependency-free and defensive by design: callers append the rendered suffix only when it is
+ * defined, so missing or unusable input degrades to byte-identical prior output instead of
+ * printing `NaN` or `undefined`.
+ */
+/**
+ * A non-negative finite duration in milliseconds, or `undefined` when the value cannot be
+ * trusted (missing, non-numeric, `NaN`, infinite or negative).
+ *
+ * The runtime emits a duration beside the identity of the call it belongs to, so a value that
+ * cannot be trusted must be dropped rather than coerced: `durationMs` returns `undefined` and the
+ * event carries no `durationMs`, which keeps consumers from pairing a fabricated duration with a
+ * real tool call. Only a number or a numeric string is accepted; other types are rejected instead
+ * of being coerced through `Number()`, which would silently turn `[]` into a `0ms` reading.
+ */
+export declare function durationMs(ms: unknown): number | undefined;
+/**
+ * Renders a duration for display: whole milliseconds below one second (`123ms`, `0ms`), otherwise
+ * one-decimal seconds (`1.2s`, `65.0s`).
+ *
+ * Returns `undefined` for anything `durationMs` rejects so the caller can omit the suffix
+ * entirely; this function never returns `NaN` or `undefined` as text.
+ */
+export declare function formatDuration(ms: unknown): string | undefined;
+/** Monotonic clock source for a per-call start reading. */
+export declare const monotonicNow: () => number;
+/**
+ * Elapsed milliseconds between a monotonic start reading and now, or `undefined` when the start
+ * cannot be trusted.
+ *
+ * `performance.now()` is monotonic, so a per-call reading cannot go negative if the system wall
+ * clock is adjusted mid-run. The span is rounded to whole milliseconds: the value is rendered to
+ * whole milliseconds or one-decimal seconds, and a raw `performance.now()` difference carries
+ * float noise ("17.22060000000056") that a duration was never measured to. The emitted event is
+ * what a run record persists, so the reading is fixed here rather than at each consumer. A host
+ * that lacks `performance` yields `undefined` instead of throwing inside a tool-call event
+ * emitter.
+ *
+ * Each call reads the clock independently, so concurrent branches of one batch can hold their own
+ * reader while the events they emit stay paired with the right `toolCallId`.
+ */
+export declare function elapsedMs(startedAt: number | undefined): number | undefined;

package/dist/src/duration.js

@@ -0,0 +1,72 @@
+import { performance } from 'node:perf_hooks';
+/**
+ * Timing helpers for tool-call telemetry and user-facing surfaces (transcripts, status lines).
+ *
+ * Dependency-free and defensive by design: callers append the rendered suffix only when it is
+ * defined, so missing or unusable input degrades to byte-identical prior output instead of
+ * printing `NaN` or `undefined`.
+ */
+/**
+ * A non-negative finite duration in milliseconds, or `undefined` when the value cannot be
+ * trusted (missing, non-numeric, `NaN`, infinite or negative).
+ *
+ * The runtime emits a duration beside the identity of the call it belongs to, so a value that
+ * cannot be trusted must be dropped rather than coerced: `durationMs` returns `undefined` and the
+ * event carries no `durationMs`, which keeps consumers from pairing a fabricated duration with a
+ * real tool call. Only a number or a numeric string is accepted; other types are rejected instead
+ * of being coerced through `Number()`, which would silently turn `[]` into a `0ms` reading.
+ */
+export function durationMs(ms) {
+    if (typeof ms !== 'number' && typeof ms !== 'string')
+        return undefined;
+    if (typeof ms === 'string' && !ms.trim())
+        return undefined;
+    const value = typeof ms === 'number' ? ms : Number(ms);
+    if (!Number.isFinite(value) || value < 0)
+        return undefined;
+    return value;
+}
+/**
+ * Renders a duration for display: whole milliseconds below one second (`123ms`, `0ms`), otherwise
+ * one-decimal seconds (`1.2s`, `65.0s`).
+ *
+ * Returns `undefined` for anything `durationMs` rejects so the caller can omit the suffix
+ * entirely; this function never returns `NaN` or `undefined` as text.
+ */
+export function formatDuration(ms) {
+    const value = durationMs(ms);
+    if (value === undefined)
+        return undefined;
+    if (value < 1000)
+        return `${Math.round(value)}ms`;
+    return `${(value / 1000).toFixed(1)}s`;
+}
+/** Monotonic clock source for a per-call start reading. */
+export const monotonicNow = () => performance.now();
+/**
+ * Elapsed milliseconds between a monotonic start reading and now, or `undefined` when the start
+ * cannot be trusted.
+ *
+ * `performance.now()` is monotonic, so a per-call reading cannot go negative if the system wall
+ * clock is adjusted mid-run. The span is rounded to whole milliseconds: the value is rendered to
+ * whole milliseconds or one-decimal seconds, and a raw `performance.now()` difference carries
+ * float noise ("17.22060000000056") that a duration was never measured to. The emitted event is
+ * what a run record persists, so the reading is fixed here rather than at each consumer. A host
+ * that lacks `performance` yields `undefined` instead of throwing inside a tool-call event
+ * emitter.
+ *
+ * Each call reads the clock independently, so concurrent branches of one batch can hold their own
+ * reader while the events they emit stay paired with the right `toolCallId`.
+ */
+export function elapsedMs(startedAt) {
+    if (typeof startedAt !== 'number' || !Number.isFinite(startedAt))
+        return undefined;
+    let value;
+    try {
+        value = performance.now() - startedAt;
+    }
+    catch {
+        return undefined;
+    }
+    return Number.isFinite(value) && value >= 0 ? Math.round(value) : undefined;
+}

package/dist/src/efficiency.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Independent controls for the efficiency optimizations layered on the agent runtime.
+ *
+ * Every switch here is off unless the configuration turns it on, so a configuration that names
+ * none of them runs the shipped behavior byte for byte. Each feature is evaluated on its own
+ * (`scripts/jev-efficiency-eval.mjs`), and the switches are independent so a feature whose
+ * evaluation does not justify it can stay off while the others ship.
+ *
+ * None of the switches widens what the hosted decision service receives: the deterministic paths
+ * run locally, and a semantic selection that would need excerpts the service is not contracted to
+ * receive stays disabled rather than sending them (see `docs/concepts/jev-efficiency.md`).
+ * @module efficiency
+ */
+/** A model the adaptive router may select; it must name a configured provider and model. */
+export interface ModelTierTarget {
+    provider: string;
+    model?: string;
+}
+/**
+ * User-supplied prices for cost reporting. Nothing here is invented by the runtime: a model
+ * without an entry reports "cost unavailable", never zero.
+ */
+export interface ModelPricing {
+    inputPerMillionUsd: number;
+    outputPerMillionUsd: number;
+    cacheReadPerMillionUsd?: number;
+}
+export interface AdaptiveRoutingConfig {
+    /** Off unless true; the tiers alone do not enable routing. */
+    enabled?: boolean;
+    tiers?: {
+        economy?: ModelTierTarget;
+        balanced?: ModelTierTarget;
+        premium?: ModelTierTarget;
+    };
+    /** Upward re-tiering after a defined failure; 0 disables escalation. Default 1. */
+    maxEscalations?: number;
+    /** Prices keyed by `<provider>/<model>`, for reports only. */
+    pricing?: Record<string, ModelPricing>;
+}
+/** Tool-menu routing is independently opt-in; shadow measures without trimming. */
+export interface ToolMenuRoutingConfig {
+    mode?: 'off' | 'shadow' | 'lean';
+    topK?: number;
+    minSavingsChars?: number;
+    /** Explicit host/node tools remain exposed. These names never grant permissions. */
+    pinnedTools?: string[];
+}
+export interface EfficiencyConfig {
+    /** Independent local finish/check machinery. Omission preserves the existing JEV-facts default. */
+    deterministicContinuations?: boolean;
+    /** False disables remote fact interpretation without disabling local continuations. */
+    jevFactInterpretation?: boolean;
+    /** Skip legacy preflight entirely without disabling fact or tool-menu decisions. */
+    jevPreflight?: boolean;
+    /** Pin project skill discovery independently of JEV. Undefined preserves the existing behavior. */
+    projectSkillDiscovery?: boolean;
+    toolMenuRouting?: ToolMenuRoutingConfig;
+    /**
+     * Prepared steps may declare `when: 'success' | 'failure' | 'always'`; a declared step runs
+     * deterministically after the batch it followed, without a decision request.
+     */
+    preparedContinuations?: boolean;
+    /** Skip the post-tool decision round when no prepared candidate could change execution. */
+    postflightOnlyWithCandidates?: boolean;
+    /** Parse bulky tool results before they enter the model-visible conversation. */
+    toolResultFiltering?: boolean;
+    /** Minimum output size, in characters, before a result is a filtering candidate. Default 6000. */
+    toolResultFilterThresholdChars?: number;
+    /** Workspace-fact gating of automatic retrieval and relevance selection of retrieved context. */
+    contextSelection?: boolean;
+    /** Deterministic task-appropriate tool catalog and lazy skill catalog ordering. */
+    catalogSelection?: boolean;
+    adaptiveRouting?: AdaptiveRoutingConfig;
+}
+export declare const EFFICIENCY_FEATURES: readonly ["preparedContinuations", "postflightOnlyWithCandidates", "toolResultFiltering", "contextSelection", "catalogSelection"];
+export type EfficiencyFeature = typeof EFFICIENCY_FEATURES[number];
+export declare const DEFAULT_TOOL_RESULT_FILTER_THRESHOLD = 6000;
+declare const TIERS: readonly ["economy", "balanced", "premium"];
+export type ModelTier = typeof TIERS[number];
+export declare const MODEL_TIERS: readonly ModelTier[];
+/** Fail closed on shape: a mistyped switch is an error, not a silently ignored optimization. */
+export declare function validateEfficiencyConfig(value: unknown): void;
+export interface ResolvedEfficiency {
+    preparedContinuations: boolean;
+    postflightOnlyWithCandidates: boolean;
+    toolResultFiltering: boolean;
+    toolResultFilterThresholdChars: number;
+    contextSelection: boolean;
+    catalogSelection: boolean;
+    adaptiveRouting: AdaptiveRoutingConfig & {
+        enabled: boolean;
+        maxEscalations: number;
+    };
+}
+/** The effective switches; every absent value is the shipped behavior. */
+export declare function resolveEfficiency(config: EfficiencyConfig | undefined): ResolvedEfficiency;
+/** Fixed reason codes shared by every `efficiency.*` event; free text never rides an event. */
+export declare const EFFICIENCY_REASONS: readonly ["deterministic_continuation", "jev_selected", "no_candidates", "no_actionable_decision", "stale_task", "stale_permissions", "catalog_mismatch", "blocked", "denied", "invalid_arguments", "automatic_limit", "batch_failed", "batch_succeeded", "filtered", "below_threshold", "unknown_format", "protected_tool", "error_output", "expanded", "expansion_rejected", "empty_workspace", "index_unavailable", "memory_unavailable", "selected", "duplicate", "changed", "fallback", "economy", "balanced", "premium", "baseline", "pinned", "unconfigured", "low_confidence", "risk", "escalated", "escalation_limit", "omitted", "restored", "historical", "explicit"];
+export type EfficiencyReason = typeof EFFICIENCY_REASONS[number];
+export {};