opencode-ultracode 0.1.0

package/src/server/index.ts

@@ -0,0 +1,394 @@
+// opencode-ultracode — server plugin.
+//
+// Registers the `workflow` tool (model-facing orchestration), keyword triggers
+// ("run a workflow", "ultracode", ...), a system-prompt nudge so the model
+// recommends workflows for large tasks, and live usage tracking for sub-agent
+// child sessions.
+
+import { tool, type Hooks, type PluginInput } from "@opencode-ai/plugin"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs"
+import { generateRunId, loadPriorRun, RunEngine } from "../runtime/engine.ts"
+import { parseScript } from "../runtime/script.ts"
+import { type AgentState, type RunState, controlPath, runsRoot } from "../shared/state.ts"
+
+const KEYWORD_RE =
+  /\b(ultracode|run\s+a\s+workflow|start\s+(?:a\s+)?workflow|use\s+(?:a\s+)?workflow)\b/iu
+
+const KEYWORD_DIRECTIVE =
+  "[workflow requested] The user explicitly asked for workflow orchestration. Immediately call the `workflow` tool: author a script (must start with `export const meta = {...}`) that decomposes the request into phases and parallel agents, using agent()/parallel()/pipeline()/phase()/log(). Keep the plan proportional to the task."
+
+const SYSTEM_GUIDANCE = `## Workflow orchestration
+You have a \`workflow\` tool that fans a task out across many parallel sub-agents (50-100 in large runs) with phases, structured outputs, and a live progress view (/workflows).
+Use it when:
+- the user explicitly asks ("run a workflow", "ultracode", or the same in another language — the model decides), or
+- the task is too large for one pass: it spans many files/modules, decomposes into parallel workstreams (audit, review, migration, research), or benefits from independent adversarial verification.
+When the task seems large but the user did not ask: recommend a workflow in one or two sentences (scale + rough shape: phases and agent count) and wait for the go-ahead before calling the tool.
+Do NOT use workflows for trivial or single-file tasks.
+For script format (meta block, primitives, patterns), load the \`workflow-authoring\` skill (bundled with this plugin) before writing a script.`
+
+const TOOL_DESCRIPTION = `Run a multi-agent workflow: parallel sub-agents over phases with structured outputs, for tasks too large for one pass.
+Args: one of \`script\` (inline JS workflow, must start with \`export const meta = { name, description, phases? }\`), \`scriptPath\` (file), or \`name\` (saved workflow in .opencode/workflows/). Optional \`args\` passed to the script.
+The run starts in the background after the user approves the plan; a result turn is delivered when it finishes. The user can watch progress in /workflows (phases, per-agent model/tokens/time, stop/pause).
+\`resumeRunId\`: restart a run that was stopped or whose engine died (opencode exited while it ran). Completed agents replay from the journal; the rest run again. The user can also do this with \`p\` in /workflows.
+Use for: audits, multi-file migrations, code review across many files, research sweeps, anything parallelizable or needing independent verification.
+Authoring guide: the workflow-authoring skill (bundled with this plugin; load it first) documents agent()/parallel()/pipeline()/phase()/log(), schema-validated structured output, and quality patterns.`
+
+// Skills shipped with the plugin (skills/<name>/SKILL.md next to src/). Registered
+// through the `config` hook via `skills.paths`, so the model gets the
+// workflow-authoring skill in every project without the user copying files
+// into .opencode/skill or ~/.config/opencode/skill.
+const BUNDLED_SKILLS_DIR = fileURLToPath(new URL("../../skills", import.meta.url))
+
+type Client = NonNullable<PluginInput["client"]>
+
+function modelLabel(providerID: string | undefined, id: string | undefined): string | undefined {
+  if (!providerID || !id) return undefined
+  return `${providerID}/${id}`
+}
+
+export default async (input: PluginInput): Promise<Hooks> => {
+  const active = new Map<string, RunEngine>()
+  const sessionModel = new Map<string, string>()
+  const childSessionRun = new Map<string, string>()
+  const childSessions = new Set<string>()
+
+  const log = (level: "debug" | "info" | "warn" | "error", message: string, meta?: Record<string, unknown>) => {
+    try {
+      input.client.app.log({ body: { level, service: "workflow", message, ...meta } }).catch(() => {})
+    } catch {}
+  }
+
+  // Fetched lazily (first workflow call), never during plugin init:
+  // awaiting a client call at init deadlocks against the server that is
+  // still bootstrapping (it waits for plugins before serving HTTP).
+  let modelsPromise: Promise<Set<string>> | undefined
+  const fetchModels = (): Promise<Set<string>> => {
+    modelsPromise ??= (async () => {
+      const out = new Set<string>()
+      try {
+        const res: any = await Promise.race([
+          input.client.config.providers(),
+          new Promise((_, rej) => setTimeout(() => rej(new Error("providers timeout")), 5000)),
+        ])
+        const data = res?.providers ?? res?.data?.providers ?? res ?? []
+        for (const p of data) for (const m of Object.keys(p?.models ?? {})) out.add(`${p.id}/${m}`)
+      } catch (e) {
+        log("warn", `could not list models: ${errMsg(e)}`)
+      }
+      return out
+    })()
+    return modelsPromise
+  }
+
+  const projectRootOf = (worktree: string, directory: string): string =>
+    existsSync(worktree) ? worktree : directory
+  const opencodeDirOf = (worktree: string, directory: string): string =>
+    join(projectRootOf(worktree, directory), ".opencode")
+
+  const preview = (args: { script?: string; scriptPath?: string; name?: string }): {
+    name: string
+    description: string
+    phases: string[]
+  } => {
+      let raw = args.script
+    if (!raw && args.scriptPath) {
+      raw = readFileSync(args.scriptPath, "utf8")
+    }
+    if (!raw && args.name) {
+      const bases = [join(input.directory, ".opencode", "workflows"), join(input.worktree, ".opencode", "workflows")]
+      for (const base of bases) {
+        for (const ext of [".js", ""]) {
+          const p = join(base, `${safeName(args.name)}${ext}`)
+          if (existsSync(p)) raw = readFileSync(p, "utf8")
+        }
+      }
+    }
+    if (!raw) throw new Error("no workflow script provided")
+    const parsed = parseScript(raw)
+    return {
+      name: parsed.meta.name,
+      description: parsed.meta.description,
+      phases: (parsed.meta.phases ?? []).map((p) => p.title),
+    }
+  }
+
+  const notifyMainSession = async (mainSessionID: string, res: { runId: string; status: string; name: string; error?: string; result?: string }): Promise<void> => {
+    const lines: string[] = []
+    lines.push(`Workflow run "${res.name}" finished with status: ${res.status}.`)
+    if (res.error) lines.push(`Error: ${res.error}`)
+    if (res.result) lines.push("", "Final result:", res.result)
+    lines.push("", "Summarize the outcome for the user concisely (a few sentences). Full run details are available in /workflows.")
+    try {
+      await input.client.session.prompt({
+        path: { id: mainSessionID },
+        body: { parts: [{ type: "text", text: lines.join("\n") }] },
+      })
+    } catch (e) {
+      log("warn", `could not deliver workflow result to session: ${errMsg(e)}`)
+    }
+  }
+
+  const runsRootHere = () => runsRoot(projectRootOf(input.worktree, input.directory))
+
+  /**
+   * Restart a run in place: same runId, same script, completed agents replayed
+   * from journal.jsonl. Used by the TUI (control.json {action:"resume"} on a run
+   * with no live engine) and by the tool's `resumeRunId`.
+   */
+  const resumeRun = async (
+    runId: string,
+    opts: { runsRoot: string; notifySessionID?: string },
+  ): Promise<{ ok: true; name: string; replayable: number } | { ok: false; reason: string }> => {
+    if (active.has(runId)) return { ok: false, reason: "run is already live in this opencode" }
+    const prior = loadPriorRun(opts.runsRoot, runId)
+    if (!prior) return { ok: false, reason: "no state.json/script.js for that run" }
+    if (prior.state.status === "completed") return { ok: false, reason: "run already completed" }
+    const mainSessionID = prior.state.mainSessionID ?? opts.notifySessionID ?? ""
+    const availableModels = await fetchModels()
+    const engine = new RunEngine(
+      {
+        client: input.client as any,
+        opencodeDir: join(prior.state.directory || projectRootOf(input.worktree, input.directory), ".opencode"),
+        runsRoot: opts.runsRoot,
+        mainSessionID,
+        defaultModel: prior.state.defaultModel ?? (mainSessionID ? sessionModel.get(mainSessionID) : undefined),
+        availableModels,
+        runArgs: prior.state.args,
+        onChildSession: (_agentId, sessionId) => {
+          childSessions.add(sessionId)
+          childSessionRun.set(sessionId, runId)
+        },
+        log,
+      },
+      runId,
+    )
+    active.set(runId, engine)
+    log("info", `resuming workflow run ${runId} (${prior.replayable} agents replay)`)
+    engine
+      .run({ resume: prior })
+      .then((res) => {
+        active.delete(runId)
+        for (const [sid, rid] of childSessionRun) if (rid === runId) childSessionRun.delete(sid)
+        const target = opts.notifySessionID ?? prior.state.mainSessionID
+        if (target) notifyMainSession(target, res)
+      })
+      .catch((e) => {
+        active.delete(runId)
+        log("error", `resumed workflow run ${runId} crashed: ${errMsg(e)}`)
+      })
+    return { ok: true, name: prior.state.name, replayable: prior.replayable }
+  }
+
+  // The TUI can only write files. A live engine consumes its own control.json;
+  // a control file next to a run with NO engine in this process is a request
+  // aimed at us: "resume" restarts the run, anything else is stale and dropped.
+  const pollOrphanControls = () => {
+    let names: string[]
+    const root = runsRootHere()
+    try {
+      names = readdirSync(root).filter((n) => n.startsWith("run_"))
+    } catch {
+      return
+    }
+    for (const runId of names) {
+      if (active.has(runId)) continue
+      const cp = controlPath(root, runId)
+      let ctl: any
+      try {
+        if (!existsSync(cp)) continue
+        ctl = JSON.parse(readFileSync(cp, "utf8"))
+      } catch {
+        continue
+      }
+      try {
+        rmSync(cp, { force: true })
+      } catch {}
+      const wantResume = ctl?.action === "resume" || ctl?.resume === true
+      if (!wantResume) continue
+      resumeRun(runId, { runsRoot: root })
+        .then((r) => {
+          if (!r.ok) log("warn", `cannot resume ${runId}: ${r.reason}`)
+        })
+        .catch((e) => log("error", `resume ${runId} failed: ${errMsg(e)}`))
+    }
+  }
+  const orphanTimer = setInterval(pollOrphanControls, 1000)
+
+  const workflowTool = tool({
+    description: TOOL_DESCRIPTION,
+    args: {
+      script: tool.schema.string().optional().describe("Inline workflow script (must start with `export const meta = { name, description, phases? }`)"),
+      scriptPath: tool.schema.string().optional().describe("Path to a workflow script file"),
+      name: tool.schema.string().optional().describe("Saved workflow name (.opencode/workflows/<name>.js)"),
+      args: tool.schema.any().optional().describe("Value passed to the script as global `args` (real JSON, not a stringified list)"),
+      resumeRunId: tool.schema.string().optional().describe("Resume a stopped run (its engine died) by runId: completed agents replay, the rest run again"),
+    },
+    execute: async (args, ctx) => {
+      if (args.resumeRunId) {
+        const r = await resumeRun(args.resumeRunId, {
+          runsRoot: runsRoot(projectRootOf(input.worktree, ctx.directory)),
+          notifySessionID: ctx.sessionID,
+        })
+        if (!r.ok) return { title: "workflow: cannot resume", output: `Run ${args.resumeRunId} cannot be resumed: ${r.reason}` }
+        return {
+          title: `workflow: ${r.name} resumed`,
+          output: `Workflow "${r.name}" resumed (runId ${args.resumeRunId}); ${r.replayable} completed agent(s) replay from the journal, the rest run again. A result turn will arrive automatically when it finishes — do not poll.`,
+          metadata: { runId: args.resumeRunId },
+        }
+      }
+      if (!args.script && !args.scriptPath && !args.name)
+        return { title: "workflow: missing input", output: "Provide one of: script (inline), scriptPath, name (saved workflow), or resumeRunId." }
+
+      let plan: { name: string; description: string; phases: string[] }
+      try {
+        plan = preview(args)
+      } catch (e: any) {
+        return { title: "workflow: invalid script", output: `Could not parse workflow: ${e?.message ?? e}` }
+      }
+
+      const runId = generateRunId()
+      const availableModels = await fetchModels()
+      const engine = new RunEngine(
+        {
+          client: input.client as any,
+          opencodeDir: opencodeDirOf(input.worktree, ctx.directory),
+          runsRoot: runsRoot(projectRootOf(input.worktree, ctx.directory)),
+          mainSessionID: ctx.sessionID,
+          defaultModel: sessionModel.get(ctx.sessionID),
+          availableModels,
+          runArgs: args.args,
+          onChildSession: (agentId, sessionId) => {
+            childSessions.add(sessionId)
+            childSessionRun.set(sessionId, runId)
+          },
+          log,
+        },
+        runId,
+      )
+      active.set(runId, engine)
+
+      // Plan approval through the standard permission flow.
+      await ctx.ask({
+        permission: "workflow",
+        patterns: [plan.name],
+        always: [plan.name],
+        metadata: {
+          description: plan.description,
+          phases: plan.phases,
+          runId,
+          hint: "workflow plan approval — phases shown; use /workflows to watch progress",
+        },
+      })
+
+      engine
+        .run({ script: args.script, scriptPath: args.scriptPath, name: args.name, args: args.args })
+        .then((res) => {
+          active.delete(runId)
+          for (const [sid, rid] of childSessionRun) if (rid === runId) childSessionRun.delete(sid)
+          notifyMainSession(ctx.sessionID, res)
+        })
+        .catch((e) => {
+          active.delete(runId)
+          log("error", `workflow run ${runId} crashed: ${errMsg(e)}`)
+        })
+
+      return {
+        title: `workflow: ${plan.name} started`,
+        output: `Workflow "${plan.name}" is now running (runId ${runId}). Phases: ${plan.phases.join(" → ") || "auto"}. The user can watch progress, pause, or stop it in /workflows. A result turn will arrive automatically when the run finishes — do not poll.`,
+        metadata: { runId },
+      }
+    },
+  })
+
+  return {
+    tool: { workflow: workflowTool },
+
+    // Runs once at startup with the merged config object that opencode later
+    // hands to skill discovery, so pushing here is enough to make the bundled
+    // skills visible in this and every other project the plugin is loaded in.
+    config: async (cfg) => {
+      let isDir = false
+      try {
+        isDir = statSync(BUNDLED_SKILLS_DIR).isDirectory()
+      } catch {}
+      if (!isDir) {
+        log("warn", "bundled skills directory missing; workflow-authoring skill unavailable", { dir: BUNDLED_SKILLS_DIR })
+        return
+      }
+      const c = cfg as { skills?: { paths?: string[]; urls?: string[] } }
+      c.skills ??= {}
+      c.skills.paths ??= []
+      if (!c.skills.paths.includes(BUNDLED_SKILLS_DIR)) c.skills.paths.push(BUNDLED_SKILLS_DIR)
+      log("debug", "registered bundled skills", { dir: BUNDLED_SKILLS_DIR })
+    },
+
+    "chat.params": async (i) => {
+      const label = modelLabel(i.model?.providerID, i.model?.id)
+      if (label && !childSessions.has(i.sessionID)) sessionModel.set(i.sessionID, label)
+    },
+
+    "chat.message": async (i, o) => {
+      if (childSessions.has(i.sessionID)) return
+      const text = (o.parts ?? []).map((p) => (p as any).type === "text" ? (p as any).text ?? "" : "").join("\n")
+      if (KEYWORD_RE.test(text)) {
+        o.parts.push({
+          type: "text",
+          text: KEYWORD_DIRECTIVE,
+          id: `prt_workflow_request_${Math.random().toString(36).slice(2, 8)}`,
+        } as any)
+      }
+    },
+
+    "experimental.chat.system.transform": async (i, o) => {
+      if (i.sessionID && childSessions.has(i.sessionID)) return
+      o.system.push(SYSTEM_GUIDANCE)
+    },
+
+    event: async ({ event }) => {
+      const e = event as any
+      if (e?.type === "message.part.updated") {
+        const part = e.properties?.part
+        const runId = part?.sessionID ? childSessionRun.get(part.sessionID) : undefined
+        if (runId) active.get(runId)?.onPartUpdated(part)
+      }
+      if (e?.type === "message.updated") {
+        const m = e.properties?.info ?? e.properties?.message ?? (e.properties?.id ? e.properties : undefined)
+        const runId = m?.sessionID ? childSessionRun.get(m.sessionID) : undefined
+        if (runId) active.get(runId)?.onMessageUpdated(m)
+      }
+    },
+
+    dispose: async () => {
+      clearInterval(orphanTimer)
+      // opencode is going away: close out live runs so their state files do
+      // not claim "running" forever (the TUI would otherwise refuse to delete them).
+      // The run folder stays intact and can be resumed (p in /workflows).
+      for (const engine of active.values()) {
+        try {
+          engine.shutdown("opencode exited while the workflow was running — press p in /workflows to resume")
+        } catch (e) {
+          log("warn", `workflow shutdown failed: ${errMsg(e)}`)
+        }
+      }
+      active.clear()
+    },
+  }
+}
+
+// --- small helpers -----------------------------------------------------------
+
+function safeName(n: string): string {
+  return n.replace(/[^a-zA-Z0-9_-]/g, "-")
+}
+
+function errMsg(e: unknown): string {
+  if (e instanceof Error) return e.message
+  if (typeof e === "string") return e
+  try {
+    return JSON.stringify(e)
+  } catch {
+    return String(e)
+  }
+}

package/src/shared/format.ts

@@ -0,0 +1,123 @@
+export function fmtTokens(n: number | undefined): string {
+  if (!n) return "0 tok"
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M tok`
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k tok`
+  return `${Math.round(n)} tok`
+}
+
+/** compact token count for table cells: "58.1k", "1.2M", "512" */
+export function fmtTok(n: number | undefined): string {
+  if (!n) return "0"
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`
+  if (n >= 10_000) return `${Math.round(n / 1000)}k`
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`
+  return String(Math.round(n))
+}
+
+/** "$0.0421", "$1.23", "$0" */
+export function fmtCost(n: number | undefined): string {
+  if (!n) return "$0"
+  if (n < 0.01) return `$${n.toFixed(4)}`
+  if (n < 1) return `$${n.toFixed(3)}`
+  return `$${n.toFixed(2)}`
+}
+
+export function fmtDuration(ms: number | undefined, maxMs?: number): string {
+  if (ms == null) return "—"
+  const t = maxMs != null ? Math.min(ms, maxMs) : ms
+  if (t < 1000) return "0s"
+  const s = Math.floor(t / 1000)
+  if (s < 60) return `${s}s`
+  const m = Math.floor(s / 60)
+  const rs = s % 60
+  if (m < 60) return rs ? `${m}m ${rs}s` : `${m}m`
+  const h = Math.floor(m / 60)
+  const rm = m % 60
+  return rm ? `${h}h ${rm}m` : `${h}h`
+}
+
+/** elapsed for a still-running agent */
+export function fmtElapsed(startedAt: number | undefined, endedAt: number | undefined, now: number): string {
+  return fmtDuration(endedAt != null ? endedAt - (startedAt ?? endedAt) : startedAt ? now - startedAt : undefined)
+}
+
+/** "just now", "3m ago", "2h ago", "yesterday", "3d ago" */
+export function fmtAgo(ts: number | undefined, now: number): string {
+  if (!ts) return "—"
+  const s = Math.max(0, Math.floor((now - ts) / 1000))
+  if (s < 45) return "just now"
+  const m = Math.floor(s / 60)
+  if (m < 60) return `${m}m ago`
+  const h = Math.floor(m / 60)
+  if (h < 24) return `${h}h ago`
+  const d = Math.floor(h / 24)
+  if (d === 1) return "yesterday"
+  return `${d}d ago`
+}
+
+export function fmtClock(ts: number | undefined): string {
+  if (!ts) return "—"
+  const d = new Date(ts)
+  const p = (n: number) => String(n).padStart(2, "0")
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`
+}
+
+/** "anthropic/claude-sonnet-4-6" -> "claude-sonnet-4-6"; keeps provider for unknown tiers */
+export function shortModel(model: string | undefined): string {
+  if (!model) return "default"
+  const i = model.indexOf("/")
+  return i >= 0 ? model.slice(i + 1) : model
+}
+
+/** clamp a string to n chars with an ellipsis */
+export function clip(s: string, n: number): string {
+  if (n <= 0) return ""
+  if (s.length <= n) return s
+  if (n === 1) return "…"
+  return s.slice(0, n - 1) + "…"
+}
+
+/** clip then pad to exactly n chars (left-aligned) */
+export function cell(s: string, n: number): string {
+  return clip(s, n).padEnd(n)
+}
+
+/** clip then pad to exactly n chars (right-aligned) */
+export function cellR(s: string, n: number): string {
+  return clip(s, n).padStart(n)
+}
+
+/** collapse whitespace/newlines into one line */
+export function oneLine(s: string | undefined): string {
+  return String(s ?? "").replace(/\s+/g, " ").trim()
+}
+
+/** word-wrap text to a column width, preserving explicit newlines */
+export function wrapWords(text: string | undefined, width: number): string[] {
+  const w = Math.max(8, width | 0)
+  const out: string[] = []
+  for (const raw of String(text ?? "").replace(/\r/g, "").split("\n")) {
+    const line = raw.replace(/\t/g, "  ")
+    if (line.length <= w) {
+      out.push(line)
+      continue
+    }
+    let cur = ""
+    for (const word of line.split(" ")) {
+      if (word.length > w) {
+        if (cur) out.push(cur)
+        cur = ""
+        for (let i = 0; i < word.length; i += w) out.push(word.slice(i, i + w))
+        continue
+      }
+      if (!cur) cur = word
+      else if (cur.length + 1 + word.length <= w) cur += " " + word
+      else {
+        out.push(cur)
+        cur = word
+      }
+    }
+    if (cur) out.push(cur)
+  }
+  return out
+}