@sheetxl/mcp 0.0.0-stage → 0.8.0-beta.15

package/types/src/SessionRegistry.d.ts

@@ -0,0 +1,630 @@
+import { IModule, IWorkbook } from '@sheetxl/sdk';
+import { RunResultLike } from './lib/runReport.ts';
+import { RelayClient } from './relay.ts';
+/**
+ * A session's backing tells the agent (and routing) where the SDK instance lives:
+ *  - `sandbox`  — server-owned, headless, in-process. Created on demand; an agent may hold many.
+ *  - `attended`   — owned by a client UI (a VS Code webview today), reached over the relay.
+ *
+ * `origin` is orthogonal to backing: how the session was seeded.
+ */
+export interface SessionInfo {
+    id: string;
+    name: string;
+    kind: 'sandbox' | 'attended';
+    origin: 'blank' | 'file' | 'fork';
+    /** Whether the session has a live UI view (presence/selection only applies when true). */
+    hasView: boolean;
+    /**
+     * Where the workbook came from — the file for `origin: 'file'` (and, when the client UI reports
+     * it, for an attended session's document).
+     *
+     * @remarks
+     * A name is not an identity. `list_sessions` showed `named-formulas.xlsx` and nothing else, so
+     * two workbooks of the same name in different directories were one row twice, and an agent
+     * choosing between them was guessing. Attended ids are now DERIVED from this path (stable across
+     * reloads), so the path is the identity's source rather than its only survivor — and still the
+     * handle for untitled/legacy sessions whose ids are per-load.
+     */
+    originPath?: string;
+    /**
+     * For `origin: 'fork'`, the session this was cloned from.
+     *
+     * @remarks
+     * Forks used to be indistinguishable: every one was named `Fork`, with no record of its source,
+     * so three open experiments were three identical rows. Applying the wrong one to the original is
+     * the failure that costs real work.
+     */
+    originSource?: string;
+    /** Current transaction head — the value to pass as `original_commit_id` for a drift-guarded write. */
+    headCommitId?: string;
+    /** The last-touched session — what the {@link ACTIVE_SESSION} token resolves to. */
+    active?: boolean;
+    /**
+     * When the session's workbook was (re)loaded — its **history epoch**, epoch-ms.
+     *
+     * @remarks
+     * Attended ids are path-derived and survive reloads/restarts, so the id no longer signals "your
+     * history is gone" by changing. This does: commit ids are scoped to an epoch, and this timestamp
+     * moving under a constant id is how the registry detects (and the events channel reports) that
+     * the commit/undo history was reset. For a sandbox it is simply the creation time.
+     */
+    openedAt?: number;
+}
+/** How a sandbox was seeded. */
+export type SandboxOrigin = 'blank' | 'file' | 'fork';
+/**
+ * The one `session_id` that is not an id: resolves to the sole open session, or to the unambiguous
+ * active one. Deliberately absent from every tool description — `session_id` is required so that a
+ * write can never land on a workbook the agent did not name, and a documented shortcut would be
+ * the default by another spelling. It exists for hand-driven tool testing, where naming a session
+ * that was just created is ceremony.
+ */
+export declare const ACTIVE_SESSION = "active";
+/**
+ * Settles a sandbox's origin from what the caller actually supplied: a `path` means `file`, a
+ * `source` means `fork`, neither means `blank`. An explicit `origin` is honored, and checked
+ * against the arguments — "origin 'file' with no path" and "origin 'blank' with a path" are the
+ * same confusion, so both are refused rather than half-obeyed.
+ */
+export declare function inferSandboxOrigin(origin: SandboxOrigin | undefined, opts: {
+    path?: string;
+    source?: string;
+}): SandboxOrigin;
+/**
+ * A session that is no longer usable, and why — the tier above commits.
+ *
+ * @remarks
+ * A dead id used to resolve to nothing, which reads identically whether it never existed, was
+ * closed, or came back under a new number. Kept in a small ring buffer, so an agent holding a stale
+ * id is answered rather than left to experiment.
+ */
+export interface ClosedSession {
+    id: string;
+    name: string;
+    /** The document it was showing, when known — the key a reload is matched on. */
+    path?: string;
+    kind: 'sandbox' | 'attended';
+    closedAt: number;
+    /**
+     * `closed` — this server disposed a sandbox on request.
+     * `gone` — an attended workbook stopped being reported by the client UI.
+     * `reloaded` — an attended workbook came back under a new id (see {@link replacedBy}). With
+     * path-derived ids this is the untitled/legacy case only — a file-backed workbook returns under
+     * the SAME id (its tombstone is simply withdrawn; see the `returned` event).
+     */
+    reason: 'closed' | 'gone' | 'reloaded';
+    /** The id that took over, when a workbook was reloaded rather than closed. */
+    replacedBy?: string;
+    /** Where it was when it died — so an agent can tell whether it lost work. */
+    headCommitId?: string;
+    /** Tool-authored commits it held. Zero for an untouched session; nothing was lost with it. */
+    agentCommits?: number;
+}
+/**
+ * One attended-session lifecycle change, observed but not yet reported to the agent.
+ *
+ * @remarks
+ * An agent perceives the world only through tool results — it does not poll `list_sessions`, and a
+ * protocol notification never reaches the model. So changes the user makes (opening, closing,
+ * reloading a workbook) are queued here and delivered at the top of the NEXT tool result, whatever
+ * it is. Until this existed, the diff was computed on every call and shown to no one: an agent
+ * learned "the workbook closed" only by failing against its dead id.
+ *
+ * A departure holds the {@link ClosedSession} BY REFERENCE because `reconcileAttended` upgrades a
+ * tombstone in place when the matching arrival lands (`gone` → `reloaded`) — rendering at delivery
+ * time sees the upgrade, so a same-poll reload reads as one reload, not a close plus an open.
+ *
+ * Only USER actions are recorded. Sandbox create/close are the agent's own calls — their results
+ * already said what happened — and a server restart is the stale-state notice's job (`instances.ts`).
+ *
+ * `returned` and `reset` exist because attended ids are path-derived and STABLE: a closed file
+ * reopens under the same id (`returned` — its tombstone is withdrawn), and a reload keeps the id
+ * while rebuilding the workbook (`reset` — detected by `openedAt` moving under a constant id).
+ * In both, the fact the agent must hear is not "the id changed" (it did not) but "the commit/undo
+ * history you may be holding ids into is gone".
+ */
+export type SessionEvent = {
+    kind: 'departed';
+    tomb: ClosedSession;
+} | {
+    kind: 'arrived';
+    info: SessionInfo;
+} | {
+    kind: 'returned';
+    info: SessionInfo;
+} | {
+    kind: 'reset';
+    info: SessionInfo;
+};
+/**
+ * Normalized outcome of a macro run, shared by sandbox (in-process) and attended (relayed) sessions.
+ * Exactly one of `drift` or `result` is set. The tool layer turns this into the MCP report.
+ */
+export interface RunOutcome {
+    /** Set when `originalCommitId` did not match the session head — the write was NOT applied. */
+    drift?: {
+        expected: string;
+        actual?: string;
+    };
+    /** The run result when not a drift (may itself be a compile/runtime failure). */
+    result?: RunResultLike;
+    logs: string;
+}
+/** One row of a session's commit log (newest first). JSON-safe — crosses the relay as-is. */
+export interface CommitEntry {
+    id: string;
+    description: string | null;
+    /** Who wrote it, or `null` when unattributed. Commits an agent did not write mean the session moved under it. */
+    author: string | null;
+    timestamp: number;
+}
+export interface ListCommitsOptions {
+    /** Maximum entries, newest first. */
+    limit?: number;
+}
+export interface RunOptions {
+    description?: string;
+    /** Drift guard: reject (without applying) if the session head differs from this. */
+    originalCommitId?: string;
+    /**
+     * Arguments exposed to the macro as `ctx.args` — the MCP half of the CLI's `-- <args…>`, so the
+     * same parameterized script runs on either transport without editing its source.
+     */
+    args?: Record<string, any>;
+    /**
+     * Report options for the rendered result — the MCP half of the CLI's `--md.<key>=<value>`.
+     *
+     * @remarks
+     * String-valued and parsed by `@sheetxl/query`, so both transports read one vocabulary. The
+     * agent-facing reason to reach for it is the same one a person has at a terminal: a workbook
+     * report over a heavily formatted sheet is dozens of region sections, and `{ features: "fill" }`
+     * is the difference between an answer and a haystack.
+     */
+    md?: Record<string, string>;
+}
+/**
+ * An ephemeral grid highlight — one or more ranges marked in a session's view. Never a commit (see
+ * lane1-target-state decision #7). Declarative: each call REPLACES the prior highlight, so an empty
+ * `ranges` clears it. Only meaningful for sessions with `hasView === true`; a no-op on headless
+ * sandboxes.
+ */
+export interface Highlight {
+    /**
+     * The marked ranges, **in review order** — empty clears the highlight.
+     *
+     * @remarks
+     * Order is meaningful, not incidental: the UI walks this list (a counter and next/previous over
+     * the set), so index 0 is the first thing the user is taken to. A findings list is therefore
+     * ranked by the agent — most severe or most confident first — and not left in whatever order the
+     * scan happened to produce.
+     *
+     * Each entry carries its own `label` because that is what a walked list needs: one label across
+     * seven findings shows the same text at all seven stops, which is the least useful moment for it.
+     */
+    ranges: HighlightRange[];
+    /** Visual intent — drives styling (working cursor / finding / candidate question). */
+    intent: 'working' | 'finding' | 'question';
+}
+/** One marked range and what it means. */
+export interface HighlightRange {
+    /** Sheet-qualified range (e.g. "Sheet1!B2:D8"). */
+    range: string;
+    /** Short label for THIS range — what the user reads when they arrive at it. */
+    label?: string;
+}
+/**
+ * What actually happened to a {@link Highlight} — so the caller is never told it marked cells it
+ * did not.
+ *
+ * @remarks
+ * Two separate false positives lived here: a headless sandbox silently discarded the call, and a
+ * malformed address was accepted and only failed later at render time. Both reported success.
+ * `ranges` is what the grid RESOLVED (sheet-qualified, normalized), not what was asked for, so the
+ * reply stays observable in the same way `run` reports the form it chose.
+ */
+export interface HighlightResult {
+    /** The addresses a grid actually marked, as it resolved them. Empty when the highlight was cleared. */
+    ranges: string[];
+    /**
+     * `true` when a grid applied it. `false` on a headless sandbox — nothing was highlighted and
+     * nothing could be, which the caller must be told rather than shown an unbacked success.
+     */
+    applied: boolean;
+}
+/**
+ * A grid prompt — the human-facing step of an MCP `prompt` task. Shown in the session's grid; the
+ * answer flows back through the relay. Only meaningful for sessions with a view (rejected on headless
+ * sandboxes).
+ *
+ * @remarks
+ * One prompt is one dialog. It holds one question or several, which the user answers one step at a
+ * time and which come back together. At most one prompt is pending per session.
+ */
+export interface PromptSpec {
+    questions: PromptQuestion[];
+}
+/** One question of a {@link PromptSpec}. */
+export interface PromptQuestion {
+    /** What the answer comes back under. */
+    id: string;
+    /** A short name for the question's tab in the dialog. */
+    header?: string;
+    message: string;
+    /**
+     * Empty for an acknowledge step (message and continue / close only). `description` is a second,
+     * quieter line under the label.
+     */
+    options: {
+        id: string;
+        label: string;
+        description?: string;
+    }[];
+    /**
+     * The single range the question is ABOUT — the step is shown at those cells.
+     *
+     * @remarks
+     * Omitted, the step is a centred dialog rather than being anchored somewhere arbitrary. It
+     * deliberately does **not** fall back to the user's selection: the selection is theirs, it is
+     * almost never the subject of the agent's question, and anchoring there asserts a relationship
+     * that does not exist.
+     */
+    range?: string;
+}
+/**
+ * One question's answer: the option chosen, or `text` when the user answered in their own words
+ * ("Other"). Neither is set for an acknowledged step.
+ */
+export interface PromptQuestionAnswer {
+    questionId: string;
+    optionId?: string;
+    text?: string;
+}
+/**
+ * The user's answer — elicitation-shaped (`accept`/`cancel`).
+ *
+ * @remarks
+ * `answers` is in question order. On `accept` every question is answered; on `cancel` it holds the
+ * questions answered before the user dismissed the prompt (possibly none).
+ */
+export interface PromptResult {
+    action: 'accept' | 'cancel';
+    answers: PromptQuestionAnswer[];
+}
+/** Common write/read surface implemented by both sandbox and attended sessions. */
+export interface Session {
+    /**
+     * The id every tool routes by — what `run` echoes back so the agent can read which workbook its
+     * code ran against. Defined for any session a tool call resolved; an attended session built
+     * without one (the synchronous logging path) routes to the relay's active workbook.
+     */
+    readonly id: string | undefined;
+    /**
+     * Where this session's SDK instance lives — in-process (`sandbox`) or in a client UI reached over
+     * the relay (`attended`). Both implementations already carried it; it is on the interface so a
+     * caller holding a `Session` can attribute it (the tool log does) without a `list()` round-trip.
+     */
+    readonly kind: 'sandbox' | 'attended';
+    /**
+     * Execute a read tool from the shared `TOOLS` descriptor list (`@sheetxl/query`) against this
+     * session's live workbook, returning the descriptor's rendering. A sandbox runs it in-process;
+     * an attended session runs it in the webview — the only place its workbook lives.
+     */
+    runTool(name: string, args: Record<string, unknown>): Promise<string>;
+    /**
+     * Execute an already-compiled module as one undoable commit. Compilation (and snippet
+     * classification/wrapping) happens in the tool layer — see `prepareRun` — so both session kinds
+     * run the identical artifact.
+     */
+    run(module: IModule.JSON, opts: RunOptions): Promise<RunOutcome>;
+    revert(commitId: string): Promise<void>;
+    restore(commitId: string): Promise<void>;
+    /** The session's commit log, newest first — the ids `session_revert`/`session_restore` take. */
+    listCommits(opts: ListCommitsOptions): Promise<CommitEntry[]>;
+    /**
+     * Mark ranges in the session's grid. Reports back what a grid actually resolved and marked —
+     * a headless sandbox has no view, and says so rather than reporting success.
+     */
+    highlight(highlight: Highlight): Promise<HighlightResult>;
+    /**
+     * Show a grid prompt and resolve when the user answers. `opts.signal` aborts the wait (and clears
+     * the grid prompt) — used for agent-side cancellation (`tasks/cancel`). Rejected on headless sandboxes.
+     */
+    prompt(spec: PromptSpec, opts?: {
+        signal?: AbortSignal;
+    }): Promise<PromptResult>;
+    /** Serialize the workbook to JSON — the fork/snapshot primitive (rides the relay's JSON channel). */
+    snapshot(): Promise<IWorkbook.JSON>;
+    /**
+     * Waits until no async function call (`IMAGE`, `STOCKHISTORY`) is waiting for an answer, so a
+     * {@link snapshot} taken next holds the answers rather than `#BUSY!`. Gives up after `timeout`
+     * milliseconds. An attended session's workbook is the client's, and is not waited for.
+     */
+    whenAnswered(timeout: number): Promise<void>;
+    /**
+     * Write the workbook to disk and resolve the absolute path written.
+     *
+     * @param path Absolute destination. Omitted, or the session's own file, is a Save; any other
+     *   path is a Save As.
+     */
+    save(path: string | undefined, opts?: SaveOptions): Promise<string>;
+}
+/** Options for {@link Session.save}. */
+export interface SaveOptions {
+    /** Replace an existing file other than the session's own. */
+    overwrite?: boolean;
+    /** Each feature the destination format cannot hold; the session still has it. */
+    onWarning?: (message: string) => void;
+}
+/**
+ * A server-owned, in-process workbook. This is the headless side of the session registry — the
+ * "sandbox" backing. It owns the `IWorkbook` directly, so macros run in-process with no relay.
+ */
+export declare class SandboxSession implements Session {
+    readonly id: string;
+    readonly name: string;
+    readonly origin: 'blank' | 'file' | 'fork';
+    private readonly workbook;
+    private readonly lineage;
+    readonly kind: "sandbox";
+    /** Creation time — the sandbox's `openedAt`. In-memory, so its history epoch IS its lifetime. */
+    private readonly createdAt;
+    private constructor();
+    static create(id: string, origin: 'blank' | 'file' | 'fork', opts: {
+        path?: string;
+        name?: string;
+        json?: IWorkbook.JSON;
+        source?: string;
+        sourceName?: string;
+    }): Promise<SandboxSession>;
+    snapshot(): Promise<IWorkbook.JSON>;
+    whenAnswered(timeout: number): Promise<void>;
+    /**
+     * Saves the session's own workbook. A Save As moves the session to the new file, so the next
+     * plain save writes there.
+     */
+    save(path: string | undefined, opts?: SaveOptions): Promise<string>;
+    /** Dispose the in-memory workbook. No further operations are valid after this. */
+    close(): void;
+    /** Current transaction head id — `undefined` only if the store has no commits yet. */
+    getHeadCommitId(): string | undefined;
+    /**
+     * How many commits in this sandbox were written through a tool — what an agent loses if the
+     * session goes away unnoticed.
+     *
+     * @remarks
+     * Agent-authored only. The raw log counts the workbook's initial state as an entry, so an
+     * untouched sandbox would report "1 commit" and a tombstone would claim work was lost where none
+     * existed. The number exists to answer "did I lose anything", and only these commits can be lost.
+     */
+    agentCommitCount(): number;
+    info(): SessionInfo;
+    runTool(name: string, args: Record<string, unknown>): Promise<string>;
+    run(module: IModule.JSON, opts: RunOptions): Promise<RunOutcome>;
+    revert(commitId: string): Promise<void>;
+    restore(commitId: string): Promise<void>;
+    listCommits(opts: ListCommitsOptions): Promise<CommitEntry[]>;
+    highlight(_highlight: Highlight): Promise<HighlightResult>;
+    prompt(_spec: PromptSpec, _opts?: {
+        signal?: AbortSignal;
+    }): Promise<PromptResult>;
+}
+/**
+ * An attended session — owned by a client UI (a VS Code webview). All operations forward over the relay
+ * to the webview, which executes them against the live `IWorkbook`. `id` is the workbook id; when
+ * `undefined`, the relay routes to its active workbook.
+ */
+export declare class AttendedSession implements Session {
+    private readonly relay;
+    readonly id: string | undefined;
+    readonly kind: "attended";
+    constructor(relay: RelayClient, id: string | undefined);
+    runTool(name: string, args: Record<string, unknown>): Promise<string>;
+    run(module: IModule.JSON, opts: RunOptions): Promise<RunOutcome>;
+    revert(commitId: string): Promise<void>;
+    restore(commitId: string): Promise<void>;
+    listCommits(opts: ListCommitsOptions): Promise<CommitEntry[]>;
+    highlight(highlight: Highlight): Promise<HighlightResult>;
+    prompt(spec: PromptSpec, opts?: {
+        signal?: AbortSignal;
+    }): Promise<PromptResult>;
+    snapshot(): Promise<IWorkbook.JSON>;
+    whenAnswered(): Promise<void>;
+    /**
+     * The workbook lives in the client UI, so this writes a copy of it to `path`. The UI's workbook
+     * stays bound to its own file.
+     */
+    save(path: string | undefined, opts?: SaveOptions): Promise<string>;
+}
+/**
+ * The token identifying THIS server process, minted once at module load.
+ *
+ * @remarks
+ * Sandbox ids used to be `sandbox-<n>` off a process-local counter, which meant a restart handed
+ * `sandbox-1` to a different workbook — an agent that created a sandbox, lost the server, and then
+ * ran against `sandbox-1` could be answered confidently about the wrong file. That is strictly
+ * worse than an error, so the id carries who issued it.
+ *
+ * Time-ordered rather than purely random, because the ordering is what lets
+ * {@link SessionRegistry.explainUnknownId} separate an id from an EARLIER instance (a restart —
+ * sandboxes are in-memory and simply gone) from one issued by a CONCURRENTLY running server (another
+ * chat, or a duplicate registration — a different failure with a different fix). The trailing random character
+ * breaks the tie when two servers start in the same second, which duplicate registrations do.
+ */
+export declare const INSTANCE_TOKEN: string;
+/**
+ * The single source of truth for open sessions. Replaces the old global connected/direct mode:
+ * the server ALWAYS owns sandboxes in-process, and ADDITIONALLY surfaces attended sessions from the
+ * relay when one is attached (the relay is the attended-session provider, not a mode selector).
+ *
+ * Routing: a `session_id` that resolves to a local sandbox executes in-process; otherwise it is a
+ * attended session and forwards to the relay.
+ */
+export declare class SessionRegistry {
+    private readonly discover;
+    private readonly sandboxes;
+    private activeId;
+    private counter;
+    private readonly startedAt;
+    /** The live relay, once discovered. Mutable: a client UI can start, stop and restart under us. */
+    private relayClient;
+    private lastProbeAt;
+    private probing;
+    /** Sessions that have died, oldest first. Capped — this is a hint, not an audit trail. */
+    private readonly closed;
+    /** The last SUCCESSFULLY observed attended list, for the departure/arrival diff. */
+    private lastAttended;
+    /** Lifecycle changes observed but not yet delivered on a tool result — see {@link SessionEvent}. */
+    private pendingEvents;
+    /** Whether the attended list has ever been successfully read (the diff baseline exists). */
+    private attendedObserved;
+    /** Whether at least one tool result has gone out — see the baseline rule in {@link reconcileAttended}. */
+    private deliveredOnce;
+    private static readonly CLOSED_LIMIT;
+    private static readonly EVENT_LIMIT;
+    /** How long a departed workbook stays eligible to be recognized as a reload rather than a close. */
+    private static readonly RELOAD_WINDOW_MS;
+    /**
+     * Discovery is a function rather than a pre-resolved client because presence CHANGES: the old
+     * shape resolved it once at startup, so a workbook opened after the server was invisible forever,
+     * and a UI restart left a stale endpoint whose failures were swallowed into "no sessions open".
+     */
+    constructor(discover: () => Promise<RelayClient | null>);
+    /**
+     * Cooldown between negative probes. `discoverRelay` costs up to 2s against a stale lock, and a
+     * genuinely unattended server would otherwise pay that on every tool call.
+     */
+    private static readonly REDISCOVER_COOLDOWN_MS;
+    /** The relay, discovering one if we have none and the cooldown has passed. */
+    private getRelay;
+    /**
+     * Forget the current relay after a failed call — the endpoint is stale (the UI restarted onto a
+     * new port/token). The cooldown is cleared rather than started: the failure WAS the probe, and
+     * the point of dropping is to re-discover at the next opportunity.
+     */
+    private dropRelay;
+    /** Discover eagerly and report whether a relay is attached — for the startup log line. */
+    probeRelay(): Promise<boolean>;
+    /**
+     * The relay if one is ALREADY attached — never probes for one. For fire-and-forget side channels
+     * (the tool-call trace) that must add neither latency nor discovery cost to the call they are
+     * describing. A truly headless server has nowhere to send them anyway, and `info` — the required
+     * first call — has already discovered by the time there is anything interesting to say.
+     */
+    get attachedRelay(): RelayClient | null;
+    /**
+     * Whether a client UI is attached, as of the last discovery. Read AFTER {@link list} — it is what
+     * turns an empty session list from a dead end into "nothing is listening" or "nothing is open".
+     */
+    get relayAttached(): boolean;
+    /**
+     * Creates a sandbox. `origin` may be omitted — it is settled by {@link inferSandboxOrigin} from
+     * the arguments that were passed, which is also the check an explicit origin is held to.
+     */
+    createSandbox(origin: SandboxOrigin | undefined, opts?: {
+        path?: string;
+        name?: string;
+        source?: string;
+    }): Promise<SandboxSession>;
+    /** Resolves a sandbox by id, or the active sandbox when `id` is omitted. */
+    getSandbox(id?: string): SandboxSession | undefined;
+    /**
+     * Dispose a sandbox session. Attended (VS Code) sessions cannot be closed here — the UI owns their
+     * lifecycle — so a non-sandbox id is rejected.
+     *
+     * An id that IS sandbox-shaped but unknown gets the full explanation instead: "not a sandbox" is
+     * the one thing it definitely is not, and sending an agent to look for an attended session it will
+     * never find is the failure this whole pass exists to remove.
+     */
+    closeSandbox(id: string): Promise<void>;
+    /**
+     * Resolves any session for a tool call. Precedence: a matching sandbox (or the active sandbox when
+     * `id` is omitted); otherwise, if a relay is attached, an attended session (the relay validates the id,
+     * and routes to its active workbook when `id` is omitted). Returns `undefined` when nothing matches.
+     *
+     * Sync and best-effort — it reads the last-known relay rather than discovering one. An id that is
+     * SHAPED like a sandbox never falls through to the relay: a dead sandbox id is a dead sandbox id,
+     * and handing it to the relay as a workbook id is how a lookup failure turns into an answer about
+     * the wrong workbook.
+     */
+    resolveSession(id?: string): Session | undefined;
+    /**
+     * Resolve the target session for a tool call, validating against the live session list and
+     * producing friendly errors. Unlike {@link resolveSession} (sync, internal), this:
+     *
+     *  - **requires** an `id` — an omitted one is refused with the open sessions listed, never
+     *    defaulted. A default here is how a write reaches the human's open workbook without the
+     *    agent ever naming it; the tool schemas require the field, and this is the backstop;
+     *  - **validates** a provided `id` — an unknown id throws "no session with id …" instead of
+     *    letting it fall through to the relay and surface a misleading "no workbook open" error;
+     *  - **auto-selects** only on the {@link ACTIVE_SESSION} token — the sole open session if there
+     *    is exactly one, else the unambiguous active session.
+     *
+     * Costs one relay round-trip (via {@link list}) per call when a relay is attached.
+     */
+    resolveForTool(id?: string): Promise<Session>;
+    /**
+     * Fold a successful attended-session observation into the closed log and the events queue.
+     *
+     * @remarks
+     * With path-derived ids the common cases are the QUIET ones: a reload keeps the id and only
+     * moves `openedAt` (a `reset`), and a closed file reopens under the id the agent already holds
+     * (a `returned`, which withdraws the tombstone). The id-SWAP machinery below them — a departure
+     * recorded as `gone`, upgraded to `reloaded` when a same-document arrival shows up under a
+     * different id, matched by path/name across polls — survives for the sessions that still re-mint:
+     * untitled workbooks and older clients. Both halves of a swap need not land in the same poll, so
+     * both orders are handled.
+     */
+    private reconcileAttended;
+    /** Queue an event for the next tool result, oldest evicted beyond the cap. */
+    private recordEvent;
+    /**
+     * Drain undelivered lifecycle events into the notice that rides the next tool result, or `null`
+     * when nothing changed. Call once per delivered result — draining IS the delivery.
+     *
+     * @remarks
+     * A same-batch reload arrives as two events (a departure upgraded to `reloaded`, and its
+     * arrival); they render as ONE line, because "Budget.xlsx was closed. Budget.xlsx was opened."
+     * invites the agent to mourn and re-plan when the only fact that matters is "your id changed".
+     * When the halves were delivered in different batches (the close was reported before the file
+     * came back), the arrival line does the repair instead: it names the dead id it replaces.
+     */
+    drainEventsNotice(): string | null;
+    /** Append to the ring buffer, newest last, oldest evicted. */
+    private remember;
+    /** Sessions that are no longer usable, newest first. */
+    listClosed(): ClosedSession[];
+    /**
+     * Why an id did not resolve — the whole point of this method existing.
+     *
+     * @remarks
+     * `No session with id X. No sessions are open.` covered four different situations (never existed
+     * / the user closed the workbook / the sandbox was closed / this server restarted), and an agent
+     * had to run experiments to tell them apart. Each of those has a different next move, so each
+     * gets its own sentence.
+     *
+     * The two "this instance" answers need no lifecycle log: an ordinal at or below the counter was
+     * necessarily issued by us, and only `session_close` removes an entry — so the arithmetic proves
+     * "closed" without recording anything.
+     */
+    /**
+     * The open sessions as a sentence, or — when there are none — which kind of none: a client UI
+     * with nothing open and no client UI at all have different next moves.
+     */
+    private describeOpen;
+    private explainUnknownId;
+    /** Materialize a {@link Session} from a {@link SessionInfo} row (sandbox instance or relayed attended). */
+    private sessionFor;
+    /**
+     * Merged view: attended sessions (from the relay, if attached) followed by local sandboxes.
+     *
+     * @remarks
+     * Two attempts, not one. A client UI that restarts comes back on a new port with a new token, so
+     * the first call after a restart fails against the stale endpoint — dropping it and re-discovering
+     * inside the SAME call is what makes the user's workbook reappear now rather than one tool call
+     * later. Falling through with sandboxes only is still the last resort, but it is now the answer
+     * to "nothing is listening", not to "we are holding a dead endpoint".
+     */
+    list(): Promise<SessionInfo[]>;
+}
+//# sourceMappingURL=SessionRegistry.d.ts.map

package/types/src/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map