@2kw/ai 7.4.0-dev.9 → 8.0.0-dev.11

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

@@ -571,7 +571,7 @@ export declare const agentSchema: {
                     };
                     readonly additionalProperties: {
                         readonly type: "string";
-                        readonly enum: readonly ["read", "write", "destructive", "approve", "auto", "deny"];
+                        readonly enum: readonly ["read", "write", "destructive", "approve", "deny"];
                     };
                 };
             };

package/dist/agent-config/schema.js

@@ -105,8 +105,8 @@ export const agentSchema = {
             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).
+                // Optional. With destructiveHint: false it declares the tool harmless, so a write that needs
+                // approval may be decided by the automatic approver in the Auto mode (#938, #1645).
                 openWorldHint: { type: "boolean" },
             },
         },
@@ -290,17 +290,17 @@ export const agentSchema = {
                     type: "object",
                     additionalProperties: false,
                     properties: {
-                        read: oneOfLowercase("allow", "auto", "approve", "block", "deny"),
-                        write: oneOfLowercase("auto", "approve", "block", "deny"),
-                        destructive: oneOfLowercase("block", "deny"),
+                        read: oneOfLowercase("allow", "approve", "block", "deny"),
+                        write: oneOfLowercase("approve", "block", "deny"),
+                        destructive: oneOfLowercase("approve", "block", "deny"),
                     },
                 },
                 tools: {
-                    // Value is a policy class or an action. Actions (approve, auto, deny) are exact lowercase;
+                    // Value is a policy class or an action. Actions (approve, deny) are exact lowercase;
                     // classes (read, write, destructive) are case-insensitive and lowercased by the validator.
                     type: "object",
                     propertyNames: { pattern: "\\S" },
-                    additionalProperties: { type: "string", enum: ["read", "write", "destructive", "approve", "auto", "deny"] },
+                    additionalProperties: { type: "string", enum: ["read", "write", "destructive", "approve", "deny"] },
                 },
             },
         },

package/dist/commands/agent-policy.js

@@ -24,7 +24,8 @@ export function makeAgentPolicyCommand() {
         .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)")
+        "ask (a person decides every call that needs approval), auto (the automatic approver decides reads and " +
+        "writes the server marks safe). Without it, the agent's default mode")
         .action(async (agentRef, opts, command) => {
         await runAction(command, async () => {
             const mode = parseModeOption(opts.mode);
@@ -49,11 +50,14 @@ export function makeAgentPolicyCommand() {
             // model, so they belong above the table rather than in a footnote.
             const auto = data?.autoApproval;
             const parts = [
-                `auto-approval ${auto?.enabled ? "on" : "off (every auto pauses for a human)"}`,
-                `judge ${auto?.judgeConfigured ? "configured" : "not configured (every candidate escalates)"}`,
+                `auto-approval ${auto?.enabled ? "on" : "off (every call the approver would decide pauses for a human)"}`,
+                `approver ${auto?.judgeConfigured ? "configured" : "not configured (every candidate escalates)"}`,
             ];
-            if (mode)
-                parts.push(`mode ${mode}`);
+            if (auto?.instructionsExceedJudgeBound) {
+                parts.push("instructions longer than the approver reads (every candidate escalates)");
+            }
+            if (data?.effectiveMode)
+                parts.push(`mode ${data.effectiveMode} (${data.effectiveModeSource})`);
             if (data?.catalogResolvedAt)
                 parts.push(`catalog resolved ${data.catalogResolvedAt}`);
             console.log(chalk.dim(parts.join(", ")));

package/dist/commands/dataset-versions.js

@@ -97,7 +97,6 @@ export function makeDatasetVersionsCommand() {
             const versionId = opts.versionId ?? (await resolveLatestVersionId(client, opts.dataset));
             await client.DELETE("/v1/datasets/{id}/versions/{versionId}/items/{itemId}", {
                 params: {
-                    // OpenAPI spec omits `id` in declared path params though `{id}` is in the URL template.
                     path: { id: opts.dataset, versionId, itemId },
                 },
             });
@@ -120,7 +119,6 @@ export function makeDatasetVersionsCommand() {
                 body.expectedOutput = JSON.parse(opts.expectedOutput);
             const { data } = await client.PATCH("/v1/datasets/{id}/versions/{versionId}/items/{itemId}/expected-output", {
                 params: {
-                    // OpenAPI spec omits `id` in declared path params though `{id}` is in the URL template.
                     path: { id: opts.dataset, versionId, itemId },
                 },
                 body: body,

package/dist/commands/datasets.js

@@ -138,7 +138,6 @@ export function makeDatasetsCommand() {
                 body.metadata = JSON.parse(opts.metadata);
             const { data } = await client.POST("/v1/datasets/{id}/versions/{versionId}/items", {
                 params: {
-                    // OpenAPI spec omits `id` in declared path params though `{id}` is in the URL template.
                     path: { id: opts.dataset, versionId },
                 },
                 body: body,
@@ -158,7 +157,6 @@ export function makeDatasetsCommand() {
             const items = JSON.parse(opts.items);
             const { data } = await client.POST("/v1/datasets/{id}/versions/{versionId}/items/bulk", {
                 params: {
-                    // OpenAPI spec omits `id` in declared path params though `{id}` is in the URL template.
                     path: { id: opts.dataset, versionId },
                 },
                 body: items,

package/dist/commands/experiments.js

@@ -335,7 +335,7 @@ export function makeExperimentsCommand() {
                 },
             });
             formatPage(data, command, [
-                "datasetItemId", "durationMs", "inputTokens", "outputTokens", "estimatedCost", "error",
+                "datasetItemId", "durationMs", "inputTokens", "outputTokens", "error",
             ]);
         });
     });
@@ -418,7 +418,7 @@ export function makeExperimentsCommand() {
                 // Only when something was skipped, so a clean run keeps its narrow table (#693).
                 const showSkipped = aggregates.some((agg) => skippedOf(agg) !== "");
                 const aggTable = new Table({
-                    head: ["Variant", "Items", "Avg Duration", "Avg Tokens", "Total Cost", ...(showSkipped ? ["Skipped"] : [])].map((h) => chalk.cyan(h)),
+                    head: ["Variant", "Items", "Avg Duration", "Avg Tokens", ...(showSkipped ? ["Skipped"] : [])].map((h) => chalk.cyan(h)),
                     wordWrap: true,
                 });
                 for (const agg of aggregates) {
@@ -427,7 +427,6 @@ export function makeExperimentsCommand() {
                         agg.itemCount ?? "—",
                         agg.avgDurationMs != null ? `${Math.round(agg.avgDurationMs)}ms` : "—",
                         agg.avgTokens != null ? Math.round(agg.avgTokens) : "—",
-                        agg.totalCost != null ? `$${agg.totalCost}` : "—",
                         ...(showSkipped ? [skippedOf(agg) || "—"] : []),
                     ]);
                 }

package/dist/commands/files.js

@@ -2,10 +2,9 @@ import { Command } from "commander";
 import { writeFileSync } from "node:fs";
 import chalk from "chalk";
 import { getClient, resolveAuthHeader, runAction } from "../lib/client.js";
-import { resolveConfig } from "../lib/config.js";
+import { isJsonOutput, resolveConfig } from "../lib/config.js";
 import { BackboneApiError } from "../lib/errors.js";
-import { formatPage, formatDetail, formatSuccess, withSpinner } from "../lib/output.js";
-import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+import { formatDetail, formatList, formatSuccess, withSpinner } from "../lib/output.js";
 import { fileToBlob } from "../lib/multipart.js";
 /**
  * Upload a single file with purpose=agent_input|knowledge. Both are multipart
@@ -59,15 +58,31 @@ async function downloadFile(command, fileId) {
 export function makeFilesCommand() {
     const cmd = new Command("files").description("Manage uploaded files");
     const list = new Command("list").description("List files");
-    addPaginationOptions(list);
     list.option("--purpose <purpose>", "Filter by purpose (agent_input, knowledge)");
+    list.option("--limit <number>", "How many files to list (1-100)", "20");
+    list.option("--after <fileId>", "List the files after this one (the previous list's last id)");
+    list.option("--order <order>", "asc (oldest first) or desc (newest first)", "desc");
     list.action(async (opts, command) => {
         await runAction(command, async () => {
             const client = getClient(command);
             const { data } = await client.GET("/v1/files", {
-                params: { query: { purpose: opts.purpose, ...paginationParams(opts) } },
+                params: {
+                    query: {
+                        purpose: opts.purpose,
+                        limit: parseInt(opts.limit, 10),
+                        after: opts.after,
+                        order: opts.order,
+                    },
+                },
             });
-            formatPage(data, command, ["id", "filename", "purpose", "bytes", "created_at"]);
+            if (isJsonOutput(command)) {
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            formatList(data?.data, command, ["id", "filename", "purpose", "bytes", "created_at"]);
+            if (data?.has_more) {
+                console.log(chalk.dim(`More files: --after ${data.last_id}`));
+            }
         });
     });
     cmd.addCommand(list);

package/dist/commands/knowledge.js

@@ -86,10 +86,23 @@ export function makeKnowledgeCommand() {
         .option("--reranker-provider <id>", "New reranker provider ID")
         .option("--hybrid-search <bool>", "Enable hybrid search (true/false)")
         .option("--text-search-language <name>", "Change the text-search language (reindexes in the background); omit to leave it untouched")
+        .option("--cancel-text-search-reindex", "Abandon the text-search reindex in progress and keep the active language")
         .action(async (id, opts, command) => {
         await runAction(command, async () => {
             const client = getClient(command);
-            const body = {};
+            // The update takes the full body: name, slug, provider, model and dimension are required on
+            // every PATCH, so start from the stored values and overlay the flags. Optional fields left
+            // out keep their stored values server-side.
+            const { data: current } = await client.GET("/v1/knowledge-bases/{id}", {
+                params: { path: { id } },
+            });
+            const body = {
+                name: current?.name,
+                slug: current?.slug,
+                embeddingProviderId: current?.embeddingProviderId,
+                embeddingModel: current?.embeddingModel,
+                embeddingDim: current?.embeddingDim,
+            };
             if (opts.name)
                 body.name = opts.name;
             if (opts.description !== undefined)
@@ -112,6 +125,8 @@ export function makeKnowledgeCommand() {
                 body.hybridSearchEnabled = opts.hybridSearch === "true";
             if (opts.textSearchLanguage)
                 body.textSearchLanguage = opts.textSearchLanguage;
+            if (opts.cancelTextSearchReindex)
+                body.cancelTextSearchReindex = true;
             const { data } = await client.PATCH("/v1/knowledge-bases/{id}", {
                 params: { path: { id } },
                 body: body,

package/dist/commands/skills.js

@@ -138,7 +138,7 @@ export function makeSkillsCommand() {
                 const bundle = packSkillDirectory(path);
                 if (bundle.skipped.length > 0) {
                     // The server reports what it was sent; only the CLI can name what never left the disk.
-                    console.error(`Left out of the bundle (the importer takes SKILL.md, references/, assets/, scripts/): ${bundle.skipped.join(", ")}`);
+                    console.error(`Left out of the bundle (the importer takes SKILL.md, references/, assets/, scripts/, examples/): ${bundle.skipped.join(", ")}`);
                 }
                 blob = new Blob([bundle.bytes], { type: "application/zip" });
                 filename = bundle.filename;
@@ -171,6 +171,7 @@ export function makeSkillsCommand() {
         .option("-o, --output <file>", "Output path (default: <skill-name>-v<n>.zip)")
         .option("-d, --extract-to <dir>", "Unpack the bundle into this directory instead of writing a zip")
         .option("--force", "Write into a non-empty --extract-to directory")
+        .option("--include-examples", "Keep the confidential examples/ files (needs ADMIN or OWNER)")
         .action(async (id, versionNumber, opts, command) => {
         await runAction(command, async () => {
             if (opts.output && opts.extractTo)
@@ -189,14 +190,21 @@ export function makeSkillsCommand() {
             }
             const config = resolveConfig(command);
             const authHeader = await resolveAuthHeader(config);
+            let omitted = 0;
             const bytes = await withSpinner("Exporting skill...", async () => {
                 const baseUrl = config.baseUrl.replace(/\/+$/, "");
-                const res = await fetch(`${baseUrl}/v1/skills/${encodeURIComponent(id)}/versions/${encodeURIComponent(versionNumber)}/export`, {
+                const query = opts.includeExamples ? "?includeExamples=true" : "";
+                const res = await fetch(`${baseUrl}/v1/skills/${encodeURIComponent(id)}/versions/${encodeURIComponent(versionNumber)}/export${query}`, {
                     headers: { Authorization: authHeader },
                 });
                 await checkResponse(res);
+                omitted = Number(res.headers.get("X-Skill-Examples-Omitted") ?? 0);
                 return Buffer.from(await res.arrayBuffer());
             });
+            if (omitted > 0) {
+                // #926: a re-import of this bundle would drop them, so say so where the user looks.
+                console.error(`${omitted} confidential example file(s) left out; --include-examples (admin) keeps them`);
+            }
             if (opts.extractTo) {
                 mkdirSync(opts.extractTo, { recursive: true });
                 const written = unpackSkillBundle(new Uint8Array(bytes), opts.extractTo);

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { Command } from "commander";
+import { Command, CommanderError } from "commander";
 import { makeAuthCommand } from "./commands/auth.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
@@ -78,5 +78,20 @@ program.addCommand(makeConnectorsCommand());
 program.addCommand(makeRelaysCommand());
 program.addCommand(makeBridgeCommand());
 program.addCommand(makeDocsCommand());
-program.parseAsync().then(() => updater.notify());
+// Commander exits 1 on its own parse errors, and 1 is the exit code for API and network failures.
+// Every command throws instead, so a usage error exits 2 like a CliUsageError (#697).
+const throwOnExit = (cmd) => {
+    cmd.exitOverride();
+    cmd.commands.forEach(throwOnExit);
+};
+throwOnExit(program);
+program
+    .parseAsync()
+    .then(() => updater.notify())
+    .catch((err) => {
+    if (!(err instanceof CommanderError))
+        throw err;
+    // --help, --version and a command group's help without a subcommand succeed.
+    process.exit(err.exitCode === 0 || err.code === "commander.help" ? 0 : 2);
+});
 //# sourceMappingURL=index.js.map

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

@@ -60,7 +60,7 @@ export declare const CONVERSATION_MODES: readonly ConversationMode[];
 export declare const MODE_OPTION_HELP: string;
 /**
  * The `--mode` value, checked before any request is sent: anything but the three exact values is a
- * usage error (exit 2). Commander's `.choices()` is not used because it exits 1 through `process.exit`.
+ * usage error (exit 2).
  */
 export declare function parseModeOption(raw: string | undefined): ConversationMode | undefined;
 /** The `backbone:mode` input item (S1 D7); always appended last. */

package/dist/lib/agent-run.js

@@ -5,14 +5,15 @@ import { CliUsageError } from "./errors.js";
 import { previewIsIncomplete, previewLines } from "./skills-apply-preview.js";
 export const CONVERSATION_MODES = ["plan", "ask", "auto"];
 /** `--mode` help text, in the words of the embedded chat's mode chip (#655). */
-export const MODE_OPTION_HELP = "Conversation mode: plan (read-only), ask (no automatic approver; calls that need approval wait for you), " +
-    "auto (the operator's policy as written). Without it, the conversation keeps its mode";
+export const MODE_OPTION_HELP = "Conversation mode: plan (read-only), ask (calls that need approval wait for you), " +
+    "auto (the automatic approver decides reads and writes the server marks safe; the rest wait for you). " +
+    "Without it, the conversation keeps its mode, else the agent's default; a mode the agent does not offer is refused";
 function isConversationMode(value) {
     return typeof value === "string" && CONVERSATION_MODES.includes(value);
 }
 /**
  * The `--mode` value, checked before any request is sent: anything but the three exact values is a
- * usage error (exit 2). Commander's `.choices()` is not used because it exits 1 through `process.exit`.
+ * usage error (exit 2).
  */
 export function parseModeOption(raw) {
     if (raw === undefined)

package/dist/lib/errors.js

@@ -102,6 +102,7 @@ const CODE_HINTS = {
         "Check pendingToolCalls and pendingApprovals in the run envelope.",
     unknown_tool_output: "That call id was not released by this response. Use the responseId of the latest envelope.",
     conversation_agent_mismatch: "This conversation belongs to another agent. Start a new conversation or run the agent that owns it.",
+    conversation_mode_not_offered: "The agent does not offer that mode. Use one of the modes the message lists (plan is always offered), or leave --mode out for the agent's default.",
     provider_quota_exhausted: "The model provider account is out of credits or at its spend limit. Add credits or raise the limit with the provider; retrying will not help.",
 };
 /** The most specific hint for an API error: gateway code, then known messages, then the status table. */
@@ -117,6 +118,9 @@ export function hintFor(err) {
     }
     if (err.code && Object.hasOwn(CODE_HINTS, err.code))
         return CODE_HINTS[err.code];
+    // The REST layer (the explain view) spells the same refusal as an errorCode.
+    if (err.errorCode === "CONVERSATION_MODE_NOT_OFFERED")
+        return CODE_HINTS.conversation_mode_not_offered;
     // The gateway answers `agent_not_published` (code), the REST layer AGENT_NOT_PUBLISHED (errorCode).
     if (err.code === "agent_not_published" || err.errorCode === "AGENT_NOT_PUBLISHED") {
         return NOT_PUBLISHED_HINT;

package/dist/lib/skill-bundle.js

@@ -2,11 +2,12 @@ import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { unzipSync, zipSync } from "fflate";
 /**
- * The importer takes SKILL.md plus these three directories and reports anything else as
+ * The importer takes SKILL.md plus these four directories and reports anything else as
  * `unsupported-path` (spec §4). Packing only these keeps a stray .git or node_modules out of
- * the upload instead of spending the 20 MB bundle cap on it.
+ * the upload instead of spending the 20 MB bundle cap on it. `examples/` holds confidential
+ * files (#926): imported like the rest, left out of a plain export.
  */
-const RESOURCE_DIRS = ["references", "assets", "scripts"];
+const RESOURCE_DIRS = ["references", "assets", "scripts", "examples"];
 function byName(left, right) {
     return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai",
-  "version": "7.4.0-dev.9",
+  "version": "8.0.0-dev.11",
   "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",