ticket-runner 0.6.2 → 0.6.4
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/README.ko.md +20 -14
- package/README.md +13 -7
- package/docs/templates/operator-skill.md +1 -0
- package/package.json +1 -1
- package/src/adapters/claude-agent-runner.ts +149 -14
- package/src/adapters/exec.ts +18 -1
- package/src/adapters/git-workspace.ts +10 -1
- package/src/command-line.ts +18 -1
- package/src/config.ts +3 -2
- package/src/conventions.ts +3 -3
- package/src/credential.ts +159 -0
- package/src/orchestrator.ts +103 -20
- package/src/ports/agent-runner.ts +40 -4
- package/src/ports/workspace.ts +14 -0
- package/src/prompts.ts +7 -1
- package/src/readiness.ts +67 -11
- package/src/run.ts +107 -26
- package/src/start.ts +52 -13
- package/src/templates.ts +84 -15
- package/src/timer.ts +25 -0
- package/src/title.ts +1 -1
package/README.ko.md
CHANGED
|
@@ -23,9 +23,11 @@ Acceptance Criteria 체크리스트가 달리고, blocker가 연결됩니다. **
|
|
|
23
23
|
5. rebase하고, pull request를 열고, CI를 기다린 뒤 squash merge합니다.
|
|
24
24
|
|
|
25
25
|
한 번 실패하면 고치는 세션 한 번과 두 번째 검사를 받습니다. 그래도 끝내지 못한 일은 사람에게 돌아옵니다.
|
|
26
|
-
`ready-for-human` 라벨과 draft pull request, 무엇이 실패했는지 적은 코멘트가 함께 남습니다.
|
|
27
|
-
|
|
28
|
-
|
|
26
|
+
`ready-for-human` 라벨과 draft pull request, 무엇이 실패했는지 적은 코멘트가 함께 남습니다.
|
|
27
|
+
세션은 Claude 요금제로 돌고, 셸이 export한 `ANTHROPIC_API_KEY`는 세션에 넘기지 않습니다. `run --api-key`로
|
|
28
|
+
시작하면 대신 그 키로 과금합니다. rate limit이나 일시적인 API 장애, 키의 크레딧 소진이나 사용 한도 도달로
|
|
29
|
+
멈춘 세션은 아무것도 잃지 않습니다. 이슈는 보드로 돌아가고, Run은 무엇이 멈췄는지와 알 수 있으면 한도가 풀리는
|
|
30
|
+
시각을 알려 주며, 다음 Run이 멈춘 곳부터 이어 합니다.
|
|
29
31
|
|
|
30
32
|
## 나에게 맞을까?
|
|
31
33
|
|
|
@@ -38,7 +40,7 @@ rate limit이나 일시적인 API 장애로 멈춘 세션은 아무것도 잃지
|
|
|
38
40
|
[`mattpocock-skills`](https://github.com/mattpocock/skills) 플러그인 1.2.3 이상 버전을 설치한 `claude`가
|
|
39
41
|
있습니다.
|
|
40
42
|
|
|
41
|
-
파이프라인은 묻지 않고
|
|
43
|
+
파이프라인은 묻지 않고 Base branch에 merge합니다. 그걸 원하는 저장소에 쓰세요.
|
|
42
44
|
|
|
43
45
|
## 써 보기
|
|
44
46
|
|
|
@@ -46,12 +48,15 @@ rate limit이나 일시적인 API 장애로 멈춘 세션은 아무것도 잃지
|
|
|
46
48
|
|
|
47
49
|
```bash
|
|
48
50
|
npx ticket-runner init # Target을 준비하고, 아직 빠진 것을 알려 줍니다
|
|
51
|
+
git add .gitignore CLAUDE.md ticket-runner.json docs/agents .claude/skills/ticket-runner
|
|
52
|
+
git commit -m "chore: set up ticket-runner" && git push
|
|
49
53
|
npx ticket-runner run # 준비된 이슈를 모두 처리합니다
|
|
50
54
|
```
|
|
51
55
|
|
|
52
56
|
`init`은 검토하고 commit할 파일 몇 개를 씁니다. `.gitignore` 줄, conventions 문서, `CLAUDE.md`의 한
|
|
53
57
|
섹션, Claude skill 하나입니다. 또 triage 라벨을 만들고, squash merge와 merge 시 branch 삭제를 켭니다.
|
|
54
|
-
commit은 하지 않습니다.
|
|
58
|
+
commit은 하지 않습니다. 세션은 이 파일들이 Base branch에 올라간 뒤에야 읽으므로, 첫 `run` 전에
|
|
59
|
+
push하세요.
|
|
55
60
|
|
|
56
61
|
계속 쓰려면 전역으로 설치하세요.
|
|
57
62
|
|
|
@@ -61,16 +66,17 @@ npm install -g ticket-runner
|
|
|
61
66
|
|
|
62
67
|
| 명령 | 하는 일 |
|
|
63
68
|
|---|---|
|
|
64
|
-
| `ticket-runner init` | 이 저장소를 준비하고, 사람이 고쳐야 할 것을 알려
|
|
65
|
-
| `ticket-runner run` | 준비된 이슈를 하나씩 모두
|
|
66
|
-
| `ticket-runner run 12 14` | 같은 일을 하되 #12와 #14만
|
|
67
|
-
| `ticket-runner run --lanes 2` | 이슈 두 개를 동시에
|
|
68
|
-
| `ticket-runner
|
|
69
|
-
| `ticket-runner
|
|
70
|
-
| `ticket-runner
|
|
69
|
+
| `ticket-runner init` | 이 저장소를 준비하고, 사람이 고쳐야 할 것을 알려 줍니다. |
|
|
70
|
+
| `ticket-runner run` | 준비된 이슈를 하나씩 모두 처리합니다. |
|
|
71
|
+
| `ticket-runner run 12 14` | 같은 일을 하되 #12와 #14만 맡습니다. |
|
|
72
|
+
| `ticket-runner run --lanes 2` | 이슈 두 개를 동시에 처리합니다. |
|
|
73
|
+
| `ticket-runner run --api-key` | 모든 세션을 Claude 요금제 대신 `ANTHROPIC_API_KEY`로 과금합니다. |
|
|
74
|
+
| `ticket-runner stop` | 진행 중인 Run에게 맡은 것만 끝내고 더 맡지 말라고 합니다. |
|
|
75
|
+
| `ticket-runner remove` | 이 저장소에서 파이프라인을 걷어 냅니다. |
|
|
76
|
+
| `ticket-runner -v` | Version을 출력합니다. |
|
|
71
77
|
|
|
72
78
|
Claude 앱에서도 Run을 시작할 수 있습니다. Target에서 Claude Code 클라우드 세션을 열고 "run it"이라고
|
|
73
|
-
말하면 됩니다.
|
|
79
|
+
말하면 됩니다. 클라우드 세션은 늘 요금제로 돌기 때문에 `--api-key`를 거절합니다.
|
|
74
80
|
|
|
75
81
|
## 다시 걷어 내기
|
|
76
82
|
|
|
@@ -91,7 +97,7 @@ npm uninstall -g ticket-runner # 전역 설치
|
|
|
91
97
|
- [실행하기](https://jjongs2.github.io/ticket-runner/ko/guide/running)
|
|
92
98
|
- [설정](https://jjongs2.github.io/ticket-runner/ko/guide/configuration)
|
|
93
99
|
- [Ticket 하나가 merge되기까지](https://jjongs2.github.io/ticket-runner/ko/guide/ticket-to-merge)
|
|
94
|
-
- [멈추고 이어 하기](https://jjongs2.github.io/ticket-runner/ko/guide/stopping-and-resuming)
|
|
100
|
+
- [Hand-off, 멈추고 이어 하기](https://jjongs2.github.io/ticket-runner/ko/guide/stopping-and-resuming)
|
|
95
101
|
- [내부 구조](https://jjongs2.github.io/ticket-runner/ko/guide/internals)
|
|
96
102
|
|
|
97
103
|
용어는 [`GLOSSARY.md`](https://github.com/jjongs2/ticket-runner/blob/main/GLOSSARY.md)에, 설계 결정은
|
package/README.md
CHANGED
|
@@ -24,9 +24,11 @@ every such issue whose blockers have closed, it:
|
|
|
24
24
|
|
|
25
25
|
One failure buys one fix session and a second pass. Anything it still cannot finish goes back
|
|
26
26
|
to you, labelled `ready-for-human`, with a draft pull request and a comment saying what failed.
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
27
|
+
Sessions run on your Claude plan, and an `ANTHROPIC_API_KEY` your shell exports is kept from
|
|
28
|
+
them; `run --api-key` bills them to that key instead. A session stopped by the rate limit, by the
|
|
29
|
+
API failing on its side, or by the key running out of credit or into its spend limit costs
|
|
30
|
+
nothing: the issue goes back on the board, the Run says what stopped it, and when the limit
|
|
31
|
+
resets where it can, and the next Run carries on from where it stopped.
|
|
30
32
|
|
|
31
33
|
## Is it for you?
|
|
32
34
|
|
|
@@ -40,7 +42,7 @@ It fits a repository where:
|
|
|
40
42
|
[`gh`](https://cli.github.com/), and `claude` with the
|
|
41
43
|
[`mattpocock-skills`](https://github.com/mattpocock/skills) plugin, version 1.2.3 or later
|
|
42
44
|
|
|
43
|
-
It merges to your
|
|
45
|
+
It merges to your Base branch without asking. It is for repositories where that is what you want.
|
|
44
46
|
|
|
45
47
|
## Try it
|
|
46
48
|
|
|
@@ -48,12 +50,15 @@ In the repository you want it to work in (the **Target**):
|
|
|
48
50
|
|
|
49
51
|
```bash
|
|
50
52
|
npx ticket-runner init # set the Target up and report what is still missing
|
|
53
|
+
git add .gitignore CLAUDE.md ticket-runner.json docs/agents .claude/skills/ticket-runner
|
|
54
|
+
git commit -m "chore: set up ticket-runner" && git push
|
|
51
55
|
npx ticket-runner run # work through every ready issue
|
|
52
56
|
```
|
|
53
57
|
|
|
54
58
|
`init` writes a few files for you to review and commit: `.gitignore` lines, a conventions
|
|
55
59
|
document, a section in `CLAUDE.md` and a Claude skill. It also creates the triage labels and
|
|
56
|
-
turns on squash merging and branch deletion on merge. It commits nothing
|
|
60
|
+
turns on squash merging and branch deletion on merge. It commits nothing, and a session reads
|
|
61
|
+
those files only once they are on your Base branch, so push them before the first `run`.
|
|
57
62
|
|
|
58
63
|
To keep it, install it globally:
|
|
59
64
|
|
|
@@ -67,12 +72,13 @@ npm install -g ticket-runner
|
|
|
67
72
|
| `ticket-runner run` | Work through every ready issue, one at a time |
|
|
68
73
|
| `ticket-runner run 12 14` | The same, taking only #12 and #14 |
|
|
69
74
|
| `ticket-runner run --lanes 2` | Two issues at once |
|
|
75
|
+
| `ticket-runner run --api-key` | Bill every session to your `ANTHROPIC_API_KEY`, not your Claude plan |
|
|
70
76
|
| `ticket-runner stop` | Ask the Run in progress to finish what it holds and take no more |
|
|
71
77
|
| `ticket-runner remove` | Take the pipeline out of this repository |
|
|
72
78
|
| `ticket-runner -v` | Print the Version |
|
|
73
79
|
|
|
74
80
|
A Run can also be started from the Claude app, in a Claude Code cloud session on the Target:
|
|
75
|
-
say "run it".
|
|
81
|
+
say "run it". A cloud session always runs on your plan, so it refuses `--api-key`.
|
|
76
82
|
|
|
77
83
|
## Take it out again
|
|
78
84
|
|
|
@@ -94,7 +100,7 @@ The [project wiki](https://jjongs2.github.io/ticket-runner/) explains the pipeli
|
|
|
94
100
|
- [Running](https://jjongs2.github.io/ticket-runner/guide/running)
|
|
95
101
|
- [Configuration](https://jjongs2.github.io/ticket-runner/guide/configuration)
|
|
96
102
|
- [From Ticket to merge](https://jjongs2.github.io/ticket-runner/guide/ticket-to-merge)
|
|
97
|
-
- [
|
|
103
|
+
- [Hand-offs, stopping and resuming](https://jjongs2.github.io/ticket-runner/guide/stopping-and-resuming)
|
|
98
104
|
- [Internals](https://jjongs2.github.io/ticket-runner/guide/internals)
|
|
99
105
|
|
|
100
106
|
The vocabulary is defined in [`GLOSSARY.md`](https://github.com/jjongs2/ticket-runner/blob/main/GLOSSARY.md), the decisions in
|
|
@@ -48,6 +48,7 @@ Start what the human asked for as a background command, so the session stays fre
|
|
|
48
48
|
- `ticket-runner run` to work through every Ticket that is ready.
|
|
49
49
|
- `ticket-runner run <n>...` when the human names Tickets, one number each. The Run takes only those, lowest number first whatever order they were named in, and leaves every other Ticket alone.
|
|
50
50
|
- `ticket-runner run --lanes <count>` when the human asks for a number of Tickets at once, with or without numbers. Pass it only when they do; otherwise the repository's own config decides.
|
|
51
|
+
- `ticket-runner run --api-key` when the human asks for the Run to bill their API key rather than their Claude plan, beside numbers or `--lanes` or without. Pass it only when they do. Tell them an API-key Run needs a workstation Host: a cloud Host refuses it, because a cloud session runs every Stage on the subscription whatever key it exports.
|
|
51
52
|
|
|
52
53
|
Start one at a time. While a Run of yours is running, start no other.
|
|
53
54
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { randomUUID } from "node:crypto";
|
|
2
2
|
import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
|
|
3
3
|
import { join } from "node:path";
|
|
4
|
+
import { API_KEY_ENV_VAR, type Credential } from "../credential.js";
|
|
4
5
|
import {
|
|
5
6
|
type AgentPreflight,
|
|
6
7
|
type AgentRunner,
|
|
@@ -62,6 +63,11 @@ interface ResultEvent {
|
|
|
62
63
|
subtype?: string;
|
|
63
64
|
is_error?: boolean;
|
|
64
65
|
num_turns?: number;
|
|
66
|
+
/**
|
|
67
|
+
* What the CLI priced the whole session at so far, in dollars. Unlike
|
|
68
|
+
* `num_turns`, it is the session's on every waking, not the waking's.
|
|
69
|
+
*/
|
|
70
|
+
total_cost_usd?: unknown;
|
|
65
71
|
result?: unknown;
|
|
66
72
|
structured_output?: unknown;
|
|
67
73
|
/**
|
|
@@ -76,14 +82,27 @@ interface ResultEvent {
|
|
|
76
82
|
api_error_status?: number | null;
|
|
77
83
|
}
|
|
78
84
|
|
|
85
|
+
/**
|
|
86
|
+
* The `system/init` event a stream-json run opens with, as far as we rely on
|
|
87
|
+
* it: what the session says it is billed to.
|
|
88
|
+
*/
|
|
89
|
+
interface InitEvent {
|
|
90
|
+
type: "system";
|
|
91
|
+
subtype?: string;
|
|
92
|
+
apiKeySource?: unknown;
|
|
93
|
+
}
|
|
94
|
+
|
|
79
95
|
/**
|
|
80
96
|
* A `rate_limit_event` of a stream-json run: the CLI's own word on where the
|
|
81
97
|
* subscription stands, printed as each request's answer comes back.
|
|
82
98
|
*/
|
|
83
99
|
interface RateLimitEvent {
|
|
84
100
|
type: "rate_limit_event";
|
|
85
|
-
/**
|
|
86
|
-
|
|
101
|
+
/**
|
|
102
|
+
* `resetsAt` is when the limit resets, in seconds since the epoch, and
|
|
103
|
+
* `isUsingOverage` whether the request ran on the plan's extra usage.
|
|
104
|
+
*/
|
|
105
|
+
rate_limit_info?: { status?: string; resetsAt?: number; isUsingOverage?: unknown };
|
|
87
106
|
}
|
|
88
107
|
|
|
89
108
|
/**
|
|
@@ -141,6 +160,7 @@ export class ClaudeAgentRunner implements AgentRunner {
|
|
|
141
160
|
cwd: request.cwd,
|
|
142
161
|
timeoutMs: request.maxMinutes * 60_000,
|
|
143
162
|
extraEnv: env,
|
|
163
|
+
...(request.credential === "subscription" ? { unsetEnv: [API_KEY_ENV_VAR] } : {}),
|
|
144
164
|
mark: session,
|
|
145
165
|
onStdout: log.appendStdout,
|
|
146
166
|
onStderr: log.appendStderr,
|
|
@@ -154,12 +174,12 @@ export class ClaudeAgentRunner implements AgentRunner {
|
|
|
154
174
|
const args = buildArgs(request);
|
|
155
175
|
const session = { name: SESSION_ENV_VAR, value: randomUUID() };
|
|
156
176
|
const env = this.stageEnv(request, session);
|
|
157
|
-
const commandLine = quoteCommand(env, this.binary, args);
|
|
177
|
+
const commandLine = quoteCommand(request.credential, env, this.binary, args);
|
|
158
178
|
const startedAt = Date.now();
|
|
159
179
|
|
|
160
180
|
// Started before the child, so a Run killed mid-Stage still leaves the
|
|
161
181
|
// command line and everything printed so far behind.
|
|
162
|
-
const log = startStageLog(request, commandLine);
|
|
182
|
+
const log = startStageLog(request, commandLine, process.env[API_KEY_ENV_VAR]);
|
|
163
183
|
const execution = await this.spawn(request, args, env, session, log);
|
|
164
184
|
|
|
165
185
|
const events = parseEvents(execution.stdout);
|
|
@@ -170,6 +190,8 @@ export class ClaudeAgentRunner implements AgentRunner {
|
|
|
170
190
|
const structured = request.jsonSchema === undefined ? undefined : structuredOutput(results);
|
|
171
191
|
const turns = countTurns(results);
|
|
172
192
|
const resetsAt = failure === "rate-limited" ? limitResetsAt(events) : undefined;
|
|
193
|
+
const apiKeySource = keySource(events);
|
|
194
|
+
const cost = sessionCost(execution, events);
|
|
173
195
|
|
|
174
196
|
return {
|
|
175
197
|
ok: failure === undefined,
|
|
@@ -179,6 +201,9 @@ export class ClaudeAgentRunner implements AgentRunner {
|
|
|
179
201
|
transcriptPath: log.transcriptPath,
|
|
180
202
|
...(turns === undefined ? {} : { turns }),
|
|
181
203
|
...(resetsAt === undefined ? {} : { limitResetsAt: resetsAt }),
|
|
204
|
+
...(apiKeySource === undefined ? {} : { apiKeySource }),
|
|
205
|
+
...cost,
|
|
206
|
+
...(events.some(usedExtraUsage) ? { extraUsage: true } : {}),
|
|
182
207
|
// The clock is the runner's own. A session that woke for a background
|
|
183
208
|
// agent reports one `duration_ms` per waking, and the time it spent
|
|
184
209
|
// waiting for that agent belongs to none of them.
|
|
@@ -213,6 +238,39 @@ function countTurns(results: ResultEvent[]): number | undefined {
|
|
|
213
238
|
return counted.reduce((sum, result) => sum + (result.num_turns ?? 0), 0);
|
|
214
239
|
}
|
|
215
240
|
|
|
241
|
+
/**
|
|
242
|
+
* What the CLI priced the session at: the latest figure a `result` event gave.
|
|
243
|
+
* Every waking repeats the session's running total, so the last one is the
|
|
244
|
+
* whole session and summing them would count the early turns again.
|
|
245
|
+
*
|
|
246
|
+
* The figure is only part of the session's where the session did not end on
|
|
247
|
+
* the event that gave it: anything printed after it, a later `result` event
|
|
248
|
+
* without a figure included, or a kill at the wall-clock limit, which can land
|
|
249
|
+
* while a background agent runs and prints nothing.
|
|
250
|
+
*/
|
|
251
|
+
function sessionCost(
|
|
252
|
+
execution: Execution,
|
|
253
|
+
events: unknown[],
|
|
254
|
+
): { costUsd?: number; costIncomplete?: true } {
|
|
255
|
+
const priced = events.findLastIndex(
|
|
256
|
+
(event) => isResultEvent(event) && isAmount(event.total_cost_usd),
|
|
257
|
+
);
|
|
258
|
+
if (priced === -1) return {};
|
|
259
|
+
const costUsd = (events[priced] as ResultEvent).total_cost_usd as number;
|
|
260
|
+
const incomplete = execution.timedOut || priced < events.length - 1;
|
|
261
|
+
return incomplete ? { costUsd, costIncomplete: true } : { costUsd };
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/** A figure a `result` event can be read for: a finite number. */
|
|
265
|
+
function isAmount(value: unknown): value is number {
|
|
266
|
+
return typeof value === "number" && Number.isFinite(value);
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/** A `rate_limit_event` saying the request ran on the plan's extra usage. */
|
|
270
|
+
function usedExtraUsage(event: unknown): boolean {
|
|
271
|
+
return isRateLimitEvent(event) && event.rate_limit_info?.isUsingOverage === true;
|
|
272
|
+
}
|
|
273
|
+
|
|
216
274
|
/** A session that could not even start still has to leave a trace behind. */
|
|
217
275
|
async function spawnFailure(error: unknown): Promise<Execution> {
|
|
218
276
|
const message = `ticket-runner could not start the Stage: ${(error as Error).message}\n`;
|
|
@@ -260,6 +318,13 @@ interface StageLog {
|
|
|
260
318
|
close: (execution: Execution, events: unknown[]) => void;
|
|
261
319
|
}
|
|
262
320
|
|
|
321
|
+
/**
|
|
322
|
+
* What stands in a Stage's files for the Host's API key, wherever the session
|
|
323
|
+
* printed it: an `--api-key` Stage that runs `env` would otherwise put the key
|
|
324
|
+
* in a transcript, which reaches the Target's remote with a hand-off.
|
|
325
|
+
*/
|
|
326
|
+
const REDACTED_KEY = `<${API_KEY_ENV_VAR}>`;
|
|
327
|
+
|
|
263
328
|
/**
|
|
264
329
|
* Put the Stage's command line on disk and empty its output files, before
|
|
265
330
|
* anything is spawned. Chunks are appended as they arrive rather than saved at
|
|
@@ -267,9 +332,16 @@ interface StageLog {
|
|
|
267
332
|
* alive to write them (#12). The transcript is the one derivation that has to
|
|
268
333
|
* wait: it is parsed out of the stdout the session has finished printing.
|
|
269
334
|
*/
|
|
270
|
-
function startStageLog(
|
|
335
|
+
function startStageLog(
|
|
336
|
+
request: StageRequest,
|
|
337
|
+
commandLine: string,
|
|
338
|
+
/** The Host's API key, whose value no file of the Stage may carry. */
|
|
339
|
+
key: string | undefined,
|
|
340
|
+
): StageLog {
|
|
271
341
|
mkdirSync(request.logDir, { recursive: true });
|
|
272
342
|
const path = (suffix: string) => join(request.logDir, `${request.stage}.${suffix}`);
|
|
343
|
+
const redact = (text: string) =>
|
|
344
|
+
key === undefined || key === "" ? text : text.replaceAll(key, REDACTED_KEY);
|
|
273
345
|
|
|
274
346
|
writeFileSync(path("command"), `${commandLine}\n`);
|
|
275
347
|
// Emptied up front, so a Stage never appends to output from an earlier one.
|
|
@@ -277,11 +349,18 @@ function startStageLog(request: StageRequest, commandLine: string): StageLog {
|
|
|
277
349
|
writeFileSync(path("stderr"), "");
|
|
278
350
|
|
|
279
351
|
const appended = { stdout: 0, stderr: 0 };
|
|
352
|
+
// The tail of each stream that may be the start of a key the next chunk
|
|
353
|
+
// finishes. It stays off disk until that chunk shows it is not, so a Run
|
|
354
|
+
// killed between the two chunks leaves no part of the key behind.
|
|
355
|
+
const heldBack = { stdout: "", stderr: "" };
|
|
280
356
|
// Appending happens inside the child's stream handler, where a throw would
|
|
281
357
|
// take the whole Run down. A write that fails is left to `close` to redo.
|
|
282
358
|
const append = (suffix: "stdout" | "stderr") => (chunk: string) => {
|
|
283
359
|
try {
|
|
284
|
-
|
|
360
|
+
const text = redact(heldBack[suffix] + chunk);
|
|
361
|
+
const held = keyPrefixAtEnd(text, key);
|
|
362
|
+
heldBack[suffix] = text.slice(text.length - held);
|
|
363
|
+
appendFileSync(path(suffix), text.slice(0, text.length - held));
|
|
285
364
|
appended[suffix] += chunk.length;
|
|
286
365
|
} catch {
|
|
287
366
|
// Nothing is lost: the chunk is still part of the Execution.
|
|
@@ -295,21 +374,38 @@ function startStageLog(request: StageRequest, commandLine: string): StageLog {
|
|
|
295
374
|
close: (execution, events) => {
|
|
296
375
|
// Whatever the appends missed — a failed write, or a process runner that
|
|
297
376
|
// delivered no chunks at all — is written back whole here, so a Stage
|
|
298
|
-
// that ran to the end always has its full output on disk.
|
|
299
|
-
|
|
300
|
-
|
|
377
|
+
// that ran to the end always has its full output on disk. Where the
|
|
378
|
+
// Host has a key, both are written back whole whatever was appended,
|
|
379
|
+
// which also puts the tail held back from the last chunk on disk.
|
|
380
|
+
const keyed = key !== undefined && key !== "";
|
|
381
|
+
if (keyed || appended.stdout !== execution.stdout.length) {
|
|
382
|
+
writeFileSync(path("stdout"), redact(execution.stdout));
|
|
301
383
|
}
|
|
302
|
-
if (appended.stderr !== execution.stderr.length) {
|
|
303
|
-
writeFileSync(path("stderr"), execution.stderr);
|
|
384
|
+
if (keyed || appended.stderr !== execution.stderr.length) {
|
|
385
|
+
writeFileSync(path("stderr"), redact(execution.stderr));
|
|
304
386
|
}
|
|
305
387
|
writeFileSync(
|
|
306
388
|
path("transcript.jsonl"),
|
|
307
|
-
|
|
389
|
+
redact(
|
|
390
|
+
events.map((event) => JSON.stringify(event)).join("\n") + (events.length ? "\n" : ""),
|
|
391
|
+
),
|
|
308
392
|
);
|
|
309
393
|
},
|
|
310
394
|
};
|
|
311
395
|
}
|
|
312
396
|
|
|
397
|
+
/**
|
|
398
|
+
* How many characters at the end of `text` could be the start of `key`, so a
|
|
399
|
+
* key split across two chunks is redacted once the second arrives.
|
|
400
|
+
*/
|
|
401
|
+
function keyPrefixAtEnd(text: string, key: string | undefined): number {
|
|
402
|
+
if (key === undefined || key === "") return 0;
|
|
403
|
+
for (let length = Math.min(key.length - 1, text.length); length > 0; length--) {
|
|
404
|
+
if (text.endsWith(key.slice(0, length))) return length;
|
|
405
|
+
}
|
|
406
|
+
return 0;
|
|
407
|
+
}
|
|
408
|
+
|
|
313
409
|
function parseEvents(stdout: string): unknown[] {
|
|
314
410
|
const events: unknown[] = [];
|
|
315
411
|
for (const line of stdout.split("\n")) {
|
|
@@ -328,6 +424,19 @@ function isResultEvent(event: unknown): event is ResultEvent {
|
|
|
328
424
|
return isEvent(event, "result");
|
|
329
425
|
}
|
|
330
426
|
|
|
427
|
+
function isInitEvent(event: unknown): event is InitEvent {
|
|
428
|
+
return isEvent(event, "system") && (event as InitEvent).subtype === "init";
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
/**
|
|
432
|
+
* What the session said it was billed to: the first init event's word on it.
|
|
433
|
+
* A waking for a background agent is the same session on the same credential.
|
|
434
|
+
*/
|
|
435
|
+
function keySource(events: unknown[]): string | undefined {
|
|
436
|
+
const source = events.find(isInitEvent)?.apiKeySource;
|
|
437
|
+
return typeof source === "string" ? source : undefined;
|
|
438
|
+
}
|
|
439
|
+
|
|
331
440
|
function isRateLimitEvent(event: unknown): event is RateLimitEvent {
|
|
332
441
|
return isEvent(event, "rate_limit_event");
|
|
333
442
|
}
|
|
@@ -357,6 +466,8 @@ function classify(
|
|
|
357
466
|
// still succeeds.
|
|
358
467
|
const failed = execution.exitCode !== 0 || result?.is_error === true || result === undefined;
|
|
359
468
|
if (failed) {
|
|
469
|
+
// Before the rate limit, whose wording the spend limit's message matches.
|
|
470
|
+
if (outOfBudget(result)) return "out-of-budget";
|
|
360
471
|
if (rateLimited(execution, events, result)) return "rate-limited";
|
|
361
472
|
if (transientApiFailure(result)) return "api-error";
|
|
362
473
|
return "nonzero-exit";
|
|
@@ -374,7 +485,20 @@ function classify(
|
|
|
374
485
|
}
|
|
375
486
|
|
|
376
487
|
/**
|
|
377
|
-
* Whether a session that failed was
|
|
488
|
+
* Whether a session that failed was refused because its API key's organization
|
|
489
|
+
* is out of credit, or its workspace reached the spend limit set in the
|
|
490
|
+
* Console. Both are a 400, as a malformed request is, and the spend limit's
|
|
491
|
+
* `error` is `unknown`, so the message is what tells them apart: either
|
|
492
|
+
* wording of the credit balance, or the workspace's usage limits.
|
|
493
|
+
*/
|
|
494
|
+
function outOfBudget(result: ResultEvent | undefined): boolean {
|
|
495
|
+
if (result?.api_error_status !== 400) return false;
|
|
496
|
+
return /credit balance is too low|workspace API usage limits/i.test(String(result.result ?? ""));
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
/**
|
|
500
|
+
* Whether a session that failed was stopped by the rate limit: the
|
|
501
|
+
* subscription's, or the API's on a Stage run on a key.
|
|
378
502
|
*
|
|
379
503
|
* The CLI says so in three places, and any one of them is enough: the `result`
|
|
380
504
|
* event carries the API's 429, a `rate_limit_event` reports the request
|
|
@@ -469,14 +593,25 @@ function structuredOutputOf(result: ResultEvent): unknown {
|
|
|
469
593
|
/**
|
|
470
594
|
* Shell-quote the command so a human can paste it back into a terminal, with
|
|
471
595
|
* the Stage's environment in front of it so the reproduction is exact.
|
|
596
|
+
*
|
|
597
|
+
* How the environment differed from the Host's leads it: a subscription Stage
|
|
598
|
+
* ran without the Host's key, which `env -u` removes again, and an API-key
|
|
599
|
+
* Stage ran on it, which is named and left for the shell to fill in. Its value
|
|
600
|
+
* is never written: command files reach the Target's remote with a hand-off.
|
|
472
601
|
*/
|
|
473
602
|
function quoteCommand(
|
|
603
|
+
credential: Credential,
|
|
474
604
|
extraEnv: Record<string, string>,
|
|
475
605
|
binary: string,
|
|
476
606
|
args: string[],
|
|
477
607
|
): string {
|
|
478
608
|
const assignments = Object.entries(extraEnv).map(([name, value]) => `${name}=${value}`);
|
|
479
|
-
|
|
609
|
+
const differed =
|
|
610
|
+
credential === "subscription"
|
|
611
|
+
? `env -u ${API_KEY_ENV_VAR}`
|
|
612
|
+
: `${API_KEY_ENV_VAR}="$${API_KEY_ENV_VAR}"`;
|
|
613
|
+
const quoted = [...assignments, binary, ...args]
|
|
480
614
|
.map((part) => (/^[\w./:=-]+$/.test(part) ? part : `'${part.replaceAll("'", `'\\''`)}'`))
|
|
481
615
|
.join(" ");
|
|
616
|
+
return `${differed} ${quoted}`;
|
|
482
617
|
}
|
package/src/adapters/exec.ts
CHANGED
|
@@ -27,6 +27,8 @@ export interface ExecOptions {
|
|
|
27
27
|
killGraceMs?: number;
|
|
28
28
|
/** Variables merged over the environment the child inherits, not replacing it. */
|
|
29
29
|
extraEnv?: Record<string, string>;
|
|
30
|
+
/** Variables the child does not inherit, whatever this process carries. */
|
|
31
|
+
unsetEnv?: string[];
|
|
30
32
|
/**
|
|
31
33
|
* A variable set over `extraEnv`, whose value nothing else on the Host
|
|
32
34
|
* carries. A kill at `timeoutMs` also takes every process still carrying it,
|
|
@@ -84,9 +86,10 @@ export function exec(
|
|
|
84
86
|
const { mark } = options;
|
|
85
87
|
const extraEnv =
|
|
86
88
|
mark === undefined ? options.extraEnv : { ...options.extraEnv, [mark.name]: mark.value };
|
|
89
|
+
const env = childEnv(extraEnv, options.unsetEnv);
|
|
87
90
|
const child = spawn(command, args, {
|
|
88
91
|
...(options.cwd === undefined ? {} : { cwd: options.cwd }),
|
|
89
|
-
...(
|
|
92
|
+
...(env === undefined ? {} : { env }),
|
|
90
93
|
shell: options.shell ?? false,
|
|
91
94
|
stdio: ["ignore", "pipe", "pipe"],
|
|
92
95
|
});
|
|
@@ -196,3 +199,17 @@ export function throwOnFailure(
|
|
|
196
199
|
}
|
|
197
200
|
return result;
|
|
198
201
|
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* The environment a child is given, or nothing where it inherits this
|
|
205
|
+
* process's own untouched.
|
|
206
|
+
*/
|
|
207
|
+
function childEnv(
|
|
208
|
+
extraEnv: Record<string, string> | undefined,
|
|
209
|
+
unsetEnv: string[] | undefined,
|
|
210
|
+
): NodeJS.ProcessEnv | undefined {
|
|
211
|
+
if (extraEnv === undefined && (unsetEnv === undefined || unsetEnv.length === 0)) return undefined;
|
|
212
|
+
const env: NodeJS.ProcessEnv = { ...process.env, ...extraEnv };
|
|
213
|
+
for (const name of unsetEnv ?? []) delete env[name];
|
|
214
|
+
return env;
|
|
215
|
+
}
|
|
@@ -147,7 +147,7 @@ export class GitWorkspace implements Workspace {
|
|
|
147
147
|
|
|
148
148
|
constructor(
|
|
149
149
|
private readonly repoRoot: string,
|
|
150
|
-
|
|
150
|
+
readonly remote = "origin",
|
|
151
151
|
{ host = currentHost(process.env), checkProcess = checkProcessTable }: LockOptions = {},
|
|
152
152
|
) {
|
|
153
153
|
this.host = host;
|
|
@@ -575,6 +575,15 @@ export class GitWorkspace implements Workspace {
|
|
|
575
575
|
return stdout.trim() !== "";
|
|
576
576
|
}
|
|
577
577
|
|
|
578
|
+
async readRemoteFile(branch: string, path: string): Promise<string | undefined> {
|
|
579
|
+
// Fetched first, as a worktree is made from it: the checkout's own
|
|
580
|
+
// remote-tracking ref may predate a push another clone made.
|
|
581
|
+
const tracking = await this.fetchBranch(branch);
|
|
582
|
+
if (tracking === undefined) return undefined;
|
|
583
|
+
const read = await this.tryGit(["cat-file", "blob", `${tracking}:${path}`]);
|
|
584
|
+
return read.exitCode === 0 ? read.stdout : undefined;
|
|
585
|
+
}
|
|
586
|
+
|
|
578
587
|
async deleteRemoteBranch(branch: string): Promise<void> {
|
|
579
588
|
// Asked before anything is sent: a repository that deletes a merged branch
|
|
580
589
|
// has usually done it by now, and a cloud Host, which may delete nothing,
|
package/src/command-line.ts
CHANGED
|
@@ -34,6 +34,10 @@ Usage:
|
|
|
34
34
|
Options:
|
|
35
35
|
--lanes <n> With \`run\`: work on up to <n> issues at once,
|
|
36
36
|
whatever \`lanes\` in ticket-runner.json says.
|
|
37
|
+
--api-key With \`run\`: bill every session to the
|
|
38
|
+
ANTHROPIC_API_KEY this shell exports. Without
|
|
39
|
+
it, sessions run on your Claude login and the
|
|
40
|
+
key is kept from them. Not on a cloud session.
|
|
37
41
|
-y, --yes With \`remove\`: go ahead without asking.
|
|
38
42
|
-h, --help Show this message.
|
|
39
43
|
-v, --version Show which version this pipeline is.`;
|
|
@@ -75,6 +79,11 @@ export function readCommandLine(argv: string[]): CommandLine {
|
|
|
75
79
|
return refused("`--lanes` is for `run` only, which has a Frontier to share out.");
|
|
76
80
|
}
|
|
77
81
|
|
|
82
|
+
// The same for `--api-key`: only `run` starts the sessions it would bill.
|
|
83
|
+
if (values["api-key"] === true && command !== "run") {
|
|
84
|
+
return refused("`--api-key` is for `run` only, the one command that starts Stages.");
|
|
85
|
+
}
|
|
86
|
+
|
|
78
87
|
// The same for `--yes` everywhere but `remove`, the one command that asks
|
|
79
88
|
// before it acts: given to any other, it answers a question nobody asks.
|
|
80
89
|
if (values.yes === true && command !== "remove") {
|
|
@@ -101,6 +110,7 @@ export function readCommandLine(argv: string[]): CommandLine {
|
|
|
101
110
|
command: "run",
|
|
102
111
|
...(lanes === undefined ? {} : { lanes }),
|
|
103
112
|
...(tickets.length === 0 ? {} : { tickets }),
|
|
113
|
+
...(values["api-key"] === true ? { apiKey: true as const } : {}),
|
|
104
114
|
},
|
|
105
115
|
};
|
|
106
116
|
}
|
|
@@ -148,7 +158,13 @@ function refused(complaint: string): CommandLine {
|
|
|
148
158
|
/** What `parseArgs` makes of the arguments: the options, and the rest. */
|
|
149
159
|
interface ParsedArgs {
|
|
150
160
|
positionals: string[];
|
|
151
|
-
values: {
|
|
161
|
+
values: {
|
|
162
|
+
help?: boolean;
|
|
163
|
+
version?: boolean;
|
|
164
|
+
lanes?: string;
|
|
165
|
+
"api-key"?: boolean;
|
|
166
|
+
yes?: boolean;
|
|
167
|
+
};
|
|
152
168
|
}
|
|
153
169
|
|
|
154
170
|
/**
|
|
@@ -169,6 +185,7 @@ function parseCommandLine(argv: string[]): ParsedArgs | string {
|
|
|
169
185
|
help: { type: "boolean", short: "h" },
|
|
170
186
|
version: { type: "boolean", short: "v" },
|
|
171
187
|
lanes: { type: "string" },
|
|
188
|
+
"api-key": { type: "boolean" },
|
|
172
189
|
yes: { type: "boolean", short: "y" },
|
|
173
190
|
},
|
|
174
191
|
allowPositionals: true,
|
package/src/config.ts
CHANGED
|
@@ -53,7 +53,7 @@ const configSchema = z
|
|
|
53
53
|
.optional(),
|
|
54
54
|
permissionMode: z.enum(PERMISSION_MODES).optional(),
|
|
55
55
|
ciTimeoutMinutes: z.number().positive().optional(),
|
|
56
|
-
ciGraceMinutes: z.number().
|
|
56
|
+
ciGraceMinutes: z.number().nonnegative().optional(),
|
|
57
57
|
checkTimeoutMinutes: z.number().positive().optional(),
|
|
58
58
|
labels: z
|
|
59
59
|
.object({
|
|
@@ -112,7 +112,8 @@ export interface Config {
|
|
|
112
112
|
/**
|
|
113
113
|
* How long a pull request GitHub has registered no check run for still counts
|
|
114
114
|
* as pending. A Target whose Actions queue slowly raises it; a Target with no
|
|
115
|
-
* CI
|
|
115
|
+
* CI sets it to zero, or else pays it once per Landing, so it is not the CI
|
|
116
|
+
* timeout.
|
|
116
117
|
*/
|
|
117
118
|
ciGraceMinutes: number;
|
|
118
119
|
/**
|
package/src/conventions.ts
CHANGED
|
@@ -79,9 +79,9 @@ What \`ticket-runner\` requires of this repository, and nothing else. \`ticket-r
|
|
|
79
79
|
|
|
80
80
|
## Commits
|
|
81
81
|
|
|
82
|
-
- Subject: \`<type>(<scope>): <summary
|
|
83
|
-
- The type and scope vocabulary is this repository's own. The pipeline reads the shape
|
|
84
|
-
- A commit subject describes its own commit. The whole branch is summarised by the \`title\` the implement and fix Stages each answer beside their Notes: one line in the same shape
|
|
82
|
+
- Subject: \`<type>(<scope>): <summary>\`.
|
|
83
|
+
- The type and scope vocabulary is this repository's own. The pipeline reads the shape, never the words.
|
|
84
|
+
- A commit subject describes its own commit. The whole branch is summarised by the \`title\` the implement and fix Stages each answer beside their Notes: one line in the same shape. The latest one becomes the pull request title, and the pull request title becomes the subject of the squash commit that lands.
|
|
85
85
|
|
|
86
86
|
## Branches
|
|
87
87
|
|