@lanework/contracts 0.0.0-stage → 0.4.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/LICENSE +21 -0
- package/README.md +39 -2
- package/package.json +32 -4
- package/src/agent-notes.ts +69 -0
- package/src/auth.ts +251 -0
- package/src/boards.ts +932 -0
- package/src/checkpoints.ts +96 -0
- package/src/common.ts +85 -0
- package/src/endpoints.ts +435 -0
- package/src/index.ts +18 -0
- package/src/sync.ts +148 -0
- package/src/tools/board.ts +590 -0
- package/src/tools/control.ts +519 -0
- package/src/tools/index.ts +41 -0
- package/src/tools/instructions.ts +153 -0
- package/src/tools/kit.ts +233 -0
- package/src/tools/outputs.ts +279 -0
- package/src/tools/schema.ts +149 -0
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
// How an agent uses the board tools: the `instructions` both Lanework MCP
|
|
2
|
+
// servers answer `initialize` with, the cloud one (mcp.lanework.dev) and the
|
|
3
|
+
// desktop's offline one, word for word.
|
|
4
|
+
//
|
|
5
|
+
// One source, so the rules ship with the tools: a server update is a rules
|
|
6
|
+
// update, in every harness and every repo, and a project's AGENTS.md needs
|
|
7
|
+
// only a pointer (`AGENT_NOTES`). Both servers' parity checks compare their
|
|
8
|
+
// `initialize` answer with these strings.
|
|
9
|
+
//
|
|
10
|
+
// ⚠️ Constants only, never built per request: they head the model's context,
|
|
11
|
+
// and text that changed per call would break the client's prompt cache.
|
|
12
|
+
|
|
13
|
+
const INTRO =
|
|
14
|
+
"lanework is a Kanban board for AI-driven development. A card is a " +
|
|
15
|
+
"review checklist: decisions to approve, then verify steps to prove. ";
|
|
16
|
+
|
|
17
|
+
/** Finding the board, as far as a session with only `list_boards` can. */
|
|
18
|
+
const FIND_BOARD =
|
|
19
|
+
"Every tool needs a board_id and there is no default. A conversation " +
|
|
20
|
+
"the Lanework app started is told its board_id when it starts: use that " +
|
|
21
|
+
"one. Otherwise run `git remote get-url origin` and call " +
|
|
22
|
+
"list_boards({ repo }) with the output as is. Exactly one board: use it. ";
|
|
23
|
+
|
|
24
|
+
/** What a full session does when the repo has no board, or several. */
|
|
25
|
+
const NO_BOARD =
|
|
26
|
+
"None: call list_boards without repo and ask the user which board this " +
|
|
27
|
+
"repo belongs to — the boards you can see, PLUS an option to create a " +
|
|
28
|
+
"new board for this repo (suggest `owner/name` from the remote as its " +
|
|
29
|
+
"name). Then link_repo the one they picked, or create_board if they " +
|
|
30
|
+
"chose a new one; never create a board they did not ask for. A board " +
|
|
31
|
+
"links to ONE repo: linking a board that already has another repo " +
|
|
32
|
+
"MOVES it (replace), it never adds a second. Several: ask the user. No " +
|
|
33
|
+
"git remote: ask the user. Never pick a board by its name. ";
|
|
34
|
+
|
|
35
|
+
/** Creating a card: what every create_review must carry. */
|
|
36
|
+
const NEW_CARD =
|
|
37
|
+
"Before creating a card, read board_summary so its category and tags " +
|
|
38
|
+
"match the vocabulary the board already uses; the category is also what " +
|
|
39
|
+
"mints the card's permanent task id. Every create_review (a successor " +
|
|
40
|
+
"card too) passes category, 1-3 tags and priority explicitly: high for " +
|
|
41
|
+
"blockers and release prerequisites, medium for planned work, low for " +
|
|
42
|
+
"polish. Put context, an out-of-scope section and the files touched in " +
|
|
43
|
+
"the body; decisions the user approves and verify steps that prove the " +
|
|
44
|
+
"work in the checklist, a pick-ONE choice as boxes sharing a `group` " +
|
|
45
|
+
"with the recommendation marked. Never invent a task id: the server " +
|
|
46
|
+
"mints it. After create_review, offer to review the new card right " +
|
|
47
|
+
"here. ";
|
|
48
|
+
|
|
49
|
+
/** The gate between a card's plan and its implementation. */
|
|
50
|
+
const REVIEW_GATE =
|
|
51
|
+
"Behavior-changing work starts only once every decision box is ticked " +
|
|
52
|
+
"(a card in todo with decisions open is a plan, not a go). Read-only " +
|
|
53
|
+
"requests, single-file obvious fixes, or work whose exact shape the user " +
|
|
54
|
+
"gave need no card. Use toggle_item for checklist boxes and notes, " +
|
|
55
|
+
"update_review for metadata, set_status for lanes; ticking a verify item " +
|
|
56
|
+
"sends evidence (the command and whether it passed). ";
|
|
57
|
+
|
|
58
|
+
const CHECKPOINT_FLOW =
|
|
59
|
+
"While working a card, call checkpoint after each checklist item you " +
|
|
60
|
+
"finish and before you stop mid-task. Asked to resume a card: " +
|
|
61
|
+
"get_review it and read its checkpoint. If checkpoint.git.wipRef is " +
|
|
62
|
+
"set AND you are not in the checkout it came from (checkpoint.host " +
|
|
63
|
+
"is another machine, or this is a fresh clone or a cloud sandbox), " +
|
|
64
|
+
"check out checkpoint.git.head, then `git fetch origin <wipRef> && " +
|
|
65
|
+
"git cherry-pick --no-commit FETCH_HEAD && git reset` to restore the " +
|
|
66
|
+
"uncommitted work; in the same checkout that work is already on " +
|
|
67
|
+
"disk, so skip it. Re-run every check it claims passed, then " +
|
|
68
|
+
"continue from nextStep (or the summary). ";
|
|
69
|
+
|
|
70
|
+
const STALE =
|
|
71
|
+
"A card with `stale` set was left mid-task by another agent: before " +
|
|
72
|
+
"opening a new card for the same work, get_review it and resume from " +
|
|
73
|
+
"its checkpoint. ";
|
|
74
|
+
|
|
75
|
+
const HAND_OFF =
|
|
76
|
+
"Finished and verified work goes to the board's review-role lane via " +
|
|
77
|
+
"set_status, not done; only a human moves it to done. A card sent " +
|
|
78
|
+
"back from review carries changesRequested.reason in get_review: " +
|
|
79
|
+
"read it first. " +
|
|
80
|
+
"When set_status returns retro, propose at most 3 lessons and ask the " +
|
|
81
|
+
"user before writing any. ";
|
|
82
|
+
|
|
83
|
+
/** Leading a card's streams (BE-19); also the `work` prompt's text. */
|
|
84
|
+
export const STREAMS_FLOW =
|
|
85
|
+
"A card with streams comes back from get_review with `dispatch: { waves, " +
|
|
86
|
+
"briefs }`, and you are its lead. Run it wave by wave: spawn every stream " +
|
|
87
|
+
"of a wave at once, one sub-agent per stream, each in its own git worktree " +
|
|
88
|
+
"from the current HEAD (in the shared checkout when its isolation is " +
|
|
89
|
+
"shared), and hand each one `dispatch.briefs[key]` verbatim. No " +
|
|
90
|
+
"sub-agents? Run the streams yourself, one by one, in wave order. " +
|
|
91
|
+
"Sub-agents never call Lanework and never commit. After each wave, merge " +
|
|
92
|
+
"each worktree into the main checkout, revert anything outside the " +
|
|
93
|
+
"stream's `owns`, re-run the stream's checks, tick its verify items, and " +
|
|
94
|
+
"call checkpoint once for the wave. After the last wave, run the untagged " +
|
|
95
|
+
"verify items. On resume, re-dispatch only the streams whose verify items " +
|
|
96
|
+
"are not all ticked. A card without streams (dispatch: null) works as " +
|
|
97
|
+
"before: one agent, end to end.";
|
|
98
|
+
|
|
99
|
+
/** Splitting a new card into streams, when writing it. */
|
|
100
|
+
const WRITE_STREAMS =
|
|
101
|
+
"Split a card into streams only when it touches two or more independent " +
|
|
102
|
+
"write areas: each stream has a key (W0, W1…), a goal, a role and exact " +
|
|
103
|
+
"`owns` paths no other stream in its wave owns, and at least one verify " +
|
|
104
|
+
"item tagged with its key; shared types go in a W0 the others depend " +
|
|
105
|
+
"on, at most 4 streams per wave. ";
|
|
106
|
+
|
|
107
|
+
/** Reviewing a card with the user (BE-14); also the `review` prompt's text. */
|
|
108
|
+
export const REVIEW_FLOW =
|
|
109
|
+
"To review a card with the user in the CLI: get_review it, then ask the " +
|
|
110
|
+
"user with your option picker (AskUserQuestion) if you have one. Each " +
|
|
111
|
+
"pick-ONE group (boxes sharing a `group`) is one single-select question, " +
|
|
112
|
+
"its options the group's boxes, the one marked (Recommended) first. Gather " +
|
|
113
|
+
"the ungrouped decisions into multi-select questions of up to 4 boxes " +
|
|
114
|
+
"each. At most 4 questions per turn — ask again for the rest. A group with " +
|
|
115
|
+
"more than 4 options cannot fit: say so and send the user to the app for " +
|
|
116
|
+
"that group. Then call review_card ONCE with exactly what the user picked: " +
|
|
117
|
+
"a picked box checked: true, an offered but unpicked ungrouped box " +
|
|
118
|
+
"checked: false, and anything they typed under Other as that box's note. " +
|
|
119
|
+
"Never tick a decision the user did not pick; only a plain instruction in " +
|
|
120
|
+
"chat (e.g. 'tick the recommended ones') stands in for the picker. " +
|
|
121
|
+
"review_card does not move the card, and work starts only once it answers " +
|
|
122
|
+
"ready: true.";
|
|
123
|
+
|
|
124
|
+
/** Every board tool's rules: the full toolset's `initialize` instructions. */
|
|
125
|
+
export const BOARD_INSTRUCTIONS =
|
|
126
|
+
INTRO +
|
|
127
|
+
FIND_BOARD +
|
|
128
|
+
NO_BOARD +
|
|
129
|
+
NEW_CARD +
|
|
130
|
+
REVIEW_GATE +
|
|
131
|
+
CHECKPOINT_FLOW +
|
|
132
|
+
STALE +
|
|
133
|
+
HAND_OFF +
|
|
134
|
+
WRITE_STREAMS +
|
|
135
|
+
STREAMS_FLOW +
|
|
136
|
+
" " +
|
|
137
|
+
REVIEW_FLOW;
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* The worker toolset's instructions (BE-24): only what a session working
|
|
141
|
+
* ONE existing card needs. Sentences about tools it does not have would
|
|
142
|
+
* cost tokens every turn and invite calls to tools that are not there.
|
|
143
|
+
*/
|
|
144
|
+
export const BOARD_WORKER_INSTRUCTIONS =
|
|
145
|
+
INTRO +
|
|
146
|
+
"This connection serves only the tools for working an existing card; " +
|
|
147
|
+
"creating, linking or reviewing cards needs the full lanework server. " +
|
|
148
|
+
FIND_BOARD +
|
|
149
|
+
"None, several, or no git remote: ask the user. Never pick a board by " +
|
|
150
|
+
"its name. Do not start a card still in todo with decisions unticked. " +
|
|
151
|
+
CHECKPOINT_FLOW +
|
|
152
|
+
HAND_OFF +
|
|
153
|
+
STREAMS_FLOW;
|
package/src/tools/kit.ts
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
// The 5 lanework-kit tools (FE-152): searching this machine's files and agent
|
|
2
|
+
// transcripts. The `lwk` CLI and the lanework-kit MCP server run them on one
|
|
3
|
+
// core; the board MCP servers do not serve them. Offline only: the cloud
|
|
4
|
+
// cannot read this machine's disk.
|
|
5
|
+
//
|
|
6
|
+
// NOTE: Every path an answer carries is relative to the folder searched,
|
|
7
|
+
// `/`-separated. Ranges are `[start, end)` UTF-16 offsets.
|
|
8
|
+
import type { ToolContract, ToolParam } from "./schema";
|
|
9
|
+
|
|
10
|
+
export type KitToolName =
|
|
11
|
+
| "find_files"
|
|
12
|
+
| "search_text"
|
|
13
|
+
| "search_structural"
|
|
14
|
+
| "list_files"
|
|
15
|
+
| "search_sessions";
|
|
16
|
+
|
|
17
|
+
/** Each kit tool's `limit`: what it is when omitted, and the most it may be. */
|
|
18
|
+
export const KIT_TOOL_LIMITS = {
|
|
19
|
+
find_files: { default: 50, max: 200 },
|
|
20
|
+
search_text: { default: 50, max: 200 },
|
|
21
|
+
search_structural: { default: 50, max: 200 },
|
|
22
|
+
list_files: { default: 1000, max: 50_000 },
|
|
23
|
+
search_sessions: { default: 20, max: 50 },
|
|
24
|
+
} as const satisfies Record<KitToolName, { default: number; max: number }>;
|
|
25
|
+
|
|
26
|
+
/** Languages a structural pattern can be written in. */
|
|
27
|
+
export const STRUCTURAL_LANGS = [
|
|
28
|
+
"ts",
|
|
29
|
+
"tsx",
|
|
30
|
+
"js",
|
|
31
|
+
"jsx",
|
|
32
|
+
"json",
|
|
33
|
+
"css",
|
|
34
|
+
"html",
|
|
35
|
+
"python",
|
|
36
|
+
"rust",
|
|
37
|
+
"go",
|
|
38
|
+
] as const;
|
|
39
|
+
export type StructuralLang = (typeof STRUCTURAL_LANGS)[number];
|
|
40
|
+
|
|
41
|
+
/** The agent harnesses whose transcripts `search_sessions` reads. */
|
|
42
|
+
export type SessionHarness = "claude" | "codex" | "opencode";
|
|
43
|
+
|
|
44
|
+
// ── Shared parameter shapes ─────────────────────────────────────────────────
|
|
45
|
+
|
|
46
|
+
const FOLDER: ToolParam = {
|
|
47
|
+
type: "string",
|
|
48
|
+
description:
|
|
49
|
+
"The folder to search, an absolute path (e.g. the repo's root); the working directory when omitted",
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
function limit(tool: KitToolName, what: string): ToolParam {
|
|
53
|
+
const { default: fallback, max } = KIT_TOOL_LIMITS[tool];
|
|
54
|
+
return {
|
|
55
|
+
type: "integer",
|
|
56
|
+
minimum: 1,
|
|
57
|
+
maximum: max,
|
|
58
|
+
description: `${what} returned; default ${fallback}`,
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// ── The tools ───────────────────────────────────────────────────────────────
|
|
63
|
+
|
|
64
|
+
/** The kit tools, in the order `tools/list` advertises them. */
|
|
65
|
+
export const KIT_TOOLS: readonly ToolContract<KitToolName>[] = [
|
|
66
|
+
{
|
|
67
|
+
name: "find_files",
|
|
68
|
+
description:
|
|
69
|
+
"Fuzzy-find files by path in a folder, best match first. Respects .gitignore. Returns each file's path, score and the matched character ranges.",
|
|
70
|
+
readOnly: true,
|
|
71
|
+
properties: {
|
|
72
|
+
query: {
|
|
73
|
+
type: "string",
|
|
74
|
+
description: "Part of a file name or path, e.g. `mcp tools`",
|
|
75
|
+
},
|
|
76
|
+
folder: FOLDER,
|
|
77
|
+
limit: limit("find_files", "Files"),
|
|
78
|
+
},
|
|
79
|
+
required: ["query"],
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
name: "search_text",
|
|
83
|
+
description:
|
|
84
|
+
"Search the contents of a folder's files with ripgrep. Respects .gitignore; skips hidden and binary files. Returns each matching file with its matching lines (1-based) and match ranges; `truncated` marks where the search stopped.",
|
|
85
|
+
readOnly: true,
|
|
86
|
+
properties: {
|
|
87
|
+
query: {
|
|
88
|
+
type: "string",
|
|
89
|
+
description: "A literal string, or a regex when `regex` is true",
|
|
90
|
+
},
|
|
91
|
+
folder: FOLDER,
|
|
92
|
+
regex: {
|
|
93
|
+
type: "boolean",
|
|
94
|
+
description: "Read `query` as a regex (ripgrep's syntax)",
|
|
95
|
+
},
|
|
96
|
+
case_sensitive: {
|
|
97
|
+
type: "boolean",
|
|
98
|
+
description: "Match case; ignored when omitted",
|
|
99
|
+
},
|
|
100
|
+
globs: {
|
|
101
|
+
type: "string[]",
|
|
102
|
+
description: "ripgrep globs limiting the files; a leading `!` excludes",
|
|
103
|
+
},
|
|
104
|
+
limit: limit("search_text", "Files"),
|
|
105
|
+
},
|
|
106
|
+
required: ["query"],
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
name: "search_structural",
|
|
110
|
+
description:
|
|
111
|
+
"Search a folder's code by syntax with an ast-grep pattern, e.g. `console.log($A)`. Respects .gitignore. Returns each matching file with its matching lines and match ranges, as search_text does.",
|
|
112
|
+
readOnly: true,
|
|
113
|
+
properties: {
|
|
114
|
+
pattern: {
|
|
115
|
+
type: "string",
|
|
116
|
+
description: "An ast-grep pattern; `$A` matches one node",
|
|
117
|
+
},
|
|
118
|
+
folder: FOLDER,
|
|
119
|
+
lang: {
|
|
120
|
+
type: "string",
|
|
121
|
+
enum: STRUCTURAL_LANGS,
|
|
122
|
+
description:
|
|
123
|
+
"The pattern's language; each file's own, from its extension, when omitted",
|
|
124
|
+
},
|
|
125
|
+
limit: limit("search_structural", "Files"),
|
|
126
|
+
},
|
|
127
|
+
required: ["pattern"],
|
|
128
|
+
},
|
|
129
|
+
{
|
|
130
|
+
name: "list_files",
|
|
131
|
+
description:
|
|
132
|
+
"Every file in a folder that ripgrep would search: .gitignore respected, hidden files skipped. Paths in no particular order; `truncated` when cut at the limit.",
|
|
133
|
+
readOnly: true,
|
|
134
|
+
properties: {
|
|
135
|
+
folder: FOLDER,
|
|
136
|
+
limit: limit("list_files", "Paths"),
|
|
137
|
+
},
|
|
138
|
+
},
|
|
139
|
+
// FE-149: moved here from the offline board MCP. Text kept as it was.
|
|
140
|
+
{
|
|
141
|
+
name: "search_sessions",
|
|
142
|
+
description:
|
|
143
|
+
"Search this machine's Claude Code, Codex and OpenCode conversations for a phrase in what was said (prompts, answers, tool calls and output), newest first. Returns each session's harness, id, title, last write and up to 3 matching snippets.",
|
|
144
|
+
readOnly: true,
|
|
145
|
+
properties: {
|
|
146
|
+
query: { type: "string", description: "A literal phrase, not a regex" },
|
|
147
|
+
limit: limit("search_sessions", "Sessions"),
|
|
148
|
+
folder: {
|
|
149
|
+
type: "string",
|
|
150
|
+
description:
|
|
151
|
+
"Only sessions run in this folder (an absolute path, e.g. the repo's root); every folder's when omitted",
|
|
152
|
+
},
|
|
153
|
+
},
|
|
154
|
+
required: ["query"],
|
|
155
|
+
},
|
|
156
|
+
];
|
|
157
|
+
|
|
158
|
+
// ── The answers ─────────────────────────────────────────────────────────────
|
|
159
|
+
|
|
160
|
+
/** A file whose path matches a fuzzy query. */
|
|
161
|
+
export interface FileHit {
|
|
162
|
+
/** Relative to the searched folder, `/`-separated. */
|
|
163
|
+
path: string;
|
|
164
|
+
/** Higher is a better match. Only comparable within one answer. */
|
|
165
|
+
score: number;
|
|
166
|
+
/** The matched characters as `[start, end)` UTF-16 offsets into `path`. */
|
|
167
|
+
ranges?: [number, number][];
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/** One matching line. */
|
|
171
|
+
export interface MatchLine {
|
|
172
|
+
/** 1-based line number. */
|
|
173
|
+
line: number;
|
|
174
|
+
/** The line, without its newline. A very long line is cut to a window around its first match. */
|
|
175
|
+
text: string;
|
|
176
|
+
/** Each match as `[start, end)` UTF-16 offsets into `text`. */
|
|
177
|
+
ranges: [number, number][];
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/** A file with matches. */
|
|
181
|
+
export interface FileMatch {
|
|
182
|
+
/** Relative to the searched folder, `/`-separated. */
|
|
183
|
+
path: string;
|
|
184
|
+
lines: MatchLine[];
|
|
185
|
+
/**
|
|
186
|
+
* The search stopped in or right after this file (a match or file limit, or
|
|
187
|
+
* the timeout), so there may be more matches here or after it.
|
|
188
|
+
*/
|
|
189
|
+
truncated: boolean;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** A session transcript with matches. */
|
|
193
|
+
export interface SessionMatch {
|
|
194
|
+
harness: SessionHarness;
|
|
195
|
+
sessionId: string;
|
|
196
|
+
/** The session's title, or its first prompt. */
|
|
197
|
+
title: string;
|
|
198
|
+
/** When the session was last written, ISO 8601. */
|
|
199
|
+
at: string;
|
|
200
|
+
/** The transcript, relative to the harness's own folder. */
|
|
201
|
+
file: string;
|
|
202
|
+
lines: MatchLine[];
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
/** What each kit tool takes, as the MCP server and `lwk` both read it. */
|
|
206
|
+
export interface KitToolInputs {
|
|
207
|
+
find_files: { query: string; folder?: string; limit?: number };
|
|
208
|
+
search_text: {
|
|
209
|
+
query: string;
|
|
210
|
+
folder?: string;
|
|
211
|
+
regex?: boolean;
|
|
212
|
+
case_sensitive?: boolean;
|
|
213
|
+
globs?: string[];
|
|
214
|
+
limit?: number;
|
|
215
|
+
};
|
|
216
|
+
search_structural: {
|
|
217
|
+
pattern: string;
|
|
218
|
+
folder?: string;
|
|
219
|
+
lang?: StructuralLang;
|
|
220
|
+
limit?: number;
|
|
221
|
+
};
|
|
222
|
+
list_files: { folder?: string; limit?: number };
|
|
223
|
+
search_sessions: { query: string; folder?: string; limit?: number };
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/** What each kit tool answers, inside its text content, as JSON. */
|
|
227
|
+
export interface KitToolOutputs {
|
|
228
|
+
find_files: { files: FileHit[] };
|
|
229
|
+
search_text: { matches: FileMatch[] };
|
|
230
|
+
search_structural: { matches: FileMatch[] };
|
|
231
|
+
list_files: { files: string[]; truncated: boolean };
|
|
232
|
+
search_sessions: { sessions: SessionMatch[] };
|
|
233
|
+
}
|
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
// What each board tool answers, as data a script can check a live answer
|
|
2
|
+
// against (BE-28). `BoardToolOutputs` states it for the compiler; types do not
|
|
3
|
+
// exist at run time, so this file states it again for the two parity gates:
|
|
4
|
+
// `apps/desktop/scripts/mcp-parity.mjs` (offline server) and
|
|
5
|
+
// `apps/mcp/scripts/mcp-parity.ts` in the cloud repo. One definition, so
|
|
6
|
+
// the two servers are held to the same answer.
|
|
7
|
+
//
|
|
8
|
+
// NOTE: An object shape is exact: a missing key and an extra one are both
|
|
9
|
+
// drift. Change this file together with `BoardToolOutputs` in board.ts.
|
|
10
|
+
import type { BoardToolName } from "./board";
|
|
11
|
+
|
|
12
|
+
/** A run-time description of a JSON value. */
|
|
13
|
+
export type Shape =
|
|
14
|
+
| { kind: "string" | "number" | "boolean" | "any" }
|
|
15
|
+
| { kind: "nullable" | "optional" | "list" | "record"; inner: Shape }
|
|
16
|
+
| { kind: "object"; fields: Record<string, Shape> }
|
|
17
|
+
| { kind: "enum"; values: readonly unknown[] };
|
|
18
|
+
|
|
19
|
+
const str: Shape = { kind: "string" };
|
|
20
|
+
const num: Shape = { kind: "number" };
|
|
21
|
+
const bool: Shape = { kind: "boolean" };
|
|
22
|
+
const any: Shape = { kind: "any" };
|
|
23
|
+
const nullable = (inner: Shape): Shape => ({ kind: "nullable", inner });
|
|
24
|
+
const optional = (inner: Shape): Shape => ({ kind: "optional", inner });
|
|
25
|
+
const list = (inner: Shape): Shape => ({ kind: "list", inner });
|
|
26
|
+
const record = (inner: Shape): Shape => ({ kind: "record", inner });
|
|
27
|
+
const obj = (fields: Record<string, Shape>): Shape => ({
|
|
28
|
+
kind: "object",
|
|
29
|
+
fields,
|
|
30
|
+
});
|
|
31
|
+
const oneOf = (...values: unknown[]): Shape => ({ kind: "enum", values });
|
|
32
|
+
|
|
33
|
+
const PRIORITY = nullable(oneOf("low", "medium", "high"));
|
|
34
|
+
const COLUMN_ROLE = nullable(
|
|
35
|
+
oneOf("intake", "start", "active", "review", "done", "archive"),
|
|
36
|
+
);
|
|
37
|
+
|
|
38
|
+
const BOARD_SUMMARY = obj({
|
|
39
|
+
workspaceId: str,
|
|
40
|
+
name: str,
|
|
41
|
+
role: str,
|
|
42
|
+
changeSeq: num,
|
|
43
|
+
repo: nullable(str),
|
|
44
|
+
});
|
|
45
|
+
const CHECKLIST_ITEM = obj({
|
|
46
|
+
key: str,
|
|
47
|
+
section: oneOf("decisions", "verify"),
|
|
48
|
+
text: str,
|
|
49
|
+
checked: bool,
|
|
50
|
+
checkedAt: nullable(str),
|
|
51
|
+
note: nullable(str),
|
|
52
|
+
group: nullable(str),
|
|
53
|
+
stream: nullable(str),
|
|
54
|
+
checkedBy: optional(any),
|
|
55
|
+
evidence: optional(any),
|
|
56
|
+
});
|
|
57
|
+
const STREAM = obj({
|
|
58
|
+
key: str,
|
|
59
|
+
title: str,
|
|
60
|
+
goal: str,
|
|
61
|
+
role: oneOf("research", "implement", "test"),
|
|
62
|
+
owns: list(str),
|
|
63
|
+
reads: list(str),
|
|
64
|
+
dependsOn: list(str),
|
|
65
|
+
isolation: oneOf("worktree", "shared"),
|
|
66
|
+
position: num,
|
|
67
|
+
});
|
|
68
|
+
const DISPATCH = obj({ waves: list(list(str)), briefs: record(str) });
|
|
69
|
+
const CARD_FIELDS: Record<string, Shape> = {
|
|
70
|
+
id: str,
|
|
71
|
+
workspaceId: str,
|
|
72
|
+
seq: num,
|
|
73
|
+
revision: num,
|
|
74
|
+
type: oneOf("epic", "issue", "task"),
|
|
75
|
+
parentId: nullable(str),
|
|
76
|
+
columnKey: str,
|
|
77
|
+
rank: str,
|
|
78
|
+
title: str,
|
|
79
|
+
body: str,
|
|
80
|
+
priority: PRIORITY,
|
|
81
|
+
estimate: nullable(num),
|
|
82
|
+
categoryKey: nullable(str),
|
|
83
|
+
taskId: nullable(str),
|
|
84
|
+
tags: list(str),
|
|
85
|
+
checklistProgress: obj({ done: num, total: num }),
|
|
86
|
+
streams: list(STREAM),
|
|
87
|
+
metadata: nullable(any),
|
|
88
|
+
source: nullable(any),
|
|
89
|
+
createdAt: nullable(str),
|
|
90
|
+
updatedAt: nullable(str),
|
|
91
|
+
startedAt: nullable(str),
|
|
92
|
+
completedAt: nullable(str),
|
|
93
|
+
dueAt: nullable(str),
|
|
94
|
+
archivedAt: nullable(str),
|
|
95
|
+
stale: optional(nullable(any)),
|
|
96
|
+
changesRequested: optional(nullable(any)),
|
|
97
|
+
};
|
|
98
|
+
const CARD = obj(CARD_FIELDS);
|
|
99
|
+
const DETAIL_FIELDS: Record<string, Shape> = {
|
|
100
|
+
...CARD_FIELDS,
|
|
101
|
+
checklist: list(CHECKLIST_ITEM),
|
|
102
|
+
assignees: obj({ users: list(str), agents: list(str) }),
|
|
103
|
+
links: list(any),
|
|
104
|
+
attachments: list(any),
|
|
105
|
+
subscribers: list(str),
|
|
106
|
+
subscribed: bool,
|
|
107
|
+
favorite: bool,
|
|
108
|
+
commentCount: num,
|
|
109
|
+
};
|
|
110
|
+
/** `CardDetail`, run plan included. */
|
|
111
|
+
const CARD_DETAIL = obj({ ...DETAIL_FIELDS, dispatch: nullable(DISPATCH) });
|
|
112
|
+
/** `get_review`'s card: its run plan sits beside it. */
|
|
113
|
+
const CARD_DETAIL_NO_DISPATCH = obj(DETAIL_FIELDS);
|
|
114
|
+
const CHECKPOINT_FIELDS: Record<string, Shape> = {
|
|
115
|
+
id: str,
|
|
116
|
+
agent: str,
|
|
117
|
+
userId: str,
|
|
118
|
+
machineId: nullable(str),
|
|
119
|
+
createdAt: str,
|
|
120
|
+
request: nullable(str),
|
|
121
|
+
summary: str,
|
|
122
|
+
nextStep: nullable(str),
|
|
123
|
+
files: list(str),
|
|
124
|
+
commands: list(obj({ command: str, ok: nullable(bool) })),
|
|
125
|
+
host: nullable(str),
|
|
126
|
+
session: nullable(str),
|
|
127
|
+
git: nullable(
|
|
128
|
+
obj({
|
|
129
|
+
branch: nullable(str),
|
|
130
|
+
head: nullable(str),
|
|
131
|
+
wipRef: nullable(str),
|
|
132
|
+
wipSha: nullable(str),
|
|
133
|
+
diffStat: nullable(str),
|
|
134
|
+
}),
|
|
135
|
+
),
|
|
136
|
+
};
|
|
137
|
+
const CARD_REF_FIELDS: Record<string, Shape> = {
|
|
138
|
+
id: str,
|
|
139
|
+
taskId: nullable(str),
|
|
140
|
+
title: str,
|
|
141
|
+
};
|
|
142
|
+
|
|
143
|
+
/** `BoardToolOutputs`, tool by tool. */
|
|
144
|
+
export const BOARD_TOOL_OUTPUT_SHAPES: Record<BoardToolName, Shape> = {
|
|
145
|
+
list_boards: obj({
|
|
146
|
+
repo: optional(str),
|
|
147
|
+
boards: list(BOARD_SUMMARY),
|
|
148
|
+
next: optional(str),
|
|
149
|
+
}),
|
|
150
|
+
create_board: obj({ board_id: str, name: str, slug: str, repo: str }),
|
|
151
|
+
link_repo: obj({
|
|
152
|
+
repo: str,
|
|
153
|
+
previous: nullable(str),
|
|
154
|
+
boards: list(BOARD_SUMMARY),
|
|
155
|
+
}),
|
|
156
|
+
board_summary: obj({
|
|
157
|
+
workspaceId: str,
|
|
158
|
+
role: str,
|
|
159
|
+
head: num,
|
|
160
|
+
lanes: list(obj({ key: str, label: str, role: COLUMN_ROLE, count: num })),
|
|
161
|
+
stale: num,
|
|
162
|
+
categories: list(obj({ key: str, name: str })),
|
|
163
|
+
tags: obj({ max: num, allowed: list(str) }),
|
|
164
|
+
labels: list(obj({ tag: str, name: str, tone: str })),
|
|
165
|
+
}),
|
|
166
|
+
list_reviews: obj({
|
|
167
|
+
items: list(CARD),
|
|
168
|
+
head: num,
|
|
169
|
+
columns: list(obj({ key: str, name: str, role: COLUMN_ROLE })),
|
|
170
|
+
}),
|
|
171
|
+
get_review: obj({
|
|
172
|
+
item: CARD_DETAIL_NO_DISPATCH,
|
|
173
|
+
checkpoint: nullable(
|
|
174
|
+
obj({
|
|
175
|
+
...CHECKPOINT_FIELDS,
|
|
176
|
+
nextStepFrom: nullable(obj({ id: str, agent: str, createdAt: str })),
|
|
177
|
+
}),
|
|
178
|
+
),
|
|
179
|
+
dispatch: nullable(DISPATCH),
|
|
180
|
+
}),
|
|
181
|
+
create_review: obj({ item: CARD_DETAIL }),
|
|
182
|
+
update_review: obj({ item: CARD_DETAIL }),
|
|
183
|
+
toggle_item: obj({
|
|
184
|
+
checklistItem: CHECKLIST_ITEM,
|
|
185
|
+
card: obj({
|
|
186
|
+
...CARD_REF_FIELDS,
|
|
187
|
+
columnKey: str,
|
|
188
|
+
revision: num,
|
|
189
|
+
done: num,
|
|
190
|
+
total: num,
|
|
191
|
+
}),
|
|
192
|
+
ready: bool,
|
|
193
|
+
open: optional(list(str)),
|
|
194
|
+
}),
|
|
195
|
+
review_card: obj({
|
|
196
|
+
ready: bool,
|
|
197
|
+
next: optional(str),
|
|
198
|
+
open: optional(list(str)),
|
|
199
|
+
item: CARD_DETAIL,
|
|
200
|
+
}),
|
|
201
|
+
set_status: obj({
|
|
202
|
+
item: CARD_DETAIL,
|
|
203
|
+
retro: optional(obj({ signals: list(any), ask: str })),
|
|
204
|
+
}),
|
|
205
|
+
delete_review: obj({ archived: str, seq: nullable(num) }),
|
|
206
|
+
checkpoint: obj({ checkpoint: obj(CHECKPOINT_FIELDS) }),
|
|
207
|
+
lifecycle_status: obj({
|
|
208
|
+
waiting: list(obj({ ...CARD_REF_FIELDS, done: num, total: num })),
|
|
209
|
+
ready: list(obj(CARD_REF_FIELDS)),
|
|
210
|
+
inFlight: list(obj({ ...CARD_REF_FIELDS, columnKey: str })),
|
|
211
|
+
review: list(obj({ ...CARD_REF_FIELDS, columnKey: str })),
|
|
212
|
+
}),
|
|
213
|
+
};
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* Every way a board tool's answer differs from its contract, as
|
|
217
|
+
* `path: what` lines; empty when it matches.
|
|
218
|
+
*/
|
|
219
|
+
export function boardToolOutputProblems(
|
|
220
|
+
name: BoardToolName,
|
|
221
|
+
value: unknown,
|
|
222
|
+
): string[] {
|
|
223
|
+
const out: string[] = [];
|
|
224
|
+
const check = (shape: Shape, v: unknown, path: string): void => {
|
|
225
|
+
switch (shape.kind) {
|
|
226
|
+
case "any":
|
|
227
|
+
return;
|
|
228
|
+
case "optional":
|
|
229
|
+
if (v !== undefined) check(shape.inner, v, path);
|
|
230
|
+
return;
|
|
231
|
+
case "nullable":
|
|
232
|
+
if (v !== null) check(shape.inner, v, path);
|
|
233
|
+
return;
|
|
234
|
+
case "string":
|
|
235
|
+
case "number":
|
|
236
|
+
case "boolean":
|
|
237
|
+
if (typeof v !== shape.kind)
|
|
238
|
+
out.push(`${path}: expected ${shape.kind}, got ${JSON.stringify(v)}`);
|
|
239
|
+
return;
|
|
240
|
+
case "enum":
|
|
241
|
+
if (!shape.values.includes(v))
|
|
242
|
+
out.push(
|
|
243
|
+
`${path}: ${JSON.stringify(v)} is not one of ${shape.values.join(", ")}`,
|
|
244
|
+
);
|
|
245
|
+
return;
|
|
246
|
+
case "list":
|
|
247
|
+
if (!Array.isArray(v)) out.push(`${path}: expected a list`);
|
|
248
|
+
else
|
|
249
|
+
for (const [i, entry] of v.entries())
|
|
250
|
+
check(shape.inner, entry, `${path}[${i}]`);
|
|
251
|
+
return;
|
|
252
|
+
case "record":
|
|
253
|
+
if (typeof v !== "object" || v === null || Array.isArray(v))
|
|
254
|
+
out.push(`${path}: expected an object`);
|
|
255
|
+
else
|
|
256
|
+
for (const [k, entry] of Object.entries(v))
|
|
257
|
+
check(shape.inner, entry, `${path}.${k}`);
|
|
258
|
+
return;
|
|
259
|
+
case "object": {
|
|
260
|
+
if (typeof v !== "object" || v === null || Array.isArray(v)) {
|
|
261
|
+
out.push(`${path}: expected an object`);
|
|
262
|
+
return;
|
|
263
|
+
}
|
|
264
|
+
const fields = v as Record<string, unknown>;
|
|
265
|
+
for (const [k, field] of Object.entries(shape.fields)) {
|
|
266
|
+
if (!(k in fields) && field.kind !== "optional")
|
|
267
|
+
out.push(`${path}.${k}: missing`);
|
|
268
|
+
else check(field, fields[k], `${path}.${k}`);
|
|
269
|
+
}
|
|
270
|
+
for (const k of Object.keys(fields))
|
|
271
|
+
if (!(k in shape.fields))
|
|
272
|
+
out.push(`${path}.${k}: not in the contract`);
|
|
273
|
+
return;
|
|
274
|
+
}
|
|
275
|
+
}
|
|
276
|
+
};
|
|
277
|
+
check(BOARD_TOOL_OUTPUT_SHAPES[name], value, name);
|
|
278
|
+
return out;
|
|
279
|
+
}
|