@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,216 @@
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
+ export interface StartResponse {
160
+ kind: "work" | "review";
161
+ task: StartTask;
162
+ expectedFinishState?: string;
163
+ groundingHint?: StartGroundingHint;
164
+ project?: unknown;
165
+ confidence?: {
166
+ score: number;
167
+ };
168
+ }
169
+ export interface StartSlice {
170
+ ok: true;
171
+ task: {
172
+ id: string;
173
+ status?: string;
174
+ };
175
+ /** Bare scalar only — see the KNOWN GAP note on StartResponse.confidence. */
176
+ confidence?: number;
177
+ /** Derived from task.templateData.taskType (the same source
178
+ * backend/src/lib/confidence.ts's own inferredTaskType uses), not echoed
179
+ * from the caller's own request (taskType is set once, at task_create
180
+ * time, by whoever created the task — not by this call's caller). */
181
+ inferredTaskType?: string;
182
+ expectedFinishState?: string;
183
+ /** The `requires` gate list for the transition out of the task's current
184
+ * state to `expectedFinishState`. See deriveGateExpectations for the
185
+ * dynamic-vs-static-fallback resolution and its documented gap. */
186
+ gateExpectations?: string[];
187
+ /** Present only alongside `gateExpectations`, only when it was derived
188
+ * from the static default-workflow.ts fallback table rather than an
189
+ * embedded `task.workflow.definition`. A `null` `task.workflowId` does
190
+ * NOT prove the built-in default workflow governs this task — it can
191
+ * also mean a project-default customized Workflow row applies (see the
192
+ * KNOWN GAP note on deriveGateExpectations) — so this marks the gate
193
+ * list as an assumption the caller should not treat as authoritative. */
194
+ gateExpectationsSource?: "assumed-default-workflow";
195
+ next?: string[];
196
+ description?: string;
197
+ comments?: unknown[];
198
+ instructions?: string;
199
+ /** Same provenance rule as gateExpectationsSource: present only when the
200
+ * prose came from the static default-workflow.ts fallback (null
201
+ * workflowId), which does not prove the built-in default governs this
202
+ * task. See deriveStartInstructions. */
203
+ instructionsSource?: "assumed-default-workflow";
204
+ }
205
+ export declare function receiptForStart(response: StartResponse, include?: readonly string[]): StartSlice | StartResponse;
206
+ export interface PickupResponse {
207
+ kind: "signal" | "review" | "work" | "idle";
208
+ task?: {
209
+ comments?: unknown[];
210
+ [key: string]: unknown;
211
+ };
212
+ signal?: unknown;
213
+ groundingHint?: unknown;
214
+ }
215
+ export declare function projectPickup(response: PickupResponse, include?: readonly string[]): PickupResponse;
216
+ export {};