@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/app-server/reasoning.js

@@ -0,0 +1,173 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Publish a model call's reasoning to the window as display-only events.
+ *
+ * `GenerateRequest.onReasoning` is display-only by contract: reasoning is streamed so a turn can
+ * show its thinking, and it is never written to the run journal, the session record, or the
+ * trajectory. This wrapper honors that boundary for the desktop — the events it publishes go to
+ * the connected client alone, so the journal stays exactly as large as it was and no reasoning
+ * text is persisted anywhere.
+ *
+ * The events mirror the tool-call pair the window already folds (`node.tool.started` /
+ * `node.tool.completed`): one row opens when the first delta arrives, so a turn can show that the
+ * model is thinking, and closes with the text and the window it streamed over. Between them the
+ * reasoning streams as `agent.reasoning.delta` events, so a window can show the thought as it
+ * forms instead of waiting for the call to settle; the completion still carries the authoritative
+ * text, so a window that folds only the pair renders exactly as it did before. A retried request
+ * restarts its own row rather than concatenating a failed attempt's reasoning with the answer that
+ * replaced it, which is the same rule the terminal's live preview follows.
+ *
+ * Each row is named by the call that opened it (`reasoningId`), because one invocation makes many
+ * calls and their thinking must not collapse into one row. The invocation identity the runtime
+ * stamps on its own events travels along, so a row is attributable to its node and subagent.
+ */
+/**
+ * Characters of one call's reasoning carried by the live stream.
+ *
+ * Reasoning may run far longer than the answer it precedes; the row shows a bounded head rather
+ * than letting one call's thinking occupy the window's memory. The marker on the event says so, so
+ * a truncated row is never presented as the whole thought.
+ */
+export const REASONING_TEXT_LIMIT = 12_000;
+/**
+ * Longest gap between two delta events on the wire.
+ *
+ * A provider can deliver reasoning many times a second, and every event is a notification the
+ * window folds into a render; coalescing to this cadence — the same figure the terminal's live
+ * preview paints at — keeps a token firehose from becoming a render firehose while still reading
+ * as live. What coalescing holds back travels with the next flush, and the remainder with the
+ * completion, so no text is lost to the pace.
+ */
+export const REASONING_DELTA_MS = 80;
+export function withReasoningEvents(adapter, publish) {
+    const generate = async (request) => {
+        // One row per model call, so consecutive calls in one invocation each keep their own thinking
+        // instead of the later call replacing the earlier one's text.
+        const reasoningId = randomUUID();
+        let open = false;
+        let text = '';
+        let truncated = false;
+        let openedAt = 0;
+        let attempts = 0;
+        let pendingDelta = '';
+        let lastDeltaAt = 0;
+        let deltaTimer;
+        // The invocation identity travels with every event, the way the runtime stamps its own: it is
+        // what the window pairs this row with the model call and node it belongs to.
+        const identity = {
+            reasoningId,
+            ...(request.context?.invocationId ? { invocationId: request.context.invocationId } : {}),
+            ...(request.context?.nodeId ? { nodeId: request.context.nodeId } : {}),
+            ...(request.context?.subagentId ? { subagentId: request.context.subagentId } : {}),
+        };
+        const stamp = () => new Date().toISOString();
+        const openRow = () => {
+            open = true;
+            openedAt = Date.now();
+            publish({ type: 'agent.reasoning.started', time: stamp(), data: { ...identity } });
+        };
+        // Each HTTP attempt restarts the stream, so its text replaces the previous attempt's: the row it
+        // belongs to is reopened with its clock reset, and the abandoned text is dropped rather than
+        // joined to a response it did not produce. Deltas still waiting to coalesce belong to that
+        // abandoned attempt, so they are dropped with it rather than streaming into the reopened row.
+        const beginAttempt = () => {
+            attempts += 1;
+            if (!open)
+                return;
+            text = '';
+            truncated = false;
+            pendingDelta = '';
+            if (deltaTimer) {
+                clearTimeout(deltaTimer);
+                deltaTimer = undefined;
+            }
+            openedAt = Date.now();
+            publish({ type: 'agent.reasoning.started', time: stamp(), data: { ...identity, attempt: attempts } });
+        };
+        const flushDelta = () => {
+            if (deltaTimer) {
+                clearTimeout(deltaTimer);
+                deltaTimer = undefined;
+            }
+            if (!pendingDelta)
+                return;
+            const delta = pendingDelta;
+            pendingDelta = '';
+            publish({ type: 'agent.reasoning.delta', time: stamp(), data: { ...identity, text: delta } });
+        };
+        // A stream that goes quiet must not leave its last fragment waiting for the next one: the
+        // coalescing delay is a maximum, so whatever is buffered gets its own timer for the remainder of
+        // the window. The timer never outlives a settle or a reopen (both clear it) and never keeps the
+        // process alive (unref'd), so it cannot publish an abandoned attempt's text or block exit.
+        const scheduleDeltaFlush = () => {
+            if (deltaTimer)
+                return;
+            const remaining = REASONING_DELTA_MS - (Date.now() - lastDeltaAt);
+            if (remaining <= 0) {
+                flushDelta();
+                return;
+            }
+            deltaTimer = setTimeout(() => {
+                deltaTimer = undefined;
+                lastDeltaAt = Date.now();
+                flushDelta();
+            }, remaining);
+            deltaTimer.unref?.();
+        };
+        const settle = () => {
+            if (!open)
+                return;
+            open = false;
+            // The stream ends complete: what coalescing still holds travels ahead of the completion, so a
+            // window rendering live never falls behind the authoritative text that settles the row.
+            flushDelta();
+            publish({
+                type: 'agent.reasoning.completed',
+                time: stamp(),
+                data: { ...identity, text, durationMs: Math.max(0, Date.now() - openedAt), ...(truncated ? { truncated: true } : {}) },
+            });
+        };
+        try {
+            return await adapter.generate({
+                ...request,
+                onRequest: () => { beginAttempt(); request.onRequest?.(); },
+                onReasoning: delta => {
+                    if (!delta)
+                        return;
+                    if (!open)
+                        openRow();
+                    // Only the characters the row keeps are streamed: past the display limit the event would
+                    // carry text the settled row drops, and the live preview would jump backwards on settle.
+                    const room = Math.max(0, REASONING_TEXT_LIMIT - text.length);
+                    if (room === 0)
+                        truncated = true;
+                    else {
+                        const kept = delta.length > room ? delta.slice(0, room) : delta;
+                        if (kept.length < delta.length)
+                            truncated = true;
+                        text += kept;
+                        pendingDelta += kept;
+                        const now = Date.now();
+                        if (now - lastDeltaAt >= REASONING_DELTA_MS) {
+                            lastDeltaAt = now;
+                            flushDelta();
+                        }
+                        else {
+                            scheduleDeltaFlush();
+                        }
+                    }
+                    request.onReasoning?.(delta);
+                },
+            });
+        }
+        finally {
+            // A failed request still ends its row: a row left open would keep the transcript claiming the
+            // model is thinking about a call that is already over.
+            settle();
+        }
+    };
+    return {
+        generate,
+        ...(adapter.listModels ? { listModels: (signal) => adapter.listModels(signal) } : {}),
+    };
+}

package/dist/src/app-server/terminal.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Interactive terminal sessions for the desktop client.
+ *
+ * The environment is the user's own, not the allowlisted `shellBaseEnv` that agent tool shells
+ * receive: this shell is driven by the person at the keyboard, and a terminal that hid their
+ * PATH, credentials, or aliases would not be the terminal they asked for. The distinction is
+ * deliberate, so the two paths keep separate constructors.
+ */
+export interface TerminalSession {
+    id: string;
+    shell: string;
+    cwd: string;
+}
+export interface TerminalCallbacks {
+    data(id: string, chunk: string): void;
+    exit(id: string, code: number, signal?: number): void;
+}
+/**
+ * Flow control for streamed terminal output.
+ *
+ * The protocol is one line per event on a single stream, so a shell that produces faster than the client
+ * reads would otherwise queue its output inside this process until it runs out of memory — one `yes` can
+ * do that. The rule is small enough to test on its own: a write the stream refuses pauses the shell it
+ * came from, and the stream's own `drain` lets every paused shell go again.
+ */
+export declare class TerminalFlow {
+    private readonly stream;
+    private readonly pause;
+    private readonly resume;
+    private readonly paused;
+    private listening;
+    constructor(stream: {
+        once(event: 'drain', listener: () => void): unknown;
+    }, pause: (id: string) => void, resume: (id: string) => void);
+    /** Report what happened to one terminal's line: `accepted` is the stream's own answer. */
+    sent(id: string, accepted: boolean): void;
+}
+/**
+ * Resolve the interactive shell.
+ *
+ * PowerShell is the Windows default because it is the interpreter the tool shells already use
+ * and it is present on every supported Windows; `ComSpec` is the fallback rather than the
+ * choice. POSIX hosts use the login shell the user selected.
+ */
+export declare function terminalShell(): string;
+export declare class TerminalManager {
+    private readonly callbacks;
+    private readonly terminals;
+    /** Set once the manager has been closed, so a late open cannot outlive the shutdown that closed it. */
+    private closed;
+    constructor(callbacks: TerminalCallbacks);
+    open(options: {
+        cwd: string;
+        cols?: unknown;
+        rows?: unknown;
+    }): TerminalSession;
+    private forget;
+    private require;
+    write(id: unknown, data: unknown): void;
+    resize(id: unknown, cols: unknown, rows: unknown): void;
+    /** Close one terminal and reap its process. Returns whether it was open. */
+    close(id: unknown): boolean;
+    /** Hold one shell's output back; a request for a terminal that is gone is a no-op. */
+    pause(id: string): void;
+    /** Let a held shell produce output again. */
+    resume(id: string): void;
+    /**
+     * Close every open terminal and report how many were closed.
+     *
+     * A client that reattaches after a renderer reload has no way to name the terminals the previous
+     * one left behind, and the ids it does hold are gone with it: closing them is how the engine's slots
+     * come back instead of being held by shells nobody can see or reach.
+     */
+    closeAll(): number;
+    /** Close every terminal and finish the manager: nothing it spawns afterwards would be reaped. */
+    shutdown(): void;
+}

package/dist/src/app-server/terminal.js

@@ -0,0 +1,177 @@
+import { existsSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import * as pty from 'node-pty';
+/**
+ * Flow control for streamed terminal output.
+ *
+ * The protocol is one line per event on a single stream, so a shell that produces faster than the client
+ * reads would otherwise queue its output inside this process until it runs out of memory — one `yes` can
+ * do that. The rule is small enough to test on its own: a write the stream refuses pauses the shell it
+ * came from, and the stream's own `drain` lets every paused shell go again.
+ */
+export class TerminalFlow {
+    stream;
+    pause;
+    resume;
+    paused = new Set();
+    listening = false;
+    constructor(stream, pause, resume) {
+        this.stream = stream;
+        this.pause = pause;
+        this.resume = resume;
+    }
+    /** Report what happened to one terminal's line: `accepted` is the stream's own answer. */
+    sent(id, accepted) {
+        if (accepted) {
+            // Nothing is waiting on the drain for this one: it kept up.
+            if (this.paused.delete(id))
+                this.resume(id);
+            return;
+        }
+        // One pause per flood: every line a held shell reports while it is held is the same state.
+        if (!this.paused.has(id)) {
+            this.paused.add(id);
+            this.pause(id);
+        }
+        if (this.listening)
+            return;
+        this.listening = true;
+        this.stream.once('drain', () => {
+            this.listening = false;
+            const releasing = [...this.paused];
+            this.paused.clear();
+            for (const paused of releasing)
+                this.resume(paused);
+        });
+    }
+}
+const MAX_TERMINALS = 8;
+const MIN_DIMENSION = 2;
+/**
+ * Resolve the interactive shell.
+ *
+ * PowerShell is the Windows default because it is the interpreter the tool shells already use
+ * and it is present on every supported Windows; `ComSpec` is the fallback rather than the
+ * choice. POSIX hosts use the login shell the user selected.
+ */
+export function terminalShell() {
+    if (process.platform === 'win32') {
+        const powershell = join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+        if (existsSync(powershell))
+            return powershell;
+        return process.env.ComSpec ?? 'cmd.exe';
+    }
+    return process.env.SHELL || '/bin/bash';
+}
+function dimension(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < MIN_DIMENSION || value > 500)
+        throw new Error(`${name} must be an integer from ${MIN_DIMENSION} to 500`);
+    return value;
+}
+export class TerminalManager {
+    callbacks;
+    terminals = new Map();
+    /** Set once the manager has been closed, so a late open cannot outlive the shutdown that closed it. */
+    closed = false;
+    constructor(callbacks) {
+        this.callbacks = callbacks;
+    }
+    open(options) {
+        // A request that was waiting on its own workspace lookup when the engine shut down would otherwise
+        // spawn a shell after `closeAll()` had already finished, leaving the process and its listeners
+        // alive with nothing left that would ever close them.
+        if (this.closed)
+            throw new Error('The engine is shutting down');
+        if (this.terminals.size >= MAX_TERMINALS)
+            throw new Error(`At most ${MAX_TERMINALS} terminals can be open at once`);
+        const cols = dimension(options.cols, 80, 'cols'), rows = dimension(options.rows, 24, 'rows');
+        const shell = terminalShell();
+        const id = randomUUID();
+        const terminal = pty.spawn(shell, [], { name: 'xterm-256color', cwd: options.cwd, cols, rows, env: { ...process.env } });
+        const entry = {
+            id, shell, cwd: options.cwd, pty: terminal,
+            // Dispose both listeners together: a closed terminal that kept its exit listener would
+            // report the death of a session the client already forgot.
+            disposeData: terminal.onData(chunk => this.callbacks.data(id, chunk)),
+            disposeExit: terminal.onExit(({ exitCode, signal }) => { this.forget(id); this.callbacks.exit(id, exitCode, signal); }),
+        };
+        this.terminals.set(id, entry);
+        return { id, shell, cwd: options.cwd };
+    }
+    forget(id) {
+        const entry = this.terminals.get(id);
+        if (!entry)
+            return;
+        this.terminals.delete(id);
+        entry.disposeData.dispose();
+        entry.disposeExit.dispose();
+    }
+    require(id) {
+        if (typeof id !== 'string' || !this.terminals.has(id))
+            throw new Error('Unknown terminal');
+        return this.terminals.get(id);
+    }
+    write(id, data) {
+        if (typeof data !== 'string' || data.length > 100_000)
+            throw new Error('Terminal input must be a string of up to 100000 characters');
+        this.require(id).pty.write(data);
+    }
+    resize(id, cols, rows) {
+        const terminal = this.require(id);
+        try {
+            terminal.pty.resize(dimension(cols, 80, 'cols'), dimension(rows, 24, 'rows'));
+        }
+        catch (error) {
+            // A resize that loses the race with process exit is not a client error.
+            if (!/exited|closed|killed/i.test(error instanceof Error ? error.message : ''))
+                throw error;
+        }
+    }
+    /** Close one terminal and reap its process. Returns whether it was open. */
+    close(id) {
+        const terminal = this.terminals.get(id);
+        if (!terminal)
+            return false;
+        this.forget(terminal.id);
+        try {
+            terminal.pty.kill();
+        }
+        catch { /* The process may have already exited. */ }
+        return true;
+    }
+    /** Hold one shell's output back; a request for a terminal that is gone is a no-op. */
+    pause(id) {
+        try {
+            this.terminals.get(id)?.pty.pause();
+        }
+        catch { /* The process may have exited first. */ }
+    }
+    /** Let a held shell produce output again. */
+    resume(id) {
+        try {
+            this.terminals.get(id)?.pty.resume();
+        }
+        catch { /* The process may have exited first. */ }
+    }
+    /**
+     * Close every open terminal and report how many were closed.
+     *
+     * A client that reattaches after a renderer reload has no way to name the terminals the previous
+     * one left behind, and the ids it does hold are gone with it: closing them is how the engine's slots
+     * come back instead of being held by shells nobody can see or reach.
+     */
+    closeAll() {
+        const ids = [...this.terminals.keys()];
+        for (const id of ids)
+            this.close(id);
+        return ids.length;
+    }
+    /** Close every terminal and finish the manager: nothing it spawns afterwards would be reaped. */
+    shutdown() {
+        this.closed = true;
+        this.closeAll();
+    }
+}

package/dist/src/app-server/workspace.d.ts

@@ -0,0 +1,247 @@
+import type { Config, McpServerConfig } from '../config.js';
+import type { AppServerBranchList, AppServerBundle, AppServerGitStatus, AppServerRunSummary, AppServerTreeEntry } from './protocol.js';
+/**
+ * Resolve a client-supplied relative path inside the workspace, without following the final component.
+ *
+ * The containment check is the same lexical one `resolveInside` starts with; what is left out is the
+ * canonicalization, for the callers that need the name the client chose rather than the file it points
+ * at (a Git pathspec, for one).
+ */
+export declare function resolveLexicalInside(root: string, name: unknown): Promise<string>;
+/**
+ * Resolve a client-supplied relative path inside the workspace.
+ *
+ * The lexical check runs before `realpath`, so a path that escapes through `..` never reaches the
+ * filesystem, and the canonical check runs after, so a symlink or junction that leaves the
+ * workspace is refused even when its name looked local.
+ */
+export declare function resolveInside(root: string, name: unknown): Promise<string>;
+export declare function workspaceRoot(value: unknown): Promise<string>;
+/**
+ * List one directory level or a bounded subtree.
+ *
+ * A tree panel asks for one level at a time, so the default walk stops at the requested directory
+ * and only the opt-in deep form recurses; either way directories come before files and both sort
+ * by name, which keeps a level stable between refreshes.
+ */
+export declare function readTree(root: string, options?: {
+    path?: unknown;
+    depth?: unknown;
+}): Promise<{
+    path: string;
+    entries: AppServerTreeEntry[];
+    truncated: boolean;
+}>;
+/**
+ * Read one text file with a byte cap.
+ *
+ * The cap is enforced on the read, not after it: stat gives the size, and a large file is read
+ * through a bounded handle so opening a multi-gigabyte artifact cannot allocate it in full just to
+ * hand back its first half megabyte. Binary detection keeps a NUL byte from reaching a text view.
+ */
+export declare function readWorkspaceFile(root: string, name: unknown): Promise<{
+    content: string;
+    truncated: boolean;
+    binary: boolean;
+    size: number;
+}>;
+/**
+ * Working-tree status through the `git` executable.
+ *
+ * Startup metadata deliberately avoids running workspace-controlled helpers; a user-opened Changes
+ * panel is the opposite case, where the repository's own Git is the authority and the call is
+ * explicit. Arguments are fixed (no shell, no interpolation) and the call is time bounded.
+ *
+ * Paths come from `-z` output rather than the default: porcelain quotes names containing non-ASCII
+ * or control characters in C style, and a client that treated the quoted form as a path could not
+ * open the file it names. With `-z` each record is NUL terminated and renames carry the source in a
+ * following field, so no path has to be decoded.
+ */
+export declare function gitStatus(root: string, options?: {
+    maxBytes?: number;
+}): Promise<AppServerGitStatus>;
+/**
+ * The local branches of a repository, and the one the working tree is on.
+ *
+ * `refs/heads` is read directly rather than through `git branch`, whose listing in a detached HEAD
+ * also contains a pseudo-entry naming the commit — a name no client could check out. The branch the
+ * working tree is on is asked separately because a detached HEAD has none, and "absent from the
+ * listing" would otherwise be indistinguishable from a branch that only does not exist yet.
+ * Remote-tracking refs are left out: landing on one needs a tracking decision — which local branch
+ * follows it — that this request cannot express.
+ */
+export declare function listBranches(root: string): Promise<AppServerBranchList>;
+/**
+ * Switch the working tree to a branch, creating it when asked.
+ *
+ * The name is a Git ref name and Git judges it, after the cases that would make it mean something
+ * other than the branch typed are refused here: a leading dash would reach the command as an option,
+ * and `@{` is resolved by `check-ref-format --branch` against the reflog — a way to name a different
+ * branch than the one in the request. Nothing else about the name is guessed; Git's own refusal is
+ * what the caller reports, because it names the reason (no such branch, a working tree that would
+ * lose changes) better than a rule kept in sync here could.
+ */
+export declare function checkoutBranch(root: string, options: {
+    branch?: unknown;
+    create?: unknown;
+}): Promise<{
+    branch: string;
+}>;
+/**
+ * A diff for one path or the whole tree.
+ *
+ * `base` names what the diff is taken against: the working tree alone (unstaged changes, Git's
+ * default) or `head`, which is what a per-file view wants because it includes staged and unstaged
+ * changes together. Untracked files have no diff at all and are read as content by the client.
+ */
+export declare function gitDiff(root: string, options?: {
+    path?: unknown;
+    staged?: unknown;
+    base?: unknown;
+}): Promise<{
+    diff: string;
+    truncated: boolean;
+}>;
+/** What a capped command produced, including the parts a caller has to judge for itself. */
+export interface CollectedOutput {
+    /** The decoded standard output, up to the cap. */
+    text: string;
+    truncated: boolean;
+    /** The exit code, or `null` when the command was killed rather than exiting. */
+    code: number | null;
+    /** Standard error, so a caller can tell one refusal from another. */
+    failure: string;
+}
+/**
+ * Run a command, keeping at most `cap` bytes of its standard output.
+ *
+ * Exported for the streaming test: the split it guards against is a property of pipe reads, which a
+ * test can only produce by driving this collector directly. Rejection is reserved for a command that
+ * never ran or never finished; what it exited with is the caller's business, because the same exit is
+ * an empty answer for one command and a real failure for another.
+ */
+export declare function collectCapped(program: string, args: string[], cap: number, timeoutMs: number): Promise<CollectedOutput>;
+export declare function listRuns(directory: string, limit?: unknown): Promise<AppServerRunSummary[]>;
+/**
+ * Read one run's result and its journal.
+ *
+ * The slice returned is the *newest* part of the journal, because that is what a detail view is read
+ * for — the run's latest activity, with tool calls whose results arrived, rather than the opening
+ * events of a run whose outcome the record already reports. Reading starts at the end of the file, so
+ * a journal larger than the cap costs what the slice needs and not what the file holds, and
+ * `truncated` says older events exist beyond it so a client can label the slice instead of presenting
+ * it as the whole journal.
+ */
+export declare function readRun(directory: string, id: unknown): Promise<{
+    result: unknown;
+    events: unknown[];
+    truncated: boolean;
+}>;
+/**
+ * Where one run's stored result record lives, and whether it holds a finished trajectory.
+ *
+ * Saving a trajectory as JSON and showing it in the file manager both need the file itself rather than its
+ * contents, and this home is the only thing that knows where its records go — so the answer is the engine's
+ * own path plus whether it is actually there. A run whose record was never written, or has since been
+ * deleted, is answered with `exists: false` rather than a throw: "there is nothing to save yet" is a control
+ * the client holds back, not a failure it reports. The id is validated by the same rule every other run read
+ * uses, so a crafted id cannot name a file outside this home's `runs` directory.
+ *
+ * A running attempt's open record answers `exists: false` as well. The record is written the moment the run
+ * starts and finalization rewrites it in place, so its presence is not a trajectory being finished — a copy
+ * taken mid-rewrite can be half of two records. The stat alone used to call that file exportable; reading it
+ * is what lets the answer match what the document is.
+ */
+export declare function runRecordFile(directory: string, id: unknown): Promise<{
+    path: string;
+    exists: boolean;
+}>;
+/**
+ * Where a session's trajectory log lives — the per-session mirror of `runs.files`.
+ *
+ * A session trajectory is append-only, but an independent shell read while the engine is
+ * appending a large JSONL line can end mid-record. Withhold the export action while an open-run
+ * claim exists for this session, including a live run in another engine. Finalization flushes
+ * the trajectory before clearing the claim, so a finished session becomes available only after
+ * all its records are written. The shell additionally guards snapshots against an append that
+ * begins after this lookup. Missing files return `exists: false`; genuine I/O failures surface
+ * to the caller so it can keep the unrelated run-record controls usable.
+ */
+export declare function sessionTrajectoryFile(directory: string, id: unknown): Promise<{
+    path: string;
+    exists: boolean;
+}>;
+/** One record of a session's trajectory log, as the reader hands it over. */
+export interface SessionTrajectoryRecord {
+    /** The record's kind: `run.started`, `model.request`, `runtime.event`, and so on. */
+    type: string;
+    /** When the record was written. */
+    time: string;
+    /** Every other field of the record, in the order the log wrote it. */
+    data: Record<string, unknown>;
+}
+/** One page of a session's trajectory log. */
+export interface SessionTrajectoryPage {
+    /** Where the log lives, so a reader can name the file it is showing. */
+    path: string;
+    /** Whether the session has a log at all. */
+    exists: boolean;
+    /** The line this page starts at, counted from the beginning of the log. */
+    offset: number;
+    /** The line the next page starts at: the page's own cursor into the log. */
+    nextOffset: number;
+    /** How many records this page carries. */
+    count: number;
+    /** How many records the log holds. A truncated read counts only what it saw. */
+    total: number;
+    records: SessionTrajectoryRecord[];
+    /** The log holds records past this page. */
+    hasMore: boolean;
+    /** The log was longer than the read's budget, so the count is a lower bound. */
+    truncated: boolean;
+}
+/**
+ * Read one page of a session's trajectory log.
+ *
+ * The log is the session's own debug file: every run and every resume appends to it, so it holds the
+ * whole conversation — each prompt, each model call, each runtime event, in the order they happened.
+ * A client reads it the way it reads a long document, one page at a time, and the page says how much
+ * of the log it did not carry so the reader can say so rather than present a slice as the whole.
+ *
+ * The records are read in the order the log wrote them, from the beginning: a debugging reader wants
+ * the first prompt as much as the last one. The scan continues past the page to count what the log
+ * holds, so the reader can say "record 200 of 3,412" instead of guessing.
+ *
+ * The page's position in the log is a **line**, and the page answers with the line the next one
+ * starts at. A reader that asked for a page past the end of what one read can cover is answered
+ * from where the last page stopped rather than from the beginning, so the rest of a long log stays
+ * reachable page by page.
+ *
+ * A log that is still being appended to is read as it stands. The engine never rewrites one, so a
+ * record that is half-written is a torn line and is skipped rather than guessed at.
+ *
+ * `folder` names which of the home's logs to read: the engine's `trajectories`, or the
+ * `browser-trajectories` the CLI's browser workspace records its own runs to.
+ */
+export declare function readSessionTrajectory(directory: string, id: string, offset?: unknown, limit?: unknown, folder?: 'trajectories' | 'browser-trajectories'): Promise<SessionTrajectoryPage>;
+/**
+ * One line describing a configured MCP server, without anything that authenticates it.
+ *
+ * A stdio command line can carry `--token <value>` and an HTTP URL can carry a query string; both are
+ * permitted by the configuration schema, and both reach this renderer's Settings view. Only the
+ * command itself and the URL's scheme, host, and path are reported, matching the deliberate omission
+ * of MCP environment and header values.
+ */
+export declare function summarizeMcpServer(server: McpServerConfig): string;
+/** Installed skills, plugins, and configured MCP servers. Secrets in env/headers are never included. */
+export declare function listExtensions(config: Config, signal?: AbortSignal, directory?: string): Promise<{
+    skills: AppServerBundle[];
+    plugins: AppServerBundle[];
+    mcpServers: {
+        id: string;
+        transport: string;
+        summary: string;
+        enabled: boolean;
+    }[];
+    notices: string[];
+}>;