@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,23 @@
1
+ export interface DefaultWorkflowState {
2
+ name: string;
3
+ label: string;
4
+ terminal: boolean;
5
+ agentInstructions: string;
6
+ }
7
+ export declare const DEFAULT_WORKFLOW_STATES: readonly DefaultWorkflowState[];
8
+ /** State name -> agentInstructions. Convenience lookup for `receiptForStart`
9
+ * (include:["instructions"] fallback) and for rc-v1-C004's future
10
+ * workflow_primer verb. */
11
+ export declare const DEFAULT_WORKFLOW_AGENT_INSTRUCTIONS: Readonly<Record<string, string>>;
12
+ export interface DefaultWorkflowTransition {
13
+ to: string;
14
+ label: string;
15
+ requires?: string[];
16
+ }
17
+ /** from-state -> the edges leaving it, each with its `requires` gate list
18
+ * when one applies. Mirrors backend/src/services/default-workflow.ts's
19
+ * `DEFAULT_TRANSITIONS` verbatim (including the deliberate absence of
20
+ * `branchPresent` on the `open -> in_progress` edge — see that file's
21
+ * comment on why: requiring a branch before work even starts would
22
+ * self-checkmate the default workflow once task_start enforces gates). */
23
+ export declare const DEFAULT_WORKFLOW_TRANSITIONS: Readonly<Record<string, readonly DefaultWorkflowTransition[]>>;
@@ -0,0 +1,107 @@
1
+ // Verbatim mirror of the built-in default workflow's agent-facing content:
2
+ // backend/src/services/default-workflow.ts's `DEFAULT_STATES` (per-state
3
+ // `agentInstructions`) and `DEFAULT_TRANSITIONS` (per-edge `requires` gate
4
+ // lists). backend/** is out of scope for the task that added this file
5
+ // (rc-v1-C003, docs/response-contract-v1.md), so this RUNTIME module does
6
+ // NOT import from or otherwise couple to the backend package at build/run
7
+ // time — it is a plain, hand-copied snapshot kept in sync by convention,
8
+ // not a shared import (tests DO cross-import the backend module directly to
9
+ // verify the mirror stays honest; see "Keep in sync" below).
10
+ //
11
+ // Why this file exists: rc-v1-C003 stops task_start's DEFAULT response from
12
+ // embedding the full per-task workflow object (docs/response-contract-v1.md's
13
+ // "no static instructions on every call" rule — see `receiptForStart` in
14
+ // receipt.ts). Two consequences of that cut needed a home:
15
+ //
16
+ // 1. The per-state `agentInstructions` prose (open / in_progress / review /
17
+ // done) is genuinely useful to an agent once per session, not replayed
18
+ // on every task_start call. Per docs/response-contract-v1.md's
19
+ // "Onboarding channels by rate of change" table, content that
20
+ // "effectively never" changes belongs in a channel paid for once per
21
+ // session (`initialize.instructions` + a `workflow_primer` verb), not
22
+ // the per-call receipt. `DEFAULT_WORKFLOW_AGENT_INSTRUCTIONS` is the
23
+ // verbatim, content-preserving handover point for that follow-up
24
+ // (rc-v1-C004, out of scope here) — no information is lost by the cut.
25
+ // It IS wired into task_start's `include: ["instructions"]` path today
26
+ // (see receipt.ts's `deriveStartInstructions`): that is in-scope reuse
27
+ // of task_start's own existing include mechanism, not the new
28
+ // onboarding-channel verb C004 will add.
29
+ // 2. The per-edge `requires` gate list (e.g. "in_progress -> review needs
30
+ // branchPresent + prPresent") is exactly the "task-specific gate
31
+ // expectations" rc-v1-C003 surfaces on task_start's default response
32
+ // (see `deriveGateExpectations` in receipt.ts). It is used live, as
33
+ // the fallback whenever a task's `workflowId` is `null`. That is NOT
34
+ // proof the built-in default workflow governs the task: per
35
+ // backend/src/services/default-workflow.ts's
36
+ // `resolveEffectiveDefinition` (ADR-0008 §50-56), `workflowId === null`
37
+ // is equally consistent with a project-default customized Workflow row
38
+ // (isDefault: true, looked up by projectId, created via POST
39
+ // /projects/:projectId/workflow/customize) whose gates can differ from
40
+ // this table. `deriveGateExpectations` therefore marks its fallback
41
+ // result with `source: "assumed-default-workflow"` rather than
42
+ // presenting it as authoritative. A task governed by a CUSTOM workflow
43
+ // (non-null `workflowId`) is never guessed against this table at all;
44
+ // its gates are only surfaced when the raw `task.workflow` relation
45
+ // happens to be embedded in the response (today: both sub-paths of the
46
+ // review-claim branch — see the KNOWN GAP comment on
47
+ // `deriveGateExpectations`).
48
+ //
49
+ // Keep in sync: tests/default-workflow.test.ts DOES cross-import
50
+ // backend/src/services/default-workflow.ts's DEFAULT_STATES /
51
+ // DEFAULT_TRANSITIONS directly and asserts content-equality against this
52
+ // file's exports, so drift between the two IS caught automatically by
53
+ // `npm test` — the cross-workspace import is test-only (mcp-server's
54
+ // tsconfig.json excludes `tests/`, so it never reaches `npm run build`'s
55
+ // tsc output or this runtime module's own import graph). If backend's
56
+ // defaults ever change, that test fails until this file's mirror is
57
+ // updated to match.
58
+ export const DEFAULT_WORKFLOW_STATES = [
59
+ {
60
+ name: "open",
61
+ label: "Open",
62
+ terminal: false,
63
+ agentInstructions: "Claim this task, create a branch, then transition to in_progress.",
64
+ },
65
+ {
66
+ name: "in_progress",
67
+ label: "In progress",
68
+ terminal: false,
69
+ agentInstructions: "Implement the changes. When done, push the branch, create a PR, update prUrl and branchName, then transition to review.",
70
+ },
71
+ {
72
+ name: "review",
73
+ label: "In review",
74
+ terminal: false,
75
+ agentInstructions: "Review is a code-review state. Approve or request changes here. Merge, deploy, and production verification are external follow-up actions unless your project defines a custom workflow for them.",
76
+ },
77
+ {
78
+ name: "done",
79
+ label: "Done",
80
+ terminal: true,
81
+ agentInstructions: "Task is complete. Merge, deploy, and production verification are operational follow-ups outside the modeled task states unless a custom workflow models them explicitly.",
82
+ },
83
+ ];
84
+ /** State name -> agentInstructions. Convenience lookup for `receiptForStart`
85
+ * (include:["instructions"] fallback) and for rc-v1-C004's future
86
+ * workflow_primer verb. */
87
+ export const DEFAULT_WORKFLOW_AGENT_INSTRUCTIONS = Object.fromEntries(DEFAULT_WORKFLOW_STATES.map((s) => [s.name, s.agentInstructions]));
88
+ /** from-state -> the edges leaving it, each with its `requires` gate list
89
+ * when one applies. Mirrors backend/src/services/default-workflow.ts's
90
+ * `DEFAULT_TRANSITIONS` verbatim (including the deliberate absence of
91
+ * `branchPresent` on the `open -> in_progress` edge — see that file's
92
+ * comment on why: requiring a branch before work even starts would
93
+ * self-checkmate the default workflow once task_start enforces gates). */
94
+ export const DEFAULT_WORKFLOW_TRANSITIONS = {
95
+ open: [{ to: "in_progress", label: "Start" }],
96
+ in_progress: [
97
+ { to: "review", label: "Submit for review", requires: ["branchPresent", "prPresent"] },
98
+ { to: "done", label: "Mark done", requires: ["branchPresent", "prPresent"] },
99
+ { to: "open", label: "Release" },
100
+ ],
101
+ review: [
102
+ { to: "done", label: "Approve" },
103
+ { to: "in_progress", label: "Request changes" },
104
+ ],
105
+ done: [],
106
+ };
107
+ //# sourceMappingURL=default-workflow.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"default-workflow.js","sourceRoot":"","sources":["../src/default-workflow.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,yEAAyE;AACzE,2EAA2E;AAC3E,uEAAuE;AACvE,0EAA0E;AAC1E,0EAA0E;AAC1E,yEAAyE;AACzE,4EAA4E;AAC5E,6DAA6D;AAC7D,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,yEAAyE;AACzE,2DAA2D;AAC3D,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,oEAAoE;AACpE,mEAAmE;AACnE,0EAA0E;AAC1E,2EAA2E;AAC3E,0EAA0E;AAC1E,sEAAsE;AACtE,4EAA4E;AAC5E,4EAA4E;AAC5E,4EAA4E;AAC5E,mEAAmE;AACnE,8CAA8C;AAC9C,4EAA4E;AAC5E,sEAAsE;AACtE,0EAA0E;AAC1E,yEAAyE;AACzE,0EAA0E;AAC1E,iEAAiE;AACjE,kDAAkD;AAClD,6EAA6E;AAC7E,4EAA4E;AAC5E,kEAAkE;AAClE,4EAA4E;AAC5E,yEAAyE;AACzE,oEAAoE;AACpE,4EAA4E;AAC5E,2EAA2E;AAC3E,yEAAyE;AACzE,4EAA4E;AAC5E,0DAA0D;AAC1D,kCAAkC;AAClC,EAAE;AACF,iEAAiE;AACjE,8DAA8D;AAC9D,yEAAyE;AACzE,sEAAsE;AACtE,qEAAqE;AACrE,yEAAyE;AACzE,sEAAsE;AACtE,oEAAoE;AACpE,oBAAoB;AASpB,MAAM,CAAC,MAAM,uBAAuB,GAAoC;IACtE;QACE,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,MAAM;QACb,QAAQ,EAAE,KAAK;QACf,iBAAiB,EACf,mEAAmE;KACtE;IACD;QACE,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,aAAa;QACpB,QAAQ,EAAE,KAAK;QACf,iBAAiB,EACf,yHAAyH;KAC5H;IACD;QACE,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,WAAW;QAClB,QAAQ,EAAE,KAAK;QACf,iBAAiB,EACf,mMAAmM;KACtM;IACD;QACE,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,MAAM;QACb,QAAQ,EAAE,IAAI;QACd,iBAAiB,EACf,0KAA0K;KAC7K;CACO,CAAC;AAEX;;4BAE4B;AAC5B,MAAM,CAAC,MAAM,mCAAmC,GAAqC,MAAM,CAAC,WAAW,CACrG,uBAAuB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAClE,CAAC;AAQF;;;;;2EAK2E;AAC3E,MAAM,CAAC,MAAM,4BAA4B,GAAmE;IAC1G,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAC7C,WAAW,EAAE;QACX,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,CAAC,eAAe,EAAE,WAAW,CAAC,EAAE;QACtF,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,eAAe,EAAE,WAAW,CAAC,EAAE;QAC5E,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE;KACjC;IACD,MAAM,EAAE;QACN,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE;QAChC,EAAE,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,iBAAiB,EAAE;KAChD;IACD,IAAI,EAAE,EAAE;CACT,CAAC"}
@@ -0,0 +1,87 @@
1
+ /** The full block-tier response shape. */
2
+ export interface TeachingError {
3
+ ok: false;
4
+ error: {
5
+ code: string;
6
+ message: string;
7
+ recipe: string;
8
+ /** Verb names only, machine-checkable. Empty when no self-service
9
+ * corrective call exists (e.g. an admin-only wall). */
10
+ allowedNext: string[];
11
+ /** Present when this entry carries structured detail: today,
12
+ * precondition_failed's `failed[]`, low_confidence's
13
+ * score/threshold/missing[]/totalMissing, and, for the generic
14
+ * degrade path, a clamped passthrough of whatever `details` object
15
+ * the backend itself sent, OR, when the backend instead sent an
16
+ * OBJECT `error` (a raw zod SafeParseError spread into the body, see
17
+ * genericDegrade/deriveGenericDetailSource), a clamped
18
+ * issues[]/totalIssues summary derived from it. */
19
+ detail?: Record<string, unknown>;
20
+ };
21
+ }
22
+ /** Serializes a TeachingError exactly as server.ts's serializeResult would
23
+ * (JSON.stringify(x, null, 2) for a non-string result — a teaching error is
24
+ * always an object, never a string, so the two are always equal for this
25
+ * input). Defined locally rather than importing serializeResult from
26
+ * server.ts to avoid a circular import (server.ts -> tools.ts -> errors.ts);
27
+ * tests/errors.test.ts asserts the two stay equal for every catalog entry. */
28
+ export declare function serializeTeachingError(err: TeachingError): string;
29
+ export declare const ALREADY_CLAIMED_CASES: {
30
+ readonly inProgress: "In-progress claim: task_finish or task_abandon on it.";
31
+ readonly workClaimInReview: "Work claim on an in-review task: abandon is rejected (409); wait for the reviewer, or task_merge + task_finish outcome=approve.";
32
+ readonly reviewClaim: "Review claim: task_abandon frees the review lock.";
33
+ };
34
+ export declare const KNOWN_RULE_CORRECTIVES: Record<string, string>;
35
+ /** True when `value` (trimmed) looks like an LLM-style structured wrapper
36
+ * around what should be plain prose: an `<?xml` preamble, a fenced code
37
+ * block (the single most common mistake — wrapping the whole answer, or a
38
+ * JSON payload, in a \`\`\` / \`\`\`json fence), valid whole-string JSON, or
39
+ * a suspicious tag pair (see hasSuspiciousTagPair). Deliberately NOT
40
+ * triggered by a value that merely contains an angle bracket or a brace
41
+ * somewhere in ordinary prose, or by a single inline-formatting tag pair
42
+ * (e.g. a result of exactly "<b>Done</b>") — both stay legitimate prose. */
43
+ export declare function looksLikeStructuredWrapper(value: string): boolean;
44
+ export declare function resultMustBePlainStringError(verb?: "task_finish" | "tasks_update"): TeachingError;
45
+ export declare function projectAddressingConflictError(verb: string, reason?: "both_provided" | "neither_provided" | "project_and_projectId" | "project_and_projectSlug"): TeachingError;
46
+ export declare function unknownProjectSlugError(slug: string, verb: string): TeachingError;
47
+ /** Enforces the response budget invariant documented in the file header.
48
+ * buildTeachingError's own per-field clamps (MESSAGE_CHAR_BUDGET,
49
+ * RECIPE_CHAR_BUDGET) and each catalog entry's own array/key clamps
50
+ * bound individual FIELDS' codepoint counts, never their escaped wire
51
+ * cost nor their sum: several near-max fields at once, or a single
52
+ * escape-heavy `message`, can still exceed ERROR_BUDGET_CHARS in total.
53
+ * This is the one place that actually guarantees the total. `code`,
54
+ * `recipe`, and `allowedNext` are never touched here EXCEPT in the
55
+ * unreachable-today overflow case described on ERROR_BUDGET_OVERFLOW_CODE
56
+ * (the contract otherwise mandates them whole, regardless of size, and
57
+ * none of the three carries raw untrusted text at any of today's catalog
58
+ * call sites -- see the file header). `detail` is degraded first, and
59
+ * NEVER silently: first a harder recursive re-clamp (same
60
+ * clampDetailValue walk, tighter HARD_* limits), and, only if that still
61
+ * is not enough AND this entry actually had a `detail` to begin with, a
62
+ * small visible summary object replaces it entirely, so a caller always
63
+ * sees that something was omitted rather than getting a truncated,
64
+ * possibly-misleading fragment (an entry with no `detail` at all never
65
+ * has one fabricated here -- see the `if (priorDetail)` guard below).
66
+ * Only if the total STILL exceeds budget after `detail` is fully
67
+ * minimized (or was never present) does `message` itself get shortened,
68
+ * via trimMessageForBudget above -- the one scenario the per-field clamps
69
+ * alone cannot catch, since an escape-heavy `message` can blow the wire
70
+ * budget even with an empty `detail`.
71
+ *
72
+ * Exported so tests/errors.test.ts can exercise the
73
+ * ERROR_BUDGET_OVERFLOW_CODE fallback directly with a synthetic,
74
+ * hand-built TeachingError whose code/recipe alone already exceed
75
+ * ERROR_BUDGET_CHARS -- not a runtime consumer outside this module (same
76
+ * idiom as KNOWN_RULE_CORRECTIVES/ALREADY_CLAIMED_CASES above), and the
77
+ * only way to reach that fallback deterministically in a test, since no
78
+ * real catalog entry's own code/recipe/allowedNext gets anywhere close
79
+ * to ERROR_BUDGET_CHARS today (see the envelope-floor tests). */
80
+ export declare function enforceErrorBudget(err: TeachingError): TeachingError;
81
+ /**
82
+ * Maps a backend AgentTasksApiError's (status, body) to the teaching-error
83
+ * shape. `verbContext`, when supplied, is the calling tool's own registered
84
+ * name — see the precondition_failed catalog entry above for the one place
85
+ * it changes the output.
86
+ */
87
+ export declare function mapBackendError(status: number, rawBody: unknown, verbContext?: string): TeachingError;