@plainconceptsplatform/agent-harness 2.9.0 → 3.0.1

package/harness/.opencode/plugins/pc-subagent-tiers.js

@@ -1,7 +1,7 @@
 // pc-subagent-tiers: on startup, reads *-engineer.md templates and creates
-// tier variant files with the resolved model, plus the two primary agents the
-// user actually talks to. Everything generated here is gitignored and rebuilt
-// every startup. Model resolution: user override > team config.
+// tier variant agent files with the resolved model, plus the two primary agents
+// the user actually talks to. Everything generated here is gitignored and
+// rebuilt every startup. Model resolution: user override > team config.
 //
 // Agent topology:
 //   build.md / plan.md      mode: primary   the only agents a human selects.
@@ -10,39 +10,41 @@
 //                                           nor spawn.
 //   fullstack-engineer.md   mode: subagent  the shared body of build and plan,
 //                                           and the fallback worker.
-//   *-engineer.md           mode: subagent  specialists, spawned by task().
+//   *-engineer.md           mode: subagent  specialists, spawned by subagent().
 //   *-engineer.<tier>.md    mode: subagent  the same specialist pinned to a tier.
 //
-// Overriding opencode's built-in build and plan (rather than disabling them, as
-// earlier versions did) means the agent picker offers exactly two entries and
-// both carry our prompt and abilities.
+// OpenCode 2 discovers agents from .opencode/agents/*.md and overrides a built-in
+// by ID, so the generated files replace the built-in build/plan. The plugin API's
+// agent editor can update or remove an existing agent but cannot add one, so file
+// generation is the mechanism: writing the files in setup, before agents resolve,
+// is what makes them visible.
 
+import { Plugin } from "@opencode/plugin"
 import fs from "node:fs/promises"
 import path from "node:path"
 
 const TIERS = ["build", "fast", "plan"]
 
 // The two primaries, and the tier each takes its model from. plan denies edit
-// and task: a planning session cannot mutate the tree itself, and it cannot
-// spawn a worker that would do it on its behalf. bash stays allowed because the
+// and subagent: a planning session cannot mutate the tree itself, and it cannot
+// spawn a worker that would do it on its behalf. shell stays allowed because the
 // planning skills shell out to git and openspec to read state, and
 // pc-system-reminders holds it to inspection commands.
-//
-// Their colours are theme keywords rather than derived hexes, and they are
-// fixed: these are the two agents a human picks, so they should look the same
-// in every project regardless of the theme in use.
 const PRIMARIES = {
   build: {
     tier: "build",
     color: "primary",
     description: "Implement changes in this repository. Full write access, spawns specialist engineers for parallel work.",
-    permission: null,
+    permissions: null,
   },
   plan: {
     tier: "plan",
     color: "warning",
     description: "Explore and plan without touching the tree. Read-only: proposes work for build to carry out.",
-    permission: { edit: "deny", task: "deny" },
+    permissions: [
+      { action: "edit", resource: "*", effect: "deny" },
+      { action: "subagent", resource: "*", effect: "deny" },
+    ],
   },
 }
 
@@ -51,6 +53,20 @@ const PRIMARIES = {
 // avoid collisions by hand, which does not survive more than a few agents.
 const THEME_COLORS = new Set(["primary", "secondary", "accent", "success", "warning", "error", "info"])
 
+// Fields V1 agent frontmatter used that V2 forbids. Stripped on sight so a repo
+// upgraded in place does not carry a definition V2 refuses to load.
+const LEGACY_FIELDS = [
+  "model",
+  "permission",
+  "prompt",
+  "disable",
+  "disabled",
+  "temperature",
+  "top_p",
+  "maxSteps",
+  "tools",
+]
+
 // Mirrors cli/utils/agent-color.js in the CLI, duplicated because a plugin has
 // to stand alone in the consumer repo. agent-color.test.js asserts the two stay
 // in step; change one and change the other.
@@ -102,12 +118,49 @@ function unquoteColor(raw) {
   return (raw ?? "").trim().replace(/^["']/, "").replace(/["']$/, "")
 }
 
-/**
- * The colour line an agent should have, or null when the current one is already
- * right. Handles both choosing the colour and quoting it, so a file written by
- * an earlier version with a bare hex is repaired in place rather than left
- * broken.
- */
+function splitFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
+  if (!match) return { frontmatter: null, body: content }
+  return { frontmatter: match[1], body: content.slice(match[0].length) }
+}
+
+function stripLegacyFields(frontmatter) {
+  const lines = frontmatter.split(/\r?\n/)
+  const kept = []
+  for (let i = 0; i < lines.length; i++) {
+    const key = lines[i].match(/^([A-Za-z0-9_-]+):/)?.[1]
+    if (key && LEGACY_FIELDS.includes(key)) {
+      // Drop the key and any indented continuation lines that belong to it.
+      i++
+      while (i < lines.length && /^\s+\S/.test(lines[i])) i++
+      i--
+      continue
+    }
+    kept.push(lines[i])
+  }
+  return kept.join("\n").replace(/\n{3,}/g, "\n\n").trim()
+}
+
+function setScalar(frontmatter, key, value) {
+  const line = `${key}: ${value}`
+  if (new RegExp(`^${key}:`, "m").test(frontmatter)) {
+    return frontmatter.replace(new RegExp(`^${key}:.*$`, "m"), () => line)
+  }
+  return frontmatter ? `${line}\n${frontmatter}` : line
+}
+
+function permissionsYaml(permissions) {
+  return [
+    "permissions:",
+    ...permissions.flatMap(p => [
+      `  - action: ${p.action}`,
+      `    resource: ${p.resource}`,
+      `    effect: ${p.effect}`,
+    ]),
+  ].join("\n")
+}
+
+/** The colour line an agent should have, or null when the current one is right. */
 function colorLineFor(name, rawCurrent) {
   const current = unquoteColor(rawCurrent)
   const target = shouldDeriveColor(current) ? agentColor(name) : current
@@ -118,254 +171,169 @@ function colorLineFor(name, rawCurrent) {
 const FULLSTACK_NAME = "fullstack-engineer"
 const FULLSTACK_TEMPLATE = `${FULLSTACK_NAME}.md`
 
-export const PcSubagentTiers = async ({ directory }) => {
-  const root = directory || process.cwd()
-  const agentsDir = path.join(root, ".opencode", "agents")
-
-  async function readJson(filePath) {
-    try {
-      return JSON.parse(await fs.readFile(filePath, "utf-8"))
-    } catch {
-      return null
-    }
-  }
-
-  async function resolveModels() {
-    const [user, team] = await Promise.all([
-      readJson(path.join(root, ".opencode", "harness.user.json")),
-      readJson(path.join(root, ".opencode", "harness.json")),
-    ])
-    const models = {}
-    for (const tier of TIERS) {
-      models[tier] = user?.models?.[tier] ?? team?.models?.[tier] ?? null
-    }
-    return models
-  }
+/** Rewrite a template's frontmatter to a clean V2 subagent definition. */
+function normalizeTemplate(content, name) {
+  const { frontmatter, body } = splitFrontmatter(content)
+  if (frontmatter === null) return `---\nmode: subagent\ncolor: ${yamlColor(agentColor(name))}\n---\n\n${content}`
 
-  async function scanEngineers() {
-    try {
-      const entries = await fs.readdir(agentsDir)
-      return {
-        templates: entries.filter(f => /^[\w-]+-engineer\.md$/.test(f) && f !== FULLSTACK_TEMPLATE).map(f => f.replace(/\.md$/, "")),
-        variantFiles: entries.filter(f => /^[\w-]+-engineer\.(build|fast|plan)\.md$/.test(f)),
-        hasFullstack: entries.includes(FULLSTACK_TEMPLATE),
-      }
-    } catch {
-      return { templates: [], variantFiles: [], hasFullstack: false }
-    }
-  }
+  let fm = stripLegacyFields(frontmatter)
+  fm = setScalar(fm, "mode", "subagent")
+  const colorLine = colorLineFor(name, fm.match(/^color:\s*(.+)$/m)?.[1])
+  if (colorLine) fm = setScalar(fm, "color", colorLine.slice("color: ".length))
+  return `---\n${fm}\n---\n${body}`
+}
 
-  function variantFile(name, tier) {
-    return `${name}.${tier}.md`
+/** A tier-pinned copy of a specialist: same body, resolved model. */
+function buildVariant(templateContent, model) {
+  const { frontmatter, body } = splitFrontmatter(templateContent)
+  let fm = stripLegacyFields(frontmatter ?? "")
+  fm = setScalar(fm, "mode", "subagent")
+  fm = setScalar(fm, "model", model)
+  if (!/^color:/m.test(fm)) {
+    const name = ""
+    fm = setScalar(fm, "color", name ? yamlColor(agentColor(name)) : yamlColor(agentColor("engineer")))
   }
+  return `---\n${fm}\n---\n${body}`
+}
 
-  function buildVariant(templateContent, model) {
-    const fmMatch = templateContent.match(/^---\r?\n([\s\S]*?)\r?\n---/)
-    const modelLine = `model: ${model}`
-    if (!fmMatch) return `---\nmode: subagent\n${modelLine}\n---\n\n${templateContent}`
-
-    let fm = fmMatch[1]
-    fm = /^mode:/m.test(fm) ? fm.replace(/^mode:.*$/m, 'mode: subagent') : `mode: subagent\n${fm}`
-    fm = /^model:/m.test(fm) ? fm.replace(/^model:.*$/m, modelLine) : `${modelLine}\n${fm}`
+/**
+ * Build a primary from the fullstack body: same identity and the same
+ * ## Abilities block, with our own frontmatter on top. The body is taken
+ * verbatim so /make-engineer only has to maintain fullstack-engineer.md and
+ * both primaries inherit whatever it lists.
+ */
+function buildPrimary(spec, fullstackContent, model) {
+  const { body } = splitFrontmatter(fullstackContent)
+  const lines = [
+    "---",
+    `description: ${spec.description}`,
+    "mode: primary",
+  ]
+  if (model) lines.push(`model: ${model}`)
+  lines.push(`color: ${yamlColor(spec.color)}`)
+  if (spec.permissions) lines.push(permissionsYaml(spec.permissions))
+  lines.push("---")
+  return `${lines.join("\n")}\n\n${body.trim()}\n`
+}
 
-    // Slice at frontmatter end: never String.replace with content-derived
-    // strings, it matches the wrong occurrence and expands $& sequences.
-    return `---\n${fm}\n---${templateContent.slice(fmMatch[0].length)}`
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf-8"))
+  } catch {
+    return null
   }
+}
 
-  // Ensure template files are mode: subagent with no stale model: line. Only
-  // build and plan are primary; every engineer is reached through task(), never
-  // picked by a human, so a primary engineer would just clutter the picker.
-  // Templates must never declare a model either: models resolve per tier at
-  // startup and are injected into generated files only, so a stale model: (from
-  // a prior `stampAgentModels` run, or from when these were primary) is
-  // stripped and the agent falls back to the session model in opencode.jsonc.
-  function normalizeTemplate(templateContent, name) {
-    const fmMatch = templateContent.match(/^---\r?\n([\s\S]*?)\r?\n---/)
-    if (!fmMatch) return templateContent
-
-    let fm = fmMatch[1]
-    let changed = false
-
-    if (!/^mode:\s*subagent/m.test(fm)) {
-      fm = /^mode:/m.test(fm) ? fm.replace(/^mode:.*$/m, 'mode: subagent') : `mode: subagent\n${fm}`
-      changed = true
+async function scanEngineers(agentsDir) {
+  try {
+    const entries = await fs.readdir(agentsDir)
+    return {
+      templates: entries
+        .filter(f => /^[\w-]+-engineer\.md$/.test(f) && f !== FULLSTACK_TEMPLATE)
+        .map(f => f.replace(/\.md$/, "")),
+      variantFiles: entries.filter(f => /^[\w-]+-engineer\.(build|fast|plan)\.md$/.test(f)),
+      hasFullstack: entries.includes(FULLSTACK_TEMPLATE),
     }
-    // Give every agent a colour derived from its name, so the same engineer
-    // reads the same in any project and two agents never collide by accident.
-    // colorLineFor also repairs a bare #hex written by an earlier version,
-    // which YAML read as a comment and opencode rejected outright.
-    if (name) {
-      const colorLine = colorLineFor(name, fm.match(/^color:\s*(.+)$/m)?.[1])
-      if (colorLine) {
-        fm = /^color:/m.test(fm) ? fm.replace(/^color:.*$/m, () => colorLine) : `${fm}\n${colorLine}`
-        changed = true
-      }
-    }
-    if (/^model:/m.test(fm)) {
-      // Remove the model: line and its trailing newline without leaving a
-      // leading blank line (model: can be the first frontmatter entry).
-      fm = fm.replace(/^model:[^\n]*\r?\n?/m, '').replace(/^\r?\n/, '').replace(/\n$/, '')
-      changed = true
-    }
-
-    return changed ? `---\n${fm}\n---${templateContent.slice(fmMatch[0].length)}` : templateContent
+  } catch {
+    return { templates: [], variantFiles: [], hasFullstack: false }
   }
+}
 
-  function descriptionOf(templateContent) {
-    return templateContent.match(/^description:\s*(.+)$/m)?.[1]?.trim() ?? null
+async function writeIfChanged(filePath, content) {
+  try {
+    if ((await fs.readFile(filePath, "utf-8")) === content) return
+  } catch {
+    // file missing, write it
   }
+  const tmpPath = `${filePath}.tmp`
+  await fs.writeFile(tmpPath, content, "utf-8")
+  await fs.rename(tmpPath, filePath)
+}
 
-  // Build a primary from the fullstack body: same identity and the same
-  // ## Abilities block, with our own frontmatter on top. The body is taken
-  // verbatim so /make-engineer only has to maintain fullstack-engineer.md and
-  // both primaries inherit whatever it lists.
-  function buildPrimary(name, spec, fullstackContent, model) {
-    const body = fullstackContent.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim()
-
-    const lines = [
-      '---',
-      `description: ${spec.description}`,
-      'mode: primary',
-    ]
-    if (model) lines.push(`model: ${model}`)
-    lines.push(`color: ${yamlColor(spec.color)}`)
-    lines.push('permission:')
-    // plan denies edit and task; the rest stays allowed so the planning skills
-    // can still read the tree and shell out to git and openspec.
-    lines.push(`  edit: ${spec.permission?.edit ?? 'allow'}`)
-    for (const key of ['bash', 'read', 'glob', 'grep', 'question', 'todowrite', 'task', 'skill']) {
-      lines.push(`  ${key}: ${spec.permission?.[key] ?? 'allow'}`)
-    }
-    lines.push('---')
-
-    return `${lines.join('\n')}\n\n${body}\n`
-  }
+export default Plugin.define({
+  id: "pc.subagent-tiers",
+  async setup(ctx) {
+    const root = ctx.location.directory
+    const agentsDir = path.join(root, ".opencode", "agents")
 
-  // Skip writing if the file already has identical content.
-  async function writeIfChanged(filePath, content) {
     try {
-      if ((await fs.readFile(filePath, "utf-8")) === content) return
-    } catch {
-      // file missing, write it
-    }
-    const tmpPath = `${filePath}.tmp`
-    await fs.writeFile(tmpPath, content, "utf-8")
-    await fs.rename(tmpPath, filePath)
-  }
-
-  return {
-    config: async (cfg) => {
-      try {
-        const models = await resolveModels()
-        const available = TIERS.filter(t => models[t])
-        const { templates, variantFiles, hasFullstack } = await scanEngineers()
+      const [user, team] = await Promise.all([
+        readJson(path.join(root, ".opencode", "harness.user.json")),
+        readJson(path.join(root, ".opencode", "harness.json")),
+      ])
+      const models = {}
+      for (const tier of TIERS) {
+        models[tier] = user?.models?.[tier] ?? team?.models?.[tier] ?? null
+      }
+      const available = TIERS.filter(t => models[t])
 
-        // build.md and plan.md are regenerated from fullstack-engineer.md every
-        // startup, which is also how an edit to fullstack propagates to both.
-        // normalizeTemplate runs on it too, so a repo carrying the old
-        // mode: primary fullstack is migrated in place on first launch.
-        if (hasFullstack) {
-          const fullstackPath = path.join(agentsDir, FULLSTACK_TEMPLATE)
-          const rawFullstack = await fs.readFile(fullstackPath, "utf-8")
-          const fullstack = normalizeTemplate(rawFullstack, FULLSTACK_NAME)
-          if (fullstack !== rawFullstack) {
-            await writeIfChanged(fullstackPath, fullstack)
-            console.error(`[pc-subagent-tiers] Normalized ${FULLSTACK_TEMPLATE} (mode: subagent)`)
-          }
+      const { templates, variantFiles, hasFullstack } = await scanEngineers(agentsDir)
 
-          for (const [name, spec] of Object.entries(PRIMARIES)) {
-            const model = models[spec.tier]
-            await writeIfChanged(
-              path.join(agentsDir, `${name}.md`),
-              buildPrimary(name, spec, fullstack, model),
-            )
-            if (cfg?.agent) {
-              // Override opencode's built-in agent of the same name rather than
-              // disabling it, so the picker shows ours with our model.
-              cfg.agent[name] = {
-                ...cfg.agent[name],
-                mode: 'primary',
-                description: spec.description,
-                color: spec.color,
-                ...(model ? { model } : {}),
-                ...(spec.permission ? { permission: { ...cfg.agent[name]?.permission, ...spec.permission } } : {}),
-              }
-            }
-          }
-          console.error(`[pc-subagent-tiers] Wrote primaries: build (${models.build ?? 'session model'}), plan (${models.plan ?? 'session model'})`)
-        } else {
-          console.error(`[pc-subagent-tiers] ${FULLSTACK_TEMPLATE} missing: build and plan not generated`)
+      if (hasFullstack) {
+        const fullstackPath = path.join(agentsDir, FULLSTACK_TEMPLATE)
+        const rawFullstack = await fs.readFile(fullstackPath, "utf-8")
+        const fullstack = normalizeTemplate(rawFullstack, FULLSTACK_NAME)
+        if (fullstack !== rawFullstack) {
+          await writeIfChanged(fullstackPath, fullstack)
+          console.error("[pc-subagent-tiers] Normalized fullstack-engineer.md (V2 subagent)")
         }
 
-        const templateContents = await Promise.all(
-          templates.map(async name => {
-            const rawContent = await fs.readFile(path.join(agentsDir, `${name}.md`), "utf-8")
-            const content = normalizeTemplate(rawContent, name)
-            // If the template had the wrong mode or a stale model:, persist the fix to disk
-            if (content !== rawContent) {
-              await writeIfChanged(path.join(agentsDir, `${name}.md`), content)
-              console.error(`[pc-subagent-tiers] Normalized ${name}.md (mode: subagent, model: removed)`)
-            }
-            return { name, content }
-          })
-        )
-
-        const keepSet = new Set()
-        const variantsToWrite = []
-
-        for (const { name, content } of templateContents) {
-          for (const tier of available) {
-            const file = variantFile(name, tier)
-            variantsToWrite.push({
-              file,
-              path: path.join(agentsDir, file),
-              content: buildVariant(content, models[tier]),
-              name,
-              tier,
-              templateContent: content,
-            })
-            keepSet.add(file)
-          }
+        for (const [name, spec] of Object.entries(PRIMARIES)) {
+          await writeIfChanged(
+            path.join(agentsDir, `${name}.md`),
+            buildPrimary(spec, fullstack, models[spec.tier]),
+          )
         }
+        console.error(`[pc-subagent-tiers] Wrote primaries: build (${models.build ?? "session model"}), plan (${models.plan ?? "session model"})`)
+      } else {
+        console.error(`[pc-subagent-tiers] ${FULLSTACK_TEMPLATE} missing: build and plan not generated`)
+      }
 
-        await Promise.all(variantsToWrite.map(v => writeIfChanged(v.path, v.content)))
-
-        if (cfg?.agent) {
-          // Ensure base templates are always mode: subagent in-memory. A repo
-          // upgraded from an earlier version may still have primary in config.
-          for (const { name } of templateContents) {
-            if (cfg.agent[name]) {
-              cfg.agent[name].mode = 'subagent'
-            }
-          }
-          if (cfg.agent[FULLSTACK_NAME]) {
-            cfg.agent[FULLSTACK_NAME].mode = 'subagent'
-          }
-          for (const { name, tier, templateContent } of variantsToWrite) {
-            const base = cfg.agent[name]
-            cfg.agent[`${name}.${tier}`] = base
-              ? { ...base, mode: 'subagent', model: models[tier] }
-              : {
-                mode: "subagent",
-                description: descriptionOf(templateContent) ?? `${name} (${tier} tier)`,
-                model: models[tier],
-              }
-          }
+      const keepSet = new Set()
+      const variantsToWrite = []
+      for (const name of templates) {
+        const rawContent = await fs.readFile(path.join(agentsDir, `${name}.md`), "utf-8")
+        const content = normalizeTemplate(rawContent, name)
+        if (content !== rawContent) {
+          await writeIfChanged(path.join(agentsDir, `${name}.md`), content)
+          console.error(`[pc-subagent-tiers] Normalized ${name}.md (V2 subagent)`)
+        }
+        for (const tier of available) {
+          const file = `${name}.${tier}.md`
+          variantsToWrite.push({ file, path: path.join(agentsDir, file), content: buildVariant(content, models[tier]) })
+          keepSet.add(file)
         }
+      }
 
-        await Promise.all(
-          variantFiles.filter(f => !keepSet.has(f)).map(f => fs.unlink(path.join(agentsDir, f)).catch(() => {}))
-        )
+      await Promise.all(variantsToWrite.map(v => writeIfChanged(v.path, v.content)))
+      await Promise.all(
+        variantFiles.filter(f => !keepSet.has(f)).map(f => fs.unlink(path.join(agentsDir, f)).catch(() => {})),
+      )
 
-        if (variantsToWrite.length > 0) {
-          console.error(`[pc-subagent-tiers] Created ${variantsToWrite.length} variant files (${templates.length} engineers x ${available.length} tiers)`)
-        } else if (templates.length > 0) {
-          console.error(`[pc-subagent-tiers] No variants created. Models: ${JSON.stringify(models)}`)
-        }
-      } catch (err) {
-        console.error(`[pc-subagent-tiers] Error: ${err.message}`)
+      if (variantsToWrite.length > 0) {
+        console.error(`[pc-subagent-tiers] Created ${variantsToWrite.length} variant files (${templates.length} engineers x ${available.length} tiers)`)
+      } else if (templates.length > 0) {
+        console.error(`[pc-subagent-tiers] No variants created. Models: ${JSON.stringify(models)}`)
       }
-    },
-  }
-}
+
+      // Best effort: if V2 already discovered these agents (same startup), pin
+      // the primaries' model and plan's read-only permissions in memory too.
+      if (typeof ctx.agent?.transform === "function") {
+        await ctx.agent.transform(editor => {
+          for (const [id, spec] of Object.entries(PRIMARIES)) {
+            const existing = editor.get(id)
+            if (!existing) continue
+            const model = models[spec.tier]
+            if (model) existing.model = model
+            existing.mode = "primary"
+            existing.description = spec.description
+            if (spec.permissions) existing.permissions = spec.permissions
+          }
+        })
+        await ctx.agent.reload?.()
+      }
+    } catch (error) {
+      console.error(`[pc-subagent-tiers] Error: ${error?.message}`)
+    }
+  },
+})