@2kw/ai 8.1.2 → 8.2.0-dev.10

package/dist/agent-config/file.js

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { extname } from "node:path";
 import { parse, YAMLParseError } from "yaml";
 import { CliUsageError } from "../lib/errors.js";
-import { validateAgentConfig } from "./validate.js";
+import { agentConfigWarnings, validateAgentConfig } from "./validate.js";
 const PLACEHOLDER = /\$\$\{|\$\{([A-Z_][A-Z0-9_]*)\}/g;
 /** Variable names whose value is a secret wherever it is used. */
 const SECRET_NAME = /(SECRET|TOKEN|PASSWORD|PASSWD|PASS|API_?KEY|KEY|PRIVATE|CREDENTIAL|AUTH)/;
@@ -132,6 +132,8 @@ export function loadAgentConfig(path, env, readStdin = () => readFileSync(0, "ut
     if (issues.length) {
         throw new CliUsageError(`${source} is invalid:\n${issues.map((i) => `  ${i.pointer}: ${i.message}`).join("\n")}`);
     }
+    for (const warning of agentConfigWarnings(value))
+        console.error(`warning: ${source}: ${warning}`);
     return { config: value, secrets };
 }
 //# sourceMappingURL=file.js.map

package/dist/agent-config/schema.d.ts

@@ -10,6 +10,14 @@ export declare const AGENT_SCHEMA_ID = "https://docs.2kw.ai/schemas/agent.v1.jso
  * The backend refuses the same map on save (NonAuthorableTools, #1263); its test fails if they differ.
  */
 export declare const NON_AUTHORABLE_TOOL_TYPES: Record<string, string>;
+/**
+ * The three tools `backbone.canvas` grants (#1698). Listing one is refused on the backend too
+ * (CanvasToolEntryValidator, 422); kept apart from NON_AUTHORABLE_TOOL_TYPES, which the backend's
+ * NonAuthorableToolsTest holds equal to the backend list.
+ */
+export declare const CANVAS_MEMBER_TYPES: Record<string, string>;
+/** Types Canvas replaced: still accepted, with a warning (#1698). */
+export declare const RETIRED_TOOL_TYPES: string[];
 export declare const agentSchema: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
     readonly $id: "https://docs.2kw.ai/schemas/agent.v1.json";
@@ -309,6 +317,19 @@ export declare const agentSchema: {
                 };
             };
         };
+        readonly canvasTool: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["type"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "backbone.canvas";
+                };
+                readonly requiresConfirmation: {
+                    readonly type: "boolean";
+                };
+            };
+        };
         readonly showTableTool: {
             readonly type: "object";
             readonly additionalProperties: false;
@@ -527,6 +548,18 @@ export declare const agentSchema: {
                 readonly then: {
                     readonly $ref: "#/$defs/bashTool";
                 };
+            }, {
+                readonly if: {
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                readonly then: {
+                    readonly $ref: "#/$defs/canvasTool";
+                };
             }, {
                 readonly if: {
                     required: string[];
@@ -579,6 +612,22 @@ export declare const agentSchema: {
                         };
                     };
                 };
+            }, {
+                readonly if: {
+                    readonly required: readonly ["type"];
+                    readonly properties: {
+                        readonly type: {
+                            readonly enum: string[];
+                        };
+                    };
+                };
+                readonly then: {
+                    readonly properties: {
+                        readonly type: {
+                            readonly not: {};
+                        };
+                    };
+                };
             }, {
                 readonly if: {
                     readonly properties: {

package/dist/agent-config/schema.js

@@ -35,6 +35,18 @@ export const NON_AUTHORABLE_TOOL_TYPES = {
     // #1244: injected wherever backbone.bash is advertised; an authored copy is dropped.
     "backbone.view_image": "it is added at run time wherever the sandboxed shell is",
 };
+/**
+ * The three tools `backbone.canvas` grants (#1698). Listing one is refused on the backend too
+ * (CanvasToolEntryValidator, 422); kept apart from NON_AUTHORABLE_TOOL_TYPES, which the backend's
+ * NonAuthorableToolsTest holds equal to the backend list.
+ */
+export const CANVAS_MEMBER_TYPES = {
+    "backbone.canvas_write": "it is granted by backbone.canvas",
+    "backbone.canvas_edit": "it is granted by backbone.canvas",
+    "backbone.canvas_read": "it is granted by backbone.canvas",
+};
+/** Types Canvas replaced: still accepted, with a warning (#1698). */
+export const RETIRED_TOOL_TYPES = ["backbone.show_table", "backbone.show_chart"];
 const BUILTIN_TYPES = [
     "file_search",
     "web_search",
@@ -44,6 +56,7 @@ const BUILTIN_TYPES = [
     "backbone.todo",
     "backbone.skill",
     "backbone.bash",
+    "backbone.canvas",
     "backbone.show_table",
     "backbone.show_chart",
     "function",
@@ -220,7 +233,14 @@ export const agentSchema = {
             required: ["type"],
             properties: { type: { const: "backbone.todo" }, requiresConfirmation: { type: "boolean" } },
         },
-        // #1419: no options; requiresConfirmation as todoTool, since an author may tighten a read tool.
+        // #1698: one grant for tables, charts and documents; no options. requiresConfirmation as todoTool.
+        canvasTool: {
+            type: "object",
+            additionalProperties: false,
+            required: ["type"],
+            properties: { type: { const: "backbone.canvas" }, requiresConfirmation: { type: "boolean" } },
+        },
+        // #1419, retired by Canvas (#1698) but still valid: no options; requiresConfirmation as todoTool.
         showTableTool: {
             type: "object",
             additionalProperties: false,
@@ -292,6 +312,7 @@ export const agentSchema = {
                 { if: typeIs("backbone.todo"), then: { $ref: "#/$defs/todoTool" } },
                 { if: typeIs("backbone.skill"), then: { $ref: "#/$defs/skillTool" } },
                 { if: typeIs("backbone.bash"), then: { $ref: "#/$defs/bashTool" } },
+                { if: typeIs("backbone.canvas"), then: { $ref: "#/$defs/canvasTool" } },
                 { if: typeIs("backbone.show_table"), then: { $ref: "#/$defs/showTableTool" } },
                 { if: typeIs("backbone.show_chart"), then: { $ref: "#/$defs/showChartTool" } },
                 { if: typeIs("function"), then: { $ref: "#/$defs/functionTool" } },
@@ -301,7 +322,15 @@ export const agentSchema = {
                     then: { properties: { type: { not: {} } } },
                 },
                 {
-                    if: { properties: { type: { enum: [...BUILTIN_TYPES, ...Object.keys(NON_AUTHORABLE_TOOL_TYPES)] } }, required: ["type"] },
+                    // validateAgentConfig reports these with the reason from CANVAS_MEMBER_TYPES.
+                    if: { required: ["type"], properties: { type: { enum: Object.keys(CANVAS_MEMBER_TYPES) } } },
+                    then: { properties: { type: { not: {} } } },
+                },
+                {
+                    if: {
+                        properties: { type: { enum: [...BUILTIN_TYPES, ...Object.keys(NON_AUTHORABLE_TOOL_TYPES), ...Object.keys(CANVAS_MEMBER_TYPES)] } },
+                        required: ["type"],
+                    },
                     else: { $ref: "#/$defs/namedTool" },
                 },
             ],

package/dist/agent-config/template.js

@@ -20,9 +20,10 @@ model: provider/model-name
 #   - provider/other-model
 instructions: |
   Describe the agent's job, its inputs, and what a good answer looks like.
-tools: []
-# Uncomment the tools this agent may use and delete the empty list above.
-# tools:
+# Canvas lets the agent show tables, charts and documents beside the conversation.
+tools:
+  - type: backbone.canvas
+# Uncomment more tools this agent may use.
 #   - type: file_search
 #     config:
 #       knowledgeBaseIds: [kb_id]
@@ -41,8 +42,6 @@ tools: []
 #     skills: [skill-name@latest]
 #   - type: backbone.bash
 #     approval: sandbox
-#   - type: backbone.show_table
-#   - type: backbone.show_chart
 #   - type: function
 #     name: lookup_order
 #     description: Look up an order by number

package/dist/agent-config/validate.d.ts

@@ -26,4 +26,9 @@ export interface AgentConfig {
  */
 export declare function normalizeForValidation(doc: unknown): unknown;
 export declare function validateAgentConfig(raw: unknown): ConfigIssue[];
+/**
+ * Warnings for a valid config: one per retired tool type it lists, however often (#1698). The
+ * backend still accepts these types, so they never fail validation.
+ */
+export declare function agentConfigWarnings(raw: unknown): string[];
 //# sourceMappingURL=validate.d.ts.map

package/dist/agent-config/validate.js

@@ -1,5 +1,5 @@
 import { Ajv2020 } from "ajv/dist/2020.js";
-import { agentSchema, NON_AUTHORABLE_TOOL_TYPES } from "./schema.js";
+import { agentSchema, CANVAS_MEMBER_TYPES, NON_AUTHORABLE_TOOL_TYPES, RETIRED_TOOL_TYPES } from "./schema.js";
 const ajv = new Ajv2020({ allErrors: true, strict: false });
 const validate = ajv.compile(agentSchema);
 /** Top-level keys whose explicit `null` the backend reads as absent. */
@@ -135,6 +135,9 @@ export function validateAgentConfig(raw) {
             if (typeof type === "string" && Object.hasOwn(NON_AUTHORABLE_TOOL_TYPES, type)) {
                 issues.push({ pointer: `/tools/${i}/type`, message: `type "${type}" cannot be authored: ${NON_AUTHORABLE_TOOL_TYPES[type]}` });
             }
+            if (typeof type === "string" && Object.hasOwn(CANVAS_MEMBER_TYPES, type)) {
+                issues.push({ pointer: `/tools/${i}/type`, message: `type "${type}" cannot be authored: ${CANVAS_MEMBER_TYPES[type]}` });
+            }
             // The backend refuses a second envelope (WebToolEntryValidator).
             if (type === "web_search") {
                 if (webSearchSeen)
@@ -163,4 +166,12 @@ export function validateAgentConfig(raw) {
     const unique = new Map(issues.map((i) => [JSON.stringify([i.pointer, i.message]), i]));
     return [...unique.values()];
 }
+/**
+ * Warnings for a valid config: one per retired tool type it lists, however often (#1698). The
+ * backend still accepts these types, so they never fail validation.
+ */
+export function agentConfigWarnings(raw) {
+    const tools = isPlainObject(raw) && Array.isArray(raw.tools) ? raw.tools : [];
+    return RETIRED_TOOL_TYPES.filter((type) => tools.some((t) => isPlainObject(t) && t.type === type)).map((type) => `${type} is no longer used; use backbone.canvas`);
+}
 //# sourceMappingURL=validate.js.map

package/dist/lib/connect-pause.d.ts

@@ -1,6 +1,6 @@
 /**
- * The connect pause, decoded one way for every client (#1086, spec §4, D4): an open
- * `backbone:connector_auth_request` (#807 R12) is a connector the run waits for the user to
+ * The connect pause, decoded one way for every client: an open
+ * `backbone:connector_auth_request` is a connector the run waits for the user to
  * connect, allow or reconnect in chat.2kw.ai.
  *
  * This file is canonical. `mcp/src/lib/connect-pause.ts` and
@@ -8,7 +8,7 @@
  * here, then run `npm run sync:connect-pause` in mcp/ and `npm run sync-connect-pause` in n8n/.
  * Its golden fixture, `cli/tests/fixtures/connect-pause-cases.json`, is copied the same way into
  * mcp/, n8n/ and surface/, and every client's decoder test runs every case of it. The input pause
- * (#1320, connectors spec §12) lives here too, with its own fixture `input-pause-cases.json`.
+ * lives here too, with its own fixture `input-pause-cases.json`.
  *
  * Plain TypeScript with no imports, no `process`, no Node types and no timers, so n8n's source
  * scanner and its empty `dependencies` accept the copy. The CLI and the MCP server keep their
@@ -16,7 +16,7 @@
  */
 /** Fallback chat.2kw.ai origin when the API host is not one we recognise. */
 export declare const DEFAULT_CHAT_URL = "https://chat.2kw.ai";
-/** Known API-host → chat web host mappings; a connect pause points the user there (#807 R11). */
+/** Known API-host → chat web host mappings; a connect pause points the user there. */
 export declare const CHAT_URL_BY_API_HOST: Readonly<Record<string, string>>;
 /**
  * The chat web host that belongs to an API base URL, where a member connects a connector
@@ -38,7 +38,7 @@ export interface PendingConnection {
     /** The MCP server's host: what the user is asked to connect to. */
     host: string;
     reason: ConnectReason;
-    /** The egress difference an allow is asked again for (#807 R9); absent otherwise, never empty. */
+    /** The egress difference an allow is asked again for; absent otherwise, never empty. */
     destinations?: string[];
 }
 /** Enough of a connection to name it in a sentence. */
@@ -47,7 +47,7 @@ export interface ConnectTarget {
     host: string;
     reason: string;
 }
-/** The synthetic tool a connector's connect pause is raised through (#806). */
+/** The synthetic tool a connector's connect pause is raised through. */
 export declare function connectToolName(serverLabel: string): string;
 /**
  * The connectors a response's `output` still waits on: every `in_progress` connect request whose
@@ -75,7 +75,7 @@ export declare function connectionsPhrase(connections: readonly ConnectTarget[])
  */
 export type InputMode = "form" | "url" | "mixed" | "unknown";
 /**
- * One open `backbone:input_request` (#1320, connectors spec §12): a connector's question that only
+ * One open `backbone:input_request`: a connector's question that only
  * the requester can answer, and only in chat. `id` is the item's `inreq_…` id. Its message, schema
  * and URL are never read: no assistant may see them (D7).
  */

package/dist/lib/connect-pause.js

@@ -1,6 +1,6 @@
 /**
- * The connect pause, decoded one way for every client (#1086, spec §4, D4): an open
- * `backbone:connector_auth_request` (#807 R12) is a connector the run waits for the user to
+ * The connect pause, decoded one way for every client: an open
+ * `backbone:connector_auth_request` is a connector the run waits for the user to
  * connect, allow or reconnect in chat.2kw.ai.
  *
  * This file is canonical. `mcp/src/lib/connect-pause.ts` and
@@ -8,7 +8,7 @@
  * here, then run `npm run sync:connect-pause` in mcp/ and `npm run sync-connect-pause` in n8n/.
  * Its golden fixture, `cli/tests/fixtures/connect-pause-cases.json`, is copied the same way into
  * mcp/, n8n/ and surface/, and every client's decoder test runs every case of it. The input pause
- * (#1320, connectors spec §12) lives here too, with its own fixture `input-pause-cases.json`.
+ * lives here too, with its own fixture `input-pause-cases.json`.
  *
  * Plain TypeScript with no imports, no `process`, no Node types and no timers, so n8n's source
  * scanner and its empty `dependencies` accept the copy. The CLI and the MCP server keep their
@@ -16,7 +16,7 @@
  */
 /** Fallback chat.2kw.ai origin when the API host is not one we recognise. */
 export const DEFAULT_CHAT_URL = "https://chat.2kw.ai";
-/** Known API-host → chat web host mappings; a connect pause points the user there (#807 R11). */
+/** Known API-host → chat web host mappings; a connect pause points the user there. */
 export const CHAT_URL_BY_API_HOST = {
     "api.2kw.ai": "https://chat.2kw.ai",
     "api-dev.2kw.ai": "https://chat-dev.2kw.ai",
@@ -48,7 +48,7 @@ function itemsOf(output) {
 function text(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
-/** The synthetic tool a connector's connect pause is raised through (#806). */
+/** The synthetic tool a connector's connect pause is raised through. */
 export function connectToolName(serverLabel) {
     return `mcp__${serverLabel}__connect`;
 }

package/package.json

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