@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.
@@ -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 {};