@2kw/ai 6.3.0-dev.12 → 6.3.0-dev.122

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,10 +108,11 @@ 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 |
-| `agents` | Run agents and decide approvals; apply, export and scaffold agent.yaml; manage versions, labels, approvals and tool catalogs |
+| `agents` | Run agents and answer paused runs (approvals and relayed tool calls); apply, export and scaffold agent.yaml; manage versions, labels, approvals and tool catalogs |
 | `skills` | Import and export SKILL.md bundles; manage skill versions and labels |
 | `plugins` | Install plugin repositories, sync them, and inspect their reports |
 | `conversations` | Create and manage conversations and their items |

package/dist/agent-config/schema.d.ts

@@ -83,8 +83,8 @@ export declare const agentSchema: {
                 readonly properties: {
                     readonly name: {
                         readonly type: "string";
-                        readonly pattern: "^[a-z0-9]+(-[a-z0-9]+)*$";
-                        readonly maxLength: 100;
+                        readonly pattern: "^[a-z0-9]+(-[a-z0-9]+)*(:[a-z0-9]+(-[a-z0-9]+)*)?$";
+                        readonly maxLength: 201;
                     };
                     readonly ref: {
                         readonly type: "string";
@@ -106,6 +106,9 @@ export declare const agentSchema: {
                 readonly destructiveHint: {
                     readonly type: "boolean";
                 };
+                readonly openWorldHint: {
+                    readonly type: "boolean";
+                };
             };
         };
         readonly fileSearchTool: {
@@ -213,7 +216,7 @@ export declare const agentSchema: {
                     readonly uniqueItems: true;
                     readonly items: {
                         readonly type: "string";
-                        readonly pattern: "^[a-z0-9]+(-[a-z0-9]+)*(@[A-Za-z0-9._-]+)?$";
+                        readonly pattern: "^[a-z0-9]+(-[a-z0-9]+)*(:[a-z0-9]+(-[a-z0-9]+)*)?(@[A-Za-z0-9._-]+)?$";
                     };
                 };
             };

package/dist/agent-config/schema.js

@@ -5,8 +5,11 @@
  * Kept as a TS constant: package.json `files` publishes only dist JS/d.ts.
  */
 export const AGENT_SCHEMA_ID = "https://docs.2kw.ai/schemas/agent.v1.json";
-const SKILL_NAME = "^[a-z0-9]+(-[a-z0-9]+)*$";
-const SKILL_REF = "^[a-z0-9]+(-[a-z0-9]+)*(@[A-Za-z0-9._-]+)?$";
+// #788: a skill name is a slug, or <plugin>:<skill> for a skill a plugin import created.
+// Mirrors ValidationLimits.SKILL_NAME_PATTERN; each part is at most 100 characters, 201 in all.
+const SKILL_NAME = "^[a-z0-9]+(-[a-z0-9]+)*(:[a-z0-9]+(-[a-z0-9]+)*)?$";
+const SKILL_REF = "^[a-z0-9]+(-[a-z0-9]+)*(:[a-z0-9]+(-[a-z0-9]+)*)?(@[A-Za-z0-9._-]+)?$";
+const SKILL_NAME_MAX = 201;
 const MODEL_REF = {
     type: "string",
     minLength: 1,
@@ -18,6 +21,8 @@ const oneOfLowercase = (...values) => ({ type: "string", enum: values });
 export const NON_AUTHORABLE_TOOL_TYPES = {
     "backbone.tool_search": "the planner adds it automatically",
     "backbone.skill_read": "it is added at run time when skills are pinned",
+    // #944: SkillsetPinner injects it for eligible callers and strips any stored copy (#779).
+    "backbone.skills_apply": "it is added at run time for callers allowed to author skills",
     web_search: "it has no executor and is skipped",
 };
 const BUILTIN_TYPES = [
@@ -74,7 +79,7 @@ export const agentSchema = {
                 additionalProperties: false,
                 required: ["name"],
                 properties: {
-                    name: { type: "string", pattern: SKILL_NAME, maxLength: 100 },
+                    name: { type: "string", pattern: SKILL_NAME, maxLength: SKILL_NAME_MAX },
                     ref: { type: "string", pattern: "\\S", description: "Label name or version number; default latest." },
                 },
             },
@@ -84,7 +89,13 @@ export const agentSchema = {
         annotations: {
             type: "object",
             required: ["readOnlyHint", "destructiveHint"],
-            properties: { readOnlyHint: { type: "boolean" }, destructiveHint: { type: "boolean" } },
+            properties: {
+                readOnlyHint: { type: "boolean" },
+                destructiveHint: { type: "boolean" },
+                // Optional. With destructiveHint: false it declares the tool harmless, so a write under
+                // `auto` may reach the approver (#938).
+                openWorldHint: { type: "boolean" },
+            },
         },
         fileSearchTool: {
             type: "object",

package/dist/agent-config/template.js

@@ -43,7 +43,7 @@ tools: []
 #       properties:
 #         order: { type: string }
 #       required: [order]
-#     annotations: { readOnlyHint: true, destructiveHint: false }
+#     annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
 # Approval policy. Defaults: read allow, write approve, destructive block. Rules can only tighten.
 # hitlPolicy:
 #   version: 1

package/dist/commands/agent-apply.js

@@ -30,7 +30,7 @@ export function versionBody(config, changeDescription) {
 /**
  * The complete agent DTO for POST /v1/agents and PUT /v1/agents/{id}. The backend's PUT maps every DTO field
  * onto the row without skipping nulls (#624), so an absent key clears the column: `skills` (NOT NULL) must
- * always be sent, and a PUT must carry `latestVersionId` or the agent loses its head pointer. Nullable
+ * always be sent. `latestVersionId` is server-managed and ignored in a body (#996); it is still sent. Nullable
  * columns (instructions, options, hitl_policy) are omitted when the file omits them, which clears them to
  * SQL NULL exactly as createVersion does; an explicit JSON null would arrive as a NullNode instead.
  */

package/dist/commands/agent-policy.d.ts

@@ -5,7 +5,8 @@ import { Command } from "commander";
  *
  * Answers the question an operator otherwise has to answer by running the agent
  * and reading the transcript. The version defaults to the agent's latest, which
- * is the one an unlabelled reference resolves to.
+ * is the one an unlabelled reference resolves to. `--mode` answers for a conversation in that
+ * mode (#1037); a contributing mode shows in the matched rules as `conversation_mode.<mode>`.
  */
 export declare function makeAgentPolicyCommand(): Command;
 //# sourceMappingURL=agent-policy.d.ts.map

package/dist/commands/agent-policy.js

@@ -4,6 +4,7 @@ import { getClient, runAction } from "../lib/client.js";
 import { isJsonOutput } from "../lib/config.js";
 import { formatDetail, formatList } from "../lib/output.js";
 import { resolveAgent } from "../lib/agent-lookup.js";
+import { parseModeOption } from "../lib/agent-run.js";
 import { CliUsageError } from "../lib/errors.js";
 import { getLatestVersion } from "./agent-apply.js";
 /**
@@ -12,7 +13,8 @@ import { getLatestVersion } from "./agent-apply.js";
  *
  * Answers the question an operator otherwise has to answer by running the agent
  * and reading the transcript. The version defaults to the agent's latest, which
- * is the one an unlabelled reference resolves to.
+ * is the one an unlabelled reference resolves to. `--mode` answers for a conversation in that
+ * mode (#1037); a contributing mode shows in the matched rules as `conversation_mode.<mode>`.
  */
 export function makeAgentPolicyCommand() {
     return new Command("policy")
@@ -21,8 +23,11 @@ export function makeAgentPolicyCommand() {
         .option("--version <id>", "Agent version ID (default: the agent's latest version)")
         .option("--tool <name>", "Answer for one tool instead of every configured tool")
         .option("--installation <id>", "Resolve the module tool catalog of this installation")
+        .option("--mode <mode>", "Answer as a conversation in this mode would be gated: plan (every call that is not read-only is refused), " +
+        "ask (a person decides where the policy would ask the judge), auto (the policy as written)")
         .action(async (agentRef, opts, command) => {
         await runAction(command, async () => {
+            const mode = parseModeOption(opts.mode);
             const client = getClient(command);
             const agent = await resolveAgent(client, agentRef);
             const agentId = agent.id;
@@ -33,7 +38,7 @@ export function makeAgentPolicyCommand() {
             const { data } = await client.GET("/v1/agents/{agentId}/versions/{versionId}/policy", {
                 params: {
                     path: { agentId, versionId },
-                    query: { tool: opts.tool, installation: opts.installation },
+                    query: { tool: opts.tool, installation: opts.installation, mode },
                 },
             });
             if (isJsonOutput(command)) {
@@ -47,6 +52,8 @@ export function makeAgentPolicyCommand() {
                 `auto-approval ${auto?.enabled ? "on" : "off (every auto pauses for a human)"}`,
                 `judge ${auto?.judgeConfigured ? "configured" : "not configured (every candidate escalates)"}`,
             ];
+            if (mode)
+                parts.push(`mode ${mode}`);
             if (data?.catalogResolvedAt)
                 parts.push(`catalog resolved ${data.catalogResolvedAt}`);
             console.log(chalk.dim(parts.join(", ")));

package/dist/commands/agent-run.d.ts

@@ -1,5 +1,10 @@
 import { Command } from "commander";
 export declare function resolveRunInput(arg: string | undefined, inputFile: string | undefined, readStdin?: () => string | undefined): string;
+/**
+ * The task text from the argument, then the file, then stdin; `undefined` when none is given. A
+ * `--continue` run may have none: a connect pause is continued with an empty input (#807).
+ */
+export declare function readRunInput(arg: string | undefined, inputFile: string | undefined, readStdin?: () => string | undefined): string | undefined;
 export declare function makeAgentRunCommand(): Command;
 export declare function makeAgentDecideCommand(): Command;
 //# sourceMappingURL=agent-run.d.ts.map

package/dist/commands/agent-run.js

@@ -1,16 +1,27 @@
 import { Command } from "commander";
 import { readFileSync } from "node:fs";
 import { getClient, runAction } from "../lib/client.js";
-import { isJsonOutput } from "../lib/config.js";
+import { chatUrlFor, isJsonOutput, resolveConfig } from "../lib/config.js";
 import { BackboneApiError, CliUsageError } from "../lib/errors.js";
 import { withSpinner } from "../lib/output.js";
 import { resolveAgent, splitAgentRef, suggestAgents } from "../lib/agent-lookup.js";
-import { buildRunEnvelope, EXIT_CODES, printRunText, stripControl } from "../lib/agent-run.js";
-import { continueWithDecisions, decisionsFromAnswers, fetchPendingApprovals, planDecisions, } from "../lib/agent-decide.js";
+import { buildRunEnvelope, EXIT_CODES, MODE_OPTION_HELP, modeItem, parseModeOption, printRunText, stripControl, } from "../lib/agent-run.js";
+import { continueWithDecisions, decisionsFromAnswers, fetchPendingApprovals, parseToolAnswers, planContinuation, } from "../lib/agent-decide.js";
 import { PromptAbortedError, promptApprovals, readlineAsk } from "../lib/approval-prompt.js";
 import { withModelOverride } from "../lib/agent-models.js";
 import { readStdinInput } from "./ai.js";
 export function resolveRunInput(arg, inputFile, readStdin = readStdinInput) {
+    const text = readRunInput(arg, inputFile, readStdin);
+    if (text === undefined) {
+        throw new CliUsageError("Input is required: pass it as an argument, with --input-file, or via stdin.");
+    }
+    return text;
+}
+/**
+ * The task text from the argument, then the file, then stdin; `undefined` when none is given. A
+ * `--continue` run may have none: a connect pause is continued with an empty input (#807).
+ */
+export function readRunInput(arg, inputFile, readStdin = readStdinInput) {
     if (arg)
         return arg;
     if (inputFile) {
@@ -29,10 +40,7 @@ export function resolveRunInput(arg, inputFile, readStdin = readStdinInput) {
             throw new CliUsageError(`Input file ${inputFile} is empty.`);
         return text;
     }
-    const piped = readStdin();
-    if (piped)
-        return piped;
-    throw new CliUsageError("Input is required: pass it as an argument, with --input-file, or via stdin.");
+    return readStdin() || undefined;
 }
 async function withAgentSuggestions(client, agentRef, err) {
     if (!(err instanceof BackboneApiError) || err.status !== 404 || !err.message.startsWith("Agent not found")) {
@@ -56,8 +64,9 @@ async function withAgentSuggestions(client, agentRef, err) {
  */
 async function finishRun(command, client, target, first, opts) {
     const agentRef = `${target.name}${target.label ? `@${target.label}` : ""}${target.model ? `#${target.model}` : ""}`;
+    const chatUrl = chatUrlFor(resolveConfig(command).baseUrl);
     let result = first;
-    let env = buildRunEnvelope(result, agentRef);
+    let env = buildRunEnvelope(result, agentRef, chatUrl);
     if (opts.interactive && env.status === "requires_approval") {
         try {
             const agent = await resolveAgent(client, target.name);
@@ -90,8 +99,8 @@ async function finishRun(command, client, target, first, opts) {
                     throw new CliUsageError(`No pending approvals for ${responseId} (already decided or superseded).`);
                 }
                 const decisions = decisionsFromAnswers(rows, answers);
-                result = await withSpinner("Continuing...", () => continueWithDecisions(client, String(agent.id), responseId, decisions, target.label, target.model));
-                env = buildRunEnvelope(result, agentRef);
+                result = await withSpinner("Continuing...", () => continueWithDecisions(client, String(agent.id), responseId, decisions, target.label, target.model, target.mode));
+                env = buildRunEnvelope(result, agentRef, chatUrl);
             }
         }
         catch (err) {
@@ -115,21 +124,30 @@ async function finishRun(command, client, target, first, opts) {
 }
 export function makeAgentRunCommand() {
     return new Command("run")
-        .description("Run an agent on a task (exit 3 = paused for approval, 4 = needs client tool output, 5 = incomplete)")
+        .description("Run an agent on a task (exit 3 = paused for approval, 4 = needs client tool output or a connector connected in chat, 5 = incomplete)")
         .argument("<agent>", "Agent name or id, optionally with @label and #model")
-        .argument("[input]", "Task text (or use --input-file, or pipe it on stdin)")
+        .argument("[input]", "Task text (or use --input-file, or pipe it on stdin); optional with --continue")
         .option("--input-file <path>", "Read the task text from a file")
         .option("--conversation <id>", "Continue a conversation")
-        .option("--continue <responseId>", "Continue from a previous response")
+        .option("--continue <responseId>", "Continue from a previous response, with or without new input")
         .option("--model <model>", "Run this request on another model from the agent's list (sends <agent>#<model>)")
+        .option("--mode <mode>", MODE_OPTION_HELP)
         .option("--no-input", "Never prompt for approvals, even on a terminal")
         .option("--raw", "Print the untouched API response")
         .action(async (agentArg, input, opts, command) => {
         await runAction(command, async () => {
             const agentRef = withModelOverride(agentArg, opts.model);
-            const text = resolveRunInput(input, opts.inputFile);
+            const mode = parseModeOption(opts.mode);
+            // A continuation may send no new turn (#807): the connect pause's `next` is exactly that command.
+            const text = opts.continue ? readRunInput(input, opts.inputFile) : resolveRunInput(input, opts.inputFile);
             const client = getClient(command);
-            const body = { model: `agent/${agentRef}`, input: text, stream: false };
+            const turn = text === undefined ? [] : [{ type: "message", role: "user", content: text }];
+            // Without --mode the body stays exactly as before #656 (D2): input is the bare string, or [] without one.
+            const body = {
+                model: `agent/${agentRef}`,
+                input: mode ? [...turn, modeItem(mode)] : text ?? [],
+                stream: false,
+            };
             if (opts.conversation)
                 body.conversation = opts.conversation;
             if (opts.continue)
@@ -146,16 +164,18 @@ export function makeAgentRunCommand() {
             // The prompt reads stdin and writes to stderr, so those two decide; stdout may be redirected.
             const interactive = !!process.stdin.isTTY && !!process.stderr.isTTY && !isJsonOutput(command) && opts.input !== false && !opts.raw;
             const { name, label, model } = splitAgentRef(agentRef);
-            await finishRun(command, client, { name, label, model }, data, {
+            await finishRun(command, client, { name, label, model, mode }, data, {
                 raw: !!opts.raw,
                 interactive,
             });
         });
     });
 }
+/** Repeatable `--output` / `--fail`: a variadic `<v...>` would swallow the arguments that follow it. */
+const collect = (value, previous = []) => [...previous, value];
 export function makeAgentDecideCommand() {
     return new Command("decide")
-        .description("Decide every pending approval of a paused run and continue it")
+        .description("Answer a paused run: decide every pending approval and answer every relayed tool call in one call, then continue it")
         .argument("<agent>", "Agent name or id, optionally with @label and #model (use the same @label and #model the run used)")
         .requiredOption("--response <responseId>", "The paused response id (responseId in the run envelope)")
         .option("--approve <ids...>", "Approval ids to approve")
@@ -164,9 +184,15 @@ export function makeAgentDecideCommand() {
         .option("--reject-all", "Reject every pending approval of the response")
         .option("--reason <text>", "Reason recorded on each decision (the model sees it on rejects)")
         .option("--remember", "Also approve later calls of the same tool in this conversation")
+        .option("--output <callId=value>", "Answer a relayed tool call: <callId>=<text>, <callId>=@<file> or <callId>=@- for stdin; within one hour of the pause (repeatable)", collect)
+        .option("--fail <callId=message>", "Answer a relayed tool call as failed: <callId>=<message> (same @file / @- forms; repeatable)", collect)
+        .option("--mode <mode>", MODE_OPTION_HELP)
         .option("--raw", "Print the untouched API response")
         .action(async (agentRef, opts, command) => {
         await runAction(command, async () => {
+            const mode = parseModeOption(opts.mode);
+            // Syntax, duplicates and file reads are checked before any request (#671 D4).
+            const toolAnswers = parseToolAnswers(opts.output, opts.fail);
             const client = getClient(command);
             const { name, label, model } = splitAgentRef(agentRef);
             // Dropped silently, an empty override would continue the run on the default model.
@@ -174,16 +200,16 @@ export function makeAgentDecideCommand() {
                 throw new CliUsageError(`Empty #model in '${agentRef}': use the model the run used, or drop the '#'.`);
             const agent = await resolveAgent(client, name);
             const pending = await fetchPendingApprovals(client, String(agent.id), opts.response);
-            const decisions = planDecisions(pending, {
+            const decisions = planContinuation(pending, {
                 approve: opts.approve,
                 reject: opts.reject,
                 approveAll: opts.approveAll,
                 rejectAll: opts.rejectAll,
                 reason: opts.reason,
                 remember: opts.remember,
-            }, opts.response);
-            const result = await withSpinner("Continuing...", () => continueWithDecisions(client, String(agent.id), opts.response, decisions, label, model));
-            await finishRun(command, client, { name, label, model }, result, { raw: !!opts.raw, interactive: false });
+            }, toolAnswers, opts.response);
+            const result = await withSpinner("Continuing...", () => continueWithDecisions(client, String(agent.id), opts.response, decisions, label, model, mode, toolAnswers));
+            await finishRun(command, client, { name, label, model, mode }, result, { raw: !!opts.raw, interactive: false });
         });
     });
 }

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";
@@ -11,6 +11,7 @@ import { makeAgentPolicyCommand } from "./agent-policy.js";
 import { makeAgentInitCommand, makeAgentSchemaCommand } from "./agent-init.js";
 import { maskSecrets } from "../agent-config/file.js";
 import { collectModel, MODEL_HELP, MODELS_HELP, modelFieldsFromOptions } from "../lib/agent-models.js";
+import { assertNameNotBlank } from "../lib/overlay.js";
 export function makeAgentsCommand() {
     const cmd = new Command("agents").description("Manage agents");
     const list = new Command("list").description("List agents");
@@ -101,13 +102,25 @@ export function makeAgentsCommand() {
         .option("--hitl-policy <json>", "New human-in-the-loop policy as JSON")
         .action(async (id, opts, command) => {
         await runAction(command, async () => {
+            let name = opts.name;
+            let description = opts.description;
+            assertNameNotBlank(name);
             const client = getClient(command);
-            const body = {};
-            if (opts.name)
-                body.name = opts.name;
+            // PUT /v1/agents/{id} keeps the configuration fields a body omits, but name is required and
+            // description is written as sent, so an omitted description would be cleared (#1195).
+            if (name === undefined || description === undefined) {
+                const { data: current } = await client.GET("/v1/agents/{id}", {
+                    params: { path: { id } },
+                });
+                if (!current)
+                    throw new Error(`Agent ${id} could not be read.`);
+                name ??= current.name;
+                description ??= current.description;
+            }
+            const body = { name };
             Object.assign(body, modelFieldsFromOptions(opts, false));
-            if (opts.description !== undefined)
-                body.description = opts.description;
+            if (description !== undefined)
+                body.description = description;
             if (opts.instructions !== undefined)
                 body.instructions = opts.instructions;
             if (opts.options)
@@ -172,6 +185,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/ai.js

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import { readFileSync } from "node:fs";
 import { getClient, runAction } from "../lib/client.js";
-import { isJsonOutput } from "../lib/config.js";
+import { chatUrlFor, isJsonOutput, resolveConfig } from "../lib/config.js";
 import { CliUsageError } from "../lib/errors.js";
 import { withModelOverride } from "../lib/agent-models.js";
 import { formatList, withSpinner } from "../lib/output.js";
@@ -46,7 +46,7 @@ function printResponseResult(result, command, agentRef) {
         console.log(JSON.stringify(result, null, 2));
         return;
     }
-    printRunText(buildRunEnvelope(result, agentRef));
+    printRunText(buildRunEnvelope(result, agentRef, chatUrlFor(resolveConfig(command).baseUrl)));
     if (result?.usage) {
         const usage = result.usage;
         console.log(chalk.dim(`[${result.model} | ${usage.input_tokens} in / ${usage.output_tokens} out / ${usage.total_tokens} total tokens]`));
@@ -125,13 +125,7 @@ export function makeAiCommand() {
             if (opts.conversation)
                 body.conversation = opts.conversation;
             const client = getClient(command);
-            const { data } = await withSpinner("Generating response...", () => 
-            // The wire `input` field also accepts a bare string (shorthand for
-            // a single user message; see ResponseItemInputDeserializer), which
-            // the generated type does not model — hence the cast, same as the
-            // untyped convert.ts source-conversion calls.
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            client.POST("/v1/responses", { body }));
+            const { data } = await withSpinner("Generating response...", () => client.POST("/v1/responses", { body }));
             printResponseResult(data, command, opts.agent);
         });
     });

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

@@ -49,10 +49,12 @@ export function makeBillingCommand() {
                     }
                     console.log();
                 }
+                // A null maximum is "unlimited" (schemas and prompts in every tier since #971), not 0.
+                const max = (value) => (value == null ? "unlimited" : String(value));
                 console.log(chalk.bold("Usage:"));
-                console.log(`  Schemas:      ${data?.currentSchemas ?? 0} / ${data?.maxSchemas ?? 0}`);
-                console.log(`  Prompts:      ${data?.currentPrompts ?? 0} / ${data?.maxPrompts ?? 0}`);
-                console.log(`  Team members: ${data?.currentTeamMembers ?? 0} / ${data?.maxTeamMembers ?? 0}`);
+                console.log(`  Schemas:      ${data?.currentSchemas ?? 0} / ${max(data?.maxSchemas)}`);
+                console.log(`  Prompts:      ${data?.currentPrompts ?? 0} / ${max(data?.maxPrompts)}`);
+                console.log(`  Team members: ${data?.currentTeamMembers ?? 0} / ${max(data?.maxTeamMembers)}`);
                 console.log();
                 console.log(chalk.bold("Features:"));
                 console.log(`  BYOK:             ${data?.byokEnabled ? chalk.green("yes") : chalk.dim("no")}`);

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

@@ -28,7 +28,8 @@ function parsePort(value) {
     if (value === undefined) {
         return undefined;
     }
-    const port = Number(value);
+    // 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}'`);
     }

package/dist/commands/conversations.js

@@ -98,6 +98,22 @@ export function makeConversationsCommand() {
             formatSuccess(`Conversation ${conversationId} deleted.`, command);
         });
     });
+    cmd
+        .command("cancel")
+        .description("Ask a running turn of a conversation to stop")
+        .argument("<conversationId>", "Conversation ID")
+        .requiredOption("--turn <turnId>", "The turn id the client sent as the Backbone-Turn-Id header")
+        .action(async (conversationId, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.POST("/v1/conversations/{conversationId}/cancel", {
+                params: { path: { conversationId } },
+                body: { turn_id: opts.turn },
+            });
+            // Accepted, not performed: the turn's own response says whether it stopped.
+            formatSuccess(`Stop requested for turn ${opts.turn} of conversation ${conversationId}.`, command);
+        });
+    });
     const items = new Command("items").description("List a conversation's items");
     items
         .command("list")

package/dist/commands/datasets.js

@@ -3,6 +3,7 @@ import { getClient, runAction } from "../lib/client.js";
 import { resolveLatestVersionId } from "../lib/datasets.js";
 import { formatPage, formatDetail, formatList, formatSuccess } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+import { assertNameNotBlank, overlay } from "../lib/overlay.js";
 import { makeDatasetVersionsCommand } from "./dataset-versions.js";
 export function makeDatasetsCommand() {
     const cmd = new Command("datasets").description("Manage datasets");
@@ -77,24 +78,25 @@ export function makeDatasetsCommand() {
         .option("--metadata <json>", "Metadata (JSON)")
         .action(async (id, opts, command) => {
         await runAction(command, async () => {
+            assertNameNotBlank(opts.name);
+            const changes = {
+                name: opts.name,
+                description: opts.description,
+                type: opts.type,
+                inputSchema: opts.inputSchema ? JSON.parse(opts.inputSchema) : undefined,
+                expectedOutputSchema: opts.expectedOutputSchema ? JSON.parse(opts.expectedOutputSchema) : undefined,
+                metadata: opts.metadata ? JSON.parse(opts.metadata) : undefined,
+            };
             const client = getClient(command);
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const body = {};
-            if (opts.name)
-                body.name = opts.name;
-            if (opts.description !== undefined)
-                body.description = opts.description;
-            if (opts.type !== undefined)
-                body.type = opts.type;
-            if (opts.inputSchema)
-                body.inputSchema = JSON.parse(opts.inputSchema);
-            if (opts.expectedOutputSchema)
-                body.expectedOutputSchema = JSON.parse(opts.expectedOutputSchema);
-            if (opts.metadata)
-                body.metadata = JSON.parse(opts.metadata);
+            // PUT /v1/datasets/{id} replaces the whole dataset, so an omitted field would be stored as null.
+            const { data: current } = await client.GET("/v1/datasets/{id}", {
+                params: { path: { id } },
+            });
+            if (!current)
+                throw new Error(`Dataset ${id} could not be read.`);
             const { data } = await client.PUT("/v1/datasets/{id}", {
                 params: { path: { id } },
-                body: body,
+                body: overlay(current, changes),
             });
             formatDetail(data, command);
         });