@symerian/symi 3.0.21 → 3.0.22

package/docs/perplexity.md

@@ -1,80 +0,0 @@
----
-summary: "Perplexity Sonar setup for web_search"
-read_when:
-  - You want to use Perplexity Sonar for web search
-  - You need PERPLEXITY_API_KEY or OpenRouter setup
-title: "Perplexity Sonar"
----
-
-# Perplexity Sonar
-
-Symi can use Perplexity Sonar for the `web_search` tool. You can connect
-through Perplexity’s direct API or via OpenRouter.
-
-## API options
-
-### Perplexity (direct)
-
-- Base URL: [https://api.perplexity.ai](https://api.perplexity.ai)
-- Environment variable: `PERPLEXITY_API_KEY`
-
-### OpenRouter (alternative)
-
-- Base URL: [https://openrouter.ai/api/v1](https://openrouter.ai/api/v1)
-- Environment variable: `OPENROUTER_API_KEY`
-- Supports prepaid/crypto credits.
-
-## Config example
-
-```json5
-{
-  tools: {
-    web: {
-      search: {
-        provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...",
-          baseUrl: "https://api.perplexity.ai",
-          model: "perplexity/sonar-pro",
-        },
-      },
-    },
-  },
-}
-```
-
-## Switching from Brave
-
-```json5
-{
-  tools: {
-    web: {
-      search: {
-        provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...",
-          baseUrl: "https://api.perplexity.ai",
-        },
-      },
-    },
-  },
-}
-```
-
-If both `PERPLEXITY_API_KEY` and `OPENROUTER_API_KEY` are set, set
-`tools.web.search.perplexity.baseUrl` (or `tools.web.search.perplexity.apiKey`)
-to disambiguate.
-
-If no base URL is set, Symi chooses a default based on the API key source:
-
-- `PERPLEXITY_API_KEY` or `pplx-...` → direct Perplexity (`https://api.perplexity.ai`)
-- `OPENROUTER_API_KEY` or `sk-or-...` → OpenRouter (`https://openrouter.ai/api/v1`)
-- Unknown key formats → OpenRouter (safe fallback)
-
-## Models
-
-- `perplexity/sonar` — fast Q&A with web search
-- `perplexity/sonar-pro` (default) — multi-step reasoning + web search
-- `perplexity/sonar-reasoning-pro` — deep research
-
-See [Web tools](/tools/web) for the full web_search configuration.

package/docs/phase-6.5-pre-flight-audit.md

@@ -1,268 +0,0 @@
-# Phase 6.5 — Pre-flight audit (chain migration blockers)
-
-**Date:** 2026-04-29
-**Branch:** `symi-phase3`
-**Scope:** Audit all pre-existing test failures and classify them as
-blockers vs deferrable before Phase 7+ chain migration begins.
-
-## Summary
-
-Full vitest run (excluding e2e/live):
-
-```
-Test Files: 16 failed | 1048 passed | 1 skipped (1065)
-Tests:      68 failed | 9356 passed | 10 skipped (9434)
-Duration:   ~13 minutes
-```
-
-**Pass rate: 99.3% of tests, 98.5% of files.** The pre-existing
-failures cluster into a small number of root causes — none of them
-catch a latent regression in the dispatch chain. All 68 failures
-classify as **B (test infrastructure)** or **D (genuinely broken
-feature, but isolated from the chain)**. Phase 7+ chain migration is
-unblocked; we can address the test infrastructure hygiene as we go
-without it gating the work.
-
-## Classification key
-
-| Cat   | Meaning                                                               | Action                                         |
-| ----- | --------------------------------------------------------------------- | ---------------------------------------------- |
-| **A** | Latent chain regression                                               | **BLOCKS Phase 7** — must fix before migration |
-| **B** | Test infrastructure issue (mock at wrong path, missing fixture, etc.) | Fix opportunistically; does not block          |
-| **C** | Flaky / non-deterministic                                             | Deflake or quarantine with comment             |
-| **D** | Genuinely broken feature (test correctly catches a real bug)          | File issue; decide if blocking on user impact  |
-| **E** | TS-only (runtime works, typecheck fails)                              | Fix during Phase 7 type tightening             |
-
-## Verdict per failure cluster
-
-### Cluster 1 — `STATE_DIR` mock pattern (CAT B, 1 file)
-
-**File:** `src/gateway/server-chat.agent-events.test.ts`
-
-**Symptom:** `Error: [vitest] No "STATE_DIR" export is defined on the
-"../config/config.js" mock.`
-
-**Root cause:** Test mocks `../config/config.js` with the narrow form
-`vi.mock(path, () => ({ loadConfig: ... }))` instead of using
-`importOriginal`. Transitive imports (e.g. `sandbox/constants.ts`
-needs `STATE_DIR`) fail to resolve.
-
-**Fix:** Convert to `vi.mock(path, async (importOriginal) => { const
-actual = await importOriginal(); return { ...actual, loadConfig: ... }
-})` — the same pattern already established in
-`src/gateway/glass-ui-rendering-parity.test.ts` (Phase 0).
-
-**Phase 7 implication:** None. Fix it whenever convenient; it
-exposes one test file's surface but doesn't shift behavior.
-
----
-
-### Cluster 2 — Auth profile setup in temp homes (CAT B, 3+ files)
-
-**Files:**
-
-- `src/auto-reply/reply.media-note.test.ts`
-- `src/auto-reply/reply.raw-body.test.ts`
-- `src/cron/isolated-agent.delivers-response-has-heartbeat-ok-but-includes.test.ts`
-
-**Symptom:** `Embedded agent failed before reply: No API key found for
-provider "anthropic"`. Tests then assert the agent's `text` is `"ok"`
-but receive the auth error message.
-
-**Root cause:** Tests use `withTempHome` which creates an isolated
-`HOME` but does NOT seed `auth-profiles.json`. The chain layer's auth
-resolution (which runs BEFORE any model invocation) requires the file
-to exist. Tests mock `runEmbeddedPiAgent` but the failure happens at
-the auth-profile resolution layer earlier in the chain.
-
-**Fix:** Add an `auth-profiles.json` seeder to the `withTempHome`
-helper that includes a fake anthropic provider key, OR mock the
-`auth-profiles.js` module entirely.
-
-**Phase 7 implication:** When the chain is collapsed, the auth
-resolution will move to a middleware. These tests will need to mock
-either at the middleware layer OR at the `auth-profiles.js` module —
-NOT at `runEmbeddedPiAgent` (which fires after auth resolution).
-Plan to update test harnesses as part of Phase 9 (per-turn pre-flight
-middlewares).
-
----
-
-### Cluster 3 — `pi-embedded.js` mock path mismatch (CAT B, ~10 files)
-
-**Files (representative):**
-
-- `src/auto-reply/reply/agent-runner.runreplyagent.test.ts` (~25 failures
-  with "Unknown model: anthropic/claude")
-- `src/auto-reply/reply/followup-runner.test.ts` (4 failures)
-- Other tests using `vi.mock("../../agents/pi-embedded.js", ...)` or
-  the harness file `reply.directive.directive-behavior.e2e-mocks.ts`
-
-**Symptom:** `Embedded agent failed before reply: Unknown model:
-anthropic/claude`. The model fixture `model: "claude"` (intentionally
-short to avoid coupling tests to specific model names) fails resolution
-because `pi-embedded-runner/model.ts` requires a known model.
-
-**Root cause:** Tests mock at `../../agents/pi-embedded.js` (the
-re-export), but production code (e.g. `src/agents/unified-runner.ts:39`)
-imports from `./pi-embedded-runner/run.js` directly (the canonical
-source). ESM mocking is path-specific — mocking the re-export doesn't
-intercept calls that arrive through the canonical path.
-
-This is a **pre-existing structural issue** (the canonical-path import
-in `unified-runner.ts` dates to its creation in commit `ca6e99b21`,
-well before this Phase 3 work). The tests were probably passing earlier
-when test fixtures used real model names that happened to resolve, OR
-when the production import path was different.
-
-**Fix options:**
-
-1. **Mock at canonical path:** add a second `vi.mock` for
-   `./pi-embedded-runner/run.js` alongside the existing
-   `vi.mock("pi-embedded.js")` — minimal change, preserves existing tests.
-2. **Update production imports:** change `unified-runner.ts` (and any
-   other production importers) to use the `pi-embedded.js` re-export.
-   Cleaner long-term but touches more files.
-3. **Use real model fixture names:** change `model: "claude"` to
-   `model: "claude-opus-4-5"` so resolution succeeds even when the mock
-   doesn't fire. Doesn't fix the underlying mock issue but stops the
-   bleeding.
-
-**Phase 7 implication:** When the chain collapses, these test files
-will need to mock at whatever the new entry point's import path is.
-Plan to fix the mock pattern as part of Phase 12 (`runUnifiedTurn`)
-when the canonical entry point gets defined.
-
----
-
-### Cluster 4 — Block-streaming + followup-runner downstream effects (CAT B, 7 failures combined)
-
-**Files:**
-
-- `src/auto-reply/reply.block-streaming.test.ts` (3 failures)
-- `src/auto-reply/reply/followup-runner.test.ts` (4 failures)
-
-**Symptoms:**
-
-- block-streaming: `expected { Object (text) } to be undefined` —
-  tests expect `getReplyFromConfig` to return undefined when block
-  streaming successfully delivered, but the chain returns a ReplyPayload.
-- followup-runner: `expected vi.fn() to be called at least once` /
-  `expected vi.fn() to be called 1 times, but got 0 times` /
-  `expected undefined to be 400` — assertions on payload delivery
-  callbacks fail because no payload was delivered.
-
-**Root cause:** Both are downstream effects of Cluster 3 — same
-`pi-embedded.js` mock-path mismatch. Confirmed by the stderr output
-in followup-runner: every failing test logged `Followup agent failed
-before reply: Unknown model: anthropic/claude` from the runtime,
-proving the mock didn't intercept and the real runner ran.
-
-In block-streaming, the inner mock doesn't fire so no `onBlockReply`
-gets invoked, the chain falls through to a regular reply, and the
-assertion that "block streaming bypasses the final return" fails
-because the return wasn't bypassed.
-
-**Phase 7 implication:** Same as Cluster 3 — fix as part of Phase 12.
-
----
-
-### Cluster 6 — TypeScript-only errors (CAT E, 14 files)
-
-**TS errors found:** 42 across 14 files.
-
-| File                                                                                       | Errors | Notes                               |
-| ------------------------------------------------------------------------------------------ | ------ | ----------------------------------- |
-| `extensions/learning-loop/src/analytics/gateway-methods.ts`                                | 16     | Pre-existing extension issue        |
-| `extensions/learning-loop/src/test/fixes.test.ts`                                          | 7      | Pre-existing                        |
-| `extensions/learning-loop/src/db.ts`                                                       | 5      | Pre-existing                        |
-| `extensions/bluebubbles/src/monitor.test.ts`                                               | 1      | Pre-existing                        |
-| `src/config/config.compact-mode.test.ts`                                                   | 4      | Phase 3.4 era; investigate          |
-| `src/gateway/server.impl.ts`                                                               | 2      | Pre-existing                        |
-| `src/agents/model-aware-stream.test.ts`                                                    | 1      | Pre-existing                        |
-| `src/auto-reply/reply/middleware-{circuit-breaker,model-fallback,transient-retry}.test.ts` | 3      | Phase 4-6 type assertion ergonomics |
-| `src/auto-reply/reply/turn-middleware.test.ts`                                             | 1      | Phase 3 type assertion              |
-| `src/commands/doctor-memory-search.ts`                                                     | 1      | Pre-existing                        |
-| `src/gateway/glass-ui-ws.ts`                                                               | 1      | Pre-existing                        |
-| `src/gateway/server-runtime-state.ts`                                                      | 1      | Pre-existing                        |
-
-**Phase 7 implication:** None — vitest's transform tolerates these.
-Fix during a dedicated TS-tightening pass (could be a Phase 6.6 if
-desired). The Phase 3-6 test assertions can be cleaned up trivially
-(replace `as AgentTurnResult["profile"]` with `as unknown as
-AgentTurnResult["profile"]`).
-
-**Decision:** Defer. Track as Phase 6.6 candidate.
-
----
-
-## Full failure inventory by file
-
-| File                                                                              | Failure count  | Root cause cluster                         | Cat                                          |
-| --------------------------------------------------------------------------------- | -------------- | ------------------------------------------ | -------------------------------------------- |
-| `src/gateway/server-chat.agent-events.test.ts`                                    | 1 (file-level) | Cluster 1 STATE_DIR mock                   | B → **FIXED in Phase 6.5**                   |
-| `src/cron/isolated-agent/run.skill-filter.test.ts`                                | 1 (file-level) | Likely Cluster 1 (mock issue)              | B (defer)                                    |
-| `src/agents/system-prompt-skills-jit.test.ts`                                     | 1              | Skill-search fixture                       | B (defer)                                    |
-| `src/auto-reply/reply.block-streaming.test.ts`                                    | 3              | Cluster 4 (downstream of Cluster 3)        | B (defer to Phase 12)                        |
-| `src/auto-reply/reply.media-note.test.ts`                                         | 1              | Cluster 2 (auth profile)                   | B (defer to Phase 9)                         |
-| `src/auto-reply/reply.raw-body.test.ts`                                           | 1              | Cluster 2 (auth profile)                   | B (defer to Phase 9)                         |
-| `src/cron/isolated-agent.delivers-response-has-heartbeat-ok-but-includes.test.ts` | 1              | Cluster 2 (auth profile)                   | B (defer to Phase 9)                         |
-| `src/cron/service.issue-regressions.test.ts`                                      | 1              | Cron concurrency setting drift             | D (defer; investigate during cron migration) |
-| `src/gateway/method-scopes.test.ts`                                               | 1              | Method inventory drift (not a runtime bug) | B (defer)                                    |
-| `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`                   | 3              | Compaction trigger routing                 | D (defer; investigate isolated)              |
-| `src/agents/pi-embedded-runner/usage-reporting.test.ts`                           | 1              | Usage reporting                            | D (defer)                                    |
-| `src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts`                    | ~15            | Cluster 3 (mock path)                      | B (defer to Phase 12)                        |
-| `src/auto-reply/reply/agent-runner.runreplyagent.test.ts`                         | ~25            | Cluster 3 (mock path)                      | B (defer to Phase 12)                        |
-| `src/auto-reply/reply/followup-runner.test.ts`                                    | 4              | Cluster 4 (downstream of Cluster 3)        | B (defer to Phase 12)                        |
-
-**Total deferred failures:** 60 (after Phase 6.5 fix of 8 STATE_DIR cases).
-
-## Phase 6.5 fixes applied
-
-1. **`src/gateway/server-chat.agent-events.test.ts`** — converted
-   `vi.mock("../config/config.js", () => ({...}))` to use `importOriginal`
-   so transitive imports (STATE_DIR, etc.) resolve. **14 tests recovered.**
-
-2. **`src/auto-reply/reply/{turn-middleware,middleware-circuit-breaker,
-middleware-model-fallback,middleware-transient-retry}.test.ts`** —
-   replaced `as AgentTurnResult["profile"]` with `as unknown as
-AgentTurnResult["profile"]` to silence pre-existing TS-only warnings
-   on the Phase 3-6 test files. **4 TS errors eliminated.**
-
-## Conclusion
-
-**Phase 7 is unblocked.** No category-A failures found.
-
-The failure landscape is dominated by **two pre-existing test
-infrastructure issues** that have been there for many releases:
-
-1. **Mock-at-wrong-path** for `pi-embedded.js` (Cluster 3 + 5) — affects
-   the largest swath of failures.
-2. **Auth profile setup** for `withTempHome` tests (Cluster 2) — affects
-   media-note, raw-body, and isolated-agent tests.
-
-Both are systemic and worth fixing, but **neither catches a chain
-regression that would compound during migration**. The chain code paths
-those tests cover are exercised by other passing tests in the same
-suite — coverage isn't lost, just the specific assertions fail.
-
-## Phase 7 plan
-
-Proceed with Phase 7 as planned (PayloadMiddleware contract). Fold the
-test infrastructure fixes into the relevant later phases:
-
-- **Phase 8 (Pipeline-A wrappers):** investigate Cluster 4 (block-streaming)
-- **Phase 9 (Per-turn pre-flight):** fix Cluster 2 (auth fixtures) so the
-  `withMessageHooks` / `withFastAbort` migrations have a clean test base
-- **Phase 12 (`runUnifiedTurn`):** fix Cluster 3 + 5 (mock path) by either
-  consolidating import paths or updating the test harnesses
-- **Phase 6.6 (optional):** fix the TS-only errors when type-tightening
-  the middleware test files
-
-## Audit data
-
-Full test run captured at:
-`/tmp/claude-1000/-home-symi-projects-symi/9adc0eb5-488e-4054-b2d5-7025691c1d0f/tasks/bvo0cycjv.output`
-
-TS error inventory captured at:
-`/tmp/claude-1000/-home-symi-projects-symi/9adc0eb5-488e-4054-b2d5-7025691c1d0f/tasks/b62pi8sjy.output`

package/docs/pi-dev.md

@@ -1,70 +0,0 @@
----
-title: "Pi Development Workflow"
----
-
-# Pi Development Workflow
-
-This guide summarizes a sane workflow for working on the pi integration in Symi.
-
-## Type Checking and Linting
-
-- Type check and build: `pnpm build`
-- Lint: `pnpm lint`
-- Format check: `pnpm format`
-- Full gate before pushing: `pnpm lint && pnpm build && pnpm test`
-
-## Running Pi Tests
-
-Use the dedicated script for the pi integration test set:
-
-```bash
-scripts/pi/run-tests.sh
-```
-
-To include the live test that exercises real provider behavior:
-
-```bash
-scripts/pi/run-tests.sh --live
-```
-
-The script runs all pi related unit tests via these globs:
-
-- `src/agents/pi-*.test.ts`
-- `src/agents/pi-embedded-*.test.ts`
-- `src/agents/pi-tools*.test.ts`
-- `src/agents/pi-settings.test.ts`
-- `src/agents/pi-tool-definition-adapter.test.ts`
-- `src/agents/pi-extensions/*.test.ts`
-
-## Manual Testing
-
-Recommended flow:
-
-- Run the gateway in dev mode:
-  - `pnpm gateway:dev`
-- Trigger the agent directly:
-  - `pnpm symi agent --message "Hello" --thinking low`
-- Use the TUI for interactive debugging:
-  - `pnpm tui`
-
-For tool call behavior, prompt for a `read` or `exec` action so you can see tool streaming and payload handling.
-
-## Clean Slate Reset
-
-State lives under the Symi state directory. Default is `~/.symi`. If `SYMI_STATE_DIR` is set, use that directory instead.
-
-To reset everything:
-
-- `symi.json` for config
-- `credentials/` for auth profiles and tokens
-- `agents/<agentId>/sessions/` for agent session history
-- `agents/<agentId>/sessions.json` for the session index
-- `sessions/` if legacy paths exist
-- `workspace/` if you want a blank workspace
-
-If you only want to reset sessions, delete `agents/<agentId>/sessions/` and `agents/<agentId>/sessions.json` for that agent. Keep `credentials/` if you do not want to reauthenticate.
-
-## References
-
-- [https://docs.symi.ai/testing](https://docs.symi.ai/testing)
-- [https://docs.symi.ai/start/getting-started](https://docs.symi.ai/start/getting-started)