@2kw/ai 6.3.0-dev.8 → 6.3.0-dev.85

package/dist/commands/memory.js

@@ -0,0 +1,132 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
+import { CliUsageError } from "../lib/errors.js";
+import { formatDetail, formatList, formatSuccess } from "../lib/output.js";
+/** The If-Match value for a version a GET returned: the quoted ETag the API expects. */
+export function ifMatchHeader(version) {
+    if (!/^\d{1,18}$/.test(version)) {
+        throw new CliUsageError(`--if-match takes the file's version, a whole number: ${version}`);
+    }
+    return `"${version}"`;
+}
+function requireYes(opts, what) {
+    if (!opts.yes) {
+        throw new CliUsageError(`${what} cannot be undone. Pass --yes to confirm.`);
+    }
+}
+/**
+ * Agent memory (agent memory spec §7.1, §7.4). `ls`, `cat`, `put`, `rm` and `forget` act on
+ * the caller's own memory; `members` and `erase` are for ADMIN and OWNER and never show
+ * paths or content. Content is lossless: `cat` prints it raw, `put` sends the file as is.
+ */
+export function makeMemoryCommand() {
+    const cmd = new Command("memory").description("Your agent memory files; member totals and erasure for admins");
+    cmd
+        .command("ls")
+        .description("List your memory files")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/memories/me/files");
+            formatList(data, command, [
+                "path",
+                "sizeBytes",
+                "version",
+                "updatedAt",
+                "lastWrittenByAgentId",
+            ]);
+        });
+    });
+    cmd
+        .command("cat <path>")
+        .description("Print one of your memory files, raw (--json for the file object)")
+        .action(async (path, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/memories/me/file", {
+                params: { query: { path } },
+            });
+            if (isJsonOutput(command)) {
+                formatDetail(data, command);
+            }
+            else {
+                process.stdout.write(data.content);
+            }
+        });
+    });
+    cmd
+        .command("put <path>")
+        .description("Create or replace one of your memory files from a local UTF-8 file")
+        .requiredOption("--file <file>", "Local file whose content is stored")
+        .option("--if-match <version>", "Only replace the file if it still has this version")
+        .action(async (path, opts, command) => {
+        await runAction(command, async () => {
+            // An empty --if-match (e.g. an unset shell variable) must be refused, never dropped
+            // into an unconditional overwrite.
+            const headers = opts.ifMatch !== undefined ? { "If-Match": ifMatchHeader(opts.ifMatch) } : undefined;
+            const content = readFileSync(opts.file, "utf8");
+            const client = getClient(command);
+            const { data } = await client.PUT("/v1/memories/me/file", {
+                params: { query: { path } },
+                body: { content },
+                headers,
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("rm <path>")
+        .description("Delete one of your memory files, or a directory with everything below it")
+        .action(async (path, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.DELETE("/v1/memories/me/file", { params: { query: { path } } });
+            formatSuccess(`Deleted ${path}`, command);
+        });
+    });
+    cmd
+        .command("forget")
+        .description("Delete your whole memory (cannot be undone)")
+        .option("--yes", "Confirm")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            requireYes(opts, "Forgetting your whole memory");
+            const client = getClient(command);
+            await client.DELETE("/v1/memories/me");
+            formatSuccess("Forgot your whole memory", command);
+        });
+    });
+    cmd
+        .command("members")
+        .description("Memory totals per member, without paths or content (ADMIN+)")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/memories/users");
+            formatList(data, command, [
+                "userId",
+                "fileCount",
+                "totalBytes",
+                "lastUpdatedAt",
+            ]);
+        });
+    });
+    cmd
+        .command("erase <userId>")
+        .description("Erase a member's whole memory (ADMIN+, cannot be undone)")
+        .option("--yes", "Confirm")
+        .action(async (userId, opts, command) => {
+        await runAction(command, async () => {
+            requireYes(opts, "Erasing a member's memory");
+            const client = getClient(command);
+            await client.DELETE("/v1/memories/users/{userId}", {
+                params: { path: { userId } },
+            });
+            formatSuccess(`Erased the memory of ${userId}`, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=memory.js.map

package/dist/commands/settings.d.ts

@@ -0,0 +1,13 @@
+import { Command } from "commander";
+/**
+ * Parses the value a setting takes: a JSON object. The server checks its shape per key
+ * (for agents.default: {"agentId": "<id>"}); this only refuses what can never be valid.
+ */
+export declare function parseSettingValue(raw: string): Record<string, unknown>;
+/**
+ * Organization and member settings (agent-first chat spec §3.1, §4). Without --org every
+ * write targets the caller's own member tier; --org writes the organization's, which needs
+ * the key's write role (ADMIN or OWNER for agents.default).
+ */
+export declare function makeSettingsCommand(): Command;
+//# sourceMappingURL=settings.d.ts.map

package/dist/commands/settings.js

@@ -0,0 +1,80 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { CliUsageError } from "../lib/errors.js";
+import { formatDetail } from "../lib/output.js";
+/**
+ * Parses the value a setting takes: a JSON object. The server checks its shape per key
+ * (for agents.default: {"agentId": "<id>"}); this only refuses what can never be valid.
+ */
+export function parseSettingValue(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CliUsageError(`Setting value is not valid JSON: ${raw}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliUsageError('Setting value must be a JSON object, e.g. \'{"agentId":"agt_123"}\'');
+    }
+    return parsed;
+}
+/**
+ * Organization and member settings (agent-first chat spec §3.1, §4). Without --org every
+ * write targets the caller's own member tier; --org writes the organization's, which needs
+ * the key's write role (ADMIN or OWNER for agents.default).
+ */
+export function makeSettingsCommand() {
+    const cmd = new Command("settings").description("Organization and member settings (e.g. agents.default)");
+    cmd
+        .command("get <key>")
+        .description("Show a setting: the effective value, its source and both tiers")
+        .action(async (key, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/settings/{key}", {
+                params: { path: { key } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("set <key> <json>")
+        .description("Set your own value, or the organization's with --org (ADMIN+)")
+        .option("--org", "Write the organization's value instead of your own")
+        .action(async (key, json, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const body = { value: parseSettingValue(json) };
+            const { data } = opts.org
+                ? await client.PUT("/v1/settings/{key}/org", {
+                    params: { path: { key } },
+                    body,
+                })
+                : await client.PUT("/v1/settings/{key}/member", {
+                    params: { path: { key } },
+                    body,
+                });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("unset <key>")
+        .description("Clear your own value, or the organization's with --org (ADMIN+)")
+        .option("--org", "Clear the organization's value instead of your own")
+        .action(async (key, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = opts.org
+                ? await client.DELETE("/v1/settings/{key}/org", {
+                    params: { path: { key } },
+                })
+                : await client.DELETE("/v1/settings/{key}/member", {
+                    params: { path: { key } },
+                });
+            formatDetail(data, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=settings.js.map

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")

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);
         });
     });

package/dist/index.js

@@ -21,6 +21,8 @@ import { makeDocsCommand } from "./commands/docs.js";
 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";
@@ -62,6 +64,8 @@ program.addCommand(makeEvaluatorsCommand());
 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[];
@@ -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,43 @@ 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.
+ */
+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 +70,7 @@ export interface RunEnvelope {
     toolCalls: ToolCallSummary[];
     pendingApprovals: PendingApproval[];
     pendingToolCalls: PendingToolCall[];
+    pendingConnections: PendingConnection[];
     incompleteReason: string | null;
     usage: {
         inputTokens: number;
@@ -56,6 +95,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 +116,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 {};