@2kw/ai 6.3.0-dev.8 → 6.3.0-dev.84

package/dist/lib/agent-run.js

@@ -1,4 +1,36 @@
 import chalk from "chalk";
+import { DEFAULT_CHAT_URL } from "./config.js";
+import { CliUsageError } from "./errors.js";
+export const CONVERSATION_MODES = ["plan", "ask", "auto"];
+/** `--mode` help text, in the words of the embedded chat's mode chip (#655). */
+export const MODE_OPTION_HELP = "Conversation mode: plan (read-only), ask (no automatic approver; calls that need approval wait for you), " +
+    "auto (the operator's policy as written). Without it, the conversation keeps its mode";
+function isConversationMode(value) {
+    return typeof value === "string" && CONVERSATION_MODES.includes(value);
+}
+/**
+ * The `--mode` value, checked before any request is sent: anything but the three exact values is a
+ * usage error (exit 2). Commander's `.choices()` is not used because it exits 1 through `process.exit`.
+ */
+export function parseModeOption(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (isConversationMode(raw))
+        return raw;
+    throw new CliUsageError(`Invalid --mode '${raw}': use plan, ask or auto.`);
+}
+/** The `backbone:mode` input item (S1 D7); always appended last. */
+export function modeItem(mode) {
+    return { type: "backbone:mode", mode };
+}
+/**
+ * The mode the response ran under (`conversation_mode`, #656). An absent key (a server before #656)
+ * and any value other than the three read as null, which also means "none set".
+ */
+export function responseMode(result) {
+    const raw = result?.conversation_mode;
+    return isConversationMode(raw) ? raw : null;
+}
 export const EXIT_CODES = {
     completed: 0,
     requires_approval: 3,
@@ -60,7 +92,78 @@ export function shellQuote(value) {
         return value;
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-export function buildRunEnvelope(result, agentRef) {
+/** An open connector consent request; a continuation's projection carries another status. */
+function pendingConnectionsOf(output) {
+    return output
+        .filter((i) => i.type === "backbone:connector_auth_request" && (i.status === undefined || i.status === "in_progress"))
+        .map((i) => ({
+        serverLabel: String(i.server_label),
+        host: String(i.host),
+        reason: String(i.reason),
+        ...(Array.isArray(i.destinations) && i.destinations.length > 0
+            ? { destinations: i.destinations.map((d) => String(d)) }
+            : {}),
+    }));
+}
+/**
+ * The call ids a connect pause withholds from the caller: the call each request names, and every
+ * `mcp__<label>__connect` call for a pending connector (the model may call it more than once; one
+ * request stands for all of them).
+ */
+function connectCallIds(output, connections) {
+    const connectNames = new Set(connections.map((c) => `mcp__${c.serverLabel}__connect`));
+    const ids = new Set();
+    for (const item of output) {
+        if (item.type === "backbone:connector_auth_request" && (item.status === undefined || item.status === "in_progress")) {
+            ids.add(String(item.call_id));
+        }
+        else if (item.type === "function_call" && connectNames.has(String(item.name))) {
+            ids.add(String(item.call_id));
+        }
+    }
+    return ids;
+}
+function connectionPhrase(c) {
+    const target = `${c.serverLabel} (${c.host})`;
+    if (c.reason === "allow")
+        return `allow the agent to use ${target}`;
+    if (c.reason === "reconnect")
+        return `reconnect ${target}`;
+    return `connect ${target}`;
+}
+/** "Connect a (h), allow the agent to use b (h) and reconnect c (h)". */
+export function connectionsSentence(connections) {
+    const phrases = connections.map(connectionPhrase);
+    const joined = phrases.length > 1 ? `${phrases.slice(0, -1).join(", ")} and ${phrases.at(-1)}` : phrases[0] ?? "";
+    return joined.charAt(0).toUpperCase() + joined.slice(1);
+}
+/** Joins a connect pause's instruction to the command that continues it; {@link printRunText} breaks the line there. */
+const THEN_RUN = ", then run: ";
+/**
+ * Output item types the envelope decodes, or that never hold a run: text, reasoning and finished
+ * connector calls. A pause on anything else (a connector approval's `mcp_approval_request`) is named.
+ */
+const DECODED_ITEM_TYPES = new Set([
+    "message",
+    "reasoning",
+    "function_call",
+    "function_call_output",
+    "backbone:approval_request",
+    "backbone:connector_auth_request",
+    "mcp_call",
+    "mcp_list_tools",
+]);
+function undecodedPause(output) {
+    const types = [...new Set(output.map((i) => String(i.type)).filter((t) => !DECODED_ITEM_TYPES.has(t)))];
+    return types.length > 0
+        ? `This CLI cannot show or answer ${types.join(", ")}.`
+        : "This CLI cannot tell what the run waits for.";
+}
+/**
+ * @param chatUrl the chat web host of the API the run went to ({@link chatUrlFor}); a connect pause's
+ *   `next` sends the user to its Connectors page.
+ */
+export function buildRunEnvelope(result, agentRef, chatUrl = DEFAULT_CHAT_URL) {
     const output = result?.output ?? [];
     const { agent, version } = parseAgentModel(result?.model);
     // call_id → status of its tool output; a failed server-side tool run is marked `incomplete`.
@@ -80,8 +183,10 @@ export function buildRunEnvelope(result, agentRef) {
         arguments: parseArguments(i.arguments),
         policyClass: String(i.policy_class),
         reason: typeof i.reason === "string" && i.reason ? i.reason : null,
+        preview: i.preview && typeof i.preview === "object" && !Array.isArray(i.preview) ? i.preview : null,
     }));
-    const withheldCallIds = new Set(pendingApprovals.map((a) => a.callId));
+    const pendingConnections = pendingConnectionsOf(output);
+    const withheldCallIds = new Set([...pendingApprovals.map((a) => a.callId), ...connectCallIds(output, pendingConnections)]);
     const toolCalls = [];
     const pendingToolCalls = [];
     for (const item of output) {
@@ -105,19 +210,38 @@ export function buildRunEnvelope(result, agentRef) {
             status = "incomplete";
             break;
         case "requires_action":
-            status = pendingToolCalls.length > 0 || pendingApprovals.length === 0 ? "requires_tool_output" : "requires_approval";
+            // A connect pause keeps exit 4 (§8, CLI agents D14): the CLI cannot answer it either.
+            status =
+                pendingToolCalls.length > 0 || pendingConnections.length > 0 || pendingApprovals.length === 0
+                    ? "requires_tool_output"
+                    : "requires_approval";
             break;
         default:
             throw new Error(`Unexpected response status: ${result?.status}`);
     }
     const responseId = result?.id ?? null;
     const ref = agentRef ?? agent;
-    const next = status === "requires_approval" && ref && responseId
-        ? `2kw agents decide ${shellQuote(ref)} --response ${responseId} --approve-all`
-        : null;
+    let next = null;
+    if (status === "requires_approval" && ref && responseId) {
+        next = `2kw agents decide ${shellQuote(ref)} --response ${responseId} --approve-all`;
+    }
+    else if (status === "requires_tool_output" && pendingConnections.length > 0 && pendingToolCalls.length === 0 && responseId) {
+        // Not with a relayed call beside it: a continuation without that call's output is refused.
+        // `agents run --continue` needs no input: the continuation re-checks access itself.
+        const resume = ref
+            ? `${THEN_RUN}2kw agents run ${shellQuote(ref)} --continue ${shellQuote(responseId)}`
+            : `, then run the agent again with --continue ${shellQuote(responseId)}`;
+        next = `${connectionsSentence(pendingConnections)} in ${chatUrl}/connectors${resume}`;
+    }
+    else if (status === "requires_tool_output" && pendingConnections.length === 0 && pendingToolCalls.length === 0 && responseId) {
+        // Paused on nothing the envelope decodes: say so, rather than exit 4 without a word.
+        next =
+            `${undecodedPause(output)} Response ${responseId} stays paused: answer it in ${chatUrl}/ ` +
+                "or from a client that continues it by previous_response_id.";
+    }
     return {
         status,
-        mode: null,
+        mode: responseMode(result),
         agent,
         version,
         responseId,
@@ -126,6 +250,7 @@ export function buildRunEnvelope(result, agentRef) {
         toolCalls,
         pendingApprovals,
         pendingToolCalls,
+        pendingConnections,
         incompleteReason: result?.incomplete_details?.reason ?? null,
         usage: result?.usage
             ? { inputTokens: result.usage.input_tokens ?? 0, outputTokens: result.usage.output_tokens ?? 0 }
@@ -160,8 +285,26 @@ export function printRunText(env) {
             console.log(`\nDecide with:\n  ${s(env.next)}`);
     }
     else if (env.status === "requires_tool_output") {
-        console.log(chalk.yellow("\nPaused: the agent needs client-side tool output this CLI cannot provide:"));
-        env.pendingToolCalls.forEach((c) => console.log(`  - ${s(c.tool)} (${s(c.callId)})`));
+        if (env.pendingConnections.length) {
+            console.log(chalk.yellow("\nPaused: the agent needs you to connect in chat:"));
+            env.pendingConnections.forEach((c) => {
+                console.log(`  - ${s(connectionsSentence([c]))}`);
+                if (c.destinations?.length)
+                    console.log(chalk.dim(`    new destinations: ${s(c.destinations.join(", "))}`));
+            });
+            // The continue command on its own line, ready to copy.
+            if (env.next)
+                console.log(`\n${s(env.next.replace(THEN_RUN, ", then run:\n  "))}`);
+        }
+        if (env.pendingToolCalls.length) {
+            console.log(chalk.yellow("\nPaused: the agent needs client-side tool output this CLI cannot provide:"));
+            env.pendingToolCalls.forEach((c) => console.log(`  - ${s(c.tool)} (${s(c.callId)})`));
+        }
+        if (!env.pendingConnections.length && !env.pendingToolCalls.length) {
+            console.log(chalk.yellow("\nPaused on something this CLI cannot show:"));
+            if (env.next)
+                console.log(`  ${s(env.next)}`);
+        }
     }
     else if (env.status === "incomplete") {
         console.log(chalk.yellow(`\nIncomplete: ${s(env.incompleteReason ?? "unknown reason")}`));

package/dist/lib/approval-prompt.js

@@ -1,6 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import chalk from "chalk";
 import { stripControl } from "./agent-run.js";
+import { REMEMBER_NOTE, previewIsIncomplete, previewLines } from "./skills-apply-preview.js";
 /** Raised when the prompt's input closes (EOF, Ctrl+C, Ctrl+D) before an answer arrives. */
 export class PromptAbortedError extends Error {
     constructor() {
@@ -54,7 +55,23 @@ export async function promptApprovals(pending, ask, write = (line) => console.er
         const destructive = a.policyClass.toLowerCase() === "destructive";
         write(chalk.yellow(`\nApproval ${index + 1}/${pending.length}: ${s(a.tool)} [${s(a.policyClass)}]`));
         // JSON.stringify escapes C0 controls but leaves DEL and C1 raw.
-        write(chalk.dim(s(JSON.stringify(a.arguments, null, 2))));
+        const request = () => write(chalk.dim(s(JSON.stringify(a.arguments, null, 2))));
+        if (a.preview) {
+            // A SkillsApply change reads as its diff (#782, spec §10). When the preview leaves changes
+            // out, the full arguments follow it: this prompt never runs with --json, so it is the only
+            // place the member can read what would persist (spec D7).
+            for (const line of previewLines(a.preview))
+                write(colourPreviewLine(s(line)));
+            if (previewIsIncomplete(a.preview)) {
+                write(chalk.dim("Full request (the preview leaves changes out):"));
+                request();
+            }
+            if (!destructive)
+                write(chalk.dim(REMEMBER_NOTE));
+        }
+        else {
+            request();
+        }
         if (a.reason)
             write(chalk.dim(`reason: ${s(a.reason)}`));
         const question = destructive ? "[a]pprove / [r]eject? " : "[a]pprove / [r]eject / approve and [R]emember? ";
@@ -81,4 +98,17 @@ export async function promptApprovals(pending, ask, write = (line) => console.er
     }
     return answers;
 }
+/** Diff lines sit indented six spaces under their file; only those are coloured. */
+function colourPreviewLine(line) {
+    if (!line.startsWith("      "))
+        return line;
+    const body = line.slice(6);
+    if (body.startsWith("+"))
+        return chalk.green(line);
+    if (body.startsWith("-"))
+        return chalk.red(line);
+    if (body.startsWith("@@"))
+        return chalk.cyan(line);
+    return chalk.dim(line);
+}
 //# sourceMappingURL=approval-prompt.js.map

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

@@ -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;
     }
 }
 /**
@@ -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/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.3.0-dev.8",
+  "version": "6.3.0-dev.84",
   "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",