@agentorg/cli 0.0.1 → 0.0.3

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

@@ -0,0 +1,256 @@
+import { errorBodyOf, errorFromBody, OutcomeUnknown, Refused } from "./errors.js";
+import { isShellInterface } from "./frame-protocol.js";
+import { isFrameInterface, isModuleDefinition, } from "./module.js";
+import { createRuntime } from "./runtime.js";
+/**
+ * Run a view module in a frame, on the same runtime as a host module, so a view behaves as it does
+ * in tests. Every slot of `ui.shell@1` is served by the shell and always bound; every other slot is
+ * served over the port while the shell says it is bound. The shell drives `ui.view@1`: `mount`,
+ * `resize` and `unmount` reach the view's handle. Only `ui.view@1` is served among its exports.
+ */
+export function runFrame(options) {
+    const { port } = options;
+    const send = (message) => port.postMessage(message);
+    let nextId = 0;
+    const pending = new Map();
+    const request = (message, target) => new Promise((resolve, reject) => {
+        const id = ++nextId;
+        pending.set(id, { resolve, reject, target });
+        send({ ...message, id });
+    });
+    /** The view's runtime, once its start has finished. */
+    let runtime;
+    let definition;
+    let loading = false;
+    let mounted;
+    const bindings = new Map();
+    /**
+     * Until the view has started, which slots are bound: from load's snapshot, then from any notice
+     * meanwhile, while its bundle imports and while start runs.
+     */
+    let early = new Map();
+    /** Slot events the view listens to, each with its live subscription's id, if any. */
+    const listened = new Map();
+    const subscriptions = new Map();
+    const log = {
+        info: (message, fields) => send({ op: "log", level: "info", message, ...(fields ? { fields } : {}) }),
+        warn: (message, fields) => send({ op: "log", level: "warn", message, ...(fields ? { fields } : {}) }),
+        error: (message, fields) => send({ op: "log", level: "error", message, ...(fields ? { fields } : {}) }),
+    };
+    const subscribe = (slot, event) => {
+        const events = listened.get(slot) ?? new Map();
+        listened.set(slot, events);
+        if (!events.has(event))
+            events.set(event, undefined);
+        if (!bindings.has(slot) || events.get(event) !== undefined)
+            return;
+        const sub = ++nextId;
+        subscriptions.set(sub, { slot, event });
+        events.set(event, sub);
+        send({ op: "subscribe", sub, slot, event });
+    };
+    /** Stop a slot's live subscriptions; the interest stays for when it is usable again. */
+    const stopAll = (slot, tell) => {
+        const events = listened.get(slot);
+        for (const [event, sub] of events ?? []) {
+            if (sub === undefined)
+                continue;
+            subscriptions.delete(sub);
+            events?.set(event, undefined);
+            if (tell)
+                send({ op: "unsubscribe", sub });
+        }
+    };
+    const resubscribe = (slot) => {
+        stopAll(slot, true);
+        for (const event of listened.get(slot)?.keys() ?? [])
+            subscribe(slot, event);
+    };
+    const bind = (slot) => {
+        if (!runtime)
+            return;
+        bindings.set(slot, runtime.bind(slot, {
+            call: (method, input) => request({ op: "call", slot, method, input }, slot),
+            open: async () => {
+                throw new Refused("unimplemented", `${slot}: a view's stream slots aren't served yet.`);
+            },
+            fetch: async () => {
+                throw new Refused("unimplemented", `${slot}: a view's http slots aren't served yet.`);
+            },
+        }));
+        resubscribe(slot);
+    };
+    const onSlot = (slot, bound) => {
+        if (early)
+            return void early.set(slot, bound);
+        const iface = definition && Object.hasOwn(definition.slots, slot) ? definition.slots[slot] : undefined;
+        // ui.shell@1 is the shell's, always bound; the shell never names it.
+        if (!runtime || !iface || isShellInterface(iface))
+            return;
+        if (!bound) {
+            bindings.delete(slot);
+            stopAll(slot, true);
+            return runtime.unbind(slot);
+        }
+        if (bindings.has(slot)) {
+            // Its provider came back: what was missed is read again in onBind, and events resume.
+            resubscribe(slot);
+            return runtime.usable(slot);
+        }
+        bind(slot);
+    };
+    const viewExport = () => {
+        for (const [name, iface] of Object.entries(definition?.exports ?? {}))
+            if (isFrameInterface(iface))
+                return name;
+        throw new Refused("unimplemented", "This module exports no ui.view@1.");
+    };
+    const answer = async (id, run) => {
+        try {
+            send({ op: "reply", id, result: (await run()) ?? {} });
+        }
+        catch (error) {
+            send({ op: "reply", id, error: errorBodyOf(error) });
+        }
+    };
+    const handle = (message) => {
+        switch (message.op) {
+            case "load":
+                return answer(message.id, async () => {
+                    if (runtime || loading)
+                        throw new Refused("state", "This frame has loaded a view already.");
+                    loading = true;
+                    for (const [slot, isBound] of Object.entries(message.slots))
+                        early?.set(slot, isBound);
+                    try {
+                        const loaded = (await options.load(message.src));
+                        const found = loaded?.default;
+                        if (!isModuleDefinition(found) || found.placement !== "view")
+                            throw new Refused("invalid", `${message.src} isn't a view module.`);
+                        definition = found;
+                        const created = createRuntime(found, {
+                            self: message.self,
+                            log,
+                            // A view serves only ui.view@1, which the shell drives directly; nothing reaches its
+                            // other exports, so their events go nowhere.
+                            onEmit: () => { },
+                            onListen: subscribe,
+                        });
+                        // As in a host module: start implements and registers handlers, then slots bind, so
+                        // each bound slot's onBind runs once it is usable.
+                        await created.start();
+                        runtime = created;
+                        for (const [slot, iface] of Object.entries(found.slots))
+                            if (isShellInterface(iface))
+                                bindings.set(slot, created.bind(slot, {
+                                    call: (method, input) => request({ op: "shell", method, input }, slot),
+                                }));
+                        const bound = early;
+                        early = undefined;
+                        for (const [slot, isBound] of bound ?? [])
+                            if (isBound)
+                                onSlot(slot, true);
+                    }
+                    catch (error) {
+                        // Nothing is half-loaded: the frame can be asked to load again.
+                        definition = undefined;
+                        early = new Map();
+                        throw error;
+                    }
+                    finally {
+                        loading = false;
+                    }
+                });
+            case "slot":
+                return onSlot(message.name, message.bound);
+            case "mount":
+                return answer(message.id, () => {
+                    if (!runtime)
+                        throw new Refused("state", "Nothing is loaded to mount.");
+                    if (mounted)
+                        throw new Refused("state", "The view is mounted already.");
+                    options.theme?.(message.theme);
+                    mounted = runtime.mount(viewExport(), options.root, {
+                        theme: message.theme,
+                        size: message.size,
+                    });
+                });
+            case "resize":
+                return answer(message.id, () => {
+                    if (!mounted)
+                        throw new Refused("state", "The view isn't mounted.");
+                    mounted.resize(message.size);
+                });
+            case "unmount":
+                return answer(message.id, () => {
+                    const view = mounted;
+                    mounted = undefined;
+                    view?.unmount();
+                });
+            case "event": {
+                const subscription = subscriptions.get(message.sub);
+                if (!subscription)
+                    return;
+                try {
+                    bindings.get(subscription.slot)?.emit(subscription.event, message.payload);
+                }
+                catch (error) {
+                    log.warn("An event didn't fit its schema.", { ...subscription, error: String(error) });
+                }
+                return;
+            }
+            case "end": {
+                // Ended by an unbind or the provider going: the interest stays for when it is usable again.
+                const subscription = subscriptions.get(message.sub);
+                if (!subscription)
+                    return;
+                subscriptions.delete(message.sub);
+                const events = listened.get(subscription.slot);
+                if (events?.get(subscription.event) === message.sub)
+                    events.set(subscription.event, undefined);
+                return;
+            }
+            case "reply": {
+                const waiting = pending.get(message.id);
+                if (!waiting)
+                    return;
+                pending.delete(message.id);
+                if ("error" in message)
+                    waiting.reject(errorFromBody(message.error, waiting.target));
+                else
+                    waiting.resolve(message.result);
+                return;
+            }
+        }
+    };
+    port.onmessage = (event) => {
+        try {
+            void handle(event.data);
+        }
+        catch (error) {
+            log.error("The frame couldn't handle a message from the shell.", { error: String(error) });
+        }
+    };
+    let told;
+    return {
+        size(height) {
+            // Empty before mount and after unmount: those aren't the view's size.
+            if (!mounted || height === told)
+                return;
+            told = height;
+            send({ op: "size", height });
+        },
+        failed(error) {
+            log.error(error instanceof Error ? error.message : String(error), {
+                ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
+            });
+        },
+        close() {
+            port.onmessage = null;
+            for (const [, waiting] of pending)
+                waiting.reject(new OutcomeUnknown("The frame closed."));
+            pending.clear();
+            port.close();
+        },
+    };
+}

package/node_modules/@agentorg/sdk/dist/src/host-main.js

@@ -0,0 +1,60 @@
+// The program the Hub spawns for a package Actor: `runner.js <package dir> <actorId>`, with its
+// channel to the Hub on fd 3. It is bundled into one file, so the process needs to read only
+// that file and the package's folder.
+import { Socket } from "node:net";
+import { Duplex as NodeDuplex } from "node:stream";
+import { runHost } from "./host.js";
+const [packageDir, actorId] = process.argv.slice(2);
+if (!packageDir || !actorId) {
+    process.stderr.write("Usage: runner.js <package dir> <actorId>\n");
+    process.exit(2);
+}
+/** Anything as text, even what can't say itself (no prototype, a throwing `toString`). */
+const text = (value) => {
+    try {
+        return String(value);
+    }
+    catch {
+        return "[unprintable]";
+    }
+};
+/** What JSON can't hold, as text: an error by its name and message, a bigint by its digits. */
+const plain = (_key, value) => value instanceof Error
+    ? `${text(value.name)}: ${text(value.message)}`
+    : typeof value === "bigint"
+        ? String(value)
+        : value;
+/**
+ * One JSON line per log call, on stderr, which the Hub keeps as the Actor's log: a module's
+ * `ctx.log`, or the runner's own (no module). Logging never throws: data JSON can't hold (a cycle)
+ * is written as text.
+ */
+const logFor = (module) => {
+    const line = (level) => (message, data) => {
+        const entry = (fields) => JSON.stringify({
+            level,
+            message: text(message),
+            ...(fields === undefined ? {} : { data: fields }),
+            ...(module === undefined ? {} : { module }),
+            at: new Date().toISOString(),
+        }, plain);
+        let written;
+        try {
+            written = entry(data);
+        }
+        catch {
+            written = entry(text(data));
+        }
+        process.stderr.write(`${written}\n`);
+    };
+    return { info: line("info"), warn: line("warn"), error: line("error") };
+};
+// The Hub's stop. Handled, it reaches the process even as PID 1 of a PID namespace, where an
+// unhandled SIGTERM from outside is ignored.
+process.on("SIGTERM", () => process.exit(0));
+const pipe = new Socket({ fd: 3, readable: true, writable: true });
+const channel = NodeDuplex.toWeb(pipe);
+const host = await runHost({ packageDir, actorId, channel, log: logFor });
+// The Hub going away ends the process: there is nothing left to serve.
+await host.channel.closed;
+process.exit(0);

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

@@ -0,0 +1,25 @@
+import { type Channel } from "./client.js";
+import { type Duplex, type Log } from "./module.js";
+export interface RunHostOptions {
+    /** The package's folder: `agentorg.json` and `dist/<module>.js`. */
+    packageDir: string;
+    /** The Actor this process runs, as the Hub named it. */
+    actorId: string;
+    /** The pipe to the Hub. */
+    channel: Duplex;
+    /** Where each module's `ctx.log` lines go, and (with no module) the runner's own. */
+    log(module?: string): Log;
+}
+export interface Host {
+    readonly channel: Channel;
+    /** The host modules running, by name. */
+    readonly modules: readonly string[];
+}
+/**
+ * Run a package Actor's host modules over the pipe the Hub made for its process. Each module gets
+ * its own runtime, the same one `connect()` and the test context use, with its slots and exports
+ * named `<module>.<name>` on the wire. Every module's `start` runs before the hello, so the Hub
+ * never reaches an export before it is implemented; then slots are bound as the Hub says, and each
+ * `serve` stream goes to the module its export names. A `start` that throws is thrown from here.
+ */
+export declare function runHost(options: RunHostOptions): Promise<Host>;

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

@@ -0,0 +1,87 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { openChannel } from "./client.js";
+import { isModuleDefinition } from "./module.js";
+import { localServe, ModuleHost, noModule } from "./module-host.js";
+import { createRuntime } from "./runtime.js";
+/**
+ * Run a package Actor's host modules over the pipe the Hub made for its process. Each module gets
+ * its own runtime, the same one `connect()` and the test context use, with its slots and exports
+ * named `<module>.<name>` on the wire. Every module's `start` runs before the hello, so the Hub
+ * never reaches an export before it is implemented; then slots are bound as the Hub says, and each
+ * `serve` stream goes to the module its export names. A `start` that throws is thrown from here.
+ */
+export async function runHost(options) {
+    const manifest = JSON.parse(await readFile(join(options.packageDir, "agentorg.json"), "utf8"));
+    const hosts = new Map();
+    for (const [name, module] of Object.entries(manifest.modules)) {
+        if (module.placement !== "host")
+            continue;
+        const loaded = (await import(__rewriteRelativeImportExtension(pathToFileURL(join(options.packageDir, "dist", `${name}.js`)).href)));
+        const definition = loaded.default;
+        if (!isModuleDefinition(definition))
+            throw new Error(`dist/${name}.js doesn't export a module definition.`);
+        const log = options.log(name);
+        const host = new ModuleHost(`${name}.`, definition.slots, log);
+        host.runtime = createRuntime(definition, {
+            self: { actorId: options.actorId, module: name },
+            log,
+            ...host.hooks(),
+        });
+        hosts.set(name, host);
+    }
+    // Every module's start, in the manifest's order, before the Hub can reach any of them.
+    for (const host of hosts.values())
+        await host.runtime.start();
+    /** The module a wire name belongs to, and the name within it. */
+    const route = (name) => {
+        const dot = name.indexOf(".");
+        const host = dot > 0 ? hosts.get(name.slice(0, dot)) : undefined;
+        return host && [host, name.slice(dot + 1)];
+    };
+    const routed = (serve) => {
+        const found = route(serve.export);
+        if (!found)
+            throw noModule(serve.export);
+        return [found[0].serve, localServe(serve, found[1])];
+    };
+    const channel = await openChannel({
+        channel: options.channel,
+        actorId: options.actorId,
+        log: options.log(),
+        onSlot(name, bound) {
+            const found = route(name);
+            found?.[0].onSlot(found[1], bound);
+        },
+        serve: {
+            call: (serve, value) => {
+                const [handlers, local] = routed(serve);
+                return handlers.call(local, value);
+            },
+            subscribe: (serve, send, end) => {
+                const [handlers, local] = routed(serve);
+                return handlers.subscribe(local, send, end);
+            },
+            accept: (serve) => {
+                const [handlers, local] = routed(serve);
+                return handlers.accept(local);
+            },
+            serveHttp: (serve) => {
+                const [handlers, local] = routed(serve);
+                return handlers.serveHttp(local);
+            },
+        },
+    });
+    for (const host of hosts.values())
+        host.attach(channel);
+    return { channel, modules: [...hosts.keys()] };
+}

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

@@ -0,0 +1,4 @@
+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 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";

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

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

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

@@ -0,0 +1,114 @@
+import { z } from "zod";
+/** One request and its reply on an `rpc` interface. */
+export interface MethodSpec<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> {
+    readonly input: I;
+    readonly output: O;
+}
+/** One event an `rpc` interface's provider emits: live, delivered at most once. */
+export interface EventSpec<P extends z.ZodType = z.ZodType> {
+    readonly payload: P;
+}
+export type Methods = Record<string, MethodSpec>;
+export type Events = Record<string, EventSpec>;
+type NoEvents = Record<never, EventSpec>;
+export declare function method<I extends z.ZodType, O extends z.ZodType>(spec: {
+    input: I;
+    output: O;
+}): MethodSpec<I, O>;
+export declare function event<P extends z.ZodType>(payload: P): EventSpec<P>;
+interface Named<N extends string, V extends number = number> {
+    readonly name: N;
+    readonly major: V;
+}
+/** Requests, replies and events, each typed by a schema; one stream per call or subscription. */
+export interface RpcInterface<N extends string = string, M extends Methods = Methods, E extends Events = Events, V extends number = number> extends Named<N, V> {
+    readonly kind: "rpc";
+    readonly methods: M;
+    readonly events: E;
+}
+/** Raw bytes in a named protocol, the L4 shape; opening a stream takes parameters. */
+export interface StreamInterface<N extends string = string, O extends z.ZodType = z.ZodType> extends Named<N> {
+    readonly kind: "stream";
+    readonly protocol: string;
+    readonly open: O;
+}
+/** HTTP/1.1 requests and responses on streams, the L7 shape. */
+export interface HttpInterface<N extends string = string> extends Named<N> {
+    readonly kind: "http";
+}
+export type Interface = RpcInterface | StreamInterface | HttpInterface;
+/**
+ * A named, versioned contract, identified by `name@major`. A slot binds only to an export of the
+ * same `name@major` whose schemas hash the same.
+ */
+export declare function defineInterface<const N extends string, M extends Methods, E extends Events = NoEvents, const V extends number = number>(spec: {
+    name: N;
+    major: V;
+    kind: "rpc";
+    methods: M;
+    events?: E;
+}): RpcInterface<N, M, E, V>;
+export declare function defineInterface<const N extends string, O extends z.ZodType>(spec: {
+    name: N;
+    major: number;
+    kind: "stream";
+    protocol: string;
+    open: O;
+}): StreamInterface<N, O>;
+export declare function defineInterface<const N extends string>(spec: {
+    name: N;
+    major: number;
+    kind: "http";
+}): HttpInterface<N>;
+export type JsonSchema = Record<string, unknown>;
+/** An interface's identity and JSON Schemas, as the manifest records them. */
+export type InterfaceSchemas = {
+    id: string;
+} & ({
+    kind: "rpc";
+    methods: Record<string, {
+        input: JsonSchema;
+        output: JsonSchema;
+    }>;
+    events: Record<string, JsonSchema>;
+} | {
+    kind: "stream";
+    protocol: string;
+    open: JsonSchema;
+} | {
+    kind: "http";
+});
+/** An interface's identity, JSON Schemas and hash. */
+export type DescribedInterface = InterfaceSchemas & {
+    hash: string;
+};
+/** `name@major`, the identity a slot and an export must share. */
+export declare function interfaceId(iface: Interface): string;
+/**
+ * The JSON Schema as hashed, with nothing an equal contract could vary: no `$schema` (it names
+ * zod's dialect, not the contract), `required` sorted (field order isn't part of the contract) and
+ * `$defs` renamed `d0`, `d1`, … in the order a key-sorted walk first reaches them (zod numbers them
+ * in declaration order). Union options and enum values keep their order.
+ */
+export declare function normalizeSchema(schema: JsonSchema): JsonSchema;
+/**
+ * The hash of an interface: SHA-256 over the canonical JSON of its identity and normalized JSON
+ * Schemas. Everything in those schemas is contract, `.describe()` text included, so a reader can
+ * recompute the hash from the manifest alone.
+ */
+export declare function hashInterface(schemas: InterfaceSchemas): string;
+/** The interface as the manifest records it: identity, JSON Schemas and hash. */
+export declare function describeInterface(iface: Interface): DescribedInterface;
+/**
+ * Whether a slot's interface and an export's can be bound: `same` is the same `name@major` with
+ * the same hash; `conflict` is the same `name@major` with another hash, which the Hub refuses;
+ * `unrelated` is another interface.
+ */
+export declare function compareInterfaces(a: {
+    id: string;
+    hash: string;
+}, b: {
+    id: string;
+    hash: string;
+}): "same" | "unrelated" | "conflict";
+export {};