@lanework/contracts 0.0.0-stage → 0.4.0

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.
@@ -0,0 +1,590 @@
1
+ // The 14 board tools (FE-152): names, descriptions and parameters as the
2
+ // cloud MCP (`mcp.lanework.dev`) and the offline one (`electron/mcp-local/`)
3
+ // both serve them, and the answer each one returns.
4
+ //
5
+ // NOTE: The cloud is the reference (BE-27): these texts and schemas are what
6
+ // it served before it switched to serving this file, worded so they hold on
7
+ // both servers. A feature only the cloud has (`evidence`, `stale`, `retro`)
8
+ // is still described here; the offline server accepts its parameters and
9
+ // does without the rest. `board_id` is the board's `workspaceId` on both.
10
+
11
+ import type {
12
+ BoardSummary,
13
+ Card,
14
+ CardDetail,
15
+ ChecklistItem,
16
+ ColumnRole,
17
+ Dispatch,
18
+ TagPolicy,
19
+ } from "../boards";
20
+ import type { Checkpoint, LatestCheckpoint } from "../checkpoints";
21
+ import type { ToolContract, ToolParam } from "./schema";
22
+
23
+ export type BoardToolName =
24
+ | "list_boards"
25
+ | "create_board"
26
+ | "link_repo"
27
+ | "board_summary"
28
+ | "list_reviews"
29
+ | "get_review"
30
+ | "create_review"
31
+ | "update_review"
32
+ | "toggle_item"
33
+ | "review_card"
34
+ | "set_status"
35
+ | "delete_review"
36
+ | "checkpoint"
37
+ | "lifecycle_status";
38
+
39
+ // ── Shared parameter shapes ─────────────────────────────────────────────────
40
+
41
+ const BOARD_ID: ToolParam = {
42
+ type: "string",
43
+ description: "Workspace id of the board, from `list_boards`.",
44
+ };
45
+ const CARD: ToolParam = {
46
+ type: "string",
47
+ description: "Card id or task id, e.g. BE-07",
48
+ };
49
+ const REPO: ToolParam = {
50
+ type: "string",
51
+ description:
52
+ "Output of `git remote get-url origin`, unmodified — ssh or https",
53
+ };
54
+ const PRIORITY: ToolParam = {
55
+ type: "string",
56
+ enum: ["low", "medium", "high"],
57
+ };
58
+ const ASSIGNEES: ToolParam = {
59
+ type: "object",
60
+ properties: {
61
+ users: { type: "string[]" },
62
+ agents: { type: "string[]" },
63
+ },
64
+ };
65
+ /** One stream of a card (BE-19); `description` differs between create and update. */
66
+ const streams = (description: string): ToolParam => ({
67
+ type: "object[]",
68
+ description,
69
+ properties: {
70
+ key: {
71
+ type: "string",
72
+ description: "W0, W1, … — minted for you if omitted",
73
+ },
74
+ title: { type: "string", description: "One line, e.g. 'MCP tools'" },
75
+ goal: {
76
+ type: "string",
77
+ description:
78
+ "What the sub-agent must deliver, self-contained: it starts with none of your context",
79
+ },
80
+ role: { type: "string", enum: ["research", "implement", "test"] },
81
+ owns: {
82
+ type: "string[]",
83
+ description:
84
+ "Repo-relative paths it alone writes; a directory ends in '/'. No globs. Required unless role is research",
85
+ },
86
+ reads: { type: "string[]", description: "Paths it should read first" },
87
+ depends_on: {
88
+ type: "string[]",
89
+ description: "Stream keys that must finish before this one starts",
90
+ },
91
+ isolation: {
92
+ type: "string",
93
+ enum: ["worktree", "shared"],
94
+ description:
95
+ "worktree (default): its own git worktree. shared: the lead's checkout, for read-only research",
96
+ },
97
+ },
98
+ required: ["title", "goal", "role"],
99
+ });
100
+
101
+ // ── The tools ───────────────────────────────────────────────────────────────
102
+
103
+ /** The board tools, in the order `tools/list` advertises them. */
104
+ export const BOARD_TOOLS: readonly ToolContract<BoardToolName>[] = [
105
+ {
106
+ name: "list_boards",
107
+ title: "List boards",
108
+ description:
109
+ "Every board you can see, with its workspace id and linked repo. Call this FIRST: every other tool needs a `board_id` and there is no default. Pass `repo` (your `git remote get-url origin`, as is) to get only the board(s) linked to the repo you are working in.",
110
+ readOnly: true,
111
+ properties: {
112
+ repo: REPO,
113
+ },
114
+ },
115
+ {
116
+ name: "create_board",
117
+ title: "Create a board for this repo",
118
+ description:
119
+ "Create a new board and link it to the git repo in one step. ONLY after the user chose to create a new board (offered next to the existing ones when list_boards({ repo }) found none) — never on your own initiative. Suggest `owner/name` from the remote as the name. Returns board_id for every other tool.",
120
+ readOnly: false,
121
+ properties: {
122
+ name: {
123
+ type: "string",
124
+ description: "Board name the user agreed to, e.g. `acme/widgets`",
125
+ },
126
+ slug: {
127
+ type: "string",
128
+ description:
129
+ "Lower-case hyphenated key. Omit to derive it from the name.",
130
+ },
131
+ repo: REPO,
132
+ },
133
+ required: ["name", "repo"],
134
+ },
135
+ {
136
+ name: "link_repo",
137
+ title: "Link a board to a repo",
138
+ description:
139
+ "Link a board to a git repo so list_boards({ repo }) finds it. Only call this after the USER has confirmed which board the repo belongs to — never on a guess from the board's name. Owner only. Refuses to replace a different linked repo unless `replace` is true.",
140
+ readOnly: false,
141
+ properties: {
142
+ board_id: BOARD_ID,
143
+ repo: REPO,
144
+ replace: {
145
+ type: "boolean",
146
+ description:
147
+ "Move the link from the repo it has now. Only when the user asked.",
148
+ },
149
+ },
150
+ required: ["board_id", "repo"],
151
+ },
152
+ {
153
+ name: "board_summary",
154
+ title: "Board summary",
155
+ description:
156
+ "Lane-by-lane counts of live cards, plus the board's categories and tag policy. Read this before creating a card so its category and tags match what the board already uses. `stale` counts in-progress cards no agent has touched for over 2 hours — list_reviews flags which ones.",
157
+ readOnly: true,
158
+ properties: {
159
+ board_id: BOARD_ID,
160
+ },
161
+ required: ["board_id"],
162
+ },
163
+ {
164
+ name: "lifecycle_status",
165
+ title: "Lifecycle status",
166
+ description:
167
+ "What the board is waiting on: cards whose decisions are not all ticked (waiting), cards cleared to start (ready), cards being worked (in flight), and cards waiting for a human to review (review). Call this to pick up work rather than guessing from a list.",
168
+ readOnly: true,
169
+ properties: {
170
+ board_id: BOARD_ID,
171
+ },
172
+ required: ["board_id"],
173
+ },
174
+ {
175
+ name: "list_reviews",
176
+ title: "List cards",
177
+ description:
178
+ "Cards on a board, in the order the board draws them. Filter by lane, category, tag or priority. Archived cards are excluded unless asked for. Each card's `stale` is `{ since, lastAgent }` for in-progress work no agent has touched for over 2 hours, else null.",
179
+ readOnly: true,
180
+ properties: {
181
+ board_id: BOARD_ID,
182
+ column: {
183
+ type: "string",
184
+ description: "Lane key, e.g. todo | processing | done",
185
+ },
186
+ category: { type: "string", description: "Category key, e.g. backend" },
187
+ tag: { type: "string" },
188
+ priority: PRIORITY,
189
+ task_id: {
190
+ type: "string",
191
+ description:
192
+ "Exact task id such as BE-07 — matched on the field, not the title",
193
+ },
194
+ include_archived: { type: "boolean" },
195
+ limit: { type: "integer", minimum: 1, maximum: 200 },
196
+ },
197
+ required: ["board_id"],
198
+ },
199
+ {
200
+ name: "get_review",
201
+ title: "Get a card",
202
+ description:
203
+ "One card with its checklist, tags, assignees, links and `streams`, plus the latest `checkpoint` another agent left on it (or null) and `dispatch` — the card's run plan, `{ waves, briefs }`, or null when it has no streams. With a dispatch you are the lead: run it wave by wave, handing each stream's sub-agent its brief verbatim. `item.stale` is `{ since, lastAgent }` when the card sits in progress with no agent activity for over 2 hours (or null): resume it from its checkpoint. `card` takes either the card's id or its task id (e.g. BE-07).",
204
+ readOnly: true,
205
+ properties: {
206
+ board_id: BOARD_ID,
207
+ card: CARD,
208
+ },
209
+ required: ["board_id", "card"],
210
+ },
211
+ {
212
+ name: "create_review",
213
+ title: "Create a card",
214
+ description:
215
+ "Open a new card on a board. Setting `category` also mints the card's permanent task id (BE-07 and so on), so pass it unless you mean to leave the card unfiled. Split a card into `streams` only when it touches two or more independent write areas (e.g. db + mcp + desktop); a 1–2 file card has none. Shared files (types, schema, contracts) go in a W0 stream the others depend on. At most 4 streams can run in one wave, no two streams that run together may own the same path, and every stream needs at least one verify item tagged with its key (`checklist[].stream`). Untagged verify items are the lead's: gate, build, e2e. Isolation defaults to worktree.",
216
+ readOnly: false,
217
+ properties: {
218
+ board_id: BOARD_ID,
219
+ title: { type: "string" },
220
+ body: { type: "string", description: "Markdown body of the card" },
221
+ type: { type: "string", enum: ["epic", "issue", "task"] },
222
+ column: {
223
+ type: "string",
224
+ description: "Lane key; defaults to the board's start lane",
225
+ },
226
+ category: {
227
+ type: "string",
228
+ description: "Category key — this is what mints the task id",
229
+ },
230
+ priority: PRIORITY,
231
+ tags: {
232
+ type: "string[]",
233
+ description: "Reuse the board's existing tags",
234
+ },
235
+ assignees: ASSIGNEES,
236
+ checklist: {
237
+ type: "object[]",
238
+ properties: {
239
+ section: { type: "string", enum: ["decisions", "verify"] },
240
+ text: { type: "string" },
241
+ key: {
242
+ type: "string",
243
+ description: "Stable id like D1 — minted for you if omitted",
244
+ },
245
+ checked: { type: "boolean" },
246
+ group: {
247
+ type: "string",
248
+ description: "Same value on 2+ items makes them a 'pick ONE' group",
249
+ },
250
+ note: { type: "string" },
251
+ stream: {
252
+ type: "string",
253
+ description:
254
+ "Verify items only: the stream key (W1…) this item proves. Each stream needs one",
255
+ },
256
+ },
257
+ required: ["section", "text"],
258
+ },
259
+ streams: streams(
260
+ "Sub-agent jobs a lead runs in waves (BE-19). Omit for a card one agent works end to end",
261
+ ),
262
+ parent_id: { type: "string" },
263
+ },
264
+ required: ["board_id", "title"],
265
+ },
266
+ {
267
+ name: "update_review",
268
+ title: "Update a card",
269
+ description:
270
+ "Patch a card's title, body, priority, tags, assignees, category or streams. Omitted fields are left alone; `tags`, `assignees` and `streams` replace what is there (`streams: []` clears the plan). Streams are checked against the card's checklist: each one needs a verify item tagged with its key — tag them in the same call with `checklist_streams`, or one at a time with toggle_item's `stream`. Use set_status to move a card between lanes. Split a card into `streams` only when it touches two or more independent write areas (e.g. db + mcp + desktop); a 1–2 file card has none. Shared files (types, schema, contracts) go in a W0 stream the others depend on. At most 4 streams can run in one wave, no two streams that run together may own the same path, and every stream needs at least one verify item tagged with its key (`checklist[].stream`). Untagged verify items are the lead's: gate, build, e2e. Isolation defaults to worktree.",
271
+ readOnly: false,
272
+ properties: {
273
+ board_id: BOARD_ID,
274
+ card: CARD,
275
+ title: { type: "string" },
276
+ body: { type: "string" },
277
+ priority: PRIORITY,
278
+ tags: { type: "string[]", description: "Replaces the tag list" },
279
+ category: {
280
+ type: "string",
281
+ description: "Setting this on a card with no task id yet mints one",
282
+ },
283
+ assignees: ASSIGNEES,
284
+ streams: streams(
285
+ "Replaces the whole stream list; pass expected_revision so a concurrent edit is not lost",
286
+ ),
287
+ checklist_streams: {
288
+ type: "string-map",
289
+ description:
290
+ 'Tag verify items with the stream they prove, applied with `streams` in one write: { V3: "W1", V4: null }',
291
+ },
292
+ expected_revision: {
293
+ type: "integer",
294
+ description:
295
+ "Refuse the write unless the card is still at this revision — pass what get_review returned to avoid overwriting a concurrent edit.",
296
+ },
297
+ },
298
+ required: ["board_id", "card"],
299
+ },
300
+ {
301
+ name: "set_status",
302
+ title: "Set a card's lane",
303
+ description:
304
+ "Move a card to another lane — the board's status columns. Use list_boards then list_reviews to see the lane keys this board has. Finished, verified work goes to the review lane, not done. Review and done refuse a card while a verify item you ticked lacks passing `evidence` (toggle_item). Moving into review may return `retro` signals: propose lessons and ask the user before writing any.",
305
+ readOnly: false,
306
+ properties: {
307
+ board_id: BOARD_ID,
308
+ card: CARD,
309
+ status: {
310
+ type: "string",
311
+ description: "Lane key, e.g. todo | processing | review | done",
312
+ },
313
+ reason: {
314
+ type: "string",
315
+ maxLength: 2000,
316
+ description:
317
+ "What to change — required when sending a card back from review to an in-progress lane, ignored on any other move.",
318
+ },
319
+ },
320
+ required: ["board_id", "card", "status"],
321
+ },
322
+ {
323
+ name: "toggle_item",
324
+ title: "Toggle a checklist item",
325
+ description:
326
+ "Tick or untick one checklist box on a card, and optionally leave a note under it, or tag a verify item with the stream it proves (BE-19). `key` is the item's stable id, e.g. D1 or V3. Ticking a verify item, send `evidence`. Answers with that box and the card in one line, not the whole card: get_review has the rest.",
327
+ readOnly: false,
328
+ properties: {
329
+ board_id: BOARD_ID,
330
+ card: CARD,
331
+ key: { type: "string", description: "Checklist item key, e.g. D1 or V3" },
332
+ checked: { type: "boolean", description: "Omit to leave the tick alone" },
333
+ note: {
334
+ type: "string",
335
+ description: "A note recorded under the item; empty string clears it",
336
+ },
337
+ text: {
338
+ type: "string",
339
+ description: "Reword the item, keeping its key and tick",
340
+ },
341
+ stream: {
342
+ type: "nullable-string",
343
+ description:
344
+ "Verify items only: the stream key (W1…) this item proves; null removes the tag",
345
+ },
346
+ evidence: {
347
+ type: "object",
348
+ description:
349
+ "Verify items: what you ran to prove it — required before the card can move to review or done.",
350
+ properties: {
351
+ command: { type: "string", maxLength: 1000 },
352
+ ok: { type: "boolean" },
353
+ url: {
354
+ type: "string",
355
+ maxLength: 2000,
356
+ pattern: "^https?:\\/\\/\\S+$",
357
+ },
358
+ },
359
+ required: ["command", "ok"],
360
+ },
361
+ },
362
+ required: ["board_id", "card", "key"],
363
+ },
364
+ {
365
+ name: "review_card",
366
+ title: "Record the user's review of a card",
367
+ description:
368
+ "Write the user's review of a card's checklist in one call: every box they answered, with the tick it should end with. ONLY with picks the user just made (in the option picker, or said plainly in chat) — never tick a decision on your own judgement. Ticking one option of a pick-ONE group unticks the others; boxes not named are left as they are. Free text the user typed (\"Other\") goes in `note`. Returns `ready: true` once every decision is settled; it does not move the card.",
369
+ readOnly: false,
370
+ properties: {
371
+ board_id: BOARD_ID,
372
+ card: CARD,
373
+ picks: {
374
+ type: "object[]",
375
+ description: "Every box the user answered in this pass",
376
+ minItems: 1,
377
+ properties: {
378
+ key: { type: "string", description: "Checklist item key, e.g. D1" },
379
+ checked: { type: "boolean" },
380
+ note: {
381
+ type: "string",
382
+ description: "The user's own words; empty string clears the note",
383
+ },
384
+ },
385
+ required: ["key", "checked"],
386
+ },
387
+ revision: {
388
+ type: "integer",
389
+ description:
390
+ "The card's `revision` from get_review; refused if it changed since",
391
+ },
392
+ },
393
+ required: ["board_id", "card", "picks"],
394
+ },
395
+ {
396
+ name: "checkpoint",
397
+ title: "Record a checkpoint",
398
+ description:
399
+ "Record where you stopped on a card so another agent can resume it. Call after each checklist item you finish, and before you stop mid-task. `get_review` returns the latest checkpoint. Summarise — never paste transcripts, secrets, tokens or .env values. Refused on a finished or archived card.",
400
+ readOnly: false,
401
+ properties: {
402
+ board_id: BOARD_ID,
403
+ card: CARD,
404
+ summary: {
405
+ type: "string",
406
+ description:
407
+ "What is done, what is verified (and how), what is not yet done",
408
+ },
409
+ next_step: {
410
+ type: "string",
411
+ description: "The first thing the next agent should do",
412
+ },
413
+ request: {
414
+ type: "string",
415
+ description: "What the user last asked for, in their words",
416
+ },
417
+ files: {
418
+ type: "string[]",
419
+ description: "Repo-relative paths you changed",
420
+ },
421
+ commands: {
422
+ type: "object[]",
423
+ description: "Verification commands you ran and whether they passed",
424
+ properties: {
425
+ command: { type: "string" },
426
+ ok: { type: "boolean" },
427
+ },
428
+ required: ["command"],
429
+ },
430
+ git: {
431
+ type: "object",
432
+ description:
433
+ "Where the code is: branch, HEAD sha, and a pushed ref holding uncommitted work, if any",
434
+ properties: {
435
+ branch: { type: "string" },
436
+ head: { type: "string" },
437
+ wip_ref: { type: "string" },
438
+ wip_sha: { type: "string" },
439
+ },
440
+ },
441
+ },
442
+ required: ["board_id", "card", "summary"],
443
+ },
444
+ {
445
+ name: "delete_review",
446
+ title: "Archive a card",
447
+ description:
448
+ "Take a card off the board. This ARCHIVES it — the card and its history stay in the database and can be restored. Nothing here deletes rows.",
449
+ readOnly: false,
450
+ properties: {
451
+ board_id: BOARD_ID,
452
+ card: CARD,
453
+ },
454
+ required: ["board_id", "card"],
455
+ },
456
+ ];
457
+
458
+ // ── The answers ─────────────────────────────────────────────────────────────
459
+ // BE-28: the cloud's answers, field for field; the offline server answers the
460
+ // same. `apps/mcp/scripts/mcp-parity.ts` (cloud) and
461
+ // `apps/desktop/scripts/mcp-parity.mjs` (offline) check every key.
462
+
463
+ /** A lane with its live card count, as `board_summary` states it. */
464
+ export interface ToolLaneCount {
465
+ key: string;
466
+ label: string;
467
+ role: ColumnRole | null;
468
+ count: number;
469
+ }
470
+
471
+ /** A lane as `list_reviews` names it. */
472
+ export interface ToolLane {
473
+ key: string;
474
+ name: string;
475
+ role: ColumnRole | null;
476
+ }
477
+
478
+ /** A card in one line, as `lifecycle_status` lists it. */
479
+ export interface CardRef {
480
+ id: string;
481
+ taskId: string | null;
482
+ title: string;
483
+ }
484
+
485
+ /** Something a reviewer may want to turn into a lesson (PD-01). */
486
+ export type RetroSignal =
487
+ | {
488
+ kind: "changes_requested";
489
+ reason: string;
490
+ /** The lane the card was sent back from, and the one it went to. */
491
+ from: string;
492
+ to: string;
493
+ at: string;
494
+ }
495
+ | { kind: "user_note"; item: string; note: string; at: string }
496
+ | {
497
+ kind: "verify_failed_then_fixed";
498
+ item: string;
499
+ /** The command whose evidence finally passed. */
500
+ command: string;
501
+ at: string;
502
+ };
503
+
504
+ /** What each board tool answers, inside its text content, as JSON. */
505
+ export interface BoardToolOutputs {
506
+ list_boards: {
507
+ /** The normalized remote, when `repo` was passed. */
508
+ repo?: string;
509
+ boards: BoardSummary[];
510
+ /** What to do next, when `repo` was passed. */
511
+ next?: string;
512
+ };
513
+ create_board: {
514
+ board_id: string;
515
+ name: string;
516
+ slug: string;
517
+ repo: string;
518
+ };
519
+ link_repo: {
520
+ repo: string;
521
+ /** The repo the board was linked to before, or null. */
522
+ previous: string | null;
523
+ /** The boards now linked to `repo`. */
524
+ boards: BoardSummary[];
525
+ };
526
+ board_summary: {
527
+ workspaceId: string;
528
+ role: string;
529
+ /** The board's change sequence. */
530
+ head: number;
531
+ lanes: ToolLaneCount[];
532
+ /** In-progress cards no agent has touched for over 2 hours. */
533
+ stale: number;
534
+ categories: { key: string; name: string }[];
535
+ tags: TagPolicy;
536
+ labels: { tag: string; name: string; tone: string }[];
537
+ };
538
+ list_reviews: { items: Card[]; head: number; columns: ToolLane[] };
539
+ get_review: {
540
+ /** The card; its run plan is `dispatch`, beside it. */
541
+ item: Omit<CardDetail, "dispatch">;
542
+ checkpoint: LatestCheckpoint | null;
543
+ dispatch: Dispatch | null;
544
+ };
545
+ create_review: { item: CardDetail };
546
+ update_review: { item: CardDetail };
547
+ /**
548
+ * The box that changed and the card in one line, not the whole card: a
549
+ * card's detail is 2–3k tokens, and an agent ticks one box after another.
550
+ * `get_review` has the rest. `ready` / `open` as `review_card` says them.
551
+ */
552
+ toggle_item: {
553
+ checklistItem: ChecklistItem;
554
+ card: CardRef & {
555
+ columnKey: string;
556
+ revision: number;
557
+ /** Checked boxes, and all of them. */
558
+ done: number;
559
+ total: number;
560
+ };
561
+ ready: boolean;
562
+ /** When not `ready`: box keys, or `group (D1/D2)` for an unsettled group. */
563
+ open?: string[];
564
+ };
565
+ review_card: {
566
+ ready: boolean;
567
+ /** When `ready`. */
568
+ next?: string;
569
+ /** When not `ready`: box keys, or `group (D1/D2)` for an unsettled group. */
570
+ open?: string[];
571
+ item: CardDetail;
572
+ };
573
+ set_status: {
574
+ item: CardDetail;
575
+ /** Only on a move into a review lane, and only with signals. */
576
+ retro?: { signals: RetroSignal[]; ask: string };
577
+ };
578
+ delete_review: {
579
+ archived: string;
580
+ /** The change it was recorded as; null when it was already archived. */
581
+ seq: number | null;
582
+ };
583
+ checkpoint: { checkpoint: Checkpoint };
584
+ lifecycle_status: {
585
+ waiting: (CardRef & { done: number; total: number })[];
586
+ ready: CardRef[];
587
+ inFlight: (CardRef & { columnKey: string })[];
588
+ review: (CardRef & { columnKey: string })[];
589
+ };
590
+ }