# SEED HARNESS

![SEED Harness](docs/SEED-HARNESS.png)

[한국어 README](README.ko.md)

SEED Harness is an OpenCode plugin for running traceable lab-style work through
one professor-facing agent: `Lab-Representative`.

Use `/seed` in the target project. Lab-Representative receives the goal, decides
whether a dynamic internal team is useful, tracks evidence and progress, and
writes auditable run artifacts under `.seed-agent/runs/<run_id>/`.

The user should not choose or manage internal workers. SEED registers
Lab-Representative as the single SEED OpenCode agent; task-specific members are
per-run dynamic role contracts created by Lab-Representative. SEED core does
not auto-create fixed paper-review, web-app, automation, or research-framework
teams from keywords, file types, or PDF paths.

## Requirements

- Linux runtime. This release is distributed and validated for Linux only.
  Windows and macOS are not supported yet.
- Node.js `>=20`
- OpenCode `>=1.15.6`
- At least one OpenCode model provider configured or selected. SEED can run
  with OpenAI/GPT, Anthropic/Claude, or any other OpenCode `provider/model`
  because provider auth and model selection stay in OpenCode.

Check Node and npm:

```bash
node --version
npm --version
```

Install OpenCode first:

```bash
npm install -g opencode-ai
opencode --version
```

## Install In A Target Project

Run these commands in the repository or working directory where you want `/seed`
to work:

```bash
npx --yes @seed-lab/opencode-seed-agent@latest install --project
opencode providers login -p <provider>
npx --yes @seed-lab/opencode-seed-agent@latest doctor --project --agents
opencode
```

`install --project` is model-neutral by default. If you want to pin every SEED
profile to one explicit OpenCode model instead of using the model selected in
OpenCode, add `--model provider/model`, for example:

```bash
npx --yes @seed-lab/opencode-seed-agent@latest install --project --model anthropic/claude-sonnet-4-5
```

The installer writes:

- `.opencode/opencode.jsonc`
- `.opencode/seed-agent.jsonc`
- `opencode.jsonc` in the project root as a compatibility config for OpenCode
  workspaces that do not reliably discover `.opencode/` before startup

Expected install behavior:

- OpenCode opens on `Lab-Representative`.
- SEED inherits the OpenCode selected model by default. If the professor chooses
  Claude, GPT, or another provider/model for Lab-Representative, internal SEED
  delegation and dynamic agent-threads use that same selected model unless the
  project config explicitly pins a model profile.
- OpenCode keeps provider credentials. SEED does not read or store API keys.
- Project installs ignore personal SEED config by default.
- Host MCP servers, host tools, host commands, and host agents are isolated by
  default.
- Native OpenCode `build`/`plan` primary faces are disabled for the installed
  project.

Inside OpenCode, start with:

```text
/seed "Analyze this repository and tell me the run directory."
```

Plain chat with Lab-Representative is still normal OpenCode chat. Use `/seed`
when you want SEED to create a tracked run, task board, activity briefings,
evidence ledger, and final report artifacts.

## Normal Use

Give the goal once through `/seed`:

```text
/seed "analyze this repository and improve the README"
/seed "implement the missing CLI validation flow, run checks, and write a final report"
/seed "Analyze and review ./2605.18747v1.pdf"
```

These are examples, not built-in product lanes. SEED is meant for many kinds of
repository, research, implementation, review, automation, and local workflow
tasks. Paper/PDF analysis is only one possible task.

Lab-Representative should then:

- maintain the primary task and any real subtasks;
- decide whether to run solo, delegate, or create a dynamic team;
- validate member role contracts before child sessions launch;
- keep evidence, progress, trace, and final report artifacts current;
- report blockers instead of silently waiting;
- cite task, tool, agent, or evidence records for final claims.

## Agent Threads And Message Trace

SEED treats each dynamic team member as an agent-thread: a durable work thread
with a role id, OpenCode session, mailbox, tool/skill/MCP policy, helper
budget, memory, and trace. Helper child sessions are subordinate to one
agent-thread; they are useful for bounded parallel work, but they are not
top-level team members unless Lab-Representative promotes them.

Agent-to-agent prompts go through durable message envelopes. Delivery is then
recorded as live `promptAsync`, mailbox-only, retry, or failure. Inspect:

- `.seed-agent/runs/<run_id>/threads/threads.json`
- `.seed-agent/runs/<run_id>/threads/<thread_id>/tool-manifest.json`
- `.seed-agent/runs/<run_id>/threads/<thread_id>/helpers.jsonl`
- `.seed-agent/runs/<run_id>/messages/envelopes.json`
- `.seed-agent/runs/<run_id>/messages/delivery.jsonl`
- `.seed-agent/runs/<run_id>/team/conversation.jsonl`
- `.seed-agent/runs/<run_id>/context/bundles.json`
- `.seed-agent/runs/<run_id>/context/metrics.jsonl`

Inside OpenCode, use `seed_agent_thread_status`, `seed_agent_thread_trace`,
`seed_message_queue`, `seed_message_read`, `seed_message_deliver`,
`seed_context_bundle_list`, `seed_context_bundle_read`, and
`seed_context_metrics` when Lab-Representative needs to debug who called whom,
with which prompt, tool policy, context refs, and delivery state.

SEED stores stable contracts, warm run/team summaries, hot mailbox/meeting
deltas, heavy artifact refs, and memory checkpoints in the context ledger.
Launch prompts can inline stable contract context once; later turns use digests
or refs where possible. This keeps each agent-thread's role/tool prefix more
stable for prompt-cache-friendly providers while preserving a readable audit
trail.

## Long Running Work

While a SEED run is running, type these commands directly into the OpenCode TUI:

```text
/seed-status
/seed-lab-meeting
```

Useful behavior:

- `/seed-status` and `/seed-lab-meeting` are TUI-local SEED commands. They are
  not injected into the Lab-Representative prompt through OpenCode's server
  command path.
- `/seed-status` is a read-only status board. It shows the active run,
  agent-threads, sessions/background ids, helper child-session counts, recent
  checkpoints, sub-plans, budget state, context-ledger counts, trace refs, and
  activity paths without waking Lab-Representative or mutating the run.
- Activity briefings are written under
  `.seed-agent/runs/<run_id>/activity/`, including `latest.md`.
- `/seed-lab-meeting` is the only professor command that intentionally pauses a
  running SEED runtime. It blocks new queue/delegation/write work, lets already
  running background workers finish their assigned background sessions, and
  then has Lab-Representative report current results plus the remaining plan.

Use only the three professor-facing slash commands: `/seed <goal>`,
`/seed-status`, and `/seed-lab-meeting`. Detailed report/trace/intervention
flows remain available through run artifacts and SEED tools for
Lab-Representative, but they are not registered as public slash commands.

## Manual Lab Meeting

SEED no longer opens Lab Meetings automatically on a one-hour timer. A Lab
Meeting starts only when the professor types:

```text
/seed-lab-meeting
```

When already-running background sessions finish, SEED writes a meeting summary
under the run directory, sets the run to `awaiting_feedback`, and keeps new
internal delegation/team/write-lease work paused. The next normal chat message
from the professor is recorded as Lab Meeting feedback, stored as professor
memory, and used by Lab-Representative to resume and reschedule the remaining
work. There is no separate resume slash command.

## Run Artifacts

Each run writes files under:

```text
.seed-agent/memory/
  MEMORY.md
  items/
.seed-agent/runs/<run_id>/
  run.json
  tasks.json
  events.jsonl
  agent_calls.jsonl
  model_calls.jsonl
  tool_calls.jsonl
  budget.json
  workspace/
    leases.json
    conflicts.json
    diffs.json
  idempotency/
    records.json
  meetings/
    state.json
    <meeting_id>.md
  evidence.md
  progress.md
  final_report.md
  activity/
    README.md
    latest.md
    latest.json
    <10-minute-window>.md
    raw/
  artifacts/
```

Markdown files are meant to be human-readable. JSON/JSONL files are the source
of truth for reconstruction and audit. Trace payloads redact secrets, hidden
model reasoning payloads, and raw host-tool output bodies by default.

To check whether SEED actually launched team members, inspect these artifacts.
For a tiny smoke task, Lab-Representative may record a direct-work decision in
`seed_orchestrator_record_decision`; in that case `agent_calls.jsonl` can stay
empty and `team/runtime.json` may contain only the lead `lab-representative`.
When a dynamic team is created, `agent_calls.jsonl`, `team/runtime.json`,
`team/launch-ledger.jsonl`, and `team/conversation.jsonl` show member role ids,
prompt summaries, session ids, and messages. `team/conversation.jsonl` is the
primary ordered debug log for team traffic: entries include explicit `from`/`to`,
launch ids, agent call ids, child session ids, prompt refs, allowed/denied
tools, MCP/skill policy, and read/write path metadata when available. Inside
OpenCode, use `seed_team_conversation` to read the same log.

## Configuration

Project config lives at:

```text
.opencode/seed-agent.jsonc
```

Common settings:

```jsonc
{
  "reporting": {
    "default_language": "ko"
  },
  "lab_meeting": {
    "enabled": false,
    "interval_minutes": 60
  },
  "activity_journal": {
    "enabled": true,
    "interval_minutes": 10
  },
  "permissions": {
    "execution_mode": "autonomous"
  },
  "skills": {
    "allow_project_skills": true,
    "allow_user_skills": false
  }
}
```

`reporting.default_language` controls the professor-facing runtime language, not
only the final report. With `ko`, normal chat updates, `progress.md`,
`final_report.md`, Lab Meeting notes, team summaries, and blockers are written
in Korean. With `en`, those professor-facing outputs are written in English.
Code, commands, file paths, API names, package names, and quoted source text are
left unchanged.

`permissions.execution_mode` defaults to `autonomous`. Routine
Lab-Representative edit/write/bash work is allowed so the professor is not a
click bottleneck, but configured risky bash patterns such as recursive remove,
hard reset, forced clean, `dd`, and filesystem formatting still ask for
professor approval through OpenCode. Set it to `interactive` if you want
OpenCode to ask for every edit/write/bash call.

Project skills can be placed in:

```text
.seed-agent/skills/<name>/SKILL.md
.opencode/skills/<name>/SKILL.md
.agents/skills/<name>/SKILL.md
```

Personal user skill roots are disabled by default for reproducible project
behavior.

The installer also adds a project-local `.seed-agent/skills/using-superpowers`
skill. SEED disables OpenCode's native `skill` tool by default so global
`~/.agents/skills` entries do not leak into runs; reusable workflow guidance is
loaded through SEED skill tools instead.

Internet lookup has two paths. OpenCode's native `websearch` and `webfetch`
tools are allowed for Lab-Representative by default. SEED's optional
`websearch` MCP is `auto` and becomes enabled when `EXA_API_KEY` or
`TAVILY_API_KEY` is present before OpenCode starts. Dynamic team members can use
search/fetch only when Lab-Representative grants those tools in their role
contract.

OpenCode controls the TUI color theme and renders raw tool-call lines in its
own style. For a high-signal audit view, inspect
`team/conversation.jsonl`; SEED records explicit `from -> to` entries,
prompt refs, child session ids, and the per-member `session_tools` map there.

For more details, see:

- [docs/installation.md](docs/installation.md)
- [docs/cli.md](docs/cli.md)
- [docs/commands.md](docs/commands.md)
- [docs/configuration.md](docs/configuration.md)
- [docs/architecture.md](docs/architecture.md)

## Troubleshooting

Check the published package version:

```bash
npm view @seed-lab/opencode-seed-agent version
```

Reinstall the latest project config:

```bash
npx --yes @seed-lab/opencode-seed-agent@latest install --project
```

Run doctor:

```bash
npx --yes @seed-lab/opencode-seed-agent@latest doctor --project --agents
```

If OpenCode still opens on `Build` or `Plan`, check for parent OpenCode config
files. OpenCode merges parent project configs too.

Examples:

```bash
cat ../.opencode/opencode.jsonc
```

Expected agent-list check:

```bash
opencode agent list
```

`lab-representative (primary)` should be present. `build` and `plan` should
not appear in the SEED project agent list. OpenCode may still show
its own maintenance agents such as `compaction`, `summary`, and `title`.

If `doctor --agents` says Lab-Representative is not visible, rerun the latest
installer and restart OpenCode. As a manual fallback, make sure the project
`.opencode/opencode.jsonc` contains these entries. For non-git workspaces, put
the same entries in project-root `opencode.jsonc` as well:

```jsonc
{
  "plugin": ["@seed-lab/opencode-seed-agent"],
  "default_agent": "lab-representative",
  "agent": {
    "build": { "disable": true, "hidden": true },
    "plan": { "disable": true, "hidden": true },
    "general": { "disable": true, "hidden": true },
    "explore": { "disable": true, "hidden": true },
    "scout": { "disable": true, "hidden": true },
    "lab-representative": {
      "mode": "primary",
      "description": "Lab-Representative: professor-facing SEED Lab representative."
    }
  }
}
```

After a manual edit, restart OpenCode and rerun `seed-agent doctor --agents`.

If provider auth is missing, run:

```bash
opencode providers login -p <provider>
```

Examples include `opencode providers login -p openai` for GPT models and
`opencode providers login -p anthropic` for Claude models.

## Uninstall

For a project-local install, remove the SEED plugin entry from
`.opencode/opencode.jsonc`, then remove `.opencode/seed-agent.jsonc` if you no
longer need the project config.

Run artifacts are intentionally left in `.seed-agent/runs/` for audit. Delete
them only when you no longer need the trace history.

## Maintainer Checks

For source checkout validation:

```bash
npm run verify
npm run canary:package
node ./bin/seed-agent.js doctor --project --agents
```

For a provider-backed smoke run:

```bash
node ./bin/seed-agent.js run --model anthropic/claude-sonnet-4-5 --variant high "Create a short SEED trace smoke test and stop after reporting the run directory."
```

Swap the `provider/model` for whatever OpenCode provider you have configured.
