@mku1tra/que-pasa 0.1.0 → 0.2.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mku1tra/que-pasa",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "An agent harness on pi-durable: define agents and tools with define/, and run them durably and traced with loop/.",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,10 @@
     "./loop": {
       "types": "./dist/loop/index.d.ts",
       "default": "./dist/loop/index.js"
+    },
+    "./sandbox": {
+      "types": "./dist/sandbox/index.d.ts",
+      "default": "./dist/sandbox/index.js"
     }
   },
   "files": [