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

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;
     }
 }
 /**
@@ -93,7 +95,9 @@ const PENDING_APPROVALS_HINT = "The approval was already decided or its response
 const CODE_HINTS = {
     approval_hmac_mismatch: PENDING_APPROVALS_HINT,
     unknown_approval_id: PENDING_APPROVALS_HINT,
-    incomplete_tool_outputs: "Every pending approval of a paused response must be decided in one call. Use --approve-all or --reject-all, or name every id.",
+    incomplete_tool_outputs: "Every released tool call and every pending approval of a paused response must be answered in one call. " +
+        "Check pendingToolCalls and pendingApprovals in the run envelope.",
+    unknown_tool_output: "That call id was not released by this response. Use the responseId of the latest envelope.",
     conversation_agent_mismatch: "This conversation belongs to another agent. Start a new conversation or run the agent that owns it.",
 };
 /** The most specific hint for an API error: gateway code, then known messages, then the status table. */
@@ -108,8 +112,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/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.3.0-dev.12",
+  "version": "6.3.0-dev.122",
   "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",