@2kw/ai 6.3.0-dev.2 → 6.3.0-dev.24

package/dist/commands/agents.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { getClient, runAction } from "../lib/client.js";
-import { formatPage, formatDetail, formatSuccess } from "../lib/output.js";
+import { formatPage, formatDetail, formatList, formatSuccess } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
 import { makeAgentVersionsCommand } from "./agent-versions.js";
 import { makeAgentLabelsCommand } from "./agent-labels.js";
@@ -172,6 +172,20 @@ export function makeAgentsCommand() {
         });
     });
     cmd.addCommand(toolCatalogs);
+    // The skills the latest published version binds (#827) -- readable by a chat-only USER key,
+    // which cannot read the version itself. No published version answers [] rather than 404.
+    const skills = new Command("skills").description("List the skills an agent's latest published version binds");
+    skills.requiredOption("--agent <id>", "Agent ID");
+    skills.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/agents/{agentId}/skills", {
+                params: { path: { agentId: opts.agent } },
+            });
+            formatList(data, command, ["name", "description", "versionNumber", "ref", "pluginName"]);
+        });
+    });
+    cmd.addCommand(skills);
     cmd.addCommand(makeAgentRunCommand());
     cmd.addCommand(makeAgentDecideCommand());
     cmd.addCommand(makeAgentApplyCommand());

package/dist/commands/connectors.d.ts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+/**
+ * Manage the connector settings an organization decides centrally (#805).
+ *
+ * Only the approved public hosts live here: which MCP servers this organization's agents
+ * may reach directly. The connectors themselves are declared per agent, in the agent
+ * version's `tools`.
+ */
+export declare function makeConnectorsCommand(): Command;
+//# sourceMappingURL=connectors.d.ts.map

package/dist/commands/connectors.js

@@ -0,0 +1,97 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { CliUsageError } from "../lib/errors.js";
+import { formatDetail, formatList, formatSuccess } from "../lib/output.js";
+/**
+ * These three endpoints take a member sign-in only (plan ruling R10): approving a
+ * destination is the human gate against exfiltration, so an API key — however admin it is —
+ * is refused. Said in every description, because `--help` is where a reader looks before
+ * the 403.
+ */
+const SESSION_ONLY = "Signed-in admins only: run 2kw auth login and sign in through the browser; an API key is refused";
+/** The backend's limit, so a too-long host fails here instead of after a round trip. */
+const MAX_HOST_LENGTH = 253;
+const MIN_PORT = 1;
+const MAX_PORT = 65535;
+/**
+ * Parse `--port` strictly, and only when one was given.
+ *
+ * Commander's house pattern is a bare `parseInt`, which turns `--port abc` into `NaN`,
+ * `JSON.stringify` turns that into `null`, and the backend reads a null port as "not
+ * given" and approves 443. Silently approving a port nobody asked for is not a wart worth
+ * inheriting on a trust decision.
+ *
+ * Validated inside the action rather than as commander's option parser, so the refusal
+ * travels through `runAction` and exits 2 like every other usage error.
+ */
+function parsePort(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    // Digits only: `Number` alone accepts " 8443 ", "0x20FB" and "8.443e3".
+    const port = /^\d{1,5}$/.test(value) ? Number(value) : NaN;
+    if (!Number.isInteger(port) || port < MIN_PORT || port > MAX_PORT) {
+        throw new CliUsageError(`--port must be a whole number between ${MIN_PORT} and ${MAX_PORT}, not '${value}'`);
+    }
+    return port;
+}
+function requireHost(host) {
+    if (host.length > MAX_HOST_LENGTH) {
+        throw new CliUsageError(`A host name is at most ${MAX_HOST_LENGTH} characters`);
+    }
+    return host;
+}
+/**
+ * Manage the connector settings an organization decides centrally (#805).
+ *
+ * Only the approved public hosts live here: which MCP servers this organization's agents
+ * may reach directly. The connectors themselves are declared per agent, in the agent
+ * version's `tools`.
+ */
+export function makeConnectorsCommand() {
+    const cmd = new Command("connectors").description("Manage MCP connector settings");
+    const publicHosts = new Command("public-hosts").description(`Approve the public MCP hosts this organization's agents may reach. ${SESSION_ONLY}`);
+    publicHosts
+        .command("list")
+        .description(`List the approved public MCP hosts. ${SESSION_ONLY}`)
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/connectors/public-hosts");
+            formatList(data, command, [
+                "id",
+                "host",
+                "port",
+                "createdBy",
+                "createdAt",
+            ]);
+        });
+    });
+    publicHosts
+        .command("add")
+        .description(`Approve a host — every path and every account on it becomes reachable. ${SESSION_ONLY}`)
+        .argument("<host>", "Plain host name: no scheme, path, port, wildcard or IP literal")
+        .option("--port <n>", "Port to approve; 443 when omitted")
+        .action(async (host, opts, command) => {
+        await runAction(command, async () => {
+            const body = { host: requireHost(host), port: parsePort(opts.port) };
+            const client = getClient(command);
+            const { data } = await client.POST("/v1/connectors/public-hosts", { body });
+            formatDetail(data, command);
+        });
+    });
+    publicHosts
+        .command("remove")
+        .description(`Withdraw an approved host; it takes effect on the next request. ${SESSION_ONLY}`)
+        .argument("<id>", "Approved host ID, from `connectors public-hosts list`")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.DELETE("/v1/connectors/public-hosts/{id}", { params: { path: { id } } });
+            formatSuccess(`Host ${id} withdrawn.`, command);
+        });
+    });
+    cmd.addCommand(publicHosts);
+    return cmd;
+}
+//# sourceMappingURL=connectors.js.map

package/dist/commands/relays.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function makeRelaysCommand(): Command;
+//# sourceMappingURL=relays.d.ts.map

package/dist/commands/relays.js

@@ -0,0 +1,135 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
+import { formatDetail, formatPage, formatSuccess } from "../lib/output.js";
+import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+/**
+ * Prints an enrolment response in text mode. The relay record comes first when the response
+ * carries one: `create` is the only place the new relay's id is ever shown, and every other
+ * subcommand takes that id as its argument.
+ */
+function printEnrolment(data, command) {
+    if (isJsonOutput(command)) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    if (data.relay) {
+        formatDetail(data.relay, command);
+        console.log("");
+    }
+    console.log(data.enrolmentExpiresAt
+        ? `Enrolment token (shown once, valid until ${data.enrolmentExpiresAt}):`
+        : "Enrolment token (shown once):");
+    console.log(`  ${data.enrolmentToken ?? ""}`);
+    console.log("");
+    console.log("Run the relay inside your network:");
+    console.log(data.dockerRun ?? "");
+}
+export function makeRelaysCommand() {
+    const cmd = new Command("relays").description("Manage MCP relays that reach MCP servers on private networks");
+    const list = new Command("list").description("List MCP relays");
+    addPaginationOptions(list);
+    list.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/mcp-relays", {
+                params: { query: { ...paginationParams(opts) } },
+            });
+            formatPage(data, command, [
+                "id",
+                "name",
+                "status",
+                "online",
+                "relayVersion",
+                "inventoryReportedAt",
+            ]);
+        });
+    });
+    cmd.addCommand(list);
+    cmd
+        .command("get")
+        .description("Show a relay with its inventory")
+        .argument("<id>", "Relay ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/mcp-relays/{id}", {
+                params: { path: { id } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("create")
+        .description("Create a relay; prints a single-use enrolment token and a docker run snippet")
+        .requiredOption("--name <name>", 'Display name, e.g. "Office Berlin"')
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.POST("/v1/mcp-relays", {
+                body: { name: opts.name },
+            });
+            printEnrolment(data ?? {}, command);
+        });
+    });
+    cmd
+        .command("rename")
+        .description("Rename a relay")
+        .argument("<id>", "Relay ID")
+        .requiredOption("--name <name>", "New name")
+        .action(async (id, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.PATCH("/v1/mcp-relays/{id}", {
+                params: { path: { id } },
+                body: { name: opts.name },
+            });
+            formatDetail(data, command);
+        });
+    });
+    for (const [name, disabled, description] of [
+        ["disable", true, "Disable a relay: it gets no new work and its enrolment token is voided"],
+        ["enable", false, "Enable a disabled relay"],
+    ]) {
+        cmd
+            .command(name)
+            .description(description)
+            .argument("<id>", "Relay ID")
+            .action(async (id, _opts, command) => {
+            await runAction(command, async () => {
+                const client = getClient(command);
+                const { data } = await client.PATCH("/v1/mcp-relays/{id}", {
+                    params: { path: { id } },
+                    body: { disabled },
+                });
+                formatDetail(data, command);
+            });
+        });
+    }
+    cmd
+        .command("re-enrol")
+        .description("Issue a new enrolment token; redeeming it replaces the relay's key")
+        .argument("<id>", "Relay ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.POST("/v1/mcp-relays/{id}/enrolment-token", {
+                params: { path: { id } },
+            });
+            printEnrolment(data ?? {}, command);
+        });
+    });
+    cmd
+        .command("delete")
+        .description("Revoke a relay for good")
+        .argument("<id>", "Relay ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.DELETE("/v1/mcp-relays/{id}", { params: { path: { id } } });
+            formatSuccess(`Relay ${id} revoked.`, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=relays.js.map

package/dist/commands/settings.d.ts

@@ -0,0 +1,13 @@
+import { Command } from "commander";
+/**
+ * Parses the value a setting takes: a JSON object. The server checks its shape per key
+ * (for agents.default: {"agentId": "<id>"}); this only refuses what can never be valid.
+ */
+export declare function parseSettingValue(raw: string): Record<string, unknown>;
+/**
+ * Organization and member settings (agent-first chat spec §3.1, §4). Without --org every
+ * write targets the caller's own member tier; --org writes the organization's, which needs
+ * the key's write role (ADMIN or OWNER for agents.default).
+ */
+export declare function makeSettingsCommand(): Command;
+//# sourceMappingURL=settings.d.ts.map

package/dist/commands/settings.js

@@ -0,0 +1,80 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { CliUsageError } from "../lib/errors.js";
+import { formatDetail } from "../lib/output.js";
+/**
+ * Parses the value a setting takes: a JSON object. The server checks its shape per key
+ * (for agents.default: {"agentId": "<id>"}); this only refuses what can never be valid.
+ */
+export function parseSettingValue(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CliUsageError(`Setting value is not valid JSON: ${raw}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliUsageError('Setting value must be a JSON object, e.g. \'{"agentId":"agt_123"}\'');
+    }
+    return parsed;
+}
+/**
+ * Organization and member settings (agent-first chat spec §3.1, §4). Without --org every
+ * write targets the caller's own member tier; --org writes the organization's, which needs
+ * the key's write role (ADMIN or OWNER for agents.default).
+ */
+export function makeSettingsCommand() {
+    const cmd = new Command("settings").description("Organization and member settings (e.g. agents.default)");
+    cmd
+        .command("get <key>")
+        .description("Show a setting: the effective value, its source and both tiers")
+        .action(async (key, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/settings/{key}", {
+                params: { path: { key } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("set <key> <json>")
+        .description("Set your own value, or the organization's with --org (ADMIN+)")
+        .option("--org", "Write the organization's value instead of your own")
+        .action(async (key, json, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const body = { value: parseSettingValue(json) };
+            const { data } = opts.org
+                ? await client.PUT("/v1/settings/{key}/org", {
+                    params: { path: { key } },
+                    body,
+                })
+                : await client.PUT("/v1/settings/{key}/member", {
+                    params: { path: { key } },
+                    body,
+                });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("unset <key>")
+        .description("Clear your own value, or the organization's with --org (ADMIN+)")
+        .option("--org", "Clear the organization's value instead of your own")
+        .action(async (key, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = opts.org
+                ? await client.DELETE("/v1/settings/{key}/org", {
+                    params: { path: { key } },
+                })
+                : await client.DELETE("/v1/settings/{key}/member", {
+                    params: { path: { key } },
+                });
+            formatDetail(data, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=settings.js.map

package/dist/index.js

@@ -21,6 +21,7 @@ import { makeDocsCommand } from "./commands/docs.js";
 import { makeContextCommand } from "./commands/context.js";
 import { makeExperimentsCommand } from "./commands/experiments.js";
 import { makeTracingCommand } from "./commands/tracing.js";
+import { makeSettingsCommand } from "./commands/settings.js";
 import { makeEvaluatorsCommand } from "./commands/evaluators.js";
 import { makeScoresCommand } from "./commands/scores.js";
 import { makeQueuesCommand } from "./commands/queues.js";
@@ -29,6 +30,8 @@ import { makeConversationsCommand } from "./commands/conversations.js";
 import { makeKnowledgeCommand } from "./commands/knowledge.js";
 import { makeFilesCommand } from "./commands/files.js";
 import { makeInstallationsCommand } from "./commands/installations.js";
+import { makeConnectorsCommand } from "./commands/connectors.js";
+import { makeRelaysCommand } from "./commands/relays.js";
 import { checkForUpdates } from "./lib/update-notifier.js";
 const updater = checkForUpdates(pkg.version);
 const program = new Command();
@@ -60,11 +63,14 @@ program.addCommand(makeEvaluatorsCommand());
 program.addCommand(makeScoresCommand());
 program.addCommand(makeQueuesCommand());
 program.addCommand(makeTracingCommand());
+program.addCommand(makeSettingsCommand());
 program.addCommand(makeAgentsCommand());
 program.addCommand(makeConversationsCommand());
 program.addCommand(makeKnowledgeCommand());
 program.addCommand(makeFilesCommand());
 program.addCommand(makeInstallationsCommand());
+program.addCommand(makeConnectorsCommand());
+program.addCommand(makeRelaysCommand());
 program.addCommand(makeDocsCommand());
 program.parseAsync().then(() => updater.notify());
 //# sourceMappingURL=index.js.map

package/dist/lib/client.js

@@ -37,6 +37,8 @@ export const errorMiddleware = {
                 `HTTP ${response.status}: ${response.statusText}`,
             timestamp: body.timestamp ?? new Date().toISOString(),
             code: typeof nested?.code === "string" ? nested.code : undefined,
+            // A problem detail names its cause in `errorCode` (GlobalExceptionHandler).
+            errorCode: typeof body.errorCode === "string" ? body.errorCode : undefined,
         });
     },
 };

package/dist/lib/errors.d.ts

@@ -10,12 +10,18 @@ export interface ApiErrorBody {
     timestamp: string;
     /** Machine-readable code from an OpenAI-style gateway error, e.g. `approval_hmac_mismatch`. */
     code?: string;
+    /**
+     * Machine-readable code from a problem detail's `errorCode`, e.g. `CONNECTOR_HOST_SIGN_IN_REQUIRED`.
+     * Kept apart from {@link code}: that one holds lowercase gateway codes and is printed by `--json`.
+     */
+    errorCode?: string;
 }
 export declare class BackboneApiError extends Error {
     readonly status: number;
     readonly errorType: string;
     readonly timestamp: string;
     readonly code?: string;
+    readonly errorCode?: string;
     constructor(body: Omit<ApiErrorBody, "error"> & {
         error: string;
     });

package/dist/lib/errors.js

@@ -7,6 +7,7 @@ export class BackboneApiError extends Error {
     errorType;
     timestamp;
     code;
+    errorCode;
     constructor(body) {
         super(body.message);
         this.name = "BackboneApiError";
@@ -14,6 +15,7 @@ export class BackboneApiError extends Error {
         this.errorType = body.error;
         this.timestamp = body.timestamp;
         this.code = body.code;
+        this.errorCode = body.errorCode;
     }
 }
 /**
@@ -106,6 +108,13 @@ export function hintFor(err) {
     }
     if (err.code && CODE_HINTS[err.code])
         return CODE_HINTS[err.code];
+    // The 403 whose cause is the credential, not the role (#805). Without this the
+    // generic 403 hint tells an organization admin to check a role that is already
+    // right, and no role would ever have fixed it. Matched on the backend's error code,
+    // so a reworded message cannot silently drop the hint.
+    if (err.errorCode === "CONNECTOR_HOST_SIGN_IN_REQUIRED") {
+        return "Approved hosts need a browser sign-in: run 2kw auth login. An API key cannot manage them, whatever its role.";
+    }
     // Anchored on the agent service's wording: prompts and schemas send the same
     // "Label '<x>' not found" prefix, and must keep the generic 404 hint.
     if (err.status === 404 && /^Label 'latest' not found (on agent|for this agent)/.test(err.message)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai",
-  "version": "6.3.0-dev.2",
+  "version": "6.3.0-dev.24",
   "description": "CLI for 2kw.ai — schema-driven document extraction, an OpenAI-compatible EU LLM gateway, transcription, prompts, datasets, and experiments from your terminal or agentic workflows. Ships as 2kw, backbone, and bb.",
   "keywords": [
     "cli",