@2kw/ai 6.2.0-dev.42 → 6.2.0-dev.49

package/README.md

@@ -110,6 +110,8 @@ kubectl-style contexts switch between organizations and environments:
 | `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 |
+| `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 |
 | `knowledge` | Manage knowledge bases, documents, search, and citations |
 | `files` | Upload, download, and manage files |

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

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+/**
+ * `agents policy <agent>` — what the policy gate would do to a call of each tool
+ * a version configures, without running the agent (&56 S6, #662).
+ *
+ * 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.
+ */
+export declare function makeAgentPolicyCommand(): Command;
+//# sourceMappingURL=agent-policy.d.ts.map

package/dist/commands/agent-policy.js

@@ -0,0 +1,64 @@
+import { Command } from "commander";
+import chalk from "chalk";
+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 { CliUsageError } from "../lib/errors.js";
+import { getLatestVersion } from "./agent-apply.js";
+/**
+ * `agents policy <agent>` — what the policy gate would do to a call of each tool
+ * a version configures, without running the agent (&56 S6, #662).
+ *
+ * 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.
+ */
+export function makeAgentPolicyCommand() {
+    return new Command("policy")
+        .description("Show the effective tool policy of an agent version")
+        .argument("<agent>", "Agent ID or name")
+        .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")
+        .action(async (agentRef, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const agent = await resolveAgent(client, agentRef);
+            const agentId = agent.id;
+            const versionId = opts.version ?? (await getLatestVersion(client, agentId))?.id;
+            if (!versionId) {
+                throw new CliUsageError(`Agent '${agent.name}' has no versions yet, so it has no policy to read. Create a version first.`);
+            }
+            const { data } = await client.GET("/v1/agents/{agentId}/versions/{versionId}/policy", {
+                params: {
+                    path: { agentId, versionId },
+                    query: { tool: opts.tool, installation: opts.installation },
+                },
+            });
+            if (isJsonOutput(command)) {
+                formatDetail(data, command);
+                return;
+            }
+            // Both deployment switches decide whether a JUDGE row ever reaches a
+            // 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)"}`,
+            ];
+            if (data?.catalogResolvedAt)
+                parts.push(`catalog resolved ${data.catalogResolvedAt}`);
+            console.log(chalk.dim(parts.join(", ")));
+            formatList(data?.tools, command, [
+                "tool",
+                "verdict",
+                "action",
+                "policyClass",
+                "source",
+                "matchedRules",
+            ]);
+        });
+    });
+}
+//# sourceMappingURL=agent-policy.js.map

package/dist/commands/agents.js

@@ -7,6 +7,7 @@ import { makeAgentLabelsCommand } from "./agent-labels.js";
 import { makeAgentDecideCommand, makeAgentRunCommand } from "./agent-run.js";
 import { makeAgentApplyCommand } from "./agent-apply.js";
 import { makeAgentExportCommand } from "./agent-export.js";
+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";
@@ -26,6 +27,21 @@ export function makeAgentsCommand() {
         });
     });
     cmd.addCommand(list);
+    // The chat-facing read (#814): published agents, {id, name, description} only, and the
+    // one agent endpoint a chat-only USER key may call. `list` needs VIEWER or higher.
+    const catalog = new Command("catalog").description("List published agents (id, name, description)");
+    addPaginationOptions(catalog);
+    catalog.option("-s, --search <term>", "Filter by name");
+    catalog.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/agents/catalog", {
+                params: { query: { search: opts.search, ...paginationParams(opts) } },
+            });
+            formatPage(data, command, ["id", "name", "description"]);
+        });
+    });
+    cmd.addCommand(catalog);
     cmd
         .command("get")
         .description("Get an agent by ID")
@@ -162,6 +178,7 @@ export function makeAgentsCommand() {
     cmd.addCommand(makeAgentExportCommand());
     cmd.addCommand(makeAgentInitCommand());
     cmd.addCommand(makeAgentSchemaCommand());
+    cmd.addCommand(makeAgentPolicyCommand());
     cmd.addCommand(makeAgentVersionsCommand());
     cmd.addCommand(makeAgentLabelsCommand());
     return cmd;

package/dist/commands/skills.js

@@ -1,10 +1,11 @@
 import { Command, Option } from "commander";
-import { statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, extname } from "node:path";
 import { getClient, resolveAuthHeader, runAction } from "../lib/client.js";
 import { resolveConfig } from "../lib/config.js";
 import { BackboneApiError } from "../lib/errors.js";
 import { fileToBlob } from "../lib/multipart.js";
+import { packSkillDirectory, unpackSkillBundle } from "../lib/skill-bundle.js";
 import { formatPage, formatDetail, formatSuccess, withSpinner } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
 import { makeSkillVersionsCommand } from "./skill-versions.js";
@@ -98,18 +99,29 @@ export function makeSkillsCommand() {
     });
     cmd
         .command("import")
-        .description("Import a local SKILL.md or zip archive")
-        .argument("<path>", "Local SKILL.md or .zip file")
+        .description("Import a local skill directory, SKILL.md or zip archive")
+        .argument("<path>", "Local skill directory, SKILL.md or .zip file")
         .action(async (path, _opts, command) => {
         await runAction(command, async () => {
-            if (statSync(path).isDirectory())
-                throw new Error("Cannot import a directory; zip it first.");
-            if (basename(path) !== "SKILL.md" && extname(path).toLowerCase() !== ".zip") {
-                throw new Error("Import requires a SKILL.md or .zip file.");
+            let blob;
+            let filename;
+            if (statSync(path).isDirectory()) {
+                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(", ")}`);
+                }
+                blob = new Blob([bundle.bytes], { type: "application/zip" });
+                filename = bundle.filename;
+            }
+            else {
+                if (basename(path) !== "SKILL.md" && extname(path).toLowerCase() !== ".zip") {
+                    throw new Error("Import requires a skill directory, a SKILL.md or a .zip file.");
+                }
+                ({ blob, filename } = fileToBlob(path));
             }
             const config = resolveConfig(command);
             const authHeader = await resolveAuthHeader(config);
-            const { blob, filename } = fileToBlob(path);
             const formData = new FormData();
             formData.append("file", blob, filename);
             const data = await withSpinner("Importing skill...", async () => {
@@ -126,14 +138,21 @@ export function makeSkillsCommand() {
     });
     cmd
         .command("export")
-        .description("Export a skill version as a zip archive")
+        .description("Export a skill version as a zip archive or into a directory")
         .argument("<id>", "Skill ID")
         .argument("<versionNumber>", "Version number")
         .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")
         .action(async (id, versionNumber, opts, command) => {
         await runAction(command, async () => {
+            if (opts.output && opts.extractTo)
+                throw new Error("Pass either --output or --extract-to, not both.");
+            if (opts.extractTo && existsSync(opts.extractTo) && readdirSync(opts.extractTo).length > 0 && !opts.force) {
+                throw new Error(`${opts.extractTo} is not empty. Pass --force to write into it.`);
+            }
             let outputPath = opts.output;
-            if (!outputPath) {
+            if (!outputPath && !opts.extractTo) {
                 const client = getClient(command);
                 const { data } = await client.GET("/v1/skills/{id}", { params: { path: { id } } });
                 if (!data?.name)
@@ -150,6 +169,12 @@ export function makeSkillsCommand() {
                 await checkResponse(res);
                 return Buffer.from(await res.arrayBuffer());
             });
+            if (opts.extractTo) {
+                mkdirSync(opts.extractTo, { recursive: true });
+                const written = unpackSkillBundle(new Uint8Array(bytes), opts.extractTo);
+                formatSuccess(`Wrote ${written.length} file(s) to ${opts.extractTo}: ${written.join(", ")}`, command);
+                return;
+            }
             writeFileSync(outputPath, bytes);
             formatSuccess(`Wrote ${bytes.length} bytes to ${outputPath}`, command);
         });

package/dist/lib/skill-bundle.d.ts

@@ -0,0 +1,15 @@
+export interface PackedSkill {
+    /** Pinned to an ArrayBuffer so the bytes go straight into a Blob without a cast. */
+    bytes: Uint8Array<ArrayBuffer>;
+    /** Upload filename: the importer dispatches on the `.zip` suffix, not on the content type. */
+    filename: string;
+    /** Bundle paths that went in, SKILL.md first. */
+    packed: string[];
+    /** Directory-relative entries left out, directories with a trailing slash. */
+    skipped: string[];
+}
+/** Zip a local skill directory in the layout `POST /v1/skills/import` expects. */
+export declare function packSkillDirectory(dir: string): PackedSkill;
+/** Unpack an exported skill bundle into a directory. Returns the bundle paths written. */
+export declare function unpackSkillBundle(bytes: Uint8Array, dir: string): string[];
+//# sourceMappingURL=skill-bundle.d.ts.map

package/dist/lib/skill-bundle.js

@@ -0,0 +1,80 @@
+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
+ * `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.
+ */
+const RESOURCE_DIRS = ["references", "assets", "scripts"];
+function byName(left, right) {
+    return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
+}
+/** Collect one resource directory. A stable order keeps the same directory hashing the same. */
+function collect(dir, prefix, files, packed, skipped) {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort(byName)) {
+        const path = `${prefix}${entry.name}`;
+        if (entry.isDirectory())
+            collect(join(dir, entry.name), `${path}/`, files, packed, skipped);
+        // Symlinks, sockets and devices are reported rather than followed: reading one can leave
+        // the directory the user named.
+        else if (!entry.isFile())
+            skipped.push(path);
+        else {
+            files[path] = new Uint8Array(readFileSync(join(dir, entry.name)));
+            packed.push(path);
+        }
+    }
+}
+/** Zip a local skill directory in the layout `POST /v1/skills/import` expects. */
+export function packSkillDirectory(dir) {
+    const root = readdirSync(dir, { withFileTypes: true }).sort(byName);
+    if (!root.some((entry) => entry.isFile() && entry.name === "SKILL.md")) {
+        throw new Error(`${join(dir, "SKILL.md")} not found: a skill directory holds SKILL.md at its root.`);
+    }
+    const files = {
+        "SKILL.md": new Uint8Array(readFileSync(join(dir, "SKILL.md"))),
+    };
+    const packed = ["SKILL.md"];
+    const skipped = [];
+    for (const entry of root) {
+        if (entry.isFile() && entry.name === "SKILL.md")
+            continue;
+        if (entry.isDirectory() && RESOURCE_DIRS.includes(entry.name)) {
+            collect(join(dir, entry.name), `${entry.name}/`, files, packed, skipped);
+        }
+        else
+            skipped.push(entry.isDirectory() ? `${entry.name}/` : entry.name);
+    }
+    return { bytes: new Uint8Array(zipSync(files)), filename: `${basename(resolve(dir))}.zip`, packed, skipped };
+}
+/**
+ * Refuse what the backend refuses on import (SkillBundleReader.validatePath), so a crafted
+ * archive cannot write outside the directory the user named.
+ */
+function assertSafePath(path) {
+    const parts = path.split("/");
+    if (path === "" ||
+        path.startsWith("/") ||
+        path.includes("\\") ||
+        /^[A-Za-z]:/.test(path) ||
+        parts.some((part) => part === ".." || part === ".") ||
+        [...path].some((character) => character.charCodeAt(0) < 32)) {
+        throw new Error(`The archive holds an unsafe path and was not written: ${path}`);
+    }
+}
+/** Unpack an exported skill bundle into a directory. Returns the bundle paths written. */
+export function unpackSkillBundle(bytes, dir) {
+    const written = [];
+    for (const [path, content] of Object.entries(unzipSync(bytes))) {
+        if (path.endsWith("/"))
+            continue;
+        assertSafePath(path);
+        const target = join(dir, ...path.split("/"));
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, content);
+        written.push(path);
+    }
+    return written.sort();
+}
+//# sourceMappingURL=skill-bundle.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai",
-  "version": "6.2.0-dev.42",
+  "version": "6.2.0-dev.49",
   "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",
@@ -51,6 +51,7 @@
     "cli-table3": "^0.6.5",
     "commander": "^13.1.0",
     "conf": "^13.1.0",
+    "fflate": "^0.8.3",
     "open": "^10.2.0",
     "openapi-fetch": "^0.13.5",
     "ora": "^8.2.0",