@2kw/ai 6.2.0-dev.14 → 6.2.0-dev.25

package/dist/lib/approval-prompt.js

@@ -0,0 +1,84 @@
+import { createInterface } from "node:readline/promises";
+import chalk from "chalk";
+import { stripControl } from "./agent-run.js";
+/** Raised when the prompt's input closes (EOF, Ctrl+C, Ctrl+D) before an answer arrives. */
+export class PromptAbortedError extends Error {
+    constructor() {
+        super("Approval prompt closed");
+        this.name = "PromptAbortedError";
+    }
+}
+/**
+ * Prompts go to stderr so stdout stays the agent's answer. A closed input never
+ * leaves a question hanging: every pending and later `ask` rejects with
+ * {@link PromptAbortedError}.
+ */
+export function readlineAsk(input = process.stdin, output = process.stderr) {
+    const rl = createInterface({ input, output, terminal: Boolean(input.isTTY) });
+    let closed = false;
+    let abortPending;
+    rl.once("close", () => {
+        closed = true;
+        abortPending?.();
+    });
+    const ask = (question) => new Promise((resolve, reject) => {
+        if (closed) {
+            reject(new PromptAbortedError());
+            return;
+        }
+        let settled = false;
+        const abort = () => settle(() => reject(new PromptAbortedError()));
+        const settle = (finish) => {
+            if (settled)
+                return;
+            settled = true;
+            if (abortPending === abort)
+                abortPending = undefined;
+            finish();
+        };
+        abortPending = abort;
+        rl.question(question).then((answer) => settle(() => resolve(answer)), (err) => settle(() => reject(err?.name === "AbortError" ? new PromptAbortedError() : err)));
+    });
+    return {
+        ask,
+        close: () => {
+            if (!closed)
+                rl.close();
+        },
+    };
+}
+export async function promptApprovals(pending, ask, write = (line) => console.error(line)) {
+    const answers = new Map();
+    const s = stripControl;
+    for (const [index, a] of pending.entries()) {
+        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))));
+        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? ";
+        const hint = destructive
+            ? "Answer a (approve), r (reject)"
+            : "Answer a (approve), r (reject), or R (approve and remember)";
+        for (;;) {
+            const reply = (await ask(question)).trim();
+            if (reply === "a") {
+                answers.set(a.approvalId, { decision: "approve" });
+                break;
+            }
+            if (reply === "R" && !destructive) {
+                answers.set(a.approvalId, { decision: "approve", remember: true });
+                break;
+            }
+            if (reply === "r") {
+                const reason = (await ask("Reason (optional): ")).trim();
+                answers.set(a.approvalId, reason ? { decision: "reject", reason } : { decision: "reject" });
+                break;
+            }
+            write(hint);
+        }
+    }
+    return answers;
+}
+//# sourceMappingURL=approval-prompt.js.map

package/dist/lib/client.d.ts

@@ -23,6 +23,8 @@ export interface SessionAuthDeps {
 }
 /**
  * Error-handling middleware: intercepts non-ok responses and throws BackboneApiError.
+ * The api-key filter now returns the OpenAI envelope (#658); the surface
+ * filter still sends the flat shape, so both are normalized here.
  */
 export declare const errorMiddleware: Middleware;
 /**

package/dist/lib/client.js

@@ -9,6 +9,8 @@ import { BackboneApiError, handleError } from "./errors.js";
 export const RETRY_MARKER = "x-2kw-auth-retried";
 /**
  * Error-handling middleware: intercepts non-ok responses and throws BackboneApiError.
+ * The api-key filter now returns the OpenAI envelope (#658); the surface
+ * filter still sends the flat shape, so both are normalized here.
  */
 export const errorMiddleware = {
     async onResponse({ response }) {
@@ -21,11 +23,20 @@ export const errorMiddleware = {
         catch {
             body = {};
         }
+        // Gateway endpoints and the api-key filter answer in the OpenAI shape
+        // {error: {message, type, param, code}}; its code is also kept on its own.
+        const nested = body && typeof body.error === "object" && body.error !== null ? body.error : undefined;
         throw new BackboneApiError({
             status: body.status ?? response.status,
-            error: body.title ?? body.error ?? response.statusText,
-            message: body.detail ?? body.message ?? `HTTP ${response.status}: ${response.statusText}`,
+            error: typeof body.error === "string"
+                ? body.error
+                : (nested?.code ?? nested?.type ?? body.title ?? response.statusText),
+            message: body.detail ??
+                body.message ??
+                nested?.message ??
+                `HTTP ${response.status}: ${response.statusText}`,
             timestamp: body.timestamp ?? new Date().toISOString(),
+            code: typeof nested?.code === "string" ? nested.code : undefined,
         });
     },
 };

package/dist/lib/errors.d.ts

@@ -1,14 +1,31 @@
 export interface ApiErrorBody {
     status: number;
-    error: string;
+    error?: string | {
+        message?: string;
+        type?: string;
+        param?: string | null;
+        code?: string | null;
+    };
     message: string;
     timestamp: string;
+    /** Machine-readable code from an OpenAI-style gateway error, e.g. `approval_hmac_mismatch`. */
+    code?: string;
 }
 export declare class BackboneApiError extends Error {
     readonly status: number;
     readonly errorType: string;
     readonly timestamp: string;
-    constructor(body: ApiErrorBody);
+    readonly code?: string;
+    constructor(body: Omit<ApiErrorBody, "error"> & {
+        error: string;
+    });
+}
+/**
+ * Invalid usage, invalid config, or a local check that failed before any request.
+ * `handleError` maps it to exit code 2 so scripted callers can tell it from an API failure.
+ */
+export declare class CliUsageError extends Error {
+    constructor(message: string);
 }
 /**
  * Discriminated cause of a failed credential check. Lets callers give a
@@ -28,5 +45,7 @@ export type AuthFailureKind = "UNAUTHORIZED" | "FORBIDDEN" | "UNREACHABLE" | "UN
  * - Everything else → UNKNOWN.
  */
 export declare function classifyAuthFailure(err: unknown): AuthFailureKind;
+/** The most specific hint for an API error: gateway code, then known messages, then the status table. */
+export declare function hintFor(err: BackboneApiError): string | undefined;
 export declare function handleError(err: unknown, json: boolean): void;
 //# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.js

@@ -6,12 +6,24 @@ export class BackboneApiError extends Error {
     status;
     errorType;
     timestamp;
+    code;
     constructor(body) {
         super(body.message);
         this.name = "BackboneApiError";
         this.status = body.status;
         this.errorType = body.error;
         this.timestamp = body.timestamp;
+        this.code = body.code;
+    }
+}
+/**
+ * Invalid usage, invalid config, or a local check that failed before any request.
+ * `handleError` maps it to exit code 2 so scripted callers can tell it from an API failure.
+ */
+export class CliUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CliUsageError";
     }
 }
 // Node/undici surface network faults through the error's `code`. A DNS or
@@ -77,6 +89,37 @@ const HINTS = {
     422: "Validation error. Check the input values.",
     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 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.",
+    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. */
+export function hintFor(err) {
+    if (err.code === "invalid_approval_decision" && /decided automatically/.test(err.message)) {
+        return "This request was already decided by the automatic approver; nothing to decide.";
+    }
+    if (err.code === "invalid_approval_decision" && /decided by a conversation grant/.test(err.message)) {
+        return "This request was already approved by a conversation grant; nothing to decide.";
+    }
+    if (err.code && CODE_HINTS[err.code])
+        return CODE_HINTS[err.code];
+    // 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).";
+    }
+    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>";
+    }
+    // Only a skill-binding resolution failure, not any 422 that mentions a skill.
+    if (err.status === 422 && /^Skill '.+' (cannot be resolved|is archived)/.test(err.message)) {
+        return "Check the skill exists, is active, and has that label or version: 2kw skills list";
+    }
+    return HINTS[err.status];
+}
 /**
  * Drop the cached org JWT of the active session context.
  *
@@ -114,13 +157,14 @@ export function handleError(err, json) {
             console.error(JSON.stringify({
                 error: err.errorType,
                 status: err.status,
+                ...(err.code ? { code: err.code } : {}),
                 message: err.message,
                 timestamp: err.timestamp,
             }));
         }
         else {
             console.error(chalk.red(`Error ${err.status}: ${err.message}`));
-            const hint = HINTS[err.status];
+            const hint = hintFor(err);
             if (hint) {
                 console.error(chalk.yellow(`Hint: ${hint}`));
             }
@@ -151,6 +195,6 @@ export function handleError(err, json) {
     else {
         console.error(chalk.red(`Unknown error: ${String(err)}`));
     }
-    process.exitCode = 1;
+    process.exitCode = err instanceof CliUsageError ? 2 : 1;
 }
 //# sourceMappingURL=errors.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai",
-  "version": "6.2.0-dev.14",
+  "version": "6.2.0-dev.25",
   "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",
@@ -38,6 +38,7 @@
     "check:generated": "tsx openapi/scripts/check-generated.ts",
     "fix:generated": "tsx openapi/scripts/check-generated.ts --write",
     "check:coverage": "tsx openapi/scripts/check-coverage.ts",
+    "sync:agent-schema": "tsx scripts/sync-agent-schema.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest",
     "test:run": "vitest run",
@@ -45,13 +46,15 @@
     "test:contract": "vitest run tests/contract"
   },
   "dependencies": {
+    "ajv": "^8.20.0",
     "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
     "commander": "^13.1.0",
     "conf": "^13.1.0",
     "open": "^10.2.0",
     "openapi-fetch": "^0.13.5",
-    "ora": "^8.2.0"
+    "ora": "^8.2.0",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",