# Advisor Implementation Plans

Generated by the `improve` skill on 2026-07-25. These plans are intentionally
separate from the repository's existing `plans/` ExecPlan catalogue.

Execute plans in the order below unless dependencies say otherwise. Each
executor must read the selected plan fully before starting, honor its STOP
conditions, and update the status row when done.

## Execution order and status

| Plan | Title | Priority | Effort | Depends on | Status |
|---|---|---|---|---|---|
| 001 | Build a deterministic Anthropic Messages and OpenAI Responses API simulator | P1 | L | — | IN PROGRESS |
| 002 | Expose committed chat-run activity to server plugins | P1 | M | — | DONE |
| 003 | UI activity pipeline with Jarvis, analytics, and web plugin sinks | P1 | L | — | DONE |

Status values: `TODO` | `IN PROGRESS` | `DONE` | `BLOCKED` (with a one-line
reason) | `REJECTED` (with a one-line rationale).

## Dependency notes

- Plan 001 is a standalone infrastructure track. It deliberately does not
  migrate Claude Agent or Codex provider tests; those consumers should be
  planned only after the simulator's official-SDK conformance suite passes.
- Plan 002 is independent of Plan 001. It reuses Chat Runtime's committed fact
  publication and does not modify any provider implementation. Plan 002 observes
  **agent chat run** lifecycle on the server.
- Plan 003 is independent of Plans 001 and 002. It owns renderer **user UI
  activity** segments and ships three built-in sinks (Jarvis ambient session,
  product analytics, web plugin SDK). A future WakaTime plugin is a documented
  reference consumer only; it is not implemented in Plan 003.

## Findings considered and rejected

- **Record/proxy/replay support**: rejected for this plan because the desired
  simulator synthesizes fixtures from authoritative schemas and protocol
  grammars. Capturing production prompts or upstream responses is unnecessary.
- **A single provider-neutral wire schema**: rejected because Anthropic
  Messages and OpenAI Responses have different resource, streaming, error, and
  lifecycle semantics. They share only the scenario scheduler, request ledger,
  corpus generator primitives, and server lifecycle.
- **Immediate replacement of provider `vi.mock` suites**: rejected as
  out-of-scope sequencing. First prove the simulator independently against the
  official OpenAI and Anthropic SDKs.
- **One AJV dialect for both provider catalogues**: rejected because
  `ts-json-schema-generator` emits Draft-07 while the OpenAI snapshot is
  OpenAPI 3.1. The package owns a dialect-aware registry instead.
- **Use Elysia's Node adapter as the random-port listener**: rejected for this
  package because the repository's current patched adapter reports port `0`
  before bind and does not give `app.stop()` ownership of that listener. The
  reviewed plan retains a direct srvx server around Elysia's web-standard
  handler.
- **Treat every inferred stream ordering rule as provider compatibility**:
  rejected. Only official source-backed invariants are compatibility
  requirements; simulator-owned ordering constraints are tagged separately.
- **Implement every event family reachable from the provider schemas**:
  rejected as unnecessary for the simulator's first useful profile. Plan 001
  explicitly includes ordinary text, reasoning, refusal, function/tool-call,
  lifecycle, error, and disconnect flows; MCP, hosted search, citations,
  image/audio, computer, shell, code execution/interpreter, custom tools, and
  provider-hosted server-tool event families remain outside the allowlist.
- **Expose plugin activity through chat hooks**: rejected because observation
  must not be able to modify a query or delay Chat Runtime. Plan 002 uses a
  post-commit subscription.
- **Adapt the existing plugin event bus**: rejected because its
  `string + unknown` contract has no host producers, type safety, or read/write
  boundary. Plan 002 replaces it with a narrow read-only discriminated union.
- **Include tool events, replay, filters, batching, or usage in the first
  activity contract**: rejected because the motivating WakaTime integration
  only needs run start/finish signals. The plugin owns heartbeat scheduling and
  batching.
- **Build the WakaTime plugin in Plan 002**: rejected. This plan establishes
  SDK support only; API key UX and WakaTime network behavior are a separate
  consumer.
- **Use server chat-run activity for WakaTime heartbeats**: rejected. User UI
  presence belongs in the renderer activity pipeline (Plan 003), not committed
  `RunStarted` facts (Plan 002).
- **Split Plan 003 into separate plans for analytics and web plugin SDK**:
  rejected. All three sinks consume the same segment bus and ship as one
  product capability.
- **Trigger Jarvis model runs on activity segment end**: rejected. Ambient
  injection persists observation user messages only; the user or an explicit
  Jarvis send still owns run scheduling.
