@2kw/ai 6.2.2 → 6.3.0-dev.105

package/dist/lib/client.d.ts

@@ -39,6 +39,14 @@ export declare function apiKeyAuthMiddleware(config: ApiKeyConfig): Middleware;
  * fires and cannot be replayed safely.
  */
 export declare function sessionAuthMiddleware(config: SessionConfig, deps?: SessionAuthDeps): Middleware;
+/** The per-request opt-in to agent memory for API-key runs (spec §3.3, D6, D7). */
+export declare const MEMORY_HEADER = "X-Backbone-Memory";
+/**
+ * Adds `X-Backbone-Memory: enabled` to `POST …/v1/responses`, the call that starts a run
+ * and that also carries approval decisions (`lib/agent-decide.ts`). No other request gets
+ * it; the server reads it only there.
+ */
+export declare const memoryHeaderMiddleware: Middleware;
 /**
  * The middleware stack for a resolved config, in registration order.
  *

package/dist/lib/client.js

@@ -1,5 +1,5 @@
 import createClient from "openapi-fetch";
-import { resolveConfig, isJsonOutput } from "./config.js";
+import { resolveConfig, isJsonOutput, memoryEnabled } from "./config.js";
 import { ensureJwt } from "./auth-session.js";
 import { BackboneApiError, handleError } from "./errors.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,
         });
     },
 };
@@ -83,6 +85,21 @@ export function sessionAuthMiddleware(config, deps = {}) {
         },
     };
 }
+/** The per-request opt-in to agent memory for API-key runs (spec §3.3, D6, D7). */
+export const MEMORY_HEADER = "X-Backbone-Memory";
+/**
+ * Adds `X-Backbone-Memory: enabled` to `POST …/v1/responses`, the call that starts a run
+ * and that also carries approval decisions (`lib/agent-decide.ts`). No other request gets
+ * it; the server reads it only there.
+ */
+export const memoryHeaderMiddleware = {
+    onRequest({ request }) {
+        if (request.method === "POST" && new URL(request.url).pathname.endsWith("/v1/responses")) {
+            request.headers.set(MEMORY_HEADER, "enabled");
+        }
+        return request;
+    },
+};
 /**
  * The middleware stack for a resolved config, in registration order.
  *
@@ -123,6 +140,8 @@ export function getClient(command) {
         baseUrl: config.baseUrl.replace(/\/+$/, ""),
     });
     client.use(...buildMiddleware(config));
+    if (memoryEnabled())
+        client.use(memoryHeaderMiddleware);
     return client;
 }
 /**

package/dist/lib/config.d.ts

@@ -14,6 +14,8 @@ export interface ContextEntry {
     cachedJwt?: string;
     /** Epoch millis when cachedJwt expires. */
     cachedJwtExp?: number;
+    /** Send `X-Backbone-Memory: enabled` on responses calls (`2kw config set memory true`, #721). */
+    memory?: boolean;
 }
 export interface BackboneConfigStore {
     activeContext: string;
@@ -50,11 +52,25 @@ export declare const DEFAULT_BASE_URL: string;
  */
 export declare const DEFAULT_AUTH_URL: string;
 export declare function defaultAuthUrlFor(baseUrl: string): string;
+/** Fallback chat.2kw.ai origin when the API host is not one we recognise. */
+export declare const DEFAULT_CHAT_URL = "https://chat.2kw.ai";
+/**
+ * The chat web host that belongs to an API base URL, where a member connects a connector
+ * (`<chat>/connectors`). `AI_2KW_CHAT_URL` overrides the mapping, for deployments the map
+ * does not know; a trailing slash is dropped so callers can append a path.
+ */
+export declare function chatUrlFor(baseUrl: string, env?: NodeJS.ProcessEnv): string;
 declare const store: Conf<BackboneConfigStore>;
 export { store };
 export declare function validateContextName(name: string): void;
 export declare function getActiveContextName(): string;
 export declare function getActiveContext(): ContextEntry | undefined;
+/**
+ * Whether responses calls opt into agent memory (spec §3.3, D6). `AI_2KW_MEMORY` wins when
+ * set (`true` on, anything else off), so CI can switch it without touching the store;
+ * otherwise the active context's `memory` key decides. Off by default.
+ */
+export declare function memoryEnabled(env?: NodeJS.ProcessEnv): boolean;
 export declare function getAllContexts(): Record<string, ContextEntry>;
 export declare function getContextCount(): number;
 export declare function setContext(name: string, entry: ContextEntry): void;

package/dist/lib/config.js

@@ -9,7 +9,7 @@ import { resolve } from "node:path";
  */
 export const DEFAULT_BASE_URL = process.env.AI_2KW_DEFAULT_BASE_URL ??
     process.env.BACKBONE_DEFAULT_BASE_URL ??
-    "https://backbone.manfred-kunze.dev/api";
+    "https://api.2kw.ai";
 /**
  * Fallback auth-service URL used when the API host is not one we recognise.
  * Override at runtime with AI_2KW_DEFAULT_AUTH_URL.
@@ -36,6 +36,34 @@ export function defaultAuthUrlFor(baseUrl) {
         return DEFAULT_AUTH_URL;
     }
 }
+/** Fallback chat.2kw.ai origin when the API host is not one we recognise. */
+export const DEFAULT_CHAT_URL = "https://chat.2kw.ai";
+/** Known API-host → chat web host mappings; a connect pause points the user there (#807 R11). */
+const CHAT_URL_BY_API_HOST = {
+    "api.2kw.ai": "https://chat.2kw.ai",
+    "api-dev.2kw.ai": "https://chat-dev.2kw.ai",
+    "backbone.manfred-kunze.dev": "https://chat.2kw.ai",
+    "localhost:8080": "http://localhost:3000",
+    "127.0.0.1:8080": "http://localhost:3000",
+};
+/**
+ * The chat web host that belongs to an API base URL, where a member connects a connector
+ * (`<chat>/connectors`). `AI_2KW_CHAT_URL` overrides the mapping, for deployments the map
+ * does not know; a trailing slash is dropped so callers can append a path.
+ */
+export function chatUrlFor(baseUrl, env = process.env) {
+    const override = env.AI_2KW_CHAT_URL?.trim();
+    if (override)
+        return override.replace(/\/+$/, "");
+    try {
+        const host = new URL(baseUrl).host;
+        // hasOwn, as in defaultAuthUrlFor: a host named after an Object.prototype key must not resolve.
+        return Object.hasOwn(CHAT_URL_BY_API_HOST, host) ? CHAT_URL_BY_API_HOST[host] : DEFAULT_CHAT_URL;
+    }
+    catch {
+        return DEFAULT_CHAT_URL;
+    }
+}
 // One-shot flag so we only print the deprecation warning once per process,
 // even if resolveConfig is called multiple times across commands.
 let legacyEnvWarned = false;
@@ -142,6 +170,17 @@ export function getActiveContext() {
     const contexts = store.get("contexts") ?? {};
     return contexts[name];
 }
+/**
+ * Whether responses calls opt into agent memory (spec §3.3, D6). `AI_2KW_MEMORY` wins when
+ * set (`true` on, anything else off), so CI can switch it without touching the store;
+ * otherwise the active context's `memory` key decides. Off by default.
+ */
+export function memoryEnabled(env = process.env) {
+    const fromEnv = env.AI_2KW_MEMORY;
+    if (fromEnv !== undefined && fromEnv !== "")
+        return fromEnv === "true";
+    return getActiveContext()?.memory === true;
+}
 export function getAllContexts() {
     return store.get("contexts") ?? {};
 }

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;
     }
 }
 /**
@@ -106,6 +108,13 @@ export function hintFor(err) {
     }
     if (err.code && CODE_HINTS[err.code])
         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. 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
     // "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)) {

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/dist/lib/skills-apply-preview.d.ts

@@ -0,0 +1,19 @@
+import type { SkillsApplyPreview } from "./agent-run.js";
+/** The grant's consequence for a SkillsApply change (spec §6, D13), shown next to "approve and Remember". */
+export declare const REMEMBER_NOTE = "approve and Remember: later skill changes you make in this chat apply without asking";
+/**
+ * A SkillsApply preview as plain text, one entry per line (#782, spec §10): per skill where it
+ * starts and the labels it moves, each file with its unified diff indented under it, then the
+ * followers snapshot and the binding. Lines are unstyled and unstripped; the prompt does both.
+ * The generated type marks every field optional and the wire sends nulls, so every read is guarded.
+ */
+export declare function previewLines(preview: SkillsApplyPreview): string[];
+/**
+ * Whether the preview leaves part of the change unseen (#782, spec D7): a skill with files left
+ * out, a diff that was cut, or an add or edit with no diff at all (abandoned as too large, or a
+ * base the server could not read). The prompt then prints the full arguments as well, because a
+ * change that persists must be readable at the prompt. A `put` or `delete` carries no diff by
+ * design and does not count. Guarded like {@link previewLines}: every field optional, nulls on the wire.
+ */
+export declare function previewIsIncomplete(preview: SkillsApplyPreview): boolean;
+//# sourceMappingURL=skills-apply-preview.d.ts.map

package/dist/lib/skills-apply-preview.js

@@ -0,0 +1,94 @@
+/** The grant's consequence for a SkillsApply change (spec §6, D13), shown next to "approve and Remember". */
+export const REMEMBER_NOTE = "approve and Remember: later skill changes you make in this chat apply without asking";
+const OP_WORDS = { add: "new file", edit: "edited", delete: "deleted", put: "uploaded file" };
+/**
+ * A SkillsApply preview as plain text, one entry per line (#782, spec §10): per skill where it
+ * starts and the labels it moves, each file with its unified diff indented under it, then the
+ * followers snapshot and the binding. Lines are unstyled and unstripped; the prompt does both.
+ * The generated type marks every field optional and the wire sends nulls, so every read is guarded.
+ */
+export function previewLines(preview) {
+    const lines = ["Skill changes:"];
+    for (const skill of list(preview.skills)) {
+        const name = String(skill.name ?? "");
+        const from = typeof skill.from === "number" ? skill.from : null;
+        const moves = list(skill.moves).map(String);
+        const start = from === null ? `${name}: new skill` : `${name} v${from} -> new version`;
+        lines.push(`  ${start}${moves.length > 0 ? `, moves ${moves.join(", ")}` : ""}`);
+        if (typeof skill.fork_of_plugin === "string" && skill.fork_of_plugin) {
+            lines.push(`    forks the plugin skill from ${skill.fork_of_plugin}: later plugin syncs no longer move latest`);
+        }
+        for (const file of list(skill.files))
+            lines.push(...fileLines(file));
+        const omitted = typeof skill.files_omitted === "number" ? skill.files_omitted : 0;
+        if (omitted > 0)
+            lines.push(`    ${omitted} more ${omitted === 1 ? "file" : "files"} not shown`);
+    }
+    const followers = preview.followers;
+    if (followers) {
+        const agents = list(followers.agents).map(String);
+        const more = typeof followers.more === "number" ? followers.more : 0;
+        const when = typeof followers.as_of === "string" ? ` (as of ${followers.as_of})` : "";
+        if (agents.length === 0 && more === 0)
+            lines.push(`No agent follows these labels${when}`);
+        else
+            lines.push(`Agents following these labels${when}: ${agents.length > 0 ? agents.join(", ") : `${more} agents`}${agents.length > 0 && more > 0 ? ` and ${more} more` : ""}`);
+    }
+    const agent = preview.agent;
+    const bind = agent ? list(agent.bind).map(String) : [];
+    if (agent && bind.length > 0) {
+        const base = typeof agent.from === "number" ? ` (new agent version from v${agent.from})` : "";
+        lines.push(`Binds ${bind.join(", ")} to this agent${base}`);
+    }
+    return lines;
+}
+/**
+ * Whether the preview leaves part of the change unseen (#782, spec D7): a skill with files left
+ * out, a diff that was cut, or an add or edit with no diff at all (abandoned as too large, or a
+ * base the server could not read). The prompt then prints the full arguments as well, because a
+ * change that persists must be readable at the prompt. A `put` or `delete` carries no diff by
+ * design and does not count. Guarded like {@link previewLines}: every field optional, nulls on the wire.
+ */
+export function previewIsIncomplete(preview) {
+    for (const skill of list(preview.skills)) {
+        if (typeof skill.files_omitted === "number" && skill.files_omitted > 0)
+            return true;
+        for (const file of list(skill.files)) {
+            if (file.truncated === true)
+                return true;
+            if ((file.op === "add" || file.op === "edit") && typeof file.diff !== "string")
+                return true;
+        }
+    }
+    return false;
+}
+function fileLines(file) {
+    const facts = [OP_WORDS[String(file.op)] ?? String(file.op)];
+    if (typeof file.added === "number" && typeof file.removed === "number")
+        facts.push(`+${file.added} -${file.removed}`);
+    if (typeof file.bytes === "number")
+        facts.push(size(file.bytes));
+    const lines = [`    ${String(file.path ?? "")}: ${facts.join(", ")}`];
+    const diff = typeof file.diff === "string" ? file.diff : null;
+    if (diff !== null) {
+        for (const line of diff.split("\n"))
+            lines.push(`      ${line}`);
+        if (file.truncated === true)
+            lines.push("      (diff cut; the counts cover every changed line)");
+    }
+    else if (file.truncated === true) {
+        lines.push(`      too many changes to show: at most +${Number(file.added ?? 0)} -${Number(file.removed ?? 0)} lines`);
+    }
+    return lines;
+}
+function list(value) {
+    return Array.isArray(value) ? value.filter((entry) => entry !== null && entry !== undefined) : [];
+}
+function size(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+//# sourceMappingURL=skills-apply-preview.js.map

package/dist/lib/tracing-settings.d.ts

@@ -0,0 +1,26 @@
+/** The options of `tracing settings set`, as commander hands them over. */
+export interface TracingSettingsOptions {
+    includePrompts?: string;
+    includeCompletions?: string;
+    retentionDays?: string;
+}
+/** The fields of a GET this command carries through. */
+export interface TracingSettingsCurrent {
+    includePrompts?: boolean;
+    includeCompletions?: boolean;
+    retentionDays?: number | null;
+}
+export interface TracingSettingsBody {
+    includePrompts: boolean;
+    includeCompletions: boolean;
+    retentionDays: number | null;
+}
+/**
+ * The PUT body: the options given, and the current value of everything else. The PUT is a
+ * full replace (#1015), so a field left out would reset: a missing retentionDays would
+ * follow the plan again and undo the admin's shorter choice.
+ */
+export declare function tracingSettingsBody(current: TracingSettingsCurrent | undefined, opts: TracingSettingsOptions): TracingSettingsBody;
+/** `plan` follows the plan's limit; anything else must be a whole number of days, 1 or more. */
+export declare function parseRetentionDays(value: string): number | null;
+//# sourceMappingURL=tracing-settings.d.ts.map

package/dist/lib/tracing-settings.js

@@ -0,0 +1,25 @@
+import { CliUsageError } from "./errors.js";
+/**
+ * The PUT body: the options given, and the current value of everything else. The PUT is a
+ * full replace (#1015), so a field left out would reset: a missing retentionDays would
+ * follow the plan again and undo the admin's shorter choice.
+ */
+export function tracingSettingsBody(current, opts) {
+    return {
+        includePrompts: opts.includePrompts !== undefined ? opts.includePrompts === "true" : (current?.includePrompts ?? false),
+        includeCompletions: opts.includeCompletions !== undefined
+            ? opts.includeCompletions === "true"
+            : (current?.includeCompletions ?? false),
+        retentionDays: opts.retentionDays !== undefined ? parseRetentionDays(opts.retentionDays) : (current?.retentionDays ?? null),
+    };
+}
+/** `plan` follows the plan's limit; anything else must be a whole number of days, 1 or more. */
+export function parseRetentionDays(value) {
+    if (value === "plan")
+        return null;
+    if (!/^[1-9]\d*$/.test(value)) {
+        throw new CliUsageError(`--retention-days must be a whole number of days (1 or more) or "plan", got "${value}".`);
+    }
+    return Number(value);
+}
+//# sourceMappingURL=tracing-settings.js.map

package/package.json

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