@2kw/ai 6.3.0-dev.39 → 6.3.0-dev.42

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/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

@@ -25,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;
@@ -61,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,
@@ -118,7 +149,7 @@ export function buildRunEnvelope(result, agentRef) {
         : null;
     return {
         status,
-        mode: null,
+        mode: responseMode(result),
         agent,
         version,
         responseId,

package/package.json

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