@agentorg/cli 0.0.5 → 0.0.7

package/dist/node_modules/@agentorg/mcp/dist/src/provider.d.ts

@@ -0,0 +1,22 @@
+import { type Log } from "@agentorg/sdk";
+import { type Timing } from "./connection.js";
+export interface McpProviderOptions {
+    hubUrl: string;
+    /** The provider's own Actor, bound to `hub.actors@1` at its slot `actors`. */
+    actorId: string;
+    credential: string;
+    /** A private folder of the provider's, which holds each connection's Hub credential. */
+    dir: string;
+    log?: Log;
+    /** How often a server is checked, and the first wait before trying one again. For tests. */
+    timing?: Timing;
+}
+export interface McpProvider {
+    /** Leave the Hub and let every server go. The connections stay, and resume at the next start. */
+    close(): Promise<void>;
+}
+/**
+ * Run the built-in MCP provider as an Actor exporting `unit.provider@1` as `provider`. It offers two
+ * units, `url` and `command`; a server it starts runs with this process's rights. Connections made earlier are joined again at the start.
+ */
+export declare function startMcpProvider(options: McpProviderOptions): Promise<McpProvider>;

package/dist/node_modules/@agentorg/mcp/dist/src/provider.js

@@ -0,0 +1,197 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { hubActors, unitProvider } from "@agentorg/interfaces";
+import { Refused } from "@agentorg/sdk";
+import { connect } from "@agentorg/sdk/client";
+import { z } from "zod";
+import { Connection } from "./connection.js";
+import { namedSecrets, parseConnection, targetOf, UNITS, } from "./kinds.js";
+import { notPublic } from "./public.js";
+/** What is kept of a connection between runs, in the provider's private file. */
+const Stored = z.object({
+    credential: z.string(),
+    kind: z.string(),
+    params: z.record(z.string(), z.unknown()),
+    secrets: z.record(z.string(), z.string()),
+});
+const FILE = "connections.json";
+/** What a unit's values come to as a connection's parameters: its name isn't one. */
+const paramsOf = ({ slot: _, ...params }) => params;
+const quiet = { info() { }, warn() { }, error() { } };
+/**
+ * Run the built-in MCP provider as an Actor exporting `unit.provider@1` as `provider`. It offers two
+ * units, `url` and `command`; a server it starts runs with this process's rights. Connections made earlier are joined again at the start.
+ */
+export async function startMcpProvider(options) {
+    const log = options.log ?? quiet;
+    const { hubUrl, dir } = options;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    const path = join(dir, FILE);
+    /** The file, entry by entry; one that can't be read is set aside and the rest still run. */
+    const read = () => {
+        let raw;
+        try {
+            raw = readFileSync(path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return {};
+            throw error;
+        }
+        const entries = z.record(z.string(), z.unknown()).safeParse((() => {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return undefined;
+            }
+        })());
+        if (!entries.success) {
+            renameSync(path, `${path}.unreadable-${Date.now()}`);
+            log.error("The connections file can't be read: it is set aside and starts empty.");
+            return {};
+        }
+        const kept = {};
+        for (const [id, entry] of Object.entries(entries.data)) {
+            const parsed = Stored.safeParse(entry);
+            if (parsed.success)
+                kept[id] = parsed.data;
+            else
+                log.error(`Connection ${id} can't be read, and is left out.`);
+        }
+        return kept;
+    };
+    const stored = read();
+    const save = () => {
+        writeFileSync(`${path}.tmp`, JSON.stringify(stored), { mode: 0o600, flush: true });
+        renameSync(`${path}.tmp`, path);
+    };
+    const connections = new Map();
+    const open = async (actorId, credential, spec, secrets) => {
+        const connection = new Connection(spec, secrets, log, options.timing);
+        await connection.join({ hubUrl, actorId, credential });
+        connections.set(actorId, connection);
+        return connection;
+    };
+    let closing = false;
+    const endAll = () => Promise.all([...connections.values()].map((c) => c.end()));
+    const held = (id) => {
+        const connection = connections.get(id);
+        if (!connection)
+            throw new Refused("unknown", `This provider holds no connection ${id}.`);
+        return connection;
+    };
+    for (const [actorId, { credential, kind, params, secrets }] of Object.entries(stored)) {
+        const { spec, secrets: hidden, why } = parseConnection(kind, params, secrets);
+        if (!spec) {
+            log.error(`Connection ${actorId} can't be read: ${why}`);
+            continue;
+        }
+        try {
+            (await open(actorId, credential, spec, hidden)).run();
+        }
+        catch (error) {
+            log.error(`Connection ${actorId} didn't rejoin the Hub: ${String(error)}`);
+            // The Hub no longer knows it: its Actor was closed while the provider was away.
+            if (error instanceof Refused && error.code === "forbidden") {
+                delete stored[actorId];
+                save();
+            }
+        }
+    }
+    const provider = await connect({
+        hubUrl,
+        actorId: options.actorId,
+        credential: options.credential,
+        slots: { actors: hubActors },
+        exports: { provider: unitProvider },
+        log,
+        start(ctx) {
+            ctx.exports.provider.implement({
+                units: () => ({ units: UNITS }),
+                skill: () => {
+                    throw new Refused("unknown", "These units come with no skill.");
+                },
+                check({ unit, values, secrets }) {
+                    // Only whether a token is there matters, and a check never holds its value.
+                    const given = secrets.includes("token") ? { token: "given" } : {};
+                    const { why } = parseConnection(unit, paramsOf(values), given);
+                    return { problems: why ? [{ message: why }] : [] };
+                },
+                async apply({ unit: kind, values, secrets, name }) {
+                    const params = paramsOf(values);
+                    const named = namedSecrets(secrets);
+                    if (!named.secrets)
+                        throw new Refused("invalid", named.why ?? "Its secrets don't fit.");
+                    const { spec, secrets: hidden, why } = parseConnection(kind, params, named.secrets);
+                    if (!spec)
+                        throw new Refused("invalid", why);
+                    // Said now, as well as at each request.
+                    const away = spec.kind === "url" && spec.public ? await notPublic(spec.url) : undefined;
+                    if (away)
+                        throw new Refused("invalid", away);
+                    const { actorId, credential } = await ctx.slots.actors.call.create({ name });
+                    let connection;
+                    try {
+                        connection = await open(actorId, credential, spec, hidden);
+                        if (closing)
+                            throw new Refused("unavailable", "This provider is stopping.");
+                        stored[actorId] = { credential: credential, kind, params, secrets: hidden };
+                        save();
+                        connection.run();
+                    }
+                    catch (error) {
+                        connections.delete(actorId);
+                        delete stored[actorId];
+                        await connection?.end();
+                        await ctx.slots.actors.call.close({ actorId }).catch(() => { });
+                        throw error;
+                    }
+                    // The instance is the connection: one made before units had no other id.
+                    return {
+                        instance: actorId,
+                        connections: [
+                            { slot: String(values.slot), connection: actorId, target: targetOf(spec) },
+                        ],
+                        results: [],
+                    };
+                },
+                async status({ instance }) {
+                    const status = await held(instance).status();
+                    return {
+                        state: status.state,
+                        ...(status.detail ? { detail: status.detail } : {}),
+                        connections: [{ ...status, connection: instance }],
+                    };
+                },
+                live: () => {
+                    throw new Refused("unknown", "A connection has nothing to open live.");
+                },
+                async remove({ instance: connection }) {
+                    const found = held(connection);
+                    await ctx.slots.actors.call.close({ actorId: connection });
+                    connections.delete(connection);
+                    delete stored[connection];
+                    try {
+                        save();
+                    }
+                    finally {
+                        await found.end();
+                    }
+                    return {};
+                },
+            });
+        },
+    }).catch(async (error) => {
+        await endAll();
+        throw error;
+    });
+    return {
+        async close() {
+            closing = true;
+            await endAll();
+            provider.close();
+        },
+    };
+}

package/dist/node_modules/@agentorg/mcp/dist/src/public.d.ts

@@ -0,0 +1,6 @@
+/** Whether an IP address is one anyone on the internet could reach. */
+export declare function isPublicAddress(address: string): boolean;
+/** Why an address isn't a public https one, or nothing when it is. */
+export declare function notPublic(url: string): Promise<string | undefined>;
+/** A fetch for a public server: it checks where each request goes, and never follows a redirect. */
+export declare const publicFetch: typeof fetch;

package/dist/node_modules/@agentorg/mcp/dist/src/public.js

@@ -0,0 +1,72 @@
+// An address on the public internet, and a fetch that reaches nothing else: not this machine, not
+// its network, and no redirect, which could lead anywhere.
+import { lookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+const NOT_PUBLIC = new BlockList();
+for (const [address, prefix] of [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+])
+    NOT_PUBLIC.addSubnet(address, prefix, "ipv4");
+for (const [address, prefix] of [
+    ["::", 128],
+    ["::1", 128],
+    ["64:ff9b::", 96],
+    ["64:ff9b:1::", 48],
+    ["100::", 64],
+    ["2001:db8::", 32],
+    ["fc00::", 7],
+    ["fe80::", 10],
+    ["ff00::", 8],
+])
+    NOT_PUBLIC.addSubnet(address, prefix, "ipv6");
+/** Whether an IP address is one anyone on the internet could reach. */
+export function isPublicAddress(address) {
+    const family = isIP(address);
+    if (family === 0)
+        return false;
+    // An IPv4 address written as IPv6 is the IPv4 address.
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address)?.[1];
+    if (mapped)
+        return isPublicAddress(mapped);
+    return !NOT_PUBLIC.check(address, family === 4 ? "ipv4" : "ipv6");
+}
+/** Why an address isn't a public https one, or nothing when it is. */
+export async function notPublic(url) {
+    if (!URL.canParse(url))
+        return "That isn't an address.";
+    const { protocol, hostname } = new URL(url);
+    if (protocol !== "https:")
+        return "Only an https address can be used.";
+    const host = hostname.replace(/^\[|\]$/g, "");
+    let addresses;
+    try {
+        addresses = isIP(host) ? [host] : (await lookup(host, { all: true })).map((one) => one.address);
+    }
+    catch {
+        return `${hostname} can't be found.`;
+    }
+    return addresses.length && addresses.every(isPublicAddress)
+        ? undefined
+        : `${hostname} isn't on the public internet.`;
+}
+/** A fetch for a public server: it checks where each request goes, and never follows a redirect. */
+export const publicFetch = async (input, init) => {
+    const url = input instanceof Request ? input.url : String(input);
+    const why = await notPublic(url);
+    if (why)
+        throw new Error(why);
+    return fetch(input, { ...init, redirect: "error" });
+};

package/dist/node_modules/@agentorg/mcp/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@agentorg/mcp",
+  "version": "0.0.0",
+  "private": true,
+  "description": "The built-in MCP provider: each connection to an MCP server is an Actor offering tools@1",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
+    "test": "node --test \"dist/test/**/*.test.js\""
+  },
+  "dependencies": {
+    "@agentorg/interfaces": "0.0.0",
+    "@agentorg/sdk": "0.0.0",
+    "@modelcontextprotocol/client": "2.4.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@agentorg/hub": "0.0.0",
+    "@modelcontextprotocol/server": "2.4.0"
+  }
+}

package/dist/node_modules/@agentorg/sdk/dist/src/cli.js

@@ -8,22 +8,19 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join, relative } from "node:path";
+import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { openChannel } from "./client.js";
 import { NotConnected, OutcomeUnknown, Refused } from "./errors.js";
-import { BuildError, buildPackage } from "./package.js";
 import { hubHome, personCall, UsageError } from "./person-commands.js";
 const USAGE = `Usage: agentorg <command> [--home DIR]
 
-  build [package-dir]                       build a package into a .agentorg archive
   hub [--port N]                            run a Hub, serving on loopback
-  add <file.agentorg>                       hub.packages.add
   actors | bindings | exports | audit       each one's list
   bind <consumer.slot> <provider.export>    hub.grants.bind
   call <slot> <method> [json]               call one of the person's slots
 
-Commands other than build and hub act as the person, with the Hub home's person-credential.
+Commands other than hub act as the person, with the Hub home's person-credential.
 The home is --home, else $AGENTORG_HUB_HOME, else
 $XDG_DATA_HOME/agentorg, else ~/.local/share/agentorg.
 `;
@@ -56,21 +53,6 @@ if (values.help) {
     process.exit(0);
 }
 const home = hubHome(values.home);
-async function build() {
-    try {
-        const built = await buildPackage(rest[0] ?? ".");
-        write(process.stdout, `${built.manifest.name}@${built.manifest.version} ${built.hash}\n${relative(process.cwd(), built.file)}`);
-    }
-    catch (error) {
-        // A BuildError says what to fix; anything else is a bug, so its stack is shown.
-        write(process.stderr, error instanceof BuildError
-            ? error.message
-            : error instanceof Error
-                ? (error.stack ?? error.message)
-                : String(error));
-        process.exit(1);
-    }
-}
 /** Run a Hub in the home, and leave its address in `<home>/url` for the other commands. */
 async function hub() {
     if (values.port !== undefined && !/^\d{1,5}$/.test(values.port))
@@ -178,9 +160,7 @@ catch (error) {
         throw error;
     usage(error.message);
 }
-if (command === "build")
-    await build();
-else if (command === "hub")
+if (command === "hub")
     await hub();
 else if (call)
     await asPerson(call.slot, call.method, call.input);

package/dist/node_modules/@agentorg/sdk/dist/src/client.d.ts

@@ -1,6 +1,6 @@
 import { type Header, type WireError } from "@agentorg/wire";
 import { type DescribedInterface, type Interface } from "./interface.js";
-import { type Context, type Duplex, type ExportMap, type InterfaceMap, type Log } from "./module.js";
+import { type Context, type ExportMap, type InterfaceMap, type Log } from "./module.js";
 /** A stream the Hub opens toward this Actor's exports, naming the export and who is calling. */
 export type Serve = Extract<Header, {
     op: "serve";
@@ -10,25 +10,11 @@ export interface ServeHandlers {
     call(serve: Serve, input: unknown): Promise<unknown>;
     /** Start sending an export's events; `end` stops them from this side. Returns how to stop. */
     subscribe(serve: Serve, send: (payload: unknown) => void, end: (error?: unknown) => void): () => void;
-    /** Check that the export takes the stream (throwing a refusal if not), then return what runs it. */
-    accept(serve: Serve): (stream: Duplex) => Promise<void>;
-    /** The same for an `http` export: the stream carries HTTP/1.1 once accepted. */
-    serveHttp(serve: Serve): (stream: Duplex) => Promise<void>;
 }
-/**
- * Where the channel goes: the Hub's WebSocket address with the Actor's credential, or a pipe the
- * Hub made for this Actor's process, whose hello needs no credential.
- */
-export type ChannelOptions = ChannelBase & ({
+export interface ChannelOptions {
+    /** The Hub's WebSocket address. */
     hubUrl: string;
     credential: string;
-    channel?: never;
-} | {
-    channel: Duplex;
-    hubUrl?: never;
-    credential?: never;
-});
-interface ChannelBase {
     actorId: string;
     /**
      * Whether this channel may replace one the Actor already has (the default). With `false`, a
@@ -76,12 +62,6 @@ export interface Channel {
     call(slot: string, method: string, value: unknown): Promise<unknown>;
     /** Events from a slot's provider until it ends (`onEnd`) or is stopped; returns how to stop. */
     subscribe(slot: string, event: string, onEvent: (payload: unknown) => void, onEnd?: (error?: Error) => void): () => void;
-    open(slot: string, params: unknown): Promise<Duplex>;
-    /** A stream to an `http` slot's provider, carrying HTTP/1.1 once it accepts. */
-    http(slot: string): Promise<Duplex>;
-    /** Offer and withdraw run-time exports; they reach the Hub in the order they were made. */
-    offer(name: string, iface: DescribedInterface): Promise<void>;
-    withdraw(name: string): Promise<void>;
     close(): void;
     /** Settles when the channel ends. */
     readonly closed: Promise<void>;
@@ -128,8 +108,7 @@ type None = Record<never, Interface>;
  * `start`, and use slots from `onBind`. `start` runs before the channel opens, so the Hub never
  * reaches an export before it is implemented. A slot is bound when the Hub says so; `onBind` runs
  * when it becomes usable (bound, or its provider back), and `on` handlers subscribe while it is
- * usable. `exports.add` and `withdraw()` offer and withdraw over the channel. `http` slots and
- * exports speak HTTP/1.1 over the Hub's stream, one request per stream, with `node:http`.
+ * usable.
  */
 export declare function connect<const S extends InterfaceMap = None, const X extends ExportMap = None>(options: ConnectOptions<S, X>): Promise<Client<S, X>>;
 export {};

package/dist/node_modules/@agentorg/sdk/dist/src/client.js

@@ -57,9 +57,7 @@ export async function openChannel(options) {
         ready = resolve;
     });
     try {
-        const bytes = options.channel !== undefined
-            ? options.channel
-            : await webSocketChannel(new WebSocket(options.hubUrl));
+        const bytes = await webSocketChannel(new WebSocket(options.hubUrl));
         session = new Session(bytes, {
             client: true,
             onStream(stream) {
@@ -73,7 +71,7 @@ export async function openChannel(options) {
         });
     }
     catch {
-        throw new NotConnected(`the Hub at ${options.hubUrl ?? "its pipe"}`);
+        throw new NotConnected(`the Hub at ${options.hubUrl}`);
     }
     async function serveStream(header, stream, reader) {
         if (header.op === "slot") {
@@ -119,14 +117,6 @@ export async function openChannel(options) {
             }
             if (header.kind === "subscribe")
                 return subscribeStream(handlers, header, stream);
-            if (header.kind === "open" || header.kind === "http") {
-                const run = header.kind === "open" ? handlers.accept(header) : handlers.serveHttp(header);
-                const writer = stream.writable.getWriter();
-                await writer.write(encodeFrame(result({})));
-                writer.releaseLock();
-                // Accepted: from here the stream is raw bytes, so a failing handler can only reset it.
-                return await run({ readable: reader.rest(), writable: stream.writable }).catch(() => stream.reset());
-            }
             return stream.reset();
         }
         catch (error) {
@@ -195,7 +185,7 @@ export async function openChannel(options) {
     const hello = await exchange({
         op: "hello",
         actorId: options.actorId,
-        ...(options.credential === undefined ? {} : { credential: options.credential }),
+        credential: options.credential,
         ...(options.declares ? { declares: options.declares } : {}),
         ...(options.replace === false ? { replace: false } : {}),
     }, "the Hub");
@@ -213,13 +203,6 @@ export async function openChannel(options) {
             throw new Refused("bad_output", "The Hub's answer isn't a result.");
         return body.result;
     };
-    // Offers and withdrawals go one at a time, so the Hub sees them in the order they were made.
-    let changes = Promise.resolve();
-    const inOrder = (work) => {
-        const next = changes.then(work, work);
-        changes = next.catch(() => { });
-        return next;
-    };
     const closed = session.closed.then(() => {
         ended = true;
         bound.clear();
@@ -274,41 +257,9 @@ export async function openChannel(options) {
                 stream.reset();
             };
         },
-        open: (slot, params) => splice({ op: "open", slot, params }, slot),
-        http: (slot) => splice({ op: "http", slot }, slot),
-        offer: (name, iface) => inOrder(async () => {
-            answered(await exchange({ op: "offer", name, interface: iface }, name), name);
-        }),
-        withdraw: (name) => inOrder(async () => {
-            answered(await exchange({ op: "withdraw", name }, name), name);
-        }),
         close: () => session.close(),
         closed,
     };
-    /** Open a raw stream: send its header, read the one body that answers, then hand over the bytes. */
-    async function splice(header, slot) {
-        let stream;
-        try {
-            stream = session.open();
-            const writer = stream.writable.getWriter();
-            await writer.write(encodeFrame(header));
-            writer.releaseLock();
-            const reader = new FrameReader(stream.readable);
-            const first = await reader.next();
-            if (first === undefined)
-                throw new NotConnected(slot);
-            answered(parseBody(first), slot);
-            return { readable: reader.rest(), writable: stream.writable };
-        }
-        catch (error) {
-            stream?.reset();
-            if (error instanceof Refused ||
-                error instanceof NotConnected ||
-                error instanceof OutcomeUnknown)
-                throw error;
-            throw new NotConnected(slot);
-        }
-    }
 }
 const quiet = { info() { }, warn() { }, error() { } };
 /**
@@ -317,8 +268,7 @@ const quiet = { info() { }, warn() { }, error() { } };
  * `start`, and use slots from `onBind`. `start` runs before the channel opens, so the Hub never
  * reaches an export before it is implemented. A slot is bound when the Hub says so; `onBind` runs
  * when it becomes usable (bound, or its provider back), and `on` handlers subscribe while it is
- * usable. `exports.add` and `withdraw()` offer and withdraw over the channel. `http` slots and
- * exports speak HTTP/1.1 over the Hub's stream, one request per stream, with `node:http`.
+ * usable.
  */
 export async function connect(options) {
     const slots = (options.slots ?? {});
@@ -326,7 +276,7 @@ export async function connect(options) {
     const log = options.log ?? quiet;
     // defineActor checks the names, as it does for a module.
     const definition = defineActor({ slots, exports, start: options.start ?? (() => { }) });
-    const host = new ModuleHost("", slots, log);
+    const host = new ModuleHost(slots, log);
     const runtime = createRuntime(definition, {
         self: { actorId: options.actorId, module: "client" },
         log,

package/dist/node_modules/@agentorg/sdk/dist/src/errors.d.ts

@@ -1,4 +1,4 @@
-/** A call on a slot that no export is bound to, or on an export that was withdrawn. */
+/** A call on a slot that no export is bound to. */
 export declare class NotConnected extends Error {
     static [Symbol.hasInstance](value: unknown): boolean;
     readonly name = "NotConnected";

package/dist/node_modules/@agentorg/sdk/dist/src/errors.js

@@ -1,6 +1,6 @@
 /**
- * Marks an SDK error class's prototype with its name. A package's bundles and the runner each carry
- * their own copy of the SDK, so `instanceof` on these three classes checks this mark rather than
+ * Marks an SDK error class's prototype with its name. Programs may carry their own copy of the SDK,
+ * so `instanceof` on these three classes checks this mark rather than
  * the class, and an error made by one copy is the same error to the other. A subclass is checked
  * as usual.
  */
@@ -12,7 +12,7 @@ const instanceOf = (asked, base, name, value) =>
 asked === base
     ? isBranded(value, name)
     : Function.prototype[Symbol.hasInstance].call(asked, value);
-/** A call on a slot that no export is bound to, or on an export that was withdrawn. */
+/** A call on a slot that no export is bound to. */
 export class NotConnected extends Error {
     static [Symbol.hasInstance](value) {
         // biome-ignore lint/complexity/noThisInStatic: `this` is the class instanceof was asked about, a subclass included.

package/dist/node_modules/@agentorg/sdk/dist/src/filled.d.ts

@@ -0,0 +1,21 @@
+/** One field of a unit's form, as far as the reader needs it. */
+interface FormField {
+    id: string;
+    value: "string" | "number" | "boolean" | "strings" | "secret";
+}
+type Value = string | number | boolean | string[];
+/**
+ * What a unit's logic reads of what was filled in, by field id, one method per value kind. It has
+ * already been settled: checked against the form, defaults applied, a field not shown absent. The
+ * logic can't tell who filled it. Asking for a field the form doesn't have, or as the wrong kind,
+ * throws at once: that is a mistake in the unit, not in what was filled.
+ */
+export declare function filled(form: readonly FormField[], values: Readonly<Record<string, Value>>, secrets?: Readonly<Record<string, string>>): {
+    string: (id: string) => string | undefined;
+    number: (id: string) => number | undefined;
+    boolean: (id: string) => boolean | undefined;
+    strings: (id: string) => string[] | undefined;
+    /** Read the same way, and kept apart: only `apply` has them. */
+    secret: (id: string) => string | undefined;
+};
+export {};

package/dist/node_modules/@agentorg/sdk/dist/src/filled.js

@@ -0,0 +1,24 @@
+/**
+ * What a unit's logic reads of what was filled in, by field id, one method per value kind. It has
+ * already been settled: checked against the form, defaults applied, a field not shown absent. The
+ * logic can't tell who filled it. Asking for a field the form doesn't have, or as the wrong kind,
+ * throws at once: that is a mistake in the unit, not in what was filled.
+ */
+export function filled(form, values, secrets = {}) {
+    const read = (id, kind) => {
+        const field = form.find((one) => one.id === id);
+        if (!field)
+            throw new TypeError(`This unit's form has no field ${id}.`);
+        if (field.value !== kind)
+            throw new TypeError(`${id} holds a ${field.value}, not a ${kind}.`);
+        return (kind === "secret" ? secrets[id] : values[id]);
+    };
+    return {
+        string: (id) => read(id, "string"),
+        number: (id) => read(id, "number"),
+        boolean: (id) => read(id, "boolean"),
+        strings: (id) => read(id, "strings"),
+        /** Read the same way, and kept apart: only `apply` has them. */
+        secret: (id) => read(id, "secret"),
+    };
+}

package/dist/node_modules/@agentorg/sdk/dist/src/index.d.ts

@@ -1,4 +1,5 @@
 export { canonicalJson, hashOf, sha256 } from "./canonical.js";
 export { NotConnected, OutcomeUnknown, Refused, type RefusedCode } from "./errors.js";
-export { compareInterfaces, type DescribedInterface, defineInterface, describeInterface, type EventSpec, type Events, event, type HttpInterface, hashInterface, type Interface, type InterfaceSchemas, interfaceId, type JsonSchema, type MethodSpec, type Methods, method, normalizeSchema, type RpcInterface, type StreamInterface, } from "./interface.js";
-export { type CallInfo, type Context, type Duplex, defineActor, defineWidget, type EmitOptions, type Export, type ExportMap, type ExposedSlot, type FrameRoot, type Handlers, type HttpExport, type HttpSlot, type InterfaceMap, isFrameInterface, isModuleDefinition, type Log, MODULE, type ModuleDefinition, type ModuleSpec, type Placement, type RpcExport, type RpcSlot, type Slot, type StreamExport, type StreamSlot, type ViewExport, } from "./module.js";
+export { filled } from "./filled.js";
+export { compareInterfaces, type DescribedInterface, defineInterface, describeInterface, type EventSpec, type Events, event, hashInterface, type Interface, type InterfaceSchemas, interfaceId, type JsonSchema, type MethodSpec, type Methods, method, normalizeSchema, type RpcInterface, } from "./interface.js";
+export { type CallInfo, type Context, defineActor, type EmitOptions, type Export, type ExportMap, type ExposedSlot, type Handlers, type InterfaceMap, type Log, type ModuleDefinition, type ModuleSpec, type RpcExport, type RpcSlot, type Slot, } from "./module.js";

package/dist/node_modules/@agentorg/sdk/dist/src/index.js

@@ -1,4 +1,5 @@
 export { canonicalJson, hashOf, sha256 } from "./canonical.js";
 export { NotConnected, OutcomeUnknown, Refused } from "./errors.js";
+export { filled } from "./filled.js";
 export { compareInterfaces, defineInterface, describeInterface, event, hashInterface, interfaceId, method, normalizeSchema, } from "./interface.js";
-export { defineActor, defineWidget, isFrameInterface, isModuleDefinition, MODULE, } from "./module.js";
+export { defineActor, } from "./module.js";