@mku1tra/que-pasa 0.1.0 → 0.2.1

package/README.md

@@ -4,7 +4,7 @@ que-v2's harness, on pi-durable: a workspace defines its agents with `@mku1tra/q
 
 ## Run and check
 
-Node runs in the dev container (`.devcontainer/devcontainer.json`), never on the host. You need `just`, `podman` and `npx`.
+Node runs in the dev container (`.devcontainer/devcontainer.json`), never on the host. The container starts from the dev image, `ghcr.io/matta-kelly/que-pasa-dev:main`, which `.devcontainer/Containerfile` builds with the npm cache of `package-lock.json`, and the `dev-image` workflow on main builds and pushes it. You need `just`, `podman` and `npx`; once per machine, log in with `podman login ghcr.io`, and the first `just up` pulls the dev image, then installs from its cache in seconds.
 
 - `just up`: make or start this checkout's dev container
 - `just check`: the check set, `scripts/check.sh`: notes, then types, lint, format, tests and the build. The pre-push hook and the pipeline run the same file
@@ -24,6 +24,25 @@ await runtime.close();
 
 One runtime per process owns its SQLite file. After a crash, open it again with the same agents: unfinished runs go on, and `run` with the same `runId` gives back the result.
 
+A tool gets what it acts on from its run, as a resource the host provides. The file and command tools of `@mku1tra/que-pasa/sandbox` act in the `Sandbox` the host gives each run:
+
+```ts
+import { provide } from "@mku1tra/que-pasa/loop";
+import { Sandbox, execute, fileTools, podman, view } from "@mku1tra/que-pasa/sandbox";
+
+const coder = defineAgent({ name: "coder", model, instructions, tools: [...fileTools, execute] });
+const runtime = await openRuntime({
+  storage, models, agents: [coder],
+  resources: [
+    provide(Sandbox, ({ runId }) =>
+      podman({ name: `run-${runId}`, image: "node:22", mounts: [{ source: worktree, target: "/work" }] }),
+    ),
+  ],
+});
+```
+
+A provider resolves from the run as it was started, so a run that resumes after a crash gets the same sandbox. `view(backend, { read, write })` limits a run to some files. What each backend's wall stops: `sandbox/que-pasa-sandbox.md`.
+
 Each run is traced as OpenTelemetry GenAI spans through `@opentelemetry/api`. To keep them, register an SDK (a tracer provider, an exporter, and an async context manager). To add what only the host knows, call `runtime.run()` inside a span of its own. `captureContent: true` on `openRuntime` adds message content.
 
 ## Use it from another project

package/dist/define/index.d.ts

@@ -1,3 +1,4 @@
 export { defineAgent, parseModel, type Agent } from "./agent.ts";
+export { defineResource, type Resource } from "./resource.ts";
 export { defineTool, type Tool } from "./tool.ts";
 export type { Caller, Json, Runtime } from "./runtime.ts";

package/dist/define/index.js

@@ -1,2 +1,3 @@
 export { defineAgent, parseModel } from "./agent.js";
+export { defineResource } from "./resource.js";
 export { defineTool } from "./tool.js";

package/dist/define/resource.d.ts

@@ -0,0 +1,15 @@
+declare const valueType: unique symbol;
+/**
+ * Something a tool needs that the host gives each run: a sandbox, and later a connection. It holds no value, only its
+ * name and the type of its value: the host provides the value per run (`openRuntime({ resources })`), and a tool asks
+ * for it with `runtime.use(resource)`.
+ */
+export type Resource<T = unknown> = {
+    /** kebab-case: the host provides it by this name. */
+    readonly name: string;
+    /** The type of its value; never set. */
+    readonly [valueType]?: T;
+};
+/** A resource, checked: its name is kebab-case. */
+export declare function defineResource<T>(name: string): Resource<T>;
+export {};

package/dist/define/resource.js

@@ -0,0 +1,8 @@
+const resourceName = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/** A resource, checked: its name is kebab-case. */
+export function defineResource(name) {
+    if (!resourceName.test(name)) {
+        throw new Error(`resource "${name}": the name must be kebab-case`);
+    }
+    return Object.freeze({ name });
+}

package/dist/define/runtime.d.ts

@@ -2,16 +2,19 @@
 export type Caller = {
     id: string;
 };
+import type { Resource } from "./resource.ts";
 /** A JSON value: what a run keeps in storage, so it survives a restart. */
 export type Json = string | number | boolean | null | Json[] | {
     [key: string]: Json;
 };
 /**
- * What a tool gets from its run, besides its input: the caller, and the context the run was given (LangChain's
- * runtime context). The context is the host's, per run, such as the sandbox an attempt's tools exec into. It is JSON,
- * because the run keeps it, and a run that resumes after a restart gives its tools the same one.
+ * What a tool gets from its run, besides its input: the caller, the context the run was given (LangChain's runtime
+ * context), and the resources the host provides for the run. The context is JSON, because the run keeps it, and a run
+ * that resumes after a restart gives its tools the same one, so they get the same resources.
  */
 export type Runtime<C extends Json | undefined = undefined> = {
     caller: Caller;
     context: C;
+    /** The run's value of a resource the tool declares in `uses`. Any other resource throws. */
+    use<T>(resource: Resource<T>): Promise<T>;
 };

package/dist/define/tool.d.ts

@@ -1,4 +1,5 @@
 import type { z } from "zod";
+import type { Resource } from "./resource.ts";
 import type { Json, Runtime } from "./runtime.ts";
 /** A function an agent can call: written once in a workspace, so any agent in it can be given it. */
 export type Tool<S extends z.ZodObject = z.ZodObject, C extends Json | undefined = undefined> = {
@@ -8,8 +9,8 @@ export type Tool<S extends z.ZodObject = z.ZodObject, C extends Json | undefined
     description: string;
     /** The input the model must give. */
     schema: S;
-    /** The name of the connection it reads at call time. The tool never holds the credential. */
-    connection?: string;
+    /** The resources it asks its run for, with `runtime.use`: a sandbox, a connection. It never holds one. */
+    uses?: readonly Resource[];
     /**
      * "safe": a call a crash cut off runs again when the run resumes. Left out, it never runs twice: the model gets an
      * `interrupted` result and decides what to do. pi's own term.

package/dist/define/tool.js

@@ -7,8 +7,13 @@ export function defineTool(tool) {
     if (tool.description.trim() === "") {
         throw new Error(`tool "${tool.name}": the description is empty`);
     }
-    if (tool.connection !== undefined && tool.connection.trim() === "") {
-        throw new Error(`tool "${tool.name}": the connection name is empty`);
+    const uses = tool.uses ?? [];
+    const named = new Set(uses.map((resource) => resource.name));
+    if (named.size !== uses.length) {
+        throw new Error(`tool "${tool.name}": a resource is in uses twice`);
     }
-    return Object.freeze({ ...tool });
+    return Object.freeze({
+        ...tool,
+        ...(tool.uses ? { uses: Object.freeze([...tool.uses]) } : {}),
+    });
 }

package/dist/loop/extension.d.ts

@@ -1,6 +1,7 @@
 import { type Extension } from "@earendil-works/pi-durable";
 import { z } from "zod";
 import type { Agent, Json } from "../define/index.ts";
+import type { Resources } from "./resources.ts";
 /** Any agent, as the runtime holds it. */
 export type AnyAgent = Agent<z.ZodObject | undefined, Json | undefined>;
 /** The tool an agent with an output calls to give its result. No agent tool may take its name. */
@@ -14,7 +15,7 @@ export declare const extensionName: (agent: AnyAgent) => string;
  * no run's state: each call reads its run's document and transcript, so it serves every run of the agent, also one that
  * resumes in a new process.
  */
-export declare function agentExtension(agent: AnyAgent): Extension;
+export declare function agentExtension(agent: AnyAgent, resources: Resources): Extension;
 /**
  * The JSON Schema of what the model must give: the input shape, so a field with a default is not required. Without the
  * `$schema` key a tool's parameters do not take.

package/dist/loop/extension.js

@@ -15,12 +15,12 @@ export const extensionName = (agent) => `agent-${agent.name}`;
  * no run's state: each call reads its run's document and transcript, so it serves every run of the agent, also one that
  * resumes in a new process.
  */
-export function agentExtension(agent) {
+export function agentExtension(agent, resources) {
     const { output } = agent;
     if (output && agent.tools.some((tool) => tool.name === submitTool)) {
         throw new Error(`agent "${agent.name}": a tool is named "${submitTool}", which its output needs`);
     }
-    const tools = agent.tools.map(toPiTool);
+    const tools = agent.tools.map((tool) => toPiTool(tool, resources));
     if (output)
         tools.push(submit(output));
     return defineExtension({
@@ -30,14 +30,14 @@ export function agentExtension(agent) {
     });
 }
 /** A que-pasa tool as a pi tool: pi checks the arguments against the JSON Schema, zod parses them, and the run's runtime goes in. */
-function toPiTool(tool) {
+function toPiTool(tool, resources) {
     return definePiTool({
         name: tool.name,
         description: tool.description,
         parameters: jsonSchema(tool.schema),
         ...(tool.replay ? { replay: tool.replay } : {}),
         execute: async (args, api, context) => {
-            const result = await tool.run(tool.schema.parse(args), await runtimeOf(api, context));
+            const result = await tool.run(tool.schema.parse(args), await runtimeOf(tool, resources, api, context));
             return {
                 output: [
                     {
@@ -73,12 +73,22 @@ const remind = hook(GenerationTask, {
         return sent < reminders ? { continue: reminder } : undefined;
     },
 });
-/** The runtime of the call's run, from its run document. */
-async function runtimeOf(api, context) {
+/** The runtime of the call's run, from its run document: its caller, its context, and the resources the tool uses. */
+async function runtimeOf(tool, resources, api, context) {
     const run = await api.snapshot(RunDoc, api.conversationId, context);
     if (!run)
         throw new Error("the run has no run document");
-    return { caller: run.caller, context: run.context };
+    const uses = new Set((tool.uses ?? []).map((resource) => resource.name));
+    return {
+        caller: run.caller,
+        context: run.context,
+        use: async (resource) => {
+            if (!uses.has(resource.name)) {
+                throw new Error(`tool "${tool.name}" uses resource "${resource.name}", which it does not declare in uses`);
+            }
+            return resources.use(run, resource);
+        },
+    };
 }
 /**
  * The JSON Schema of what the model must give: the input shape, so a field with a default is not required. Without the

package/dist/loop/index.d.ts

@@ -1,2 +1,3 @@
 export { reminder, submitTool } from "./extension.ts";
+export { provide, type Provider, type RunOf } from "./resources.ts";
 export { openRuntime, type RunOptions, type RunResult, type RunUsage, type Runtime, type RuntimeOptions, } from "./runtime.ts";

package/dist/loop/index.js

@@ -1,2 +1,3 @@
 export { reminder, submitTool } from "./extension.js";
+export { provide } from "./resources.js";
 export { openRuntime, } from "./runtime.js";

package/dist/loop/resources.d.ts

@@ -0,0 +1,34 @@
+import type { Caller, Json, Resource } from "../define/index.ts";
+import type { RunState } from "./state.ts";
+/** What a provider resolves a resource from: the run as it was started, read from its run document. */
+export type RunOf = {
+    runId: string;
+    caller: Caller;
+    /** Absent when the run was given none. */
+    context?: Json;
+};
+/** The host's value of one resource, per run. */
+export type Provider<T = unknown> = {
+    readonly resource: Resource<T>;
+    resolve(run: RunOf): T | Promise<T>;
+};
+/**
+ * The host's value of a resource for each run, resolved from the run as it was started: a run that resumes in a new
+ * process gets the same one.
+ */
+export declare function provide<T>(resource: Resource<T>, resolve: (run: RunOf) => T | Promise<T>): Provider<T>;
+/** The host's providers, and each run's resolved values: resolved once per run while it goes on in this process. */
+export declare function createResources(providers: readonly Provider[]): {
+    /** Throws when a resource a tool uses has no provider: at open, never in a run. */
+    check(uses: readonly {
+        tool: string;
+        resource: Resource;
+    }[]): void;
+    /** The run's value of a resource. */
+    use<T>(run: RunState, resource: Resource<T>): Promise<T>;
+    /** Drop a run's values, when it ends. */
+    forget(runId: string): void;
+    /** Drop every run's values, when the runtime closes. */
+    clear(): void;
+};
+export type Resources = ReturnType<typeof createResources>;

package/dist/loop/resources.js

@@ -0,0 +1,57 @@
+/**
+ * The host's value of a resource for each run, resolved from the run as it was started: a run that resumes in a new
+ * process gets the same one.
+ */
+export function provide(resource, resolve) {
+    return Object.freeze({ resource, resolve });
+}
+/** The host's providers, and each run's resolved values: resolved once per run while it goes on in this process. */
+export function createResources(providers) {
+    const byName = new Map();
+    for (const provider of providers) {
+        const { name } = provider.resource;
+        if (byName.has(name))
+            throw new Error(`resource "${name}" is provided twice`);
+        byName.set(name, provider);
+    }
+    const resolved = new Map();
+    return {
+        /** Throws when a resource a tool uses has no provider: at open, never in a run. */
+        check(uses) {
+            for (const { tool, resource } of uses) {
+                if (!byName.has(resource.name)) {
+                    throw new Error(`tool "${tool}" uses resource "${resource.name}", which is not provided`);
+                }
+            }
+        },
+        /** The run's value of a resource. */
+        use(run, resource) {
+            const provider = byName.get(resource.name);
+            if (!provider)
+                throw new Error(`resource "${resource.name}" is not provided`);
+            const values = resolved.get(run.runId) ??
+                resolved.set(run.runId, new Map()).get(run.runId);
+            let value = values.get(resource.name);
+            if (!value) {
+                const { runId, caller, context } = run;
+                value = Promise.resolve(provider.resolve({
+                    runId,
+                    caller,
+                    ...(context === undefined ? {} : { context }),
+                }));
+                // A failed resolve is not kept: the next call tries again.
+                value.catch(() => values.delete(resource.name));
+                values.set(resource.name, value);
+            }
+            return value;
+        },
+        /** Drop a run's values, when it ends. */
+        forget(runId) {
+            resolved.delete(runId);
+        },
+        /** Drop every run's values, when the runtime closes. */
+        clear() {
+            resolved.clear();
+        },
+    };
+}

package/dist/loop/runtime.d.ts

@@ -3,6 +3,7 @@ import { type Storage, type UsageState } from "@earendil-works/pi-durable";
 import type { z } from "zod";
 import { type Agent, type Caller, type Json } from "../define/index.ts";
 import { type AnyAgent } from "./extension.ts";
+import { type Provider } from "./resources.ts";
 /** The tokens and cost a run spent: per `provider/model-id` for model calls, and per tool for tools that report it. */
 export type RunUsage = UsageState;
 /** What a run gives back: the agent's output, checked against its schema, or its answer as text. */
@@ -15,6 +16,11 @@ export type RuntimeOptions = {
     models: Models;
     /** Every agent the host can run. A run that resumes after a restart finds its agent here, by name. */
     agents: readonly AnyAgent[];
+    /**
+     * The host's value of each resource the agents' tools use, per run: `provide(resource, (run) => value)`. A provider
+     * resolves from the run as it was started, so a run that resumes after a restart gets the same one.
+     */
+    resources?: readonly Provider[];
     /**
      * Record message content in the trace: instructions, tool definitions, messages, tool arguments and results. Off by
      * default, as the GenAI conventions say: content can hold sensitive data.
@@ -58,4 +64,4 @@ export type Runtime = {
  * Open a runtime: one pi harness on `storage`, with each agent installed as its own extension. Runs a crash left
  * unfinished go on at once.
  */
-export declare function openRuntime({ storage, models, agents, captureContent, }: RuntimeOptions): Promise<Runtime>;
+export declare function openRuntime({ storage, models, agents, resources: providers, captureContent, }: RuntimeOptions): Promise<Runtime>;

package/dist/loop/runtime.js

@@ -2,6 +2,7 @@ import { BACKGROUND_CONTEXT, withAbortSignal, } from "@earendil-works/chord/cont
 import { configure, createRegistry, Harness, UsageDoc, } from "@earendil-works/pi-durable";
 import { parseModel, } from "../define/index.js";
 import { agentExtension, submitTool } from "./extension.js";
+import { createResources } from "./resources.js";
 import { RunDoc, RunIndex } from "./state.js";
 import { activeParent, createTracing } from "./trace.js";
 import { answerOf, messagesOf, resultOf } from "./transcript.js";
@@ -10,12 +11,17 @@ const context = BACKGROUND_CONTEXT;
  * Open a runtime: one pi harness on `storage`, with each agent installed as its own extension. Runs a crash left
  * unfinished go on at once.
  */
-export async function openRuntime({ storage, models, agents, captureContent = false, }) {
+export async function openRuntime({ storage, models, agents, resources: providers = [], captureContent = false, }) {
+    const resources = createResources(providers);
+    resources.check(agents.flatMap((agent) => agent.tools.flatMap((tool) => (tool.uses ?? []).map((resource) => ({ tool: tool.name, resource })))));
     const installed = new Map();
     for (const agent of agents) {
         if (installed.has(agent.name))
             throw new Error(`two agents are named "${agent.name}"`);
-        installed.set(agent.name, { agent, extension: agentExtension(agent) });
+        installed.set(agent.name, {
+            agent,
+            extension: agentExtension(agent, resources),
+        });
     }
     const tracing = createTracing({
         agents: new Map([...installed].map(([name, { agent }]) => [name, agent])),
@@ -103,6 +109,7 @@ export async function openRuntime({ storage, models, agents, captureContent = fa
                 tools: {},
             });
             onMessages?.(await transcript());
+            resources.forget(runId);
         }
     }
     return {
@@ -110,6 +117,7 @@ export async function openRuntime({ storage, models, agents, captureContent = fa
         async close() {
             await tracing.closeAll();
             await harness.close(context);
+            resources.clear();
         },
     };
 }

package/dist/sandbox/backend.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A backend: the place where a run's files are and its commands run, behind one interface. Two abilities, as in
+ * LangChain Deep Agents' backend protocol: files (`FileBackend`), and commands on top of files (`SandboxBackend`).
+ * Every path is the backend's own: relative to its root, or absolute under it. Every path a result gives is relative to
+ * the root. A backend gives its errors back in the result, and throws only when it cannot run at all.
+ */
+/** Why an operation did nothing. Deep Agents' file errors, and the two of an edit. */
+export type FileError = "file_not_found" | "is_directory" | "invalid_path" | "permission_denied" | "string_not_found" | "string_not_unique";
+/** What every result can say: that the operation did nothing, and why. `message` says more, for the model. */
+export type Failed = {
+    error?: FileError;
+    message?: string;
+};
+export type FileInfo = {
+    path: string;
+    isDir: boolean;
+};
+export type LsResult = Failed & {
+    files?: FileInfo[];
+};
+export type ReadResult = Failed & {
+    /** The lines asked for, each with its newline. */
+    content?: string;
+    /** How many lines the file has. */
+    totalLines?: number;
+};
+export type WriteResult = Failed & {
+    path?: string;
+};
+export type EditResult = Failed & {
+    path?: string;
+    occurrences?: number;
+};
+export type GlobResult = Failed & {
+    files?: string[];
+    truncated?: boolean;
+};
+export type GrepMatch = {
+    path: string;
+    line: number;
+    text: string;
+};
+export type GrepResult = Failed & {
+    matches?: GrepMatch[];
+    truncated?: boolean;
+};
+export type ExecuteResult = {
+    /** stdout and stderr, as they came. */
+    output: string;
+    /** null when the command was killed by a signal. */
+    exitCode: number | null;
+    /** The output kept only its tail. */
+    truncated: boolean;
+};
+/** Files: read, write and search them. */
+export interface FileBackend {
+    /** The folder every path is under. */
+    readonly root: string;
+    /** What a folder holds, or the file itself. */
+    ls(path: string): Promise<LsResult>;
+    /** `limit` lines of a file, after the first `offset`. */
+    read(path: string, offset: number, limit: number): Promise<ReadResult>;
+    /** A file, whole, made with its folder if it has none. It replaces what was there. */
+    write(path: string, content: string): Promise<WriteResult>;
+    /** Replace `old` with `next` in a file: it must occur once, unless `all`. */
+    edit(path: string, old: string, next: string, all: boolean): Promise<EditResult>;
+    /** The files under a folder whose path from that folder matches a glob. */
+    glob(pattern: string, path: string): Promise<GlobResult>;
+    /** The lines of the files under a path that hold a text, as is (not a pattern), in files matching `glob` if given. */
+    grep(pattern: string, path: string, glob?: string): Promise<GrepResult>;
+}
+/** Files, and commands: a backend that can run a shell command. */
+export interface SandboxBackend extends FileBackend {
+    /** Names this sandbox, such as its container. */
+    readonly id: string;
+    /** Run a shell command in the root. The signal kills it. */
+    execute(command: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ExecuteResult>;
+}
+/** Whether a backend can run commands. */
+export declare function canExecute(backend: FileBackend): backend is SandboxBackend;

package/dist/sandbox/backend.js

@@ -0,0 +1,10 @@
+/**
+ * A backend: the place where a run's files are and its commands run, behind one interface. Two abilities, as in
+ * LangChain Deep Agents' backend protocol: files (`FileBackend`), and commands on top of files (`SandboxBackend`).
+ * Every path is the backend's own: relative to its root, or absolute under it. Every path a result gives is relative to
+ * the root. A backend gives its errors back in the result, and throws only when it cannot run at all.
+ */
+/** Whether a backend can run commands. */
+export function canExecute(backend) {
+    return typeof backend.execute === "function";
+}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,7 @@
+export { canExecute, type EditResult, type ExecuteResult, type FileBackend, type FileError, type FileInfo, type GlobResult, type GrepMatch, type GrepResult, type LsResult, type ReadResult, type SandboxBackend, type WriteResult, } from "./backend.ts";
+export { local } from "./local.ts";
+export { podman, type Mount, type Podman, type PodmanOptions, } from "./podman.ts";
+export { shellBackend, type Exec } from "./shell.ts";
+export type { Ran, Script } from "./process.ts";
+export { Sandbox, edit_file, execute, fileTools, glob, grep, ls, read_file, readTools, write_file, } from "./tools.ts";
+export { view, type ViewPaths } from "./view.ts";

package/dist/sandbox/index.js

@@ -0,0 +1,6 @@
+export { canExecute, } from "./backend.js";
+export { local } from "./local.js";
+export { podman, } from "./podman.js";
+export { shellBackend } from "./shell.js";
+export { Sandbox, edit_file, execute, fileTools, glob, grep, ls, read_file, readTools, write_file, } from "./tools.js";
+export { view } from "./view.js";

package/dist/sandbox/local.d.ts

@@ -0,0 +1,8 @@
+import type { SandboxBackend } from "./backend.ts";
+/**
+ * A folder on the host as a backend: files and commands run as the host's own user. No wall: a path is checked
+ * against the root, but a symlink, or any command, reaches the whole host. For the host's own trusted work, and tests.
+ */
+export declare function local({ root }: {
+    root: string;
+}): SandboxBackend;

package/dist/sandbox/local.js

@@ -0,0 +1,20 @@
+import { isAbsolute } from "node:path";
+import { run } from "./process.js";
+import { shellBackend } from "./shell.js";
+/**
+ * A folder on the host as a backend: files and commands run as the host's own user. No wall: a path is checked
+ * against the root, but a symlink, or any command, reaches the whole host. For the host's own trusted work, and tests.
+ */
+export function local({ root }) {
+    if (!isAbsolute(root))
+        throw new Error(`local: the root must be absolute, not "${root}"`);
+    return shellBackend({
+        id: `local:${root}`,
+        root,
+        exec: ({ script, args = [], stdin, signal }) => run("sh", ["-c", script, "sh", ...args], {
+            cwd: root,
+            ...(stdin === undefined ? {} : { stdin }),
+            ...(signal === undefined ? {} : { signal }),
+        }),
+    });
+}

package/dist/sandbox/paths.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A path as a tool gives it, as a path from the root: "" for the root itself. undefined for a path the backend refuses:
+ * one that leaves the root (by `..`, or absolute and not under it), starts with `~`, or holds a control character,
+ * which a line-based listing cannot carry.
+ */
+export declare function fromRoot(root: string, path: string): string | undefined;
+/** A path from the root as a shell argument: "." for the root. */
+export declare const asArg: (p: string) => string;
+/** Whether `path` is `folder` or under it; every path is under the root (""). */
+export declare const isUnder: (path: string, folder: string) => boolean;

package/dist/sandbox/paths.js

@@ -0,0 +1,31 @@
+import { posix } from "node:path";
+/**
+ * A path as a tool gives it, as a path from the root: "" for the root itself. undefined for a path the backend refuses:
+ * one that leaves the root (by `..`, or absolute and not under it), starts with `~`, or holds a control character,
+ * which a line-based listing cannot carry.
+ */
+export function fromRoot(root, path) {
+    const given = path.trim();
+    // A control character, such as a newline: no file of a backend is named with one.
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f\u007f]/.test(given) || given.startsWith("~"))
+        return undefined;
+    let p = given === "" ? "." : given;
+    if (posix.isAbsolute(p)) {
+        const top = posix.normalize(root).replace(/\/+$/, "");
+        const at = posix.normalize(p).replace(/\/+$/, "");
+        if (at === top)
+            return "";
+        if (!at.startsWith(`${top}/`))
+            return undefined;
+        p = at.slice(top.length + 1);
+    }
+    const n = posix.normalize(p).replace(/\/+$/, "");
+    if (n === ".." || n.startsWith("../"))
+        return undefined;
+    return n === "." ? "" : n;
+}
+/** A path from the root as a shell argument: "." for the root. */
+export const asArg = (p) => p || ".";
+/** Whether `path` is `folder` or under it; every path is under the root (""). */
+export const isUnder = (path, folder) => folder === "" || path === folder || path.startsWith(`${folder}/`);

package/dist/sandbox/podman.d.ts

@@ -0,0 +1,38 @@
+import type { SandboxBackend } from "./backend.ts";
+/** A folder of the host in the container. */
+export type Mount = {
+    source: string;
+    target: string;
+    readOnly?: boolean;
+};
+/** One container, as the host sets it: what it runs, what it sees, and what bounds it. */
+export type PodmanOptions = {
+    /** The container's name: one per sandbox, so a process that starts again finds it. */
+    name: string;
+    image: string;
+    /** The host folders it sees. Nothing else of the host is in it. */
+    mounts: readonly Mount[];
+    /** Its root: every path is under it. */
+    workdir?: string;
+    /** "none" by default: no network. */
+    network?: string;
+    /** The user commands run as, such as "1000:1000". */
+    user?: string;
+    /** Such as "4g". */
+    memory?: string;
+    /** Such as 3. */
+    cpus?: number;
+    /** Any other `podman run` options, such as `--userns=keep-id`. */
+    runArgs?: readonly string[];
+};
+/** A Podman container that outlives the process, as a backend. */
+export type Podman = SandboxBackend & {
+    /** Remove the container. The next call makes it again. */
+    close(): Promise<void>;
+};
+/**
+ * A Podman container as a backend: every operation execs into it, so its mounts, its network and its limits are the
+ * wall. It is made on its first call and kept: started again if it stopped, made again if it is gone, so a run that
+ * resumes after a restart works with no host step. One made with other options is refused, never used.
+ */
+export declare function podman(options: PodmanOptions): Podman;