@braedonsaunders/appkit-desk 0.4.0

package/README.md

@@ -0,0 +1,233 @@
+# @braedonsaunders/appkit-desk
+
+Per-agent Debian machines in Cloud Hypervisor microVMs: a terminal, a
+filesystem, arbitrary software, and — only when genuinely needed — a real
+desktop, all on one machine with one identity.
+
+A desk boots **headless** (a few hundred megabytes of RAM: kernel, filesystem,
+network, the guest agent). The desktop environment is installed in the base
+image but is not running. When work genuinely needs a screen, the compositor is
+started *on the machine the agent is already using* as a service — one
+filesystem, one machine, one event stream. This package owns the mechanism and
+exposes ports; the consuming application supplies policy behind those ports and
+owns the record. The package never touches a database and knows nothing about
+tenants, employees, or approvals.
+
+## Choosing a tier
+
+The desk is the middle and top of a cost ladder. Reach for the cheapest tier
+that does the job; the expensive tiers are strictly worse at tasks the cheap
+tiers already cover.
+
+| Tier | Surface | When | Cost |
+| --- | --- | --- | --- |
+| Document/tool abilities, in-process script sandboxes | No VM at all | Structured outputs, pure computation | Ordinary model calls |
+| **Headless desk** (this package) | Shell, filesystem, background jobs, persistent disk | Real software, persistent state, downloads | A small resident VM |
+| **Desk with a screen open** | GUI apps, pixels + opportunistic accessibility tree | Software with no CLI, visual verification | ~1.2GB+ resident, a vision call per unassisted step |
+
+Size the concurrency cap against screen-open desks, not headless ones.
+
+## Booting a desk
+
+```ts
+import { createDeskHost, isDeskSupported } from '@braedonsaunders/appkit-desk'
+
+if (!isDeskSupported()) {
+  // Fail closed: no KVM or no Cloud Hypervisor means no desk ability at all,
+  // not a degraded one.
+  throw new Error('This host cannot run desks.')
+}
+
+const host = createDeskHost({
+  imageRoot: '/data/agent-disks',
+  capacity: 8,
+  idleSuspendMs: 5 * 60_000,
+  ports: {
+    policy: { allowExec: ({ command }) => policyFor(command) },
+    onEvent: (event) => ledger.append(event),   // the typed desk event union
+    audit: (entry) => auditLog.append(entry),   // handover boundaries only
+  },
+})
+
+const desk = await host.start({
+  deskId: 'agent-7',
+  baseImage: '/data/agent-disks/base.img',
+  overlayPath: '/data/agent-disks/overlays/agent-7.img',
+  memoryMb: 384,
+  vcpus: 2,
+})
+
+const result = await desk.exec({ command: '/usr/bin/git', args: ['clone', repo] })
+const job = await desk.exec({ command: '/usr/bin/serve', keepAlive: true }) // dies with the lease
+
+const screen = await desk.screen.start({ width: 1280, height: 900 })
+const { png, a11y, focused } = await screen.observe() // lossless PNG, on demand
+await screen.input.click(640, 320)
+
+// The live view is a different job: H.264, for a human driving the screen.
+for await (const chunk of screen.video({ fps: 30 })) {
+  send(chunk) // init segment first, then one unit per media fragment
+}
+
+await desk.screen.stop() // back to headless; the machine keeps running
+```
+
+There are three ways to see the screen and they take different trades.
+
+- **`observe()`** is what a model looks at: a lossless PNG plus windows and the
+  accessibility tree, on demand and infrequent.
+- **`video()`** is what a person drives by. A video codec ships the difference
+  between pictures and a desktop is mostly still, so it costs one to two orders
+  of magnitude fewer bytes than the same screen as stills — and bytes between
+  the guest and the host are what actually bounds a live view. Chunks are
+  ordered: the `init` segment first, then `media` fragments, resumable only at
+  one whose `keyframe` is true.
+- **`frames()`** is for a consumer that needs whole pictures — one feeding an
+  encoder of its own, or one that cannot decode H.264. `format` picks `jpeg`
+  (roughly a tenth the bytes) or `png` (exact).
+
+All three are the screen's real size and never rescaled, so all three anchor the
+coordinate space a click is aimed in. `video()` and `frames()` are both masked:
+neither emits anything while a handover is active.
+
+Every desk boots from one golden **raw** base image plus a per-desk
+copy-on-write overlay, so patching the base patches every desk on its next boot
+while agent installs and home directories persist. The overlay is a plain raw
+file cloned from the base with `cp --reflink=auto` — an instant, block-sharing
+CoW clone on XFS/Btrfs and a graceful full-copy fallback on ext4. It is
+deliberately *not* a qcow2 backing overlay: Cloud Hypervisor cannot follow disk
+backing chains and rejects them (`UnsupportedFeature` /
+`MaxNestingDepthExceeded`), so the disk is passed as `image_type=raw` with no
+chain to follow. `buildDeskLaunchPlan` produces the entire invocation — VMM
+argv, overlay-creation step, vsock socket path, TAP device and MAC — as
+inspectable data before anything is spawned, and it fails closed: a missing
+`/dev/kvm`, VMM binary, kernel, base image, or overlay directory throws rather
+than producing a plan that cannot boot.
+
+## Leases, idle suspend, and the queue
+
+A desk is resident under a lease. `renewLease(ms)` extends it; activity defers
+the idle timer; a desk past its lease or idle deadline is suspended — the VM
+stops, the disk persists, applications cold-start on `resume`. Keep-alive jobs
+die with the lease, and their termination is recorded as `job_exit` so no
+process ever runs where an operator cannot see it.
+
+Residency is bounded by a hard capacity cap. Starts beyond the cap queue FIFO
+rather than overcommitting host memory. `host.stats()` reports
+`{ resident, queued, capacity, suspended, lastStartedAt, lastSuspendedAt,
+reconnects, lastReconnectAt, lastReconnectDeskId, lastError }`; queue depth is
+worth alerting on, and so is a `reconnects` count that climbs. With an injected
+`now`, tests drive all of this deterministically through `host.sweep()`.
+
+## A connection is re-established, not assumed
+
+The vsock channel to a guest is not a fact learned once at boot. It can drop
+mid-lease for reasons that say nothing about whether the desk is usable — the
+guest agent restarts, the bridge drops, the guest wedges for a moment — and
+treating that as terminal stranded the desk for the rest of its lease with a
+healthy guest behind it. So the backend reconnects: same retry path, same
+`confirmGuest` ping, bounded window and backoff. It never reconnects after
+`shutdown()` or once the VMM has exited, because then the desk genuinely needs
+a fresh boot; when the window runs out the host suspends the desk so `resume()`
+boots a new one instead of handing back a dead handle.
+
+Two things a caller must handle, because pretending otherwise would be a lie:
+a request that was **in flight** when the channel dropped rejects with
+`DeskRequestFateUnknownError` — the guest may already have run it, and silently
+replaying an `exec` that sent mail is the wrong kind of resilience. And the
+guest's own capture state does not survive its agent restarting, so live
+`frames()`/`video()` iterators **end** on a reconnect and the coordinate anchor
+is cleared; observe (or take a frame) again before aiming.
+
+## The coordinate contract
+
+**Input coordinates are in the pixel space of the most recent `observe()`,
+one to one.** Any scaling applied on the way out must be undone on the way in.
+The package enforces this rather than documenting it and hoping: coordinate
+input before the first `observe()`, or outside its bounds, throws. Getting
+this wrong makes every click land slightly off in a way that looks like model
+failure and is very hard to diagnose.
+
+Perception is pixels-primary: `observe()` always returns a PNG, and
+opportunistically includes the focused application's AT-SPI accessibility tree
+(`a11y`) when one is exposed. `screen.a11y.invoke(nodeId, action)` targets by
+role and name when a tree exists; the pixel path always works.
+
+## The handover masking contract
+
+`screen.handover.begin({ ttlMs, scope })` returns a URL through which a human
+can view or control the screen — for example to complete a login the agent
+cannot. The masking rules are load-bearing:
+
+- While a handover is active, **input events never reach the `onEvent`
+  recording port** — no `click`, `type`, `key`, `scroll`, `drag`,
+  `window_focus`, or `app_launch` is emitted, even though the input itself is
+  faithfully forwarded to the guest.
+- **Frames are not emitted** to `frames()` consumers for the duration.
+- **`clipboard.read()` is refused** during a handover, so a freshly typed
+  credential cannot ride the clipboard into the agent's context.
+- Only `handover_begin` and `handover_end` cross the boundary, carrying actor,
+  scope, and duration — never content. Both reach `onEvent` (for the ledger)
+  and the `audit` port.
+
+A handover ends explicitly, at its TTL (`reason: 'expired'`), or when the desk
+is suspended (`reason: 'revoked'`). The failure this prevents is concrete:
+keystrokes typed by a human during a credential handover leaking into an
+append-only record that cannot be edited afterward.
+
+## The event union
+
+`onEvent` receives a closed union — `shell_command`, `app_launch`, `click`,
+`type`, `key`, `scroll`, `drag`, `window_focus`, `screen_open`,
+`screen_close`, `handover_begin`, `handover_end`, `job_start`, `job_exit` —
+each stamped with `deskId` and an ISO timestamp. The union is defined here so
+the consumer's ledger and this package agree on the taxonomy; persistence is
+entirely the consumer's concern.
+
+## The backend port and the guest agent
+
+`DeskBackend` is the seam that keeps everything testable without a hypervisor:
+`boot(plan)` returns a `DeskMachine` — a request/response channel to the
+in-guest agent plus an event subscription. The default is
+`cloudHypervisorBackend`, which creates the overlay, spawns Cloud Hypervisor
+with the plan's argv, performs the vsock `CONNECT` handshake, and speaks the
+framed protocol. Its process-spawning glue is thin on purpose; the launcher
+and the socket transport are injectable, and CI substitutes in-memory fakes.
+
+The wire protocol — length-prefixed JSON frames with bounded sizes, strict
+field validation, and a closed operation set — is pure code in `protocol.ts`,
+shared by both ends. The in-guest agent (`guest-agent.ts`) is the
+security-critical piece: it is the only new attack surface in the design, so
+it is small enough to read in one sitting, does no parsing it does not need,
+dispatches through a closed switch, and treats any framing violation as fatal
+to the connection. Its message-handling core is pure and hard-tested; contact
+with the guest OS is injected as handlers by the guest's init glue.
+
+`verifyDeskHost()` belongs in service startup: it boots a throwaway microVM
+through the backend and distinguishes a host that is unusable (wrong platform,
+missing VMM or images — throws) from capabilities that are merely absent,
+reported as booleans: `kvm`, `vsock`, and `virtioGpu`.
+
+Every additional provider runs `verifyDeskBackendConformance()` against a
+disposable launch plan. The shared check verifies request/capability round trips,
+idempotent terminal shutdown, and refusal of work after shutdown. Provider test
+suites extend this contract; they do not restate it.
+
+`exportPortableDeskHome()` and `importPortableDeskHome()` are the migration seam
+between providers. Sources expose entries and file bytes; exports produce a
+bounded, sorted, content-addressed manifest preserving directories, files,
+safe relative symlinks, modes, and timestamps. Imports verify every SHA-256,
+path, symlink target, size, and aggregate limit before opening a sink, then
+stage the complete home and make it authoritative with one `commit()`. Any
+failure calls `rollback()`. This moves an agent's working home, not an operating
+system image: installed packages and provider-specific machine state remain
+the provider's concern.
+
+`createDeskFrameDeduplicator()` assigns exact SHA-256 identities to observations
+without retaining their bytes. A repeated identity can reuse the prior audit
+frame and omit another model image; reset it whenever the capture session or
+masking boundary changes.
+
+Do not fall back to unconfined execution when this package reports an
+unsupported host. A deployment without KVM loses the desk ability entirely —
+the same fail-closed posture as the rest of AppKit.

package/backend.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The backend port and its default Cloud Hypervisor implementation.
+ *
+ * `DeskBackend` is the seam that keeps the package testable without a
+ * hypervisor: the host asks a backend to boot a `DeskLaunchPlan` and gets a
+ * `DeskMachine` — a request/response channel to the in-guest agent plus an
+ * event subscription. CI and non-KVM developer machines inject an in-memory
+ * fake; production uses `cloudHypervisorBackend`, whose process-spawning glue
+ * is deliberately thin because everything that can be pure lives in the plan
+ * builder and the protocol module.
+ */
+import { type ChildProcess } from 'node:child_process';
+import type { Duplex } from 'node:stream';
+import { DeskError, type DeskLaunchPlan, type DeskLauncherIdentity } from './plan.js';
+import { type GuestCommand, type GuestEventMessage } from './protocol.js';
+/**
+ * A request that was in flight when the guest connection dropped.
+ *
+ * Distinct from a plain `DeskError` because the caller's next move is
+ * different: this request may ALREADY HAVE RUN. The frame reached the guest,
+ * and whether the guest executed it before the channel went away is not
+ * knowable from the host. An `exec` may have sent mail; a `click` may have
+ * landed. So the transport refuses to guess — it names the ambiguity and lets
+ * the caller decide whether the operation is safe to repeat. Anything that
+ * rejects with a plain `DeskError` instead never reached the guest at all.
+ */
+export declare class DeskRequestFateUnknownError extends DeskError {
+    readonly name: string;
+}
+/**
+ * What happened to the transport underneath a machine.
+ *
+ * `reconnected` means the host lost the guest channel mid-lease and got it
+ * back; the desk is usable again. It is NOT a promise that the guest is
+ * unchanged — see the note on `onConnectionChange`. `lost` means it will not
+ * come back on this VM and the desk needs a fresh boot.
+ */
+export type DeskConnectionChange = {
+    state: 'reconnected';
+    deskId: string;
+    /** How the previous connection went away. */
+    reason: string;
+    /** Wall-clock time the desk spent with no channel to its guest. */
+    downtimeMs: number;
+    /** Reconnects this machine has survived, including this one. */
+    reconnects: number;
+} | {
+    state: 'lost';
+    deskId: string;
+    /** Why it is gone for good: the VMM exited, or the window ran out. */
+    reason: string;
+};
+/** A booted microVM as the host sees it: one desk, one guest-agent channel. */
+export interface DeskMachine {
+    readonly deskId: string;
+    /**
+     * Send one request to the in-guest agent and await its correlated result.
+     *
+     * Rejects with `DeskError` when the guest reports an error, the request
+     * times out, or the connection is gone for good — in that last case the
+     * request never left the host, so repeating it is safe.
+     *
+     * A connection lost mid-lease is re-established rather than fatal: a call
+     * that arrives while that is happening WAITS for it instead of failing.
+     * A call that was already in flight when the channel dropped rejects with
+     * `DeskRequestFateUnknownError`, because the host cannot tell whether the
+     * guest ran it.
+     */
+    request(command: GuestCommand, options?: {
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    /**
+     * Subscribe to unsolicited guest events (job exits, frames, focus changes).
+     *
+     * Subscriptions belong to the machine, not to the socket under it, so they
+     * survive a reconnect. What does NOT survive is the guest's own capture
+     * state: a guest agent that restarted has no screen, no frame encoder and
+     * no video encoder, and a subscriber will simply stop receiving. Watch
+     * `onConnectionChange` to notice.
+     */
+    subscribe(listener: (event: GuestEventMessage) => void): () => void;
+    /**
+     * Watch the transport under this machine.
+     *
+     * Optional: a backend whose channel cannot drop has nothing to report. The
+     * default backend reports every reconnect, because a reconnect that leaves
+     * no trace turns a guest agent restarting every few minutes into a desk that
+     * misbehaves for reasons nobody can find.
+     */
+    onConnectionChange?(listener: (change: DeskConnectionChange) => void): () => void;
+    /** Stop the VM. Idempotent; resolves once the VMM process has exited. */
+    shutdown(): Promise<void>;
+}
+export interface DeskBackend {
+    boot(plan: DeskLaunchPlan): Promise<DeskMachine>;
+}
+export type DeskProcessLauncher = (command: string, args: readonly string[], options: {
+    identity?: DeskLauncherIdentity;
+}) => ChildProcess;
+export interface CloudHypervisorBackendOptions {
+    /** Spawns the VMM and image tooling; injectable for tests. */
+    launcher?: DeskProcessLauncher;
+    /** Opens the host side of the vsock Unix socket; injectable for tests. */
+    connect?: (socketPath: string) => Duplex;
+    platform?: NodeJS.Platform;
+    /**
+     * Clock behind every connect and reconnect deadline. Injectable for the same
+     * reason `DeskHostOptions.now` is: a test drives a window to its end by
+     * moving the clock, rather than sleeping for it and hoping the machine it
+     * runs on is fast enough.
+     */
+    now?: () => number;
+    idFactory?: () => string;
+    requestTimeoutMs?: number;
+    connectTimeoutMs?: number;
+    connectRetryDelayMs?: number;
+    /** Bound on a single handshake attempt; see attemptHandshake. */
+    handshakeTimeoutMs?: number;
+    /**
+     * How long a machine keeps trying to get its guest channel back after an
+     * unexpected drop before declaring the desk lost. Bounded on purpose: the
+     * VMM is still alive so a reconnect is cheap and usually fast, but retrying
+     * forever against a guest that is never coming back is worse than failing.
+     */
+    reconnectWindowMs?: number;
+    /**
+     * First delay between reconnect attempts. It doubles toward a ceiling, so
+     * this is the fast first poll rather than the steady rate. Separate from
+     * `connectRetryDelayMs`, which is sized for a guest that is still cold
+     * booting; here the guest was up a moment ago.
+     */
+    reconnectRetryDelayMs?: number;
+    killGraceMs?: number;
+    guestAgentPort?: number;
+}
+export declare function createCloudHypervisorBackend(options?: CloudHypervisorBackendOptions): DeskBackend;
+/** The default backend: real Cloud Hypervisor over a real vsock socket. */
+export declare const cloudHypervisorBackend: DeskBackend;
+//# sourceMappingURL=backend.d.ts.map

package/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAI7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,QAAQ,CAAA;AAClF,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;GAUG;AACH,qBAAa,2BAA4B,SAAQ,SAAS;IACxD,SAAkB,IAAI,EAAE,MAAM,CAAgC;CAC/D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE,KAAK,EAAE,aAAa,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAA;IAClB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAA;CACnB,GACD;IACE,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAEL,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAClF;;;;;;;;OAQG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IACnE;;;;;;;OAOG;IACH,kBAAkB,CAAC,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IACjF,yEAAyE;IACzE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CACjD;AAED,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,oBAAoB,CAAA;CAAE,KACzC,YAAY,CAAA;AAEjB,MAAM,WAAW,6BAA6B;IAC5C,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAA;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAA;IAC1B;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,MAAM,CAAA;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAkBD,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE,6BAAkC,GAC1C,WAAW,CAoFb;AAED,2EAA2E;AAC3E,eAAO,MAAM,sBAAsB,EAAE,WAA4C,CAAA"}