@2kw/ai 6.3.0-dev.36 → 6.3.0-dev.40

package/dist/commands/agent-run.js

@@ -5,7 +5,7 @@ import { isJsonOutput } from "../lib/config.js";
 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, printRunText, stripControl } from "../lib/agent-run.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 { PromptAbortedError, promptApprovals, readlineAsk } from "../lib/approval-prompt.js";
 import { withModelOverride } from "../lib/agent-models.js";
@@ -90,7 +90,7 @@ async function finishRun(command, client, target, first, opts) {
                     throw new CliUsageError(`No pending approvals for ${responseId} (already decided or superseded).`);
                 }
                 const decisions = decisionsFromAnswers(rows, answers);
-                result = await withSpinner("Continuing...", () => continueWithDecisions(client, String(agent.id), responseId, decisions, target.label, target.model));
+                result = await withSpinner("Continuing...", () => continueWithDecisions(client, String(agent.id), responseId, decisions, target.label, target.model, target.mode));
                 env = buildRunEnvelope(result, agentRef);
             }
         }
@@ -122,14 +122,21 @@ export function makeAgentRunCommand() {
         .option("--conversation <id>", "Continue a conversation")
         .option("--continue <responseId>", "Continue from a previous response")
         .option("--model <model>", "Run this request on another model from the agent's list (sends <agent>#<model>)")
+        .option("--mode <mode>", MODE_OPTION_HELP)
         .option("--no-input", "Never prompt for approvals, even on a terminal")
         .option("--raw", "Print the untouched API response")
         .action(async (agentArg, input, opts, command) => {
         await runAction(command, async () => {
             const agentRef = withModelOverride(agentArg, opts.model);
+            const mode = parseModeOption(opts.mode);
             const text = resolveRunInput(input, opts.inputFile);
             const client = getClient(command);
-            const body = { model: `agent/${agentRef}`, input: text, stream: false };
+            // Without --mode the body stays exactly as before #656 (D2): input is the bare string.
+            const body = {
+                model: `agent/${agentRef}`,
+                input: mode ? [{ type: "message", role: "user", content: text }, modeItem(mode)] : text,
+                stream: false,
+            };
             if (opts.conversation)
                 body.conversation = opts.conversation;
             if (opts.continue)
@@ -146,7 +153,7 @@ export function makeAgentRunCommand() {
             // The prompt reads stdin and writes to stderr, so those two decide; stdout may be redirected.
             const interactive = !!process.stdin.isTTY && !!process.stderr.isTTY && !isJsonOutput(command) && opts.input !== false && !opts.raw;
             const { name, label, model } = splitAgentRef(agentRef);
-            await finishRun(command, client, { name, label, model }, data, {
+            await finishRun(command, client, { name, label, model, mode }, data, {
                 raw: !!opts.raw,
                 interactive,
             });
@@ -164,9 +171,11 @@ 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("--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);
             const client = getClient(command);
             const { name, label, model } = splitAgentRef(agentRef);
             // Dropped silently, an empty override would continue the run on the default model.
@@ -182,8 +191,8 @@ export function makeAgentDecideCommand() {
                 reason: opts.reason,
                 remember: opts.remember,
             }, opts.response);
-            const result = await withSpinner("Continuing...", () => continueWithDecisions(client, String(agent.id), opts.response, decisions, label, model));
-            await finishRun(command, client, { name, label, model }, result, { raw: !!opts.raw, interactive: false });
+            const result = await withSpinner("Continuing...", () => continueWithDecisions(client, String(agent.id), opts.response, decisions, label, model, mode));
+            await finishRun(command, client, { name, label, model, mode }, result, { raw: !!opts.raw, interactive: false });
         });
     });
 }

package/dist/commands/conversations.js

@@ -98,6 +98,22 @@ export function makeConversationsCommand() {
             formatSuccess(`Conversation ${conversationId} deleted.`, command);
         });
     });
+    cmd
+        .command("cancel")
+        .description("Ask a running turn of a conversation to stop")
+        .argument("<conversationId>", "Conversation ID")
+        .requiredOption("--turn <turnId>", "The turn id the client sent as the Backbone-Turn-Id header")
+        .action(async (conversationId, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.POST("/v1/conversations/{conversationId}/cancel", {
+                params: { path: { conversationId } },
+                body: { turn_id: opts.turn },
+            });
+            // Accepted, not performed: the turn's own response says whether it stopped.
+            formatSuccess(`Stop requested for turn ${opts.turn} of conversation ${conversationId}.`, command);
+        });
+    });
     const items = new Command("items").description("List a conversation's items");
     items
         .command("list")

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[];
@@ -36,6 +36,7 @@ export declare function toApprovalItems(decisions: Decision[]): Record<string, s
  * 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).
  */
-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): Promise<ResponsesResult>;
 //# sourceMappingURL=agent-decide.d.ts.map

package/dist/lib/agent-decide.js

@@ -1,3 +1,4 @@
+import { modeItem } from "./agent-run.js";
 import { CliUsageError } from "./errors.js";
 import { paginationParams } from "./pagination.js";
 const MAX_PAGES = 50;
@@ -113,13 +114,15 @@ export function toApprovalItems(decisions) {
  * 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).
  */
-export async function continueWithDecisions(client, agentId, responseId, decisions, label, model) {
+export async function continueWithDecisions(client, agentId, responseId, decisions, label, model, mode) {
+    const approvals = toApprovalItems(decisions);
     const body = {
         model: `agent/${agentId}${label ? `@${label}` : ""}${model ? `#${model}` : ""}`,
         previous_response_id: responseId,
         stream: false,
-        input: toApprovalItems(decisions),
+        input: mode ? [...approvals, modeItem(mode)] : approvals,
     };
     // 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,30 @@ export interface PendingToolCall {
     callId: string;
     arguments: unknown;
 }
+/** 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;
@@ -56,6 +81,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. */

package/dist/lib/agent-run.js

@@ -1,4 +1,35 @@
 import chalk from "chalk";
+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,
@@ -80,6 +111,7 @@ 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 toolCalls = [];
@@ -117,7 +149,7 @@ export function buildRunEnvelope(result, agentRef) {
         : null;
     return {
         status,
-        mode: null,
+        mode: responseMode(result),
         agent,
         version,
         responseId,

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/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/package.json

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