opencode-agent-harness 0.0.0-stage → 0.3.14

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 (171) hide show
  1. package/CHANGELOG.md +217 -0
  2. package/LICENSE +21 -0
  3. package/README.md +636 -2
  4. package/bin/agent-harness.js +3182 -0
  5. package/contrib/global-plugins/README.md +49 -0
  6. package/contrib/global-plugins/harness-freshness.ts +355 -0
  7. package/package.json +86 -4
  8. package/templates/.agents/AGENTS.md +148 -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 +1924 -0
  100. package/templates/scripts/board-service.sh +214 -0
  101. package/templates/scripts/checkpoint.js +290 -0
  102. package/templates/scripts/finalize.js +416 -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 +323 -0
  106. package/templates/scripts/qa/board-lib.js +96 -0
  107. package/templates/scripts/qa/board-sync.js +499 -0
  108. package/templates/scripts/qa/capacity-lib.js +916 -0
  109. package/templates/scripts/qa/check-backlog.js +434 -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 +288 -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 +187 -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/check-worktrees.js +93 -0
  124. package/templates/scripts/qa/ci-triage.js +346 -0
  125. package/templates/scripts/qa/ci-usage-lib.js +185 -0
  126. package/templates/scripts/qa/ci-wait-lib.js +294 -0
  127. package/templates/scripts/qa/command-classifier.js +552 -0
  128. package/templates/scripts/qa/context-guard-core.js +1618 -0
  129. package/templates/scripts/qa/diff.js +174 -0
  130. package/templates/scripts/qa/feature-scaffold.js +224 -0
  131. package/templates/scripts/qa/fixtures/backlog.md +104 -0
  132. package/templates/scripts/qa/governance.js +174 -0
  133. package/templates/scripts/qa/hash-file.js +32 -0
  134. package/templates/scripts/qa/lease-lib.js +263 -0
  135. package/templates/scripts/qa/merge-backlog.js +324 -0
  136. package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
  137. package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
  138. package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
  139. package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
  140. package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
  141. package/templates/scripts/qa/mobile-e2e/check-flows.js +568 -0
  142. package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
  143. package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
  144. package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
  145. package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
  146. package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
  147. package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
  148. package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
  149. package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
  150. package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
  151. package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
  152. package/templates/scripts/qa/models.allowlist.txt +32 -0
  153. package/templates/scripts/qa/provider-stats.js +878 -0
  154. package/templates/scripts/qa/run-clean.js +83 -0
  155. package/templates/scripts/qa/run-gates.js +213 -0
  156. package/templates/scripts/qa/run-loop.js +220 -0
  157. package/templates/scripts/qa/session-recon.js +512 -0
  158. package/templates/scripts/qa/store-lib.js +324 -0
  159. package/templates/scripts/qa/tool-lib.js +134 -0
  160. package/templates/scripts/qa/where.js +214 -0
  161. package/templates/scripts/qa/worktree-hygiene.js +217 -0
  162. package/templates/scripts/qa/wslconfig-merge.js +157 -0
  163. package/templates/scripts/serve.js +1328 -0
  164. package/templates/scripts/setup-nightly.sh +185 -0
  165. package/templates/scripts/setup-tmpfs.sh +374 -0
  166. package/templates/scripts/ship.js +586 -0
  167. package/templates/scripts/switch-reasoning-model.ps1 +101 -0
  168. package/templates/scripts/switch-reasoning-model.sh +104 -0
  169. package/templates/scripts/wait-for.js +342 -0
  170. package/templates/scripts/wsl-gpu.sh +180 -0
  171. package/templates/scripts/wsl-tune.sh +319 -0
@@ -0,0 +1,85 @@
1
+ import type { Plugin } from "@opencode/plugin"
2
+ import toolLib from "../../scripts/qa/tool-lib.js"
3
+
4
+ // `diff` — a bounded change view. The 2026-10-16 field review found the thinker
5
+ // personas (qa-architect/planner/system-architect) have no shell and no diff
6
+ // capability: qa-architect logged 799 `Read` / 132 `Grep` / 0 bash and 10
7
+ // `Maximum steps` truncations, because "inspect the diff" is done by mass-reading
8
+ // whole files. This returns the changed paths + hunks in ONE bounded call
9
+ // (`--limit` lines, default 400), and lists untracked files. Prefer it over
10
+ // shell `git diff` and over reading a file to see what changed.
11
+ //
12
+ // V2: registered from a plugin via `ctx.tool.transform`; the launch directory is
13
+ // captured in `setup` and paired with the call's sessionID for the sessionRoot
14
+ // reroot (same pairing as `where`/`gates`).
15
+
16
+ export default {
17
+ id: "diff-tools",
18
+ async setup(ctx) {
19
+ const directory = ctx.location.directory
20
+ const h = (context: any) => ({
21
+ directory,
22
+ sessionID: context?.sessionID,
23
+ agent: context?.agent,
24
+ })
25
+ await ctx.tool.transform((editor) => {
26
+ editor.add({
27
+ name: "diff",
28
+ description:
29
+ "Show the current change as a bounded diff (changed paths + hunks, capped at --limit lines; untracked files listed). Defaults to the working tree vs HEAD. Use it to inspect a change instead of reading whole files or shelling out to `git diff`. Modes: default (hunks), stat (numstat summary), files (name-status list). Options: staged, base <ref>, paths <a,b>, unified <n>.",
30
+ input: {
31
+ type: "object",
32
+ properties: {
33
+ base: {
34
+ type: "string",
35
+ description: "diff against this ref instead of HEAD (e.g. origin/main, a feature branch, a SHA)",
36
+ },
37
+ staged: {
38
+ type: "boolean",
39
+ description: "diff the staged (index) changes only (`git diff --cached`)",
40
+ },
41
+ paths: {
42
+ type: "string",
43
+ description: "comma/space-separated path scope (else the whole change)",
44
+ },
45
+ stat: {
46
+ type: "boolean",
47
+ description: "summary only (`git diff --stat`) — cheapest for a large change",
48
+ },
49
+ files: {
50
+ type: "boolean",
51
+ description: "changed paths + status only (name-status)",
52
+ },
53
+ unified: {
54
+ type: "number",
55
+ description: "context lines per hunk (default 3, max 50)",
56
+ },
57
+ limit: {
58
+ type: "number",
59
+ description: "max output lines (default 400)",
60
+ },
61
+ },
62
+ required: [],
63
+ additionalProperties: false,
64
+ },
65
+ async execute(input, context) {
66
+ const helper = h(context)
67
+ const argv = ["--root", toolLib.sessionRoot(helper, "")]
68
+ if (input.base) argv.push("--base", String(input.base))
69
+ if (input.staged) argv.push("--staged")
70
+ if (input.paths) argv.push("--paths", String(input.paths))
71
+ if (input.stat) argv.push("--stat")
72
+ if (input.files) argv.push("--files")
73
+ if (input.unified) argv.push("--unified", String(input.unified))
74
+ if (input.limit) argv.push("--limit", String(input.limit))
75
+ return {
76
+ content: toolLib.runScript(helper, "scripts/qa/diff.js", argv, {
77
+ label: "diff",
78
+ timeout: 30000,
79
+ }),
80
+ }
81
+ },
82
+ })
83
+ })
84
+ },
85
+ } satisfies Plugin
@@ -0,0 +1,71 @@
1
+ import type { Plugin } from "@opencode/plugin"
2
+ import toolLib from "../../scripts/qa/tool-lib.js"
3
+
4
+ // `gates` — run the harness gate battery as one call. The 2026-10 LibraryOS
5
+ // recon measured ~700 individual gate invocations in 14 days (tsc 125,
6
+ // test:quick 120, test:qa-plan 50 …): each a separate tool round-trip with its
7
+ // own banner. This runs a phase in order, stops at the first failure, and
8
+ // returns a compact PASS/FAIL summary. It wraps scripts/qa/run-gates.js, the
9
+ // SAME list the pre-push hook runs (`--phase=pre-push`), so the two can never
10
+ // drift. A gate the project has not wired is skipped, never failed.
11
+ //
12
+ // Async (runScriptAsync): a full battery can run minutes, and a synchronous
13
+ // execFileSync would freeze opencode's event loop the way the old `wait` did.
14
+ //
15
+ // V2: registered from a plugin via `ctx.tool.transform`. The executor context has
16
+ // no `directory`/`worktree`, so the launch directory is captured in `setup` and
17
+ // paired with the call's sessionID for tool-lib's sessionRoot reroot.
18
+
19
+ export default {
20
+ id: "gates-tools",
21
+ async setup(ctx) {
22
+ const directory = ctx.location.directory
23
+ const h = (context: any) => ({
24
+ directory,
25
+ sessionID: context?.sessionID,
26
+ agent: context?.agent,
27
+ })
28
+ await ctx.tool.transform((editor) => {
29
+ editor.add({
30
+ name: "gates",
31
+ description:
32
+ "Run the harness gate battery in one call: phases pre-push (process + quick), process (dispatch/governance/concurrency/capacity/backlog/wiring/integrate/qa-plan/product/docs/quality), quick (lint:hooks/test:schema/test:quick), or all. Stops at the first failure by default and prints a compact per-gate PASS/FAIL summary. Use it instead of running the gates one shell command at a time. Unwired gates are skipped, never failed.",
33
+ input: {
34
+ type: "object",
35
+ properties: {
36
+ phase: {
37
+ type: "string",
38
+ enum: ["pre-push", "process", "quick", "all"],
39
+ description: "which gate phase to run (default pre-push)",
40
+ },
41
+ base: {
42
+ type: "string",
43
+ description: "base ref for the diff-scoped gates (default origin/main)",
44
+ },
45
+ continueOnError: {
46
+ type: "boolean",
47
+ description: "run every gate even after one fails (default false)",
48
+ },
49
+ },
50
+ required: [],
51
+ additionalProperties: false,
52
+ },
53
+ async execute(input, context) {
54
+ const helper = h(context)
55
+ const argv = ["--root", toolLib.sessionRoot(helper, "")]
56
+ if (input.phase) argv.push("--phase", input.phase)
57
+ if (input.base) argv.push("--base", input.base)
58
+ if (input.continueOnError) argv.push("--continue")
59
+ const res = await toolLib.runScriptAsync(helper, "scripts/qa/run-gates.js", argv, {
60
+ label: "gates",
61
+ timeout: 45 * 60 * 1000,
62
+ })
63
+ if (res.error) return { content: `${res.error}\n${res.stderr || ""}`.trim() }
64
+ const body = (res.stdout || "").trim()
65
+ const tail = (res.stderr || "").trim()
66
+ return { content: [body, tail].filter(Boolean).join("\n") || `gates: exit ${res.code}` }
67
+ },
68
+ })
69
+ })
70
+ },
71
+ } satisfies Plugin
@@ -0,0 +1,241 @@
1
+ import type { Plugin } from "@opencode/plugin"
2
+ import fs from "node:fs"
3
+ import jobEvents from "../../scripts/qa/mobile-e2e/job-events.js"
4
+
5
+ // Turns a detached mobile-E2E run into a PUSH, not a poll. The agent launches
6
+ // `run-detached.sh` (which writes a job record + a JSONL progress stream) and
7
+ // then gets on with its work; this plugin tails that stream and:
8
+ // * logs progress per scenario (live progress, no LLM turn and no re-billed
9
+ // context), and
10
+ // * wakes the owning session via `session.prompt` on the FIRST failure (so it
11
+ // can react early) and again when the matrix finishes.
12
+ // `--wait` launches are skipped: there the agent blocks and streams the same
13
+ // lines itself. Everything is best-effort — the notifier must never break a
14
+ // session, a launch, or an unrelated tool call.
15
+
16
+ const TICK_MS = 3000
17
+ const MAX_WATCH_MS = 3 * 60 * 60 * 1000
18
+ const LAUNCH_RE = /run-detached\.sh|run-maestro\.js/
19
+
20
+ type Watch = {
21
+ sessionID: string
22
+ events: string
23
+ record: string | null
24
+ lastLine: number
25
+ failureNotified: boolean
26
+ stalledNotified: boolean
27
+ doneNotified: boolean
28
+ startedAt: number
29
+ timer: ReturnType<typeof setInterval>
30
+ }
31
+
32
+ function pathFrom(text: string, label: string): string | null {
33
+ const m = String(text || "").match(new RegExp(label + ":\\s*(\\S+)"))
34
+ return m ? m[1] : null
35
+ }
36
+
37
+ function alive(pid: unknown): boolean {
38
+ const n = Number(pid)
39
+ if (!Number.isFinite(n) || n <= 0) return true // unknown -> assume running
40
+ try {
41
+ process.kill(n, 0)
42
+ return true
43
+ } catch (err: any) {
44
+ return err && err.code === "EPERM"
45
+ }
46
+ }
47
+
48
+ const JobNotify: Plugin = {
49
+ id: "job-notify",
50
+ async setup(ctx) {
51
+ const pending = new Map<string, number>()
52
+ const watches = new Map<string, Watch>()
53
+
54
+ // V1 called `client.app.log`; V2 server plugins log to the console.
55
+ const report = (message: string, level: "info" | "warn" | "error" = "info") => {
56
+ const line = `job-notify: ${message}`
57
+ if (level === "error") console.error(line)
58
+ else if (level === "warn") console.warn(line)
59
+ else console.log(line)
60
+ }
61
+
62
+ // Wake an idle session with a real message so it resumes on its own.
63
+ const wake = async (sessionID: string, text: string) => {
64
+ try {
65
+ await ctx.session.prompt({ sessionID, text })
66
+ } catch (err: any) {
67
+ report(`could not notify session ${sessionID}: ${err?.message || err}`, "warn")
68
+ }
69
+ }
70
+
71
+ const stopWatch = (key: string, reason: string) => {
72
+ const w = watches.get(key)
73
+ if (!w) return
74
+ clearInterval(w.timer)
75
+ watches.delete(key)
76
+ report(`stopped watching ${w.events} (${reason})`)
77
+ }
78
+
79
+ const startWatch = (sessionID: string, events: string, record: string | null) => {
80
+ const key = events
81
+ if (watches.has(key)) return
82
+ const w: Watch = {
83
+ sessionID,
84
+ events,
85
+ record,
86
+ lastLine: 0,
87
+ failureNotified: false,
88
+ stalledNotified: false,
89
+ doneNotified: false,
90
+ startedAt: Date.now(),
91
+ timer: null as any,
92
+ }
93
+ w.timer = setInterval(() => void tick(key), TICK_MS)
94
+ if (typeof (w.timer as any)?.unref === "function") (w.timer as any).unref()
95
+ watches.set(key, w)
96
+ report(`watching ${events} for session ${sessionID}`)
97
+ void tick(key)
98
+ }
99
+
100
+ const readRecord = (w: Watch): any => {
101
+ if (!w.record) return null
102
+ try {
103
+ return JSON.parse(fs.readFileSync(w.record, "utf8"))
104
+ } catch {
105
+ return null
106
+ }
107
+ }
108
+
109
+ const tick = async (key: string) => {
110
+ const w = watches.get(key)
111
+ if (!w) return
112
+ try {
113
+ if (Date.now() - w.startedAt > MAX_WATCH_MS) {
114
+ stopWatch(key, "watch timeout")
115
+ return
116
+ }
117
+ const events = jobEvents.readEvents(w.events)
118
+ const fresh = events.slice(w.lastLine)
119
+ if (fresh.length > 0) {
120
+ w.lastLine = events.length
121
+ for (const event of fresh) {
122
+ const line = jobEvents.progressLine(event)
123
+ if (!line) continue
124
+ const failed = event.type === "flow_result" && event.status !== "pass"
125
+ const stalled = event.type === "invocation_stalled"
126
+ // A heartbeat proves liveness to the log/wait stream; reporting it
127
+ // without extra ceremony keeps the log quiet.
128
+ if (event.type === "invocation_heartbeat") {
129
+ report(line, "info")
130
+ continue
131
+ }
132
+ report(line, failed || stalled ? "warn" : "info")
133
+ }
134
+ const firstFailure = fresh.find(
135
+ (e: any) => e.type === "flow_result" && e.status !== "pass"
136
+ )
137
+ if (firstFailure && !w.failureNotified) {
138
+ w.failureNotified = true
139
+ await wake(
140
+ w.sessionID,
141
+ jobEvents.notificationText(jobEvents.summarize(events), { eventsPath: w.events })
142
+ )
143
+ }
144
+ const stalled = fresh.find((e: any) => e.type === "invocation_stalled")
145
+ if (stalled && !w.stalledNotified) {
146
+ w.stalledNotified = true
147
+ await wake(
148
+ w.sessionID,
149
+ `Mobile E2E invocation ${stalled.index}/${stalled.total} has produced no output for ` +
150
+ `${Math.round((stalled.msSinceOutput || 0) / 1000)}s — possible hang.\n` +
151
+ `Stop it deterministically: scripts/qa/mobile-e2e/run-detached.sh --stop <job-id>\n` +
152
+ `Events: ${w.events}`
153
+ )
154
+ }
155
+ const aborted = fresh.find((e: any) => e.type === "matrix_aborted")
156
+ if (aborted) {
157
+ await wake(
158
+ w.sessionID,
159
+ jobEvents.notificationText(jobEvents.summarize(events), { eventsPath: w.events })
160
+ )
161
+ stopWatch(key, "matrix aborted")
162
+ return
163
+ }
164
+ const done = fresh.find((e: any) => e.type === "matrix_done")
165
+ if (done) {
166
+ w.doneNotified = true
167
+ await wake(
168
+ w.sessionID,
169
+ jobEvents.notificationText(jobEvents.summarize(events), { eventsPath: w.events })
170
+ )
171
+ stopWatch(key, "matrix done")
172
+ return
173
+ }
174
+ }
175
+ // A crashed runner may never emit matrix_done: fall back to the pid.
176
+ const rec = readRecord(w)
177
+ if (rec && !w.doneNotified && !alive(rec.pid)) {
178
+ w.doneNotified = true
179
+ await wake(
180
+ w.sessionID,
181
+ jobEvents.notificationText(jobEvents.summarize(events), {
182
+ reportPath: jobEvents.summarize(events).reportPath,
183
+ eventsPath: w.events,
184
+ })
185
+ )
186
+ stopWatch(key, "runner exited")
187
+ }
188
+ } catch (err: any) {
189
+ report(`watch tick failed: ${err?.message || err}`, "warn")
190
+ }
191
+ }
192
+
193
+ // V2: the `bash` tool is named `shell`; `event.input` carries the args.
194
+ await ctx.tool.hook("execute.before", (event: any) => {
195
+ try {
196
+ if (String(event?.tool || "").toLowerCase() !== "shell") return
197
+ const command = String(event?.input?.command || "")
198
+ const sid = event?.sessionID
199
+ if (typeof sid !== "string" || sid.length === 0) return
200
+ if (LAUNCH_RE.test(command) && !/--wait\b/.test(command)) {
201
+ pending.set(sid, Date.now())
202
+ }
203
+ } catch {
204
+ /* never break a tool call */
205
+ }
206
+ })
207
+
208
+ await ctx.tool.hook("execute.after", (event: any) => {
209
+ try {
210
+ if (String(event?.tool || "").toLowerCase() !== "shell") return
211
+ const sid = event?.sessionID
212
+ if (typeof sid !== "string" || sid.length === 0) return
213
+ const startedAt = pending.get(sid)
214
+ if (!startedAt || Date.now() - startedAt > 60000) return
215
+ pending.delete(sid)
216
+ const result: any = event?.result
217
+ const text =
218
+ typeof result?.content === "string"
219
+ ? result.content
220
+ : Array.isArray(result?.content)
221
+ ? result.content.map((p: any) => (p && typeof p.text === "string" ? p.text : "")).join("\n")
222
+ : ""
223
+ const blob = `${text}\n${JSON.stringify(result?.metadata || {})}`
224
+ const events = pathFrom(blob, "events")
225
+ if (!events) return
226
+ const record = pathFrom(blob, "record")
227
+ startWatch(sid, events, record)
228
+ } catch {
229
+ /* never break a tool call */
230
+ }
231
+ })
232
+
233
+ // Cleanup: stop every tail timer so an unloaded plugin leaves no interval behind.
234
+ return () => {
235
+ for (const w of watches.values()) clearInterval(w.timer)
236
+ watches.clear()
237
+ }
238
+ },
239
+ }
240
+
241
+ export default JobNotify
@@ -0,0 +1,67 @@
1
+ import type { Plugin } from "@opencode/plugin"
2
+ import toolLib from "../../scripts/qa/tool-lib.js"
3
+
4
+ // `orient` — one call that returns everything a session re-derives by hand at
5
+ // resume/claim time: the tree root + branch + HEAD + dirty count, the feature,
6
+ // the checkpoint, the board rows (In progress + next queued), owned files, the
7
+ // live `serve.js` jobs + capacity verdict, the last device-run summary, and the
8
+ // harness version. The 2026-09 LibraryOS recon measured a single F-291 resume
9
+ // spending 21 orientation calls (`git rev-parse`/`branch`/`status`, memory
10
+ // reads, `serve.js list`, `test:capacity`, checkpoint) before any real work; the
11
+ // exact `git rev-parse --show-toplevel` shape ran 114 times across 103 sessions.
12
+ //
13
+ // Read-only and best-effort: a source that is missing (no checkpoint, no lease,
14
+ // no `.serve/`) is reported `unavailable`, never invented. Node resolution + the
15
+ // mid-session worktree reroot live in scripts/qa/tool-lib.js.
16
+ //
17
+ // V2: registered from a plugin via `ctx.tool.transform`. The executor context has
18
+ // no `directory`/`worktree`, so the launch directory is captured in `setup` and
19
+ // paired with the call's sessionID for tool-lib's sessionRoot reroot.
20
+
21
+ export default {
22
+ id: "orient-tools",
23
+ async setup(ctx) {
24
+ const directory = ctx.location.directory
25
+ const h = (context: any) => ({
26
+ directory,
27
+ sessionID: context?.sessionID,
28
+ agent: context?.agent,
29
+ })
30
+ await ctx.tool.transform((editor) => {
31
+ editor.add({
32
+ name: "orient",
33
+ description:
34
+ "One-call session orientation: git tree/branch/HEAD/dirty, the active feature, its checkpoint (phase + next action), board In-progress + next-queued rows, owned files, live serve jobs + machine-capacity verdict, the last mobile-E2E run, and the harness version. Use it at session start / resume instead of a pile of `git rev-parse`/`status`, `serve.js list`, `test:capacity`, and memory reads. Read-only; missing sources are reported `unavailable`.",
35
+ input: {
36
+ type: "object",
37
+ properties: {
38
+ feature: {
39
+ type: "string",
40
+ description:
41
+ "backlog row ID to orient on (optional; inferred from the board/branch when omitted)",
42
+ },
43
+ json: {
44
+ type: "boolean",
45
+ description:
46
+ "return the raw JSON object instead of the human summary (optional)",
47
+ },
48
+ },
49
+ required: [],
50
+ additionalProperties: false,
51
+ },
52
+ async execute(input, context) {
53
+ const helper = h(context)
54
+ const argv = ["--root", toolLib.sessionRoot(helper, "")]
55
+ if (input.feature) argv.push("--feature", input.feature)
56
+ if (input.json) argv.push("--json")
57
+ return {
58
+ content: toolLib.runScript(helper, "scripts/orient.js", argv, {
59
+ label: "orient",
60
+ timeout: 30000,
61
+ }),
62
+ }
63
+ },
64
+ })
65
+ })
66
+ },
67
+ } satisfies Plugin
@@ -0,0 +1,89 @@
1
+ import type { Plugin } from "@opencode/plugin"
2
+ import toolLib from "../../scripts/qa/tool-lib.js"
3
+
4
+ // `session_info` — the join key between this session's handoff and observed
5
+ // provider telemetry. The orchestrator records the returned `session:` line in
6
+ // the handoff's `## Session metadata`; `node scripts/agent-report.js --cost`
7
+ // then joins the provider group (primary session + every subagent session) to
8
+ // it, giving real cost per feature / per shipped feature.
9
+ //
10
+ // Safe from a subagent too: the provider store is walked to the top ancestor
11
+ // session, and both the primary id (the join key) and the calling session id
12
+ // are reported. Never fabricates cost — an unreachable store reports
13
+ // "unavailable" and still returns the id. Node resolution + the mid-session
14
+ // worktree reroot live in scripts/qa/tool-lib.js.
15
+ //
16
+ // V2: registered from a plugin via `ctx.tool.transform`. The executor context has
17
+ // no `directory`/`worktree`, so the launch directory is captured in `setup` and
18
+ // paired with the call's sessionID; the effective tree is tool-lib's sessionRoot.
19
+
20
+ function observed(context: any, sessionID: string): any | null {
21
+ const root = toolLib.sessionRoot(context, "")
22
+ const out = toolLib.runScript(context, "scripts/qa/provider-stats.js", ["--session", sessionID, "--json", "--root", root], {
23
+ timeout: 60000,
24
+ label: "provider-stats",
25
+ })
26
+ try {
27
+ return JSON.parse(out)
28
+ } catch {
29
+ return null
30
+ }
31
+ }
32
+
33
+ function int(n: any): string {
34
+ return String(Math.round(Number(n || 0))).replace(/\B(?=(\d{3})+(?!\d))/g, ",")
35
+ }
36
+
37
+ export default {
38
+ id: "session-tools",
39
+ async setup(ctx) {
40
+ const directory = ctx.location.directory
41
+ await ctx.tool.transform((editor) => {
42
+ editor.add({
43
+ name: "session_info",
44
+ description:
45
+ "Report this orchestrator session's id — the `session:` value to record in the handoff's Session metadata so `agent-report --cost` can join real cost/token/turns — plus any observed provider telemetry for this session (primary + subagent sessions). Never invents numbers: if the opencode store is unreachable it says so and still returns the id.",
46
+ input: {
47
+ type: "object",
48
+ properties: {},
49
+ required: [],
50
+ additionalProperties: false,
51
+ },
52
+ async execute(_input, context) {
53
+ const sessionID = String(context.sessionID || "unknown")
54
+ // V2's executor has no `directory`/`worktree`; rebuild the context the
55
+ // shared tool-lib expects and report the effective root it resolves.
56
+ const helper = {
57
+ directory,
58
+ sessionID: context.sessionID,
59
+ agent: context.agent,
60
+ }
61
+ const stats = observed(helper, sessionID)
62
+ const rootID = stats?.meta?.scope?.rootId
63
+ const lines = [
64
+ `session: ${rootID || sessionID}`,
65
+ rootID && rootID !== sessionID ? `this_session: ${sessionID} (subagent of the primary above)` : null,
66
+ `directory: ${helper.directory}`,
67
+ `worktree: ${toolLib.sessionRoot(helper, "")}`,
68
+ `agent: ${helper.agent}`,
69
+ ].filter(Boolean) as string[]
70
+
71
+ const totals = stats?.aggregates?.totals
72
+ if (totals && totals.sessions > 0) {
73
+ const tokens = totals.tokens || {}
74
+ const share =
75
+ totals.cacheReadShare == null ? "n/a" : `${(totals.cacheReadShare * 100).toFixed(1)}% of input`
76
+ lines.push(
77
+ `observed: cost $${Number(totals.cost || 0).toFixed(4)} · turns ${int(totals.turns)} · ` +
78
+ `tokens in ${int(tokens.input)} / cache-read ${int(tokens.cacheRead)} (${share}) / out ${int(tokens.output)} / reasoning ${int(tokens.reasoning)} · ` +
79
+ `${int(totals.sessions)} session(s)`
80
+ )
81
+ } else {
82
+ lines.push("observed: unavailable (opencode store not reachable from this machine — the id above is still the join key)")
83
+ }
84
+ return { content: lines.join("\n") }
85
+ },
86
+ })
87
+ })
88
+ },
89
+ } satisfies Plugin
@@ -0,0 +1,101 @@
1
+ import type { Plugin } from "@opencode/plugin"
2
+ import toolLib from "../../scripts/qa/tool-lib.js"
3
+
4
+ // `wait` — block (bounded) for a detached job / CI run / log line / URL to reach
5
+ // a terminal state, instead of the agent's `sleep N; grep log` or `gh run watch`
6
+ // polling loop. The 2026-09 LibraryOS recon measured 98 `sleep` + 81 `gh` polls
7
+ // in 30 days; a blind sleep either wastes minutes or forces another poll. This
8
+ // wraps `scripts/wait-for.js`, which reuses the same `ci-wait-lib.js` the
9
+ // lander (`ship.js`) uses.
10
+ //
11
+ // BOUNDED by design: a `--timeout` (default 20 min, hard-capped here at 45 min)
12
+ // is required, so a wedged target can never hang the session. Returns the
13
+ // waiter's stdout and its exit status via the script output. The 45-min cap is
14
+ // above the longest known target — a full 26-journey mobile device matrix runs
15
+ // ~33 min on a software renderer, so a 30-min cap forced a second wait (F-296).
16
+ //
17
+ // It runs the child ASYNC (toolLib.runScriptAsync) rather than blocking the
18
+ // runtime: an `execFileSync` wait froze opencode's whole event loop, so the
19
+ // `job-notify` plugin's progress interval could not tick and a healthy detached
20
+ // run looked frozen until the wait returned (F-296). Spawning keeps the plugin
21
+ // (toasts + first-failure/completion wakes) live while the agent blocks here.
22
+ //
23
+ // V2: registered from a plugin via `ctx.tool.transform`. The executor context has
24
+ // no `directory`/`worktree`, so the launch directory is captured in `setup` and
25
+ // paired with the call's sessionID for tool-lib's sessionRoot reroot.
26
+
27
+ export default {
28
+ id: "wait-tools",
29
+ async setup(ctx) {
30
+ const directory = ctx.location.directory
31
+ const h = (context: any) => ({
32
+ directory,
33
+ sessionID: context?.sessionID,
34
+ agent: context?.agent,
35
+ })
36
+ await ctx.tool.transform((editor) => {
37
+ editor.add({
38
+ name: "wait",
39
+ description:
40
+ "Block (bounded) until a detached job, CI run, log line, URL, or TCP port reaches a terminal state — then return. Use it INSTEAD of `sleep N; grep log` polling or `gh run watch`. Modes: job (record.json), events (events.jsonl), ci (a commit's CI run), health (url), port (n), file+grep (a log line). Always timeout-bounded (default 20 min); never hangs.",
41
+ input: {
42
+ type: "object",
43
+ properties: {
44
+ mode: {
45
+ type: "string",
46
+ enum: ["job", "events", "ci", "health", "port", "file"],
47
+ description: "what to wait on",
48
+ },
49
+ target: {
50
+ type: "string",
51
+ description:
52
+ "the mode's target: job record path, events path, commit sha (ci), url, port, or log path (file)",
53
+ },
54
+ grep: {
55
+ type: "string",
56
+ description: "regex to match when mode=file (optional otherwise)",
57
+ },
58
+ timeout: {
59
+ type: "number",
60
+ description: "max seconds to wait (default 1200; hard cap 2700)",
61
+ },
62
+ poll: {
63
+ type: "number",
64
+ description: "poll interval seconds (default 5)",
65
+ },
66
+ },
67
+ required: ["mode", "target"],
68
+ additionalProperties: false,
69
+ },
70
+ async execute(input, context) {
71
+ const helper = h(context)
72
+ const root = toolLib.sessionRoot(helper, "")
73
+ const argv = ["--root", root]
74
+ const mode = String(input.mode || "")
75
+ if (mode === "job") argv.push("--job", input.target)
76
+ else if (mode === "events") argv.push("--events", input.target)
77
+ else if (mode === "ci") {
78
+ argv.push("--ci")
79
+ if (input.target) argv.push("--commit", input.target)
80
+ } else if (mode === "health") argv.push("--health", input.target)
81
+ else if (mode === "port") argv.push("--port", String(input.target))
82
+ else if (mode === "file") {
83
+ argv.push("--file", input.target)
84
+ if (input.grep) argv.push("--grep", input.grep)
85
+ }
86
+ const timeout = Math.min(Math.max(Number(input.timeout) || 1200, 1), 2700)
87
+ argv.push("--timeout", String(timeout))
88
+ if (input.poll) argv.push("--poll", String(input.poll))
89
+ const res = await toolLib.runScriptAsync(helper, "scripts/wait-for.js", argv, {
90
+ label: "wait",
91
+ timeout: (timeout + 60) * 1000,
92
+ })
93
+ if (res.error) return { content: `${res.error}\n${res.stderr || ""}`.trim() }
94
+ const body = (res.stdout || "").trim()
95
+ const tail = (res.stderr || "").trim()
96
+ return { content: [body, tail].filter(Boolean).join("\n") || `wait: exit ${res.code}` }
97
+ },
98
+ })
99
+ })
100
+ },
101
+ } satisfies Plugin