@2kw/ai 6.2.0-dev.14 → 6.2.0-dev.25

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

@@ -0,0 +1,420 @@
+/**
+ * JSON Schema for `agent.yaml` (spec §5.2). Hand-written because `tools`, `skills`,
+ * `hitlPolicy` and `options` are untyped JsonNode in the OpenAPI spec (follow-up #670).
+ * Mirrored to public-docs/public/schemas/agent.v1.json by `npm run sync:agent-schema`.
+ * Kept as a TS constant: package.json `files` publishes only dist JS/d.ts.
+ */
+export declare const AGENT_SCHEMA_ID = "https://docs.2kw.ai/schemas/agent.v1.json";
+/** Types the backend injects or cannot execute; authoring them has no effect or breaks the run. */
+export declare const NON_AUTHORABLE_TOOL_TYPES: Record<string, 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";
+    readonly title: "2kw agent";
+    readonly description: "Agent configuration applied with `2kw agents apply -f <file>`.";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["name"];
+    readonly anyOf: readonly [{
+        readonly required: readonly ["model"];
+    }, {
+        readonly required: readonly ["models"];
+    }];
+    readonly properties: {
+        readonly $schema: {
+            readonly type: "string";
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 255;
+            readonly pattern: "^[^#@]+$";
+            readonly description: "Unique per organization; apply looks the agent up by this exact name. '#' and '@' are reserved.";
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly maxLength: 4000;
+        };
+        readonly model: {
+            readonly description: "provider/model, or a bare model name for the default provider. '#' is reserved. With `models`, must equal its first entry.";
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 255;
+            readonly pattern: "^(?:[^/#]+|[A-Za-z0-9-]+/[^#]+)$";
+        };
+        readonly models: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly maxItems: 10;
+            readonly uniqueItems: true;
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 255;
+                readonly pattern: "^(?:[^/#]+|[A-Za-z0-9-]+/[^#]+)$";
+            };
+            readonly description: "Ordered model list (#591): the first entry is the default, the others can be picked per request with <agent>#<model>. 1-10 unique entries.";
+        };
+        readonly instructions: {
+            readonly type: "string";
+            readonly maxLength: 20000;
+        };
+        readonly tools: {
+            readonly type: "array";
+            readonly items: {
+                readonly $ref: "#/$defs/tool";
+            };
+        };
+        readonly hitlPolicy: {
+            readonly $ref: "#/$defs/hitlPolicy";
+        };
+        readonly options: {
+            readonly type: "object";
+            readonly description: "Stored with the version; not read by the run engine.";
+        };
+        readonly skills: {
+            readonly type: "array";
+            readonly maxItems: 20;
+            readonly description: "Skill bindings (#639): each names an org skill and a label or version.";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["name"];
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                        readonly pattern: "^[a-z0-9]+(-[a-z0-9]+)*$";
+                        readonly maxLength: 100;
+                    };
+                    readonly ref: {
+                        readonly type: "string";
+                        readonly pattern: "\\S";
+                        readonly description: "Label name or version number; default latest.";
+                    };
+                };
+            };
+        };
+    };
+    readonly $defs: {
+        readonly annotations: {
+            readonly type: "object";
+            readonly required: readonly ["readOnlyHint", "destructiveHint"];
+            readonly properties: {
+                readonly readOnlyHint: {
+                    readonly type: "boolean";
+                };
+                readonly destructiveHint: {
+                    readonly type: "boolean";
+                };
+            };
+        };
+        readonly fileSearchTool: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["type", "config"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "file_search";
+                };
+                readonly requiresConfirmation: {
+                    readonly type: "boolean";
+                };
+                readonly config: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["knowledgeBaseIds"];
+                    readonly properties: {
+                        readonly knowledgeBaseIds: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly extractionTool: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["type", "config"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "backbone.extraction";
+                };
+                readonly requiresConfirmation: {
+                    readonly type: "boolean";
+                };
+                readonly config: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["schemaIds"];
+                    readonly properties: {
+                        readonly schemaIds: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                        };
+                        readonly model: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                    };
+                };
+            };
+        };
+        readonly documentConvertTool: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["type"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "backbone.document_convert";
+                };
+                readonly requiresConfirmation: {
+                    readonly type: "boolean";
+                };
+                readonly config: {
+                    readonly type: "object";
+                };
+            };
+        };
+        readonly todoTool: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["type"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "backbone.todo";
+                };
+                readonly requiresConfirmation: {
+                    readonly type: "boolean";
+                };
+            };
+        };
+        readonly skillTool: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["type", "skills"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "backbone.skill";
+                };
+                readonly requiresConfirmation: {
+                    readonly type: "boolean";
+                };
+                readonly skills: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly maxItems: 20;
+                    readonly uniqueItems: true;
+                    readonly items: {
+                        readonly type: "string";
+                        readonly pattern: "^[a-z0-9]+(-[a-z0-9]+)*(@[A-Za-z0-9._-]+)?$";
+                    };
+                };
+            };
+        };
+        readonly functionTool: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["type", "name", "endpoint"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "function";
+                };
+                readonly name: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly description: {
+                    readonly type: "string";
+                };
+                readonly parameters: {
+                    readonly type: "object";
+                };
+                readonly endpoint: {
+                    readonly type: "string";
+                    readonly pattern: "^https?://";
+                };
+                readonly secret: {
+                    readonly type: "string";
+                };
+                readonly annotations: {
+                    readonly $ref: "#/$defs/annotations";
+                };
+            };
+        };
+        readonly namedTool: {
+            readonly type: "object";
+            readonly required: readonly ["name"];
+            readonly properties: {
+                readonly type: {
+                    readonly type: "string";
+                };
+                readonly name: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly description: {
+                    readonly type: "string";
+                };
+                readonly parameters: {
+                    readonly type: "object";
+                };
+                readonly annotations: {
+                    readonly $ref: "#/$defs/annotations";
+                };
+            };
+        };
+        readonly tool: {
+            readonly type: "object";
+            readonly allOf: readonly [{
+                readonly if: {
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                readonly then: {
+                    readonly $ref: "#/$defs/fileSearchTool";
+                };
+            }, {
+                readonly if: {
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                readonly then: {
+                    readonly $ref: "#/$defs/extractionTool";
+                };
+            }, {
+                readonly if: {
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                readonly then: {
+                    readonly $ref: "#/$defs/documentConvertTool";
+                };
+            }, {
+                readonly if: {
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                readonly then: {
+                    readonly $ref: "#/$defs/todoTool";
+                };
+            }, {
+                readonly if: {
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                readonly then: {
+                    readonly $ref: "#/$defs/skillTool";
+                };
+            }, {
+                readonly if: {
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                readonly then: {
+                    readonly $ref: "#/$defs/functionTool";
+                };
+            }, {
+                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: {
+                        readonly type: {
+                            readonly enum: readonly string[];
+                        };
+                    };
+                    readonly required: readonly ["type"];
+                };
+                readonly else: {
+                    readonly $ref: "#/$defs/namedTool";
+                };
+            }];
+        };
+        readonly hitlPolicy: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly version: {
+                    readonly const: 1;
+                };
+                readonly default: {
+                    type: string;
+                    enum: string[];
+                };
+                readonly classes: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly read: {
+                            type: string;
+                            enum: string[];
+                        };
+                        readonly write: {
+                            type: string;
+                            enum: string[];
+                        };
+                        readonly destructive: {
+                            type: string;
+                            enum: string[];
+                        };
+                    };
+                };
+                readonly tools: {
+                    readonly type: "object";
+                    readonly propertyNames: {
+                        readonly pattern: "\\S";
+                    };
+                    readonly additionalProperties: {
+                        readonly type: "string";
+                        readonly enum: readonly ["read", "write", "destructive", "approve", "auto", "deny"];
+                    };
+                };
+            };
+        };
+    };
+};
+//# sourceMappingURL=schema.d.ts.map

package/dist/agent-config/schema.js

@@ -0,0 +1,222 @@
+/**
+ * JSON Schema for `agent.yaml` (spec §5.2). Hand-written because `tools`, `skills`,
+ * `hitlPolicy` and `options` are untyped JsonNode in the OpenAPI spec (follow-up #670).
+ * Mirrored to public-docs/public/schemas/agent.v1.json by `npm run sync:agent-schema`.
+ * Kept as a TS constant: package.json `files` publishes only dist JS/d.ts.
+ */
+export const AGENT_SCHEMA_ID = "https://docs.2kw.ai/schemas/agent.v1.json";
+const SKILL_NAME = "^[a-z0-9]+(-[a-z0-9]+)*$";
+const SKILL_REF = "^[a-z0-9]+(-[a-z0-9]+)*(@[A-Za-z0-9._-]+)?$";
+const MODEL_REF = {
+    type: "string",
+    minLength: 1,
+    maxLength: 255,
+    pattern: "^(?:[^/#]+|[A-Za-z0-9-]+/[^#]+)$",
+};
+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 = {
+    "backbone.tool_search": "the planner adds it automatically",
+    "backbone.skill_read": "it is added at run time when skills are pinned",
+    web_search: "it has no executor and is skipped",
+};
+const BUILTIN_TYPES = [
+    "file_search",
+    "backbone.extraction",
+    "backbone.document_convert",
+    "backbone.todo",
+    "backbone.skill",
+    "function",
+];
+const typeIs = (t) => ({ required: ["type"], properties: { type: { const: t } } });
+export const agentSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: AGENT_SCHEMA_ID,
+    title: "2kw agent",
+    description: "Agent configuration applied with `2kw agents apply -f <file>`.",
+    type: "object",
+    additionalProperties: false,
+    required: ["name"],
+    // A model is required, as `model` (one) or `models` (an ordered list); both may be given when model = models[0].
+    anyOf: [{ required: ["model"] }, { required: ["models"] }],
+    properties: {
+        $schema: { type: "string" },
+        name: {
+            type: "string",
+            minLength: 1,
+            maxLength: 255,
+            pattern: "^[^#@]+$",
+            description: "Unique per organization; apply looks the agent up by this exact name. '#' and '@' are reserved.",
+        },
+        description: { type: "string", maxLength: 4000 },
+        model: {
+            ...MODEL_REF,
+            description: "provider/model, or a bare model name for the default provider. '#' is reserved. With `models`, must equal its first entry.",
+        },
+        models: {
+            type: "array",
+            minItems: 1,
+            maxItems: 10,
+            uniqueItems: true,
+            items: MODEL_REF,
+            description: "Ordered model list (#591): the first entry is the default, the others can be picked per request with <agent>#<model>. 1-10 unique entries.",
+        },
+        instructions: { type: "string", maxLength: 20000 },
+        tools: { type: "array", items: { $ref: "#/$defs/tool" } },
+        hitlPolicy: { $ref: "#/$defs/hitlPolicy" },
+        options: { type: "object", description: "Stored with the version; not read by the run engine." },
+        skills: {
+            type: "array",
+            maxItems: 20,
+            description: "Skill bindings (#639): each names an org skill and a label or version.",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["name"],
+                properties: {
+                    name: { type: "string", pattern: SKILL_NAME, maxLength: 100 },
+                    ref: { type: "string", pattern: "\\S", description: "Label name or version number; default latest." },
+                },
+            },
+        },
+    },
+    $defs: {
+        annotations: {
+            type: "object",
+            required: ["readOnlyHint", "destructiveHint"],
+            properties: { readOnlyHint: { type: "boolean" }, destructiveHint: { type: "boolean" } },
+        },
+        fileSearchTool: {
+            type: "object",
+            additionalProperties: false,
+            required: ["type", "config"],
+            properties: {
+                type: { const: "file_search" },
+                requiresConfirmation: { type: "boolean" },
+                config: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["knowledgeBaseIds"],
+                    // An empty list is a tool the console seeded but nobody configured; the backend stores it and does not advertise it.
+                    properties: { knowledgeBaseIds: { type: "array", items: { type: "string", minLength: 1 } } },
+                },
+            },
+        },
+        extractionTool: {
+            type: "object",
+            additionalProperties: false,
+            required: ["type", "config"],
+            properties: {
+                type: { const: "backbone.extraction" },
+                requiresConfirmation: { type: "boolean" },
+                config: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["schemaIds"],
+                    properties: {
+                        schemaIds: { type: "array", items: { type: "string", minLength: 1 } },
+                        model: { type: "string", minLength: 1 },
+                    },
+                },
+            },
+        },
+        documentConvertTool: {
+            type: "object",
+            additionalProperties: false,
+            required: ["type"],
+            properties: {
+                type: { const: "backbone.document_convert" },
+                requiresConfirmation: { type: "boolean" },
+                config: { type: "object" },
+            },
+        },
+        todoTool: {
+            type: "object",
+            additionalProperties: false,
+            required: ["type"],
+            properties: { type: { const: "backbone.todo" }, requiresConfirmation: { type: "boolean" } },
+        },
+        skillTool: {
+            type: "object",
+            additionalProperties: false,
+            required: ["type", "skills"],
+            properties: {
+                type: { const: "backbone.skill" },
+                requiresConfirmation: { type: "boolean" },
+                skills: { type: "array", minItems: 1, maxItems: 20, uniqueItems: true, items: { type: "string", pattern: SKILL_REF } },
+            },
+        },
+        functionTool: {
+            type: "object",
+            additionalProperties: false,
+            required: ["type", "name", "endpoint"],
+            properties: {
+                type: { const: "function" },
+                name: { type: "string", minLength: 1 },
+                description: { type: "string" },
+                parameters: { type: "object" },
+                endpoint: { type: "string", pattern: "^https?://" },
+                secret: { type: "string" },
+                annotations: { $ref: "#/$defs/annotations" },
+            },
+        },
+        namedTool: {
+            type: "object",
+            required: ["name"],
+            properties: {
+                type: { type: "string" },
+                name: { type: "string", minLength: 1 },
+                description: { type: "string" },
+                parameters: { type: "object" },
+                annotations: { $ref: "#/$defs/annotations" },
+            },
+        },
+        tool: {
+            type: "object",
+            allOf: [
+                { if: typeIs("file_search"), then: { $ref: "#/$defs/fileSearchTool" } },
+                { 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" } },
+                { if: typeIs("backbone.skill"), then: { $ref: "#/$defs/skillTool" } },
+                { if: typeIs("function"), then: { $ref: "#/$defs/functionTool" } },
+                {
+                    // The validator reports these with the reason from NON_AUTHORABLE_TOOL_TYPES; this keeps the published schema honest.
+                    if: { required: ["type"], properties: { type: { enum: Object.keys(NON_AUTHORABLE_TOOL_TYPES) } } },
+                    then: { properties: { type: { not: {} } } },
+                },
+                {
+                    if: { properties: { type: { enum: [...BUILTIN_TYPES, ...Object.keys(NON_AUTHORABLE_TOOL_TYPES)] } }, required: ["type"] },
+                    else: { $ref: "#/$defs/namedTool" },
+                },
+            ],
+        },
+        hitlPolicy: {
+            // The backend reads a missing version as 1. It matches `default`, the `classes` keys and their
+            // values case-insensitively; validateAgentConfig lowercases those before checking this schema.
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                version: { const: 1 },
+                default: oneOfLowercase("allow", "approve", "block", "deny"),
+                classes: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        read: oneOfLowercase("allow", "auto", "approve", "block", "deny"),
+                        write: oneOfLowercase("auto", "approve", "block", "deny"),
+                        destructive: oneOfLowercase("block", "deny"),
+                    },
+                },
+                tools: {
+                    // Value is a policy class or an action. Actions (approve, auto, deny) are exact lowercase;
+                    // classes (read, write, destructive) are case-insensitive and lowercased by the validator.
+                    type: "object",
+                    propertyNames: { pattern: "\\S" },
+                    additionalProperties: { type: "string", enum: ["read", "write", "destructive", "approve", "auto", "deny"] },
+                },
+            },
+        },
+    },
+};
+//# sourceMappingURL=schema.js.map

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

@@ -0,0 +1,6 @@
+/**
+ * Commented starter file. Prose comments start with "# " + an uppercase letter; YAML
+ * examples start with "# " + a lowercase key, a space or "-" (the template test relies on it).
+ */
+export declare function agentTemplate(name: string): string;
+//# sourceMappingURL=template.d.ts.map