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

package/dist/runtime/context/build.js

@@ -4,6 +4,7 @@ import { renderBackgroundFinished } from "../../background/render.js";
 import { isAbsorbable, } from "../../conversations/events.js";
 import { catalogText, isAlwaysLoaded } from "../../tools/builtins/tool-search.js";
 import { renderSubagentDelivery } from "../subagents/render.js";
+import { environmentPathsAt, environmentPathsText } from "./environment-paths.js";
 import { LEGACY_CATALOG_HEADER, LEGACY_SKILL_TEXTS, usesLegacyToolNames } from "./legacy-text.js";
 import { currentRunContext, runContextEvents, runContextFullText, runContextText, senderLines, } from "./run-context.js";
 import { invokedSkillNames, invokedSkillsText, SKILL_TEXTS, skillsCatalogEvents, snapshotChangeText, snapshotCurrentText, snapshotSystemText, systemSkillsCatalog, } from "./skills.js";
@@ -336,6 +337,8 @@ export function summaryText(summary) {
  *   `user_message` / `assistant_message`（content 原样，含 opaque；aborted 的也回放；媒体引用按
  *   {@link resolveMedia} 换成 base64 或文字占位）/ `reminder`
  *   （`role: "system"`，放在它所在的位置）/ `tools_changed` (`role: "system"`, the text of {@link toolsChangedText}, at its position) /
+ *   `environment_paths` (`role: "system"` at its position, `environmentPathsText`; covered by the
+ *   summary: the latest one follows the summary) /
  *   `run_context` (`role: "system"` at its position, `runContextText`; covered by the summary: the
  *   current context follows the summary whole; a user message's sender line by `senderLines`) /
  *   `background_task_finished`（`role: "system"`, the text of
@@ -547,6 +550,12 @@ export function buildModelRequest(input) {
                 content: runContextFullText(currentRunContext(events, after)),
             });
         }
+        // environments spec §13.1: the instance's directories told before the boundary follow the
+        // summary again (the model keeps using the real paths)
+        const paths = environmentPathsAt(events, after);
+        if (paths) {
+            messages.push({ role: "system", content: environmentPathsText(paths.payload.roots) });
+        }
         // 被摘要覆盖的变更提醒不再发送：摘要时生效的目录与 system 里的不同 → 紧随摘要补上完整的当前目录
         const covered = skillSnaps.filter((e) => e.seq <= after).at(-1);
         // (phase B: plus the current pinned skills and tool-name map when they differ from system's)
@@ -620,6 +629,11 @@ export function buildModelRequest(input) {
             case "run_context":
                 messages.push({ role: "system", content: runContextText(events, e) });
                 break;
+            // the instance's directories (environments spec §13.1): logged during a step's tool call,
+            // so rendered after that step's tool results
+            case "environment_paths":
+                messages.push({ role: "system", content: environmentPathsText(e.payload.roots) });
+                break;
             // hook_denied is not model-visible: the model sees only the denied tool call's tool_result
             // (and nothing for a denied model request), so request building skips it
             case "hook_denied":

package/dist/runtime/context/compaction.js

@@ -134,6 +134,7 @@ function transcriptLine(e) {
         // phase D: a forked skill's report is user content of the request (build.ts)
         case "skill_fork_result":
             return `User: ${e.payload.text}`;
+        // environment_paths is left out too: the latest one follows the summary (build.ts)
         // run_context is left out: its current values follow the summary anyway (build.ts), and
         // stale names should not be summarised as current
         case "tool_result":

package/dist/runtime/context/environment-paths.d.ts

@@ -0,0 +1,40 @@
+import type { SandboxRoots } from "@capybara-hq/plugin-sdk";
+import type { ConversationEvent } from "../../conversations/events.js";
+/**
+ * The `environment_paths` event (environments spec §13.1, ruling R22): the first sandbox tool call
+ * of every conversation records the instance's roots (the defaults included), and a later call
+ * records them again whenever they differ from the conversation's latest recorded ones (a
+ * connected machine's real paths, a mode switch back to the defaults). Model-visible: rendered at
+ * its position as a system message; in the log, so it needs no `DriftReason`.
+ */
+/** The system line of an `environment_paths` event (model-visible, English). */
+export declare function environmentPathsText(r: SandboxRoots): string;
+/** Whether two sets of roots are the same paths. */
+export declare const sameRoots: (a: SandboxRoots, b: SandboxRoots) => boolean;
+/**
+ * The idempotency key of an `environment_paths` event for `r` that follows the conversation's
+ * event at `prevSeq` (0: none). Unique per change (A → B → A gets three events), while parallel
+ * calls that saw the same latest event write it once.
+ */
+export declare const environmentPathsIdemKey: (r: SandboxRoots, prevSeq: number) => string;
+/**
+ * The `environment_paths` event to append when a sandbox call holds an instance with `roots` and
+ * the conversation's latest such event is `latest`; null when nothing changed.
+ */
+export declare function environmentPathsChange(latest: {
+    seq: number;
+    payload: {
+        roots: SandboxRoots;
+    };
+} | undefined, roots: SandboxRoots, runId: string | undefined): {
+    type: "environment_paths";
+    runId?: string;
+    idemKey: string;
+    payload: {
+        roots: SandboxRoots;
+    };
+} | null;
+/** The latest `environment_paths` event at or before `seq`; undefined without one. */
+export declare function environmentPathsAt(events: readonly ConversationEvent[], seq: number): Extract<ConversationEvent, {
+    type: "environment_paths";
+}> | undefined;

package/dist/runtime/context/environment-paths.js

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+/**
+ * The `environment_paths` event (environments spec §13.1, ruling R22): the first sandbox tool call
+ * of every conversation records the instance's roots (the defaults included), and a later call
+ * records them again whenever they differ from the conversation's latest recorded ones (a
+ * connected machine's real paths, a mode switch back to the defaults). Model-visible: rendered at
+ * its position as a system message; in the log, so it needs no `DriftReason`.
+ */
+/** The system line of an `environment_paths` event (model-visible, English). */
+export function environmentPathsText(r) {
+    return `This environment's directories: workspace ${r.workspace}, skills ${r.skills} (read only), temporary files ${r.tmp}. Use these paths in commands and tool calls.`;
+}
+/** Whether two sets of roots are the same paths. */
+export const sameRoots = (a, b) => a.workspace === b.workspace && a.skills === b.skills && a.tmp === b.tmp;
+/**
+ * The idempotency key of an `environment_paths` event for `r` that follows the conversation's
+ * event at `prevSeq` (0: none). Unique per change (A → B → A gets three events), while parallel
+ * calls that saw the same latest event write it once.
+ */
+export const environmentPathsIdemKey = (r, prevSeq) => `environment_paths:${createHash("sha256")
+    .update(JSON.stringify([r.workspace, r.skills, r.tmp]))
+    .digest("hex")
+    .slice(0, 16)}:${prevSeq}`;
+/**
+ * The `environment_paths` event to append when a sandbox call holds an instance with `roots` and
+ * the conversation's latest such event is `latest`; null when nothing changed.
+ */
+export function environmentPathsChange(latest, roots, runId) {
+    if (latest && sameRoots(latest.payload.roots, roots))
+        return null;
+    return {
+        type: "environment_paths",
+        ...(runId !== undefined && { runId }),
+        idemKey: environmentPathsIdemKey(roots, latest?.seq ?? 0),
+        payload: { roots: { workspace: roots.workspace, skills: roots.skills, tmp: roots.tmp } },
+    };
+}
+/** The latest `environment_paths` event at or before `seq`; undefined without one. */
+export function environmentPathsAt(events, seq) {
+    let found;
+    for (const e of events) {
+        if (e.seq > seq)
+            break;
+        if (e.type === "environment_paths")
+            found = e;
+    }
+    return found;
+}

package/dist/runtime/model-call.js

@@ -163,6 +163,8 @@ wrapUpReason) {
             subagents: input.agent.subagents,
             child: input.parent !== undefined || input.parentRunId !== undefined || input.subagent === true,
             forkChild: input.parent?.forSkill === true,
+            sandboxConversationId: input.parent?.rootConversationId ?? input.conversationId,
+            replay: input.conversationKind === "eval",
             skillLoad: skillLoadOffered(events.findLast((e) => e.type === "skills_catalog"), hasInvocation(events)),
         });
         const tools = {

package/dist/sandbox/providers.d.ts

@@ -1,19 +1,41 @@
 import { type SandboxProvider } from "@capybara-hq/plugin-sdk";
 import { ExtensionRegistry } from "../extensions/registry.js";
-/** 当前的 `sandbox@2` 提供方：插件名与实现。 */
+/** The kernel-internal provider of connected machines (`device` environments). */
+export declare const DEVICE_PROVIDER = "@device";
+/**
+ * A kernel-internal provider name: it starts with `@`, which no extension name can
+ * (`EXTENSION_NAME_RE`), so it never collides with a loaded `sandbox@2` plugin.
+ */
+export declare const isInternalProvider: (name: string) => boolean;
+/** A sandbox provider: its name (plugin name, or an internal `@…` name) and implementation. */
 export interface SandboxProviderEntry {
     plugin: string;
     impl: SandboxProvider;
 }
 /**
- * The `sandbox@2` providers of this process, read from the {@link ExtensionRegistry} at every
- * call: providers are ready only after the extension load, and change with installs.
+ * The sandbox providers of this process. The cloud provider is the loaded `sandbox@2` extension,
+ * read from the {@link ExtensionRegistry} at every call (providers are ready only after the
+ * extension load, and change with installs). Kernel-internal providers (`@device`) are registered
+ * by their module on init, in every replica: they are code, not shared state.
  */
 export declare class SandboxProviders {
     private readonly registry;
+    private readonly internal;
     constructor(registry: Pick<ExtensionRegistry, "list">);
-    /** The current provider; undefined without one. */
-    current(): SandboxProviderEntry | undefined;
-    /** A still-loaded provider by plugin name (to destroy an earlier provider's instance). */
-    lookup(plugin: string): SandboxProvider | undefined;
+    /** Registers a kernel-internal provider (an `@…` name); a later registration replaces it. */
+    register(entry: SandboxProviderEntry): void;
+    /** The cloud provider (the loaded `sandbox@2` extension); undefined without one. */
+    cloud(): SandboxProviderEntry | undefined;
+    /**
+     * A provider by name: a registered internal provider, else a still-loaded `sandbox@2` extension
+     * of that plugin name (to destroy an earlier provider's resources).
+     */
+    forName(name: string): SandboxProviderEntry | undefined;
 }
+/**
+ * The provider an environment works with, from its `environments.provider`: an internal one
+ * (`@device`) by that name only, never falling back to the cloud provider; any other environment
+ * is a cloud environment and uses the current cloud provider (files kept by another provider are
+ * refused by the sandbox service, `environment.unavailable`).
+ */
+export declare function providerForEnvironment(providers: Pick<SandboxProviders, "cloud" | "forName">, provider: string | null): SandboxProviderEntry | undefined;

package/dist/sandbox/providers.js

@@ -10,25 +10,49 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { SANDBOX_EXTENSION_POINT } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { ExtensionRegistry } from "../extensions/registry.js";
+/** The kernel-internal provider of connected machines (`device` environments). */
+export const DEVICE_PROVIDER = "@device";
 /**
- * The `sandbox@2` providers of this process, read from the {@link ExtensionRegistry} at every
- * call: providers are ready only after the extension load, and change with installs.
+ * A kernel-internal provider name: it starts with `@`, which no extension name can
+ * (`EXTENSION_NAME_RE`), so it never collides with a loaded `sandbox@2` plugin.
+ */
+export const isInternalProvider = (name) => name.startsWith("@");
+/**
+ * The sandbox providers of this process. The cloud provider is the loaded `sandbox@2` extension,
+ * read from the {@link ExtensionRegistry} at every call (providers are ready only after the
+ * extension load, and change with installs). Kernel-internal providers (`@device`) are registered
+ * by their module on init, in every replica: they are code, not shared state.
  */
 let SandboxProviders = class SandboxProviders {
     registry;
+    internal = new Map();
     constructor(registry) {
         this.registry = registry;
     }
-    /** The current provider; undefined without one. */
-    current() {
+    /** Registers a kernel-internal provider (an `@…` name); a later registration replaces it. */
+    register(entry) {
+        if (!isInternalProvider(entry.plugin)) {
+            throw new Error(`an internal sandbox provider name starts with @: ${entry.plugin}`);
+        }
+        this.internal.set(entry.plugin, entry);
+    }
+    /** The cloud provider (the loaded `sandbox@2` extension); undefined without one. */
+    cloud() {
         const e = this.registry.list("sandbox").find((x) => x.capability === SANDBOX_EXTENSION_POINT);
         return e ? { plugin: e.plugin, impl: e.impl } : undefined;
     }
-    /** A still-loaded provider by plugin name (to destroy an earlier provider's instance). */
-    lookup(plugin) {
-        return this.registry
+    /**
+     * A provider by name: a registered internal provider, else a still-loaded `sandbox@2` extension
+     * of that plugin name (to destroy an earlier provider's resources).
+     */
+    forName(name) {
+        const own = this.internal.get(name);
+        if (own)
+            return own;
+        const e = this.registry
             .list("sandbox")
-            .find((x) => x.capability === SANDBOX_EXTENSION_POINT && x.plugin === plugin)?.impl;
+            .find((x) => x.capability === SANDBOX_EXTENSION_POINT && x.plugin === name);
+        return e ? { plugin: e.plugin, impl: e.impl } : undefined;
     }
 };
 SandboxProviders = __decorate([
@@ -36,3 +60,14 @@ SandboxProviders = __decorate([
     __param(0, Inject(ExtensionRegistry))
 ], SandboxProviders);
 export { SandboxProviders };
+/**
+ * The provider an environment works with, from its `environments.provider`: an internal one
+ * (`@device`) by that name only, never falling back to the cloud provider; any other environment
+ * is a cloud environment and uses the current cloud provider (files kept by another provider are
+ * refused by the sandbox service, `environment.unavailable`).
+ */
+export function providerForEnvironment(providers, provider) {
+    if (provider !== null && isInternalProvider(provider))
+        return providers.forName(provider);
+    return providers.cloud();
+}

package/dist/sandbox/sandbox.service.d.ts

@@ -1,4 +1,4 @@
-import { type ExecResult, type SandboxActor, type SandboxHandle, type SandboxLimits, type SandboxProvider } from "@capybara-hq/plugin-sdk";
+import { type ExecResult, type SandboxActor, type SandboxHandle, type SandboxLimits, type SandboxProvider, type SandboxRoots } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import { type Selectable } from "kysely";
 import { BackgroundTaskStore } from "../background/store.js";
@@ -21,6 +21,11 @@ export interface SandboxUseInfo {
      * new instance on the kept files, so earlier processes are gone.
      */
     restarted: boolean;
+    /**
+     * The instance's roots ({@link rootsOf} of its handle): every model-visible path is built from
+     * them (environments spec §13.1; a connected machine's real paths).
+     */
+    roots: SandboxRoots;
 }
 /** Who uses the sandbox in {@link SandboxService.withSandbox}. */
 export interface SandboxUseContext {
@@ -78,8 +83,12 @@ export type IfRunningResult<T> = {
 export declare const environmentResourceName: (environmentId: string) => string;
 /** The environment is missing, deleted, or not in the caller's org (404; ids cannot be probed). */
 export declare const environmentNotFound: () => ApiError;
-/** The environment's file system is gone at the provider (409); never replaced silently. */
-export declare const environmentFilesLost: () => ApiError;
+/**
+ * The environment's file system is gone at the provider (409); never replaced silently. On a
+ * connected machine (`device`, details `[{ source: "device" }]`) the directory is the machine
+ * owner's: `capybara-device logout`, then `login` into the environment, recreates it (ruling R24).
+ */
+export declare const environmentFilesLost: (device?: boolean) => ApiError;
 /**
  * The row still records the instance `gone` (same handle and same `created_at`). Handles compare
  * canonically: a jsonb round trip reorders a multi-key handle's keys (final review m9).
@@ -146,18 +155,25 @@ export declare const sandboxUnavailable: () => ApiError;
  *   row's `created_at` (set by the fenced write after each `create`); the handle alone is the same
  *   after a rebuild on providers whose handle is the instance name (sandbox-docker).
  *
+ * - **Provider per environment** (environments spec §6): each call resolves the provider from
+ *   the environment's `environments.provider` ({@link providerForEnvironment}): a `device`
+ *   environment runs on the kernel-internal `@device` provider (never the cloud one), a cloud
+ *   environment on the loaded `sandbox@2` extension. A `@device` instance is never suspended or
+ *   destroyed for inactivity; a deleted `@device` environment (or one of a deleted org) is
+ *   destroyed by the sweep like any other.
+ *
  * Files kept by another provider than the current one make the environment unusable
  * (`environment.unavailable`) until that provider is back; deleting it still works while that
- * provider is loaded ({@link SandboxProviders.lookup}). Without a provider {@link available} is false and
- * uses throw `sandbox.unavailable` (503). No in-process state: replicas share it through PG and
- * Redis.
+ * provider is loaded ({@link SandboxProviders.forName}). Without the environment's provider
+ * {@link availableFor} is false and uses throw `sandbox.unavailable` (503). No in-process state:
+ * replicas share it through PG and Redis.
  */
 export declare class SandboxService {
     private readonly db;
     /** The record of the instance each holder last used (`capk:sandbox-seen:…`). */
     private readonly redis;
     private readonly leases;
-    /** The `sandbox@2` provider (read at every call: providers are ready after the extension load). */
+    /** The providers (read at every call: providers are ready after the extension load). */
     private readonly providers;
     private readonly config;
     private readonly log;
@@ -166,14 +182,28 @@ export declare class SandboxService {
     constructor(db: KernelDb, 
     /** The record of the instance each holder last used (`capk:sandbox-seen:…`). */
     redis: Pick<Redis, "set">, leases: SandboxLeases, 
-    /** The `sandbox@2` provider (read at every call: providers are ready after the extension load). */
-    providers: Pick<SandboxProviders, "current" | "lookup">, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "info" | "warn">, 
+    /** The providers (read at every call: providers are ready after the extension load). */
+    providers: Pick<SandboxProviders, "cloud" | "forName">, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "info" | "warn">, 
     /** Background tasks lost while their process may live on (killed after a resume). */
     background: Pick<BackgroundTaskStore, "pendingKills" | "clearKill">);
     /** Poll interval while waiting for a lease (the leases' own). */
     private get pollMs();
-    /** Whether there is a sandbox provider. */
-    get available(): boolean;
+    /**
+     * Whether there is a cloud sandbox provider (a loaded `sandbox@2` extension). For gates that have
+     * no environment yet (tool listing, skill files); a call on an environment asks
+     * {@link availableFor}.
+     */
+    get cloudAvailable(): boolean;
+    /** Whether the environment's provider is there (`@device` registered, or a cloud provider). */
+    availableFor(environmentId: string): Promise<boolean>;
+    /**
+     * The provider the environment works with, read from its row ({@link providerForEnvironment});
+     * a missing row (or one of another org, with `orgId`) reads as a cloud environment, whose use
+     * then fails as not found.
+     */
+    private providerOf;
+    /** {@link providerOf}, or `sandbox.unavailable` (503) without it. */
+    private require;
     /** Concurrent holders of one environment (`sandbox.maxConcurrentCommands`, read at every use). */
     private get cap();
     /**
@@ -233,11 +263,20 @@ export declare class SandboxService {
      * - When `fn` throws `SandboxGoneError` (the instance is gone) the instance is rebuilt on the
      *   kept files (or the one another holder rebuilt is taken) and `fn` runs once more with
      *   `restarted: true`; a second `gone` is thrown. Other errors are thrown as they are.
-     * - Lost files throw `environment.files_lost` (409).
+     * - Lost files throw `environment.files_lost` (409), also when `fn` throws
+     *   `FileSystemGoneError` (the files are then recorded lost, ruling R24).
      * - When `ctx.holderConversationId` last used another instance (another holder rebuilt it
      *   meanwhile), `info.restarted` is true, so it learns its processes are gone (final review m5).
      */
     withSandbox<T>(ctx: SandboxUseContext, fn: (h: SandboxHandle, p: HeldProvider, info: SandboxUseInfo, signal: AbortSignal) => Promise<T>, signal: AbortSignal): Promise<T>;
+    /**
+     * Ruling R24: an operation on the held instance `e` found its file system gone. Records
+     * `fs_status = 'lost'` while the row still records that instance on its file system (the
+     * instance handle stays, so a reset still destroys it), moving the fence on, and returns
+     * `environment.files_lost` to throw. Uses then fail until the files are reset (a connected
+     * machine: until a new login, which resets the row). A failed write only logs.
+     */
+    private filesGone;
     /**
      * Records that `holder` uses the instance of `e` (`capk:sandbox-seen:<env>:<holder>` =
      * `<created_at>:<file system id>`, with a TTL of the inactivity destruction plus a day). When the
@@ -258,7 +297,10 @@ export declare class SandboxService {
     private readRow;
     /** The instance row belongs to another org: reported as not found, so ids cannot be probed. */
     private foreign;
-    /** Recorded running with the current provider, and not the instance found gone. */
+    /**
+     * Recorded running with the current provider on files not lost (lost ones go through the
+     * exclusive path, which refuses them), and not the instance found gone.
+     */
     private usable;
     /**
      * Under a just-taken shared lease: confirms the row is still `accept`ed (else releases and
@@ -295,15 +337,19 @@ export declare class SandboxService {
      * (the instance only; the file system is kept and the next use builds a new instance on it); an
      * environment that was deleted, or whose org was deleted, loses its instance and its file system
      * and its row is deleted (as {@link destroyEnvironment} does). Environments with any holder are
-     * skipped. Returns how many it destroyed. Called hourly by the `sandbox-destroy-inactive` cron.
+     * skipped. Inactivity never destroys a `@device` instance; a gone `@device` environment is
+     * destroyed like any other while `@device` is registered. Returns how many it destroyed. Called
+     * hourly by the `sandbox-destroy-inactive` cron.
      */
     destroyInactive(now: Date): Promise<number>;
     /**
      * Destroys the environment's instance, then its file system, then deletes its instance row
      * (environment deletion, offboarding); nothing to do without a row. Waits for the exclusive lease
-     * (with intent, so running commands finish and new ones wait) up to 10 minutes. Without a
-     * provider it only warns (the destruction sweep finishes a deleted environment later). Files kept
-     * by another provider that is not loaded cannot be destroyed: it throws and the row stays.
+     * (with intent, so running commands finish and new ones wait) up to 10 minutes. Without the
+     * environment's provider it throws and the row stays, marked `sweep_failed_at` (the job is
+     * retried, and the destruction sweep finishes a deleted environment once the provider is back).
+     * Files kept by another provider that is not loaded cannot be destroyed: it throws and the row
+     * stays.
      */
     destroyEnvironment(environmentId: string): Promise<void>;
     /**
@@ -329,7 +375,6 @@ export declare class SandboxService {
      * and leaves the flags of this instance's tasks for the next resume.
      */
     private killPendingTasks;
-    private require;
     /**
      * A fenced write: only while the lease holds and the row's generation is still the one read
      * under it (and incremented); otherwise {@link SandboxLockLostError}.
@@ -390,6 +435,13 @@ export declare class SandboxService {
     private destroyRow;
     /** Due for suspension: made by this provider, running, and idle or running for too long. */
     private suspendDue;
+    /** The provider of an instance row: an internal one (`@device`) by name, else the cloud one. */
+    private rowProvider;
+    /**
+     * A row the idle sweeps may touch: not on a kernel-internal provider (`@device` instances live on
+     * people's machines and are never suspended or destroyed for inactivity).
+     */
+    private cloudRow;
     /** The environment was deleted, or its org was: the instance and the files go. */
     private environmentGone;
     /** Due for instance destruction: an instance (or a create in progress) unused for too long. */