@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/transcript.js

@@ -0,0 +1,228 @@
+import { stripVTControlCharacters } from 'node:util';
+import { clipText } from './text.js';
+import { formatFileChange } from './diff-preview.js';
+import { accentSgr, DIM, GRAY, STATUS, WHITE } from './palette.js';
+import { HEADING_PREFIX, renderMarkdown } from './markdown.js';
+import { formatDuration } from './duration.js';
+import { toolCallStamp } from './tool-call-clock.js';
+import { canonicalCodingToolName } from './tool-names.js';
+const clean = (value) => stripVTControlCharacters(String(value ?? '')).replace(/\r\n?/g, '\n').replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, '');
+const line = (value) => clipText(clean(value).replace(/\s+/g, ' ').trim(), 240);
+/**
+ * Render an event-supplied duration for display without ever printing `NaN` or `undefined`.
+ *
+ * The transcript is both a user surface and a log: an absent or unusable `durationMs` must leave
+ * the line byte-identical to the output produced before durations existed, so the caller appends
+ * the rendered text only when this returns a non-empty suffix.
+ */
+export function formatDurationSuffix(data) {
+    const rendered = formatDuration(data.durationMs);
+    return rendered ? ` in ${rendered}` : '';
+}
+function formatRetryDelay(ms) {
+    const value = typeof ms === 'number' ? ms : Number(ms);
+    if (!Number.isFinite(value) || value < 0)
+        return 'unknown time';
+    if (value >= 60_000 && value % 60_000 === 0)
+        return `${value / 60_000}m`;
+    if (value % 1000 === 0)
+        return `${value / 1000}s`;
+    return formatDuration(value) ?? 'unknown time';
+}
+/** Describe the action without dumping file contents or graph handoff payloads. */
+export function describeTool(name, value) {
+    let args = {};
+    try {
+        const parsed = typeof value === 'string' ? JSON.parse(value) : value;
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            args = parsed;
+    }
+    catch { /* The runtime reports malformed arguments as a tool failure. */ }
+    // One label per operation. The canonical name selects it, so every spelling in the shared
+    // alias registry resolves here and a newly adopted spelling cannot drift out of this list.
+    // Read/Write/Edit carry file_path on the canonical tool and path on the adopted spellings.
+    const label = (tool) => `${tool} ${line(args.file_path ?? args.path)}`;
+    switch (canonicalCodingToolName(name)) {
+        case 'Bash':
+        case 'PowerShell': return `Run ${line(args.command)}`;
+        case 'Read': return label('Read');
+        case 'Write': return label('Write');
+        case 'Edit': return label('Edit');
+        // list_files and search_files are Andorra's directory listing and literal query, whose
+        // contracts carry no pattern/query the canonical form would show.
+        case 'Glob': return name === 'list_files' ? `List files in ${line(args.path ?? '.')}` : `Glob "${line(args.pattern ?? '*')}" in ${line(args.path ?? '.')}`;
+        case 'Grep': return name === 'search_files' ? `Search for "${line(args.query ?? args.pattern)}" in ${line(args.path ?? '.')}` : `Grep "${line(args.pattern)}" in ${line(args.path ?? '.')}`;
+        default: break;
+    }
+    switch (name) {
+        case 'spawn_subagent': return `Delegate to ${line(args.role)}: ${line(args.task)}`;
+        case 'ask_user': return 'Ask a question';
+        case 'git_read':
+        case 'git_write': return `Git ${line(args.operation)}`;
+        case 'memory_search': return `Search memory for "${line(args.query)}"`;
+        case 'repo_explore': return `Explore repository for "${line(args.query)}"`;
+        default: return `${line(name)}${args.path ? ` ${line(args.path)}` : ''}`;
+    }
+}
+/**
+ * Colors are selected from trusted presentation markers, never provider ANSI.
+ *
+ * Returns a 256-color index for neutral and semantic tones, or a ready SGR sequence for
+ * the brand accent, which needs truecolor on supporting terminals.
+ * @param text - one rendered transcript line.
+ * @returns a paint color: a palette index or an SGR parameter string.
+ */
+export function transcriptColor(text) {
+    if (/^\s*-\s+\d+\s*\|/.test(text))
+        return STATUS.error;
+    if (/^\s*\+\s+\d+\s*\|/.test(text))
+        return STATUS.added;
+    // The trusted code/heading markers outrank error prose: a code line that happens to
+    // contain `failed:` or `Error:` is still code. A message that opens with rendered
+    // markdown keeps its marker color even behind the `• [actor]` prefix its first
+    // line carries.
+    if (/^\s*(?:•(?:\s*\[[^\]]*\])?\s*)?┆/.test(text))
+        return GRAY;
+    if (/^\s*(?:•(?:\s*\[[^\]]*\])?\s*)?▌/.test(text))
+        return WHITE;
+    if (/failed:|^\s*Error:/.test(text))
+        return STATUS.error;
+    if (/^\s*•/.test(text))
+        return accentSgr();
+    if (/^\s*(?:└|…)/.test(text))
+        return GRAY;
+    return DIM;
+}
+/**
+ * Render a finished run for the transcript: the completion summary as rendered markdown, the
+ * checks the agent reports under their own heading, and the run line last.
+ *
+ * The summary is the agent's final answer and is written in markdown like every other agent
+ * message, so it goes through the same renderer — a fence or heading printed verbatim reads as
+ * a broken response. Each check is one line (the model is told to keep it so; a stray newline is
+ * folded), and the heading is only drawn when there is a check to put under it. A collapsed code
+ * block returns the full rendering as `detail`, with the same checks and run line, so Ctrl+O
+ * shows the whole answer in place.
+ */
+export function formatRunResult(result) {
+    const summary = clean(result.summary).replace(/^(?:[ \t]*\n)+/, '').replace(/\s+$/, '');
+    const rendered = renderMarkdown(summary);
+    const checks = (result.tests ?? []).map(check => line(check)).filter(Boolean);
+    const trailer = [
+        ...(checks.length ? ['', `${HEADING_PREFIX} Checks`, ...checks.map(check => `  • ${check}`)] : []),
+        '',
+        `Run ${line(result.id)} - ${line(result.status)}`,
+    ];
+    const assemble = (body) => [...(body ? [body] : []), ...trailer].join('\n').replace(/^\n+/, '');
+    return { text: assemble(rendered.text), ...(rendered.detail ? { detail: assemble(rendered.detail) } : {}) };
+}
+export function formatEvent(event) {
+    const data = event.data;
+    if (data.provider === 'andorra' || data.provider === 'jev') {
+        // Decision calls have their own actor; originating graph names and provider payloads stay private.
+        if (event.type === 'decision.requested')
+            return { text: '• [Jev] Evaluating context needs' };
+        if (event.type === 'decision.completed')
+            return { text: `  └ [Jev] Decisions received${formatDurationSuffix({ durationMs: data.latencyMs })}` };
+        if (event.type === 'decision.fallback' && data.reason !== 'low_confidence') {
+            const reasons = {
+                authentication_required: 'Sign in required', decision_daily_limit_reached: 'Daily quota reached',
+                decision_service_unavailable: 'Service unavailable', invalid_response: 'Invalid response',
+                decision_input_too_large: 'Context exceeds hosted size limits; evaluation skipped locally',
+                timeout: 'Request timed out', cancelled: 'Request cancelled',
+            };
+            const reason = String(data.reason);
+            return { text: `  └ [Jev] ${Object.hasOwn(reasons, reason) ? reasons[reason] : 'Decision service unavailable'}; using standard context routing` };
+        }
+    }
+    const identity = [data.nodeName, typeof data.copy === 'number' && Number(data.copies ?? 2) > 1 ? `copy ${data.copy}${data.copies ? `/${data.copies}` : ''}` : '', data.subagentId].filter(Boolean).map(line).join(' - ');
+    const actor = identity ? `[${identity}] ` : '';
+    if (event.type === 'agent.context.compaction.started')
+        return { text: 'Summarizing earlier work to free context.' };
+    if (event.type === 'agent.context.compaction.retry')
+        return { text: `Context summary incomplete (${line(data.reason)}); retrying ${line(data.nextAttempt)}/3.` };
+    if (event.type === 'agent.model.retry')
+        return { text: `\u2022 ${actor}Provider request retry ${line(data.retry)}/${line(data.maxRetries)} in ${formatRetryDelay(data.delayMs)}: ${line(data.reason)}` };
+    if (event.type === 'graph.node.started')
+        return { text: `Node: ${line(data.nodeName ?? data.nodeId)}${Number(data.visit) > 1 ? ` (visit ${line(data.visit)})` : ''}` };
+    if (event.type === 'agent.modifier.iteration.started' && Number(data.maxIterations) > 1)
+        return { text: `${line(data.nodeName ?? data.nodeId)} - loop ${line(data.iteration)}/${line(data.maxIterations)}` };
+    if (event.type === 'agent.modifier.copy.started' && Number(data.copies) > 1)
+        return { text: `${line(data.nodeName ?? data.nodeId)} - copy ${line(data.copy)}/${line(data.copies)} started` };
+    if (event.type === 'graph.todos.updated') {
+        const todos = data.todos;
+        return { text: todos.length ? `Todo\n${todos.map(todo => `  ${todo.status === 'completed' ? '✓' : todo.status === 'in_progress' ? '●' : '○'} ${line(todo.text)}`).join('\n')}` : 'Todo: cleared' };
+    }
+    if (event.type === 'agent.message') {
+        // The model writes markdown; the transcript paints whole lines with trusted
+        // markers. Collapsed code blocks come back as detail for the Ctrl+O view.
+        // Only outer blank lines are stripped — leading spaces can be a fenced block's
+        // GFM indentation, which the renderer needs intact to de-indent its content.
+        const body = clean(data.text).replace(/^(?:[ \t]*\n)+/, '').replace(/\s+$/, '');
+        const rendered = renderMarkdown(body);
+        return { text: `• ${actor}${rendered.text}`, ...(rendered.detail ? { detail: `• ${actor}${rendered.detail}` } : {}) };
+    }
+    if (event.type === 'node.tool.started') {
+        const heading = `• ${actor}${describeTool(String(data.name), data.arguments)}`;
+        let change;
+        try {
+            const args = typeof data.arguments === 'string' ? JSON.parse(data.arguments) : data.arguments;
+            if (args && typeof args === 'object' && !Array.isArray(args))
+                change = formatFileChange(String(data.name), args);
+        }
+        catch { /* Invalid arguments are reported by tool execution. */ }
+        return { text: heading + (change ? `\n${change.text}` : ''), ...(change?.detail ? { detail: `${heading}\n${change.detail}` } : {}), toolCall: toolCallStamp(event) };
+    }
+    if (event.type === 'node.tool.completed' || event.type === 'node.tool.failed') {
+        // The question UI already echoes the answer. Keep the structured tool result
+        // available to the agent and run log, but out of both transcript views.
+        if (event.type === 'node.tool.completed' && data.name === 'ask_user') {
+            return { text: `  \u2514 ${actor}Answer received${formatDurationSuffix(data)}` };
+        }
+        const output = clean(data.output).trimEnd();
+        const rows = output.split('\n');
+        const preview = rows.slice(0, 5).map(row => clipText(row, 180));
+        const shortened = rows.length > 5 || preview.some((row, index) => row !== rows[index]);
+        const failed = event.type === 'node.tool.failed';
+        const heading = `${actor}${failed ? `${line(data.name)} failed: ` : ''}`;
+        // The duration trails the output the way a shell reports completion: `… in 123ms`. A missing
+        // or unusable duration leaves the rendering identical to the pre-timing output. Failure
+        // headings already end in a space, so the suffix is emitted bare and never doubles it.
+        const suffix = formatDurationSuffix(data) ?? '';
+        const indent = (text) => text.split('\n').map((row, index) => `${index ? '    ' : '  └ '}${index ? '' : heading}${row}`).join('\n');
+        return { text: indent(preview.join('\n') || '(no output)') + (shortened ? `\n    … ${rows.length} lines total` : '') + suffix,
+            ...(shortened ? { detail: indent(output) + suffix } : {}) };
+    }
+    if (event.type === 'agent.turn.continued')
+        return { text: `? ${actor}Continuing: graph stop hook requested more work or a structured handoff.` };
+    if (event.type === 'agent.completion.rejected')
+        return { text: `• ${actor}Retrying: ${data.reason === 'truncatedResponse' ? 'model response was truncated; no tools executed' : data.reason === 'outputTokenLimit' ? 'output token limit reached; continuing the response' : data.reason === 'duplicateToolCallIds' ? 'model reused a tool-call ID; no tools executed' : 'model response did not meet the completion contract'}.` };
+    if (event.type === 'subagent.started')
+        return { text: `• Started ${line(data.role)} (${line(data.subagentId)})` };
+    if (event.type === 'subagent.completed')
+        return { text: `• ${line(data.role)} ${line(data.status)}` };
+    if (event.type === 'codeintel.state') {
+        if (data.state === 'ready' || data.state === 'uninitialized')
+            return undefined;
+        return { text: `• [CodeGraph] ${line(data.state)}${data.detail ? ` — ${line(data.detail)}` : ''}` };
+    }
+    if (event.type === 'codeintel.indexed')
+        return { text: `• [CodeGraph] Indexed ${Number(data.files ?? 0)} files, ${Number(data.nodes ?? 0)} nodes in ${Math.round(Number(data.durationMs ?? 0) / 1000)}s` };
+    if (event.type === 'codeintel.query')
+        return { text: `• [CodeGraph] Served ${Number(data.files ?? 0)} ${Number(data.files ?? 0) === 1 ? 'file' : 'files'} (${Number(data.chars ?? 0)} chars, graph revision ${line(data.revision)})` };
+    if (event.type === 'codeintel.fallback')
+        return { text: `• [CodeGraph] Unavailable for this query (${line(data.reason ?? 'unknown')}); using filesystem tools` };
+    if (event.type === 'memory.retrieved') {
+        const memories = (Array.isArray(data.memories) ? data.memories : []);
+        const rows = memories.slice(0, 8).map(memory => `  - ${line(String(memory.id ?? '').slice(0, 8))} ${line(memory.type)} ${String(memory.temporalStatus ?? 'unknown').toUpperCase()}${memory.requiresRevalidation ? ' (needs revalidation)' : ''}`);
+        return {
+            text: `• [Memory] ${memories.length} relevant ${memories.length === 1 ? 'memory' : 'memories'} for ${line(data.nodeId ?? 'agent')} (repo: ${line(data.repository)}, ${Number(data.chars ?? 0)} chars)${rows.length ? `\n${rows.join('\n')}` : ''}`,
+            ...(memories.length > 8 ? { detail: JSON.stringify(memories, null, 2) } : {}),
+        };
+    }
+    if (event.type === 'memory.distilled' && Number(data.persisted) > 0)
+        return { text: `• [Memory] Persisted ${Number(data.persisted)} durable ${Number(data.persisted) === 1 ? 'memory' : 'memories'} from this task` };
+    if (event.type === 'memory.error')
+        return { text: `• [Memory] ${line(data.operation ?? 'operation')} unavailable: ${line(data.detail ?? 'unknown error')} — continuing without persistent memory` };
+    return undefined;
+}

package/dist/src/types.d.ts

@@ -0,0 +1,248 @@
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+/** In-memory, provider-bound opaque reasoning replay; excluded from diagnostics and summaries. */
+export interface ProviderContinuation {
+    api: string;
+    provider: string;
+    model: string;
+    thinking: {
+        type: 'thinking';
+        thinking: string;
+        thinkingSignature?: string;
+        redacted?: boolean;
+    }[];
+}
+export interface ToolImage {
+    mimeType: 'image/png' | 'image/jpeg';
+    data: string;
+}
+export interface Message {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /** Runtime-owned semantic summary marker; never inferred from user text. */
+    contextSummary?: true;
+    content: string;
+    /** Provider protocol state for thinking tool continuations; never render or log. */
+    reasoningContent?: string;
+    providerContinuation?: ProviderContinuation;
+    toolCalls?: ToolCall[];
+    toolCallId?: string;
+    /** Native visual observations; never serialize these as text in prompts or summaries. */
+    images?: ToolImage[];
+}
+/**
+ * Billed and measured figures for one request or an accumulated run.
+ *
+ * `decodeMs` is the measured decode window of a streamed response: the wall time from the first
+ * generated fragment to the last. It excludes prompt processing (which ends at the first token)
+ * and tool execution (which happens between requests), so a throughput figure over it describes
+ * how fast the model produced tokens. It is absent when the window could not be observed: a
+ * whole-body response, a single-fragment stream, or an adapter that does not measure one.
+ */
+export interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+    requests: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    decodeMs?: number;
+}
+export interface ToolSchema {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export interface ModelResponse {
+    text: string;
+    toolCalls: ToolCall[];
+    usage?: Partial<Usage>;
+    stopReason?: string;
+    reasoningContent?: string;
+    providerContinuation?: ProviderContinuation;
+}
+/** Local diagnostics only; never part of a provider transport payload. */
+export interface ModelRequestContext {
+    runId?: string;
+    nodeId?: string;
+    providerId?: string;
+    subagentId?: string;
+    invocationId?: string;
+}
+export interface ModelRetry {
+    retry: number;
+    maxRetries: number;
+    delayMs: number;
+    reason: string;
+}
+export interface GenerateRequest {
+    model: string;
+    messages: Message[];
+    tools: ToolSchema[];
+    signal: AbortSignal;
+    /** Explicit bounded auxiliary output (for example semantic summaries); absent for ordinary inference. */
+    maxTokens?: number;
+    /**
+     * How many trailing messages are run snapshots rewritten between turns (todo list, widget
+     * values, post-tool guidance). A provider that caches only up to explicit breakpoints places
+     * its conversation breakpoint on the last committed message in front of them, so the next
+     * request can reuse the cached history even though the snapshots moved or changed.
+     */
+    mutableTail?: number;
+    context?: ModelRequestContext;
+    onRetry?: (retry: ModelRetry) => void | Promise<void>;
+    onRequest?: () => void;
+    /**
+     * Live reasoning sink for interactive callers. When provided, OpenAI-compatible
+     * providers stream the completion and forward each `reasoning_content` delta as it
+     * arrives; provider types without streamed reasoning ignore it and answer whole.
+     * Deltas are display-only: they must never be persisted, logged, or replayed into
+     * model context. The final `ModelResponse.reasoningContent` remains the only
+     * continuation state.
+     */
+    onReasoning?: (delta: string) => void;
+    /** Visible response streaming; final text remains authoritative. */
+    onText?: (delta: string) => void;
+}
+export interface ModelAdapter {
+    generate(request: GenerateRequest): Promise<ModelResponse>;
+    listModels?(signal: AbortSignal): Promise<string[]>;
+}
+export interface ToolFileReadState {
+    path: string;
+    /** Retained only while the aggregate snapshot cache has capacity. */
+    content?: string;
+    /** SHA-256 of the full UTF-16 snapshot, retained when content is evicted. */
+    contentHash?: string;
+    complete: boolean;
+    sizeBytes: number;
+    mtimeMs?: number;
+    /** Model-visible line ranges from one or more Read calls; omitted for complete snapshots. */
+    ranges?: {
+        start: number;
+        end: number;
+    }[];
+    lineCount?: number;
+    source: 'Read' | 'CodeGraph' | 'mutation';
+}
+export interface ToolRuntimeState {
+    fileReads: Map<string, ToolFileReadState>;
+}
+export interface ToolContext {
+    /** Installation store for durable schedules; never accepted from model arguments. */
+    automationDirectory?: string;
+    /** Per-agent identity for isolated browser sessions, never sent to a provider. */
+    browserSessionOwner?: object;
+    /** Runtime-owned identity for one model response's tool batch; never provider-visible. */
+    browserToolBatch?: object;
+    runControl?: import('./run-control.js').RunControl;
+    workspace: string;
+    signal: AbortSignal;
+    /**
+     * Session or parent cancellation without any wall clock.
+     *
+     * Interactive prompts must use this rather than `signal`: a run may not abort a question
+     * the user is still answering, while Ctrl+C must still cancel it. Falls back to `signal`
+     * for embedders that supply no separate value.
+     */
+    userSignal?: AbortSignal;
+    yolo: boolean;
+    permissions?: import('./permissions.js').PermissionMode;
+    /** Runtime-owned scoped approval: canonical file paths must not change. */
+    pinFilePaths?: boolean;
+    /**
+     * Engine-written attachment spool directories for this run, realpath-resolved.
+     *
+     * The user attached this content to the very turn that named the paths, so reads under
+     * these roots are trusted as strongly as workspace reads: they skip the outside-workspace
+     * and protected-metadata gates that would otherwise demand an approval headless runs
+     * cannot grant. Never model input; never widened beyond the engine's own spools.
+     */
+    attachmentRoots?: readonly string[];
+    /** Runtime-owned explicit file-mutation grant, scoped to one tool call. */
+    fileMutationApproval?: {
+        explicit: boolean;
+    };
+    /** Runtime-owned approval for one host QA tool call, never model input. */
+    qaHostApproved?: boolean;
+    /** Omitted means interactive for existing embedders; headless denies without a callback. */
+    approvalMode?: 'interactive' | 'headless';
+    /** Only true is an explicit user grant; policy changes require a fresh policy decision. */
+    approve: (name: string, args: Record<string, unknown>, signal: AbortSignal) => Promise<boolean | 'policy-changed'>;
+    /** Runtime-owned clarification channel; undefined answers decline the current intake. */
+    askUser?: (question: string, signal: AbortSignal, choices?: readonly string[]) => Promise<string | undefined>;
+    onApprovalEvent?: (type: string, data: Record<string, unknown>) => void | Promise<void>;
+    /** Browser lifecycle observations, scoped to the current coding session, never a tool-supplied identity. */
+    onBrowserEvent?: (type: string, data: Record<string, unknown>) => void | Promise<void>;
+    /**
+     * Called by the file permission wrapper once a mutation's path has been authorized and
+     * canonicalized, immediately before the tool executes.
+     *
+     * The runtime uses it to read the before-half of a diff: reading the target any earlier would
+     * perform the very access the approval (of a protected path, an outside path, or a link) exists
+     * to grant. Absent when the call is not a file mutation.
+     */
+    onFilePathAuthorized?: (canonicalTarget: string) => void | Promise<void>;
+    /** Shared invocation state used by canonical coding tools for read/write freshness. */
+    toolState?: ToolRuntimeState;
+    /** Session self-wake timers backing `set_timer`; absent means the tool reports itself unavailable. */
+    timers?: import('./timers.js').TimerRegistry;
+    /**
+     * The selections the current run started with, tagged onto a wake it arms. A wake outlives its run and is
+     * delivered as a new one, so without this the continuation loses a per-project graph/model and a per-run
+     * effort or scope. Surfaces with no run of their own leave it unset.
+     */
+    wakeCarry?: import('./timers.js').WakeCarry;
+    /**
+     * Filled in with the id of every wake this run arms, so a run can tell its own wakes from the session's.
+     *
+     * A wake is the promise the turn that armed it made about the conversation as that turn left it. When that
+     * turn's record never reaches the disk the promise is not the session's to keep - but a wake an earlier turn
+     * armed and saved is, and nothing but their ids tells the two apart. Surfaces with no run of their own leave
+     * it unset.
+     */
+    wakesArmed?: string[];
+    /**
+     * The session the run belongs to, used only to tag a wake armed through `timers`.
+     *
+     * Needed because a registry can outlive the run that armed into it: an engine keeps one for every
+     * session it has served, and a delivered wake has to land back in the conversation that asked for it.
+     */
+    sessionScope?: string;
+    /** The session's pull request backing `pull_request`; absent means the tool reports itself unavailable. */
+    pullRequests?: import('./pull-requests.js').PullRequestControl;
+}
+export type ToolFamily = 'filesystem-read' | 'filesystem-write' | 'code-search' | 'codegraph' | 'git' | 'shell' | 'qa' | 'memory' | 'web' | 'browser' | 'subagents' | 'artifact';
+export interface Tool extends ToolSchema {
+    /** Internal backward-compatible validation shape; never advertised to providers. */
+    validationParameters?: Record<string, unknown>;
+    /** Normalize provider arguments before native schema validation and execution. */
+    prepareArguments?: (args: unknown) => Record<string, unknown>;
+    /** Hidden compatibility tools remain callable by internal/legacy code but are never advertised to models. */
+    providerVisible?: boolean;
+    family?: ToolFamily;
+    capability?: 'git.read' | 'git.write' | 'github.read' | 'github.pull-request' | 'github.review' | 'browser' | 'deployment' | 'external' | 'extension.read';
+    /** Pi-style batch scheduling hint. Parallel is the hardened executor default; mark mutations/interactive tools sequential. */
+    executionMode?: 'parallel' | 'sequential';
+    /**
+     * A shell whose normal return means the command exited 0: any other exit, a timeout or a
+     * cancellation throws. The output text then carries no status line, so this is the only exact
+     * record of a passing verification command.
+     */
+    exitZeroOnReturn?: boolean;
+    execute(args: Record<string, unknown>, context: ToolContext): Promise<string>;
+    /** Consume native visual output separately from bounded text and event logs. */
+    resultImages?: (output: string) => ToolImage[] | undefined;
+    /**
+     * Optional projection of the tool output for `node.tool.*` events (which
+     * are persisted in run records). Tools whose output must not be retained —
+     * e.g. memory content — return a metadata-only rendering here.
+     */
+    eventOutput?: (output: string) => string;
+}
+export interface RuntimeEvent {
+    type: string;
+    time: string;
+    data: Record<string, unknown>;
+}

package/dist/src/types.js

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

package/dist/src/update.d.ts

@@ -0,0 +1,48 @@
+export type UpdateRunner = (program: string, args: string[], cwd: string) => Promise<string>;
+/** Outcome of deciding whether the installed dependency tree can be replaced in place. */
+export interface LockProbe {
+    state: 'clear' | 'locked' | 'unknown';
+    /** The file or directory npm could not replace, when the probe identified one. */
+    path?: string;
+    detail: string;
+}
+export type ReinstallProbe = (checkout: string) => Promise<LockProbe>;
+export interface UpdateOptions {
+    /** Injectable only for embedding/tests; the CLI uses this module's installed location. */
+    moduleUrl?: string | URL;
+    run?: UpdateRunner;
+    /** Injectable only for tests; the CLI probes the real tree by renaming within it. */
+    probe?: ReinstallProbe;
+    /** Injectable only for tests; the CLI waits between bounded reinstall attempts. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Replace an existing updater lock even when its recorded process still appears to run. */
+    breakLock?: boolean;
+    /** Injectable only for tests; the CLI asks the OS whether the lock's recorded process exists. */
+    isRunning?: (pid: number) => boolean;
+    /** Receives progress notes the caller should show, such as a reclaimed stale lock. */
+    notify?: (message: string) => void;
+}
+/**
+ * True when the installed tree is provably complete for the lockfile the checkout carries: both the
+ * root lockfile and npm's own hidden lockfile parse, every package npm recorded still matches the
+ * version and hash the root lockfile pins, and every direct dependency the package declares is
+ * present. The hidden lockfile is written only by a completed install, and it omits the root entry,
+ * so a legitimate tree has one fewer entry than the lockfile — it is never compared by count, and it
+ * is never trusted on its own, because a failed install can leave a stale one behind.
+ */
+export declare function dependenciesSatisfied(checkout: string): Promise<boolean>;
+export interface UpdateLockOptions {
+    breakLock?: boolean;
+    isRunning?: (pid: number) => boolean;
+    notify?: (message: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Take the updater lock and return the record written into it. A lock whose recorded process is
+ * gone was left by an interrupted update (Ctrl+C, a closed terminal, a crash) and is reclaimed; one
+ * whose process still runs, or that does not name a process, is only broken with breakLock, because
+ * a process id can be reused.
+ */
+export declare function acquireUpdateLock(lockPath: string, options?: UpdateLockOptions): Promise<string>;
+/** Update the linked installation checkout, never the caller's working directory. */
+export declare function updateInstallation(options?: UpdateOptions): Promise<string>;