@agentorg/cli 0.0.5 → 0.0.7

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

@@ -0,0 +1,30 @@
+{
+  "name": "@agentorg/manager",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Management: creating agents and connecting skills and MCP servers to them",
+  "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",
+    "yaml": "2.9.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@agentorg/hub": "0.0.0"
+  }
+}

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

@@ -0,0 +1,34 @@
+import { type Log } from "@agentorg/sdk";
+import type { Secrets, Spec } from "./kinds.js";
+/**
+ * One connection to one MCP server, and its Actor. The Actor stays on the Hub while the server
+ * comes and goes: the connection is kept up, tried again after a backoff when it ends, and says
+ * `changed` whenever the tools it can offer change, that being up or down too.
+ */
+export interface Timing {
+    pingEveryMs?: number;
+    firstDelayMs?: number;
+}
+export declare class Connection {
+    #private;
+    /** `hide` names tools of the server that are never offered or run through this connection. */
+    constructor(spec: Spec, secrets: Secrets, log: Log, timing?: Timing, hide?: readonly string[]);
+    /** Join the Hub as the connection's Actor, offering its tools. */
+    join(hub: {
+        hubUrl: string;
+        actorId: string;
+        credential: string;
+    }): Promise<void>;
+    /** Keep the server connected, from now until the connection ends. */
+    run(): void;
+    status(): {
+        state: "connected" | "connecting" | "down";
+        detail?: string | undefined;
+        tools: {
+            name: string;
+            description?: string | undefined;
+        }[];
+    };
+    /** End it: the server is let go and the Actor leaves the Hub. */
+    end(): Promise<void>;
+}

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

@@ -0,0 +1,296 @@
+import { tools } from "@agentorg/interfaces";
+import { Refused } from "@agentorg/sdk";
+import { connect } from "@agentorg/sdk/client";
+import { Client, ProtocolError, SdkError, SdkErrorCode, StreamableHTTPClientTransport, } from "@modelcontextprotocol/client";
+import { getDefaultEnvironment, StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { publicFetch } from "./public.js";
+/** How often a connection asks its server whether it is there, and how long it waits. */
+const PING_EVERY_MS = 30_000;
+const PING_TIMEOUT_MS = 10_000;
+const FIRST_DELAY_MS = 1_000;
+const MAX_DELAY_MS = 60_000;
+/** A server up this long is well again: the next failure starts over from the first delay. */
+const STEADY_MS = 10 * 60_000;
+/** What `tools@1` carries: its limits, and room in one frame for a list. */
+const NAME_MAX = 128;
+const DESCRIPTION_MAX = 16_384;
+const STATUS_DESCRIPTION_MAX = 512;
+const OUTPUT_MAX = 200_000;
+const LIST_ROOM = 900 * 1024;
+const cut = (text, max) => text.length <= max ? text : `${text.slice(0, max - 40)}… [cut: ${text.length} characters]`;
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+/** The tools a server lists, fitted to what `tools@1` can carry; what can't be is logged. */
+function fit(listed, log) {
+    const kept = [];
+    let room = LIST_ROOM;
+    for (const tool of listed) {
+        const entry = {
+            name: tool.name,
+            ...(tool.description ? { description: cut(tool.description, DESCRIPTION_MAX) } : {}),
+            inputSchema: tool.inputSchema,
+        };
+        const size = Buffer.byteLength(JSON.stringify(entry));
+        if (tool.name.length < 1 || tool.name.length > NAME_MAX || size > room) {
+            log.warn(`Left out the tool ${tool.name.slice(0, NAME_MAX)}: it doesn't fit tools@1.`);
+            continue;
+        }
+        room -= size;
+        kept.push(entry);
+    }
+    return kept;
+}
+/** A tool's result as text: its text blocks as they are, and what else it held by name. */
+function textOf(result) {
+    const parts = (result.content ?? []).map((block) => {
+        switch (block.type) {
+            case "text":
+                return block.text;
+            case "resource":
+                return "text" in block.resource ? block.resource.text : `[resource ${block.resource.uri}]`;
+            case "resource_link":
+                return `[resource ${block.uri}]`;
+            default:
+                return `[${block.type}]`;
+        }
+    });
+    if (parts.length === 0 && result.structuredContent)
+        return JSON.stringify(result.structuredContent);
+    return parts.join("\n");
+}
+function transportOf(spec, secrets, log) {
+    if (spec.kind === "url") {
+        const { token } = secrets;
+        return new StreamableHTTPClientTransport(new URL(spec.url), {
+            ...(token ? { requestInit: { headers: { Authorization: `Bearer ${token}` } } } : {}),
+            // Checked at each request, so a name that later points home is refused then.
+            ...(spec.public ? { fetch: publicFetch } : {}),
+        });
+    }
+    const transport = new StdioClientTransport({
+        command: spec.command,
+        args: spec.args ?? [],
+        env: { ...getDefaultEnvironment(), ...secrets },
+        stderr: "pipe",
+        ...(spec.cwd ? { cwd: spec.cwd } : {}),
+    });
+    // By whole lines, so a secret the server prints can't be split past the log's scrubbing.
+    let line = "";
+    transport.stderr?.on("data", (chunk) => {
+        const parts = (line + String(chunk)).split("\n");
+        line = (parts.pop() ?? "").slice(-65_536);
+        for (const part of parts)
+            log.warn(part);
+    });
+    return transport;
+}
+export class Connection {
+    #state = "connecting";
+    #detail;
+    #tools = [];
+    #mcp;
+    #hub;
+    #ended = false;
+    #wake;
+    /** Ends the current session at once, whatever its transport is still waiting for. */
+    #lose;
+    #running;
+    #spec;
+    #hide;
+    #secrets;
+    #log;
+    #scrub;
+    #pingEveryMs;
+    #firstDelayMs;
+    /** `hide` names tools of the server that are never offered or run through this connection. */
+    constructor(spec, secrets, log, timing = {}, hide = []) {
+        this.#hide = new Set(hide);
+        this.#spec = spec;
+        this.#secrets = secrets;
+        this.#pingEveryMs = timing.pingEveryMs ?? PING_EVERY_MS;
+        this.#firstDelayMs = timing.firstDelayMs ?? FIRST_DELAY_MS;
+        // What is secret never leaves in a log, a detail or an error: its values, and an address's query.
+        const query = spec.kind === "url" ? new URL(spec.url).search : "";
+        // A value that spans lines is also hidden line by line, as a server prints it; longest first.
+        const hidden = [
+            ...Object.values(secrets).flatMap((value) => [
+                value,
+                ...value.split(/\r?\n/).filter((line) => line.length > 0),
+            ]),
+            ...(query.length > 1 ? [query] : []),
+        ].sort((a, b) => b.length - a.length);
+        this.#scrub = (text) => hidden.reduce((out, value) => out.replaceAll(value, "[hidden]"), text);
+        const clean = (message) => cut(this.#scrub(message), 4000);
+        this.#log = {
+            info: (message, fields) => log.info(clean(message), fields),
+            warn: (message, fields) => log.warn(clean(message), fields),
+            error: (message, fields) => log.error(clean(message), fields),
+        };
+    }
+    /** Join the Hub as the connection's Actor, offering its tools. */
+    async join(hub) {
+        this.#hub = await connect({
+            ...hub,
+            exports: { tools },
+            log: this.#log,
+            start: (ctx) => {
+                ctx.exports.tools.implement({
+                    list: () => {
+                        this.#requireUp();
+                        return { tools: this.#tools };
+                    },
+                    call: ({ name, arguments: args }) => this.#call(name, args),
+                });
+            },
+        });
+    }
+    /** Keep the server connected, from now until the connection ends. */
+    run() {
+        this.#running = this.#keepUp();
+    }
+    status() {
+        return {
+            state: this.#state,
+            ...(this.#detail ? { detail: this.#detail } : {}),
+            tools: this.#tools.map((tool) => ({
+                name: tool.name,
+                ...(tool.description ? { description: cut(tool.description, STATUS_DESCRIPTION_MAX) } : {}),
+            })),
+        };
+    }
+    /** End it: the server is let go and the Actor leaves the Hub. */
+    async end() {
+        this.#ended = true;
+        this.#wake?.();
+        this.#lose?.();
+        await this.#mcp?.close().catch(() => { });
+        await this.#running;
+        this.#hub?.close();
+    }
+    #requireUp() {
+        if (this.#state !== "connected")
+            throw new Refused("not_connected", this.#detail ?? "The server isn't connected yet.");
+    }
+    async #call(name, args) {
+        this.#requireUp();
+        if (!this.#tools.some((tool) => tool.name === name))
+            throw new Refused("unknown", `This connection has no tool named ${name}.`);
+        const mcp = this.#mcp;
+        try {
+            const result = await mcp.callTool({ name, arguments: args });
+            return {
+                output: cut(textOf(result), OUTPUT_MAX),
+                ...(result.isError ? { failed: true } : {}),
+            };
+        }
+        catch (error) {
+            if (this.#gone(error)) {
+                this.#lose?.();
+                throw new Refused("not_connected", `The server went away during ${name}.`);
+            }
+            return { output: cut(this.#scrub(messageOf(error)), 2000), failed: true };
+        }
+    }
+    /** Whether an error says the server can't be reached, rather than that one request failed. */
+    #gone(error) {
+        if (error instanceof TypeError)
+            return true;
+        return (error instanceof SdkError &&
+            (error.code === SdkErrorCode.ConnectionClosed || error.code === SdkErrorCode.NotConnected));
+    }
+    #set(state, detail) {
+        const changed = state !== this.#state && (state === "connected" || this.#state === "connected");
+        this.#state = state;
+        this.#detail = detail === undefined ? undefined : cut(this.#scrub(detail), 2000);
+        if (state !== "connected")
+            this.#tools = [];
+        if (changed)
+            this.#changed();
+    }
+    #changed() {
+        this.#hub?.exports.tools.emit("changed", {});
+    }
+    async #keepUp() {
+        let delay = this.#firstDelayMs;
+        while (!this.#ended) {
+            const began = Date.now();
+            const why = await this.#session();
+            if (this.#ended)
+                return;
+            this.#set("down", why);
+            if (Date.now() - began >= STEADY_MS)
+                delay = this.#firstDelayMs;
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, delay);
+                this.#wake = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+            });
+            delay = Math.min(delay * 2, MAX_DELAY_MS);
+        }
+    }
+    /** One connection to the server, for as long as it lasts; it resolves with why it ended. */
+    async #session() {
+        const log = this.#log;
+        const mcp = new Client({ name: "agentorg", version: "0" }, {
+            listChanged: {
+                tools: {
+                    autoRefresh: false,
+                    onChanged: () => {
+                        this.#refresh(mcp).then(() => this.#changed(), (error) => log.warn(`Listing the tools again didn't work: ${messageOf(error)}`));
+                    },
+                },
+            },
+        });
+        this.#mcp = mcp;
+        let over = false;
+        const closed = new Promise((resolve) => {
+            const done = () => {
+                over = true;
+                resolve();
+            };
+            mcp.onclose = done;
+            this.#lose = done;
+        });
+        let pinging;
+        try {
+            // A failed start closes before it rejects: what it rejects with is the reason to give.
+            for (const step of [
+                () => mcp.connect(transportOf(this.#spec, this.#secrets, log)),
+                () => this.#refresh(mcp),
+            ]) {
+                const going = step();
+                await Promise.race([going, closed]);
+                if (this.#ended)
+                    return "";
+                if (over) {
+                    await going;
+                    return "The connection to the server ended.";
+                }
+            }
+            this.#set("connected");
+            // An address's transport says nothing when its server dies: asking is how that's noticed.
+            pinging = setInterval(() => {
+                mcp.ping({ timeout: PING_TIMEOUT_MS }).catch((error) => {
+                    if (!(error instanceof ProtocolError))
+                        this.#lose?.();
+                });
+            }, this.#pingEveryMs);
+            await closed;
+            return "The connection to the server ended.";
+        }
+        catch (error) {
+            return messageOf(error);
+        }
+        finally {
+            clearInterval(pinging);
+            this.#mcp = undefined;
+            this.#lose = undefined;
+            await mcp.close().catch(() => { });
+        }
+    }
+    async #refresh(mcp) {
+        const { tools: listed } = await mcp.listTools();
+        this.#tools = fit(listed.filter((tool) => !this.#hide.has(tool.name)), this.#log);
+    }
+}

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

@@ -0,0 +1,4 @@
+export { Connection, type Timing } from "./connection.js";
+export { parseConnection, type Spec } from "./kinds.js";
+export { type McpProvider, type McpProviderOptions, startMcpProvider } from "./provider.js";
+export { isPublicAddress, notPublic } from "./public.js";

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

@@ -0,0 +1,4 @@
+export { Connection } from "./connection.js";
+export { parseConnection } from "./kinds.js";
+export { startMcpProvider } from "./provider.js";
+export { isPublicAddress, notPublic } from "./public.js";

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

@@ -0,0 +1,158 @@
+import { z } from "zod";
+declare const UrlParams: z.ZodObject<{
+    url: z.ZodURL;
+    public: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+declare const CommandParams: z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type Spec = ({
+    kind: "url";
+} & z.infer<typeof UrlParams>) | ({
+    kind: "command";
+} & z.infer<typeof CommandParams>);
+export type Secrets = Record<string, string>;
+export declare const KINDS: readonly [{
+    readonly kind: "url";
+    readonly title: "A server at an address";
+    readonly params: z.ZodObject<{
+        url: z.ZodURL;
+        public: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    readonly secrets: z.ZodObject<{
+        token: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, {
+    readonly kind: "command";
+    readonly title: "A local server this machine starts";
+    readonly params: z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    readonly secrets: z.ZodRecord<z.ZodString, z.ZodString>;
+}];
+/** Each kind as a unit: it gives one connection, under the name it is filled in with. */
+export declare const UNITS: ({
+    id: string;
+    title: string;
+    description: string;
+    form: ({
+        readonly id: "slot";
+        readonly type: "text";
+        readonly value: "string";
+        readonly title: "Name";
+        readonly description: "What the agent knows this connection as.";
+        readonly required: true;
+    } | {
+        id: string;
+        authority: "contacts";
+        type: string;
+        value: "string";
+        title: string;
+        description: string;
+        required: true;
+    } | {
+        authority?: undefined;
+        required?: undefined;
+        id: string;
+        type: string;
+        value: "secret";
+        title: string;
+        description?: undefined;
+    } | {
+        authority?: undefined;
+        required?: undefined;
+        id: string;
+        type: string;
+        value: "boolean";
+        title: string;
+        description: string;
+    })[];
+    needs: never[];
+    gives: {
+        slots: {
+            field: string;
+        }[];
+        skills: never[];
+        results: never[];
+    };
+} | {
+    id: string;
+    title: string;
+    description: string;
+    form: ({
+        readonly id: "slot";
+        readonly type: "text";
+        readonly value: "string";
+        readonly title: "Name";
+        readonly description: "What the agent knows this connection as.";
+        readonly required: true;
+    } | {
+        description?: undefined;
+        id: string;
+        authority: "runs";
+        type: string;
+        value: "string";
+        title: string;
+        required: true;
+    } | {
+        required?: undefined;
+        description?: undefined;
+        id: string;
+        authority: "runs";
+        type: string;
+        value: "strings";
+        title: string;
+    } | {
+        required?: undefined;
+        description?: undefined;
+        id: string;
+        authority: "runs";
+        type: string;
+        value: "string";
+        title: string;
+    } | {
+        authority?: undefined;
+        required?: undefined;
+        id: string;
+        type: string;
+        value: "secret";
+        title: string;
+        description: string;
+    })[];
+    needs: never[];
+    gives: {
+        slots: {
+            field: string;
+        }[];
+        skills: never[];
+        results: never[];
+    };
+})[];
+/**
+ * What a unit's secrets mean to a connection: the lines are environment variables by name.
+ * Secrets that come by name already are as they are. A line is named by position, never by content.
+ */
+export declare function namedSecrets(secrets: Secrets): {
+    secrets?: Secrets;
+    why?: string;
+};
+/** What a connection's parameters and secrets say, or why they don't fit its kind. */
+export declare function parseConnection(kind: string, params: unknown, secrets: unknown): {
+    spec: Spec;
+    secrets: Secrets;
+    why?: undefined;
+} | {
+    spec?: undefined;
+    secrets?: undefined;
+    why: string;
+};
+/**
+ * What a connection attaches to or runs, for people to read. An address loses its query, which is
+ * where a secret would be.
+ */
+export declare function targetOf(spec: Spec): string;
+export {};

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

@@ -0,0 +1,164 @@
+import { z } from "zod";
+const SecretValue = z.string().min(1).max(16_384);
+const EnvName = z
+    .string()
+    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/)
+    .max(256);
+const UrlParams = z.strictObject({
+    url: z
+        .url({ protocol: /^https?$/ })
+        .max(4096)
+        .refine((url) => {
+        if (!URL.canParse(url))
+            return true; // Said already, by `z.url`.
+        const { username, password } = new URL(url);
+        return !username && !password;
+    }, "An address can't hold a user or a password: give a token as a secret.")
+        .meta({ title: "Address" }),
+    public: z.boolean().optional().meta({ title: "Public addresses only" }),
+});
+/** The bearer token sent to the server on every request. */
+const UrlSecrets = z.strictObject({ token: SecretValue.optional().meta({ title: "Token" }) });
+const CommandParams = z.strictObject({
+    command: z.string().min(1).max(4096).meta({ title: "Command" }),
+    args: z.array(z.string().max(4096)).max(256).optional().meta({ title: "Arguments" }),
+    cwd: z.string().min(1).max(4096).optional().meta({ title: "Working folder" }),
+});
+/** Each one is an environment variable of the server, by its name. */
+const CommandSecrets = z.record(EnvName, SecretValue);
+export const KINDS = [
+    { kind: "url", title: "A server at an address", params: UrlParams, secrets: UrlSecrets },
+    {
+        kind: "command",
+        title: "A local server this machine starts",
+        params: CommandParams,
+        secrets: CommandSecrets,
+    },
+];
+/** The secret holding a command's environment as lines; named so that no variable is called it. */
+const LINES = "agentorgEnvironmentLines";
+const NAME = {
+    id: "slot",
+    type: "text",
+    value: "string",
+    title: "Name",
+    description: "What the agent knows this connection as.",
+    required: true,
+};
+const GIVES = { slots: [{ field: "slot" }], skills: [], results: [] };
+/** Each kind as a unit: it gives one connection, under the name it is filled in with. */
+export const UNITS = [
+    {
+        id: "url",
+        title: "A server at an address",
+        description: "Connects to an MCP server over HTTP.",
+        form: [
+            {
+                id: "url",
+                authority: "contacts",
+                type: "text",
+                value: "string",
+                title: "Address",
+                description: "It is shown and kept as written: a token goes in Token.",
+                required: true,
+            },
+            { id: "token", type: "secret", value: "secret", title: "Token" },
+            {
+                id: "public",
+                type: "toggle",
+                value: "boolean",
+                title: "Public addresses only",
+                description: "It reaches only https servers on the public internet, never this machine or its network, and follows no redirect.",
+            },
+            NAME,
+        ],
+        needs: [],
+        gives: GIVES,
+    },
+    {
+        id: "command",
+        title: "A local server this machine starts",
+        description: "Starts an MCP server with this app's rights.",
+        form: [
+            {
+                id: "command",
+                authority: "runs",
+                type: "text",
+                value: "string",
+                title: "Command",
+                required: true,
+            },
+            { id: "args", authority: "runs", type: "lines", value: "strings", title: "Arguments" },
+            { id: "cwd", authority: "runs", type: "directory", value: "string", title: "Working folder" },
+            {
+                id: LINES,
+                type: "environment",
+                value: "secret",
+                title: "Secrets",
+                description: "One NAME=value per line: each is an environment variable of the server.",
+            },
+            NAME,
+        ],
+        needs: [],
+        gives: GIVES,
+    },
+];
+/**
+ * What a unit's secrets mean to a connection: the lines are environment variables by name.
+ * Secrets that come by name already are as they are. A line is named by position, never by content.
+ */
+export function namedSecrets(secrets) {
+    const { [LINES]: lines, ...named } = secrets;
+    if (lines === undefined)
+        return { secrets: named };
+    for (const [index, line] of lines.split(/\r?\n/).entries()) {
+        if (line.trim() === "")
+            continue;
+        const split = line.indexOf("=");
+        if (split < 1)
+            return { why: `Line ${index + 1} of the secrets isn't NAME=value.` };
+        named[line.slice(0, split).trim()] = line.slice(split + 1);
+    }
+    return { secrets: named };
+}
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"]);
+/** What a connection's parameters and secrets say, or why they don't fit its kind. */
+export function parseConnection(kind, params, secrets) {
+    const found = KINDS.find((k) => k.kind === kind);
+    if (!found)
+        return { why: `No kind is named ${kind}: this provider offers url and command.` };
+    const parsed = found.params.safeParse(params);
+    if (!parsed.success)
+        return { why: `${kind}: ${z.prettifyError(parsed.error)}` };
+    const hidden = found.secrets.safeParse(secrets ?? {});
+    // Named by what's wrong with their shape only: a refusal never repeats a value.
+    if (!hidden.success)
+        return { why: `${kind}: its secrets don't fit: ${found.title}.` };
+    const spec = { kind, ...parsed.data };
+    if (spec.kind === "url" && spec.public) {
+        if (new URL(spec.url).protocol !== "https:")
+            return { why: "A public address is https." };
+        if ("token" in hidden.data)
+            return { why: "A public-only connection takes no token." };
+    }
+    if (spec.kind === "url" && "token" in hidden.data) {
+        const url = new URL(spec.url);
+        if (url.protocol === "http:" && !LOOPBACK.has(url.hostname))
+            return { why: "A token is sent only over https, or to this machine." };
+    }
+    return { spec, secrets: hidden.data };
+}
+/**
+ * What a connection attaches to or runs, for people to read. An address loses its query, which is
+ * where a secret would be.
+ */
+export function targetOf(spec) {
+    if (spec.kind === "url") {
+        const url = new URL(spec.url);
+        url.search = "";
+        url.hash = "";
+        return url.href.slice(0, 4096);
+    }
+    const line = [spec.command, ...(spec.args ?? [])].join(" ");
+    return (spec.cwd ? `${line} (in ${spec.cwd})` : line).slice(0, 4096);
+}