@2kw/ai 6.3.0-dev.3 → 6.3.0-dev.31

package/README.md

@@ -88,6 +88,8 @@ kubectl-style contexts switch between organizations and environments:
 2kw context create staging    # Create a new context
 ```
 
+`2kw config set memory true` makes an API-key context send `X-Backbone-Memory: enabled` on `ai respond` and `agents run` calls, which opts those runs into agent memory; `AI_2KW_MEMORY=true|false` overrides it per shell. Runs from a browser-login (session) context are always eligible for agent memory regardless of this setting, so `memory false` only affects API-key contexts.
+
 ## Commands
 
 | Command | Description |
@@ -106,6 +108,7 @@ kubectl-style contexts switch between organizations and environments:
 | `evaluators` | Manage evaluator templates |
 | `scores` | Record and inspect quality scores |
 | `tracing` | Inspect request traces and tracing settings |
+| `memory` | Your agent memory files (list, read, write, delete, forget); member totals and erasure for admins |
 | `providers` | Manage BYOK AI providers |
 | `analytics` | Usage analytics: spend, quality, providers, errors |
 | `billing` | Check subscription tier and usage limits |

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/auth.js

@@ -160,7 +160,12 @@ async function manualLogin(opts) {
         console.error(chalk.red("API key is required."));
         process.exit(1);
     }
-    setContext(contextName, { apiKey, baseUrl });
+    // Carry the memory opt-in over: re-entering a key should not silently turn it off (#721).
+    setContext(contextName, {
+        apiKey,
+        baseUrl,
+        ...(currentCtx?.memory !== undefined ? { memory: currentCtx.memory } : {}),
+    });
     setActiveContext(contextName);
     console.log(chalk.green("Credentials saved successfully."));
     console.log(chalk.dim(`Config stored at: ${store.path}`));

package/dist/commands/config.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-declare const ALLOWED_KEYS: readonly ["apiKey", "baseUrl"];
+declare const ALLOWED_KEYS: readonly ["apiKey", "baseUrl", "memory"];
 type ConfigKey = (typeof ALLOWED_KEYS)[number];
 /**
  * Write one config key onto the active context.

package/dist/commands/config.js

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { store, isJsonOutput, getActiveContext, getActiveContextName, getContextCount, setContext, DEFAULT_BASE_URL, } from "../lib/config.js";
 import { maskApiKey } from "../lib/redact.js";
-const ALLOWED_KEYS = ["apiKey", "baseUrl"];
+const ALLOWED_KEYS = ["apiKey", "baseUrl", "memory"];
 const KEY_ALIASES = {
     "api-key": "apiKey",
     "base-url": "baseUrl",
@@ -43,6 +43,14 @@ export function applyConfigSet(key, value) {
         setContext(contextName, entry);
         return { clearedSession };
     }
+    if (key === "memory") {
+        if (value !== "true" && value !== "false") {
+            throw new Error('memory takes true or false');
+        }
+        entry.memory = value === "true";
+        setContext(contextName, entry);
+        return { clearedSession: false };
+    }
     entry[key] = value;
     setContext(contextName, entry);
     return { clearedSession: false };
@@ -82,7 +90,12 @@ export function makeConfigCommand() {
         const validKey = validateKey(key);
         const ctx = getActiveContext();
         const raw = ctx?.[validKey];
-        const value = raw && validKey === "apiKey" ? maskApiKey(raw) : raw;
+        // A stored "" apiKey stays "" (shown as "(not set)"); only a real key is masked.
+        const value = raw === undefined
+            ? undefined
+            : validKey === "apiKey" && typeof raw === "string"
+                ? raw && maskApiKey(raw)
+                : String(raw);
         if (isJsonOutput(command)) {
             console.log(JSON.stringify({ key: validKey, value: value ?? null }));
         }
@@ -103,6 +116,7 @@ export function makeConfigCommand() {
         const values = {
             apiKey: ctx?.apiKey ? maskApiKey(ctx.apiKey) : undefined,
             baseUrl: ctx?.baseUrl,
+            memory: ctx?.memory === undefined ? undefined : String(ctx.memory),
         };
         if (isJsonOutput(command)) {
             console.log(JSON.stringify(values, null, 2));

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/files.js

@@ -8,40 +8,22 @@ import { formatPage, formatDetail, formatSuccess, withSpinner } from "../lib/out
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
 import { fileToBlob } from "../lib/multipart.js";
 /**
- * Upload a single file with purpose=agent_input|knowledge. Bypasses the typed
- * client the same way convert.ts and transcribe.ts do: the generated types
- * describe the multipart body as an opaque `file: string`, which is not
- * something FormData can produce a match for.
+ * Upload a single file with purpose=agent_input|knowledge. The generated type
+ * describes the "file" part as a binary string, which FormData cannot match,
+ * so the placeholder body satisfies the type and bodySerializer sends the
+ * real part.
  */
 async function uploadFile(command, filePath, purpose) {
-    const config = resolveConfig(command);
-    const authHeader = await resolveAuthHeader(config);
     const { blob, filename } = fileToBlob(filePath);
     const formData = new FormData();
     formData.append("file", blob, filename);
-    const baseUrl = config.baseUrl.replace(/\/+$/, "");
-    const url = `${baseUrl}/v1/files?purpose=${encodeURIComponent(purpose)}`;
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { Authorization: authHeader },
-        body: formData,
+    const client = getClient(command);
+    const { data } = await client.POST("/v1/files", {
+        params: { query: { purpose } },
+        body: { file: "" },
+        bodySerializer: () => formData,
     });
-    if (!res.ok) {
-        let body;
-        try {
-            body = await res.json();
-        }
-        catch {
-            body = {
-                error: res.statusText,
-                message: `HTTP ${res.status}: ${res.statusText}`,
-                status: res.status,
-                timestamp: new Date().toISOString(),
-            };
-        }
-        throw new BackboneApiError(body);
-    }
-    return (await res.json());
+    return data;
 }
 /** Stream a file's bytes from /v1/files/{fileId}/content via a raw fetch. */
 async function downloadFile(command, fileId) {

package/dist/commands/knowledge-documents.js

@@ -1,49 +1,29 @@
 import { Command } from "commander";
 import chalk from "chalk";
-import { getClient, resolveAuthHeader, runAction } from "../lib/client.js";
-import { resolveConfig, isJsonOutput } from "../lib/config.js";
-import { BackboneApiError } from "../lib/errors.js";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
 import { formatPage, formatDetail, formatSuccess, withSpinner } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
 import { fileToBlob } from "../lib/multipart.js";
 /**
- * Upload one or more local files to a knowledge base. Bypasses the typed
- * client the same way convert.ts's multipartConvert does: springdoc mis-shapes
- * this endpoint's `files` parameter as a query array of binary strings, but the
- * controller (`KnowledgeDocumentController.upload`) actually reads it off a
- * multipart/form-data body with repeated "files" parts.
+ * Upload one or more local files to a knowledge base as repeated "files"
+ * parts of a multipart/form-data body. The generated type describes each part
+ * as a binary string, which FormData cannot match, so the placeholder body
+ * satisfies the type and bodySerializer sends the real parts.
  */
 async function uploadDocuments(command, knowledgeBaseId, paths) {
-    const config = resolveConfig(command);
-    const authHeader = await resolveAuthHeader(config);
     const formData = new FormData();
     for (const p of paths) {
         const { blob, filename } = fileToBlob(p);
         formData.append("files", blob, filename);
     }
-    const baseUrl = config.baseUrl.replace(/\/+$/, "");
-    const url = `${baseUrl}/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents`;
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { Authorization: authHeader },
-        body: formData,
+    const client = getClient(command);
+    const { data } = await client.POST("/v1/knowledge-bases/{knowledgeBaseId}/documents", {
+        params: { path: { knowledgeBaseId } },
+        body: { files: [] },
+        bodySerializer: () => formData,
     });
-    if (!res.ok) {
-        let body;
-        try {
-            body = await res.json();
-        }
-        catch {
-            body = {
-                error: res.statusText,
-                message: `HTTP ${res.status}: ${res.statusText}`,
-                status: res.status,
-                timestamp: new Date().toISOString(),
-            };
-        }
-        throw new BackboneApiError(body);
-    }
-    return (await res.json());
+    return data ?? [];
 }
 function printUploadResults(results, command) {
     if (isJsonOutput(command)) {

package/dist/commands/memory.d.ts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+/** The If-Match value for a version a GET returned: the quoted ETag the API expects. */
+export declare function ifMatchHeader(version: string): string;
+/**
+ * Agent memory (agent memory spec §7.1, §7.4). `ls`, `cat`, `put`, `rm` and `forget` act on
+ * the caller's own memory; `members` and `erase` are for ADMIN and OWNER and never show
+ * paths or content. Content is lossless: `cat` prints it raw, `put` sends the file as is.
+ */
+export declare function makeMemoryCommand(): Command;
+//# sourceMappingURL=memory.d.ts.map

package/dist/commands/memory.js

@@ -0,0 +1,132 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
+import { CliUsageError } from "../lib/errors.js";
+import { formatDetail, formatList, formatSuccess } from "../lib/output.js";
+/** The If-Match value for a version a GET returned: the quoted ETag the API expects. */
+export function ifMatchHeader(version) {
+    if (!/^\d{1,18}$/.test(version)) {
+        throw new CliUsageError(`--if-match takes the file's version, a whole number: ${version}`);
+    }
+    return `"${version}"`;
+}
+function requireYes(opts, what) {
+    if (!opts.yes) {
+        throw new CliUsageError(`${what} cannot be undone. Pass --yes to confirm.`);
+    }
+}
+/**
+ * Agent memory (agent memory spec §7.1, §7.4). `ls`, `cat`, `put`, `rm` and `forget` act on
+ * the caller's own memory; `members` and `erase` are for ADMIN and OWNER and never show
+ * paths or content. Content is lossless: `cat` prints it raw, `put` sends the file as is.
+ */
+export function makeMemoryCommand() {
+    const cmd = new Command("memory").description("Your agent memory files; member totals and erasure for admins");
+    cmd
+        .command("ls")
+        .description("List your memory files")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/memories/me/files");
+            formatList(data, command, [
+                "path",
+                "sizeBytes",
+                "version",
+                "updatedAt",
+                "lastWrittenByAgentId",
+            ]);
+        });
+    });
+    cmd
+        .command("cat <path>")
+        .description("Print one of your memory files, raw (--json for the file object)")
+        .action(async (path, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/memories/me/file", {
+                params: { query: { path } },
+            });
+            if (isJsonOutput(command)) {
+                formatDetail(data, command);
+            }
+            else {
+                process.stdout.write(data.content);
+            }
+        });
+    });
+    cmd
+        .command("put <path>")
+        .description("Create or replace one of your memory files from a local UTF-8 file")
+        .requiredOption("--file <file>", "Local file whose content is stored")
+        .option("--if-match <version>", "Only replace the file if it still has this version")
+        .action(async (path, opts, command) => {
+        await runAction(command, async () => {
+            // An empty --if-match (e.g. an unset shell variable) must be refused, never dropped
+            // into an unconditional overwrite.
+            const headers = opts.ifMatch !== undefined ? { "If-Match": ifMatchHeader(opts.ifMatch) } : undefined;
+            const content = readFileSync(opts.file, "utf8");
+            const client = getClient(command);
+            const { data } = await client.PUT("/v1/memories/me/file", {
+                params: { query: { path } },
+                body: { content },
+                headers,
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("rm <path>")
+        .description("Delete one of your memory files, or a directory with everything below it")
+        .action(async (path, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.DELETE("/v1/memories/me/file", { params: { query: { path } } });
+            formatSuccess(`Deleted ${path}`, command);
+        });
+    });
+    cmd
+        .command("forget")
+        .description("Delete your whole memory (cannot be undone)")
+        .option("--yes", "Confirm")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            requireYes(opts, "Forgetting your whole memory");
+            const client = getClient(command);
+            await client.DELETE("/v1/memories/me");
+            formatSuccess("Forgot your whole memory", command);
+        });
+    });
+    cmd
+        .command("members")
+        .description("Memory totals per member, without paths or content (ADMIN+)")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/memories/users");
+            formatList(data, command, [
+                "userId",
+                "fileCount",
+                "totalBytes",
+                "lastUpdatedAt",
+            ]);
+        });
+    });
+    cmd
+        .command("erase <userId>")
+        .description("Erase a member's whole memory (ADMIN+, cannot be undone)")
+        .option("--yes", "Confirm")
+        .action(async (userId, opts, command) => {
+        await runAction(command, async () => {
+            requireYes(opts, "Erasing a member's memory");
+            const client = getClient(command);
+            await client.DELETE("/v1/memories/users/{userId}", {
+                params: { path: { userId } },
+            });
+            formatSuccess(`Erased the memory of ${userId}`, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=memory.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,8 @@ 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 { makeMemoryCommand } from "./commands/memory.js";
 import { makeEvaluatorsCommand } from "./commands/evaluators.js";
 import { makeScoresCommand } from "./commands/scores.js";
 import { makeQueuesCommand } from "./commands/queues.js";
@@ -29,6 +31,7 @@ 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);
@@ -61,11 +64,14 @@ program.addCommand(makeEvaluatorsCommand());
 program.addCommand(makeScoresCommand());
 program.addCommand(makeQueuesCommand());
 program.addCommand(makeTracingCommand());
+program.addCommand(makeSettingsCommand());
+program.addCommand(makeMemoryCommand());
 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());

package/dist/lib/client.d.ts

@@ -39,6 +39,14 @@ export declare function apiKeyAuthMiddleware(config: ApiKeyConfig): Middleware;
  * fires and cannot be replayed safely.
  */
 export declare function sessionAuthMiddleware(config: SessionConfig, deps?: SessionAuthDeps): Middleware;
+/** The per-request opt-in to agent memory for API-key runs (spec §3.3, D6, D7). */
+export declare const MEMORY_HEADER = "X-Backbone-Memory";
+/**
+ * Adds `X-Backbone-Memory: enabled` to `POST …/v1/responses`, the call that starts a run
+ * and that also carries approval decisions (`lib/agent-decide.ts`). No other request gets
+ * it; the server reads it only there.
+ */
+export declare const memoryHeaderMiddleware: Middleware;
 /**
  * The middleware stack for a resolved config, in registration order.
  *

package/dist/lib/client.js

@@ -1,5 +1,5 @@
 import createClient from "openapi-fetch";
-import { resolveConfig, isJsonOutput } from "./config.js";
+import { resolveConfig, isJsonOutput, memoryEnabled } from "./config.js";
 import { ensureJwt } from "./auth-session.js";
 import { BackboneApiError, handleError } from "./errors.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,
         });
     },
 };
@@ -83,6 +85,21 @@ export function sessionAuthMiddleware(config, deps = {}) {
         },
     };
 }
+/** The per-request opt-in to agent memory for API-key runs (spec §3.3, D6, D7). */
+export const MEMORY_HEADER = "X-Backbone-Memory";
+/**
+ * Adds `X-Backbone-Memory: enabled` to `POST …/v1/responses`, the call that starts a run
+ * and that also carries approval decisions (`lib/agent-decide.ts`). No other request gets
+ * it; the server reads it only there.
+ */
+export const memoryHeaderMiddleware = {
+    onRequest({ request }) {
+        if (request.method === "POST" && new URL(request.url).pathname.endsWith("/v1/responses")) {
+            request.headers.set(MEMORY_HEADER, "enabled");
+        }
+        return request;
+    },
+};
 /**
  * The middleware stack for a resolved config, in registration order.
  *
@@ -123,6 +140,8 @@ export function getClient(command) {
         baseUrl: config.baseUrl.replace(/\/+$/, ""),
     });
     client.use(...buildMiddleware(config));
+    if (memoryEnabled())
+        client.use(memoryHeaderMiddleware);
     return client;
 }
 /**

package/dist/lib/config.d.ts

@@ -14,6 +14,8 @@ export interface ContextEntry {
     cachedJwt?: string;
     /** Epoch millis when cachedJwt expires. */
     cachedJwtExp?: number;
+    /** Send `X-Backbone-Memory: enabled` on responses calls (`2kw config set memory true`, #721). */
+    memory?: boolean;
 }
 export interface BackboneConfigStore {
     activeContext: string;
@@ -55,6 +57,12 @@ export { store };
 export declare function validateContextName(name: string): void;
 export declare function getActiveContextName(): string;
 export declare function getActiveContext(): ContextEntry | undefined;
+/**
+ * Whether responses calls opt into agent memory (spec §3.3, D6). `AI_2KW_MEMORY` wins when
+ * set (`true` on, anything else off), so CI can switch it without touching the store;
+ * otherwise the active context's `memory` key decides. Off by default.
+ */
+export declare function memoryEnabled(env?: NodeJS.ProcessEnv): boolean;
 export declare function getAllContexts(): Record<string, ContextEntry>;
 export declare function getContextCount(): number;
 export declare function setContext(name: string, entry: ContextEntry): void;

package/dist/lib/config.js

@@ -142,6 +142,17 @@ export function getActiveContext() {
     const contexts = store.get("contexts") ?? {};
     return contexts[name];
 }
+/**
+ * Whether responses calls opt into agent memory (spec §3.3, D6). `AI_2KW_MEMORY` wins when
+ * set (`true` on, anything else off), so CI can switch it without touching the store;
+ * otherwise the active context's `memory` key decides. Off by default.
+ */
+export function memoryEnabled(env = process.env) {
+    const fromEnv = env.AI_2KW_MEMORY;
+    if (fromEnv !== undefined && fromEnv !== "")
+        return fromEnv === "true";
+    return getActiveContext()?.memory === true;
+}
 export function getAllContexts() {
     return store.get("contexts") ?? {};
 }

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.3",
+  "version": "6.3.0-dev.31",
   "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",