@jagreehal/shepherd 0.3.0 → 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.
@@ -0,0 +1,461 @@
1
+ // Optional measurements for garden. Only known span names and numeric measurements leave this module;
2
+ // prompts, tool arguments, logs and arbitrary span attributes never become gardener instructions.
3
+ import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
4
+ import { z } from "zod";
5
+ import type { PrRecord } from "./garden.ts";
6
+ import { STAGES } from "./trace.ts";
7
+
8
+ const MAX_BYTES = 10_000_000;
9
+
10
+ const MAX_TRACES = 100;
11
+
12
+ const MAX_SPANS = 50_000;
13
+
14
+ const MAX_MEASUREMENTS = 50_000_000;
15
+
16
+ const KEYS = new Set(["vcs.repository.name", "vcs.change.id", "vcs.ref.head.revision", "shepherd.retries", "shepherd.stage", "shepherd.outcome", "stamp.cost_usd", "stamp.cost_complete"]);
17
+
18
+ const Id = z.string().transform((s) => /^[0-9a-f]{1,32}$/.test(s) ? s.padStart(32, "0") : /^[A-Za-z0-9+/]{22}==$/.test(s) ? Buffer.from(s, "base64").toString("hex") : s)
19
+ .pipe(z.string().regex(/^[0-9a-f]{32}$/).refine((s) => /[1-9a-f]/.test(s)));
20
+
21
+ const SpanId = z.string().transform((s) => /^[A-Za-z0-9+/]{11}=$/.test(s) ? Buffer.from(s, "base64").toString("hex") : s).pipe(z.string().regex(/^[0-9a-f]{16}$/));
22
+
23
+ const Integer = z.union([z.string().regex(/^\d{1,20}$/), z.number().int().nonnegative().safe()]);
24
+
25
+ const Attribute = z.object({ key: z.string(), value: z.object({ stringValue: z.string().optional(), intValue: Integer.optional(), doubleValue: z.number().finite().optional(), boolValue: z.boolean().optional() }) });
26
+
27
+ const Span = z.object({
28
+ name: z.string(), traceId: Id, spanId: SpanId, parentSpanId: z.union([SpanId, z.literal("")]).optional().transform((s) => s || undefined),
29
+ startTimeUnixNano: Integer, endTimeUnixNano: Integer,
30
+ attributes: z.array(Attribute).default([]),
31
+ status: z.object({ code: z.union([z.number(), z.string()]).optional() }).optional(),
32
+ }).transform((s) => ({ ...s, attributes: s.attributes.filter((a) => KEYS.has(a.key)) }));
33
+
34
+ const Resource = z.object({ scopeSpans: z.array(z.object({ spans: z.array(Span) })).default([]) });
35
+
36
+ // Tempo calls resourceSpans `batches`; collector file exports use resourceSpans, one JSON object per line.
37
+ const Envelope = z.object({ resourceSpans: z.array(Resource).optional(), batches: z.array(Resource).optional() })
38
+ .refine((e) => e.resourceSpans !== undefined || e.batches !== undefined);
39
+
40
+ type Span = z.infer<typeof Span>;
41
+
42
+ export type TraceInput = { spans: Span[]; sources: number; unavailable: number; limited: boolean; bytes?: number };
43
+
44
+ export const traceLimits = { retries: 3, waitMs: 300_000, costUsd: 5 };
45
+
46
+ export type TraceLimits = typeof traceLimits;
47
+
48
+ export function traceHeaders(raw: string): Record<string, string> {
49
+ try {
50
+ return z.record(z.string(), z.string()).parse(JSON.parse(raw));
51
+ } catch {
52
+ throw new Error("GARDEN_TEMPO_HEADERS must be a JSON object of header strings");
53
+ }
54
+ }
55
+
56
+ /**
57
+ * The credential headers for one Tempo endpoint. GARDEN_TEMPO_HEADERS belongs to GARDEN_TEMPO_URL, so an
58
+ * endpoint on any other origin, such as a `--tempo-url` pointing elsewhere, gets no headers.
59
+ */
60
+ export function tempoHeaders(endpoint: string | undefined, configured: string | undefined, raw: string | undefined): Record<string, string> {
61
+ if (!endpoint || !configured || !raw) return {};
62
+
63
+ const origin = (u: string) => {
64
+ try {
65
+ return new URL(u).origin;
66
+ } catch {
67
+ return null;
68
+ }
69
+ };
70
+
71
+ return origin(endpoint) !== null && origin(endpoint) === origin(configured) ? traceHeaders(raw) : {};
72
+ }
73
+
74
+ export type TraceSignal = "trace_stage_failed" | "trace_retries" | "trace_approval_wait" | "trace_review_cost";
75
+
76
+ /** Decode OTLP JSON or a collector's JSON-lines file. A malformed source contributes no measurements. */
77
+ export function parseTraces(text: string): Span[] {
78
+ let envelopes: z.infer<typeof Envelope>[];
79
+
80
+ try {
81
+ envelopes = [Envelope.parse(JSON.parse(text))];
82
+ } catch {
83
+ envelopes = text.split("\n").filter((s) => s.trim()).map((s) => Envelope.parse(JSON.parse(s)));
84
+ }
85
+
86
+ return envelopes.flatMap((e) => (e.resourceSpans ?? e.batches ?? []).flatMap((r) => r.scopeSpans.flatMap((s) => s.spans)));
87
+ }
88
+
89
+ /** Open without following symlinks and bound the same descriptor that gets read. */
90
+ export function readTraceFile(file: string): Span[] {
91
+ const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
92
+
93
+ try {
94
+ const stat = fstatSync(fd);
95
+
96
+ if (!stat.isFile() || stat.size > MAX_BYTES) throw new Error("trace input must be a regular file of at most 10 MB");
97
+
98
+ const bytes = Buffer.alloc(MAX_BYTES + 1);
99
+ let length = 0;
100
+
101
+ while (length <= MAX_BYTES) {
102
+ const read = readSync(fd, bytes, length, bytes.length - length, null);
103
+
104
+ if (!read) break;
105
+ length += read;
106
+ }
107
+
108
+ if (length > MAX_BYTES) throw new Error("trace input exceeds 10 MB");
109
+
110
+ return parseTraces(bytes.subarray(0, length).toString("utf8"));
111
+ } finally {
112
+ closeSync(fd);
113
+ }
114
+ }
115
+
116
+ /** Read a response under a byte cap, keeping the timeout active until its body has finished. */
117
+ async function readResponse(response: Response): Promise<string> {
118
+ if (!response.ok || !response.body) throw new Error("trace backend request failed");
119
+
120
+ const reader = response.body.getReader();
121
+ const chunks: Uint8Array[] = [];
122
+ let bytes = 0;
123
+
124
+ try {
125
+ for (;;) {
126
+ const next = await reader.read();
127
+
128
+ if (next.done) break;
129
+ bytes += next.value.byteLength;
130
+
131
+ if (bytes > MAX_BYTES) throw new Error("trace response exceeds 10 MB");
132
+ chunks.push(next.value);
133
+ }
134
+ } finally {
135
+ await reader.cancel();
136
+ }
137
+
138
+ return Buffer.concat(chunks).toString("utf8");
139
+ }
140
+
141
+ const Search = z.object({ traces: z.array(z.object({ traceID: Id })).default([]) });
142
+
143
+ const appendSpans = (input: TraceInput, spans: Span[]) => {
144
+ const bytes = Buffer.byteLength(JSON.stringify(spans));
145
+
146
+ if ((input.bytes ?? 0) + bytes > MAX_MEASUREMENTS) {
147
+ input.limited = true;
148
+
149
+ return;
150
+ }
151
+
152
+ const available = MAX_SPANS - input.spans.length;
153
+ input.spans.push(...spans.slice(0, available));
154
+ input.bytes = (input.bytes ?? 0) + bytes;
155
+ input.limited ||= spans.length > available;
156
+ };
157
+
158
+ /** Tempo's read-only search and trace-by-id APIs. No URL from a span or search result is ever followed. */
159
+ export async function readTempo(endpoint: string, headers: Record<string, string>, repo: string, since: string, now = Date.now()): Promise<TraceInput> {
160
+ const base = new URL(endpoint.endsWith("/") ? endpoint : endpoint + "/");
161
+
162
+ if (!["http:", "https:"].includes(base.protocol) || base.username || base.password || base.search || base.hash) throw new Error("invalid Tempo endpoint");
163
+
164
+ const signal = AbortSignal.timeout(30_000);
165
+ const get = async (url: URL) => readResponse(await fetch(url, { headers: { ...headers, Accept: "application/json" }, redirect: "error", signal }));
166
+ const search = new URL("api/search", base);
167
+ search.searchParams.set("q", `{ (name = "shepherd.iteration" || name = "stamp.review") && span.vcs.repository.name = ${JSON.stringify(repo)} }`);
168
+ search.searchParams.set("start", String(Math.floor(Date.parse(since) / 1000)));
169
+ search.searchParams.set("end", String(Math.floor(now / 1000)));
170
+ search.searchParams.set("limit", String(MAX_TRACES));
171
+
172
+ const found = Search.parse(JSON.parse(await get(search))).traces;
173
+ const input: TraceInput = { spans: [], sources: 1, unavailable: 0, limited: found.length >= MAX_TRACES };
174
+
175
+ for (const id of new Set(found.map((t) => t.traceID))) {
176
+ try {
177
+ appendSpans(input, parseTraces(await get(new URL(`api/traces/${id}`, base))));
178
+ } catch {
179
+ input.unavailable++;
180
+ }
181
+ }
182
+
183
+ return input;
184
+ }
185
+
186
+ // Datadog keeps OTLP attributes nested under `custom` and span IDs in decimal; the trace ID stays 128-bit hex.
187
+ // Each field falls back to absent, so one odd attribute drops that measurement, not the span.
188
+ const str = z.string().optional().catch(undefined);
189
+
190
+ const num = z.number().optional().catch(undefined);
191
+
192
+ const DatadogCustom = z.object({
193
+ vcs: z.object({
194
+ repository: z.object({ name: str }).optional().catch(undefined),
195
+ change: z.object({ id: str }).optional().catch(undefined),
196
+ ref: z.object({ head: z.object({ revision: str }).optional().catch(undefined) }).optional().catch(undefined),
197
+ }).optional().catch(undefined),
198
+ shepherd: z.object({ retries: num, stage: str, outcome: str }).optional().catch(undefined),
199
+ // Datadog stores a boolean attribute as the string "true" or "false".
200
+ stamp: z.object({ cost_usd: num, cost_complete: z.enum(["true", "false"]).optional().catch(undefined) }).optional().catch(undefined),
201
+ otel: z.object({ status_code: str }).optional().catch(undefined),
202
+ }).catch({});
203
+
204
+ const DatadogSpan = z.object({
205
+ attributes: z.object({
206
+ trace_id: z.string(), span_id: z.string().regex(/^\d{1,20}$/), parent_id: z.string().regex(/^\d{1,20}$/),
207
+ start_timestamp: z.iso.datetime(), end_timestamp: z.iso.datetime(), resource_name: z.string(),
208
+ custom: DatadogCustom.default({}),
209
+ }),
210
+ });
211
+
212
+ type DatadogSpan = z.infer<typeof DatadogSpan>;
213
+
214
+ const DatadogPage = z.object({
215
+ data: z.array(DatadogSpan.nullable().catch(null)).default([]),
216
+ // Datadog sends `page: null` on the last page, and a status other than `done` or any warning when the
217
+ // results are partial, such as a query that timed out.
218
+ meta: z.object({
219
+ page: z.object({ after: z.string() }).nullish(),
220
+ status: z.string().nullish(),
221
+ warnings: z.array(z.unknown()).nullish(),
222
+ }).nullish(),
223
+ });
224
+
225
+ const partial = (page: z.infer<typeof DatadogPage>) => (page.meta?.status ?? "done") !== "done" || Boolean(page.meta?.warnings?.length);
226
+
227
+ /** Datadog's API hosts, so its keys only ever go to Datadog. */
228
+ export const DATADOG_SITES = ["datadoghq.com", "datadoghq.eu", "us3.datadoghq.com", "us5.datadoghq.com", "ap1.datadoghq.com", "ap2.datadoghq.com", "ddog-gov.com"];
229
+
230
+ const toNano = (iso: string) => String(BigInt(Date.parse(iso)) * 1_000_000n);
231
+
232
+ const decimalId = (id: string) => BigInt(id).toString(16).padStart(16, "0");
233
+
234
+ const asText = (key: string, v: string | undefined) => (v === undefined ? [] : [{ key, value: { stringValue: v } }]);
235
+
236
+ const asDouble = (key: string, v: number | undefined) => (v === undefined ? [] : [{ key, value: { doubleValue: v } }]);
237
+
238
+ /** One Datadog span in the OTLP shape the scorer reads, keeping only the known attribute keys. */
239
+ export function fromDatadog(span: DatadogSpan): Span | null {
240
+ const a = span.attributes;
241
+ const c = a.custom;
242
+
243
+ const attributes = [
244
+ ...asText("vcs.repository.name", c.vcs?.repository?.name),
245
+ ...asText("vcs.change.id", c.vcs?.change?.id),
246
+ ...asText("vcs.ref.head.revision", c.vcs?.ref?.head?.revision),
247
+ ...asDouble("shepherd.retries", c.shepherd?.retries),
248
+ ...asText("shepherd.stage", c.shepherd?.stage),
249
+ ...asText("shepherd.outcome", c.shepherd?.outcome),
250
+ ...asDouble("stamp.cost_usd", c.stamp?.cost_usd),
251
+ ...(c.stamp?.cost_complete === undefined ? [] : [{ key: "stamp.cost_complete", value: { boolValue: c.stamp.cost_complete === "true" } }]),
252
+ ];
253
+
254
+ const parsed = Span.safeParse({
255
+ name: a.resource_name, traceId: a.trace_id, spanId: decimalId(a.span_id), parentSpanId: a.parent_id === "0" ? "" : decimalId(a.parent_id),
256
+ startTimeUnixNano: toNano(a.start_timestamp), endTimeUnixNano: toNano(a.end_timestamp), attributes,
257
+ status: c.otel?.status_code === "Error" ? { code: 2 } : undefined,
258
+ });
259
+
260
+ return parsed.success ? parsed.data : null;
261
+ }
262
+
263
+ /**
264
+ * Datadog's span search: the repository's `shepherd.iteration` and `stamp.review` roots, then every span in those
265
+ * traces, since stage spans carry no repository. The endpoint rate-limits at 300 requests an hour, so the reader
266
+ * batches trace IDs and stops at the trace and span caps.
267
+ */
268
+ export async function readDatadog(site: string, apiKey: string, appKey: string, repo: string, since: string, now = Date.now(), get: (url: string, init: RequestInit) => Promise<Response> = fetch): Promise<TraceInput> {
269
+ if (!DATADOG_SITES.includes(site)) throw new Error("invalid Datadog site");
270
+
271
+ const signal = AbortSignal.timeout(30_000);
272
+
273
+ const search = async (query: string, cursor?: string) =>
274
+ DatadogPage.parse(JSON.parse(await readResponse(await get(`https://api.${site}/api/v2/spans/events/search`, {
275
+ method: "POST",
276
+ headers: { "DD-API-KEY": apiKey, "DD-APPLICATION-KEY": appKey, "Content-Type": "application/json", Accept: "application/json" },
277
+ body: JSON.stringify({ data: { type: "search_request", attributes: { filter: { query, from: new Date(Date.parse(since)).toISOString(), to: new Date(now).toISOString() }, page: { limit: 1000, cursor }, sort: "timestamp" } } }),
278
+ redirect: "error",
279
+ signal,
280
+ }))));
281
+
282
+ const roots = await search(`@vcs.repository.name:${JSON.stringify(repo)} resource_name:(shepherd.iteration OR stamp.review)`);
283
+ const ids = [...new Set(roots.data.flatMap((s) => (s ? [s.attributes.trace_id] : [])).filter((id) => /^[0-9a-f]{32}$/.test(id)))].slice(0, MAX_TRACES);
284
+ // Here `limited` tracks only the span budget, so a truncated root search still pages through every trace it found.
285
+ const input: TraceInput = { spans: [], sources: 1, unavailable: 0, limited: false };
286
+ let incomplete = ids.length >= MAX_TRACES || Boolean(roots.meta?.page) || partial(roots);
287
+
288
+ for (let i = 0; i < ids.length && !input.limited; i += 50) {
289
+ let cursor: string | undefined;
290
+
291
+ do {
292
+ try {
293
+ const page = await search(`trace_id:(${ids.slice(i, i + 50).join(" OR ")})`, cursor);
294
+ appendSpans(input, page.data.flatMap((s) => (s ? (fromDatadog(s) ?? []) : [])));
295
+ incomplete ||= partial(page);
296
+ cursor = page.meta?.page?.after;
297
+ } catch {
298
+ input.unavailable++;
299
+ cursor = undefined;
300
+ }
301
+ } while (cursor && !input.limited);
302
+ }
303
+
304
+ input.limited ||= incomplete;
305
+
306
+ return input;
307
+ }
308
+
309
+ /** Only operator-selected files and backend configuration enter here; errors never include URLs, headers or bodies. */
310
+ export type DatadogConfig = { site: string; apiKey: string; appKey: string };
311
+
312
+ export async function collectTraces(files: string[], endpoint: string | undefined, headers: Record<string, string>, repo: string, since: string, datadog?: DatadogConfig): Promise<TraceInput> {
313
+ const input: TraceInput = { spans: [], sources: files.length + (endpoint ? 1 : 0) + (datadog ? 1 : 0), unavailable: 0, limited: false };
314
+
315
+ if (files.length > MAX_TRACES) throw new Error("at most 100 trace files may be read");
316
+
317
+ for (const file of files) {
318
+ try {
319
+ appendSpans(input, readTraceFile(file));
320
+ } catch {
321
+ input.unavailable++;
322
+ }
323
+ }
324
+
325
+ const remotes = [endpoint ? () => readTempo(endpoint, headers, repo, since) : null, datadog ? () => readDatadog(datadog.site, datadog.apiKey, datadog.appKey, repo, since) : null];
326
+
327
+ for (const read of remotes) {
328
+ if (!read) continue;
329
+
330
+ try {
331
+ const remote = await read();
332
+ appendSpans(input, remote.spans);
333
+ input.unavailable += remote.unavailable;
334
+ input.limited ||= remote.limited;
335
+ } catch {
336
+ input.unavailable++;
337
+ }
338
+ }
339
+
340
+ return input;
341
+ }
342
+
343
+ const value = (s: Span, key: string) => s.attributes.find((a) => a.key === key)?.value;
344
+
345
+ const text = (s: Span, key: string) => value(s, key)?.stringValue;
346
+
347
+ const number = (s: Span, key: string): number | undefined => {
348
+ const v = value(s, key);
349
+ const parsed = z.coerce.number().finite().nonnegative().safeParse(v?.doubleValue ?? v?.intValue);
350
+
351
+ return parsed.success ? parsed.data : undefined;
352
+ };
353
+
354
+ const startMs = (s: Span) => Number(BigInt(s.startTimeUnixNano)) / 1e6;
355
+
356
+ const duration = (s: Span) => Number(BigInt(s.endTimeUnixNano) - BigInt(s.startTimeUnixNano)) / 1e6;
357
+
358
+ const unionMs = (intervals: [number, number][]) => {
359
+ let end = 0;
360
+ let total = 0;
361
+
362
+ for (const [from, to] of intervals.sort((a, b) => a[0] - b[0])) {
363
+ total += Math.max(0, to - Math.max(from, end));
364
+ end = Math.max(end, to);
365
+ }
366
+
367
+ return total;
368
+ };
369
+
370
+ export type TraceSummary = {
371
+ iterations: number; reviews: number; failedStages: number; retries: number; iterationMs: number; approvalWaitMs: number;
372
+ reviewMs: number; knownCostUsd: number; pricedReviews: number; unpricedReviews: number;
373
+ stages: { stage: typeof STAGES[number]; durationMs: number; runs: number; failed: number }[];
374
+ signals: TraceSignal[];
375
+ evidence: { traceId: string; spanId: string; headSha: string; kind: "shepherd.iteration" | "stamp.review" }[];
376
+ };
377
+
378
+ const Kind = z.enum(["shepherd.iteration", "stamp.review"]);
379
+
380
+ /** Deduplicate exports, then correlate only known PR commits inside the requested window. These are observed samples, not a complete history. */
381
+ export function traceScores(input: TraceInput, repo: string, prs: PrRecord[], since: string, limits = traceLimits, now = Date.now()) {
382
+ const spans = [...new Map(input.spans.map((s) => [`${s.traceId}:${s.spanId}`, s])).values()];
383
+ const byPr = new Map(prs.map((pr) => [pr.number, pr]));
384
+ const summaries = new Map<number, TraceSummary>();
385
+ const children = new Map<string, Span[]>();
386
+ let unmatched = 0;
387
+
388
+ for (const s of spans) {
389
+ const key = `${s.traceId}:${s.parentSpanId}`;
390
+ const group = children.get(key) ?? [];
391
+ group.push(s);
392
+ children.set(key, group);
393
+ }
394
+
395
+ for (const root of spans) {
396
+ const kind = Kind.safeParse(root.name);
397
+
398
+ if (!kind.success || text(root, "vcs.repository.name")?.toLowerCase() !== repo.toLowerCase() || startMs(root) < Date.parse(since) || startMs(root) > now) continue;
399
+ const n = Number(text(root, "vcs.change.id") ?? number(root, "vcs.change.id"));
400
+ const pr = byPr.get(n);
401
+ const head = text(root, "vcs.ref.head.revision") ?? "";
402
+
403
+ if (!pr || !/^[0-9a-f]{40}$/.test(head) || ![pr.headSha, ...pr.commits.map((c) => c.sha)].includes(head) || duration(root) < 0 || duration(root) > 7 * 864e5) {
404
+ unmatched++;
405
+ continue;
406
+ }
407
+
408
+ const summary = summaries.get(n) ?? { iterations: 0, reviews: 0, failedStages: 0, retries: 0, iterationMs: 0, approvalWaitMs: 0, reviewMs: 0, knownCostUsd: 0, pricedReviews: 0, unpricedReviews: 0, stages: [], signals: [], evidence: [] };
409
+
410
+ if (summary.evidence.length < 20) summary.evidence.push({ traceId: root.traceId, spanId: root.spanId, headSha: head, kind: kind.data });
411
+
412
+ if (kind.data === "stamp.review") {
413
+ summary.reviews++;
414
+ summary.reviewMs += duration(root);
415
+ const cost = number(root, "stamp.cost_usd");
416
+
417
+ if (cost !== undefined) summary.knownCostUsd += cost;
418
+
419
+ if (cost !== undefined && value(root, "stamp.cost_complete")?.boolValue === true) summary.pricedReviews++;
420
+ else summary.unpricedReviews++;
421
+ } else {
422
+ summary.iterations++;
423
+ summary.iterationMs += duration(root);
424
+ summary.retries += number(root, "shepherd.retries") ?? 0;
425
+ const waits: [number, number][] = [];
426
+
427
+ for (const child of children.get(`${root.traceId}:${root.spanId}`) ?? []) {
428
+ const stage = z.enum(STAGES).safeParse(text(child, "shepherd.stage"));
429
+ const elapsed = duration(child);
430
+
431
+ if (!stage.success || elapsed < 0 || startMs(child) < startMs(root) || startMs(child) + elapsed > startMs(root) + duration(root)) continue;
432
+ const failed = ["failed", "unfinished"].includes(text(child, "shepherd.outcome") ?? "") || child.status?.code === 2 || child.status?.code === "STATUS_CODE_ERROR";
433
+ const record = summary.stages.find((s) => s.stage === stage.data) ?? { stage: stage.data, durationMs: 0, runs: 0, failed: 0 };
434
+ record.durationMs += elapsed;
435
+ record.runs++;
436
+ record.failed += Number(failed);
437
+ summary.failedStages += Number(failed);
438
+
439
+ if (stage.data === "stamp") waits.push([startMs(child), startMs(child) + elapsed]);
440
+
441
+ if (!summary.stages.includes(record)) summary.stages.push(record);
442
+ }
443
+
444
+ summary.approvalWaitMs += unionMs(waits);
445
+ }
446
+
447
+ summaries.set(n, summary);
448
+ }
449
+
450
+ for (const s of summaries.values()) {
451
+ if (s.failedStages) s.signals.push("trace_stage_failed");
452
+
453
+ if (s.retries >= limits.retries) s.signals.push("trace_retries");
454
+
455
+ if (s.approvalWaitMs >= limits.waitMs && s.approvalWaitMs >= s.iterationMs / 2) s.signals.push("trace_approval_wait");
456
+
457
+ if (s.knownCostUsd >= limits.costUsd) s.signals.push("trace_review_cost");
458
+ }
459
+
460
+ return { summaries, coverage: { sources: input.sources, unavailable: input.unavailable, limited: input.limited, unmatchedRoots: unmatched, observedOnly: true }, limits };
461
+ }
package/src/garden.ts CHANGED
@@ -12,6 +12,7 @@ export type Commit = { sha: string; headline: string; skill: string | null; lens
12
12
 
13
13
  export type PrRecord = {
14
14
  number: number;
15
+ headSha?: string;
15
16
  title: string;
16
17
  state: string;
17
18
  threads: Thread[];
@@ -218,6 +219,6 @@ export function collect(repo: string, since: string): PrRecord[] {
218
219
  const status = Statuses.parse(JSON.parse(gh(["api", `repos/${repo}/commits/${pr.headRefOid}/status`]))).statuses.find((s) => s.context === "shepherd");
219
220
  const summary = Comments.parse(JSON.parse(gh(["api", "--paginate", "--slurp", `repos/${repo}/issues/${pr.number}/comments`])).flat()).find((c) => c.body.includes("<!-- shepherd-swarm-summary -->"));
220
221
 
221
- return { number: pr.number, title: pr.title, state: pr.state, threads, commits, status: status ? { state: status.state, description: status.description ?? "", updatedAt: status.updated_at } : null, rounds: roundsOf(summary?.body), trusted: trusted(pr.author.login) };
222
+ return { number: pr.number, headSha: pr.headRefOid, title: pr.title, state: pr.state, threads, commits, status: status ? { state: status.state, description: status.description ?? "", updatedAt: status.updated_at } : null, rounds: roundsOf(summary?.body), trusted: trusted(pr.author.login) };
222
223
  });
223
224
  }
package/src/install.ts CHANGED
@@ -6,6 +6,9 @@ import path from "node:path";
6
6
 
7
7
  export const MARKER = ".shepherd-installed";
8
8
 
9
+ /** A workflow template with every `SHEPHERD_VERSION:` pin set to `version`, so each job runs the CLI that wrote it. */
10
+ export const pinWorkflow = (text: string, version: string) => text.replaceAll(/SHEPHERD_VERSION: \S+/g, `SHEPHERD_VERSION: ${version}`);
11
+
9
12
  // Command files are single files, so they carry the marker as a comment line instead.
10
13
  const COMMAND_MARKER = "<!-- shepherd-installed -->";
11
14
 
package/src/notify.ts ADDED
@@ -0,0 +1,138 @@
1
+ // Outbound notifications. Off until SHEPHERD_NOTIFY_WEBHOOK is set. A Slack Incoming Webhook URL gets a
2
+ // Slack message; any other URL gets the event as JSON, for Discord relays, Teams, n8n, Zapier or an agent
3
+ // platform's trigger. The caller runs `shepherd notify` right after setting the commit status; this
4
+ // module drops repeats (a local record across heads, a `shepherd/notify` status on the head for fresh CI
5
+ // runners), so a /loop or a rerun tells people once per change of state, not every iteration. People answer
6
+ // on the PR, where the next iteration's triage reads them.
7
+ import { execFileSync } from "node:child_process";
8
+ import { createHash } from "node:crypto";
9
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
10
+ import path from "node:path";
11
+ import { z } from "zod";
12
+ import { stateDir } from "./local.ts";
13
+
14
+ export const STATES = ["success", "failure", "pending", "error"] as const;
15
+
16
+ export type State = (typeof STATES)[number];
17
+
18
+ export type NotifyEvent = {
19
+ event: "shepherd.state";
20
+ repo: string;
21
+ pr: number;
22
+ url: string;
23
+ head_sha: string;
24
+ state: State;
25
+ description: string;
26
+ };
27
+
28
+ /** States that notify unless SHEPHERD_NOTIFY_ON says otherwise: done, needs a person, and stopped by an error. */
29
+ export const NOTIFY_DEFAULT: State[] = ["success", "failure", "error"];
30
+
31
+ export function notifyOn(raw: string | undefined): State[] {
32
+ const asked = new Set((raw ?? "").split(",").map((s) => s.trim().toLowerCase()));
33
+ const list = STATES.filter((s) => asked.has(s));
34
+
35
+ return list.length ? list : NOTIFY_DEFAULT;
36
+ }
37
+
38
+ const LABEL: Record<State, string> = { success: "ready to merge", failure: "needs you", pending: "working", error: "stopped" };
39
+
40
+ // Descriptions can quote PR titles, reviewers and bot output; Slack reads <...> as links and mentions (<!channel>).
41
+ export const slackEscape = (t: string) => t.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
42
+
43
+ export const isSlack = (url: string) => url.startsWith("https://hooks.slack.com/services/");
44
+
45
+ export function payload(url: string, e: NotifyEvent): string {
46
+ return JSON.stringify(isSlack(url) ? { text: `*shepherd ${LABEL[e.state]}* <${e.url}|${e.repo}#${e.pr}>\n${slackEscape(e.description)}` } : e);
47
+ }
48
+
49
+ export type Sent = "sent" | "unchanged" | "off" | "failed";
50
+
51
+ /** Where the last delivered (or deliberately skipped) state is kept. Written only after it is settled. */
52
+ export type Ledger = { read(): string | null; write(token: string): void };
53
+
54
+ const token = (e: NotifyEvent) => createHash("sha256").update(`${e.state}\n${e.description}`).digest("hex").slice(0, 16);
55
+
56
+ /** A file under the git directory: survives a local /loop across heads. */
57
+ export function fileLedger(repoRoot: string, pr: number): Ledger {
58
+ // Resolved on use: outside a repository, read and write throw and notify treats that as no record.
59
+ const file = () => path.join(stateDir(repoRoot), `notified-${pr}`);
60
+
61
+ return {
62
+ read: () => (existsSync(file()) ? readFileSync(file(), "utf8").trim() : null),
63
+ write: (t) => {
64
+ mkdirSync(path.dirname(file()), { recursive: true });
65
+ writeFileSync(file(), t);
66
+ },
67
+ };
68
+ }
69
+
70
+ const Statuses = z.array(z.object({ context: z.string(), description: z.string().nullable() }));
71
+
72
+ export const LEDGER_CONTEXT = "shepherd/notify";
73
+
74
+ /**
75
+ * A `shepherd/notify` commit status on the head: survives fresh CI runners, and is separate from the `shepherd`
76
+ * status, so a status that was set but never delivered is retried. GitHub lists statuses newest first.
77
+ */
78
+ export function statusLedger(repo: string, head: string, cwd: string): Ledger {
79
+ const gh = (args: string[]) => execFileSync("gh", args, { cwd, encoding: "utf8", timeout: 15_000 });
80
+
81
+ return {
82
+ read: () => {
83
+ const latest = Statuses.parse(JSON.parse(gh(["api", `repos/${repo}/commits/${head}/statuses?per_page=100`]))).find((st) => st.context === LEDGER_CONTEXT);
84
+
85
+ return /([0-9a-f]{16})$/.exec(latest?.description ?? "")?.[1] ?? null;
86
+ },
87
+ write: (t) => {
88
+ gh(["api", `repos/${repo}/statuses/${head}`, "-f", `context=${LEDGER_CONTEXT}`, "-f", "state=success", "-f", `description=last notified ${t}`]);
89
+ },
90
+ };
91
+ }
92
+
93
+ /**
94
+ * Posts the event when its state is wanted and differs from the last one settled for this PR. A state that is
95
+ * not wanted is settled without a post, so failure → pending → failure tells people twice. A failed post is
96
+ * not settled, so the next call retries it. A ledger that cannot be read or written never stops the call.
97
+ * Never throws.
98
+ */
99
+ export async function notify(url: string | undefined, e: NotifyEvent, on: State[], ledgers: Ledger[], post: typeof fetch = fetch): Promise<Sent> {
100
+ if (!url) return "off";
101
+ const t = token(e);
102
+
103
+ for (const l of ledgers) {
104
+ try {
105
+ if (l.read() === t) return "unchanged";
106
+ } catch {
107
+ // unreadable: treat as not sent
108
+ }
109
+ }
110
+
111
+ const settle = () => {
112
+ for (const l of ledgers) {
113
+ try {
114
+ l.write(t);
115
+ } catch {
116
+ // a repeat next time is better than failing this iteration
117
+ }
118
+ }
119
+ };
120
+
121
+ if (!on.includes(e.state)) {
122
+ settle();
123
+
124
+ return "off";
125
+ }
126
+
127
+ try {
128
+ const res = await post(url, { method: "POST", headers: { "content-type": "application/json" }, body: payload(url, e), signal: AbortSignal.timeout(10_000) });
129
+
130
+ if (!res.ok) return "failed";
131
+ } catch {
132
+ return "failed";
133
+ }
134
+
135
+ settle();
136
+
137
+ return "sent";
138
+ }