@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,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,45 @@
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. */
16
+ detail?: Record<string, unknown>;
17
+ };
18
+ }
19
+ /** Serializes a TeachingError exactly as server.ts's serializeResult would
20
+ * (JSON.stringify(x, null, 2) for a non-string result — a teaching error is
21
+ * always an object, never a string, so the two are always equal for this
22
+ * input). Defined locally rather than importing serializeResult from
23
+ * server.ts to avoid a circular import (server.ts -> tools.ts -> errors.ts);
24
+ * tests/errors.test.ts asserts the two stay equal for every catalog entry. */
25
+ export declare function serializeTeachingError(err: TeachingError): string;
26
+ export declare const KNOWN_RULE_CORRECTIVES: Record<string, string>;
27
+ /** True when `value` (trimmed) looks like an LLM-style structured wrapper
28
+ * around what should be plain prose: an `<?xml` preamble, a fenced code
29
+ * block (the single most common mistake — wrapping the whole answer, or a
30
+ * JSON payload, in a \`\`\` / \`\`\`json fence), valid whole-string JSON, or
31
+ * a suspicious tag pair (see hasSuspiciousTagPair). Deliberately NOT
32
+ * triggered by a value that merely contains an angle bracket or a brace
33
+ * somewhere in ordinary prose, or by a single inline-formatting tag pair
34
+ * (e.g. a result of exactly "<b>Done</b>") — both stay legitimate prose. */
35
+ export declare function looksLikeStructuredWrapper(value: string): boolean;
36
+ export declare function resultMustBePlainStringError(verb?: "task_finish" | "tasks_update"): TeachingError;
37
+ export declare function projectAddressingConflictError(verb: string, reason?: "both_provided" | "neither_provided"): TeachingError;
38
+ export declare function unknownProjectSlugError(slug: string, verb: string): TeachingError;
39
+ /**
40
+ * Maps a backend AgentTasksApiError's (status, body) to the teaching-error
41
+ * shape. `verbContext`, when supplied, is the calling tool's own registered
42
+ * name — see the precondition_failed catalog entry above for the one place
43
+ * it changes the output.
44
+ */
45
+ export declare function mapBackendError(status: number, rawBody: unknown, verbContext?: string): TeachingError;