@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.6

package/dist/tools/builtins/platform.d.ts

@@ -0,0 +1,34 @@
+import type { OrgSettings } from "../../orgs/settings.service.js";
+import type { ActorFacts } from "../../platform/actor.js";
+import type { AgentDocTopic } from "../../platform/agent-docs.js";
+import type { PlatformOperations } from "../../platform/registry.js";
+import type { BuiltinTool, CallPolicyContext } from "../registry.js";
+/**
+ * The `Platform` builtin (Platform tool spec §3–§6): one tool through which an agent discovers and
+ * calls the platform's own operations as the run's trigger account, and reads the agent docs.
+ * - `browse` / `search` / `describe` / `read` only read; their policy is the tool's `allow`.
+ * - `call` gets a per-call policy key `Platform:<operation>` ({@link BuiltinTool.callPolicy}): a
+ *   read runs, a write asks (remembered only for `personal`), an operation that cannot run now is
+ *   denied with its reason. Right before `op.run` the availability is checked again on fresh facts
+ *   (the actor may have lost the role while the confirmation waited).
+ * - The actor, the agent and the conversation come from the runtime context, never from input.
+ * - Results are JSON text; a list an operation returns is capped at {@link LIST_MAX} entries.
+ */
+/** The most entries of a list in one result (operations that page return `next`). */
+export declare const LIST_MAX = 50;
+/** The tool's `unavailable` reason when the org setting `platformTool` is `off` (spec §3). */
+export declare const PLATFORM_UNAVAILABLE_OFF = "The org turned the Platform tool off; ask an org admin to turn it on.";
+/** What the tool needs; `BuiltinTools` passes the Nest providers. */
+export interface PlatformToolDeps {
+    ops: Pick<PlatformOperations, "domains" | "inDomain" | "get" | "search">;
+    actor: {
+        facts(ctx: CallPolicyContext): Promise<ActorFacts>;
+    };
+    docs: {
+        topics(): AgentDocTopic[];
+        read(id: string): string | null;
+    };
+    /** The org setting `platformTool`. */
+    setting(orgId: string): Promise<OrgSettings["platformTool"]>;
+}
+export declare function platformTool(deps: PlatformToolDeps): BuiltinTool;

package/dist/tools/builtins/platform.js

@@ -0,0 +1,362 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import { availability } from "../../platform/availability.js";
+import { toToolError } from "../../platform/errors.js";
+import { PLATFORM_METHOD } from "../../platform/method.js";
+import { OPERATION_ID, operationDomain, } from "../../platform/operation.js";
+import { BUILTIN } from "../builtin-names.js";
+/**
+ * The `Platform` builtin (Platform tool spec §3–§6): one tool through which an agent discovers and
+ * calls the platform's own operations as the run's trigger account, and reads the agent docs.
+ * - `browse` / `search` / `describe` / `read` only read; their policy is the tool's `allow`.
+ * - `call` gets a per-call policy key `Platform:<operation>` ({@link BuiltinTool.callPolicy}): a
+ *   read runs, a write asks (remembered only for `personal`), an operation that cannot run now is
+ *   denied with its reason. Right before `op.run` the availability is checked again on fresh facts
+ *   (the actor may have lost the role while the confirmation waited).
+ * - The actor, the agent and the conversation come from the runtime context, never from input.
+ * - Results are JSON text; a list an operation returns is capped at {@link LIST_MAX} entries.
+ */
+/** The most entries of a list in one result (operations that page return `next`). */
+export const LIST_MAX = 50;
+/** The most operations `search` returns. */
+const SEARCH_MAX = 20;
+/** The tool's `unavailable` reason when the org setting `platformTool` is `off` (spec §3). */
+export const PLATFORM_UNAVAILABLE_OFF = "The org turned the Platform tool off; ask an org admin to turn it on.";
+const ACTIONS = ["browse", "search", "describe", "call", "read"];
+const SPEC = {
+    name: BUILTIN.Platform,
+    description: "Discover and use the platform's own operations (skills, agents, templates, plugins, " +
+        "marketplaces, requests, connectors, extensions) and its documentation, as the person you are " +
+        'working for. Start with action "browse", then "describe" an operation before you "call" it; ' +
+        'never guess parameters. Writes ask the person to confirm. Use "read" for how-to documentation ' +
+        "(plugin format, skills, extension points).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: [...ACTIONS],
+                description: 'browse: the domains and the method, or one domain\'s operations with "domain"; search: ' +
+                    'operations matching "query"; describe: one operation\'s full definition; call: run ' +
+                    '"operation" with "params"; read: a documentation topic, or the list of topics without ' +
+                    '"topic".',
+            },
+            domain: {
+                type: "string",
+                maxLength: 100,
+                description: 'For browse: a domain id from the browse result, e.g. "skills".',
+            },
+            query: {
+                type: "string",
+                maxLength: 200,
+                description: "For search: words to look for in operation ids and descriptions.",
+            },
+            operation: {
+                type: "string",
+                maxLength: 100,
+                description: 'For describe and call: an operation id, e.g. "skills.list".',
+            },
+            params: {
+                type: "object",
+                description: "For call: the operation's input, matching the inputSchema describe returned. Pass " +
+                    '"cursor" from a previous result\'s "next" to get the next page.',
+            },
+            topic: {
+                type: "string",
+                maxLength: 100,
+                description: "For read: a topic id from the topic list.",
+            },
+        },
+        required: ["action"],
+        additionalProperties: false,
+    },
+    keyArgs: ["action", "operation", "domain"],
+};
+const json = (value, summary) => ({
+    content: [{ type: "text", text: JSON.stringify(value) }],
+    display: { summary },
+});
+/** Longest model-written text quoted in a display summary (summaries are at most 200). */
+const SUMMARY_QUOTE_MAX = 80;
+const clip = (s) => s.length > SUMMARY_QUOTE_MAX ? `${s.slice(0, SUMMARY_QUOTE_MAX)}…` : s;
+/** The first sentence of a description: the line `browse` and `search` show. */
+const firstSentence = (text) => {
+    const m = /^(.+?[.!?])(\s|$)/s.exec(text.trim());
+    return (m?.[1] ?? text).trim();
+};
+const kindOf = (op) => op.confirm === "read" ? "read" : "write";
+const availabilityFields = (a) => a.ok ? { available: true } : { available: false, reason: a.reason };
+/** One operation as `browse` and `search` list it. */
+const line = (op, facts) => ({
+    id: op.id,
+    description: firstSentence(op.description),
+    kind: kindOf(op),
+    ...availabilityFields(availability(op, facts)),
+});
+const capped = (items) => ({
+    items: items.slice(0, LIST_MAX),
+    ...(items.length > LIST_MAX && {
+        total: items.length,
+        truncated: true,
+        hint: "Narrow the query or pass params.cursor where the operation pages.",
+    }),
+});
+/** An operation's result as a JSON object: a bare list is capped, nothing becomes `{ ok: true }`. */
+function asResult(value) {
+    if (Array.isArray(value))
+        return capped(value);
+    if (value === undefined || value === null)
+        return { ok: true };
+    if (typeof value !== "object")
+        return { result: value };
+    return value;
+}
+const unknownOperationText = (id) => `Unknown operation "${id}". Use browse or search to find an operation id, then describe it.`;
+const missingText = (action, field, what) => `Action ${action} needs "${field}": pass ${what}.`;
+const invalidParamsText = (id, problems) => `Invalid params for ${id}: ${problems}. Call describe with operation "${id}" for its input schema and an example, then call again.`;
+const unavailableOpText = (id, reason) => `Operation ${id} is unavailable, so do not call it again as is: ${reason}`;
+const outputRefText = (id) => `Operation ${id} writes, and its params hold a {"$output": ...} reference, which the person confirming would see instead of the content. Pass the content inline in params and call again.`;
+/** Whether a value holds a `{"$output": …}` reference anywhere (the pipeline's form). */
+function hasOutputRef(v) {
+    if (Array.isArray(v))
+        return v.some(hasOutputRef);
+    if (typeof v !== "object" || v === null)
+        return false;
+    const keys = Object.keys(v);
+    if (keys.length === 1 && keys[0] === "$output")
+        return true;
+    return Object.values(v).some(hasOutputRef);
+}
+/** Zod issues as one line: `path: message; …` (at most five). */
+function issuesText(error) {
+    const parts = error.issues
+        .slice(0, 5)
+        .map((i) => `${i.path.length === 0 ? "params" : i.path.join(".")}: ${i.message}`);
+    if (error.issues.length > 5)
+        parts.push(`and ${error.issues.length - 5} more`);
+    return parts.join("; ");
+}
+/** The operation of a `call` / `describe`; a `ToolError` when there is none (model-visible). */
+function operationOf(deps, action, id) {
+    if (id === undefined || id === "") {
+        throw new ToolError(missingText(action, "operation", "an operation id from browse or search"));
+    }
+    const op = deps.ops.get(id);
+    if (op === null)
+        throw new ToolError(unknownOperationText(id));
+    return op;
+}
+/** `params` checked against the operation's schema; a `ToolError` naming `describe` otherwise. */
+function paramsOf(op, params) {
+    const parsed = op.input.safeParse(params ?? {});
+    if (!parsed.success)
+        throw new ToolError(invalidParamsText(op.id, issuesText(parsed.error)));
+    return parsed.data;
+}
+/**
+ * The operation context of a confirmation (`confirmFor`, `summary`): the runtime's ids, never
+ * input. Nothing aborts it; it only reads.
+ */
+const confirmCtx = (ctx) => ({
+    orgId: ctx.orgId,
+    actorAccountId: ctx.accountId,
+    agentId: ctx.agentId,
+    conversationId: ctx.conversationId,
+    runId: ctx.runId,
+    signal: new AbortController().signal,
+});
+const factsCtx = (ctx) => ({
+    orgId: ctx.orgId,
+    accountId: ctx.accountId,
+    agentId: ctx.agentId,
+    conversationId: ctx.conversationId,
+    runId: ctx.runId ?? null,
+});
+export function platformTool(deps) {
+    const facts = (ctx) => deps.actor.facts(ctx);
+    async function callPolicy(raw, ctx) {
+        const input = raw;
+        if (input.action !== "call")
+            return null;
+        const id = input.operation;
+        const key = `${BUILTIN.Platform}:${id !== undefined && OPERATION_ID.test(id) ? id : "unknown"}`;
+        const deny = (denyReason) => ({
+            key,
+            policy: "deny",
+            remember: false,
+            denyReason,
+        });
+        let op;
+        let params;
+        try {
+            op = operationOf(deps, "call", id);
+            // params that cannot run are refused here, so the person is never asked to confirm them
+            params = paramsOf(op, input.params);
+        }
+        catch (e) {
+            if (e instanceof ToolError)
+                return deny(e.message);
+            throw e;
+        }
+        const verdict = availability(op, await facts(ctx));
+        if (!verdict.ok)
+            return deny(unavailableOpText(op.id, verdict.reason));
+        if (op.confirm === "read")
+            return { key, policy: "allow", remember: false };
+        // the card shows the raw input: a write must carry what it writes, not a reference to it
+        if (hasOutputRef(ctx.rawInput?.params)) {
+            return deny(outputRefText(op.id));
+        }
+        const octx = confirmCtx(ctx);
+        const [cls, summary] = await Promise.all([
+            classOf(op, params, octx),
+            summaryOf(op, params, octx),
+        ]);
+        return {
+            key,
+            policy: "ask",
+            // org / platform writes are confirmed every time (spec §6.2)
+            remember: cls === "personal",
+            summary,
+        };
+    }
+    async function run(raw, ctx) {
+        const input = raw;
+        switch (input.action) {
+            case "browse":
+                return input.domain === undefined ? browseRoot() : browseDomain(input.domain, ctx);
+            case "search":
+                return search(input.query, ctx);
+            case "describe":
+                return describe(input.operation, ctx);
+            case "call":
+                return call(input, ctx);
+            case "read":
+                return read(input.topic);
+        }
+    }
+    function browseRoot() {
+        const domains = deps.ops.domains().map((d) => ({
+            id: d.id,
+            description: d.description,
+            operations: deps.ops.inDomain(d.id).length,
+        }));
+        return json({ domains, method: PLATFORM_METHOD }, { zh: "浏览平台操作", en: "Browsed platform operations" });
+    }
+    async function browseDomain(domain, ctx) {
+        const ids = deps.ops.domains().map((d) => d.id);
+        if (!ids.includes(domain)) {
+            throw new ToolError(`Unknown domain "${domain}". Use one of: ${ids.join(", ")}; or call browse without a domain.`);
+        }
+        const f = await facts(factsCtx(ctx));
+        const ops = deps.ops.inDomain(domain);
+        return json({
+            domain,
+            operations: ops.slice(0, LIST_MAX).map((op) => line(op, f)),
+            ...(ops.length > LIST_MAX && { truncated: true, hint: "Use search to narrow the list." }),
+        }, { zh: `浏览平台操作：${domain}`, en: `Browsed platform operations: ${domain}` });
+    }
+    async function search(query, ctx) {
+        if (query === undefined || query.trim() === "") {
+            throw new ToolError(missingText("search", "query", "words to look for"));
+        }
+        const f = await facts(factsCtx(ctx));
+        const found = deps.ops.search(query, SEARCH_MAX);
+        return json({
+            query,
+            operations: found.map((op) => line(op, f)),
+            ...(found.length === 0 && {
+                hint: "Nothing matched; use other words, or browse a domain.",
+            }),
+        }, { zh: `搜索平台操作：${clip(query)}`, en: `Searched platform operations: ${clip(query)}` });
+    }
+    async function describe(id, ctx) {
+        const op = operationOf(deps, "describe", id);
+        const f = await facts(factsCtx(ctx));
+        return json({
+            id: op.id,
+            description: op.description,
+            kind: kindOf(op),
+            confirm: op.confirm,
+            inputSchema: z.toJSONSchema(op.input, { io: "input", unrepresentable: "any" }),
+            example: op.example,
+            ...(op.errors !== undefined && op.errors.length > 0 && { errors: op.errors }),
+            ...availabilityFields(availability(op, f)),
+            related: deps.ops
+                .inDomain(operationDomain(op.id))
+                .filter((o) => o.id !== op.id)
+                .map((o) => o.id),
+        }, { zh: `查看平台操作 ${op.id}`, en: `Described platform operation ${op.id}` });
+    }
+    async function call(input, ctx) {
+        const op = operationOf(deps, "call", input.operation);
+        const params = paramsOf(op, input.params);
+        // fresh facts right before running: the role may be gone since the confirmation (Review Focus 3)
+        const verdict = availability(op, await facts(factsCtx(ctx)));
+        if (!verdict.ok)
+            throw new ToolError(unavailableOpText(op.id, verdict.reason));
+        let result;
+        try {
+            result = await op.run(params, {
+                orgId: ctx.orgId,
+                actorAccountId: ctx.accountId,
+                agentId: ctx.agentId,
+                conversationId: ctx.conversationId,
+                runId: ctx.runId ?? null,
+                signal: ctx.signal,
+            });
+        }
+        catch (e) {
+            throw toToolError(e);
+        }
+        return json(asResult(result), { zh: `调用平台操作 ${op.id}`, en: `Called ${op.id}` });
+    }
+    function read(topic) {
+        if (topic === undefined || topic === "") {
+            return json({ topics: deps.docs.topics(), hint: 'Read one with action "read" and its "topic".' }, { zh: "查看平台文档目录", en: "Listed platform docs" });
+        }
+        const text = deps.docs.read(topic);
+        if (text === null) {
+            throw new ToolError(`Unknown topic "${topic}". Call read without a topic to list the topics.`);
+        }
+        return {
+            content: [{ type: "text", text }],
+            display: { summary: { zh: `阅读平台文档 ${topic}`, en: `Read platform doc ${topic}` } },
+        };
+    }
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        run,
+        callPolicy,
+        async unavailable({ orgId }) {
+            return (await deps.setting(orgId)) === "off" ? PLATFORM_UNAVAILABLE_OFF : null;
+        },
+    };
+}
+/**
+ * The class of one write: `confirmFor` when the operation has one (the target decides), else
+ * `confirm`. A `confirmFor` that throws counts as `org`: never remembered.
+ */
+async function classOf(op, params, ctx) {
+    if (op.confirmFor === undefined)
+        return op.confirm;
+    try {
+        return await op.confirmFor(params, ctx);
+    }
+    catch {
+        return "org";
+    }
+}
+/** The card summary of a write, rendered from the validated params and kernel reads. */
+async function summaryOf(op, params, ctx) {
+    try {
+        const s = await op.summary?.(params, ctx);
+        if (s !== undefined)
+            return s;
+    }
+    catch {
+        // a summary that cannot render falls back to the operation id (the card shows every param)
+    }
+    return { zh: `平台操作 ${op.id}`, en: `Platform operation ${op.id}` };
+}

package/dist/tools/builtins/sandbox/bash.js

@@ -1,7 +1,7 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { backgroundMaxSeconds, LAUNCH_EXEC_TIMEOUT_MS, launchScript, newTaskId, startedText, taskOutputPath, taskSidPath, } from "../../../background/launch.js";
 import { KILL_SESSION_TIMEOUT_MS, killSession, SID_RE } from "../../../background/session.js";
-import { clip, display, inSandbox, noSandboxError, runBudgetNote, runTimeLeftMs, sandboxBaseTimeoutMs, sandboxConversationOf, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+import { clip, display, inSandbox, mapSandboxError, noSandboxError, runBudgetNote, runTimeLeftMs, sandboxBaseTimeoutMs, sandboxConversationOf, unavailableWhenNoSandbox, withNotices, } from "./common.js";
 /** The command timeout in seconds when `timeout` is not given, at most `sandbox.limits.maxCommandSeconds`. */
 export const BASH_DEFAULT_TIMEOUT_SECONDS = 120;
 /** The longest `description` (the shell row shows it instead of the command). */
@@ -19,7 +19,8 @@ const SPEC = {
         "filesystem. The working directory is /workspace; files persist between calls in the same " +
         "conversation, but background processes may not: when the sandbox is suspended after a period " +
         "without use they can be stopped and /tmp cleared, so keep results in files under /workspace. " +
-        "Files the user attached to the conversation are under /workspace/attachments, " +
+        "Files the user attached to the conversation are copied to /workspace/attachments/<conversation>/ " +
+        "(the result names the paths), " +
         "and skill files under /skills (read-only). Each call runs in a fresh shell (no state such as " +
         "cd or environment variables carries over). The result has stdout, stderr and the exit code; " +
         "long output is saved and can be paged with ReadToolOutput. A command that runs longer than " +
@@ -143,6 +144,14 @@ async function runInBackground(deps, ctx, input) {
     const requested = input.timeout;
     const seconds = Math.max(1, Math.ceil(Math.min(requested ?? maxMs, maxMs) / 1000));
     const root = sandboxConversationOf(ctx);
+    // the environment the task will run in (the root conversation's, bound for good)
+    let environmentId;
+    try {
+        environmentId = await deps.environments.forTool(ctx.orgId, root);
+    }
+    catch (e) {
+        throw mapSandboxError(e);
+    }
     const maxTasks = cfg.sandbox.background.maxTasks;
     const id = newTaskId();
     const description = input.description ?? clip(input.command, 120);
@@ -152,6 +161,7 @@ async function runInBackground(deps, ctx, input) {
         orgId: ctx.orgId,
         conversationId: ctx.conversationId,
         sandboxConversationId: root,
+        environmentId,
         runId: ctx.runId,
         callId: ctx.callId,
         // the run's trigger account (the pipeline passes `runs.trigger_account_id` as `accountId`)
@@ -224,7 +234,7 @@ async function runInBackground(deps, ctx, input) {
             const sid = out;
             try {
                 // under the shared lease: no rebuild can come between the launch and this read
-                const instance = await currentInstance(root);
+                const instance = await currentInstance(environmentId);
                 if (instance === null)
                     throw new Error("the sandbox instance could not be read");
                 const marked = await background.markStarted(id, {

package/dist/tools/builtins/sandbox/common.d.ts

@@ -1,12 +1,13 @@
-import { type SandboxHandle, type SandboxProvider, ToolError } from "@capybara-hq/plugin-sdk";
+import { type SandboxHandle, ToolError } from "@capybara-hq/plugin-sdk";
 import type { BackgroundTaskFinisher } from "../../../background/finish.js";
 import type { BackgroundTaskStopper } from "../../../background/stop.js";
 import type { BackgroundTaskStore } from "../../../background/store.js";
 import type { KernelConfig } from "../../../config/schema.js";
 import type { AttachmentsService } from "../../../conversations/attachments.service.js";
 import type { EventLog } from "../../../conversations/event-log.js";
+import { type ConversationEnvironments } from "../../../environments/conversation-environments.js";
 import type { KernelConfigService } from "../../../infra/config/kernel-config.service.js";
-import { type SandboxService } from "../../../sandbox/sandbox.service.js";
+import { type HeldProvider, type SandboxService } from "../../../sandbox/sandbox.service.js";
 import type { StorageService } from "../../../storage/storage.service.js";
 import type { BuiltinCallContext } from "../../registry.js";
 /** 沙箱工具的依赖（都按调用时取，多副本下无进程内状态）。 */
@@ -17,6 +18,8 @@ export interface SandboxToolDeps {
      * `ifRunning`, which `TaskOutput` reads a task through.
      */
     sandbox: Pick<SandboxService, "available" | "withSandbox"> & Partial<Pick<SandboxService, "pathLease" | "currentInstance" | "ifRunning">>;
+    /** The environment a call enters: the root conversation's, checked for its owner every call. */
+    environments: Pick<ConversationEnvironments, "forTool">;
     /** Background `Bash` tasks; absent in test stubs, where `run_in_background` is refused. */
     background?: Pick<BackgroundTaskStore, "reserve" | "markStarted" | "failLaunch" | "finishStoppedLaunch" | "releaseStop" | "get" | "advanceOffset">;
     /**
@@ -28,32 +31,43 @@ export interface SandboxToolDeps {
         stopper: Pick<BackgroundTaskStopper, "stop">;
     };
     attachments: Pick<AttachmentsService, "listForConversation" | "openForConversation">;
-    storage: Pick<StorageService, "kernel" | "available">;
+    storage: Pick<StorageService, "kernel" | "deployment" | "available">;
     /** `publishChanged`: `Deliver` announces `changed: files` (UI refresh B). */
     eventLog: Pick<EventLog, "append" | "latestFileState"> & Partial<Pick<EventLog, "publishChanged">>;
     config: Pick<KernelConfigService, "get">;
 }
-/** 回调拿到的沙箱：句柄、提供方与「调用 signal + 锁丢失」合并后的 signal（每个提供方调用都传它）。 */
+/**
+ * The sandbox a callback gets: the instance handle, the provider (every `exec` carries the
+ * holder's tag and the call's actor) and the call's signal combined with the lease's (pass it to
+ * every provider call).
+ */
 export interface SandboxSession {
+    /** The environment the call runs in (path leases are taken on it). */
+    environmentId: string;
     h: SandboxHandle;
-    p: SandboxProvider;
+    p: HeldProvider;
     signal: AbortSignal;
-    /** 本次是新建 / 重建的沙箱（之前复制进去的文件都已不在）。 */
-    reset: boolean;
 }
 /** 没有沙箱提供方时「工具不可用」的原因（进提醒与调用结果）。 */
-/** 本对话第一次用沙箱。 */
-export declare const SANDBOX_STARTED_NOTICE = "Sandbox started for this conversation (first use); the working directory is /workspace.";
-/** 沙箱被重建（之前的实例已销毁或不在了）。 */
-export declare const SANDBOX_RECREATED_NOTICE = "Sandbox was recreated; previous files are gone.";
+/** This conversation's first use of its environment. */
+export declare const SANDBOX_STARTED_NOTICE = "Environment started (first use in this conversation); the working directory is /workspace, shared with the environment's other conversations.";
+/** A new instance came up on the environment's kept files. */
+export declare const SANDBOX_RESTARTED_NOTICE = "The environment's instance was restarted; files are kept, running processes and /tmp are gone.";
 /** 没有沙箱提供方时「工具不可用」的原因（进提醒，内核在后面补句号）：与调用时的错误同一句话。 */
 export declare const SANDBOX_UNAVAILABLE_REASON: string;
 /** The error of a sandbox call in a deployment without a sandbox provider. */
 export declare function noSandboxError(): ToolError;
-/** 沙箱里附件所在目录。 */
-export declare const ATTACHMENTS_DIR = "/workspace/attachments";
-/** 已同步附件的标记文件：`{ <附件 id>: <文件名> }`。 */
-export declare const SYNC_MARKER = "/workspace/attachments/.capybara-sync.json";
+/** The directory of attachments in the environment (each conversation has a subdirectory). */
+export declare const ATTACHMENTS_ROOT = "/workspace/attachments";
+/**
+ * One conversation's attachment directory: the first 12 hex digits of the root conversation's
+ * UUID, so conversations sharing an environment do not overwrite each other's files.
+ */
+export declare const attachmentsDir: (rootConversationId: string) => string;
+/** The conversation's marker of synced attachments: `{ <attachment id>: <file name> }`. */
+export declare const syncMarkerPath: (rootConversationId: string) => string;
+/** Whether a path, or a Grep output line starting with one, belongs to a sync marker (hidden from Glob / Grep). */
+export declare const isSyncMarkerEntry: (pathOrLine: string) => boolean;
 /** 附件文件名的上限（UTF-8 字节，常见文件系统单个文件名上限 255 字节，留出 `-N` 后缀的余量）。 */
 export declare const ATTACHMENT_NAME_MAX_BYTES = 200;
 /**
@@ -115,23 +129,28 @@ export declare function assignAttachmentNames(items: readonly {
 /** 沙箱服务的错误 → 给模型的可执行说明；其余原样抛出（管线按「工具失败」处理）。 */
 export declare function mapSandboxError(e: unknown): unknown;
 /**
- * 在本对话的沙箱上执行 `fn`（`SandboxService.withSandbox`：懒创建、恢复、重建）：先同步附件，
- * 再执行；返回结果与要加在结果开头的状态说明（首次使用 / 重建 / 新复制的附件）。
- * `withSandbox` 遇到实例不在时会重建并再调用一次回调，说明按最后一次调用的为准。
+ * Runs `fn` in the environment of the call's conversation (a sub-agent: its root's): resolves and
+ * checks the environment for the conversation's owner (binding an unbound conversation to the
+ * owner's default first), then `SandboxService.withSandbox` (the instance created, resumed or
+ * rebuilt on the kept files as needed, every `exec` carrying the call's actor). Attachments are
+ * synced first. Returns the value and the notices to put before the result (first use, a new
+ * instance, newly copied attachments). When `withSandbox` rebuilds a gone instance and calls
+ * `fn` again, the notices are the last call's.
  */
 export declare function inSandbox<T>(deps: SandboxToolDeps, ctx: BuiltinCallContext, fn: (s: SandboxSession) => Promise<T>): Promise<{
     value: T;
     notices: string[];
 }>;
-/** The conversation whose sandbox a call uses (the parent's for a sub-agent). */
+/** The conversation whose environment a call uses (the root conversation's for a sub-agent). */
 export declare const sandboxConversationOf: (ctx: BuiltinCallContext) => string;
 /**
- * Runs `fn` under the per-path lease of `path` in the call's sandbox (spec §10.4: the kernel's own
- * read-modify-write of one file never loses another holder's update). `fn` gets `signal` combined
- * with the path lease's: pass it to every provider call, so a lost path lease stops the write.
- * Without `pathLease` (test stubs) it just runs `fn` with `signal`.
+ * Runs `fn` under the per-path lease of `path` in the session's environment (spec §10.4: the
+ * kernel's own read-modify-write of one file never loses another holder's update, from any
+ * conversation sharing the environment). `fn` gets `signal` combined with the path lease's: pass
+ * it to every provider call, so a lost path lease stops the write. Without `pathLease` (test
+ * stubs) it just runs `fn` with `signal`.
  */
-export declare function withPathLease<T>(deps: Pick<SandboxToolDeps, "sandbox">, ctx: BuiltinCallContext, path: string, signal: AbortSignal, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+export declare function withPathLease<T>(deps: Pick<SandboxToolDeps, "sandbox">, s: Pick<SandboxSession, "environmentId">, path: string, signal: AbortSignal, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
 /** 本部署是否有沙箱：没有时返回「不可用」原因（注册表据此把沙箱工具报为不可用）。 */
 export declare const unavailableWhenNoSandbox: (deps: Pick<SandboxToolDeps, "sandbox">) => (_ctx?: {
     orgId: string;