# SEED HARNESS

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

[English README](README.md)

SEED Harness는 OpenCode에서 하나의 사용자-facing agent,
`Lab-Representative`, 를 통해 추적 가능한 연구실식 작업을 수행하게 해주는
플러그인입니다.

대상 프로젝트에서 `/seed`를 사용하세요. Lab-Representative가 목표를 받고,
필요하면 동적 내부 팀을 구성하며, evidence와 progress를 관리하고, 실행 기록을
`.seed-agent/runs/<run_id>/` 아래에 남깁니다.

사용자는 내부 worker를 직접 고르거나 관리하지 않아도 됩니다. SEED가 OpenCode에
등록하는 SEED agent는 Lab-Representative 하나이며, 실제 작업 팀은 매 run마다
Lab-Representative가 작성하는 dynamic role contract로 정해집니다. SEED core는
keyword, file type, PDF path만 보고 paper-review, web-app, automation,
research-framework 같은 고정 팀을 자동 생성하지 않습니다.

## Requirements

- Linux runtime. 이번 릴리스는 Linux에서만 배포/검증합니다. Windows와 macOS는
  아직 지원 대상이 아닙니다.
- Node.js `>=20`
- OpenCode `>=1.15.6`
- OpenCode에 설정되거나 선택된 model provider 하나 이상. SEED는 provider
  인증과 model 선택을 OpenCode에 맡기므로 OpenAI/GPT, Anthropic/Claude, 그 밖의
  OpenCode `provider/model`로 동작할 수 있습니다.

Node와 npm을 확인합니다.

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

OpenCode를 먼저 설치합니다.

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

## Target Project에 설치

`/seed`를 사용할 repository나 작업 디렉터리에서 실행합니다.

```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`의 기본값은 model-neutral입니다. OpenCode에서 현재 선택된
모델을 쓰지 않고 모든 SEED profile을 하나의 모델로 고정하고 싶을 때만
`--model provider/model`을 추가하세요.

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

Installer가 생성하는 파일:

- `.opencode/opencode.jsonc`
- `.opencode/seed-agent.jsonc`
- `.opencode/`를 시작 전에 안정적으로 발견하지 못하는 OpenCode workspace를 위한
  project root `opencode.jsonc`

기대 동작:

- OpenCode가 `Lab-Representative`로 열립니다.
- SEED는 기본적으로 OpenCode에서 선택된 모델을 상속합니다. 교수님이
  Lab-Representative 모델로 Claude, GPT, 또는 다른 provider/model을 고르면
  내부 delegation과 동적 agent-thread도 같은 선택 모델을 사용합니다. 단, project
  config에서 model profile을 명시적으로 고정한 경우에는 그 설정이 우선합니다.
- Provider credential은 OpenCode가 관리합니다. SEED는 API key를 읽거나 저장하지
  않습니다.
- Project install은 개인 SEED config를 기본적으로 무시합니다.
- Host MCP server, host tool, host command, host agent는 기본적으로 격리됩니다.
- OpenCode native `build`/`plan` primary face는 해당 project config에서
  비활성화됩니다.

OpenCode 안에서는 이렇게 시작합니다.

```text
/seed "이 repository를 분석하고 run directory를 알려줘."
```

Lab-Representative에게 그냥 입력하면 일반 OpenCode chat으로 동작합니다.
SEED가 추적 가능한 run, task board, activity briefing, evidence ledger,
final report artifact를 만들게 하려면 `/seed`로 시작하세요.

## 일반 사용

목표는 `/seed`로 한 번 줍니다.

```text
/seed "이 repository를 분석하고 README를 개선해줘"
/seed "빠진 CLI validation flow를 구현하고 check를 돌린 뒤 final report를 써줘"
/seed "Analyze and review ./2605.18747v1.pdf"
```

위 항목들은 예시일 뿐, 내장 product lane이 아닙니다. SEED는 repository 분석,
구현, 리뷰, 연구 프레임워크 설계, 로컬 자동화, 기타 workflow 작업을 다루기
위한 하네스입니다. 논문/PDF 분석은 가능한 작업 중 하나입니다.

Lab-Representative는 다음을 수행해야 합니다.

- primary task와 실제 subtask 관리
- 혼자 처리할지, delegate할지, dynamic team을 만들지 판단
- child session launch 전에 member role contract 검증
- evidence, progress, trace, final report artifact 유지
- 조용히 기다리지 않고 blocker 보고
- final claim에 task, tool, agent, evidence record 인용

## Agent Thread와 Message Trace

SEED에서 동적 팀원은 agent-thread입니다. 즉 role id, OpenCode session,
mailbox, tool/skill/MCP policy, helper budget, memory, trace를 가진 durable
작업 thread입니다. helper child session은 특정 agent-thread에 종속된 작은
병렬 작업 단위이며, Lab-Representative가 승격하지 않는 한 top-level 팀원이
아닙니다.

agent 사이의 prompt는 durable message envelope로 남고, delivery supervisor가
live `promptAsync`, mailbox-only, retry, failure 상태를 기록합니다. 확인 경로:

- `.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`

OpenCode 안에서는 `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`, `seed_context_metrics`로
누가 누구에게 어떤 prompt, tool policy, context ref로 요청했고 delivery가
어떻게 처리됐는지 확인할 수 있습니다.

SEED는 stable contract, warm run/team summary, hot mailbox/meeting delta,
heavy artifact ref, memory checkpoint를 context ledger에 저장합니다. launch
prompt에는 stable contract를 한 번 inline할 수 있고, 이후 turn에서는 가능하면
digest나 ref를 사용합니다. 이렇게 agent-thread별 role/tool prefix를 더 안정적으로
유지해 prompt-cache 친화적인 provider에서 이득을 기대할 수 있고, 동시에 사람이
읽을 수 있는 audit trail도 남깁니다.

## 긴 작업 확인

SEED run이 진행 중일 때, OpenCode TUI에 바로 입력할 수 있는 명령:

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

유용한 동작:

- `/seed-status`와 `/seed-lab-meeting`은 TUI-local SEED command입니다.
  OpenCode server command 경로로 Lab-Representative prompt에 주입되지
  않습니다.
- `/seed-status`는 완전 읽기 전용 상태판입니다. active run, agent-thread,
  session/background id, helper child-session 수, 최근 checkpoint, sub-plan,
  budget state, context-ledger count, trace ref, activity path를 보여주되 Lab-Representative를
  깨우거나 run state를 바꾸지 않습니다.
- Activity briefing은 `.seed-agent/runs/<run_id>/activity/` 아래에 쓰이며,
  `latest.md`가 최신 briefing입니다.
- `/seed-lab-meeting`은 교수님이 의도적으로 runtime을 멈추는 유일한 공개
  command입니다. 새 queue/delegation/write 작업을 막고, 이미 실행 중인
  background worker는 맡은 background session을 끝까지 마무리하게 한 뒤,
  Lab-Representative가 현재 결과와 남은 계획을 보고하게 합니다.

교수용 slash command는 `/seed <목표>`, `/seed-status`,
`/seed-lab-meeting` 세 개만 사용합니다. 상세 report/trace/intervention은 run
artifact와 Lab-Representative용 SEED tool로 남아 있지만, public slash command로
등록하지 않습니다.

## 수동 Lab Meeting

SEED는 더 이상 1시간 타이머로 Lab Meeting을 자동으로 열지 않습니다. Lab
Meeting은 교수님이 다음 command를 직접 입력했을 때만 시작됩니다.

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

이미 실행 중인 background session이 끝나면 SEED는 run directory 아래에 meeting
summary를 쓰고, run을 `awaiting_feedback`으로 바꾸며 새 내부
delegation/team/write-lease 작업을 계속 멈춰둡니다. 그 다음 교수님이 일반 채팅
메시지로 피드백을 보내면, 그 메시지가 Lab Meeting feedback으로 기록되고 professor
memory에도 저장됩니다. 이후 Lab-Representative가 그 피드백을 기준으로 runtime을
resume하고 남은 작업을 다시 스케줄합니다. 별도의 resume slash command는 없습니다.

## Run Artifacts

각 run은 다음 위치에 기록됩니다.

```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 파일은 사람이 읽기 좋은 보고서입니다. JSON/JSONL 파일은 reconstruction과
audit을 위한 source of truth입니다. Trace payload는 기본적으로 secret, hidden
model reasoning payload, raw host-tool output body를 redact합니다.

팀원이 실제로 호출됐는지는 다음 파일로 확인합니다. 아주 짧은 smoke처럼
Lab-Representative가 `seed_orchestrator_record_decision`에 단일 직접 처리
결정을 남긴 경우에는 `agent_calls.jsonl`이 비어 있고, `team/runtime.json`에는
lead인 `lab-representative`만 보일 수 있습니다. 큰 작업에서 동적 팀이 만들어지면
`agent_calls.jsonl`, `team/runtime.json`, `team/launch-ledger.jsonl`,
`team/conversation.jsonl`에 팀원 role id, 프롬프트 요약, session id, 메시지가
기록됩니다. 특히 `team/conversation.jsonl`은 호출/메시지 순서대로 명시적인
`from`/`to`, launch id, agent call id, child session id, prompt ref,
허용/차단 tool, MCP/skill policy, read/write path 메타데이터를 남기는 기본
디버깅 로그입니다. OpenCode 안에서는 `seed_team_conversation`으로 같은 로그를
읽을 수 있습니다.

## Configuration

Project config 위치:

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

자주 쓰는 설정:

```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`는 보고서만이 아니라 교수-facing 기본 언어를
정합니다. `ko`이면 일반 응답, `progress.md`, `final_report.md`, Lab Meeting
요약, 팀원 보고/차단 사유가 한국어로 작성됩니다. `en`으로 바꾸면 같은
교수-facing 출력이 영어로 작성됩니다. 코드, 명령어, 파일 경로, API 이름,
패키지명, 원문 인용은 번역하지 않습니다.

`permissions.execution_mode` 기본값은 `autonomous`입니다.
Lab-Representative의 일반적인 edit/write/bash는 교수님이 엔터를 계속 누르지
않아도 진행되지만, recursive remove, hard reset, forced clean, `dd`, filesystem
formatting 같은 위험 bash 패턴은 OpenCode 권한 프롬프트로 교수 승인을 묻습니다.
모든 edit/write/bash마다 OpenCode가 묻게 하려면 `interactive`로 바꾸세요.

Project skill 위치:

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

재현 가능한 project behavior를 위해 personal user skill root는 기본적으로
비활성화됩니다.

Installer는 `.seed-agent/skills/using-superpowers` project skill도 함께
추가합니다. SEED는 전역 `~/.agents/skills`가 run에 새어 들어오지 않도록
OpenCode native `skill` tool을 기본 비활성화하고, 재사용 workflow 지침은 SEED
skill tool을 통해 로드합니다.

인터넷 조회 경로는 두 가지입니다. OpenCode native `websearch`, `webfetch`는
Lab-Representative에게 기본 허용됩니다. SEED optional `websearch` MCP는
`auto`이며, OpenCode 시작 전에 `EXA_API_KEY` 또는 `TAVILY_API_KEY`가 있으면
enabled가 됩니다. Dynamic team member는 Lab-Representative가 role contract의
tool policy에 search/fetch 도구를 열어준 경우에만 인터넷 검색을 사용할 수
있습니다.

OpenCode TUI 색상과 raw tool-call 라인의 명암은 OpenCode가 렌더링합니다.
사람이 읽는 감사용 뷰는 `team/conversation.jsonl`을 보세요. SEED는 여기에
명시적인 `from -> to`, prompt ref, child session id, 그리고 팀원 세션에 전달된
`session_tools` tool map을 남깁니다.

자세한 문서:

- [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

배포된 package version 확인:

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

최신 project config 재설치:

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

Doctor 실행:

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

OpenCode가 아직 `Build`나 `Plan`으로 열린다면 parent OpenCode config를
확인하세요. OpenCode는 parent project config도 merge합니다.

예시:

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

Agent list 확인:

```bash
opencode agent list
```

`lab-representative (primary)`는 보여야 합니다. `build`, `plan`은 SEED
project agent list에 보이면 안 됩니다. OpenCode 내부
maintenance agent인 `compaction`, `summary`, `title`은 보일 수 있습니다.

`doctor --agents`가 Lab-Representative를 찾지 못한다고 하면 최신 installer를
다시 실행하고 OpenCode를 재시작하세요. 임시 수동 fallback으로는 project
`.opencode/opencode.jsonc`에 최소한 아래 항목이 들어가 있어야 합니다. git repo가
아닌 작업 폴더에서는 project root의 `opencode.jsonc`에도 같은 항목을 넣으세요.

```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."
    }
  }
}
```

수동으로 고친 뒤에는 OpenCode를 재시작하고 `seed-agent doctor --agents`를
다시 실행하세요.

Provider auth가 없다면:

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

예를 들어 GPT 모델은 `opencode providers login -p openai`, Claude 모델은
`opencode providers login -p anthropic`처럼 OpenCode provider를 인증합니다.

## Uninstall

Project-local install을 제거하려면 `.opencode/opencode.jsonc`에서 SEED plugin
entry를 지우고, project config가 더 필요 없으면 `.opencode/seed-agent.jsonc`를
삭제합니다.

Run artifact는 audit을 위해 `.seed-agent/runs/`에 남깁니다. Trace history가 더
이상 필요 없을 때만 삭제하세요.

## Maintainer Checks

Source checkout 검증:

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

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."
```

`provider/model`은 현재 OpenCode에 설정된 모델로 바꿔 실행하면 됩니다.
