librebot-tools 0.4.5 → 0.4.9

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,25 @@ 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.
79
+ - Optional `completionJudge: { instructions, modelRole? }` enables authoritative
80
+ automatic task completion using the task's full tools and capability boundary.
81
+ Instructions must be non-empty (at most 20000 characters after trimming).
82
+ The role defaults to `default`; an explicit role must appear in `modelRoles`,
83
+ including custom roles. Omitting the judge disables automatic completion.
84
+ Export/import preserves the optional judge and omitted role without inventing
85
+ defaults. Invalid or failed judge output leaves the task open.
68
86
  - `knowledge/README.md` is the index, not an entry. Every other file under
69
87
  `knowledge/` is one knowledge asset: UTF-8 text inlines as `content`;
70
88
  anything else is returned as an `assets[]` entry
@@ -124,9 +142,17 @@ import {
124
142
  `.warnings[]`) instead. Same contract for `validateFiles` / `parseBotFiles`.
125
143
  - `librebot-tools/contract` exports the portable vocabulary with no Node
126
144
  dependencies, so browsers can import it too: `FORMAT_VERSION`,
127
- `MODEL_ROLES`, `REPO_CAPABILITIES`, `GITREPO_TRIGGER_EVENT_TYPES`,
128
- `WHATSAPP_CAPABILITIES`, `WHATSAPP_TRIGGER_EVENT_TYPES` (frozen arrays), and
129
- the derived `ModelRoleId`, `RepoCapability`, `WhatsAppCapability`,
145
+ `MODEL_ROLES` (reserved OMP built-ins `default`, `smol`, `slow`, `plan`),
146
+ `BUILT_IN_MODEL_ROLES` (alias), `MAX_MODEL_ROLES` (8),
147
+ `CUSTOM_MODEL_ROLE_ID_RE`, `isBuiltInModelRole`, `isCustomModelRoleId`,
148
+ `isModelRoleId`, plus `REPO_CAPABILITIES`, `GITREPO_TRIGGER_EVENT_TYPES`,
149
+ `WHATSAPP_CAPABILITIES`, `WHATSAPP_TRIGGER_EVENT_TYPES`,
150
+ `GOOGLE_ACTION_KINDS`, `GOOGLE_DOCS_CAPABILITIES`,
151
+ `GOOGLE_SHEETS_CAPABILITIES`, `GOOGLE_CALENDAR_CAPABILITIES` (frozen arrays), and
152
+ the derived `ModelRoleId` (generic string: built-in or custom),
153
+ `BuiltInModelRoleId`, `RepoCapability`, `WhatsAppCapability`,
154
+ `GoogleActionKind`, `GoogleDocsCapability`, `GoogleSheetsCapability`,
155
+ `GoogleCalendarCapability`,
130
156
  `GitrepoTriggerEventType`, and `WhatsAppTriggerEventType` types. The root
131
157
  entry re-exports the same values.
132
158
  - No author-configured shell commands are executed. Standard skill
@@ -160,11 +186,13 @@ triggers:
160
186
  Action capabilities are `read_issue`, `push_branch`, `propose_change`,
161
187
  `comment_issue`, `search_issues`, `read_change_request`, `read_repository`,
162
188
  `update_issue_labels`, `react_issue`, `update_issue_body`, `update_issue_title`,
163
- `publish_attachments` (GitHub only: uploads task-local SVG/PNG files as issue
164
- attachments, posts one comment embedding them, and optionally transitions labels
165
- after the comment is confirmed; it needs an owner-linked upload token on the
166
- GitHub connection, and GitLab bindings are rejected), and
167
- `merge_change_request`.
189
+ `publish_attachments` (commits task-local SVG/PNG files to the dedicated
190
+ `design-artifacts` branch, posts one comment with commit-addressed links, and
191
+ optionally transitions labels after the comment is confirmed),
192
+ `merge_change_request` (sha-guarded native merge on GitHub and GitLab),
193
+ and `comment_change_request` (replies inside an existing change-request review
194
+ thread by thread ID; top-level change-request comments use `comment_issue`
195
+ with `targetKind: change_request`).
168
196
  Groups require at least one capability; at most 20 groups are accepted.
169
197
  API-only actions do not require workspace. Platform bindings select the provider,
170
198
  connection, numeric repository identity, and optional checkout independently.
@@ -178,12 +206,15 @@ Semantic trigger events are `issue.opened`, `issue.updated`, `issue.closed`,
178
206
  `change_request.commits_updated`, `change_request.checks_updated`,
179
207
  `change_request.comment.created`,
180
208
  `change_request.comment.updated`, `change_request.approval_changed`, and
181
- `repository.pushed`. Repository selection belongs only in instance bindings.
209
+ `repository.pushed`. `GITREPO_TRIGGER_EVENT_SOURCES` maps each event to the
210
+ GitHub App event subscriptions and GitLab webhook triggers that deliver it;
211
+ `librebot preview` prints them per trigger (`triggerProviderEvents` in
212
+ `--json`). Repository selection belongs only in instance bindings.
182
213
  Legacy provider-specific action fields/kinds, derived IDs, and pinned trigger
183
214
  repositories are rejected. Messaging declarations are not implemented and are
184
215
  rejected by the runtime/schema.
185
216
 
186
- - `authorId` and the issue/PR creator's `authorId` are stable GitHub user IDs.
217
+ - `authorId` and the issue/PR creator's `authorId` are stable provider user IDs.
187
218
  `isIssueAuthor` compares these IDs, not mutable logins; it is `null` when
188
219
  either identity is missing. On a PR it refers to that PR's creator.
189
220
  - `authorAssociation`, when present, is GitHub's relationship label, not an
@@ -192,7 +223,10 @@ rejected by the runtime/schema.
192
223
  `checkedAt`, and `status` (`verified` or `unknown`). It describes the
193
224
  comment author's current effective access to the bound repository, not the
194
225
  connection owner, App permissions, or access when the comment was posted.
195
- Unknown authority uses `null` for permission, role, and `canPush`.
226
+ Unknown authority uses `null` for permission, role, and `canPush`. On GitLab
227
+ it is the author's effective project membership by user ID: `roleName` is
228
+ the access level and `canPush` means Developer or above ("can push to the
229
+ repository", not "to protected branches").
196
230
 
197
231
  For requirements acceptance/revisions, require `isIssueAuthor === true`.
198
232
  For a ready-for-development decision, require
@@ -220,27 +254,63 @@ External skill resolution requires `npx` on PATH. It selects its pinned Skills C
220
254
  independently of the parent npm invocation, including when Librebot itself runs
221
255
  through `npx --package=... librebot`.
222
256
 
257
+ ## Publishing
258
+
259
+ Releases use `.github/workflows/publish.yml` on GitHub-hosted runners with npm
260
+ trusted publishing (OIDC). No npm token or per-release browser approval is needed.
261
+ The npm package's Trusted Publisher must authorize organization `librebot-work`,
262
+ repository `tools`, workflow filename `publish.yml`, with direct `npm publish`
263
+ allowed and no environment name.
264
+
265
+ After the compatible platform contract is ready, commit the version change and
266
+ lockfile, merge it to `main`, then push a matching stable version tag:
267
+
268
+ ```sh
269
+ git tag v0.4.7
270
+ git push origin v0.4.7
271
+ ```
272
+
273
+ Use the new package version, not an already published version. The workflow
274
+ requires the tag to match `package.json` and point to a commit reachable from
275
+ `main`, installs dependencies, runs tests, inspects the package, and publishes.
276
+ Protect `main` and restrict creation/update/deletion of `v*` tags to release
277
+ maintainers: pushing a release tag authorizes publishing. npm trusted publisher
278
+ setup must complete its first successful publish within two days; otherwise
279
+ recreate that configuration when a release is ready.
280
+
223
281
  ## Platform integration
224
282
 
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`.
283
+ - The platform pins the exact npm release in its dependency manifest and lockfile.
284
+ API/runtime ingestion and the Git validator install the same version.
285
+ - Bot authors use `npx --yes --package=librebot-tools@latest librebot ...`.
286
+ Custom model roles require version `0.4.6` or newer; publish a compatible
287
+ platform release before adopting a newer source contract.
234
288
  - Portable `actions` also accept `kind: whatsapp` with only `read_messages`,
235
289
  `send_text`, `set_reaction`, and `remove_reaction`. Repository capabilities
236
290
  remain exclusive to `gitrepo`. Exact sender-phone bindings, independent read
237
291
  context, destination policies, and automated-write consent belong to owner
238
- instance settings, never portable source. Version 0.4.1 added this parser/schema
239
- contract; 0.4.2 replaces the scaffold README with a user-manual skeleton;
292
+ instance settings, never portable source.
293
+ - Portable `actions` also accept `kind: google_docs` (`search_documents`,
294
+ `read_document`, `create_document`, `edit_document`), `kind: google_sheets`
295
+ (`search_spreadsheets`, `read_spreadsheet`, `create_spreadsheet`,
296
+ `write_values`, `append_values`, `write_formulas`), and
297
+ `kind: google_calendar` (`search_events`, `read_event`, `create_event`,
298
+ `edit_event`, `cancel_event`, `manage_attendees`). Capability namespaces are
299
+ exclusive to their kind. Drive bindings are account-wide; calendar bindings
300
+ pin exact calendar IDs with attendee/notification policy in owner instance
301
+ settings, never portable source. Version 0.4.9 is the first published
302
+ release with this parser/schema contract.
303
+ - Version history: 0.4.1 added the WhatsApp parser/schema contract; 0.4.2
304
+ replaces the scaffold README with a user-manual skeleton;
240
305
  0.4.3 adds the `publish_attachments` repository capability; 0.4.4 adds the
241
306
  `merge_change_request` repository capability and the
242
- `change_request.checks_updated` trigger event.
243
- All are locally bundled, not published to npm.
307
+ `change_request.checks_updated` trigger event; 0.4.6 adds custom model role
308
+ ids (up to 8 roles including `default`; workspace defaults stay built-in-only
309
+ while custom roles require explicit instance bindings); 0.4.9 publishes the
310
+ Google action kinds, optional `completionJudge`, the `comment_change_request`
311
+ capability, and `GITREPO_TRIGGER_EVENT_SOURCES`, and documents GitLab
312
+ parity for `merge_change_request`, `publish_attachments`, and author
313
+ authority (no contract change for those).
244
314
  - Portable WhatsApp triggers use `kind: whatsapp`, semantic `message.created`
245
315
  and/or `reaction.changed`, and the existing keyed decider definition fields.
246
316
  Event namespaces are checked against the selected trigger kind.
@@ -272,7 +342,9 @@ export round-trips, and skill-lock reproducibility.
272
342
 
273
343
  750 KB draft cap (UTF-8 bytes); knowledge <= 100 entries (files + `knowledgeSources`
274
344
  combined); skills <= 100; connectors <= 50; triggers <= 20; workspace
275
- mounts <= 10; model roles 1-4 including `default`; SKILL.md <= 50,000 bytes
345
+ mounts <= 10; model roles 1-8 including `default` (reserved built-ins
346
+ `default`, `smol`, `slow`, `plan` plus custom ids such as `frontend_dev_model`);
347
+ SKILL.md <= 50,000 bytes
276
348
  and non-empty; text knowledge <= 100,000 chars inline (empty files inline
277
349
  as empty content, matching platform acceptance); knowledge assets
278
350
  <= 10 MiB; skill supporting files <= 1 MiB each.
package/bin/librebot.js CHANGED
@@ -5,6 +5,7 @@ import { parseArgs } from "node:util";
5
5
  import { writeFile, mkdir, rm } from "node:fs/promises";
6
6
  import { join } from "node:path";
7
7
  import {
8
+ GITREPO_TRIGGER_EVENT_SOURCES,
8
9
  readDirFiles,
9
10
  scaffoldBot,
10
11
  validateSource,
@@ -17,6 +18,18 @@ import {
17
18
  } from "../src/skills-lock.js";
18
19
  import { toBytes } from "../src/util.js";
19
20
 
21
+ /** Provider subscriptions a gitrepo trigger needs, deduplicated in declaration order. */
22
+ function providerEvents(trigger) {
23
+ if (trigger.kind !== "gitrepo") return undefined;
24
+ const github = new Set(), gitlab = new Set();
25
+ for (const event of trigger.eventTypes) {
26
+ const sources = GITREPO_TRIGGER_EVENT_SOURCES[event];
27
+ for (const name of sources?.github ?? []) github.add(name);
28
+ for (const name of sources?.gitlab ?? []) gitlab.add(name);
29
+ }
30
+ return { github: [...github], gitlab: [...gitlab] };
31
+ }
32
+
20
33
  function fail(message, issues) {
21
34
  console.error(`error: ${message}`);
22
35
  for (const issue of issues ?? []) {
@@ -50,6 +63,9 @@ function previewShape(result) {
50
63
  content: undefined,
51
64
  })),
52
65
  },
66
+ triggerProviderEvents: Object.fromEntries(result.draft.triggers
67
+ .map((trigger) => [trigger.key, providerEvents(trigger)])
68
+ .filter(([, events]) => events !== undefined)),
53
69
  icon: result.icon ? (({ bytes, ...metadata }) => metadata)(result.icon) : undefined,
54
70
  assets: result.assets.map((a) => ({
55
71
  knowledgeId: a.knowledgeId,
@@ -132,6 +148,11 @@ async function cmdPreview(dir, json) {
132
148
  console.log("triggers:");
133
149
  for (const trigger of draft.triggers) {
134
150
  console.log(` - ${trigger.label} [${trigger.key}; ${trigger.kind}] ${trigger.eventTypes.join(", ")}`);
151
+ const required = providerEvents(trigger);
152
+ if (required) {
153
+ console.log(` GitHub App events: ${required.github.join(", ")}`);
154
+ console.log(` GitLab webhook triggers: ${required.gitlab.join(", ")}`);
155
+ }
135
156
  }
136
157
  }
137
158
  if (draft.workspace.length > 0) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "librebot-tools",
3
- "version": "0.4.5",
3
+ "version": "0.4.9",
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": {
@@ -36,5 +36,9 @@
36
36
  "image-size": "2.1.0",
37
37
  "saxes": "6.0.0",
38
38
  "yaml": "2.9.1"
39
+ },
40
+ "repository": {
41
+ "type": "git",
42
+ "url": "git+https://github.com/librebot-work/tools.git"
39
43
  }
40
44
  }
@@ -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",
@@ -41,6 +41,16 @@
41
41
  }
42
42
  }
43
43
  },
44
+ "completionJudge": {
45
+ "type": "object",
46
+ "additionalProperties": false,
47
+ "required": ["instructions"],
48
+ "description": "Optional authoritative task completion judge using the task's full tools. Omit to disable automatic completion.",
49
+ "properties": {
50
+ "instructions": { "type": "string", "minLength": 1, "maxLength": 20000, "pattern": "\\S" },
51
+ "modelRole": { "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"] } }], "default": "default", "description": "Must name a role declared in modelRoles, including custom roles. Defaults to default when omitted." }
52
+ }
53
+ },
44
54
  "workspace": {
45
55
  "type": "array",
46
56
  "maxItems": 10,
@@ -96,7 +106,7 @@
96
106
  }
97
107
  }
98
108
  },
99
- "deciderRole": { "enum": ["default", "smol", "slow", "plan"] },
109
+ "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
110
  "deciderInstructions": { "type": "string", "minLength": 1, "maxLength": 20000 },
101
111
  "enabledByDefault": { "type": "boolean" }
102
112
  },
@@ -116,18 +126,34 @@
116
126
  "required": ["key", "kind", "capabilities"],
117
127
  "properties": {
118
128
  "key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
119
- "kind": { "enum": ["gitrepo", "whatsapp"] },
129
+ "kind": { "enum": ["gitrepo", "whatsapp", "google_docs", "google_sheets", "google_calendar"] },
120
130
  "label": { "type": "string", "minLength": 1, "maxLength": 100 },
121
131
  "capabilities": {
122
132
  "type": "array", "minItems": 1, "maxItems": 13, "uniqueItems": true,
123
- "items": { "enum": ["read_issue", "push_branch", "propose_change", "comment_issue", "search_issues", "read_change_request", "read_repository", "update_issue_labels", "react_issue", "update_issue_body", "update_issue_title", "publish_attachments", "merge_change_request", "read_messages", "send_text", "set_reaction", "remove_reaction"] }
133
+ "items": { "enum": ["read_issue", "push_branch", "propose_change", "comment_issue", "search_issues", "read_change_request", "read_repository", "update_issue_labels", "react_issue", "update_issue_body", "update_issue_title", "publish_attachments", "merge_change_request", "comment_change_request", "read_messages", "send_text", "set_reaction", "remove_reaction", "search_documents", "read_document", "create_document", "edit_document", "search_spreadsheets", "read_spreadsheet", "create_spreadsheet", "write_values", "append_values", "write_formulas", "search_events", "read_event", "create_event", "edit_event", "cancel_event", "manage_attendees"] }
124
134
  }
125
135
  },
126
- "allOf": [{
127
- "if": { "properties": { "kind": { "const": "whatsapp" } } },
128
- "then": { "properties": { "capabilities": { "maxItems": 4, "items": { "enum": ["read_messages", "send_text", "set_reaction", "remove_reaction"] } } } },
129
- "else": { "properties": { "capabilities": { "items": { "enum": ["read_issue", "push_branch", "propose_change", "comment_issue", "search_issues", "read_change_request", "read_repository", "update_issue_labels", "react_issue", "update_issue_body", "update_issue_title", "publish_attachments", "merge_change_request"] } } } }
130
- }]
136
+ "allOf": [
137
+ {
138
+ "if": { "properties": { "kind": { "const": "whatsapp" } } },
139
+ "then": { "properties": { "capabilities": { "maxItems": 4, "items": { "enum": ["read_messages", "send_text", "set_reaction", "remove_reaction"] } } } }
140
+ },
141
+ {
142
+ "if": { "properties": { "kind": { "const": "google_docs" } } },
143
+ "then": { "properties": { "capabilities": { "maxItems": 4, "items": { "enum": ["search_documents", "read_document", "create_document", "edit_document"] } } } }
144
+ },
145
+ {
146
+ "if": { "properties": { "kind": { "const": "google_sheets" } } },
147
+ "then": { "properties": { "capabilities": { "maxItems": 6, "items": { "enum": ["search_spreadsheets", "read_spreadsheet", "create_spreadsheet", "write_values", "append_values", "write_formulas"] } } } }
148
+ },
149
+ {
150
+ "if": { "properties": { "kind": { "const": "google_calendar" } } },
151
+ "then": { "properties": { "capabilities": { "maxItems": 6, "items": { "enum": ["search_events", "read_event", "create_event", "edit_event", "cancel_event", "manage_attendees"] } } } }
152
+ },
153
+ {
154
+ "if": { "properties": { "kind": { "const": "gitrepo" } } },
155
+ "then": { "properties": { "capabilities": { "items": { "enum": ["read_issue", "push_branch", "propose_change", "comment_issue", "search_issues", "read_change_request", "read_repository", "update_issue_labels", "react_issue", "update_issue_body", "update_issue_title", "publish_attachments", "merge_change_request", "comment_change_request"] } } } } }
156
+ ]
131
157
  }
132
158
  },
133
159
  "connectors": {
package/src/contract.d.ts CHANGED
@@ -1,10 +1,18 @@
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",
6
14
  "update_issue_labels", "react_issue", "update_issue_body", "update_issue_title",
7
- "publish_attachments", "merge_change_request",
15
+ "publish_attachments", "merge_change_request", "comment_change_request",
8
16
  ];
9
17
  export const GITREPO_TRIGGER_EVENT_TYPES: readonly [
10
18
  "issue.opened", "issue.updated", "issue.closed", "issue.reopened",
@@ -15,11 +23,21 @@ export const GITREPO_TRIGGER_EVENT_TYPES: readonly [
15
23
  "change_request.comment.created", "change_request.comment.updated",
16
24
  "change_request.approval_changed", "repository.pushed",
17
25
  ];
26
+ export const GITREPO_TRIGGER_EVENT_SOURCES: Readonly<Record<GitrepoTriggerEventType, { readonly github: readonly string[]; readonly gitlab: readonly string[] }>>;
18
27
  export const WHATSAPP_CAPABILITIES: readonly ["read_messages", "send_text", "set_reaction", "remove_reaction"];
19
28
  export const WHATSAPP_TRIGGER_EVENT_TYPES: readonly ["message.created", "reaction.changed"];
29
+ export const GOOGLE_ACTION_KINDS: readonly ["google_docs", "google_sheets", "google_calendar"];
30
+ export const GOOGLE_DOCS_CAPABILITIES: readonly ["search_documents", "read_document", "create_document", "edit_document"];
31
+ export const GOOGLE_SHEETS_CAPABILITIES: readonly ["search_spreadsheets", "read_spreadsheet", "create_spreadsheet", "write_values", "append_values", "write_formulas"];
32
+ export const GOOGLE_CALENDAR_CAPABILITIES: readonly ["search_events", "read_event", "create_event", "edit_event", "cancel_event", "manage_attendees"];
20
33
 
21
- export type ModelRoleId = typeof MODEL_ROLES[number];
34
+ export type BuiltInModelRoleId = typeof MODEL_ROLES[number];
35
+ export type ModelRoleId = string;
22
36
  export type RepoCapability = typeof REPO_CAPABILITIES[number];
23
37
  export type GitrepoTriggerEventType = typeof GITREPO_TRIGGER_EVENT_TYPES[number];
24
38
  export type WhatsAppCapability = typeof WHATSAPP_CAPABILITIES[number];
25
39
  export type WhatsAppTriggerEventType = typeof WHATSAPP_TRIGGER_EVENT_TYPES[number];
40
+ export type GoogleActionKind = typeof GOOGLE_ACTION_KINDS[number];
41
+ export type GoogleDocsCapability = typeof GOOGLE_DOCS_CAPABILITIES[number];
42
+ export type GoogleSheetsCapability = typeof GOOGLE_SHEETS_CAPABILITIES[number];
43
+ export type GoogleCalendarCapability = typeof GOOGLE_CALENDAR_CAPABILITIES[number];
package/src/contract.js CHANGED
@@ -4,11 +4,38 @@
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",
10
37
  "update_issue_labels", "react_issue", "update_issue_body", "update_issue_title",
11
- "publish_attachments", "merge_change_request",
38
+ "publish_attachments", "merge_change_request", "comment_change_request",
12
39
  ]);
13
40
  export const GITREPO_TRIGGER_EVENT_TYPES = Object.freeze([
14
41
  "issue.opened", "issue.updated", "issue.closed", "issue.reopened",
@@ -19,5 +46,32 @@ export const GITREPO_TRIGGER_EVENT_TYPES = Object.freeze([
19
46
  "change_request.comment.created", "change_request.comment.updated",
20
47
  "change_request.approval_changed", "repository.pushed",
21
48
  ]);
49
+ // Provider deliveries that produce each semantic repository event. Values
50
+ // name the GitHub App "Subscribe to events" entries and the GitLab project
51
+ // webhook triggers that must be enabled for the event to arrive.
52
+ const source = (github, gitlab) => Object.freeze({ github: Object.freeze(github), gitlab: Object.freeze(gitlab) });
53
+ export const GITREPO_TRIGGER_EVENT_SOURCES = Object.freeze({
54
+ "issue.opened": source(["Issues"], ["Issues events"]),
55
+ "issue.updated": source(["Issues"], ["Issues events"]),
56
+ "issue.closed": source(["Issues"], ["Issues events"]),
57
+ "issue.reopened": source(["Issues"], ["Issues events"]),
58
+ "issue.comment.created": source(["Issue comment"], ["Comments"]),
59
+ "issue.comment.updated": source(["Issue comment"], ["Comments"]),
60
+ "change_request.opened": source(["Pull request"], ["Merge request events"]),
61
+ "change_request.updated": source(["Pull request"], ["Merge request events"]),
62
+ "change_request.closed": source(["Pull request"], ["Merge request events"]),
63
+ "change_request.reopened": source(["Pull request"], ["Merge request events"]),
64
+ "change_request.merged": source(["Pull request"], ["Merge request events"]),
65
+ "change_request.commits_updated": source(["Pull request"], ["Merge request events"]),
66
+ "change_request.checks_updated": source(["Check run", "Check suite", "Workflow run", "Status"], ["Pipeline events"]),
67
+ "change_request.comment.created": source(["Issue comment", "Pull request review comment"], ["Comments"]),
68
+ "change_request.comment.updated": source(["Issue comment", "Pull request review comment"], ["Comments"]),
69
+ "change_request.approval_changed": source(["Pull request review"], ["Merge request events"]),
70
+ "repository.pushed": source(["Push"], ["Push events"]),
71
+ });
22
72
  export const WHATSAPP_CAPABILITIES = Object.freeze(["read_messages", "send_text", "set_reaction", "remove_reaction"]);
23
73
  export const WHATSAPP_TRIGGER_EVENT_TYPES = Object.freeze(["message.created", "reaction.changed"]);
74
+ export const GOOGLE_ACTION_KINDS = Object.freeze(["google_docs", "google_sheets", "google_calendar"]);
75
+ export const GOOGLE_DOCS_CAPABILITIES = Object.freeze(["search_documents", "read_document", "create_document", "edit_document"]);
76
+ export const GOOGLE_SHEETS_CAPABILITIES = Object.freeze(["search_spreadsheets", "read_spreadsheet", "create_spreadsheet", "write_values", "append_values", "write_formulas"]);
77
+ export const GOOGLE_CALENDAR_CAPABILITIES = Object.freeze(["search_events", "read_event", "create_event", "edit_event", "cancel_event", "manage_attendees"]);
package/src/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  // Type definitions for librebot-tools (hand-written; no build step).
2
- import type { ModelRoleId, RepoCapability, WhatsAppCapability } from "./contract.js";
2
+ import type { ModelRoleId, RepoCapability, WhatsAppCapability, GoogleDocsCapability, GoogleSheetsCapability, GoogleCalendarCapability } from "./contract.js";
3
3
  export * from "./contract.js";
4
4
 
5
5
  export interface SourceIssue {
@@ -48,6 +48,12 @@ export interface BotConnector {
48
48
  endpoint?: string;
49
49
  }
50
50
 
51
+ export interface BotCompletionJudge {
52
+ instructions: string;
53
+ /** Declared role; defaults to default when omitted. */
54
+ modelRole?: ModelRoleId;
55
+ }
56
+
51
57
  export interface BotDraft {
52
58
  name: string;
53
59
  description: string;
@@ -55,12 +61,14 @@ export interface BotDraft {
55
61
  /** User-facing documentation from root README.md, separate from the prompt and knowledge. */
56
62
  readme: string;
57
63
  modelRoles: BotModelRole[];
64
+ /** Omit to disable automatic task completion. */
65
+ completionJudge?: BotCompletionJudge;
58
66
  knowledge: BotKnowledge[];
59
67
  skills: BotSkill[];
60
68
  connectors: BotConnector[];
61
69
  triggers: Array<{ key: string; label: string; kind: "gitrepo" | "whatsapp"; eventTypes: string[]; description?: string; inputs?: Array<{ key: string; label?: string; type: "string" | "number" | "boolean" | "select"; required?: boolean; options?: string[]; help?: string }>; deciderRole?: ModelRoleId; deciderInstructions: string; enabledByDefault?: boolean }>;
62
70
  workspace: Array<{ key: string; label?: string; path: string }>;
63
- actions: Array<{ key: string; kind: "gitrepo"; label?: string; capabilities: RepoCapability[] } | { key: string; kind: "whatsapp"; label?: string; capabilities: WhatsAppCapability[] }>;
71
+ actions: Array<{ key: string; kind: "gitrepo"; label?: string; capabilities: RepoCapability[] } | { key: string; kind: "whatsapp"; label?: string; capabilities: WhatsAppCapability[] } | { key: string; kind: "google_docs"; label?: string; capabilities: GoogleDocsCapability[] } | { key: string; kind: "google_sheets"; label?: string; capabilities: GoogleSheetsCapability[] } | { key: string; kind: "google_calendar"; label?: string; capabilities: GoogleCalendarCapability[] }>;
64
72
  icon?: string;
65
73
  }
66
74
 
package/src/index.js CHANGED
@@ -47,11 +47,24 @@ 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,
57
+ GITREPO_TRIGGER_EVENT_SOURCES,
53
58
  GITREPO_TRIGGER_EVENT_TYPES,
59
+ GOOGLE_ACTION_KINDS,
60
+ GOOGLE_CALENDAR_CAPABILITIES,
61
+ GOOGLE_DOCS_CAPABILITIES,
62
+ GOOGLE_SHEETS_CAPABILITIES,
54
63
  WHATSAPP_CAPABILITIES,
55
64
  WHATSAPP_TRIGGER_EVENT_TYPES,
65
+ isBuiltInModelRole,
66
+ isCustomModelRoleId,
67
+ isModelRoleId,
68
+ isReservedModelRoleId,
56
69
  } from "./contract.js";
57
70
  export { validateKnowledgeSources, validateRequirements } from "./validate.js";
package/src/parse.js CHANGED
@@ -19,6 +19,7 @@ import {
19
19
  validateActions,
20
20
  validateKnowledgeSources,
21
21
  validateModelRoles,
22
+ validateCompletionJudge,
22
23
  validateTriggerDefinitions,
23
24
  validateWorkspaceMounts,
24
25
  } from "./validate.js";
@@ -39,6 +40,7 @@ const TOP_LEVEL_KEYS = [
39
40
  "description",
40
41
  "icon",
41
42
  "modelRoles",
43
+ "completionJudge",
42
44
  "workspace",
43
45
  "triggers",
44
46
  "actions",
@@ -313,6 +315,7 @@ export async function validateFiles(input) {
313
315
  for (const role of modelRoles) {
314
316
  if (role.role === "default") role.requirements.tools = true;
315
317
  }
318
+ const completionJudge = validateCompletionJudge(botDoc.completionJudge, modelRoles, sink, FILE_BOT_YAML);
316
319
  const workspace = validateWorkspaceMounts(botDoc.workspace, sink, FILE_BOT_YAML);
317
320
  const triggers = validateTriggerDefinitions(botDoc.triggers, sink, FILE_BOT_YAML);
318
321
  const actions = validateActions(botDoc.actions, sink, FILE_BOT_YAML);
@@ -598,6 +601,7 @@ export async function validateFiles(input) {
598
601
  botPrompt,
599
602
  readme,
600
603
  modelRoles,
604
+ ...(completionJudge !== undefined ? { completionJudge } : {}),
601
605
  knowledge,
602
606
  skills,
603
607
  connectors,
package/src/scaffold.js CHANGED
@@ -179,6 +179,7 @@ export function exportBotFiles(
179
179
  description: description ?? "",
180
180
  ...(draft.icon !== undefined ? { icon: `./${iconPath(draft.icon)}` } : {}),
181
181
  modelRoles: modelRoles ?? [{ role: "default", label: "Main" }],
182
+ ...(draft.completionJudge !== undefined ? { completionJudge: draft.completionJudge } : {}),
182
183
  workspace: workspace ?? [],
183
184
  triggers: triggers ?? [],
184
185
  actions: actions ?? [],
package/src/validate.js CHANGED
@@ -8,9 +8,20 @@
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
+ GOOGLE_ACTION_KINDS, GOOGLE_DOCS_CAPABILITIES, GOOGLE_SHEETS_CAPABILITIES,
14
+ GOOGLE_CALENDAR_CAPABILITIES,
15
+ isModelRoleId,
13
16
  } from "./contract.js";
17
+ const ACTION_CAPABILITIES = {
18
+ gitrepo: REPO_CAPABILITIES,
19
+ whatsapp: WHATSAPP_CAPABILITIES,
20
+ google_docs: GOOGLE_DOCS_CAPABILITIES,
21
+ google_sheets: GOOGLE_SHEETS_CAPABILITIES,
22
+ google_calendar: GOOGLE_CALENDAR_CAPABILITIES,
23
+ };
24
+ const ACTION_KINDS = ["gitrepo", "whatsapp", ...GOOGLE_ACTION_KINDS];
14
25
 
15
26
  const ENTRY_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
16
27
  const INPUT_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
@@ -182,8 +193,8 @@ function stringList(value, field, sink, file) {
182
193
  }
183
194
 
184
195
  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");
196
+ if (!Array.isArray(input) || input.length === 0 || input.length > MAX_MODEL_ROLES) {
197
+ err(sink, file, "modelRoles", `must declare 1-${MAX_MODEL_ROLES} roles including default`);
187
198
  return [];
188
199
  }
189
200
  const seen = {};
@@ -195,8 +206,8 @@ export function validateModelRoles(input, sink, file) {
195
206
  return;
196
207
  }
197
208
  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");
209
+ if (typeof entry.role !== "string" || !isModelRoleId(entry.role)) {
210
+ 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
211
  return;
201
212
  }
202
213
  if (seen[entry.role]) {
@@ -216,6 +227,28 @@ export function validateModelRoles(input, sink, file) {
216
227
  return roles;
217
228
  }
218
229
 
230
+ export function validateCompletionJudge(input, modelRoles, sink, file) {
231
+ if (input === undefined) return undefined;
232
+ const field = "completionJudge";
233
+ if (!isRecord(input)) {
234
+ err(sink, file, field, "must be an object");
235
+ return undefined;
236
+ }
237
+ checkKeys(input, ["instructions", "modelRole"], field, sink, file);
238
+ const instructions = requiredString(input.instructions, `${field}.instructions`, 20000, sink, file);
239
+ if (input.modelRole !== undefined && (
240
+ !isModelRoleId(input.modelRole) ||
241
+ !modelRoles.some((role) => role.role === input.modelRole)
242
+ )) {
243
+ err(sink, file, `${field}.modelRole`, "must be one of the bot's declared model roles");
244
+ }
245
+ if (instructions === undefined) return undefined;
246
+ return {
247
+ instructions,
248
+ ...(input.modelRole !== undefined ? { modelRole: input.modelRole } : {}),
249
+ };
250
+ }
251
+
219
252
  /**
220
253
  * Model capability requirements. Passed through (validated) so bot.yaml
221
254
  * preserves the full platform ModelRequirements contract: tools, vision,
@@ -552,8 +585,8 @@ export function validateActions(input, sink, file) {
552
585
  checkKeys(entry, ["key", "kind", "label", "capabilities"], field, sink, file);
553
586
  const key = entryId(entry.key, `${field}.key`, sink, file);
554
587
  const label = optionalText(entry.label, `${field}.label`, 100, sink, file);
555
- if (entry.kind !== "gitrepo" && entry.kind !== "whatsapp") err(sink, file, `${field}.kind`, "must be gitrepo or whatsapp");
556
- const supported = entry.kind === "whatsapp" ? WHATSAPP_CAPABILITIES : REPO_CAPABILITIES;
588
+ if (!ACTION_KINDS.includes(entry.kind)) err(sink, file, `${field}.kind`, "must be gitrepo, whatsapp, google_docs, google_sheets, or google_calendar");
589
+ const supported = ACTION_CAPABILITIES[entry.kind] ?? REPO_CAPABILITIES;
557
590
  if (key === undefined) return;
558
591
  if (seen.has(key)) err(sink, file, `${field}.key`, `contains duplicate key ${key}`);
559
592
  seen.add(key);
@@ -807,12 +840,12 @@ export function validateTriggerDefinitions(input, sink, file) {
807
840
  definition.inputs = inputs;
808
841
  }
809
842
  if (entry.deciderRole !== undefined) {
810
- if (typeof entry.deciderRole !== "string" || !MODEL_ROLES.includes(entry.deciderRole)) {
843
+ if (typeof entry.deciderRole !== "string" || !isModelRoleId(entry.deciderRole)) {
811
844
  err(
812
845
  sink,
813
846
  file,
814
847
  `${field}.deciderRole`,
815
- "must be one of default, smol, slow, plan",
848
+ "must be a declared model role: default, smol, slow, plan, or a custom role id",
816
849
  );
817
850
  return;
818
851
  }
@@ -0,0 +1,71 @@
1
+ import { describe, it } from "node:test";
2
+ import assert from "node:assert/strict";
3
+ import { stringify } from "yaml";
4
+ import { exportBotFiles, parseBotFiles, validateFiles } from "../src/index.js";
5
+
6
+ function files(judge, roles = ["default"]) {
7
+ return {
8
+ "bot.yaml": stringify({
9
+ formatVersion: 1,
10
+ name: "Completion",
11
+ description: "Completion contract",
12
+ modelRoles: roles.map((role) => ({ role, label: role })),
13
+ ...(judge !== undefined ? { completionJudge: judge } : {}),
14
+ }),
15
+ "instructions.md": "Complete the requested work.",
16
+ "README.md": "# Completion\nA test bot.",
17
+ };
18
+ }
19
+
20
+ async function roundtrip(input) {
21
+ const parsed = await parseBotFiles(input);
22
+ const exported = exportBotFiles(parsed.draft);
23
+ const restored = await parseBotFiles(exported);
24
+ assert.deepEqual(restored.draft, parsed.draft);
25
+ return { parsed, exported, restored };
26
+ }
27
+
28
+ describe("optional completion judge source contract", () => {
29
+ it("does not enable automatic completion when the field is absent", async () => {
30
+ const { parsed, exported, restored } = await roundtrip(files());
31
+ assert.equal(Object.hasOwn(parsed.draft, "completionJudge"), false);
32
+ assert.equal(Object.hasOwn(restored.draft, "completionJudge"), false);
33
+ assert.doesNotMatch(exported["bot.yaml"], /completionJudge/);
34
+ });
35
+
36
+ it("preserves an omitted default role without materializing it", async () => {
37
+ const instructions = "Check the requested outcome.\nKeep open if incomplete.";
38
+ const { restored } = await roundtrip(files({ instructions }));
39
+ assert.deepEqual(restored.draft.completionJudge, { instructions });
40
+ assert.equal(Object.hasOwn(restored.draft.completionJudge, "modelRole"), false);
41
+ });
42
+
43
+ it("round-trips explicit default, built-in, and custom declared roles", async () => {
44
+ for (const modelRole of ["default", "slow", "completion_reviewer"]) {
45
+ const judge = { instructions: "Verify the outcome using the task tools.", modelRole };
46
+ const { restored } = await roundtrip(files(judge, [...new Set(["default", modelRole])]));
47
+ assert.deepEqual(restored.draft.completionJudge, judge);
48
+ }
49
+ });
50
+
51
+ it("requires an explicitly selected role to exist, including built-ins", async () => {
52
+ for (const modelRole of ["slow", "missing_custom", "judge", "has.dot", "", null, 42]) {
53
+ const result = await validateFiles(files({ instructions: "Review.", modelRole }));
54
+ assert.equal(result.ok, false, String(modelRole));
55
+ assert.ok(result.errors.some((error) => error.field === "completionJudge.modelRole"));
56
+ }
57
+ });
58
+
59
+ it("rejects malformed, unknown, missing, blank, and oversized judge definitions", async () => {
60
+ for (const judge of [null, [], "review", {}, { instructions: 42 }, { instructions: " \n " }, { instructions: "x".repeat(20001) }, { instructions: "Review.", enabled: true }]) {
61
+ const result = await validateFiles(files(judge));
62
+ assert.equal(result.ok, false, JSON.stringify(judge));
63
+ assert.ok(result.errors.some((error) => error.field.startsWith("completionJudge")));
64
+ }
65
+ });
66
+
67
+ it("uses the existing instruction trimming and length boundary", async () => {
68
+ const result = await parseBotFiles(files({ instructions: ` ${"x".repeat(20000)}\n` }));
69
+ assert.equal(result.draft.completionJudge.instructions, "x".repeat(20000));
70
+ });
71
+ });
@@ -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
+ });
@@ -0,0 +1,27 @@
1
+ import { it } from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { validateFiles } from '../src/index.js';
4
+ import { GOOGLE_DOCS_CAPABILITIES, GOOGLE_SHEETS_CAPABILITIES, GOOGLE_CALENDAR_CAPABILITIES } from '../src/index.js';
5
+ const files = (kind, capabilities) => ({
6
+ 'bot.yaml': `formatVersion: 1\nname: Researcher\ndescription: Uses owner-bound Google authority\nmodelRoles:\n - {role: default, label: Main}\nactions:\n - {key: work, kind: ${kind}, capabilities: [${capabilities.join(', ')}]}\n`,
7
+ 'instructions.md': 'Use only owner-bound Google authority.',
8
+ 'README.md': '# Researcher',
9
+ });
10
+ it('parses portable Google Docs, Sheets, and Calendar declarations', async () => {
11
+ assert.deepEqual([...GOOGLE_DOCS_CAPABILITIES], ['search_documents', 'read_document', 'create_document', 'edit_document']);
12
+ assert.deepEqual([...GOOGLE_SHEETS_CAPABILITIES], ['search_spreadsheets', 'read_spreadsheet', 'create_spreadsheet', 'write_values', 'append_values', 'write_formulas']);
13
+ assert.deepEqual([...GOOGLE_CALENDAR_CAPABILITIES], ['search_events', 'read_event', 'create_event', 'edit_event', 'cancel_event', 'manage_attendees']);
14
+ for (const [kind, capabilities] of [['google_docs', GOOGLE_DOCS_CAPABILITIES], ['google_sheets', GOOGLE_SHEETS_CAPABILITIES], ['google_calendar', GOOGLE_CALENDAR_CAPABILITIES]]) {
15
+ const result = await validateFiles(files(kind, [...capabilities]));
16
+ assert.equal(result.ok, true, JSON.stringify(result.errors));
17
+ assert.deepEqual(result.draft.actions, [{ key: 'work', kind, capabilities: [...capabilities] }]);
18
+ }
19
+ });
20
+ it('rejects crossing Google and repository/WhatsApp capabilities', async () => {
21
+ assert.equal((await validateFiles(files('google_docs', ['send_text']))).ok, false);
22
+ assert.equal((await validateFiles(files('google_sheets', ['read_issue']))).ok, false);
23
+ assert.equal((await validateFiles(files('google_calendar', ['read_document']))).ok, false);
24
+ assert.equal((await validateFiles(files('google_docs', ['read_document', 'read_document']))).ok, false);
25
+ assert.equal((await validateFiles(files('whatsapp', ['read_event']))).ok, false);
26
+ assert.equal((await validateFiles(files('gitrepo', ['edit_event']))).ok, false);
27
+ });
@@ -44,7 +44,7 @@ describe("semantic cross-references", () => {
44
44
  });
45
45
 
46
46
  it("accepts every portable repository capability", async () => {
47
- const capabilities = ["read_issue", "push_branch", "propose_change", "comment_issue", "search_issues", "read_change_request", "read_repository", "update_issue_labels", "react_issue", "update_issue_body", "update_issue_title", "publish_attachments", "merge_change_request"];
47
+ const capabilities = ["read_issue", "push_branch", "propose_change", "comment_issue", "search_issues", "read_change_request", "read_repository", "update_issue_labels", "react_issue", "update_issue_body", "update_issue_title", "publish_attachments", "merge_change_request", "comment_change_request"];
48
48
  const result = await base(`workspace: [{key: source, path: ./code}]\nactions: [{key: repo, kind: gitrepo, capabilities: ${JSON.stringify(capabilities)}}]\n`);
49
49
  assert.equal(result.ok, true);
50
50
  assert.deepEqual(result.draft.actions[0].capabilities, capabilities);