@agentorg/cli 0.0.6 → 0.0.8

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

@@ -11,7 +11,8 @@ export interface Timing {
 }
 export declare class Connection {
     #private;
-    constructor(spec: Spec, secrets: Secrets, log: Log, timing?: Timing);
+    /** `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;

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

@@ -3,6 +3,7 @@ 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;
@@ -61,6 +62,8 @@ function transportOf(spec, secrets, log) {
         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({
@@ -92,12 +95,15 @@ export class Connection {
     #lose;
     #running;
     #spec;
+    #hide;
     #secrets;
     #log;
     #scrub;
     #pingEveryMs;
     #firstDelayMs;
-    constructor(spec, secrets, log, timing = {}) {
+    /** `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;
@@ -285,6 +291,6 @@ export class Connection {
     }
     async #refresh(mcp) {
         const { tools: listed } = await mcp.listTools();
-        this.#tools = fit(listed, this.#log);
+        this.#tools = fit(listed.filter((tool) => !this.#hide.has(tool.name)), this.#log);
     }
 }

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

@@ -1 +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

@@ -1 +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

@@ -1,6 +1,7 @@
 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;
@@ -18,6 +19,7 @@ export declare const KINDS: readonly [{
     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>;
@@ -32,6 +34,112 @@ export declare const KINDS: readonly [{
     }, 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;

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

@@ -9,10 +9,13 @@ const UrlParams = z.strictObject({
         .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" }) });
@@ -32,6 +35,92 @@ export const KINDS = [
         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) {
@@ -46,6 +135,12 @@ export function parseConnection(kind, params, secrets) {
     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))

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

@@ -16,7 +16,7 @@ export interface McpProvider {
     close(): Promise<void>;
 }
 /**
- * Run the built-in MCP provider as an Actor exporting `mcp.provider@1` as `provider`. It offers two
- * kinds, `url` and `command`; a server it starts runs with this process's rights. Connections made earlier are joined again at the start.
+ * Run the built-in MCP provider as an Actor exporting `unit.provider@1` as `provider`. It offers two
+ * units, `url` and `command`; a server it starts runs with this process's rights. Connections made earlier are joined again at the start.
  */
 export declare function startMcpProvider(options: McpProviderOptions): Promise<McpProvider>;

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

@@ -1,11 +1,12 @@
 import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { hubActors, mcpProvider } from "@agentorg/interfaces";
+import { hubActors, unitProvider } from "@agentorg/interfaces";
 import { Refused } from "@agentorg/sdk";
 import { connect } from "@agentorg/sdk/client";
 import { z } from "zod";
 import { Connection } from "./connection.js";
-import { KINDS, parseConnection, targetOf } from "./kinds.js";
+import { namedSecrets, parseConnection, targetOf, UNITS, } from "./kinds.js";
+import { notPublic } from "./public.js";
 /** What is kept of a connection between runs, in the provider's private file. */
 const Stored = z.object({
     credential: z.string(),
@@ -14,10 +15,12 @@ const Stored = z.object({
     secrets: z.record(z.string(), z.string()),
 });
 const FILE = "connections.json";
+/** What a unit's values come to as a connection's parameters: its name isn't one. */
+const paramsOf = ({ slot: _, ...params }) => params;
 const quiet = { info() { }, warn() { }, error() { } };
 /**
- * Run the built-in MCP provider as an Actor exporting `mcp.provider@1` as `provider`. It offers two
- * kinds, `url` and `command`; a server it starts runs with this process's rights. Connections made earlier are joined again at the start.
+ * Run the built-in MCP provider as an Actor exporting `unit.provider@1` as `provider`. It offers two
+ * units, `url` and `command`; a server it starts runs with this process's rights. Connections made earlier are joined again at the start.
  */
 export async function startMcpProvider(options) {
     const log = options.log ?? quiet;
@@ -102,22 +105,32 @@ export async function startMcpProvider(options) {
         actorId: options.actorId,
         credential: options.credential,
         slots: { actors: hubActors },
-        exports: { provider: mcpProvider },
+        exports: { provider: unitProvider },
         log,
         start(ctx) {
             ctx.exports.provider.implement({
-                kinds: () => ({
-                    kinds: KINDS.map(({ kind, title, params, secrets }) => ({
-                        kind,
-                        title,
-                        params: JSON.parse(JSON.stringify(z.toJSONSchema(params))),
-                        secrets: JSON.parse(JSON.stringify(z.toJSONSchema(secrets))),
-                    })),
-                }),
-                async create({ kind, params, secrets, name }) {
-                    const { spec, secrets: hidden, why } = parseConnection(kind, params, secrets);
+                units: () => ({ units: UNITS }),
+                skill: () => {
+                    throw new Refused("unknown", "These units come with no skill.");
+                },
+                check({ unit, values, secrets }) {
+                    // Only whether a token is there matters, and a check never holds its value.
+                    const given = secrets.includes("token") ? { token: "given" } : {};
+                    const { why } = parseConnection(unit, paramsOf(values), given);
+                    return { problems: why ? [{ message: why }] : [] };
+                },
+                async apply({ unit: kind, values, secrets, name }) {
+                    const params = paramsOf(values);
+                    const named = namedSecrets(secrets);
+                    if (!named.secrets)
+                        throw new Refused("invalid", named.why ?? "Its secrets don't fit.");
+                    const { spec, secrets: hidden, why } = parseConnection(kind, params, named.secrets);
                     if (!spec)
                         throw new Refused("invalid", why);
+                    // Said now, as well as at each request.
+                    const away = spec.kind === "url" && spec.public ? await notPublic(spec.url) : undefined;
+                    if (away)
+                        throw new Refused("invalid", away);
                     const { actorId, credential } = await ctx.slots.actors.call.create({ name });
                     let connection;
                     try {
@@ -135,10 +148,27 @@ export async function startMcpProvider(options) {
                         await ctx.slots.actors.call.close({ actorId }).catch(() => { });
                         throw error;
                     }
-                    return { connection: actorId, target: targetOf(spec) };
+                    // The instance is the connection: one made before units had no other id.
+                    return {
+                        instance: actorId,
+                        connections: [
+                            { slot: String(values.slot), connection: actorId, target: targetOf(spec) },
+                        ],
+                        results: [],
+                    };
+                },
+                async status({ instance }) {
+                    const status = await held(instance).status();
+                    return {
+                        state: status.state,
+                        ...(status.detail ? { detail: status.detail } : {}),
+                        connections: [{ ...status, connection: instance }],
+                    };
+                },
+                live: () => {
+                    throw new Refused("unknown", "A connection has nothing to open live.");
                 },
-                status: ({ connection }) => held(connection).status(),
-                async remove({ connection }) {
+                async remove({ instance: connection }) {
                     const found = held(connection);
                     await ctx.slots.actors.call.close({ actorId: connection });
                     connections.delete(connection);

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

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

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

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

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

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

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

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

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

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

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

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