@2kw/ai 7.1.0-dev.14 → 7.1.0-dev.16

package/dist/commands/agent-apply.js

@@ -3,6 +3,7 @@ import chalk from "chalk";
 import { getClient, runAction } from "../lib/client.js";
 import { isJsonOutput } from "../lib/config.js";
 import { BackboneApiError, CliUsageError } from "../lib/errors.js";
+import { ensurePublished } from "../lib/agent-publish.js";
 import { findAgentByName } from "../lib/agent-lookup.js";
 import { loadAgentConfig, maskSecrets } from "../agent-config/file.js";
 import { CONFIG_FIELDS, planApply } from "../agent-config/plan.js";
@@ -110,30 +111,31 @@ export function makeAgentApplyCommand() {
                 let versionId = latest?.id;
                 version = latest?.versionNumber ?? null;
                 if (plan.action === "created") {
-                    let created;
-                    try {
-                        ({ data: created } = await client.POST("/v1/agents", {
-                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                            body: agentBody(config),
-                        }));
-                    }
-                    catch (err) {
-                        if (err instanceof BackboneApiError && err.status === 500) {
-                            throw new BackboneApiError({
-                                status: err.status,
-                                error: err.errorType,
-                                message: `${err.message} — an agent named "${config.name}" may already exist`,
-                                timestamp: err.timestamp,
-                                code: err.code,
-                            });
-                        }
-                        throw err;
-                    }
+                    // A duplicate name answers 409 with the backend's own message (#668).
+                    const { data: created } = await client.POST("/v1/agents", {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        body: agentBody(config),
+                    });
                     if (!created?.id)
                         throw new Error("Agent was created but the response has no id");
                     agentId = String(created.id);
+                    // Create publishes version 1 (#668); an older backend does not, so publish as a fallback.
+                    const head = await ensurePublished(client, created, versionBody(config, opts.message));
+                    versionId = head.versionId;
+                    version = head.version;
+                    // A message given on the command line is kept in the history as a second version (D4);
+                    // the default message is not worth a version of its own.
+                    if (!head.fallback && command.getOptionValueSource("message") === "cli") {
+                        const { data: v } = await client.POST("/v1/agents/{agentId}/versions", {
+                            params: { path: { agentId } },
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            body: versionBody(config, opts.message),
+                        });
+                        versionId = v?.id;
+                        version = v?.versionNumber ?? null;
+                    }
                 }
-                if (plan.action === "created" || plan.action === "versioned") {
+                if (plan.action === "versioned") {
                     const { data: v } = await client.POST("/v1/agents/{agentId}/versions", {
                         params: { path: { agentId: agentId } },
                         // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/commands/agents.js

@@ -10,6 +10,7 @@ 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 { ensurePublished } from "../lib/agent-publish.js";
 import { collectModel, MODEL_HELP, MODELS_HELP, modelFieldsFromOptions } from "../lib/agent-models.js";
 import { assertNameNotBlank } from "../lib/overlay.js";
 export function makeAgentsCommand() {
@@ -58,7 +59,7 @@ export function makeAgentsCommand() {
     });
     cmd
         .command("create")
-        .description("Create a new agent")
+        .description("Create a new agent; it is published as version 1 and runnable at once")
         .requiredOption("-n, --name <name>", "Agent name")
         .option("-m, --model <model>", MODEL_HELP, collectModel)
         .option("--models <list>", MODELS_HELP)
@@ -72,18 +73,38 @@ export function makeAgentsCommand() {
         await runAction(command, async () => {
             const models = modelFieldsFromOptions(opts, true);
             const client = getClient(command);
+            const tools = opts.tools ? JSON.parse(opts.tools) : undefined;
+            const skills = opts.skills ? JSON.parse(opts.skills) : undefined;
+            const options = opts.options ? JSON.parse(opts.options) : undefined;
+            const hitlPolicy = opts.hitlPolicy ? JSON.parse(opts.hitlPolicy) : undefined;
             const { data } = await client.POST("/v1/agents", {
                 body: {
                     name: opts.name,
                     ...models,
                     description: opts.description,
                     instructions: opts.instructions,
-                    options: opts.options ? JSON.parse(opts.options) : undefined,
-                    tools: opts.tools ? JSON.parse(opts.tools) : undefined,
-                    skills: opts.skills ? JSON.parse(opts.skills) : undefined,
-                    hitlPolicy: opts.hitlPolicy ? JSON.parse(opts.hitlPolicy) : undefined,
+                    options,
+                    tools,
+                    skills,
+                    hitlPolicy,
                 },
             });
+            if (data?.id) {
+                // Create publishes version 1; an older backend leaves it unpublished, so publish then.
+                const head = await ensurePublished(client, data, {
+                    ...models,
+                    instructions: opts.instructions,
+                    options,
+                    tools,
+                    skills,
+                    hitlPolicy,
+                    changeDescription: "Initial version",
+                });
+                // Report the head the fallback just published, not the pre-publish create response.
+                if (head.fallback && head.versionId) {
+                    Object.assign(data, { latestVersionId: head.versionId, latestVersionNumber: head.version ?? undefined });
+                }
+            }
             formatDetail(maskSecrets(data, []), command);
         });
     });

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

@@ -0,0 +1,15 @@
+import type { AgentDTO, ApiClient } from "./agent-lookup.js";
+export interface PublishedHead {
+    versionId: string | undefined;
+    version: number | null;
+}
+/**
+ * The head of a just-created agent. A backend that publishes version 1 on create (#668) answers with
+ * `latestVersionId`: use it. An older backend leaves the agent unpublished, so publish with
+ * `POST /v1/agents/{agentId}/versions` as before. One path, correct against either backend, so neither
+ * deploy order nor a backend rollback leaves a new agent unrunnable.
+ */
+export declare function ensurePublished(client: ApiClient, created: AgentDTO, versionBody: Record<string, unknown>): Promise<PublishedHead & {
+    fallback: boolean;
+}>;
+//# sourceMappingURL=agent-publish.d.ts.map

package/dist/lib/agent-publish.js

@@ -0,0 +1,18 @@
+/**
+ * The head of a just-created agent. A backend that publishes version 1 on create (#668) answers with
+ * `latestVersionId`: use it. An older backend leaves the agent unpublished, so publish with
+ * `POST /v1/agents/{agentId}/versions` as before. One path, correct against either backend, so neither
+ * deploy order nor a backend rollback leaves a new agent unrunnable.
+ */
+export async function ensurePublished(client, created, versionBody) {
+    if (created.latestVersionId) {
+        return { versionId: created.latestVersionId, version: created.latestVersionNumber ?? 1, fallback: false };
+    }
+    const { data: v } = await client.POST("/v1/agents/{agentId}/versions", {
+        params: { path: { agentId: String(created.id) } },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        body: versionBody,
+    });
+    return { versionId: v?.id, version: v?.versionNumber ?? null, fallback: true };
+}
+//# sourceMappingURL=agent-publish.js.map

package/dist/lib/errors.js

@@ -94,6 +94,7 @@ const HINTS = {
     429: "Rate limit exceeded. Wait a moment and try again.",
 };
 const PENDING_APPROVALS_HINT = "The approval was already decided or its response was superseded. See what is still pending: 2kw agents approvals --agent <agent-id> --status pending";
+const NOT_PUBLISHED_HINT = "The agent has no published version. Run: 2kw agents apply -f agent.yaml (or 2kw agents versions create).";
 const CODE_HINTS = {
     approval_hmac_mismatch: PENDING_APPROVALS_HINT,
     unknown_approval_id: PENDING_APPROVALS_HINT,
@@ -115,6 +116,10 @@ export function hintFor(err) {
     }
     if (err.code && CODE_HINTS[err.code])
         return CODE_HINTS[err.code];
+    // 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;
+    }
     // The 403 whose cause is the credential, not the role (#805). Without this the
     // generic 403 hint tells an organization admin to check a role that is already
     // right, and no role would ever have fixed it. Matched on the backend's error code,
@@ -125,7 +130,7 @@ export function hintFor(err) {
     // Anchored on the agent service's wording: prompts and schemas send the same
     // "Label '<x>' not found" prefix, and must keep the generic 404 hint.
     if (err.status === 404 && /^Label 'latest' not found (on agent|for this agent)/.test(err.message)) {
-        return "The agent has no published version. Run: 2kw agents apply -f agent.yaml (or 2kw agents versions create).";
+        return NOT_PUBLISHED_HINT;
     }
     if (err.status === 404 && /^Label '.+' not found (on agent|for this agent)/.test(err.message)) {
         return "That label does not exist on the agent. List labels: 2kw agents labels list --agent <agent-id>";

package/package.json

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