@loopable/mcp 0.1.0 → 0.2.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.
package/README.md CHANGED
@@ -39,11 +39,75 @@ gets this server, and most of them do not have a token.
39
39
  | tool | |
40
40
  |---|---|
41
41
  | `whoami` | which account the token acts as, and what it can see |
42
+ | `next_ready` | what to pick up next — the oldest ready item nobody is on, as a pack |
43
+ | `pull_item` | the brief pack of one item: the first call of any work session |
42
44
  | `list_backlog` | one project's work items |
45
+ | `node` | one node and the edges touching it — the cheapest orientation there is |
46
+ | `neighbourhood` | what is around a node, one or two hops, filterable by relation |
47
+ | `path` | how two things relate: the shortest route between them, or none |
43
48
  | `add_item` | write work into the backlog, under a parent if it has one |
44
49
  | `propose` | put somebody else's ask in the approval queue — **not** in the backlog |
45
50
  | `revise` | correct an item's title or body |
46
- | `report_progress` | move an item to todo / in_progress / done |
51
+ | `write_brief` | propose the spec of one item — the ask, the acceptance criteria, what is out of scope |
52
+ | `report_progress` | move an item to todo / in_progress / in_review / blocked / awaiting_input — never done, which is a person's word |
53
+ | `open_session` | say you have started on an item — opens the live record of this piece of work |
54
+ | `post_activity` | one line into an open session: thought, action, question, result or error |
55
+ | `close_session` | end it — `error` takes a summary; `complete` is a claim and carries its evidence (brief revision, HEAD sha, verdict, every criterion, screenshots, cost), and moves the item to `in_review` |
56
+
57
+ ## Starting work
58
+
59
+ `pull_item` is the first call of a work session, and `next_ready` is the same
60
+ answer when the item has not been chosen yet. Both return one **brief pack**:
61
+
62
+ | | |
63
+ |---|---|
64
+ | `item` | id, kind, title, the ask, the body, status, `brief_rev`, `ready_blockers` |
65
+ | `criteria` | the acceptance criteria — text, how each is verified, where each stands |
66
+ | `neighbourhood` | one hop of the graph, **by title**: `nodes` as `[kind, title]` pairs, `edges` naming both ends |
67
+ | `decisions` | the ones that still stand — those **about** this item first, then the project's, capped |
68
+ | `environments` | kind and base URL: where the built thing is allowed to be run |
69
+ | `pack_bytes` `truncated` `trimmed` | how big it came out, and what was cut to make it fit |
70
+
71
+ Three properties are worth relying on rather than rediscovering.
72
+
73
+ **It is bounded.** 24 KB, and what goes when it does not fit is decided in the
74
+ API in a fixed order — the neighbourhood first, then the decisions, then the
75
+ tail of the body — and named in `trimmed`. **The acceptance criteria are never
76
+ trimmed**: a truncated pack is still a complete spec, which is what makes it
77
+ safe to call unconditionally.
78
+
79
+ **There are no ids in it but the item's own.** Everything else is titles, so
80
+ nothing in a pack can be pasted back into a call as an id — look one up by
81
+ title with `list_backlog` or `neighbourhood` when you need it. The item's id is
82
+ there because you have to name it back: `report_progress`, `open_session`, and
83
+ `Loopable: <id>` in the pull request.
84
+
85
+ **Pulling is not claiming.** `next_ready` is a read, and two harnesses asking
86
+ in the same second are told the same item. Claiming is `open_session` and
87
+ `report_progress` to `in_progress`. The plugin's `/loopable:start` will do the
88
+ whole sequence — pull, refuse when the item is not `ready` and list its
89
+ blockers, make the worktree, report and open the session — and until it lands,
90
+ doing it by hand in that order is the same thing.
91
+
92
+ `ready_blockers` is the one field to read before anything else. A non-empty
93
+ list means nobody has groomed the item — there is no criterion carrying a
94
+ verify method, or the project has no registered environment — and it is not
95
+ work to pick up yet.
96
+
97
+ ## Which kind
98
+
99
+ Epic, story, task and bug are defined once, in `apps/loopable/VOCABULARY.md`,
100
+ which the Loopable plugin ships as the skill reference
101
+ `skills/loopable/vocabulary.md` — the same text the product owner's prompt and
102
+ the in-app Help page read. `add_item` and `propose` quote its rule of thumb in
103
+ their own descriptions, because that is the sentence that decides most cases:
104
+
105
+ > If you cannot say what a person will see when it lands, it is not a story; if
106
+ > you cannot say what the client would call it, it is not an epic.
107
+
108
+ The rank rule that goes with it: epic outranks story outranks task, a parent
109
+ must outrank its child, levels may be skipped, and a bug sits outside the ranks
110
+ entirely — no parent, no children. Read the reference before inventing a shape.
47
111
 
48
112
  ## The two things to know
49
113
 
@@ -55,6 +119,22 @@ those routes are generated from one list so an agent can never reach something
55
119
  a person with the same membership cannot. Narrowing what an agent may touch
56
120
  means giving it a membership with a smaller role.
57
121
 
122
+ **The graph is a view, not a store.** `node`, `neighbourhood` and `path` walk
123
+ the same `graph_edges` view the product owner reads, through the same
124
+ `api/lib/graph.mjs`, wearing the same audience filter — which is why there is
125
+ no graph database here: a second store would need a second copy of the
126
+ authorization policy, and a policy in two places is a policy that will
127
+ disagree with itself. Every hop stands only on nodes the caller may read, so a
128
+ route that exists only through something they may not see comes back as **no
129
+ route** rather than as a gap they could infer a secret from.
130
+
131
+ **The brief is the exception, and it is the interesting one.** `write_brief`
132
+ proposes even though the same token could `add_item` — because the brief is
133
+ what readiness and verification are gated on, and a spec nobody agreed to is a
134
+ bar the agent set for itself. Reporting where a criterion was implemented and
135
+ whether it is met goes the other way: that is progress, not scope, and it is a
136
+ direct write.
137
+
58
138
  **The backlog and the queue are for different things.** `add_item` writes
59
139
  straight into the backlog; `propose` puts a draft in the approval queue for a
60
140
  human to accept, reword or decline. The line between them is not how much we
package/lib/tools.mjs CHANGED
@@ -52,6 +52,44 @@ export function makeClient({ apiUrl, token, fetch: doFetch = fetch }) {
52
52
  return { call };
53
53
  }
54
54
 
55
+ /*
56
+ * WHAT A NODE IS, said once for the three graph tools.
57
+ *
58
+ * The list is prose and not a schema `enum`, deliberately. api/lib/graph.mjs
59
+ * holds the vocabulary, and a copy of it validated HERE would refuse a kind
60
+ * the API had learned the day this package went a version out of date — the
61
+ * failure mode of every second copy of a policy. So an unknown kind travels
62
+ * and comes back as the API's own 400, which is the answer with the authority
63
+ * behind it.
64
+ */
65
+ const KIND_HELP =
66
+ 'What sort of thing that id names, and it defaults to work_item — which is '
67
+ + 'what a coding agent almost always has. The others: feature, decision, '
68
+ + 'evidence, commitment, stakeholder, raid, conversation, message, draft, '
69
+ + 'escalation, session.';
70
+
71
+ /** A node is (kind, id) everywhere in the graph; one string is easier to compare. */
72
+ const nodeKey = (kind, id) => `${kind}:${id}`;
73
+
74
+ /** kind:id -> the node, so an edge can be read without its ends looked up by hand. */
75
+ const titleIndex = (nodes = []) =>
76
+ new Map(nodes.map((n) => [nodeKey(n.kind, n.id), n]));
77
+
78
+ /**
79
+ * An edge with both of its ends named.
80
+ *
81
+ * The API answers edges as four columns because that is what the walk produced
82
+ * and what the SPA draws with; a model reading a tool result wants the words.
83
+ * Both ends are always in `nodes` — the API returns an edge only when both of
84
+ * them survived the audience filter — so a missing title here would be a bug
85
+ * in that invariant rather than something to paper over with a fallback.
86
+ */
87
+ const withTitles = (edge, named) => ({
88
+ relation: edge.relation,
89
+ from: named.get(nodeKey(edge.from_kind, edge.from_id)) ?? null,
90
+ to: named.get(nodeKey(edge.to_kind, edge.to_id)) ?? null,
91
+ });
92
+
55
93
  /**
56
94
  * The tools, in the order an agent uses them: find out where you are, read
57
95
  * what you are meant to build, write down work, propose work that is not
@@ -117,29 +155,45 @@ export const TOOLS = [
117
155
  required: ['project_id'],
118
156
  additionalProperties: false,
119
157
  },
120
- run: (client, { project_id, status, parent_id, titles_only }) => {
158
+ run: async (client, { project_id, status, parent_id, titles_only }) => {
121
159
  const q = new URLSearchParams();
122
160
  if (status) q.set('status', status);
123
161
  if (parent_id) q.set('parent_id', parent_id);
124
162
  if (titles_only) q.set('bodies', 'false');
125
163
  const qs = q.toString();
126
- return client.call(
164
+ const out = await client.call(
127
165
  `/agent/projects/${encodeURIComponent(project_id)}/items${qs ? `?${qs}` : ''}`,
128
166
  );
167
+ /*
168
+ * THE REF LEADS ON THE ORIENTING READ. Same rows, same fields — only the
169
+ * order changes, and only here: titles_only is the read an agent makes
170
+ * to decide what to ask for next, and the first thing on the row should
171
+ * be the name it will use to ask. The full read keeps the server's order,
172
+ * because there the body is what somebody came for.
173
+ */
174
+ if (!titles_only || !Array.isArray(out?.items)) return out;
175
+ return { ...out, items: out.items.map(({ ref, ...rest }) => ({ ref, ...rest })) };
129
176
  },
130
177
  },
131
178
 
132
179
  {
133
180
  name: 'get_item',
134
181
  description:
135
- 'One work item in full: its body, its children by title, and the ' +
136
- 'dependency links touching it. The read to make after list_backlog with ' +
137
- 'titles_only told you which items matter.',
182
+ 'One work item in full: its body, its brief (the ask and the acceptance ' +
183
+ 'criteria), its children by title, and the dependency links touching it. ' +
184
+ 'The read to make after list_backlog with titles_only told you which ' +
185
+ 'items matter. `ready_blockers` on the item says why the last readiness ' +
186
+ 'pass would not let it start — a criterion with no verify method, no ' +
187
+ 'environment registered — and an item carrying any of them is not work ' +
188
+ 'to pick up yet.',
138
189
  input: {
139
190
  type: 'object',
140
191
  properties: {
141
192
  project_id: { type: 'string', description: 'From whoami.' },
142
- item_id: { type: 'string' },
193
+ item_id: {
194
+ type: 'string',
195
+ description: 'The item, by its id or by its ref — the short name, like s41. Refs are on every row list_backlog returns.',
196
+ },
143
197
  },
144
198
  required: ['project_id', 'item_id'],
145
199
  additionalProperties: false,
@@ -150,6 +204,277 @@ export const TOOLS = [
150
204
  ),
151
205
  },
152
206
 
207
+ /*
208
+ * THE FIRST CALL OF ANY WORK SESSION.
209
+ *
210
+ * `pull_item` and `next_ready` are one answer under two questions — "brief
211
+ * me on this" and "what should I pick up" — and they are deliberately the
212
+ * cheapest thing a harness can do at the start, because the alternative is
213
+ * what harnesses used to do: get_item, then neighbourhood, then
214
+ * list_decisions, then the environments, each one a judgement call about
215
+ * whether the context could afford it. A model budgeting its own reading
216
+ * reads the wrong half.
217
+ *
218
+ * THE PACK IS BOUNDED AND IT SAYS SO. `pack_bytes` and `truncated` are on
219
+ * every answer, and `trimmed` names what went — neighbourhood first, then
220
+ * decisions, then the tail of the body. The acceptance criteria are never
221
+ * trimmed, so a pack that came back truncated is still a complete spec.
222
+ *
223
+ * NO IDS BUT THE ITEM'S OWN, which is the property to rely on rather than
224
+ * to notice: everything else is titles, so nothing in a pack can be pasted
225
+ * into a call as an id. When you need one, the thing to do is look it up by
226
+ * title with `list_backlog` or `neighbourhood` — and the id you were given
227
+ * is the one you report progress against and the one that goes in the PR.
228
+ */
229
+ {
230
+ name: 'pull_item',
231
+ description:
232
+ 'THE FIRST CALL OF A WORK SESSION: everything needed to start on one ' +
233
+ 'item, in one bounded answer. The item and its ask, the acceptance ' +
234
+ 'criteria with how each will be checked, what is around it in the graph ' +
235
+ 'BY TITLE, the standing decisions that govern it, the registered ' +
236
+ 'environments to point at, and `ready_blockers` — which, if it is not ' +
237
+ 'empty, means the item is not groomed and is not work to pick up yet. ' +
238
+ 'Prefer this over get_item plus neighbourhood plus list_decisions: it is ' +
239
+ 'the same reads, assembled once and capped. `truncated` with `trimmed` ' +
240
+ 'says what was cut to make it fit — the neighbourhood goes first, the ' +
241
+ 'criteria never go — and the only id in the answer is the item’s own.',
242
+ input: {
243
+ type: 'object',
244
+ properties: {
245
+ project_id: { type: 'string', description: 'From whoami.' },
246
+ item_id: { type: 'string', description: 'The item to be briefed on, by id or ref (s41).' },
247
+ },
248
+ required: ['project_id', 'item_id'],
249
+ additionalProperties: false,
250
+ },
251
+ run: async (client, { project_id, item_id }) => {
252
+ const { pack } = await client.call(
253
+ `/agent/projects/${encodeURIComponent(project_id)}`
254
+ + `/items/${encodeURIComponent(item_id)}/pack`,
255
+ );
256
+ return pack;
257
+ },
258
+ },
259
+
260
+ {
261
+ name: 'next_ready',
262
+ description:
263
+ 'What to pick up next: the oldest `ready` item nobody has an open ' +
264
+ 'session on, as the same pack pull_item returns. `ready` means a person ' +
265
+ 'or a grooming pass judged it startable — criteria somebody can act on, ' +
266
+ 'and somewhere to run them — so an item this hands back needs no ' +
267
+ 'further check before starting. `null` is an ordinary answer and not an ' +
268
+ 'error: it means everything is either not ready or already being ' +
269
+ 'worked. IT DOES NOT CLAIM THE ITEM. Two harnesses asking at the same ' +
270
+ 'moment are told the same thing; claiming is open_session, and ' +
271
+ 'report_progress to in_progress.',
272
+ input: {
273
+ type: 'object',
274
+ properties: {
275
+ project_id: { type: 'string', description: 'From whoami.' },
276
+ feature_id: {
277
+ type: 'string',
278
+ description:
279
+ 'Only items tagged with this feature — a surface of the product, '
280
+ + 'from list_backlog. Omit for the whole backlog.',
281
+ },
282
+ },
283
+ required: ['project_id'],
284
+ additionalProperties: false,
285
+ },
286
+ run: async (client, { project_id, feature_id }) => {
287
+ const q = feature_id ? `?feature_id=${encodeURIComponent(feature_id)}` : '';
288
+ const { pack } = await client.call(
289
+ `/agent/projects/${encodeURIComponent(project_id)}/items/next-ready${q}`,
290
+ );
291
+ return pack;
292
+ },
293
+ },
294
+
295
+ /*
296
+ * THE GRAPH, AS THREE QUESTIONS.
297
+ *
298
+ * The registers were always a graph — the parent tree, the blocking DAG,
299
+ * feature tags, mentions, supersession, provenance — and 20260908030000 made
300
+ * it traversable without adding a graph store to traverse (there is one copy
301
+ * of the authorization policy, and a second store would need a second copy).
302
+ * These three tools are the same surface the product owner reads with, over
303
+ * the same routes, wearing the same audience filter: a coding agent asking
304
+ * "what does this touch" gets the answer its own membership is owed and no
305
+ * more, and a route through something it may not read comes back as no route
306
+ * rather than as a gap it could infer from.
307
+ *
308
+ * WHICH ONE TO REACH FOR is the thing worth spelling out, because all three
309
+ * answer with nodes and edges and a model will otherwise pick the biggest:
310
+ *
311
+ * node you have an id and want its immediate surroundings. The
312
+ * cheapest read: one node, the edges touching it, and what
313
+ * is on the other end of each.
314
+ * neighbourhood you are orienting. One or two hops, filterable by
315
+ * relation, and two hops of a busy epic is most of a
316
+ * project — which is what the cap and the filter are for.
317
+ * path you have TWO things and the question is whether they are
318
+ * connected at all, and by what. Never the tool for "what
319
+ * is near this".
320
+ *
321
+ * THE IDS THAT COME BACK are the ids of nodes the caller could have listed:
322
+ * a work item, a feature, a decision. No member uuid, no row id belonging to
323
+ * something with no list route — and every node carries its title and its
324
+ * kind, because a hex string is not an answer a person or a model can act on.
325
+ */
326
+ {
327
+ name: 'node',
328
+ description:
329
+ 'One node and the edges touching it: what it is called, what kind of ' +
330
+ 'thing it is, and everything one step away with the relation naming the ' +
331
+ 'step (parent, blocks, tag, evidence_tag, mention, supersedes, ' +
332
+ 'provenance, session, about). The cheapest orientation there is, and the ' +
333
+ 'right call when you have just pulled an item and want to know what it ' +
334
+ 'touches. For two hops, or to keep only some relations, use ' +
335
+ 'neighbourhood; to ask how two particular things relate, use path.',
336
+ input: {
337
+ type: 'object',
338
+ properties: {
339
+ project_id: { type: 'string', description: 'From whoami.' },
340
+ id: { type: 'string', description: 'The node id — a work item id unless you say otherwise.' },
341
+ kind: {
342
+ type: 'string',
343
+ description: KIND_HELP,
344
+ },
345
+ },
346
+ required: ['project_id', 'id'],
347
+ additionalProperties: false,
348
+ },
349
+ /*
350
+ * ONE HOP, THEN NARROWED HERE. The route answers a neighbourhood, which at
351
+ * one hop also carries the edges BETWEEN two neighbours — true, and not
352
+ * what was asked. Filtering to the edges touching the node is what makes
353
+ * this a different question from neighbourhood rather than a spelling of
354
+ * it, and it is done here because the route is shared with the product
355
+ * owner and the inspector, which both want the wider answer.
356
+ */
357
+ run: async (client, { project_id, id, kind = 'work_item' }) => {
358
+ const seen = await client.call(
359
+ `/agent/projects/${encodeURIComponent(project_id)}/graph/`
360
+ + `${encodeURIComponent(kind)}/${encodeURIComponent(id)}?depth=1`,
361
+ );
362
+ const here = nodeKey(kind, id);
363
+ const named = titleIndex(seen.nodes);
364
+ return {
365
+ node: seen.node,
366
+ edges: seen.edges
367
+ .filter((e) => nodeKey(e.from_kind, e.from_id) === here
368
+ || nodeKey(e.to_kind, e.to_id) === here)
369
+ .map((e) => withTitles(e, named)),
370
+ };
371
+ },
372
+ },
373
+
374
+ {
375
+ name: 'neighbourhood',
376
+ description:
377
+ 'What is around one node, out to one or two hops, with every node named ' +
378
+ 'and every edge saying which relation joins which two. The read to make ' +
379
+ 'when orienting on a piece of work: it crosses the planes a single list ' +
380
+ 'cannot — the item, the feature it touches, the decision that governs ' +
381
+ 'it, the evidence behind that — in one answer. TWO HOPS OF A BUSY EPIC ' +
382
+ 'IS MOST OF A PROJECT: start at one, and use relation to keep only the ' +
383
+ 'kind of link you are actually asking about. `truncated` means the ' +
384
+ 'answer was cut at the cap and the nearest nodes are what survived.',
385
+ input: {
386
+ type: 'object',
387
+ properties: {
388
+ project_id: { type: 'string', description: 'From whoami.' },
389
+ id: { type: 'string', description: 'The node id — a work item id unless you say otherwise.' },
390
+ kind: {
391
+ type: 'string',
392
+ description: KIND_HELP,
393
+ },
394
+ hops: {
395
+ type: 'integer',
396
+ description:
397
+ 'How far to walk: 1 (the default) or 2. Two is for a question one ' +
398
+ 'could not answer — "what evidence is behind the feature this story ' +
399
+ 'touches" — and costs most of a project to ask idly.',
400
+ },
401
+ relation: {
402
+ type: 'string',
403
+ description:
404
+ 'Keep only these relations, comma-separated: parent, blocks, tag, '
405
+ + 'evidence_tag, mention, supersedes, provenance, session, about. '
406
+ + 'A word that is not one of those is refused rather than quietly '
407
+ + 'returning nothing.',
408
+ },
409
+ },
410
+ required: ['project_id', 'id'],
411
+ additionalProperties: false,
412
+ },
413
+ run: async (client, { project_id, id, kind = 'work_item', hops, relation }) => {
414
+ const q = new URLSearchParams({ depth: String(hops ?? 1) });
415
+ if (relation) q.set('relation', relation);
416
+ const seen = await client.call(
417
+ `/agent/projects/${encodeURIComponent(project_id)}/graph/`
418
+ + `${encodeURIComponent(kind)}/${encodeURIComponent(id)}?${q.toString()}`,
419
+ );
420
+ const named = titleIndex(seen.nodes);
421
+ return {
422
+ node: seen.node,
423
+ nodes: seen.nodes,
424
+ edges: seen.edges.map((e) => withTitles(e, named)),
425
+ truncated: seen.truncated ?? false,
426
+ };
427
+ },
428
+ },
429
+
430
+ {
431
+ name: 'path',
432
+ description:
433
+ 'How two things relate: the shortest route between them, as the nodes ' +
434
+ 'along it and the relations between those. "Is this bug anywhere near ' +
435
+ 'that feature", "what connects this story to the decision we made in ' +
436
+ 'March" — questions with TWO subjects, which neighbourhood cannot ' +
437
+ 'answer. `found: false` means no route within the hop limit THAT YOU MAY ' +
438
+ 'SEE: a chain that only exists through something your membership does ' +
439
+ 'not reach is no chain, and you are not told one is there.',
440
+ input: {
441
+ type: 'object',
442
+ properties: {
443
+ project_id: { type: 'string', description: 'From whoami.' },
444
+ from_id: { type: 'string' },
445
+ to_id: { type: 'string' },
446
+ from_kind: { type: 'string', description: KIND_HELP },
447
+ to_kind: { type: 'string', description: KIND_HELP },
448
+ hops: {
449
+ type: 'integer',
450
+ description:
451
+ 'How far to look, 1 to 6. Six is the default and the ceiling: past ' +
452
+ 'about six hops everything is connected to everything and the ' +
453
+ 'answer stops being information.',
454
+ },
455
+ relation: {
456
+ type: 'string',
457
+ description:
458
+ 'Only routes made of these relations, comma-separated. "How does '
459
+ + 'this story reach that one through blocking alone" is a different '
460
+ + 'question from "are they connected", and this is how to ask it.',
461
+ },
462
+ },
463
+ required: ['project_id', 'from_id', 'to_id'],
464
+ additionalProperties: false,
465
+ },
466
+ run: (client, {
467
+ project_id, from_id, to_id, from_kind = 'work_item', to_kind = 'work_item', hops, relation,
468
+ }) => {
469
+ const q = new URLSearchParams({ from_kind, from_id, to_kind, to_id });
470
+ if (hops !== undefined) q.set('hops', String(hops));
471
+ if (relation) q.set('relation', relation);
472
+ return client.call(
473
+ `/agent/projects/${encodeURIComponent(project_id)}/graph/path?${q.toString()}`,
474
+ );
475
+ },
476
+ },
477
+
153
478
  {
154
479
  name: 'list_decisions',
155
480
  description:
@@ -235,13 +560,17 @@ export const TOOLS = [
235
560
  name: 'add_item',
236
561
  description:
237
562
  'Write a work item into the backlog: work the studio has decided to do. ' +
563
+ 'Which kind, by rule of thumb: if you cannot say what a person will see ' +
564
+ 'when it lands, it is not a story; if you cannot say what the client ' +
565
+ 'would call it, it is not an epic. ' +
238
566
  'Pass parent_id to file it under an epic or story — the parent need only ' +
239
567
  'OUTRANK the item (epic > story > task, levels may be skipped, so a task ' +
240
568
  'sits directly under an epic). A bug stands alone: no parent, no children ' +
241
569
  '— it is something broken on a surface, and feature_ids says which. ' +
242
570
  'Features themselves are not work items: to ask for a new surface, use ' +
243
571
  'propose with kind feature. For something SOMEBODY ELSE asked for, use ' +
244
- 'propose instead.',
572
+ 'propose instead. The full definitions are the loopable skill reference ' +
573
+ 'vocabulary.md — read it before inventing a shape.',
245
574
  input: {
246
575
  type: 'object',
247
576
  properties: {
@@ -251,12 +580,12 @@ export const TOOLS = [
251
580
  kind: { type: 'string', enum: ['epic', 'story', 'task', 'bug'] },
252
581
  parent_id: {
253
582
  type: 'string',
254
- description: 'An existing item of a broader kind than this one — epic > story > task, and levels may be skipped. Omit for a root; a bug never has one.',
583
+ description: 'An existing item of a broader kind than this one, by id or ref (e12) — epic > story > task, and levels may be skipped. Omit for a root; a bug never has one.',
255
584
  },
256
585
  feature_ids: {
257
586
  type: 'array',
258
587
  items: { type: 'string' },
259
- description: 'The features (surfaces) this work touches — ids from list_backlog. One is usual, several is legal, none is fine.',
588
+ description: 'The features (surfaces) this work touches — ids from list_backlog (their refs, f7, are for people; this list takes ids). One is usual, several is legal, none is fine.',
260
589
  },
261
590
  },
262
591
  required: ['project_id', 'title'],
@@ -280,7 +609,10 @@ export const TOOLS = [
280
609
  'the feature plane, not in the backlog). It goes to the approval queue ' +
281
610
  'for a human to accept, reword or decline — it does NOT become work. Say ' +
282
611
  'what was asked and who asked. For work the studio has already decided to ' +
283
- 'do, use add_item instead.',
612
+ 'do, use add_item instead. Same rule of thumb for the kind: if you ' +
613
+ 'cannot say what a person will see when it lands, it is not a story; if ' +
614
+ 'you cannot say what the client would call it, it is not an epic. The ' +
615
+ 'full definitions are the loopable skill reference vocabulary.md.',
284
616
  input: {
285
617
  type: 'object',
286
618
  properties: {
@@ -310,7 +642,10 @@ export const TOOLS = [
310
642
  type: 'object',
311
643
  properties: {
312
644
  project_id: { type: 'string' },
313
- item_id: { type: 'string' },
645
+ item_id: {
646
+ type: 'string',
647
+ description: 'The item, by its id or by its ref — the short name, like s41. Refs are on every row list_backlog returns.',
648
+ },
314
649
  title: { type: 'string' },
315
650
  body: { type: 'string' },
316
651
  },
@@ -388,24 +723,43 @@ export const TOOLS = [
388
723
  },
389
724
  {
390
725
  name: 'report_progress',
726
+ /*
727
+ * THE ENUM IS THE AGENT'S HALF OF THE TRANSITION TABLE, and it is shorter
728
+ * than the API's list on purpose. `ready`, `verifying` and `done` are a
729
+ * person's words — grooming, deploying and accepting are seats a person
730
+ * sits in — and the API refuses them from a token whatever this file
731
+ * offers. Offering them here anyway would only turn a rule into a 403 the
732
+ * agent discovers by trying, which is a worse way to learn it.
733
+ */
391
734
  description:
392
- 'Move a work item to todo, in_progress or done. This is how the backlog ' +
393
- 'stays true — report it as part of finishing, not as a chore afterwards, ' +
394
- 'and say WHAT happened in the note ("shipped in PR 475, verified live"): ' +
395
- 'that sentence exists only right now, and the studio feed is a delivery ' +
396
- 'log exactly as far as people write it. To change what an item SAYS ' +
397
- 'rather than where it is, use revise.',
735
+ 'Move a work item to todo, in_progress, in_review, blocked or ' +
736
+ 'awaiting_input. This is how the backlog stays true — report it as part ' +
737
+ 'of doing the work, not as a chore afterwards, and say WHAT happened in ' +
738
+ 'the note ("opened PR 475, tests green"): that sentence exists only ' +
739
+ 'right now, and the studio feed is a delivery log exactly as far as ' +
740
+ 'people write it. in_review is as far as you go: a person reads the ' +
741
+ 'diff, merges, and accepts the work as done. Say blocked when something ' +
742
+ 'outside the item is stopping you and awaiting_input when you need an ' +
743
+ 'answer — both beat leaving the item claiming work is happening. To ' +
744
+ 'change what an item SAYS rather than where it is, use revise.',
398
745
  input: {
399
746
  type: 'object',
400
747
  properties: {
401
748
  project_id: { type: 'string' },
402
- item_id: { type: 'string' },
403
- status: { type: 'string', enum: ['todo', 'in_progress', 'done'] },
749
+ item_id: {
750
+ type: 'string',
751
+ description: 'The item, by its id or by its ref — the short name, like s41. Refs are on every row list_backlog returns.',
752
+ },
753
+ status: {
754
+ type: 'string',
755
+ enum: ['todo', 'in_progress', 'in_review', 'blocked', 'awaiting_input'],
756
+ },
404
757
  note: {
405
758
  type: 'string',
406
759
  description:
407
- 'One sentence about this move, for the studio. Replaced by the ' +
408
- 'next status change; clients never see it raw.',
760
+ 'One sentence about this move, for the studio. Cite other work by ' +
761
+ 'its ref — "waiting on t44" — the way a person would. Replaced by ' +
762
+ 'the next status change; clients never see it raw.',
409
763
  },
410
764
  },
411
765
  required: ['project_id', 'item_id', 'status'],
@@ -420,6 +774,293 @@ export const TOOLS = [
420
774
  { method: 'PATCH', body: JSON.stringify(note ? { status, note } : { status }) },
421
775
  ),
422
776
  },
777
+
778
+ {
779
+ name: 'write_brief',
780
+ description:
781
+ 'Write the BRIEF of one story, task or bug — the spec, as rows: the ask ' +
782
+ 'as it was actually made, the acceptance criteria each carrying how it ' +
783
+ 'will be checked, what is out of scope, what you assumed, what is still ' +
784
+ 'open. It goes to the approval queue: unlike add_item, a brief is ' +
785
+ 'PROPOSED even by an agent that could write the backlog directly, ' +
786
+ 'because the brief is what readiness and verification are gated on and a ' +
787
+ 'person has to have agreed to it. Approving replaces the item’s criteria ' +
788
+ 'whole and bumps its revision. Read the item first (get_item returns the ' +
789
+ 'brief) — you are writing the next revision of it, not adding to it. ' +
790
+ 'Never on an epic: an epic is a container.',
791
+ input: {
792
+ type: 'object',
793
+ properties: {
794
+ project_id: { type: 'string', description: 'From whoami.' },
795
+ item_id: {
796
+ type: 'string',
797
+ description: 'The story, task or bug this is the spec of, by id or ref (s41).',
798
+ },
799
+ title: {
800
+ type: 'string',
801
+ description:
802
+ 'One line naming what this brief is for — it is what the approval ' +
803
+ 'queue shows the person deciding.',
804
+ },
805
+ ask: {
806
+ type: 'string',
807
+ description:
808
+ 'The request as it was made, quoted. Not your summary of it — the ' +
809
+ 'item body is already that.',
810
+ },
811
+ criteria: {
812
+ type: 'array',
813
+ description:
814
+ 'At least one, and each needs a verify method — a criterion nothing ' +
815
+ 'can check is a wish, and readiness counts these.',
816
+ items: {
817
+ type: 'object',
818
+ properties: {
819
+ text: { type: 'string', description: 'One checkable statement.' },
820
+ source: {
821
+ type: 'string',
822
+ enum: ['issue', 'inferred', 'client'],
823
+ description:
824
+ 'Where it came from. Be honest about inferred — it is what ' +
825
+ 'tells a person which criteria they never actually asked for.',
826
+ },
827
+ verify: {
828
+ type: 'string',
829
+ enum: ['browser', 'http', 'eval', 'manual'],
830
+ description: 'How it will be checked.',
831
+ },
832
+ },
833
+ required: ['text', 'verify'],
834
+ additionalProperties: false,
835
+ },
836
+ },
837
+ out_of_scope: { type: 'array', items: { type: 'string' } },
838
+ assumptions: { type: 'array', items: { type: 'string' } },
839
+ open_questions: { type: 'array', items: { type: 'string' } },
840
+ },
841
+ required: ['project_id', 'item_id', 'title', 'criteria'],
842
+ additionalProperties: false,
843
+ },
844
+ /*
845
+ * A draft, through the ordinary proposals door — no privileged path here
846
+ * either. The kind rides the default ('story'): approving a brief creates
847
+ * nothing, it writes onto the item the payload names.
848
+ */
849
+ run: (client, { project_id, item_id, title, ...brief }) =>
850
+ client.call(`/agent/projects/${encodeURIComponent(project_id)}/drafts`, {
851
+ method: 'POST',
852
+ body: JSON.stringify({
853
+ title,
854
+ proposal_type: 'brief',
855
+ payload: { item_id, ...brief },
856
+ }),
857
+ }),
858
+ },
859
+
860
+ /*
861
+ * SESSIONS. What you are doing, while you are doing it.
862
+ *
863
+ * These three are not reporting-after-the-fact — report_progress is that.
864
+ * A session is the live record: a person watching the console, and the
865
+ * product owner watching for stalls, both read this table and nothing else.
866
+ * Which is why post_activity is cheap and expected to be frequent, and why
867
+ * the plugin's hooks call it without a model in the path (S2.2).
868
+ *
869
+ * What a CLIENT sees of all this is one sentence — "an agent is working on
870
+ * X" — and never a body. Write the bodies for the studio, plainly.
871
+ */
872
+ {
873
+ name: 'open_session',
874
+ description:
875
+ 'Say you have started working on an item: opens a session, which is the ' +
876
+ 'live record of this piece of work — the console and the product owner ' +
877
+ 'both read it. Do it once, when you start, and keep the id: ' +
878
+ 'post_activity and close_session both need it. Say which harness, which ' +
879
+ 'repo and which branch, so a person watching can find what you are doing.',
880
+ input: {
881
+ type: 'object',
882
+ properties: {
883
+ project_id: { type: 'string', description: 'From whoami.' },
884
+ item_id: {
885
+ type: 'string',
886
+ description: 'The work item you are starting on, by id or ref (s41).',
887
+ },
888
+ harness: { type: 'string', description: 'What you are — "claude-code", say.' },
889
+ repo: { type: 'string', description: 'The repository, as a person would name it.' },
890
+ branch: { type: 'string', description: 'The branch you are working on.' },
891
+ },
892
+ required: ['project_id', 'item_id'],
893
+ additionalProperties: false,
894
+ },
895
+ // Whose session is read from the TOKEN, never sent — the proposer rule,
896
+ // at a different table. A caller that could name the member could sign
897
+ // somebody else's name to a night of work.
898
+ run: (client, { project_id, ...session }) =>
899
+ client.call(`/agent/projects/${encodeURIComponent(project_id)}/sessions`, {
900
+ method: 'POST',
901
+ body: JSON.stringify(session),
902
+ }),
903
+ },
904
+
905
+ {
906
+ name: 'post_activity',
907
+ description:
908
+ 'Add one line to an open session: a thought, an action, a question, a ' +
909
+ 'result or an error. This is the stream a person watches, so post as you ' +
910
+ 'go rather than in a batch at the end — a session with no activity for a ' +
911
+ 'while reads as stalled, and that is the point of it. A `question` puts ' +
912
+ 'the session in awaiting_input; to actually ASK the studio something and ' +
913
+ 'get an answer back, use ask_studio.',
914
+ input: {
915
+ type: 'object',
916
+ properties: {
917
+ project_id: { type: 'string', description: 'From whoami.' },
918
+ session_id: { type: 'string', description: 'From open_session.' },
919
+ kind: {
920
+ type: 'string',
921
+ enum: ['thought', 'action', 'question', 'result', 'error'],
922
+ },
923
+ body: { type: 'string', description: 'What happened, in a sentence or two.' },
924
+ ref: {
925
+ type: 'object',
926
+ description:
927
+ 'What it points at, if anything: a file, a tool call, a PR, a sha. ' +
928
+ 'Free-form — the shape differs per harness.',
929
+ },
930
+ },
931
+ required: ['project_id', 'session_id', 'kind', 'body'],
932
+ additionalProperties: false,
933
+ },
934
+ run: (client, { project_id, session_id, ...activity }) =>
935
+ client.call(
936
+ `/agent/projects/${encodeURIComponent(project_id)}/sessions/${encodeURIComponent(session_id)}/activities`,
937
+ { method: 'POST', body: JSON.stringify(activity) },
938
+ ),
939
+ },
940
+
941
+ /*
942
+ * THE CONTRACT IS SPELLED OUT HERE so that nobody has to guess it from a
943
+ * 422. Closing `complete` is the one moment an agent gets to say the work
944
+ * is done, and the API asks it to prove that: a brief revision, a HEAD sha,
945
+ * a verifier verdict, every acceptance criterion accounted for, screenshots
946
+ * where a browser was the way to check, and what it cost. A missing field
947
+ * comes back as one 422 naming all of them, and NOTHING moves — the session
948
+ * stays open and the item stays in_progress.
949
+ *
950
+ * THE `required` LIST BELOW IS THE ALWAYS-REQUIRED SET, and deliberately
951
+ * does not include the contract. An `error` close owes none of it: an agent
952
+ * that stopped because something broke has no sha worth recording and no
953
+ * verdict worth trusting, and a schema that demanded them would only teach
954
+ * it to close `complete` with invented values. So the descriptions carry
955
+ * the conditional rule that this schema cannot express, and `state` is
956
+ * required — which ending this was is not a thing to leave to a default.
957
+ */
958
+ {
959
+ name: 'close_session',
960
+ description:
961
+ 'End the session: "complete" when the work is done, "error" when you ' +
962
+ 'stopped because something broke. A "complete" close is a CLAIM, and it ' +
963
+ 'comes with its evidence — brief_rev, head_sha, verdict, criteria, ' +
964
+ 'screenshot_ids and cost are all required, a missing one is a 422 that ' +
965
+ 'names every field you left out, and the item stays in_progress until ' +
966
+ 'you send them. A successful "complete" close moves the item to ' +
967
+ 'in_review for you; an "error" close owes none of it and moves nothing.',
968
+ input: {
969
+ type: 'object',
970
+ properties: {
971
+ project_id: { type: 'string', description: 'From whoami.' },
972
+ session_id: { type: 'string', description: 'From open_session.' },
973
+ state: {
974
+ type: 'string',
975
+ enum: ['complete', 'error'],
976
+ description:
977
+ 'complete when the work is done and you can prove it; error when you ' +
978
+ 'stopped because something broke. Say which — do not let it default.',
979
+ },
980
+ summary: { type: 'string', description: 'What happened, for whoever reads this later.' },
981
+ brief_rev: {
982
+ type: 'integer',
983
+ description:
984
+ 'Required to close complete. Which revision of the item brief you built ' +
985
+ 'against — brief_rev from pull_item or get_item. A brief is rewritten ' +
986
+ 'whole, so "it met the criteria" is a claim about a revision or about ' +
987
+ 'nothing. You cannot name one that does not exist yet.',
988
+ },
989
+ head_sha: {
990
+ type: 'string',
991
+ description:
992
+ 'Required to close complete. The commit you built, as a git sha. The ' +
993
+ 'verifier and the merge guard both read it; a verdict with nothing ' +
994
+ 'underneath it is a claim about a working tree nobody can retrieve.',
995
+ },
996
+ verdict: {
997
+ type: 'string',
998
+ enum: ['pass', 'fail', 'not_run'],
999
+ description:
1000
+ 'Required to close complete. What your own verification said. not_run is ' +
1001
+ 'a real answer and costs you nothing — say it rather than spelling ' +
1002
+ 'unchecked as pass. fail is a perfectly good close: the record is worth ' +
1003
+ 'more when it can carry bad news.',
1004
+ },
1005
+ verdict_reason: {
1006
+ type: 'string',
1007
+ description:
1008
+ 'Required when the verdict is fail or not_run. One sentence saying why — ' +
1009
+ 'those are the verdicts somebody has to act on, and one word is not ' +
1010
+ 'enough to act on.',
1011
+ },
1012
+ criteria: {
1013
+ type: 'array',
1014
+ description:
1015
+ 'Required to close complete, and it must account for EVERY acceptance ' +
1016
+ 'criterion of the item — one entry each, no more and no fewer. Each is ' +
1017
+ '{ id, implemented_at, status }: the id from the brief, implemented_at a ' +
1018
+ 'path, route, test name or sentence saying where it landed, and status ' +
1019
+ 'met or skipped (a close cannot leave one open — skipped is how you say ' +
1020
+ 'so honestly). This writes progress, not scope: it never changes what a ' +
1021
+ 'criterion says, and it does not cost a brief revision.',
1022
+ items: {
1023
+ type: 'object',
1024
+ properties: {
1025
+ id: { type: 'string' },
1026
+ implemented_at: { type: 'string' },
1027
+ status: { type: 'string', enum: ['met', 'skipped'] },
1028
+ },
1029
+ required: ['id', 'implemented_at', 'status'],
1030
+ },
1031
+ },
1032
+ screenshot_ids: {
1033
+ type: 'array',
1034
+ description:
1035
+ 'Required to close complete — an empty list if there is genuinely ' +
1036
+ 'nothing to show, because an empty list is a claim and a missing field ' +
1037
+ 'is a shrug. Each must be a STORED IMAGE attachment of this project. At ' +
1038
+ 'least one is required when any criterion of the item is verified in a ' +
1039
+ 'browser.',
1040
+ items: { type: 'string' },
1041
+ },
1042
+ cost: {
1043
+ type: 'object',
1044
+ description:
1045
+ 'Required to close complete: { tokens, usd }, both whole-hearted numbers ' +
1046
+ 'and both allowed to be zero. Zero means it cost nothing; leaving it out ' +
1047
+ 'would mean nobody measured, and those must not look the same.',
1048
+ properties: {
1049
+ tokens: { type: 'integer' },
1050
+ usd: { type: 'number' },
1051
+ },
1052
+ required: ['tokens', 'usd'],
1053
+ },
1054
+ },
1055
+ required: ['project_id', 'session_id', 'state'],
1056
+ additionalProperties: false,
1057
+ },
1058
+ run: (client, { project_id, session_id, ...ending }) =>
1059
+ client.call(
1060
+ `/agent/projects/${encodeURIComponent(project_id)}/sessions/${encodeURIComponent(session_id)}/close`,
1061
+ { method: 'POST', body: JSON.stringify(ending) },
1062
+ ),
1063
+ },
423
1064
  ];
424
1065
 
425
1066
  export const toolByName = (name) => {
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The version the server announces is the version it was published as.
3
+ *
4
+ * server.mjs once carried a literal '0.1.0' that survived a release to 0.2.0,
5
+ * so a harness asking the server what it was got a number npm disagreed
6
+ * with. package.json is the one copy — it is what the release tag is checked
7
+ * against and what npm records — so it is read here, once, at startup.
8
+ */
9
+ import { readFileSync } from 'node:fs';
10
+
11
+ const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
12
+
13
+ export const VERSION = pkg.version;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@loopable/mcp",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "description": "The Loopable MCP server: an agent reads the backlog it is meant to build, proposes work, asks the studio a question, and says when it is done.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://loopable.ai",
package/server.mjs CHANGED
@@ -21,6 +21,7 @@ import {
21
21
  } from '@modelcontextprotocol/sdk/types.js';
22
22
  import { LoopableError, TOOLS, makeClient, runTool } from './lib/tools.mjs';
23
23
  import { resolveToken } from './lib/token.mjs';
24
+ import { VERSION } from './lib/version.mjs';
24
25
 
25
26
  /**
26
27
  * Built on first use, not at startup.
@@ -45,7 +46,7 @@ const clientOrThrow = () => {
45
46
  };
46
47
 
47
48
  const server = new Server(
48
- { name: 'loopable', version: '0.1.0' },
49
+ { name: 'loopable', version: VERSION },
49
50
  { capabilities: { tools: {} } },
50
51
  );
51
52