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

package/dist/tools/builtins/skill-load.js

@@ -9,19 +9,19 @@ import { resolveSkillForkType } from "../../runtime/subagents/roster.js";
 import { invocationOf, resolveSkills } from "../../skills/catalog.js";
 import { PLATFORM_SOURCE, skillFileStore } from "../../skills/usable.js";
 import { AGENT_TOOL, SANDBOX_TOOL_NAMES } from "../builtin-names.js";
-import { clip, display, inSandbox, sandboxBaseTimeoutMs, withNotices, withPathLease, } from "./sandbox/common.js";
+import { clip, display, inSandbox, sandboxBaseTimeoutMs, sandboxConversationOf, sandboxUsable, withNotices, withPathLease, } from "./sandbox/common.js";
 /**
  * Builtin tool `Skill` (M5 T14, ruling M17): resolves the name against the latest skills catalog
  * snapshot in the log to an id and version, and returns that version's SKILL.md body and file list
  * (the result names the version). A skill with other files is copied whole into the conversation's
- * environment at `/skills/<name>@<digest>/` (the provider writes as root, commands read only; the
+ * environment at `<skills root>/<name>@<digest>/` (the instance's skills root, `/skills` by default; the provider writes as root, commands read only; the
  * digest is {@link skillDigest} of the version's file manifest, so versions of one skill coexist in
  * the shared file system). Without a sandbox provider only the body is given, with a note that
  * scripts are unavailable.
  *
  * - Every file read from storage is checked against the manifest's sha256; a mismatch is refused.
  * - The copy is recorded in a kernel-controlled marker, one per skill version
- *   ({@link skillMarkerPath}: `/skills/.capybara/<name>@<digest>.json`, commands cannot change it):
+ *   ({@link skillMarkerPath}: `<skills root>/.capybara/<name>@<digest>.json`, commands cannot change it):
  *   `{ digest, files }`. A present marker with the same digest skips the copy.
  * - An agent without any sandbox tool creates no sandbox and copies nothing (the model could not
  *   run the scripts), and is told so.
@@ -29,11 +29,14 @@ import { clip, display, inSandbox, sandboxBaseTimeoutMs, withNotices, withPathLe
  *   to run scripts with an interpreter (`sh` / `python3` / `node`).
  */
 /**
- * 已复制进沙箱的技能的标记目录（内核控制：`/skills` 只有提供方以 root 能写；技能名不以 `.` 开头，不会撞名）。
+ * 已复制进沙箱的技能的标记目录（内核控制：技能根目录只有提供方以 root 能写；技能名不以 `.` 开头，不会撞名）。
+ * `skillsRoot`: the instance's skills root.
  */
-export const SKILLS_MARKER_DIR = `${SKILLS_SANDBOX_ROOT}/.capybara`;
+export const skillsMarkerDir = (skillsRoot = SKILLS_SANDBOX_ROOT) => `${skillsRoot}/.capybara`;
+/** {@link skillsMarkerDir} of an instance with the default roots. */
+export const SKILLS_MARKER_DIR = skillsMarkerDir();
 /** The marker file of one skill version. */
-export const skillMarkerPath = (name, digest) => `${SKILLS_MARKER_DIR}/${name}@${digest}.json`;
+export const skillMarkerPath = (name, digest, skillsRoot = SKILLS_SANDBOX_ROOT) => `${skillsMarkerDir(skillsRoot)}/${name}@${digest}.json`;
 const MARKER_MAX_BYTES = 256 * 1024;
 /** 结果里最多列出的文件数（其余只给数量）。 */
 const MAX_LISTED_FILES = 200;
@@ -46,7 +49,7 @@ const SPEC = {
     description: "Load a skill from the skills list: returns the skill's instructions " +
         "(its SKILL.md) and the list of its files. Call it before starting a task that matches a " +
         "skill's description, then follow the returned instructions. If the skill has scripts or other " +
-        "files, they are copied read-only to /skills/<name>@<version-id>/ in this environment; run scripts " +
+        "files, they are copied read-only to <name>@<version-id>/ in the skills directory of this environment; run scripts " +
         "there with an interpreter (sh, python3, node). Call it again when the skills list changes. Pass args when the task gives the skill arguments (they replace " +
         "$ARGUMENTS and $1, $2… in the instructions). Do not use it for skills that are not in the list.",
     inputSchema: {
@@ -157,13 +160,13 @@ async function readVerified(store, key, file, skill, signal) {
     }
 }
 /**
- * Copies the skill version whole to `/skills/<name>@<digest>/` (skipped when its marker matches).
+ * Copies the skill version whole to `<skills root>/<name>@<digest>/` (skipped when its marker matches).
  * Every file is checked against the manifest before it is written; the marker is written last, so
  * a failure midway means the next call starts over.
  */
 async function copySkill(s, v) {
     const { name } = v.entry;
-    const markerPath = skillMarkerPath(name, v.digest);
+    const markerPath = skillMarkerPath(name, v.digest, s.roots.skills);
     const m = await s.p.readFile(s.h, markerPath, { maxBytes: MARKER_MAX_BYTES, signal: s.signal });
     const cur = m && !m.truncated ? parseMarker(m.data) : undefined;
     if (cur?.digest === v.digest)
@@ -172,7 +175,7 @@ async function copySkill(s, v) {
         const data = f.path === SKILL_ENTRY_FILE
             ? v.entryBytes
             : await readVerified(v.store, `${v.keyPrefix}${f.path}`, f, name, s.signal);
-        await s.p.writeFile(s.h, skillSandboxPath(name, v.digest, f.path), data, s.signal);
+        await s.p.writeFile(s.h, skillSandboxPath(name, v.digest, f.path, s.roots.skills), data, s.signal);
     }
     const entry = { digest: v.digest, files: v.manifest.files.map((f) => f.path) };
     await s.p.writeFile(s.h, markerPath, new TextEncoder().encode(JSON.stringify(entry)), s.signal);
@@ -435,14 +438,15 @@ export function skillLoadTool(deps) {
             }
             if ("errors" in parsed)
                 throw new ToolError(integrityText(name));
-            const dir = `${skillSandboxDir(name, digest)}/`;
+            // the skills root of the instance the files were copied to (the default without a copy)
+            let skillsRoot = SKILLS_SANDBOX_ROOT;
             const others = manifest.files.filter((f) => f.path !== SKILL_ENTRY_FILE);
             let notices = [];
             let filesText;
             if (others.length === 0) {
                 filesText = "This skill has no files besides its instructions.";
             }
-            else if (!deps.sandbox.available) {
+            else if (!(await sandboxUsable(deps, ctx.orgId, sandboxConversationOf(ctx)))) {
                 filesText =
                     `Skill files (for reference):\n${fileList(manifest.files)}\n` +
                         "This deployment has no sandbox, so the skill's scripts and other files are not available; " +
@@ -457,19 +461,21 @@ export function skillLoadTool(deps) {
             }
             else {
                 // the skill's marker is read, compared and written: one holder at a time per skill
-                const r = await inSandbox(deps, ctx, (s) => withPathLease(deps, s, skillMarkerPath(name, digest), s.signal, (signal) => copySkill({ ...s, signal }, v)));
+                const r = await inSandbox(deps, ctx, (s) => withPathLease(deps, s, skillMarkerPath(name, digest, s.roots.skills), s.signal, (signal) => copySkill({ ...s, signal }, v).then(() => s.roots)));
                 notices = r.notices;
+                skillsRoot = r.value.skills;
+                const dir = `${skillSandboxDir(name, digest, skillsRoot)}/`;
                 filesText =
                     `Skill files (copied to ${dir} in the sandbox, read-only):\n${fileList(manifest.files)}\n` +
                         `Run scripts with an interpreter, e.g. \`sh ${dir}<script>.sh\`, \`python3 ${dir}<script>.py\` ` +
                         "or `node`; the files are not executable, so `./script` does not work. Write outputs under " +
-                        `/workspace, not ${SKILLS_SANDBOX_ROOT}.`;
+                        `${r.value.workspace}, not ${skillsRoot}.`;
             }
             const invocation = invocationOf(manifest);
             const fork = invocation.fork;
             let instructions;
             try {
-                instructions = renderSkillBody(parsed.body.trim(), invocation, args ?? "", name, digest);
+                instructions = renderSkillBody(parsed.body.trim(), invocation, args ?? "", name, digest, skillsRoot);
             }
             catch (e) {
                 if (!(e instanceof RangeError))

package/dist/tools/builtins/skill-write.js

@@ -29,7 +29,7 @@ const SPEC = {
         "user-invocable, context, agent, argument-hint and arguments, which are kept; with " +
         "disable-model-invocation: true only a person can invoke the skill and you cannot load it). " +
         "Every other entry in `files` is stored at " +
-        "/skills/<name>@<version-id>/<path> once loaded. Files of the previous version that you leave out are not part of the new " +
+        "<name>@<version-id>/<path> in the skills directory once loaded. Files of the previous version that you leave out are not part of the new " +
         "version. Text files only, at most 1 MB per skill in total. Use an existing skill's name to update " +
         "it; an organization skill with the same name is shadowed by this agent's own skill. On a private " +
         "agent the new version takes effect immediately. On a shared agent the change is sent to the " +
@@ -41,7 +41,7 @@ const SPEC = {
                 type: "string",
                 minLength: 1,
                 maxLength: SKILL_LIMITS.nameMaxChars,
-                description: 'Skill name: lowercase letters, digits and single hyphens, e.g. "weekly-report". Also the folder name under /skills/.',
+                description: 'Skill name: lowercase letters, digits and single hyphens, e.g. "weekly-report". Also the folder name in the skills directory.',
             },
             description: {
                 type: "string",

package/dist/tools/pipeline.js

@@ -249,6 +249,8 @@ let ToolPipeline = class ToolPipeline {
                     subagents: ctx.agent.subagents,
                     child: ctx.parent !== undefined,
                     forkChild: ctx.parent?.forSkill === true,
+                    sandboxConversationId: ctx.parent?.rootConversationId ?? ctx.conversationId,
+                    replay: ctx.conversationKind === "eval",
                 });
             }
             return resolved;

package/dist/tools/registry.d.ts

@@ -12,6 +12,18 @@ import { BuiltinTools } from "./builtins/builtin-tools.js";
 import { OrgToolSwitches } from "./org-tool-switches.js";
 export { BUILTIN_TOOL_NAMES } from "./builtin-names.js";
 export { canonicalJson } from "./canonical-json.js";
+/**
+ * What a tool's `unavailable` is asked with: the org, and for a run's listing the root
+ * conversation (`conversationId`; the sandbox tools follow its environment, ruling R8), whether
+ * the run is an eval replay (`replay`: its tool calls are never executed), and a `memo` shared by
+ * the tools of one listing (one answer per question per listing).
+ */
+export interface ToolListingScope {
+    orgId: string;
+    conversationId?: string;
+    replay?: boolean;
+    memo?: Map<string, unknown>;
+}
 /** A problem of a saved definition's `disabledTools` (`path` is `disabledTools.<i>`). */
 export interface ToolRefIssue {
     path: string;
@@ -82,11 +94,9 @@ export interface BuiltinTool {
     /**
      * The factual reason this tool is unavailable for the org right now (English, actionable; it goes
      * into the "tool unavailable" reminder), or null when it is available. May be async (e.g. a
-     * per-org extension-point default).
+     * per-org extension-point default). See {@link ToolListingScope} for what a listing passes.
      */
-    unavailable?: (ctx: {
-        orgId: string;
-    }) => Promise<string | null> | string | null;
+    unavailable?: (ctx: ToolListingScope) => Promise<string | null> | string | null;
     /**
      * A policy key derived from the validated input (Platform tool spec §6.2), or null to use the
      * tool key. With a key, agent and parent policies, grants and approvals are keyed by it (an
@@ -334,6 +344,13 @@ export declare class ToolRegistry {
          * it reaches its parent with neither tool (`SendMessage` only to its own sub-agents).
          */
         forkChild?: boolean;
+        /**
+         * The root conversation of the run (a sub-agent's tree root): tools whose availability
+         * depends on the conversation's environment (the sandbox tools) are listed by it.
+         */
+        sandboxConversationId?: string;
+        /** An eval replay's listing: its calls are never executed (the sandbox tools are listed). */
+        replay?: boolean;
     }): Promise<AgentTools>;
     /** 是否启用 `ToolSearch`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
     private searchActive;

package/dist/tools/registry.js

@@ -348,6 +348,14 @@ let ToolRegistry = class ToolRegistry {
     }
     async resolve(orgId, def) {
         const disabled = def.disabledTools ?? [];
+        const scope = {
+            orgId,
+            ...(def.sandboxConversationId !== undefined && {
+                conversationId: def.sandboxConversationId,
+            }),
+            ...(def.replay === true && { replay: true }),
+            memo: new Map(),
+        };
         const tools = [];
         const unavailable = [];
         const hidden = [];
@@ -373,7 +381,7 @@ let ToolRegistry = class ToolRegistry {
             const b = this.builtins.find((x) => x.spec.name === name);
             if (!b)
                 continue;
-            const why = (await b.unavailable?.({ orgId })) ?? null;
+            const why = (await b.unavailable?.(scope)) ?? null;
             if (why !== null) {
                 hidden.push({ ref: name, reason: why });
                 continue;
@@ -392,7 +400,7 @@ let ToolRegistry = class ToolRegistry {
             if (name === BUILTIN.Bash) {
                 for (const companion of BASH_COMPANION_TOOLS) {
                     const c = this.builtins.find((x) => x.spec.name === companion);
-                    if (c && ((await c.unavailable?.({ orgId })) ?? null) === null) {
+                    if (c && ((await c.unavailable?.(scope)) ?? null) === null) {
                         add(builtinTool(c, c.spec));
                     }
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/kernel",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.9",
   "description": "Capybara kernel: config, database, plugin host and HTTP API of the Capybara agent platform",
   "license": "Apache-2.0",
   "repository": {
@@ -32,6 +32,7 @@
   "dependencies": {
     "@fastify/cookie": "^11.1.3",
     "@fastify/static": "^9.3.0",
+    "@fastify/websocket": "^11.3.7",
     "@langchain/core": "^1.2.18",
     "@langchain/langgraph": "^1.5.1",
     "@langchain/langgraph-checkpoint": "^1.2.0",
@@ -64,14 +65,16 @@
     "yaml": "^2.9.1",
     "yauzl": "3.4.0",
     "zod": "^4.6.7",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.5"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.6"
   },
   "devDependencies": {
     "@langchain/langgraph-checkpoint-validation": "^1.2.0",
     "@types/pg": "^8.23.1",
     "@types/semver": "^7.8.0",
+    "@types/ws": "^8.18.2",
     "@types/yauzl": "3.4.0",
-    "@capybara-hq/testing": "0.1.0-rc.8"
+    "ws": "^8.22.0",
+    "@capybara-hq/testing": "0.1.0-rc.9"
   },
   "scripts": {
     "build": "tsc -b"

package/src/migrations/0093_connected_environments.sql

@@ -0,0 +1,37 @@
+-- Environments phase 2 (spec 2026-11-07-environments-design §6, §13): a person's own machine,
+-- connected through the device program, becomes an environment with source 'device'. Expand-only:
+-- the source CHECK list grows and a new table holds the connected machine.
+
+-- 0088 left the CHECK unnamed, so Postgres named it environments_source_check; re-add it under
+-- the same name with the longer list.
+ALTER TABLE environments DROP CONSTRAINT IF EXISTS environments_source_check;
+ALTER TABLE environments
+  ADD CONSTRAINT environments_source_check CHECK (source IN ('cloud', 'device'));
+
+-- The machine connected to a device environment. credential_hash is a hash of the machine's
+-- long-lived credential (cap_dev_...), never the credential itself; revoking a machine sets
+-- revoked_at and keeps the row, so only one unrevoked machine exists per environment.
+-- program_version, mode, roots and session_isolation are what the program reported on its last
+-- connection; last_seen_at is the last time it connected or pinged.
+CREATE TABLE IF NOT EXISTS environment_machines (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id text NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  environment_id text NOT NULL REFERENCES environments(id) ON DELETE CASCADE,
+  account_id text NOT NULL,
+  credential_hash text NOT NULL UNIQUE,
+  name text NOT NULL,
+  os text NOT NULL,
+  arch text NOT NULL,
+  program_version text,
+  mode text CHECK (mode IN ('os', 'docker')),
+  roots jsonb,
+  session_isolation boolean NOT NULL DEFAULT false,
+  last_seen_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  revoked_at timestamptz
+);
+CREATE UNIQUE INDEX IF NOT EXISTS environment_machines_active_uq
+  ON environment_machines (environment_id)
+  WHERE revoked_at IS NULL;
+-- The org cascade delete looks rows up by org (as environment_instances_org_idx in 0088).
+CREATE INDEX IF NOT EXISTS environment_machines_org_idx ON environment_machines (org_id);

package/src/migrations/0094_environment_paths_idx.sql

@@ -0,0 +1,7 @@
+-- Environments phase 2 (spec 2026-11-07-environments-design §13.1, ruling R22): every sandbox tool
+-- call reads the conversation's latest environment_paths event; a partial index answers it
+-- without scanning the conversation's events backwards. Not CONCURRENTLY, like the other index
+-- migrations (0025).
+CREATE INDEX IF NOT EXISTS conversation_events_environment_paths_idx
+  ON conversation_events (conversation_id, seq)
+  WHERE type = 'environment_paths';