@andorra-labs/code 0.0.0-stage → 0.1.5

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

@@ -0,0 +1,500 @@
+/**
+ * Wire contract for `andorra app-server --stdio`.
+ *
+ * The desktop client drives the runtime over newline-delimited JSON on stdio: one request per
+ * input line, one response per request, and any number of unsolicited events out. stdio keeps
+ * the engine parent-owned, so the transport needs no port, no token, and no listener policy;
+ * any client that can spawn a process can drive it, which is the client/runtime boundary the
+ * architecture decisions describe.
+ *
+ * Sequencing: responses are matched by `id`, never by order. A slow call (model discovery, a
+ * sign-in) is answered after later requests were accepted, so a client must not assume that
+ * response `n` belongs to request `n`. Events carry no `id` and never answer a request.
+ *
+ * The desktop project keeps a hand-written mirror of these shapes in
+ * `desktop/src/engine/protocol.ts`. `test/app-server.test.ts` locks the serialized payloads
+ * this file names, so a change here that the mirror misses fails a test rather than a build.
+ *
+ * Version: the desktop refuses an engine that does not speak exactly this version, so an RPC the
+ * client needs unconditionally must raise it. Version 2 added `sessions.setArchived`: an engine
+ * still on version 1 answers that call with `unknown-method`, and a rail that silently offered an
+ * archive it could not perform would fail the action far from the version check that explains it.
+ */
+export declare const APP_SERVER_PROTOCOL_VERSION = 2;
+/**
+ * What this engine can do beyond the methods and fields every engine on that version answers.
+ *
+ * The version is one number for the shapes that must hold for every installation on it; an additive
+ * optional field or a new method is not a version change, so a client needs something else to tell an
+ * engine that learned the feature from one that never did. A client must read an absent list as "nothing
+ * beyond the version" — that is what an engine built before this field sends.
+ *
+ * Some of them exist so a client is told before it writes: `providers.streamIdleTimeout` is a provider
+ * field an engine from before it drops on write while still answering success, so the window withholds
+ * the control — and refuses the write — unless the engine says it stores the field.
+ */
+/** run.start.runPermissions binds one attempt without changing the workspace permission default. */
+/** attachments.read returns one spooled image's bytes, so a window can preview a pasted image in
+ * the timeline and expand it; an engine without it renders the attachment chip's name alone. */
+/** providers.codexAccounts: a Codex entry may carry `codexAccount` and `codexEmail`, and an upsert
+ * retains both when a client omits them. An engine without it rebuilds a replaced entry from its
+ * own field list, so a save through it silently drops the account slot and points the provider at
+ * the default home's sign-in; a client that names a slot must refuse the write first. */
+/** providers.name: a provider entry may carry a display `name`, and an upsert retains the stored
+ * one when a client omits it. An engine without it rebuilds a replaced entry from its own field
+ * list, so a save through it silently drops the rename and every surface falls back to the id; a
+ * client that can show the field must refuse the write first. */
+export declare const APP_SERVER_CAPABILITIES: readonly ["run.start.runPermissions", "automations", "providers.models", "providers.test", "providers.test.model", "providers.streamIdleTimeout", "providers.modelContextWindows", "providers.name", "providers.claude", "providers.opencodeGo", "providers.discover.draft", "providers.codexAuth", "providers.codexAuth.logout", "providers.codexAccounts", "providers.anthropicConsole", "run.resume.direction", "run.steer", "run.overrideAllNodes", "run.setModel", "run.start.continueSession", "remote.owner.projects", "remote.workspaces.probe", "remote.engine.relay", "remote.hosting.device.grant", "extensions.manage", "extensions.resources", "skills.invoke", "mcp.manage", "runs.files", "sessions.files", "account.profile", "sessions.stats", "sessions.usage", "config.analytics", "config.analytics.planGate", "sessions.trajectory", "config.externalSubagent", "config.decisions", "browser.view", "attachments.read", "config.general", "sessions.pullRequest", "browser.view.go"];
+/** One client call. `params` is omitted only for calls that take no arguments. */
+export interface AppServerRequest {
+    id: number | string;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface AppServerSuccess {
+    id: number | string;
+    result: unknown;
+}
+export interface AppServerFailure {
+    id: number | string;
+    error: {
+        code: AppServerErrorCode;
+        message: string;
+    };
+}
+export type AppServerResponse = AppServerSuccess | AppServerFailure;
+export interface AppServerEvent {
+    event: string;
+    data: Record<string, unknown>;
+}
+/** The handshake payload: the `ready` event, and the same fields plus `running` for `host.info`. */
+export interface AppServerHostInfo {
+    protocol: number;
+    engine: string;
+    version: string;
+    /**
+     * The configuration home (`ANDORRACODE_HOME`), where sessions, runs, and the registry live.
+     *
+     * Not to be confused with `userHome`: this one holds Andorra's own files, that one is the
+     * person's home folder and is what the desktop offers as the workspace for a task that belongs
+     * to no project.
+     */
+    home: string;
+    /** The operating system's home folder for the account running this engine. */
+    userHome: string;
+    platform: string;
+    arch: string;
+    node: string;
+    /** Whether a run owns this engine. Only `host.info` reports it; `ready` precedes any run. */
+    running?: boolean;
+    capabilities: readonly string[];
+}
+/**
+ * Failure vocabulary.
+ *
+ * These codes are the contract a client branches on; `message` is display text and may change.
+ * `engine-busy` is the one state the TUI never has to express: the desktop asks for a second run
+ * while this engine already owns one, and it is what tells that client to use another engine
+ * instead of waiting. `busy` stays for a write that lost a race with another writer — a run refused
+ * for one of those reasons is a failure to report, not a reason to start a second process.
+ * `nothing-to-continue` is an answer, not a failure: the stopped attempt a `run.resume` named has
+ * already run everything its journal records, so the client that sent a message with the resume may
+ * turn it into the new task it has to become — the one refusal a fallback is allowed to act on.
+ */
+export type AppServerErrorCode = 'invalid-request' | 'unknown-method' | 'invalid-params' | 'busy' | 'engine-busy' | 'not-found' | 'login-required' | 'auth' | 'storage' | 'network' | 'cancelled' | 'internal' | 'remote' | 'nothing-to-continue';
+/** The permission modes a project can hold, mirroring `src/permissions.ts`. */
+export type AppServerPermissionMode = 'read-only' | 'ask-for-approval' | 'approve-for-me' | 'full-access';
+/** Verified official Codex account/catalog, never its credentials or token payloads. */
+export interface AppServerProviderAuth {
+    state: 'signedOut' | 'starting' | 'waiting' | 'signedIn' | 'cancelled' | 'error';
+    reason?: 'unavailable' | 'timeout' | 'denied' | 'connectionClosed' | 'unsupported' | 'busy' | 'unverified' | 'catalogUnavailable' | 'logoutFailed';
+    attemptId?: string;
+    email?: string;
+    planType?: string;
+    models?: Array<{
+        id: string;
+        isDefault?: boolean;
+        contextWindow?: number;
+    }>;
+    message?: string;
+    /** Only returned by a local initiating start request, never broadcast or included in status. */
+    authUrl?: string;
+    /** The Claude Console organization a signed-in Anthropic provider is billed to. */
+    organization?: string;
+    /** The Claude Console workspace a signed-in Anthropic provider's token is bound to. */
+    workspace?: string;
+}
+/** One configured provider as the client may see it. API keys are never included. */
+export interface AppServerProvider {
+    id: string;
+    type: 'openai-compatible' | 'anthropic' | 'codex' | 'claude' | 'opencode-go';
+    baseUrl: string;
+    model: string;
+    apiKeyEnv?: string;
+    /** Every model configured for the provider; `model` is the active one. Absent means the active model alone. */
+    models?: string[];
+    /** A context window saved per configured model id, used when the endpoint does not report one. */
+    modelContextWindows?: Record<string, number>;
+    /** Whether a credential is saved or resolvable; the value itself never leaves the engine. */
+    hasApiKey: boolean;
+    /**
+     * An opaque id for the stored credential that changes when the stored key is replaced by anyone —
+     * the CLI, another window — and means nothing else. Absent when no key is stored, and absent from
+     * engines built before the field, where a client can only see that a key exists.
+     */
+    apiKeyRevision?: string;
+    contextWindow?: number;
+    /** The provider's configured thinking effort; `run.start` may name another one for a single task. */
+    reasoningEffort?: string;
+    requestTimeoutMs?: number;
+    /** The provider's independent inference inactivity bound; absent means it follows `requestTimeoutMs`. */
+    streamIdleTimeoutMs?: number;
+    /**
+     * The name a person reads for the provider, computed by the engine from the whole list; a Codex
+     * entry that is one of several carries the account's email localpart. Absent on engines built
+     * before the field, where a client falls back to the id.
+     */
+    label?: string;
+    /**
+     * The display name the user chose for this provider, the text `label` resolves to. Editing it is
+     * how a provider is renamed: the id never changes, so usage rows and journals record past runs
+     * under the same identity and every label picks the new name up. Absent on engines built before
+     * the field, where a client must not send a name at all.
+     */
+    name?: string;
+    /** The ChatGPT account email verified at sign-in, for a Codex provider that has one. */
+    codexEmail?: string;
+    /** `console`: an Anthropic provider that signs in with Claude Console instead of an API key. */
+    anthropicAuth?: 'console';
+}
+export interface AppServerConfig {
+    version: 1;
+    provider: string;
+    providers: AppServerProvider[];
+    graph?: string;
+    graphSelections?: Record<string, string>;
+    jevEnabled?: boolean;
+    decisions?: import('../decision/types.js').DecisionConfig;
+    commandMemory?: boolean;
+    /**
+     * The anonymous-feedback preference. An absent block means the default: reporting is on.
+     *
+     * `generation` tags queued events; `plan` and `canOptOut` are what the settings page needs to
+     * withhold a switch the account's plan cannot exercise.
+     */
+    analytics?: {
+        enabled?: boolean;
+        generation?: number;
+        plan?: 'free' | 'legacy' | 'paid' | 'unknown';
+        canOptOut?: boolean;
+    };
+    limits?: {
+        maxIterations?: number;
+        wallTimeMs?: number;
+        maxToolCalls?: number;
+        maxContextChars?: number;
+        maxCompletionRepairs?: number;
+    };
+    workspacePermissions?: Record<string, AppServerPermissionMode>;
+    mcpServers?: Record<string, {
+        transport: 'stdio' | 'http';
+        summary: string;
+        enabled: boolean;
+    }>;
+    extensions?: {
+        disabledSkills?: string[];
+        disabledPlugins?: string[];
+    };
+    /** The mandatory provider/model external hosts must name for subagent runs; null in a patch clears it. */
+    externalSubagent?: {
+        provider: string;
+        model: string;
+    } | null;
+    /** Instructions used instead of the workspace guide (ANDORRA.md, AGENTS.md); null or blank in a patch clears it. */
+    systemPromptOverride?: string | null;
+    /** Days without activity before a session is archived automatically (1-30); null in a patch turns it off. */
+    autoArchiveDays?: number | null;
+}
+export interface AppServerAccount {
+    signedIn: boolean;
+    label: string;
+    notice: string;
+    jevQuota?: string;
+    subject?: string;
+    email?: string;
+    paid: boolean;
+    unavailable?: boolean;
+    /** The plan the account belongs to: `free`, `legacy`, or `paid`. */
+    tier?: AppServerMembershipTier;
+    dailyDecisionLimit?: number;
+    dailyDecisionUsed?: number;
+    /** The account's running total of hosted decisions across every day. */
+    decisionsSinceRollout?: number;
+    /**
+     * Where the account's billing lives, when the service has a billing page for it.
+     *
+     * Subscription billing is not set up yet, so the account service does not send this.
+     */
+    billingUrl?: string;
+}
+/** The plan an account belongs to. `legacy` is free of charge and carries the premium benefits. */
+export type AppServerMembershipTier = 'free' | 'legacy' | 'paid';
+/** The account's own profile: the verified email and the fields its owner may edit. */
+export interface AppServerProfile {
+    email?: string;
+    name?: string;
+    givenName?: string;
+    familyName?: string;
+    /** When the account itself last changed, which is the closest thing to "profile saved". */
+    accountUpdatedAt?: string;
+}
+/** What an account has done on this machine, in totals. */
+export interface AppServerSessionStats {
+    total: number;
+    archived: number;
+    turns: number;
+    inputTokens: number;
+    outputTokens: number;
+    requests: number;
+    projects: number;
+    firstActivity?: number;
+    lastActivity?: number;
+}
+export interface AppServerUsageModel {
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    savedInputEstimate: number;
+    bypassedTurns: number;
+}
+export interface AppServerUsageDay {
+    date: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    savedInputEstimate: number;
+    bypassedTurns: number;
+    models: AppServerUsageModel[];
+}
+/** Source usage is measured; Jev bypass estimates are a separate, explicitly non-billing category. */
+export interface AppServerUsageAnalytics {
+    days: AppServerUsageDay[];
+    models: AppServerUsageModel[];
+    totals: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheRead: number;
+        savedInputEstimate: number;
+        bypassedTurns: number;
+        unestimatedTurns: number;
+    };
+    incomplete: boolean;
+    filesScanned: number;
+    windowDays: number;
+}
+export interface AppServerSessionSummary {
+    id: string;
+    name: string;
+    workspace: string;
+    updatedAt: string;
+    parentId?: string;
+    projectId?: string;
+    turns: number;
+    /** The most recent task, so a session row reads as the work it holds. */
+    lastTask?: string;
+    /** Set when the session is put away from the rail rather than deleted. */
+    archived?: boolean;
+    /**
+     * How the newest saved attempt ended.
+     *
+     * `succeeded` is what a turn that carries no status means: the saved record keeps a status only for an
+     * attempt that stopped without completing. A surface decides what a task row says about its task from
+     * this field rather than from wording — and it is the one completion reading that survives a reload or
+     * a reconnect, because it comes out of the saved record, not out of anything the client remembers.
+     */
+    lastTurnStatus?: AppServerTurnStatus;
+    /**
+     * Self-wakes this session is waiting on, soonest first; empty or absent means it is waiting on none.
+     *
+     * This is what separates a task that is done from one that is held up: the prompt exists and has to be
+     * delivered before the task can go on. Clients render the wait and do not time it themselves, because
+     * the engine owns the deadline and the delivery.
+     */
+    timers?: AppServerTimerState[];
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        requests: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    };
+}
+/** How a saved attempt ended. `succeeded` is the engine's reading of a turn that carries no status. */
+export type AppServerTurnStatus = 'succeeded' | 'running' | 'cancelled' | 'interrupted' | 'infrastructure_error' | 'exhausted' | 'needs_clarification';
+/** One armed self-wake, in the shape a client needs to draw it. The prompt text is deliberately not sent. */
+export interface AppServerTimerState {
+    id: string;
+    /** Epoch milliseconds at which the prompt becomes due, so a client compares against the engine's clock. */
+    dueAt: number;
+}
+export interface AppServerRunSummary {
+    id: string;
+    status: string;
+    graph: string;
+    provider: string;
+    model: string;
+    workspace?: string;
+    startedAt: string;
+    updatedAt: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        requests: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    };
+    toolCalls: number;
+    task?: string;
+    /** The session this run belongs to, so a client can reach a session's trajectory from its row. */
+    sessionId?: string;
+}
+export interface AppServerGraphSummary {
+    id: string;
+    name: string;
+    revision: number;
+    preset: boolean;
+    updatedAt?: string;
+}
+export interface AppServerTreeEntry {
+    name: string;
+    path: string;
+    type: 'file' | 'directory';
+    size?: number;
+}
+/** One git working-tree entry, in `git status --porcelain=v1` terms. */
+export interface AppServerGitFile {
+    path: string;
+    index: string;
+    worktree: string;
+}
+/** `truncated` means the working tree listed more changes than the engine reads in one answer. */
+export interface AppServerGitStatus {
+    repository: boolean;
+    branch?: string;
+    files: AppServerGitFile[];
+    truncated?: boolean;
+}
+/**
+ * The branches a client may put a task on.
+ *
+ * `current` is absent in a detached HEAD rather than naming the commit as if it were a branch, and
+ * `branches` holds local branches only: a remote-tracking ref is not a branch a checkout can land on
+ * without a decision — which local branch tracks it — the client cannot express here.
+ */
+export interface AppServerBranchList {
+    repository: boolean;
+    current?: string;
+    branches: string[];
+    truncated?: boolean;
+}
+export interface AppServerBundle {
+    id: string;
+    name: string;
+    description: string;
+    enabled: boolean;
+    unavailable?: boolean;
+    repository?: {
+        id: string;
+        name: string;
+        source: string;
+        path: string;
+    };
+    relativePath?: string;
+    command?: string;
+}
+/**
+ * Remote Workspace wire shapes.
+ *
+ * `remote` in the error codes covers a peer-side refusal whose `message` is the display text. The
+ * states the UI branches on come from the per-workspace `status` field of `remote.workspaces.list`,
+ * which the engine computes by probing the peer — a thrown call's code is never the branch.
+ *
+ * Nothing in these shapes carries a device token or a peer certificate. The pairing code carries
+ * the invitation once, and credentials live only inside the engine.
+ */
+export type AppServerRemoteTransport = 'https' | 'http';
+/** One project in the installation registry — the list the rail reads and paired peers see. */
+export interface AppServerProject {
+    path: string;
+    name?: string;
+    addedAt: string;
+}
+/** Hosting state of THIS machine as a peer host, for the Settings page. */
+export interface AppServerRemoteHostingStatus {
+    serving: boolean;
+    port: number;
+    transport: AppServerRemoteTransport;
+    hostname: string;
+    fingerprint: string;
+    /** The live single-use pairing code, or null when no code can be served yet. */
+    code: string | null;
+    invitationExpiresAt: string | null;
+    invitationGrant?: 'browse' | 'full';
+    /** Display metadata for the Revoke control, which addresses devices by id — never tokens. */
+    devices: {
+        id: string;
+        label?: string;
+        addedAt: string;
+        lastSeenAt?: string;
+        grant?: 'browse' | 'full';
+    }[];
+    shares: {
+        id: string;
+        path: string;
+        label?: string;
+    }[];
+}
+/** A machine this installation paired into. `status` is the branch field for every UI state. */
+export interface AppServerRemoteWorkspace {
+    id: string;
+    nickname: string;
+    host: string;
+    hosts: string[];
+    port: number;
+    transport: AppServerRemoteTransport;
+    fingerprint: string;
+    hostname?: string;
+    platform?: string;
+    version?: string;
+    addedAt: string;
+    status: 'online' | 'offline' | 'identity-changed' | 'unauthorized' | 'unknown';
+    grant?: 'browse' | 'full';
+    /** Whether the peer serves the engine relay, so a full grant means tasks can run over the link. */
+    relay?: boolean;
+    /** Display text for a non-online status; never a secret. */
+    statusDetail?: string;
+}
+/** A peer's registered project: an opaque root id and a name — never an absolute path. */
+export interface AppServerRemoteProject {
+    rootId: string;
+    name: string;
+}
+/** A browseable root on a peer: the host's registered projects plus its explicit shares. */
+export interface AppServerRemoteRoot {
+    id: string;
+    label: string;
+    kind: 'project' | 'share';
+}
+/** One directory level of a remote root; `hasMore` means the 1000-entry cap was reached. */
+export interface AppServerRemoteListing {
+    rootId: string;
+    rel: string;
+    parent: string | null;
+    entries: {
+        name: string;
+        type: 'file' | 'directory';
+    }[];
+    hasMore: boolean;
+}

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

@@ -0,0 +1,106 @@
+/**
+ * Wire contract for `andorra app-server --stdio`.
+ *
+ * The desktop client drives the runtime over newline-delimited JSON on stdio: one request per
+ * input line, one response per request, and any number of unsolicited events out. stdio keeps
+ * the engine parent-owned, so the transport needs no port, no token, and no listener policy;
+ * any client that can spawn a process can drive it, which is the client/runtime boundary the
+ * architecture decisions describe.
+ *
+ * Sequencing: responses are matched by `id`, never by order. A slow call (model discovery, a
+ * sign-in) is answered after later requests were accepted, so a client must not assume that
+ * response `n` belongs to request `n`. Events carry no `id` and never answer a request.
+ *
+ * The desktop project keeps a hand-written mirror of these shapes in
+ * `desktop/src/engine/protocol.ts`. `test/app-server.test.ts` locks the serialized payloads
+ * this file names, so a change here that the mirror misses fails a test rather than a build.
+ *
+ * Version: the desktop refuses an engine that does not speak exactly this version, so an RPC the
+ * client needs unconditionally must raise it. Version 2 added `sessions.setArchived`: an engine
+ * still on version 1 answers that call with `unknown-method`, and a rail that silently offered an
+ * archive it could not perform would fail the action far from the version check that explains it.
+ */
+export const APP_SERVER_PROTOCOL_VERSION = 2;
+/**
+ * What this engine can do beyond the methods and fields every engine on that version answers.
+ *
+ * The version is one number for the shapes that must hold for every installation on it; an additive
+ * optional field or a new method is not a version change, so a client needs something else to tell an
+ * engine that learned the feature from one that never did. A client must read an absent list as "nothing
+ * beyond the version" — that is what an engine built before this field sends.
+ *
+ * Some of them exist so a client is told before it writes: `providers.streamIdleTimeout` is a provider
+ * field an engine from before it drops on write while still answering success, so the window withholds
+ * the control — and refuses the write — unless the engine says it stores the field.
+ */
+// `run.resume.direction`: `run.resume` honors a `direction` and delivers it as the continued
+// attempt's first steering message. An engine without it accepts the field and ignores it, so a
+// client that offers a continuation message must not send one to such an engine: the resume would
+// succeed with the user's instruction silently dropped.
+// `remote.engine.relay`: this engine can proxy a full-grant paired workspace's engine surface —
+// `remote.engine.connect`/`request`/`disconnect` — so a window may run tasks on that machine. An
+// engine without it has only the browse subset, and the desktop keeps the read-only presentation.
+// `remote.hosting.device.grant`: the Settings action that raises an existing browse-only pairing to
+// full owner authority exists; an older engine would answer unknown-method for the control.
+// `runs.files`: `runs.files` reports the file a run's stored result record lives in, and whether it
+// is on disk. Saving a trajectory as JSON and showing it in the file manager are the two actions
+// that need the file rather than its contents, and only the engine knows where this home keeps its
+// records — so a window on an engine without this capability holds both controls back instead of
+// opening a dialog that can only answer `unknown-method`.
+// `sessions.files`: `sessions.files` names the session's trajectory log — the per-session debug
+// record every run and resume of that session appends to — the same way `runs.files` names one
+// run's record. A window on an engine without it omits the session file actions, and such an
+// engine writes no session trajectory at all.
+// `providers.modelContextWindows`: the provider view reports `modelContextWindows` and an upsert
+// stores it, so the settings surface can offer a saved context window per configured model. An
+// engine without it filters the field out of a write and never reports it, so the client keeps the
+// per-model window controls off rather than accept a save that silently dropped them.
+// `providers.test.model`: `providers.test` accepts a `model` override and answers `modelAvailable`
+// for that model. An engine without it probes the provider's active model and ignores the parameter,
+// so a per-row Test would present the active model's verdict as if it were the row's own.
+// `providers.discover.draft`: `providers.discover` accepts `providerType` instead of `providerId`
+// for a Claude or OpenCode Go catalog before a provider is saved. It neither stores a provider nor
+// forwards draft credentials; other provider types still require their saved connection.
+// `run.overrideAllNodes`: `run.start` accepts `overrideAllNodes`, which runs every node of the
+// graph on the run's own provider and model. An engine without it ignores the parameter and runs
+// the graph's own per-node selections, so a client would show an armed override that the run
+// never applied.
+// `config.analytics.planGate`: the analytics block reports `generation`, `plan` and `canOptOut`,
+// so a client can withhold the switch for a plan that cannot opt out instead of offering one that
+// silently does nothing. An engine without it reports only `enabled`, and a window on such an
+// engine keeps the preference switch unconditional.
+// `sessions.trajectory`: `sessions.trajectory` reads the session's trajectory log, one page at a
+// time, in the order it was written. A window on an engine without it cannot read a session's
+// trajectory at all.
+// `run.start.continueSession`: `run.start` accepts `continueSession`, which appends the run to the
+// session it names instead of forking a new record from it. An engine without it ignores the extra
+// parameter and forks: the work still runs, but the session the client is showing stays behind and
+// the rail grows a duplicate-named thread, so a client that keeps one task tree sends the flag only
+// to an engine that advertises it.
+// `automations`: the engine owns persistent schedules: `automations.*` lists, creates, updates,
+// deletes and runs saved prompts, and reports the scheduler service's state, each firing as its own
+// session. An engine without it answers `unknown-method`, so a window on such an engine hides the
+// Automations surface rather than offering a list it cannot serve.
+// `browser.view`: the session browser panel is live: `browser.runtime.*` reports and installs the
+// isolated-browser dependency, `browser.view.*` opens session-owned pages, streams them as CDP
+// screencast frames, forwards panel input, and reads the page's selection back so a copy reaches
+// the viewer's own clipboard, and the `browser.view`/`browser.runtime` events carry tabs, frames
+// and install state. An engine without it can only ever answer `unknown-method`, so a window on
+// such an engine keeps the panel's placeholder and never offers the address bar.
+/** run.start.runPermissions binds one attempt without changing the workspace permission default. */
+/** attachments.read returns one spooled image's bytes, so a window can preview a pasted image in
+ * the timeline and expand it; an engine without it renders the attachment chip's name alone. */
+/** providers.codexAccounts: a Codex entry may carry `codexAccount` and `codexEmail`, and an upsert
+ * retains both when a client omits them. An engine without it rebuilds a replaced entry from its
+ * own field list, so a save through it silently drops the account slot and points the provider at
+ * the default home's sign-in; a client that names a slot must refuse the write first. */
+/** providers.name: a provider entry may carry a display `name`, and an upsert retains the stored
+ * one when a client omits it. An engine without it rebuilds a replaced entry from its own field
+ * list, so a save through it silently drops the rename and every surface falls back to the id; a
+ * client that can show the field must refuse the write first. */
+// `run.steer`: `run.steer` queues a message into a live attempt's own steering channel, the one the
+// runtime polls at turn boundaries, and records it in the run journal as a `run.steered` event. An
+// engine without it answers `unknown-method`, and a client that offers steering must not fall back to
+// cancelling the run: the attempt would stop for a message this engine could only deliver by starting
+// it over.
+export const APP_SERVER_CAPABILITIES = ['run.start.runPermissions', 'automations', 'providers.models', 'providers.test', 'providers.test.model', 'providers.streamIdleTimeout', 'providers.modelContextWindows', 'providers.name', 'providers.claude', 'providers.opencodeGo', 'providers.discover.draft', 'providers.codexAuth', 'providers.codexAuth.logout', 'providers.codexAccounts', 'providers.anthropicConsole', 'run.resume.direction', 'run.steer', 'run.overrideAllNodes', 'run.setModel', 'run.start.continueSession', 'remote.owner.projects', 'remote.workspaces.probe', 'remote.engine.relay', 'remote.hosting.device.grant', 'extensions.manage', 'extensions.resources', 'skills.invoke', 'mcp.manage', 'runs.files', 'sessions.files', 'account.profile', 'sessions.stats', 'sessions.usage', 'config.analytics', 'config.analytics.planGate', 'sessions.trajectory', 'config.externalSubagent', 'config.decisions', 'browser.view', 'attachments.read', 'config.general', 'sessions.pullRequest', 'browser.view.go'];

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

@@ -0,0 +1,43 @@
+import type { ModelAdapter, RuntimeEvent } from '../types.js';
+/**
+ * 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 declare const REASONING_TEXT_LIMIT = 12000;
+/**
+ * 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 declare const REASONING_DELTA_MS = 80;
+export type ReasoningPublisher = (event: RuntimeEvent) => void;
+export declare function withReasoningEvents(adapter: ModelAdapter, publish: ReasoningPublisher): ModelAdapter;