opencode-agent-harness 0.0.0-stage → 0.2.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.
Files changed (169) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE +21 -0
  3. package/README.md +590 -2
  4. package/bin/agent-harness.js +3059 -0
  5. package/contrib/global-plugins/README.md +49 -0
  6. package/contrib/global-plugins/harness-freshness.ts +355 -0
  7. package/package.json +48 -4
  8. package/templates/.agents/AGENTS.md +204 -0
  9. package/templates/.agents/features/INDEX.md +10 -0
  10. package/templates/.agents/handoffs/README.md +87 -0
  11. package/templates/.agents/memory/dev-loop.md +59 -0
  12. package/templates/.agents/memory/domain-map.md +29 -0
  13. package/templates/.agents/memory/environments.md +35 -0
  14. package/templates/.agents/memory/flow-map.md +23 -0
  15. package/templates/.agents/memory/history.md +7 -0
  16. package/templates/.agents/memory/locations.md +14 -0
  17. package/templates/.agents/memory/model-routing.md +261 -0
  18. package/templates/.agents/memory/orchestration.md +183 -0
  19. package/templates/.agents/memory/owned-files.md +19 -0
  20. package/templates/.agents/memory/product-principles.md +37 -0
  21. package/templates/.agents/memory/quality-parameters.md +37 -0
  22. package/templates/.agents/memory/stack-versions.md +35 -0
  23. package/templates/.agents/memory/test-design-parameters.md +36 -0
  24. package/templates/.agents/nightly.json +17 -0
  25. package/templates/.agents/qa-plans/README.md +70 -0
  26. package/templates/.agents/qa-runs/README.md +21 -0
  27. package/templates/.agents/reviews/README.md +47 -0
  28. package/templates/.agents/rules/00-operating.md +199 -0
  29. package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
  30. package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
  31. package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
  32. package/templates/.agents/skills/docs/SKILL.md +140 -0
  33. package/templates/.agents/skills/features/SKILL.md +187 -0
  34. package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
  35. package/templates/.agents/skills/handoff/SKILL.md +85 -0
  36. package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
  37. package/templates/.agents/skills/planner/SKILL.md +112 -0
  38. package/templates/.agents/skills/product-manager/SKILL.md +115 -0
  39. package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
  40. package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
  41. package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
  42. package/templates/.agents/skills/system-architect/SKILL.md +42 -0
  43. package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
  44. package/templates/.github/workflows/ci.yml +148 -0
  45. package/templates/.github/workflows/deploy-uat.yml +95 -0
  46. package/templates/.github/workflows/nightly.yml +83 -0
  47. package/templates/.github/workflows/uat-health.yml +41 -0
  48. package/templates/.husky/pre-push +23 -0
  49. package/templates/.ignore +28 -0
  50. package/templates/.opencode/agents/data-engineer.md +37 -0
  51. package/templates/.opencode/agents/devops-engineer.md +37 -0
  52. package/templates/.opencode/agents/diagnostics-expert.md +37 -0
  53. package/templates/.opencode/agents/docs.md +37 -0
  54. package/templates/.opencode/agents/features.md +21 -0
  55. package/templates/.opencode/agents/frontend-engineer.md +37 -0
  56. package/templates/.opencode/agents/handoff.md +21 -0
  57. package/templates/.opencode/agents/mobile-engineer.md +37 -0
  58. package/templates/.opencode/agents/planner.md +34 -0
  59. package/templates/.opencode/agents/product-manager.md +29 -0
  60. package/templates/.opencode/agents/qa-architect.md +27 -0
  61. package/templates/.opencode/agents/qa-runner.md +17 -0
  62. package/templates/.opencode/agents/security-engineer.md +37 -0
  63. package/templates/.opencode/agents/system-architect.md +37 -0
  64. package/templates/.opencode/agents/ui-designer.md +37 -0
  65. package/templates/.opencode/commands/board.md +15 -0
  66. package/templates/.opencode/commands/checkpoint.md +25 -0
  67. package/templates/.opencode/commands/feature.md +56 -0
  68. package/templates/.opencode/commands/finish.md +36 -0
  69. package/templates/.opencode/commands/next.md +49 -0
  70. package/templates/.opencode/commands/report.md +55 -0
  71. package/templates/.opencode/commands/resume.md +39 -0
  72. package/templates/.opencode/commands/switch-model.md +34 -0
  73. package/templates/.opencode/commands/tidy.md +49 -0
  74. package/templates/.opencode/plugins/backlog-notify.ts +57 -0
  75. package/templates/.opencode/plugins/backlog.ts +272 -0
  76. package/templates/.opencode/plugins/checkpoint.ts +160 -0
  77. package/templates/.opencode/plugins/context-guard.ts +1164 -0
  78. package/templates/.opencode/plugins/diff.ts +85 -0
  79. package/templates/.opencode/plugins/gates.ts +71 -0
  80. package/templates/.opencode/plugins/job-notify.ts +241 -0
  81. package/templates/.opencode/plugins/orient.ts +67 -0
  82. package/templates/.opencode/plugins/session.ts +89 -0
  83. package/templates/.opencode/plugins/wait.ts +101 -0
  84. package/templates/.opencode/plugins/where.ts +70 -0
  85. package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
  86. package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
  87. package/templates/.vercelignore +16 -0
  88. package/templates/AGENTS.md +27 -0
  89. package/templates/BACKLOG.md +95 -0
  90. package/templates/docs/ci-cd-pipeline.md +81 -0
  91. package/templates/docs/gates.md +128 -0
  92. package/templates/docs/mcp-integrations.md +97 -0
  93. package/templates/docs/mobile-testing.md +555 -0
  94. package/templates/docs/nightly-testing.md +106 -0
  95. package/templates/docs/wsl-optimizations.md +290 -0
  96. package/templates/opencode.json +188 -0
  97. package/templates/scripts/agent-report.js +541 -0
  98. package/templates/scripts/agent-search.sh +117 -0
  99. package/templates/scripts/backlog.js +1864 -0
  100. package/templates/scripts/board-service.sh +207 -0
  101. package/templates/scripts/checkpoint.js +290 -0
  102. package/templates/scripts/finalize.js +277 -0
  103. package/templates/scripts/nightly.js +913 -0
  104. package/templates/scripts/orient.js +514 -0
  105. package/templates/scripts/qa/board-client.js +260 -0
  106. package/templates/scripts/qa/board-lib.js +96 -0
  107. package/templates/scripts/qa/board-sync.js +469 -0
  108. package/templates/scripts/qa/capacity-lib.js +916 -0
  109. package/templates/scripts/qa/check-backlog.js +427 -0
  110. package/templates/scripts/qa/check-capacity.js +85 -0
  111. package/templates/scripts/qa/check-ci-policy.js +164 -0
  112. package/templates/scripts/qa/check-concurrency.js +344 -0
  113. package/templates/scripts/qa/check-dispatch-config.js +296 -0
  114. package/templates/scripts/qa/check-docs.js +284 -0
  115. package/templates/scripts/qa/check-integrate.js +98 -0
  116. package/templates/scripts/qa/check-linger.js +160 -0
  117. package/templates/scripts/qa/check-prefix-stability.js +183 -0
  118. package/templates/scripts/qa/check-product.js +177 -0
  119. package/templates/scripts/qa/check-qa-plan.js +378 -0
  120. package/templates/scripts/qa/check-qa-scripts.js +85 -0
  121. package/templates/scripts/qa/check-quality.js +249 -0
  122. package/templates/scripts/qa/check-test-wiring.js +253 -0
  123. package/templates/scripts/qa/ci-triage.js +346 -0
  124. package/templates/scripts/qa/ci-usage-lib.js +185 -0
  125. package/templates/scripts/qa/ci-wait-lib.js +294 -0
  126. package/templates/scripts/qa/command-classifier.js +552 -0
  127. package/templates/scripts/qa/context-guard-core.js +1618 -0
  128. package/templates/scripts/qa/diff.js +174 -0
  129. package/templates/scripts/qa/feature-scaffold.js +224 -0
  130. package/templates/scripts/qa/fixtures/backlog.md +104 -0
  131. package/templates/scripts/qa/governance.js +174 -0
  132. package/templates/scripts/qa/hash-file.js +32 -0
  133. package/templates/scripts/qa/lease-lib.js +263 -0
  134. package/templates/scripts/qa/merge-backlog.js +324 -0
  135. package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
  136. package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
  137. package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
  138. package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
  139. package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
  140. package/templates/scripts/qa/mobile-e2e/check-flows.js +453 -0
  141. package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
  142. package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
  143. package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
  144. package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
  145. package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
  146. package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
  147. package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
  148. package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
  149. package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
  150. package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
  151. package/templates/scripts/qa/models.allowlist.txt +32 -0
  152. package/templates/scripts/qa/provider-stats.js +878 -0
  153. package/templates/scripts/qa/run-clean.js +83 -0
  154. package/templates/scripts/qa/run-gates.js +212 -0
  155. package/templates/scripts/qa/run-loop.js +220 -0
  156. package/templates/scripts/qa/session-recon.js +512 -0
  157. package/templates/scripts/qa/store-lib.js +324 -0
  158. package/templates/scripts/qa/tool-lib.js +134 -0
  159. package/templates/scripts/qa/where.js +214 -0
  160. package/templates/scripts/qa/wslconfig-merge.js +157 -0
  161. package/templates/scripts/serve.js +1328 -0
  162. package/templates/scripts/setup-nightly.sh +185 -0
  163. package/templates/scripts/setup-tmpfs.sh +374 -0
  164. package/templates/scripts/ship.js +586 -0
  165. package/templates/scripts/switch-reasoning-model.ps1 +101 -0
  166. package/templates/scripts/switch-reasoning-model.sh +104 -0
  167. package/templates/scripts/wait-for.js +342 -0
  168. package/templates/scripts/wsl-gpu.sh +180 -0
  169. package/templates/scripts/wsl-tune.sh +261 -0
@@ -0,0 +1,541 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * agent-report — deterministic agent-dispatch efficiency report.
5
+ *
6
+ * Reads every session handoff (`.agents/handoffs/*.md`, plus the legacy
7
+ * `.agents/memory/handoff.md`) and aggregates the wrap-up dispatch log so a
8
+ * session can answer "why did we spend this inference budget?" without reading
9
+ * every transcript. No LLM in the loop — pure Node, deterministic.
10
+ *
11
+ * Aggregates: dispatches per feature / persona / model, recorded retries,
12
+ * recorded escalations, structured session metadata (work_type / outcome /
13
+ * termination_reason / checkpoint_count), and a per-feature trace (`--json`).
14
+ * Token/cost is intentionally NOT fabricated here — the handoff records dispatch
15
+ * intent, not per-token telemetry. With `--cost` the observed provider data
16
+ * (opencode store, via `scripts/qa/provider-stats.js`) is joined in through the
17
+ * handoff `session:` metadata, giving cost per feature / per shipped feature.
18
+ *
19
+ * Usage:
20
+ * node scripts/agent-report.js # human-readable report
21
+ * node scripts/agent-report.js --json # machine-readable trace
22
+ * node scripts/agent-report.js --cost --since=14d # + observed provider cost
23
+ * node scripts/agent-report.js --cost --export provider.json # write fixture
24
+ * node scripts/agent-report.js --cost --fixture provider.json # read fixture
25
+ */
26
+
27
+ const fs = require("fs");
28
+ const path = require("path");
29
+
30
+ const root = path.resolve(__dirname, "..");
31
+
32
+ function parseArgs(argv) {
33
+ const out = {
34
+ json: false,
35
+ cost: false,
36
+ since: null,
37
+ fixture: null,
38
+ exportFile: null,
39
+ opencode: null,
40
+ root,
41
+ };
42
+ for (let i = 0; i < argv.length; i++) {
43
+ const a = argv[i];
44
+ if (a === "--json") out.json = true;
45
+ else if (a === "--cost") out.cost = true;
46
+ else if (a === "--since") out.since = argv[++i];
47
+ else if (a.startsWith("--since=")) out.since = a.slice("--since=".length);
48
+ else if (a === "--fixture") out.fixture = argv[++i];
49
+ else if (a === "--export") out.exportFile = argv[++i];
50
+ else if (a === "--opencode") out.opencode = argv[++i];
51
+ else if (a === "--root") out.root = argv[++i];
52
+ }
53
+ return out;
54
+ }
55
+
56
+ const args = parseArgs(process.argv.slice(2));
57
+ const json = args.json;
58
+
59
+ /* All handoff files: every `.md` under `.agents/handoffs/` (recursive), plus the
60
+ * legacy single `.agents/memory/handoff.md` if present. `README.md` files are
61
+ * documentation, not handoffs, so they are skipped. Sorted for deterministic
62
+ * output (mirrors scripts/qa/governance.js). */
63
+ function handoffFiles() {
64
+ const files = [];
65
+ const collect = (dir) => {
66
+ if (!fs.existsSync(dir)) return;
67
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
68
+ const abs = path.join(dir, entry.name);
69
+ if (entry.isDirectory()) collect(abs);
70
+ else if (
71
+ entry.name.toLowerCase().endsWith(".md") &&
72
+ entry.name.toLowerCase() !== "readme.md"
73
+ )
74
+ files.push(abs);
75
+ }
76
+ };
77
+ collect(path.join(root, ".agents", "handoffs"));
78
+ const legacy = path.join(root, ".agents", "memory", "handoff.md");
79
+ if (fs.existsSync(legacy)) files.push(legacy);
80
+ return files.sort();
81
+ }
82
+
83
+ /* Extract the body of a `## <heading>` section (until the next heading).
84
+ * A trailing qualifier is allowed (`## Session metadata (structured — ...)`
85
+ * is the template heading), so both bare and suffixed forms parse. */
86
+ function section(src, heading) {
87
+ const re = new RegExp("^#{1,6}\\s*" + heading + "\\b.*$", "im");
88
+ const m = src.match(re);
89
+ if (!m) return "";
90
+ const after = src.slice(m.index + m[0].length);
91
+ const tail = after.match(/^#{1,6}\s/m);
92
+ return (tail ? after.slice(0, tail.index) : after).trim();
93
+ }
94
+
95
+ /* Strip surrounding backticks / whitespace and normalize a "(per routing)"
96
+ * placeholder to "?" (the handoff did not record a concrete model). */
97
+ function cleanCell(s) {
98
+ return String(s == null ? "" : s).replace(/^`+|`+$/g, "").trim();
99
+ }
100
+ function normModel(s) {
101
+ const m = cleanCell(s);
102
+ return m && !/^\(per routing\)$/i.test(m) ? m : "?";
103
+ }
104
+
105
+ /* Parse dispatch-log entries. Accepted shapes (mirror governance.js, plus the
106
+ * table variants seen in the wild):
107
+ * bullet: - <persona> -> <model> -> <shipped/deferred>
108
+ * table: | subagent | model | shipped/deferred | (header + separator)
109
+ * table: | # | Subagent | Model | Shipped | Deferred | (indexed table)
110
+ * Tables are parsed by their HEADER row, so column order never matters. */
111
+ function parseDispatchEntries(sectionText) {
112
+ const entries = [];
113
+ const lines = sectionText.split(/\r?\n/);
114
+ let header = null;
115
+ let seenSeparator = false;
116
+
117
+ for (const raw of lines) {
118
+ const line = raw.trim();
119
+ if (!line) continue;
120
+
121
+ // bullet form: - persona -> model -> status
122
+ const bullet = line.match(/^[-*]\s+(.+?)\s*->\s*([^\s>]+)\s*->\s*(.+)$/);
123
+ if (bullet) {
124
+ entries.push({ persona: cleanCell(bullet[1]), model: normModel(bullet[2]), status: bullet[3].trim() });
125
+ continue;
126
+ }
127
+
128
+ // table form
129
+ if (/^\|.*\|$/.test(line)) {
130
+ if (/^\|(\s*:?-+:?\s*\|)+\s*$/.test(line)) {
131
+ seenSeparator = true;
132
+ continue;
133
+ }
134
+ const cells = line.slice(1, -1).split("|").map((c) => c.trim());
135
+ if (!header) {
136
+ // First data-looking row is the header: map column roles by keyword.
137
+ header = cells.map((c, idx) => ({ idx, text: c.toLowerCase() }));
138
+ continue;
139
+ }
140
+ if (!seenSeparator) continue;
141
+ const findIdx = (re) => header.findIndex((h) => re.test(h.text));
142
+ const modelIdx = findIdx(/model/);
143
+ const statusIdx = findIdx(/shipped|deferred|status/);
144
+ let personaIdx = findIdx(/subagent|persona|agent/);
145
+ if (personaIdx === -1) {
146
+ // No named persona column: first column that isn't a bare `#` index and
147
+ // isn't the model/status column.
148
+ personaIdx = cells.findIndex((c, i) => c && !/^#?$/.test(c) && i !== modelIdx && i !== statusIdx);
149
+ }
150
+ if (personaIdx === -1 || !cells[personaIdx]) continue;
151
+ entries.push({
152
+ persona: cleanCell(cells[personaIdx]),
153
+ model: modelIdx !== -1 ? normModel(cells[modelIdx]) : "?",
154
+ status: statusIdx !== -1 ? cells[statusIdx] : "shipped",
155
+ });
156
+ }
157
+ }
158
+ return entries;
159
+ }
160
+
161
+ /* Parse a bulleted list section (`## Retries` / `## Escalations`) into strings. */
162
+ function parseListItems(sectionText) {
163
+ const items = [];
164
+ for (const raw of sectionText.split(/\r?\n/)) {
165
+ const line = raw.trim();
166
+ if (/^[-*]\s+\S/.test(line)) items.push(line.replace(/^[-*]\s+/, "").trim());
167
+ }
168
+ return items;
169
+ }
170
+
171
+ /* Parse the `## Session metadata` block: bullet `- key: value` lines into a
172
+ * plain object. Values are kept verbatim (never normalized/inferred); absent
173
+ * keys stay undefined so "not recorded" is distinguishable from "unknown". */
174
+ function parseSessionMetadata(sectionText) {
175
+ const meta = {};
176
+ for (const raw of sectionText.split(/\r?\n/)) {
177
+ const m = raw.trim().match(/^[-*]\s+([a-z_]+)\s*:\s*(.+)$/i);
178
+ if (m) meta[m[1].toLowerCase()] = m[2].trim();
179
+ }
180
+ return meta;
181
+ }
182
+
183
+ /* Controlled vocabularies (mirror .agents/skills/handoff/SKILL.md). */
184
+ const WORK_TYPES = [
185
+ "feature", "bugfix", "investigation", "architecture", "planning", "qa",
186
+ "security", "maintenance", "process", "conversation", "other",
187
+ ];
188
+ const OUTCOMES = [
189
+ "shipped", "resolved", "deferred", "investigation-complete", "abandoned",
190
+ "superseded", "conversation-only",
191
+ ];
192
+
193
+ const files = handoffFiles();
194
+
195
+ if (files.length === 0) {
196
+ console.log("No handoffs found under .agents/handoffs/ — nothing to report.");
197
+ process.exit(0);
198
+ }
199
+
200
+ const perFeature = {};
201
+ const personaCount = {};
202
+ const modelCount = {};
203
+ const workTypeCount = {};
204
+ const outcomeCount = {};
205
+ const terminationCount = {};
206
+ const VALIDATION_WARNINGS = [];
207
+ let totalDispatches = 0;
208
+ let totalRetries = 0;
209
+ let totalEscalations = 0;
210
+ let totalCheckpoints = 0;
211
+
212
+ function bump(map, key) {
213
+ if (!key) return;
214
+ map[key] = (map[key] || 0) + 1;
215
+ }
216
+
217
+ for (const file of files) {
218
+ const src = fs.readFileSync(file, "utf8");
219
+ const feature = path.basename(file, ".md");
220
+ const entries = parseDispatchEntries(section(src, "Dispatch log"));
221
+ const retries = parseListItems(section(src, "Retries"));
222
+ const escalations = parseListItems(section(src, "Escalations"));
223
+ const meta = parseSessionMetadata(section(src, "Session metadata"));
224
+
225
+ perFeature[feature] = { dispatches: entries, retries, escalations, meta };
226
+ totalRetries += retries.length;
227
+ totalEscalations += escalations.length;
228
+
229
+ const workType = meta.work_type;
230
+ const outcome = meta.outcome;
231
+ const termination = meta.termination_reason;
232
+ if (workType && !WORK_TYPES.includes(workType))
233
+ VALIDATION_WARNINGS.push(`${feature}: metadata work_type \`${workType}\` is not in the controlled vocabulary`);
234
+ if (outcome && !OUTCOMES.includes(outcome))
235
+ VALIDATION_WARNINGS.push(`${feature}: metadata outcome \`${outcome}\` is not in the controlled vocabulary`);
236
+ bump(workTypeCount, workType);
237
+ bump(outcomeCount, outcome);
238
+ bump(terminationCount, termination);
239
+ const checkpoints = parseInt(meta.checkpoint_count, 10);
240
+ if (!Number.isNaN(checkpoints)) totalCheckpoints += checkpoints;
241
+
242
+ for (const e of entries) {
243
+ totalDispatches += 1;
244
+ personaCount[e.persona] = (personaCount[e.persona] || 0) + 1;
245
+ modelCount[e.model] = (modelCount[e.model] || 0) + 1;
246
+ }
247
+ }
248
+
249
+ /* Deterministic, defensible suggestions only — never a speculative "could have".
250
+ * Fan-out / repeated-dispatch thresholds mirror .agents/memory/orchestration.md
251
+ * (5+ dispatches = planner justification, 8+ = explicit fan-out review). */
252
+ const FAN_OUT_REVIEW = 8;
253
+ const FAN_OUT_JUSTIFY = 5;
254
+ const suggestions = [];
255
+ for (const [feature, f] of Object.entries(perFeature)) {
256
+ const seen = new Set();
257
+ let duplicates = 0;
258
+ for (const e of f.dispatches) {
259
+ if (seen.has(e.persona)) duplicates += 1;
260
+ seen.add(e.persona);
261
+ }
262
+ if (duplicates > 0) {
263
+ suggestions.push(
264
+ `${feature}: ${duplicates} duplicate persona dispatch(es) — absorb-before-spawn candidate`
265
+ );
266
+ }
267
+ if (f.dispatches.length >= FAN_OUT_REVIEW) {
268
+ suggestions.push(
269
+ `${feature}: ${f.dispatches.length} dispatches (\u2265${FAN_OUT_REVIEW}) — requires explicit fan-out review (see orchestration.md)`
270
+ );
271
+ } else if (f.dispatches.length >= FAN_OUT_JUSTIFY) {
272
+ suggestions.push(
273
+ `${feature}: ${f.dispatches.length} dispatches (\u2265${FAN_OUT_JUSTIFY}) — planner should carry decomposition justification`
274
+ );
275
+ }
276
+ const retried = f.retries.filter((r) => /attempt|same|identical|re[- ]?ran/i.test(r));
277
+ if (retried.length >= 2) {
278
+ suggestions.push(
279
+ `${feature}: ${retried.length} retries with no stated change — a retry must change instructions/context/model/decomposition/diagnostics`
280
+ );
281
+ }
282
+ }
283
+
284
+ /* Join observed provider sessions to handoff `session:` metadata: the primary
285
+ * orchestrator session id mapped to its provider group (primary + subagent
286
+ * child sessions) gives real cost per feature / per shipped feature. Handoffs
287
+ * without a recorded session, or whose session is outside the window, are
288
+ * reported as unmatched — never guessed. When a primary session observed on a
289
+ * declared escalation model has no recorded reason (`model_escalation_evidence`
290
+ * metadata or an `## Escalations` bullet), it is flagged — never assumed. */
291
+ function escalationEvidenceOf(f) {
292
+ const meta = f.meta.model_escalation_evidence;
293
+ if (meta && !/^(none|no|n\/a|\?|unknown)$/i.test(meta.trim())) return meta.trim();
294
+ if (f.escalations && f.escalations.length) return f.escalations.join("; ");
295
+ return null;
296
+ }
297
+
298
+ function providerJoin(features, providerStats, escalationIds) {
299
+ const byId = new Map(providerStats.sessions.map((s) => [s.id, s]));
300
+ const groups = providerStats.aggregates.groups || {};
301
+ const byFeature = {};
302
+ let matched = 0;
303
+ for (const [feature, f] of Object.entries(features)) {
304
+ const sid = f.meta.session;
305
+ if (!sid) continue;
306
+ const s = byId.get(sid);
307
+ if (!s) {
308
+ byFeature[feature] = { session: sid, status: "not in provider window" };
309
+ continue;
310
+ }
311
+ let cur = s;
312
+ const seen = new Set();
313
+ while (cur.parentId && byId.has(cur.parentId) && !seen.has(cur.id)) {
314
+ seen.add(cur.id);
315
+ cur = byId.get(cur.parentId);
316
+ }
317
+ const g = groups[cur.id] || { cost: s.cost, turns: s.turns, totalTurns: s.turns, sessions: 1 };
318
+ byFeature[feature] = {
319
+ session: sid,
320
+ rootId: cur.id,
321
+ rootModel: g.rootModel || s.model || null,
322
+ cost: g.cost,
323
+ turns: g.turns,
324
+ totalTurns: g.totalTurns,
325
+ sessions: g.sessions,
326
+ outcome: f.meta.outcome || null,
327
+ escalated: !!escalationIds && escalationIds.has(cur.id),
328
+ escalationEvidence: escalationEvidenceOf(f),
329
+ };
330
+ matched += 1;
331
+ }
332
+ const entries = Object.values(byFeature);
333
+ const successful = entries.filter(
334
+ (h) => typeof h.cost === "number" && (h.outcome === "shipped" || h.outcome === "resolved")
335
+ );
336
+ const shippedCost = successful.reduce((a, h) => a + h.cost, 0);
337
+ const matchedSessions = new Set(entries.map((h) => h.session));
338
+ const roots = providerStats.sessions.filter((s) => !s.parentId || !byId.has(s.parentId));
339
+
340
+ const escalated = Object.entries(byFeature).filter(([, h]) => h.escalated && !h.status);
341
+ const withEvidence = escalated.filter(([, h]) => h.escalationEvidence);
342
+ const withoutEvidence = escalated.filter(([, h]) => !h.escalationEvidence);
343
+ const matchedRoots = new Set(entries.filter((h) => !h.status).map((h) => h.rootId));
344
+ const escalation = {
345
+ models: (providerStats.aggregates.escalation && providerStats.aggregates.escalation.models) || [],
346
+ proSessions: (providerStats.aggregates.escalation && providerStats.aggregates.escalation.count) || 0,
347
+ matchedProSessions: escalated.length,
348
+ withEvidence: withEvidence.length,
349
+ withoutEvidence: withoutEvidence.map(([feature, h]) => ({
350
+ feature,
351
+ model: h.rootModel,
352
+ session: h.rootId,
353
+ })),
354
+ unobservable: ((providerStats.aggregates.escalation && providerStats.aggregates.escalation.rootIds) || []).filter(
355
+ (id) => !matchedRoots.has(id)
356
+ ),
357
+ };
358
+
359
+ return {
360
+ matched,
361
+ handoffsWithSession: Object.values(features).filter((f) => f.meta.session).length,
362
+ unmatchedHandoffs: entries.filter((h) => h.status).length,
363
+ unmatchedSessions: roots.filter((s) => !matchedSessions.has(s.id)).length,
364
+ shippedCount: successful.length,
365
+ shippedCost,
366
+ costPerShippedFeature: successful.length ? shippedCost / successful.length : null,
367
+ escalation,
368
+ byFeature,
369
+ };
370
+ }
371
+
372
+ function sortCounts(obj) {
373
+ return Object.entries(obj).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
374
+ }
375
+
376
+ /* `--cost`: observed provider telemetry, joined to the handoffs. Fails loudly
377
+ * when the store is unreachable instead of printing fabricated numbers. */
378
+ let provider = null;
379
+ if (args.cost) {
380
+ const ps = require("./qa/provider-stats.js");
381
+ const stats = args.fixture
382
+ ? ps.readFixture(args.fixture)
383
+ : ps.collectStats({ root: args.root, since: args.since, opencode: args.opencode });
384
+ const thresholds = ps.readThresholds(args.root);
385
+ const tiers = stats.meta.modelTiers || ps.readModelTiers(args.root);
386
+ const aggregates = ps.aggregateSessions(stats.sessions, {
387
+ stuck: stats.meta.stuck || thresholds.stuck,
388
+ softTurnBudget: stats.meta.softTurnBudget,
389
+ opportunisticModels: tiers.opportunistic,
390
+ escalationModels: tiers.escalation,
391
+ });
392
+ if (args.exportFile) ps.writeFixture(args.exportFile, stats);
393
+ provider = {
394
+ meta: stats.meta,
395
+ aggregates,
396
+ join: providerJoin(perFeature, { sessions: stats.sessions, aggregates }, new Set(aggregates.escalation.rootIds)),
397
+ };
398
+ }
399
+
400
+ if (json) {
401
+ const payload = {
402
+ schema: "agent-report/1",
403
+ features: perFeature,
404
+ personaCount,
405
+ modelCount,
406
+ totalDispatches,
407
+ totalRetries,
408
+ totalEscalations,
409
+ totalCheckpoints,
410
+ workTypeCount,
411
+ outcomeCount,
412
+ terminationCount,
413
+ validationWarnings: VALIDATION_WARNINGS,
414
+ suggestions,
415
+ };
416
+ if (provider) payload.provider = provider;
417
+ console.log(JSON.stringify(payload, null, 2));
418
+ } else {
419
+ console.log("Agent efficiency report\n");
420
+ console.log(`Features (handoffs): ${files.length}`);
421
+ console.log(`Total dispatches: ${totalDispatches}`);
422
+ console.log(`Retries recorded: ${totalRetries}`);
423
+ console.log(`Escalations: ${totalEscalations}`);
424
+ console.log(`Checkpoints: ${totalCheckpoints}\n`);
425
+
426
+ console.log("Work type (recorded):");
427
+ for (const [k, c] of sortCounts(workTypeCount)) console.log(` ${k.padEnd(22)} ${c}`);
428
+ console.log("\nOutcome (recorded):");
429
+ for (const [k, c] of sortCounts(outcomeCount)) console.log(` ${k.padEnd(22)} ${c}`);
430
+ console.log("\nTermination reason (recorded):");
431
+ for (const [k, c] of sortCounts(terminationCount)) console.log(` ${k.padEnd(22)} ${c}`);
432
+
433
+ console.log("\nDispatches by persona:");
434
+ for (const [p, c] of sortCounts(personaCount)) console.log(` ${p.padEnd(22)} ${c}`);
435
+ console.log("\nDispatches by model:");
436
+ for (const [m, c] of sortCounts(modelCount)) console.log(` ${m.padEnd(40)} ${c}`);
437
+
438
+ console.log("\nPer-feature:");
439
+ for (const [feature, f] of Object.entries(perFeature)) {
440
+ const personas = f.dispatches.map((e) => `${e.persona} \u2192 ${e.model}`).join(", ") || "(none)";
441
+ console.log(` ${feature.padEnd(28)} ${f.dispatches.length} dispatch(es): ${personas}`);
442
+ for (const r of f.retries) console.log(` retry: ${r}`);
443
+ for (const e of f.escalations) console.log(` escalation: ${e}`);
444
+ const metaBits = [];
445
+ if (f.meta.work_type) metaBits.push(`work_type: ${f.meta.work_type}`);
446
+ if (f.meta.outcome) metaBits.push(`outcome: ${f.meta.outcome}`);
447
+ if (f.meta.termination_reason) metaBits.push(`termination_reason: ${f.meta.termination_reason}`);
448
+ if (f.meta.checkpoint_count) metaBits.push(`checkpoints: ${f.meta.checkpoint_count}`);
449
+ if (metaBits.length) console.log(` metadata: ${metaBits.join(" · ")}`);
450
+ }
451
+
452
+ if (VALIDATION_WARNINGS.length) {
453
+ console.log("\nValidation warnings (metadata outside the controlled vocabulary):");
454
+ for (const w of VALIDATION_WARNINGS) console.log(` - ${w}`);
455
+ }
456
+
457
+ if (suggestions.length) {
458
+ console.log("\nPotential savings (deterministic heuristics):");
459
+ for (const s of suggestions) console.log(` - ${s}`);
460
+ } else {
461
+ console.log("\nPotential savings: none flagged.");
462
+ }
463
+
464
+ if (provider) {
465
+ const t = provider.aggregates.totals;
466
+ const since = provider.meta.since ? provider.meta.since.arg : "all time";
467
+ console.log(`\nCost telemetry (observed provider data — ${provider.meta.root}, ${since}):`);
468
+ if (t.sessions === 0) {
469
+ console.log(` No provider sessions: ${provider.meta.note || "none in this window"}.`);
470
+ } else {
471
+ console.log(
472
+ ` ${t.sessions} sessions (${t.primarySessions} primary + ${t.subagentSessions} subagent) · ${"$" + t.cost.toFixed(4)} total`
473
+ );
474
+ console.log(
475
+ ` Cache-read share: ${t.cacheReadShare == null ? "n/a" : (t.cacheReadShare * 100).toFixed(1) + "% of input tokens"}` +
476
+ ` · turns/primary P50 ${provider.aggregates.percentiles.primaryTurns.p50 == null ? "n/a" : provider.aggregates.percentiles.primaryTurns.p50}` +
477
+ ` / P90 ${provider.aggregates.percentiles.primaryTurns.p90 == null ? "n/a" : provider.aggregates.percentiles.primaryTurns.p90}`
478
+ );
479
+ console.log(
480
+ ` Primary sessions over ${provider.aggregates.sessionsOverTurnBudget.threshold} turns: ${provider.aggregates.sessionsOverTurnBudget.count}` +
481
+ ` · identical-call loops (>= ${provider.aggregates.loopCandidates.threshold}x): ${provider.aggregates.loopCandidates.count}`
482
+ );
483
+ if (provider.aggregates.resumes) {
484
+ const r = provider.aggregates.resumes;
485
+ const sample = r.sessions.slice(0, 3).map((s) => s.title.slice(0, 40)).join("; ");
486
+ console.log(
487
+ ` Mid-cycle context resets (resume/checkpoint sessions): ${r.count}` + (sample ? ` — ${sample}` : "")
488
+ );
489
+ }
490
+ if (provider.aggregates.topSessions.length) {
491
+ console.log(" Top primary sessions by cost:");
492
+ for (const s of provider.aggregates.topSessions) {
493
+ console.log(` ${("$" + s.cost.toFixed(4)).padStart(10)} ${s.id} ${s.title.slice(0, 50)}`);
494
+ }
495
+ }
496
+ }
497
+ const j = provider.join;
498
+ if (j.handoffsWithSession > 0 || j.unmatchedSessions > 0) {
499
+ console.log(
500
+ ` Session join: ${j.matched}/${j.handoffsWithSession} handoffs with a recorded session matched` +
501
+ (j.unmatchedHandoffs ? ` · ${j.unmatchedHandoffs} outside the provider window` : "") +
502
+ (j.unmatchedSessions ? ` · ${j.unmatchedSessions} primary session(s) with no handoff in window` : "")
503
+ );
504
+ for (const [feature, h] of Object.entries(j.byFeature)) {
505
+ if (h.status) console.log(` ${feature.padEnd(24)} (${h.status})`);
506
+ else
507
+ console.log(
508
+ ` ${feature.padEnd(24)} ${("$" + h.cost.toFixed(4)).padStart(10)} ${h.totalTurns} turn(s) · ${h.sessions} session(s) · outcome: ${h.outcome || "unknown"}`
509
+ );
510
+ }
511
+ console.log(
512
+ ` Cost per shipped feature: ${
513
+ j.costPerShippedFeature == null
514
+ ? "n/a (no shipped/resolved handoff with a session)"
515
+ : "$" + j.costPerShippedFeature.toFixed(4) + " (" + j.shippedCount + " feature(s))"
516
+ }`
517
+ );
518
+ const esc = j.escalation;
519
+ if (esc && esc.proSessions > 0) {
520
+ console.log(
521
+ ` Escalation evidence: ${esc.proSessions} primary session(s) on a pro model (${esc.models.join(", ")}) — ` +
522
+ `${esc.withEvidence} with a recorded reason, ${esc.withoutEvidence.length} without` +
523
+ (esc.unobservable.length ? ` · ${esc.unobservable.length} with no handoff in window` : "")
524
+ );
525
+ for (const u of esc.withoutEvidence)
526
+ console.log(` ${u.feature.padEnd(24)} ${u.model} (no model_escalation_evidence recorded)`);
527
+ }
528
+ }
529
+ }
530
+
531
+ console.log(
532
+ provider
533
+ ? "\nNote: dispatch intent and session metadata are recorded verbatim (absent = not counted,\n" +
534
+ "distinct from `unknown`, which is counted). Cost/token/turn numbers above are observed\n" +
535
+ "provider data from the opencode store — never inferred from text length."
536
+ : "\nNote: token/cost is not fabricated here — the handoff records dispatch intent and\n" +
537
+ "session metadata, not per-token telemetry. Run with --cost to join observed provider\n" +
538
+ "data via the handoff `session:` metadata. Recorded values are verbatim; absent metadata\n" +
539
+ "is simply not counted (distinct from `unknown`, which is counted)."
540
+ );
541
+ }
@@ -0,0 +1,117 @@
1
+ #!/usr/bin/env bash
2
+ #
3
+ # agent-search.sh — thin, ignore-aware ripgrep wrapper for agent workspaces.
4
+ #
5
+ # Why this exists: recursive discovery is run constantly by agents and must stay
6
+ # cheap and deterministic. This wrapper
7
+ # * relies on the canonical ignore files (`.ignore` + `.gitignore`) and NEVER
8
+ # passes --no-ignore / --unrestricted, so node_modules/.git/build trees are
9
+ # skipped by default;
10
+ # * drops lockfiles, minified bundles, source maps, and oversized files
11
+ # (--max-columns / --max-filesize) so one generated 20 MB file can't dominate;
12
+ # * supports `--files` for cheap file discovery (no content is read);
13
+ # * caps output (default 200 lines; override with --limit N or
14
+ # AGENT_SEARCH_LIMIT) so a broad query can't flood an agent's context.
15
+ #
16
+ # Usage:
17
+ # scripts/agent-search.sh <pattern> [paths...] # content search
18
+ # scripts/agent-search.sh --files [path] # list candidate files
19
+ # scripts/agent-search.sh -g '*.ts' <pattern> # extra rg globs pass through
20
+ # scripts/agent-search.sh --limit 50 <pattern>
21
+ # scripts/agent-search.sh --help
22
+ #
23
+ # `git grep` is still preferred for symbol searches over tracked files only (it
24
+ # reads the git index and its file set is exactly the repo's); use this wrapper
25
+ # for generated/untracked-aware content search. See docs/wsl-optimizations.md.
26
+ set -u
27
+
28
+ LIMIT="${AGENT_SEARCH_LIMIT:-200}"
29
+ MAX_FILESIZE="${AGENT_SEARCH_MAX_FILESIZE:-1M}"
30
+ MAX_COLUMNS="${AGENT_SEARCH_MAX_COLUMNS:-300}"
31
+
32
+ usage() {
33
+ sed -n '2,/^set -u$/p' "$0" | sed 's/^# \{0,1\}//; /^set -u$/d'
34
+ }
35
+
36
+ if ! command -v rg >/dev/null 2>&1; then
37
+ echo "agent-search: ripgrep (rg) not found — install it (apt-get install ripgrep)." >&2
38
+ exit 127
39
+ fi
40
+
41
+ FILES_MODE=0
42
+ args=()
43
+ while [ $# -gt 0 ]; do
44
+ case "$1" in
45
+ --files) FILES_MODE=1; shift ;;
46
+ --limit) LIMIT="${2:-200}"; shift 2 ;;
47
+ --limit=*) LIMIT="${1#--limit=}"; shift ;;
48
+ -h | --help)
49
+ usage
50
+ exit 0
51
+ ;;
52
+ --no-ignore | --unrestricted | -u | -U)
53
+ echo "agent-search: refusing '$1' — this wrapper relies on the canonical" >&2
54
+ echo " ignore files; pass an explicit -g glob to add a path back in." >&2
55
+ exit 2
56
+ ;;
57
+ --hidden)
58
+ echo "agent-search: refusing '--hidden' — hidden trees (.next/.cache/.git)" >&2
59
+ echo " are the high-cost ones this wrapper exists to skip." >&2
60
+ exit 2
61
+ ;;
62
+ --)
63
+ shift
64
+ while [ $# -gt 0 ]; do
65
+ args+=("$1")
66
+ shift
67
+ done
68
+ ;;
69
+ *)
70
+ args+=("$1")
71
+ shift
72
+ ;;
73
+ esac
74
+ done
75
+
76
+ if [ "$FILES_MODE" -eq 0 ] && [ "${#args[@]}" -eq 0 ]; then
77
+ echo "agent-search: a pattern is required (or use --files)." >&2
78
+ exit 2
79
+ fi
80
+
81
+ # Lockfiles / minified bundles / maps are noise for an agent reading matches.
82
+ # --hidden is intentionally never used: hidden trees are exactly the expensive
83
+ # ones (build output, caches) we want skipped.
84
+ common=(
85
+ --color=never
86
+ --max-columns="$MAX_COLUMNS"
87
+ --max-columns-preview
88
+ --max-filesize="$MAX_FILESIZE"
89
+ --glob '!package-lock.json'
90
+ --glob '!npm-shrinkwrap.json'
91
+ --glob '!yarn.lock'
92
+ --glob '!pnpm-lock.yaml'
93
+ --glob '!bun.lockb'
94
+ --glob '!Cargo.lock'
95
+ --glob '!poetry.lock'
96
+ --glob '!Pipfile.lock'
97
+ --glob '!composer.lock'
98
+ --glob '!Gemfile.lock'
99
+ --glob '!*.min.js'
100
+ --glob '!*.min.css'
101
+ --glob '!*.map'
102
+ --glob '!*.tsbuildinfo'
103
+ )
104
+
105
+ # Cap the stream with `head`; a broad query is expected to truncate, and the
106
+ # SIGPIPE that gives rg (exit 141) is not an error. Treat 0/1/141 as success.
107
+ set +o pipefail 2>/dev/null || true
108
+ if [ "$FILES_MODE" -eq 1 ]; then
109
+ rg --files "${common[@]}" ${args[@]+"${args[@]}"} | head -n "$LIMIT"
110
+ else
111
+ rg "${common[@]}" ${args[@]+"${args[@]}"} | head -n "$LIMIT"
112
+ fi
113
+ rc=${PIPESTATUS[0]:-0}
114
+ case "$rc" in
115
+ 0 | 1 | 141) exit 0 ;;
116
+ *) exit "$rc" ;;
117
+ esac