librebot-tools 0.4.5 → 0.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -64,7 +64,18 @@ Rules:
64
64
  bindings belong to instances. Connectors retain unique labels and platform
65
65
  identities. Knowledge source IDs remain portable references.
66
66
  - `modelRoles[]` accepts optional `requirements: { tools?, vision?,
67
- reasoning?, minContextWindow? }`, validated and preserved end to end.
67
+ - reasoning?, minContextWindow? }`, validated and preserved end to end.
68
+ - Role ids are `default` (required), the reserved OMP built-ins `smol`,
69
+ - `slow`, `plan`, or custom ids such as `frontend_dev_model`: start with a
70
+ - letter or digit, then letters/digits with `-`/`_` only, max 64 chars.
71
+ - Custom ids must avoid all reserved ids: the four built-ins plus the OMP
72
+ - built-in names `vision`, `commit`, `tiny`, `memory`, `task`, `advisor`,
73
+ - `widget`, `image`, `web`, `speech`, `dictation`, `judge` and the unsafe
74
+ - object keys `__proto__`, `constructor`, `prototype` (no dots).
75
+ - Up to 8 roles may be declared. A trigger `deciderRole` may name any
76
+ - declared role. Custom roles never inherit workspace model defaults: every
77
+ - custom role needs an explicit instance model binding, while defaults cover
78
+ - the built-ins only.
68
79
  - `knowledge/README.md` is the index, not an entry. Every other file under
69
80
  `knowledge/` is one knowledge asset: UTF-8 text inlines as `content`;
70
81
  anything else is returned as an `assets[]` entry
@@ -124,9 +135,13 @@ import {
124
135
  `.warnings[]`) instead. Same contract for `validateFiles` / `parseBotFiles`.
125
136
  - `librebot-tools/contract` exports the portable vocabulary with no Node
126
137
  dependencies, so browsers can import it too: `FORMAT_VERSION`,
127
- `MODEL_ROLES`, `REPO_CAPABILITIES`, `GITREPO_TRIGGER_EVENT_TYPES`,
138
+ `MODEL_ROLES` (reserved OMP built-ins `default`, `smol`, `slow`, `plan`),
139
+ `BUILT_IN_MODEL_ROLES` (alias), `MAX_MODEL_ROLES` (8),
140
+ `CUSTOM_MODEL_ROLE_ID_RE`, `isBuiltInModelRole`, `isCustomModelRoleId`,
141
+ `isModelRoleId`, plus `REPO_CAPABILITIES`, `GITREPO_TRIGGER_EVENT_TYPES`,
128
142
  `WHATSAPP_CAPABILITIES`, `WHATSAPP_TRIGGER_EVENT_TYPES` (frozen arrays), and
129
- the derived `ModelRoleId`, `RepoCapability`, `WhatsAppCapability`,
143
+ the derived `ModelRoleId` (generic string: built-in or custom),
144
+ `BuiltInModelRoleId`, `RepoCapability`, `WhatsAppCapability`,
130
145
  `GitrepoTriggerEventType`, and `WhatsAppTriggerEventType` types. The root
131
146
  entry re-exports the same values.
132
147
  - No author-configured shell commands are executed. Standard skill
@@ -222,15 +237,13 @@ through `npx --package=... librebot`.
222
237
 
223
238
  ## Platform integration
224
239
 
225
- - The platform consumes `services/shared/librebot-tools-0.4.4.tgz`, packed from
226
- this source checkout. This is not a published npm release or a claim that an
227
- upstream commit contains these changes.
228
- Platform CI and images do not need this separate Git checkout. Refresh with
229
- `npm pack --pack-destination "$HOME/librebot.work/services/shared"`,
230
- then update the platform dependency and lockfile using
231
- `npm install --workspace services.shared ./services/shared/librebot-tools-0.4.4.tgz`.
232
- Authoring environments must receive this exact local bundle rather than
233
- substituting an older public CLI pin, `main`, or `latest`.
240
+ - The platform consumes an exact public source archive of this checkout,
241
+ - `https://codeload.github.com/librebot-work/tools/tar.gz/<40-char-SHA>`,
242
+ - never a local path or a `git+https` spec (minimal validator images lack
243
+ - git). Refresh the pin to the commit that carries the needed contract and
244
+ - update the platform dependency and lockfile against that archive URL.
245
+ - Authoring environments must receive this exact archive rather than
246
+ - substituting an older public CLI pin, `main`, or `latest`.
234
247
  - Portable `actions` also accept `kind: whatsapp` with only `read_messages`,
235
248
  `send_text`, `set_reaction`, and `remove_reaction`. Repository capabilities
236
249
  remain exclusive to `gitrepo`. Exact sender-phone bindings, independent read
@@ -239,8 +252,11 @@ through `npx --package=... librebot`.
239
252
  contract; 0.4.2 replaces the scaffold README with a user-manual skeleton;
240
253
  0.4.3 adds the `publish_attachments` repository capability; 0.4.4 adds the
241
254
  `merge_change_request` repository capability and the
242
- `change_request.checks_updated` trigger event.
243
- All are locally bundled, not published to npm.
255
+ `change_request.checks_updated` trigger event; 0.4.6 adds custom model role
256
+ ids (up to 8 roles including `default`; workspace defaults stay built-in-only
257
+ while custom roles require explicit instance bindings).
258
+ Custom-role sources require tooling at 0.4.6 or newer; 0.4.5 accepts only
259
+ `default`, `smol`, `slow`, `plan`.
244
260
  - Portable WhatsApp triggers use `kind: whatsapp`, semantic `message.created`
245
261
  and/or `reaction.changed`, and the existing keyed decider definition fields.
246
262
  Event namespaces are checked against the selected trigger kind.
@@ -272,7 +288,9 @@ export round-trips, and skill-lock reproducibility.
272
288
 
273
289
  750 KB draft cap (UTF-8 bytes); knowledge <= 100 entries (files + `knowledgeSources`
274
290
  combined); skills <= 100; connectors <= 50; triggers <= 20; workspace
275
- mounts <= 10; model roles 1-4 including `default`; SKILL.md <= 50,000 bytes
291
+ mounts <= 10; model roles 1-8 including `default` (reserved built-ins
292
+ `default`, `smol`, `slow`, `plan` plus custom ids such as `frontend_dev_model`);
293
+ SKILL.md <= 50,000 bytes
276
294
  and non-empty; text knowledge <= 100,000 chars inline (empty files inline
277
295
  as empty content, matching platform acceptance); knowledge assets
278
296
  <= 10 MiB; skill supporting files <= 1 MiB each.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "librebot-tools",
3
- "version": "0.4.5",
3
+ "version": "0.4.6",
4
4
  "description": "Public source-format tooling for Librebot bots: parse, validate, preview, scaffold, and skill-lock resolution.",
5
5
  "type": "module",
6
6
  "scripts": {
@@ -20,13 +20,13 @@
20
20
  "modelRoles": {
21
21
  "type": "array",
22
22
  "minItems": 1,
23
- "maxItems": 4,
23
+ "maxItems": 8,
24
24
  "items": {
25
25
  "type": "object",
26
26
  "additionalProperties": false,
27
27
  "required": ["role", "label"],
28
28
  "properties": {
29
- "role": { "enum": ["default", "smol", "slow", "plan"] },
29
+ "role": { "anyOf": [{ "enum": ["default", "smol", "slow", "plan"] }, { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$", "not": { "enum": ["vision", "commit", "tiny", "memory", "task", "advisor", "widget", "image", "web", "speech", "dictation", "judge", "__proto__", "constructor", "prototype"] } }], "description": "Built-in roles default, smol, slow, plan or a custom id (letters/digits with -/_, max 64 chars). Reserved OMP built-in names and object keys are rejected; a default role is always required." },
30
30
  "label": { "type": "string", "minLength": 1, "maxLength": 100 },
31
31
  "requirements": {
32
32
  "type": "object",
@@ -96,7 +96,7 @@
96
96
  }
97
97
  }
98
98
  },
99
- "deciderRole": { "enum": ["default", "smol", "slow", "plan"] },
99
+ "deciderRole": { "anyOf": [{ "enum": ["default", "smol", "slow", "plan"] }, { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$", "not": { "enum": ["vision", "commit", "tiny", "memory", "task", "advisor", "widget", "image", "web", "speech", "dictation", "judge", "__proto__", "constructor", "prototype"] } }], "description": "Any role declared in modelRoles: a built-in or a custom role id. Custom roles need an explicit instance binding." },
100
100
  "deciderInstructions": { "type": "string", "minLength": 1, "maxLength": 20000 },
101
101
  "enabledByDefault": { "type": "boolean" }
102
102
  },
package/src/contract.d.ts CHANGED
@@ -1,5 +1,13 @@
1
1
  export const FORMAT_VERSION: 1;
2
2
  export const MODEL_ROLES: readonly ["default", "smol", "slow", "plan"];
3
+ export const BUILT_IN_MODEL_ROLES: readonly ["default", "smol", "slow", "plan"];
4
+ export const MAX_MODEL_ROLES: 8;
5
+ export const RESERVED_MODEL_ROLE_IDS: readonly string[];
6
+ export const CUSTOM_MODEL_ROLE_ID_RE: RegExp;
7
+ export function isReservedModelRoleId(role: string): boolean;
8
+ export function isBuiltInModelRole(role: string): role is BuiltInModelRoleId;
9
+ export function isCustomModelRoleId(role: string): boolean;
10
+ export function isModelRoleId(role: string): role is ModelRoleId;
3
11
  export const REPO_CAPABILITIES: readonly [
4
12
  "read_issue", "push_branch", "propose_change", "comment_issue",
5
13
  "search_issues", "read_change_request", "read_repository",
@@ -18,7 +26,8 @@ export const GITREPO_TRIGGER_EVENT_TYPES: readonly [
18
26
  export const WHATSAPP_CAPABILITIES: readonly ["read_messages", "send_text", "set_reaction", "remove_reaction"];
19
27
  export const WHATSAPP_TRIGGER_EVENT_TYPES: readonly ["message.created", "reaction.changed"];
20
28
 
21
- export type ModelRoleId = typeof MODEL_ROLES[number];
29
+ export type BuiltInModelRoleId = typeof MODEL_ROLES[number];
30
+ export type ModelRoleId = string;
22
31
  export type RepoCapability = typeof REPO_CAPABILITIES[number];
23
32
  export type GitrepoTriggerEventType = typeof GITREPO_TRIGGER_EVENT_TYPES[number];
24
33
  export type WhatsAppCapability = typeof WHATSAPP_CAPABILITIES[number];
package/src/contract.js CHANGED
@@ -4,6 +4,33 @@
4
4
 
5
5
  export const FORMAT_VERSION = 1;
6
6
  export const MODEL_ROLES = Object.freeze(["default", "smol", "slow", "plan"]);
7
+ export const BUILT_IN_MODEL_ROLES = MODEL_ROLES;
8
+ export const MAX_MODEL_ROLES = 8;
9
+ // Reserved ids beyond the four portable built-ins: OMP built-in agent/model
10
+ // role names plus dangerous object keys. Custom ids must avoid all of these;
11
+ // only default/smol/slow/plan are portable workspace defaults.
12
+ export const RESERVED_MODEL_ROLE_IDS = Object.freeze([
13
+ "default", "smol", "slow", "plan",
14
+ "vision", "commit", "tiny", "memory", "task", "advisor", "widget",
15
+ "image", "web", "speech", "dictation", "judge",
16
+ "__proto__", "constructor", "prototype",
17
+ ]);
18
+ export function isReservedModelRoleId(role) {
19
+ return RESERVED_MODEL_ROLE_IDS.includes(role);
20
+ }
21
+ // Custom model role ids: safe slugs that never collide with reserved OMP
22
+ // built-in names. Dots are excluded so role ids stay usable as binding keys
23
+ // and selectors.
24
+ export const CUSTOM_MODEL_ROLE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
25
+ export function isBuiltInModelRole(role) {
26
+ return MODEL_ROLES.includes(role);
27
+ }
28
+ export function isCustomModelRoleId(role) {
29
+ return typeof role === "string" && CUSTOM_MODEL_ROLE_ID_RE.test(role) && !isReservedModelRoleId(role);
30
+ }
31
+ export function isModelRoleId(role) {
32
+ return isBuiltInModelRole(role) || isCustomModelRoleId(role);
33
+ }
7
34
  export const REPO_CAPABILITIES = Object.freeze([
8
35
  "read_issue", "push_branch", "propose_change", "comment_issue",
9
36
  "search_issues", "read_change_request", "read_repository",
package/src/index.js CHANGED
@@ -47,11 +47,19 @@ export {
47
47
  export { SCHEMA_VERSIONS, loadSchema } from "./schema.js";
48
48
  export { canonicalJson, sha256Hex, toBytes } from "./util.js";
49
49
  export {
50
+ BUILT_IN_MODEL_ROLES,
51
+ CUSTOM_MODEL_ROLE_ID_RE,
50
52
  FORMAT_VERSION,
53
+ MAX_MODEL_ROLES,
51
54
  MODEL_ROLES,
52
55
  REPO_CAPABILITIES,
56
+ RESERVED_MODEL_ROLE_IDS,
53
57
  GITREPO_TRIGGER_EVENT_TYPES,
54
58
  WHATSAPP_CAPABILITIES,
55
59
  WHATSAPP_TRIGGER_EVENT_TYPES,
60
+ isBuiltInModelRole,
61
+ isCustomModelRoleId,
62
+ isModelRoleId,
63
+ isReservedModelRoleId,
56
64
  } from "./contract.js";
57
65
  export { validateKnowledgeSources, validateRequirements } from "./validate.js";
package/src/validate.js CHANGED
@@ -8,8 +8,9 @@
8
8
  import { isRecord } from "./errors.js";
9
9
  import { sha256Hex } from "./util.js";
10
10
  import {
11
- MODEL_ROLES, REPO_CAPABILITIES, GITREPO_TRIGGER_EVENT_TYPES,
11
+ MAX_MODEL_ROLES, REPO_CAPABILITIES, GITREPO_TRIGGER_EVENT_TYPES,
12
12
  WHATSAPP_CAPABILITIES, WHATSAPP_TRIGGER_EVENT_TYPES,
13
+ isModelRoleId,
13
14
  } from "./contract.js";
14
15
 
15
16
  const ENTRY_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
@@ -182,8 +183,8 @@ function stringList(value, field, sink, file) {
182
183
  }
183
184
 
184
185
  export function validateModelRoles(input, sink, file) {
185
- if (!Array.isArray(input) || input.length === 0 || input.length > 4) {
186
- err(sink, file, "modelRoles", "must declare 1-4 roles including default");
186
+ if (!Array.isArray(input) || input.length === 0 || input.length > MAX_MODEL_ROLES) {
187
+ err(sink, file, "modelRoles", `must declare 1-${MAX_MODEL_ROLES} roles including default`);
187
188
  return [];
188
189
  }
189
190
  const seen = {};
@@ -195,8 +196,8 @@ export function validateModelRoles(input, sink, file) {
195
196
  return;
196
197
  }
197
198
  checkKeys(entry, ["role", "label", "requirements"], field, sink, file);
198
- if (typeof entry.role !== "string" || !MODEL_ROLES.includes(entry.role)) {
199
- err(sink, file, `${field}.role`, "must be one of default, smol, slow, plan");
199
+ if (typeof entry.role !== "string" || !isModelRoleId(entry.role)) {
200
+ err(sink, file, `${field}.role`, "must be default, smol, slow, plan, or a custom id of letters/digits with -/_ (max 64 chars, starting alphanumeric, not a reserved OMP or object key)");
200
201
  return;
201
202
  }
202
203
  if (seen[entry.role]) {
@@ -807,12 +808,12 @@ export function validateTriggerDefinitions(input, sink, file) {
807
808
  definition.inputs = inputs;
808
809
  }
809
810
  if (entry.deciderRole !== undefined) {
810
- if (typeof entry.deciderRole !== "string" || !MODEL_ROLES.includes(entry.deciderRole)) {
811
+ if (typeof entry.deciderRole !== "string" || !isModelRoleId(entry.deciderRole)) {
811
812
  err(
812
813
  sink,
813
814
  file,
814
815
  `${field}.deciderRole`,
815
- "must be one of default, smol, slow, plan",
816
+ "must be a declared model role: default, smol, slow, plan, or a custom role id",
816
817
  );
817
818
  return;
818
819
  }
@@ -0,0 +1,93 @@
1
+ import { describe, it } from "node:test";
2
+ import assert from "node:assert/strict";
3
+ import { validateFiles } from "../src/index.js";
4
+ import {
5
+ BUILT_IN_MODEL_ROLES,
6
+ CUSTOM_MODEL_ROLE_ID_RE,
7
+ MAX_MODEL_ROLES,
8
+ MODEL_ROLES,
9
+ RESERVED_MODEL_ROLE_IDS,
10
+ isBuiltInModelRole,
11
+ isCustomModelRoleId,
12
+ isModelRoleId,
13
+ isReservedModelRoleId,
14
+ } from "../src/contract.js";
15
+
16
+ const base = (yaml) =>
17
+ validateFiles({
18
+ "bot.yaml":
19
+ "formatVersion: 1\nname: T\ndescription: D\nmodelRoles:\n - role: default\n label: Main\n" +
20
+ yaml,
21
+ "instructions.md": "Be helpful.",
22
+ "README.md": "# T",
23
+ });
24
+
25
+ describe("custom model roles", () => {
26
+ it("accepts a safe custom role id alongside default", async () => {
27
+ const result = await base(" - role: frontend_dev_model\n label: Frontend dev\n");
28
+ assert.equal(result.ok, true);
29
+ assert.deepEqual(
30
+ result.draft.modelRoles.map((r) => r.role),
31
+ ["default", "frontend_dev_model"],
32
+ );
33
+ });
34
+
35
+ it("keeps built-ins reserved and default mandatory", async () => {
36
+ assert.deepEqual([...MODEL_ROLES], ["default", "smol", "slow", "plan"]);
37
+ assert.equal(BUILT_IN_MODEL_ROLES, MODEL_ROLES);
38
+ assert.equal(MAX_MODEL_ROLES, 8);
39
+ assert.equal(isBuiltInModelRole("default"), true);
40
+ assert.equal(isCustomModelRoleId("default"), false);
41
+ assert.equal(isCustomModelRoleId("frontend_dev_model"), true);
42
+ assert.equal(isModelRoleId("frontend_dev_model"), true);
43
+ assert.equal(isModelRoleId("has.dot"), false);
44
+ assert.match("frontend_dev_model", CUSTOM_MODEL_ROLE_ID_RE);
45
+ const missing = await validateFiles({
46
+ "bot.yaml":
47
+ "formatVersion: 1\nname: T\ndescription: D\nmodelRoles:\n - role: frontend_dev_model\n label: Frontend dev\n",
48
+ "instructions.md": "Be helpful.",
49
+ "README.md": "# T",
50
+ });
51
+ assert.equal(missing.ok, false);
52
+ assert.ok(missing.errors.some((e) => e.field === "modelRoles" && /default/.test(e.message)));
53
+ });
54
+
55
+ it("rejects dotted or oversized role ids", async () => {
56
+ for (const role of ["has.dot", "x".repeat(65), "9-ok_but_long_" + "x".repeat(60)]) {
57
+ const result = await base(` - role: ${role}\n label: Bad\n`);
58
+ assert.equal(result.ok, false, role);
59
+ }
60
+ });
61
+
62
+ it("rejects reserved OMP names and unsafe object keys", async () => {
63
+ for (const reserved of RESERVED_MODEL_ROLE_IDS) assert.equal(isReservedModelRoleId(reserved), true);
64
+ for (const role of ["task", "commit", "vision", "constructor", "prototype", "__proto__"]) {
65
+ assert.equal(isCustomModelRoleId(role), false, role);
66
+ assert.equal(isModelRoleId(role) && !isBuiltInModelRole(role), false, role);
67
+ const result = await base(` - role: ${role}\n label: Reserved\n`);
68
+ assert.equal(result.ok, false, role);
69
+ }
70
+ });
71
+
72
+ it("rejects duplicate roles and more than the role cap", async () => {
73
+ const dup = await base(" - role: smol\n label: S\n - role: smol\n label: S2\n");
74
+ assert.equal(dup.ok, false);
75
+ const many = await base(
76
+ ["smol", "slow", "plan", "a", "b", "c", "d", "e"]
77
+ .map((r) => ` - role: ${r}\n label: ${r}\n`)
78
+ .join(""),
79
+ );
80
+ assert.equal(many.ok, false);
81
+ });
82
+
83
+ it("accepts a declared custom deciderRole and rejects undeclared ones", async () => {
84
+ const ok = await base(
85
+ " - role: frontend_dev_model\n label: Frontend dev\ntriggers:\n - key: t\n label: T\n kind: gitrepo\n eventTypes: [issue.opened]\n deciderRole: frontend_dev_model\n deciderInstructions: Decide.\n",
86
+ );
87
+ assert.equal(ok.ok, true);
88
+ const bad = await base(
89
+ "triggers:\n - key: t\n label: T\n kind: gitrepo\n eventTypes: [issue.opened]\n deciderRole: ghost_role\n deciderInstructions: Decide.\n",
90
+ );
91
+ assert.equal(bad.ok, false);
92
+ });
93
+ });