proofdeck 0.0.0-stage → 0.1.1

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.
Files changed (139) hide show
  1. package/LICENSE +201 -0
  2. package/NOTICE +23 -0
  3. package/README.md +152 -2
  4. package/README.zh-CN.md +152 -0
  5. package/bin/proofdeck.js +191 -0
  6. package/board/LICENSE +201 -0
  7. package/board/README.md +473 -0
  8. package/board/README.zh-CN.md +424 -0
  9. package/board/dist/_chk.db-shm +0 -0
  10. package/board/dist/_chk.db-wal +0 -0
  11. package/board/dist/adapters.d.ts +40 -0
  12. package/board/dist/adapters.d.ts.map +1 -0
  13. package/board/dist/adapters.js +124 -0
  14. package/board/dist/adapters.js.map +1 -0
  15. package/board/dist/board.d.ts +628 -0
  16. package/board/dist/board.d.ts.map +1 -0
  17. package/board/dist/board.js +2767 -0
  18. package/board/dist/board.js.map +1 -0
  19. package/board/dist/cli.d.ts +3 -0
  20. package/board/dist/cli.d.ts.map +1 -0
  21. package/board/dist/cli.js +1663 -0
  22. package/board/dist/cli.js.map +1 -0
  23. package/board/dist/config.d.ts +57 -0
  24. package/board/dist/config.d.ts.map +1 -0
  25. package/board/dist/config.js +99 -0
  26. package/board/dist/config.js.map +1 -0
  27. package/board/dist/db.d.ts +9 -0
  28. package/board/dist/db.d.ts.map +1 -0
  29. package/board/dist/db.js +506 -0
  30. package/board/dist/db.js.map +1 -0
  31. package/board/dist/git.d.ts +35 -0
  32. package/board/dist/git.d.ts.map +1 -0
  33. package/board/dist/git.js +147 -0
  34. package/board/dist/git.js.map +1 -0
  35. package/board/dist/index.d.ts +18 -0
  36. package/board/dist/index.d.ts.map +1 -0
  37. package/board/dist/index.js +13 -0
  38. package/board/dist/index.js.map +1 -0
  39. package/board/dist/mcp-config.d.ts +26 -0
  40. package/board/dist/mcp-config.d.ts.map +1 -0
  41. package/board/dist/mcp-config.js +88 -0
  42. package/board/dist/mcp-config.js.map +1 -0
  43. package/board/dist/mcp.d.ts +3 -0
  44. package/board/dist/mcp.d.ts.map +1 -0
  45. package/board/dist/mcp.js +949 -0
  46. package/board/dist/mcp.js.map +1 -0
  47. package/board/dist/quickstart.d.ts +75 -0
  48. package/board/dist/quickstart.d.ts.map +1 -0
  49. package/board/dist/quickstart.js +156 -0
  50. package/board/dist/quickstart.js.map +1 -0
  51. package/board/dist/serve.d.ts +10 -0
  52. package/board/dist/serve.d.ts.map +1 -0
  53. package/board/dist/serve.js +445 -0
  54. package/board/dist/serve.js.map +1 -0
  55. package/board/dist/signing.d.ts +18 -0
  56. package/board/dist/signing.d.ts.map +1 -0
  57. package/board/dist/signing.js +26 -0
  58. package/board/dist/signing.js.map +1 -0
  59. package/board/dist/sync.d.ts +49 -0
  60. package/board/dist/sync.d.ts.map +1 -0
  61. package/board/dist/sync.js +158 -0
  62. package/board/dist/sync.js.map +1 -0
  63. package/board/dist/types.d.ts +359 -0
  64. package/board/dist/types.d.ts.map +1 -0
  65. package/board/dist/types.js +20 -0
  66. package/board/dist/types.js.map +1 -0
  67. package/board/docs/adr/0001-shared-worktree-collision.md +102 -0
  68. package/board/docs/adr/0001-shared-worktree-collision.zh-CN.md +90 -0
  69. package/board/docs/attribution.md +123 -0
  70. package/board/docs/attribution.zh-CN.md +104 -0
  71. package/board/docs/development-workflow.md +81 -0
  72. package/board/docs/development-workflow.zh-CN.md +75 -0
  73. package/board/docs/diagrams/banner.png +0 -0
  74. package/board/docs/diagrams/banner.svg +1 -0
  75. package/board/docs/diagrams/before-after.png +0 -0
  76. package/board/docs/diagrams/before-after.svg +1 -0
  77. package/board/docs/diagrams/governance-chain.png +0 -0
  78. package/board/docs/diagrams/governance-chain.svg +1 -0
  79. package/board/docs/diagrams/value-flow.png +0 -0
  80. package/board/docs/diagrams/value-flow.svg +1 -0
  81. package/board/docs/entry-point.md +81 -0
  82. package/board/docs/entry-point.zh-CN.md +65 -0
  83. package/board/docs/kanban.png +0 -0
  84. package/board/docs/octoryn-mark.png +0 -0
  85. package/board/docs/registry-metadata.md +34 -0
  86. package/board/docs/registry-metadata.zh-CN.md +30 -0
  87. package/board/package.json +87 -0
  88. package/config.example.json +72 -0
  89. package/daemon.js +1148 -0
  90. package/docs/assets/demo.gif +0 -0
  91. package/docs/assets/logo-512.png +0 -0
  92. package/docs/assets/logo.svg +31 -0
  93. package/docs/assets/social-preview.png +0 -0
  94. package/docs/demo-run.mjs +61 -0
  95. package/docs/render-demo.py +94 -0
  96. package/docs/render-logo.py +101 -0
  97. package/docs/task-book.md +58 -0
  98. package/e2e/verify-acceptance.mjs +150 -0
  99. package/e2e/verify-antifraud.mjs +128 -0
  100. package/e2e/verify-caps.mjs +46 -0
  101. package/e2e/verify-checkpoint.mjs +208 -0
  102. package/e2e/verify-firstclass.mjs +110 -0
  103. package/e2e/verify-judge.mjs +52 -0
  104. package/e2e/verify-lease.mjs +95 -0
  105. package/e2e/verify-replay.mjs +92 -0
  106. package/e2e/verify-resilience.mjs +323 -0
  107. package/e2e/verify-review.mjs +86 -0
  108. package/e2e/verify-scheduling.mjs +110 -0
  109. package/e2e/verify-schema-evolution.mjs +107 -0
  110. package/e2e/verify-sla-digest.mjs +105 -0
  111. package/guard.js +97 -0
  112. package/lib/adapters/codex.js +206 -0
  113. package/lib/billing-convert.js +57 -0
  114. package/lib/board.js +46 -0
  115. package/lib/caps.js +35 -0
  116. package/lib/checkpoint.js +130 -0
  117. package/lib/gating.js +218 -0
  118. package/lib/guard-core.mjs +108 -0
  119. package/lib/http.js +161 -0
  120. package/lib/judge.js +89 -0
  121. package/lib/lease.js +93 -0
  122. package/lib/notify.js +56 -0
  123. package/lib/platform.js +120 -0
  124. package/lib/replay.js +68 -0
  125. package/lib/review.js +40 -0
  126. package/lib/runner.js +152 -0
  127. package/lib/schedule.js +59 -0
  128. package/lib/sla.js +42 -0
  129. package/lib/spans.js +36 -0
  130. package/lib/starve.js +43 -0
  131. package/lib/store.js +109 -0
  132. package/lib/supply.js +101 -0
  133. package/lib/usage.js +103 -0
  134. package/lib/verify.js +223 -0
  135. package/lib/watchdog-core.mjs +68 -0
  136. package/lib/watchdog-worker.mjs +75 -0
  137. package/package.json +55 -4
  138. package/scripts/run-daemon.sh +18 -0
  139. package/scripts/run-e2e.mjs +39 -0
@@ -0,0 +1,949 @@
1
+ #!/usr/bin/env node
2
+ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
3
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
4
+ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
5
+ import { Board } from "./board.js";
6
+ import { loadConfig } from "./config.js";
7
+ import { getAdapter, ADAPTERS } from "./adapters.js";
8
+ import * as git from "./git.js";
9
+ /**
10
+ * MCP server for the Octopus Blackboard. Any MCP-capable agent (Claude Code,
11
+ * Cursor, a custom client) can read and write the shared board without the
12
+ * blackboard orchestrating anything: the agent decides when to look and what
13
+ * to record. Identity defaults to OCTOBOARD_AGENT; a per-call `agent` argument
14
+ * overrides it.
15
+ */
16
+ /**
17
+ * MCP `instructions`: the protocol-level handshake carries this string into every
18
+ * client's context at initialize time -- no tool call, no agent cooperation needed.
19
+ * It is the only injection point that reaches every MCP-capable surface at once.
20
+ * Keep it a POINTER (paths + the few rules that must not be missed), never the full
21
+ * constitution: this is paid once per client session by every agent on the board.
22
+ * Evidence: @modelcontextprotocol/sdk 1.30.0 server/index.js:268 spreads
23
+ * `instructions` into the initialize result when set. Measured 2026-10-09 with
24
+ * mcp-handshake-probe.mjs (before: undefined, after: present).
25
+ */
26
+ const BOARD_INSTRUCTIONS = "多 agent 共享黑板。开工前必读两处:\n① 团队宪法 D:/AgentHub/team/AGENTS.md(§3 开工流程 / §7 红线 / §11 记忆协议 / §12 输出纪律)\n② 本项目 .agent/STATE.md(我是谁 / 在做什么 / 下一步)\n红线须先请示人类:删改他人文件、改动 AGENTS.md、向工作区外发布、装软件、碰敏感信息。\n规矩:先认领任务再动手;收工留 note;给选项/下推荐/声称完成前先跑 advice_lint.py。";
27
+ const server = new Server({ name: "octopus-blackboard", version: "0.2.4" }, { capabilities: { tools: {} }, instructions: BOARD_INSTRUCTIONS });
28
+ const defaultAgent = loadConfig().agent;
29
+ function withBoard(fn) {
30
+ const b = Board.open();
31
+ try {
32
+ return fn(b);
33
+ }
34
+ finally {
35
+ b.close();
36
+ }
37
+ }
38
+ function text(value) {
39
+ return {
40
+ content: [
41
+ {
42
+ type: "text",
43
+ text: typeof value === "string" ? value : JSON.stringify(value, null, 2),
44
+ },
45
+ ],
46
+ };
47
+ }
48
+ const AGENT_PROP = {
49
+ agent: {
50
+ type: "string",
51
+ description: "acting agent identity (defaults to OCTOBOARD_AGENT)",
52
+ },
53
+ };
54
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({
55
+ tools: [
56
+ {
57
+ name: "board_status",
58
+ description: "Read the board: active agents, open tasks and who holds them, unread messages, open risks, recent history. Call this before starting work to see what other agents are doing. \u5f00\u5de5\u524d\u5fc5\u8bfb\u4e24\u5904\uff1a\u56e2\u961f\u5baa\u6cd5 D:/AgentHub/team/AGENTS.md\uff08\u00a73 \u5f00\u5de5\u6d41\u7a0b / \u00a77 \u7ea2\u7ebf / \u00a711 \u8bb0\u5fc6\u534f\u8bae / \u00a712 \u8f93\u51fa\u7eaa\u5f8b\uff09\uff0c\u4ee5\u53ca\u672c\u9879\u76ee .agent/STATE.md\u3002",
59
+ inputSchema: {
60
+ type: "object",
61
+ properties: { ...AGENT_PROP },
62
+ },
63
+ },
64
+ {
65
+ name: "board_timeline",
66
+ description: "Read the append-only, hash-chained history of everything that happened on the board.",
67
+ inputSchema: {
68
+ type: "object",
69
+ properties: { limit: { type: "number", default: 30 } },
70
+ },
71
+ },
72
+ {
73
+ name: "board_note",
74
+ description: "Broadcast a free-form status note to the board.",
75
+ inputSchema: {
76
+ type: "object",
77
+ properties: { text: { type: "string" }, ...AGENT_PROP },
78
+ required: ["text"],
79
+ },
80
+ },
81
+ {
82
+ name: "board_claim",
83
+ description: "Claim a task by key so other agents know you own it. If another agent already holds it, the response reports the conflict (the board records but does not block).",
84
+ inputSchema: {
85
+ type: "object",
86
+ properties: {
87
+ key: {
88
+ type: "string",
89
+ description: "task key, e.g. trust-layer-policy-schema",
90
+ },
91
+ title: { type: "string" },
92
+ ...AGENT_PROP,
93
+ },
94
+ required: ["key"],
95
+ },
96
+ },
97
+ {
98
+ name: "board_task_define",
99
+ description: "Create or update a task's kanban fields: title, description (what it is), project, impact (change surface), and risk level. New keys get a stable task number. Optional `acceptance` stores a first-class machine-checkable acceptance spec (JSON object, e.g. {baseDir, mode, checks}) that the verification layer reads directly.",
100
+ inputSchema: {
101
+ type: "object",
102
+ properties: {
103
+ key: { type: "string" },
104
+ title: { type: "string" },
105
+ description: { type: "string" },
106
+ project: { type: "string" },
107
+ stream: { type: "string", description: "controlled stream/phase label within the project (e.g. 串讲/译文). Rejected if the project has declared a vocabulary and this value is not in it." },
108
+ impact: { type: "string" },
109
+ riskLevel: { type: "string", enum: ["low", "medium", "high"] },
110
+ acceptance: {
111
+ type: "object",
112
+ description: "machine-checkable acceptance spec (JSON object), e.g. {baseDir, mode: auto|cross|human, checks: [...]}",
113
+ },
114
+ ...AGENT_PROP,
115
+ },
116
+ required: ["key"],
117
+ },
118
+ },
119
+ {
120
+ name: "board_verify",
121
+ description: "Record a verification outcome for a task as a first-class, tamper-evident timeline event (kind 'verify'). verdict is fail-closed: only 'pass' or 'fail'. Use this instead of free-form notes when a check layer signs off on (or rejects) a deliverable.",
122
+ inputSchema: {
123
+ type: "object",
124
+ properties: {
125
+ ref: { type: "string", description: "task key or number" },
126
+ verdict: { type: "string", enum: ["pass", "fail"] },
127
+ level: { type: "string", description: "verification level label, e.g. V1 (mechanical) / V2 (cross-review) / V3 (human)" },
128
+ summary: { type: "string" },
129
+ checks: { type: "array", description: "per-check results: [{type, target, pass, evidence?}]" },
130
+ ...AGENT_PROP,
131
+ },
132
+ required: ["ref", "verdict"],
133
+ },
134
+ },
135
+ {
136
+ name: "board_task",
137
+ description: "Get a task's full kanban card (status, progress, assignees, active-agent count, impacted files, linked risks) by key or number (#145).",
138
+ inputSchema: {
139
+ type: "object",
140
+ properties: {
141
+ ref: { type: "string", description: "task key or number" },
142
+ },
143
+ required: ["ref"],
144
+ },
145
+ },
146
+ {
147
+ name: "board_tasks",
148
+ description: "List all tasks as kanban cards (for a board/kanban view).",
149
+ inputSchema: { type: "object", properties: {} },
150
+ },
151
+ {
152
+ name: "board_assign",
153
+ description: "Assign a task to an agent and notify them — records the assignee AND leaves a 'please look at task #N' message in that agent's inbox. Passive: the board records the ask; the agent reads its inbox and decides to act. Never launches the agent.",
154
+ inputSchema: {
155
+ type: "object",
156
+ properties: {
157
+ ref: { type: "string", description: "task key or number" },
158
+ to: { type: "string", description: "agent to notify" },
159
+ ...AGENT_PROP,
160
+ },
161
+ required: ["ref", "to"],
162
+ },
163
+ },
164
+ {
165
+ name: "board_progress",
166
+ description: "Report task progress 0–100 (moves it to in-progress, or done at 100). Use this from an agent as it works a task so the kanban shows a live progress bar.",
167
+ inputSchema: {
168
+ type: "object",
169
+ properties: {
170
+ ref: { type: "string", description: "task key or number" },
171
+ percent: { type: "number" },
172
+ ...AGENT_PROP,
173
+ },
174
+ required: ["ref", "percent"],
175
+ },
176
+ },
177
+ {
178
+ name: "board_message",
179
+ description: "Leave a message for another agent (or broadcast with to='all').",
180
+ inputSchema: {
181
+ type: "object",
182
+ properties: {
183
+ to: { type: "string", description: "recipient agent name, or 'all'" },
184
+ body: { type: "string" },
185
+ ...AGENT_PROP,
186
+ },
187
+ required: ["to", "body"],
188
+ },
189
+ },
190
+ {
191
+ name: "board_inbox",
192
+ description: "Read what's waiting for you: messages (addressed or broadcast) and handoffs left for you. Pass markRead=true to ack everything returned, scoped to YOUR identity — other agents' inboxes are unaffected. Reading without acking leaves the sender unable to tell whether you saw it.",
193
+ inputSchema: {
194
+ type: "object",
195
+ properties: {
196
+ includeRead: { type: "boolean", default: false },
197
+ markRead: {
198
+ type: "boolean",
199
+ default: false,
200
+ description: "ack the messages this call returns, for `agent` only",
201
+ },
202
+ ...AGENT_PROP,
203
+ },
204
+ },
205
+ },
206
+ {
207
+ name: "board_mark_read",
208
+ description: "Ack a message as seen, scoped to your identity (so acking a broadcast never hides it from other agents). Give messageId for one message, or all=true for the whole inbox.",
209
+ inputSchema: {
210
+ type: "object",
211
+ properties: {
212
+ messageId: { type: "string" },
213
+ all: { type: "boolean", default: false },
214
+ ...AGENT_PROP,
215
+ },
216
+ },
217
+ },
218
+ {
219
+ name: "board_outbox",
220
+ description: "The sender's half of the ack loop: direct messages you left that nobody has opened yet, with who has acked each. Use this before re-pinging an agent or assuming a dispatch was ignored.",
221
+ inputSchema: { type: "object", properties: { ...AGENT_PROP } },
222
+ },
223
+ {
224
+ name: "board_handoffs",
225
+ description: "Handoffs left FOR you — the work another agent passed to you, with context and open questions.",
226
+ inputSchema: { type: "object", properties: { ...AGENT_PROP } },
227
+ },
228
+ {
229
+ name: "board_decision",
230
+ description: "Record a decision and its rationale so other agents see what was decided and why.",
231
+ inputSchema: {
232
+ type: "object",
233
+ properties: {
234
+ title: { type: "string" },
235
+ rationale: { type: "string" },
236
+ ...AGENT_PROP,
237
+ },
238
+ required: ["title"],
239
+ },
240
+ },
241
+ {
242
+ name: "board_evidence",
243
+ description: "Attach evidence (file path, URL, log, test run) supporting some work. Optionally scope it to a project/task and tag a kind (memory | skill | hook | lesson | playbook) to enter the project sedimentation register.",
244
+ inputSchema: {
245
+ type: "object",
246
+ properties: {
247
+ ref: { type: "string" },
248
+ note: { type: "string" },
249
+ target: {
250
+ type: "string",
251
+ description: "what it supports, e.g. task:auth-mw",
252
+ },
253
+ project: { type: "string", description: "scope the register entry to a project" },
254
+ task: { type: "string", description: "scope the register entry to a task" },
255
+ kind: { type: "string", description: "memory | skill | hook | lesson | playbook" },
256
+ ...AGENT_PROP,
257
+ },
258
+ required: ["ref"],
259
+ },
260
+ },
261
+ {
262
+ name: "board_evidence_list",
263
+ description: "List the sedimentation register (evidence) filtered by project / task / kind.",
264
+ inputSchema: {
265
+ type: "object",
266
+ properties: {
267
+ project: { type: "string" },
268
+ task: { type: "string" },
269
+ kind: { type: "string", description: "memory | skill | hook | lesson | playbook" },
270
+ },
271
+ },
272
+ },
273
+ {
274
+ name: "board_file_changed",
275
+ description: "Record that you touched a file. If a task key is given, the response reports files other agents already changed for that task (conflict awareness).",
276
+ inputSchema: {
277
+ type: "object",
278
+ properties: {
279
+ path: { type: "string" },
280
+ change: {
281
+ type: "string",
282
+ enum: ["added", "modified", "deleted"],
283
+ default: "modified",
284
+ },
285
+ task: { type: "string" },
286
+ ...AGENT_PROP,
287
+ },
288
+ required: ["path"],
289
+ },
290
+ },
291
+ {
292
+ name: "board_risk",
293
+ description: "Flag an open risk the next agent should know before acting.",
294
+ inputSchema: {
295
+ type: "object",
296
+ properties: {
297
+ title: { type: "string" },
298
+ severity: {
299
+ type: "string",
300
+ enum: ["low", "medium", "high"],
301
+ default: "medium",
302
+ },
303
+ ...AGENT_PROP,
304
+ },
305
+ required: ["title"],
306
+ },
307
+ },
308
+ {
309
+ name: "board_resolve_risk",
310
+ description: "Settle a risk card so the loop closes: move it out of open (mitigated/closed) or reopen it. Quote the risk id from board_status. Always give a note saying how or why.",
311
+ inputSchema: {
312
+ type: "object",
313
+ properties: {
314
+ ref: {
315
+ type: "string",
316
+ description: "risk id, unique id prefix, or exact title",
317
+ },
318
+ status: {
319
+ type: "string",
320
+ enum: ["open", "mitigated", "closed"],
321
+ default: "closed",
322
+ },
323
+ note: { type: "string", description: "how/why it was settled" },
324
+ ...AGENT_PROP,
325
+ },
326
+ required: ["ref"],
327
+ },
328
+ },
329
+ {
330
+ name: "board_handoff",
331
+ description: "Hand off work to another agent with a summary of the state at handoff.",
332
+ inputSchema: {
333
+ type: "object",
334
+ properties: {
335
+ to: { type: "string" },
336
+ summary: { type: "string" },
337
+ context: { type: "string" },
338
+ relatedFiles: { type: "array", items: { type: "string" } },
339
+ openQuestions: { type: "array", items: { type: "string" } },
340
+ task: { type: "string" },
341
+ ...AGENT_PROP,
342
+ },
343
+ required: ["to", "summary"],
344
+ },
345
+ },
346
+ {
347
+ name: "session_start",
348
+ description: "Start an execution session. Subsequent writes and links attribute to it. Captures machine, working directory, git branch, and repository.",
349
+ inputSchema: {
350
+ type: "object",
351
+ properties: { label: { type: "string" }, ...AGENT_PROP },
352
+ },
353
+ },
354
+ {
355
+ name: "session_stop",
356
+ description: "Close the active session (or a specific one).",
357
+ inputSchema: {
358
+ type: "object",
359
+ properties: { session: { type: "string" }, ...AGENT_PROP },
360
+ },
361
+ },
362
+ {
363
+ name: "board_link",
364
+ description: "Attribute a Git commit's files to the current session (who actually produced the code). Reads Git; never rewrites history. Optionally writes an additive git note.",
365
+ inputSchema: {
366
+ type: "object",
367
+ properties: {
368
+ rev: {
369
+ type: "string",
370
+ description: "commit/revision, defaults to HEAD",
371
+ },
372
+ actorType: { type: "string", enum: ["human", "ai"], default: "ai" },
373
+ name: { type: "string", description: "explicit actor name" },
374
+ writeNote: { type: "boolean", default: false },
375
+ ...AGENT_PROP,
376
+ },
377
+ },
378
+ },
379
+ {
380
+ name: "board_attribute",
381
+ description: "Record a single attribution (commit + optional file) to a human or AI actor.",
382
+ inputSchema: {
383
+ type: "object",
384
+ properties: {
385
+ rev: { type: "string" },
386
+ file: { type: "string" },
387
+ actorType: { type: "string", enum: ["human", "ai"], default: "ai" },
388
+ name: { type: "string" },
389
+ ...AGENT_PROP,
390
+ },
391
+ required: ["rev"],
392
+ },
393
+ },
394
+ {
395
+ name: "board_review",
396
+ description: "Record who reviewed a commit and the outcome (human or AI reviewer).",
397
+ inputSchema: {
398
+ type: "object",
399
+ properties: {
400
+ rev: { type: "string" },
401
+ reviewerType: {
402
+ type: "string",
403
+ enum: ["human", "ai"],
404
+ default: "human",
405
+ },
406
+ name: { type: "string" },
407
+ outcome: {
408
+ type: "string",
409
+ enum: ["approved", "changes-requested", "rejected", "commented"],
410
+ default: "approved",
411
+ },
412
+ note: { type: "string" },
413
+ ...AGENT_PROP,
414
+ },
415
+ required: ["rev"],
416
+ },
417
+ },
418
+ {
419
+ name: "board_who",
420
+ description: "Who changed a file: Git authors, AI sessions that touched it, and commit attributions. Pass a line number to trace which session introduced that line.",
421
+ inputSchema: {
422
+ type: "object",
423
+ properties: { file: { type: "string" }, line: { type: "number" } },
424
+ required: ["file"],
425
+ },
426
+ },
427
+ {
428
+ name: "board_explain",
429
+ description: "Explain a commit: its AI attribution, reviews, and related decisions.",
430
+ inputSchema: {
431
+ type: "object",
432
+ properties: {
433
+ rev: { type: "string", description: "defaults to HEAD" },
434
+ },
435
+ },
436
+ },
437
+ {
438
+ name: "board_unreviewed",
439
+ description: "List AI-produced commits that have never been reviewed by a human.",
440
+ inputSchema: { type: "object", properties: {} },
441
+ },
442
+ {
443
+ name: "board_check",
444
+ description: "Governance gate: assert policy over commits and report pass/fail plus violations. Read-only — reports, does not block. Use in CI to keep unreviewed AI work off a branch.",
445
+ inputSchema: {
446
+ type: "object",
447
+ properties: {
448
+ range: {
449
+ type: "string",
450
+ description: "commit range, e.g. main..HEAD (default: all attributed commits)",
451
+ },
452
+ requireHumanReview: {
453
+ type: "boolean",
454
+ description: "fail if an AI commit lacks a human review",
455
+ },
456
+ requireAttribution: {
457
+ type: "boolean",
458
+ description: "fail if a scoped commit has no attribution",
459
+ },
460
+ verifyChain: {
461
+ type: "boolean",
462
+ description: "fail if the timeline hash chain is broken",
463
+ },
464
+ },
465
+ },
466
+ },
467
+ {
468
+ name: "board_export",
469
+ description: "Export a portable attribution bundle (attributions, reviews, sessions, decisions) for a commit range, so attribution survives push/PR into a team board or CI.",
470
+ inputSchema: {
471
+ type: "object",
472
+ properties: {
473
+ range: {
474
+ type: "string",
475
+ description: "commit range (default: all attributed commits)",
476
+ },
477
+ },
478
+ },
479
+ },
480
+ {
481
+ name: "board_import",
482
+ description: "Import an attribution bundle (as produced by board_export) into this board. Idempotent.",
483
+ inputSchema: {
484
+ type: "object",
485
+ properties: {
486
+ bundle: {
487
+ type: "object",
488
+ description: "the bundle object from board_export",
489
+ },
490
+ },
491
+ required: ["bundle"],
492
+ },
493
+ },
494
+ {
495
+ name: "board_trailers",
496
+ description: "Git trailer lines encoding a commit's attribution, for embedding in a commit message.",
497
+ inputSchema: {
498
+ type: "object",
499
+ properties: {
500
+ rev: { type: "string", description: "defaults to HEAD" },
501
+ },
502
+ },
503
+ },
504
+ {
505
+ name: "board_since",
506
+ description: "Subscribe primitive: poll for timeline events after a given seq. Returns the new head seq and events (optionally filtered to those relevant to an agent). Call board_status first to get a starting seq.",
507
+ inputSchema: {
508
+ type: "object",
509
+ properties: {
510
+ afterSeq: {
511
+ type: "number",
512
+ description: "return events with seq greater than this",
513
+ },
514
+ forAgent: {
515
+ type: "string",
516
+ description: "filter to messages/handoffs/conflicts for this agent",
517
+ },
518
+ },
519
+ required: ["afterSeq"],
520
+ },
521
+ },
522
+ {
523
+ name: "board_sign",
524
+ description: "Sign the current timeline head with the active session's key (attests board state through the head seq).",
525
+ inputSchema: { type: "object", properties: { ...AGENT_PROP } },
526
+ },
527
+ {
528
+ name: "board_trust",
529
+ description: "Show signature trust: which sessions have signed the timeline and whether each signature is valid and still current.",
530
+ inputSchema: { type: "object", properties: {} },
531
+ },
532
+ {
533
+ name: "board_report",
534
+ description: "Accountability scorecard: review coverage, AI/human ratio, per-agent breakdown, session and risk counts. With an optional `project` key, returns the three-level project -> task -> trace aggregation INSTEAD of the scorecard (a different shape).",
535
+ inputSchema: {
536
+ type: "object",
537
+ properties: {
538
+ project: { type: "string", description: "optional: three-level aggregation for this project key" },
539
+ },
540
+ },
541
+ },
542
+ {
543
+ name: "board_project",
544
+ description: "Projects (board -> project -> task -> trace). One tool, dispatched by `action`: add = create/update a project (records who created it), show = one project's tasks + trace, list = all projects with live task counts, status = set active|paused|archived.",
545
+ inputSchema: {
546
+ type: "object",
547
+ properties: {
548
+ action: { type: "string", description: "add | show | list | status", enum: ["add", "show", "list", "status"] },
549
+ key: { type: "string", description: "project key (required for add/show/status)" },
550
+ name: { type: "string", description: "human-facing name (add; defaults to the key)" },
551
+ description: { type: "string", description: "what the project is (add)" },
552
+ status: { type: "string", description: "lifecycle state (add/status)", enum: ["active", "paused", "archived"] },
553
+ streams: { type: "string", description: "controlled stream vocabulary (add): comma-separated list or JSON array; once declared, defineTask rejects streams outside it" },
554
+ ...AGENT_PROP,
555
+ },
556
+ required: ["action"],
557
+ },
558
+ },
559
+ {
560
+ name: "board_blame",
561
+ description: "Blame → narrative: trace a file line back to the session that introduced it and surface that session's other work, decisions, and handoffs.",
562
+ inputSchema: {
563
+ type: "object",
564
+ properties: { file: { type: "string" }, line: { type: "number" } },
565
+ required: ["file", "line"],
566
+ },
567
+ },
568
+ {
569
+ name: "board_heartbeat",
570
+ description: "Stamp the active session as alive (real-time liveness, so other agents can tell active from stale).",
571
+ inputSchema: { type: "object", properties: { ...AGENT_PROP } },
572
+ },
573
+ {
574
+ name: "board_prune",
575
+ description: "Retention: delete messages/evidence/file-change rows created before an ISO time. The audit timeline is never pruned.",
576
+ inputSchema: {
577
+ type: "object",
578
+ properties: {
579
+ before: { type: "string", description: "ISO timestamp" },
580
+ },
581
+ required: ["before"],
582
+ },
583
+ },
584
+ {
585
+ name: "board_redact",
586
+ description: "Hide a timeline entry's content at the read layer (the hash chain stays valid — this is not cryptographic erasure).",
587
+ inputSchema: {
588
+ type: "object",
589
+ properties: { seq: { type: "number" }, reason: { type: "string" } },
590
+ required: ["seq"],
591
+ },
592
+ },
593
+ {
594
+ name: "board_ingest",
595
+ description: "Ingest a CLI transcript's content into the active session (file edits, decisions, notes). Format is one of: " +
596
+ ADAPTERS.join(", ") +
597
+ ". Use 'generic' with our normalized event schema for any CLI.",
598
+ inputSchema: {
599
+ type: "object",
600
+ properties: {
601
+ content: { type: "string", description: "raw transcript content" },
602
+ format: { type: "string", enum: ADAPTERS, default: "generic" },
603
+ },
604
+ required: ["content"],
605
+ },
606
+ },
607
+ ],
608
+ }));
609
+ /** Coerce an optional numeric arg to a non-negative integer, or a fallback. */
610
+ function intArg(value, fallback) {
611
+ const n = typeof value === "number"
612
+ ? value
613
+ : typeof value === "string"
614
+ ? Number(value)
615
+ : NaN;
616
+ return Number.isInteger(n) && n >= 0 ? n : fallback;
617
+ }
618
+ server.setRequestHandler(CallToolRequestSchema, async (request) => {
619
+ const { name, arguments: rawArgs } = request.params;
620
+ const args = (rawArgs ?? {});
621
+ const actor = args.agent ?? defaultAgent;
622
+ try {
623
+ return handleTool(name, args, actor);
624
+ }
625
+ catch (err) {
626
+ // Never let a malformed request crash the server; surface a clean error.
627
+ return {
628
+ isError: true,
629
+ ...text(`Error in ${name}: ${err instanceof Error ? err.message : String(err)}`),
630
+ };
631
+ }
632
+ });
633
+ function handleTool(name, args, actor) {
634
+ switch (name) {
635
+ case "board_status":
636
+ return text(withBoard((b) => ({ ...b.status(actor), chain: b.verifyChain() })));
637
+ case "board_timeline":
638
+ return text(withBoard((b) => b.timeline(intArg(args.limit, 30))));
639
+ case "board_note":
640
+ return text(withBoard((b) => b.note(actor, String(args.text))));
641
+ case "board_claim":
642
+ return text(withBoard((b) => {
643
+ const r = b.claim(actor, String(args.key), args.title ?? null);
644
+ return r.conflict
645
+ ? {
646
+ ...r,
647
+ warning: `Task "${args.key}" is also held by ${r.conflict}.`,
648
+ }
649
+ : r;
650
+ }));
651
+ case "board_task_define":
652
+ return text(withBoard((b) => b.defineTask(actor, String(args.key), {
653
+ title: args.title ?? null,
654
+ description: args.description ?? null,
655
+ project: args.project ?? null,
656
+ stream: args.stream ?? null,
657
+ impact: args.impact ?? null,
658
+ riskLevel: args.riskLevel ?? null,
659
+ acceptance: args.acceptance ?? null,
660
+ })));
661
+ case "board_verify":
662
+ return text(withBoard((b) => {
663
+ const ev = b.verify(actor, String(args.ref), String(args.verdict), {
664
+ level: typeof args.level === "string" ? args.level : undefined,
665
+ summary: typeof args.summary === "string" ? args.summary : undefined,
666
+ checks: Array.isArray(args.checks) ? args.checks : undefined,
667
+ });
668
+ return ev ?? `No task '${args.ref}'.`;
669
+ }));
670
+ case "board_task":
671
+ return text(withBoard((b) => {
672
+ const t = b.resolveTask(String(args.ref));
673
+ return t
674
+ ? (b.taskCard(t.key) ?? `No task '${args.ref}'.`)
675
+ : `No task '${args.ref}'.`;
676
+ }));
677
+ case "board_tasks":
678
+ return text(withBoard((b) => b.listTaskCards()));
679
+ case "board_assign":
680
+ return text(withBoard((b) => {
681
+ const t = b.resolveTask(String(args.ref));
682
+ return t
683
+ ? (b.assign(actor, t.key, String(args.to)) ??
684
+ `No task '${args.ref}'.`)
685
+ : `No task '${args.ref}'.`;
686
+ }));
687
+ case "board_progress":
688
+ return text(withBoard((b) => {
689
+ const t = b.resolveTask(String(args.ref));
690
+ return t
691
+ ? (b.setProgress(actor, t.key, Number(args.percent)) ??
692
+ `No task '${args.ref}'.`)
693
+ : `No task '${args.ref}'.`;
694
+ }));
695
+ case "board_message": {
696
+ const to = args.to === "all" ? null : String(args.to);
697
+ return text(withBoard((b) => b.message(actor, to, String(args.body))));
698
+ }
699
+ case "board_inbox":
700
+ return text(withBoard((b) => {
701
+ const messages = b.inbox(actor, Boolean(args.includeRead));
702
+ // Ack the ids we are about to return, so a message that lands
703
+ // during this call stays unread for the next look.
704
+ const acked = args.markRead
705
+ ? messages.map((m) => {
706
+ b.markRead(m.id, actor);
707
+ return m.id;
708
+ })
709
+ : [];
710
+ return {
711
+ messages,
712
+ handoffs: b.handoffsFor(actor),
713
+ acked: acked.length > 0 ? acked.length : undefined,
714
+ };
715
+ }));
716
+ case "board_mark_read": {
717
+ if (!args.messageId && !args.all) {
718
+ return text({ error: "Give messageId, or pass all=true." });
719
+ }
720
+ return text(withBoard((b) => {
721
+ if (args.all) {
722
+ const ids = b.markInboxRead(actor);
723
+ return { agent: actor, acked: ids.length, ids };
724
+ }
725
+ if (!b.markRead(String(args.messageId), actor)) {
726
+ return { error: `No such message: ${args.messageId}` };
727
+ }
728
+ return { agent: actor, acked: 1, ids: [String(args.messageId)] };
729
+ }));
730
+ }
731
+ case "board_outbox":
732
+ return text(withBoard((b) => b.pendingAcks(actor).map((p) => ({
733
+ ...p,
734
+ readers: b.readers(p.id).map((r) => r.agent),
735
+ }))));
736
+ case "board_handoffs":
737
+ return text(withBoard((b) => b.handoffsFor(actor)));
738
+ case "board_decision":
739
+ return text(withBoard((b) => b.decision(actor, String(args.title), {
740
+ rationale: args.rationale ?? null,
741
+ evidence: args.evidence ?? null,
742
+ relatedCommits: args.relatedCommits ?? [],
743
+ relatedTasks: args.relatedTasks ?? [],
744
+ })));
745
+ case "board_evidence":
746
+ return text(withBoard((b) => b.evidence(actor, String(args.ref), args.note ?? null, args.target ?? null, args.project ?? null, {
747
+ taskKey: args.task ?? null,
748
+ kind: args.kind ?? null,
749
+ })));
750
+ case "board_evidence_list":
751
+ return text(withBoard((b) => b.listEvidence({
752
+ ...(args.project !== undefined ? { project: args.project } : {}),
753
+ ...(args.task !== undefined ? { taskKey: args.task } : {}),
754
+ ...(args.kind !== undefined ? { kind: args.kind } : {}),
755
+ })));
756
+ case "board_file_changed":
757
+ return text(withBoard((b) => {
758
+ const taskKey = args.task ?? null;
759
+ const others = taskKey
760
+ ? b.filesForTask(taskKey).filter((f) => f.agentId !== actor)
761
+ : [];
762
+ const fc = b.fileChanged(actor, String(args.path), (args.change ?? "modified"), taskKey);
763
+ return others.length > 0
764
+ ? {
765
+ file: fc,
766
+ warning: `${others.length} change(s) by other agents on task "${taskKey}".`,
767
+ others,
768
+ }
769
+ : { file: fc };
770
+ }));
771
+ case "board_risk":
772
+ return text(withBoard((b) => b.risk(actor, String(args.title), (args.severity ?? "medium"))));
773
+ case "board_resolve_risk":
774
+ return text(withBoard((b) => {
775
+ const r = b.resolveRisk(actor, String(args.ref), (args.status ?? "closed"), args.note ?? null);
776
+ return r ?? `No risk matches '${args.ref}'. Use board_status to list open risks.`;
777
+ }));
778
+ case "board_handoff":
779
+ return text(withBoard((b) => b.handoff(actor, String(args.to), String(args.summary), {
780
+ context: args.context ?? null,
781
+ relatedFiles: args.relatedFiles ?? [],
782
+ openQuestions: args.openQuestions ?? [],
783
+ taskKey: args.task ?? null,
784
+ })));
785
+ case "session_start":
786
+ return text(withBoard((b) => b.startSession(args.label ?? null)));
787
+ case "session_stop":
788
+ return text(withBoard((b) => b.stopSession(args.session ?? undefined) ?? "No active session."));
789
+ case "board_link":
790
+ return text(withBoard((b) => {
791
+ const r = b.link(String(args.rev ?? "HEAD"), {
792
+ actorType: args.actorType ?? "ai",
793
+ actor: args.name,
794
+ writeNote: Boolean(args.writeNote),
795
+ });
796
+ return r ?? `Could not resolve '${args.rev ?? "HEAD"}'.`;
797
+ }));
798
+ case "board_attribute":
799
+ return text(withBoard((b) => b.attribute(String(args.rev), {
800
+ file: args.file ?? null,
801
+ actorType: args.actorType ?? "ai",
802
+ actor: args.name,
803
+ })));
804
+ case "board_review":
805
+ return text(withBoard((b) => b.review(String(args.rev), {
806
+ reviewerType: args.reviewerType ?? "human",
807
+ reviewer: args.name,
808
+ outcome: args.outcome ?? "approved",
809
+ note: args.note ?? null,
810
+ })));
811
+ case "board_who": {
812
+ // Distinguish "no line given" from line 0/NaN — only blame on a valid
813
+ // positive integer line.
814
+ const line = typeof args.line === "number" || typeof args.line === "string"
815
+ ? Number(args.line)
816
+ : NaN;
817
+ const hasLine = Number.isInteger(line) && line > 0;
818
+ return text(withBoard((b) => hasLine
819
+ ? (b.blame(String(args.file), line) ?? "No blame available.")
820
+ : b.whoTouched(String(args.file))));
821
+ }
822
+ case "board_explain":
823
+ return text(withBoard((b) => b.explain(String(args.rev ?? "HEAD")) ??
824
+ `Nothing known about '${args.rev ?? "HEAD"}'.`));
825
+ case "board_unreviewed":
826
+ return text(withBoard((b) => b.unreviewedCommits()));
827
+ case "board_check": {
828
+ const commits = args.range ? git.revList(String(args.range)) : undefined;
829
+ const anyPolicy = args.requireHumanReview || args.requireAttribution || args.verifyChain;
830
+ return text(withBoard((b) => b.check({
831
+ commits,
832
+ requireHumanReview: anyPolicy
833
+ ? Boolean(args.requireHumanReview)
834
+ : true,
835
+ requireAttribution: Boolean(args.requireAttribution),
836
+ verifyChain: anyPolicy ? Boolean(args.verifyChain) : true,
837
+ })));
838
+ }
839
+ case "board_export":
840
+ return text(withBoard((b) => b.exportBundle(args.range ? git.revList(String(args.range)) : undefined)));
841
+ case "board_import":
842
+ return text(withBoard((b) => b.importBundle(args.bundle)));
843
+ case "board_trailers":
844
+ return text(withBoard((b) => b.trailersFor(String(args.rev ?? "HEAD")).join("\n")));
845
+ case "board_since":
846
+ return text(withBoard((b) => {
847
+ const events = b.since(intArg(args.afterSeq, 0));
848
+ return {
849
+ headSeq: b.headSeq(),
850
+ events: args.forAgent
851
+ ? b.notable(events, String(args.forAgent))
852
+ : events,
853
+ };
854
+ }));
855
+ case "board_sign":
856
+ return text(withBoard((b) => b.signHead() ??
857
+ "Nothing to sign (no active session, missing key, or empty board)."));
858
+ case "board_trust":
859
+ return text(withBoard((b) => ({
860
+ signedThrough: b.signedThrough(),
861
+ signatures: b.verifySignatures(),
862
+ })));
863
+ case "board_report":
864
+ return text(withBoard((b) => b.report(args.project ? String(args.project) : null)));
865
+ case "board_project": {
866
+ const action = String(args.action ?? "");
867
+ if (action === "list")
868
+ return text(withBoard((b) => b.listProjects()));
869
+ if (action === "add") {
870
+ const key = String(args.key ?? "").trim();
871
+ if (!key)
872
+ return text("key is required for add.");
873
+ try {
874
+ return text(withBoard((b) => b.createProject(actor, key, {
875
+ name: args.name ?? null,
876
+ description: args.description ?? null,
877
+ status: args.status ?? "active",
878
+ streams: args.streams ?? null,
879
+ })));
880
+ }
881
+ catch (e) {
882
+ return text(`Error: ${e.message}`);
883
+ }
884
+ }
885
+ if (action === "show") {
886
+ const key = String(args.key ?? "").trim();
887
+ if (!key)
888
+ return text("key is required for show.");
889
+ return text(withBoard((b) => b.projectReport(key) ?? `No project '${key}'.`));
890
+ }
891
+ if (action === "status") {
892
+ const key = String(args.key ?? "").trim();
893
+ if (!key)
894
+ return text("key is required for status.");
895
+ try {
896
+ return text(withBoard((b) => b.setProjectStatus(actor, key, String(args.status ?? "")) ?? `No project '${key}'.`));
897
+ }
898
+ catch (e) {
899
+ return text(`Error: ${e.message}`);
900
+ }
901
+ }
902
+ return text("action must be one of add | show | list | status.");
903
+ }
904
+ case "board_heartbeat":
905
+ return text(withBoard((b) => b.heartbeat() ?? "No active session."));
906
+ case "board_prune": {
907
+ const when = new Date(String(args.before));
908
+ if (isNaN(when.getTime())) {
909
+ return text("before must be a valid ISO timestamp.");
910
+ }
911
+ return text(withBoard((b) => b.prune(when.toISOString())));
912
+ }
913
+ case "board_redact": {
914
+ const seq = intArg(args.seq, 0);
915
+ if (seq < 1) {
916
+ return text("seq must be a positive integer.");
917
+ }
918
+ return text(withBoard((b) => b.redact(seq, args.reason ?? null)
919
+ ? `Redacted #${seq}.`
920
+ : `No timeline entry #${seq}.`));
921
+ }
922
+ case "board_ingest": {
923
+ const adapter = getAdapter(String(args.format ?? "generic"));
924
+ if (!adapter) {
925
+ return text(`Unknown format. Available: ${ADAPTERS.join(", ")}`);
926
+ }
927
+ const events = adapter.parse(String(args.content ?? ""));
928
+ return text(withBoard((b) => b.ingest(events)));
929
+ }
930
+ case "board_blame": {
931
+ const line = intArg(args.line, 0);
932
+ if (line < 1) {
933
+ return text("line must be a positive integer.");
934
+ }
935
+ return text(withBoard((b) => b.blameNarrative(String(args.file), line) ?? "No blame available."));
936
+ }
937
+ default:
938
+ return text(`Unknown tool: ${name}`);
939
+ }
940
+ }
941
+ async function main() {
942
+ const transport = new StdioServerTransport();
943
+ await server.connect(transport);
944
+ }
945
+ main().catch((err) => {
946
+ console.error(err instanceof Error ? err.message : String(err));
947
+ process.exit(1);
948
+ });
949
+ //# sourceMappingURL=mcp.js.map