omnius 1.0.591 → 1.0.592

package/docs/multimodal-identity-memory-implementation.md

@@ -0,0 +1,76 @@
+# Multimodal Identity Memory Implementation Tracker
+
+Goal: make voice, text, image, Telegram reply context, CLIP-like embeddings, zettelkasten links, and social profiles converge on one evidence-based identity substrate.
+
+## Scope
+
+- [ ] Route Telegram, TUI, GUI, voice, and API media ingestion through one identity/evidence layer.
+- [ ] Keep private/public/terminal/gui scopes explicit on every assertion and retrieval path.
+- [ ] Represent uploader/sender, depicted person, speaker, reply target, media asset, and message as separate graph atoms.
+- [ ] Preserve CLIP/image, CLIP/text, face, speaker, transcript, and aligned embeddings with explicit vector-space metadata.
+- [ ] Use agentic structured identity extraction later for "this is X" style assertions; avoid hard-coded naming heuristics.
+- [ ] Feed durable interaction/profile facts into social memory and zettelkasten instead of isolated JSON-only stores.
+
+## Code Anchors
+
+- `MMID-001` - central multimodal identity/evidence service.
+- `MMID-002` - API memory ingest uses shared orchestrator DB names.
+- `MMID-003` - Telegram media ingest sends structured source/scope/sender/message metadata.
+- `MMID-004` - embedding-space handling stores OpenCLIP-compatible vectors as `clipEmbedding`.
+- `MMID-005` - scoped graph atoms for sender, message, media asset, reply target, and identity assertion.
+- `MMID-006` - dependency/worker path for image/audio/text embedding providers.
+- `MMID-007` - Telegram/TUI tool exposure and context injection.
+- `MMID-008` - backward-pass validation checklist and tests.
+- `MMID-009` - scoped automatic prior-enrolled visual identity association and recall injection.
+- `MMID-010` - unified `.omnius/episodes.db` / `.omnius/knowledge.db` paths for identity, reflection, and API media ingest.
+- `MMID-011` - natural chronology support for explicit identity-before-image assertions and unknown-face steering.
+
+## Implementation Checklist
+
+- [x] Create this tracking document before code changes.
+- [x] Add multimodal identity service in `@omnius/memory`.
+- [x] Extend graph relation vocabulary for identity evidence.
+- [x] Make `/v1/memory/ingest` use `episodes.db` and `knowledge.db`.
+- [x] Replace legacy `labels`-as-person behavior with structured sender/media/assertion handling.
+- [x] Store supplied image/text CLIP vectors in `clipEmbedding`.
+- [x] Store supplied speaker/audio vectors in native `embedding` with vector-space metadata.
+- [x] Pass Telegram source scope, sender, message id, media id, caption, and reply context into ingest.
+- [x] Keep legacy ingest clients compatible.
+- [x] Add tests for visual media not misbinding uploader as depicted person.
+- [x] Add tests for explicit identity assertion creating scoped `named_as` / `depicts` evidence.
+- [x] Add tests for audio voice sample linking to sender without global leakage.
+- [x] Add structured JSON output mode for `visual_memory identify` so association code does not parse display text.
+- [x] Add scoped visual identity association service that records prior enrolled face matches as graph evidence.
+- [x] Inject scoped visual identity recall into Telegram and TUI image ingress.
+- [x] Return visual identity recall metadata from `/v1/memory/ingest` for GUI/API callers.
+- [x] Wire GUI attachment upload into scoped media ingest and prepend returned identity context to the next chat turn.
+- [x] Move identity/reflection stores onto the same `.omnius/episodes.db` and `.omnius/knowledge.db` files used by the orchestrator and API.
+- [x] Add `identity_memory action='stage_identity'` for explicit "next image/media is <name>" chronology without regex parsing.
+- [x] Apply pending same-scope visual identity assertions when a later image arrives and face enrollment succeeds.
+- [x] Add unknown-face context when structured detection sees a face but no enrolled identity matches.
+- [x] Run focused builds/tests.
+- [x] Backward pass: verify each item above against code anchors and test coverage.
+
+## Backward Pass Verification
+
+- `MMID-001`: implemented `MultimodalIdentityService` and exported it from `@omnius/memory`.
+- `MMID-002`: API ingest, API memory search/entities, route-v1 memory stores, embedding workers, and `multimodal_memory` bridge now use `episodes.db` / `knowledge.db`.
+- `MMID-003`: Telegram media ingest now sends structured source/scope/sender/message/reply/media payloads.
+- `MMID-004`: OpenCLIP-compatible vectors are stored via `setClipEmbedding`; speaker/audio vectors are stored as native embeddings.
+- `MMID-005`: tests cover distinct sender, media, message, reply/identity evidence graph atoms.
+- `MMID-006`: provider hooks are used when configured; full CLIP/ECAPA dependency install is opt-in via `OMNIUS_INSTALL_FULL_EMBED_DEPS=1`.
+- `MMID-007`: identity memory remains an agent-facing tool; explicit name/enrollment requests are tool calls, not regex captures.
+- `MMID-008`: verified with `pnpm -r build`, `pnpm --filter omnius test -- tests/identity-memory-tool.test.ts tests/visual-identity-association.test.ts`, `pnpm --filter omnius test -- tests/telegram-reflection-corpus.test.ts tests/telegram-reflection-extraction.test.ts`, `pnpm --filter omnius test -- tests/telegram-bot-api-10.test.ts`, and `git diff --check`. The visual association tests now cover prior-match recall, cross-scope isolation, pending next-image application, and unknown-face steering.
+- `MMID-009`: `associateVisualIdentityFromImage` calls `visual_memory identify` with `format=json`, commits `same_person_candidate` / `depicts` evidence for prior enrolled matches, and formats same-scope recall context.
+- `MMID-010`: `IdentityMemoryTool`, Telegram reflection corpus/extraction, API ingest, memory menus, and orchestrator memory now converge on `.omnius/episodes.db` / `.omnius/knowledge.db`.
+- `MMID-011`: `stageVisualIdentityAssertion` records explicit pending next-image identity evidence; later image ingress consumes it only in the same scope/session and only after face enrollment succeeds. Unknown face detection produces a model-facing prompt to ask the user instead of guessing.
+
+## Follow-Up Work After First Slice
+
+- [ ] Add agentic structured identity assertion extraction from reply/message/media context.
+- [x] Wire `visual_memory` face enrollment and prior-enrolled recognition into the identity graph.
+- [ ] Extend the same structured association path to taught object CLIP recognition.
+- [ ] Wire ECAPA speaker embeddings into Telegram voice/audio ingest.
+- [x] Add retrieval context injection for scoped visual identity graph neighborhoods.
+- [ ] Mirror scoped behavior/personality facts into `SocialMemoryStore`.
+- [ ] Expose scoped Telegram tools for identity recall/enrollment with privacy guards.

package/docs/omnius-self-edit-eval-2026-06-10.md

@@ -0,0 +1,169 @@
+# Omnius Self-Edit Evaluation — Uncommitted Changes & Duplicate-Tool-Call Failure Mode
+
+> Eval of the working-tree changes against `docs/opencode-agentic-loop-comparison.md`.
+> Subject: an Omnius instance editing its own orchestrator to implement the P0–P10
+> learnings. Generated 2026-06-10.
+
+---
+
+## TL;DR
+
+1. **The self-edit failed.** The agent attempted the full P0–P10 refactor, produced
+   6 new modules plus in-place edits, but **the orchestrator package does not compile**
+   (`tsc --noEmit` → exit 2, ~40+ errors). The 6 new modules are **dead code** — not
+   imported anywhere except one broken import in `agent-tool.ts`.
+2. **The live instance is unaffected — by luck.** `dist/agenticRunner.js` was built at
+   02:35; the broken source edits landed at 05:06 and never recompiled. The running
+   self-editing instance is still executing the **old, working dist**. The build silently
+   stayed green-at-runtime because the broken code was never built.
+3. **The reported duplicate-tool-call / duplicate-read failure mode is NOT caused by
+   these edits.** It lives in the existing (working) dedup architecture. Root cause:
+   dedup is **reactive, cross-turn-blind, and result-agnostic** — duplicates are executed
+   then cleaned up, and repeated *failures* have their evidence pruned away.
+4. **The diff is itself a symptom of the same pathology.** The agent pasted **three
+   near-identical compaction blocks** into one loop and hallucinated an entire `index.ts`
+   export surface. "Duplicate, low-grounding output" shows up at both the tool-call layer
+   (runtime) and the code-generation layer (this diff).
+
+---
+
+## Part 1 — How well did the self-editing agent do?
+
+### Verdict: **Poor / non-shippable.** Ambitious scope, no verification, broken build.
+
+The agent violated the project's own `executable-feedback` rule (code-generating agents
+must compile/test before returning). None of this compiles.
+
+### 1.1 What was produced
+
+| Module | P-item | Lines | Wired in? | Quality |
+| --- | --- | --- | --- | --- |
+| `runner.ts` | P3/P7 | 258 | ❌ no | Toy. Regex `<tool_call>` parsing (Omnius uses native OpenAI tool calls). Name **collides** with the real `AgenticRunner`. Re-calls the LLM after tools and discards the result. |
+| `orchestrator.ts` | P4/P7 | 387 | ❌ no | Toy. `checkCompletion` = substring match on last message. `prune` strategy keeps "every other message" — would split `tool_call`/`tool_result` pairs. |
+| `childSession.ts` | P0/P10 | 288 | ❌ (import is broken) | Best of the six. Plausible permission-derivation + `task_id` resume shape. Glob matcher is naive. |
+| `permissionRuleset.ts` | P1/P6 | 166 | ❌ no | Reasonable. `evaluatePermission` cascade + `checkDoomLoop`. Never called. |
+| `compactionAgent.ts` | P9 | 101 | ⚠️ imported, wrong shape | **Placeholder** — `compress()` never calls an LLM; returns "last 10 messages" stub. Imports `ChatMessage` which `agent-types.ts` does not export. |
+| `backendAdapter.ts` | P8 | 443 | ❌ no | Three backend adapters. **Single-tool-call only** (`currentToolName`/`accumulatedArgs` are scalars) — contradicts the parallel-batching premise. Ollama branch double-accumulates `toolCallBuffer`. |
+
+### 1.2 What broke (compile errors, by file)
+
+- **`agenticRunner.ts`** — the loop got **three stacked compaction blocks** (lines ~9474,
+  ~9489, ~9495), each calling a different non-existent API:
+  - `compactionResult.success` / `.compressedContext` — real shape is `{ compacted, messages, summary }`.
+  - `this.messages` — the field is not named `messages` on the class (`TS2339` ×7).
+  - `new CompactionAgent({ model })` — `CompactionAgent` is **not imported** here and is a
+    const object, not a class (`TS2304`); its method is `compress`, not `compact`;
+    `result.tokenCount` doesn't exist; `this.options.model` doesn't exist.
+  - `estimateMessagesTokens` imported from `textSanitize.js` **and** redeclared → `TS2440`.
+- **`index.ts`** — rewritten into a "clean" barrel that re-exports a **hallucinated API
+  surface**: `SessionManager`, `SessionConfig` (module exports `SessionOrchestrator`),
+  `AgentType`, `AgentMode`, `AgentConfig`, `AgentState`, `AgentStatus`, `CompactionConfig`,
+  `AgentTask` — none exist. Plus duplicate `LLMBackend` and `export type` violations under
+  `verbatimModuleSyntax`. This **also deleted real exports** the rest of the repo depends on
+  (`OllamaPool`, `discoverSystemOllamaModelStore`, `modelProfile` helpers, …) — `cli` imports
+  these from `@omnius/orchestrator` in ~30 files.
+- **`compactionAgent.ts`** — `import { ChatMessage }` fails (`TS2305`).
+- **`agent-tool.ts`** — import line injected **into the file's top doc-comment** (line 2),
+  then duplicated correctly at line 28. Cross-package deep import
+  `../../orchestrator/src/childSession.js` from `packages/execution` breaks package boundaries.
+  Calls `this.callbacks.getParentSessionId?.()` / `resolveParentPermissions?.()` callbacks
+  that don't exist on the interface.
+
+### 1.3 What was actually fine
+
+A few in-place edits are individually sound and worth salvaging:
+- `agent-types.ts` — adding `mode: "primary" | "subagent" | "all"` + `canSpawnAsSubagent` /
+  `canUserSelect` (P1) is clean. **But** it renamed `plan` → `architect` and dropped
+  `getAgentTypeRegistry` / `resolveAgentTools` / `registerAgentType` / `buildAgentTypeSummary`,
+  which are referenced elsewhere — breaking callers.
+- `tool-batching.ts` — Zod schemas + `validateToolArgs` (P5) are self-contained and harmless.
+- `agenticRunner.ts` — the `finish_reason` plumbing on the Ollama backend (P3) is correct and
+  is the one genuinely useful, low-risk change in the whole diff.
+- `textSanitize.ts` — `estimateMessagesTokens` helper is fine (just double-imported elsewhere).
+
+### 1.4 Behavioral read
+
+Classic over-eager refactor by a capable model with **no feedback loop**:
+- Wrote the code it *wished* existed (idealized `index.ts`) rather than the code that matches
+  the modules it actually wrote.
+- Built parallel "clean-room" modules instead of integrating into the 25k-line monolith — the
+  hard part (wiring) was skipped, so 100% of the architectural value is unrealized.
+- Never ran `tsc`. The `executable-feedback` / `anti-laziness` rules were not honored.
+
+---
+
+## Part 2 — Duplicate failed tool calls & duplicate reads
+
+### This is a pre-existing runtime issue in the working code, independent of Part 1.
+
+The dedup architecture in the live `agenticRunner.ts` is large and thoughtful, but its design
+has three structural gaps that together produce the observed loop.
+
+### 2.1 What exists today
+
+1. **`_dedupeToolCallsForResponse` (line 7397)** — drops exact-duplicate tool calls
+   **within a single response batch**, before execution. Good, but **intra-turn only**.
+2. **`proactivePrune` (line 4937)** — post-hoc context hygiene. On each turn it walks history
+   and, for repeated fingerprints, **replaces the *earlier* result** with
+   `[deduped — same call as turn N]`. Also ages out `file_read` results older than 20 turns
+   (`AGED_FILE_READ_TURNS`) and successful shells older than 12.
+3. **Failure-learning injectors** — `_recentFailures`, `_argCohorts`, `_errorPatterns`
+   (WO-NC-07 pre-action guidance), `_failureReflections` (REG-26 Reflexion), REG-32 opaque-error
+   hints. These *can* inject "you tried this and it failed" before re-dispatch.
+
+### 2.2 Root causes (ranked)
+
+**RC-1 — No cross-turn pre-execution dedup (primary).**
+`_dedupeToolCallsForResponse` only looks within one response. A `file_read(X)` on turn 5 and an
+identical `file_read(X)` on turn 25 **both execute**. The fingerprint
+(`_buildToolFingerprint` = name + exact args, line 7389) is computed but never consulted as an
+emission-time gate across turns. Duplicates are *cleaned up*, never *prevented*.
+
+**RC-2 — Aging causes re-reads (acknowledged in-code).**
+`proactivePrune` ages out `file_read` results after 20 turns. The REG-64 comment (line 4940)
+admits: *"too-aggressive aging causes the model to re-read the same file because it forgot the
+content, creating duplicate calls."* Bumping 10→20 mitigated but did not remove this — long runs
+still strip content the model then re-fetches.
+
+**RC-3 — Repeated *failures* have their evidence pruned (why failed calls loop).**
+The fingerprint is **result-agnostic**: a failed call and its retry share a fingerprint, so
+proactivePrune replaces the earlier *failure* with `[deduped — same call as turn N — duplicate
+file_read() call]`. That stub **does not record that the prior call failed**. The model's inline
+history therefore looks *cleaner* after each retry, removing the strongest natural signal
+("I've failed this exact call twice") and making another retry *more* likely. The system leans
+entirely on the separate `_recentFailures`/`_errorPatterns` injectors to re-surface the pattern —
+and those are gated by per-turn one-shot flags (`_errorGuidanceInjected`,
+`_reflectionsInjectedThisTurn`, `_opaqueErrorHintInjected`) and **stem matching**, which misses
+when the model varies args slightly or pivots stems (the exact case REG-32 was added for).
+
+### 2.3 Where to patch
+
+| # | Patch | Location | Effort |
+| --- | --- | --- | --- |
+| **P-A** | **Cross-turn pre-execution dedup gate.** Maintain a run-level `Map<fingerprint, { turn, ok, resultRef }>`. Before dispatch, if a *successful* identical fingerprint exists, **short-circuit**: skip execution and inject `"already executed at turn N — see prior result"` instead of re-running. Reuse `_buildToolFingerprint`. This is the single highest-leverage fix. | new gate in the dispatch path alongside `_dedupeToolCallsForResponse` (`agenticRunner.ts:7397`) | M |
+| **P-B** | **Make dedup result-aware.** When pruning a duplicate in `proactivePrune`, if the pruned call **failed**, preserve that in the stub: `[deduped — same FAILED call as turn N: <error 1-liner>]`. Keep the failure signal visible instead of erasing it. | `proactivePrune` dedupe branch (`agenticRunner.ts:5020-5031`) | S |
+| **P-C** | **Escalate on Nth identical failure → hard stop, not soft nudge.** Wire `permissionRuleset.checkDoomLoop` (already written, P6) — after 3 identical fingerprints, switch from "inject guidance" to "refuse the call and force a different action or `task_complete`." This is OpenCode's `doom_loop: ask` pattern. | consume `_recentFailures`/`_argCohorts` at dispatch; the helper already exists in `permissionRuleset.ts:113` | M |
+| **P-D** | **Don't age out a `file_read` unless it can be cheaply re-summarized in place.** Instead of clearing aged reads to a stub that triggers re-reads, replace with a **content digest** (path + line range + a few key symbols) so the model rarely needs the raw bytes again. | `proactivePrune` aged-file branch (`agenticRunner.ts:5096+`) | M |
+| **P-E** | **Loosen one-shot injection gating for repeated failures.** The per-turn dedup flags suppress re-injection across turns when the model pivots stems; allow re-injection when `_argCohorts[fp].failure >= 2` regardless of stem. | injectors around `_errorPatterns` / REG-32 | S |
+
+### 2.4 Note on the new modules
+
+`permissionRuleset.checkDoomLoop` and `childSession`'s permission model are exactly the
+primitives P-C wants — but they are **dead code**. The agent built the right tool for this fix and
+then never connected it. Wiring `checkDoomLoop` into the live dispatch path (P-C) is the one piece
+of the self-edit worth rescuing immediately.
+
+---
+
+## Recommended next actions
+
+1. **Do not commit the working tree as-is** — it does not build and deletes exports the CLI needs.
+2. **Salvage list** (cherry-pick into compiling changes): `agent-types.ts` `mode` field (restore
+   the removed registry functions + keep `plan`), `tool-batching.ts` Zod schemas, Ollama
+   `finish_reason` plumbing.
+3. **Quarantine** the 6 new modules into a `proposals/` or feature branch — they're design sketches,
+   not integrations. Fix `compactionAgent` to actually call an LLM before anyone imports it.
+4. **Ship the duplicate-call fix independently** of the P0–P10 refactor: P-A + P-B + P-C give the
+   biggest behavior win and don't depend on the broken modules.
+5. **Add a build gate to the self-edit loop** — the agent must run `tsc -p packages/orchestrator`
+   and only mark `task_complete` on exit 0. This run would have caught everything in Part 1.

package/docs/opencode-agentic-loop-comparison.md

@@ -0,0 +1,290 @@
+# OpenCode → Omnius: Agentic Loop & Sub-Agent Delegation Comparison
+
+> Exhaustive comparison between `https://github.com/anomalyco/opencode/tree/dev` and
+> `packages/orchestrator/src/agenticRunner.ts` (omnius).
+> Generated 2026-06-10.
+
+---
+
+## 1. Main Agent Loop Structure
+
+### OpenCode — `src/session/prompt.ts:1190-1390`
+
+- **`while(true)`** loop with **natural exit** conditions — breaks when `lastAssistant.finish` is not `"tool-calls"` AND no pending tool calls
+- Each iteration: `filterCompacted` → `latest` (find last user/assistant/finished/tasks) → resolve tools → call LLM → decide next step
+- No fixed turn cap — bounded by agent `steps` config (default varies by agent)
+- Result triage: `"stop"`, `"compact"`, or `"continue"` — compaction is an **inline loop control** decision
+
+### Omnius — `orchestrator/src/agenticRunner.ts:9311`
+
+- **`for (let turn = 0; turn < turnCap; turn++)`** with explicit turn cap (default 60)
+- Much more complex per-turn preamble: REG-35 DoVer checkpoints, REG-46 world-state, REG-58/60/61 stagnation, REG-44 stuck, REG-50 write-thrash, REG-53 edit-fail-thrash, REG-18 stagnation window, etc.
+- Exit only via `task_complete` tool with 3 identical handler implementations (streaming/unhandled/batch paths)
+- No natural "model ran out of things to do" exit — model must explicitly call `task_complete`
+
+### Learnings
+
+- **Replace fixed `for` loop with natural-exit `while(true)`** — let the model exhaust its intent naturally. Keep turn cap as a safety fuse only (e.g., `maxTurns`). The 3× duplicated `task_complete` handler is a code-smell; unify into one path.
+- **Adopt OpenCode's `finish` reason pattern** — use the LLM's `stop_reason` / `finish_reason` to detect natural completion instead of requiring an explicit `task_complete` tool call for every exit.
+
+---
+
+## 2. Sub-Agent Delegation
+
+### OpenCode — `src/tool/task.ts`
+
+- **`sessions.create({ parentID, title, agent, permission })`** — creates a **persisted child session** in the DB with full lifecycle
+- **Permission derivation** (`src/agent/subagent-permissions.ts:1-46`): forwards parent agent `edit` denies, parent session denies, defaults-deny `todowrite`/`task` unless subagent explicitly permits
+- **Background mode** (`task.ts:background.start()`): returns immediately, result injected as synthetic message
+- **`task_id` resumption**: passing a prior `task_id` continues the same subagent session with accumulated context
+- **Agent types are declarative** (`src/agent/agent.ts`): `mode: "subagent" | "primary" | "all"` — subagents can only be spawned via `task` tool, never selected by user
+- **Concurrency hint in prompt** (`src/tool/task.txt`): "Launch multiple agents concurrently whenever possible"
+
+### Omnius — `execution/src/tools/agent-tool.ts`
+
+- **Three delegation mechanisms**:
+  1. `agent-tool.ts:329` — **worktree isolation**: spawns subprocess via `spawnSubprocess`
+  2. `agent-tool.ts:351` — **background in-process**: returns task ID, spawns in-process agent
+  3. `agent-tool.ts:390` — **foreground in-process**: blocks until complete
+- **No persisted child session** — sub-agents share the parent session's message array
+- **No permission derivation** — sub-agents get same permissions as parent (except optional `toolNames` filter)
+- **No `task_id` resumption** — each spawn is fresh context
+- **Also has legacy**: `full-sub-agent.ts` (separate OS process), `sub_agent` (routed through agent-tool.ts now)
+- **Coordinator pattern** (`orchestrator/src/coordinator.ts:106`): `CoordinatorManager` enforces `maxConcurrentWorkers` (5) and `maxTotalWorkers` (20), but limited to coordinator mode
+
+### Learnings
+
+- **Implement child sessions with permission derivation** — this is the single biggest gap. Sub-agents currently unbounded — can do anything parent can. No state isolation.
+- **Add `task_id` resumption** — deduplicate sub-agent invocations by allowing the model to continue a prior sub-agent's context. This avoids redundant exploration and enables iterative refinement.
+- **Adopt declarative agent types with `mode`** — replace the programmatic `agent-types.ts` registry with a schema-driven system where `mode: "subagent"` agents can only be called via the `agent` tool (not activated directly by user), matching OpenCode's separation of concerns.
+- **Permission forwarding**: parent agent's `edit`-deny rules (e.g., plan mode) must cascade to sub-agents automatically.
+
+---
+
+## 3. Tool Batching / Parallel Execution
+
+### OpenCode — `src/session/processor.ts`
+
+- **No explicit batching** — relies on LLM provider's native ability to emit multiple `tool-call` events in one stream
+- **AI SDK `streamText()`** (`src/session/llm/ai-sdk.ts`) executes tools concurrently internally
+- **Per-tool `Deferred<void>`** (`processor.ts:ensureToolCall`) — each tool call gets a deferred that resolves when result arrives
+- **Cleanup**: `Effect.forEach(Object.values(ctx.toolcalls), ..., { concurrency: "unbounded" })` with 250ms timeout per call
+- **Ordering**: events arrive in temporal order from the LLM stream; results are interleaved arbitrarily
+
+### Omnius — `orchestrator/src/tool-batching.ts`
+
+- **Explicit batching**: `partitionToolCalls()` groups concurrent-safe tools into parallel batches, serial tools each get single-item batches
+- **`executeBatch()` with worker pool** (`tool-batching.ts:212-233`): `withConcurrencyLimit(fns, limit=8)` — N concurrent workers
+- **Dual dispatch paths** (`agenticRunner.ts:15281-15705`):
+  - Streaming: `StreamingToolExecutor` with `queue → finalize → waitAll → drainCompleted` + ordering guarantees
+  - Non-streaming: `partitionToolCalls → executeBatch` with REG-24 fingerprint dedup
+- **Streaming executor state machine** (`streaming-executor.ts:292`): `canExecute()` checks — concurrent-safe tools run in parallel, exclusive tools run alone (ordering: stops at first exclusive)
+- **Duplicate detection** (`streaming-executor.ts:327-393`): `entryFingerprint()` / `findPriorEquivalent()` / `mirrorPriorEquivalent()` — identical tool calls within same stream share results
+
+### Learnings
+
+- **Simplify to single dispatch path** — the streaming/non-streaming bifurcation leads to code duplication (3 `task_complete` handlers, parallel dispatch logic). OpenCode's unified event-stream model avoids this entirely.
+- **Adopt event-based tool tracking** — replace the `rawToolCalls` array + result-mapping with a per-call `Deferred`/`Promise` map. This eliminates the need for `drainCompleted()` ordering logic and the dual-path complexity.
+- **OpenCode's simplicity is instructive** — it doesn't need `partitionToolCalls` or concurrency-safe classifications because the AI SDK handles it. Consider delegating concurrency to the backend layer.
+
+---
+
+## 4. Session / Runner State Management
+
+### OpenCode — Three-Layer Architecture
+
+1. **`Runner`** (`src/effect/runner.ts:1-220`): Per-session state machine with 4 states — `Idle`, `Running`, `Shell`, `ShellThenRun`. Run and shell are **mutually exclusive**. Shell has priority; runs queue as `ShellThenRun` and auto-start when shell finishes.
+2. **`RunCoordinator`** (`packages/core/src/session/run-coordinator.ts:1-200`): Per-key drain coordination with coalescing. At most **1 active + 1 pending** per session. `run` (explicit) dominates `wake` (advisory). Interrupts suppress stale wakes.
+3. **`SessionPrompt.runLoop`** (`src/session/prompt.ts`): High-level loop orchestration. `ensureRunning()` guarantees at most one loop iteration per session.
+
+### Omnius — `orchestrator/src/agenticRunner.ts:1583-1600`
+
+- **Single-class monolith**: `AgenticRunner` class with 200+ private properties, all in one file (~25,159 lines)
+- **No state machine** for run/shell concurrency — the `run()` method is called directly
+- **No drain coordination** — multiple calls to `run()` would stack, not coalesce
+- **No explicit interruption model** — abort via `options.abortSignal` at `agenticRunner.ts:9330` (passthrough, not session-aware)
+
+### Learnings
+
+- **Decompose `AgenticRunner`** — split into layers: Runner (state machine), Orchestrator (loop control), Coordinator (drain + interruption). The monolith approach makes reasoning about concurrency impossible.
+- **Add Run/Shell mutual exclusion** — when a shell command is running, agent loop should defer; when loop is running, shell should either fail or queue. OpenCode's `ShellThenRun` pattern is correct.
+- **Add drain coalescing** — if the agent completes a turn and the session has new work, coalesce into one chain instead of stacking multiple `run()` calls.
+
+---
+
+## 5. Tool Definition & Registration
+
+### OpenCode — `packages/core/src/tool/tool.ts`
+
+- **`Tool.make(config)`**: Zod-schema-validated input/output, `toModelOutput` mapping, opaque branded `Definition<Input, Output>` type
+- **`definition(name)` + `settle(call, context)`** stored in `WeakMap<AnyTool, Runtime>` — decoupled from AI SDK format
+- **`withPermission(tool, name)`** — decorator pattern, produces a new tool object with an attached permission string
+- **`ToolRegistry.materialize()`** (`packages/core/src/tool/registry.ts`): resolves full tool definitions for a given permission ruleset
+- **`SessionTools.resolve()`** (`packages/opencode/src/session/tools.ts`): wraps tools as AI SDK `tool()` objects with permission checking, plugin hooks, truncation
+
+### Omnius — `execution/src/index.ts`
+
+- **`AgenticTool` interface**: `{ name, description, execute(args): Promise<string>, parameters?, isConcurrencySafe?, isReadOnly?, executeStream? }`
+- **Flat catalog registration** — all tools exported from a single massive `index.ts` (~100+ tools)
+- **No schema validation** — `execute` receives `Record<string, unknown>`, manual parsing inside each tool
+- **No permission system** — tools are either available or not, no granular `allow`/`deny`/`ask` rules
+- **No AI SDK compatibility layer** — tool definitions are constructed manually for each backend format
+
+### Learnings
+
+- **Add schema-validated tool definitions** — Zod schemas for input/output give free validation, documentation generation, and type safety. The current `Record<string, unknown>` pattern is error-prone.
+- **Add a permission decorator system** — `withPermission` pattern allows reusable, composable permission rules on any tool without modifying the tool itself. This cascades naturally to sub-agent permissions.
+- **Decouple tool definition from backend format** — like OpenCode's `WeakMap<AnyTool, Runtime>`, have a canonical internal format and adapters per backend (OpenAI, vLLM, Ollama).
+
+---
+
+## 6. Context Compaction / Overflow
+
+### OpenCode — `src/session/prompt.ts` + `compaction` agent
+
+- **Inline overflow detection**: `runLoop` checks `lastFinished` context size against budget; if exceeded, `compaction.create()` and `continue`
+- **Dedicated compaction agent** (`src/agent/agent.ts`): `compaction` — hidden primary agent with all tools denied, runs `PROMPT_COMPACTION` via LLM
+- **Message filtering**: `MessageV2.filterCompactedEffect(sessionID)` — compacted messages are filtered out before each loop iteration
+- **Compact or break**: compaction returns `"stop"` or `"continue"` — if context is too tight even after compaction, the loop terminates naturally
+
+### Omnius — `orchestrator/src/context-compressor.ts`
+
+- **Two-phase compression**:
+  1. Phase 1 (cheap): prune old tool results (no LLM call)
+  2. Phase 2 (expensive): LLM-generated structured summaries with sections (Goal, Constraints, Progress, Key Decisions, Relevant Files, Next Steps, Critical Context)
+- **`DefaultContextEngine`** (`orchestrator/src/contextEngine.ts`): simple budget-based pruning — drops oldest non-evidence messages
+- **Context assembly** (`agenticRunner.ts:assembleContext()`): sections `c_instr, c_state, c_identity, c_know, c_retrieval, c_graph, c_plan, c_todos, c_lessons, c_workboard`
+- **No compaction agent** — compression is performed in-process, not delegated to a dedicated agent call
+
+### Learnings
+
+- **Consider a dedicated compaction agent** — OpenCode's approach of delegating context compression to a separate LLM call with zero-tool agent avoids polluting the main agent's context with compression overhead and allows the compression to be a real summarization pass rather than a pruning pass.
+- **Add post-compaction exit** — when compression has been applied but token budget is still exceeded, the loop should terminate gracefully (signal "context too tightly coupled to summarize") instead of entering a compaction loop.
+- **Pre-compute budget before LLM call** — detect overflow before calling the LLM, not after. OpenCode does this in `runLoop` via the `overflow` task check.
+
+---
+
+## 7. Model Calling / Streaming
+
+### OpenCode — `src/session/llm.ts`
+
+- **Dual runtime architecture**: Native (`@opencode-ai/llm`) or AI SDK (`streamText`) fallback
+- **Unified `LLMEvent` stream**: normalized event types — `text-start/delta/end`, `reasoning-start/delta/end`, `tool-input-start/delta/end`, `tool-call`, `tool-result`, `tool-error`, `step-start/finish`, `finish`
+- **Tool call streaming**: `tool-input-start/delta/end` events let the processor track partial tool arguments before the call is finalized
+- **`createStructuredOutputTool()`** (`prompt.ts`): injects a json_schema tool via `tool_choice: "required"` for structured outputs
+
+### Omnius — `backend-vllm/src/VllmBackend.ts`, `OllamaBackend.ts`
+
+- **Simple `chatCompletion({ messages, tools })`** — standard OpenAI-compatible API
+- **Streaming path** (`agenticRunner.ts:23035-23392`): custom SSE accumulation via `streamingRequest()` — manually accumulates `tool_call_delta` chunks, repairs JSON, manages multi-tool ordering
+- **No normalized event stream** — tool parsing is done after the entire response is received (non-streaming) or via ad-hoc accumulator logic (streaming)
+- **No tool-call streaming** — partial tool arguments are not exposed to the executor (cannot start executing before args are fully received, unlike OpenCode's `tool-input-start`)
+
+### Learnings
+
+- **Normalize the event stream** — build an `LLMEvent` union type that all backends emit. This eliminates the streaming/non-streaming bifurcation and the two separate dispatch paths. Omnius already has `runEvents.ts` types but doesn't use them as a unified stream.
+- **Adopt tool-input streaming** — expose partial tool argument events upstream so the streaming executor can start executing tools before all arguments are fully received (especially valuable for large writes/reads with many arguments).
+- **Unify backend adapter interface** — currently each backend returns a different format. A normalized `Stream<LLMEvent>` return type would allow the entire dispatch pipeline to be backend-agnostic.
+
+---
+
+## 8. Adversary / Critic / Post-Turn Analysis
+
+### OpenCode
+
+- **No adversary system** — OpenCode does not have a dedicated post-turn meta-analysis layer. It relies on:
+  - **Permission `ask` prompts** for user-in-the-loop decisions (`doom_loop` detection at `processor.ts` — checks last 3 identical tool calls)
+  - **The model's own reasoning** to self-correct
+  - **Compaction agent** for context-level correction
+- **Error handling**: `tool-error` → `failToolCall()` → marks part as `"error"` + sets `ctx.blocked` for permission rejections
+
+### Omnius — `orchestrator/src/agenticRunner.ts:20395-20758`
+
+- **Extensive adversary system** with 4 detections:
+  1. `adversaryObserve` false failure claim (line 20541)
+  2. False success claim (line 20595)
+  3. **Redundant action** — repeated same tool+args that already succeeded (line 20659)
+  4. **Idle think** — runaway output without input (line 20743)
+- **Redundant action signal** (`_adversaryRedundantSignals`): forwarded to `Critic.evaluate()` in `executeSingle` (line 12735-12738)
+- **Escalation**: dedup `_adversaryRecentFlags` with system-role injection after 3 repeats
+- **Adversary mode**: `"backseat"` (events only), `"skillcoach"` (injects critiques), `"both"` (default)
+- **Also**: REG-24 fingerprint dedup, REG-47 backward-pass critic, REG-11 semantic shell failure detection
+
+### Learnings
+
+- **Omnius's adversary system is genuinely innovative** — OpenCode has no equivalent. The redundant action detection, false-failure-correction, and depth-gauge integration are unique differentiators.
+- **But complexity is high** — the adversary adds 500+ lines of stateful logic across multiple methods. Consider whether some adversarial patterns could be simplified to OpenCode's permission `ask` pattern (user-in-the-loop) instead of autonomous critique generation, at least for lower-confidence detections.
+- **Unify with Critic** — the adversary `_adversaryRedundantSignals` is consumed by `Critic.evaluate()` in `executeSingle`. This cross-cutting coupling makes it hard to understand the full redundant-action flow. Consider making the adversary emit typed events that the critic subscribes to.
+
+---
+
+## 9. Agent Type System
+
+### OpenCode — `src/agent/agent.ts`
+
+- **Declarative schema**: `Info = { name, description, mode: "subagent"|"primary"|"all", permission: Ruleset[], model, prompt, steps, color, ... }`
+- **Built-in registration inside `layer`**: build (primary), plan (primary), general (subagent), explore (subagent), compaction/title/summary (hidden primaries)
+- **User-defined**: read from user config (`cfg.agent`), merged into `agents` map
+- **`generate()`**: creates new agents via LLM `generateObject` using `PROMPT_GENERATE`
+- **Permission rulesets per agent**: `explore` denies everything except grep/glob/list/bash/webfetch/websearch/read; `plan` denies all edit tools
+- **Hidden agents**: `compaction`, `title`, `summary` — `native: true, hidden: true`, not shown in agent picker, used internally
+
+### Omnius — `orchestrator/src/agent-types.ts`
+
+- **Programmatic registry**: `AGENT_TYPES = Record<string, AgentType>` with `registerAgentType(name, config)`
+- **Built-in**: `general` (full access), `explore` (read-only), `plan` (read-only + planning), `coordinator` (orchestration + spawning)
+- **Agent shape**: `{ allowedTools, disallowedTools, maxTurns, model, canSpawnAgents, description, systemPromptAddition }`
+- **No `mode` field** — agents aren't classified as primary/subagent. Any agent can be activated by the user.
+- **No user-defined agents** — no config-based agent creation
+- **No agent generation** — no LLM-based agent creation
+
+### Learnings
+
+- **Add `mode` to agent types** — explicitly declare which agents are `"primary"` (user-selectable) vs `"subagent"` (task-tool-only) vs `"all"`. This enforces the architectural constraint that subagents can only be spawned via the `agent` tool.
+- **Make agent definitions declarative/configurable** — allow users to define custom agents in config files. The `generate()` pattern (LLM creates an agent definition) is an interesting power feature but secondary.
+- **Use permission rulesets per agent type** — instead of `allowedTools`/`disallowedTools` arrays, adopt OpenCode's `PermissionV1.Ruleset` pattern. This enables granular `allow`/`deny`/`ask` per tool/permission and natural subagent inheritance.
+
+---
+
+## 10. Permissions & Safety
+
+### OpenCode — `packages/core/src/session/permission.ts`
+
+- **Granular rulesets**: `PermissionV1.Ruleset = Array<{ permission: string, pattern: string, action: "allow" | "deny" | "ask" }>`
+- **`ask` prompts**: user-in-the-loop permission checks (e.g., `doom_loop: ask` — after 3 identical tool calls, ask user if they want to allow/deny)
+- **Parent→child forwarding** (`src/agent/subagent-permissions.ts`): parent agent denies + parent session denies + `external_directory` rules are forwarded to subagent sessions
+- **Default deny for subagents**: `todowrite` and `task` are denied in subagents unless explicitly permitted
+
+### Omnius — `orchestrator/src/agenticRunner.ts` + tool implementations
+
+- **Constraint system** (`execution/src/workingNotes.ts`, `constraints`):
+  - `formatSecurityNotice()`, `checkConstraints()`, `formatViolationWarning()`
+  - Constraints checked in `executeSingle` before tool dispatch
+- **Tool allow/disallow lists**: per agent type, simple string arrays
+- **No granular permission rules** — no `ask` prompts, no `deny`/`allow`/`ask` ternary
+- **No subagent permission derivation** — sub-agents (via `agent` tool) inherit parent's full permission set
+- **No doom-loop detection** — the adversary has `idle_think` (consecutive short outputs) but no permission-based intervention
+
+### Learnings
+
+- **Implement granular permission rulesets** — replace flat allow/disallow arrays with structured `{ permission, pattern, action }` rules. This enables: (a) `ask` for sensitive operations, (b) pattern-based denials (e.g., `edit:*.env` → deny), (c) forwarding to subagents, (d) user-configurable permission overrides.
+- **Add doom-loop detection with `ask`** — when the model repeats the same tool with same args 3+ times, prompt the user instead of silently injecting an adversary critique. The user can decide allow/deny/interrupt.
+- **Constraint system is good, but integrate with permissions** — the `checkConstraints()` system is powerful but operates independently of the agent type system. Constraints should be part of the permission ruleset, not a separate pre-hook.
+
+---
+
+## Summary: Highest-Impact Improvements (Stack Ranked)
+
+| Priority | Improvement                               | Why                                                                                                      |
+| -------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| **P0**   | Child sessions with permission derivation | Sub-agents currently unbounded — can do anything parent can. No state isolation.                         |
+| **P1**   | Declarative agent types with `mode`       | Enables architectural enforcement (primary vs subagent), user-configurable agents, LLM-generated agents  |
+| **P2**   | Unified event-stream dispatch             | Eliminates streaming/non-streaming bifurcation + 3× duplicated `task_complete` handlers                  |
+| **P3**   | Natural exit condition                    | Replace `task_complete`-required exit with LLM `stop_reason` detection; keep `task_complete` as optional |
+| **P4**   | Runner state machine                      | Run/Shell mutual exclusion, drain coalescing, interruption model — prevents subtle concurrency bugs      |
+| **P5**   | Tool definition schema validation         | Replace `Record<string, unknown>` with Zod schemas for free validation + documented schemas              |
+| **P6**   | Granular permission rulesets              | `allow`/`deny`/`ask` ternary — cascade to subagents, user-in-the-loop for sensitive ops                  |
+| **P7**   | Decompose AgenticRunner                   | Split into Runner + Orchestrator + Coordinator layers (currently 25K-line monolith)                      |
+| **P8**   | Unify backend adapter interface           | Normalized `LLMEvent` stream type eliminates per-backend dispatch differences                            |
+| **P9**   | Dedicated compaction agent                | Offload context compression to a zero-tool agent to avoid pollution in main context                      |
+| **P10**  | `task_id` resumption for sub-agents       | Allow continuing prior sub-agent sessions (dedup exploration, iterative refinement)                      |

package/docs/operations/security-and-remote-access.md

@@ -14,7 +14,7 @@ Bind to a network interface only when you also configure auth:
 
 ```bash
 OMNIUS_HOST=0.0.0.0:11435 \
-OMNIUS_API_KEYS="read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops" \
+OMNIUS_REST_API_KEYS="read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops" \
 omnius serve
 ```
 
@@ -59,7 +59,7 @@ For a LAN daemon, prefer a scoped key set:
 
 ```bash
 OMNIUS_HOST=0.0.0.0:11435 \
-OMNIUS_API_KEYS="dash:read:grafana:600::,ci:run:ci:60:100000:3,ops:admin:ops:120:500000:10" \
+OMNIUS_REST_API_KEYS="dash:read:grafana:600::,ci:run:ci:60:100000:3,ops:admin:ops:120:500000:10" \
 omnius serve
 ```
 

package/docs/operations/version-compatibility.md

@@ -0,0 +1,63 @@
+# Service Version Compatibility
+
+A client may be newer than the long-running Omnius daemon it reaches. The
+runtime version gate prevents a stale service from quietly accepting work
+whose provider, tool, or request contract it does not understand.
+
+## Inspect The Service
+
+```bash
+curl -s http://127.0.0.1:11435/version
+```
+
+The response contains `package_version`, `api_version`, and
+`discovery_schema_version`. Compatibility fields `version`, `boot_version`,
+`boot_package_hash`, `node`, and `platform` remain for existing clients.
+
+Inspection endpoints remain available even when the service is too old to run
+a new client request: health, version, help, OpenAPI, and discovery.
+
+## Require A Minimum Version
+
+Send a SemVer minimum on execution requests:
+
+```text
+X-Omnius-Min-Version: <minimum-compatible-package-version>
+```
+
+The gate applies to:
+
+- `POST /v1/run`;
+- `POST /v1/chat`, `/api/chat`, and `/v1/chat/completions`;
+- `POST /v1/generate` and `/api/generate`;
+- `POST /v1/tools/{name}/call`;
+- `POST /v1/commands/{cmd}`.
+
+The service checks the precondition before the request handler creates state,
+loads a model, calls a provider, or invokes a command/tool.
+
+Responses:
+
+| Condition | Result |
+| --- | --- |
+| header omitted | normal backward-compatible behavior |
+| valid minimum, service satisfies it | request proceeds |
+| invalid SemVer | RFC 7807 `400 Bad Request` |
+| service older than minimum | RFC 7807 `412 Precondition Failed` |
+
+A `412` is not retryable against the same daemon. Update or reconnect to a
+verified compatible Omnius service, inspect `/version` again, and resubmit
+only after the precondition can succeed.
+
+## Why Both Check And Header
+
+`GET /version` gives a useful compatibility diagnostic. The header is the
+execution-time guard and closes the race between checking a service and
+submitting work after that service has been replaced or routed elsewhere.
+
+## Client Rule
+
+Keep the required version in the adapter that constructs Omnius execution
+requests. Do not rely on a human-readable npm version, cached install
+metadata, or the client's own package version. Compare against the daemon's
+reported package version and preserve the execution precondition.