@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/token-rate.js

@@ -0,0 +1,287 @@
+/**
+ * Cumulative token speed meter.
+ *
+ * Providers report a request's tokens only when that request finishes. Each finished request
+ * is folded into running totals - sum of output tokens over sum of decoding time - so the
+ * reading is the *average* decoding speed across every request measured since the last
+ * reset, not the newest request alone. One fast call does not swing the footer: a 900-token
+ * request over 3 seconds and a later 2,000-token request over 10 seconds average to about
+ * 208 tok/s, and the average converges toward the provider's steady state as more land.
+ *
+ * The time a request is credited with is its decode window - first generated fragment to
+ * last - whenever the streaming adapter measured one (`Usage.decodeMs`). Prompt processing,
+ * the network and the runtime's own pre-request work all happen before the first fragment, so
+ * they stay out: a short answer to a 10K-token prompt is not read as a slow model. A request
+ * without a decode window falls back to the window between its start marker and its usage,
+ * and once any request was decode-measured those coarser readings no longer dilute the
+ * average.
+ *
+ * While a request is still streaming, its fragments are estimated into the reading live
+ * ({@link TokenRateMeter.stream}), so a long thinking stream moves the footer instead of
+ * holding the previous number until it completes. The provider's count replaces the estimate
+ * the moment the request's usage lands. Between LLM calls nothing changes and nothing decays.
+ * A completion that finished without usage still closes its request window but keeps the
+ * totals: the average it leaves on screen is a measurement of the requests that did report.
+ */
+/**
+ * Window assumed when a request finished without one being opened.
+ *
+ * Both executors emit a start event before every model call, so this only happens for an
+ * embedder that reports usage on its own. Crediting those tokens one synthetic second of
+ * generating time keeps them in the average at a plausible speed; crediting them to a
+ * zero-length instant would divide by (near) zero and spike the whole average.
+ */
+const UNKNOWN_WINDOW_MS = 1_000;
+/**
+ * How many requests may be in flight at once.
+ *
+ * Branch workers, parallel copies and delegated subagents each open their own request, and a
+ * start whose request never reports (aborted mid-call, or a run stopped between the start and
+ * its usage) would otherwise hold its slot forever and pair with a later completion. The
+ * runtime never runs more than a handful of model calls at a time, so this is a leak valve:
+ * the oldest in-flight window is dropped, and a completion that has lost its window falls back
+ * to {@link UNKNOWN_WINDOW_MS}.
+ */
+const MAX_IN_FLIGHT = 64;
+/**
+ * Streamed decode time a live estimate needs before it joins the reading.
+ *
+ * The first fragments of a stream arrive in bursts a few milliseconds apart; dividing their
+ * characters by that sliver would flash an absurd speed before the window settles.
+ */
+const LIVE_MIN_WINDOW_MS = 1_000;
+/**
+ * Estimate the tokens in a streamed fragment: four ASCII characters to a token, the common
+ * rate for English prose and code, and one token per character outside ASCII, which CJK text
+ * comes close to. Only a live reading uses it; the provider's count replaces it on completion.
+ */
+export function estimateStreamedTokens(text) {
+    let ascii = 0, other = 0;
+    for (const character of text) {
+        if (character.charCodeAt(0) < 0x80)
+            ascii += 1;
+        else
+            other += 1;
+    }
+    return ascii / 4 + other;
+}
+export class TokenRateMeter {
+    clock;
+    /** When each in-flight model request began, oldest first; the pairing fallback for starts and completions that carry no id. See {@link MAX_IN_FLIGHT}. */
+    open = [];
+    /**
+     * In-flight requests that arrived with the executor's `invocationId`, keyed by it.
+     *
+     * Concurrent requests - branch workers, parallel graph copies, subagents - finish in an
+     * order no queue can predict: a later start can complete first. Keying by the id the
+     * executor stamps on both the start event and the usage delta pairs each completion with
+     * the window its own request opened.
+     */
+    openById = new Map();
+    /** Output tokens summed over every request measured by its request window since the last reset. */
+    tokens = 0;
+    /** Request-window time summed over the same requests, in milliseconds. */
+    milliseconds = 0;
+    /** Output tokens summed over every request whose adapter measured a decode window. */
+    decodedTokens = 0;
+    /** Decode windows summed over the same requests, in milliseconds. */
+    decodeMilliseconds = 0;
+    /**
+     * Requests streaming right now, keyed by `invocationId` (`''` without one): the estimated
+     * tokens so far and the arrival times of the first and the latest fragment.
+     */
+    live = new Map();
+    constructor(clock = () => Date.now()) {
+        this.clock = clock;
+    }
+    /**
+     * Mark the start of a model request, so its eventual tokens are measured over this window.
+     *
+     * Every concurrent request gets its own entry: `src/graph-runner.ts` runs branch workers
+     * side by side, and a single slot would have a later start overwrite the first request's
+     * timestamp and the first completion clear it, leaving every later completion without a
+     * window of its own.
+     */
+    beginRequest(invocationId) {
+        const at = this.clock();
+        if (invocationId) {
+            this.openById.set(invocationId, at);
+            while (this.openById.size > MAX_IN_FLIGHT) {
+                const oldest = this.openById.keys().next();
+                if (oldest.done)
+                    break;
+                this.openById.delete(oldest.value);
+            }
+            return;
+        }
+        this.open.push(at);
+        if (this.open.length > MAX_IN_FLIGHT)
+            this.open.shift();
+    }
+    /**
+     * Record provider-reported tokens for one finished model request.
+     *
+     * A completion carrying the executor's `invocationId` closes exactly the window that id's
+     * start opened, so concurrent requests finishing out of order each measure over their own
+     * generation. Without an id on either side, each completion is paired with the oldest
+     * request still in flight - the one that has been generating longest - which is the best a
+     * start with no identity allows; what matters is that every completion gets a real window
+     * rather than the synthetic fallback.
+     *
+     * Only a delta that carries tokens closes a window. The adapters also report pure transport
+     * bookkeeping through this callback - the HTTP adapter counts every attempt, retries
+     * included, as `requests: 1` with zero tokens - and pairing a completion with the *wrong*
+     * window is worse than the synthetic fallback: an attempt delta popping a window would leave
+     * the real completion to pair with an older request's start or with none at all. A window
+     * whose call never reports tokens (a request that failed or was aborted) is dropped by the
+     * {@link MAX_IN_FLIGHT} valve instead.
+     *
+     * The delta that closes a request arrives flagged `final`. A final delta without tokens is
+     * an unmeasured completion - a provider that omits usage - and it closes its request all
+     * the same, but the cumulative totals stay: they describe the requests that did report, and
+     * the average on screen remains their measurement until the next completion or a reset.
+     * An attempt delta keeps its early return: it reports zero tokens by design, and it must
+     * neither steal a window nor disturb the average the real completion will extend.
+     * @param tokens - output tokens the provider reported for that one request.
+     * @param invocationId - request identity from the executor, when the caller has one.
+     * @param final - true when this delta closes its request (the response accounting), as
+     * opposed to per-attempt transport bookkeeping.
+     * @param decodeMs - the adapter's measured decode window for the request, when it has one;
+     * it replaces the request window as the time the tokens are credited with.
+     */
+    report(tokens, invocationId, final, decodeMs) {
+        const count = Number.isFinite(tokens) && tokens > 0 ? Math.floor(tokens) : 0;
+        if (!count) {
+            if (!final)
+                return;
+            // An unmeasured completion still closes the request it belongs to, so its window is
+            // consumed here - leaving it open would make the next measured completion pair with
+            // this request's start instead of its own. The cumulative average stays as it is.
+            this.takeWindow(invocationId);
+            this.endStream(invocationId);
+            return;
+        }
+        const at = this.clock();
+        const started = this.takeWindow(invocationId);
+        // The provider's count supersedes the live estimate of the same request.
+        this.endStream(invocationId);
+        if (decodeMs !== undefined && Number.isFinite(decodeMs) && decodeMs > 0) {
+            this.decodedTokens += count;
+            this.decodeMilliseconds += decodeMs;
+            return;
+        }
+        // A request that starts and completes inside one clock tick (a cached answer, an
+        // in-process or test adapter) has no measurable duration. Crediting its tokens against
+        // even one real millisecond would spike the cumulative average to an absurd speed, so an
+        // unmeasurable window takes the same synthetic second an unknown window does.
+        const duration = started !== undefined && at > started ? at - started : UNKNOWN_WINDOW_MS;
+        this.tokens += count;
+        this.milliseconds += duration;
+    }
+    /**
+     * Take the window a completion closes: the one its `invocationId` opened, or - when the
+     * request carried no id, or the id never opened one - the oldest still in flight. Returns
+     * undefined when nothing is in flight and the caller falls back to the synthetic window.
+     */
+    takeWindow(invocationId) {
+        if (invocationId !== undefined) {
+            const started = this.openById.get(invocationId);
+            if (started !== undefined) {
+                this.openById.delete(invocationId);
+                return started;
+            }
+        }
+        return this.open.length ? this.open.shift() : undefined;
+    }
+    /**
+     * Credit a streamed fragment of a request that has not finished yet.
+     *
+     * The estimate counts toward the reading over the stream's own decode window - first
+     * fragment to latest - so a pause in the stream (a tool call's arguments, which do not
+     * stream as text) holds the reading rather than decaying it.
+     */
+    stream(text, invocationId) {
+        const tokens = estimateStreamedTokens(text);
+        if (!tokens)
+            return;
+        const at = this.clock();
+        const key = invocationId ?? '';
+        const entry = this.live.get(key);
+        if (entry) {
+            entry.tokens += tokens;
+            entry.last = at;
+            return;
+        }
+        this.live.set(key, { tokens, first: at, last: at });
+        while (this.live.size > MAX_IN_FLIGHT) {
+            const oldest = this.live.keys().next();
+            if (oldest.done)
+                break;
+            this.live.delete(oldest.value);
+        }
+    }
+    /** Drop a request's live estimate: its attempt failed, was retried, or was aborted. */
+    endStream(invocationId) {
+        this.live.delete(invocationId ?? '');
+    }
+    /**
+     * The tokens per second the footer shows: the average decoding speed over every request
+     * measured since the last reset, with any request still streaming blended in.
+     *
+     * Decode-measured requests and live streams are preferred; the request-window totals answer
+     * only when neither exists. Between completions the reading holds - no window drains and
+     * nothing decays. It moves as a stream grows or a completion lands, and resets to 0 with
+     * {@link reset}.
+     */
+    rate() {
+        let tokens = this.decodedTokens, milliseconds = this.decodeMilliseconds;
+        for (const entry of this.live.values()) {
+            const window = entry.last - entry.first;
+            if (window >= LIVE_MIN_WINDOW_MS) {
+                tokens += entry.tokens;
+                milliseconds += window;
+            }
+        }
+        if (tokens <= 0 || milliseconds <= 0) {
+            tokens = this.tokens;
+            milliseconds = this.milliseconds;
+        }
+        if (tokens <= 0 || milliseconds <= 0)
+            return 0;
+        // A positive reading never rounds away. A very slow cumulative average (say 1 token
+        // over several seconds) is a real measurement, and the footer gates the segment on
+        // `> 0`: rounding it to 0 would silently drop finished requests, reading like "nothing
+        // measured" when exactly the opposite happened.
+        return Math.max(1, Math.round(tokens / (milliseconds / 1_000)));
+    }
+    /** Forget everything measured so far; the caller resets it when the graph switches nodes. */
+    reset() {
+        this.open = [];
+        this.openById.clear();
+        this.live.clear();
+        this.tokens = 0;
+        this.milliseconds = 0;
+        this.decodedTokens = 0;
+        this.decodeMilliseconds = 0;
+    }
+}
+/**
+ * Route a model request's streamed fragments into the speed readout, keeping the caller's hooks.
+ *
+ * Only a request carrying the executor's `invocationId` is metered: its usage delta reports under
+ * the same id and replaces the estimate. A call made outside the runtime - a graph health probe,
+ * whose usage only feeds the probe bookkeeping - has no completion that would ever retire its
+ * estimate, which would then blend into every later reading, so it passes through untouched.
+ * Each new attempt drops the estimate the previous one left.
+ */
+export function meterStreamedRequest(request, sink) {
+    const invocationId = request.context?.invocationId;
+    if (invocationId === undefined)
+        return request;
+    return {
+        ...request,
+        onRequest: () => { sink.noteStreamEnded(invocationId); request.onRequest?.(); },
+        onReasoning: delta => { sink.noteStreamedOutput(delta, invocationId); request.onReasoning?.(delta); },
+        onText: delta => { sink.noteStreamedOutput(delta, invocationId); request.onText?.(delta); },
+    };
+}

package/dist/src/tool-activity.d.ts

@@ -0,0 +1,20 @@
+import type { RuntimeEvent } from './types.js';
+/** Tracks tool calls that are currently executing across concurrent graph invocations. */
+export declare class ToolActivity {
+    private readonly active;
+    private readonly retries;
+    retry(data: Record<string, unknown>): string;
+    finishModel(data: Record<string, unknown>): string;
+    start(data: Record<string, unknown>): string;
+    finish(data: Record<string, unknown>): string;
+    clear(): void;
+    label(): string;
+    private invocationKey;
+    private key;
+}
+/**
+ * Converts runtime events that affect the single-slot CLI activity label into the correct label.
+ * Iteration events intentionally derive from the tracker, so one parallel invocation cannot replace
+ * a sibling's still-running tool with "Thinking".
+ */
+export declare function activityForRuntimeEvent(event: RuntimeEvent, activity: ToolActivity): string | undefined;

package/dist/src/tool-activity.js

@@ -0,0 +1,76 @@
+/** Tracks tool calls that are currently executing across concurrent graph invocations. */
+export class ToolActivity {
+    active = new Map();
+    retries = new Map();
+    retry(data) {
+        this.retries.set(this.invocationKey(data), `Retrying provider request (${data.retry}/${data.maxRetries})`);
+        return this.label();
+    }
+    finishModel(data) {
+        this.retries.delete(this.invocationKey(data));
+        return this.label();
+    }
+    start(data) {
+        const name = typeof data.name === 'string' ? data.name : '';
+        if (!name)
+            return this.label();
+        const key = this.key(data);
+        const running = this.active.get(key);
+        if (running)
+            running.count++;
+        else
+            this.active.set(key, { name, count: 1 });
+        return this.label();
+    }
+    finish(data) {
+        const key = this.key(data);
+        const running = this.active.get(key);
+        if (running) {
+            if (running.count > 1)
+                running.count--;
+            else
+                this.active.delete(key);
+        }
+        return this.label();
+    }
+    clear() { this.active.clear(); this.retries.clear(); }
+    label() {
+        const retry = this.retries.values().next().value;
+        if (retry)
+            return retry;
+        const names = [...new Set([...this.active.values()].map(entry => entry.name))];
+        if (!names.length)
+            return 'Thinking';
+        return `Running ${names.slice(0, 2).join(', ')}${names.length > 2 ? ` +${names.length - 2} more` : ''}`;
+    }
+    invocationKey(data) {
+        return [data.runId, data.nodeId, data.copy, data.subagentId]
+            .map(value => value === undefined || value === null ? '' : String(value))
+            .join('\u0000');
+    }
+    key(data) {
+        const invocation = this.invocationKey(data);
+        return typeof data.toolCallId === 'string'
+            ? `${invocation}\u0000call:${data.toolCallId}`
+            : `${invocation}\u0000name:${String(data.name ?? '')}`;
+    }
+}
+/**
+ * Converts runtime events that affect the single-slot CLI activity label into the correct label.
+ * Iteration events intentionally derive from the tracker, so one parallel invocation cannot replace
+ * a sibling's still-running tool with "Thinking".
+ */
+export function activityForRuntimeEvent(event, activity) {
+    if (event.type === 'node.tool.started')
+        return activity.start(event.data);
+    if (event.type === 'node.tool.completed' || event.type === 'node.tool.failed')
+        return activity.finish(event.data);
+    if (event.type === 'agent.model.retry')
+        return activity.retry(event.data);
+    // Session completion also covers exhausted retries, failed requests and cancellation.
+    if (event.type === 'agent.model.completed' || event.type === 'agent.session.completed')
+        return activity.finishModel(event.data);
+    if (event.type === 'agent.iteration.started')
+        return activity.label();
+    return undefined;
+}

package/dist/src/tool-call-clock.d.ts

@@ -0,0 +1,32 @@
+import type { RuntimeEvent } from './types.js';
+export interface ToolCallStamp {
+    key: string;
+    timestamp?: string;
+}
+export interface ToolCallTiming extends ToolCallStamp {
+    runId: unknown;
+    nodeId: unknown;
+    copy: unknown;
+    subagentId: unknown;
+    startedAt: number;
+    elapsedMs?: number; /** Set while the call waits on a human decision; the clock holds its reading at this instant. */
+    pausedSince?: number;
+}
+export declare function toolCallStamp(event: RuntimeEvent): ToolCallStamp;
+/** UI-only state. Completed entries retain their frozen object after leaving the active map. */
+export declare class ToolCallClock {
+    private readonly now;
+    private readonly active;
+    constructor(now?: () => number);
+    get running(): boolean;
+    get(key: string): ToolCallTiming | undefined;
+    elapsed(timing: ToolCallTiming): number;
+    /** Hold the displayed reading while a human decides; the wait is not the call running. */
+    private pause;
+    private resume;
+    stop(runId?: unknown): void;
+    accept(event: RuntimeEvent): void;
+}
+/** Keep the complete header; reserve a right column when it fits, otherwise wrap the clock. */
+export declare function toolHeaderRows(header: string, right: string, width: number): string[];
+export declare function staticToolTimestamp(text: string, stamp?: ToolCallStamp): string;

package/dist/src/tool-call-clock.js

@@ -0,0 +1,157 @@
+import stringWidth from 'string-width';
+import { durationMs, monotonicNow } from './duration.js';
+export function toolCallStamp(event) {
+    const data = event.data;
+    const key = JSON.stringify([data.runId, data.nodeId, data.copy, data.subagentId,
+        typeof data.toolCallId === 'string' ? ['call', data.toolCallId] : ['name', data.name]]);
+    const date = new Date(event.time);
+    const timestamp = Number.isFinite(date.getTime())
+        ? [date.getHours(), date.getMinutes(), date.getSeconds()].map(value => String(value).padStart(2, '0')).join(':') : undefined;
+    return { key, ...(timestamp ? { timestamp } : {}) };
+}
+/** UI-only state. Completed entries retain their frozen object after leaving the active map. */
+export class ToolCallClock {
+    now;
+    active = new Map();
+    constructor(now = monotonicNow) {
+        this.now = now;
+    }
+    get running() { return this.active.size > 0; }
+    get(key) { return this.active.get(key); }
+    elapsed(timing) { return timing.elapsedMs ?? Math.max(0, (timing.pausedSince ?? this.now()) - timing.startedAt); }
+    /** Hold the displayed reading while a human decides; the wait is not the call running. */
+    pause(timing) { if (timing.elapsedMs === undefined && timing.pausedSince === undefined)
+        timing.pausedSince = this.now(); }
+    resume(timing) {
+        if (timing.pausedSince === undefined)
+            return;
+        timing.startedAt += this.now() - timing.pausedSince;
+        timing.pausedSince = undefined;
+    }
+    stop(runId) {
+        for (const [key, timing] of this.active) {
+            if (runId !== undefined && timing.runId !== runId)
+                continue;
+            timing.elapsedMs = this.elapsed(timing);
+            this.active.delete(key);
+        }
+    }
+    accept(event) {
+        if (event.type === 'graph.completed' || event.type === 'graph.stopped') {
+            this.stop(event.data.runId);
+            return;
+        }
+        if (event.type === 'graph.started') {
+            this.stop();
+            return;
+        }
+        if (['graph.node.completed', 'agent.session.completed', 'subagent.completed'].includes(event.type)) {
+            for (const [key, timing] of this.active) {
+                const fields = event.type === 'graph.node.completed' ? ['runId', 'nodeId']
+                    : event.type === 'subagent.completed' ? ['runId', 'subagentId'] : ['runId', 'nodeId', 'copy', 'subagentId'];
+                if (fields.every(field => timing[field] === event.data[field])) {
+                    timing.elapsedMs = this.elapsed(timing);
+                    this.active.delete(key);
+                }
+            }
+            return;
+        }
+        // A human decision inside a call — an approval prompt or a clarification question — is not
+        // execution time: freeze the clock for the affected call for as long as the wait lasts.
+        if (event.type === 'node.tool.approval.requested' || event.type === 'node.tool.approval.decided') {
+            if (typeof event.data.toolCallId !== 'string' || !event.data.toolCallId.trim())
+                return;
+            const timing = this.active.get(toolCallStamp(event).key);
+            if (timing) {
+                if (event.type === 'node.tool.approval.requested')
+                    this.pause(timing);
+                else
+                    this.resume(timing);
+            }
+            return;
+        }
+        if (event.type === 'agent.clarification.requested' || event.type === 'agent.clarification.answered') {
+            // Clarification events carry no call id, so they pair by the invocation they belong to.
+            // `ask_user` is sequential only inside one invocation: concurrent copies of a node, and a
+            // node's subagents, ask and answer apart, so the pairing must match every stamp an active
+            // call carries — otherwise one copy's question freezes a sibling still at work, and one
+            // answer resumes a clock whose own question nobody has answered.
+            for (const timing of this.active.values()) {
+                if (timing.runId !== event.data.runId || timing.nodeId !== event.data.nodeId)
+                    continue;
+                if (timing.copy !== event.data.copy || timing.subagentId !== event.data.subagentId)
+                    continue;
+                if (event.type === 'agent.clarification.requested')
+                    this.pause(timing);
+                else
+                    this.resume(timing);
+            }
+            return;
+        }
+        if (!['node.tool.started', 'node.tool.completed', 'node.tool.failed'].includes(event.type))
+            return;
+        // Legacy events without a call ID get a static timestamp; guessing by name
+        // would pair concurrent calls incorrectly.
+        if (typeof event.data.toolCallId !== 'string' || !event.data.toolCallId.trim())
+            return;
+        const stamp = toolCallStamp(event);
+        if (event.type === 'node.tool.started') {
+            // Duplicate start delivery must not restart a timer already on screen.
+            if (!this.active.has(stamp.key))
+                this.active.set(stamp.key, { ...stamp, runId: event.data.runId,
+                    nodeId: event.data.nodeId, copy: event.data.copy, subagentId: event.data.subagentId, startedAt: this.now() });
+        }
+        else {
+            const timing = this.active.get(stamp.key);
+            if (timing) {
+                timing.elapsedMs = durationMs(event.data.durationMs) ?? this.elapsed(timing);
+                this.active.delete(stamp.key);
+            }
+        }
+    }
+}
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+function splitWidth(text, width) {
+    const rows = [];
+    let row = '', used = 0;
+    for (const { segment } of segmenter.segment(text)) {
+        const size = stringWidth(segment);
+        if (used + size > width && row) {
+            rows.push(row);
+            row = '';
+            used = 0;
+        }
+        if (size > width) {
+            rows.push('…');
+            continue;
+        }
+        row += segment;
+        used += size;
+    }
+    rows.push(row);
+    return rows;
+}
+/** Keep the complete header; reserve a right column when it fits, otherwise wrap the clock. */
+export function toolHeaderRows(header, right, width) {
+    width = Math.max(1, Math.floor(width));
+    if (!right)
+        return splitWidth(header, width);
+    const rightWidth = stringWidth(right);
+    if (width <= rightWidth + 2)
+        return [...splitWidth(header, width), ...splitWidth(right, width).map(row => ' '.repeat(width - stringWidth(row)) + row)];
+    const parts = [...segmenter.segment(header)].map(part => part.segment);
+    let first = '', used = 0;
+    while (parts.length && used + stringWidth(parts[0]) <= width - rightWidth - 2) {
+        const part = parts.shift();
+        first += part;
+        used += stringWidth(part);
+    }
+    return [first + ' '.repeat(width - used - rightWidth) + right, ...(parts.length ? splitWidth(parts.join(''), width) : [])];
+}
+export function staticToolTimestamp(text, stamp) {
+    if (!stamp?.timestamp)
+        return text;
+    const rows = text.split('\n');
+    rows[0] += `  ${stamp.timestamp}`;
+    return rows.join('\n');
+}

package/dist/src/tool-catalog.d.ts

@@ -0,0 +1,40 @@
+import type { Tool } from './types.js';
+import type { WorkspaceFacts } from './workspace-facts.js';
+export interface CatalogSelectionInput {
+    tools: Tool[];
+    task: string;
+    facts?: WorkspaceFacts;
+    /** Tools the node configuration names explicitly; always kept when permitted. */
+    explicitTools?: readonly string[];
+    /** Tool names called in an inherited conversation; always kept. */
+    historicalToolNames?: readonly string[];
+    codeGraphAvailable?: boolean;
+    memoryAvailable?: boolean;
+}
+export interface CatalogSelection {
+    tools: Tool[];
+    omitted: Tool[];
+    reasons: Record<string, 'no_repository' | 'index_unavailable' | 'memory_unavailable' | 'empty_workspace' | 'not_indicated'>;
+    schemaCharsBefore: number;
+    schemaCharsAfter: number;
+}
+export declare function schemaChars(tools: readonly Tool[]): number;
+/**
+ * Select the catalog. The order of the kept tools is the order of the input, so a stable input
+ * yields a byte-stable schema list.
+ */
+export declare function selectToolCatalog(input: CatalogSelectionInput): CatalogSelection;
+export interface SkillSummary {
+    id: string;
+    description: string;
+    unavailable?: string;
+}
+/**
+ * Order the skill catalog by lexical relevance to the task and fit it into a budget, keeping
+ * explicitly requested and inherited skills first and whole. Entries that do not fit are named
+ * without their descriptions so they stay loadable.
+ */
+export declare function orderSkillCatalog(skills: readonly SkillSummary[], task: string, required: readonly string[], budgetChars: number): {
+    entries: SkillSummary[];
+    namedOnly: string[];
+};