@skrr-ai/cli 0.1.86 → 0.1.88

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

@@ -0,0 +1,1070 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPUTER_BROWSER_DIALOG_CREDENTIAL_MAX_LENGTH = exports.COMPUTER_BROWSER_DIALOG_PROMPT_MAX_LENGTH = exports.COMPUTER_BROWSER_DIALOG_MESSAGE_MAX_LENGTH = exports.COMPUTER_BROWSER_DIALOG_ANSWERERS = exports.COMPUTER_BROWSER_DIALOG_OUTCOMES = exports.COMPUTER_BROWSER_DIALOG_KINDS = exports.COMPUTER_INPUT_TEXT_MAX_LENGTH = exports.COMPUTER_BROWSER_INPUT_PLATFORMS = exports.COMPUTER_BROWSER_INPUT_TYPES = exports.COMPUTER_TERMINAL_CAVEATS = exports.COMPUTER_TERMINAL_HISTORY_CAUSES = exports.COMPUTER_TERMINAL_LIFETIMES = exports.COMPUTER_TERMINAL_INPUT_TYPES = exports.COMPUTER_TERMINAL_SIGNALS = exports.COMPUTER_DIAGNOSTICS_MAX_STREAMS = exports.COMPUTER_DIAGNOSTICS_INTERVAL_MS = exports.COMPUTER_DIAGNOSTIC_COUNTERS = exports.COMPUTER_FRAME_ACK_TIMEOUT_MS = exports.COMPUTER_FRAME_MAX_BYTES = exports.COMPUTER_BROWSER_VIEWPORT = exports.COMPUTER_SURFACE_END_REASONS = exports.COMPUTER_SURFACE_STATES = exports.COMPUTER_SURFACE_KINDS = exports.COMPUTER_CONTROL_ACTIVITY_CHANGES = exports.COMPUTER_CONTROL_CHANGE_REASONS = exports.COMPUTER_SURFACE_UNPIN_REASONS = exports.COMPUTER_SURFACE_PIN_ACTIONS = exports.COMPUTER_SHARE_MODES = exports.COMPUTER_SHARE_ACTIONS = exports.COMPUTER_CONTROL_ACTIONS = exports.COMPUTER_AGENT_WRITE_WAIT_MS = exports.COMPUTER_RECONNECT_GRACE_MS = exports.COMPUTER_RECLAIM_WARNING_MS = exports.COMPUTER_CONTROL_IDLE_MS = exports.COMPUTER_HANDBACK_NOTE_MAX_LENGTH = exports.COMPUTER_GRANT_TIERS = exports.COMPUTER_OPERATIONS = exports.COMPUTER_ACCESS_LEVELS = exports.COMPUTER_ACTIVITY_ACTOR_KINDS = exports.COMPUTER_ACTOR_KINDS = exports.COMPUTER_LEGACY_REFUSAL_SPELLINGS = exports.COMPUTER_REFUSAL_CODES = exports.COMPUTER_CAPABILITY_VALUES = exports.COMPUTER_CAPABILITIES = exports.COMPUTER_SERVER_EVENT_KEYS = exports.DAEMON_COMPUTER_REPORT_EVENT_KEYS = exports.DAEMON_COMPUTER_EVENT_NAMES = exports.COMPUTER_EVENT_NAMES = exports.DAEMON_COMPUTER_EVENTS = exports.COMPUTER_EVENTS = void 0;
+exports.COMPUTER_DECLARED_SERVICE_PROBLEMS = exports.COMPUTER_DECLARED_SERVICE_NAME_PATTERN = exports.COMPUTER_DECLARED_SERVICE_HOST = exports.COMPUTER_DECLARED_SERVICE_PATH_MAX_LENGTH = exports.COMPUTER_DECLARED_SERVICE_NAME_MAX_LENGTH = exports.COMPUTER_DECLARED_SERVICES_MAX = exports.COMPUTER_DECLARED_SERVICE_PROTOCOLS = exports.COMPUTER_SERVICES_TOOL_ERROR_PREFIX = exports.COMPUTER_SERVICES_TOOL_NAME = exports.COMPUTER_DECLARED_SERVICE_ACTIONS = exports.COMPUTER_COMMAND_OUTPUT_STREAMS = exports.COMPUTER_COMMAND_START_REFUSALS = exports.COMPUTER_COMMAND_UNKNOWN_END_SIGNAL = exports.COMPUTER_COMMAND_NOT_STARTED_SIGNAL = exports.COMPUTER_COMMAND_OUTCOMES = exports.COMPUTER_LIFECYCLE_EVENTS = exports.COMPUTER_COMMAND_PHASES = exports.COMPUTER_ACTIVITY_WITHHELD_PLACEHOLDER = exports.COMPUTER_ACTIVITY_OUTPUT_MAX_LENGTH = exports.COMPUTER_ACTIVITY_SUMMARY_MAX_LENGTH = exports.COMPUTER_ACTIVITY_KINDS = exports.COMPUTER_FILE_CONTENTS_TAG_PATTERN = exports.COMPUTER_FILE_CONTENTS_TAG_MAX_ENTRIES = exports.COMPUTER_FILE_CHANGES = exports.COMPUTER_FILES_CHANGED_MAX_CHANGES = exports.COMPUTER_FILES_WATCH_DEGRADED_REASONS = exports.COMPUTER_FILE_WITHHELD_REASONS = exports.COMPUTER_FILE_TYPES = exports.COMPUTER_FILE_GIT_STATUS_BUDGET_MS = exports.COMPUTER_FILE_SEARCH_MAX_QUERY_LENGTH = exports.COMPUTER_FILE_SEARCH_MAX_BUDGET_MS = exports.COMPUTER_FILE_SEARCH_DEFAULT_BUDGET_MS = exports.COMPUTER_FILE_SEARCH_MAX_LIMIT = exports.COMPUTER_FILE_SEARCH_DEFAULT_LIMIT = exports.COMPUTER_FILE_GIT_MARKS = exports.COMPUTER_FILE_SEARCH_STATES = exports.COMPUTER_FILE_SEARCH_OPERATIONS = exports.COMPUTER_FILE_OPERATIONS = exports.COMPUTER_BROWSER_URL_MAX_LENGTH = exports.COMPUTER_BROWSER_TAB_ACTIONS = exports.COMPUTER_BROWSER_HISTORY_ACTIONS = exports.COMPUTER_BROWSER_COPY_MAX_LENGTH = exports.COMPUTER_TERMINAL_CWD_MAX_LENGTH = exports.COMPUTER_BROWSER_FILE_CHOOSER_PATH_MAX_LENGTH = exports.COMPUTER_BROWSER_FILE_CHOOSER_ACCEPT_MAX_LENGTH = exports.COMPUTER_BROWSER_FILE_CHOOSER_MAX_FILES = exports.COMPUTER_BROWSER_FILE_CHOOSER_OUTCOMES = exports.COMPUTER_BROWSER_FILE_CHOOSER_MODES = exports.COMPUTER_BROWSER_DOWNLOADS_MAX = exports.COMPUTER_BROWSER_DOWNLOAD_STATES = void 0;
+exports.COMPUTER_LEASE_STATE_POWER_PHASE = exports.COMPUTER_START_REFUSALS = exports.COMPUTER_PERSONAL_SIGN_IN_REASONS = exports.COMPUTER_PERSONAL_POWER_PHASES = exports.COMPUTER_POWER_PHASES = exports.COMPUTER_MACHINE_KINDS = void 0;
+exports.normalizeComputerRefusalCode = normalizeComputerRefusalCode;
+exports.computerTierOperations = computerTierOperations;
+exports.computerOperationAllowed = computerOperationAllowed;
+exports.computerAccessOperations = computerAccessOperations;
+exports.computerControlChangeIsHolderChange = computerControlChangeIsHolderChange;
+exports.computerLeaseInputRefusal = computerLeaseInputRefusal;
+exports.computerLeaseAcceptsInput = computerLeaseAcceptsInput;
+exports.computerFileEntityTagsEqual = computerFileEntityTagsEqual;
+exports.computerDeclaredServiceOperation = computerDeclaredServiceOperation;
+exports.computerDeclaredServiceSpec = computerDeclaredServiceSpec;
+exports.computerDeclaredServiceUrl = computerDeclaredServiceUrl;
+exports.computerPowerPhaseForLeaseState = computerPowerPhaseForLeaseState;
+exports.computerShowsDesktop = computerShowsDesktop;
+exports.computerOffersPowerActions = computerOffersPowerActions;
+// ---------------------------------------------------------------------------
+// Events (§7.1)
+// ---------------------------------------------------------------------------
+/**
+ * Client ⇄ API, on the existing `/ws/agentic` socket. A request the client
+ * needs answered is acknowledged through the Socket.IO acknowledgement
+ * callback.
+ */
+exports.COMPUTER_EVENTS = {
+    /** client → API: attach to a machine. */
+    attach: 'computer:attach',
+    /** client → API: leave. */
+    detach: 'computer:detach',
+    /** API → client: this attachment was detached, with the reason (revoked, stale generation, …). */
+    detached: 'computer:detached',
+    /** API → client: a whole manifest, or a revisioned delta. */
+    manifest: 'computer:manifest',
+    /** client → API: observe one surface. */
+    subscribe: 'computer:surface:subscribe',
+    /** client → API: stop observing one surface. */
+    unsubscribe: 'computer:surface:unsubscribe',
+    /** API → client: terminal bytes with a byte cursor, or a page frame. */
+    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.
+     */
+    frameAck: 'computer:surface:frame:ack',
+    /** client → API: take / release / request / grant / decline. */
+    control: 'computer:surface:control',
+    /** client → API: share or unshare one of the person's own surfaces with an agent session. */
+    share: 'computer:surface:share',
+    /** client → API: one input, carrying the lease epoch. Never acknowledged. */
+    input: 'computer:surface:input',
+    /** client → API: open a person's own terminal or browser window. */
+    open: 'computer:surface:open',
+    /** client → API: close a surface. */
+    close: 'computer:surface:close',
+    /** API → client: activity events. */
+    activity: 'computer:activity',
+    /** client → API: the activity events after a `seq`, to fill a gap. */
+    activityFill: 'computer:activity:fill',
+    /** client → API: the directories expanded and files open, which scope the file watches. */
+    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`.
+     */
+    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`.
+     */
+    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`.
+     */
+    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`.
+     */
+    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`.
+ */
+exports.DAEMON_COMPUTER_EVENTS = {
+    // API → daemon
+    /** Bind an attachment: its principal, operations and (dedicated) generation. */
+    attach: 'daemon:computer:attach',
+    detach: 'daemon:computer:detach',
+    /** The machine's grant set, whole, on registration and on every change. */
+    grants: 'daemon:computer:grants',
+    subscribe: 'daemon:computer:surface:subscribe',
+    unsubscribe: 'daemon:computer:surface:unsubscribe',
+    frameAck: 'daemon:computer:surface:frame:ack',
+    control: 'daemon:computer:surface:control',
+    share: 'daemon:computer:surface:share',
+    input: 'daemon:computer:surface:input',
+    open: 'daemon:computer:surface:open',
+    close: 'daemon:computer:surface:close',
+    activityFill: 'daemon:computer:activity:fill',
+    filesWatch: 'daemon:computer:files:watch',
+    /** One file operation, relayed from `/api/machines/:machineId/files/<op>`. */
+    files: 'daemon:computer:files',
+    dialog: 'daemon:computer:surface:dialog',
+    copy: 'daemon:computer:surface:copy',
+    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`.
+     */
+    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`.
+     */
+    services: 'daemon:computer:services',
+    // daemon → API
+    /** The answer to any request that carried a `requestId`. */
+    ack: 'daemon:computer:ack',
+    manifest: 'daemon:computer:manifest',
+    data: 'daemon:computer:surface:data',
+    activity: 'daemon:computer:activity',
+    /** The daemon detached an attachment itself, e.g. its grant was revoked. */
+    detached: 'daemon:computer:detached',
+    /** One attachment's scoped watches saw changes, or went stale (§6.3). */
+    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.
+     */
+    diagnostics: 'daemon:computer:diagnostics',
+};
+exports.COMPUTER_EVENT_NAMES = Object.values(exports.COMPUTER_EVENTS);
+exports.DAEMON_COMPUTER_EVENT_NAMES = Object.values(exports.DAEMON_COMPUTER_EVENTS);
+/** The daemon → API events; every other `daemon:computer:*` event flows API → daemon. */
+exports.DAEMON_COMPUTER_REPORT_EVENT_KEYS = [
+    'ack',
+    'manifest',
+    'data',
+    'activity',
+    'detached',
+    'filesChanged',
+    'diagnostics',
+];
+/** The API → client events; every other `computer:*` event flows client → API. */
+exports.COMPUTER_SERVER_EVENT_KEYS = [
+    'detached',
+    'manifest',
+    'data',
+    'activity',
+    'filesChanged',
+];
+// ---------------------------------------------------------------------------
+// Capabilities (§7.1)
+// ---------------------------------------------------------------------------
+/**
+ * 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`.
+ */
+exports.COMPUTER_CAPABILITIES = {
+    /** Manifest, surfaces, control leases, terminal surfaces, activity core. */
+    computer: 'computer_v1',
+    /** The grant set and the daemon's own check of every attachment against it (§9). */
+    access: 'computer_access_v1',
+    /** The file surface: `daemon:computer:files` and `computer:files:watch` (§6.3). */
+    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.
+     */
+    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.
+     */
+    filesFenced: 'computer_files_fenced_v1',
+    /** Observe attachments on a browser surface, separate from control (§6.2). */
+    browserObserve: 'computer_browser_observe_v1',
+    /** A browser surface's tab strip and tab input (§6.2). */
+    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.
+     */
+    browserPage: 'computer_browser_page_v1',
+    /** Sharing a person's own surface with an agent session (§5.4). */
+    surfaceShare: 'computer_surface_share_v1',
+    /** Pinning a surface an open human-input request names: `daemon:computer:surface:pin` (§8). */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    declaredServices: 'computer_declared_services_v1',
+};
+exports.COMPUTER_CAPABILITY_VALUES = Object.values(exports.COMPUTER_CAPABILITIES);
+// ---------------------------------------------------------------------------
+// Refusals (§5.2, §6.3, §7.2 R4/R8, §9, §18)
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+exports.COMPUTER_REFUSAL_CODES = [
+    /** A person holds the surface; the agent may wait, do other work, or ask. */
+    'human_control',
+    /** The input was issued under a lease epoch that is no longer current. */
+    'stale_epoch',
+    /** The attachment is bound to a Dedicated Runtime generation that has been replaced. */
+    'stale_generation',
+    /** The file changed since it was read; the refusal carries the current tag. */
+    'file_changed',
+    /** The machine's daemon did not announce the capability this needs. */
+    'capability_missing',
+    /** The principal may not perform this operation on this machine. */
+    'unauthorized',
+    /** Control cannot move this way, e.g. an agent asking to take from a person. */
+    'control_denied',
+    /** The attachment does not hold the lease it is acting under. */
+    'not_holder',
+    'attachment_limit',
+    'observer_limit',
+    'watch_limit',
+    'grant_limit',
+    /** The machine runs as many browsers as it allows; a person's own window waits for one to close. */
+    'browser_limit',
+    'rate_limited',
+    /** The machine, surface, tab or request does not exist. */
+    'not_found',
+    /** The surface has ended. */
+    'surface_ended',
+    /** The machine is not running (§10 decides the picture). */
+    'machine_unavailable',
+    /** The machine's daemon is not answering. */
+    'daemon_unreachable',
+    /** A bounded wait ran out (§7.2 R4). */
+    'timeout',
+    'invalid_request',
+    /** A personal machine has not allowed this part of the computer (§18, D11). */
+    'consent_missing',
+    /** The path is withheld by the daemon's deny set, `blockedPaths` or a sensitive pattern (§18). */
+    'path_withheld',
+    /** The file is over the size the editor or the read accepts. */
+    'too_large',
+    /** The machine has as many declared services as it allows (`COMPUTER_DECLARED_SERVICES_MAX`). */
+    'service_limit',
+];
+/**
+ * Older spellings the daemon boundary accepts for one release (§5.2). After
+ * that release this map is emptied, and nothing else names the old spelling.
+ */
+exports.COMPUTER_LEGACY_REFUSAL_SPELLINGS = Object.freeze({
+    live_view_active: 'human_control',
+});
+/** The canonical code for a received spelling, or `null` when it is not a computer refusal. */
+function normalizeComputerRefusalCode(code) {
+    if (typeof code !== 'string') {
+        return null;
+    }
+    if (exports.COMPUTER_REFUSAL_CODES.includes(code)) {
+        return code;
+    }
+    return Object.prototype.hasOwnProperty.call(exports.COMPUTER_LEGACY_REFUSAL_SPELLINGS, code)
+        ? exports.COMPUTER_LEGACY_REFUSAL_SPELLINGS[code]
+        : null;
+}
+// ---------------------------------------------------------------------------
+// Actors, operations and grant tiers (§4.2, §9, D10)
+// ---------------------------------------------------------------------------
+exports.COMPUTER_ACTOR_KINDS = ['agent', 'human'];
+/**
+ * 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.
+ */
+exports.COMPUTER_ACTIVITY_ACTOR_KINDS = [...exports.COMPUTER_ACTOR_KINDS, 'system'];
+/**
+ * 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.
+ */
+exports.COMPUTER_ACCESS_LEVELS = ['owner', 'watch', 'operate'];
+/**
+ * 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`.
+ */
+exports.COMPUTER_OPERATIONS = [
+    'observe',
+    'control',
+    'files.read',
+    'files.write',
+    'open',
+    'power',
+];
+/** A grant is one of two fixed tiers: a finer grant cannot be enforced on a shell. */
+exports.COMPUTER_GRANT_TIERS = ['watch', 'operate'];
+const TIER_OPERATIONS = Object.freeze({
+    /** See every surface on the machine and its activity. No input, no file browsing. */
+    watch: Object.freeze(['observe']),
+    /** The machine's account in another person's hands. */
+    operate: Object.freeze(['observe', 'control', 'files.read', 'files.write', 'open']),
+});
+/** The fixed set of operations a grant tier carries. */
+function computerTierOperations(tier) {
+    return TIER_OPERATIONS[tier];
+}
+/** Whether a grant tier carries `operation`. */
+function computerOperationAllowed(tier, operation) {
+    return TIER_OPERATIONS[tier].includes(operation);
+}
+/** The operations an access level carries: the owner holds every one. */
+function computerAccessOperations(level) {
+    return level === 'owner' ? exports.COMPUTER_OPERATIONS : TIER_OPERATIONS[level];
+}
+// ---------------------------------------------------------------------------
+// Control leases (§4.3, §5)
+// ---------------------------------------------------------------------------
+/** A person releasing control may leave a note for the agent (§8). */
+exports.COMPUTER_HANDBACK_NOTE_MAX_LENGTH = 2000;
+/** A person holding control is released after this long without human input (§5.1 rule 4). */
+exports.COMPUTER_CONTROL_IDLE_MS = 10 * 60 * 1000;
+/** How long before idle reclaim of a person's hold the daemon says it is coming (§8). */
+exports.COMPUTER_RECLAIM_WARNING_MS = 60 * 1000;
+/** A transport blip shorter than this changes no lease (§7.2 R6). */
+exports.COMPUTER_RECONNECT_GRACE_MS = 10 * 1000;
+/** An agent terminal write waits this long for a person to hand back before refusing (§5.2). */
+exports.COMPUTER_AGENT_WRITE_WAIT_MS = 60 * 1000;
+/** What a person can do to a surface's lease (§5.1, §5.3). */
+exports.COMPUTER_CONTROL_ACTIONS = [
+    /** A person takes an agent-held surface. Human priority over the agent is unconditional. */
+    'take',
+    /** The holder hands back, optionally with a note. */
+    'release',
+    /** Ask a PERSON who holds the surface for it; leaves the lease untouched. */
+    'request',
+    /** The holding person gives the surface to the person who requested it. */
+    'grant',
+    /** The holding person declines a request. Changes nothing. */
+    'decline',
+    /**
+     * The person who stopped driving a browser without handing it back says the
+     * agent may see the page again (D12). Changes no holder.
+     */
+    'reveal',
+    /**
+     * Sign out everywhere (§6.2, OSK-13499): end every browser window on the
+     * computer — the agent's and the person's, which share one cookie jar —
+     * stop the browser and remove its profile. On a browser surface, by the
+     * owner or the person holding it; never an observer. Needs
+     * `computer_browser_reset_v1`. Answers with the asking surface's last lease.
+     */
+    'reset_browser',
+];
+/** Sharing one of a person's own surfaces with one agent session (§5.4). */
+exports.COMPUTER_SHARE_ACTIONS = ['share', 'unshare'];
+exports.COMPUTER_SHARE_MODES = ['observe', 'control'];
+/** `daemon:computer:surface:pin` actions (§8). */
+exports.COMPUTER_SURFACE_PIN_ACTIONS = ['pin', 'unpin'];
+/** Why a pin ended: the request it held the surface for left `open`. */
+exports.COMPUTER_SURFACE_UNPIN_REASONS = ['answered', 'dismissed', 'expired'];
+/** Why a lease changed holder. Carried by `control` activity events and the audit record. */
+exports.COMPUTER_CONTROL_CHANGE_REASONS = [
+    'take',
+    'release',
+    'grant',
+    /** No human input for `COMPUTER_CONTROL_IDLE_MS`. */
+    'idle',
+    /** The holding client stayed disconnected past the reconnect grace. */
+    'disconnect',
+    /** A person's surface was shared with an agent session for control. */
+    'share',
+    /** The share ended: unshared, or the agent session ended. */
+    'unshare',
+    /** The holder's grant was revoked. */
+    'revoked',
+    'machine_stopped',
+];
+/**
+ * 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.
+ */
+exports.COMPUTER_CONTROL_ACTIVITY_CHANGES = [
+    ...exports.COMPUTER_CONTROL_CHANGE_REASONS,
+    /** A person asked the holding person for the surface. */
+    'request',
+    'request_declined',
+    'request_expired',
+    'request_withdrawn',
+    /** The page is visible to the agent again; no holder changed. */
+    'revealed',
+];
+/** Whether a `control` activity change moved the lease to a new holder. */
+function computerControlChangeIsHolderChange(change) {
+    return exports.COMPUTER_CONTROL_CHANGE_REASONS.includes(change);
+}
+/**
+ * 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.
+ */
+function computerLeaseInputRefusal(lease, attachmentId, epoch) {
+    if (lease.epoch !== epoch) {
+        return 'stale_epoch';
+    }
+    if (lease.holder.kind !== 'human' || !lease.holderAttachmentId) {
+        return 'not_holder';
+    }
+    return lease.holderAttachmentId === attachmentId ? null : 'not_holder';
+}
+/** Whether the lease accepts an input from `attachmentId` issued under `epoch`. */
+function computerLeaseAcceptsInput(lease, attachmentId, epoch) {
+    return computerLeaseInputRefusal(lease, attachmentId, epoch) === null;
+}
+// ---------------------------------------------------------------------------
+// Surfaces and lanes (§4.2, §6.1, §6.2, §7.2 R3/R7)
+// ---------------------------------------------------------------------------
+/** Files are a namespace, not a leased surface (§6.3). */
+exports.COMPUTER_SURFACE_KINDS = ['terminal', 'browser'];
+exports.COMPUTER_SURFACE_STATES = ['live', 'ended'];
+/**
+ * Why a surface ended (§10). An ended surface stays as a tombstone with its
+ * history until dismissed, and its reason is shown, never swallowed.
+ */
+exports.COMPUTER_SURFACE_END_REASONS = [
+    'machine_stopped',
+    /** The machine's owner closed a surface someone else opened (§5.1 rule 8). */
+    'closed_by_owner',
+    /** Whoever opened the surface closed it. */
+    'closed',
+    'process_exited',
+    'daemon_restarted',
+    'browser_crashed',
+    /** The browser session was reclaimed by idle or wall-clock expiry. */
+    'expired',
+    /** Someone signed the computer's browser out everywhere, which ends every browser window. */
+    'browser_reset',
+];
+/** The browser's fixed logical viewport, whoever is looking (§6.2). */
+exports.COMPUTER_BROWSER_VIEWPORT = Object.freeze({ width: 1280, height: 800 });
+/** One frame never exceeds this, so it fits the SSE transport every guest uses (§7.2 R7). */
+exports.COMPUTER_FRAME_MAX_BYTES = 1024 * 1024;
+/**
+ * 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.
+ */
+exports.COMPUTER_FRAME_ACK_TIMEOUT_MS = 5_000;
+/**
+ * The daemon's frame-lane counters (`daemon:computer:diagnostics`, OSK-13616).
+ * Cumulative since `since`, so a lost report loses nothing but its moment.
+ */
+exports.COMPUTER_DIAGNOSTIC_COUNTERS = [
+    /** The browser handed the lane a frame for a live viewer: the page changed. */
+    'frames_produced',
+    /** A browser frame handed to the transport for a viewer. */
+    'frames_sent',
+    /** The transport was down when a frame was produced; the live view keeps it for its resume. */
+    'frames_held_disconnected',
+    /** A frame larger than the smallest transport, dropped at the source (R7). */
+    'frames_dropped_oversize',
+    /** The transport refused a frame; the next one is the newest anyway. */
+    'frames_send_failed',
+    /** A viewer acknowledged the frame in flight. */
+    'frames_acked',
+    /** No acknowledgement within the bound: the slot freed itself. */
+    'frames_ack_timeout',
+    /** A viewer's frame slot was freed by a resubscribe, detach or stop. */
+    'frame_slots_released',
+];
+/** How often a daemon with anyone attached reports its counters. */
+exports.COMPUTER_DIAGNOSTICS_INTERVAL_MS = 15_000;
+/** Viewers one report names, newest first; the rest are in the totals only. */
+exports.COMPUTER_DIAGNOSTICS_MAX_STREAMS = 64;
+exports.COMPUTER_TERMINAL_SIGNALS = ['interrupt', 'eof'];
+/** Input a terminal surface takes. */
+exports.COMPUTER_TERMINAL_INPUT_TYPES = ['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.
+ */
+exports.COMPUTER_TERMINAL_LIFETIMES = ['host', 'tmux', 'daemon'];
+/**
+ * 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.
+ */
+exports.COMPUTER_TERMINAL_HISTORY_CAUSES = [
+    /** The machine stopped or rebooted. */
+    'machine_restarted',
+    /** The terminal host was stopped while the shell ran. */
+    'host_stopped',
+    /** Off a guest: the host closed its terminals after its daemon stayed away for an hour. */
+    'host_orphaned',
+    /** The terminal host died without stopping and was started again. */
+    'host_restarted',
+];
+/**
+ * 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).
+ */
+exports.COMPUTER_TERMINAL_CAVEATS = ['windows_pty_unverified'];
+/** Input a browser surface takes. `tab` needs `computer_browser_tabs_v1`. */
+exports.COMPUTER_BROWSER_INPUT_TYPES = [
+    'pointer',
+    'key',
+    'text',
+    'navigate',
+    'history',
+    'tab',
+];
+/**
+ * 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).
+ */
+exports.COMPUTER_BROWSER_INPUT_PLATFORMS = ['mac', 'windows', 'linux', 'other'];
+/** The most text one `text` input, `paste` input or `key` input's `text` carries. */
+exports.COMPUTER_INPUT_TEXT_MAX_LENGTH = 16 * 1024;
+/** What a page can block on until someone answers (§6.2). Permission prompts have no CDP event. */
+exports.COMPUTER_BROWSER_DIALOG_KINDS = [
+    'alert',
+    'confirm',
+    'prompt',
+    'beforeunload',
+    'auth',
+];
+/** How a dialog ended; `cancelled` is the page or a navigation closing it first. */
+exports.COMPUTER_BROWSER_DIALOG_OUTCOMES = [
+    'accepted',
+    'dismissed',
+    'credentials_supplied',
+    'cancelled',
+];
+/** Who answered: the standing policy, the agent, the person, or the page itself. */
+exports.COMPUTER_BROWSER_DIALOG_ANSWERERS = [
+    'agent_policy',
+    'agent',
+    'person',
+    'page',
+];
+/** The most of a dialog's message the surface carries; the page's text is cut there. */
+exports.COMPUTER_BROWSER_DIALOG_MESSAGE_MAX_LENGTH = 2000;
+/** The longest answer a `prompt` dialog takes. */
+exports.COMPUTER_BROWSER_DIALOG_PROMPT_MAX_LENGTH = 4096;
+/** The longest username or password an `auth` dialog takes; forwarded to the page only. */
+exports.COMPUTER_BROWSER_DIALOG_CREDENTIAL_MAX_LENGTH = 1024;
+/** A download's state on the surface (§6.2); a finished one also appears in Files. */
+exports.COMPUTER_BROWSER_DOWNLOAD_STATES = ['in_progress', 'completed', 'canceled'];
+/** The downloads one browser surface lists, newest first; older ones are in Files. */
+exports.COMPUTER_BROWSER_DOWNLOADS_MAX = 20;
+/** Whether the page's file input takes one file or several. */
+exports.COMPUTER_BROWSER_FILE_CHOOSER_MODES = ['single', 'multiple'];
+/** How a file chooser ended: files went to the page, or the person chose none. */
+exports.COMPUTER_BROWSER_FILE_CHOOSER_OUTCOMES = ['files_chosen', 'cancelled'];
+/** The most files one answer hands the page. */
+exports.COMPUTER_BROWSER_FILE_CHOOSER_MAX_FILES = 32;
+/** The longest `accept` attribute the descriptor carries; the page's is cut there. */
+exports.COMPUTER_BROWSER_FILE_CHOOSER_ACCEPT_MAX_LENGTH = 512;
+/** The longest path one answer names. */
+exports.COMPUTER_BROWSER_FILE_CHOOSER_PATH_MAX_LENGTH = 4096;
+/** The longest folder `computer:surface:open` may name as a terminal's `cwd`. */
+exports.COMPUTER_TERMINAL_CWD_MAX_LENGTH = 4096;
+/** The most text one copy-out returns; a longer selection is cut there. */
+exports.COMPUTER_BROWSER_COPY_MAX_LENGTH = 64 * 1024;
+/** `history` input: the browser's own back, forward and reload. */
+exports.COMPUTER_BROWSER_HISTORY_ACTIONS = ['back', 'forward', 'reload'];
+/** `tab` input. `activate` and `close` name a `tabId`; `open` opens a blank tab. */
+exports.COMPUTER_BROWSER_TAB_ACTIONS = ['activate', 'open', 'close'];
+/** The longest URL a `navigate` input carries. */
+exports.COMPUTER_BROWSER_URL_MAX_LENGTH = 4096;
+// ---------------------------------------------------------------------------
+// Files (§6.3, §18)
+// ---------------------------------------------------------------------------
+exports.COMPUTER_FILE_OPERATIONS = [
+    'list',
+    'stat',
+    'read',
+    'write',
+    'mkdir',
+    'move',
+    'delete',
+    'archive',
+];
+/**
+ * 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.
+ */
+exports.COMPUTER_FILE_SEARCH_OPERATIONS = ['search', 'gitstatus'];
+/** How a search ended: all of it read, cut at the result limit, or cut at the time bound. */
+exports.COMPUTER_FILE_SEARCH_STATES = ['complete', 'truncated', 'timed_out'];
+/** What `git status` says about one entry of a directory. */
+exports.COMPUTER_FILE_GIT_MARKS = [
+    'modified',
+    'added',
+    'untracked',
+    'ignored',
+    'conflicted',
+];
+/** Search bounds, one declaration for the daemon, the API and the client. */
+exports.COMPUTER_FILE_SEARCH_DEFAULT_LIMIT = 200;
+exports.COMPUTER_FILE_SEARCH_MAX_LIMIT = 1000;
+exports.COMPUTER_FILE_SEARCH_DEFAULT_BUDGET_MS = 8_000;
+exports.COMPUTER_FILE_SEARCH_MAX_BUDGET_MS = 20_000;
+exports.COMPUTER_FILE_SEARCH_MAX_QUERY_LENGTH = 200;
+exports.COMPUTER_FILE_GIT_STATUS_BUDGET_MS = 4_000;
+exports.COMPUTER_FILE_TYPES = ['file', 'directory', 'symlink', 'other'];
+/**
+ * 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.
+ */
+exports.COMPUTER_FILE_WITHHELD_REASONS = [
+    'deny_set',
+    'blocked_path',
+    'sensitive_pattern',
+    'os_permission',
+];
+/**
+ * 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.
+ */
+exports.COMPUTER_FILES_WATCH_DEGRADED_REASONS = [
+    'spawn_failed',
+    'watcher_exited',
+    'watch_quota',
+    'events_overflow',
+    'delivery_gap',
+];
+/** Changes one `computer:files:changed` report carries; more in one window is `events_overflow`. */
+exports.COMPUTER_FILES_CHANGED_MAX_CHANGES = 256;
+/** The kinds of change a `file_change` activity event reports. */
+exports.COMPUTER_FILE_CHANGES = ['created', 'modified', 'deleted', 'moved'];
+/** The most entries below a folder a contents tag covers; a larger folder is `too_large`. */
+exports.COMPUTER_FILE_CONTENTS_TAG_MAX_ENTRIES = 100_000;
+/** A contents tag's shape: SHA-256 as lowercase hex. */
+exports.COMPUTER_FILE_CONTENTS_TAG_PATTERN = /^[0-9a-f]{64}$/;
+function computerFileEntityTagsEqual(a, b) {
+    return (a.inode === b.inode &&
+        a.size === b.size &&
+        a.mtimeNs === b.mtimeNs &&
+        (a.contents ?? null) === (b.contents ?? null));
+}
+// ---------------------------------------------------------------------------
+// Activity (§4.4, §6.4)
+// ---------------------------------------------------------------------------
+exports.COMPUTER_ACTIVITY_KINDS = [
+    'command',
+    'browser_action',
+    'file_change',
+    'control',
+    'lifecycle',
+];
+/** `summary` is one line, safe to show. */
+exports.COMPUTER_ACTIVITY_SUMMARY_MAX_LENGTH = 500;
+/** The most command output one event carries; longer output is split across events. */
+exports.COMPUTER_ACTIVITY_OUTPUT_MAX_LENGTH = 64 * 1024;
+/**
+ * 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.
+ */
+exports.COMPUTER_ACTIVITY_WITHHELD_PLACEHOLDER = '[withheld]';
+exports.COMPUTER_COMMAND_PHASES = ['started', 'output', 'exited'];
+exports.COMPUTER_LIFECYCLE_EVENTS = [
+    'surface_opened',
+    'surface_ended',
+    'surface_shared',
+    'surface_unshared',
+    /**
+     * A person whose access was revoked left this surface open: it is theirs and
+     * still running, and closing it is the owner's visible decision (§5.1 rule 8).
+     */
+    'surface_orphaned',
+    /**
+     * A person holds this surface and idle reclaim will hand it back to the agent
+     * at `deadline` unless they provide input or take it again (§8, D12). Emitted
+     * `COMPUTER_RECLAIM_WARNING_MS` before the deadline, once per idle window;
+     * input moves the deadline and the warning is stale from that moment.
+     */
+    'reclaim_imminent',
+    'power',
+    /** The computer's browser was signed out everywhere: its profile removed, every window ended. */
+    'browser_reset',
+];
+/** How a command call ended, as its producer stated it — never inferred from output. */
+exports.COMPUTER_COMMAND_OUTCOMES = ['succeeded', 'failed'];
+/**
+ * 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.
+ */
+exports.COMPUTER_COMMAND_NOT_STARTED_SIGNAL = 'not_started';
+exports.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.
+ */
+exports.COMPUTER_COMMAND_START_REFUSALS = [
+    'session_busy',
+    'session_closed',
+    'session_not_ready',
+    'human_control',
+    'start_failed',
+    'invalid_request',
+];
+exports.COMPUTER_COMMAND_OUTPUT_STREAMS = ['stdout', 'stderr'];
+// ---------------------------------------------------------------------------
+// Declared services (§20.5; 9-17, OSK-13579)
+// ---------------------------------------------------------------------------
+/**
+ * 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`.
+ */
+exports.COMPUTER_DECLARED_SERVICE_ACTIONS = ['declare', 'withdraw', 'list'];
+/**
+ * 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.
+ */
+exports.COMPUTER_SERVICES_TOOL_NAME = 'computer.services';
+/** A refused `computer.services` call: this prefix, then the refusal as JSON. */
+exports.COMPUTER_SERVICES_TOOL_ERROR_PREFIX = 'computer_services_refused:';
+/** The operation each action needs, by the one access vocabulary. */
+function computerDeclaredServiceOperation(action) {
+    return action === 'list' ? 'observe' : 'open';
+}
+exports.COMPUTER_DECLARED_SERVICE_PROTOCOLS = ['http', 'https'];
+/** Services one machine holds at once; one more is `service_limit`. */
+exports.COMPUTER_DECLARED_SERVICES_MAX = 16;
+exports.COMPUTER_DECLARED_SERVICE_NAME_MAX_LENGTH = 48;
+exports.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.
+ */
+exports.COMPUTER_DECLARED_SERVICE_HOST = 'localhost';
+/** A service's name: its key on the machine, lower case, shown as written. */
+exports.COMPUTER_DECLARED_SERVICE_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+/**
+ * A path on the service: absolute, no query and no fragment (a token in a
+ * query string would be shown to everyone who can see the machine), no
+ * whitespace or backslash, and not starting with two slashes.
+ */
+const DECLARED_SERVICE_PATH_PATTERN = /^\/(?!\/)[A-Za-z0-9\-._~!$&'()*+,;=:@%/]*$/;
+const DECLARED_SERVICE_KEYS = new Set(['name', 'port', 'path', 'protocol']);
+/** Which part of a declaration was refused. */
+exports.COMPUTER_DECLARED_SERVICE_PROBLEMS = [
+    /** Not an object, or a field other than name, port, path and protocol (a host, a URL). */
+    'shape',
+    'name',
+    'port',
+    'path',
+    'protocol',
+];
+/**
+ * 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.
+ */
+function computerDeclaredServiceSpec(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, problem: 'shape' };
+    }
+    const data = raw;
+    if (Object.keys(data).some((key) => !DECLARED_SERVICE_KEYS.has(key))) {
+        return { ok: false, problem: 'shape' };
+    }
+    const { name, port, path, protocol } = data;
+    if (typeof name !== 'string' ||
+        name.length === 0 ||
+        name.length > exports.COMPUTER_DECLARED_SERVICE_NAME_MAX_LENGTH ||
+        !exports.COMPUTER_DECLARED_SERVICE_NAME_PATTERN.test(name)) {
+        return { ok: false, problem: 'name' };
+    }
+    if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535) {
+        return { ok: false, problem: 'port' };
+    }
+    if (path !== undefined &&
+        (typeof path !== 'string' ||
+            path.length > exports.COMPUTER_DECLARED_SERVICE_PATH_MAX_LENGTH ||
+            !DECLARED_SERVICE_PATH_PATTERN.test(path))) {
+        return { ok: false, problem: 'path' };
+    }
+    if (protocol !== undefined &&
+        (typeof protocol !== 'string' ||
+            !exports.COMPUTER_DECLARED_SERVICE_PROTOCOLS.includes(protocol))) {
+        return { ok: false, problem: 'protocol' };
+    }
+    return {
+        ok: true,
+        spec: {
+            name,
+            port,
+            path: typeof path === 'string' ? path : '/',
+            protocol: protocol ?? 'http',
+        },
+    };
+}
+/**
+ * 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.
+ */
+function computerDeclaredServiceUrl(service) {
+    const checked = computerDeclaredServiceSpec({
+        name: 'service',
+        port: service.port,
+        ...(service.path !== undefined ? { path: service.path } : {}),
+        ...(service.protocol !== undefined ? { protocol: service.protocol } : {}),
+    });
+    if (!checked.ok) {
+        throw new Error(`not a declared service address (${checked.problem})`);
+    }
+    const { protocol, port, path } = checked.spec;
+    return `${protocol}://${exports.COMPUTER_DECLARED_SERVICE_HOST}:${port}${path}`;
+}
+// ---------------------------------------------------------------------------
+// Machines and power (§10, §18)
+// ---------------------------------------------------------------------------
+exports.COMPUTER_MACHINE_KINDS = ['dedicated', 'personal'];
+/**
+ * One picture per machine state; none of them is a spinner without a bound,
+ * and none collapses two states into the reassuring one.
+ */
+exports.COMPUTER_POWER_PHASES = [
+    // A Dedicated Runtime, from its lease state.
+    /** `ready`, `active`, `idle`: the desktop. */
+    'on',
+    /** On the way up: a boot screen naming the step, with elapsed time. */
+    'booting',
+    /** `stopping`, `snapshotting`: saving files, with the checkpoint outcome when known. */
+    'stopping',
+    /** `stopped`: off, files preserved. */
+    'off',
+    /** Files retained until a date. */
+    'archived',
+    /** `terminating`: being removed. */
+    'removing',
+    /** `failed`, `lost`, `terminated`: the reason, and what is recoverable. */
+    'gone',
+    /** The provider could not be read. Explicitly not "off". */
+    'blind',
+    /** The lease is healthy and the daemon is not answering. */
+    'unresponsive',
+    /** A lease state that belongs to another machine product (`pausing`, `paused`, `resuming`). */
+    'not_a_computer',
+    // Either kind.
+    /** The daemon does not announce `computer_v1`. */
+    'needs_update',
+    // A personal machine: no lease, no power actions.
+    'online',
+    'offline',
+    'needs_sign_in',
+    /** The machine has not allowed the computer (§18). */
+    'not_allowed',
+];
+/**
+ * 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).
+ */
+exports.COMPUTER_PERSONAL_POWER_PHASES = [
+    '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.
+ */
+exports.COMPUTER_PERSONAL_SIGN_IN_REASONS = ['needs_reauth', 'revoked'];
+/** Why a stopped machine would also refuse a start, so the screen does not offer one (§10). */
+exports.COMPUTER_START_REFUSALS = ['spend_cap', 'entitlement'];
+/**
+ * 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.
+ */
+exports.COMPUTER_LEASE_STATE_POWER_PHASE = Object.freeze({
+    ready: 'on',
+    active: 'on',
+    idle: 'on',
+    requested: 'booting',
+    provisioning: 'booting',
+    bootstrapping: 'booting',
+    starting: 'booting',
+    restarting: 'booting',
+    recovering: 'booting',
+    stopping: 'stopping',
+    snapshotting: 'stopping',
+    stopped: 'off',
+    archived: 'archived',
+    terminating: 'removing',
+    failed: 'gone',
+    lost: 'gone',
+    terminated: 'gone',
+    pausing: 'not_a_computer',
+    paused: 'not_a_computer',
+    resuming: 'not_a_computer',
+});
+/** The phase a Dedicated Runtime lease state shows as, or `null` for a state this build does not know. */
+function computerPowerPhaseForLeaseState(state) {
+    return typeof state === 'string' &&
+        Object.prototype.hasOwnProperty.call(exports.COMPUTER_LEASE_STATE_POWER_PHASE, state)
+        ? exports.COMPUTER_LEASE_STATE_POWER_PHASE[state]
+        : null;
+}
+/** Whether the phase shows the desktop. */
+function computerShowsDesktop(phase) {
+    return phase === 'on' || phase === 'online';
+}
+/** Power actions are offered for a Dedicated Runtime only; a personal machine has none (§18). */
+function computerOffersPowerActions(machineKind) {
+    return machineKind === 'dedicated';
+}