amicus 4.3.0 → 4.4.1

package/docs/opencode-integration.md

@@ -0,0 +1,114 @@
+# OpenCode Integration
+
+How Amicus integrates with OpenCode's native capabilities and avoids redundant implementations.
+
+## SDK & API Notes
+
+### OpenCode SDK Requirements
+
+- SDK's `createOpencodeServer()` spawns `opencode` CLI internally
+- `opencode-ai` is a regular dependency -- its binary is in `node_modules/.bin/`
+- `src/utils/path-setup.js` adds `node_modules/.bin/` to PATH so the binary is always found
+- SDK is ESM-only; use dynamic `import()` not `require()` in CommonJS projects
+- Jest can't mock dynamic imports without `--experimental-vm-modules` - skip those tests
+
+### OpenCode API Format
+
+- Model must be object: `{ providerID: 'openrouter', modelID: 'google/gemini-2.5-flash' }`
+- Sending model as string causes 400 Bad Request
+- Use `formatModelForAPI()` from `electron/ui/model-picker.js` for conversion
+
+### Session Status Idle Signal
+
+The OpenCode SDK exposes `client.session.status({ path: { id } })`, wrapped by `getSessionStatus()` in `src/opencode-client.js`. In headless runs this is the **authoritative completion signal**: when the response is `{ type: 'idle' }`, the poll loop in `src/headless.js` treats the session as done and exits immediately.
+
+This signal is **gated on real output existing** (the `output.length > 0` check at `src/headless.js` line 500) so a pre-processing `idle` response from the SDK cannot end the run before the model has produced any text. If the status call fails or returns an unexpected shape, the code falls back transparently to the activity-heuristic idle detection (consecutive polls with no output growth, no new tool calls, no new messages). This gating was introduced as the F1 authoritative-idle-signal improvement.
+
+---
+
+## What OpenCode Provides (Use Native APIs)
+
+| Feature | OpenCode API | How We Use It |
+|---------|-------------|---------------|
+| **Agent Types** | Native `build`, `plan`, `explore`, `general`, `chat` | Pass `agent` parameter to `sendPrompt()` |
+| **Tool Permissions** | Enforced by agent framework | NO custom prompt-based restrictions |
+| **Session Status** | `session.status()` | Used in `headless.js` as authoritative idle signal (F1) |
+| **Session Messages** | `session.messages()` | Used for polling and conversation capture |
+| **Child Sessions** | `session.create({ parentID })` | Used for subagent spawning |
+| **Health Check** | `config.get()` | Used to verify server ready state |
+
+## What We Built (Unique Value)
+
+| Feature | Why We Need It | Implementation |
+|---------|----------------|----------------|
+| **Context Extraction** | Bridge Claude Code sessions to OpenCode | `context.js` reads `.jsonl` files |
+| **File Conflict Detection** | Safety feature - OpenCode doesn't track this | `conflict.js` compares mtimes |
+| **Context Drift Detection** | Safety feature - detect stale context | `drift.js` calculates staleness |
+| **Session Persistence** | Custom metadata (briefing, agent, thinking) | `session-manager.js` |
+| **MCP Config Merging** | CLI overrides + file config | `opencode-client.js` |
+| **Client-aware prompt** | Cowork needs general-purpose, not SE-focused | `prompts/cowork-agent-prompt.js` sets `chat` agent `prompt` field |
+
+## Removed Redundancies
+
+The following custom implementations were **removed** because OpenCode handles them natively:
+
+| Removed | Reason | Native Replacement |
+|---------|--------|-------------------|
+| ~~`buildCodeModeEnvironment()`~~ | Tool restrictions in prompts | OpenCode `build` agent |
+| ~~`buildPlanModeEnvironment()`~~ | Tool restrictions in prompts | OpenCode `plan` agent |
+| ~~`buildAskModeEnvironment()`~~ | Tool restrictions in prompts | OpenCode `build` with `permissions` |
+| ~~Custom heartbeat polling~~ | Basic sleep loop | `session.status()` API |
+
+---
+
+## Agent Type Mapping
+
+Agent name mapping is implemented in `src/utils/agent-mapping.js`. All known OpenCode native agents are normalised to lowercase before being sent to the API:
+
+```javascript
+// src/utils/agent-mapping.js
+mapAgentToOpenCode('build')    // -> { agent: 'build' }
+mapAgentToOpenCode('plan')     // -> { agent: 'plan' }
+mapAgentToOpenCode('explore')  // -> { agent: 'explore' }
+mapAgentToOpenCode('general')  // -> { agent: 'general' }
+mapAgentToOpenCode('chat')     // -> { agent: 'chat' }
+mapAgentToOpenCode('custom')   // -> { agent: 'custom' } // passed through as lowercase
+```
+
+**Default when agent is unset:** `mapAgentToOpenCode(undefined)` returns `{ agent: 'chat' }`.
+
+**Headless mode default:** When `--no-ui` is set, Amicus hard-codes `agent || 'build'` before calling `mapAgentToOpenCode` (`src/headless.js` line 275), so the effective default in headless mode is `build`, not `chat`. The `chat` agent requires user interaction for write/bash permissions and stalls in headless mode.
+
+`isHeadlessSafe(agent)` returns `true` (safe: build/plan/explore/general), `false` (unsafe: chat), or `null` (custom/unknown).
+
+## Key Integration Files
+
+| File | OpenCode Integration |
+|------|---------------------|
+| `src/opencode-client.js` | SDK wrapper - `createSession()`, `sendPrompt()`, `getSessionStatus()` |
+| `src/headless.js` | Uses `session.status()` for authoritative idle detection (F1); falls back to activity heuristic |
+| `src/utils/agent-mapping.js` | Maps Amicus agent names to OpenCode agents (all lowercase) |
+| `electron/main.js` | Creates child sessions for subagents |
+| `src/sidecar/fanout.js` | `amicus fanout` reuses the same `runHeadless` path per leg over one shared server — see [Fanout Wave Architecture](architecture.md#fanout-wave-architecture). |
+
+---
+
+## Backward Compatibility
+
+**Removed in v2.0.0.** Through v1.9.1, `src/index.js` exported `startSidecar`, `listSidecars`, `resumeSidecar`, `continueSidecar`, `readSidecar` from the package root as deprecated aliases (present on npm in every v1.x release), alongside the canonical `startAmicus`, `listAmicus`, `resumeAmicus`, `continueAmicus`, `readAmicus` names. v2.0.0 deletes the `*Sidecar` aliases from `module.exports`; only the canonical `*Amicus` names remain exported. There is no `*Sidecar`-named export on the package root in this version — switch any import of one to its `*Amicus` equivalent. See [docs/SHIMS.md](./SHIMS.md) for the full removal record.
+
+---
+
+## SDK & HTTP API Reference
+
+Refer to the [OpenCode documentation](https://opencode.ai/docs/) for SDK and server API details.
+
+**Critical: Model Format** -- Models MUST be objects, not strings:
+
+```javascript
+// WRONG - causes 400 Bad Request
+{ model: "google/gemini-2.5-flash" }
+
+// CORRECT
+{ model: { providerID: "openrouter", modelID: "google/gemini-2.5-flash" } }
+```

package/docs/publishing.md

@@ -0,0 +1,60 @@
+# npm Publishing
+
+**Package**: `amicus` on npm (public)
+**Repo**: `github.com/BourbonDog/amicus`
+
+## How to Publish a New Version
+
+```bash
+npm version patch   # or minor/major (bumps version + creates git tag)
+git push origin main --tags
+```
+
+The `.github/workflows/publish.yml` workflow triggers on `v*` tags and publishes automatically.
+
+## What the Workflow Does
+
+1. `npm ci` — install dependencies
+2. `npm publish --access public --provenance` — publish with Sigstore attestation (requires `id-token: write` permission)
+3. Create a GitHub Release with auto-generated notes
+4. Call the Anthropic API to write richer release notes and update the release
+
+**Publish auth: npm Trusted Publishing (OIDC).** Configured on npm for
+`BourbonDog/amicus` + `publish.yml` (2026-06-11). The workflow authenticates via
+GitHub's OIDC token (`id-token: write`) — no npm token is used. The runner
+upgrades npm first (OIDC publishing needs npm ≥ 11.5; Node 22 bundles 10.x).
+Provenance is implied under trusted publishing.
+
+**Secrets:**
+| Secret | Purpose |
+|--------|---------|
+| `ANTHROPIC_API_KEY` | Used in the "Generate release notes with Claude" step (direct `/v1/messages` call). Without it the step exits 0 with a warning and keeps the default GitHub release notes. **As of v1.0.0 this secret exists but is empty — set a real key to get Claude-written notes.** |
+| `NPM_TOKEN` | **Legacy — no longer read by the workflow.** Kept only until the first successful OIDC publish confirms trusted publishing end-to-end; then delete the secret and revoke the token on npmjs.com. |
+
+## Publishing history / notes
+
+- v1.0.0 (2026-06-11) was published with `NPM_TOKEN` (granular, bypass-2FA). First
+  attempt failed `EOTP` because the original token lacked 2FA bypass.
+- Trusted Publishing was configured immediately after launch; the next tagged
+  release is the first OIDC publish. If it fails, re-add a bypass-2FA granular
+  token as `NPM_TOKEN` and restore the `NODE_AUTH_TOKEN` env on the publish step
+  (see git history of `publish.yml`).
+- After the first successful OIDC publish, optionally tighten the package's
+  publishing access on npmjs.com to require trusted publishing.
+- The upstream `jrenaldi79/sidecar` repo had its own npm trusted-publisher
+  config; it never applied to this repository.
+
+## Release checklist
+
+Run top-to-bottom before `npm version`:
+
+1. **MODEL-NOTES fold-back:** diff the machine-local ledger (`~/.claude/skills/second-opinion/MODEL-NOTES.md`) against the shipped seed (`skills/second-opinion/MODEL-NOTES.md`); port durable, machine-independent lessons into the shipped file (merge/prune, keep it tight — no run-ledger numbers, those live in `amicus council stats`).
+2. `npm test` green; `npm run lint` clean.
+3. **Integration tier, both rails:**
+   - `npm run test:integration` (keyless) — must be **0 failures**. This is the same thing the `integration` job in `ci.yml` runs on every push, so it should already be green.
+   - `npm run test:integration:live` **with real keys** — must be **0 failures**. This is the only step in the whole release that exercises the paid E2E suites (real CLI/MCP sessions against a real LLM), so it is the only thing that catches a break in the spawn/session/MCP lifecycle or a dead model alias. **It spends money — expect that, and do not skip it because the keyless run was green:** keyless *skips* those suites entirely, so a green keyless run says nothing about them. Locally: `npm run test:integration:live` with `OPENROUTER_API_KEY` set (or a key in `~/.config/amicus/.env`). In CI: dispatch `.github/workflows/integration-live.yml` from the Actions tab. The script carries `--runInBand` as of v4.4.1 (REL-1) and the CI job runs the same script, so **no extra flag is needed on either surface** — if you find an older note telling you to append `-- --runInBand`, it is stale. Expect ~2 minutes rather than ~40 s; that is the serialization, not a hang (see [testing.md](testing.md#which-gate-runs-which-tier)).
+   - A suite that reports *skipped* here means the key was not picked up. That is a misconfigured run, not a pass — fix it and re-run.
+4. `npm run generate-docs:check` passes (CLAUDE.md markers + cross-links).
+5. Bump `.claude-plugin/plugin.json` `version` to match `package.json` (no script syncs it). Also bump `server.json` — both `.version` and `.packages[0].version` — to the same value (no script syncs this either). Also bump the `status --json` **example blocks** in `README.md` and `docs/usage.md` (`"version": "x.y.z"`) — they are drift-test-pinned to `package.json` by `tests/docs-quick-sync.test.js` and have now missed the cut twice (v2.1.0 and v2.2.0).
+6. Update `CHANGELOG.md` (move Unreleased → the new version).
+7. `npm version <x.y.z> --no-git-tag-version` + plugin.json lockstep + server.json lockstep (`.version` and `.packages[0].version`), single `chore(release): vX.Y.Z` commit, then push main + tag (publish.yml does the rest — see the canonical ritual in Phase 2 of the 2026-07-01 review-execution plan). If you forget the server.json bump, `tests/scripts/package-manifest.test.js` fails the suite (`server.json versions stay in lockstep with package.json`) — that's your safety net, but don't rely on it; do the bump.

package/docs/schemas.md

@@ -0,0 +1,55 @@
+# JSON output schemas
+
+Every JSON document Amicus emits carries a versioned envelope: `{ "schemaVersion": <n>, "type": "<doc-type>", … }`.
+Published JSON Schemas (draft 2020-12) live in [`schemas/`](../schemas/) at the repo root and ship in the npm tarball —
+validate any `--json` output with them (e.g. `ajv validate -s node_modules/amicus/schemas/run.schema.json -d out.json`).
+
+**Stability contract:** within a `schemaVersion`, fields are only ever ADDED. Any rename/removal bumps the family's version.
+Schemas leave `additionalProperties` open for exactly this reason — a doc with extra fields still validates.
+
+## Families
+
+| Family | schemaVersion | Types |
+|---|---|---|
+| result | 2 | `run`, `wave`, `abort`, `error`, `spend`, `model-catalog`, `alias-audit`, `doctor` |
+| council | 2 (v4.0 bumped 1→2) | `council-tally`, `council-verdict`, `council-stats`, `council-validate`, `council-run` |
+| observability | 1 | `event`, `progress` (v4.3, spec §4.2 — the events stream and the progress snapshot) |
+
+`wave-live` and `run-live` are not a new family: they're the existing **result family (v2)** `wave`/`run` docs, composed at read time with an additive `view:'live'` marker — `amicus_status` stamps `schemaVersion: 2` (`stampEnvelope`) exactly as the durable `wave.json`/per-leg `run` docs do. `council-run-live` is the composed council live status payload (`buildCouncilStatusPayload`) — a point-in-time `amicus_status` snapshot like the other live/ack payloads in [Documented exclusions](#documented-exclusions), not a versioned result doc — and carries **no `schemaVersion` key at all**.
+
+## Files
+
+| Schema | Emitted by |
+|---|---|
+| [`run.schema.json`](../schemas/run.schema.json) | `start`/`read`/`resume`/`continue --json`; every wave leg |
+| [`wave.schema.json`](../schemas/wave.schema.json) | `fanout --json`; `wave.json` |
+| [`abort.schema.json`](../schemas/abort.schema.json) | `abort <id|--all> --json` |
+| [`error.schema.json`](../schemas/error.schema.json) | every `--json` pre-flight/validation/route failure (stdout, exit 1) and every MCP error tool-text |
+| [`spend.schema.json`](../schemas/spend.schema.json) | `spend --json` |
+| [`model-catalog.schema.json`](../schemas/model-catalog.schema.json) | `models --json` |
+| [`alias-audit.schema.json`](../schemas/alias-audit.schema.json) | `models --check --json` |
+| [`doctor.schema.json`](../schemas/doctor.schema.json) | `doctor --json` |
+| [`council-tally.schema.json`](../schemas/council-tally.schema.json) | `council tally --json`; `amicus_council_tally` |
+| [`council-verdict.schema.json`](../schemas/council-verdict.schema.json) | `council verdict --json`; `amicus_verdict`; `verdict.json` |
+| [`council-stats.schema.json`](../schemas/council-stats.schema.json) | `council stats --json`; `amicus_council_stats` |
+| [`council-validate.schema.json`](../schemas/council-validate.schema.json) | `council validate --json` |
+| [`council-run.schema.json`](../schemas/council-run.schema.json) | the headless engine's `run.json` manifest (`amicus council run` — lands after the trust-foundation phase; the schema is published ahead as the contract) |
+| [`event.schema.json`](../schemas/event.schema.json) | `events.jsonl` lines — one append-only file per wave dir / council-run dir, milestone events appended by fan-out waves and council runs (wave/leg/run/stage lifecycle) |
+| [`progress.schema.json`](../schemas/progress.schema.json) | `progress.json` — a leg/solo session's lifecycle stage + raw per-leg usage snapshot |
+| [`wave-live.schema.json`](../schemas/wave-live.schema.json) | `amicus_status` on a running wave — the composed doc, `view:'live'` + per-leg read-time usage |
+| [`run-live.schema.json`](../schemas/run-live.schema.json) | `amicus_status` on a running single session — the composed doc, `view:'live'` + read-time usage |
+| [`council-run-live.schema.json`](../schemas/council-run-live.schema.json) | `amicus_status` on a running council run (`buildCouncilStatusPayload`) — the composed doc, `view:'live'` + read-time usage |
+
+## Breaking change at v4.0 — `council stats --json`
+
+Pre-4.0, `council stats --json` (and the `amicus_council_stats` MCP tool) emitted a **bare array** of per-model rows.
+v4.0 wraps it: `{ "schemaVersion": 2, "type": "council-stats", "models": [ … ] }`. The row shape is unchanged.
+This is the one non-additive shape change in the envelope unification; migrate `doc[0]` → `doc.models[0]`.
+
+## Documented exclusions
+
+- **The two JSONL ledgers** (`council-ledger.jsonl`, `spend-ledger.jsonl`): internal append-only storage, each stays at its own v1 row format (`SPEND_LEDGER_SCHEMA_VERSION` is 1, unrelated to and unbumped by the result/council envelope versions above) — not an emitted/published doc. `spend.schema.json` (the `amicus spend --json` output) is the published, versioned doc built *from* `spend-ledger.jsonl` rows — the ledger row shape itself is not published.
+- **`amicus_list`** (MCP): returns a bare JSON array of session rows; a wrap would be a second breaking change and is deliberately not taken.
+- **`setup` / `update` / `key`**: interactive-only commands with no `--json` mode.
+- **MCP acks and live-status snapshots** (start/resume/continue/abort acks, `amicus_status`/`amicus_wait` bodies): carry the envelope keys with subject-family types (`run`/`wave`/`abort`) but are point-in-time snapshots, not the durable result docs the published schemas describe.
+- **Fencing:** MCP council tool text arrives wrapped in the `<untrusted_sidecar_output>` fence with the JSON intact inside; CLI `--json` stdout is never fenced.