@agent-tasks/mcp-server 0.12.0 → 0.14.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.
- package/README.md +108 -23
- package/dist/client.d.ts +88 -21
- package/dist/client.js +189 -14
- package/dist/client.js.map +1 -1
- package/dist/default-workflow.d.ts +23 -0
- package/dist/default-workflow.js +107 -0
- package/dist/default-workflow.js.map +1 -0
- package/dist/errors.d.ts +87 -0
- package/dist/errors.js +1402 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.js +16 -1
- package/dist/index.js.map +1 -1
- package/dist/legacy-flag.d.ts +1 -0
- package/dist/legacy-flag.js +36 -0
- package/dist/legacy-flag.js.map +1 -0
- package/dist/primer.d.ts +15 -0
- package/dist/primer.js +89 -0
- package/dist/primer.js.map +1 -0
- package/dist/read.d.ts +133 -0
- package/dist/read.js +193 -0
- package/dist/read.js.map +1 -0
- package/dist/receipt.d.ts +293 -0
- package/dist/receipt.js +622 -0
- package/dist/receipt.js.map +1 -0
- package/dist/server.d.ts +8 -3
- package/dist/server.js +22 -9
- package/dist/server.js.map +1 -1
- package/dist/tools.d.ts +3 -1
- package/dist/tools.js +417 -70
- package/dist/tools.js.map +1 -1
- package/package.json +4 -2
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
/** One entry in the Tier 2 `deviations` array. */
|
|
2
|
+
export interface Deviation {
|
|
3
|
+
code: string;
|
|
4
|
+
/** Present only where the caller can act on it (create/respec catalog). */
|
|
5
|
+
detail?: Record<string, unknown>;
|
|
6
|
+
/** Free text: what this means and what changes because of it, right now. */
|
|
7
|
+
actNow?: string;
|
|
8
|
+
/** Free-form hints, SHOULD lead with a verb name. Not machine-parseable. */
|
|
9
|
+
next?: string[];
|
|
10
|
+
}
|
|
11
|
+
/** The full write-verb response shape, per docs/response-contract-v1.md. */
|
|
12
|
+
export interface Receipt {
|
|
13
|
+
ok: true;
|
|
14
|
+
task: {
|
|
15
|
+
id: string;
|
|
16
|
+
status?: string;
|
|
17
|
+
};
|
|
18
|
+
/** Only present on an actual state change. */
|
|
19
|
+
transition?: {
|
|
20
|
+
from: string;
|
|
21
|
+
to: string;
|
|
22
|
+
};
|
|
23
|
+
/** Bare scalar. Only set by receiptForCreate / receiptForRespec in this
|
|
24
|
+
* layer — no other write verb carries confidence (actionable counter-rule:
|
|
25
|
+
* detail belongs only where the caller can act on it). */
|
|
26
|
+
confidence?: number;
|
|
27
|
+
/** Absent or empty on the happy path — report by exception. */
|
|
28
|
+
deviations?: Deviation[];
|
|
29
|
+
/** 1-3 free-form hints, not a menu. */
|
|
30
|
+
next?: string[];
|
|
31
|
+
}
|
|
32
|
+
interface BuildReceiptOpts {
|
|
33
|
+
taskId: string;
|
|
34
|
+
status?: string;
|
|
35
|
+
transition?: {
|
|
36
|
+
from: string;
|
|
37
|
+
to: string;
|
|
38
|
+
};
|
|
39
|
+
confidence?: number;
|
|
40
|
+
deviations?: Deviation[];
|
|
41
|
+
next?: string[];
|
|
42
|
+
}
|
|
43
|
+
/** Low-level composer. Every receiptFor* builder below funnels through this
|
|
44
|
+
* so the tier layering (present/absent rules) lives in exactly one place. */
|
|
45
|
+
export declare function buildReceipt(opts: BuildReceiptOpts): Receipt;
|
|
46
|
+
export interface BackendTask {
|
|
47
|
+
id: string;
|
|
48
|
+
status?: string;
|
|
49
|
+
createdAt?: string;
|
|
50
|
+
updatedAt?: string;
|
|
51
|
+
labels?: string[];
|
|
52
|
+
blockedBy?: {
|
|
53
|
+
id: string;
|
|
54
|
+
}[];
|
|
55
|
+
}
|
|
56
|
+
export interface ConfidenceObj {
|
|
57
|
+
score: number;
|
|
58
|
+
threshold: number;
|
|
59
|
+
enforcementMode: string | null;
|
|
60
|
+
blocking?: boolean;
|
|
61
|
+
missing?: string[];
|
|
62
|
+
findings?: unknown[];
|
|
63
|
+
nextActions?: unknown[];
|
|
64
|
+
}
|
|
65
|
+
export declare const DETAIL_CLAMP = 5;
|
|
66
|
+
export declare const ENTRY_CHAR_BUDGET = 19;
|
|
67
|
+
export declare const ENTRY_TRUNCATION_MARKER = "...";
|
|
68
|
+
/**
|
|
69
|
+
* Byte-bounds a detail array by construction: caps the element COUNT (as
|
|
70
|
+
* DETAIL_CLAMP alone already did) AND caps each surviving entry's own
|
|
71
|
+
* length, so a future detector cannot blow the tier-2 budget just by
|
|
72
|
+
* carrying long strings inside an already-short array. Truncation is never
|
|
73
|
+
* silent: a shortened entry visibly ends with ENTRY_TRUNCATION_MARKER, and
|
|
74
|
+
* the deviation's own totalX field already reports the untruncated
|
|
75
|
+
* cardinality.
|
|
76
|
+
*
|
|
77
|
+
* Exported for reuse by read.ts (rc-v1-C006): tasks_get's summary
|
|
78
|
+
* projection and the block-tier's client-side project-addressing errors
|
|
79
|
+
* clamp their own arrays the same way, at their own (different) budgets, by
|
|
80
|
+
* calling this shared helper rather than re-implementing the clamp+marker
|
|
81
|
+
* logic a second time.
|
|
82
|
+
*/
|
|
83
|
+
export declare function clampEntries(values: string[], opts?: {
|
|
84
|
+
max?: number;
|
|
85
|
+
entryChars?: number;
|
|
86
|
+
}): string[];
|
|
87
|
+
export interface CreateOrRespecResponse {
|
|
88
|
+
task: BackendTask;
|
|
89
|
+
confidence?: ConfidenceObj;
|
|
90
|
+
}
|
|
91
|
+
export declare function receiptForCreate(response: CreateOrRespecResponse, input: {
|
|
92
|
+
labels?: string[];
|
|
93
|
+
dependsOn?: string[];
|
|
94
|
+
externalRef?: string;
|
|
95
|
+
}): Receipt | CreateOrRespecResponse;
|
|
96
|
+
export declare function receiptForRespec(response: CreateOrRespecResponse): Receipt | CreateOrRespecResponse;
|
|
97
|
+
export interface FinishResponse {
|
|
98
|
+
kind: "work" | "review";
|
|
99
|
+
task: BackendTask;
|
|
100
|
+
targetStatus?: string;
|
|
101
|
+
outcome?: string;
|
|
102
|
+
autoMergeSha?: string;
|
|
103
|
+
skippedGates?: string[];
|
|
104
|
+
}
|
|
105
|
+
export declare function receiptForFinish(response: FinishResponse): Receipt | FinishResponse;
|
|
106
|
+
export interface SubmitPrResponse {
|
|
107
|
+
kind: "submit_pr";
|
|
108
|
+
task: BackendTask;
|
|
109
|
+
}
|
|
110
|
+
export declare function receiptForSubmitPr(response: SubmitPrResponse): Receipt | SubmitPrResponse;
|
|
111
|
+
export interface MergeResponse {
|
|
112
|
+
task: BackendTask;
|
|
113
|
+
merged: boolean;
|
|
114
|
+
sha?: string | null;
|
|
115
|
+
alreadyMerged?: boolean;
|
|
116
|
+
}
|
|
117
|
+
export declare function receiptForMerge(response: MergeResponse): Receipt | MergeResponse;
|
|
118
|
+
export interface AbandonResponse {
|
|
119
|
+
task: BackendTask;
|
|
120
|
+
}
|
|
121
|
+
export declare function receiptForAbandon(response: AbandonResponse): Receipt | AbandonResponse;
|
|
122
|
+
export interface NoteResponse {
|
|
123
|
+
comment?: {
|
|
124
|
+
taskId?: string;
|
|
125
|
+
};
|
|
126
|
+
}
|
|
127
|
+
export declare function receiptForNote(taskId: string, response: NoteResponse): Receipt;
|
|
128
|
+
export interface StartWorkflowDefinition {
|
|
129
|
+
states?: {
|
|
130
|
+
name: string;
|
|
131
|
+
agentInstructions?: string;
|
|
132
|
+
}[];
|
|
133
|
+
transitions?: {
|
|
134
|
+
from: string;
|
|
135
|
+
to: string;
|
|
136
|
+
requires?: string[];
|
|
137
|
+
}[];
|
|
138
|
+
}
|
|
139
|
+
export interface StartTask extends BackendTask {
|
|
140
|
+
workflowId?: string | null;
|
|
141
|
+
templateData?: {
|
|
142
|
+
taskType?: unknown;
|
|
143
|
+
} | null;
|
|
144
|
+
description?: string | null;
|
|
145
|
+
comments?: unknown[];
|
|
146
|
+
workflow?: {
|
|
147
|
+
definition?: StartWorkflowDefinition;
|
|
148
|
+
} | null;
|
|
149
|
+
}
|
|
150
|
+
export interface StartGroundingHint {
|
|
151
|
+
debugFlavor: true;
|
|
152
|
+
recommendedAction: string;
|
|
153
|
+
mcpToolHint: string;
|
|
154
|
+
backendSessionRef?: string;
|
|
155
|
+
currentPhase?: string;
|
|
156
|
+
mandatorySequence?: string[];
|
|
157
|
+
activeGuardrails?: string[];
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* Backend field since rc-v1-B001 (PR #445): the gates configured on the
|
|
161
|
+
* edge(s) this call's caller will hit next on a subsequent task_finish,
|
|
162
|
+
* resolved server-side from the SAME effectiveDefinition already used to
|
|
163
|
+
* gate the claim itself (backend/src/routes/tasks.ts's
|
|
164
|
+
* gatesForTransitionOrNull), authoritative over this module's own
|
|
165
|
+
* client-side approximation (deriveGateExpectations below), which is now a
|
|
166
|
+
* fallback for backends that predate this field (see
|
|
167
|
+
* resolveGateExpectations). `null` means the edge itself is absent (the
|
|
168
|
+
* corresponding finish call will 400 with no_transition); `[]` means the
|
|
169
|
+
* edge exists with nothing required. This distinction MUST NOT be
|
|
170
|
+
* collapsed: see gatesForTransitionOrNull's own doc comment for why a
|
|
171
|
+
* workflow that drops one edge while keeping another makes `[]` and `null`
|
|
172
|
+
* mean genuinely different things for the caller.
|
|
173
|
+
*/
|
|
174
|
+
export interface StartEffectiveGates {
|
|
175
|
+
finish: string[] | null;
|
|
176
|
+
/** Review-claim only: previews the "request_changes" outcome's edge, a
|
|
177
|
+
* DIFFERENT edge than `finish` (which previews "approve" on a review
|
|
178
|
+
* claim, see backend/src/routes/tasks.ts's review-claim branch). Absent
|
|
179
|
+
* on a work-claim response, which has only one relevant edge. */
|
|
180
|
+
requestChanges?: string[] | null;
|
|
181
|
+
}
|
|
182
|
+
export interface StartResponse {
|
|
183
|
+
kind: "work" | "review";
|
|
184
|
+
task: StartTask;
|
|
185
|
+
expectedFinishState?: string;
|
|
186
|
+
groundingHint?: StartGroundingHint;
|
|
187
|
+
project?: unknown;
|
|
188
|
+
confidence?: {
|
|
189
|
+
score: number;
|
|
190
|
+
};
|
|
191
|
+
/** Since rc-v1-B001. See StartEffectiveGates. Declared optional (`?:`),
|
|
192
|
+
* not required, so a pre-B001 backend response is still a valid
|
|
193
|
+
* StartResponse: resolveGateExpectations reads this defensively and
|
|
194
|
+
* falls back to deriveGateExpectations when it is absent. */
|
|
195
|
+
effectiveGates?: StartEffectiveGates;
|
|
196
|
+
/** Since rc-v1-B001: task status immediately before this call, the real
|
|
197
|
+
* transition.from, not a guess. On a work claim this is the state the
|
|
198
|
+
* task was in before the claim (e.g. "open"); on a review claim it
|
|
199
|
+
* equals the current task.status ("review"), since review-claiming does
|
|
200
|
+
* not itself transition status (backend/src/routes/tasks.ts's
|
|
201
|
+
* review-claim branch comment). Absent on a pre-B001 backend, in which
|
|
202
|
+
* case StartSlice.transition is simply omitted, no guess is made. */
|
|
203
|
+
previousStatus?: string;
|
|
204
|
+
}
|
|
205
|
+
export interface StartSlice {
|
|
206
|
+
ok: true;
|
|
207
|
+
task: {
|
|
208
|
+
id: string;
|
|
209
|
+
status?: string;
|
|
210
|
+
};
|
|
211
|
+
/** Only present on an actual state change (response.previousStatus !==
|
|
212
|
+
* response.task.status), the same "only on a state change" rule the
|
|
213
|
+
* general Receipt.transition field follows (docs/response-contract-v1.md).
|
|
214
|
+
* Absent on a review-claim start (task.status stays "review", so
|
|
215
|
+
* previousStatus equals it), and absent entirely against a pre-rc-v1-B001
|
|
216
|
+
* backend that does not send `previousStatus`, no guess is made. */
|
|
217
|
+
transition?: {
|
|
218
|
+
from: string;
|
|
219
|
+
to: string;
|
|
220
|
+
};
|
|
221
|
+
/** Bare scalar only — see the KNOWN GAP note on StartResponse.confidence. */
|
|
222
|
+
confidence?: number;
|
|
223
|
+
/** Derived from task.templateData.taskType (the same source
|
|
224
|
+
* backend/src/lib/confidence.ts's own inferredTaskType uses), not echoed
|
|
225
|
+
* from the caller's own request (taskType is set once, at task_create
|
|
226
|
+
* time, by whoever created the task — not by this call's caller). */
|
|
227
|
+
inferredTaskType?: string;
|
|
228
|
+
/** On a work claim, this names the SAME edge `gateExpectations` previews
|
|
229
|
+
* (startTarget -> expectedFinishState). On a review claim, it does NOT:
|
|
230
|
+
* it names the definition-wide work-finish target (what an author's
|
|
231
|
+
* task_finish would target on this task), while `gateExpectations`
|
|
232
|
+
* previews the review -> approveTarget edge (the "approve" outcome), a
|
|
233
|
+
* different edge, resolved from the backend's own
|
|
234
|
+
* `expectedFinishStateFromDefinition` vs `approveTarget` (see
|
|
235
|
+
* backend/src/routes/tasks.ts's review-claim branch). A review-claim
|
|
236
|
+
* receipt like `{ expectedFinishState: "review", gateExpectations: null
|
|
237
|
+
* }` therefore means the approve edge is absent, NOT that this field's
|
|
238
|
+
* own named state is unreachable; do not pair the two fields as if they
|
|
239
|
+
* describe the same transition on a review claim. */
|
|
240
|
+
expectedFinishState?: string;
|
|
241
|
+
/** The `requires` gate list for the edge task_finish will hit next: on a
|
|
242
|
+
* work claim, the single startTarget -> expectedFinishState edge; on a
|
|
243
|
+
* review claim, the "approve" edge (see requestChangesGateExpectations
|
|
244
|
+
* for the review claim's other outcome). Sourced from the backend's
|
|
245
|
+
* authoritative `effectiveGates.finish` (rc-v1-B001) when present, via
|
|
246
|
+
* resolveGateExpectations; falls back to deriveGateExpectations'
|
|
247
|
+
* dynamic-vs-static-fallback resolution only against a pre-B001 backend.
|
|
248
|
+
* `null` = the edge does not exist (finish will 400 with no_transition);
|
|
249
|
+
* omitted = either the edge exists with nothing required, or (fallback
|
|
250
|
+
* path only) no data was derivable at all: see resolveGateExpectations
|
|
251
|
+
* and projectGateList for the exact collapse rule. */
|
|
252
|
+
gateExpectations?: string[] | null;
|
|
253
|
+
/** Present only alongside `gateExpectations`, only when it came from the
|
|
254
|
+
* pre-B001 fallback (deriveGateExpectations' static default-workflow.ts
|
|
255
|
+
* table) rather than the backend's own authoritative `effectiveGates`.
|
|
256
|
+
* A `null` `task.workflowId` does NOT prove the built-in default
|
|
257
|
+
* workflow governs this task — it can also mean a project-default
|
|
258
|
+
* customized Workflow row applies (see the KNOWN GAP note on
|
|
259
|
+
* deriveGateExpectations) — so this marks the gate list as an assumption
|
|
260
|
+
* the caller should not treat as authoritative. Never set when
|
|
261
|
+
* `effectiveGates` was present on the response: the backend's own value
|
|
262
|
+
* needs no such caveat. */
|
|
263
|
+
gateExpectationsSource?: "assumed-default-workflow";
|
|
264
|
+
/** Review-claim only: the `requires` gate list for the "request_changes"
|
|
265
|
+
* outcome's edge, sourced exclusively from the backend's
|
|
266
|
+
* `effectiveGates.requestChanges` (rc-v1-B001); there is no client-side
|
|
267
|
+
* fallback derivation for this edge (the pre-B001 code never computed it
|
|
268
|
+
* at all), so on a pre-B001 backend this field is simply absent, never
|
|
269
|
+
* guessed, and carries no separate "source" marker. Same null-vs-omitted
|
|
270
|
+
* rule as `gateExpectations`. */
|
|
271
|
+
requestChangesGateExpectations?: string[] | null;
|
|
272
|
+
next?: string[];
|
|
273
|
+
description?: string;
|
|
274
|
+
comments?: unknown[];
|
|
275
|
+
instructions?: string;
|
|
276
|
+
/** Same provenance rule as gateExpectationsSource: present only when the
|
|
277
|
+
* prose came from the static default-workflow.ts fallback (null
|
|
278
|
+
* workflowId), which does not prove the built-in default governs this
|
|
279
|
+
* task. See deriveStartInstructions. */
|
|
280
|
+
instructionsSource?: "assumed-default-workflow";
|
|
281
|
+
}
|
|
282
|
+
export declare function receiptForStart(response: StartResponse, include?: readonly string[]): StartSlice | StartResponse;
|
|
283
|
+
export interface PickupResponse {
|
|
284
|
+
kind: "signal" | "review" | "work" | "idle";
|
|
285
|
+
task?: {
|
|
286
|
+
comments?: unknown[];
|
|
287
|
+
[key: string]: unknown;
|
|
288
|
+
};
|
|
289
|
+
signal?: unknown;
|
|
290
|
+
groundingHint?: unknown;
|
|
291
|
+
}
|
|
292
|
+
export declare function projectPickup(response: PickupResponse, include?: readonly string[]): PickupResponse;
|
|
293
|
+
export {};
|