# Agent And Service Integration

An integration should discover Omnius at runtime instead of encoding a partial
provider or tool list.

## Bootstrap Sequence

1. Read `GET /v1/discovery/bootstrap` (or run `omnius docs`) to obtain the
   compact strategy, start-here entries, profiles, common intents, and safety
   invariants.
2. Read `GET /version` and assert the minimum compatible Omnius package
   version.
3. Search `GET /v1/discovery` or the bundled `docs/DISCOVERY.json` by user
   intent, then expand one stable ID.
4. Follow its `use_when`, `avoid_when`, exact interfaces, workflow, safety,
   state, verification, failure recovery, and source-of-truth fields.
5. Confirm dynamic availability through OpenAPI and the relevant live registry.
6. For live work, send `X-Omnius-Min-Version` on execution requests and verify
   the declared terminal result.

Human and CLI equivalents:

```bash
omnius docs
omnius discover "<user need>"
omnius show <stable-id>
omnius capabilities --json
```

## Stable Discovery Surfaces

| Surface | Use |
| --- | --- |
| `docs/DISCOVERY.json` | offline package catalog |
| `docs/DISCOVERY.md` | compact human/agent orientation |
| `omnius discover` | ranked local lookup |
| `omnius show` | exact entry expansion |
| `GET /v1/discovery/bootstrap` | compact onboarding profiles and start-here map |
| `GET /v1/discovery` | daemon lookup |
| `GET /v1/discovery/{id}` | daemon exact entry |
| `GET /openapi.json` | canonical HTTP wire contract |
| `GET /v1/tools` | live tool metadata |
| `GET /v1/skills` | live skill catalog |

The discovery catalog describes how to find a capability; live OpenAPI,
provider, tool, auth, and policy state determine whether it can be used by the
current caller.

## Search Contract

Search accepts a query, optional `kind`, and result limit. Prefer stable IDs
in stored integrations. Use free text only to find an ID or handle a user's
new intent. Exact IDs, aliases, and titles should rank above prefix and token
matches.

Supported kinds are `capability`, `layer`, `module`, `workflow`, `runtime`,
`store`, `provider`, `tool`, `api`, `command`, `skill`, `guide`, `config`, and
`operation`. Filters also accept exact `audience` and `layer` values;
`include_internal=true` deliberately includes internal notes that are hidden
from the default result set.

## Agent Profiles

| Agent | Minimum context to load |
| --- | --- |
| Small or constrained model | bootstrap + one `workflow.*` entry + its smallest referenced guide |
| Coding agent | workflow + owning `layer.*` + owning `module.*` + targeted source/tests |
| Service integrator | bootstrap + `workflow.choose-entrypoint` + exact `api.*`/tool/provider entry + live OpenAPI |
| Operator | `layer.operations` + affected `runtime.*` + `workflow.debug-runtime` |
| Maintainer | architecture/system map + contracts/observability layers + affected modules and freshness tests |

Do not dump the complete 600+ entry catalog or whole docs tree into a small
model. Use search to narrow, exact expansion to plan, and references to load
only the evidence required by the current step.

## Entrypoint Decision

| Requirement | Surface | Completion semantics |
| --- | --- | --- |
| Interactive human control or user-only slash command | `omnius` | foreground TUI event |
| One synchronous shell task | `omnius "<task>"` | process exit plus verified output |
| Stateful daemon conversation | `POST /v1/chat` | response tied to a real chat session |
| OpenAI client compatibility | `POST /v1/chat/completions` | one completion or SSE; optional agent loop |
| Long task, events, steering, or cancellation | `POST /v1/run` | retain run ID until terminal verified state |
| One isolated directly exposed tool | declared `POST /v1/tools/{name}/call` | structured tool result and side-effect check |

Expand `workflow.choose-entrypoint` for executable steps. Never construct
`/v1/commands/<name>` or `/v1/tools/<name>/call` from a display name alone.
Command `surfaces.rest` and tool `direct_callable`/interfaces are authoritative.

## Long-Run Recipe

1. Check `/version`, `/health/ready`, and the `/v1/run` OpenAPI operation.
2. Submit the task with the explicit workspace and minimum Omnius version.
3. Persist the returned run ID. Accepted or queued is not completed.
4. Poll status and/or consume events; retain evidence across reconnects.
5. Steer or cancel only through documented routes and state transitions.
6. At terminal status, inspect result artifacts and verification evidence.

Expand `workflow.async-agent-run` for failure recovery and canonical sources.

## State Scope

- `<project>/.omnius` is project-local: conversations, sessions, tasks/runs,
  project context, indexes, memories, and project preferences.
- `~/.omnius` is user-global: daemon and update state, global configuration and
  credentials, managed Python environments, shared model/media storage, and
  the workspace registry.

Resolve the active workspace before reading project state. Never return raw
global secrets through discovery, errors, logs, URLs, or telemetry. Expand
`store.project` or `store.global` before writing state from an integration.

## Bring Your Own Inference

Do not infer provider protocol in an account adapter from a display label or
from “has an API key.” Resolve the provider descriptor and preserve its
protocol:

- `anthropic-messages` for Anthropic/Claude;
- `openai-chat` for Gemini and registered OpenAI-compatible providers;
- `ollama` for Ollama;
- explicit protocol for custom endpoints.

See [Bring Your Own Inference](./bring-your-own-inference.md).

## Tool Invocation

Treat invocation mode as data. A tool in the catalog may be agent-bound even
when its schema and security classification are visible. `web_search` is the
important example: offer it to an Omnius agent loop instead of assuming
`POST /v1/tools/web_search/call`.

See [Tools And Web Search](./tools-and-web-search.md).

## Version Precondition

Reading `/version` is useful for diagnostics, but there is a race between a
version check and job submission. Send the same minimum version on each
execution request so a stale daemon rejects the request before it creates a
job or invokes a model/tool. See
[Service Version Compatibility](../operations/version-compatibility.md).

## Secret Boundary

Store provider and daemon credentials separately. Discovery results, project
guidance, error messages, URLs, logs, and telemetry must never contain raw
keys. Prefer scoped REST bearer keys and the narrowest compatible tool
profile for remote agents.