@skrr-ai/cli 0.1.87 → 0.1.89

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/computerWire.d.ts

@@ -0,0 +1,1050 @@
+/**
+ * computerWire.ts — the ONE declaration of every name the computer protocol
+ * puts on the wire, and the pure rules the daemon applies to them (design
+ * docs/architecture/dedicated-runtime-computer-2026-10-01.md §4, §7.1).
+ *
+ * The daemon is published and cannot depend on `@skrr-ai/data-provider`, which
+ * is private. Without this module it would declare its own copy of the event
+ * names and refusal codes, and two hand-typed copies of a wire contract drift
+ * in exactly the way neither copy's tests can see (OSK-8588). So the names live
+ * here, in the published package, the way `firstPartyHarness.ts` does for the
+ * harness; `@skrr-ai/data-provider` re-exports this module and builds its zod
+ * schemas over these constants (`z.enum(COMPUTER_REFUSAL_CODES)`), so each name
+ * is still declared exactly once. `packages/data-provider/specs/computerWireBoundary.spec.ts`
+ * fails on a `computer:*` event name or a refusal-code table declared anywhere
+ * else.
+ *
+ * Pure TypeScript: no zod, no Node-only imports, so the browser, React Native
+ * and a bun-compiled daemon all load it. Most payload SHAPES are not here — they
+ * are zod schemas in data-provider; the daemon re-validates every field it
+ * reads. The exceptions are shapes the DAEMON produces and the API re-validates
+ * (activity details, the browser key input): those are declared here as plain
+ * interfaces, and data-provider's zod schemas are checked against them at
+ * compile time, because a producer and a validator that each spell the shape
+ * dropped every command event for a release (OSK-13605).
+ */
+/**
+ * Client ⇄ API, on the existing `/ws/agentic` socket. A request the client
+ * needs answered is acknowledged through the Socket.IO acknowledgement
+ * callback.
+ */
+export declare const COMPUTER_EVENTS: {
+    /** client → API: attach to a machine. */
+    readonly attach: "computer:attach";
+    /** client → API: leave. */
+    readonly detach: "computer:detach";
+    /**
+     * client → API: read the whole manifest again ON THE SAME ATTACHMENT, after
+     * a missed delta or a `stale_epoch` (OSK-13815). The ack carries what an
+     * attach's does — the attachment id (unchanged), the manifest and the
+     * operations — or a typed refusal; `not_found` means the attachment is gone
+     * and only then does the client attach afresh. Re-reading state must never
+     * change who the reader is: a control lease is bound to the attachment
+     * (`holderAttachmentId`), and a resync that detached and attached again
+     * orphaned the hold the person had just taken. Answered by the API, which
+     * renews the binding with the daemon exactly as its periodic re-check does
+     * (a repeated `daemon:computer:attach` with the same id), so it has no
+     * daemon mirror and needs no daemon capability. An API that predates it
+     * never answers; the client bounds the wait and falls back to attaching
+     * afresh.
+     */
+    readonly resync: "computer:resync";
+    /** API → client: this attachment was detached, with the reason (revoked, stale generation, …). */
+    readonly detached: "computer:detached";
+    /** API → client: a whole manifest, or a revisioned delta. */
+    readonly manifest: "computer:manifest";
+    /** client → API: observe one surface. */
+    readonly subscribe: "computer:surface:subscribe";
+    /** client → API: stop observing one surface. */
+    readonly unsubscribe: "computer:surface:unsubscribe";
+    /** API → client: terminal bytes with a byte cursor, or a page frame. */
+    readonly data: "computer:surface:data";
+    /**
+     * client → API: this viewer painted the page frame `seq` and wants the next.
+     * A viewer's slot is latest-wins: until it acknowledges, newer frames
+     * replace the one waiting for it and nothing queues (§6.2, §7.2 R3).
+     * Never acknowledged.
+     */
+    readonly frameAck: "computer:surface:frame:ack";
+    /** client → API: take / release / request / grant / decline. */
+    readonly control: "computer:surface:control";
+    /** client → API: share or unshare one of the person's own surfaces with an agent session. */
+    readonly share: "computer:surface:share";
+    /** client → API: one input, carrying the lease epoch. Never acknowledged. */
+    readonly input: "computer:surface:input";
+    /** client → API: open a person's own terminal or browser window. */
+    readonly open: "computer:surface:open";
+    /** client → API: close a surface. */
+    readonly close: "computer:surface:close";
+    /** API → client: activity events. */
+    readonly activity: "computer:activity";
+    /** client → API: the activity events after a `seq`, to fill a gap. */
+    readonly activityFill: "computer:activity:fill";
+    /** client → API: the directories expanded and files open, which scope the file watches. */
+    readonly filesWatch: "computer:files:watch";
+    /**
+     * API → client: what this attachment's scoped watches saw — paths and kinds,
+     * never contents — or that they went stale and the tree must be refreshed
+     * (§6.3 layer 2). Needs `computer_files_watch_v1`.
+     */
+    readonly filesChanged: "computer:files:changed";
+    /**
+     * client → API: answer a dialog the page is blocked on. Only the attachment
+     * holding the browser's lease, at the current epoch. Needs
+     * `computer_browser_page_v1`.
+     */
+    readonly dialog: "computer:surface:dialog";
+    /**
+     * client → API: copy-out — the text the person selected on the page, answered
+     * to the asking attachment alone and only while it holds the lease at the
+     * current epoch. Needs `computer_browser_page_v1`.
+     */
+    readonly copy: "computer:surface:copy";
+    /**
+     * client → API: answer the file chooser a page opened (§6.2 "a file chooser
+     * opens a picker over the computer's files, or a local upload"): paths on the
+     * computer, or none to cancel. Only the attachment holding the browser's
+     * lease, at the current epoch; the paths are read as the file surface reads
+     * them. Needs `computer_browser_file_chooser_v1`.
+     */
+    readonly fileChooser: "computer:surface:filechooser";
+};
+/**
+ * API ⇄ daemon. The daemon transports (Socket.IO and SSE) carry no
+ * acknowledgement callback, so a request the API needs answered carries a
+ * `requestId` and the daemon answers with `daemon:computer:ack`.
+ */
+export declare const DAEMON_COMPUTER_EVENTS: {
+    /** Bind an attachment: its principal, operations and (dedicated) generation. */
+    readonly attach: "daemon:computer:attach";
+    readonly detach: "daemon:computer:detach";
+    /** The machine's grant set, whole, on registration and on every change. */
+    readonly grants: "daemon:computer:grants";
+    readonly subscribe: "daemon:computer:surface:subscribe";
+    readonly unsubscribe: "daemon:computer:surface:unsubscribe";
+    readonly frameAck: "daemon:computer:surface:frame:ack";
+    readonly control: "daemon:computer:surface:control";
+    readonly share: "daemon:computer:surface:share";
+    readonly input: "daemon:computer:surface:input";
+    readonly open: "daemon:computer:surface:open";
+    readonly close: "daemon:computer:surface:close";
+    readonly activityFill: "daemon:computer:activity:fill";
+    readonly filesWatch: "daemon:computer:files:watch";
+    /** One file operation, relayed from `/api/machines/:machineId/files/<op>`. */
+    readonly files: "daemon:computer:files";
+    readonly dialog: "daemon:computer:surface:dialog";
+    readonly copy: "daemon:computer:surface:copy";
+    readonly fileChooser: "daemon:computer:surface:filechooser";
+    /**
+     * Pin or unpin the surface an open human-input request names (§8): a pinned
+     * surface is not reclaimed by idle or wall-clock expiry. Fire-and-forget,
+     * idempotent on the pin id, bounded by its own `until`. Needs
+     * `computer_surface_pin_v1`.
+     */
+    readonly pin: "daemon:computer:surface:pin";
+    /**
+     * Declare, withdraw or list the machine's declared services (§20.5): a web
+     * service someone started on the machine, named and opened in the
+     * computer's own browser. Carries a `requestId`, the principal the API
+     * authorized and, for a declaration, who declared it; the daemon checks the
+     * principal against the grant set it holds. Needs
+     * `computer_declared_services_v1`.
+     */
+    readonly services: "daemon:computer:services";
+    /** The answer to any request that carried a `requestId`. */
+    readonly ack: "daemon:computer:ack";
+    readonly manifest: "daemon:computer:manifest";
+    readonly data: "daemon:computer:surface:data";
+    readonly activity: "daemon:computer:activity";
+    /** The daemon detached an attachment itself, e.g. its grant was revoked. */
+    readonly detached: "daemon:computer:detached";
+    /** One attachment's scoped watches saw changes, or went stale (§6.3). */
+    readonly filesChanged: "daemon:computer:files:changed";
+    /**
+     * The daemon's own frame-lane counters (§7.2, OSK-13616), every
+     * `COMPUTER_DIAGNOSTICS_INTERVAL_MS` while anyone is attached: counters and
+     * per-viewer timestamps from a closed vocabulary, never content. Needs
+     * `computer_diagnostics_v1`. Fire-and-forget; a lost report is the next one.
+     */
+    readonly diagnostics: "daemon:computer:diagnostics";
+};
+export type ComputerEventKey = keyof typeof COMPUTER_EVENTS;
+export type ComputerEventName = (typeof COMPUTER_EVENTS)[ComputerEventKey];
+export type DaemonComputerEventKey = keyof typeof DAEMON_COMPUTER_EVENTS;
+export type DaemonComputerEventName = (typeof DAEMON_COMPUTER_EVENTS)[DaemonComputerEventKey];
+export declare const COMPUTER_EVENT_NAMES: readonly ComputerEventName[];
+export declare const DAEMON_COMPUTER_EVENT_NAMES: readonly DaemonComputerEventName[];
+/** The daemon → API events; every other `daemon:computer:*` event flows API → daemon. */
+export declare const DAEMON_COMPUTER_REPORT_EVENT_KEYS: readonly ["ack", "manifest", "data", "activity", "detached", "filesChanged", "diagnostics"];
+/** The API → client events; every other `computer:*` event flows client → API. */
+export declare const COMPUTER_SERVER_EVENT_KEYS: readonly ["detached", "manifest", "data", "activity", "filesChanged"];
+/**
+ * Client → API requests the API answers itself, with no `daemon:computer:*`
+ * mirror: every other client request is relayed to the daemon under the same
+ * key. `resync` renews the binding through the daemon's existing attach
+ * (OSK-13815).
+ */
+export declare const COMPUTER_API_ANSWERED_EVENT_KEYS: readonly ["resync"];
+/** How long the client waits for a `computer:resync` answer before attaching afresh (an API that predates it never answers). */
+export declare const COMPUTER_RESYNC_TIMEOUT_MS = 12000;
+/**
+ * How long a client holds a manifest delta that arrived AHEAD of its
+ * predecessor before reading the hole as a loss (OSK-13815). Deltas fan out
+ * through a relay of several replicas; a reorder is milliseconds, a loss is
+ * forever, and only a loss needs the whole manifest again.
+ */
+export declare const COMPUTER_MANIFEST_REORDER_WAIT_MS = 300;
+/**
+ * One capability per wire addition, each withheld positively at dispatch: the
+ * API never sends a computer event to a daemon that did not announce the
+ * capability that event belongs to. Activity is part of `computer_v1`.
+ */
+export declare const COMPUTER_CAPABILITIES: {
+    /** Manifest, surfaces, control leases, terminal surfaces, activity core. */
+    readonly computer: "computer_v1";
+    /** The grant set and the daemon's own check of every attachment against it (§9). */
+    readonly access: "computer_access_v1";
+    /** The file surface: `daemon:computer:files` and `computer:files:watch` (§6.3). */
+    readonly files: "computer_files_v1";
+    /**
+     * Filename and content search and git status decorations over the tenant
+     * roots, as the workload (§6.3 "Later, same contract"): the `FileSearch` and
+     * `FileGitStatus` tools. A daemon without it is never asked.
+     */
+    readonly filesSearch: "computer_files_search_v1";
+    /**
+     * File mutations fenced on what the person saw (review CW-01, CW-02 and the
+     * folder-delete finding): an upload commits create-only (`exists` when the
+     * name was claimed) or over exactly the version chosen to be replaced
+     * (`replaceTag`, else `file_changed`); a committed transfer leaves a receipt,
+     * so a resume after a lost final acknowledgement answers "already
+     * committed"; and `stat` with `contents: true` gives a folder a contents tag that
+     * a recursive delete presents. A daemon without it would ignore those
+     * conditions, so the API refuses them `capability_missing` instead of
+     * sending them.
+     */
+    readonly filesFenced: "computer_files_fenced_v1";
+    /** Observe attachments on a browser surface, separate from control (§6.2). */
+    readonly browserObserve: "computer_browser_observe_v1";
+    /** A browser surface's tab strip and tab input (§6.2). */
+    readonly browserTabs: "computer_browser_tabs_v1";
+    /**
+     * The rest of a real browser on a browser surface (§6.2): its pending
+     * dialogs and its downloads on the descriptor, answering a dialog
+     * (`computer:surface:dialog`) and copy-out (`computer:surface:copy`).
+     * Permission prompts are not part of it: Chromium exposes no CDP event for
+     * them (headless refuses them), so no surface may claim to show one.
+     */
+    readonly browserPage: "computer_browser_page_v1";
+    /** Sharing a person's own surface with an agent session (§5.4). */
+    readonly surfaceShare: "computer_surface_share_v1";
+    /** Pinning a surface an open human-input request names: `daemon:computer:surface:pin` (§8). */
+    readonly surfacePin: "computer_surface_pin_v1";
+    /**
+     * "Reset browser" — sign out everywhere (§6.2, OSK-13499): the
+     * `reset_browser` control action on a browser surface. Announced only by a
+     * daemon whose browser keeps one profile across sessions (a Dedicated
+     * Runtime guest); a personal machine's browser keeps nothing to reset.
+     */
+    readonly browserReset: "computer_browser_reset_v1";
+    /**
+     * Scoped file watches (§6.3 layer 2): `computer:files:watch` is served and
+     * `computer:files:changed` reports. Announced only where the daemon runs a
+     * watcher it can stand behind; without it the file tree says it does not
+     * update by itself and offers a refresh.
+     */
+    readonly filesWatch: "computer_files_watch_v1";
+    /**
+     * The file chooser a page opens while a person holds the browser (§6.2,
+     * OSK-13481): the pending chooser on the descriptor (`fileChooser`) and
+     * answering it with files on the computer (`computer:surface:file-chooser`).
+     * Announced only by a daemon whose browser intercepts the chooser.
+     */
+    readonly browserFileChooser: "computer_browser_file_chooser_v1";
+    /**
+     * A person's own terminal opens in a folder (§6.3 "Open a terminal here",
+     * OSK-13615): `computer:surface:open` carries `cwd`, which the daemon checks
+     * the way the file surface would (the tenant roots as the workload; on a
+     * personal machine the deny set, `blockedPaths` and home) and refuses typed
+     * when it may not. Without it the client types `cd` once it holds control.
+     */
+    readonly terminalCwd: "computer_terminal_cwd_v1";
+    /**
+     * A run in an agent's interactive shell (`terminal.run`, tool `Terminal`)
+     * says where in its terminal's byte stream it began: `streamOffset` on its
+     * `command` activity, the terminal lane's cursor at that moment (§6.1, task
+     * 5-04b, OSK-13614). A client places such a block inline at that point of
+     * the terminal; without the capability it keeps every block in the list
+     * below the terminal, as before.
+     */
+    readonly terminalCommandOffset: "computer_terminal_command_offset_v1";
+    /**
+     * The daemon reports its frame-lane counters (`daemon:computer:diagnostics`,
+     * OSK-13616), so the API's own logs can tell "the daemon stopped sending"
+     * from "the page did not change". Announced by the relay that sends them;
+     * the API asks nothing of a daemon without it, and reads its silence as
+     * "unreported", never as healthy.
+     */
+    readonly diagnostics: "computer_diagnostics_v1";
+    /**
+     * Declared services (§20.5, 9-17, OSK-13579): the manifest carries
+     * `services`, the web services an agent or a person declared on this
+     * machine, and `daemon:computer:services` (and the agent's
+     * `computer.services` tool call) declares, withdraws and lists them. A
+     * service is a localhost port on the machine, opened in the computer's own
+     * browser; nothing is proxied to it. Announced by the relay that serves it.
+     */
+    readonly declaredServices: "computer_declared_services_v1";
+    /**
+     * The page follows the controlling window (§6.2 "a stable viewport", §7.1,
+     * OSK-13808): a browser `viewport` input, sent only by the attachment that
+     * holds the browser's lease at the current epoch, sizes the streamed page
+     * to that window's content box (`COMPUTER_BROWSER_VIEWPORT_LIMITS`). Only
+     * while a person holds control: handing back — or the hold lapsing, being
+     * revoked or moving to the agent any other way — restores the browser's own
+     * viewport before the agent can act, so an agent never inherits a person's
+     * size. Watchers keep seeing the page at whatever size it is, scaled to
+     * fit. Announced only where the browser driver can override and restore
+     * the page's metrics; without it the window scales the fixed page, as
+     * before, and never sends the input.
+     */
+    readonly browserViewport: "computer_browser_viewport_v1";
+};
+export type ComputerCapabilityKey = keyof typeof COMPUTER_CAPABILITIES;
+export type ComputerCapability = (typeof COMPUTER_CAPABILITIES)[ComputerCapabilityKey];
+export declare const COMPUTER_CAPABILITY_VALUES: [ComputerCapability, ...ComputerCapability[]];
+/**
+ * Every refusal and limit the computer protocol can answer with. Callers branch
+ * on the code; a message beside it is free text and may change.
+ */
+export declare const COMPUTER_REFUSAL_CODES: readonly ["human_control", "stale_epoch", "stale_generation", "file_changed", "capability_missing", "unauthorized", "control_denied", "not_holder", "attachment_limit", "observer_limit", "watch_limit", "grant_limit", "browser_limit", "rate_limited", "not_found", "surface_ended", "machine_unavailable", "daemon_unreachable", "relay_error", "timeout", "invalid_request", "consent_missing", "path_withheld", "too_large", "service_limit"];
+export type ComputerRefusalCode = (typeof COMPUTER_REFUSAL_CODES)[number];
+/**
+ * The code when it is a computer refusal, else `null`. There is one spelling
+ * per code: the browser's older spelling of `human_control` was accepted for
+ * one release and retired with the old browser events (§5.2, OSK-13509).
+ */
+export declare function normalizeComputerRefusalCode(code: unknown): ComputerRefusalCode | null;
+export declare const COMPUTER_ACTOR_KINDS: readonly ["agent", "human"];
+export type ComputerActorKind = (typeof COMPUTER_ACTOR_KINDS)[number];
+/**
+ * Who an activity event is attributed to. `system` is what happened with no
+ * actor behind it — a process exited, the machine stopped — and appears ONLY
+ * on activity: it never holds a lease, is never present, is never audited as
+ * an actor. Without it on the wire every lifecycle event was dropped by the
+ * API and a client saw a `seq` hole no fill could close.
+ */
+export declare const COMPUTER_ACTIVITY_ACTOR_KINDS: readonly ["agent", "human", "system"];
+export type ComputerActivityActorKind = (typeof COMPUTER_ACTIVITY_ACTOR_KINDS)[number];
+/**
+ * The session ids the PLATFORM's own routes run daemon tools under — the web
+ * Files surface (`computer-files:` on a personal machine, `dedicated-runtime:`
+ * on a Dedicated Runtime) and the owner's `skrr machines dedicated` commands.
+ * No agent and no model is behind such a session: the person who asked is
+ * known to the API (which audits it), not to the daemon. So an activity event
+ * produced under one names no agent (OSK-13790: a person's upload used to read
+ * "agent created …"). Built by `ComputerFileService.runPersonalMachineTool`
+ * and `DedicatedRuntimeMachineAccess.runDedicatedRuntimeTool`.
+ */
+export declare const COMPUTER_PLATFORM_ROUTE_SESSION_PREFIXES: readonly ["dedicated-runtime:", "computer-files:"];
+/** Whether a tool call's session is one of the platform's own routes, not an agent's. */
+export declare function isComputerPlatformRouteSession(sessionId: unknown): boolean;
+/** An agent session, as the wire names it. Same session = same `agentId` AND `sessionId`. */
+export interface ComputerWireAgentActor {
+    kind: 'agent';
+    agentId: string;
+    sessionId: string;
+    label: string;
+}
+export interface ComputerWireHumanActor {
+    kind: 'human';
+    userId: string;
+    label: string;
+}
+/** Activity only (see `COMPUTER_ACTIVITY_ACTOR_KINDS`). */
+export interface ComputerWireSystemActor {
+    kind: 'system';
+    label: string;
+}
+/** Who can hold a lease or be present. */
+export type ComputerWireActor = ComputerWireAgentActor | ComputerWireHumanActor;
+/** Who an activity event is attributed to. */
+export type ComputerWireActivityActor = ComputerWireActor | ComputerWireSystemActor;
+/**
+ * How a person present on the machine reached it: as its owner, or through a
+ * grant at one of the two tiers. Agents carry no access level — an agent
+ * session acts with its own run's authority, not a grant.
+ */
+export declare const COMPUTER_ACCESS_LEVELS: readonly ["owner", "watch", "operate"];
+export type ComputerAccessLevel = (typeof COMPUTER_ACCESS_LEVELS)[number];
+/**
+ * What a principal may do on a computer. Kept separate so a refusal says
+ * exactly what was refused. `power`, closing other people's surfaces and
+ * managing grants stay with the owner; no tier contains `power`.
+ */
+export declare const COMPUTER_OPERATIONS: readonly ["observe", "control", "files.read", "files.write", "open", "power"];
+export type ComputerOperation = (typeof COMPUTER_OPERATIONS)[number];
+/** A grant is one of two fixed tiers: a finer grant cannot be enforced on a shell. */
+export declare const COMPUTER_GRANT_TIERS: readonly ["watch", "operate"];
+export type ComputerGrantTier = (typeof COMPUTER_GRANT_TIERS)[number];
+/** The fixed set of operations a grant tier carries. */
+export declare function computerTierOperations(tier: ComputerGrantTier): readonly ComputerOperation[];
+/** Whether a grant tier carries `operation`. */
+export declare function computerOperationAllowed(tier: ComputerGrantTier, operation: ComputerOperation): boolean;
+/** The operations an access level carries: the owner holds every one. */
+export declare function computerAccessOperations(level: ComputerAccessLevel): readonly ComputerOperation[];
+/** A person releasing control may leave a note for the agent (§8). */
+export declare const COMPUTER_HANDBACK_NOTE_MAX_LENGTH = 2000;
+/** A person holding control is released after this long without human input (§5.1 rule 4). */
+export declare const COMPUTER_CONTROL_IDLE_MS: number;
+/** How long before idle reclaim of a person's hold the daemon says it is coming (§8). */
+export declare const COMPUTER_RECLAIM_WARNING_MS: number;
+/** A transport blip shorter than this changes no lease (§7.2 R6). */
+export declare const COMPUTER_RECONNECT_GRACE_MS: number;
+/** An agent terminal write waits this long for a person to hand back before refusing (§5.2). */
+export declare const COMPUTER_AGENT_WRITE_WAIT_MS: number;
+/** What a person can do to a surface's lease (§5.1, §5.3). */
+export declare const COMPUTER_CONTROL_ACTIONS: readonly ["take", "release", "request", "grant", "decline", "reveal", "reset_browser"];
+export type ComputerControlAction = (typeof COMPUTER_CONTROL_ACTIONS)[number];
+/** Sharing one of a person's own surfaces with one agent session (§5.4). */
+export declare const COMPUTER_SHARE_ACTIONS: readonly ["share", "unshare"];
+export type ComputerShareAction = (typeof COMPUTER_SHARE_ACTIONS)[number];
+export declare const COMPUTER_SHARE_MODES: readonly ["observe", "control"];
+export type ComputerShareMode = (typeof COMPUTER_SHARE_MODES)[number];
+/** `daemon:computer:surface:pin` actions (§8). */
+export declare const COMPUTER_SURFACE_PIN_ACTIONS: readonly ["pin", "unpin"];
+export type ComputerSurfacePinAction = (typeof COMPUTER_SURFACE_PIN_ACTIONS)[number];
+/** Why a pin ended: the request it held the surface for left `open`. */
+export declare const COMPUTER_SURFACE_UNPIN_REASONS: readonly ["answered", "dismissed", "expired"];
+export type ComputerSurfaceUnpinReason = (typeof COMPUTER_SURFACE_UNPIN_REASONS)[number];
+/**
+ * A surface held for a person by an open human-input request (§8), as the
+ * manifest shows it: which request, since when, until when at the latest.
+ */
+export interface ComputerSurfacePin {
+    /** The human-input request id. */
+    pinId: string;
+    taskId?: string;
+    since: number;
+    until: number;
+}
+/** Why a lease changed holder. Carried by `control` activity events and the audit record. */
+export declare const COMPUTER_CONTROL_CHANGE_REASONS: readonly ["take", "release", "grant", "idle", "disconnect", "share", "unshare", "revoked", "machine_stopped"];
+export type ComputerControlChangeReason = (typeof COMPUTER_CONTROL_CHANGE_REASONS)[number];
+/**
+ * What a `control` activity event reports: a change of holder (one of
+ * `COMPUTER_CONTROL_CHANGE_REASONS`), a person-to-person request's lifecycle,
+ * or a reveal (D12). Only the first changes the holder or the epoch's owner;
+ * {@link computerControlChangeIsHolderChange} tells them apart.
+ */
+export declare const COMPUTER_CONTROL_ACTIVITY_CHANGES: readonly ["take", "release", "grant", "idle", "disconnect", "share", "unshare", "revoked", "machine_stopped", "request", "request_declined", "request_expired", "request_withdrawn", "revealed"];
+export type ComputerControlActivityChange = (typeof COMPUTER_CONTROL_ACTIVITY_CHANGES)[number];
+/** Whether a `control` activity change moved the lease to a new holder. */
+export declare function computerControlChangeIsHolderChange(change: unknown): change is ComputerControlChangeReason;
+/**
+ * The part of a control lease the input fence reads. `epoch` is a fence, not
+ * an authorisation: it increments on every change of holder, and because every
+ * observer can read it, input is accepted only from the ATTACHMENT that took
+ * the lease (`holderAttachmentId` + `epoch`).
+ */
+export interface ComputerLeaseFence {
+    holder: {
+        kind: ComputerActorKind;
+    };
+    epoch: number;
+    /** The attachment that took the lease. Set while a person holds; absent for an agent. */
+    holderAttachmentId?: string;
+}
+/**
+ * Why an input from `attachmentId`, issued under `epoch`, must be dropped — or
+ * `null` when the lease accepts it.
+ *
+ * The epoch is checked first: an input issued under an epoch that is no longer
+ * current is the in-flight keystroke the fence exists for, whoever sent it.
+ * Only a current-epoch input from an attachment that does not hold the lease
+ * is `not_holder`. An agent-held lease accepts no attachment's input.
+ */
+export declare function computerLeaseInputRefusal(lease: ComputerLeaseFence, attachmentId: string, epoch: number): Extract<ComputerRefusalCode, 'stale_epoch' | 'not_holder'> | null;
+/** Whether the lease accepts an input from `attachmentId` issued under `epoch`. */
+export declare function computerLeaseAcceptsInput(lease: ComputerLeaseFence, attachmentId: string, epoch: number): boolean;
+/** Files are a namespace, not a leased surface (§6.3). */
+export declare const COMPUTER_SURFACE_KINDS: readonly ["terminal", "browser"];
+export type ComputerSurfaceKind = (typeof COMPUTER_SURFACE_KINDS)[number];
+export declare const COMPUTER_SURFACE_STATES: readonly ["live", "ended"];
+export type ComputerSurfaceState = (typeof COMPUTER_SURFACE_STATES)[number];
+/**
+ * Why a surface ended (§10). An ended surface stays as a tombstone with its
+ * history until dismissed, and its reason is shown, never swallowed.
+ */
+export declare const COMPUTER_SURFACE_END_REASONS: readonly ["machine_stopped", "closed_by_owner", "closed", "process_exited", "daemon_restarted", "browser_crashed", "expired", "browser_reset"];
+export type ComputerSurfaceEndReason = (typeof COMPUTER_SURFACE_END_REASONS)[number];
+/**
+ * The browser's logical viewport whoever is looking (§6.2): what the agent
+ * always works at. A person holding control may size the page to their window
+ * (`computer_browser_viewport_v1`); handing back restores this.
+ */
+export declare const COMPUTER_BROWSER_VIEWPORT: Readonly<{
+    width: 1280;
+    height: 800;
+}>;
+/** One frame never exceeds this, so it fits the SSE transport every guest uses (§7.2 R7). */
+export declare const COMPUTER_FRAME_MAX_BYTES: number;
+/**
+ * A viewer's frame slot frees itself after this long without the viewer's
+ * acknowledgement. The relay cannot promise delivery of the acknowledgement
+ * either, and a lost one must not freeze a viewer that is still painting; a
+ * viewer that really stalled still gets at most one frame per bound, never a
+ * backlog.
+ */
+export declare const COMPUTER_FRAME_ACK_TIMEOUT_MS = 5000;
+/**
+ * The daemon's frame-lane counters (`daemon:computer:diagnostics`, OSK-13616).
+ * Cumulative since `since`, so a lost report loses nothing but its moment.
+ */
+export declare const COMPUTER_DIAGNOSTIC_COUNTERS: readonly ["frames_produced", "frames_sent", "frames_held_disconnected", "frames_dropped_oversize", "frames_send_failed", "frames_acked", "frames_ack_timeout", "frame_slots_released"];
+/** How often a daemon with anyone attached reports its counters. */
+export declare const COMPUTER_DIAGNOSTICS_INTERVAL_MS = 15000;
+/** Viewers one report names, newest first; the rest are in the totals only. */
+export declare const COMPUTER_DIAGNOSTICS_MAX_STREAMS = 64;
+export declare const COMPUTER_TERMINAL_SIGNALS: readonly ["interrupt", "eof"];
+export type ComputerTerminalSignal = (typeof COMPUTER_TERMINAL_SIGNALS)[number];
+/** Input a terminal surface takes. */
+export declare const COMPUTER_TERMINAL_INPUT_TYPES: readonly ["bytes", "paste", "resize", "signal"];
+/**
+ * How long a terminal lives (§6.1, §18), so its window can say so instead of
+ * implying a guest's guarantees on a laptop (OSK-13535):
+ *   - `host`: its shell is in the terminal host; a daemon restart or update
+ *     leaves it running. Off a guest the host closes it an hour after its
+ *     daemon stopped for good. Its output is kept on disk, so after the machine
+ *     (or the host) restarts it reopens with its history above a divider;
+ *   - `tmux`: a guest's persistent terminal from before the host; it outlives
+ *     the daemon and ends with the machine, with no history;
+ *   - `daemon`: its shell is in the daemon's own process and ends with it.
+ */
+export declare const COMPUTER_TERMINAL_LIFETIMES: readonly ["host", "tmux", "daemon"];
+export type ComputerTerminalLifetime = (typeof COMPUTER_TERMINAL_LIFETIMES)[number];
+/**
+ * Why a reopened terminal's shell is not the one that wrote the history above
+ * its divider (OSK-13474). The terminal host decides it from its records.
+ */
+export declare const COMPUTER_TERMINAL_HISTORY_CAUSES: readonly ["machine_restarted", "host_stopped", "host_orphaned", "host_restarted"];
+export type ComputerTerminalHistoryCause = (typeof COMPUTER_TERMINAL_HISTORY_CAUSES)[number];
+/**
+ * What a terminal's window cannot promise on this machine, said rather than
+ * left silent. `windows_pty_unverified`: a Windows machine's terminal is a
+ * ConPTY in the daemon's process; its resize and PTY behaviour have not been
+ * verified (OSK-13535).
+ */
+export declare const COMPUTER_TERMINAL_CAVEATS: readonly ["windows_pty_unverified"];
+export type ComputerTerminalCaveat = (typeof COMPUTER_TERMINAL_CAVEATS)[number];
+/** Terminal-only facts a surface descriptor carries (`terminal`). Every field is optional. */
+export interface ComputerTerminalInfo {
+    /**
+     * The size the terminal's controller set (§6.1, OSK-13475). A viewer that
+     * does not hold control renders at this size, scaled to fit, and never sends
+     * its own.
+     */
+    cols?: number;
+    rows?: number;
+    lifetime?: ComputerTerminalLifetime;
+    /** It reopened above the history of a shell that ended with the machine or its host. */
+    restarted?: {
+        cause: ComputerTerminalHistoryCause;
+        at: number;
+    };
+    caveats?: ComputerTerminalCaveat[];
+}
+/**
+ * Input a browser surface takes. `tab` needs `computer_browser_tabs_v1`;
+ * `viewport` needs `computer_browser_viewport_v1`.
+ */
+export declare const COMPUTER_BROWSER_INPUT_TYPES: readonly ["pointer", "key", "text", "navigate", "history", "tab", "viewport"];
+/**
+ * What a `viewport` input may ask of the page (OSK-13808), in CSS pixels: the
+ * controlling window's content box, bounded so no window can make the page
+ * absurd for the agent that gets it back, and aspect-clamped (`minAspect` and
+ * `maxAspect` are width ÷ height) so a sliver of a window cannot either.
+ * Device pixel ratio is not part of it: the page keeps the browser's own, so a
+ * high-density screen changes no layout and no picture size.
+ */
+export declare const COMPUTER_BROWSER_VIEWPORT_LIMITS: Readonly<{
+    minWidth: 320;
+    maxWidth: 2560;
+    minHeight: 240;
+    maxHeight: 1600;
+    minAspect: 0.4;
+    maxAspect: 3.2;
+}>;
+/**
+ * The size a `viewport` input asks for, made legal: whole CSS pixels inside
+ * `COMPUTER_BROWSER_VIEWPORT_LIMITS`, its aspect inside the clamp. Total and
+ * idempotent: the window sends what this returns and the daemon applies what
+ * this returns, so both ends agree on the page a size produces. Null for a size
+ * with no area (a hidden or collapsed window asks for nothing).
+ */
+export declare function clampComputerBrowserViewport(size: {
+    width: number;
+    height: number;
+}): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * The client OS a browser `key` input comes from. A person's shortcuts are
+ * mapped onto the Linux page's by the daemon: on `mac`, Command is Control,
+ * Command+Arrow is Home/End and Option+Arrow is Control+Arrow. Omitted, the
+ * keys are sent as they are (the client has already mapped them, or needs none).
+ */
+export declare const COMPUTER_BROWSER_INPUT_PLATFORMS: readonly ["mac", "windows", "linux", "other"];
+export type ComputerBrowserInputPlatform = (typeof COMPUTER_BROWSER_INPUT_PLATFORMS)[number];
+/** The most text one `text` input, `paste` input or `key` input's `text` carries. */
+export declare const COMPUTER_INPUT_TEXT_MAX_LENGTH: number;
+/**
+ * A browser `key` input. `text` is the character the key produces, so a
+ * printable key is inserted by the key itself (one input, the page sees the
+ * key and the character together); IME composition still commits through a
+ * separate `text` input. `platform` names the client OS so the daemon maps its
+ * shortcuts (see `COMPUTER_BROWSER_INPUT_PLATFORMS`).
+ */
+export interface ComputerBrowserKeyInput {
+    type: 'key';
+    action: 'down' | 'up';
+    key: string;
+    code?: string;
+    /** CDP modifier bits: Alt 1, Control 2, Meta 4, Shift 8. */
+    modifiers?: number;
+    text?: string;
+    platform?: ComputerBrowserInputPlatform;
+}
+/** What a page can block on until someone answers (§6.2). Permission prompts have no CDP event. */
+export declare const COMPUTER_BROWSER_DIALOG_KINDS: readonly ["alert", "confirm", "prompt", "beforeunload", "auth"];
+export type ComputerBrowserDialogKind = (typeof COMPUTER_BROWSER_DIALOG_KINDS)[number];
+/** How a dialog ended; `cancelled` is the page or a navigation closing it first. */
+export declare const COMPUTER_BROWSER_DIALOG_OUTCOMES: readonly ["accepted", "dismissed", "credentials_supplied", "cancelled"];
+export type ComputerBrowserDialogOutcome = (typeof COMPUTER_BROWSER_DIALOG_OUTCOMES)[number];
+/** Who answered: the standing policy, the agent, the person, or the page itself. */
+export declare const COMPUTER_BROWSER_DIALOG_ANSWERERS: readonly ["agent_policy", "agent", "person", "page"];
+export type ComputerBrowserDialogAnswerer = (typeof COMPUTER_BROWSER_DIALOG_ANSWERERS)[number];
+/** The most of a dialog's message the surface carries; the page's text is cut there. */
+export declare const COMPUTER_BROWSER_DIALOG_MESSAGE_MAX_LENGTH = 2000;
+/** The longest answer a `prompt` dialog takes. */
+export declare const COMPUTER_BROWSER_DIALOG_PROMPT_MAX_LENGTH = 4096;
+/** The longest username or password an `auth` dialog takes; forwarded to the page only. */
+export declare const COMPUTER_BROWSER_DIALOG_CREDENTIAL_MAX_LENGTH = 1024;
+/** A download's state on the surface (§6.2); a finished one also appears in Files. */
+export declare const COMPUTER_BROWSER_DOWNLOAD_STATES: readonly ["in_progress", "completed", "canceled"];
+export type ComputerBrowserDownloadState = (typeof COMPUTER_BROWSER_DOWNLOAD_STATES)[number];
+/** The downloads one browser surface lists, newest first; older ones are in Files. */
+export declare const COMPUTER_BROWSER_DOWNLOADS_MAX = 20;
+/** Whether the page's file input takes one file or several. */
+export declare const COMPUTER_BROWSER_FILE_CHOOSER_MODES: readonly ["single", "multiple"];
+export type ComputerBrowserFileChooserMode = (typeof COMPUTER_BROWSER_FILE_CHOOSER_MODES)[number];
+/** How a file chooser ended: files went to the page, or the person chose none. */
+export declare const COMPUTER_BROWSER_FILE_CHOOSER_OUTCOMES: readonly ["files_chosen", "cancelled"];
+export type ComputerBrowserFileChooserOutcome = (typeof COMPUTER_BROWSER_FILE_CHOOSER_OUTCOMES)[number];
+/** The most files one answer hands the page. */
+export declare const COMPUTER_BROWSER_FILE_CHOOSER_MAX_FILES = 32;
+/** The longest `accept` attribute the descriptor carries; the page's is cut there. */
+export declare const COMPUTER_BROWSER_FILE_CHOOSER_ACCEPT_MAX_LENGTH = 512;
+/** The longest path one answer names. */
+export declare const COMPUTER_BROWSER_FILE_CHOOSER_PATH_MAX_LENGTH = 4096;
+/** The longest folder `computer:surface:open` may name as a terminal's `cwd`. */
+export declare const COMPUTER_TERMINAL_CWD_MAX_LENGTH = 4096;
+/** The most text one copy-out returns; a longer selection is cut there. */
+export declare const COMPUTER_BROWSER_COPY_MAX_LENGTH: number;
+/** `history` input: the browser's own back, forward and reload. */
+export declare const COMPUTER_BROWSER_HISTORY_ACTIONS: readonly ["back", "forward", "reload"];
+export type ComputerBrowserHistoryAction = (typeof COMPUTER_BROWSER_HISTORY_ACTIONS)[number];
+/** `tab` input. `activate` and `close` name a `tabId`; `open` opens a blank tab. */
+export declare const COMPUTER_BROWSER_TAB_ACTIONS: readonly ["activate", "open", "close"];
+export type ComputerBrowserTabAction = (typeof COMPUTER_BROWSER_TAB_ACTIONS)[number];
+/** The longest URL a `navigate` input carries. */
+export declare const COMPUTER_BROWSER_URL_MAX_LENGTH = 4096;
+export type ComputerSurfaceInputType = (typeof COMPUTER_TERMINAL_INPUT_TYPES)[number] | (typeof COMPUTER_BROWSER_INPUT_TYPES)[number];
+export declare const COMPUTER_FILE_OPERATIONS: readonly ["list", "stat", "read", "write", "mkdir", "move", "delete", "archive"];
+export type ComputerFileOperation = (typeof COMPUTER_FILE_OPERATIONS)[number];
+/**
+ * The read-only file routes that arrived with `computer_files_search_v1`
+ * (§6.3). A separate list: the operations above are the original contract and
+ * the audit/activity vocabulary pins them; these two never mutate.
+ */
+export declare const COMPUTER_FILE_SEARCH_OPERATIONS: readonly ["search", "gitstatus"];
+export type ComputerFileSearchOperation = (typeof COMPUTER_FILE_SEARCH_OPERATIONS)[number];
+/** How a search ended: all of it read, cut at the result limit, or cut at the time bound. */
+export declare const COMPUTER_FILE_SEARCH_STATES: readonly ["complete", "truncated", "timed_out"];
+export type ComputerFileSearchState = (typeof COMPUTER_FILE_SEARCH_STATES)[number];
+/** What `git status` says about one entry of a directory. */
+export declare const COMPUTER_FILE_GIT_MARKS: readonly ["modified", "added", "untracked", "ignored", "conflicted"];
+export type ComputerFileGitMark = (typeof COMPUTER_FILE_GIT_MARKS)[number];
+/** Search bounds, one declaration for the daemon, the API and the client. */
+export declare const COMPUTER_FILE_SEARCH_DEFAULT_LIMIT = 200;
+export declare const COMPUTER_FILE_SEARCH_MAX_LIMIT = 1000;
+export declare const COMPUTER_FILE_SEARCH_DEFAULT_BUDGET_MS = 8000;
+export declare const COMPUTER_FILE_SEARCH_MAX_BUDGET_MS = 20000;
+export declare const COMPUTER_FILE_SEARCH_MAX_QUERY_LENGTH = 200;
+export declare const COMPUTER_FILE_GIT_STATUS_BUDGET_MS = 4000;
+export declare const COMPUTER_FILE_TYPES: readonly ["file", "directory", "symlink", "other"];
+export type ComputerFileType = (typeof COMPUTER_FILE_TYPES)[number];
+/**
+ * Why an entry is withheld rather than listed as readable (§18): the daemon's
+ * own deny set, the machine's `blockedPaths`, a built-in sensitive pattern, or
+ * an operating-system privacy control denying the daemon the folder.
+ */
+export declare const COMPUTER_FILE_WITHHELD_REASONS: readonly ["deny_set", "blocked_path", "sensitive_pattern", "os_permission"];
+export type ComputerFileWithheldReason = (typeof COMPUTER_FILE_WITHHELD_REASONS)[number];
+/**
+ * Why an attachment's scoped watches went stale (§6.3 "degrades to stale, not
+ * to wrong"). The tree then says so and offers a refresh — it never sits on a
+ * silently partial picture.
+ *
+ * - `spawn_failed`: the watcher could not start.
+ * - `watcher_exited`: the watcher ended (tenant code may kill it on a guest).
+ * - `watch_quota`: the account's watch quota is spent.
+ * - `events_overflow`: more changes arrived than are forwarded (a build
+ *   writing thousands of files), so the watcher stopped rather than queue.
+ * - `delivery_gap`: a report was lost between the machine and this viewer.
+ */
+export declare const COMPUTER_FILES_WATCH_DEGRADED_REASONS: readonly ["spawn_failed", "watcher_exited", "watch_quota", "events_overflow", "delivery_gap"];
+export type ComputerFilesWatchDegradedReason = (typeof COMPUTER_FILES_WATCH_DEGRADED_REASONS)[number];
+/** Changes one `computer:files:changed` report carries; more in one window is `events_overflow`. */
+export declare const COMPUTER_FILES_CHANGED_MAX_CHANGES = 256;
+/** The kinds of change a `file_change` activity event reports. */
+export declare const COMPUTER_FILE_CHANGES: readonly ["created", "modified", "deleted", "moved"];
+export type ComputerFileChange = (typeof COMPUTER_FILE_CHANGES)[number];
+/**
+ * The optimistic-concurrency tag a read returns and a write presents. Inode
+ * and nanosecond mtime are decimal strings: both exceed what a JS number holds
+ * exactly.
+ */
+export interface ComputerFileEntityTagFields {
+    inode: string;
+    size: number;
+    mtimeNs: string;
+    /**
+     * A DIRECTORY's contents tag, asked for with `stat {contents: true}`: a
+     * SHA-256 (lowercase hex) over every entry below the folder — its type,
+     * inode, size, change time and relative path. It changes when anything
+     * inside the folder is created, removed, renamed or written, at any depth,
+     * which the folder's own `mtimeNs` does not (that moves only for its direct
+     * children). A recursive delete that presents a tag must present this one,
+     * so it can only erase the contents the person was shown. Comparable only
+     * on the machine that computed it.
+     */
+    contents?: string;
+}
+/** The most entries below a folder a contents tag covers; a larger folder is `too_large`. */
+export declare const COMPUTER_FILE_CONTENTS_TAG_MAX_ENTRIES = 100000;
+/** A contents tag's shape: SHA-256 as lowercase hex. */
+export declare const COMPUTER_FILE_CONTENTS_TAG_PATTERN: RegExp;
+export declare function computerFileEntityTagsEqual(a: ComputerFileEntityTagFields, b: ComputerFileEntityTagFields): boolean;
+export declare const COMPUTER_ACTIVITY_KINDS: readonly ["command", "browser_action", "file_change", "control", "lifecycle"];
+export type ComputerActivityKind = (typeof COMPUTER_ACTIVITY_KINDS)[number];
+/** `summary` is one line, safe to show. */
+export declare const COMPUTER_ACTIVITY_SUMMARY_MAX_LENGTH = 500;
+/** The most command output one event carries; longer output is split across events. */
+export declare const COMPUTER_ACTIVITY_OUTPUT_MAX_LENGTH: number;
+/**
+ * What a viewer without file access reads where a withheld path stood
+ * (security review PM-10, OSK-13701): one stable token, so a client can say
+ * "withheld" rather than render a path-shaped string.
+ */
+export declare const COMPUTER_ACTIVITY_WITHHELD_PLACEHOLDER = "[withheld]";
+export declare const COMPUTER_COMMAND_PHASES: readonly ["started", "output", "exited"];
+export type ComputerCommandPhase = (typeof COMPUTER_COMMAND_PHASES)[number];
+export declare const COMPUTER_LIFECYCLE_EVENTS: readonly ["surface_opened", "surface_ended", "surface_shared", "surface_unshared", "surface_orphaned", "reclaim_imminent", "power", "browser_reset"];
+export type ComputerLifecycleEvent = (typeof COMPUTER_LIFECYCLE_EVENTS)[number];
+/** How a command call ended, as its producer stated it — never inferred from output. */
+export declare const COMPUTER_COMMAND_OUTCOMES: readonly ["succeeded", "failed"];
+export type ComputerCommandOutcome = (typeof COMPUTER_COMMAND_OUTCOMES)[number];
+/**
+ * The `signal` of a command that ended without a process exit status, beyond
+ * `timeout`, `error`, `cancelled` and signal names (task 5-04b, OSK-13614):
+ * `not_started` — the run was refused before it began, and `refusal` says
+ * why; `unknown` — the shell it ran in ended first, so its own exit status
+ * cannot be known.
+ */
+export declare const COMPUTER_COMMAND_NOT_STARTED_SIGNAL = "not_started";
+export declare const COMPUTER_COMMAND_UNKNOWN_END_SIGNAL = "unknown";
+/**
+ * Why a run in an agent's shell never started (`refusal` beside
+ * `signal: 'not_started'`): the shell was busy with another run, had ended,
+ * was still opening, a person held the terminal, the command could not be
+ * handed to the shell, or the request was incomplete. A client shows an
+ * unknown value as "did not start" without a reason.
+ */
+export declare const COMPUTER_COMMAND_START_REFUSALS: readonly ["session_busy", "session_closed", "session_not_ready", "human_control", "start_failed", "invalid_request"];
+export type ComputerCommandStartRefusal = (typeof COMPUTER_COMMAND_START_REFUSALS)[number];
+export declare const COMPUTER_COMMAND_OUTPUT_STREAMS: readonly ["stdout", "stderr"];
+export type ComputerCommandOutputStream = (typeof COMPUTER_COMMAND_OUTPUT_STREAMS)[number];
+/**
+ * The `detail` of each activity kind, exactly as the daemon's stream composes
+ * it (`daemon/src/computer/activity-stream.ts` `compose()`). This is the one
+ * declaration of those shapes: data-provider's zod schema is checked against
+ * it at compile time, and the daemon's replay test pushes every producer's
+ * real events through that schema and fails on a rejected or a stripped field.
+ *
+ * Every text field has been redacted at the source; `redacted` says a secret
+ * pattern matched in at least one of them.
+ */
+export interface ComputerCommandActivityDetail {
+    phase: ComputerCommandPhase;
+    /**
+     * Correlates the started / output / exited events of one call: the tool use
+     * id, or a harness's call id. Absent only when the producer had none (a
+     * harness call announced without an id), and such a call cannot be grouped.
+     */
+    runId?: string;
+    /** The command line as run (or the tool's one whitelisted line: a path, a pattern). Redacted. */
+    commandLine?: string;
+    cwd?: string;
+    /** `exited` only. `null`: the call ended without a process exit status (timeout, error). */
+    exitCode?: number | null;
+    /**
+     * `exited` only: `timeout`, `error`, `cancelled`, `not_started`, `unknown`
+     * (`COMPUTER_COMMAND_NOT_STARTED_SIGNAL`, `COMPUTER_COMMAND_UNKNOWN_END_SIGNAL`),
+     * or a signal name.
+     */
+    signal?: string;
+    /**
+     * `exited` with `signal: 'not_started'`: why the run never began, one of
+     * `COMPUTER_COMMAND_START_REFUSALS` (a string, so a newer reason does not
+     * break an older reader).
+     */
+    refusal?: string;
+    /**
+     * A run in an agent's shell: the terminal lane cursor where it began — the
+     * byte the shell's echo of the command starts at. Announced by
+     * `computer_terminal_command_offset_v1`.
+     */
+    streamOffset?: number;
+    /** `output` only, as produced — the one field that is not redacted. */
+    output?: string;
+    /** `output` only: this event's output was cut at `COMPUTER_ACTIVITY_OUTPUT_MAX_LENGTH`. */
+    outputTruncated?: true;
+    /**
+     * `output` only: this viewer may not read the machine's files (the watch
+     * tier), so the output was not sent to them (PM-10, OSK-13701). Set by the
+     * relay's per-viewer projection, never by the daemon.
+     */
+    outputWithheld?: true;
+    stream?: ComputerCommandOutputStream;
+    /** `output` only: bytes the live view did not stream before this event. */
+    droppedBytes?: number;
+    /** `output` only: the per-call streaming cap was reached; nothing further streams. */
+    streamTruncated?: true;
+    /** The agent tool behind the call (`Bash`, `Grep`); absent for a terminal's own commands. */
+    tool?: string;
+    outcome?: ComputerCommandOutcome;
+    durationMs?: number;
+    /**
+     * An agent session acted on a person's surface shared with it (§5.4): the
+     * audit record keeps it. Typed text is never carried on such an event.
+     */
+    shared?: true;
+    redacted?: true;
+}
+export interface ComputerActivityBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ComputerBrowserActionActivityDetail {
+    /** `navigate`, `click`, `type`, … */
+    action: string;
+    url?: string;
+    tabId?: string;
+    /** The element acted on (role + name), from the daemon's snapshot. Never typed text. */
+    target?: string;
+    /** A short label for the target, never typed text. */
+    label?: string;
+    /** The target's box, for the cursor and ripple overlay. */
+    box?: ComputerActivityBox;
+    /** A two-target action's second box (a drag's destination). */
+    toBox?: ComputerActivityBox;
+    /** A named key, mouse button or mode token — never a typed character. */
+    key?: string;
+    count?: number;
+    /** `type`: how many characters, never which. */
+    textLength?: number;
+    /** An agent session acted on a person's window shared with it (§5.4). */
+    shared?: true;
+    redacted?: true;
+}
+export interface ComputerFileChangeActivityDetail {
+    change: ComputerFileChange;
+    /** Where the file is now (a move's destination). */
+    path: string;
+    /** A move's previous path. */
+    fromPath?: string;
+    bytes?: number;
+    redacted?: true;
+}
+export interface ComputerControlActivityDetail {
+    change: ComputerControlActivityChange;
+    epoch?: number;
+    /** The holder before (for a request: the holding person). */
+    from?: ComputerWireActor;
+    /** The holder after (for a request: the requester). */
+    to?: ComputerWireActor;
+    /** A handback note, or what caused a reveal. */
+    note?: string;
+    redacted?: true;
+}
+export interface ComputerLifecycleActivityDetail {
+    event: ComputerLifecycleEvent;
+    surfaceKind?: string;
+    title?: string;
+    endedReason?: ComputerSurfaceEndReason;
+    /** `power`: the machine's power phase now. */
+    phase?: string;
+    /** `surface_shared`: the share mode. */
+    mode?: string;
+    /** `surface_shared` / `surface_unshared`: the agent session. */
+    agent?: ComputerWireActor;
+    /** `surface_orphaned`: the person who opened it and lost access. */
+    opener?: ComputerWireActor;
+    /** `reclaim_imminent`: epoch ms the daemon hands the surface back unless the person acts. */
+    deadline?: number;
+    redacted?: true;
+}
+export interface ComputerActivityDetailByKind {
+    command: ComputerCommandActivityDetail;
+    browser_action: ComputerBrowserActionActivityDetail;
+    file_change: ComputerFileChangeActivityDetail;
+    control: ComputerControlActivityDetail;
+    lifecycle: ComputerLifecycleActivityDetail;
+}
+/**
+ * What `daemon:computer:services` (and the agent's `computer.services` call)
+ * asks of the machine: add or replace one service by name, remove one, or
+ * answer the list. Declaring and withdrawing need `open`; listing needs
+ * `observe`.
+ */
+export declare const COMPUTER_DECLARED_SERVICE_ACTIONS: readonly ["declare", "withdraw", "list"];
+export type ComputerDeclaredServiceAction = (typeof COMPUTER_DECLARED_SERVICE_ACTIONS)[number];
+/**
+ * The tool an agent session's declaration rides to its own daemon: the same
+ * `daemon:tool:request` channel that carries its other calls, answered by the
+ * same gate as `daemon:computer:services`. The input is the API's (action,
+ * principal, agent, service or name); the session is the request's own.
+ */
+export declare const COMPUTER_SERVICES_TOOL_NAME = "computer.services";
+/** A refused `computer.services` call: this prefix, then the refusal as JSON. */
+export declare const COMPUTER_SERVICES_TOOL_ERROR_PREFIX = "computer_services_refused:";
+/** The operation each action needs, by the one access vocabulary. */
+export declare function computerDeclaredServiceOperation(action: ComputerDeclaredServiceAction): Extract<ComputerOperation, 'open' | 'observe'>;
+export declare const COMPUTER_DECLARED_SERVICE_PROTOCOLS: readonly ["http", "https"];
+export type ComputerDeclaredServiceProtocol = (typeof COMPUTER_DECLARED_SERVICE_PROTOCOLS)[number];
+/** Services one machine holds at once; one more is `service_limit`. */
+export declare const COMPUTER_DECLARED_SERVICES_MAX = 16;
+export declare const COMPUTER_DECLARED_SERVICE_NAME_MAX_LENGTH = 48;
+export declare const COMPUTER_DECLARED_SERVICE_PATH_MAX_LENGTH = 512;
+/**
+ * The one host a declared service names. A declaration carries a port and a
+ * path, never a host or a URL: the target is always this machine's own
+ * loopback, by construction, and a request that names anything else is
+ * refused as malformed rather than narrowed.
+ */
+export declare const COMPUTER_DECLARED_SERVICE_HOST = "localhost";
+/** A service's name: its key on the machine, lower case, shown as written. */
+export declare const COMPUTER_DECLARED_SERVICE_NAME_PATTERN: RegExp;
+/** A service as it is declared: what it is called and where it listens. */
+export interface ComputerDeclaredServiceSpec {
+    name: string;
+    /** A TCP port on the machine's loopback, 1 to 65535. */
+    port: number;
+    /** Absolute; `/` when the declaration named none. */
+    path: string;
+    protocol: ComputerDeclaredServiceProtocol;
+}
+/** A declared service as the manifest carries it. */
+export interface ComputerDeclaredService extends ComputerDeclaredServiceSpec {
+    /** Who declared it: an agent session or a person. */
+    declaredBy: ComputerWireActor;
+    /** Epoch ms of the declaration (or of the latest one that replaced it). */
+    declaredAt: number;
+}
+/** Which part of a declaration was refused. */
+export declare const COMPUTER_DECLARED_SERVICE_PROBLEMS: readonly ["shape", "name", "port", "path", "protocol"];
+export type ComputerDeclaredServiceProblem = (typeof COMPUTER_DECLARED_SERVICE_PROBLEMS)[number];
+/**
+ * A declaration, checked and filled in, or the part of it that was refused.
+ * The daemon, the API, the client and the CLI all read a declaration through
+ * this one rule, so a service none of them would accept never reaches the
+ * manifest.
+ */
+export declare function computerDeclaredServiceSpec(raw: unknown): {
+    ok: true;
+    spec: ComputerDeclaredServiceSpec;
+} | {
+    ok: false;
+    problem: ComputerDeclaredServiceProblem;
+};
+/**
+ * The address a declared service opens at in the computer's browser: always
+ * this machine's loopback. Throws on a spec the rule above would refuse, so a
+ * caller can never be handed an address off the machine.
+ */
+export declare function computerDeclaredServiceUrl(service: Pick<ComputerDeclaredServiceSpec, 'port'> & Partial<Pick<ComputerDeclaredServiceSpec, 'path' | 'protocol'>>): string;
+export declare const COMPUTER_MACHINE_KINDS: readonly ["dedicated", "personal"];
+export type ComputerMachineKind = (typeof COMPUTER_MACHINE_KINDS)[number];
+/**
+ * One picture per machine state; none of them is a spinner without a bound,
+ * and none collapses two states into the reassuring one.
+ */
+export declare const COMPUTER_POWER_PHASES: readonly ["on", "booting", "stopping", "off", "archived", "removing", "gone", "blind", "unresponsive", "not_a_computer", "needs_update", "online", "offline", "needs_sign_in", "not_allowed"];
+export type ComputerPowerPhase = (typeof COMPUTER_POWER_PHASES)[number];
+/**
+ * Phases a personal machine can be in. `blind` is shared with a Dedicated
+ * Runtime: the machine's presence could not be READ, which is not the same
+ * fact as "offline" and must not be shown as it (§10, §18; 10-09).
+ */
+export declare const COMPUTER_PERSONAL_POWER_PHASES: readonly ["online", "offline", "needs_sign_in", "not_allowed", "needs_update", "blind"];
+/**
+ * Why a personal machine needs signing in again — `power.reason` on
+ * `needs_sign_in`. `needs_reauth`: the daemon's credential stopped refreshing
+ * (it latches the Harness mark and waits). `revoked`: the machine's sign-in was
+ * revoked from the account, so it is no longer this person's machine until it
+ * is signed in again. Same next action, different fact, different picture.
+ */
+export declare const COMPUTER_PERSONAL_SIGN_IN_REASONS: readonly ["needs_reauth", "revoked"];
+export type ComputerPersonalSignInReason = (typeof COMPUTER_PERSONAL_SIGN_IN_REASONS)[number];
+/** Why a stopped machine would also refuse a start, so the screen does not offer one (§10). */
+export declare const COMPUTER_START_REFUSALS: readonly ["spend_cap", "entitlement"];
+export type ComputerStartRefusal = (typeof COMPUTER_START_REFUSALS)[number];
+/**
+ * The picture for each Dedicated Runtime lease state. Its keys are the lease
+ * states; `@skrr-ai/data-provider` asserts at compile time that they are
+ * exactly `MachineLeaseStateName`, so a new lease state fails to compile there
+ * until it is given a picture here — never a default.
+ */
+export declare const COMPUTER_LEASE_STATE_POWER_PHASE: Readonly<{
+    readonly ready: "on";
+    readonly active: "on";
+    readonly idle: "on";
+    readonly requested: "booting";
+    readonly provisioning: "booting";
+    readonly bootstrapping: "booting";
+    readonly starting: "booting";
+    readonly restarting: "booting";
+    readonly recovering: "booting";
+    readonly stopping: "stopping";
+    readonly snapshotting: "stopping";
+    readonly stopped: "off";
+    readonly archived: "archived";
+    readonly terminating: "removing";
+    readonly failed: "gone";
+    readonly lost: "gone";
+    readonly terminated: "gone";
+    readonly pausing: "not_a_computer";
+    readonly paused: "not_a_computer";
+    readonly resuming: "not_a_computer";
+}>;
+export type ComputerLeaseStateName = keyof typeof COMPUTER_LEASE_STATE_POWER_PHASE;
+/** The phase a Dedicated Runtime lease state shows as, or `null` for a state this build does not know. */
+export declare function computerPowerPhaseForLeaseState(state: unknown): ComputerPowerPhase | null;
+/** Whether the phase shows the desktop. */
+export declare function computerShowsDesktop(phase: ComputerPowerPhase): boolean;
+/** Power actions are offered for a Dedicated Runtime only; a personal machine has none (§18). */
+export declare function computerOffersPowerActions(machineKind: ComputerMachineKind): boolean;