@2kw/ai 7.1.0-dev.7 → 7.1.0

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

@@ -140,6 +140,99 @@ export function makeBillingCommand() {
     });
     cmd.addCommand(makeOverageCommand());
     cmd.addCommand(makeTopUpsCommand());
+    cmd.addCommand(makeUsageCommand());
+    return cmd;
+}
+/**
+ * `bb billing usage periods|period|external` — the console usage page's reads (#1076): platform usage
+ * as a share of the period's included usage, and usage on the organisation's own provider keys. All
+ * three need a member login.
+ */
+function makeUsageCommand() {
+    const cmd = new Command("usage").description("Show platform usage and usage on your own provider keys");
+    cmd
+        .command("periods")
+        .description("List billing periods, newest first (needs `bb auth login`)")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/usage/periods");
+            formatList((data ?? []), command, ["periodStart", "periodEnd", "kind"]);
+        });
+    });
+    cmd
+        .command("period")
+        .description("Show platform usage of a period, the current one by default (needs `bb auth login`)")
+        .option("--start <instant>", "A period start from `bb billing usage periods`")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/usage/period", {
+                params: { query: opts.start ? { periodStart: String(opts.start) } : {} },
+            });
+            if (isJsonOutput(command)) {
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            if (!data || data.accounting === "UNAVAILABLE") {
+                console.log(chalk.dim("Platform usage is not available for this organisation yet."));
+                return;
+            }
+            if (data.accounting === "SHADOW") {
+                console.log(chalk.yellow("Preview: usage is counted but not yet enforced."));
+            }
+            const plan = data.plan ? `${data.plan} ${data.usageLevel ?? ""}`.trim() : data.kind;
+            console.log(`Period:      ${data.periodStart?.slice(0, 10)} → ${data.periodEnd?.slice(0, 10)} (${plan})`);
+            console.log(`Used:        ${data.usedPercent == null ? "no included usage" : `${data.usedPercent} %`}`);
+            for (const meter of data.meters ?? []) {
+                console.log(`  ${(meter.meter ?? "").padEnd(18)} ${meter.percent ?? "-"} %   ${meter.quantity} ${meter.unit}`);
+            }
+            if (data.extraUsage) {
+                const state = data.extraUsage.enabled ? "" : chalk.dim(" (off)");
+                console.log(`Extra usage: €${data.extraUsage.spentEur} of €${data.extraUsage.capEur}${state}`);
+            }
+            if (data.prepaid) {
+                const expiry = data.prepaid.nextExpiry ? chalk.dim(` (next expiry ${data.prepaid.nextExpiry})`) : "";
+                console.log(`Prepaid:     €${data.prepaid.remainingEur}${expiry}`);
+            }
+        });
+    });
+    cmd
+        .command("external")
+        .description("Show usage on your own provider keys, estimated at list price (needs `bb auth login`)")
+        .option("--from <date>", "First day, YYYY-MM-DD (UTC); default 30 days ago")
+        .option("--to <date>", "Last day, YYYY-MM-DD (UTC), included; at most 90 days")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const query = {};
+            if (opts.from)
+                query.startDate = String(opts.from);
+            if (opts.to)
+                query.endDate = String(opts.to);
+            const { data } = await client.GET("/v1/usage/external", { params: { query } });
+            if (isJsonOutput(command)) {
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            if (!data?.available) {
+                console.log(chalk.dim("Usage capture is off."));
+                return;
+            }
+            const estimate = data.totals?.estimatedCostEur;
+            const total = estimate == null ? "not priced" : `~€${estimate}`;
+            console.log(`Range:      ${data.startDate} → ${data.endDate}`);
+            console.log(`Requests:   ${data.totals?.requests ?? 0}`);
+            console.log(`Estimated:  ${total} ${chalk.dim("(provider list price, billed by the provider)")}`);
+            const rows = (data.rows ?? []).map((row) => ({
+                provider: row.provider ?? "-",
+                model: row.model,
+                requests: row.requests,
+                estimate: row.estimatedCostEur == null ? "-" : `~€${row.estimatedCostEur}`,
+            }));
+            formatList(rows, command, ["provider", "model", "requests", "estimate"]);
+        });
+    });
     return cmd;
 }
 /** Whole euros from cents, e.g. 1234 → "€12.34". Amounts are net of VAT (#973 D-O). */

package/dist/commands/installations.js

@@ -1,8 +1,15 @@
 import { Command } from "commander";
 import { getClient, runAction } from "../lib/client.js";
+import { resolveConfig } from "../lib/config.js";
 import { CliUsageError } from "../lib/errors.js";
 import { formatPage, formatDetail, formatList, formatSuccess } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+/**
+ * Switching member sign-in on or off is a decision a signed-in person makes: the backend refuses an
+ * API key, however admin it is, so the command says so before it sends anything (see `SESSION_ONLY`
+ * in connectors.ts for the same wording).
+ */
+const SESSION_ONLY = "Signed-in admins only: run 2kw auth login and sign in through the browser; an API key is refused";
 const MIN_MONTHLY_PERCENT = 0;
 const MAX_MONTHLY_PERCENT = 1000;
 /**
@@ -217,6 +224,28 @@ export function makeInstallationsCommand() {
         });
     });
     cmd.addCommand(budget);
+    cmd
+        .command("member-login")
+        .description(`Allow or stop members signing in to this installation's app as themselves. Stopping signs everyone out of it. ${SESSION_ONLY}`)
+        .argument("<id>", "Installation ID")
+        .option("--enable", "Allow members to sign in")
+        .option("--disable", "Stop member sign-in and sign everyone out of the app")
+        .action(async (id, opts, command) => {
+        await runAction(command, async () => {
+            if (Boolean(opts.enable) === Boolean(opts.disable)) {
+                throw new CliUsageError("pass exactly one of --enable and --disable");
+            }
+            if (resolveConfig(command).kind === "apiKey") {
+                throw new CliUsageError(SESSION_ONLY);
+            }
+            const client = getClient(command);
+            const { data } = await client.PUT("/v1/installations/{id}/member-login", {
+                params: { path: { id } },
+                body: { enabled: Boolean(opts.enable) },
+            });
+            formatDetail(data, command);
+        });
+    });
     return cmd;
 }
 //# sourceMappingURL=installations.js.map

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.7",
+  "version": "7.1.0",
   "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",