@agent-tasks/mcp-server 0.11.0 → 0.13.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,542 @@
1
+ // Central receipt layer for write-verb responses. Normative reference:
2
+ // docs/response-contract-v1.md. This is the "new responsibility at the
3
+ // choke point" the contract calls out for tools.ts's wrap() helper — this
4
+ // module is that responsibility, kept separate from wrap() itself so wrap()
5
+ // stays a pure error-mapping helper and the receipt projection stays
6
+ // independently testable.
7
+ //
8
+ // A receipt has three tiers layered in one object:
9
+ // Tier 1 (confirm) — always present, <= ~60 tokens.
10
+ // Tier 2 (deviations) — present only when something needs the caller's
11
+ // attention, <= ~400 tokens.
12
+ // Tier 3 (next) — optional, 1-3 free-form hints, present only when
13
+ // there is an obvious follow-up call.
14
+ //
15
+ // Every verb's `include: ["task"]` valve returns the backend object
16
+ // verbatim, bypassing the tier machinery entirely — the old, pre-contract
17
+ // shape stays reachable unchanged. Most write verbs check this in their
18
+ // tools.ts handler before calling into this module at all; task_pickup's
19
+ // projectPickup and task_start's receiptForStart instead own the check
20
+ // themselves, since both verbs' `include` vocabulary is wider than the
21
+ // single "task" value the other write verbs accept, so the valve lives at
22
+ // the same layer as the rest of their include handling.
23
+ import { DEFAULT_WORKFLOW_AGENT_INSTRUCTIONS, DEFAULT_WORKFLOW_TRANSITIONS, } from "./default-workflow.js";
24
+ /** Low-level composer. Every receiptFor* builder below funnels through this
25
+ * so the tier layering (present/absent rules) lives in exactly one place. */
26
+ export function buildReceipt(opts) {
27
+ const receipt = {
28
+ ok: true,
29
+ task: opts.status !== undefined
30
+ ? { id: opts.taskId, status: opts.status }
31
+ : { id: opts.taskId },
32
+ };
33
+ if (opts.transition)
34
+ receipt.transition = opts.transition;
35
+ if (opts.confidence !== undefined)
36
+ receipt.confidence = opts.confidence;
37
+ if (opts.deviations && opts.deviations.length > 0)
38
+ receipt.deviations = opts.deviations;
39
+ if (opts.next && opts.next.length > 0)
40
+ receipt.next = opts.next;
41
+ return receipt;
42
+ }
43
+ // Shared clamp for every deviation's array-valued detail field (`missing[]`
44
+ // on CONFIDENCE_BELOW_THRESHOLD, `rejected[]` on DEPENDS_ON_REJECTED,
45
+ // `dropped[]` on LABELS_DROPPED, `skipped[]` on WORKFLOW_GATE_SKIPPED):
46
+ // first N entries plus an explicit total count, so a caller at the tail of
47
+ // a long list still learns "there were more" instead of the array being
48
+ // silently truncated with no signal. This is a contract-wide rule (see
49
+ // docs/response-contract-v1.md's "Detail arrays are clamped" paragraph),
50
+ // applied unconditionally so it holds without exceptions, even for fields
51
+ // (like `skipped[]`, bounded by the fixed set of workflow gates) that can
52
+ // never actually reach the clamp in practice.
53
+ export const DETAIL_CLAMP = 5;
54
+ // Per-entry byte bound layered on top of DETAIL_CLAMP. DETAIL_CLAMP alone
55
+ // only bounds array LENGTH: a caller-influenced string entering a detail
56
+ // array (today: LABELS_DROPPED's `dropped[]`, sourced from task_create's
57
+ // `labels` schema, each up to 100 chars per tools.ts inputShape) can still
58
+ // blow the tier-2 budget at its own declared maximum even with only 5
59
+ // entries kept, measured at 1731 emitted chars (already over the
60
+ // 1600-char cap) with an unbounded entry length, before this clamp existed.
61
+ //
62
+ // 19 is not a round guess, it is the largest value that clears the tier-2
63
+ // budget with real headroom at the worst case (all three array-bearing
64
+ // task_create deviations firing at once, each at its schema/backend
65
+ // maximum): measured via tests/receipt.test.ts's maxima test at each
66
+ // candidate value. 20 chars already regresses to 1551 (over budget), 19
67
+ // measures 1541 (comfortable margin below both the test's 1550 floor and
68
+ // the 1600 cap itself). 19 also happens to be exactly long enough that the
69
+ // backend's longest `missing[]` field name ("acceptanceCriteria", 19
70
+ // chars) never truncates; the 36-char dependsOn UUIDs still do truncate
71
+ // under this bound, since there is no room left for a higher,
72
+ // ID-preserving value once labels are at their real maximum. This is an
73
+ // accepted, visible (ends in "...") consequence of one shared per-entry
74
+ // bound applying uniformly to every future detector, not a special case
75
+ // per field.
76
+ export const ENTRY_CHAR_BUDGET = 19;
77
+ // Visible truncation marker: a shortened entry must not look complete, so
78
+ // the caller can tell at the string level (not just via the totalX count)
79
+ // that this particular entry was cut.
80
+ export const ENTRY_TRUNCATION_MARKER = "...";
81
+ /**
82
+ * Byte-bounds a detail array by construction: caps the element COUNT (as
83
+ * DETAIL_CLAMP alone already did) AND caps each surviving entry's own
84
+ * length, so a future detector cannot blow the tier-2 budget just by
85
+ * carrying long strings inside an already-short array. Truncation is never
86
+ * silent: a shortened entry visibly ends with ENTRY_TRUNCATION_MARKER, and
87
+ * the deviation's own totalX field already reports the untruncated
88
+ * cardinality.
89
+ *
90
+ * Exported for reuse by read.ts (rc-v1-C006): tasks_get's summary
91
+ * projection and the block-tier's client-side project-addressing errors
92
+ * clamp their own arrays the same way, at their own (different) budgets, by
93
+ * calling this shared helper rather than re-implementing the clamp+marker
94
+ * logic a second time.
95
+ */
96
+ export function clampEntries(values, opts = {}) {
97
+ const max = opts.max ?? DETAIL_CLAMP;
98
+ const entryChars = opts.entryChars ?? ENTRY_CHAR_BUDGET;
99
+ return values.slice(0, max).map((v) => v.length > entryChars
100
+ ? v.slice(0, entryChars - ENTRY_TRUNCATION_MARKER.length) + ENTRY_TRUNCATION_MARKER
101
+ : v);
102
+ }
103
+ // ── task_create / task_respec: confidence deviation ─────────────────────────
104
+ //
105
+ // Trigger per the contract's create catalog: "confidence score is below the
106
+ // project's threshold" — this is `score < threshold`, deliberately NOT the
107
+ // backend's own `blocking` flag (backend/src/lib/confidence.ts: `blocking`
108
+ // is narrower, "a hard, threshold-INDEPENDENT keystone is violated"; using
109
+ // it here would under-report the contract's stated trigger).
110
+ function confidenceDeviation(c) {
111
+ if (!c || c.score >= c.threshold)
112
+ return null;
113
+ const missing = c.missing ?? [];
114
+ return {
115
+ code: "CONFIDENCE_BELOW_THRESHOLD",
116
+ detail: {
117
+ score: c.score,
118
+ threshold: c.threshold,
119
+ enforcementMode: c.enforcementMode,
120
+ // Clamped like DEPENDS_ON_REJECTED/LABELS_DROPPED below: the backend
121
+ // scorer (backend/src/lib/confidence.ts) can populate up to 9 entries
122
+ // (title, description, goal, acceptanceCriteria, scope, outOfScope,
123
+ // dependencies, risk, agentPrompt), already in surfacing-priority
124
+ // order, so the clamp keeps the entries that matter most.
125
+ missing: clampEntries(missing, { max: DETAIL_CLAMP, entryChars: ENTRY_CHAR_BUDGET }),
126
+ totalMissing: missing.length,
127
+ },
128
+ // Kept short on purpose: at the missing[]/dependsOn/labels maxima, all
129
+ // four task_create deviations firing together leaves little headroom
130
+ // under the tier-2 cap (see the "clamps ... at the schemas' and
131
+ // backend's declared maxima" test in tests/receipt.test.ts).
132
+ actNow: c.enforcementMode === "BLOCK"
133
+ ? "Description/templateData not editable after create except via task_respec; at BLOCK, task_pickup/task_start rejects until the score improves."
134
+ : "Description/templateData not editable after create except via task_respec; not BLOCK, so advisory only for now.",
135
+ next: ["task_respec to raise the score above the threshold"],
136
+ };
137
+ }
138
+ // ── task_create: DEDUPED_EXTERNAL_REF ────────────────────────────────────────
139
+ //
140
+ // KNOWN GAP (see the implementer's summary / open_questions): the live
141
+ // backend (backend/src/routes/tasks.ts, POST /projects/:projectId/tasks)
142
+ // rejects a duplicate (projectId, externalRef) with an HTTP 409 P2002
143
+ // conflict BEFORE a task is created — it never returns 200 with the
144
+ // existing task, so this deviation cannot fire against the current backend.
145
+ // It is implemented here for contract-shape completeness (and is exercised
146
+ // in tests against a constructed 200 response) so it activates the moment
147
+ // the backend gains a soft dedupe-return, without another mcp-server change.
148
+ //
149
+ // Detection heuristic (the backend provides no explicit dedupe flag on a
150
+ // hypothetical 200 response): createdAt !== updatedAt. This is imperfect —
151
+ // an existing task that was never touched after its own creation would
152
+ // coincidentally have createdAt === updatedAt and be missed — but it is the
153
+ // best signal available without a backend change, per the task brief's
154
+ // explicit fallback ("createdAt != updatedAt or a backend flag").
155
+ //
156
+ // Scope gate: the contract's trigger for this deviation is "(projectId,
157
+ // externalRef) already exists", the dedupe is keyed on externalRef, so a
158
+ // create call that sent no externalRef at all cannot have hit that path,
159
+ // regardless of what the createdAt/updatedAt heuristic says. Callers that
160
+ // omit externalRef must never see this code.
161
+ function dedupedExternalRefDeviation(task, externalRef) {
162
+ if (!externalRef)
163
+ return null;
164
+ if (!task.createdAt || !task.updatedAt)
165
+ return null;
166
+ if (task.createdAt === task.updatedAt)
167
+ return null;
168
+ return {
169
+ code: "DEDUPED_EXTERNAL_REF",
170
+ detail: { existingTaskId: task.id, existingStatus: task.status },
171
+ next: ["tasks_get"],
172
+ };
173
+ }
174
+ // Both DEPENDS_ON_REJECTED and LABELS_DROPPED echo a slice of the caller's
175
+ // own input back in `detail`. Both schema fields have generous array
176
+ // maxima (dependsOn 50, labels 20; see tools.ts's task_create inputShape),
177
+ // and at those maxima an unclamped detail array alone blows past the
178
+ // tier-2 budget several times over. They reuse DETAIL_CLAMP (defined above,
179
+ // next to ConfidenceObj) for the same reason CONFIDENCE_BELOW_THRESHOLD's
180
+ // `missing[]` does.
181
+ // ── task_create: DEPENDS_ON_REJECTED ─────────────────────────────────────────
182
+ //
183
+ // KNOWN GAP: the live backend validates `dependsOn` before insert and 400s
184
+ // the WHOLE create request if any id is missing/cross-project (tasks.ts
185
+ // ~lines 795-813) rather than creating the task with the valid subset and
186
+ // reporting the rejected ids as a deviation. On today's backend this
187
+ // comparison can only ever find zero missing ids on a successful create
188
+ // (all-or-nothing), so this detector is inert in production until/unless
189
+ // the backend adopts a soft-accept model. Implemented + tested against a
190
+ // constructed response for contract-shape completeness (see above).
191
+ function dependsOnRejectedDeviation(sentDependsOn, blockedBy) {
192
+ if (!sentDependsOn || sentDependsOn.length === 0)
193
+ return null;
194
+ const present = new Set((blockedBy ?? []).map((b) => b.id));
195
+ const rejectedIds = sentDependsOn.filter((id) => !present.has(id));
196
+ if (rejectedIds.length === 0)
197
+ return null;
198
+ return {
199
+ code: "DEPENDS_ON_REJECTED",
200
+ detail: {
201
+ // Every rejected id shares the same reason today (the backend gives
202
+ // no per-id detail), so the reason is hoisted out of the array
203
+ // instead of repeated per entry: that repetition was itself most
204
+ // of the bloat this clamp fixes.
205
+ rejected: clampEntries(rejectedIds, { max: DETAIL_CLAMP, entryChars: ENTRY_CHAR_BUDGET }),
206
+ reason: "not found or cross-project",
207
+ totalRejected: rejectedIds.length,
208
+ },
209
+ next: ["task_create again with corrected dependsOn"],
210
+ };
211
+ }
212
+ // ── task_create: LABELS_DROPPED ──────────────────────────────────────────────
213
+ //
214
+ // KNOWN GAP: the live backend stores `labels` verbatim (trimmed by zod, but
215
+ // not deduped/normalized/soft-rejected) — see createTaskSchema in
216
+ // backend/src/routes/tasks.ts. No label is ever silently dropped today, so
217
+ // this detector is inert in production until/unless the backend adopts
218
+ // normalization or a per-label rejection policy. Implemented + tested
219
+ // against a constructed response for contract-shape completeness.
220
+ function labelsDroppedDeviation(sentLabels, responseLabels) {
221
+ if (!sentLabels || sentLabels.length === 0)
222
+ return null;
223
+ const present = new Set(responseLabels ?? []);
224
+ const dropped = sentLabels.filter((l) => !present.has(l));
225
+ if (dropped.length === 0)
226
+ return null;
227
+ return {
228
+ code: "LABELS_DROPPED",
229
+ detail: {
230
+ dropped: clampEntries(dropped, { max: DETAIL_CLAMP, entryChars: ENTRY_CHAR_BUDGET }),
231
+ totalDropped: dropped.length,
232
+ },
233
+ next: ["task_create again (agents cannot set labels post-create)"],
234
+ };
235
+ }
236
+ // ── Per-verb receipt builders ────────────────────────────────────────────────
237
+ //
238
+ // Defensive guard shared by every builder below: each one is fed a `response`
239
+ // that arrived through an `as` cast in tools.ts (the real runtime shape is
240
+ // only as trustworthy as the backend's success body). Dereferencing
241
+ // `response.task.id` without checking first throws a raw, unhelpful
242
+ // TypeError on a malformed body. Every builder therefore checks
243
+ // `response?.task?.id` up front and, when it's missing, returns the raw
244
+ // response unprojected instead of crashing: the caller still gets
245
+ // something machine-usable, just not the small receipt. This is a
246
+ // deliberate, documented exemption from the contract's "no echo, ever"
247
+ // rule (docs/response-contract-v1.md): a malformed success body falls
248
+ // outside the receipt/tier machinery entirely, so returning it raw is not
249
+ // an echo of caller-sent content, it's the only fallback that avoids
250
+ // crashing on an unexpected backend shape.
251
+ function hasTaskId(response) {
252
+ return !!response?.task?.id;
253
+ }
254
+ export function receiptForCreate(response, input) {
255
+ if (!hasTaskId(response))
256
+ return response;
257
+ const deviations = [];
258
+ const confDev = confidenceDeviation(response.confidence);
259
+ if (confDev)
260
+ deviations.push(confDev);
261
+ const dedupeDev = dedupedExternalRefDeviation(response.task, input.externalRef);
262
+ if (dedupeDev)
263
+ deviations.push(dedupeDev);
264
+ const dependsOnDev = dependsOnRejectedDeviation(input.dependsOn, response.task.blockedBy);
265
+ if (dependsOnDev)
266
+ deviations.push(dependsOnDev);
267
+ const labelsDev = labelsDroppedDeviation(input.labels, response.task.labels);
268
+ if (labelsDev)
269
+ deviations.push(labelsDev);
270
+ return buildReceipt({
271
+ taskId: response.task.id,
272
+ status: response.task.status,
273
+ confidence: response.confidence?.score,
274
+ deviations,
275
+ next: deviations.length === 0 ? ["task_start to begin work on this task"] : undefined,
276
+ });
277
+ }
278
+ export function receiptForRespec(response) {
279
+ if (!hasTaskId(response))
280
+ return response;
281
+ const deviations = [];
282
+ const confDev = confidenceDeviation(response.confidence);
283
+ if (confDev)
284
+ deviations.push(confDev);
285
+ return buildReceipt({
286
+ taskId: response.task.id,
287
+ status: response.task.status,
288
+ confidence: response.confidence?.score,
289
+ deviations,
290
+ });
291
+ }
292
+ // task_finish: `transition.from` would require either an extra pre-fetch
293
+ // (defeats the whole point of the receipt) or hardcoding a "from" state that
294
+ // varies per custom workflow (finish resolves its pre/post states via
295
+ // resolveEffectiveDefinition, not literal status strings) — so it is
296
+ // deliberately omitted here; `task.status` alone reports the outcome. The
297
+ // one deviation this verb DOES carry is grounded in a real backend field:
298
+ // `skippedGates`, populated when autoMerge skips the normally-required
299
+ // `prMerged` precondition (tasks.ts work/review/self-approve branches all
300
+ // echo it back verbatim when non-empty).
301
+ export function receiptForFinish(response) {
302
+ if (!hasTaskId(response))
303
+ return response;
304
+ const deviations = [];
305
+ if (response.skippedGates && response.skippedGates.length > 0) {
306
+ deviations.push({
307
+ code: "WORKFLOW_GATE_SKIPPED",
308
+ detail: {
309
+ // Clamped like every other deviation's array-valued detail field
310
+ // (see DETAIL_CLAMP above), even though the fixed set of workflow
311
+ // gates (branchPresent, prPresent, ciGreen, prMerged) means this
312
+ // can never actually reach 5 entries today. The point is that the
313
+ // clamping rule holds unconditionally, not just where it currently
314
+ // bites.
315
+ skipped: clampEntries(response.skippedGates, { max: DETAIL_CLAMP, entryChars: ENTRY_CHAR_BUDGET }),
316
+ totalSkipped: response.skippedGates.length,
317
+ },
318
+ actNow: `autoMerge bypassed the normally-required workflow gate(s) before this transition: ${response.skippedGates.join(", ")}.`,
319
+ });
320
+ }
321
+ return buildReceipt({
322
+ taskId: response.task.id,
323
+ status: response.task.status,
324
+ deviations,
325
+ });
326
+ }
327
+ // task_submit_pr: the contract's "Known catalogs to fill in" table lists
328
+ // "unmet workflow gates" for this verb, but the live backend performs NO
329
+ // gate evaluation at submit-pr time (see the block comment directly above
330
+ // the route in backend/src/routes/tasks.ts: "No gate evaluation — that
331
+ // happens on the next task_finish call") — there is no backend signal to
332
+ // detect it from without either an extra `projects_get_effective_gates`
333
+ // round trip (defeats the budget goal) or duplicating the backend's gate
334
+ // engine client-side (out of scope). No deviation catalog is implemented
335
+ // for this verb; see open_questions in the implementer's report.
336
+ export function receiptForSubmitPr(response) {
337
+ if (!hasTaskId(response))
338
+ return response;
339
+ return buildReceipt({
340
+ taskId: response.task.id,
341
+ status: response.task.status,
342
+ next: ["task_finish once CI is green"],
343
+ });
344
+ }
345
+ // task_merge: no `transition` field. The route admits both `review` and an
346
+ // idempotent `done` retry as valid starting states (tasks.ts ~lines
347
+ // 3697-3700), and `alreadyMerged` describes the GitHub PR's own merge
348
+ // state (github-merge.ts ~lines 158-161), not whether a DB transition
349
+ // happened on THIS call: a PR merged out-of-band via the GitHub UI can
350
+ // leave the task at `review`, and a subsequent task_merge call both gets
351
+ // `alreadyMerged: true` from GitHub AND performs a real review→done
352
+ // transition in the DB. Keying `transition` off `alreadyMerged` would
353
+ // therefore report a fabricated transition in that case (and a missing one
354
+ // on the true idempotent retry, where it happens to be correct by
355
+ // coincidence). `task.status` alone reports the outcome; it needs no
356
+ // inference.
357
+ export function receiptForMerge(response) {
358
+ if (!hasTaskId(response))
359
+ return response;
360
+ return buildReceipt({
361
+ taskId: response.task.id,
362
+ status: response.task.status,
363
+ });
364
+ }
365
+ export function receiptForAbandon(response) {
366
+ if (!hasTaskId(response))
367
+ return response;
368
+ return buildReceipt({
369
+ taskId: response.task.id,
370
+ status: response.task.status,
371
+ });
372
+ }
373
+ // task_note / tasks_comment: the backend's POST /tasks/:id/comments returns
374
+ // only `{comment}` — there is no `task` object and no `status` field on the
375
+ // comment row, so `task.status` is genuinely unknown without an extra GET
376
+ // (which would double the round trip for the cheapest verb in the surface).
377
+ // The receipt therefore carries `task.id` only, sourced from the response's
378
+ // `comment.taskId` when present (falling back to the caller's own taskId,
379
+ // which is safe to surface: the no-echo rule throughout this module targets
380
+ // CONTENT the caller sent (description, templateData, comment body, and
381
+ // so on), not correlation ids. Every other receipt in this module already
382
+ // carries `task.id` unconditionally).
383
+ export function receiptForNote(taskId, response) {
384
+ return buildReceipt({ taskId: response.comment?.taskId ?? taskId });
385
+ }
386
+ function deriveInferredTaskType(task) {
387
+ const taskType = task.templateData?.taskType;
388
+ return typeof taskType === "string" && taskType.length > 0 ? taskType : undefined;
389
+ }
390
+ /**
391
+ * Resolves the `requires` gate list for task.status -> expectedFinishState.
392
+ *
393
+ * Dynamic path: when the raw response embeds `task.workflow.definition`
394
+ * (today: both sub-paths of the review-claim branch of POST
395
+ * /tasks/:id/start — see the KNOWN GAP on StartTask.workflow above), it is
396
+ * authoritative for this project and takes priority.
397
+ *
398
+ * Static fallback: `task.workflowId === null` does NOT prove the task runs
399
+ * the built-in default workflow. Per the backend's resolveEffectiveDefinition
400
+ * chain (backend/src/services/default-workflow.ts, ADR-0008 §50-56):
401
+ * 1. task.workflowId set -> that Workflow row's definition (the dynamic
402
+ * path above, when embedded).
403
+ * 2. a project-default Workflow row (isDefault: true, looked up by
404
+ * projectId) -> a CUSTOMIZED workflow that a project admin created via
405
+ * POST /projects/:projectId/workflow/customize. Tasks governed by this
406
+ * row still carry `workflowId === null`, and its gate structure can
407
+ * differ from the built-in table below.
408
+ * 3. the built-in defaultWorkflowDefinition() -> what DEFAULT_WORKFLOW_
409
+ * TRANSITIONS mirrors.
410
+ * `workflowId === null` is therefore consistent with EITHER step 2 or step
411
+ * 3, and this function cannot distinguish them without the embedded
412
+ * definition. Falling back to the built-in table is an assumption, not a
413
+ * guarantee, so the result carries `source: "assumed-default-workflow"`
414
+ * whenever it fires, so the caller can tell the gate list is unconfirmed.
415
+ *
416
+ * A non-null `workflowId` without an embedded `workflow` relation means a
417
+ * CUSTOM workflow governs this task but its definition was not sent —
418
+ * guessing its gates from the default table would be actively wrong, so
419
+ * gates is omitted (no source marker either) rather than guessed in that
420
+ * case.
421
+ */
422
+ function deriveGateExpectations(task, expectedFinishState) {
423
+ if (!expectedFinishState || !task.status)
424
+ return {};
425
+ const dynamicTransitions = task.workflow?.definition?.transitions;
426
+ if (dynamicTransitions) {
427
+ const match = dynamicTransitions.find((t) => t.from === task.status && t.to === expectedFinishState);
428
+ const gates = match?.requires && match.requires.length > 0 ? match.requires : undefined;
429
+ return gates ? { gates } : {};
430
+ }
431
+ if (task.workflowId)
432
+ return {}; // custom workflow, definition not sent: do not guess
433
+ const fallback = DEFAULT_WORKFLOW_TRANSITIONS[task.status]?.find((t) => t.to === expectedFinishState);
434
+ const gates = fallback?.requires && fallback.requires.length > 0 ? fallback.requires : undefined;
435
+ return gates ? { gates, source: "assumed-default-workflow" } : {};
436
+ }
437
+ /**
438
+ * Same dynamic-then-static resolution as deriveGateExpectations, for the
439
+ * per-state instructions prose instead of the per-edge gate list — and the
440
+ * SAME provenance rule. An embedded `workflow.definition.states` entry is
441
+ * authoritative and carries no marker. A set `task.workflowId` without an
442
+ * embedded definition means a task-level custom workflow whose prose we do
443
+ * not have: omitted outright, never guessed (wrong instructions read as
444
+ * authoritative are actively harmful — they can tell an agent to do the
445
+ * wrong thing next). A `null` `workflowId` does NOT prove the built-in
446
+ * default (a project-default customized Workflow row can apply, see
447
+ * deriveGateExpectations' KNOWN GAP), so the static built-in prose is
448
+ * surfaced WITH `instructionsSource: "assumed-default-workflow"` — correct
449
+ * for the common built-in case, honestly labeled for the customized one.
450
+ * Recovery path when instructions are omitted: the `tasks_instructions`
451
+ * verb (GET /tasks/:id/instructions) — NOT include:["task"], because the
452
+ * work-claim raw response never embeds the workflow relation either.
453
+ */
454
+ function deriveStartInstructions(task) {
455
+ const dynamicState = task.workflow?.definition?.states?.find((s) => s.name === task.status);
456
+ if (dynamicState?.agentInstructions)
457
+ return { text: dynamicState.agentInstructions };
458
+ if (task.workflowId)
459
+ return {}; // custom workflow, definition not sent: do not guess wrong prose
460
+ if (!task.status)
461
+ return {};
462
+ const text = DEFAULT_WORKFLOW_AGENT_INSTRUCTIONS[task.status];
463
+ return text ? { text, source: "assumed-default-workflow" } : {};
464
+ }
465
+ /**
466
+ * Compacts a debugFlavor groundingHint down to its actionable part: the
467
+ * callable recipe (`mcpToolHint`) alone. `backendSessionRef` is deliberately
468
+ * dropped from this string entirely, not merely de-prioritized: per
469
+ * GroundingHint's own doc comment in backend/src/lib/debug-flavor.ts, that
470
+ * field is named "backendSessionRef" (not "sessionId") specifically because
471
+ * it is NOT usable as a grounding-mcp sessionId — appending it into the
472
+ * actionable `next[]` string would present a value the caller cannot
473
+ * actually pass to any grounding-mcp tool as if it were one. `mcpToolHint`
474
+ * already carries a self-sufficient recipe on its own. `backendSessionRef`
475
+ * remains reachable via include:["task"] for forensic/debugging purposes;
476
+ * it just does not belong in the actionable hint. Also deliberately drops
477
+ * `recommendedAction` (a restated sentence, not an action), `currentPhase`,
478
+ * `mandatorySequence`, and `activeGuardrails` (verbose, not actionable for
479
+ * THIS call) — the full hint remains reachable via include:["task"]. This is
480
+ * also where `metadata.groundingSessionState` (the large persisted session
481
+ * blob) is kept OUT of the default response: this function never reads
482
+ * `metadata` at all, only the already-compact `groundingHint` field.
483
+ */
484
+ function deriveGroundingNext(hint) {
485
+ if (!hint)
486
+ return undefined;
487
+ return [hint.mcpToolHint];
488
+ }
489
+ export function receiptForStart(response, include) {
490
+ // Compatibility valve: bypasses the tier machinery entirely, same as
491
+ // projectPickup's own include:["task"] check for task_pickup. Checked
492
+ // first, unconditionally, regardless of whether `response` even carries
493
+ // a task.id — the caller asked for the raw object back.
494
+ if (include?.includes("task"))
495
+ return response;
496
+ if (!hasTaskId(response))
497
+ return response;
498
+ const slice = {
499
+ ok: true,
500
+ task: response.task.status !== undefined
501
+ ? { id: response.task.id, status: response.task.status }
502
+ : { id: response.task.id },
503
+ };
504
+ if (response.confidence?.score !== undefined)
505
+ slice.confidence = response.confidence.score;
506
+ const inferredTaskType = deriveInferredTaskType(response.task);
507
+ if (inferredTaskType)
508
+ slice.inferredTaskType = inferredTaskType;
509
+ if (response.expectedFinishState)
510
+ slice.expectedFinishState = response.expectedFinishState;
511
+ const { gates: gateExpectations, source: gateExpectationsSource } = deriveGateExpectations(response.task, response.expectedFinishState);
512
+ if (gateExpectations)
513
+ slice.gateExpectations = gateExpectations;
514
+ if (gateExpectationsSource)
515
+ slice.gateExpectationsSource = gateExpectationsSource;
516
+ const next = deriveGroundingNext(response.groundingHint);
517
+ if (next)
518
+ slice.next = next;
519
+ if (include?.includes("description") && response.task.description) {
520
+ slice.description = response.task.description;
521
+ }
522
+ if (include?.includes("comments") && response.task.comments) {
523
+ slice.comments = response.task.comments;
524
+ }
525
+ if (include?.includes("instructions")) {
526
+ const { text: instructions, source: instructionsSource } = deriveStartInstructions(response.task);
527
+ if (instructions)
528
+ slice.instructions = instructions;
529
+ if (instructionsSource)
530
+ slice.instructionsSource = instructionsSource;
531
+ }
532
+ return slice;
533
+ }
534
+ export function projectPickup(response, include) {
535
+ if (include?.includes("task") || include?.includes("comments"))
536
+ return response;
537
+ if (!response.task || !("comments" in response.task))
538
+ return response;
539
+ const { comments: _comments, ...taskWithoutComments } = response.task;
540
+ return { ...response, task: taskWithoutComments };
541
+ }
542
+ //# sourceMappingURL=receipt.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"receipt.js","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,uEAAuE;AACvE,0EAA0E;AAC1E,4EAA4E;AAC5E,qEAAqE;AACrE,0BAA0B;AAC1B,EAAE;AACF,mDAAmD;AACnD,wDAAwD;AACxD,yEAAyE;AACzE,sDAAsD;AACtD,0EAA0E;AAC1E,+DAA+D;AAC/D,EAAE;AACF,oEAAoE;AACpE,0EAA0E;AAC1E,wEAAwE;AACxE,yEAAyE;AACzE,uEAAuE;AACvE,uEAAuE;AACvE,0EAA0E;AAC1E,wDAAwD;AAExD,OAAO,EACL,mCAAmC,EACnC,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAsC/B;8EAC8E;AAC9E,MAAM,UAAU,YAAY,CAAC,IAAsB;IACjD,MAAM,OAAO,GAAY;QACvB,EAAE,EAAE,IAAI;QACR,IAAI,EACF,IAAI,CAAC,MAAM,KAAK,SAAS;YACvB,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;YAC1C,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,MAAM,EAAE;KAC1B,CAAC;IACF,IAAI,IAAI,CAAC,UAAU;QAAE,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IAC1D,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IACxE,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IACxF,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IAChE,OAAO,OAAO,CAAC;AACjB,CAAC;AA6BD,4EAA4E;AAC5E,sEAAsE;AACtE,wEAAwE;AACxE,2EAA2E;AAC3E,wEAAwE;AACxE,uEAAuE;AACvE,yEAAyE;AACzE,0EAA0E;AAC1E,0EAA0E;AAC1E,8CAA8C;AAC9C,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC;AAE9B,0EAA0E;AAC1E,yEAAyE;AACzE,yEAAyE;AACzE,2EAA2E;AAC3E,sEAAsE;AACtE,iEAAiE;AACjE,4EAA4E;AAC5E,EAAE;AACF,0EAA0E;AAC1E,uEAAuE;AACvE,oEAAoE;AACpE,qEAAqE;AACrE,wEAAwE;AACxE,yEAAyE;AACzE,2EAA2E;AAC3E,qEAAqE;AACrE,wEAAwE;AACxE,8DAA8D;AAC9D,wEAAwE;AACxE,wEAAwE;AACxE,wEAAwE;AACxE,aAAa;AACb,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAEpC,0EAA0E;AAC1E,0EAA0E;AAC1E,sCAAsC;AACtC,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,CAAC;AAE7C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAgB,EAChB,OAA8C,EAAE;IAEhD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,YAAY,CAAC;IACrC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,iBAAiB,CAAC;IACxD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACpC,CAAC,CAAC,MAAM,GAAG,UAAU;QACnB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,GAAG,uBAAuB,CAAC,MAAM,CAAC,GAAG,uBAAuB;QACnF,CAAC,CAAC,CAAC,CACN,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,2EAA2E;AAC3E,2EAA2E;AAC3E,6DAA6D;AAC7D,SAAS,mBAAmB,CAAC,CAA4B;IACvD,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC9C,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC;IAChC,OAAO;QACL,IAAI,EAAE,4BAA4B;QAClC,MAAM,EAAE;YACN,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,eAAe,EAAE,CAAC,CAAC,eAAe;YAClC,qEAAqE;YACrE,sEAAsE;YACtE,oEAAoE;YACpE,kEAAkE;YAClE,0DAA0D;YAC1D,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAAC;YACpF,YAAY,EAAE,OAAO,CAAC,MAAM;SAC7B;QACD,uEAAuE;QACvE,qEAAqE;QACrE,gEAAgE;QAChE,6DAA6D;QAC7D,MAAM,EACJ,CAAC,CAAC,eAAe,KAAK,OAAO;YAC3B,CAAC,CAAC,+IAA+I;YACjJ,CAAC,CAAC,iHAAiH;QACvH,IAAI,EAAE,CAAC,oDAAoD,CAAC;KAC7D,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,EAAE;AACF,uEAAuE;AACvE,yEAAyE;AACzE,sEAAsE;AACtE,oEAAoE;AACpE,4EAA4E;AAC5E,2EAA2E;AAC3E,0EAA0E;AAC1E,6EAA6E;AAC7E,EAAE;AACF,yEAAyE;AACzE,2EAA2E;AAC3E,uEAAuE;AACvE,4EAA4E;AAC5E,uEAAuE;AACvE,kEAAkE;AAClE,EAAE;AACF,wEAAwE;AACxE,yEAAyE;AACzE,yEAAyE;AACzE,0EAA0E;AAC1E,6CAA6C;AAC7C,SAAS,2BAA2B,CAClC,IAAiB,EACjB,WAA+B;IAE/B,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IACpD,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IACnD,OAAO;QACL,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,MAAM,EAAE;QAChE,IAAI,EAAE,CAAC,WAAW,CAAC;KACpB,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,qEAAqE;AACrE,2EAA2E;AAC3E,qEAAqE;AACrE,4EAA4E;AAC5E,0EAA0E;AAC1E,oBAAoB;AAEpB,gFAAgF;AAChF,EAAE;AACF,2EAA2E;AAC3E,wEAAwE;AACxE,0EAA0E;AAC1E,qEAAqE;AACrE,wEAAwE;AACxE,yEAAyE;AACzE,yEAAyE;AACzE,oEAAoE;AACpE,SAAS,0BAA0B,CACjC,aAAmC,EACnC,SAAuC;IAEvC,IAAI,CAAC,aAAa,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9D,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5D,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACnE,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO;QACL,IAAI,EAAE,qBAAqB;QAC3B,MAAM,EAAE;YACN,oEAAoE;YACpE,+DAA+D;YAC/D,iEAAiE;YACjE,iCAAiC;YACjC,QAAQ,EAAE,YAAY,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAAC;YACzF,MAAM,EAAE,4BAA4B;YACpC,aAAa,EAAE,WAAW,CAAC,MAAM;SAClC;QACD,IAAI,EAAE,CAAC,4CAA4C,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,kEAAkE;AAClE,2EAA2E;AAC3E,uEAAuE;AACvE,sEAAsE;AACtE,kEAAkE;AAClE,SAAS,sBAAsB,CAC7B,UAAgC,EAChC,cAAoC;IAEpC,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,MAAM,EAAE;YACN,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAAC;YACpF,YAAY,EAAE,OAAO,CAAC,MAAM;SAC7B;QACD,IAAI,EAAE,CAAC,0DAA0D,CAAC;KACnE,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,oEAAoE;AACpE,oEAAoE;AACpE,gEAAgE;AAChE,wEAAwE;AACxE,kEAAkE;AAClE,kEAAkE;AAClE,uEAAuE;AACvE,sEAAsE;AACtE,0EAA0E;AAC1E,qEAAqE;AACrE,2CAA2C;AAC3C,SAAS,SAAS,CAAC,QAAuD;IACxE,OAAO,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;AAC9B,CAAC;AAOD,MAAM,UAAU,gBAAgB,CAC9B,QAAgC,EAChC,KAAwE;IAExE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1C,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,MAAM,OAAO,GAAG,mBAAmB,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACzD,IAAI,OAAO;QAAE,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,2BAA2B,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAChF,IAAI,SAAS;QAAE,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1C,MAAM,YAAY,GAAG,0BAA0B,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1F,IAAI,YAAY;QAAE,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,sBAAsB,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7E,IAAI,SAAS;QAAE,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAE1C,OAAO,YAAY,CAAC;QAClB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE;QACxB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM;QAC5B,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,KAAK;QACtC,UAAU;QACV,IAAI,EAAE,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,uCAAuC,CAAC,CAAC,CAAC,CAAC,SAAS;KACtF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,QAAgC;IAC/D,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1C,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,MAAM,OAAO,GAAG,mBAAmB,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACzD,IAAI,OAAO;QAAE,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEtC,OAAO,YAAY,CAAC;QAClB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE;QACxB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM;QAC5B,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,KAAK;QACtC,UAAU;KACX,CAAC,CAAC;AACL,CAAC;AAWD,yEAAyE;AACzE,6EAA6E;AAC7E,sEAAsE;AACtE,qEAAqE;AACrE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,0EAA0E;AAC1E,yCAAyC;AACzC,MAAM,UAAU,gBAAgB,CAAC,QAAwB;IACvD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1C,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,IAAI,QAAQ,CAAC,YAAY,IAAI,QAAQ,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9D,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,uBAAuB;YAC7B,MAAM,EAAE;gBACN,iEAAiE;gBACjE,kEAAkE;gBAClE,iEAAiE;gBACjE,kEAAkE;gBAClE,mEAAmE;gBACnE,SAAS;gBACT,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,YAAY,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAAC;gBAClG,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAC,MAAM;aAC3C;YACD,MAAM,EAAE,qFAAqF,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;SACjI,CAAC,CAAC;IACL,CAAC;IACD,OAAO,YAAY,CAAC;QAClB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE;QACxB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM;QAC5B,UAAU;KACX,CAAC,CAAC;AACL,CAAC;AAOD,yEAAyE;AACzE,yEAAyE;AACzE,0EAA0E;AAC1E,uEAAuE;AACvE,yEAAyE;AACzE,wEAAwE;AACxE,yEAAyE;AACzE,yEAAyE;AACzE,iEAAiE;AACjE,MAAM,UAAU,kBAAkB,CAAC,QAA0B;IAC3D,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1C,OAAO,YAAY,CAAC;QAClB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE;QACxB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM;QAC5B,IAAI,EAAE,CAAC,8BAA8B,CAAC;KACvC,CAAC,CAAC;AACL,CAAC;AASD,2EAA2E;AAC3E,oEAAoE;AACpE,sEAAsE;AACtE,sEAAsE;AACtE,uEAAuE;AACvE,yEAAyE;AACzE,oEAAoE;AACpE,sEAAsE;AACtE,2EAA2E;AAC3E,kEAAkE;AAClE,qEAAqE;AACrE,aAAa;AACb,MAAM,UAAU,eAAe,CAAC,QAAuB;IACrD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1C,OAAO,YAAY,CAAC;QAClB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE;QACxB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM;KAC7B,CAAC,CAAC;AACL,CAAC;AAMD,MAAM,UAAU,iBAAiB,CAAC,QAAyB;IACzD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1C,OAAO,YAAY,CAAC;QAClB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE;QACxB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM;KAC7B,CAAC,CAAC;AACL,CAAC;AAMD,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,4EAA4E;AAC5E,wEAAwE;AACxE,0EAA0E;AAC1E,sCAAsC;AACtC,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,QAAsB;IACnE,OAAO,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,MAAM,EAAE,CAAC,CAAC;AACtE,CAAC;AAyGD,SAAS,sBAAsB,CAAC,IAAe;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC;IAC7C,OAAO,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AACpF,CAAC;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,SAAS,sBAAsB,CAC7B,IAAe,EACf,mBAAuC;IAEvC,IAAI,CAAC,mBAAmB,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAEpD,MAAM,kBAAkB,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,WAAW,CAAC;IAClE,IAAI,kBAAkB,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CACnC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,KAAK,mBAAmB,CAC9D,CAAC;QACF,MAAM,KAAK,GAAG,KAAK,EAAE,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;QACxF,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAChC,CAAC;IAED,IAAI,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,CAAC,CAAC,qDAAqD;IAErF,MAAM,QAAQ,GAAG,4BAA4B,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,CAC9D,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,mBAAmB,CACpC,CAAC;IACF,MAAM,KAAK,GAAG,QAAQ,EAAE,QAAQ,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IACjG,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,uBAAuB,CAAC,IAAe;IAI9C,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5F,IAAI,YAAY,EAAE,iBAAiB;QAAE,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,iBAAiB,EAAE,CAAC;IACrF,IAAI,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,CAAC,CAAC,iEAAiE;IACjG,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAC5B,MAAM,IAAI,GAAG,mCAAmC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAS,mBAAmB,CAAC,IAAoC;IAC/D,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,QAAuB,EACvB,OAA2B;IAE3B,qEAAqE;IACrE,sEAAsE;IACtE,wEAAwE;IACxE,wDAAwD;IACxD,IAAI,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC/C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAE1C,MAAM,KAAK,GAAe;QACxB,EAAE,EAAE,IAAI;QACR,IAAI,EACF,QAAQ,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS;YAChC,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE;YACxD,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE;KAC/B,CAAC;IACF,IAAI,QAAQ,CAAC,UAAU,EAAE,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC;IAC3F,MAAM,gBAAgB,GAAG,sBAAsB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/D,IAAI,gBAAgB;QAAE,KAAK,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;IAChE,IAAI,QAAQ,CAAC,mBAAmB;QAAE,KAAK,CAAC,mBAAmB,GAAG,QAAQ,CAAC,mBAAmB,CAAC;IAC3F,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,sBAAsB,EAAE,GAAG,sBAAsB,CACxF,QAAQ,CAAC,IAAI,EACb,QAAQ,CAAC,mBAAmB,CAC7B,CAAC;IACF,IAAI,gBAAgB;QAAE,KAAK,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;IAChE,IAAI,sBAAsB;QAAE,KAAK,CAAC,sBAAsB,GAAG,sBAAsB,CAAC;IAClF,MAAM,IAAI,GAAG,mBAAmB,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IACzD,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;IAE5B,IAAI,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAClE,KAAK,CAAC,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC;IAChD,CAAC;IACD,IAAI,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC5D,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC;IAC1C,CAAC;IACD,IAAI,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACtC,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,uBAAuB,CAChF,QAAQ,CAAC,IAAI,CACd,CAAC;QACF,IAAI,YAAY;YAAE,KAAK,CAAC,YAAY,GAAG,YAAY,CAAC;QACpD,IAAI,kBAAkB;YAAE,KAAK,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;IACxE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAsBD,MAAM,UAAU,aAAa,CAC3B,QAAwB,EACxB,OAA2B;IAE3B,IAAI,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,QAAQ,CAAC;IAChF,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC,UAAU,IAAI,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC;IACtE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,mBAAmB,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC;IACtE,OAAO,EAAE,GAAG,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC;AACpD,CAAC"}
package/dist/server.d.ts CHANGED
@@ -2,8 +2,13 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import { type ClientConfig } from "./client.js";
3
3
  export declare const DEFAULT_BASE_URL = "https://agent-tasks.opentriologue.ai";
4
4
  export declare const SERVER_NAME = "agent-tasks-mcp";
5
- export declare const SERVER_VERSION = "0.11.0";
6
- export declare function createServer(config: ClientConfig): McpServer;
7
- export declare function runStdioServer(config: ClientConfig): Promise<void>;
5
+ export declare const SERVER_VERSION = "0.13.0";
6
+ export declare function serializeResult(result: unknown): string;
7
+ export declare function createServer(config: ClientConfig, options?: {
8
+ legacy?: boolean;
9
+ }): McpServer;
10
+ export declare function runStdioServer(config: ClientConfig, options?: {
11
+ legacy?: boolean;
12
+ }): Promise<void>;
8
13
  export { AgentTasksClient, type ClientConfig } from "./client.js";
9
14
  export { buildTools } from "./tools.js";
package/dist/server.js CHANGED
@@ -2,16 +2,31 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3
3
  import { AgentTasksClient } from "./client.js";
4
4
  import { buildTools } from "./tools.js";
5
+ import { HANDSHAKE_PRIMER } from "./primer.js";
5
6
  export const DEFAULT_BASE_URL = "https://agent-tasks.opentriologue.ai";
6
7
  export const SERVER_NAME = "agent-tasks-mcp";
7
- export const SERVER_VERSION = "0.11.0";
8
- export function createServer(config) {
8
+ export const SERVER_VERSION = "0.13.0";
9
+ // Wire-format serializer: the exact transform applied to every tool
10
+ // handler's return value before it goes out as the MCP text block. Exported
11
+ // so tests measuring a receipt's emitted size (the response-contract-v1.md
12
+ // token budgets) serialize through this same function instead of a
13
+ // hand-rolled compact JSON.stringify that would under-measure the real,
14
+ // pretty-printed payload and let a budget regression slip past the suite.
15
+ export function serializeResult(result) {
16
+ return typeof result === "string" ? result : JSON.stringify(result, null, 2);
17
+ }
18
+ export function createServer(config, options) {
9
19
  const client = new AgentTasksClient(config);
10
- const tools = buildTools(client);
20
+ const tools = buildTools(client, options);
21
+ // docs/response-contract-v1.md's "Onboarding channels by rate of change":
22
+ // system/lifecycle/verb-order knowledge is sent once per session via this
23
+ // `instructions` field instead of being replayed on every write-verb
24
+ // response. See primer.ts for the budgeted text and its `workflow_primer`
25
+ // on-demand companion (registered below via buildTools).
11
26
  const server = new McpServer({
12
27
  name: SERVER_NAME,
13
28
  version: SERVER_VERSION,
14
- });
29
+ }, { instructions: HANDSHAKE_PRIMER });
15
30
  for (const tool of tools) {
16
31
  server.registerTool(tool.name, {
17
32
  description: tool.description,
@@ -23,9 +38,7 @@ export function createServer(config) {
23
38
  content: [
24
39
  {
25
40
  type: "text",
26
- text: typeof result === "string"
27
- ? result
28
- : JSON.stringify(result, null, 2),
41
+ text: serializeResult(result),
29
42
  },
30
43
  ],
31
44
  };
@@ -41,8 +54,8 @@ export function createServer(config) {
41
54
  }
42
55
  return server;
43
56
  }
44
- export async function runStdioServer(config) {
45
- const server = createServer(config);
57
+ export async function runStdioServer(config, options) {
58
+ const server = createServer(config, options);
46
59
  const transport = new StdioServerTransport();
47
60
  await server.connect(transport);
48
61
  }
@@ -1 +1 @@
1
- {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAqB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,CAAC,MAAM,gBAAgB,GAAG,sCAAsC,CAAC;AACvE,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAC7C,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,MAAM,MAAM,GAAG,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAEjC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;YACE,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,UAAU;SAC7B,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAa,CAAC,CAAC;gBACjD,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAM;4BACZ,IAAI,EACF,OAAO,MAAM,KAAK,QAAQ;gCACxB,CAAC,CAAC,MAAM;gCACR,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;yBACtC;qBACF;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjE,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;iBAC3C,CAAC;YACJ,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAoB;IACvD,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAqB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
1
+ {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAqB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,sCAAsC,CAAC;AACvE,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAC7C,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC,oEAAoE;AACpE,4EAA4E;AAC5E,2EAA2E;AAC3E,mEAAmE;AACnE,wEAAwE;AACxE,0EAA0E;AAC1E,MAAM,UAAU,eAAe,CAAC,MAAe;IAC7C,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAoB,EAAE,OAA8B;IAC/E,MAAM,MAAM,GAAG,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE1C,0EAA0E;IAC1E,0EAA0E;IAC1E,qEAAqE;IACrE,0EAA0E;IAC1E,yDAAyD;IACzD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,EACD,EAAE,YAAY,EAAE,gBAAgB,EAAE,CACnC,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;YACE,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,UAAU;SAC7B,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAa,CAAC,CAAC;gBACjD,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC;yBAC9B;qBACF;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjE,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;iBAC3C,CAAC;YACJ,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAoB,EACpB,OAA8B;IAE9B,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAqB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}