@agentorg/cli 0.0.1 → 0.0.3

package/node_modules/@agentorg/shell/dist/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en" data-theme="dark">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>AgentOrg</title>
+    <link rel="stylesheet" href="/app.css" />
+    <script type="module" src="/app.js"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/node_modules/@agentorg/shell/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@agentorg/shell",
+  "version": "0.0.0",
+  "private": true,
+  "description": "The person's web shell for AgentOrg: their agents, their views and their settings.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.15"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    "./agent-bindings": {
+      "types": "./src/agent-bindings.ts",
+      "default": "./dist/agent-bindings.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/agent-bindings.ts"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json && node scripts/build.js"
+  },
+  "devDependencies": {
+    "@agentorg/interfaces": "0.0.0",
+    "@agentorg/sdk": "0.0.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "esbuild": "0.28.2",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "zod": "^4.6.7"
+  }
+}

package/node_modules/@agentorg/shell/src/agent-bindings.ts

@@ -0,0 +1,107 @@
+/**
+ * What a new agent gets: the assistant package's slots, each bound at creation (step 5, §4). The
+ * slots are its `logic` module's; `model` and `store` it always gets, and the person decides the
+ * rest in New agent's dialog. A grant that `needs` another is off while that one is: installing
+ * creates and starts Actors.
+ */
+export const AGENT_GRANTS = [
+  { slot: "model", what: "ChatGPT", iface: "llm.session@1", fixed: true },
+  { slot: "store", what: "its own storage", iface: "kv@1", fixed: true },
+  { slot: "layout", what: "your home", iface: "layout@1", fixed: false },
+  { slot: "packages", what: "install packages", iface: "hub.packages@1", fixed: false },
+  { slot: "actors", what: "create and run Actors", iface: "hub.actors@1", fixed: false },
+  { slot: "grants", what: "ask for connections", iface: "hub.grants@1", fixed: false },
+  { slot: "exports", what: "see what's offered", iface: "hub.exports@1", fixed: false },
+  {
+    slot: "installer",
+    what: "install Actors",
+    iface: "installer@1",
+    fixed: false,
+    needs: "actors",
+  },
+] as const;
+
+export type AgentSlot = (typeof AGENT_GRANTS)[number]["slot"];
+
+/**
+ * Where the app's first run records what it made, in the person's store: its `assistant` is the
+ * package New agent installs, by hash, never a package found by its name.
+ */
+export const FIRST_RUN = "app/first-run";
+
+/**
+ * The Actors a new agent's slots reach beside the built-ins: the person's own ChatGPT (what its
+ * `login` is bound to) and installer (what its `installer` is bound to).
+ */
+export interface AgentProviders {
+  chatgpt: string;
+  installer: string;
+}
+
+/** Where each slot is served: ChatGPT's session, the installer, the built-ins, the person's layout. */
+const PROVIDERS: Record<AgentSlot, (ids: AgentProviders) => { provider: string; export: string }> =
+  {
+    model: (ids) => ({ provider: ids.chatgpt, export: "model.session" }),
+    store: () => ({ provider: "storage", export: "kv" }),
+    layout: () => ({ provider: "person", export: "layout" }),
+    packages: () => ({ provider: "hub", export: "packages" }),
+    actors: () => ({ provider: "hub", export: "actors" }),
+    grants: () => ({ provider: "hub", export: "grants" }),
+    exports: () => ({ provider: "hub", export: "exports" }),
+    installer: (ids) => ({ provider: ids.installer, export: "installer.installer" }),
+  };
+
+/**
+ * A new agent's connections for `installer.install`: every grant but the ones switched off, which
+ * can't be `model` or `store`.
+ */
+export function agentConnections(
+  ids: AgentProviders,
+  off: ReadonlySet<string> = new Set(),
+): Record<string, { actor: string; export: string }> {
+  return Object.fromEntries(
+    AGENT_GRANTS.filter((grant) => grant.fixed || !off.has(grant.slot)).map((grant) => {
+      const { provider, export: name } = PROVIDERS[grant.slot](ids);
+      return [`logic.${grant.slot}`, { actor: provider, export: name }];
+    }),
+  );
+}
+
+type Call = (slot: string, method: string, input: unknown) => Promise<unknown>;
+
+/**
+ * The person's ChatGPT and installer: the Actors the person's `login` and `installer` are bound to,
+ * as the app's first run binds them (never an Actor found by its package's name).
+ */
+export async function agentProviders(call: Call): Promise<AgentProviders> {
+  const { bindings } = (await call("bindings", "list", { actor: "person" })) as {
+    bindings: { consumer: string; slot: string; provider: string }[];
+  };
+  const of = (slot: string) =>
+    bindings.find((b) => b.consumer === "person" && b.slot === slot)?.provider;
+  const chatgpt = of("login");
+  const installer = of("installer");
+  // Both are bound by the app's first run at its start; one that didn't finish tries again then.
+  if (!chatgpt || !installer)
+    throw new Error("AgentOrg isn't set up yet. Restart it to finish setting up.");
+  return { chatgpt, installer };
+}
+
+/**
+ * New agent itself: install the assistant package `assistant` named `name` through the person's
+ * `installer`, with `agentConnections` to the person's own ChatGPT and installer, and start it, all
+ * or nothing. `call` is the person's call (the shell's `/api`, or a test's). Returns the installer's
+ * answer: its id, the slots left unbound (the switched-off ones among them) and the seeds that
+ * didn't land.
+ */
+export async function installAgent(
+  call: Call,
+  agent: { assistant: string; name: string; off?: ReadonlySet<string> },
+): Promise<{ actorId: string; unbound: string[]; unseeded: string[] }> {
+  return (await call("installer", "install", {
+    package: agent.assistant,
+    name: agent.name,
+    connections: agentConnections(await agentProviders(call), agent.off),
+    start: true,
+  })) as { actorId: string; unbound: string[]; unseeded: string[] };
+}

package/node_modules/@agentorg/wire/dist/src/bytes.d.ts

@@ -0,0 +1,10 @@
+/** Bytes arriving in chunks, taken in exact sizes; each byte is copied once, however small the chunks. */
+export declare class ByteQueue {
+    #private;
+    get length(): number;
+    push(chunk: Uint8Array): void;
+    /** The first `size` bytes, removed; the caller checks `length` first. */
+    take(size: number): Uint8Array;
+    /** Everything left, removed. */
+    drain(): Uint8Array;
+}

package/node_modules/@agentorg/wire/dist/src/bytes.js

@@ -0,0 +1,42 @@
+/** Bytes arriving in chunks, taken in exact sizes; each byte is copied once, however small the chunks. */
+export class ByteQueue {
+    #chunks = [];
+    /** The first chunk not yet taken: shifting the array would be O(chunks) per chunk taken. */
+    #head = 0;
+    #length = 0;
+    get length() {
+        return this.#length;
+    }
+    push(chunk) {
+        if (!chunk.length)
+            return;
+        this.#chunks.push(chunk);
+        this.#length += chunk.length;
+    }
+    /** The first `size` bytes, removed; the caller checks `length` first. */
+    take(size) {
+        const out = new Uint8Array(size);
+        let filled = 0;
+        while (filled < size) {
+            const chunk = this.#chunks[this.#head];
+            const part = Math.min(chunk.length, size - filled);
+            out.set(chunk.subarray(0, part), filled);
+            filled += part;
+            if (part === chunk.length)
+                this.#head++;
+            else
+                this.#chunks[this.#head] = chunk.subarray(part);
+        }
+        // The taken chunks go once they are most of the array: linear over all the takes.
+        if (this.#head > 1024 && this.#head * 2 > this.#chunks.length) {
+            this.#chunks = this.#chunks.slice(this.#head);
+            this.#head = 0;
+        }
+        this.#length -= size;
+        return out;
+    }
+    /** Everything left, removed. */
+    drain() {
+        return this.take(this.#length);
+    }
+}

package/node_modules/@agentorg/wire/dist/src/frames.d.ts

@@ -0,0 +1,21 @@
+/** The largest JSON frame: 1 MiB. `stream` and `http` bodies are raw bytes, not frames. */
+export declare const MAX_FRAME: number;
+export declare class FrameError extends Error {
+    readonly name = "FrameError";
+}
+/** A frame: a 4-byte big-endian length, then that many bytes of UTF-8 JSON. */
+export declare function encodeFrame(value: unknown): Uint8Array;
+/**
+ * Reads frames from a byte stream, then hands over what follows them untouched: a stream starts
+ * with a header frame, and for `open` and `http` the rest is raw bytes.
+ */
+export declare class FrameReader {
+    #private;
+    constructor(readable: ReadableStream<Uint8Array>);
+    /** The next frame's value, or `undefined` when the stream ended cleanly between frames. */
+    next(): Promise<unknown>;
+    /** The bytes after the frames read so far, as a stream; the reader reads no more frames. */
+    rest(): ReadableStream<Uint8Array>;
+    /** Stop reading. Over a yamux stream that is a reset of both directions. */
+    cancel(reason?: unknown): Promise<void>;
+}

package/node_modules/@agentorg/wire/dist/src/frames.js

@@ -0,0 +1,90 @@
+import { ByteQueue } from "./bytes.js";
+/** The largest JSON frame: 1 MiB. `stream` and `http` bodies are raw bytes, not frames. */
+export const MAX_FRAME = 1024 * 1024;
+export class FrameError extends Error {
+    name = "FrameError";
+}
+const encoder = new TextEncoder();
+/** A frame: a 4-byte big-endian length, then that many bytes of UTF-8 JSON. */
+export function encodeFrame(value) {
+    const body = encoder.encode(JSON.stringify(value));
+    if (body.length > MAX_FRAME)
+        throw new FrameError(`A frame of ${body.length} bytes is over 1 MiB.`);
+    const frame = new Uint8Array(4 + body.length);
+    new DataView(frame.buffer).setUint32(0, body.length);
+    frame.set(body, 4);
+    return frame;
+}
+/**
+ * Reads frames from a byte stream, then hands over what follows them untouched: a stream starts
+ * with a header frame, and for `open` and `http` the rest is raw bytes.
+ */
+export class FrameReader {
+    #reader;
+    #buffer = new ByteQueue();
+    #done = false;
+    #handedOver = false;
+    constructor(readable) {
+        this.#reader = readable.getReader();
+    }
+    async #fill(size) {
+        while (this.#buffer.length < size) {
+            if (this.#done)
+                return false;
+            const { value, done } = await this.#reader.read();
+            if (done) {
+                this.#done = true;
+                return false;
+            }
+            this.#buffer.push(value);
+        }
+        return true;
+    }
+    /** The next frame's value, or `undefined` when the stream ended cleanly between frames. */
+    async next() {
+        if (this.#handedOver)
+            throw new FrameError("The rest of the stream was handed over.");
+        if (!(await this.#fill(4))) {
+            if (this.#buffer.length)
+                throw new FrameError("The stream ended inside a frame's length.");
+            return undefined;
+        }
+        const prefix = this.#buffer.take(4);
+        const length = new DataView(prefix.buffer).getUint32(0);
+        if (length > MAX_FRAME)
+            throw new FrameError(`A frame of ${length} bytes is over 1 MiB.`);
+        if (!(await this.#fill(length)))
+            throw new FrameError("The stream ended inside a frame.");
+        const body = this.#buffer.take(length);
+        try {
+            return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(body));
+        }
+        catch {
+            throw new FrameError("A frame isn't UTF-8 JSON.");
+        }
+    }
+    /** The bytes after the frames read so far, as a stream; the reader reads no more frames. */
+    rest() {
+        this.#handedOver = true;
+        let pending = this.#buffer.length ? this.#buffer.drain() : undefined;
+        return new ReadableStream({
+            pull: async (controller) => {
+                if (pending) {
+                    controller.enqueue(pending);
+                    pending = undefined;
+                    return;
+                }
+                const { value, done } = await this.#reader.read();
+                if (done)
+                    controller.close();
+                else
+                    controller.enqueue(value);
+            },
+            cancel: (reason) => this.#reader.cancel(reason),
+        }, { highWaterMark: 0 });
+    }
+    /** Stop reading. Over a yamux stream that is a reset of both directions. */
+    async cancel(reason) {
+        await this.#reader.cancel(reason);
+    }
+}

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

@@ -0,0 +1,4 @@
+export { encodeFrame, FrameError, FrameReader, MAX_FRAME } from "./frames.js";
+export { type Body, eventBody, type Header, HeaderError, input, parseBody, parseHeader, result, type WireError, type WireErrorName, wireError, } from "./ops.js";
+export { MAX_UNREAD, memoryPair, type WebSocketLike, webSocketChannel } from "./transports.js";
+export { type Duplex, GO_AWAY, Session, type SessionOptions, YamuxError, type YamuxStream, } from "./yamux.js";

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

@@ -0,0 +1,4 @@
+export { encodeFrame, FrameError, FrameReader, MAX_FRAME } from "./frames.js";
+export { eventBody, HeaderError, input, parseBody, parseHeader, result, wireError, } from "./ops.js";
+export { MAX_UNREAD, memoryPair, webSocketChannel } from "./transports.js";
+export { GO_AWAY, Session, YamuxError, } from "./yamux.js";

package/node_modules/@agentorg/wire/dist/src/ops.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The first frame of every stream says what the stream is for. A consumer's streams name its
+ * slot; the Hub, mediating, opens streams toward the provider naming its export and the caller.
+ *
+ * How each stream ends:
+ * - `hello`: the Hub answers with one body (`{result}` or `{error}`) and closes; on an error it
+ *   closes the channel too. Without `declares` the Actor keeps what it declared before; with it,
+ *   `declares` replaces that. The result is `{actorId, bound}`: the Actor's slots bound now. A
+ *   newer channel for an Actor replaces its older one; with `replace: false` the hello is refused
+ *   instead (`Refused`, code `connected`) while the Actor has a live channel. On a pipe the Hub
+ *   made for a package Actor's process, the hello names that Actor and carries no credential (the
+ *   pipe is the proof) and no `declares` (a package declares through its manifest).
+ * - `slot`: from the Hub, one of the Actor's slots was bound or unbound after its channel's hello
+ *   result was taken. The header is the whole message: the Hub closes its side, and the Actor
+ *   closes its side once it has read it (an open notice counts against its streams). Applied in
+ *   the order the streams arrive, on top of hello's `bound` (buffered until that result is read),
+ *   they give each slot's state. A `bound: true` for a slot already bound means its provider came
+ *   back after going away: the slot is usable again, and what was subscribed must be again. A
+ *   provider going away sends nothing; calls meanwhile are `NotConnected`.
+ * - `offer` and `withdraw`: the channel's own Actor offers an export at run time, or withdraws
+ *   one it offered; one body (`{result: {}}` or `{error}`) answers, then the stream closes.
+ * - `call`: the caller sends one `{input}` body and closes its side; the answer is one `{result}`
+ *   or `{error}` body, then the stream closes.
+ * - `subscribe`: `{event}` bodies flow until the subscriber resets the stream, or the provider
+ *   side closes it (with an `{error}` body first when it was refused).
+ * - `open` and `http`: the answering side sends exactly one body first, `{result: {}}` to accept
+ *   or `{error}` to refuse; after an accept, raw bytes flow both ways, each side closing its own
+ *   direction, and a reset ends both. The provider answers the Hub, and the Hub forwards that
+ *   answer. The opener may send bytes before the answer; they wait.
+ * Cancelling a reader of a yamux stream resets it.
+ */
+export type Header = 
+/**
+ * Admits a channel; its first stream. An external client's carries its credential and may
+ * declare (the Hub validates `declares`); a pipe's names its Actor only.
+ */
+{
+    op: "hello";
+    actorId: string;
+    credential?: string;
+    declares?: unknown;
+    replace?: false;
+} | {
+    op: "call";
+    slot: string;
+    method: string;
+} | {
+    op: "subscribe";
+    slot: string;
+    event: string;
+}
+/** Raw bytes in the interface's protocol, after the Hub validates `params`. */
+ | {
+    op: "open";
+    slot: string;
+    params: unknown;
+}
+/** HTTP/1.1 bytes. */
+ | {
+    op: "http";
+    slot: string;
+}
+/** Offer an export at run time, as a described interface; it lasts until withdrawn or disconnect. */
+ | {
+    op: "offer";
+    name: string;
+    interface: unknown;
+} | {
+    op: "withdraw";
+    name: string;
+}
+/** From the Hub to an Actor: one of its slots was bound or unbound. */
+ | {
+    op: "slot";
+    name: string;
+    bound: boolean;
+}
+/**
+ * From the Hub to a provider: the same four, naming its export, who is calling, and through which
+ * of the caller's slots (a provider keeping state per consumer keys it by both).
+ */
+ | {
+    op: "serve";
+    kind: "call" | "subscribe" | "open" | "http";
+    export: string;
+    caller: string;
+    slot: string;
+    method?: string;
+    event?: string;
+    params?: unknown;
+};
+export type WireErrorName = "NotConnected" | "Refused" | "OutcomeUnknown";
+/** How a refusal crosses the wire; the SDK maps it to its error classes. */
+export interface WireError {
+    error: {
+        name: WireErrorName;
+        code?: string;
+        message: string;
+    };
+}
+/** Every frame after a header is exactly one of these. */
+export type Body = {
+    input: unknown;
+} | {
+    result: unknown;
+} | {
+    event: unknown;
+} | WireError;
+export declare class HeaderError extends Error {
+    readonly name = "HeaderError";
+}
+/** A header frame checked for its shape: an unknown op or a missing field is refused. */
+export declare function parseHeader(value: unknown): Header;
+export declare const input: (value: unknown) => Body;
+export declare const result: (value: unknown) => Body;
+export declare const eventBody: (value: unknown) => Body;
+export declare const wireError: (name: WireErrorName, message: string, code?: string) => WireError;
+/** A body frame checked for its shape: exactly one of `input`, `result`, `event` or `error`. */
+export declare function parseBody(value: unknown): Body;

package/node_modules/@agentorg/wire/dist/src/ops.js

@@ -0,0 +1,92 @@
+export class HeaderError extends Error {
+    name = "HeaderError";
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const text = (record, key, max = 256) => {
+    const value = record[key];
+    if (typeof value !== "string" || !value || value.length > max)
+        throw new HeaderError(`The header's ${key} must be a non-empty string of at most ${max}.`);
+    return value;
+};
+/** A header frame checked for its shape: an unknown op or a missing field is refused. */
+export function parseHeader(value) {
+    if (!isRecord(value))
+        throw new HeaderError("A stream's first frame must be a header object.");
+    switch (value.op) {
+        case "hello":
+            return {
+                op: "hello",
+                actorId: text(value, "actorId"),
+                ...("credential" in value ? { credential: text(value, "credential", 4096) } : {}),
+                ...("declares" in value ? { declares: value.declares } : {}),
+                ...(value.replace === false ? { replace: false } : {}),
+            };
+        case "call":
+            return { op: "call", slot: text(value, "slot"), method: text(value, "method") };
+        case "subscribe":
+            return { op: "subscribe", slot: text(value, "slot"), event: text(value, "event") };
+        case "open":
+            if (!("params" in value))
+                throw new HeaderError("An open header needs params.");
+            return { op: "open", slot: text(value, "slot"), params: value.params };
+        case "http":
+            return { op: "http", slot: text(value, "slot") };
+        case "offer":
+            if (!isRecord(value.interface))
+                throw new HeaderError("An offer header needs an interface.");
+            return { op: "offer", name: text(value, "name"), interface: value.interface };
+        case "withdraw":
+            return { op: "withdraw", name: text(value, "name") };
+        case "slot":
+            if (typeof value.bound !== "boolean")
+                throw new HeaderError("A slot header needs bound.");
+            return { op: "slot", name: text(value, "name"), bound: value.bound };
+        case "serve": {
+            const kind = value.kind;
+            if (kind !== "call" && kind !== "subscribe" && kind !== "open" && kind !== "http")
+                throw new HeaderError("A serve header's kind must be call, subscribe, open or http.");
+            if (kind === "open" && !("params" in value))
+                throw new HeaderError("An open serve header needs params.");
+            return {
+                op: "serve",
+                kind,
+                export: text(value, "export"),
+                caller: text(value, "caller"),
+                slot: text(value, "slot"),
+                ...(kind === "call" ? { method: text(value, "method") } : {}),
+                ...(kind === "subscribe" ? { event: text(value, "event") } : {}),
+                ...(kind === "open" ? { params: value.params } : {}),
+            };
+        }
+        default:
+            throw new HeaderError(`Unknown op ${JSON.stringify(value.op)}.`);
+    }
+}
+export const input = (value) => ({ input: value });
+export const result = (value) => ({ result: value });
+export const eventBody = (value) => ({ event: value });
+export const wireError = (name, message, code) => ({
+    error: { name, message, ...(code === undefined ? {} : { code }) },
+});
+const NAMES = new Set(["NotConnected", "Refused", "OutcomeUnknown"]);
+/** A body frame checked for its shape: exactly one of `input`, `result`, `event` or `error`. */
+export function parseBody(value) {
+    if (!isRecord(value))
+        throw new HeaderError("A body frame must be an object.");
+    const keys = Object.keys(value);
+    if (keys.length !== 1)
+        throw new HeaderError("A body frame has exactly one key.");
+    const [key] = keys;
+    if (key === "input" || key === "result" || key === "event")
+        return value;
+    if (key === "error") {
+        const error = value.error;
+        if (isRecord(error) &&
+            NAMES.has(error.name) &&
+            typeof error.message === "string" &&
+            (error.code === undefined || typeof error.code === "string"))
+            return value;
+        throw new HeaderError("An error body needs a known name and a message.");
+    }
+    throw new HeaderError(`Unknown body ${JSON.stringify(key)}.`);
+}

package/node_modules/@agentorg/wire/dist/src/transports.d.ts

@@ -0,0 +1,29 @@
+import type { Duplex } from "./yamux.js";
+/** Two byte channels joined back to back, for tests and in-process peers. */
+export declare function memoryPair(): [Duplex, Duplex];
+/** The parts of the standard WebSocket API a channel needs; browsers, Node and `ws` all have them. */
+export interface WebSocketLike {
+    binaryType: string;
+    readonly readyState: number;
+    /** Bytes queued to send; writes wait while it is high. */
+    readonly bufferedAmount: number;
+    send(data: Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open" | "close" | "error" | "message", listener: (event: {
+        data?: unknown;
+        code?: number;
+        wasClean?: boolean;
+    }) => void): void;
+}
+/**
+ * The most received bytes a channel holds unread. A WebSocket can't pause reading, so past this
+ * the socket is closed with 1009 rather than buffered: a session moves legitimate data into stream
+ * buffers its windows bound, so only a peer flooding a session that has stopped reading gets here.
+ */
+export declare const MAX_UNREAD: number;
+/**
+ * A byte channel over a WebSocket, one binary message per write. It resolves once the socket is
+ * open. The readable ends when the socket closes cleanly with code 1000, and errors on any other
+ * close; closing the writable closes the socket.
+ */
+export declare function webSocketChannel(socket: WebSocketLike): Promise<Duplex>;