@agentorg/cli 0.0.2 → 0.0.4

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

@@ -0,0 +1,93 @@
+import type { DescribedInterface, Interface } from "./interface.js";
+import { type Context, type Duplex, type FrameRoot, type InterfaceMap, type Log, type ModuleDefinition } from "./module.js";
+/**
+ * What serves a bound slot, as the host side sees it: one function per kind. The runtime validates
+ * what goes in and comes out against the interface's schemas, as the Hub does.
+ */
+export interface SlotProvider {
+    call?(method: string, input: unknown): Promise<unknown>;
+    open?(params: unknown): Promise<Duplex>;
+    fetch?(request: Request): Promise<Response>;
+}
+/** A bound slot, seen from the host side: it delivers the provider's events to the module. */
+export interface Binding {
+    emit(event: string, payload: unknown): void;
+}
+/**
+ * A slot made at run time, as the host side gives it: the export's interface as described, whose
+ * it is, and how to reach it. Values pass as they are: the Hub checks them.
+ */
+export interface ExposedProvider {
+    described: DescribedInterface;
+    provider: {
+        actor: string;
+        export: string;
+    };
+    call(method: string, input: unknown): Promise<unknown>;
+    /** Deliver an event's payloads until it ends (`onEnd`); returns how to stop. */
+    subscribe(event: string, onEvent: (payload: unknown) => void, onEnd: () => void): () => void;
+}
+/** A mounted view, seen from the frame runtime's side. */
+export interface MountedView {
+    resize(size: unknown): void;
+    unmount(): void;
+}
+/**
+ * One module's context and the host side of it: bind providers to its slots and drive its
+ * exports. The test context and the real runtimes are both built on this, so a module behaves the
+ * same in each. Every call is checked in one order: the target is connected (`NotConnected`), the
+ * input fits its schema (`Refused`, code `invalid`), the target is implemented (`Refused`, code
+ * `unimplemented`), and the output fits its schema.
+ */
+export interface ModuleRuntime<S extends InterfaceMap, X extends InterfaceMap> {
+    readonly ctx: Context<S, X>;
+    start(): Promise<void>;
+    bind(slot: string, provider: SlotProvider): Binding;
+    unbind(slot: string): void;
+    /** A bound slot's provider came back after going away: its `onBind` handlers run again. */
+    usable(slot: string): void;
+    /**
+     * A slot made at run time is bound. Given again for one already here, it is usable again (its
+     * provider came back): its events resume.
+     */
+    expose(slot: string, provider: ExposedProvider): void;
+    /** A slot made at run time is gone with its binding. */
+    unexpose(slot: string): void;
+    /** Call an export's method for `caller`, the calling Actor as the Hub names it. */
+    call(exportName: string, method: string, input: unknown, caller: string): Promise<unknown>;
+    open(exportName: string, params: unknown, stream: Duplex): Promise<void>;
+    /**
+     * The two halves of `open`: checks that the export takes the stream (throwing a refusal at
+     * once), then returns what runs it. A remote host answers accept or refuse in between.
+     */
+    accepting(exportName: string, params: unknown): (stream: Duplex) => Promise<void>;
+    fetch(exportName: string, request: Request): Promise<Response>;
+    /** The checking half of `fetch`: refuses at once, or returns what serves each request. */
+    serving(exportName: string): (request: Request) => Promise<Response>;
+    mount(exportName: string, el: FrameRoot, options: unknown): MountedView;
+    withdrawn(exportName: string): boolean;
+}
+export interface RuntimeOptions {
+    self: {
+        actorId: string;
+        module: string;
+    };
+    log: Log;
+    /** Called with each event an export emits, after validation. */
+    onEmit(exportName: string, event: string, payload: unknown, to: string | undefined): void;
+    /** Called when the module listens to a slot's event, so a remote host can subscribe. */
+    onListen?(slot: string, event: string): void;
+    /** Called when the module offers an export at run time with `exports.add`, with its handle. */
+    onAdd?(name: string, iface: Interface, handle: {
+        withdraw(): void;
+    }): void;
+    /** Called when the module withdraws an export. */
+    onWithdraw?(name: string): void;
+}
+/**
+ * A value checked against a schema. A caller's misfit is `Refused` with code `invalid`, and nothing
+ * ran. A provider's is code `bad_output`: the provider ran and its reply or event broke the
+ * contract, so the call may have had its effect; read state before retrying.
+ */
+export declare function check(schema: unknown, value: unknown, where: string, code?: "invalid" | "bad_output"): unknown;
+export declare function createRuntime<S extends InterfaceMap, X extends InterfaceMap>(definition: ModuleDefinition<S, X>, options: RuntimeOptions): ModuleRuntime<S, X>;

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

@@ -0,0 +1,382 @@
+import { NotConnected, Refused } from "./errors.js";
+import { isFrameInterface, } from "./module.js";
+/**
+ * A value checked against a schema. A caller's misfit is `Refused` with code `invalid`, and nothing
+ * ran. A provider's is code `bad_output`: the provider ran and its reply or event broke the
+ * contract, so the call may have had its effect; read state before retrying.
+ */
+export function check(schema, value, where, code = "invalid") {
+    const result = schema.safeParse(value);
+    if (result.success)
+        return result.data;
+    const issue = result.error.issues[0];
+    throw new Refused(code, `${where}: ${issue ? `${issue.path.map(String).join(".") || "value"} ${issue.message}` : "invalid"}`);
+}
+const NAME = /^[a-z][A-Za-z0-9_]*$/;
+const own = (record, key) => Object.hasOwn(record, key) ? record[key] : undefined;
+export function createRuntime(definition, options) {
+    const slots = new Map();
+    const exported = new Map();
+    const slotHandle = (name, iface) => {
+        const state = { iface, binds: new Set(), unbinds: new Set(), listeners: new Map() };
+        slots.set(name, state);
+        const provider = () => {
+            if (!state.binding)
+                throw new NotConnected(name);
+            return state.binding.provider;
+        };
+        const base = {
+            get bound() {
+                return state.binding !== undefined;
+            },
+            onBind(fn) {
+                state.binds.add(fn);
+                return () => void state.binds.delete(fn);
+            },
+            onUnbind(fn) {
+                state.unbinds.add(fn);
+                return () => void state.unbinds.delete(fn);
+            },
+        };
+        switch (iface.kind) {
+            case "rpc":
+                return Object.assign(base, {
+                    call: Object.fromEntries(Object.entries(iface.methods).map(([method, spec]) => [
+                        method,
+                        async (input) => {
+                            const target = provider();
+                            const parsed = check(spec.input, input, `${name}.${method} input`);
+                            if (!target.call)
+                                throw new Refused("unimplemented", `${name} isn't served by an rpc provider.`);
+                            return check(spec.output, await target.call(method, parsed), `${name}.${method} output`, "bad_output");
+                        },
+                    ])),
+                    on(event, fn) {
+                        if (!own(iface.events, event))
+                            throw new TypeError(`${name} has no event ${event}.`);
+                        const set = state.listeners.get(event) ?? new Set();
+                        state.listeners.set(event, set);
+                        set.add(fn);
+                        options.onListen?.(name, event);
+                        return () => void set.delete(fn);
+                    },
+                });
+            case "stream":
+                return Object.assign(base, {
+                    async open(params) {
+                        const target = provider();
+                        const parsed = check(iface.open, params, `${name} open`);
+                        if (!target.open)
+                            throw new Refused("unimplemented", `${name} isn't served by a stream provider.`);
+                        return target.open(parsed);
+                    },
+                });
+            case "http":
+                return Object.assign(base, {
+                    async fetch(request) {
+                        const target = provider();
+                        if (!target.fetch)
+                            throw new Refused("unimplemented", `${name} isn't served by an http provider.`);
+                        return target.fetch(request);
+                    },
+                });
+        }
+    };
+    const exportHandle = (name, iface) => {
+        const state = { iface, withdrawn: false };
+        exported.set(name, state);
+        const live = () => {
+            if (state.withdrawn)
+                throw new NotConnected(name);
+        };
+        const withdraw = () => {
+            if (state.withdrawn)
+                return;
+            state.withdrawn = true;
+            options.onWithdraw?.(name);
+        };
+        const store = (impl) => {
+            live();
+            state.impl = impl;
+        };
+        if (isFrameInterface(iface))
+            return { implement: store, withdraw };
+        switch (iface.kind) {
+            case "rpc":
+                return {
+                    implement: store,
+                    emit(event, payload, emitting) {
+                        live();
+                        const spec = own(iface.events, event);
+                        if (!spec)
+                            throw new TypeError(`${name} has no event ${event}.`);
+                        options.onEmit(name, event, check(spec.payload, payload, `${name}.${event} payload`), emitting?.to);
+                    },
+                    withdraw,
+                };
+            case "stream":
+                return { accept: store, withdraw };
+            case "http":
+                return { serve: store, withdraw };
+        }
+    };
+    /** A connected export of the expected kind; implemented or not is checked after its input. */
+    const target = (name, kind) => {
+        const state = exported.get(name);
+        if (!state || state.withdrawn)
+            throw new NotConnected(name);
+        const frame = isFrameInterface(state.iface);
+        if (frame !== (kind === "frame") || (!frame && state.iface.kind !== kind))
+            throw new TypeError(`${name} isn't ${kind === "frame" ? "a ui.view@1" : `an ${kind}`} export.`);
+        return state;
+    };
+    const implemented = (state, name) => {
+        if (state.impl === undefined)
+            throw new Refused("unimplemented", `${name} hasn't been implemented yet.`);
+        return state.impl;
+    };
+    const exposed = new Map();
+    const exposedWatchers = new Set();
+    /** Run the `onExposed` handlers; one that throws is logged and the rest still run. */
+    const exposedChanged = () => {
+        const failed = (error) => options.log.error("An onExposed handler threw.", { error: String(error) });
+        for (const fn of [...exposedWatchers])
+            try {
+                const done = fn();
+                if (done instanceof Promise)
+                    done.catch(failed);
+            }
+            catch (error) {
+                failed(error);
+            }
+    };
+    /** Subscribe to an exposed slot's event while the module listens and nothing is live. */
+    const listenExposed = (slot, state, event) => {
+        const entry = state.events.get(event);
+        if (state.gone || !entry || entry.stop || !entry.fns.size)
+            return;
+        // A subscription may end before `subscribe` returns: then nothing is live.
+        let ended = false;
+        let stop;
+        stop = state.source.subscribe(event, (payload) => {
+            for (const fn of [...entry.fns])
+                try {
+                    fn(payload);
+                }
+                catch (error) {
+                    options.log.error("An event handler threw.", { slot, event, error: String(error) });
+                }
+        }, 
+        // Ended by the provider going: the interest stays for when it is usable again.
+        () => {
+            ended = true;
+            if (entry.stop === stop)
+                entry.stop = undefined;
+        });
+        if (!ended)
+            entry.stop = stop;
+    };
+    const exposedHandle = (slot, state) => {
+        const { described, provider } = state.source;
+        return Object.freeze({
+            slot,
+            described,
+            provider: Object.freeze({ actor: provider.actor, export: provider.export }),
+            call: Object.freeze(Object.fromEntries((described.kind === "rpc" ? Object.keys(described.methods) : []).map((method) => [
+                method,
+                async (input) => {
+                    if (state.gone)
+                        throw new NotConnected(slot);
+                    return state.source.call(method, input);
+                },
+            ]))),
+            on(event, fn) {
+                if (described.kind !== "rpc" || !own(described.events, event))
+                    throw new TypeError(`${slot} has no event ${event}.`);
+                const entry = state.events.get(event) ?? { fns: new Set() };
+                state.events.set(event, entry);
+                entry.fns.add(fn);
+                listenExposed(slot, state, event);
+                return () => {
+                    entry.fns.delete(fn);
+                    if (entry.fns.size)
+                        return;
+                    entry.stop?.();
+                    entry.stop = undefined;
+                };
+            },
+        });
+    };
+    const unexpose = (slot) => {
+        const state = exposed.get(slot);
+        if (!state)
+            return;
+        exposed.delete(slot);
+        state.gone = true;
+        for (const entry of state.events.values()) {
+            entry.stop?.();
+            entry.stop = undefined;
+        }
+        exposedChanged();
+    };
+    const expose = (slot, source) => {
+        const here = exposed.get(slot);
+        if (here &&
+            here.source.described.hash === source.described.hash &&
+            here.source.provider.actor === source.provider.actor &&
+            here.source.provider.export === source.provider.export) {
+            // Usable again: the same export, its provider back. What was listened to resumes.
+            here.source = source;
+            for (const [event, entry] of here.events) {
+                entry.stop?.();
+                entry.stop = undefined;
+                listenExposed(slot, here, event);
+            }
+            return;
+        }
+        if (here)
+            unexpose(slot);
+        // The handle reads the state, so it is made after; nothing reads it in between.
+        const state = { source, gone: false, events: new Map() };
+        state.handle = exposedHandle(slot, state);
+        exposed.set(slot, state);
+        exposedChanged();
+    };
+    const ctx = {
+        slots: Object.fromEntries(Object.entries(definition.slots).map(([name, iface]) => [name, slotHandle(name, iface)])),
+        exports: Object.assign(Object.fromEntries(Object.entries(definition.exports).map(([name, iface]) => [
+            name,
+            exportHandle(name, iface),
+        ])), {
+            add(name, iface) {
+                if (!NAME.test(name) || name === "add")
+                    throw new TypeError(`${JSON.stringify(name)} isn't a valid export name.`);
+                const existing = exported.get(name);
+                if (existing && !existing.withdrawn)
+                    throw new TypeError(`An export named ${name} is already offered.`);
+                const handle = exportHandle(name, iface);
+                options.onAdd?.(name, iface, handle);
+                return handle;
+            },
+        }),
+        self: options.self,
+        log: options.log,
+        exposed: () => Object.freeze([...exposed.values()].map((state) => state.handle)),
+        onExposed(fn) {
+            exposedWatchers.add(fn);
+            return () => void exposedWatchers.delete(fn);
+        },
+    };
+    const serving = (exportName) => {
+        const state = target(exportName, "http");
+        const handler = implemented(state, exportName);
+        return async (request) => handler(request);
+    };
+    const accepting = (exportName, params) => {
+        const state = target(exportName, "stream");
+        const parsed = check(state.iface.open, params, `${exportName} open`);
+        const handler = implemented(state, exportName);
+        return async (stream) => {
+            await handler(parsed, stream);
+        };
+    };
+    /** Run a slot's bind or unbind handlers; one that throws is logged and the rest still run. */
+    const notify = (slot, handlers) => {
+        const failed = (error) => options.log.error("A slot handler threw.", { slot, error: String(error) });
+        for (const fn of [...handlers])
+            try {
+                // A handler may be async; its rejection is logged the same way.
+                const done = fn();
+                if (done instanceof Promise)
+                    done.catch(failed);
+            }
+            catch (error) {
+                failed(error);
+            }
+    };
+    const unbind = (slot) => {
+        const state = slots.get(slot);
+        if (!state)
+            throw new TypeError(`No slot ${slot}.`);
+        if (!state.binding)
+            return;
+        state.binding = undefined;
+        notify(slot, state.unbinds);
+    };
+    return {
+        ctx,
+        async start() {
+            await definition.start(ctx);
+        },
+        bind(slot, provider) {
+            const state = slots.get(slot);
+            if (!state)
+                throw new TypeError(`No slot ${slot}.`);
+            unbind(slot);
+            const binding = { provider };
+            state.binding = binding;
+            notify(slot, state.binds);
+            return {
+                emit(event, payload) {
+                    const iface = state.iface;
+                    const spec = iface.kind === "rpc" ? own(iface.events, event) : undefined;
+                    if (!spec)
+                        throw new TypeError(`${slot} has no event ${event}.`);
+                    const value = check(spec.payload, payload, `${slot}.${event}`, "bad_output");
+                    if (state.binding !== binding)
+                        return;
+                    for (const fn of [...(state.listeners.get(event) ?? [])])
+                        fn(value);
+                },
+            };
+        },
+        unbind,
+        usable(slot) {
+            const state = slots.get(slot);
+            if (!state)
+                throw new TypeError(`No slot ${slot}.`);
+            if (state.binding)
+                notify(slot, state.binds);
+        },
+        expose,
+        unexpose,
+        async call(exportName, method, input, caller) {
+            const state = target(exportName, "rpc");
+            const spec = own(state.iface.methods, method);
+            if (!spec)
+                throw new TypeError(`${exportName} has no method ${method}.`);
+            const parsed = check(spec.input, input, `${exportName}.${method} input`);
+            const handler = own(implemented(state, exportName), method);
+            if (!handler)
+                throw new Refused("unimplemented", `${exportName}.${method} isn't implemented.`);
+            return check(spec.output, await handler(parsed, { caller }), `${exportName}.${method} output`, "bad_output");
+        },
+        accepting,
+        async open(exportName, params, stream) {
+            await accepting(exportName, params)(stream);
+        },
+        serving,
+        async fetch(exportName, request) {
+            return serving(exportName)(request);
+        },
+        mount(exportName, el, options) {
+            const state = target(exportName, "frame");
+            const methods = state.iface.methods;
+            const parsed = check(methods.mount?.input, options, `${exportName} mount`);
+            const view = implemented(state, exportName);
+            const cleanup = view.mount(el, parsed);
+            return {
+                resize(size) {
+                    const { size: checked } = check(methods.resize?.input, { size }, `${exportName} resize`);
+                    view.resize?.(checked);
+                },
+                unmount() {
+                    cleanup?.();
+                },
+            };
+        },
+        withdrawn(exportName) {
+            return exported.get(exportName)?.withdrawn ?? false;
+        },
+    };
+}

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

@@ -0,0 +1,7 @@
+/**
+ * A deterministic ustar archive of regular files: entries in path order, mode 0644, uid and gid 0,
+ * mtime 0 and no owner names, so equal trees give equal bytes.
+ */
+export declare function writeTar(files: Map<string, Uint8Array>): Uint8Array;
+/** The regular files of a ustar archive, refusing anything else and any checksum mismatch. */
+export declare function readTar(archive: Uint8Array): Map<string, Uint8Array>;

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

@@ -0,0 +1,71 @@
+/**
+ * A deterministic ustar archive of regular files: entries in path order, mode 0644, uid and gid 0,
+ * mtime 0 and no owner names, so equal trees give equal bytes.
+ */
+export function writeTar(files) {
+    const blocks = [];
+    for (const path of [...files.keys()].sort()) {
+        const data = files.get(path);
+        const name = new TextEncoder().encode(path);
+        if (name.length > 100)
+            throw new RangeError(`${path} is longer than a tar name allows.`);
+        const header = new Uint8Array(512);
+        header.set(name, 0);
+        const field = (offset, length, value) => header.set(new TextEncoder().encode(`${value.toString(8).padStart(length - 1, "0")}\0`), offset);
+        field(100, 8, 0o644);
+        field(108, 8, 0);
+        field(116, 8, 0);
+        field(124, 12, data.length);
+        field(136, 12, 0);
+        header.set(new TextEncoder().encode("        "), 148);
+        header[156] = "0".charCodeAt(0);
+        header.set(new TextEncoder().encode("ustar\u000000"), 257);
+        const sum = header.reduce((total, byte) => total + byte, 0);
+        header.set(new TextEncoder().encode(`${sum.toString(8).padStart(6, "0")}\0 `), 148);
+        blocks.push(header, data, new Uint8Array((512 - (data.length % 512)) % 512));
+    }
+    blocks.push(new Uint8Array(1024));
+    const out = new Uint8Array(blocks.reduce((total, block) => total + block.length, 0));
+    let offset = 0;
+    for (const block of blocks) {
+        out.set(block, offset);
+        offset += block.length;
+    }
+    return out;
+}
+/** A plain relative path: `/`-separated, with no empty, `.` or `..` segments or backslashes. */
+function safePath(path) {
+    return (path.length > 0 &&
+        !path.includes("\\") &&
+        !/^[A-Za-z]:/.test(path) &&
+        path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== ".."));
+}
+/** The regular files of a ustar archive, refusing anything else and any checksum mismatch. */
+export function readTar(archive) {
+    const files = new Map();
+    const text = (from, length) => new TextDecoder().decode(archive.subarray(from, from + length)).replace(/\0.*$/s, "");
+    let offset = 0;
+    while (offset + 512 <= archive.length) {
+        const header = archive.subarray(offset, offset + 512);
+        if (header.every((byte) => byte === 0))
+            return files;
+        const sum = header.reduce((total, byte, i) => total + (i >= 148 && i < 156 ? 32 : byte), 0);
+        if (Number.parseInt(text(offset + 148, 8).trim(), 8) !== sum)
+            throw new Error(`Corrupt tar header at byte ${offset}.`);
+        if (text(offset + 156, 1) !== "0")
+            throw new Error(`Only regular files are allowed in a package.`);
+        const path = text(offset, 100);
+        const size = Number.parseInt(text(offset + 124, 12).trim(), 8);
+        if (text(offset + 345, 155))
+            throw new Error("A package's tar uses no name prefix.");
+        if (!safePath(path))
+            throw new Error(`Unsafe path ${JSON.stringify(path)} in a package.`);
+        if (!Number.isInteger(size) || size < 0 || offset + 512 + size > archive.length)
+            throw new Error(`${path}'s size runs past the end of the archive.`);
+        if (files.has(path))
+            throw new Error(`${path} appears twice in a package.`);
+        files.set(path, archive.slice(offset + 512, offset + 512 + size));
+        offset += 512 + Math.ceil(size / 512) * 512;
+    }
+    throw new Error("The tar archive ends without its end marker.");
+}

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

@@ -0,0 +1,48 @@
+import type { z } from "zod";
+import { type Interface, type RpcInterface, type StreamInterface } from "./interface.js";
+import type { Duplex, Handlers, InterfaceMap, ModuleDefinition } from "./module.js";
+import { type Binding, type ModuleRuntime } from "./runtime.js";
+/** A fake bound to a slot in a test: handlers for `rpc`, a function for `stream` and `http`. */
+export type Provider<I extends Interface> = I extends RpcInterface<string, infer M> ? Partial<Handlers<M>> : I extends StreamInterface<string, infer O> ? (params: z.output<O>) => Duplex | Promise<Duplex> : (request: Request) => Response | Promise<Response>;
+export interface Emitted {
+    export: string;
+    event: string;
+    payload: unknown;
+    /** The one Actor it was sent to; absent when it went to every subscriber. */
+    to?: string;
+}
+export interface LogLine {
+    level: "info" | "warn" | "error";
+    message: string;
+    fields?: Record<string, unknown>;
+}
+/**
+ * A module run without a Hub, for tests: bind fakes to its slots, drive its exports, and read what
+ * it emitted and logged. It runs on the same runtime as a real module, so every call is validated
+ * as the Hub validates it: bad input is `Refused` with code `invalid`, and an unbound slot or a
+ * withdrawn export throws `NotConnected`.
+ */
+export interface TestContext<S extends InterfaceMap, X extends InterfaceMap> extends Omit<ModuleRuntime<S, X>, "bind" | "call" | "expose"> {
+    bind<K extends keyof S & string>(slot: K, provider: Provider<S[K]>): Binding;
+    /**
+     * Make a slot at run time, as `hub.grants.expose` does: an `rpc` export faked by `handlers`,
+     * whose values are checked against `iface` as the Hub checks them. `provider` names whose
+     * export it is (by default a made-up Actor's, `export`). Exposing the same slot again with the
+     * same interface and provider makes it usable again; `emit` sends its events.
+     */
+    expose<I extends RpcInterface>(slot: string, iface: I, handlers: Provider<I>, provider?: {
+        actor: string;
+        export: string;
+    }): Binding;
+    /** The slot made at run time goes, as when its binding is removed. */
+    unexpose(slot: string): void;
+    /** Call an export as `caller`; by default as the module's own Actor. */
+    call(exportName: string, method: string, input: unknown, caller?: string): Promise<unknown>;
+    readonly emitted: Emitted[];
+    readonly logs: LogLine[];
+}
+export declare function createTestContext<S extends InterfaceMap, X extends InterfaceMap>(definition: ModuleDefinition<S, X>, options?: {
+    actorId?: string;
+    module?: string;
+}): TestContext<S, X>;
+export type { Binding, MountedView } from "./runtime.js";