@2kw/ai 6.3.0-dev.91 → 6.3.0-dev.96

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";
@@ -216,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,
@@ -74,7 +77,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." },
                 },
             },

package/dist/commands/agents.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)

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);
         });

package/dist/commands/experiments.js

@@ -5,6 +5,7 @@ import Table from "cli-table3";
 import { getClient, runAction } from "../lib/client.js";
 import { formatPage, formatDetail, formatList, formatSuccess, withSpinner } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+import { assertNameNotBlank, overlay } from "../lib/overlay.js";
 import { isJsonOutput } from "../lib/config.js";
 const TERMINAL_STATUSES = new Set(["COMPLETED", "FAILED"]);
 /** Summarize a single cell of the comparison matrix (a variant's result for one item). */
@@ -92,21 +93,24 @@ export function makeExperimentsCommand() {
         .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,
+                datasetVersionId: opts.datasetVersion,
+                metadata: opts.metadata ? JSON.parse(opts.metadata) : undefined,
+            };
             const client = getClient(command);
-            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.datasetVersion !== undefined)
-                body.datasetVersionId = opts.datasetVersion;
-            if (opts.metadata)
-                body.metadata = JSON.parse(opts.metadata);
+            // PUT /v1/experiments/{id} replaces the whole experiment, so an omitted field would be stored as null.
+            const { data: current } = await client.GET("/v1/experiments/{id}", {
+                params: { path: { id } },
+            });
+            if (!current)
+                throw new Error(`Experiment ${id} could not be read.`);
             const { data } = await client.PUT("/v1/experiments/{id}", {
                 params: { path: { id } },
-                body: body,
+                body: overlay(current, changes),
             });
             formatDetail(data, command);
         });
@@ -185,21 +189,27 @@ export function makeExperimentsCommand() {
         .option("--sort-order <n>", "Sort order", parseInt)
         .action(async (variantId, opts, command) => {
         await runAction(command, async () => {
+            assertNameNotBlank(opts.name);
+            const changes = {
+                name: opts.name,
+                taskType: opts.taskType,
+                configuration: opts.config ? JSON.parse(opts.config) : undefined,
+                description: opts.description,
+                sortOrder: opts.sortOrder,
+            };
             const client = getClient(command);
-            const body = {};
-            if (opts.name !== undefined)
-                body.name = opts.name;
-            if (opts.taskType !== undefined)
-                body.taskType = opts.taskType;
-            if (opts.config)
-                body.configuration = JSON.parse(opts.config);
-            if (opts.description !== undefined)
-                body.description = opts.description;
-            if (opts.sortOrder !== undefined)
-                body.sortOrder = opts.sortOrder;
+            // The variant PUT writes name, description and configuration as sent, so an omitted one would
+            // be cleared. There is no single-variant GET: read it from the list. The read's version goes
+            // back with the body, so a change made since is refused with 409.
+            const { data: variants } = await client.GET("/v1/experiments/{id}/variants", {
+                params: { path: { id: opts.experiment } },
+            });
+            const current = variants?.find((v) => v.id === variantId);
+            if (!current)
+                throw new Error(`Variant ${variantId} is not a variant of experiment ${opts.experiment}.`);
             const { data } = await client.PUT("/v1/experiments/{id}/variants/{variantId}", {
                 params: { path: { id: opts.experiment, variantId } },
-                body: body,
+                body: overlay(current, changes),
             });
             formatDetail(data, command);
         });

package/dist/commands/prompts.js

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { getClient, runAction } from "../lib/client.js";
 import { formatPage, formatDetail, formatSuccess } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+import { assertNameNotBlank, overlay } from "../lib/overlay.js";
 import { makePromptVersionsCommand } from "./prompt-versions.js";
 import { makePromptLabelsCommand } from "./prompt-labels.js";
 export function makePromptsCommand() {
@@ -59,17 +60,17 @@ export function makePromptsCommand() {
         .option("--type <type>", "New type")
         .action(async (id, opts, command) => {
         await runAction(command, async () => {
+            assertNameNotBlank(opts.name);
             const client = getClient(command);
-            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;
+            // PUT /v1/prompts/{id} replaces the whole prompt, so an omitted field would be stored as null.
+            const { data: current } = await client.GET("/v1/prompts/{id}", {
+                params: { path: { id } },
+            });
+            if (!current)
+                throw new Error(`Prompt ${id} could not be read.`);
             const { data } = await client.PUT("/v1/prompts/{id}", {
                 params: { path: { id } },
-                body: body,
+                body: overlay(current, { name: opts.name, description: opts.description, type: opts.type }),
             });
             formatDetail(data, command);
         });

package/dist/commands/schemas.js

@@ -58,15 +58,24 @@ export function makeSchemasCommand() {
         .option("-d, --description <text>", "New description")
         .action(async (id, opts, command) => {
         await runAction(command, async () => {
+            let name = opts.name;
+            let description = opts.description;
+            if (name !== undefined && !name.trim())
+                throw new Error("--name must not be empty.");
             const client = getClient(command);
-            const body = {};
-            if (opts.name)
-                body.name = opts.name;
-            if (opts.description !== undefined)
-                body.description = opts.description;
+            // PUT /v1/schemas/{id} replaces the whole schema, so an omitted field would be stored as null.
+            if (name === undefined || description === undefined) {
+                const { data: current } = await client.GET("/v1/schemas/{id}", {
+                    params: { path: { id } },
+                });
+                if (!current)
+                    throw new Error(`Schema ${id} could not be read.`);
+                name ??= current.name;
+                description ??= current.description;
+            }
             const { data } = await client.PUT("/v1/schemas/{id}", {
                 params: { path: { id } },
-                body: body,
+                body: { name, description },
             });
             formatDetail(data, command);
         });

package/dist/commands/skills.js

@@ -186,7 +186,8 @@ export function makeSkillsCommand() {
                 const { data } = await client.GET("/v1/skills/{id}", { params: { path: { id } } });
                 if (!data?.name)
                     throw new Error("Skill name missing; specify an output path with -o.");
-                outputPath = `${basename(data.name)}-v${versionNumber}.zip`;
+                // #788: ":" (a plugin skill) becomes "." before basename, which on Windows reads "a:" as a drive.
+                outputPath = `${basename(data.name.replace(/:/g, "."))}-v${versionNumber}.zip`;
             }
             const config = resolveConfig(command);
             const authHeader = await resolveAuthHeader(config);

package/dist/lib/overlay.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The body for a PUT that replaces the whole row: the stored resource as its GET returned it, with
+ * every change the caller gave written over it. A change that is `undefined` was not given and keeps
+ * the stored value; the backend would store it as null otherwise (#1195). Server-managed fields in
+ * `current` (a dataset's or prompt's latestVersionId) go back as read, which is what keeps them.
+ */
+export declare function overlay<T extends object>(current: T, changes: Record<string, unknown>): T;
+/** Refuses a --name that is present but blank, which a full-replace PUT would otherwise store. */
+export declare function assertNameNotBlank(name: string | undefined): void;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/lib/overlay.js

@@ -0,0 +1,20 @@
+/**
+ * The body for a PUT that replaces the whole row: the stored resource as its GET returned it, with
+ * every change the caller gave written over it. A change that is `undefined` was not given and keeps
+ * the stored value; the backend would store it as null otherwise (#1195). Server-managed fields in
+ * `current` (a dataset's or prompt's latestVersionId) go back as read, which is what keeps them.
+ */
+export function overlay(current, changes) {
+    const body = { ...current };
+    for (const [key, value] of Object.entries(changes)) {
+        if (value !== undefined)
+            body[key] = value;
+    }
+    return body;
+}
+/** Refuses a --name that is present but blank, which a full-replace PUT would otherwise store. */
+export function assertNameNotBlank(name) {
+    if (name !== undefined && !name.trim())
+        throw new Error("--name must not be empty.");
+}
+//# sourceMappingURL=overlay.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai",
-  "version": "6.3.0-dev.91",
+  "version": "6.3.0-dev.96",
   "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",