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,49 @@
1
+ # Global opencode plugins
2
+
3
+ Plugins here are **machine-level**, not project-level. `agent-harness init`/`update`
4
+ never deploy these (they live outside `templates/`); install them into opencode's
5
+ global plugin directory with:
6
+
7
+ ```bash
8
+ npx opencode-agent-harness install-global # or: node bin/agent-harness.js install-global
9
+ ```
10
+
11
+ That links each `*.ts`/`*.js` here into `~/.config/opencode/plugins/` (a symlink
12
+ pointing back at this checkout, or a copy where symlinks are unavailable). Opencode
13
+ auto-loads that directory for **every** project and session. Restart opencode after
14
+ installing.
15
+
16
+ ## Why global, not a project plugin
17
+
18
+ Some checks must run even when a project's own harness is stale — and a check
19
+ shipped inside that stale harness could never fire, because the stale copy is what
20
+ opencode loads. Only a global plugin (plus a global instruction) is
21
+ version-independent. See `harness-freshness.ts`.
22
+
23
+ ## `harness-freshness.ts`
24
+
25
+ On every primary session start it compares the checkout's `.harness.json` version
26
+ to the authoritative local harness (`AGENT_HARNESS_HOME`, default
27
+ `~/develop/agent-harness`) and keeps the checkout current — **only when that is
28
+ safe for the active branch**:
29
+
30
+ | state | action |
31
+ | --- | --- |
32
+ | up to date | nothing |
33
+ | linked worktree, project **main already latest**, worktree HEAD is an ancestor of main (true fast-forward), no local change overlaps the incoming files | `git merge --ff-only <main>` (never rewrites history) |
34
+ | main checkout, no drift | `agent-harness update --target <tree>` (the sanctioned deploy; fails closed on locally-modified harness files) |
35
+ | anything else (main stale, branch diverged, overlapping dirty files, merge/rebase in progress, update failed) | **no mutation** — writes `.serve/harness-freshness.json` and injects a session notice so the agent relays it and waits |
36
+
37
+ A refresh only changes files on disk; opencode loads plugins once at startup, so the
38
+ plugin toasts that a **restart** is needed before the updated plugins take effect.
39
+
40
+ Env knobs: `AGENT_HARNESS_HOME` (authoritative checkout), `AGENT_HARNESS_FRESHNESS=dry`
41
+ (detect/report only, never apply).
42
+
43
+ ### Relationship to the manual deploy workflow
44
+
45
+ The plugin is a **safety net**, not a replacement for the release workflow
46
+ (`~/develop/agent-harness/AGENTS.md` step 5: after `update`-ing a project, refresh
47
+ its active worktrees). The manual step is deterministic and runs at deploy time; the
48
+ plugin only acts at session start and deliberately **blocks** (does not force) the
49
+ unsafe cases — a diverged worktree, or a stale project main. Keep both.
@@ -0,0 +1,355 @@
1
+ import type { Plugin } from "@opencode/plugin"
2
+ import fs from "node:fs"
3
+ import os from "node:os"
4
+ import path from "node:path"
5
+ import { execFileSync, spawn } from "node:child_process"
6
+
7
+ // harness-freshness — a GLOBAL opencode plugin (this dir is loaded for every
8
+ // project/session, independent of a project's own harness version) that keeps a
9
+ // session's checkout on the latest local harness.
10
+ //
11
+ // Why global: a check shipped inside the project harness can't catch a stale
12
+ // harness — the stale copy is what loads. And opencode loads config/plugins once
13
+ // at startup, so an in-session update only changes files on disk; the agent must
14
+ // restart opencode to load the updated plugins.
15
+ //
16
+ // "Latest" is the authoritative local checkout (`AGENT_HARNESS_HOME`, default
17
+ // ~/develop/agent-harness). On each primary session start it compares the
18
+ // checkout's `.harness.json` version. If stale it refreshes ONLY when that is
19
+ // provably safe for the active branch:
20
+ //
21
+ // * linked worktree + project main already latest + worktree HEAD is an
22
+ // ancestor of main (a fast-forward) + no local changes overlap the incoming
23
+ // files -> `git merge --ff-only <main>` (never rewrites history, never
24
+ // creates a merge commit)
25
+ // * main checkout -> `agent-harness update --target`
26
+ // (the sanctioned deploy; it fails closed on locally-modified harness files)
27
+ //
28
+ // Anything else (diverged branch, overlapping dirty files, stale project main,
29
+ // update failure) is NOT auto-changed: it records a BLOCKED notice, injected
30
+ // into the session tail so the agent must relay it and wait for the user.
31
+ //
32
+ // Set AGENT_HARNESS_FRESHNESS=dry to detect+report without applying (testing).
33
+
34
+ const HARNESS_HOME = process.env.AGENT_HARNESS_HOME || path.join(os.homedir(), "develop", "agent-harness")
35
+ const LATEST_PKG = path.join(HARNESS_HOME, "package.json")
36
+ const CLI = path.join(HARNESS_HOME, "bin", "agent-harness.js")
37
+ const DRY = process.env.AGENT_HARNESS_FRESHNESS === "dry"
38
+
39
+ // When this module is evaluated, the opencode process is (essentially) starting.
40
+ // If the checkout's `.harness.json` was written AFTER this instant, the running
41
+ // process loaded the OLD plugins/config — a deploy that has not yet activated.
42
+ // The version compares "current" but the process is stale (F-19/H-44).
43
+ const PROCESS_START = Date.now()
44
+
45
+ function writeTime(p: string): number | null {
46
+ try {
47
+ return fs.statSync(p).mtimeMs
48
+ } catch {
49
+ return null
50
+ }
51
+ }
52
+
53
+ type GitResult = { ok: boolean; out: string; err: string }
54
+
55
+ function git(cwd: string, args: string[], timeout = 10000): GitResult {
56
+ try {
57
+ const out = execFileSync("git", ["-C", cwd, ...args], {
58
+ encoding: "utf8",
59
+ timeout,
60
+ stdio: ["ignore", "pipe", "pipe"],
61
+ })
62
+ return { ok: true, out: String(out).trim(), err: "" }
63
+ } catch (e: any) {
64
+ return {
65
+ ok: false,
66
+ out: String(e?.stdout || "").trim(),
67
+ err: String(e?.stderr || e?.message || "").trim(),
68
+ }
69
+ }
70
+ }
71
+
72
+ function readVersion(p: string): string | null {
73
+ try {
74
+ const v = JSON.parse(fs.readFileSync(p, "utf8")).version
75
+ return typeof v === "string" && v ? v : null
76
+ } catch {
77
+ return null
78
+ }
79
+ }
80
+
81
+ function cmpVer(a: string, b: string): number {
82
+ const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0)
83
+ const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0)
84
+ for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
85
+ const d = (pa[i] || 0) - (pb[i] || 0)
86
+ if (d) return d
87
+ }
88
+ return 0
89
+ }
90
+
91
+ /* A real Node interpreter to run the harness CLI. opencode is a Bun-compiled
92
+ * standalone binary, so within a plugin `process.execPath` is the opencode
93
+ * executable, NOT Node — spawning it with the CLI path just re-launches opencode
94
+ * (prints its help, exits 1), which made every main-checkout refresh "fail" and
95
+ * block the session. Mirrors `templates/scripts/qa/tool-lib.js` `nodeBin()`: an
96
+ * OPENCODE_NODE override, then Bun's PATH resolver (skipping WSL /mnt entries so
97
+ * a native node beats the interop Windows node.exe), then a bare "node". */
98
+ function nodeBin(): string {
99
+ const override = process.env.OPENCODE_NODE
100
+ if (override) return override
101
+ const bun = (globalThis as any).Bun
102
+ if (bun && typeof bun.which === "function") {
103
+ const pathEnv = String(process.env.PATH || "")
104
+ const native =
105
+ process.platform === "linux"
106
+ ? pathEnv
107
+ .split(":")
108
+ .filter((p) => p && !p.startsWith("/mnt/"))
109
+ .join(":")
110
+ : pathEnv
111
+ const found = bun.which("node", native ? { PATH: native } : {}) || bun.which("node")
112
+ if (found) return found
113
+ }
114
+ return "node"
115
+ }
116
+
117
+ const HarnessFreshness: Plugin = {
118
+ id: "harness-freshness",
119
+ async setup(ctx) {
120
+ const notices = new Map<string, string>()
121
+ const checked = new Set<string>()
122
+
123
+ // V1 called `client.app.log`; V2 server plugins log to the console.
124
+ const report = (message: string, level: "info" | "warn" | "error" = "info") => {
125
+ const line = `harness-freshness: ${message}`
126
+ if (level === "error") console.error(line)
127
+ else if (level === "warn") console.warn(line)
128
+ else console.log(line)
129
+ }
130
+
131
+ const block = async (sid: string, reason: string, advice: string) => {
132
+ const text =
133
+ `HARNESS FRESHNESS — do NOT begin work yet.\n\n` +
134
+ `${reason}\n\nNext steps:\n${advice}\n\n` +
135
+ `Relay this to the user and wait for their instructions before continuing.`
136
+ notices.set(sid, text)
137
+ report(`blocked (${sid}): ${reason}`, "warn")
138
+ }
139
+
140
+ const writeStatus = (tree: string, status: Record<string, unknown>) => {
141
+ try {
142
+ const dir = path.join(tree, ".serve")
143
+ fs.mkdirSync(dir, { recursive: true })
144
+ fs.writeFileSync(path.join(dir, "harness-freshness.json"), JSON.stringify(status, null, 2) + "\n")
145
+ } catch {
146
+ /* observability only */
147
+ }
148
+ }
149
+
150
+ const evaluate = async (sid: string, dir: string) => {
151
+ const latest = readVersion(LATEST_PKG)
152
+ if (!latest) return // no authoritative checkout here
153
+ const top = git(dir, ["rev-parse", "--show-toplevel"])
154
+ if (!top.ok) return // not a git tree
155
+ const tree = top.out
156
+ const cfg = path.join(tree, ".harness.json")
157
+ if (!fs.existsSync(cfg)) return // not a harness project
158
+ const have = readVersion(cfg)
159
+ if (have && cmpVer(have, latest) >= 0) {
160
+ // Version is current, but the RUNNING process may still predate the last
161
+ // harness write (deploy != activate, F-19/H-44): the plugins/config in
162
+ // effect are the OLD ones until opencode restarts.
163
+ const wrote = writeTime(cfg)
164
+ if (wrote && wrote > PROCESS_START) {
165
+ writeStatus(tree, { status: "restart-needed", have, latest, wrote, at: new Date().toISOString() })
166
+ await block(
167
+ sid,
168
+ `The harness on disk is current (${have}) but this opencode process started before the last ` +
169
+ `harness write, so the plugins/config in effect are the OLD ones — a deploy is inert until restart.`,
170
+ ` restart opencode to load ${have}.`
171
+ )
172
+ return
173
+ }
174
+ notices.delete(sid)
175
+ writeStatus(tree, { status: "current", have, latest, at: new Date().toISOString() })
176
+ return
177
+ }
178
+
179
+ const wl = git(tree, ["worktree", "list", "--porcelain"])
180
+ const first = (wl.out || "").split(/\r?\n/).find((l) => l.startsWith("worktree "))
181
+ const mainTop = first ? first.slice("worktree ".length).trim() : tree
182
+ const mainHave = readVersion(path.join(mainTop, ".harness.json"))
183
+ const isWorktree = path.resolve(mainTop) !== path.resolve(tree)
184
+ const base = { have, latest, tree, main: mainTop, kind: isWorktree ? "worktree" : "main" }
185
+
186
+ if (isWorktree) {
187
+ if (!mainHave || cmpVer(mainHave, latest) < 0) {
188
+ writeStatus(tree, { ...base, status: "blocked", reason: "project main checkout stale" })
189
+ return block(
190
+ sid,
191
+ `This worktree is on harness ${have} (latest ${latest}), but the project's MAIN checkout ` +
192
+ `(${mainTop}) is itself stale${mainHave ? ` at ${mainHave}` : ""}.`,
193
+ ` node ${CLI} update --target ${mainTop}\n # then restart opencode; the worktree can then fast-forward.`
194
+ )
195
+ }
196
+ const ref = git(mainTop, ["rev-parse", "--abbrev-ref", "HEAD"]).out || "main"
197
+ if (!git(tree, ["merge-base", "--is-ancestor", "HEAD", ref]).ok) {
198
+ writeStatus(tree, { ...base, status: "blocked", reason: "branch has its own commits" })
199
+ return block(
200
+ sid,
201
+ `This worktree's branch (${git(tree, ["rev-parse", "--abbrev-ref", "HEAD"]).out}) has commits of ` +
202
+ `its own, so the harness refresh needs a merge/rebase, not a fast-forward.`,
203
+ ` git -C ${tree} merge ${ref} # or: git -C ${tree} rebase ${ref}\n # then restart opencode.`
204
+ )
205
+ }
206
+ const incoming = new Set(
207
+ git(tree, ["diff", "--name-only", `HEAD..${ref}`]).out.split(/\r?\n/).filter(Boolean)
208
+ )
209
+ const dirty = git(tree, ["status", "--porcelain"])
210
+ .out.split(/\r?\n/)
211
+ .filter(Boolean)
212
+ .map((l) => l.slice(3).trim().replace(/^"(.*)"$/, "$1"))
213
+ const overlap = dirty.filter((f) => incoming.has(f))
214
+ if (overlap.length) {
215
+ writeStatus(tree, { ...base, status: "blocked", reason: "overlapping local changes", overlap })
216
+ return block(
217
+ sid,
218
+ `Local changes overlap the files a harness refresh would touch: ${overlap.join(", ")}.`,
219
+ ` commit or stash them, then restart opencode to auto-refresh.`
220
+ )
221
+ }
222
+ if (DRY) {
223
+ writeStatus(tree, { ...base, status: "stale-would-ff", ref })
224
+ report(`[dry] would fast-forward ${tree} ${have} -> ${latest} (${ref})`)
225
+ return
226
+ }
227
+ const m = git(tree, ["merge", "--ff-only", ref], 30000)
228
+ if (m.ok) {
229
+ notices.delete(sid)
230
+ writeStatus(tree, { ...base, status: "refreshed", ref, at: new Date().toISOString() })
231
+ report(`refreshed worktree ${tree}: ${have} -> ${latest} (ff ${ref}) — restart opencode to load the updated plugins`)
232
+ } else {
233
+ writeStatus(tree, { ...base, status: "blocked", reason: "fast-forward failed", detail: m.err || m.out })
234
+ await block(sid, `Fast-forward refresh failed: ${(m.err || m.out || "unknown").split(/\r?\n/)[0]}`, ` git -C ${tree} merge ${ref}`)
235
+ }
236
+ return
237
+ }
238
+
239
+ // Main checkout stale relative to the authoritative local harness. Only the
240
+ // sanctioned deploy is correct here; it fails closed on locally-modified
241
+ // harness files, so a run is safe, but it commits+pushes — run it async and
242
+ // block only if it actually fails.
243
+ const inProgress =
244
+ fs.existsSync(path.join(tree, ".git", "MERGE_HEAD")) ||
245
+ fs.existsSync(path.join(tree, ".git", "rebase-merge")) ||
246
+ fs.existsSync(path.join(tree, ".git", "rebase-apply"))
247
+ if (inProgress) {
248
+ writeStatus(tree, { ...base, status: "blocked", reason: "git operation in progress" })
249
+ return block(sid, `A git merge/rebase is already in progress in the main checkout.`, ` finish or abort it, then restart opencode.`)
250
+ }
251
+ if (DRY) {
252
+ writeStatus(tree, { ...base, status: "stale-would-update" })
253
+ report(`[dry] would update main checkout ${tree} ${have} -> ${latest}`)
254
+ return
255
+ }
256
+ writeStatus(tree, { ...base, status: "updating" })
257
+ report(`updating main checkout ${tree}: ${have} -> ${latest}`)
258
+ try {
259
+ const child = spawn(nodeBin(), [CLI, "update", "--target", tree], {
260
+ cwd: tree,
261
+ stdio: ["ignore", "pipe", "pipe"],
262
+ })
263
+ let out = ""
264
+ child.stdout?.on("data", (d) => (out += d))
265
+ child.stderr?.on("data", (d) => (out += d))
266
+ child.on("error", (e: any) =>
267
+ void block(sid, `Deploy could not start: ${e?.message || e}`, ` node ${CLI} update --target ${tree}`)
268
+ )
269
+ child.on("close", (code) => {
270
+ if (code === 0) {
271
+ notices.delete(sid)
272
+ writeStatus(tree, { ...base, status: "refreshed", at: new Date().toISOString() })
273
+ report(`updated main checkout ${tree}: ${have} -> ${latest} — restart opencode to load the updated plugins`)
274
+ } else {
275
+ const tail = out.trim().split(/\r?\n/).slice(-6).join("\n")
276
+ writeStatus(tree, { ...base, status: "blocked", reason: "update failed", detail: tail })
277
+ void block(
278
+ sid,
279
+ `The harness deploy failed (exit ${code}) — usually a locally-modified harness file (update fails closed):\n${tail}`,
280
+ ` fix it upstream in templates/, or back up and re-run:\n node ${CLI} update --target ${tree} --accept-harness`
281
+ )
282
+ }
283
+ })
284
+ } catch (e: any) {
285
+ await block(sid, `Deploy threw: ${e?.message || e}`, ` node ${CLI} update --target ${tree}`)
286
+ }
287
+ }
288
+
289
+ // V1 used an `event` hook; V2 plugins subscribe to the event stream in setup.
290
+ const controller = new AbortController()
291
+ void (async () => {
292
+ try {
293
+ for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
294
+ try {
295
+ // V2 envelope: the payload is `event.data` (V1's `properties` field does
296
+ // not exist). A child session carries `data.parentID`.
297
+ const d: any = (event as any)?.data || {}
298
+ if (event?.type === "session.deleted") {
299
+ const sid = d.sessionID
300
+ if (typeof sid === "string" && sid) {
301
+ notices.delete(sid)
302
+ checked.delete(sid)
303
+ }
304
+ continue
305
+ }
306
+ if (event?.type !== "session.created") continue
307
+ const sid = d.sessionID
308
+ if (typeof sid !== "string" || !sid) continue
309
+ if (d.parentID) continue // child/subagent session
310
+ if (checked.has(sid)) continue
311
+ checked.add(sid)
312
+ const dir =
313
+ typeof d.location?.directory === "string" && d.location.directory
314
+ ? d.location.directory
315
+ : ctx.location.directory
316
+ await evaluate(sid, dir)
317
+ } catch (err: any) {
318
+ report(`check failed: ${err?.message || err}`, "warn")
319
+ }
320
+ }
321
+ } catch (err: any) {
322
+ if (!controller.signal.aborted) report(`event stream failed: ${err?.message || err}`, "warn")
323
+ }
324
+ })()
325
+
326
+ // V1 used `experimental.chat.messages.transform`; V2 surfaces the session
327
+ // context hook, which carries the session id directly.
328
+ await ctx.session.hook("context", (event: any) => {
329
+ try {
330
+ const sid = event?.sessionID
331
+ if (typeof sid !== "string" || !sid) return
332
+ const text = notices.get(sid)
333
+ if (!text) return
334
+ notices.delete(sid) // one-shot: the model already saw it and must wait
335
+ const messages = event?.messages
336
+ if (!Array.isArray(messages)) return
337
+ const last = messages[messages.length - 1]
338
+ const lastText =
339
+ typeof last?.content === "string"
340
+ ? last.content
341
+ : Array.isArray(last?.content)
342
+ ? last.content.map((p: any) => (p && typeof p.text === "string" ? p.text : "")).join("")
343
+ : ""
344
+ if (last?.role === "user" && lastText === text) return // already injected
345
+ messages.push({ role: "user", content: [{ type: "text", text }] })
346
+ } catch {
347
+ /* never break a request */
348
+ }
349
+ })
350
+
351
+ return () => controller.abort()
352
+ },
353
+ }
354
+
355
+ export default HarnessFreshness
package/package.json CHANGED
@@ -1,6 +1,88 @@
1
1
  {
2
2
  "name": "opencode-agent-harness",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.3.14",
4
+ "description": "Reusable multi-agent harness for OpenCode: personas, skills, operating rules, model routing, and QA gates. Deploy into any project with `npx opencode-agent-harness init`.",
5
+ "bin": {
6
+ "agent-harness": "bin/agent-harness.js"
7
+ },
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/dombaras/agent-harness.git"
11
+ },
12
+ "homepage": "https://github.com/dombaras/agent-harness#readme",
13
+ "bugs": {
14
+ "url": "https://github.com/dombaras/agent-harness/issues"
15
+ },
16
+ "author": "dombaras",
17
+ "publishConfig": {
18
+ "access": "public"
19
+ },
20
+ "files": [
21
+ "bin/",
22
+ "templates/",
23
+ "contrib/",
24
+ "README.md",
25
+ "CHANGELOG.md",
26
+ "LICENSE"
27
+ ],
28
+ "scripts": {
29
+ "prepublishOnly": "npm run lint && npm test && npm run test:pack",
30
+ "test:pack": "node --test tests/pack.e2e.js",
31
+ "test": "node --test tests/agent-harness.test.js tests/plugin-loader.e2e.js tests/ci-usage.test.js tests/ci-triage.test.js tests/init-safety.test.js tests/release-bundle.e2e.js tests/worktree-hygiene.test.js",
32
+ "bundle": "node tools/make-release-bundle.mjs",
33
+ "test:plugin-loader": "node --test tests/plugin-loader.e2e.js",
34
+ "lint": "node --check bin/agent-harness.js && node --check templates/scripts/backlog.js && node --check templates/scripts/nightly.js && node --check templates/scripts/ship.js && node --check templates/scripts/finalize.js && node --check templates/scripts/checkpoint.js && node --check templates/scripts/orient.js && node --check templates/scripts/wait-for.js && node --check templates/scripts/agent-report.js && node --check templates/scripts/serve.js && node --check templates/scripts/qa/check-dispatch-config.js && node --check templates/scripts/qa/governance.js && node --check templates/scripts/qa/check-qa-plan.js && node --check templates/scripts/qa/check-qa-scripts.js && node --check templates/scripts/qa/check-backlog.js && node --check templates/scripts/qa/board-lib.js && node --check templates/scripts/qa/board-sync.js && node --check templates/scripts/qa/board-client.js && node --check templates/scripts/qa/tool-lib.js && node --check templates/scripts/qa/lease-lib.js && node --check templates/scripts/qa/ci-wait-lib.js && node --check templates/scripts/qa/ci-triage.js && node --check templates/scripts/qa/check-ci-policy.js && node --check templates/scripts/qa/check-quality.js && node --check templates/scripts/qa/check-product.js && node --check templates/scripts/qa/check-docs.js && node --check templates/scripts/qa/check-concurrency.js && node --check templates/scripts/qa/check-integrate.js && node --check templates/scripts/qa/merge-backlog.js && node --check templates/scripts/qa/run-clean.js && node --check templates/scripts/qa/check-test-wiring.js && node --check templates/scripts/qa/check-linger.js && node --check templates/scripts/qa/check-prefix-stability.js && node --check templates/scripts/qa/command-classifier.js && node --check templates/scripts/qa/capacity-lib.js && node --check templates/scripts/qa/check-capacity.js && node --check templates/scripts/qa/wslconfig-merge.js && node --check templates/scripts/qa/hash-file.js && node --check templates/scripts/qa/context-guard-core.js && node --check templates/scripts/qa/run-loop.js && node --check templates/scripts/qa/provider-stats.js && node --check templates/scripts/qa/store-lib.js && node --check templates/scripts/qa/diff.js && node --check templates/scripts/qa/session-recon.js && node --check templates/scripts/qa/run-gates.js && node --check templates/scripts/qa/where.js && node --check templates/scripts/qa/feature-scaffold.js && node --check templates/scripts/qa/mobile-e2e/run-maestro.js && node --check templates/scripts/qa/mobile-e2e/job-events.js && node --check templates/scripts/qa/mobile-e2e/check-flows.js && node --check templates/scripts/qa/mobile-e2e/apk-cache.js && node --check templates/scripts/qa/mobile-e2e/backend-build-cache.js && node --check templates/scripts/qa/mobile-e2e/ui-dump.js && node --check templates/scripts/qa/mobile-e2e/analyze-timings.js && node --check templates/scripts/qa/ci-usage-lib.js && node --check tests/ci-usage.test.js && node --check tools/make-release-bundle.mjs",
35
+ "backlog": "node scripts/backlog.js",
36
+ "ship": "node scripts/ship.js",
37
+ "finalize": "node scripts/finalize.js",
38
+ "test:dispatch": "node scripts/qa/check-dispatch-config.js",
39
+ "test:governance": "node scripts/qa/governance.js",
40
+ "test:qa-plan": "node scripts/qa/check-qa-plan.js",
41
+ "test:backlog": "node scripts/qa/check-backlog.js",
42
+ "test:product": "node scripts/qa/check-product.js",
43
+ "test:docs": "node scripts/qa/check-docs.js",
44
+ "test:concurrency": "node scripts/qa/check-concurrency.js",
45
+ "test:integrate": "node scripts/qa/check-integrate.js",
46
+ "test:quality": "node scripts/qa/check-quality.js",
47
+ "test:wiring": "node scripts/qa/check-test-wiring.js",
48
+ "test:linger": "node scripts/qa/check-linger.js",
49
+ "test:capacity": "node scripts/qa/check-capacity.js",
50
+ "test:worktrees": "node scripts/qa/check-worktrees.js",
51
+ "test:ci-policy": "node scripts/qa/check-ci-policy.js",
52
+ "test:prefix": "node scripts/qa/check-prefix-stability.js",
53
+ "ci-triage": "node scripts/qa/ci-triage.js",
54
+ "gates": "node scripts/qa/run-gates.js",
55
+ "where": "node scripts/qa/where.js",
56
+ "diff": "node scripts/qa/diff.js",
57
+ "feature:scaffold": "node scripts/qa/feature-scaffold.js",
58
+ "report": "node scripts/agent-report.js",
59
+ "report:cost": "node scripts/agent-report.js --cost --since=14d",
60
+ "report:recon": "node scripts/qa/session-recon.js --since=14d",
61
+ "nightly": "node scripts/nightly.js",
62
+ "report:nightly": "node scripts/nightly.js report",
63
+ "checkpoint": "node scripts/checkpoint.js",
64
+ "orient": "node scripts/orient.js",
65
+ "wait": "node scripts/wait-for.js",
66
+ "serve": "node scripts/serve.js",
67
+ "search": "bash scripts/agent-search.sh",
68
+ "ramdisk": "bash scripts/setup-tmpfs.sh up",
69
+ "ramdisk:down": "bash scripts/setup-tmpfs.sh down",
70
+ "wsl-tune": "bash scripts/wsl-tune.sh",
71
+ "gpu": "bash scripts/wsl-gpu.sh"
72
+ },
73
+ "keywords": [
74
+ "opencode",
75
+ "opencode-plugin",
76
+ "opencode-ai",
77
+ "agents",
78
+ "subagents",
79
+ "personas",
80
+ "ai-harness",
81
+ "ai-agents",
82
+ "developer-tools"
83
+ ],
84
+ "license": "MIT",
85
+ "engines": {
86
+ "node": ">=20"
87
+ }
88
+ }