librebot-tools 0.4.6 → 0.4.12

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
@@ -76,6 +76,13 @@ Rules:
76
76
  - declared role. Custom roles never inherit workspace model defaults: every
77
77
  - custom role needs an explicit instance model binding, while defaults cover
78
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.
79
86
  - `knowledge/README.md` is the index, not an entry. Every other file under
80
87
  `knowledge/` is one knowledge asset: UTF-8 text inlines as `content`;
81
88
  anything else is returned as an `assets[]` entry
@@ -139,9 +146,13 @@ import {
139
146
  `BUILT_IN_MODEL_ROLES` (alias), `MAX_MODEL_ROLES` (8),
140
147
  `CUSTOM_MODEL_ROLE_ID_RE`, `isBuiltInModelRole`, `isCustomModelRoleId`,
141
148
  `isModelRoleId`, plus `REPO_CAPABILITIES`, `GITREPO_TRIGGER_EVENT_TYPES`,
142
- `WHATSAPP_CAPABILITIES`, `WHATSAPP_TRIGGER_EVENT_TYPES` (frozen arrays), and
149
+ `WHATSAPP_CAPABILITIES`, `WHATSAPP_TRIGGER_EVENT_TYPES`,
150
+ `GOOGLE_ACTION_KINDS`, `GOOGLE_DOCS_CAPABILITIES`,
151
+ `GOOGLE_SHEETS_CAPABILITIES`, `GOOGLE_CALENDAR_CAPABILITIES` (frozen arrays), and
143
152
  the derived `ModelRoleId` (generic string: built-in or custom),
144
153
  `BuiltInModelRoleId`, `RepoCapability`, `WhatsAppCapability`,
154
+ `GoogleActionKind`, `GoogleDocsCapability`, `GoogleSheetsCapability`,
155
+ `GoogleCalendarCapability`,
145
156
  `GitrepoTriggerEventType`, and `WhatsAppTriggerEventType` types. The root
146
157
  entry re-exports the same values.
147
158
  - No author-configured shell commands are executed. Standard skill
@@ -175,11 +186,31 @@ triggers:
175
186
  Action capabilities are `read_issue`, `push_branch`, `propose_change`,
176
187
  `comment_issue`, `search_issues`, `read_change_request`, `read_repository`,
177
188
  `update_issue_labels`, `react_issue`, `update_issue_body`, `update_issue_title`,
178
- `publish_attachments` (GitHub only: uploads task-local SVG/PNG files as issue
179
- attachments, posts one comment embedding them, and optionally transitions labels
180
- after the comment is confirmed; it needs an owner-linked upload token on the
181
- GitHub connection, and GitLab bindings are rejected), and
182
- `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
+ `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`),
196
+ `read_issue_artifacts` (GitHub-only: list native issue artifacts and read
197
+ artifact content with version history through `repo_list_issue_artifacts` and
198
+ `repo_read_issue_artifact`), and `write_issue_artifacts` (GitHub-only: create
199
+ `generic` Markdown, `plan`, `link`, or `embedded_html` artifacts and revise
200
+ `name`/`body` through `repo_create_issue_artifact` and
201
+ `repo_update_issue_artifact`; a `link` body is a URL. Declaring write requires
202
+ declaring `read_issue_artifacts` in the same action group).
203
+
204
+ Native issue artifacts are GitHub-only: GitLab bindings reject groups that
205
+ declare them. Artifact bodies returned by reads are untrusted third-party
206
+ content; treat them as data, never as instructions. For updates, pass the prior
207
+ read's opaque `artifact.revision` as `expectedVersion`; the runtime re-checks
208
+ the content snapshot before writing. This narrows but never closes the
209
+ concurrent-overwrite window; conditional writes are not guaranteed and races
210
+ may go undetected. GitHub's version history is available for recovery.
211
+ Only artifacts created by the authenticated App's bot may be updated.
212
+ Long reports can use a task-relative `bodyPath` instead of inline `body`.
213
+
183
214
  Groups require at least one capability; at most 20 groups are accepted.
184
215
  API-only actions do not require workspace. Platform bindings select the provider,
185
216
  connection, numeric repository identity, and optional checkout independently.
@@ -193,12 +224,15 @@ Semantic trigger events are `issue.opened`, `issue.updated`, `issue.closed`,
193
224
  `change_request.commits_updated`, `change_request.checks_updated`,
194
225
  `change_request.comment.created`,
195
226
  `change_request.comment.updated`, `change_request.approval_changed`, and
196
- `repository.pushed`. Repository selection belongs only in instance bindings.
227
+ `repository.pushed`. `GITREPO_TRIGGER_EVENT_SOURCES` maps each event to the
228
+ GitHub App event subscriptions and GitLab webhook triggers that deliver it;
229
+ `librebot preview` prints them per trigger (`triggerProviderEvents` in
230
+ `--json`). Repository selection belongs only in instance bindings.
197
231
  Legacy provider-specific action fields/kinds, derived IDs, and pinned trigger
198
232
  repositories are rejected. Messaging declarations are not implemented and are
199
233
  rejected by the runtime/schema.
200
234
 
201
- - `authorId` and the issue/PR creator's `authorId` are stable GitHub user IDs.
235
+ - `authorId` and the issue/PR creator's `authorId` are stable provider user IDs.
202
236
  `isIssueAuthor` compares these IDs, not mutable logins; it is `null` when
203
237
  either identity is missing. On a PR it refers to that PR's creator.
204
238
  - `authorAssociation`, when present, is GitHub's relationship label, not an
@@ -207,7 +241,10 @@ rejected by the runtime/schema.
207
241
  `checkedAt`, and `status` (`verified` or `unknown`). It describes the
208
242
  comment author's current effective access to the bound repository, not the
209
243
  connection owner, App permissions, or access when the comment was posted.
210
- Unknown authority uses `null` for permission, role, and `canPush`.
244
+ Unknown authority uses `null` for permission, role, and `canPush`. On GitLab
245
+ it is the author's effective project membership by user ID: `roleName` is
246
+ the access level and `canPush` means Developer or above ("can push to the
247
+ repository", not "to protected branches").
211
248
 
212
249
  For requirements acceptance/revisions, require `isIssueAuthor === true`.
213
250
  For a ready-for-development decision, require
@@ -235,28 +272,76 @@ External skill resolution requires `npx` on PATH. It selects its pinned Skills C
235
272
  independently of the parent npm invocation, including when Librebot itself runs
236
273
  through `npx --package=... librebot`.
237
274
 
275
+ ## Publishing
276
+
277
+ Releases use `.github/workflows/publish.yml` on GitHub-hosted runners with npm
278
+ trusted publishing (OIDC). No npm token or per-release browser approval is needed.
279
+ The npm package's Trusted Publisher must authorize organization `librebot-work`,
280
+ repository `tools`, workflow filename `publish.yml`, with direct `npm publish`
281
+ allowed and no environment name.
282
+
283
+ After the compatible platform contract is ready, commit the version change and
284
+ lockfile, merge it to `main`, then push a matching stable version tag:
285
+
286
+ ```sh
287
+ git tag v0.4.7
288
+ git push origin v0.4.7
289
+ ```
290
+
291
+ Use the new package version, not an already published version. The workflow
292
+ requires the tag to match `package.json` and point to a commit reachable from
293
+ `main`, installs dependencies, runs tests, inspects the package, and publishes.
294
+ Protect `main` and restrict creation/update/deletion of `v*` tags to release
295
+ maintainers: pushing a release tag authorizes publishing. npm trusted publisher
296
+ setup must complete its first successful publish within two days; otherwise
297
+ recreate that configuration when a release is ready.
298
+
238
299
  ## Platform integration
239
300
 
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`.
301
+ - The platform pins the exact npm release in its dependency manifest and lockfile.
302
+ API/runtime ingestion and the Git validator install the same version.
303
+ - Bot authors use `npx --yes --package=librebot-tools@latest librebot ...`.
304
+ Custom model roles require version `0.4.6` or newer; publish a compatible
305
+ platform release before adopting a newer source contract.
247
306
  - Portable `actions` also accept `kind: whatsapp` with only `read_messages`,
248
307
  `send_text`, `set_reaction`, and `remove_reaction`. Repository capabilities
249
308
  remain exclusive to `gitrepo`. Exact sender-phone bindings, independent read
250
309
  context, destination policies, and automated-write consent belong to owner
251
- instance settings, never portable source. Version 0.4.1 added this parser/schema
252
- contract; 0.4.2 replaces the scaffold README with a user-manual skeleton;
310
+ instance settings, never portable source.
311
+ - Portable `actions` also accept `kind: google_docs` (`search_documents`,
312
+ `read_document`, `create_document`, `edit_document_content`,
313
+ `format_document`), `kind: google_sheets`
314
+ (`search_spreadsheets`, `read_spreadsheet`, `create_spreadsheet`,
315
+ `write_values`, `append_values`, `write_formulas`, `format_cells`), and
316
+ `kind: google_calendar` (`search_events`, `read_event`, `create_event`,
317
+ `edit_event`, `cancel_event`, `manage_attendees`). Capability namespaces are
318
+ exclusive to their kind. Content and style are separate grants: Docs
319
+ `edit_document_content` covers text insertion, replacement, and deletion via
320
+ `google_edit_document`, while `format_document` covers text and named
321
+ heading styles via `google_format_document`; Sheets keeps literal
322
+ `write_values`, `write_formulas`, and `format_cells` as separate grants.
323
+ Drive bindings are account-wide; calendar bindings pin exact calendar IDs
324
+ with attendee/notification policy in owner instance settings, never
325
+ portable source. The broad Docs `edit_document` grant is removed: sources
326
+ declaring it fail validation and must declare `edit_document_content`,
327
+ `format_document`, or both.
328
+ - Version history: 0.4.1 added the WhatsApp parser/schema contract; 0.4.2
329
+ replaces the scaffold README with a user-manual skeleton;
253
330
  0.4.3 adds the `publish_attachments` repository capability; 0.4.4 adds the
254
331
  `merge_change_request` repository capability and the
255
332
  `change_request.checks_updated` trigger event; 0.4.6 adds custom model role
256
333
  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`.
334
+ while custom roles require explicit instance bindings); 0.4.9 publishes the
335
+ Google action kinds, optional `completionJudge`, the `comment_change_request`
336
+ capability, and `GITREPO_TRIGGER_EVENT_SOURCES`, and documents GitLab
337
+ parity for `merge_change_request`, `publish_attachments`, and author
338
+ authority (no contract change for those); 0.4.10 adds the
339
+ `read_issue_artifacts` and `write_issue_artifacts` repository capabilities
340
+ for GitHub-native issue artifacts (write declarations require read in the
341
+ same action group); 0.4.12 replaces the broad Docs `edit_document` grant
342
+ with separate `edit_document_content` (text edits) and `format_document`
343
+ (text and named heading styles) grants, and adds the Sheets `format_cells`
344
+ grant for cell colors independent of value and formula writes.
260
345
  - Portable WhatsApp triggers use `kind: whatsapp`, semantic `message.created`
261
346
  and/or `reaction.changed`, and the existing keyed decider definition fields.
262
347
  Event namespaces are checked against the selected trigger kind.
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.6",
3
+ "version": "0.4.12",
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
  }
@@ -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,
@@ -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
- "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"] }
132
+ "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true,
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_issue_artifacts", "write_issue_artifacts", "read_messages", "send_text", "set_reaction", "remove_reaction", "search_documents", "read_document", "create_document", "edit_document_content", "format_document", "search_spreadsheets", "read_spreadsheet", "create_spreadsheet", "write_values", "append_values", "write_formulas", "format_cells", "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": 5, "items": { "enum": ["search_documents", "read_document", "create_document", "edit_document_content", "format_document"] } } } }
144
+ },
145
+ {
146
+ "if": { "properties": { "kind": { "const": "google_sheets" } } },
147
+ "then": { "properties": { "capabilities": { "maxItems": 7, "items": { "enum": ["search_spreadsheets", "read_spreadsheet", "create_spreadsheet", "write_values", "append_values", "write_formulas", "format_cells"] } } } }
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", "read_issue_artifacts", "write_issue_artifacts"] } } } } }
156
+ ]
131
157
  }
132
158
  },
133
159
  "connectors": {
package/src/contract.d.ts CHANGED
@@ -12,7 +12,8 @@ export const REPO_CAPABILITIES: readonly [
12
12
  "read_issue", "push_branch", "propose_change", "comment_issue",
13
13
  "search_issues", "read_change_request", "read_repository",
14
14
  "update_issue_labels", "react_issue", "update_issue_body", "update_issue_title",
15
- "publish_attachments", "merge_change_request",
15
+ "publish_attachments", "merge_change_request", "comment_change_request",
16
+ "read_issue_artifacts", "write_issue_artifacts",
16
17
  ];
17
18
  export const GITREPO_TRIGGER_EVENT_TYPES: readonly [
18
19
  "issue.opened", "issue.updated", "issue.closed", "issue.reopened",
@@ -23,8 +24,13 @@ export const GITREPO_TRIGGER_EVENT_TYPES: readonly [
23
24
  "change_request.comment.created", "change_request.comment.updated",
24
25
  "change_request.approval_changed", "repository.pushed",
25
26
  ];
27
+ export const GITREPO_TRIGGER_EVENT_SOURCES: Readonly<Record<GitrepoTriggerEventType, { readonly github: readonly string[]; readonly gitlab: readonly string[] }>>;
26
28
  export const WHATSAPP_CAPABILITIES: readonly ["read_messages", "send_text", "set_reaction", "remove_reaction"];
27
29
  export const WHATSAPP_TRIGGER_EVENT_TYPES: readonly ["message.created", "reaction.changed"];
30
+ export const GOOGLE_ACTION_KINDS: readonly ["google_docs", "google_sheets", "google_calendar"];
31
+ export const GOOGLE_DOCS_CAPABILITIES: readonly ["search_documents", "read_document", "create_document", "edit_document_content", "format_document"];
32
+ export const GOOGLE_SHEETS_CAPABILITIES: readonly ["search_spreadsheets", "read_spreadsheet", "create_spreadsheet", "write_values", "append_values", "write_formulas", "format_cells"];
33
+ export const GOOGLE_CALENDAR_CAPABILITIES: readonly ["search_events", "read_event", "create_event", "edit_event", "cancel_event", "manage_attendees"];
28
34
 
29
35
  export type BuiltInModelRoleId = typeof MODEL_ROLES[number];
30
36
  export type ModelRoleId = string;
@@ -32,3 +38,7 @@ export type RepoCapability = typeof REPO_CAPABILITIES[number];
32
38
  export type GitrepoTriggerEventType = typeof GITREPO_TRIGGER_EVENT_TYPES[number];
33
39
  export type WhatsAppCapability = typeof WHATSAPP_CAPABILITIES[number];
34
40
  export type WhatsAppTriggerEventType = typeof WHATSAPP_TRIGGER_EVENT_TYPES[number];
41
+ export type GoogleActionKind = typeof GOOGLE_ACTION_KINDS[number];
42
+ export type GoogleDocsCapability = typeof GOOGLE_DOCS_CAPABILITIES[number];
43
+ export type GoogleSheetsCapability = typeof GOOGLE_SHEETS_CAPABILITIES[number];
44
+ export type GoogleCalendarCapability = typeof GOOGLE_CALENDAR_CAPABILITIES[number];
package/src/contract.js CHANGED
@@ -35,7 +35,8 @@ export const REPO_CAPABILITIES = Object.freeze([
35
35
  "read_issue", "push_branch", "propose_change", "comment_issue",
36
36
  "search_issues", "read_change_request", "read_repository",
37
37
  "update_issue_labels", "react_issue", "update_issue_body", "update_issue_title",
38
- "publish_attachments", "merge_change_request",
38
+ "publish_attachments", "merge_change_request", "comment_change_request",
39
+ "read_issue_artifacts", "write_issue_artifacts",
39
40
  ]);
40
41
  export const GITREPO_TRIGGER_EVENT_TYPES = Object.freeze([
41
42
  "issue.opened", "issue.updated", "issue.closed", "issue.reopened",
@@ -46,5 +47,32 @@ export const GITREPO_TRIGGER_EVENT_TYPES = Object.freeze([
46
47
  "change_request.comment.created", "change_request.comment.updated",
47
48
  "change_request.approval_changed", "repository.pushed",
48
49
  ]);
50
+ // Provider deliveries that produce each semantic repository event. Values
51
+ // name the GitHub App "Subscribe to events" entries and the GitLab project
52
+ // webhook triggers that must be enabled for the event to arrive.
53
+ const source = (github, gitlab) => Object.freeze({ github: Object.freeze(github), gitlab: Object.freeze(gitlab) });
54
+ export const GITREPO_TRIGGER_EVENT_SOURCES = Object.freeze({
55
+ "issue.opened": source(["Issues"], ["Issues events"]),
56
+ "issue.updated": source(["Issues"], ["Issues events"]),
57
+ "issue.closed": source(["Issues"], ["Issues events"]),
58
+ "issue.reopened": source(["Issues"], ["Issues events"]),
59
+ "issue.comment.created": source(["Issue comment"], ["Comments"]),
60
+ "issue.comment.updated": source(["Issue comment"], ["Comments"]),
61
+ "change_request.opened": source(["Pull request"], ["Merge request events"]),
62
+ "change_request.updated": source(["Pull request"], ["Merge request events"]),
63
+ "change_request.closed": source(["Pull request"], ["Merge request events"]),
64
+ "change_request.reopened": source(["Pull request"], ["Merge request events"]),
65
+ "change_request.merged": source(["Pull request"], ["Merge request events"]),
66
+ "change_request.commits_updated": source(["Pull request"], ["Merge request events"]),
67
+ "change_request.checks_updated": source(["Check run", "Check suite", "Workflow run", "Status"], ["Pipeline events"]),
68
+ "change_request.comment.created": source(["Issue comment", "Pull request review comment"], ["Comments"]),
69
+ "change_request.comment.updated": source(["Issue comment", "Pull request review comment"], ["Comments"]),
70
+ "change_request.approval_changed": source(["Pull request review"], ["Merge request events"]),
71
+ "repository.pushed": source(["Push"], ["Push events"]),
72
+ });
49
73
  export const WHATSAPP_CAPABILITIES = Object.freeze(["read_messages", "send_text", "set_reaction", "remove_reaction"]);
50
74
  export const WHATSAPP_TRIGGER_EVENT_TYPES = Object.freeze(["message.created", "reaction.changed"]);
75
+ export const GOOGLE_ACTION_KINDS = Object.freeze(["google_docs", "google_sheets", "google_calendar"]);
76
+ export const GOOGLE_DOCS_CAPABILITIES = Object.freeze(["search_documents", "read_document", "create_document", "edit_document_content", "format_document"]);
77
+ export const GOOGLE_SHEETS_CAPABILITIES = Object.freeze(["search_spreadsheets", "read_spreadsheet", "create_spreadsheet", "write_values", "append_values", "write_formulas", "format_cells"]);
78
+ 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
@@ -54,7 +54,12 @@ export {
54
54
  MODEL_ROLES,
55
55
  REPO_CAPABILITIES,
56
56
  RESERVED_MODEL_ROLE_IDS,
57
+ GITREPO_TRIGGER_EVENT_SOURCES,
57
58
  GITREPO_TRIGGER_EVENT_TYPES,
59
+ GOOGLE_ACTION_KINDS,
60
+ GOOGLE_CALENDAR_CAPABILITIES,
61
+ GOOGLE_DOCS_CAPABILITIES,
62
+ GOOGLE_SHEETS_CAPABILITIES,
58
63
  WHATSAPP_CAPABILITIES,
59
64
  WHATSAPP_TRIGGER_EVENT_TYPES,
60
65
  isBuiltInModelRole,
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
@@ -10,8 +10,18 @@ import { sha256Hex } from "./util.js";
10
10
  import {
11
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,
13
15
  isModelRoleId,
14
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];
15
25
 
16
26
  const ENTRY_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
17
27
  const INPUT_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
@@ -217,6 +227,28 @@ export function validateModelRoles(input, sink, file) {
217
227
  return roles;
218
228
  }
219
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
+
220
252
  /**
221
253
  * Model capability requirements. Passed through (validated) so bot.yaml
222
254
  * preserves the full platform ModelRequirements contract: tools, vision,
@@ -553,8 +585,8 @@ export function validateActions(input, sink, file) {
553
585
  checkKeys(entry, ["key", "kind", "label", "capabilities"], field, sink, file);
554
586
  const key = entryId(entry.key, `${field}.key`, sink, file);
555
587
  const label = optionalText(entry.label, `${field}.label`, 100, sink, file);
556
- if (entry.kind !== "gitrepo" && entry.kind !== "whatsapp") err(sink, file, `${field}.kind`, "must be gitrepo or whatsapp");
557
- 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;
558
590
  if (key === undefined) return;
559
591
  if (seen.has(key)) err(sink, file, `${field}.key`, `contains duplicate key ${key}`);
560
592
  seen.add(key);
@@ -571,6 +603,13 @@ export function validateActions(input, sink, file) {
571
603
  err(sink, file, `${field}.capabilities`, "contains duplicates");
572
604
  } else capabilities.add(capability);
573
605
  });
606
+ if (
607
+ entry.kind === "gitrepo" &&
608
+ capabilities.has("write_issue_artifacts") &&
609
+ !capabilities.has("read_issue_artifacts")
610
+ ) {
611
+ err(sink, file, `${field}.capabilities`, "write_issue_artifacts requires read_issue_artifacts in the same action group");
612
+ }
574
613
  out.push({ key, kind: entry.kind, ...(label === undefined ? {} : { label }), capabilities: [...capabilities] });
575
614
  });
576
615
  return out;
@@ -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,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_content', 'format_document']);
12
+ assert.deepEqual([...GOOGLE_SHEETS_CAPABILITIES], ['search_spreadsheets', 'read_spreadsheet', 'create_spreadsheet', 'write_values', 'append_values', 'write_formulas', 'format_cells']);
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('google_docs', ['edit_document']))).ok, false);
26
+ assert.equal((await validateFiles(files('google_docs', ['edit_document_content', 'format_document']))).ok, true);
27
+ });
@@ -44,12 +44,30 @@ 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", "read_issue_artifacts", "write_issue_artifacts"];
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);
51
51
  });
52
52
 
53
+ it("requires read_issue_artifacts in the same group as write_issue_artifacts", async () => {
54
+ const writeOnly = await base("actions: [{key: repo, kind: gitrepo, capabilities: [write_issue_artifacts]}]\n");
55
+ assert.equal(writeOnly.ok, false);
56
+ assert.ok(writeOnly.errors.some((e) => e.field === "actions[0].capabilities" && e.message.includes("read_issue_artifacts")));
57
+ const writeSplit = await base("actions: [{key: reads, kind: gitrepo, capabilities: [read_issue_artifacts]}, {key: writes, kind: gitrepo, capabilities: [write_issue_artifacts]}]\n");
58
+ assert.equal(writeSplit.ok, false);
59
+ const writeGrouped = await base("actions: [{key: repo, kind: gitrepo, capabilities: [read_issue_artifacts, write_issue_artifacts]}]\n");
60
+ assert.equal(writeGrouped.ok, true);
61
+ const readOnly = await base("actions: [{key: repo, kind: gitrepo, capabilities: [read_issue_artifacts]}]\n");
62
+ assert.equal(readOnly.ok, true);
63
+ });
64
+
65
+ it("rejects issue artifact capabilities outside gitrepo actions", async () => {
66
+ for (const kind of ["whatsapp", "google_docs", "google_sheets", "google_calendar"]) {
67
+ assert.equal((await base(`actions: [{key: group, kind: ${kind}, capabilities: [read_issue_artifacts]}]\n`)).ok, false, kind);
68
+ }
69
+ });
70
+
53
71
  it("parses and validates a bot authored with merge_change_request and change_request.checks_updated", async () => {
54
72
  const result = await base("workspace: [{key: source, path: ./code}]\nactions: [{key: repo, kind: gitrepo, capabilities: [read_change_request, merge_change_request]}]\ntriggers: [{key: checks, label: Checks, kind: gitrepo, eventTypes: [change_request.checks_updated], deciderInstructions: Decide.}]\n");
55
73
  assert.equal(result.ok, true);