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

package/dist/errors.d.ts

@@ -254,6 +254,30 @@ export declare const ERROR_CODES: {
     readonly "environment.name_taken": 409;
     /** The person already has `environments.maxPersonal` live personal environments. */
     readonly "environment.limit_reached": 409;
+    /**
+     * A connected environment's files are on its machine: they cannot be reset from the platform;
+     * run `capybara-device logout`, then `capybara-device login` into the environment, on the machine
+     * (ruling R24).
+     */
+    readonly "environment.files_on_device": 409;
+    /** The environment's connected machine is not connected now (no replica holds its lease). */
+    readonly "environment.offline": 503;
+    /** The connected machine runs a device program too old for this kernel; update the program. */
+    readonly "environment.program_outdated": 426;
+    /** Device sign-in (RFC 8628 style): the person has not approved the code yet; keep polling. */
+    readonly "device.authorization_pending": 400;
+    /** Device sign-in: the program polls faster than the interval; add 5 seconds and keep polling. */
+    readonly "device.slow_down": 400;
+    /** Device sign-in: the code expired before it was approved; start over. */
+    readonly "device.expired": 400;
+    /** Device sign-in: the person denied the code. */
+    readonly "device.denied": 400;
+    /** Device sign-in: no pending code matches the one given. */
+    readonly "device.code_invalid": 404;
+    /** Device sign-in: the confirmation could not hand the credential to the program; start over. */
+    readonly "device.unavailable": 503;
+    /** The machine credential is unknown or revoked. */
+    readonly "device.credential_invalid": 401;
     readonly "skill.not_found": 404;
     /** Also a skill neither the model nor a person could use (phase D: both invocation flags off). */
     readonly "skill.invalid_package": 400;

package/dist/errors.js

@@ -254,6 +254,30 @@ export const ERROR_CODES = {
     "environment.name_taken": 409,
     /** The person already has `environments.maxPersonal` live personal environments. */
     "environment.limit_reached": 409,
+    /**
+     * A connected environment's files are on its machine: they cannot be reset from the platform;
+     * run `capybara-device logout`, then `capybara-device login` into the environment, on the machine
+     * (ruling R24).
+     */
+    "environment.files_on_device": 409,
+    /** The environment's connected machine is not connected now (no replica holds its lease). */
+    "environment.offline": 503,
+    /** The connected machine runs a device program too old for this kernel; update the program. */
+    "environment.program_outdated": 426,
+    /** Device sign-in (RFC 8628 style): the person has not approved the code yet; keep polling. */
+    "device.authorization_pending": 400,
+    /** Device sign-in: the program polls faster than the interval; add 5 seconds and keep polling. */
+    "device.slow_down": 400,
+    /** Device sign-in: the code expired before it was approved; start over. */
+    "device.expired": 400,
+    /** Device sign-in: the person denied the code. */
+    "device.denied": 400,
+    /** Device sign-in: no pending code matches the one given. */
+    "device.code_invalid": 404,
+    /** Device sign-in: the confirmation could not hand the credential to the program; start over. */
+    "device.unavailable": 503,
+    /** The machine credential is unknown or revoked. */
+    "device.credential_invalid": 401,
     "skill.not_found": 404,
     /** Also a skill neither the model nor a person could use (phase D: both invocation flags off). */
     "skill.invalid_package": 400,

package/dist/evals/recorded-tools.d.ts

@@ -1,3 +1,4 @@
+import type { SandboxRoots } from "@capybara-hq/plugin-sdk";
 import type { EventLog } from "../conversations/event-log.js";
 import { type LegacyScope } from "../tools/legacy-keys.js";
 import { type ToolPipeline, type ToolStepContext } from "../tools/pipeline.js";
@@ -23,6 +24,14 @@ export interface RecordedCall {
     specHash: string;
     /** The recorded call used release-candidate names; `toolKey` and `inputKey` are already the current ones. */
     legacy?: true;
+    /**
+     * The roots of the latest `environment_paths` event the original run had logged by this call's
+     * step (environments spec §13.1, ruling R22): set on every recorded call from the step where an
+     * event was logged onward. A replay that matches the call writes the event when the eval
+     * conversation's latest one differs, so a candidate whose first sandbox call lands in another
+     * step still gets the line, once.
+     */
+    environmentPaths?: SandboxRoots;
 }
 /**
  * The connectors and extensions an rc `<x>__<tool>` key can name, from positive evidence in the

package/dist/evals/recorded-tools.js

@@ -1,3 +1,4 @@
+import { environmentPathsChange } from "../runtime/context/environment-paths.js";
 import { assistantIdemKey } from "../runtime/model-call.js";
 import { MATCH_IGNORED_FIELDS } from "../tools/builtin-names.js";
 import { isLegacyPrefixedKey, legacyToolInput, legacyToolKey, } from "../tools/legacy-keys.js";
@@ -137,11 +138,29 @@ export function recordedCalls(s) {
                 started.set(p.callId, p.specHash);
         }
     }
+    // an environment_paths event belongs to the step of the assistant message before it, and holds
+    // for that step's calls and every later step's (until the next one)
+    const pathsOf = new Map();
+    const assistants = own.filter((e) => e.type === "assistant_message").map((e) => e.seq);
+    let current;
+    let next = 0;
+    for (const [i, a] of assistants.entries()) {
+        const end = assistants[i + 1] ?? Number.POSITIVE_INFINITY;
+        for (; next < own.length && own[next].seq < end; next++) {
+            const e = own[next];
+            if (e.type === "environment_paths" && e.seq > a) {
+                current = e.payload.roots;
+            }
+        }
+        if (current !== undefined)
+            pathsOf.set(a, current);
+    }
     const scope = legacyScopeOf(s);
     const out = [];
     for (const e of own) {
         if (e.type !== "assistant_message")
             continue;
+        const paths = pathsOf.get(e.seq);
         const content = e.payload.content;
         for (const b of content) {
             if (b.type !== "tool_call")
@@ -160,6 +179,7 @@ export function recordedCalls(s) {
                 ...(r.loadedTools !== undefined && { loadedTools: r.loadedTools }),
                 ...(r.contentTypes !== undefined && { contentTypes: r.contentTypes }),
                 specHash: started.get(call.id) ?? "",
+                ...(paths !== undefined && { environmentPaths: paths }),
             });
         }
     }
@@ -213,7 +233,14 @@ export class RecordedToolPipeline {
             const rec = this.take(call.name, matchKey(call.name, call.input));
             if (!rec)
                 this.misses++;
+            // the original run had told the model the instance's directories by this call: so does the
+            // replay, when the eval conversation's latest record differs (as the sandbox tools write it)
+            const paths = rec?.environmentPaths;
+            const change = paths === undefined
+                ? null
+                : environmentPathsChange(await eventLog.latestOfType(ctx.conversationId, "environment_paths"), paths, ctx.runId);
             await eventLog.append(ctx.conversationId, [
+                ...(change ? [change] : []),
                 {
                     type: "tool_call_started",
                     runId: ctx.runId,

package/dist/http/api.module.js

@@ -30,6 +30,8 @@ import { ChannelConnectionsController } from "../channels/connections.controller
 import { AttachmentsController } from "../conversations/attachments.controller.js";
 import { ConversationsController } from "../conversations/conversations.controller.js";
 import { ConversationsModule } from "../conversations/conversations.module.js";
+import { DeviceAuthController } from "../devices/device-auth.controller.js";
+import { DeviceAuthModule } from "../devices/device-auth.module.js";
 import { EnvironmentsController } from "../environments/environments.controller.js";
 import { EnvironmentsModule } from "../environments/environments.module.js";
 import { EvalsModule } from "../evals/evals.module.js";
@@ -133,6 +135,7 @@ const CONTROLLERS = [
     OrgOwnedPluginsController,
     OrgComponentsController,
     AdminCatalogRequestsController,
+    DeviceAuthController,
 ];
 /**
  * The api role (nest kernel spec §2): the kernel API (`/api/v1/*`), imported by `KernelModule` only
@@ -158,6 +161,7 @@ ApiModule = __decorate([
             ConversationsModule,
             BackgroundModule,
             EnvironmentsModule,
+            DeviceAuthModule,
             RuntimeModule,
             ChannelsModule,
             EvalsModule,

package/dist/http/gateway-routes.d.ts

@@ -1,15 +1,19 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { FastifyInstance } from "fastify";
 import type { ChannelWebhooks } from "../channels/webhook.js";
+import { type DeviceRoutesOptions } from "../devices/device-routes.js";
 /** What the gateway role serves over HTTP besides health and plugin routes. */
 export interface GatewayRoutes {
     webhooks: Pick<ChannelWebhooks, "handle">;
     /** `channels.webhookMaxBodyBytes`. */
     webhookMaxBodyBytes: number;
+    /** The device connection route (`GET /device/connect`, environments spec §13.4). */
+    devices: DeviceRoutesOptions;
 }
 /**
- * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): today the
- * channel webhook. These are raw Fastify routes, not a Nest module, so the API's global guard and
- * CSRF check do not apply (P-4); each route does its own (plugin-side) verification.
+ * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): the
+ * channel webhook and the device connection WebSocket. These are raw Fastify routes, not a Nest
+ * module, so the API's global guard and CSRF check do not apply (P-4); each route does its own
+ * verification (the channel plugin's signature check, the machine credential).
  */
 export declare function registerGatewayRoutes(fastify: FastifyInstance, routes: GatewayRoutes, log: Pick<Logger, "error">): Promise<void>;

package/dist/http/gateway-routes.js

@@ -1,8 +1,10 @@
 import { registerChannelWebhookRoute } from "../channels/webhook.controller.js";
+import { registerDeviceConnectRoute } from "../devices/device-routes.js";
 /**
- * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): today the
- * channel webhook. These are raw Fastify routes, not a Nest module, so the API's global guard and
- * CSRF check do not apply (P-4); each route does its own (plugin-side) verification.
+ * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): the
+ * channel webhook and the device connection WebSocket. These are raw Fastify routes, not a Nest
+ * module, so the API's global guard and CSRF check do not apply (P-4); each route does its own
+ * verification (the channel plugin's signature check, the machine credential).
  */
 export async function registerGatewayRoutes(fastify, routes, log) {
     await registerChannelWebhookRoute(fastify, {
@@ -10,4 +12,5 @@ export async function registerGatewayRoutes(fastify, routes, log) {
         maxBodyBytes: routes.webhookMaxBodyBytes,
         log,
     });
+    await registerDeviceConnectRoute(fastify, routes.devices);
 }

package/dist/identity/me.controller.d.ts

@@ -6,6 +6,7 @@ import { OrgsService } from "../orgs/orgs.service.js";
 import type { OrgRole } from "../orgs/roles.js";
 import { type Account, AccountsService } from "./accounts.js";
 import { type ApiTokenRecord, ApiTokenService } from "./api-tokens.js";
+import { type PreferencesSchema } from "./me.schemas.js";
 import { type Principal } from "./principal.js";
 import { SessionService } from "./sessions.js";
 import { SettingsService } from "./settings.js";
@@ -17,9 +18,6 @@ declare const TokenSchema: z.ZodObject<{
     name: z.ZodString;
     expiresAt: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
 }, z.core.$strip>;
-declare const PreferencesSchema: z.ZodObject<{
-    timeZone: z.ZodNullable<z.ZodString>;
-}, z.core.$strict>;
 declare const CurrentOrgSchema: z.ZodObject<{
     orgId: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;

package/dist/identity/me.controller.js

@@ -15,10 +15,10 @@ import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody } from "../infra/validation/zod-params.js";
 import { OrgsService } from "../orgs/orgs.service.js";
-import { IanaTimeZone } from "../time-zone.js";
 import { AccountsService } from "./accounts.js";
 import { ApiTokenService, FutureIsoDate } from "./api-tokens.js";
 import { MAX_PASSWORD_LENGTH } from "./login.js";
+import { PreferencesBody } from "./me.schemas.js";
 import { AllowPendingPasswordChange, CurrentPrincipal, requireUser, SessionOnly, } from "./principal.js";
 import { SessionService } from "./sessions.js";
 import { SettingsService } from "./settings.js";
@@ -36,14 +36,6 @@ const TokenSchema = z.object({
 });
 class PersonalTokenBody extends createZodDto(TokenSchema, "PersonalTokenBody") {
 }
-const PreferencesSchema = z
-    .object({
-    /** The person's time zone (IANA); null = follow the browser (run context spec §3.4). */
-    timeZone: IanaTimeZone.nullable(),
-})
-    .strict();
-class PreferencesBody extends createZodDto(PreferencesSchema, "PreferencesBody") {
-}
 const CurrentOrgSchema = z.object({ orgId: z.string().min(1).nullable() });
 class CurrentOrgBody extends createZodDto(CurrentOrgSchema, "CurrentOrgBody") {
 }

package/dist/identity/me.schemas.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** `PUT /me/preferences`: the person's preferences (run context spec §3.4). */
+export declare const PreferencesSchema: z.ZodObject<{
+    timeZone: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+declare const PreferencesBody_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    timeZone: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>>;
+export declare class PreferencesBody extends PreferencesBody_base {
+}
+/** The `/me` routes the Platform operations mirror (`check:platform-ops` keys). */
+export declare const ME_ROUTES: readonly RouteSchemas[];
+export {};

package/dist/identity/me.schemas.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { IanaTimeZone } from "../time-zone.js";
+/** `PUT /me/preferences`: the person's preferences (run context spec §3.4). */
+export const PreferencesSchema = z
+    .object({
+    /** The person's time zone (IANA); null = follow the browser (run context spec §3.4). */
+    timeZone: IanaTimeZone.nullable(),
+})
+    .strict();
+export class PreferencesBody extends createZodDto(PreferencesSchema, "PreferencesBody") {
+}
+/** The `/me` routes the Platform operations mirror (`check:platform-ops` keys). */
+export const ME_ROUTES = [
+    { route: "GET /api/v1/me/preferences" },
+    { route: "PUT /api/v1/me/preferences", body: PreferencesSchema },
+];

package/dist/infra/config/kernel-config.service.js

@@ -35,6 +35,8 @@ const HOT_APPLIERS = {
     "sandbox.maxConcurrentCommands": () => { },
     // The environments service reads the personal limit at every create.
     "environments.maxPersonal": () => { },
+    // The device relay reads the reconnect grace at every disconnect and token response.
+    "environments.device.reconnectGraceSeconds": () => { },
     // Sub-agent limits are read at every dispatch, child step and tool resolution.
     "subagents.maxDepth": () => { },
     "subagents.maxConcurrentPerConversation": () => { },

package/dist/infra/throttler/named-throttlers.d.ts

@@ -25,6 +25,11 @@ export interface NamedThrottler {
  * | `PUT /api/v1/me/password` | `change-password`, `change-password-ip` |
  * | `POST /api/v1/setup` | `setup-token`, `setup-ip` |
  * | `POST /api/v1/invitations/:token/accept` | `invitation`, `invitation-ip` |
+ * | `GET /api/v1/device/pending/:userCode`, `POST /api/v1/device/confirm`, `POST /api/v1/device/deny` | `device-code-account` |
+ *
+ * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
+ * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
+ * credential: the device code is 32 random bytes).
  */
 export declare const NAMED_THROTTLERS: readonly NamedThrottler[];
 /** The storage key of a named throttler's counter for a tracker (shared by the guard and success paths). */

package/dist/infra/throttler/named-throttlers.js

@@ -28,6 +28,11 @@ const LOGIN_MSG = "Too many failed login attempts; try again later";
  * | `PUT /api/v1/me/password` | `change-password`, `change-password-ip` |
  * | `POST /api/v1/setup` | `setup-token`, `setup-ip` |
  * | `POST /api/v1/invitations/:token/accept` | `invitation`, `invitation-ip` |
+ * | `GET /api/v1/device/pending/:userCode`, `POST /api/v1/device/confirm`, `POST /api/v1/device/deny` | `device-code-account` |
+ *
+ * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
+ * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
+ * credential: the device code is 32 random bytes).
  */
 export const NAMED_THROTTLERS = [
     // (login, IP): 10; an attacker filling one login from one IP leaves the owner's other IPs alone (R25)
@@ -114,6 +119,39 @@ export const NAMED_THROTTLERS = [
         message: "Too many invitation attempts; try again later",
         getTracker: ip,
     },
+    // device sign-in codes issued per client address (each one holds Redis state for its TTL): 20.
+    // Opted in with @Throttled, which counts every request before the handler: group and onSuccess
+    // are unused (they matter only to CredentialThrottler).
+    {
+        name: "device-authorize-ip",
+        group: "device-authorize",
+        onSuccess: "clear",
+        limit: 20,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many device sign-in attempts; try again later",
+        getTracker: ip,
+    },
+    // device token polls per client address (@Throttled like device-authorize-ip): 600, one login
+    // polls up to 120 times (600 s / 5 s), so several machines behind one NAT address fit
+    {
+        name: "device-token-ip",
+        group: "device-token",
+        onSuccess: "clear",
+        limit: 600,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many device sign-in polls; try again later",
+        getTracker: ip,
+    },
+    // user codes tried per signed-in person (guessing another machine's code): 10, refunded on success
+    {
+        name: "device-code-account",
+        group: "device-code",
+        onSuccess: "refund",
+        limit: 10,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many device code attempts; try again later",
+        getTracker: (req) => sha256(principalAccountId(req)),
+    },
 ];
 /** The storage key of a named throttler's counter for a tracker (shared by the guard and success paths). */
 export const throttlerKey = (name, tracker) => sha256(`${name}:${tracker}`);

package/dist/kernel.module.js

@@ -10,6 +10,7 @@ import { APP_INTERCEPTOR } from "@nestjs/core";
 import { CatalogModule } from "./catalog/catalog.module.js";
 import { ChannelsModule } from "./channels/channels.module.js";
 import { TitlesModule } from "./conversations/titles.js";
+import { DevicesModule } from "./devices/devices.module.js";
 import { ExtensionsModule } from "./extensions/extensions.module.js";
 import { ApiModule } from "./http/api.module.js";
 import { ErrorFilterModule } from "./http/error-filter.module.js";
@@ -110,6 +111,8 @@ let KernelModule = KernelModule_1 = class KernelModule {
                 TitlesModule,
                 UsageReportModule,
                 ChannelsModule,
+                // the @device sandbox provider, registered on every role (any replica may relay to a machine)
+                DevicesModule,
                 // the Platform tool's operation registry and actor facts
                 PlatformModule,
                 // its operations (skills, agents, ...), registered at start on every role

package/dist/lifecycle/kernel-lifecycle.js

@@ -62,6 +62,8 @@ export const STOP_BUDGET_MS = {
 };
 /** 停机时留给渠道长连接交还租约的最少时间（与 runs 阶段并行开始，runs 用尽预算时仍保底）。 */
 const CHANNELS_STOP_MIN_MS = 2_000;
+/** The time the device connections get to close and hand their leases back. */
+const DEVICES_STOP_MS = 2_000;
 /** runs 阶段里留给强制关闭 worker 的余量（预算的其余部分用于等运行到达步骤边界）。 */
 const RUNS_FORCE_CLOSE_MS = 500;
 const errMsg = (e) => (e instanceof Error ? e.message : String(e));
@@ -387,6 +389,9 @@ let KernelLifecycle = class KernelLifecycle {
         this.unwatchConfig = undefined;
         gateway?.unwatch();
         await within("webhooks-unsubscribe", (gateway?.unsubscribe() ?? Promise.resolve()).catch(() => { }), 1_000);
+        // Device connections: closed (1001) and their leases handed back before the HTTP server
+        // closes, so the machines reconnect to another gateway replica at once
+        await within("devices", gateway?.stopDevices() ?? Promise.resolve(), DEVICES_STOP_MS);
         // 不再接 reconcile（进行中的那次由宿主关闭收尾）
         await within("plugin-lifecycle", this.extensionLifecycle.stop(), 1_000);
         // http 阶段：等 listen 与关闭 HTTP 共用一个截止时间；listen 卡满预算时关闭只剩 0ms，直接强制断开

package/dist/platform/exclusions.js

@@ -248,6 +248,39 @@ export const PLATFORM_EXCLUSIONS = [
         reason: "Serves sandbox file bytes",
     },
     // environments (personal cloud environments, environments design phase 1)
+    // connected machines (environments design phase 2): device sign-in by the program and on the
+    // confirmation page, and disconnecting a machine. The machine's WebSocket (`GET /device/connect`)
+    // is a raw gateway-role route, not a Nest controller, so it is not listed (like the webhook)
+    {
+        route: "DELETE /api/v1/orgs/:orgId/environments/:id/machine",
+        category: "human-only",
+        reason: "Disconnects a person's own machine (revokes its credential); a trust decision taken on the environment's page",
+    },
+    {
+        route: "POST /api/v1/device/authorize",
+        category: "transport",
+        reason: "Issues a sign-in code pair to the capybara-device program, which has no credential yet",
+    },
+    {
+        route: "POST /api/v1/device/token",
+        category: "transport",
+        reason: "The capybara-device program polls for its machine credential",
+    },
+    {
+        route: "GET /api/v1/device/pending/:userCode",
+        category: "human-only",
+        reason: "Shows the machine behind a code the person read off their own machine",
+    },
+    {
+        route: "POST /api/v1/device/confirm",
+        category: "human-only",
+        reason: "Lets a machine run commands for the person; only the person, signed in on the web, confirms it",
+    },
+    {
+        route: "POST /api/v1/device/deny",
+        category: "human-only",
+        reason: "Refuses a machine's sign-in code on the confirmation page",
+    },
     {
         route: "GET /api/v1/orgs/:orgId/conversations/:id/tools",
         category: "internal",
@@ -330,16 +363,6 @@ export const PLATFORM_EXCLUSIONS = [
         category: "human-only",
         reason: "Switches the web session's current org",
     },
-    {
-        route: "GET /api/v1/me/preferences",
-        category: "internal",
-        reason: "The person's time zone setting the web's preferences page reads; the run context already gives the agent the zone in effect",
-    },
-    {
-        route: "PUT /api/v1/me/preferences",
-        category: "human-only",
-        reason: "A person's own time zone setting, chosen on their preferences page",
-    },
     {
         route: "PUT /api/v1/me/password",
         category: "human-only",

package/dist/platform/operation.js

@@ -12,7 +12,7 @@ export const operationDomain = (id) => id.slice(0, id.indexOf("."));
 export const PLATFORM_DOMAINS = [
     {
         id: "platform",
-        description: "What this platform is, its tool families, and what you and this agent can do.",
+        description: "What this platform is, its tool families, what you and this agent can do, and your own preferences (time zone).",
     },
     { id: "skills", description: "The org's skill library: list, read, create, switch on or off." },
     {

package/dist/platform/ops/environments.ops.js

@@ -30,6 +30,13 @@ function stateOf(e) {
             next: "Ask an org admin; use another environment meanwhile.",
         };
     }
+    if (e.filesLost && e.source === "device") {
+        return {
+            state: "files_lost",
+            reason: "Its directory is gone from the connected machine.",
+            next: "Ask the person to run capybara-device logout, then capybara-device login into this environment, on that machine.",
+        };
+    }
     if (e.filesLost) {
         return {
             state: "files_lost",
@@ -44,7 +51,14 @@ const row = (e) => ({
     name: labelOf(e),
     ...stateOf(e),
     isDefault: e.isDefault,
+    source: e.source,
     provider: e.provider,
+    online: e.online,
+    machine: e.machine && {
+        name: e.machine.name,
+        os: e.machine.os,
+        lastSeenAt: e.machine.lastSeenAt,
+    },
     lastUsedAt: e.instance?.lastUsedAt ?? null,
 });
 /**
@@ -95,7 +109,7 @@ let EnvironmentsOperations = class EnvironmentsOperations {
         this.registry.register([
             defineOperation({
                 id: "environments.list",
-                description: "List your own cloud environments in this org: one compact row each (name, state, whether it is the default, provider, last use), plus the default and last used ids and whether new cloud environments can be made. The default environment is shown as Personal.",
+                description: "List your own environments in this org: one compact row each (name, state, whether it is the default, source: cloud or device for a connected machine, provider, whether a device one is online and its machine, last use), plus the default and last used ids and whether new cloud environments can be made. The default environment is shown as Personal.",
                 input: z.object({}).strict(),
                 example: {},
                 authz: { orgAction: "agents.use" },
@@ -113,7 +127,7 @@ let EnvironmentsOperations = class EnvironmentsOperations {
             }),
             defineOperation({
                 id: "environments.get",
-                description: "Read one of your environments with its provider, state, instance, limits and creation time. Takes the id from environments.list.",
+                description: "Read one of your environments with its source (cloud or device), provider, state, instance, connected machine and whether it is online, limits and creation time. Takes the id from environments.list.",
                 input: EnvironmentId,
                 example: { environmentId: "4e8a0c1d-6b2f-4a37-8d19-3c5e7f9a1b20" },
                 authz: { orgAction: "agents.use" },
@@ -208,7 +222,7 @@ let EnvironmentsOperations = class EnvironmentsOperations {
             }),
             defineOperation({
                 id: "environments.reset-files",
-                description: "Wipe one of your environments' files so it starts empty: ALL its files are destroyed (after running commands finish) and cannot be recovered; the next use creates a fresh workspace. Use it when an environment reports its files are lost. The person confirms every reset; it is never remembered. The environment this conversation works in cannot be wiped. Takes the id from environments.list.",
+                description: "Wipe one of your environments' files so it starts empty: ALL its files are destroyed (after running commands finish) and cannot be recovered; the next use creates a fresh workspace. Use it when an environment reports its files are lost (not for a connected machine's environment: its files are on the machine). The person confirms every reset; it is never remembered. The environment this conversation works in cannot be wiped. Takes the id from environments.list.",
                 input: EnvironmentId,
                 example: { environmentId: "4e8a0c1d-6b2f-4a37-8d19-3c5e7f9a1b20" },
                 authz: { orgAction: "agents.use" },
@@ -225,6 +239,10 @@ let EnvironmentsOperations = class EnvironmentsOperations {
                         code: "environment.current",
                         next: "This conversation works in it: ask the person to wipe it on the web, or wipe a different one.",
                     },
+                    {
+                        code: "environment.files_on_device",
+                        next: "Its files are on its connected machine: ask the person to run capybara-device logout, then capybara-device login into this environment, on that machine.",
+                    },
                     {
                         code: "environment.unavailable",
                         next: {

package/dist/platform/ops/platform.ops.d.ts

@@ -1,17 +1,22 @@
 import { type OnModuleInit } from "@nestjs/common";
 import { AgentsService } from "../../agents/agents.service.js";
+import { AccountsService } from "../../identity/accounts.js";
 import { OrgSettingsService } from "../../orgs/settings.service.js";
 import { ToolRegistry } from "../../tools/registry.js";
 import { PlatformActor } from "../actor.js";
 import { PlatformOperations } from "../registry.js";
-/** The `platform` domain: orientation, and what this agent is (spec §7). Synthetic, no route. */
+/**
+ * The `platform` domain: orientation and what this agent is (spec §7, synthetic), and the
+ * person's own preferences (`/me/preferences`).
+ */
 export declare class PlatformOperationsProvider implements OnModuleInit {
     private readonly registry;
     private readonly actor;
     private readonly agents;
     private readonly settings;
     private readonly tools;
-    constructor(registry: PlatformOperations, actor: PlatformActor, agents: AgentsService, settings: OrgSettingsService, tools: ToolRegistry);
+    private readonly accounts;
+    constructor(registry: PlatformOperations, actor: PlatformActor, agents: AgentsService, settings: OrgSettingsService, tools: ToolRegistry, accounts: AccountsService);
     /**
      * The agent's tools by the keys the model sees, as the registry resolves them for a run (tools
      * default-on spec §8): every tool the org offers that the definition does not turn off, builtins