# Omnius Agent System Map

Use this page when you need to understand how a user-visible behavior travels
through Omnius, where its state lives, and which package owns a change. For a
specific task recipe, search the generated catalog first:

```bash
omnius discover "<desired outcome>"
omnius show workflow.choose-entrypoint
omnius show layer.<name>
omnius show module.<name>
```

## Entrypoint Decision

| Caller needs | Entrypoint | Lifecycle | State owner |
| --- | --- | --- | --- |
| Human conversation and slash commands | `omnius` | foreground TUI | selected project + global config |
| One synchronous shell task | `omnius "<task>"` | foreground process | selected project |
| Stateful service conversation | `POST /v1/chat` | daemon session | selected project chat session |
| OpenAI-compatible completion | `POST /v1/chat/completions` | request; optional agent loop | request or selected session |
| Long autonomous task | `POST /v1/run` | asynchronous run ID + events | project run/session stores |
| One safe direct tool | declared `POST /v1/tools/{name}/call` | request | tool-specific |
| Browser GUI | daemon dashboard | browser + daemon | active workspace registry |
| Desktop health/update control | `omnius indicator`, `/indicator` | tray + daemon | global runtime |
| Remote messaging | Telegram gateway | gateway + daemon/TUI engines | scoped Telegram session |

A slash command does not automatically have a REST route. A tool schema does
not automatically imply direct-call exposure. Read the command `surfaces` or
tool `direct_callable` field first.

## Request And Evidence Flow

```text
TUI / CLI / REST / Dashboard / Tray / Telegram
                       |
                       v
          intake + version/auth/scope gates
                       |
             +---------+----------+
             |                    |
      chat/session path     asynchronous run path
             |                    |
             +------ AgenticRunner+
                       |
       prompt + context + memory + code retrieval
                       |
              provider/model backend
                       |
                 tool requests
                       |
          execution policy + tool runtime
                       |
             observation/evidence ledgers
                       |
      events + action tree + status + final result
```

The orchestration loop must retain a substantive frontier between turns.
Context compaction may summarize history, but it must not erase the current
task, inspected evidence, completed actions, unresolved blockers, or next
verification. Repeated reads without new evidence point to the context,
trajectory checkpoint, or run-frontier contracts—not to a need for more reads.

## Layer Map

| Layer ID | Owns | First source to inspect |
| --- | --- | --- |
| `layer.discovery` | catalog, bootstrap, init guidance, docs skills | `scripts/generate-discovery.mjs` |
| `layer.interface` | CLI/TUI, REST, dashboard, tray, Telegram | `packages/cli/src` |
| `layer.orchestration` | agent loop, task/run lifecycle, completion and recovery | `packages/orchestrator/src` |
| `layer.inference` | provider descriptors, endpoint/model routing | `packages/backend-vllm/src` |
| `layer.execution` | tools, schemas, security and exposure | `packages/execution/src` |
| `layer.context` | prompts, context admission/compaction, token budgets | `packages/prompts/src`, orchestrator context modules |
| `layer.memory` | sessions, episodes, temporal memory, maintenance | `packages/memory/src`, CLI session adapters |
| `layer.code-intelligence` | index, code graph, repository retrieval | `packages/indexer/src`, `packages/retrieval/src` |
| `layer.media` | ASR, TTS, voice, vision, generated media | execution ASR/media + CLI voice runtime |
| `layer.persistence` | project/global state and precedence | CLI config/project state + model store |
| `layer.observability` | events, action tree, metrics, evidence/debug artifacts | orchestrator ledgers + CLI projections |
| `layer.security` | auth/scopes, secret boundaries, tool and hardware policy | REST auth + execution classifier |
| `layer.operations` | daemon, indicator, updates, install, publish | CLI daemon/update/tray + scripts |
| `layer.contracts` | schemas, OpenAPI, registries, compatibility | schemas package + metadata registries |

Run `omnius show layer.<name>` for a compact description and source-of-truth
list. Run `omnius discover --kind module "<behavior>"` to locate package
ownership without scanning every package.

## Workspace Packages

| Package | Responsibility | Depends on |
| --- | --- | --- |
| `@omnius/cli` | all public surfaces and runtime adapters | backend, execution, memory, orchestrator, retrieval, schemas |
| `@omnius/orchestrator` | long-horizon agent control | backend, execution, memory, retrieval, schemas |
| `@omnius/execution` | executable tools and policy | schemas and external runtimes |
| `@omnius/backend-vllm` | inference protocols/providers | transport dependencies |
| `@omnius/prompts` | system/task prompt loading | prompt artifacts |
| `@omnius/memory` | persistent episodic/temporal memory | storage dependencies |
| `@omnius/indexer` | code graph/index construction | schemas/storage |
| `@omnius/retrieval` | repository retrieval | index/schema contracts |
| `@omnius/schemas` | shared wire/domain types | no higher Omnius layer |

The generated `module.*` entries are derived from workspace package manifests,
so they remain the machine-readable ownership map.

## State And Storage

| Scope | Root | Examples | Do not put here |
| --- | --- | --- | --- |
| Project | `<project>/.omnius` | sessions, task/run artifacts, project context, indexes, project memory/skills/preferences | shared weights, global credentials, daemon identity |
| User global | `~/.omnius` | global config/credentials, daemon/update state, managed Python environments, shared model/media store, workspace registry | project chat/task history |
| Published package | installed `omnius` package | compiled runtime, docs catalog, templates/assets | mutable user/project state |

Before reading project state, resolve the dashboard/TUI active workspace.
Before reading global config, apply secret-redaction rules. Never use the
current shell directory as a substitute for an explicitly selected project
when the caller supplied one.

## Canonical Registries

| Surface | Registry/source of truth | Live proof |
| --- | --- | --- |
| Slash commands | `packages/cli/src/tui/command-registry.ts` | `GET /v1/commands` for REST-exposed commands |
| REST | `packages/cli/src/api/openapi.ts` | `GET /openapi.json` |
| Providers | `packages/backend-vllm/src/providerRegistry.ts` | provider/model status routes |
| Tools | execution classes + tool manifest + direct registry | `GET /v1/tools`, `GET /v1/tools/{name}` |
| ASR | `packages/execution/src/asr/registry.ts` | `GET /v1/asr/engines`, `/status` |
| Discovery | `agent-map.json` + generated sources | `GET /v1/discovery/bootstrap`, `/v1/discovery` |
| Package/runtime identity | package metadata + boot provenance | `GET /version` |

Static discovery tells an agent what Omnius declares. Live registries tell it
what the running installation currently exposes and has ready. Listing static
discovery must never install dependencies, load models, or execute probes.

## Change Recipes

### Add or change a slash command

1. Update the command registry metadata and the execution dispatcher.
2. Set implementation status, exact surfaces, aliases, and every safety flag.
3. Add command-registry and dispatcher tests, including blocked surfaces.
4. Regenerate slash-command docs and discovery.

### Add or change a REST route

1. Define method, auth, input, output, errors, and operation summary in OpenAPI.
2. Implement the route with matching version/auth/policy gates.
3. Add route tests for success, validation, auth, and failure behavior.
4. Regenerate discovery; every OpenAPI path/method is cataloged automatically.

### Add or change a tool

1. Implement the executable and schema in `@omnius/execution`.
2. Classify side effects, risk, off-device behavior, and default exposure.
3. Add direct-call registration only when isolated invocation is intentional.
4. Test both metadata and execution; regenerate discovery.

### Add or change a provider

1. Add one descriptor with protocol, auth, paths, capabilities, and URL match.
2. Add transport/normalization tests and fail-closed unknown-provider tests.
3. Update configuration and provider guide only where the public workflow changes.
4. Regenerate discovery from the source registry—never from stale `dist/`.

## Debug Order

1. Capture the exact request/command, expected and actual output, project,
   timestamp, installed package version, and daemon version.
2. Check `/health`, `/health/ready`, `/version`, port/PID ownership, then the
   exact live registry/OpenAPI contract.
3. Inspect run/session events and verify the correct project/global state root.
4. Expand `workflow.debug-runtime`, the implicated `layer.*`, and `module.*`.
5. Patch the source owner, run the smallest regression tests, regenerate
   discovery, and reproduce the original path through terminal verification.

Do not begin with broad cache deletion, process killing, reinstalling, or model
loading. Those actions destroy evidence or can affect unrelated runtimes.