@2kw/ai 6.3.0-dev.12 → 6.3.0-dev.13

package/dist/commands/connectors.js

@@ -28,7 +28,8 @@ function parsePort(value) {
     if (value === undefined) {
         return undefined;
     }
-    const port = Number(value);
+    // Digits only: `Number` alone accepts " 8443 ", "0x20FB" and "8.443e3".
+    const port = /^\d{1,5}$/.test(value) ? Number(value) : NaN;
     if (!Number.isInteger(port) || port < MIN_PORT || port > MAX_PORT) {
         throw new CliUsageError(`--port must be a whole number between ${MIN_PORT} and ${MAX_PORT}, not '${value}'`);
     }

package/dist/commands/settings.d.ts

@@ -0,0 +1,13 @@
+import { Command } from "commander";
+/**
+ * Parses the value a setting takes: a JSON object. The server checks its shape per key
+ * (for agents.default: {"agentId": "<id>"}); this only refuses what can never be valid.
+ */
+export declare function parseSettingValue(raw: string): Record<string, unknown>;
+/**
+ * Organization and member settings (agent-first chat spec §3.1, §4). Without --org every
+ * write targets the caller's own member tier; --org writes the organization's, which needs
+ * the key's write role (ADMIN or OWNER for agents.default).
+ */
+export declare function makeSettingsCommand(): Command;
+//# sourceMappingURL=settings.d.ts.map

package/dist/commands/settings.js

@@ -0,0 +1,80 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { CliUsageError } from "../lib/errors.js";
+import { formatDetail } from "../lib/output.js";
+/**
+ * Parses the value a setting takes: a JSON object. The server checks its shape per key
+ * (for agents.default: {"agentId": "<id>"}); this only refuses what can never be valid.
+ */
+export function parseSettingValue(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CliUsageError(`Setting value is not valid JSON: ${raw}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliUsageError('Setting value must be a JSON object, e.g. \'{"agentId":"agt_123"}\'');
+    }
+    return parsed;
+}
+/**
+ * Organization and member settings (agent-first chat spec §3.1, §4). Without --org every
+ * write targets the caller's own member tier; --org writes the organization's, which needs
+ * the key's write role (ADMIN or OWNER for agents.default).
+ */
+export function makeSettingsCommand() {
+    const cmd = new Command("settings").description("Organization and member settings (e.g. agents.default)");
+    cmd
+        .command("get <key>")
+        .description("Show a setting: the effective value, its source and both tiers")
+        .action(async (key, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/settings/{key}", {
+                params: { path: { key } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("set <key> <json>")
+        .description("Set your own value, or the organization's with --org (ADMIN+)")
+        .option("--org", "Write the organization's value instead of your own")
+        .action(async (key, json, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const body = { value: parseSettingValue(json) };
+            const { data } = opts.org
+                ? await client.PUT("/v1/settings/{key}/org", {
+                    params: { path: { key } },
+                    body,
+                })
+                : await client.PUT("/v1/settings/{key}/member", {
+                    params: { path: { key } },
+                    body,
+                });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("unset <key>")
+        .description("Clear your own value, or the organization's with --org (ADMIN+)")
+        .option("--org", "Clear the organization's value instead of your own")
+        .action(async (key, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = opts.org
+                ? await client.DELETE("/v1/settings/{key}/org", {
+                    params: { path: { key } },
+                })
+                : await client.DELETE("/v1/settings/{key}/member", {
+                    params: { path: { key } },
+                });
+            formatDetail(data, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=settings.js.map

package/dist/index.js

@@ -21,6 +21,7 @@ import { makeDocsCommand } from "./commands/docs.js";
 import { makeContextCommand } from "./commands/context.js";
 import { makeExperimentsCommand } from "./commands/experiments.js";
 import { makeTracingCommand } from "./commands/tracing.js";
+import { makeSettingsCommand } from "./commands/settings.js";
 import { makeEvaluatorsCommand } from "./commands/evaluators.js";
 import { makeScoresCommand } from "./commands/scores.js";
 import { makeQueuesCommand } from "./commands/queues.js";
@@ -62,6 +63,7 @@ program.addCommand(makeEvaluatorsCommand());
 program.addCommand(makeScoresCommand());
 program.addCommand(makeQueuesCommand());
 program.addCommand(makeTracingCommand());
+program.addCommand(makeSettingsCommand());
 program.addCommand(makeAgentsCommand());
 program.addCommand(makeConversationsCommand());
 program.addCommand(makeKnowledgeCommand());

package/dist/lib/client.js

@@ -37,6 +37,8 @@ export const errorMiddleware = {
                 `HTTP ${response.status}: ${response.statusText}`,
             timestamp: body.timestamp ?? new Date().toISOString(),
             code: typeof nested?.code === "string" ? nested.code : undefined,
+            // A problem detail names its cause in `errorCode` (GlobalExceptionHandler).
+            errorCode: typeof body.errorCode === "string" ? body.errorCode : undefined,
         });
     },
 };

package/dist/lib/errors.d.ts

@@ -10,12 +10,18 @@ export interface ApiErrorBody {
     timestamp: string;
     /** Machine-readable code from an OpenAI-style gateway error, e.g. `approval_hmac_mismatch`. */
     code?: string;
+    /**
+     * Machine-readable code from a problem detail's `errorCode`, e.g. `CONNECTOR_HOST_SIGN_IN_REQUIRED`.
+     * Kept apart from {@link code}: that one holds lowercase gateway codes and is printed by `--json`.
+     */
+    errorCode?: string;
 }
 export declare class BackboneApiError extends Error {
     readonly status: number;
     readonly errorType: string;
     readonly timestamp: string;
     readonly code?: string;
+    readonly errorCode?: string;
     constructor(body: Omit<ApiErrorBody, "error"> & {
         error: string;
     });

package/dist/lib/errors.js

@@ -7,6 +7,7 @@ export class BackboneApiError extends Error {
     errorType;
     timestamp;
     code;
+    errorCode;
     constructor(body) {
         super(body.message);
         this.name = "BackboneApiError";
@@ -14,6 +15,7 @@ export class BackboneApiError extends Error {
         this.errorType = body.error;
         this.timestamp = body.timestamp;
         this.code = body.code;
+        this.errorCode = body.errorCode;
     }
 }
 /**
@@ -108,8 +110,9 @@ export function hintFor(err) {
         return CODE_HINTS[err.code];
     // 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.
-    if (err.status === 403 && /^Approved connector hosts are managed by a signed-in/.test(err.message)) {
+    // right, and no role would ever have fixed it. Matched on the backend's error code,
+    // so a reworded message cannot silently drop the hint.
+    if (err.errorCode === "CONNECTOR_HOST_SIGN_IN_REQUIRED") {
         return "Approved hosts need a browser sign-in: run 2kw auth login. An API key cannot manage them, whatever its role.";
     }
     // Anchored on the agent service's wording: prompts and schemas send the same

package/package.json

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