@2kw/ai 7.1.0-dev.1 → 7.1.0-dev.3

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

@@ -11,8 +11,8 @@ export declare function redactSecrets(tools: Record<string, unknown>[] | undefin
     envNames: string[];
 };
 /**
- * Tool entries the backend stores but never runs (planner/runtime-injected or executor-less,
- * e.g. a console-stored `web_search`). agent.yaml cannot author them, so export drops them.
+ * Tool entries the backend stores but never runs as authored (planner- or runtime-injected,
+ * e.g. `backbone.tool_search`). agent.yaml cannot author them, so export drops them.
  */
 export declare function dropInertTools(tools: Record<string, unknown>[] | undefined): {
     tools: Record<string, unknown>[] | undefined;

package/dist/agent-config/export.js

@@ -43,8 +43,8 @@ export function redactSecrets(tools) {
     return { tools: redacted, envNames: [...owners.keys()] };
 }
 /**
- * Tool entries the backend stores but never runs (planner/runtime-injected or executor-less,
- * e.g. a console-stored `web_search`). agent.yaml cannot author them, so export drops them.
+ * Tool entries the backend stores but never runs as authored (planner- or runtime-injected,
+ * e.g. `backbone.tool_search`). agent.yaml cannot author them, so export drops them.
  */
 export function dropInertTools(tools) {
     if (!tools)

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

@@ -138,6 +138,77 @@ export declare const agentSchema: {
                 };
             };
         };
+        readonly webSearchTool: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["type"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "web_search";
+                };
+                readonly config: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly source: {
+                            readonly enum: readonly ["builtin", "external", "native"];
+                        };
+                        readonly searchProviderId: {
+                            readonly type: readonly ["string", "null"];
+                        };
+                        readonly fallback: {
+                            readonly enum: readonly ["builtin", "external"];
+                        };
+                        readonly allowedDomains: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                                readonly pattern: "^(?=.{1,253}$)([\\p{L}\\p{N}](?:[\\p{L}\\p{N}-]{0,61}[\\p{L}\\p{N}])?\\.)+\\p{L}(?:[\\p{L}\\p{N}-]{0,61}[\\p{L}\\p{N}])?$";
+                            };
+                            readonly maxItems: 10;
+                        };
+                    };
+                    readonly if: {
+                        readonly anyOf: readonly [{
+                            readonly required: readonly ["source"];
+                            readonly properties: {
+                                readonly source: {
+                                    readonly const: "external";
+                                };
+                            };
+                        }, {
+                            readonly required: readonly ["source", "fallback"];
+                            readonly properties: {
+                                readonly source: {
+                                    readonly const: "native";
+                                };
+                                readonly fallback: {
+                                    readonly const: "external";
+                                };
+                            };
+                        }];
+                    };
+                    readonly then: {
+                        readonly required: readonly ["searchProviderId"];
+                        readonly properties: {
+                            readonly searchProviderId: {
+                                readonly type: "string";
+                                readonly pattern: "\\S";
+                            };
+                        };
+                    };
+                    readonly else: {
+                        readonly properties: {
+                            readonly searchProviderId: {
+                                readonly type: "null";
+                            };
+                        };
+                    };
+                };
+                readonly requiresConfirmation: {
+                    readonly type: "boolean";
+                };
+            };
+        };
         readonly extractionTool: {
             readonly type: "object";
             readonly additionalProperties: false;
@@ -306,6 +377,18 @@ export declare const agentSchema: {
                 readonly then: {
                     readonly $ref: "#/$defs/fileSearchTool";
                 };
+            }, {
+                readonly if: {
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                readonly then: {
+                    readonly $ref: "#/$defs/webSearchTool";
+                };
             }, {
                 readonly if: {
                     required: string[];

package/dist/agent-config/schema.js

@@ -16,6 +16,9 @@ const MODEL_REF = {
     maxLength: 255,
     pattern: "^(?:[^/#]+|[A-Za-z0-9-]+/[^#]+)$",
 };
+// A plain hostname (no scheme, path, port or wildcard): dot-separated labels of letters, digits and
+// inner hyphens, Unicode or ASCII. Mirrors WebToolEntryValidator.HOST; needs a Unicode-aware regex engine.
+const HOSTNAME = "^(?=.{1,253}$)([\\p{L}\\p{N}](?:[\\p{L}\\p{N}-]{0,61}[\\p{L}\\p{N}])?\\.)+\\p{L}(?:[\\p{L}\\p{N}-]{0,61}[\\p{L}\\p{N}])?$";
 const oneOfLowercase = (...values) => ({ type: "string", enum: values });
 /** Types the backend injects or cannot execute; authoring them has no effect or breaks the run. */
 export const NON_AUTHORABLE_TOOL_TYPES = {
@@ -27,10 +30,10 @@ export const NON_AUTHORABLE_TOOL_TYPES = {
     "backbone.deliver": "it is added at run time while sandbox outputs are held",
     // #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",
-    web_search: "it has no executor and is skipped",
 };
 const BUILTIN_TYPES = [
     "file_search",
+    "web_search",
     "backbone.extraction",
     "backbone.document_convert",
     "backbone.todo",
@@ -118,6 +121,35 @@ export const agentSchema = {
                 },
             },
         },
+        // A missing config, `config: {}` or a missing source runs the built-in search. Mirrors
+        // WebToolEntryValidator; `config` stays open so later sources' fields do not break older CLIs.
+        webSearchTool: {
+            type: "object",
+            additionalProperties: false,
+            required: ["type"],
+            properties: {
+                type: { const: "web_search" },
+                config: {
+                    type: "object",
+                    properties: {
+                        source: { enum: ["builtin", "external", "native"] },
+                        searchProviderId: { type: ["string", "null"] },
+                        fallback: { enum: ["builtin", "external"] },
+                        allowedDomains: { type: "array", items: { type: "string", pattern: HOSTNAME }, maxItems: 10 },
+                    },
+                    // A provider id is required exactly when an external provider serves the search.
+                    if: {
+                        anyOf: [
+                            { required: ["source"], properties: { source: { const: "external" } } },
+                            { required: ["source", "fallback"], properties: { source: { const: "native" }, fallback: { const: "external" } } },
+                        ],
+                    },
+                    then: { required: ["searchProviderId"], properties: { searchProviderId: { type: "string", pattern: "\\S" } } },
+                    else: { properties: { searchProviderId: { type: "null" } } },
+                },
+                requiresConfirmation: { type: "boolean" },
+            },
+        },
         extractionTool: {
             type: "object",
             additionalProperties: false,
@@ -204,6 +236,7 @@ export const agentSchema = {
             type: "object",
             allOf: [
                 { if: typeIs("file_search"), then: { $ref: "#/$defs/fileSearchTool" } },
+                { if: typeIs("web_search"), then: { $ref: "#/$defs/webSearchTool" } },
                 { if: typeIs("backbone.extraction"), then: { $ref: "#/$defs/extractionTool" } },
                 { if: typeIs("backbone.document_convert"), then: { $ref: "#/$defs/documentConvertTool" } },
                 { if: typeIs("backbone.todo"), then: { $ref: "#/$defs/todoTool" } },

package/dist/agent-config/template.js

@@ -26,6 +26,9 @@ tools: []
 #   - type: file_search
 #     config:
 #       knowledgeBaseIds: [kb_id]
+#   - type: web_search
+#     config:
+#       allowedDomains: [example.com]
 #   - type: backbone.extraction
 #     config:
 #       schemaIds: [schema_id]

package/dist/agent-config/validate.js

@@ -6,6 +6,8 @@ const validate = ajv.compile(agentSchema);
 const NULLABLE_KEYS = ["description", "models", "instructions", "tools", "hitlPolicy", "options", "skills"];
 /** Tool-rule values the backend matches case-insensitively; the actions (approve, auto, deny) are exact. */
 const TOOL_RULE_CLASSES = new Set(["read", "write", "destructive"]);
+/** web_search config keys whose explicit `null` the backend reads as absent. */
+const WEB_SEARCH_NULLABLE_KEYS = ["source", "fallback", "searchProviderId", "allowedDomains"];
 const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /**
  * A deep copy of `doc` in the form the backend actually checks: explicit nulls it treats as absent
@@ -31,6 +33,8 @@ export function normalizeForValidation(doc) {
         for (const tool of copy.tools) {
             if (isPlainObject(tool) && tool.annotations === null)
                 delete tool.annotations;
+            if (isPlainObject(tool) && tool.type === "web_search")
+                normalizeWebSearch(tool);
         }
     }
     const policy = copy.hitlPolicy;
@@ -50,6 +54,21 @@ export function normalizeForValidation(doc) {
     }
     return copy;
 }
+/** WebToolEntryValidator reads a null config and null config fields as absent, and trims each domain. */
+function normalizeWebSearch(tool) {
+    if (tool.config === null)
+        delete tool.config;
+    const config = tool.config;
+    if (!isPlainObject(config))
+        return;
+    for (const key of WEB_SEARCH_NULLABLE_KEYS) {
+        if (config[key] === null)
+            delete config[key];
+    }
+    if (Array.isArray(config.allowedDomains)) {
+        config.allowedDomains = config.allowedDomains.map((d) => (typeof d === "string" ? d.trim() : d));
+    }
+}
 function describe(e) {
     // if/then wrappers restate the real error one level up; drop them. `not` only marks
     // non-authorable tool types, which validateAgentConfig reports with the reason.
@@ -75,6 +94,13 @@ function describe(e) {
     if (e.keyword === "const") {
         return { pointer, message: `must be ${JSON.stringify(params.allowedValue)}` };
     }
+    // The `else` branch of webSearchTool's provider rule: an id where no external provider serves the search.
+    if (e.keyword === "type" && params.type === "null" && pointer.endsWith("/config/searchProviderId")) {
+        return {
+            pointer,
+            message: "only allowed when an external provider serves the search (source external, or native with fallback external)",
+        };
+    }
     return { pointer, message: e.message ?? e.keyword };
 }
 export function validateAgentConfig(raw) {
@@ -98,11 +124,18 @@ export function validateAgentConfig(raw) {
         }
     }
     if (Array.isArray(record.tools)) {
+        let webSearchSeen = false;
         record.tools.forEach((tool, i) => {
             const type = tool?.type;
             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]}` });
             }
+            // The backend refuses a second envelope (WebToolEntryValidator).
+            if (type === "web_search") {
+                if (webSearchSeen)
+                    issues.push({ pointer: `/tools/${i}/type`, message: "an agent may carry only one web_search tool" });
+                webSearchSeen = true;
+            }
         });
     }
     if (Array.isArray(record.skills)) {

package/package.json

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