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

package/README.md

@@ -85,7 +85,8 @@ kubectl-style contexts switch between organizations and environments:
 ```bash
 2kw context list              # List all contexts
 2kw context use acme-corp     # Switch active context
-2kw context create staging    # Create a new context
+2kw context create staging --base-url https://api.staging.example   # Create a context, sign in through the browser
+2kw context create ci --api-key sk_...   # Or store an API key instead
 ```
 
 `2kw config set memory true` makes an API-key context send `X-Backbone-Memory: enabled` on `ai respond` and `agents run` calls, which opts those runs into agent memory; `AI_2KW_MEMORY=true|false` overrides it per shell. Runs from a browser-login (session) context are always eligible for agent memory regardless of this setting, so `memory false` only affects API-key contexts.

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

@@ -11,8 +11,8 @@ export declare function redactSecrets(tools: Record<string, unknown>[] | undefin
     envNames: string[];
 };
 /**
- * Tool entries the backend stores but never runs (planner/runtime-injected or executor-less,
- * e.g. a console-stored `web_search`). agent.yaml cannot author them, so export drops them.
+ * Tool entries the backend stores but never runs as authored (planner- or runtime-injected,
+ * e.g. `backbone.tool_search`). agent.yaml cannot author them, so export drops them.
  */
 export declare function dropInertTools(tools: Record<string, unknown>[] | undefined): {
     tools: Record<string, unknown>[] | undefined;

package/dist/agent-config/export.js

@@ -43,8 +43,8 @@ export function redactSecrets(tools) {
     return { tools: redacted, envNames: [...owners.keys()] };
 }
 /**
- * Tool entries the backend stores but never runs (planner/runtime-injected or executor-less,
- * e.g. a console-stored `web_search`). agent.yaml cannot author them, so export drops them.
+ * Tool entries the backend stores but never runs as authored (planner- or runtime-injected,
+ * e.g. `backbone.tool_search`). agent.yaml cannot author them, so export drops them.
  */
 export function dropInertTools(tools) {
     if (!tools)

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

@@ -138,6 +138,77 @@ export declare const agentSchema: {
                 };
             };
         };
+        readonly webSearchTool: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["type"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "web_search";
+                };
+                readonly config: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly source: {
+                            readonly enum: readonly ["builtin", "external", "native"];
+                        };
+                        readonly searchProviderId: {
+                            readonly type: readonly ["string", "null"];
+                        };
+                        readonly fallback: {
+                            readonly enum: readonly ["builtin", "external"];
+                        };
+                        readonly allowedDomains: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                                readonly pattern: "^(?=.{1,253}$)([\\p{L}\\p{N}](?:[\\p{L}\\p{N}-]{0,61}[\\p{L}\\p{N}])?\\.)+\\p{L}(?:[\\p{L}\\p{N}-]{0,61}[\\p{L}\\p{N}])?$";
+                            };
+                            readonly maxItems: 10;
+                        };
+                    };
+                    readonly if: {
+                        readonly anyOf: readonly [{
+                            readonly required: readonly ["source"];
+                            readonly properties: {
+                                readonly source: {
+                                    readonly const: "external";
+                                };
+                            };
+                        }, {
+                            readonly required: readonly ["source", "fallback"];
+                            readonly properties: {
+                                readonly source: {
+                                    readonly const: "native";
+                                };
+                                readonly fallback: {
+                                    readonly const: "external";
+                                };
+                            };
+                        }];
+                    };
+                    readonly then: {
+                        readonly required: readonly ["searchProviderId"];
+                        readonly properties: {
+                            readonly searchProviderId: {
+                                readonly type: "string";
+                                readonly pattern: "\\S";
+                            };
+                        };
+                    };
+                    readonly else: {
+                        readonly properties: {
+                            readonly searchProviderId: {
+                                readonly type: "null";
+                            };
+                        };
+                    };
+                };
+                readonly requiresConfirmation: {
+                    readonly type: "boolean";
+                };
+            };
+        };
         readonly extractionTool: {
             readonly type: "object";
             readonly additionalProperties: false;
@@ -306,6 +377,18 @@ export declare const agentSchema: {
                 readonly then: {
                     readonly $ref: "#/$defs/fileSearchTool";
                 };
+            }, {
+                readonly if: {
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                readonly then: {
+                    readonly $ref: "#/$defs/webSearchTool";
+                };
             }, {
                 readonly if: {
                     required: string[];

package/dist/agent-config/schema.js

@@ -16,6 +16,9 @@ const MODEL_REF = {
     maxLength: 255,
     pattern: "^(?:[^/#]+|[A-Za-z0-9-]+/[^#]+)$",
 };
+// A plain hostname (no scheme, path, port or wildcard): dot-separated labels of letters, digits and
+// inner hyphens, Unicode or ASCII. Mirrors WebToolEntryValidator.HOST; needs a Unicode-aware regex engine.
+const HOSTNAME = "^(?=.{1,253}$)([\\p{L}\\p{N}](?:[\\p{L}\\p{N}-]{0,61}[\\p{L}\\p{N}])?\\.)+\\p{L}(?:[\\p{L}\\p{N}-]{0,61}[\\p{L}\\p{N}])?$";
 const oneOfLowercase = (...values) => ({ type: "string", enum: values });
 /** Types the backend injects or cannot execute; authoring them has no effect or breaks the run. */
 export const NON_AUTHORABLE_TOOL_TYPES = {
@@ -27,10 +30,10 @@ export const NON_AUTHORABLE_TOOL_TYPES = {
     "backbone.deliver": "it is added at run time while sandbox outputs are held",
     // #1244: injected wherever backbone.bash is advertised; an authored copy is dropped.
     "backbone.view_image": "it is added at run time wherever the sandboxed shell is",
-    web_search: "it has no executor and is skipped",
 };
 const BUILTIN_TYPES = [
     "file_search",
+    "web_search",
     "backbone.extraction",
     "backbone.document_convert",
     "backbone.todo",
@@ -118,6 +121,35 @@ export const agentSchema = {
                 },
             },
         },
+        // A missing config, `config: {}` or a missing source runs the built-in search. Mirrors
+        // WebToolEntryValidator; `config` stays open so later sources' fields do not break older CLIs.
+        webSearchTool: {
+            type: "object",
+            additionalProperties: false,
+            required: ["type"],
+            properties: {
+                type: { const: "web_search" },
+                config: {
+                    type: "object",
+                    properties: {
+                        source: { enum: ["builtin", "external", "native"] },
+                        searchProviderId: { type: ["string", "null"] },
+                        fallback: { enum: ["builtin", "external"] },
+                        allowedDomains: { type: "array", items: { type: "string", pattern: HOSTNAME }, maxItems: 10 },
+                    },
+                    // A provider id is required exactly when an external provider serves the search.
+                    if: {
+                        anyOf: [
+                            { required: ["source"], properties: { source: { const: "external" } } },
+                            { required: ["source", "fallback"], properties: { source: { const: "native" }, fallback: { const: "external" } } },
+                        ],
+                    },
+                    then: { required: ["searchProviderId"], properties: { searchProviderId: { type: "string", pattern: "\\S" } } },
+                    else: { properties: { searchProviderId: { type: "null" } } },
+                },
+                requiresConfirmation: { type: "boolean" },
+            },
+        },
         extractionTool: {
             type: "object",
             additionalProperties: false,
@@ -204,6 +236,7 @@ export const agentSchema = {
             type: "object",
             allOf: [
                 { if: typeIs("file_search"), then: { $ref: "#/$defs/fileSearchTool" } },
+                { if: typeIs("web_search"), then: { $ref: "#/$defs/webSearchTool" } },
                 { if: typeIs("backbone.extraction"), then: { $ref: "#/$defs/extractionTool" } },
                 { if: typeIs("backbone.document_convert"), then: { $ref: "#/$defs/documentConvertTool" } },
                 { if: typeIs("backbone.todo"), then: { $ref: "#/$defs/todoTool" } },

package/dist/agent-config/template.js

@@ -26,6 +26,9 @@ tools: []
 #   - type: file_search
 #     config:
 #       knowledgeBaseIds: [kb_id]
+#   - type: web_search
+#     config:
+#       allowedDomains: [example.com]
 #   - type: backbone.extraction
 #     config:
 #       schemaIds: [schema_id]

package/dist/agent-config/validate.js

@@ -6,6 +6,8 @@ const validate = ajv.compile(agentSchema);
 const NULLABLE_KEYS = ["description", "models", "instructions", "tools", "hitlPolicy", "options", "skills"];
 /** Tool-rule values the backend matches case-insensitively; the actions (approve, auto, deny) are exact. */
 const TOOL_RULE_CLASSES = new Set(["read", "write", "destructive"]);
+/** web_search config keys whose explicit `null` the backend reads as absent. */
+const WEB_SEARCH_NULLABLE_KEYS = ["source", "fallback", "searchProviderId", "allowedDomains"];
 const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /**
  * A deep copy of `doc` in the form the backend actually checks: explicit nulls it treats as absent
@@ -31,6 +33,8 @@ export function normalizeForValidation(doc) {
         for (const tool of copy.tools) {
             if (isPlainObject(tool) && tool.annotations === null)
                 delete tool.annotations;
+            if (isPlainObject(tool) && tool.type === "web_search")
+                normalizeWebSearch(tool);
         }
     }
     const policy = copy.hitlPolicy;
@@ -50,6 +54,21 @@ export function normalizeForValidation(doc) {
     }
     return copy;
 }
+/** WebToolEntryValidator reads a null config and null config fields as absent, and trims each domain. */
+function normalizeWebSearch(tool) {
+    if (tool.config === null)
+        delete tool.config;
+    const config = tool.config;
+    if (!isPlainObject(config))
+        return;
+    for (const key of WEB_SEARCH_NULLABLE_KEYS) {
+        if (config[key] === null)
+            delete config[key];
+    }
+    if (Array.isArray(config.allowedDomains)) {
+        config.allowedDomains = config.allowedDomains.map((d) => (typeof d === "string" ? d.trim() : d));
+    }
+}
 function describe(e) {
     // if/then wrappers restate the real error one level up; drop them. `not` only marks
     // non-authorable tool types, which validateAgentConfig reports with the reason.
@@ -75,6 +94,13 @@ function describe(e) {
     if (e.keyword === "const") {
         return { pointer, message: `must be ${JSON.stringify(params.allowedValue)}` };
     }
+    // The `else` branch of webSearchTool's provider rule: an id where no external provider serves the search.
+    if (e.keyword === "type" && params.type === "null" && pointer.endsWith("/config/searchProviderId")) {
+        return {
+            pointer,
+            message: "only allowed when an external provider serves the search (source external, or native with fallback external)",
+        };
+    }
     return { pointer, message: e.message ?? e.keyword };
 }
 export function validateAgentConfig(raw) {
@@ -98,11 +124,18 @@ export function validateAgentConfig(raw) {
         }
     }
     if (Array.isArray(record.tools)) {
+        let webSearchSeen = false;
         record.tools.forEach((tool, i) => {
             const type = tool?.type;
             if (typeof type === "string" && Object.hasOwn(NON_AUTHORABLE_TOOL_TYPES, type)) {
                 issues.push({ pointer: `/tools/${i}/type`, message: `type "${type}" cannot be authored: ${NON_AUTHORABLE_TOOL_TYPES[type]}` });
             }
+            // The backend refuses a second envelope (WebToolEntryValidator).
+            if (type === "web_search") {
+                if (webSearchSeen)
+                    issues.push({ pointer: `/tools/${i}/type`, message: "an agent may carry only one web_search tool" });
+                webSearchSeen = true;
+            }
         });
     }
     if (Array.isArray(record.skills)) {

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/auth.d.ts

@@ -14,6 +14,8 @@ type SessionConfig = Extract<ResolvedConfig, {
  * or a code that already carries its own separator) is shown untouched.
  */
 export declare function formatUserCode(code: string): string;
+/** Trailing slashes make `${authUrl}/api/auth/...` double up — drop them once, here. */
+export declare function stripTrailingSlash(url: string): string;
 /** Injection points for {@link deviceFlowLogin}; all default to the real thing. */
 export interface DeviceLoginDeps {
     requestCode?: typeof requestDeviceCode;
@@ -33,6 +35,9 @@ export interface DeviceLoginTarget {
     contextName: string;
     baseUrl: string;
     authUrl: string;
+    /** Make the context active once stored. Defaults to true; `context create`
+     *  turns it off for every context but the first. */
+    activate?: boolean;
 }
 /**
  * The browser login, end to end: ask for a device code, wait for the user to

package/dist/commands/auth.js

@@ -27,7 +27,7 @@ export function formatUserCode(code) {
     return code.length === 8 ? `${code.slice(0, 4)}-${code.slice(4)}` : code;
 }
 /** Trailing slashes make `${authUrl}/api/auth/...` double up — drop them once, here. */
-function stripTrailingSlash(url) {
+export function stripTrailingSlash(url) {
     return url.replace(/\/+$/, "");
 }
 /**
@@ -65,7 +65,7 @@ async function tryOpenBrowser(url) {
  */
 export async function deviceFlowLogin(target, deps = {}) {
     const { requestCode = requestDeviceCode, poll = pollDeviceToken, runPolling = runDevicePolling, sessionInfo = getSessionInfo, listOrgs = listOrganizations, chooseOrg = selectOrganization, setActiveOrg = setActiveOrganization, revoke = revokeSession, openBrowser = tryOpenBrowser, saveContext = setContext, activateContext = setActiveContext, } = deps;
-    const { contextName, baseUrl, authUrl } = target;
+    const { contextName, baseUrl, authUrl, activate = true } = target;
     const device = await requestCode(authUrl, CLI_CLIENT_ID);
     console.log("");
     console.log(`Open ${chalk.cyan(device.verification_uri_complete)}`);
@@ -121,10 +121,14 @@ export async function deviceFlowLogin(target, deps = {}) {
     }
     // Outside the guard on purpose: the session is on disk now, so a failure to
     // mark the context active still leaves a credential the user can reach.
-    activateContext(contextName);
+    if (activate)
+        activateContext(contextName);
     console.log(chalk.green(`Logged in as ${email}`));
     console.log(chalk.dim(`  — organization: ${org.name}`));
     console.log(chalk.dim(`Config stored at: ${store.path}`));
+    if (!activate) {
+        console.log(chalk.dim(`Switch to it with "2kw context use ${contextName}".`));
+    }
 }
 /**
  * The pre-device-flow login: take an API key from the flag or the terminal and

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/context.d.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { updateContext } from "../lib/config.js";
+import { type DeviceLoginDeps } from "./auth.js";
 import { listOrganizations, setActiveOrganization } from "../lib/auth-service.js";
 import { selectOrganization, type Asker } from "../lib/auth-session.js";
 /** Injection points for {@link performSetOrg}; all default to the real thing. */
@@ -24,5 +25,9 @@ export interface SetOrgDeps {
  * @param orgArg an organization id or slug; omitted means "prompt".
  */
 export declare function performSetOrg(orgArg: string | undefined, deps?: SetOrgDeps): Promise<void>;
-export declare function makeContextCommand(): Command;
+/**
+ * @param deviceDeps forwarded to {@link deviceFlowLogin} by `context create` —
+ *   a seam for tests, as on `makeAuthCommand`.
+ */
+export declare function makeContextCommand(deviceDeps?: DeviceLoginDeps): Command;
 //# sourceMappingURL=context.d.ts.map

package/dist/commands/context.js

@@ -2,7 +2,8 @@ import { Command } from "commander";
 import chalk from "chalk";
 import Table from "cli-table3";
 import { createInterface } from "node:readline/promises";
-import { store, isJsonOutput, getAllContexts, getActiveContext, getActiveContextName, getContextCount, setContext, deleteContext, renameContext, setActiveContext, updateContext, validateContextName, DEFAULT_BASE_URL, } from "../lib/config.js";
+import { store, isJsonOutput, getAllContexts, getActiveContext, getActiveContextName, getContextCount, setContext, deleteContext, renameContext, setActiveContext, updateContext, validateContextName, defaultAuthUrlFor, DEFAULT_BASE_URL, } from "../lib/config.js";
+import { deviceFlowLogin, stripTrailingSlash } from "./auth.js";
 import { listOrganizations, setActiveOrganization, } from "../lib/auth-service.js";
 import { selectOrganization } from "../lib/auth-session.js";
 import { runAction } from "../lib/client.js";
@@ -76,7 +77,11 @@ export async function performSetOrg(orgArg, deps = {}) {
     }
     console.log(chalk.green(`Active organization: ${org.name} (${org.slug})`));
 }
-export function makeContextCommand() {
+/**
+ * @param deviceDeps forwarded to {@link deviceFlowLogin} by `context create` —
+ *   a seam for tests, as on `makeAuthCommand`.
+ */
+export function makeContextCommand(deviceDeps = {}) {
     const cmd = new Command("context").description("Manage CLI contexts for multiple environments");
     cmd
         .command("list")
@@ -125,10 +130,12 @@ export function makeContextCommand() {
     });
     cmd
         .command("create")
-        .description("Create a new context")
+        .description("Create a new context and sign in through the browser (or with an API key)")
         .argument("<name>", "Context name")
         .option("--base-url <url>", "Base URL")
-        .option("--api-key <key>", "API key")
+        .option("--auth-url <url>", "Auth service URL (defaults to the one matching the base URL)")
+        .option("--api-key <key>", "Save an API key instead of signing in through the browser")
+        .option("--manual", "Prompt for an API key instead of signing in through the browser")
         .action(async (name, _opts, command) => {
         validateContextName(name);
         // Merged, not own — the root program declares --base-url and --api-key
@@ -140,6 +147,17 @@ export function makeContextCommand() {
         if (contexts[name]) {
             throw new Error(`Context "${name}" already exists. Delete it first or choose a different name.`);
         }
+        // The same browser login as `auth login`, written into the new context
+        // instead of the active one. Only the first context becomes active, as
+        // with an API key below: creating one is not switching to it.
+        if (!opts.apiKey && !opts.manual) {
+            const baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;
+            const authUrl = stripTrailingSlash(opts.authUrl ?? defaultAuthUrlFor(baseUrl));
+            const activate = getContextCount() === 0;
+            console.log(chalk.dim(`Auth service: ${authUrl} (override with --auth-url)`));
+            await runAction(command, () => deviceFlowLogin({ contextName: name, baseUrl, authUrl, activate }, deviceDeps));
+            return;
+        }
         let baseUrl = opts.baseUrl;
         let apiKey = opts.apiKey;
         if (!baseUrl || !apiKey) {

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/agent-run.js

@@ -156,7 +156,8 @@ function relayDecideCommand(ref, responseId, calls, withApprovals) {
 /**
  * A connector tool's open approval, decoded from the standard `mcp_approval_request` item (#949). The item
  * is the MCP twin of `backbone:approval_request` (#805): it names the server and the tool, carries no call
- * id, policy class or status, and exists only while the decision is open, so its id doubles as the call id
+ * id or status (its policy class is an optional extension, #1084; "unknown" without it), and exists only
+ * while the decision is open, so its id doubles as the call id
  * and the tool is named as the approval row stores it, `mcp__<server_label>__<tool>`.
  */
 function connectorApproval(i) {
@@ -165,7 +166,7 @@ function connectorApproval(i) {
         callId: String(i.id),
         tool: `mcp__${String(i.server_label)}__${String(i.name)}`,
         arguments: parseArguments(i.arguments),
-        policyClass: "unknown",
+        policyClass: typeof i.policy_class === "string" ? i.policy_class : "unknown",
         reason: null,
         preview: null,
     };

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.1",
+  "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",