@2kw/ai 6.3.0-dev.111 → 6.3.0-dev.116

package/README.md

@@ -112,7 +112,7 @@ kubectl-style contexts switch between organizations and environments:
 | `providers` | Manage BYOK AI providers |
 | `analytics` | Usage analytics: spend, quality, providers, errors |
 | `billing` | Check subscription tier and usage limits |
-| `agents` | Run agents and decide approvals; apply, export and scaffold agent.yaml; manage versions, labels, approvals and tool catalogs |
+| `agents` | Run agents and answer paused runs (approvals and relayed tool calls); apply, export and scaffold agent.yaml; manage versions, labels, approvals and tool catalogs |
 | `skills` | Import and export SKILL.md bundles; manage skill versions and labels |
 | `plugins` | Install plugin repositories, sync them, and inspect their reports |
 | `conversations` | Create and manage conversations and their items |

package/dist/agent-config/schema.js

@@ -21,6 +21,8 @@ const oneOfLowercase = (...values) => ({ type: "string", enum: values });
 export const NON_AUTHORABLE_TOOL_TYPES = {
     "backbone.tool_search": "the planner adds it automatically",
     "backbone.skill_read": "it is added at run time when skills are pinned",
+    // #944: SkillsetPinner injects it for eligible callers and strips any stored copy (#779).
+    "backbone.skills_apply": "it is added at run time for callers allowed to author skills",
     web_search: "it has no executor and is skipped",
 };
 const BUILTIN_TYPES = [

package/dist/commands/agent-run.js

@@ -6,7 +6,7 @@ import { BackboneApiError, CliUsageError } from "../lib/errors.js";
 import { withSpinner } from "../lib/output.js";
 import { resolveAgent, splitAgentRef, suggestAgents } from "../lib/agent-lookup.js";
 import { buildRunEnvelope, EXIT_CODES, MODE_OPTION_HELP, modeItem, parseModeOption, printRunText, stripControl, } from "../lib/agent-run.js";
-import { continueWithDecisions, decisionsFromAnswers, fetchPendingApprovals, planDecisions, } from "../lib/agent-decide.js";
+import { continueWithDecisions, decisionsFromAnswers, fetchPendingApprovals, parseToolAnswers, planContinuation, } from "../lib/agent-decide.js";
 import { PromptAbortedError, promptApprovals, readlineAsk } from "../lib/approval-prompt.js";
 import { withModelOverride } from "../lib/agent-models.js";
 import { readStdinInput } from "./ai.js";
@@ -171,9 +171,11 @@ export function makeAgentRunCommand() {
         });
     });
 }
+/** Repeatable `--output` / `--fail`: a variadic `<v...>` would swallow the arguments that follow it. */
+const collect = (value, previous = []) => [...previous, value];
 export function makeAgentDecideCommand() {
     return new Command("decide")
-        .description("Decide every pending approval of a paused run and continue it")
+        .description("Answer a paused run: decide every pending approval and answer every relayed tool call in one call, then continue it")
         .argument("<agent>", "Agent name or id, optionally with @label and #model (use the same @label and #model the run used)")
         .requiredOption("--response <responseId>", "The paused response id (responseId in the run envelope)")
         .option("--approve <ids...>", "Approval ids to approve")
@@ -182,11 +184,15 @@ export function makeAgentDecideCommand() {
         .option("--reject-all", "Reject every pending approval of the response")
         .option("--reason <text>", "Reason recorded on each decision (the model sees it on rejects)")
         .option("--remember", "Also approve later calls of the same tool in this conversation")
+        .option("--output <callId=value>", "Answer a relayed tool call: <callId>=<text>, <callId>=@<file> or <callId>=@- for stdin; within one hour of the pause (repeatable)", collect)
+        .option("--fail <callId=message>", "Answer a relayed tool call as failed: <callId>=<message> (same @file / @- forms; repeatable)", collect)
         .option("--mode <mode>", MODE_OPTION_HELP)
         .option("--raw", "Print the untouched API response")
         .action(async (agentRef, opts, command) => {
         await runAction(command, async () => {
             const mode = parseModeOption(opts.mode);
+            // Syntax, duplicates and file reads are checked before any request (#671 D4).
+            const toolAnswers = parseToolAnswers(opts.output, opts.fail);
             const client = getClient(command);
             const { name, label, model } = splitAgentRef(agentRef);
             // Dropped silently, an empty override would continue the run on the default model.
@@ -194,15 +200,15 @@ export function makeAgentDecideCommand() {
                 throw new CliUsageError(`Empty #model in '${agentRef}': use the model the run used, or drop the '#'.`);
             const agent = await resolveAgent(client, name);
             const pending = await fetchPendingApprovals(client, String(agent.id), opts.response);
-            const decisions = planDecisions(pending, {
+            const decisions = planContinuation(pending, {
                 approve: opts.approve,
                 reject: opts.reject,
                 approveAll: opts.approveAll,
                 rejectAll: opts.rejectAll,
                 reason: opts.reason,
                 remember: opts.remember,
-            }, opts.response);
-            const result = await withSpinner("Continuing...", () => continueWithDecisions(client, String(agent.id), opts.response, decisions, label, model, mode));
+            }, toolAnswers, opts.response);
+            const result = await withSpinner("Continuing...", () => continueWithDecisions(client, String(agent.id), opts.response, decisions, label, model, mode, toolAnswers));
             await finishRun(command, client, { name, label, model, mode }, result, { raw: !!opts.raw, interactive: false });
         });
     });

package/dist/commands/tracing.js

@@ -77,6 +77,7 @@ export function makeTracingCommand() {
     const sessions = new Command("sessions").description("Session-level trace views (spans grouped by exporter-stamped session id)");
     const sessionsList = new Command("list").description("List trace sessions");
     sessionsList.option("--search <query>", "Free-text search across session id and name");
+    sessionsList.option("--session-id <sessionId>", "Exact match on the session.id the exporter stamped (slashes allowed)");
     sessionsList.option("--from <iso>", "Start of time range (ISO-8601)");
     sessionsList.option("--to <iso>", "End of time range (ISO-8601)");
     sessionsList.option("--page <n>", "Page index (0-based)", "0");
@@ -88,6 +89,7 @@ export function makeTracingCommand() {
                 params: {
                     query: {
                         search: opts.search,
+                        sessionId: opts.sessionId,
                         from: opts.from,
                         to: opts.to,
                         page: parseInt(opts.page, 10),
@@ -96,17 +98,17 @@ export function makeTracingCommand() {
                 },
             });
             const page = data;
-            formatList((page?.content ?? []), command, ["sessionId", "name", "startTime", "durationMs", "turnCount", "errorCount", "costUsd"]);
+            formatList((page?.content ?? []), command, ["id", "sessionId", "name", "startTime", "durationMs", "turnCount", "errorCount", "costUsd"]);
         });
     });
     sessions.addCommand(sessionsList);
     const sessionsGet = new Command("get").description("Get all spans of a session by id, sorted chronologically");
-    sessionsGet.argument("<sessionId>", "Session id");
-    sessionsGet.action(async (sessionId, _opts, command) => {
+    sessionsGet.argument("<id>", "Session id: the id column of `sessions list` (find one by session.id with --session-id)");
+    sessionsGet.action(async (id, _opts, command) => {
         await runAction(command, async () => {
             const client = getClient(command);
-            const { data } = await client.GET("/v1/traces/sessions/{sessionId}", {
-                params: { path: { sessionId } },
+            const { data } = await client.GET("/v1/traces/sessions/{id}", {
+                params: { path: { id } },
             });
             formatDetail(data, command);
         });

package/dist/lib/agent-decide.d.ts

@@ -22,21 +22,47 @@ export interface PromptAnswer {
     reason?: string;
     remember?: boolean;
 }
+/** One relayed tool call answered by `--output` or `--fail` (#671 D2, D3). */
+export interface ToolAnswer {
+    callId: string;
+    /** Sent verbatim as the item's `output` string. */
+    output: string;
+    failed: boolean;
+}
+export interface ToolAnswerIo {
+    readFile: (path: string) => string;
+    readStdin: () => string;
+}
+/**
+ * `--output` and `--fail` values as `<callId>=<value>`, split on the first `=`. `@<path>` reads a file and
+ * `@-` reads stdin, both verbatim. Only syntax is checked here: without stored state the CLI cannot list the
+ * calls a response released, so completeness is the server's check (#671 D4). Every check runs before any read.
+ */
+export declare function parseToolAnswers(outputs?: string[], fails?: string[], io?: ToolAnswerIo): ToolAnswer[];
 export declare function fetchPendingApprovals(client: ApiClient, agentId: string, responseId: string): Promise<ApprovalRow[]>;
 /**
  * The backend refuses a continuation that leaves any pending approval of the paused
  * response undecided (400 incomplete_tool_outputs), so the whole set is checked here first.
  */
 export declare function planDecisions(pending: ApprovalRow[], opts: DecideOptions, responseId: string): Decision[];
+/**
+ * The decisions a `decide` call sends beside its tool answers (#671 D5). A pure relay pause has no pending
+ * approval, so the approval flags are optional there: `--approve-all` / `--reject-all` add nothing (P1) and
+ * only explicit ids are refused. A mixed pause needs its approvals decided in the same call.
+ */
+export declare function planContinuation(pending: ApprovalRow[], opts: DecideOptions, toolAnswers: ToolAnswer[], responseId: string): Decision[];
 export declare function decisionsFromAnswers(pending: ApprovalRow[], answers: Map<string, PromptAnswer>): Decision[];
 /** Same item shape as n8n Decide Approval (#660). */
 export declare function toApprovalItems(decisions: Decision[]): Record<string, string>[];
+/** `failed: true` is Backbone's extension (#480): the tool's span ends ERROR. */
+export declare function toToolOutputItems(answers: ToolAnswer[]): Record<string, string | boolean>[];
 /**
  * Continues on `agent/<agentId>[@<label>][#<model>]` with the label and model override the run used: the
  * server resolves the continuation's tools, instructions and model from this reference, so both must match
  * the run's or the continuation drops to another version or the agent's default model.
  * Never the echoed `name@<versionNumber>` (it would 404 as a label).
  * With `mode`, the `backbone:mode` item follows the decisions (#656 D7); without it, nothing is added (D2).
+ * Tool answers go first, in flag order (#671 D6): the server replays accepted outputs ahead of other items.
  */
-export declare function continueWithDecisions(client: ApiClient, agentId: string, responseId: string, decisions: Decision[], label?: string, model?: string, mode?: ConversationMode): Promise<ResponsesResult>;
+export declare function continueWithDecisions(client: ApiClient, agentId: string, responseId: string, decisions: Decision[], label?: string, model?: string, mode?: ConversationMode, toolAnswers?: ToolAnswer[]): Promise<ResponsesResult>;
 //# sourceMappingURL=agent-decide.d.ts.map

package/dist/lib/agent-decide.js

@@ -1,6 +1,69 @@
+import { readFileSync } from "node:fs";
 import { modeItem } from "./agent-run.js";
 import { CliUsageError } from "./errors.js";
 import { paginationParams } from "./pagination.js";
+const defaultIo = {
+    readFile: (path) => readFileSync(path, "utf-8"),
+    // Not readStdinInput: that one trims, and a tool result is sent as read (P5).
+    readStdin: () => readFileSync(0, "utf-8"),
+};
+/**
+ * `--output` and `--fail` values as `<callId>=<value>`, split on the first `=`. `@<path>` reads a file and
+ * `@-` reads stdin, both verbatim. Only syntax is checked here: without stored state the CLI cannot list the
+ * calls a response released, so completeness is the server's check (#671 D4). Every check runs before any read.
+ */
+export function parseToolAnswers(outputs = [], fails = [], io = defaultIo) {
+    const entries = [
+        ...outputs.map((raw) => ({ raw, flag: "--output", noun: "value", failed: false })),
+        ...fails.map((raw) => ({ raw, flag: "--fail", noun: "message", failed: true })),
+    ].map(({ raw, flag, noun, failed }) => {
+        const eq = raw.indexOf("=");
+        if (eq < 0)
+            throw new CliUsageError(`Invalid ${flag} '${raw}': use <callId>=<${noun}>.`);
+        const callId = raw.slice(0, eq);
+        if (!callId)
+            throw new CliUsageError(`Invalid ${flag} '${raw}': the call id is empty.`);
+        return { callId, value: raw.slice(eq + 1), failed };
+    });
+    const seen = new Map();
+    for (const e of entries) {
+        const before = seen.get(e.callId);
+        if (before === undefined) {
+            seen.set(e.callId, e.failed);
+        }
+        else if (before === e.failed) {
+            throw new CliUsageError(`Tool call ${e.callId} is answered more than once.`);
+        }
+        else {
+            throw new CliUsageError(`Tool call ${e.callId} is answered by both --output and --fail.`);
+        }
+    }
+    if (entries.filter((e) => e.value === "@-").length > 1) {
+        throw new CliUsageError("Only one --output or --fail value can read stdin (@-).");
+    }
+    return entries.map(({ callId, value, failed }) => ({ callId, output: readAnswerValue(value, io), failed }));
+}
+function readAnswerValue(value, io) {
+    if (value === "@-") {
+        try {
+            return io.readStdin();
+        }
+        catch (err) {
+            // A closed or non-blocking stdin (EAGAIN, EOF) is a usage error like an unreadable file.
+            throw new CliUsageError(`stdin: cannot read (${err.code ?? err.message})`);
+        }
+    }
+    if (!value.startsWith("@"))
+        return value;
+    const path = value.slice(1);
+    try {
+        return io.readFile(path);
+    }
+    catch (err) {
+        const code = err.code;
+        throw new CliUsageError(`${path}: cannot read file (${code ?? err.message})`);
+    }
+}
 const MAX_PAGES = 50;
 export async function fetchPendingApprovals(client, agentId, responseId) {
     const rows = [];
@@ -41,7 +104,8 @@ export function planDecisions(pending, opts, responseId) {
         throw new CliUsageError("Use either --approve-all / --reject-all or explicit --approve / --reject ids, not both.");
     }
     if (!usesAll && approve.length === 0 && reject.length === 0) {
-        throw new CliUsageError("Choose a decision: --approve <ids...>, --reject <ids...>, --approve-all or --reject-all.");
+        throw new CliUsageError("Choose a decision: --approve <ids...>, --reject <ids...>, --approve-all or --reject-all " +
+            "(and answer relayed tool calls with --output / --fail).");
     }
     const choice = new Map();
     if (usesAll) {
@@ -84,6 +148,26 @@ export function planDecisions(pending, opts, responseId) {
         };
     });
 }
+/**
+ * The decisions a `decide` call sends beside its tool answers (#671 D5). A pure relay pause has no pending
+ * approval, so the approval flags are optional there: `--approve-all` / `--reject-all` add nothing (P1) and
+ * only explicit ids are refused. A mixed pause needs its approvals decided in the same call.
+ */
+export function planContinuation(pending, opts, toolAnswers, responseId) {
+    if (toolAnswers.length === 0)
+        return planDecisions(pending, opts, responseId);
+    const ids = [...(opts.approve ?? []), ...(opts.reject ?? [])];
+    if (pending.length === 0) {
+        if (ids.length)
+            throw new CliUsageError(`Not pending on ${responseId}: ${ids.join(", ")}`);
+        return [];
+    }
+    if (!opts.approveAll && !opts.rejectAll && ids.length === 0) {
+        throw new CliUsageError(`${responseId} also waits for approvals: every relayed tool call and every pending approval must be answered ` +
+            `in one call. Undecided: ${pending.map((r) => r.id).join(", ")} (add --approve-all, --reject-all or the ids).`);
+    }
+    return planDecisions(pending, opts, responseId);
+}
 export function decisionsFromAnswers(pending, answers) {
     return pending.map((r) => {
         const answer = answers.get(String(r.id));
@@ -109,20 +193,30 @@ export function toApprovalItems(decisions) {
         ...(d.remember ? { remember: d.remember } : {}),
     }));
 }
+/** `failed: true` is Backbone's extension (#480): the tool's span ends ERROR. */
+export function toToolOutputItems(answers) {
+    return answers.map((a) => ({
+        type: "function_call_output",
+        call_id: a.callId,
+        output: a.output,
+        ...(a.failed ? { failed: true } : {}),
+    }));
+}
 /**
  * Continues on `agent/<agentId>[@<label>][#<model>]` with the label and model override the run used: the
  * server resolves the continuation's tools, instructions and model from this reference, so both must match
  * the run's or the continuation drops to another version or the agent's default model.
  * Never the echoed `name@<versionNumber>` (it would 404 as a label).
  * With `mode`, the `backbone:mode` item follows the decisions (#656 D7); without it, nothing is added (D2).
+ * Tool answers go first, in flag order (#671 D6): the server replays accepted outputs ahead of other items.
  */
-export async function continueWithDecisions(client, agentId, responseId, decisions, label, model, mode) {
-    const approvals = toApprovalItems(decisions);
+export async function continueWithDecisions(client, agentId, responseId, decisions, label, model, mode, toolAnswers = []) {
+    const items = [...toToolOutputItems(toolAnswers), ...toApprovalItems(decisions)];
     const body = {
         model: `agent/${agentId}${label ? `@${label}` : ""}${model ? `#${model}` : ""}`,
         previous_response_id: responseId,
         stream: false,
-        input: mode ? [...approvals, modeItem(mode)] : approvals,
+        input: mode ? [...items, modeItem(mode)] : items,
     };
     // The generated body type does not model backbone: extension items, hence the cast.
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/lib/agent-run.js

@@ -139,6 +139,25 @@ export function connectionsSentence(connections) {
 }
 /** Joins a connect pause's instruction to the command that continues it; {@link printRunText} breaks the line there. */
 const THEN_RUN = ", then run: ";
+/**
+ * The `decide` command that answers a relay pause (#671 D7): one `--output <callId>=@<file>` per pending call,
+ * plus `--approve-all` when approvals wait too. The call id is chosen by the model, so the suggested file name
+ * keeps only `[A-Za-z0-9_-]` (P2) and never repeats: it can be neither `../…` nor an absolute path.
+ */
+function relayDecideCommand(ref, responseId, calls, withApprovals) {
+    const used = new Set();
+    const outputs = calls.map((c) => {
+        const safe = c.callId.replace(/[^A-Za-z0-9_-]/g, "_");
+        let file = safe;
+        // Compared without case: on Windows and macOS `callA.out` and `calla.out` are one file.
+        for (let n = 2; used.has(file.toLowerCase()); n++)
+            file = `${safe}-${n}`;
+        used.add(file.toLowerCase());
+        return ` --output ${shellQuote(`${c.callId}=@${file}.out`)}`;
+    });
+    return (`2kw agents decide ${shellQuote(ref)} --response ${shellQuote(responseId)}${outputs.join("")}` +
+        (withApprovals ? " --approve-all" : ""));
+}
 /**
  * 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.
@@ -225,8 +244,16 @@ export function buildRunEnvelope(result, agentRef, chatUrl = DEFAULT_CHAT_URL) {
     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.
+    else if (status === "requires_tool_output" && pendingToolCalls.length > 0) {
+        // The engine answers the connect call itself on the continuation, so connecting first is enough.
+        if (ref && responseId) {
+            const decide = relayDecideCommand(ref, responseId, pendingToolCalls, pendingApprovals.length > 0);
+            next = pendingConnections.length > 0
+                ? `${connectionsSentence(pendingConnections)} in ${chatUrl}/connectors${THEN_RUN}${decide}`
+                : decide;
+        }
+    }
+    else if (status === "requires_tool_output" && pendingConnections.length > 0 && responseId) {
         // `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)}`
@@ -272,19 +299,32 @@ export function printRunText(env) {
         console.log(chalk.dim(`\n── ${s(head.join(" · "))}`));
     if (env.toolCalls.length)
         console.log(chalk.dim(`   tools: ${env.toolCalls.map((c) => `${s(c.tool)} ${c.status === "incomplete" ? "✗" : "✓"}`).join("  ")}`));
+    const printApprovals = () => env.pendingApprovals.forEach((a, i) => {
+        console.log(`  ${i + 1}. ${s(a.tool)} [${s(a.policyClass)}] ${s(a.approvalId)}`);
+        // JSON.stringify escapes C0 controls but leaves DEL and C1 raw.
+        console.log(chalk.dim(`     ${s(JSON.stringify(a.arguments))}`));
+        if (a.reason)
+            console.log(chalk.dim(`     reason: ${s(a.reason)}`));
+    });
     if (env.status === "requires_approval") {
         console.log(chalk.yellow("\nPaused for approval:"));
-        env.pendingApprovals.forEach((a, i) => {
-            console.log(`  ${i + 1}. ${s(a.tool)} [${s(a.policyClass)}] ${s(a.approvalId)}`);
-            // JSON.stringify escapes C0 controls but leaves DEL and C1 raw.
-            console.log(chalk.dim(`     ${s(JSON.stringify(a.arguments))}`));
-            if (a.reason)
-                console.log(chalk.dim(`     reason: ${s(a.reason)}`));
-        });
+        printApprovals();
         if (env.next)
             console.log(`\nDecide with:\n  ${s(env.next)}`);
     }
     else if (env.status === "requires_tool_output") {
+        if (env.pendingToolCalls.length) {
+            console.log(chalk.yellow("\nPaused: the agent waits for client-side tool output:"));
+            env.pendingToolCalls.forEach((c) => {
+                console.log(`  - ${s(c.tool)} (${s(c.callId)})`);
+                console.log(chalk.dim(`    ${s(JSON.stringify(c.arguments))}`));
+            });
+            // The printed command carries --approve-all, so show what it approves (#671 P3).
+            if (env.pendingApprovals.length) {
+                console.log(chalk.yellow("\nIt also waits for approval:"));
+                printApprovals();
+            }
+        }
         if (env.pendingConnections.length) {
             console.log(chalk.yellow("\nPaused: the agent needs you to connect in chat:"));
             env.pendingConnections.forEach((c) => {
@@ -296,9 +336,8 @@ export function printRunText(env) {
             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)})`));
+        else if (env.pendingToolCalls.length && env.next) {
+            console.log(`\nAnswer with:\n  ${s(env.next)}`);
         }
         if (!env.pendingConnections.length && !env.pendingToolCalls.length) {
             console.log(chalk.yellow("\nPaused on something this CLI cannot show:"));

package/dist/lib/errors.js

@@ -95,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. */

package/package.json

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