opencode-ultracode 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdulkadir Polat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# opencode-ultracode
+
+[![npm version](https://img.shields.io/npm/v/opencode-ultracode.svg)](https://www.npmjs.com/package/opencode-ultracode)
+[![license](https://img.shields.io/github/license/polatdev/opencode-ultracode.svg)](https://github.com/polatdev/opencode-ultracode/blob/main/LICENSE)
+
+Multi-agent workflow orchestration for [opencode](https://opencode.ai). The model
+writes a small JavaScript script that fans a task out across phases of parallel
+sub-agents, and you watch, pause, resume and stop the run from a live
+`/workflows` view inside the TUI.
+
+It's a plugin, not an MCP server, not a separate app. There is **no daemon and
+no service** to run — the engine lives inside your opencode process, sub-agents
+are ordinary opencode child sessions, and progress is written to a state file
+the TUI polls.
+
+```
+╭ ⠋ audit-payments ──────────────────────────────────────────────────────────╮
+│ phases                    │ agent           model     ctx    tools    time │
+│ ● 1 Scan          12/12   │ ✓ find:webhooks sonnet-4  38k    6 tools  41s  │
+│ ● 2 Verify        18/24   │ ⠋ verify:idem-2 sonnet-4  21k    3 tools  12s  │
+│ ○ 3 Synthesize     0/1    │ ⠋ verify:idem-3 qwen3.8   17k    2 tools   9s  │
+│                           │ ○ verify:retry-1 sonnet-4                      │
+├────────────────────────────────────────────────────────────────────────────┤
+│ ⠋ verify:idem-2           │ grep done · src/Services/Payment        3s ago │
+╰────────────────────────────────────────────────────────────────────────────╯
+ ↑↓ agent  ←→ pane  ⏎ open agent  r result  x stop  p pause  s save  esc back
+```
+
+## Why
+
+Some tasks do not fit one context: auditing every handler in a large codebase,
+migrating dozens of files, reviewing a big diff from several angles, or
+research that needs independent verification before you trust it. A single
+agent either runs out of context or quietly narrows the job.
+
+`opencode-ultracode` gives the model a `workflow` tool that decomposes such a
+task into phases of parallel sub-agents with structured outputs, asks you to
+approve the plan, runs it in the background, and delivers the result back into
+your session when it is done. You get a live view of every agent, its model,
+context size, tool calls and thinking, and you can stop or pause at any point.
+
+## Install
+
+The package ships two entrypoints: the **server plugin** (the tool and the
+engine) and the **TUI plugin** (the `/workflows` screens). Each goes in its
+own config file.
+
+Server plugin — add it to `opencode.json` (global `~/.config/opencode/opencode.json`
+or per-project):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "opencode-ultracode"
+  ]
+}
+```
+
+TUI plugin — add the same package to `tui.json` (global `~/.config/opencode/tui.json`
+or per-project `.opencode/tui.json`):
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": [
+    "opencode-ultracode"
+  ]
+}
+```
+
+opencode installs npm plugins automatically at startup — there is nothing to
+`npm install` yourself. Restart opencode and `/workflows` opens the run list.
+
+### From a checkout
+
+To run the plugin from source instead, point both config files at the entry
+files:
+
+```json
+// opencode.json
+{ "plugin": ["/path/to/opencode-ultracode/src/server/index.ts"] }
+```
+
+```json
+// tui.json
+{ "plugin": ["/path/to/opencode-ultracode/src/tui/index.tsx"] }
+```
+
+## How it works
+
+Ask for it in plain words. Any of these make the model call the tool right away:
+
+> run a workflow that audits every payment handler for missing idempotency checks
+>
+> ultracode: migrate all repositories from Doctrine to Eloquent
+
+For a large task you did not phrase this way, the model recommends a workflow
+(phases and rough agent count) and waits for your go-ahead.
+
+1. The model authors a script, or picks a saved one, and calls `workflow`.
+2. opencode shows a permission prompt with the plan: name, description, phases.
+3. The run starts in the background. Open `/workflows` to watch it.
+4. When the run finishes, its result arrives as a new turn in the session that
+   started it.
+
+Sub-agents run in their own child sessions with the project's tools and
+permissions. When one of them is blocked on a permission or a question, the
+workflow views flag it and let you answer without leaving the screen.
+
+If opencode exits while a run is in progress, the run is not lost. Every
+completed agent is journaled, so resuming replays those results and only runs
+the remaining agents again.
+
+### The `workflow` tool
+
+| Argument      | Meaning                                                             |
+|---------------|---------------------------------------------------------------------|
+| `script`      | Inline workflow script                                              |
+| `scriptPath`  | Path to a script file                                               |
+| `name`        | Saved workflow from `.opencode/workflows/<name>.js`                 |
+| `args`        | Value exposed to the script as `args`                               |
+| `resumeRunId` | Resume a stopped run, or one whose engine died, by its run id       |
+
+### Writing a script
+
+Scripts are plain JavaScript. They begin with a pure-literal `meta` block and
+then use the primitives below. The bundled `workflow-authoring` skill teaches
+the model the full format and the quality patterns; it is registered
+automatically in every project the plugin is loaded in.
+
+```js
+export const meta = {
+  name: 'review-changes',
+  description: 'Review changed files across dimensions, verify each finding',
+  phases: [{ title: 'Review' }, { title: 'Verify' }, { title: 'Synthesize' }],
+}
+
+const FINDING = { type: 'object', properties: { findings: { type: 'array' } }, required: ['findings'] }
+const VERDICT = { type: 'object', properties: { isReal: { type: 'boolean' }, why: { type: 'string' } }, required: ['isReal'] }
+
+const dims = [
+  { key: 'bugs', prompt: 'Review the current diff for correctness bugs…' },
+  { key: 'perf', prompt: 'Review the current diff for performance problems…' },
+]
+
+// pipeline: each dimension moves on to Verify as soon as its own Review is done
+const verified = await pipeline(
+  dims,
+  d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review', schema: FINDING }),
+  r => parallel((r?.findings ?? []).map(f => () =>
+    agent(`Try to REFUTE this finding: ${JSON.stringify(f)}`, { label: `verify:${f.file}`, phase: 'Verify', schema: VERDICT })
+      .then(v => ({ ...f, verdict: v }))
+  )),
+)
+
+phase('Synthesize')
+const confirmed = verified.flat().filter(Boolean).filter(f => f.verdict?.isReal)
+log(`${confirmed.length} confirmed findings`)
+return await agent(`Write the final report for these findings: ${JSON.stringify(confirmed)}`, { label: 'report' })
+```
+
+| Primitive                    | What it does                                                                                                                                                         |
+|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `agent(prompt, opts?)`       | Spawns a sub-agent in its own session. Resolves to the schema-validated object or the final text, `null` on failure or stop. `opts`: `label`, `phase`, `schema`, `model`. |
+| `parallel(thunks)`           | Runs `Array<() => Promise>` concurrently and waits for all of them. A throwing thunk becomes `null`.                                                                 |
+| `pipeline(items, ...stages)` | Runs each item through every stage independently, with no barrier between stages. The default choice.                                                               |
+| `phase(title)`               | Starts a display phase. Use the same titles as `meta.phases`.                                                                                                        |
+| `log(message)`               | Narrator line shown in the run view.                                                                                                                                 |
+| `args`                       | Whatever the tool call passed as `args`.                                                                                                                             |
+| `budget`                     | `{ total, spent(), remaining() }`. `agent()` throws once `total` is reached.                                                                                         |
+
+Scripts have no filesystem, network or Node APIs. `Date.now()`, `Math.random()`
+and no-arg `new Date()` throw so a resumed run replays deterministically.
+Concurrency is capped at roughly `min(16, cpus - 2)` agents at a time and
+1000 agents per run.
+
+## The `/workflows` TUI
+
+| Screen       | Keys                                                                                                                                              |
+|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
+| Run list     | `↑↓` select · `⏎` open · `r` result · `x` stop · `p` pause / resume · `s` save script · `d` delete · `esc` back                                    |
+| Run view     | `↑↓` phase or agent · `←→` switch pane · `⏎` open · `r` result · `x` stop · `p` pause / resume · `s` save · `!` answer a pending permission         |
+| Agent detail | `↑↓` scroll · `←→` previous / next agent · `e` show tool and thinking previews · `p` expand prompt · `⏎` answer a permission or question           |
+| Result view  | `↑↓` scroll · `g` top                                                                                                                             |
+
+The agent detail shows a **Live** feed while the agent runs (text, thinking
+marked `∴`, tool calls marked `⚙`, newest first), the prompt, an **Activity**
+list with one row per tool call and per thinking block with its duration, and
+the final outcome.
+
+```
+Activity · 3 tools · 2 thoughts                                 e shows previews
+✓ grep    /Users/me/PhpstormProjects/payzink-api                             0s
+✓ think   Retry logic lives in the webhook handler, so the idempotency…     16s
+✓ read    src/Services/Payment/RetryService.php                              1s
+⠋ think   Comparing the two idempotency checks…                              3s
+```
+
+Thinking rows appear only when the provider streams reasoning. With thinking
+disabled the list holds tool calls only.
+
+### Where things live
+
+| Path                                                 | Contents                                                                                                   |
+|------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
+| `/tmp/opencode-workflows/<project>-<hash>/<runId>/`  | Run artifacts: `state.json`, `journal.jsonl`, `script.js`, `control.json`. Scratch data, safe to delete.  |
+| `<project>/.opencode/workflows/<name>.js`            | Saved workflows (`s` in the TUI). Project assets; commit them if you like.                                 |
+
+The TUI polls `state.json` and merges it fine-grained, so only changed cells
+redraw. Pause, resume and stop are written to `control.json` and picked up by
+the engine.
+
+## Requirements
+
+- opencode `>= 1.3.4`
+- Node.js >= 22 (only matters if you're developing the plugin itself; end
+  users just add it to `opencode.json` and `tui.json`)
+
+## Development
+
+```bash
+npm install
+npm run typecheck      # tsc --noEmit
+npm run test:runtime   # engine self-test against a mock opencode client
+```
+
+```
+src/
+  server/index.ts    server plugin: workflow tool, triggers, system guidance, usage tracking
+  runtime/engine.ts  run engine: agents, phases, journal, resume, state file
+  runtime/script.ts  script parsing and the deterministic sandbox
+  runtime/schema.ts  structured-output schema handling
+  tui/index.tsx      TUI plugin: /workflows routes and keymaps
+  tui/store.ts       state.json polling and fine-grained merge
+  tui/requests.ts    pending permission / question tracking for sub-agents
+  shared/            types and formatting shared by both plugins
+skills/workflow-authoring/SKILL.md
+```
+
+## License
+
+MIT © [Abdulkadir Polat](https://github.com/polatdev)

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "opencode-ultracode",
+  "version": "0.1.0",
+  "description": "Workflow orchestration for opencode: model-authored scripts, parallel sub-agent fleet, live TUI progress view",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdulkadir Polat",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/polatdev/opencode-ultracode.git"
+  },
+  "homepage": "https://github.com/polatdev/opencode-ultracode#readme",
+  "bugs": {
+    "url": "https://github.com/polatdev/opencode-ultracode/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "workflow",
+    "multi-agent",
+    "orchestration",
+    "tui"
+  ],
+  "exports": {
+    "./server": "./src/server/index.ts",
+    "./tui": "./src/tui/index.tsx"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "opencode": ">=1.3.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test:runtime": "node src/runtime/selftest.ts",
+    "prepublishOnly": "npm run typecheck && npm run test:runtime"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.15.13"
+  },
+  "peerDependencies": {
+    "@opentui/solid": "^0.5.11",
+    "solid-js": "^1.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "@opentui/keymap": "^0.5.11",
+    "@opentui/solid": "^0.5.11",
+    "solid-js": "^1.9.0",
+    "zod": "^4.1.8"
+  }
+}

package/skills/workflow-authoring/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: workflow-authoring
+description: "Reference for authoring opencode workflow scripts: meta block, agent()/parallel()/pipeline()/phase()/log(), structured output schemas, quality patterns. Use ONLY when writing or editing a workflow script for the workflow tool."
+---
+
+# Workflow authoring (opencode-workflow)
+
+A workflow structures work across many agents — to be comprehensive (decompose and
+cover in parallel), to be confident (independent perspectives and adversarial checks
+before committing), or to take on scale one context can't hold (migrations, audits,
+broad sweeps). The script is where you encode that structure: what fans out, what
+verifies, what synthesizes.
+
+Hybrid tip: scout inline first (list the files, scope the diff) to discover the
+work-list, then call the `workflow` tool and pipeline over it.
+
+## Meta block (required, pure literal)
+
+Every script starts with:
+
+```js
+export const meta = {
+  name: 'find-flaky-tests',
+  description: 'Find flaky tests and propose fixes', // one line, shown in the approval dialog
+  whenToUse: 'when tests are flaky',                // optional
+  phases: [                                          // optional; one entry per phase() call
+    { title: 'Scan', detail: 'grep test logs for retries' },
+    { title: 'Fix', detail: 'one agent per flaky test' },
+  ],
+}
+```
+
+- `meta` must be a PURE LITERAL — no variables, function calls, spreads, template strings.
+- Use the SAME phase titles in `meta.phases` as in `phase()` calls.
+- `name` is used for saving (`s` in /workflows) and for invoking saved workflows by name.
+
+## Script body primitives
+
+- `agent(prompt, opts?)` → spawns a sub-agent in an isolated child session; resolves to
+  its structured result (with `schema`) or final text (without). Resolves to `null` if
+  the run is stopped or the agent fails — filter with `.filter(Boolean)`.
+  - `opts.label` — display name (shown in /workflows), e.g. `'tip:design'`
+  - `opts.phase` — assign to a progress group (use inside pipeline/parallel stages)
+  - `opts.schema` — JSON Schema; the agent is forced to return a matching JSON object
+  - `opts.model` — e.g. `'anthropic/claude-sonnet-4'`; omit to inherit the session model
+- `parallel(thunks)` → run `Array<() => Promise>` concurrently; BARRIER (awaits all).
+  A throwing thunk yields `null` in the result array — the call never rejects.
+- `pipeline(items, stage1, stage2, ...)` → run each item through all stages INDEPENDENTLY,
+  no barrier between stages. Stage callback receives `(prevResult, originalItem, index)`.
+  A throwing stage drops that item to `null` and skips its remaining stages.
+- `phase(title)` → start a display phase; subsequent agents group under it.
+- `log(message)` → narrator line in /workflows.
+- `args` → value passed via the tool's `args` input (undefined if omitted).
+- `budget` → `{ total, spent(), remaining() }`. `total` is null unless the user set a
+  token target; once `spent()` reaches `total`, further `agent()` calls throw.
+
+**DEFAULT TO pipeline().** Use `parallel()` (a barrier) only when stage N genuinely needs
+ALL of stage N-1's results at once (dedup across findings, early-exit on zero, comparing
+"the other findings"). Otherwise a barrier wastes the fast finders' time.
+
+## Constraints in scripts
+
+- Plain JavaScript (not TypeScript). No filesystem, no Node API, no network.
+- `Date.now()`, `Math.random()`, and no-arg `new Date()` THROW (determinism for resume).
+  Pass timestamps in via `args`; vary prompts/labels by index instead of randomness.
+- Concurrency is capped (~min(16, cpus-2) parallel agents); the total agent cap is 1000.
+- Sub-agents run in their own sessions with the project's tools and permissions — for
+  long autonomous runs, pre-allow the tools agents need.
+
+## Quality patterns
+
+- Adversarial verify: N independent skeptics per finding prompted to REFUTE; kill if
+  ≥majority refute.
+- Perspective-diverse verify: distinct lenses (correctness, security, perf, repro)
+  instead of N identical refuters.
+- Judge panel: N independent attempts from different angles, scored by parallel judges,
+  synthesize from the winner.
+- Loop-until-dry: keep spawning finders until K consecutive rounds return nothing new.
+- Multi-modal sweep: parallel agents each searching a different way (by-container,
+  by-content, by-entity).
+- Completeness critic: final agent asks "what's missing?" — its findings become the
+  next round.
+- No silent caps: `log()` anything you truncate top-N or drop.
+
+## Scale
+
+"find any bugs" → a few finders, single-vote verify. "thoroughly audit this" → larger
+finder pool, 3-vote adversarial pass, synthesis stage. Runs with >25 agents are flagged
+as large — expect a permission prompt for the plan either way.