@capybara-hq/kernel 0.1.0-rc.8 → 0.1.0-rc.9

package/dist/background/finish.js

@@ -13,6 +13,7 @@ import { afterCommit } from "../infra/database/after-commit.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
+import { taskOutputFile } from "./launch.js";
 import { LAST_LINES_MAX_CHARS } from "./session.js";
 import { BackgroundTaskStore } from "./store.js";
 /** The idempotency key of a task's `background_task_finished` event. */
@@ -63,7 +64,7 @@ let BackgroundTaskFinisher = class BackgroundTaskFinisher {
                     lastLines: lastLines.length > LAST_LINES_MAX_CHARS
                         ? lastLines.slice(-LAST_LINES_MAX_CHARS)
                         : lastLines,
-                    outputPath: `/workspace/${task.outputPath}`,
+                    outputPath: taskOutputFile(task.outputPath),
                     reported,
                     ...(to.lostReason !== undefined && { lostReason: to.lostReason }),
                     ...(opts.stoppedBy !== undefined && { stoppedBy: opts.stoppedBy }),

package/dist/background/launch.d.ts

@@ -2,8 +2,8 @@ import type { KernelConfig } from "../config/schema.js";
 /**
  * Launching a background Bash task (spec 2026-11-05-background-bash-design §4.2): the task id, the
  * one short exec that starts the command detached from the exec, and the model-visible result.
- * Every path is relative to `/workspace` (the launch exec's `cwd`), so a provider that maps
- * `/workspace` needs no rewriting inside the script.
+ * Every path is relative to the instance's workspace root (the launch exec's `cwd`), so the
+ * script is the same whatever the instance's roots are.
  */
 /** The launch exec's own time limit: it only writes a file and forks. */
 export declare const LAUNCH_EXEC_TIMEOUT_MS = 30000;
@@ -12,11 +12,17 @@ export declare const LAUNCH_EXEC_TIMEOUT_MS = 30000;
  * `sandbox.limits.maxCommandSeconds`. It is also a task's default `timeout`.
  */
 export declare const backgroundMaxSeconds: (cfg: Pick<KernelConfig, "sandbox">) => number;
-/** The directory of the task files, relative to `/workspace`. */
+/** The directory of the task files, relative to the workspace root. */
 export declare const TASKS_DIR = ".capybara/tasks";
-/** A task's output file, relative to `/workspace` (`output_path`). */
+/** A task's output file, relative to the workspace root (`output_path` while reserved). */
 export declare const taskOutputPath: (id: string) => string;
-/** The file the launch writes the session id to, relative to `/workspace`. */
+/**
+ * The absolute output file of a task from its `output_path`: absolute once the task started (the
+ * launch records `<workspace>/.capybara/tasks/<id>.out` of its instance); a reservation's relative
+ * path is read under the default workspace.
+ */
+export declare const taskOutputFile: (outputPath: string) => string;
+/** The file the launch writes the session id to, relative to the workspace root. */
 export declare const taskSidPath: (id: string) => string;
 /** A new task id: `bt_` plus 6 lowercase base32 characters. */
 export declare function newTaskId(): string;
@@ -32,5 +38,5 @@ export declare const TASK_ID_RE: RegExp;
  * positive integer (both go into the script unquoted).
  */
 export declare function launchScript(id: string, command: string, seconds: number): string;
-/** The model-visible result of a launch (spec §2.1). */
-export declare function startedText(id: string, description: string): string;
+/** The model-visible result of a launch (spec §2.1); `workspace`: the instance's workspace root. */
+export declare function startedText(id: string, description: string, workspace?: string): string;

package/dist/background/launch.js

@@ -1,9 +1,10 @@
 import { randomBytes } from "node:crypto";
+import { DEFAULT_SANDBOX_ROOTS } from "@capybara-hq/plugin-sdk";
 /**
  * Launching a background Bash task (spec 2026-11-05-background-bash-design §4.2): the task id, the
  * one short exec that starts the command detached from the exec, and the model-visible result.
- * Every path is relative to `/workspace` (the launch exec's `cwd`), so a provider that maps
- * `/workspace` needs no rewriting inside the script.
+ * Every path is relative to the instance's workspace root (the launch exec's `cwd`), so the
+ * script is the same whatever the instance's roots are.
  */
 /** The launch exec's own time limit: it only writes a file and forks. */
 export const LAUNCH_EXEC_TIMEOUT_MS = 30_000;
@@ -12,11 +13,17 @@ export const LAUNCH_EXEC_TIMEOUT_MS = 30_000;
  * `sandbox.limits.maxCommandSeconds`. It is also a task's default `timeout`.
  */
 export const backgroundMaxSeconds = (cfg) => Math.min(cfg.sandbox.background.maxSeconds, cfg.sandbox.limits.maxCommandSeconds);
-/** The directory of the task files, relative to `/workspace`. */
+/** The directory of the task files, relative to the workspace root. */
 export const TASKS_DIR = ".capybara/tasks";
-/** A task's output file, relative to `/workspace` (`output_path`). */
+/** A task's output file, relative to the workspace root (`output_path` while reserved). */
 export const taskOutputPath = (id) => `${TASKS_DIR}/${id}.out`;
-/** The file the launch writes the session id to, relative to `/workspace`. */
+/**
+ * The absolute output file of a task from its `output_path`: absolute once the task started (the
+ * launch records `<workspace>/.capybara/tasks/<id>.out` of its instance); a reservation's relative
+ * path is read under the default workspace.
+ */
+export const taskOutputFile = (outputPath) => outputPath.startsWith("/") ? outputPath : `${DEFAULT_SANDBOX_ROOTS.workspace}/${outputPath}`;
+/** The file the launch writes the session id to, relative to the workspace root. */
 export const taskSidPath = (id) => `${TASKS_DIR}/${id}.sid`;
 const BASE32 = "abcdefghijklmnopqrstuvwxyz234567";
 /** A new task id: `bt_` plus 6 lowercase base32 characters. */
@@ -60,11 +67,11 @@ export function launchScript(id, command, seconds) {
         `cat ${t}.sid`,
     ].join("\n");
 }
-/** The model-visible result of a launch (spec §2.1). */
-export function startedText(id, description) {
+/** The model-visible result of a launch (spec §2.1); `workspace`: the instance's workspace root. */
+export function startedText(id, description, workspace = DEFAULT_SANDBOX_ROOTS.workspace) {
     return [
         `Started background task ${id} ("${description}").`,
-        `Output: /workspace/${taskOutputPath(id)}`,
+        `Output: ${workspace}/${taskOutputPath(id)}`,
         "Read it with TaskOutput (or Read), stop it with TaskStop. You will be told when it finishes.",
     ].join("\n");
 }

package/dist/background/poll.job.d.ts

@@ -37,7 +37,7 @@ export declare class BackgroundTaskPollJob {
     readonly config: KernelConfigService;
     readonly lockService: LockService;
     readonly log: KernelLogger;
-    constructor(store: Pick<BackgroundTaskStore, "runningStarted" | "pruneFinished" | "failAbandonedLaunches">, finisher: BackgroundTaskFinisher, eventLog: Pick<EventLog, "publishChanged">, sandbox: Pick<SandboxService, "available" | "ifRunning">, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    constructor(store: Pick<BackgroundTaskStore, "runningStarted" | "pruneFinished" | "failAbandonedLaunches">, finisher: BackgroundTaskFinisher, eventLog: Pick<EventLog, "publishChanged">, sandbox: Pick<SandboxService, "cloudAvailable" | "availableFor" | "ifRunning">, config: KernelConfigService, lockService: LockService, log: KernelLogger);
     poll(signal?: AbortSignal): Promise<void>;
     /**
      * One poll of every running task (the body of {@link poll}); returns how many tasks finished.

package/dist/background/poll.job.js

@@ -7,6 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+import { rootsOf } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { EventLog } from "../conversations/event-log.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
@@ -88,8 +89,6 @@ let BackgroundTaskPollJob = class BackgroundTaskPollJob {
             for (const c of conversations)
                 await this.eventLog.publishChanged(c, "background");
         }
-        if (!this.sandbox.available)
-            return 0;
         const groups = new Map();
         for (const t of await this.store.runningStarted()) {
             if (t.sid === null || t.sandboxCreatedAt === null)
@@ -103,6 +102,12 @@ let BackgroundTaskPollJob = class BackgroundTaskPollJob {
             if (signal.aborted)
                 break;
             try {
+                // the environment's provider is not there (no cloud provider, `@device` not served):
+                // its tasks stay as they are until it is
+                const env = tasks[0]?.environmentId ?? null;
+                if (env === null ? !this.sandbox.cloudAvailable : !(await this.sandbox.availableFor(env))) {
+                    continue;
+                }
                 finished += await this.pollSandbox(tasks, signal);
             }
             catch (err) {
@@ -153,7 +158,7 @@ let BackgroundTaskPollJob = class BackgroundTaskPollJob {
     async pollExec(p, h, tasks, signal) {
         const res = await p.exec(h, {
             command: pollScript(tasks.map((t) => ({ id: t.id, sid: t.sid }))),
-            cwd: "/workspace",
+            cwd: rootsOf(h).workspace,
             timeoutMs: POLL_EXEC_TIMEOUT_MS,
             maxOutputBytes: POLL_MAX_OUTPUT_BYTES,
             signal,

package/dist/background/session.d.ts

@@ -1,4 +1,4 @@
-import type { SandboxActor, SandboxHandle } from "@capybara-hq/plugin-sdk";
+import { type SandboxActor, type SandboxHandle } from "@capybara-hq/plugin-sdk";
 import type { HeldProvider, TaggedProvider } from "../sandbox/sandbox.service.js";
 /**
  * A background task's session inside the sandbox (spec 2026-11-05-background-bash-design §4.2):
@@ -41,7 +41,7 @@ export declare function killSession(p: Pick<HeldProvider, "exec">, h: SandboxHan
 export declare const LAST_LINES_MAX_CHARS = 4000;
 /**
  * A shell pipeline printing the last 20 lines of task `id`'s output (at most {@link TAIL_BYTES}),
- * base64 on one line (empty when there is no output file). Relative to `/workspace`.
+ * base64 on one line (empty when there is no output file). Relative to the workspace root.
  */
 export declare function tailCommand(id: string): string;
 /** Decodes a {@link tailCommand} result into `lastLines`: its end, at most 4 000 characters. */

package/dist/background/session.js

@@ -1,3 +1,4 @@
+import { rootsOf } from "@capybara-hq/plugin-sdk";
 import { TASK_ID_RE, TASKS_DIR } from "./launch.js";
 /**
  * A background task's session inside the sandbox (spec 2026-11-05-background-bash-design §4.2):
@@ -53,7 +54,7 @@ export async function killSession(p, h, sid) {
     const r = await p
         .exec(h, {
         command: `${killSessionScript(sid)}; exit "$ks"`,
-        cwd: "/workspace",
+        cwd: rootsOf(h).workspace,
         timeoutMs: KILL_SESSION_TIMEOUT_MS,
         maxOutputBytes: 4096,
         signal: AbortSignal.timeout(KILL_SESSION_TIMEOUT_MS),
@@ -67,7 +68,7 @@ const TAIL_BYTES = 12_000;
 export const LAST_LINES_MAX_CHARS = 4000;
 /**
  * A shell pipeline printing the last 20 lines of task `id`'s output (at most {@link TAIL_BYTES}),
- * base64 on one line (empty when there is no output file). Relative to `/workspace`.
+ * base64 on one line (empty when there is no output file). Relative to the workspace root.
  */
 export function tailCommand(id) {
     return `{ tail -n 20 ${TASKS_DIR}/${id}.out 2>/dev/null | tail -c ${TAIL_BYTES} | base64 | tr -d '\\n'; }`;

package/dist/background/status.d.ts

@@ -19,7 +19,7 @@ export interface TaskReport {
  * processes (it left `server &` running) has the session killed in the same exec (so under the
  * caller's lease), and is reported without a process once the session was confirmed empty: the
  * task ends when its command exits, and nothing of it runs on untracked. The tail (base64) is read
- * only for a task that exited or has no process left. Relative to `/workspace`.
+ * only for a task that exited or has no process left. Relative to the workspace root.
  */
 export declare function pollScript(tasks: {
     id: string;

package/dist/background/status.js

@@ -8,7 +8,7 @@ import { exitedAs } from "./stop.js";
  * processes (it left `server &` running) has the session killed in the same exec (so under the
  * caller's lease), and is reported without a process once the session was confirmed empty: the
  * task ends when its command exits, and nothing of it runs on untracked. The tail (base64) is read
- * only for a task that exited or has no process left. Relative to `/workspace`.
+ * only for a task that exited or has no process left. Relative to the workspace root.
  */
 export function pollScript(tasks) {
     const lines = tasks.map(({ id, sid }) => {

package/dist/background/stop.js

@@ -7,6 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+import { rootsOf } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
@@ -24,7 +25,7 @@ const TAIL_EXEC_TIMEOUT_MS = 10_000;
 /**
  * Exit code 0 with `exited <code>` when the task had already finished (its exit file exists),
  * else sends SIGTERM to the session and waits up to {@link STOP_GRACE_MS} for it to empty, then
- * prints `term`. Relative to `/workspace`.
+ * prints `term`. Relative to the workspace root.
  */
 function termScript(id, sid) {
     const f = `${TASKS_DIR}/${id}`;
@@ -146,7 +147,7 @@ let BackgroundTaskStopper = class BackgroundTaskStopper {
             const p = actingAs(tp, taskActor(cur));
             const term = await p.exec(h, {
                 command: termScript(cur.id, sid),
-                cwd: "/workspace",
+                cwd: rootsOf(h).workspace,
                 timeoutMs: TERM_EXEC_TIMEOUT_MS,
                 maxOutputBytes: 4096,
                 signal: sig,
@@ -161,7 +162,7 @@ let BackgroundTaskStopper = class BackgroundTaskStopper {
             }
             const tail = await p.exec(h, {
                 command: tailCommand(cur.id),
-                cwd: "/workspace",
+                cwd: rootsOf(h).workspace,
                 timeoutMs: TAIL_EXEC_TIMEOUT_MS,
                 maxOutputBytes: 64 * 1024,
                 signal: sig,

package/dist/background/store.d.ts

@@ -28,7 +28,11 @@ export interface BackgroundTaskRow {
      * started: readers that act on the process (the poller, stops) skip such a row.
      */
     sid: string | null;
-    /** Relative to `/workspace`. */
+    /**
+     * The output file: absolute once the task started (`markStarted` records it under its
+     * instance's workspace root), relative to the workspace root while reserved
+     * (`taskOutputFile` in launch.ts).
+     */
     outputPath: string;
     status: BackgroundTaskStatus;
     lostReason: string | null;
@@ -85,6 +89,7 @@ export declare class BackgroundTaskStore {
     markStarted(id: string, to: {
         sid: string;
         sandboxCreatedAt: Date;
+        outputPath?: string;
     }): Promise<"started" | "stopping" | false>;
     /**
      * Finishes a launch whose reservation a stop claimed, once the launch killed what it started:

package/dist/background/store.js

@@ -86,7 +86,11 @@ let BackgroundTaskStore = class BackgroundTaskStore {
     async markStarted(id, to) {
         const r = await this.db
             .updateTable("background_tasks")
-            .set({ sid: to.sid, sandbox_created_at: to.sandboxCreatedAt })
+            .set({
+            sid: to.sid,
+            sandbox_created_at: to.sandboxCreatedAt,
+            ...(to.outputPath !== undefined && { output_path: to.outputPath }),
+        })
             .where("id", "=", id)
             .where("status", "=", "running")
             .where("sid", "is", null)

package/dist/background/tasks.service.d.ts

@@ -46,7 +46,7 @@ export declare class BackgroundTasks {
     private readonly eventLog;
     private readonly db;
     private readonly environments;
-    constructor(access: Pick<ConversationAccess, "isAccessible">, store: Pick<BackgroundTaskStore, "listFor" | "get">, stopper: Pick<BackgroundTaskStopper, "stop">, sandbox: Pick<SandboxService, "available" | "ifRunning">, eventLog: Pick<EventLog, "findByIdem">, db: KernelDb, environments: Pick<ConversationEnvironments, "forTool">);
+    constructor(access: Pick<ConversationAccess, "isAccessible">, store: Pick<BackgroundTaskStore, "listFor" | "get">, stopper: Pick<BackgroundTaskStopper, "stop">, sandbox: Pick<SandboxService, "availableFor" | "ifRunning">, eventLog: Pick<EventLog, "findByIdem">, db: KernelDb, environments: Pick<ConversationEnvironments, "forTool">);
     /**
      * The conversation and every sub-agent conversation below it (grandchildren too: their tasks run
      * in the root's sandbox, agent map spec §6); `conversation.not_found` when not visible.

package/dist/background/tasks.service.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { isSandboxGoneError } from "@capybara-hq/plugin-sdk";
+import { isSandboxGoneError, rootsOf } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { ConversationAccess } from "../conversations/access.js";
 import { EventLog } from "../conversations/event-log.js";
@@ -144,7 +144,7 @@ let BackgroundTasks = class BackgroundTasks {
         if (task.sid !== null &&
             task.sandboxCreatedAt !== null &&
             task.environmentId !== null &&
-            this.sandbox.available &&
+            (await this.sandbox.availableFor(task.environmentId)) &&
             (await this.environmentUsable(orgId, task.conversationId))) {
             const createdAt = task.sandboxCreatedAt;
             // the person reading it acts in the task's conversation
@@ -153,7 +153,7 @@ let BackgroundTasks = class BackgroundTasks {
                 const r = await this.sandbox.ifRunning(task.environmentId, { createdAt }, async (p, h, signal) => {
                     const res = await actingAs(p, actor).exec(h, {
                         command: tailScript(task.id, tail),
-                        cwd: "/workspace",
+                        cwd: rootsOf(h).workspace,
                         timeoutMs: OUTPUT_READ_TIMEOUT_MS,
                         maxOutputBytes: 2 * OUTPUT_TAIL_MAX_BYTES + 4096,
                         signal,
@@ -188,7 +188,7 @@ BackgroundTasks = __decorate([
     __param(6, Inject(ConversationEnvironments))
 ], BackgroundTasks);
 export { BackgroundTasks };
-/** Prints `size <bytes>` and `out <base64 of the last `tail` bytes>`. Relative to `/workspace`. */
+/** Prints `size <bytes>` and `out <base64 of the last `tail` bytes>`. Relative to the workspace root. */
 function tailScript(id, tail) {
     if (!TASK_ID_RE.test(id))
         throw new Error(`invalid background task id: ${id}`);

package/dist/catalog/marketplaces.service.d.ts

@@ -181,7 +181,7 @@ export declare function headsToResolve(entries: readonly MarketplaceEntry[], imp
 /** The host versions (an entry's `minKernel` is judged against them). */
 export declare const HOST_VERSIONS: {
     readonly kernel: string;
-    readonly sdk: "0.1.0-rc.5";
+    readonly sdk: "0.1.0-rc.6";
 };
 /** Whether this deployment satisfies the entry's `minKernel`. */
 export declare const entryCompatible: (e: Pick<MarketplaceEntry, "minKernel">) => boolean;

package/dist/config/docs.js

@@ -65,6 +65,7 @@ export function renderConfigDocs(schema) {
         // CAPYBARA_WEB_TRUST_PROXY: apps/web/src/lib/peer.ts; CAPYBARA_WEB_SHUTDOWN_GRACE_MS: apps/web/server.mjs.
         // CAPYBARA_WEB_KEEP_ALIVE_TIMEOUT_MS: apps/web/src/lib/keep-alive.ts.
         // CAPYBARA_WEB_OBJECT_STORE_*: apps/web/src/lib/object-store-proxy.ts.
+        // CAPYBARA_WEB_GATEWAY_URL: apps/web/src/lib/device-connect-proxy.ts.
         "## Web tier (apps/web) environment variables",
         "",
         "The web tier is a separate process (started through `apps/web/server.mjs`); it does not read the kernel config and only honors the following environment variables:",
@@ -81,6 +82,7 @@ export function renderConfigDocs(schema) {
         "| `CAPYBARA_WEB_OBJECT_STORE_URL` | Object storage on the web origin: the object store's address as web reaches it (e.g. `http://seaweedfs-s3:8333`). When set, web proxies `/<bucket>/**` (and `/<bucket>` itself for POST only) there, so browsers upload attachments (presigned POST) and download attachments and artifacts (presigned GET) through web; set the object-store extension's `publicEndpoint` to the web origin with `forcePathStyle: true`. Only GET, HEAD and POST; the path is forwarded unchanged; cookies and authorization are not forwarded; responses carry `X-Content-Type-Options: nosniff` and `Content-Security-Policy: sandbox`; uploads are capped at `CAPYBARA_WEB_MAX_PACKAGE_BYTES`. Unset (default): off |",
         "| `CAPYBARA_WEB_OBJECT_STORE_BUCKET` | With `CAPYBARA_WEB_OBJECT_STORE_URL`: the bucket, equal to the object-store extension's `bucket` (it is the first path segment web proxies) |",
         "| `CAPYBARA_WEB_OBJECT_STORE_PUBLIC_HOST` | With `CAPYBARA_WEB_OBJECT_STORE_URL`: the host of the extension's `publicEndpoint` (a host such as `capybara.example.com`, or that URL). Sent upstream as `Host` instead of the incoming one, because presigned URLs sign the host they were issued for and front proxies rewrite it |",
+        "| `CAPYBARA_WEB_GATEWAY_URL` | Connected machines on the web origin: a `gateway` replica's address as web reaches it (an http(s) URL, e.g. `http://gateway:8080`). When set, WebSocket upgrades on exactly `/device/connect` are forwarded to it (`capybara-device` connects at `<http.publicUrl>/device/connect`); unset, such upgrades get 404. Not needed when an external proxy routes `/device/connect` to the gateway replicas; a malformed value stops the web tier at startup |",
         "| `CAPYBARA_DEV_UI` | When set to `1`, production builds also serve the `/dev/ui` component catalog page (off by default) |",
         "",
     ].join("\n");

package/dist/config/schema.d.ts

@@ -221,6 +221,13 @@ export declare const KernelConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     environments: z.ZodPrefault<z.ZodObject<{
         maxPersonal: z.ZodDefault<z.ZodNumber>;
+        device: z.ZodPrefault<z.ZodObject<{
+            reconnectGraceSeconds: z.ZodDefault<z.ZodNumber>;
+            leaseTtlMs: z.ZodDefault<z.ZodNumber>;
+            authCodeTtlSeconds: z.ZodDefault<z.ZodNumber>;
+            pollIntervalSeconds: z.ZodDefault<z.ZodNumber>;
+            maxFrameBytes: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     evals: z.ZodPrefault<z.ZodObject<{
         orgConcurrency: z.ZodDefault<z.ZodNumber>;

package/dist/config/schema.js

@@ -1184,6 +1184,51 @@ export const KernelConfigSchema = z.object({
             hot: true,
             description: "Most personal environments a member may have in one org, the default one included; creating one more fails with environment.limit_reached",
         })),
+        device: z
+            .object({
+            reconnectGraceSeconds: z
+                .number()
+                .int()
+                .positive()
+                .default(120)
+                .meta(meta({
+                hot: true,
+                description: "Seconds a connected machine may stay disconnected before its environment is reported offline; also sent to the device program at sign-in",
+            })),
+            leaseTtlMs: z
+                .number()
+                .int()
+                .min(6000)
+                .default(30000)
+                .meta(meta({
+                description: "Milliseconds the replica holding a machine's connection keeps its lease without renewing it; at least 6000",
+            })),
+            authCodeTtlSeconds: z
+                .number()
+                .int()
+                .positive()
+                .default(600)
+                .meta(meta({
+                description: "Seconds a device sign-in code stays valid before the program must start over (device.expired)",
+            })),
+            pollIntervalSeconds: z
+                .number()
+                .int()
+                .positive()
+                .default(5)
+                .meta(meta({
+                description: "Seconds the device program waits between token polls during sign-in; polling faster gets device.slow_down",
+            })),
+            maxFrameBytes: z
+                .number()
+                .int()
+                .positive()
+                .default(16 * 1024 * 1024)
+                .meta(meta({
+                description: "Largest WebSocket frame in bytes accepted from or sent to a connected machine",
+            })),
+        })
+            .prefault({}),
     })
         .prefault({}),
     evals: z

package/dist/conversations/event-log.d.ts

@@ -131,9 +131,10 @@ export declare class EventLog {
     /** 按幂等键取事件；没有 → undefined。 */
     findByIdem(conversationId: string, idemKey: string): Promise<ConversationEvent | undefined>;
     /**
-     * 会话里某类事件的最新一条（按 seq）；没有 → undefined。`skills_catalog` 有部分索引
-     * （0025，按会话直接取到最新一条）；其他类型按 (conversation_id, seq) 主键倒序扫本会话的事件并按 type 过滤，
-     * 没有该类事件时会扫完整个会话。
+     * The conversation's latest event of `type` (by seq); undefined without one. `skills_catalog`
+     * (0025) and `environment_paths` (0094) have partial indexes that answer it directly; other
+     * types scan the conversation's events backwards on the (conversation_id, seq) key, the whole
+     * conversation when it has none.
      */
     latestOfType<T extends ConversationEventType>(conversationId: string, type: T): Promise<Extract<ConversationEvent, {
         type: T;

package/dist/conversations/event-log.js

@@ -245,9 +245,10 @@ let EventLog = class EventLog {
         return r && toEvent(r);
     }
     /**
-     * 会话里某类事件的最新一条（按 seq）；没有 → undefined。`skills_catalog` 有部分索引
-     * （0025，按会话直接取到最新一条）；其他类型按 (conversation_id, seq) 主键倒序扫本会话的事件并按 type 过滤，
-     * 没有该类事件时会扫完整个会话。
+     * The conversation's latest event of `type` (by seq); undefined without one. `skills_catalog`
+     * (0025) and `environment_paths` (0094) have partial indexes that answer it directly; other
+     * types scan the conversation's events backwards on the (conversation_id, seq) key, the whole
+     * conversation when it has none.
      */
     async latestOfType(conversationId, type) {
         const r = await this.db

package/dist/conversations/events.d.ts

@@ -515,6 +515,15 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         added: z.ZodArray<z.ZodString>;
         removed: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"environment_paths">;
+    payload: z.ZodObject<{
+        roots: z.ZodObject<{
+            workspace: z.ZodString;
+            skills: z.ZodString;
+            tmp: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"tool_call_started">;
     payload: z.ZodObject<{

package/dist/conversations/events.js

@@ -442,6 +442,20 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
      * position as a system message (`toolsChangedText`); dropped once a summary covers it.
      */
     ev("tools_changed", z.object({ step: count, added: z.array(z.string()), removed: z.array(z.string()) })),
+    /**
+     * The directories of the instance a sandbox tool call entered, when they differ from the
+     * defaults (environments spec §13.1: a connected machine's real paths). Written once per
+     * conversation and roots, before that call's result. **Model-visible**: rendered at its position
+     * as a system message (`environmentPathsText`); a summary covering it is followed by the latest
+     * one again.
+     */
+    ev("environment_paths", z.object({
+        roots: z.object({
+            workspace: z.string().min(1).max(4096),
+            skills: z.string().min(1).max(4096),
+            tmp: z.string().min(1).max(4096),
+        }),
+    })),
     /** 工具调用开始执行之前写入（续跑时「有开始无结果」的调用记为结果未知，不再执行）。 */
     ev("tool_call_started", z.object({ step: count, callId: z.string(), toolKey: z.string(), specHash: z.string() })),
     /**

package/dist/db/kernel-schema.d.ts

@@ -800,7 +800,8 @@ export interface EnvironmentsTable {
     owner_account_id: string;
     name: ColumnType<string | null, string | null | undefined, string | null>;
     is_default: ColumnType<boolean, boolean | undefined, boolean>;
-    source: "cloud";
+    /** 0093: `device` is a connected machine (environment_machines). */
+    source: "cloud" | "device";
     provider: ColumnType<string | null, string | null | undefined, string | null>;
     created_at: Ts;
     updated_at: Ts;
@@ -830,6 +831,29 @@ export interface EnvironmentInstancesTable {
     prev_handle: InstanceHandle;
     sweep_failed_at: TsNullable;
 }
+/**
+ * 0093_connected_environments.sql: the machine connected to a `device` environment. At most one
+ * unrevoked row per environment; revoking sets `revoked_at` and keeps the row.
+ */
+export interface EnvironmentMachinesTable {
+    id: Generated<string>;
+    org_id: string;
+    environment_id: string;
+    account_id: string;
+    /** A hash of the machine credential, never the credential itself. */
+    credential_hash: string;
+    name: string;
+    os: string;
+    arch: string;
+    program_version: ColumnType<string | null, string | null | undefined, string | null>;
+    mode: ColumnType<"os" | "docker" | null, "os" | "docker" | null | undefined, "os" | "docker" | null>;
+    /** The roots the program exposes, as it reported them (a JSON array). */
+    roots: ColumnType<unknown, string | null | undefined, string | null>;
+    session_isolation: ColumnType<boolean, boolean | undefined, boolean>;
+    last_seen_at: TsNullable;
+    created_at: Ts;
+    revoked_at: TsNullable;
+}
 /** 0088_environments.sql: the environment a member's new conversations use by default. */
 export interface EnvironmentDefaultsTable {
     org_id: string;
@@ -1103,6 +1127,7 @@ export interface KernelDatabase {
     environments: EnvironmentsTable;
     environment_instances: EnvironmentInstancesTable;
     environment_defaults: EnvironmentDefaultsTable;
+    environment_machines: EnvironmentMachinesTable;
     background_tasks: BackgroundTasksTable;
     skills: SkillsTable;
     skill_versions: SkillVersionsTable;

package/dist/devices/device-auth.controller.d.ts

@@ -0,0 +1,42 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import type { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { CredentialThrottler } from "../infra/throttler/credential-throttler.js";
+import { type DeviceAuthorization, DeviceAuthService, type DeviceGrant, type DeviceMachineInfo } from "./device-auth.js";
+import { type DeviceAuthorizeBody, type DeviceConfirmBody, type DeviceTokenBody, type DeviceUserCodeBody, type DeviceUserCodeParams } from "./dto.js";
+/**
+ * Device sign-in (`/api/v1/device`, environments spec §13.3; the shape of RFC 8628).
+ *
+ * The program's routes are public (it has no credential yet); like every public unsafe route
+ * they need `X-Capybara-Csrf: 1`, which `capybara-device` sends:
+ * - `POST /authorize { name, os, arch, programVersion }` → `{ deviceCode, userCode,
+ *   verificationUri, verificationUriComplete, interval, expiresIn }` (`device-authorize-ip`);
+ * - `POST /token { deviceCode }` → `{ credential, orgId, environmentId, connectUrl,
+ *   reconnectGraceSeconds, maxFrameBytes }` once, else `device.authorization_pending` / `device.slow_down` /
+ *   `device.denied` / `device.expired` (`device-token-ip`).
+ *
+ * The person's routes need a web session (the confirmation page `/device`); each try of a user
+ * code counts on `device-code-account` (refunded on success):
+ * - `GET /pending/:userCode` → `{ machine, expiresAt }`;
+ * - `POST /confirm { userCode, orgId, environmentId | name }` → `{ environmentId }`
+ *   (`device.expired` / `device.unavailable` when the credential could not be handed over: the
+ *   machine is revoked again and the person runs login again);
+ * - `POST /deny { userCode }` → 204.
+ */
+export declare class DeviceAuthController {
+    private readonly auth;
+    private readonly throttler;
+    constructor(auth: DeviceAuthService, throttler: CredentialThrottler);
+    authorize(body: z.infer<typeof DeviceAuthorizeBody>): Promise<DeviceAuthorization>;
+    token(body: z.infer<typeof DeviceTokenBody>): Promise<DeviceGrant>;
+    pending(principal: Principal, params: z.infer<typeof DeviceUserCodeParams>, req: FastifyRequest, reply: FastifyReply): Promise<{
+        machine: DeviceMachineInfo;
+        expiresAt: string;
+    }>;
+    confirm(principal: Principal, body: z.infer<typeof DeviceConfirmBody>, req: FastifyRequest, reply: FastifyReply): Promise<{
+        environmentId: string;
+    }>;
+    deny(principal: Principal, body: z.infer<typeof DeviceUserCodeBody>, req: FastifyRequest, reply: FastifyReply): Promise<void>;
+    /** Runs `fn` as one counted try of a user code; a success gives the try back. */
+    private counted;
+}