@2kw/ai 6.3.0-dev.14 → 6.3.0-dev.142

package/dist/commands/skill-versions.js

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import { Command, InvalidArgumentError } from "commander";
 import { readFileSync } from "node:fs";
 import { getClient, runAction } from "../lib/client.js";
 import { formatPage, formatDetail } from "../lib/output.js";
@@ -48,6 +48,32 @@ export function makeSkillVersionsCommand() {
             formatDetail(data, command);
         });
     });
+    cmd
+        .command("restore")
+        .description("Restore a version as a new version; latest moves to it (the newest version is reused when it already has the content)")
+        .argument("<id>", "Skill ID")
+        .argument("<versionNumber>", "Version number to restore", parseVersionNumber)
+        .action(async (id, versionNumber, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data, response } = await client.POST("/v1/skills/{id}/versions/{versionNumber}/restore", {
+                params: { path: { id, versionNumber } },
+            });
+            // 200, not 201: the newest version already had the content and latest moved to it.
+            if (response.status === 200 && data) {
+                console.error(`No new version: v${data.versionNumber} already has the content of v${versionNumber}; latest now points at v${data.versionNumber}.`);
+            }
+            formatDetail(data, command);
+        });
+    });
     return cmd;
 }
+/** A restore names an existing version by number; refuse anything else before calling the API (#783). */
+function parseVersionNumber(value) {
+    const n = Number(value);
+    if (!/^\d+$/.test(value) || n < 1) {
+        throw new InvalidArgumentError("Version number must be a positive integer.");
+    }
+    return n;
+}
 //# sourceMappingURL=skill-versions.js.map

package/dist/commands/skills.js

@@ -21,6 +21,17 @@ async function checkResponse(res) {
         timestamp: body.timestamp ?? new Date().toISOString(),
     });
 }
+const MIN_ROLES = ["user", "viewer", "member", "admin", "owner"];
+/** A role word as the API's `Role`, or null for `none` (#785). */
+function parseMinRole(word) {
+    const lower = word.trim().toLowerCase();
+    if (lower === "none")
+        return null;
+    if (MIN_ROLES.includes(lower)) {
+        return lower.toUpperCase();
+    }
+    throw new Error(`Role must be one of: ${MIN_ROLES.join(", ")}, none`);
+}
 /** Manage skills, versions and labels (#642). */
 export function makeSkillsCommand() {
     const cmd = new Command("skills").description("Manage skills");
@@ -75,6 +86,24 @@ export function makeSkillsCommand() {
             formatDetail(data, command);
         });
     });
+    cmd
+        .command("min-role")
+        .description("Set the minimum organization role that sees this skill in agent runs (admin only); none removes it")
+        .argument("<id>", "Skill ID")
+        .argument("<role>", "user, viewer, member, admin, owner or none")
+        .action(async (id, role, _opts, command) => {
+        await runAction(command, async () => {
+            const minRole = parseMinRole(role);
+            const client = getClient(command);
+            const { data } = await client.PUT("/v1/skills/{id}/min-role", {
+                params: { path: { id } },
+                // The spec publishes minRole without null (springdoc marks no record component
+                // nullable); the operation documents null as "remove the minimum", and it is sent as such.
+                body: { minRole: minRole },
+            });
+            formatDetail(data, command);
+        });
+    });
     cmd
         .command("delete")
         .description("Delete a skill")
@@ -157,7 +186,8 @@ export function makeSkillsCommand() {
                 const { data } = await client.GET("/v1/skills/{id}", { params: { path: { id } } });
                 if (!data?.name)
                     throw new Error("Skill name missing; specify an output path with -o.");
-                outputPath = `${basename(data.name)}-v${versionNumber}.zip`;
+                // #788: ":" (a plugin skill) becomes "." before basename, which on Windows reads "a:" as a drive.
+                outputPath = `${basename(data.name.replace(/:/g, "."))}-v${versionNumber}.zip`;
             }
             const config = resolveConfig(command);
             const authHeader = await resolveAuthHeader(config);

package/dist/commands/tracing.js

@@ -1,10 +1,11 @@
 import { Command } from "commander";
 import { getClient, runAction } from "../lib/client.js";
 import { formatDetail, formatList } from "../lib/output.js";
+import { tracingSettingsBody } from "../lib/tracing-settings.js";
 export function makeTracingCommand() {
     const cmd = new Command("tracing").description("Traces and per-org tracing settings (prompt / completion capture)");
     // ── settings ──────────────────────────────────────────────────
-    const settings = new Command("settings").description("Manage per-org tracing settings (includePrompts / includeCompletions)");
+    const settings = new Command("settings").description("Manage per-org tracing settings (PII capture and trace retention)");
     settings
         .command("get")
         .description("Show current tracing settings")
@@ -20,6 +21,7 @@ export function makeTracingCommand() {
         .description("Update tracing settings. Both toggles control PII capture — default is false for both.")
         .option("--include-prompts <bool>", "Retain prompt content on ingested spans (true/false)")
         .option("--include-completions <bool>", "Retain completion content on ingested spans (true/false)")
+        .option("--retention-days <days>", 'Trace retention in days, at most your plan\'s limit, or "plan" to follow the plan. Shortening deletes older traces at the next daily sweep.')
         .action(async (opts, command) => {
         await runAction(command, async () => {
             const client = getClient(command);
@@ -27,17 +29,8 @@ export function makeTracingCommand() {
             // resetting the other. Otherwise an unset flag defaults to false
             // and silently disables capture the admin had already enabled.
             const { data: current } = await client.GET("/v1/tracing/settings");
-            const body = {
-                includePrompts: opts.includePrompts !== undefined
-                    ? opts.includePrompts === "true"
-                    : (current?.includePrompts ?? false),
-                includeCompletions: opts.includeCompletions !== undefined
-                    ? opts.includeCompletions === "true"
-                    : (current?.includeCompletions ?? false),
-            };
-            const { data } = await client.PUT("/v1/tracing/settings", {
-                body,
-            });
+            const body = tracingSettingsBody(current, opts);
+            const { data } = await client.PUT("/v1/tracing/settings", { body });
             formatDetail(data, command);
         });
     });
@@ -84,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");
@@ -95,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),
@@ -103,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/index.js

@@ -22,6 +22,7 @@ import { makeContextCommand } from "./commands/context.js";
 import { makeExperimentsCommand } from "./commands/experiments.js";
 import { makeTracingCommand } from "./commands/tracing.js";
 import { makeSettingsCommand } from "./commands/settings.js";
+import { makeMemoryCommand } from "./commands/memory.js";
 import { makeEvaluatorsCommand } from "./commands/evaluators.js";
 import { makeScoresCommand } from "./commands/scores.js";
 import { makeQueuesCommand } from "./commands/queues.js";
@@ -64,6 +65,7 @@ program.addCommand(makeScoresCommand());
 program.addCommand(makeQueuesCommand());
 program.addCommand(makeTracingCommand());
 program.addCommand(makeSettingsCommand());
+program.addCommand(makeMemoryCommand());
 program.addCommand(makeAgentsCommand());
 program.addCommand(makeConversationsCommand());
 program.addCommand(makeKnowledgeCommand());

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

@@ -1,6 +1,6 @@
 import type { components } from "../generated/openapi.js";
 import type { ApiClient } from "./agent-lookup.js";
-import type { ResponsesResult } from "./agent-run.js";
+import { type ConversationMode, type ResponsesResult } from "./agent-run.js";
 export type ApprovalRow = components["schemas"]["ToolApprovalDTO"];
 export interface DecideOptions {
     approve?: string[];
@@ -22,20 +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): 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,5 +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 = [];
@@ -40,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) {
@@ -83,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));
@@ -108,18 +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) {
+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: toApprovalItems(decisions),
+        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.d.ts

@@ -1,5 +1,8 @@
+import type { components } from "../generated/openapi.js";
 type AnyRecord = Record<string, any>;
 export type RunStatus = "completed" | "requires_approval" | "requires_tool_output" | "incomplete";
+/** A built-in SkillsApply approval's preview (#781, spec §6); the generated type, fields all optional. */
+export type SkillsApplyPreview = components["schemas"]["SkillsApplyPreview"];
 export interface PendingApproval {
     approvalId: string;
     callId: string;
@@ -8,6 +11,8 @@ export interface PendingApproval {
     policyClass: string;
     /** Why the automatic approver escalated this request to a human (#634); null when it did not. */
     reason: string | null;
+    /** What a built-in SkillsApply change does (#781); null for every other approval. Keyed on presence, not on the tool name (#948). */
+    preview: SkillsApplyPreview | null;
 }
 export interface ToolCallSummary {
     tool: string;
@@ -20,10 +25,44 @@ export interface PendingToolCall {
     callId: string;
     arguments: unknown;
 }
+/**
+ * A connector the run waits for the user to connect, allow or reconnect in chat.2kw.ai: an open
+ * `backbone:connector_auth_request` (#807 R12). The caller never answers the connect call; the
+ * continuation re-checks access itself. Decoded by `connect-pause.ts` (#1086), whose `id` and
+ * `callId` the envelope does not publish.
+ */
+export interface PendingConnection {
+    serverLabel: string;
+    host: string;
+    /** `connect`, `allow` or `reconnect`. */
+    reason: string;
+    /** The egress difference an allow is re-asked for; absent otherwise. */
+    destinations?: string[];
+}
+/** The end user's conversation mode (epic &59); the server matches these three values exactly. */
+export type ConversationMode = "plan" | "ask" | "auto";
+export declare const CONVERSATION_MODES: readonly ConversationMode[];
+/** `--mode` help text, in the words of the embedded chat's mode chip (#655). */
+export declare const MODE_OPTION_HELP: string;
+/**
+ * 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 declare function parseModeOption(raw: string | undefined): ConversationMode | undefined;
+/** The `backbone:mode` input item (S1 D7); always appended last. */
+export declare function modeItem(mode: ConversationMode): {
+    type: "backbone:mode";
+    mode: ConversationMode;
+};
+/**
+ * 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 declare function responseMode(result: ResponsesResult | undefined): ConversationMode | null;
 export interface RunEnvelope {
     status: RunStatus;
-    /** Reserved for the server-side conversation mode (#656); always null until then. */
-    mode: null;
+    /** The conversation mode the request ran under (`conversation_mode`); null when none is set. */
+    mode: ConversationMode | null;
     agent: string | null;
     version: number | null;
     responseId: string | null;
@@ -32,6 +71,7 @@ export interface RunEnvelope {
     toolCalls: ToolCallSummary[];
     pendingApprovals: PendingApproval[];
     pendingToolCalls: PendingToolCall[];
+    pendingConnections: PendingConnection[];
     incompleteReason: string | null;
     usage: {
         inputTokens: number;
@@ -56,6 +96,7 @@ export interface ResponsesResult {
     incomplete_details?: {
         reason?: string;
     } | null;
+    conversation_mode?: string | null;
 }
 export declare const EXIT_CODES: Record<RunStatus, number>;
 /** The assistant's text: every `output_text` part of every `message` item, in order. */
@@ -76,7 +117,13 @@ export declare function parseAgentModel(model?: string): {
  */
 export declare function stripControl(s: string): string;
 export declare function shellQuote(value: string): string;
-export declare function buildRunEnvelope(result: ResponsesResult | undefined, agentRef?: string): RunEnvelope;
+/** "Connect a (h), allow the agent to use b (h) and reconnect c (h)". */
+export declare function connectionsSentence(connections: PendingConnection[]): string;
+/**
+ * @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 declare function buildRunEnvelope(result: ResponsesResult | undefined, agentRef?: string, chatUrl?: string): RunEnvelope;
 /** Human-readable rendering of an envelope on stdout. Every value printed is passed through {@link stripControl}. */
 export declare function printRunText(env: RunEnvelope): void;
 export {};