ticket-runner 0.6.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.ko.md +97 -0
- package/README.md +98 -0
- package/bin/ticket-runner.js +6 -0
- package/docs/templates/operator-skill.md +87 -0
- package/package.json +42 -0
- package/src/acceptance-criteria.ts +44 -0
- package/src/adapters/claude-agent-runner.ts +389 -0
- package/src/adapters/exec.ts +169 -0
- package/src/adapters/gh-tracker.ts +955 -0
- package/src/adapters/git-workspace.ts +951 -0
- package/src/adapters/repo-root.ts +20 -0
- package/src/adapters/version.ts +118 -0
- package/src/base-branch.ts +21 -0
- package/src/branch.ts +33 -0
- package/src/cli.ts +135 -0
- package/src/command-line.ts +190 -0
- package/src/config.ts +277 -0
- package/src/conventions.ts +118 -0
- package/src/criteria.ts +106 -0
- package/src/frontier.ts +36 -0
- package/src/guards.ts +143 -0
- package/src/handoff.ts +82 -0
- package/src/host.ts +116 -0
- package/src/init.ts +405 -0
- package/src/labels.ts +42 -0
- package/src/landing.ts +75 -0
- package/src/lifecycle.ts +34 -0
- package/src/lock.ts +215 -0
- package/src/note-schema.ts +58 -0
- package/src/notes.ts +433 -0
- package/src/operator-skill.ts +24 -0
- package/src/orchestrator.ts +1816 -0
- package/src/ports/agent-runner.ts +105 -0
- package/src/ports/tracker.ts +334 -0
- package/src/ports/workspace.ts +422 -0
- package/src/progress.ts +231 -0
- package/src/prompts.ts +288 -0
- package/src/readiness.ts +256 -0
- package/src/remove.ts +732 -0
- package/src/resume.ts +145 -0
- package/src/run-log.ts +85 -0
- package/src/run.ts +331 -0
- package/src/self-hosting.ts +33 -0
- package/src/stage-guard.ts +32 -0
- package/src/staleness.ts +101 -0
- package/src/start.ts +284 -0
- package/src/startup.ts +34 -0
- package/src/stop.ts +178 -0
- package/src/stranded.ts +136 -0
- package/src/templates.ts +596 -0
- package/src/title.ts +97 -0
- package/src/verdict.ts +88 -0
- package/src/version-number.ts +67 -0
- package/src/version-pr.ts +103 -0
package/src/resume.ts
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
import { readdirSync } from "node:fs";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
import { REACHED_STATES, type StateFile, type TicketState } from "./ports/workspace.js";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The State file a Ticket keeps while its branch carries work worth resuming,
|
|
8
|
+
* and what a later Run makes of it (ADR-0004).
|
|
9
|
+
*
|
|
10
|
+
* A Ticket keeps the file for as long as there is work on its branch worth
|
|
11
|
+
* resuming, so it is written as part of the Claim and rewritten whenever the
|
|
12
|
+
* Ticket reaches something a later Run should not pay for again. Three Runs read
|
|
13
|
+
* it, and what the board says decides which. One finds a Ticket the subscription
|
|
14
|
+
* rate limit released: nothing was wrong with it, so the Claim came off and this
|
|
15
|
+
* file says where to carry on from. One finds a Ticket still claimed — the Run
|
|
16
|
+
* that claimed it was killed and never released anything — and resumes it in
|
|
17
|
+
* place. One finds a Ticket a human was handed and has relabelled
|
|
18
|
+
* `ready-for-agent`, which is the human handing it back. A Ticket still sitting
|
|
19
|
+
* in `ready-for-human` is none of them: its file is inert until a human moves
|
|
20
|
+
* the label or the issue closes.
|
|
21
|
+
*
|
|
22
|
+
* It lives on the Target's remote, where a Run on any Host finds it; where
|
|
23
|
+
* exactly is the git-backed Workspace's business
|
|
24
|
+
* ({@link import("./ports/workspace.js").Workspace.readState} and the rest).
|
|
25
|
+
* This is only what the file says and what its name is, which that Workspace
|
|
26
|
+
* reads and writes through here. Whether the branch a file names is still there
|
|
27
|
+
* is the Workspace's other question, and whether the Ticket is released or
|
|
28
|
+
* stranded is the Claim's, read off GitHub.
|
|
29
|
+
*/
|
|
30
|
+
|
|
31
|
+
const stateSchema = z.object({
|
|
32
|
+
ticket: z.number().int().positive(),
|
|
33
|
+
branch: z.string().min(1),
|
|
34
|
+
state: z.enum(REACHED_STATES),
|
|
35
|
+
fixUsed: z.boolean(),
|
|
36
|
+
pullRequest: z.number().int().positive().optional(),
|
|
37
|
+
title: z.string().optional(),
|
|
38
|
+
runId: z.string(),
|
|
39
|
+
version: z.string().optional(),
|
|
40
|
+
updatedAt: z.string(),
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
/** One file per Ticket, named for it. */
|
|
44
|
+
export function stateFileName(ticket: number): string {
|
|
45
|
+
return `ticket-${ticket}.json`;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** The name {@link stateFileName} gives, read back the other way. */
|
|
49
|
+
const STATE_FILE = /^ticket-(\d+)\.json$/;
|
|
50
|
+
|
|
51
|
+
/** The Ticket a file of that name is about, or undefined for any other file. */
|
|
52
|
+
export function stateFileTicket(name: string): number | undefined {
|
|
53
|
+
const match = STATE_FILE.exec(name);
|
|
54
|
+
return match === null ? undefined : Number.parseInt(match[1] as string, 10);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** What the file holds: JSON a human can read without the pipeline. */
|
|
58
|
+
export function stateFileContents(state: TicketState): string {
|
|
59
|
+
return `${JSON.stringify(state, null, 2)}\n`;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* What the file `ticket` keeps says, and which of the two things it is.
|
|
64
|
+
*
|
|
65
|
+
* A file that is not JSON, one missing what resuming needs, and one a newer
|
|
66
|
+
* pipeline shaped differently are all unreadable: starting the Ticket over is
|
|
67
|
+
* always safe, and resuming on a guess is not. So is one that names another
|
|
68
|
+
* Ticket than its own name does, which no Version would resume either.
|
|
69
|
+
*/
|
|
70
|
+
export function readStateFile(contents: string, ticket: number): StateFile {
|
|
71
|
+
const raw = parseJson(contents);
|
|
72
|
+
const parsed = stateSchema.safeParse(raw);
|
|
73
|
+
if (!parsed.success || parsed.data.ticket !== ticket) {
|
|
74
|
+
const version = namedVersion(raw);
|
|
75
|
+
return { readable: false, ticket, ...(version === undefined ? {} : { version }) };
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
// A pull request nobody opened, a title no Stage answered, and a Version an
|
|
79
|
+
// older pipeline never wrote, are keys that are not there rather than keys
|
|
80
|
+
// holding nothing: the rest of the pipeline reads these with the same
|
|
81
|
+
// distinction.
|
|
82
|
+
const { pullRequest, title, version, ...state } = parsed.data;
|
|
83
|
+
return {
|
|
84
|
+
readable: true,
|
|
85
|
+
state: {
|
|
86
|
+
...state,
|
|
87
|
+
...(pullRequest === undefined ? {} : { pullRequest }),
|
|
88
|
+
...(title === undefined ? {} : { title }),
|
|
89
|
+
...(version === undefined ? {} : { version }),
|
|
90
|
+
},
|
|
91
|
+
};
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* The Version a file that will not parse still names, where it names one.
|
|
96
|
+
*
|
|
97
|
+
* Read off the raw JSON rather than the schema, because the schema is exactly
|
|
98
|
+
* what refused the file: a State file a newer pipeline wrote is named by the
|
|
99
|
+
* Version that wrote it, whatever else about it this one cannot read.
|
|
100
|
+
*/
|
|
101
|
+
function namedVersion(raw: unknown): string | undefined {
|
|
102
|
+
if (raw === null || typeof raw !== "object" || !("version" in raw)) return undefined;
|
|
103
|
+
const version = (raw as { version: unknown }).version;
|
|
104
|
+
return typeof version === "string" && version !== "" ? version : undefined;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** The file's JSON, or undefined where it is not JSON — which the schema refuses. */
|
|
108
|
+
function parseJson(contents: string): unknown {
|
|
109
|
+
try {
|
|
110
|
+
return JSON.parse(contents);
|
|
111
|
+
} catch {
|
|
112
|
+
return undefined;
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* The branch of the Target's remote that holds every Ticket's State, one file
|
|
118
|
+
* per Ticket, and the transcripts of a handed-off Ticket's Stages beside it,
|
|
119
|
+
* under the prefix the pipeline owns (ADR-0004). Named here rather than only in
|
|
120
|
+
* the Workspace that writes it, because `ticket-runner remove` deletes it by
|
|
121
|
+
* name and the conventions document names it to every human.
|
|
122
|
+
*/
|
|
123
|
+
export const STATE_BRANCH = "ticket-runner/state";
|
|
124
|
+
|
|
125
|
+
/** Where a pipeline before the state branch kept the State files, in the checkout. */
|
|
126
|
+
export const LOCAL_STATE_DIR = join(".ticket-runner", "state");
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* The Tickets whose State files a pipeline before the state branch left in this
|
|
130
|
+
* checkout, in ascending number.
|
|
131
|
+
*
|
|
132
|
+
* Nothing reads them any more, and nothing migrates them (ADR-0004): a Run that
|
|
133
|
+
* finds any refuses to start, because each is a Ticket a Run would otherwise
|
|
134
|
+
* take from the top, or never sweep at all, without a word.
|
|
135
|
+
*/
|
|
136
|
+
export function localStateTickets(repoRoot: string): number[] {
|
|
137
|
+
let entries: string[];
|
|
138
|
+
try {
|
|
139
|
+
entries = readdirSync(join(repoRoot, LOCAL_STATE_DIR));
|
|
140
|
+
} catch {
|
|
141
|
+
// No directory at all: no earlier pipeline ever claimed anything here.
|
|
142
|
+
return [];
|
|
143
|
+
}
|
|
144
|
+
return entries.flatMap((entry) => stateFileTicket(entry) ?? []).sort((a, b) => a - b);
|
|
145
|
+
}
|
package/src/run-log.ts
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
|
|
2
|
+
import { join, sep } from "node:path";
|
|
3
|
+
|
|
4
|
+
/** Where one Run's transcripts live: one directory per Run, under the repo root. */
|
|
5
|
+
export function runLogDir(repoRoot: string, runId: string): string {
|
|
6
|
+
return join(repoRoot, ".ticket-runner", "runs", runId);
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Where a Stage's command line, stdout, stderr and transcript are written:
|
|
11
|
+
* one directory per Run, per Ticket, under the gitignored run directory.
|
|
12
|
+
*/
|
|
13
|
+
export function stageLogDir(repoRoot: string, runId: string, ticket: number): string {
|
|
14
|
+
return join(runLogDir(repoRoot, runId), String(ticket));
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Where the fix Stage and the pass it bought write instead.
|
|
19
|
+
*
|
|
20
|
+
* A Stage's files are named after the Stage and emptied when it starts, so a
|
|
21
|
+
* second verify would overwrite the Verdict that spent the fix budget — which
|
|
22
|
+
* is the transcript a human most needs when the Ticket is handed off anyway.
|
|
23
|
+
*/
|
|
24
|
+
export function retryLogDir(repoRoot: string, runId: string, ticket: number): string {
|
|
25
|
+
return join(stageLogDir(repoRoot, runId, ticket), "retry");
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** The file naming the Version, at the top of a Run's transcripts. */
|
|
29
|
+
export const VERSION_FILE = "version.txt";
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Say which Version this Run is, beside the transcripts it is about to write.
|
|
33
|
+
*
|
|
34
|
+
* Written before the first Stage, so a transcript always sits beside the
|
|
35
|
+
* pipeline that wrote it: the Run summary names the Version too, but that is a
|
|
36
|
+
* terminal the night is over for, and these files outlive it (ADR-0007).
|
|
37
|
+
*/
|
|
38
|
+
export function writeRunVersion(repoRoot: string, runId: string, version: string): void {
|
|
39
|
+
const directory = runLogDir(repoRoot, runId);
|
|
40
|
+
mkdirSync(directory, { recursive: true });
|
|
41
|
+
writeFileSync(join(directory, VERSION_FILE), `${version}\n`);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* What of a Stage's files a hand-off keeps: its command line, to reproduce it
|
|
46
|
+
* by hand, and its transcript, to read why it did what it did. Its stdout is
|
|
47
|
+
* what the transcript was parsed out of, and its stderr is the CLI's own.
|
|
48
|
+
*/
|
|
49
|
+
const KEPT_SUFFIXES = [".command", ".transcript.jsonl"];
|
|
50
|
+
|
|
51
|
+
/** One file a hand-off keeps: its name under the Ticket's, and where it is on disk. */
|
|
52
|
+
export interface TranscriptFile {
|
|
53
|
+
/** `/`-separated, whatever the platform, since it names a file on a git branch. */
|
|
54
|
+
name: string;
|
|
55
|
+
path: string;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* The files Run `runId` wrote for `ticket` that a hand-off keeps, in name
|
|
60
|
+
* order: every Stage's command line and transcript, the retries' in `retry/`,
|
|
61
|
+
* and the Version the Run was, so they still name the pipeline that wrote them
|
|
62
|
+
* once they are somewhere else. None when the Run wrote nothing for the Ticket.
|
|
63
|
+
*/
|
|
64
|
+
export function transcriptFiles(
|
|
65
|
+
repoRoot: string,
|
|
66
|
+
runId: string,
|
|
67
|
+
ticket: number,
|
|
68
|
+
): TranscriptFile[] {
|
|
69
|
+
const directory = stageLogDir(repoRoot, runId, ticket);
|
|
70
|
+
if (!existsSync(directory)) return [];
|
|
71
|
+
|
|
72
|
+
const stages = readdirSync(directory, { recursive: true, encoding: "utf8" })
|
|
73
|
+
.filter((name) => KEPT_SUFFIXES.some((suffix) => name.endsWith(suffix)))
|
|
74
|
+
.map((name) => ({ name: name.split(sep).join("/"), path: join(directory, name) }));
|
|
75
|
+
if (stages.length === 0) return [];
|
|
76
|
+
|
|
77
|
+
const version = join(runLogDir(repoRoot, runId), VERSION_FILE);
|
|
78
|
+
const files = existsSync(version) ? [...stages, { name: VERSION_FILE, path: version }] : stages;
|
|
79
|
+
return files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** A run id that sorts chronologically and is safe in a path. */
|
|
83
|
+
export function newRunId(now: Date = new Date()): string {
|
|
84
|
+
return now.toISOString().replace(/[:.]/g, "-").replace("Z", "");
|
|
85
|
+
}
|
package/src/run.ts
ADDED
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
import { branchName } from "./branch.js";
|
|
2
|
+
import { selectFrontier } from "./frontier.js";
|
|
3
|
+
import { type Refusal, isGuardReason, skipReason } from "./guards.js";
|
|
4
|
+
import type { RoutedNote } from "./notes.js";
|
|
5
|
+
import { type Pipeline, type TicketOutcome, processTicket } from "./orchestrator.js";
|
|
6
|
+
import { StopSignal, stopLine } from "./stop.js";
|
|
7
|
+
import { holdsClaim, strandedTickets } from "./stranded.js";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* What a Run has to show for itself: every Ticket it took, in the order they
|
|
11
|
+
* ended, and why it stopped taking them.
|
|
12
|
+
*
|
|
13
|
+
* The order is completion rather than claim because Lanes run side by side: two
|
|
14
|
+
* Tickets claimed in the same breath finish whenever their own Stages let them,
|
|
15
|
+
* and the summary reads as the night happened rather than as it was planned.
|
|
16
|
+
*/
|
|
17
|
+
export interface RunResult {
|
|
18
|
+
outcomes: TicketOutcome[];
|
|
19
|
+
stop: RunStop;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Why a Run ended.
|
|
24
|
+
*
|
|
25
|
+
* A Run that drained the Frontier carries what was left held back; one the rate
|
|
26
|
+
* limit stopped carries nothing, because it ended before it could say a
|
|
27
|
+
* candidate was held back all Run; one a human stopped carries the moment it
|
|
28
|
+
* was asked and what it still had in hand. That is why this is a choice rather
|
|
29
|
+
* than a flag beside the list: the three stops do not report the same things.
|
|
30
|
+
*/
|
|
31
|
+
export type RunStop =
|
|
32
|
+
| {
|
|
33
|
+
reason: "frontier";
|
|
34
|
+
/**
|
|
35
|
+
* Candidates still held back by an open blocker when the Run ended: of
|
|
36
|
+
* a narrowed Run, only the ones it was given, whatever blocks them.
|
|
37
|
+
*/
|
|
38
|
+
blocked: number[];
|
|
39
|
+
}
|
|
40
|
+
| { reason: "rate-limited" }
|
|
41
|
+
| {
|
|
42
|
+
reason: "stopped";
|
|
43
|
+
/** When the Stop reached the Run, ISO-8601. */
|
|
44
|
+
at: string;
|
|
45
|
+
/** The Tickets its Lanes were holding at that moment, ascending. */
|
|
46
|
+
busy: number[];
|
|
47
|
+
};
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Drain the Frontier through the Lanes the Target's config gives the Run.
|
|
51
|
+
*
|
|
52
|
+
* Every free Lane is filled at once, and a Lane is filled again the moment the
|
|
53
|
+
* Ticket in it ends — merged, handed off or released. The Frontier is recomputed
|
|
54
|
+
* at every refill rather than snapshotted, so a merge that closes a blocker puts
|
|
55
|
+
* the Ticket it unblocked into the same Run, and a Ticket another Lane is still
|
|
56
|
+
* working is still an open blocker. Those edges are the whole of what keeps two
|
|
57
|
+
* Tickets apart: no heuristic here decides which are safe together.
|
|
58
|
+
*
|
|
59
|
+
* A Ticket that fails is handed off and the Lane moves on: one bad Ticket must
|
|
60
|
+
* not cost the rest of the night.
|
|
61
|
+
*
|
|
62
|
+
* A Release stops the Run filling Lanes and nothing more. Nothing was wrong with
|
|
63
|
+
* the Ticket — the subscription ran out of room — so the next one would be
|
|
64
|
+
* stopped by the same limit, and claiming it would spend a Claim, a worktree and
|
|
65
|
+
* a doomed Stage to learn what the first one already said. The Lanes still busy
|
|
66
|
+
* finish what they hold, and the Run reports the limit once the last of them
|
|
67
|
+
* comes back.
|
|
68
|
+
*
|
|
69
|
+
* A Stop is the same shape with a different reason: a human asked for no more
|
|
70
|
+
* Tickets rather than the subscription, so the Lanes busy at that moment finish
|
|
71
|
+
* what they hold and the Run takes nothing else — not off the Frontier and not
|
|
72
|
+
* off the Stranded Tickets, which is what makes a stopped Run leave none of its
|
|
73
|
+
* own behind where a killed one leaves all of them (ADR-0006).
|
|
74
|
+
*
|
|
75
|
+
* Before any of that, the Tickets a Run that never came back left claimed are
|
|
76
|
+
* resumed. They are not on the Frontier and never will be — the Claim they still
|
|
77
|
+
* wear is what keeps them off it — so this sweep is the only thing that ever
|
|
78
|
+
* picks them up again, and a free Lane takes one before it takes anything the
|
|
79
|
+
* Frontier is offering.
|
|
80
|
+
*
|
|
81
|
+
* A Run given `tickets` is that Run narrowed to them, and nothing else about it
|
|
82
|
+
* changes: the sweep and every refill see only those Tickets, and every other
|
|
83
|
+
* one, stranded or on the Frontier, is left as it was for the next Run. One of
|
|
84
|
+
* them the Run never met — nobody's to take, or no issue at all — is reported
|
|
85
|
+
* as skipped once the Lanes are back, so none of them drops out of the summary.
|
|
86
|
+
*/
|
|
87
|
+
export async function processRun(
|
|
88
|
+
pipeline: Pipeline,
|
|
89
|
+
stopping: StopSignal = new StopSignal(),
|
|
90
|
+
tickets?: readonly number[],
|
|
91
|
+
): Promise<RunResult> {
|
|
92
|
+
const { tracker, config } = pipeline;
|
|
93
|
+
const named = tickets === undefined ? undefined : new Set(tickets);
|
|
94
|
+
|
|
95
|
+
const outcomes: TicketOutcome[] = [];
|
|
96
|
+
// Every Ticket this Run has taken. A Ticket normally leaves the candidate
|
|
97
|
+
// list by being closed or relabelled; this is what stops a Run offering one
|
|
98
|
+
// to a second Lane, whether because that write did not land or because the
|
|
99
|
+
// Claim of the Lane holding it has not reached GitHub yet.
|
|
100
|
+
const taken = new Set<number>();
|
|
101
|
+
// The Lanes with a Ticket in them, by Ticket number. A Lane takes itself out
|
|
102
|
+
// of here as its Ticket ends rather than where the Run waits, so a fill pass
|
|
103
|
+
// that several Lanes came back during sees every one of them free.
|
|
104
|
+
const busy = new Map<number, Promise<void>>();
|
|
105
|
+
// What the last Frontier this Run computed held back, which is what a Run
|
|
106
|
+
// that drained the Frontier reports. Replaced at every refill: a candidate a
|
|
107
|
+
// Lane unblocked on the way is not one the Run was still held up by.
|
|
108
|
+
let blocked: number[] = [];
|
|
109
|
+
// Why this Run stopped, which is also what it reports. Set by whichever of
|
|
110
|
+
// the Release and the Stop came first and never overwritten: a Stop that
|
|
111
|
+
// arrives after a Release asked for what was already happening, and a Release
|
|
112
|
+
// afterwards stopped nothing that was not stopped already. Undefined is a Run
|
|
113
|
+
// still taking Tickets, which is why it doubles as the guard at every refill.
|
|
114
|
+
let runStop: RunStop | undefined;
|
|
115
|
+
// A Frontier the tracker refused to list, kept until the Lanes still busy are
|
|
116
|
+
// back. A Run must not walk away from a Ticket mid-Stage to report that `gh`
|
|
117
|
+
// went down, so the error waits for them and is thrown where a Run with one
|
|
118
|
+
// Lane threw it: out of the Run, with nothing else left running.
|
|
119
|
+
let listing: unknown;
|
|
120
|
+
|
|
121
|
+
// Registered before the sweep, because a Stop that arrives during it is a Run
|
|
122
|
+
// that claims nothing at all: the Lanes are empty, so there is nothing to
|
|
123
|
+
// finish and nothing to report but the request itself.
|
|
124
|
+
stopping.watch(({ at }) => {
|
|
125
|
+
const held = [...busy.keys()].sort((first, second) => first - second);
|
|
126
|
+
pipeline.log?.(stopLine(held));
|
|
127
|
+
runStop ??= { reason: "stopped", at, busy: held };
|
|
128
|
+
});
|
|
129
|
+
|
|
130
|
+
// Taken off the front as Lanes free, so the sweep is a queue rather than a
|
|
131
|
+
// pass of its own: a stranded Ticket and a Frontier Ticket can be in two
|
|
132
|
+
// Lanes at once, and neither waits for the other's kind to run out.
|
|
133
|
+
const stranded = await strandedTickets({
|
|
134
|
+
tracker,
|
|
135
|
+
workspace: pipeline.workspace,
|
|
136
|
+
inProgress: config.labels.inProgress,
|
|
137
|
+
...(named === undefined ? {} : { only: named }),
|
|
138
|
+
...(pipeline.log === undefined ? {} : { log: pipeline.log }),
|
|
139
|
+
});
|
|
140
|
+
|
|
141
|
+
/** Whether the Run has a Lane to put a Ticket in right now. */
|
|
142
|
+
function laneFree(): boolean {
|
|
143
|
+
return busy.size < config.lanes;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* Put a Ticket in a Lane, and record what came back when it ends.
|
|
148
|
+
*
|
|
149
|
+
* The line about the Run stopping is logged by the Release that stopped it and
|
|
150
|
+
* by no other. The Ticket's own release is already logged where it happened;
|
|
151
|
+
* this says the Run goes no further, so a transcript shows the Frontier was
|
|
152
|
+
* left alone rather than found empty, and a Release into a Run that an earlier
|
|
153
|
+
* Release or a Stop had stopped already claims to have stopped nothing. It
|
|
154
|
+
* leads with the Ticket's number all the same: a transcript of interleaved
|
|
155
|
+
* Lanes must not lose the line that explains why one Lane was the last to be
|
|
156
|
+
* filled.
|
|
157
|
+
*/
|
|
158
|
+
function fillLane(ticket: Taken): void {
|
|
159
|
+
taken.add(ticket.number);
|
|
160
|
+
busy.set(
|
|
161
|
+
ticket.number,
|
|
162
|
+
take(pipeline, ticket).then((outcome) => {
|
|
163
|
+
busy.delete(ticket.number);
|
|
164
|
+
outcomes.push(outcome);
|
|
165
|
+
if (outcome.outcome === "released" && runStop === undefined) {
|
|
166
|
+
runStop = { reason: "rate-limited" };
|
|
167
|
+
pipeline.log?.(`#${outcome.ticket} stopped the Run · rate limit`);
|
|
168
|
+
}
|
|
169
|
+
}),
|
|
170
|
+
);
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** Fill every free Lane: the stranded Tickets first, the Frontier second. */
|
|
174
|
+
async function fillLanes(): Promise<void> {
|
|
175
|
+
while (laneFree()) {
|
|
176
|
+
const resumable = stranded.shift();
|
|
177
|
+
if (resumable === undefined) break;
|
|
178
|
+
fillLane(resumable);
|
|
179
|
+
}
|
|
180
|
+
// Asked for only when a Lane is still free, so a Run whose Lanes are full of
|
|
181
|
+
// stranded Tickets spends no call on a Frontier it could not take from.
|
|
182
|
+
if (!laneFree()) return;
|
|
183
|
+
|
|
184
|
+
const candidates = await tracker.listCandidates(config.labels.readyForAgent);
|
|
185
|
+
const selection = selectFrontier(
|
|
186
|
+
named === undefined ? candidates : candidates.filter(({ number }) => named.has(number)),
|
|
187
|
+
);
|
|
188
|
+
blocked = selection.blocked.map((candidate) => candidate.number);
|
|
189
|
+
// Asked again after the listing, because a Lane that came back while it was
|
|
190
|
+
// in flight may have been released, and a Stop may have arrived: the Run
|
|
191
|
+
// fills no Lane after either, and this selection is one it already had no
|
|
192
|
+
// business taking from.
|
|
193
|
+
if (runStop !== undefined) return;
|
|
194
|
+
|
|
195
|
+
for (const candidate of selection.frontier) {
|
|
196
|
+
if (!laneFree()) break;
|
|
197
|
+
if (taken.has(candidate.number)) continue;
|
|
198
|
+
fillLane({
|
|
199
|
+
number: candidate.number,
|
|
200
|
+
title: candidate.title,
|
|
201
|
+
branch: branchName(candidate.number, candidate.title),
|
|
202
|
+
});
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
for (;;) {
|
|
207
|
+
if (runStop === undefined && listing === undefined) {
|
|
208
|
+
try {
|
|
209
|
+
await fillLanes();
|
|
210
|
+
} catch (error) {
|
|
211
|
+
listing = error;
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
// Never while a Lane is busy, whatever the Frontier had to offer: that Lane
|
|
215
|
+
// may be about to close the blocker the rest of the Frontier is waiting on.
|
|
216
|
+
if (busy.size === 0) break;
|
|
217
|
+
await Promise.race(busy.values());
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
if (listing !== undefined) throw listing;
|
|
221
|
+
const stop = runStop ?? { reason: "frontier", blocked };
|
|
222
|
+
if (named !== undefined) {
|
|
223
|
+
const stillBlocked = stop.reason === "frontier" ? stop.blocked : [];
|
|
224
|
+
for (const ticket of named) {
|
|
225
|
+
if (taken.has(ticket) || stillBlocked.includes(ticket)) continue;
|
|
226
|
+
const skipped = await neverMet(pipeline, ticket);
|
|
227
|
+
if (skipped !== undefined) outcomes.push(skipped);
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
return { outcomes, stop };
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/**
|
|
234
|
+
* A Ticket a narrowed Run was given and never met, as the row that says why.
|
|
235
|
+
*
|
|
236
|
+
* Neither source offered it, so it is nobody's to take — somebody else holds
|
|
237
|
+
* it, it was never offered or has closed — or it is no issue at all. It is
|
|
238
|
+
* asked about only now, when the Run is over, and passed over in silence: a
|
|
239
|
+
* warning is for a Planning defect, and a Ticket a guard could have refused was
|
|
240
|
+
* on the Frontier, where the guard already had its say.
|
|
241
|
+
*
|
|
242
|
+
* Nothing comes back for one the Run could still have taken, which a Stop or a
|
|
243
|
+
* Release kept it from, or for one the tracker would not answer about: the Run
|
|
244
|
+
* has no reason to give for either, and the last line says why it stopped.
|
|
245
|
+
*/
|
|
246
|
+
async function neverMet(pipeline: Pipeline, ticket: number): Promise<Skipped | undefined> {
|
|
247
|
+
let skipped: Skipped | undefined;
|
|
248
|
+
try {
|
|
249
|
+
skipped = await nobodysToTake(pipeline, ticket);
|
|
250
|
+
} catch (error) {
|
|
251
|
+
pipeline.log?.(`#${ticket} was never met, and reading it failed: ${(error as Error).message}`);
|
|
252
|
+
return undefined;
|
|
253
|
+
}
|
|
254
|
+
if (skipped !== undefined) pipeline.log?.(`#${ticket} skipped · ${skipped.reason}`);
|
|
255
|
+
return skipped;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/** The row a Ticket passed over earns. */
|
|
259
|
+
type Skipped = Extract<TicketOutcome, { outcome: "skipped" }>;
|
|
260
|
+
|
|
261
|
+
/** `ticket` skipped for why it is nobody's to take, or nothing where it is somebody's. */
|
|
262
|
+
async function nobodysToTake(pipeline: Pipeline, ticket: number): Promise<Skipped | undefined> {
|
|
263
|
+
const { tracker, workspace, config } = pipeline;
|
|
264
|
+
const skipped = (reason: Refusal, title?: string): Skipped => ({
|
|
265
|
+
outcome: "skipped",
|
|
266
|
+
ticket,
|
|
267
|
+
...(title === undefined ? {} : { title }),
|
|
268
|
+
reason,
|
|
269
|
+
});
|
|
270
|
+
|
|
271
|
+
const kind = await tracker.numberKind(ticket);
|
|
272
|
+
if (kind === "nothing") return skipped("no-issue");
|
|
273
|
+
if (kind === "pull-request") return skipped("pull-request");
|
|
274
|
+
|
|
275
|
+
const issue = await tracker.getIssue(ticket);
|
|
276
|
+
// A closed issue is offered to nobody, whatever labels it kept.
|
|
277
|
+
if (issue.closed) return skipped("not-ready", issue.title);
|
|
278
|
+
// Read as the Run's own guards read it, so a Stranded Ticket the Run never
|
|
279
|
+
// got to is not reported as somebody else's.
|
|
280
|
+
const stranded =
|
|
281
|
+
(await workspace.readState(ticket)) !== undefined &&
|
|
282
|
+
holdsClaim(issue, await tracker.currentUser(), config.labels.inProgress);
|
|
283
|
+
const reason = skipReason(issue, config.labels.readyForAgent, stranded);
|
|
284
|
+
if (reason === undefined || isGuardReason(reason)) return undefined;
|
|
285
|
+
return skipped(reason, issue.title);
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
/**
|
|
289
|
+
* One Ticket, and never an exception.
|
|
290
|
+
*
|
|
291
|
+
* {@link processTicket} hands off everything it can, but its claim and its own
|
|
292
|
+
* hand-off writes are outside that net: a tracker that goes down mid-Ticket
|
|
293
|
+
* would otherwise take the whole Run with it. The Ticket is reported as handed
|
|
294
|
+
* off — which, without the label, is what a human will find on the board.
|
|
295
|
+
*/
|
|
296
|
+
async function take(pipeline: Pipeline, ticket: Taken): Promise<TicketOutcome> {
|
|
297
|
+
// Handed to the Ticket rather than read off its outcome, because there is no
|
|
298
|
+
// outcome on this path: a Note already on GitHub has to reach the summary
|
|
299
|
+
// whether or not the Ticket that made it came back.
|
|
300
|
+
const notes: RoutedNote[] = [];
|
|
301
|
+
try {
|
|
302
|
+
return await processTicket(pipeline, ticket.number, notes);
|
|
303
|
+
} catch (error) {
|
|
304
|
+
const failure = (error as Error).message;
|
|
305
|
+
pipeline.log?.(`#${ticket.number} failed outside the hand-off path: ${failure}`);
|
|
306
|
+
return {
|
|
307
|
+
outcome: "handed-off",
|
|
308
|
+
ticket: ticket.number,
|
|
309
|
+
title: ticket.title,
|
|
310
|
+
branch: ticket.branch,
|
|
311
|
+
stage: "setup",
|
|
312
|
+
failure,
|
|
313
|
+
notes,
|
|
314
|
+
};
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* One Ticket a Run is about to take, named well enough to report on it when
|
|
320
|
+
* nothing comes back.
|
|
321
|
+
*
|
|
322
|
+
* The branch is carried rather than derived, because the two ways a Run reaches
|
|
323
|
+
* a Ticket know it differently: a candidate off the Frontier has whatever its
|
|
324
|
+
* title derives to, and a stranded Ticket has the branch its State file names —
|
|
325
|
+
* which is where the work actually is, whatever the title says now.
|
|
326
|
+
*/
|
|
327
|
+
interface Taken {
|
|
328
|
+
number: number;
|
|
329
|
+
title: string;
|
|
330
|
+
branch: string;
|
|
331
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether a Run's Target is the pipeline's own repository.
|
|
3
|
+
*
|
|
4
|
+
* Only there is the checkout a Stage stands in the pipeline itself, with tests
|
|
5
|
+
* and fakes to exercise it through and spellings of its commands that name no
|
|
6
|
+
* installed `ticket-runner` (`prompts.ts`). The pipeline decides this rather
|
|
7
|
+
* than leaving a Stage to judge it from the files around it, and it decides it
|
|
8
|
+
* once per Run, before the first Ticket.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import type { Tracker } from "./ports/tracker.js";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* True where the Target's GitHub repository is `pipeline`, the pipeline's own
|
|
15
|
+
* as its package names it, and false wherever either side cannot be read.
|
|
16
|
+
*
|
|
17
|
+
* GitHub reads `owner/name` without regard to case, so this does too. Nothing
|
|
18
|
+
* here may stop a Run: a tracker that fails is a Target that is not the
|
|
19
|
+
* pipeline's own, which gives its Stages the guidance that holds anywhere.
|
|
20
|
+
*/
|
|
21
|
+
export async function isPipelineRepository(
|
|
22
|
+
tracker: Tracker,
|
|
23
|
+
pipeline: string | undefined,
|
|
24
|
+
): Promise<boolean> {
|
|
25
|
+
if (pipeline === undefined) return false;
|
|
26
|
+
let target: string | undefined;
|
|
27
|
+
try {
|
|
28
|
+
target = await tracker.repository();
|
|
29
|
+
} catch {
|
|
30
|
+
return false;
|
|
31
|
+
}
|
|
32
|
+
return target !== undefined && target.toLowerCase() === pipeline.toLowerCase();
|
|
33
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Stage boundary: a Stage session may not run the pipeline that started it.
|
|
3
|
+
*
|
|
4
|
+
* Every Stage the AgentRunner starts carries the Stage mark, an environment
|
|
5
|
+
* variable the child inherits, and the CLI refuses to do anything while it is
|
|
6
|
+
* present. It is a tripwire against an honest mistake, not a sandbox — a
|
|
7
|
+
* session that unsets the variable still gets through. The prompt guidance in
|
|
8
|
+
* `prompts.ts` is what covers intent.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
/** The Stage mark: set by the AgentRunner to the name of the Stage it starts. */
|
|
12
|
+
export const STAGE_ENV_VAR = "TICKET_RUNNER_STAGE";
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Why this invocation must not start, when the shell carries the Stage mark.
|
|
16
|
+
* Takes the environment so the refusal can be tested without `process.env`.
|
|
17
|
+
*/
|
|
18
|
+
export function nestedRunRefusal(env: Record<string, string | undefined>): string | undefined {
|
|
19
|
+
const mark = env[STAGE_ENV_VAR];
|
|
20
|
+
if (mark === undefined) return undefined;
|
|
21
|
+
|
|
22
|
+
// A blanked mark is still a mark; only an unset variable is a human's shell.
|
|
23
|
+
const stage = mark.trim() === "" ? undefined : mark.trim();
|
|
24
|
+
return [
|
|
25
|
+
`Refusing to start: ${STAGE_ENV_VAR} is set${stage === undefined ? "" : ` to \`${stage}\``},`,
|
|
26
|
+
`so this shell belongs to ${stage === undefined ? "a" : `the ${stage}`} Stage of a Run`,
|
|
27
|
+
"that is already in progress.",
|
|
28
|
+
"A Stage may not run the pipeline: doing so claims a Ticket on the live tracker,",
|
|
29
|
+
"creates a second worktree and starts a nested Run.",
|
|
30
|
+
"Leave the pipeline to the Run that started this shell, and carry on with the Stage's own work.",
|
|
31
|
+
].join(" ");
|
|
32
|
+
}
|