@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/plugins/mcp/stdio.d.ts

@@ -0,0 +1,49 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { type SpawnResult } from '../../sys/spawn.js';
+export type StdioServerOptions = {
+    readonly server: string;
+    readonly command: readonly [string, ...string[]];
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    /** The owner: aborting it stops the server's process group within the bound. */
+    readonly signal: AbortSignal;
+    readonly killGraceMs?: number;
+};
+/**
+ * The SDK's `Transport` over a stdio server spawned through `sys/spawn`, so the server and
+ * everything it starts lead a process group that never outlives lagent. The SDK's own stdio
+ * transport spawns outside that containment.
+ *
+ * stdout carries newline-delimited JSON-RPC and nothing else. stderr is diagnostics: it is read
+ * from the start, since an unread pipe would block the server, and only a bounded tail is kept,
+ * for the host's errors and the debug log.
+ */
+export declare class ContainedStdioTransport implements Transport {
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: <T extends JSONRPCMessage>(message: T) => void;
+    private spawned;
+    private readonly buffer;
+    private stderr;
+    private exit;
+    private closed;
+    /** `close` came before the process existed: the process is stopped as soon as it does. */
+    private closedEarly;
+    private readonly options;
+    constructor(options: StdioServerOptions);
+    /** The server's pid, which is also its process group's id, once started. */
+    get pid(): number | undefined;
+    /** The last of what the server wrote to stderr. */
+    get stderrTail(): string;
+    /** How the server's process ended, once it has. */
+    get exited(): SpawnResult | null;
+    start(): Promise<void>;
+    private receive;
+    send(message: JSONRPCMessage): Promise<void>;
+    /**
+     * The spec's stdio shutdown: close the server's input, give it one grace period to exit, then
+     * stop its whole group, SIGTERM then SIGKILL, within `sys/spawn`'s bound.
+     */
+    close(): Promise<void>;
+}

package/dist/plugins/mcp/tools.d.ts

@@ -0,0 +1,41 @@
+import type { Tool } from '../../loop/index.js';
+import type { InterruptionPolicy } from '../../records/journal.js';
+import type { CatalogEntry } from './catalog.js';
+import type { McpConfig } from './config.js';
+import { type Generation } from './connection.js';
+import type { CallSlots } from './slots.js';
+/**
+ * The `_meta` key carrying a call's durable identity: the thread id, an opaque identifier with no
+ * meaning outside lagent's journal, and the `tool/call` sequence. Stable across a re-dispatch after
+ * a crash, so a server that chooses to can deduplicate; servers that do not know it ignore it.
+ */
+export declare const CALL_META_KEY = "work.leuduan.lagent/call";
+/** Told with the first result after a new session. */
+export declare const SESSION_RESET_NOTE = "The connection to this MCP server was re-established; any session state the server held may have been reset.";
+/** What a tool needs from the mount that published it. */
+export interface McpToolHost {
+    readonly server: string;
+    readonly config: Pick<McpConfig, 'maxCallSeconds' | 'callTimeoutSeconds' | 'maxContentBytes' | 'onInterrupted'>;
+    readonly slots: CallSlots;
+    /** The live generation, reconnecting once first if the last one went away. */
+    ready(signal: AbortSignal): Promise<Generation>;
+    /** The current catalog's entry under a lagent name. */
+    entry(name: string): CatalogEntry | undefined;
+    /** The note owed to the first result of `generation`, once. */
+    takeSessionNote(generation: Generation): string | null;
+    /** Ends a generation whose session the server no longer has. */
+    invalidate(generation: Generation): void;
+}
+/**
+ * What a re-dispatch may do with a call to `entry` after an interruption, by the mount's
+ * `onInterrupted`: `'report'` for every tool, the listed remote names for `{ rerun }`, and for
+ * `'annotations'` the server's own `readOnlyHint` or `idempotentHint`, trusted only because the
+ * mount asked for that.
+ */
+export declare function interruptionPolicyOf(onInterrupted: McpConfig['onInterrupted'], entry: Pick<CatalogEntry, 'remoteName' | 'definition'>): InterruptionPolicy;
+/**
+ * One MCP tool as a lagent tool, bound to the definition it was published with. Arguments go to
+ * the server unchanged: validating them is the server's job. The mount's `onInterrupted` decides
+ * what a re-dispatch may do; the server's annotations count only when the mount says so.
+ */
+export declare const mcpTool: (host: McpToolHost, entry: CatalogEntry) => Tool;

package/dist/plugins/mcp/version.d.ts

@@ -0,0 +1,2 @@
+/** The package version, for client/server identification strings. */
+export declare function lagentVersion(): string;

package/dist/plugins/routeNotice.d.ts

@@ -0,0 +1,22 @@
+import type { Plugin } from '@leuduan/cordis';
+import { type ModelRoute } from '../llm/provider.js';
+/**
+ * Tells an agent the route it runs on: provider, model and thinking effort.
+ *
+ * Told as a conversation message at the next model step already due whenever the turn's route
+ * differs from the latest notice the model can still see: on its first step, after a person
+ * switches its model, when a turn falls back to another provider or returns from one, and after a
+ * replacement took the notice that said it off the surface. The route is the one the turn pinned,
+ * which request middleware cannot change, so it names what lagent sends. A step whose route did not
+ * resolve is told nothing; its model call fails anyway. A fork inherits what its source was told and
+ * runs on its source's route, so it is told nothing unless the route moved.
+ *
+ * Not a prompt section: the recorded prompt must not change while the thread lives, and the route
+ * does. Mounted on the root it tells every thread; mounted through `thread.ctx` it tells that thread
+ * only.
+ */
+export declare const routeNotice: Plugin.Object<undefined>;
+/** What a thread is told: its route, and the one it replaces when the model can still see another. */
+export declare function renderRouteNotice(route: ModelRoute, told: ModelRoute | null): string;
+/** A route as a model reads it; an effort of `null` is the provider's default. */
+export declare function renderRoute(route: ModelRoute): string;

package/dist/plugins/routeNotice.js

@@ -0,0 +1 @@
+import{a,b,c}from"../chunks/OCBPT7KE.js";import"../chunks/6FRNHMCV.js";import"../chunks/CUK7CGC7.js";import"../chunks/BPRCULZH.js";import"../chunks/DDANMY45.js";import"../chunks/BBCW2FZK.js";import"../chunks/MMNNZCBO.js";import"../chunks/G44LG6VL.js";import"../chunks/D4PQP5MA.js";export{c as renderRoute,b as renderRouteNotice,a as routeNotice};

package/dist/plugins/sandbox/absent.d.ts

@@ -0,0 +1,33 @@
+import type { Plugin } from '@leuduan/cordis';
+import { z } from 'zod';
+declare const AbsentConfigSchema: z.ZodObject<{
+    drainTimeoutMs: z.ZodNumber;
+}, z.core.$strict>;
+export type SandboxAbsentConfig = z.input<typeof AbsentConfigSchema>;
+/**
+ * For a host that records sandbox modes but started without the sandbox. A process with no launch
+ * handler would run every command plain, so a conversation recorded as confined would run unconfined
+ * silently after such a restart. This is the confinement handler of core's `ctx.confinement` for that
+ * host, which is what makes the refusal cover every caller of the seam, `commands`, the search tools
+ * and a host calling `ctx.confinement` directly alike: an operation for a conversation recorded as
+ * confined is refused with a message for the model, and a launch for one recorded as unconfined, or
+ * with no mode at all, runs plain (`/bin/sh -c` for shell text, the argv itself otherwise) with
+ * provenance that says so (`unconfined`, under this plugin's own launcher),
+ * which a host's display marks. The model is told through the sandbox's notice: the unavailable
+ * guidance when confined, and the lift a restart may have left owed otherwise.
+ *
+ * The refusal happens at the operation's first use, after any confirmation the tool call needed, so
+ * a call a person approved can still be refused: rare, since the notice says so at the first step.
+ * It does not cover what spawns outside the seam: MCP stdio servers and lagent's own spawns.
+ *
+ * The recorded mode is read once, at the operation's first use, from the journal's fold; core holds
+ * the histories it is decided from for the snapshot. A thread the journal does not hold, a caller
+ * chain that does not reach its conversation root and a mode row this build cannot read refuse the
+ * operation with that error, never allow it.
+ *
+ * Mount it unscoped, after `core` and before threads start, so a failed composition is refused before
+ * recovery. It excludes `sandbox` in either mount order. Disposing it releases its handler, which
+ * stops every command it let run, within `drainTimeoutMs`.
+ */
+export declare const sandboxAbsent: Plugin.Object<SandboxAbsentConfig>;
+export {};

package/dist/plugins/sandbox/client.d.ts

@@ -0,0 +1,39 @@
+import type { WorkerMessage, WorkerValues } from './protocol.js';
+/**
+ * The main thread's end of the sandbox worker: it owns the thread and every request in flight. A
+ * request has an id and a deadline; a worker that errors or exits rejects every request at once and
+ * tells `onDeath` once, and a reply that arrives for a request already settled is dropped. Nothing
+ * here knows what the messages mean.
+ */
+export declare class WorkerClient {
+    private readonly worker;
+    private readonly pending;
+    private nextId;
+    private ended;
+    private closing;
+    private readonly onDeath;
+    /**
+     * Starts the worker with exactly `env`, which it never inherits. `onDeath` runs once when the
+     * worker ends other than through {@link terminate}.
+     */
+    constructor(entry: URL | string, env: Record<string, string>, onDeath: (error: Error) => void);
+    get alive(): boolean;
+    /**
+     * Sends `message` and resolves with its reply. Rejects at `timeoutMs`, when `signal` aborts, or
+     * when the worker ends; the first two also ask the worker to abandon the work.
+     */
+    request<M extends WorkerMessage & {
+        type: keyof WorkerValues;
+    }>(message: M, options: {
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }): Promise<WorkerValues[M['type']]>;
+    /** Ends the worker on purpose: pending requests reject, and `onDeath` is not told. */
+    terminate(): Promise<void>;
+    /** Lets the process exit while the worker still runs: for a worker kept after a failed drain. */
+    unref(): void;
+    private send;
+    private settle;
+    private end;
+    private rejectAll;
+}

package/dist/plugins/sandbox/files.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What the sandbox keeps on disk under its temporary root, which no command may write: the
+ * worker's private directory and the per-key scratch directories. Created by the host, never by a
+ * confined process, and never through a link.
+ */
+/** The directory the worker runs in: sandbox-runtime's socket files and the published Java agent. */
+export declare const privateDirectory: (tmpRoot: string) => string;
+/** A key's temporary directory. The hash gives every key one safe, fixed-length segment of its own. */
+export declare const scratchPath: (tmpRoot: string, key: string) => string;
+/** `<tmpRoot>` and `<tmpRoot>/.srt`, created. */
+export declare function ensurePrivateDirectory(tmpRoot: string): string;
+/** The scratch directory of `key`, created. */
+export declare function ensureScratchDirectory(tmpRoot: string, key: string): string;
+/**
+ * Removes the socket files sandbox-runtime left in `directory` for host processes that are gone,
+ * which a SIGKILL leaves behind, and nothing else. Returns what it removed.
+ */
+export declare function removeDeadSockets(directory: string): string[];
+/**
+ * Publishes the Java agent into `directory` as `srt-proxy-agent-<sha256>.jar`, the one a JVM in the
+ * sandbox loads. Several hosts may share a temporary root, so a name is never rewritten: the bytes
+ * go to a temporary name and are linked into place, which fails rather than replace, and a file
+ * already there is reused only after its digest checks.
+ */
+export declare function publishJar(directory: string, source: string): {
+    path: string;
+    sha256: string;
+};

package/dist/plugins/sandbox/index.d.ts

@@ -0,0 +1,52 @@
+import type { Plugin } from '@leuduan/cordis';
+import { type SandboxConfigInput } from './service.js';
+export { sandboxAbsent, type SandboxAbsentConfig } from './absent.js';
+export { sandboxRecorded, sandboxRecordedOn, type SandboxMode } from './mode.js';
+export { SandboxConfigSchema, type SandboxConfigInput, type SandboxHealth, type SandboxService } from './service.js';
+/**
+ * An optional OS sandbox for `run_command` and `start_command`, through Anthropic's sandbox-runtime
+ * (`@anthropic-ai/sandbox-runtime`, an optional peer dependency: only the worker module loads it).
+ * Mounting `sandbox` registers it as the confinement handler of core's `ctx.confinement`, so everything
+ * `commands` launches afterwards goes through it, and each confined launch is limited to writing its thread's working directory, the host's
+ * extra roots and a per-thread temporary directory, and, in `allowlist` network mode, to reaching the
+ * host's allowed domains (`unrestricted` leaves the network open: only the filesystem rules bind). A
+ * host mounts it before anything launches: once it is registered, no launch runs without it, though a
+ * conversation set to run unconfined launches plain through it.
+ *
+ * Each conversation is confined or unconfined, as its durable mode says: `ctx.sandbox.opening(mode)`
+ * records the first choice in the write that creates it, `ctx.sandbox.setMode` switches it, and
+ * `ctx.sandbox.mode` is the one effective value, which the host's `unconfined: 'refused'` forces to
+ * `confined`. `sandboxRecorded` reads what the journal says, mounted sandbox or not. A host that
+ * records modes but starts without the sandbox mounts `sandboxAbsent` instead: the two exclude each
+ * other.
+ *
+ * sandbox-runtime runs on a worker thread of the host, started once per process. The host says
+ * where the worker is (`sandboxWorker` from `dist`) and which Java agent to publish
+ * (`srtJavaAgentJar()` from `node_modules`); a compiled host embeds both itself.
+ *
+ * ```ts
+ * await root.plugin(sandbox, {
+ *   worker: sandboxWorker,
+ *   searchPath: '/usr/bin:/bin:/usr/sbin:/sbin',
+ *   tmpRoot,
+ *   javaAgentJar: srtJavaAgentJar(),
+ *   unconfined: 'allowed',
+ *   filesystem,
+ *   network: { mode: 'allowlist', allowedDomains: ['registry.npmjs.org'], deniedDomains: [], parentProxy: 'none' },
+ * })
+ * await root.plugin(commands, { environment })
+ * ```
+ *
+ * One filesystem policy per conversation, enforced two ways: srt confines the processes `commands` and
+ * the search tools launch, and the same policy is checked in process for the file tools and the readers
+ * of instruction files and skills, through the confinement operation's file facade. Other spawns are
+ * unchanged. macOS only for now.
+ */
+export declare const sandbox: Plugin.Constructor<SandboxConfigInput>;
+/** The worker entry built beside this module, for a host that runs lagent from `dist`. */
+export declare const sandboxWorker: URL;
+/**
+ * The JVM proxy agent sandbox-runtime's package ships, for a host that runs from `node_modules`.
+ * Resolved when called, so a host without the package fails here and not on import.
+ */
+export declare function srtJavaAgentJar(): string;

package/dist/plugins/sandbox/index.js

@@ -0,0 +1,4 @@
+import{a as p}from"../../chunks/VYMT4TXD.js";import{b as D,c as R,d as B,e as te}from"../../chunks/6DRCKZ2C.js";import{d as ne}from"../../chunks/7LI64H5X.js";import"../../chunks/3UMZMPWW.js";import{a as ie,b as ae}from"../../chunks/DDZ7YF26.js";import{d as N}from"../../chunks/S34ZA2R6.js";import{b as re,c as oe,e as se}from"../../chunks/6FRNHMCV.js";import"../../chunks/CUK7CGC7.js";import"../../chunks/BPRCULZH.js";import{d as E}from"../../chunks/DDANMY45.js";import{c as v}from"../../chunks/BBCW2FZK.js";import"../../chunks/MMNNZCBO.js";import"../../chunks/G44LG6VL.js";import"../../chunks/D4PQP5MA.js";import{createRequire as bn}from"node:module";import{dirname as vn,join as En}from"node:path";import{randomUUID as dn}from"node:crypto";import{homedir as hn}from"node:os";import{isAbsolute as U}from"node:path";import{Service as Pe}from"@leuduan/cordis";import{z as d}from"zod";import{Worker as He}from"node:worker_threads";var O=class{worker;pending=new Map;nextId=1;ended=null;closing=!1;onDeath;constructor(e,n,o){this.onDeath=o,this.worker=new He(e,{env:n}),this.worker.on("message",r=>this.settle(r)),this.worker.on("error",r=>this.end(new Error(`The sandbox worker failed: ${r.message}`))),this.worker.on("exit",r=>this.end(new Error(`The sandbox worker exited with code ${r}`)))}get alive(){return this.ended===null&&!this.closing}request(e,n){if(this.ended!==null)return Promise.reject(this.ended);if(this.closing)return Promise.reject(new Error("The sandbox worker is shutting down"));let{signal:o}=n;if(o?.aborted)return Promise.reject(o.reason instanceof Error?o.reason:new Error("aborted"));let r=this.nextId++;return new Promise((s,i)=>{let a=m=>{this.pending.delete(r)&&(clearTimeout(c),l(),e.type==="wrap"&&this.send({type:"cancel",id:r}),i(m))},h=()=>a(o?.reason instanceof Error?o.reason:new Error("aborted")),c=setTimeout(()=>a(new Error(`The sandbox worker did not answer ${e.type} within ${n.timeoutMs} ms`)),n.timeoutMs),l=()=>o?.removeEventListener("abort",h);o?.addEventListener("abort",h,{once:!0}),this.pending.set(r,{resolve:s,reject:i,timer:c,cleanup:l}),this.send({...e,id:r})})}async terminate(){this.closing=!0,this.rejectAll(new Error("The sandbox worker is shutting down")),await this.worker.terminate()}unref(){this.worker.unref()}send(e){try{this.worker.postMessage(e)}catch(n){this.end(new Error(`The sandbox worker could not be reached: ${n instanceof Error?n.message:n}`))}}settle(e){let n=this.pending.get(e.id);n!==void 0&&(this.pending.delete(e.id),clearTimeout(n.timer),n.cleanup(),e.ok?n.resolve(e.value):n.reject(new Error(e.error)))}end(e){this.ended===null&&(this.ended=e,this.rejectAll(e),this.closing||this.onDeath(e))}rejectAll(e){let n=[...this.pending.values()];this.pending.clear();for(let o of n)clearTimeout(o.timer),o.cleanup(),o.reject(e)}};import{createHash as I,randomUUID as Ue}from"node:crypto";import{existsSync as We,linkSync as Be,lstatSync as de,mkdirSync as he,readdirSync as Ie,readFileSync as ce,unlinkSync as ue,writeFileSync as Fe}from"node:fs";import{join as T}from"node:path";var le=t=>T(t,".srt"),G=(t,e)=>T(t,"scratch",I("sha256").update(e).digest("hex"));function F(t){try{he(t,{mode:448})}catch(n){if(!E(n,"EEXIST"))throw n}let e=de(t);if(!e.isDirectory()||e.uid!==process.getuid?.())throw new Error(`${t} is not a directory owned by this user`)}function me(t){return he(t,{recursive:!0,mode:448}),F(le(t)),le(t)}function X(t,e){F(T(t,"scratch"));let n=G(t,e);return F(n),n}function fe(t){let e=[];for(let n of Ie(t)){let o=/^srt-mux-(\d+)-[0-9a-z]+\.sock$/.exec(n);if(!(o===null||Ge(Number(o[1]))))try{ue(T(t,n)),e.push(n)}catch{}}return e}function Ge(t){if(t===process.pid)return!0;try{return process.kill(t,0),!0}catch(e){return E(e,"EPERM")}}function pe(t,e){let n=ce(e),o=I("sha256").update(n).digest("hex"),r=T(t,`srt-proxy-agent-${o}.jar`);if(!We(r)){let i=T(t,`.publish-${Ue()}.tmp`);Fe(i,n,{flag:"wx",mode:292});try{Be(i,r)}catch(a){if(!E(a,"EEXIST"))throw a}finally{ue(i)}}if(!de(r).isFile()||I("sha256").update(ce(r)).digest("hex")!==o)throw new Error(`${r} exists and is not the Java agent it is named for`);return{path:r,sha256:o}}import{createHash as ge}from"node:crypto";import{existsSync as z,lstatSync as J,opendirSync as Xe,realpathSync as ye,statSync as Je}from"node:fs";import{basename as xe,dirname as A,isAbsolute as be,join as g,relative as ze,resolve as S,sep as Ve}from"node:path";var Ye=/^(LD_.*|DYLD_.*|BASH_ENV|ENV|SHELLOPTS|BASHOPTS|BASH_FUNC_.*)$/;function ve(t){let e=Object.keys(t).filter(n=>Ye.test(n));if(e.length>0)throw new Error(`The command sandbox refuses an environment that sets ${e.join(", ")}: they run code before the sandbox holds`)}var V=128*1024;function k(t){let e=S(t),n=[];for(;!z(e)&&A(e)!==e;)n.unshift(xe(e)),e=A(e);return g(ye.native(e),...n)}var Ee=t=>({path:t,literal:!0}),Ze=/[*?[\]]/,Ke=["__GLOBSTAR_SLASH__","__GLOBSTAR__"];function Te(t){if(!be(t))throw new Error(`The command sandbox needs an absolute root, not ${t}`);let e=k(t);if(Ze.test(e)||Ke.some(n=>e.includes(n)))throw new Error(`The command sandbox refuses ${e} as a root: its name holds glob characters, which sandbox-runtime would read as a pattern`);return e}var Qe=[".gitconfig",".gitmodules",".bashrc",".bash_profile",".zshrc",".zprofile",".profile",".ripgreprc",".mcp.json",".vscode",".idea",".claude/commands",".claude/agents",".git/hooks",".git/config"];function qe(t,e){let n=[];for(let o of e)n.push(Ee(g(t,o)),`${t}/**/${o}`,`${t}/**/${o}/**`);return n}var en=["env","which","log","/bin/sh","/usr/bin/sandbox-exec"];function Ae(t){let e=t.split(":"),n=en.flatMap(o=>(o.startsWith("/")?[o]:e.map(r=>g(r,o))).filter(r=>z(r)).map(r=>ye.native(r)));return[...e,...n]}function Y(t,e,n){let o=(r,s)=>p(r,s)||p(s,r);for(let r of t){let s=e.find(i=>o(i,r));if(s!==void 0)throw new Error(`The command sandbox refuses to let commands write ${r}: it overlaps ${s}, which the sandbox runs before confinement`);if(o(n,r))throw new Error(`The command sandbox refuses to let commands write ${r}: it overlaps the temporary root`)}}var Z=(t,e)=>({spelling:t,canonical:e,foldsCase:tn(e)}),f=t=>Z(t,k(t)),nn=t=>t.replace(/[a-zA-Z]/g,e=>e===e.toLowerCase()?e.toUpperCase():e.toLowerCase());function tn(t,e=n=>J(n).dev){let n=S(t);for(;!z(n)&&A(n)!==n;)n=A(n);let o;try{Je(n).isDirectory()||(n=A(n)),o=e(n)}catch{return null}let r=(s,i)=>{let a=nn(i);if(a===i)return null;try{if(e(g(s,i))!==o)return null;let h=J(g(s,i)),c;try{c=J(g(s,a))}catch(l){return E(l,"ENOENT")?!1:null}return e(g(s,a))===o?h.ino===c.ino:null}catch{return null}};for(let s=n;;){let i=[];try{let c=Xe(s);try{for(let l=c.readSync();l!==null&&i.length<64;l=c.readSync())i.push(l.name)}finally{c.closeSync()}}catch{}for(let c of i){let l=r(s,c);if(l!==null)return l}let a=A(s);if(a===s)return null;try{if(e(a)!==o)return null}catch{return null}let h=r(a,xe(s));if(h!==null)return h;s=a}}function Se(t,e,n){return{writable:[e,...t.allowWrite,n],denyWrite:[...t.denyWrite,...t.conveniences,f("/tmp/claude"),f("/private/tmp/claude"),t.privateDirectory],denyRead:t.denyRead,protected:{root:e,suffixes:Qe}}}function ke(t){let e=n=>[...new Set(n.map(o=>o.canonical))].map(Ee);return{allowWrite:e(t.writable),denyWrite:[...e(t.denyWrite),...qe(t.protected.root.canonical,t.protected.suffixes)],denyRead:e(t.denyRead)}}var we={allowed:!0};function $e(t){let e=(r,s,i)=>{let a=s?r.normalize("NFC"):r;return i?a.toLowerCase():a},n=(r,s,i)=>{let a=i?s.foldsCase!==!1:s.foldsCase===!0,h=e(r,i,a);return p(h,e(S(s.spelling),i,a))||p(h,e(s.canonical,i,a))},o=r=>{let{root:s,suffixes:i}=t.protected,a=s.foldsCase!==!1;for(let h of[S(s.spelling),s.canonical]){let c={path:e(r,!0,a),base:e(h,!0,a)};if(!p(c.path,c.base))continue;let l=ze(c.base,c.path).split(Ve),m=i.find(x=>{let b=e(x,!0,a).split("/");return l.some((ee,w)=>b.every((_,u)=>l[w+u]===_))});if(m!==void 0)return m}return null};return{identity:ge("sha256").update(v(t.denyRead)).digest("hex"),check(r,s){if(!be(r))throw new Error(`The file policy judges absolute paths, not ${r}`);let i=S(r);if(s==="read"){let c=t.denyRead.find(l=>n(i,l,!0));return c===void 0?we:{allowed:!1,reason:`${r} is in ${c.spelling}, which this conversation may not read`}}if(!t.writable.some(c=>n(i,c,!1)))return{allowed:!1,reason:`${r} is outside the directories this conversation may write`};let a=t.denyWrite.find(c=>n(i,c,!0));if(a!==void 0)return{allowed:!1,reason:`${r} is in ${a.spelling}, which this conversation may not write`};let h=o(i);return h===null?we:{allowed:!1,reason:`${r} is protected (${h}) and cannot be written here`}}}}var K=['if [ -n "${LAGENT_SANDBOX_PATH+x}" ]; then PATH=$LAGENT_SANDBOX_PATH; export PATH; else unset PATH; fi',"TMPDIR=$LAGENT_SANDBOX_TMPDIR; export TMPDIR",'set -- "$LAGENT_SANDBOX_COMMAND"',"unset LAGENT_SANDBOX_PATH LAGENT_SANDBOX_TMPDIR LAGENT_SANDBOX_COMMAND",'exec /bin/sh -c "$1"'].join("; ");function _e(t){return"shell"in t?t.shell:`exec ${t.argv.map(e=>`'${e.replaceAll("'","'\\''")}'`).join(" ")}`}function De(t,e,n,o){let{PATH:r,...s}=t;return{...s,PATH:e,LAGENT_SANDBOX_TMPDIR:n,LAGENT_SANDBOX_COMMAND:o,...r===void 0?{}:{LAGENT_SANDBOX_PATH:r}}}var P="lagent-srt",rn="5",Re=t=>`${P}/${rn} sandbox-runtime/${t}`;function Ne(t){return`sha256:${ge("sha256").update(v({...t,bootstrap:K})).digest("hex")}`}function Oe(t){let e=t.filesystem.allowWrite.length===0?"":`, in ${t.filesystem.allowWrite.join(", ")}`,{network:n}=t,o=n.mode==="unrestricted"?"They have unrestricted network access.":n.allowedDomains.length===0?"They have no network access.":`They reach the network only through a proxy, and only these hosts: ${n.allowedDomains.join(", ")}; any other host is refused with HTTP 403. Tools that ignore HTTP_PROXY cannot connect. Refused requests are usually, not always, listed after the command's output.`;return[`run_command and start_command run in an OS sandbox. The file tools (read_file, list_dir, edit_files, rg_search, rg_files) are checked against the same rules, and name the rule when they refuse a path. Commands and edits can write only inside the conversation's working directory${e}, and in $TMPDIR. A command's refused write fails with "Operation not permitted", which is all it reports. Inside the working directory, git hooks, .git/config, shell startup files and editor settings cannot be written, by a command or by an edit.`,o,"A refusal is the sandbox, not a fault to work around: say what you needed instead."].join(" ")}import{z as Q}from"zod";var y=ae({name:"lagent:sandbox",authority:"conversation",initial:"confined",modes:["confined","unconfined"]});function C(t,e){if(t.journal.summary(e)===void 0)throw new Error(`Unknown thread: ${e}`);return y.recorded(t.journal,y.authorityOf(t,e))}var on=(t,e)=>y.recorded(t,e),sn=Q.strictObject({mode:Q.enum(["confined","unconfined"]),guidance:Q.string().nullable()}),an=re({plugin:"lagent:sandbox",kind:"notice",version:1,schema:sn}),cn="The sandbox is off: commands you start from now on run with the user's full permissions and network, and the file tools are no longer limited; commands already preparing or running keep the confinement they started with.",ln="Commands you start from now on are sandboxed, and the file tools follow the same rules; commands already preparing or running keep how they were launched.",q="The sandbox is unavailable on this host: commands, searches and file access are refused for this conversation.";function M(t,e){se(t,{event:an,agents:"all",rank:1,current:n=>{try{return e(n.threadId)}catch(o){if(o instanceof ie)return;throw o}},render:(n,o,{notices:r})=>{let s=oe(r)?.value??null;return n.mode==="unconfined"?(o??(s?.mode==="confined"?s:null))?.mode==="confined"?cn:null:n.guidance===null?null:n.guidance===q?n.guidance:`${ln} ${n.guidance}`}})}var j=new WeakMap;function L(t,e){let n=t.reflect.target,o=j.get(n);if(o!==void 0)throw new Error(`${e} cannot mount: ${o} already owns this application's sandbox, and the two exclude each other`);j.set(n,e),t.effect(()=>()=>{j.get(n)===e&&j.delete(n)})}var $=d.string().refine(U,{message:"Expected an absolute path"}),je=d.url({protocol:/^https?$/}).refine(t=>new URL(t).username===""&&new URL(t).password==="",{message:"A parent proxy URL carrying credentials is not supported"}),Me=d.strictObject({worker:d.union([d.instanceof(URL),d.string().min(1)]),searchPath:d.string().refine(t=>t.split(":").every(U),{message:"Every searchPath entry must be absolute"}),tmpRoot:$,javaAgentJar:$,unconfined:d.enum(["allowed","refused"]),filesystem:d.strictObject({allowWrite:d.array($),denyRead:d.array($),denyWrite:d.array($)}),network:d.discriminatedUnion("mode",[d.strictObject({mode:d.literal("allowlist"),allowedDomains:d.array(d.string().min(1)),deniedDomains:d.array(d.string().min(1)),parentProxy:d.union([d.literal("none"),d.strictObject({http:je.optional(),https:je.optional(),noProxy:d.string().optional()})])}),d.strictObject({mode:d.literal("unrestricted")})]),drainTimeoutMs:d.number().int().positive().default(2e4)});function un(t){if(t.mode==="unrestricted")return{deniedDomains:[]};let{parentProxy:e}=t;return{allowedDomains:t.allowedDomains,deniedDomains:t.deniedDomains,...e==="none"?{}:{parentProxy:e}}}function mn(t,e,n){return t==="allowlist"?e.isCopy?[]:[`sandbox-runtime does not advertise the Java agent copy ${n}`]:e.flags===0?[]:["sandbox-runtime advertises a Java agent although the network is unrestricted"]}var H=3e4,fn=15e3,pn=5e3,Ce=!1,W=class extends Pe{static inject=["confinement","journal","threads"];guidance;config;state="new";failure=null;admitting=!0;client=null;host=null;handle;releasing=null;constructor(e,n){super(e,"sandbox"),N(e,"sandbox"),this.config=Me.parse(n),this.guidance=Oe(this.config),L(e,"sandbox"),M(e,o=>{let r=this.mode(o);return{mode:r,guidance:r==="confined"?this.guidance:null}}),this.handle=e.confinement.handle(this),e.fiber.beforeUnload(()=>this.closeAndRelease())}async[Pe.init](){try{await this.start()}catch(e){this.state="failed",this.admitting=!1;let n=this.releaseHandle();throw this.announceFailure(),await n,await this.client?.terminate(),this.client=null,e}return()=>this.release()}get unconfined(){return this.config.unconfined}get health(){return this.state==="ready"&&this.admitting?"ready":"failed"}mode(e){return this.config.unconfined==="refused"?"confined":y.of(this.ctx,e)}async setMode(e,n){this.refuseGated(n);let o=this.ctx.journal.summary(e);if(o===void 0)throw new Error(`Unknown thread: ${e}`);if(o.origin!==null)throw new Error(`Thread ${e} is in its conversation's sandbox mode`);await y.set(this.ctx,e,n),this.handle.changed()}opening(e){return this.refuseGated(e),y.opening(e)}refuseGated(e){if(e==="unconfined"&&this.config.unconfined==="refused")throw new Error("This host refuses unconfined conversations: commands, searches and file access stay confined")}async snapshot(e){this.requireOpen();let n=this.ctx.journal.summary(e);if(n===void 0)throw new Error(`The sandbox cannot serve unknown thread ${e}`);if(this.mode(e)==="unconfined")return{files:null,prepare:s=>this.prepare(null,s)};let r={cwd:n.environment.cwd,scratch:B(e),policy:this.policyFor(n.environment.cwd,B(e),!1)};return{files:$e(r.policy),prepare:s=>this.prepare(r,s)}}async prepare(e,n){if(this.requireOpen(),!U(n.workdir))throw new Error(`The command sandbox needs an absolute workdir, not ${n.workdir}`);if(e===null)return this.plain(n);if(n.root!==e.cwd||n.scratch!==e.scratch)throw new Error(`The command sandbox refuses a launch whose root and scratch key differ from its operation's (${e.cwd}, ${e.scratch}): one operation has one policy`);return this.build(n,!1,e.policy)}plain(e){let n=this.host;if(n===null)throw new Error("The sandbox is not running");return{argv:R(e.program),cwd:e.workdir,env:e.environment,provenance:{launcher:P,version:n.version,policy:D},violations:async()=>null}}async start(){if(process.platform!=="darwin")throw new Error(`The command sandbox supports macOS only; on ${process.platform}, sandbox-runtime's launches sharing a directory can remove each other's protective mount points`);let e=k(this.config.tmpRoot),n=this.config.filesystem.denyWrite.map(f),o=n.find(u=>p(e,u.canonical)||p(u.canonical,e));if(o!==void 0)throw new Error(`tmpRoot must be outside filesystem.denyWrite, which would keep commands from writing their scratch directories: ${o.spelling}`);if(Ce)throw new Error("The command sandbox starts once per process: sandbox-runtime keeps process-wide state and is never restarted, so restart the host");Ce=!0,this.state="starting";let{config:r}=this,s=r.searchPath.split(":").map(k).join(":"),i=Ae(s),a=r.filesystem.allowWrite.map(f);Y(a.map(u=>u.canonical),i,e);let h=r.filesystem.denyRead.map(f),c=hn(),l=me(e);fe(l);let m=pe(l,r.javaAgentJar),x=new O(r.worker,{PATH:s,HOME:c,TMPDIR:l,CLAUDE_CODE_TMPDIR:l},u=>this.onWorkerDeath(u));this.client=x;let b=u=>({path:u,literal:!0}),ee={network:un(r.network),filesystem:{denyRead:h.map(u=>b(u.canonical)),allowWrite:[],denyWrite:n.map(u=>b(u.canonical))},javaAgentJarPath:m.path},w=await x.request({type:"init",config:ee,expect:{tmpdir:l,home:c}},{timeoutMs:H}),_=[...w.supported?[]:["this platform is not supported"],...w.errors,...w.warnings,...mn(r.network.mode,w.javaAgent,m.path)];if(_.length>0)throw new Error(`The command sandbox cannot start here: ${_.join("; ")}`);if(this.host={tmpRoot:e,cwd:process.cwd(),home:c,searchPath:s,trusted:i,extraRoots:r.filesystem.allowWrite,facts:{allowWrite:a,denyWrite:n,denyRead:h,conveniences:w.conveniences.map(f),privateDirectory:f(l)},version:Re(w.version),javaAgentSha256:m.sha256},await this.selfCheck(e),!x.alive||this.failure!==null)throw new Error(`The command sandbox worker ended while it started${this.failure===null?"":`: ${this.failure.message}`}`);this.state="ready"}async selfCheck(e){let n=X(e,"self-check"),o=await this.build({program:{shell:"exit 0"},workdir:n,root:n,scratch:"self-check",environment:{},signal:AbortSignal.timeout(H)},!0),r=await ne({command:o.argv,cwd:o.cwd,env:o.env,signal:AbortSignal.timeout(H),timeoutMs:H});if(r.exitCode!==0){let s=r.exitSignal===null?`exit code ${r.exitCode}`:`signal ${r.exitSignal}`;throw new Error(`The command sandbox could not run a confined command: ${r.output.trim()||s}`)}}requireOpen(){if(this.state==="failed")throw new Error(`The sandbox failed${this.failure===null?"":`: ${this.failure.message}`}. Nothing runs unconfined; it stays failed until lagent restarts.`);if(this.state==="new"||this.state==="starting")throw new Error("The sandbox is still starting");if(this.state!=="ready"||!this.admitting)throw new Error("The sandbox is shutting down")}async build(e,n,o){let r=this.host,s=this.client;if(r===null||s===null)throw new Error("The sandbox is not running");if(ve(e.environment),!U(e.workdir))throw new Error(`The command sandbox needs an absolute workdir, not ${e.workdir}`);let i=_e(e.program);if(Buffer.byteLength(i)>V)throw new Error(`The command sandbox refuses a command longer than ${V} bytes`);if(process.cwd()!==r.cwd)throw new Error(`The host changed its working directory from ${r.cwd} to ${process.cwd()}: the command sandbox refuses to launch`);let a=this.policyFor(e.root,e.scratch,n);if(o!==void 0&&v(o)!==v(a))throw new Error("The command sandbox refuses to launch: a writable root or a link in it now leads somewhere other than where this operation selected its policy, so it could not enforce the same one. Start the operation again.");let h=o??a,c=X(r.tmpRoot,e.scratch),l=ke(h),m=dn();return{argv:["/bin/sh","-c",`exec ${await s.request({type:"wrap",command:K,commandId:m,commandText:i.slice(0,1e3),config:{filesystem:l}},{timeoutMs:fn,signal:e.signal})}`],cwd:e.workdir,env:De(e.environment,r.searchPath,c,i),provenance:{launcher:P,version:r.version,policy:Ne({filesystem:l,network:this.config.network,searchPath:r.searchPath,cwd:r.cwd,home:r.home,conveniences:r.facts.conveniences.map(b=>b.spelling),javaAgent:r.javaAgentSha256,version:r.version})},violations:()=>this.violationsOf(m)}}policyFor(e,n,o){let r=this.host;if(r===null)throw new Error("The sandbox is not running");let s=Z(e,Te(e)),i=r.extraRoots.map(f),a=i.map(h=>h.canonical);return Y(o?a:[s.canonical,...a],r.trusted,r.tmpRoot),Se({...r.facts,allowWrite:i},s,f(G(r.tmpRoot,n)))}async violationsOf(e){if(this.client===null)return null;let n=await this.client.request({type:"violations",commandId:e},{timeoutMs:te});return n.length===0?null:`<sandbox_violations>
+${n.join(`
+`)}
+</sandbox_violations>`}onWorkerDeath(e){this.failure??=e,this.state==="ready"&&(this.state="failed",this.admitting=!1,this.ctx.reportError(e),this.releaseHandle(),this.announceFailure())}announceFailure(){this.ctx.parallel("lagent/sandbox/health","failed").catch(e=>this.ctx.reportError(e))}async closeAndRelease(){this.admitting=!1,this.state==="ready"&&(this.state="stopping"),await this.releaseHandle()}releaseHandle(){return this.releasing??=this.handle.release(this.config.drainTimeoutMs).then(e=>(e||this.ctx.reportError(new Error(`A command could not be confirmed stopped within ${this.config.drainTimeoutMs} ms: a confined process may still run, so the sandbox worker is kept until the process exits`)),e)),this.releasing}async release(){let e=this.client;if(e!==null){if(!await this.releaseHandle()){e.unref();return}e.alive&&await e.request({type:"reset"},{timeoutMs:pn}).catch(()=>{}),await e.terminate(),this.client=null}}};import{z as Le}from"zod";var wn=Le.strictObject({drainTimeoutMs:Le.number().int().positive()}),gn="lagent-sandbox-absent",yn="1",xn={name:"lagent:sandbox-absent",inject:["journal","threads","confinement"],apply(t,e){N(t,"sandboxAbsent");let n=wn.parse(e);L(t,"sandboxAbsent");let o=t.confinement.handle({async snapshot(s){if(C(t,s)==="confined")throw new Error("This conversation is sandboxed, and the host started without a sandbox, so its commands, searches and file access are refused.");return{files:null,async prepare(i){return{argv:R(i.program),cwd:i.workdir,env:i.environment,provenance:{launcher:gn,version:yn,policy:D},violations:async()=>null}}}}}),r=null;t.fiber.beforeUnload(()=>(r??=o.release(n.drainTimeoutMs).then(s=>(s||t.reportError(new Error(`A command could not be confirmed stopped within ${n.drainTimeoutMs} ms`)),s)),r.then(()=>{}))),M(t,s=>C(t,s)==="confined"?{mode:"confined",guidance:q}:{mode:"unconfined",guidance:null})}};var dt=W,ht=new URL("./worker.js",import.meta.url);function ut(){let t=bn(import.meta.url).resolve("@anthropic-ai/sandbox-runtime/package.json");return En(vn(t),"vendor","java-proxy-agent","srt-proxy-agent.jar")}export{Me as SandboxConfigSchema,dt as sandbox,xn as sandboxAbsent,C as sandboxRecorded,on as sandboxRecordedOn,ht as sandboxWorker,ut as srtJavaAgentJar};

package/dist/plugins/sandbox/mode.d.ts

@@ -0,0 +1,57 @@
+import type { Context } from '@leuduan/cordis';
+import { z } from 'zod';
+import type { PluginJournal } from '../../journal/index.js';
+/**
+ * Whether a conversation's shell commands run in the OS sandbox. One vocabulary from lagent to a
+ * host's wire; "sandboxed" and "unsandboxed" are a display's words.
+ */
+export type SandboxMode = 'confined' | 'unconfined';
+/**
+ * The durable mode of each conversation, on its root: a delegated thread is in its conversation's
+ * mode, so a sub-agent is never in a mode its conversation is not. Private to this package: the
+ * service is its only writer, and `sandboxRecorded` is how a host reads it.
+ */
+export declare const sandboxModes: import("../../services/modes.js").Modes<SandboxMode>;
+/**
+ * The mode recorded for the conversation `threadId` belongs to, `null` only when none was ever
+ * recorded: never the `confined` a thread without a row reads as. For a host deciding what the
+ * journal says, whether the sandbox is mounted or not. Throws for a thread the journal does not hold,
+ * a caller chain that does not reach its conversation root, and a mode row this build cannot read.
+ * Needs the thread's history loaded, as a tool call and a launch it makes already have it.
+ */
+export declare function sandboxRecorded(ctx: Context, threadId: string): SandboxMode | null;
+/**
+ * The recorded mode in this thread's own fork-lineage fold, without resolving delegation authority:
+ * a fork reads what its history recorded up to the cut, and a delegated thread reads its own fold,
+ * `null` unless it inherited a row, never its conversation's mode. For a catalog contribution, which
+ * is computed from the thread's own folds. A host deciding what the journal says uses {@link sandboxRecorded}.
+ */
+export declare const sandboxRecordedOn: (journal: PluginJournal, threadId: string) => SandboxMode | null;
+/** What the model is told about a conversation's shell commands: the mode, and what confined ones may do. */
+declare const SandboxFactSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        unconfined: "unconfined";
+        confined: "confined";
+    }>;
+    guidance: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type SandboxFact = z.output<typeof SandboxFactSchema>;
+/**
+ * What a confined conversation is told on a host started without a sandbox, where its commands, searches
+ * and file access are refused.
+ */
+export declare const ABSENT_GUIDANCE = "The sandbox is unavailable on this host: commands, searches and file access are refused for this conversation.";
+/**
+ * Tells every agent's threads the fact `current` says at their model steps. The guidance is part of
+ * the compared fact, so a changed sandbox file, or a host that lost its sandbox, is told again. A
+ * conversation that starts unconfined is told nothing; a lift is still owed when the confined notice
+ * that preceded it was compacted away, since its checkpoint may still say confined. Each telling of
+ * confinement carries the caveat that launches already preparing or running are not affected.
+ */
+export declare function tellSandbox(ctx: Context, current: (threadId: string) => SandboxFact): void;
+/**
+ * Claims the root's one sandbox slot for `owner`, released when `ctx` ends. Whichever of `sandbox`
+ * and `sandboxAbsent` mounts second fails, in either order, before it registers anything.
+ */
+export declare function claimSandbox(ctx: Context, owner: 'sandbox' | 'sandboxAbsent'): void;
+export {};

package/dist/plugins/sandbox/policy.d.ts

@@ -0,0 +1,163 @@
+import type { FilePolicy, LaunchProgram } from '../../services/confinement/service.js';
+import type { SpawnEnvironment } from '../../sys/spawn.js';
+import type { CallConfig, PathEntry } from './protocol.js';
+export declare function refuseStartupInjection(environment: SpawnEnvironment): void;
+/** The most command text one launch carries, which travels in the environment of the process that starts it. */
+export declare const MAX_COMMAND_BYTES: number;
+/**
+ * `path` with every link in its existing part resolved, so containment is judged on real locations.
+ * The one rule for every path of a policy: a link that leads nowhere is not followed, it stays the
+ * name it is, so an entry that is a dangling link covers its own name and nothing it points at.
+ */
+export declare function canonical(path: string): string;
+/**
+ * The root a command's protected names are rebuilt for, canonical. sandbox-runtime substitutes the
+ * real prefix before it compiles a pattern, and cannot anchor one this module hands it, so a root
+ * whose real path holds glob characters or its compiler's placeholders would turn the patterns
+ * below into something else: it is refused, not escaped.
+ */
+export declare function canonicalRoot(root: string): string;
+/**
+ * The names sandbox-runtime protects below its working directory, which here is the host's, not the thread's:
+ * relative suffixes, matched at the root and at any depth below it, with everything beneath them.
+ */
+export declare const PROTECTED_SUFFIXES: readonly string[];
+/**
+ * sandbox-runtime's mandatory write denies, rebuilt for `root`: its own set anchors at the host's
+ * working directory and only ever adds denies there. Each of `suffixes` once as the path at the root and
+ * twice as patterns for the same name anywhere beneath it, itself and its descendants. `root` is
+ * canonical and holds no glob characters (`canonicalRoot`).
+ */
+export declare function mandatoryDenies(root: string, suffixes: readonly string[]): PathEntry[];
+/**
+ * The programs a launch runs before confinement, as the search path finds them: the directories
+ * searched, since a program dropped into an earlier one would win, and the real file of every
+ * candidate for each program, wherever its link leads.
+ */
+export declare function helperLocations(searchPath: string): string[];
+/**
+ * Refuses roots a command could use against the sandbox itself: one overlapping, either way, what
+ * a launch runs before confinement, or the temporary root, whose directories the host creates
+ * unconfined. `roots` are canonical.
+ */
+export declare function refuseUnsafeRoots(roots: readonly string[], trusted: readonly string[], tmpRoot: string): void;
+/**
+ * A path as the host configured it and as it really is, with whether its volume folds case
+ * (`null`: it could not be told). Both spellings are matched when a path is judged by name
+ * (`filePolicy`), so a workspace configured by its link path still matches a path spelled by its
+ * real one, and the other way round; the OS sees only the real one (`srtFilesystem`).
+ */
+export type Anchor = {
+    readonly spelling: string;
+    readonly canonical: string;
+    readonly foldsCase: boolean | null;
+};
+/** `spelling` with the real path it leads to, which the caller already has, and its volume's case rule. */
+export declare const anchorAt: (spelling: string, canonicalPath: string) => Anchor;
+/** `path` as configured, with where it really leads. */
+export declare const anchor: (path: string) => Anchor;
+/**
+ * Whether the volume that holds `path` treats names that differ only in case as one, or `null` when
+ * it cannot be told. `path` may not exist yet: the answer is the volume of its nearest existing
+ * directory, probed by looking one of its entries up in another case and comparing what the two
+ * lookups find (device and inode), never by assuming a platform's default. Only what lives on that
+ * directory's own volume is probed: an entry on another device (a mount), or the directory's own
+ * name in a parent on another device, would answer for another volume. A directory with no entry to
+ * probe is probed through its own name in its parent, and so up, on the same device. `deviceOf` is
+ * the device lookup, replaceable to simulate volumes in tests.
+ */
+export declare function foldsCase(path: string, deviceOf?: (path: string) => number): boolean | null;
+/**
+ * What the sandbox allows a thread's processes and file tools, as one value in a restricted
+ * language: literal subtrees, each a path and everything below it, and protected relative suffixes
+ * under one root. `srtFilesystem` renders it for the OS, `filePolicy` for the file tools in this process.
+ */
+export type FilesystemPolicy = {
+    /** Writable subtrees: the thread's root, the host's roots and the scratch directory. */
+    readonly writable: readonly Anchor[];
+    /** Unwritable even inside a writable subtree: what the host and the sandbox keep for themselves. */
+    readonly denyWrite: readonly Anchor[];
+    /** Unreadable subtrees: credentials. */
+    readonly denyRead: readonly Anchor[];
+    /** Names unwritable at `root` and at any depth below it, with everything beneath them. */
+    readonly protected: {
+        readonly root: Anchor;
+        readonly suffixes: readonly string[];
+    };
+};
+/** What a thread's filesystem policy is made of, besides its root and scratch directory. */
+export type HostFacts = {
+    readonly allowWrite: readonly Anchor[];
+    readonly denyWrite: readonly Anchor[];
+    readonly denyRead: readonly Anchor[];
+    /** The paths under the home directory sandbox-runtime keeps writable for itself, as its worker reported them. */
+    readonly conveniences: readonly Anchor[];
+    readonly privateDirectory: Anchor;
+};
+/**
+ * A thread's filesystem policy: writes only in the root, the host's roots and the scratch directory,
+ * and never in what the host or sandbox-runtime keeps for itself or in the root's protected names.
+ * `root` is the thread's working directory, `canonicalRoot`'s answer for its spelling.
+ */
+export declare function filesystemPolicy(facts: HostFacts, root: Anchor, scratchDirectory: Anchor): FilesystemPolicy;
+/** The OS's lists for the policy, which replace the initialized ones for the call: every path real and literal. */
+export declare function srtFilesystem(policy: FilesystemPolicy): CallConfig['filesystem'];
+/**
+ * The policy for file tools in this process: the same value the OS enforces on processes, judged by
+ * name. It reads no file system, so a link in a path is the caller's to resolve: it asks for the
+ * path as requested and for where it resolves, and both must pass. A path is in a subtree, or under
+ * the protected root, by either spelling of that entry.
+ *
+ * Names are compared as the entry's volume would see them, and doubt never widens what is allowed.
+ * A rule that refuses compares in Unicode normalization form NFC, since a volume such as APFS treats
+ * the composed and decomposed spellings of a name as one, and folds case where the volume does:
+ * `.SSH` is `.ssh` there, even when `.ssh` does not exist yet, and `.GITCONFIG` is another file on a
+ * volume that keeps case. Where that could not be told (`foldsCase: null`) it folds. A rule that
+ * allows compares the spellings as they are, folding case only where the volume is known to. So on
+ * a volume that tells normalizations apart a refusal can over-match, and on APFS a writable root
+ * typed in another normalization than it was configured in is refused, never allowed too widely.
+ */
+export declare function filePolicy(policy: FilesystemPolicy): FilePolicy;
+/**
+ * The script the sandbox runs: restores the command's `PATH`, sets its temporary directory and runs
+ * it with `/bin/sh -c`. Everything it needs arrives in variables, never spliced into the script.
+ */
+export declare const BOOTSTRAP: string;
+/**
+ * A program as the shell text the sandbox runs: shell text as it is, an argv as `exec` and every word
+ * single-quoted, so the shell splits it back into exactly those words and looks the program up as a
+ * plain spawn does, never as one of its builtins or functions.
+ */
+export declare function programText(program: LaunchProgram): string;
+/**
+ * The environment of the process that starts the sandbox: the command's own, but with the trusted
+ * `PATH` until the sandbox holds, since the wrapped line runs `env` and `sandbox-exec` before
+ * confinement. The bootstrap restores the rest.
+ */
+export declare function launchEnvironment(environment: SpawnEnvironment, searchPath: string, scratchDirectory: string, command: string): SpawnEnvironment;
+/** What the name and version say in a command's recorded launch. */
+export declare const LAUNCHER = "lagent-srt";
+export declare const versionOf: (runtime: string) => string;
+/** Everything enforcement depends on, digested: recorded with a launch as its policy. */
+export declare function policyDigest(facts: {
+    readonly filesystem: CallConfig['filesystem'];
+    readonly network: unknown;
+    readonly searchPath: string;
+    readonly cwd: string;
+    readonly home: string;
+    readonly conveniences: readonly string[];
+    readonly javaAgent: string;
+    readonly version: string;
+}): string;
+/** What the model is told about sandboxed commands. */
+export declare function instructionsFor(config: {
+    readonly filesystem: {
+        readonly allowWrite: readonly string[];
+    };
+    readonly network: {
+        readonly mode: 'allowlist';
+        readonly allowedDomains: readonly string[];
+    } | {
+        readonly mode: 'unrestricted';
+    };
+}): string;