omnius 1.0.591 → 1.0.592

package/docs/getting-started/install.md

@@ -18,6 +18,20 @@ omnius
 
 The first launch opens the setup flow, probes local capabilities, and asks which endpoint and model path to use.
 
+The installer prints a short agent-discovery primer. It does not print keys or
+other secrets. You can run the discovery commands at any time:
+
+```bash
+omnius discover "bring your own inference"
+omnius show tool.web-search
+omnius docs
+omnius init
+```
+
+`omnius init` adds a managed Omnius discovery block to the project guidance
+files without replacing content outside that block. `--check` reports whether
+the guidance is current and `--dry-run` previews changes.
+
 ## Start The REST Daemon
 
 ```bash
@@ -36,6 +50,16 @@ Open API docs:
 http://127.0.0.1:11435/docs
 ```
 
+Agent-readable daemon entrypoints:
+
+```text
+http://127.0.0.1:11435/help
+http://127.0.0.1:11435/openapi.json
+http://127.0.0.1:11435/v1/discovery
+http://127.0.0.1:11435/v1/tools
+http://127.0.0.1:11435/v1/skills
+```
+
 ## Workspace Development
 
 ```bash

package/docs/getting-started/model-providers.md

@@ -10,6 +10,9 @@ Supported endpoint patterns include:
 - Omnius-managed Ollama pool
 - vLLM
 - OpenAI-compatible HTTP servers
+- Anthropic Claude through the native Messages API
+- Google Gemini through its official OpenAI-compatible endpoint
+- OpenAI
 - OpenRouter
 - Groq
 - Chutes
@@ -29,6 +32,16 @@ Use:
 
 Endpoint history records recently used URLs and auth metadata so users can return to external routers without retyping them.
 
+For the complete protocol, authentication, and fail-closed behavior, read
+[Bring Your Own Inference](../guides/bring-your-own-inference.md). The important
+distinction is that provider names are not cosmetic:
+
+- Ollama uses the `ollama` protocol.
+- Anthropic uses `anthropic-messages` and `POST /v1/messages`.
+- Gemini and the other compatible providers use `openai-chat`.
+- A custom URL must declare its protocol. Omnius does not send a probe or
+  inference request when it cannot determine the protocol safely.
+
 ## Model Discovery Rule
 
 When multiple endpoints are enabled, model lists should be consolidated from all toggled enabled endpoints. This applies to:

package/docs/guides/agent-integration.md

@@ -0,0 +1,87 @@
+# 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 /version` and assert the minimum compatible Omnius package
+   version.
+2. Read `GET /v1/discovery` or the bundled `docs/DISCOVERY.json`.
+3. Search by user intent, then expand the chosen stable ID.
+4. Follow the returned interface and reference links.
+5. For live work, send `X-Omnius-Min-Version` on execution requests.
+
+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` | 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`, `provider`, `tool`, `api`, `command`,
+`skill`, `guide`, `config`, and `operation`.
+
+## 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.

package/docs/guides/bring-your-own-inference.md

@@ -0,0 +1,126 @@
+# Bring Your Own Inference
+
+Omnius routes local and hosted models through an explicit provider descriptor.
+The descriptor determines the wire protocol, URL paths, authentication
+headers, and supported operations. It is the source of truth used by setup,
+model discovery, TUI runs, REST chat, summaries, voice, Telegram, sponsors,
+and endpoint probes.
+
+## Discover The Provider Contract
+
+```bash
+omnius discover "bring your own inference"
+omnius show provider.anthropic
+omnius show provider.gemini
+omnius discover "provider protocol" --kind provider
+```
+
+From the daemon:
+
+```bash
+curl -s "http://127.0.0.1:11435/v1/discovery?q=provider&kind=provider"
+curl -s "http://127.0.0.1:11435/v1/discovery/provider.anthropic"
+```
+
+## Protocol Matrix
+
+| Provider | Protocol | Canonical base | Authentication |
+| --- | --- | --- | --- |
+| Ollama | `ollama` | `http://127.0.0.1:11434` | none by default |
+| LM Studio, vLLM | `openai-chat` | local configured URL | optional Bearer |
+| OpenAI | `openai-chat` | `https://api.openai.com/v1` | Bearer |
+| Anthropic / Claude | `anthropic-messages` | `https://api.anthropic.com/v1` | `x-api-key` plus `anthropic-version` |
+| Google Gemini | `openai-chat` | `https://generativelanguage.googleapis.com/v1beta/openai` | Bearer plus Omnius client header |
+| OpenRouter, Groq, Chutes, DeepInfra, Together, Fireworks, Mistral, Cerebras, SambaNova, NVIDIA NIM, Hyperbolic | `openai-chat` | provider preset | Bearer |
+| Sponsor and COHERE peers | negotiated Omnius endpoint | discovered peer | peer/session policy |
+| Custom | explicitly selected | user supplied | configured for that endpoint |
+
+Known aliases include `claude` for Anthropic and `google` / `google-ai` for
+Gemini.
+
+## Anthropic Messages Translation
+
+Anthropic is not treated as an OpenAI-shaped URL. Omnius sends
+`POST /v1/messages` with `x-api-key`, `anthropic-version: 2023-06-01`, and
+JSON content type. The shared adapter translates:
+
+- the OpenAI-style system message into Anthropic's top-level `system`;
+- ordinary user and assistant messages into Messages content blocks;
+- tool definitions into Anthropic tool declarations;
+- assistant tool calls into `tool_use` blocks;
+- tool results into `tool_result` blocks;
+- Anthropic text, tool calls, streaming events, stop reasons, and usage back
+  into Omnius' common completion shape.
+
+This behavior follows Anthropic's
+[Messages API](https://platform.claude.com/docs/en/api/messages/create) and
+[authentication contract](https://platform.claude.com/docs/en/manage-claude/authentication).
+
+## Gemini OpenAI Compatibility
+
+Gemini uses Google's official OpenAI-compatible prefix:
+
+```text
+https://generativelanguage.googleapis.com/v1beta/openai
+```
+
+Omnius appends compatible resources such as `/models`,
+`/chat/completions`, and `/embeddings`, authenticates with
+`Authorization: Bearer <key>`, and identifies the client with
+`x-goog-api-client: omnius/<version>`. See Google's
+[OpenAI compatibility guide](https://ai.google.dev/gemini-api/docs/openai).
+
+The compatibility API is not a promise that every Gemini-native feature is
+available. Discover Omnius' advertised provider capabilities before depending
+on a provider-specific extension.
+
+## Key Resolution
+
+Omnius resolves upstream provider credentials in this exact order:
+
+```text
+OMNIUS_PROVIDER_API_KEY
+  → OMNIUS_MODEL_API_KEY
+  → OMNIUS_UPSTREAM_API_KEY
+  → OMNIUS_API_KEY
+  → VLLM_API_KEY
+  → persisted endpoint configuration
+```
+
+The first defined credential wins. REST bearer keys are a separate boundary:
+use `OMNIUS_REST_API_KEY` or `OMNIUS_REST_API_KEYS` for callers of the daemon.
+Never put either provider or REST credentials in URLs, logs, discovery data,
+or agent guidance files.
+
+## Fail-Closed Custom Endpoints
+
+Omnius may infer a protocol only for a registered provider or an unambiguous
+legacy configuration:
+
+- a known host selects its registered protocol;
+- a legacy `ollama` backend selects `ollama`;
+- a legacy `vllm` backend selects `openai-chat`;
+- a custom or ambiguous endpoint must declare its protocol explicitly.
+
+When the protocol is ambiguous, Omnius performs no model listing, health
+probe, embeddings request, chat request, or generated-token request. It keeps
+the saved endpoint disabled and returns an actionable configuration error.
+It never falls back to Ollama, CPU, a different provider, or a guessed
+OpenAI-compatible path.
+
+## Hardware Gate
+
+The repository's `AGENTS.md` requires a live hardware preflight before local
+inference. Confirm the designated endpoint, exact model tag, actual GPU
+placement with `nvidia-smi`, and absence of the test runner on an unintended
+device before generating tokens. If the endpoint-to-GPU mapping cannot be
+verified, stop instead of falling back.
+
+## Verify Without Generating Tokens
+
+Use discovery and configuration inspection first. Endpoint/model probes may
+contact a provider and therefore still require the correct protocol and
+credential. A local model-load probe must obey the hardware gate.
+
+For a service integration, also require the minimum Omnius version described
+in [Service Version Compatibility](../operations/version-compatibility.md).

package/docs/guides/tools-and-web-search.md

@@ -0,0 +1,95 @@
+# Tools And Web Search
+
+Omnius has two related tool surfaces:
+
+- the agent tool catalog offered to a model during an Omnius run; and
+- the daemon's direct-call registry exposed by `/v1/tools`.
+
+Discovering a tool does not imply that it is directly callable. Always inspect
+the tool metadata and its invocation interfaces.
+
+## Discover Before Calling
+
+```bash
+omnius discover "web search"
+omnius show tool.web-search
+omnius discover "tools API" --kind api
+```
+
+Daemon metadata:
+
+```bash
+curl -s http://127.0.0.1:11435/v1/tools
+curl -s http://127.0.0.1:11435/v1/tools/web_search
+```
+
+`GET /v1/tools/{name}` describes the schema, scope, risk, network behavior,
+and invocation mode. A tool is directly callable only when its returned
+metadata says `direct_callable: true`.
+
+## `web_search` Is Agent-Bound
+
+`web_search` is intentionally documented as agent-bound. Inspect its schema
+through discovery or `GET /v1/tools/web_search`, then execute it through an
+agent loop:
+
+```bash
+curl -s -X POST http://127.0.0.1:11435/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -H 'authorization: Bearer <run-key>' \
+  -H 'x-omnius-min-version: <required-version>' \
+  -d '{
+    "model": "<configured-model>",
+    "messages": [{"role":"user","content":"Find current primary sources for this claim."}],
+    "agent_loop": true,
+    "include_daemon_tools": ["read"],
+    "prompt_template": "factual-first"
+  }'
+```
+
+Equivalent agentic entrypoints are `POST /v1/chat` and `POST /v1/run`.
+`include_daemon_tools: ["read"]` offers read-scope tools such as
+`web_search`, `web_fetch`, and safe file inspection to the model.
+`prompt_template: "factual-first"` requests a search-first policy but does not
+expand auth scope or bypass the tool policy.
+
+Do not call `POST /v1/tools/web_search/call` unless the live metadata for the
+installed service explicitly marks it direct-callable. Catalog presence,
+read-scope classification, or a tool schema alone does not grant that
+invocation mode.
+
+## Direct Tools
+
+For a tool marked `direct_callable: true`, use:
+
+```bash
+curl -s -X POST http://127.0.0.1:11435/v1/tools/<name>/call \
+  -H 'content-type: application/json' \
+  -H 'authorization: Bearer <key>' \
+  -H 'x-omnius-min-version: <required-version>' \
+  -d '{"args":{}}'
+```
+
+The body wrapper is always `args`; the nested shape comes from the tool
+metadata. Direct calls are still gated by bearer scope, tool policy, profile,
+origin, network/off-device policy, and risk.
+
+## External And MCP Tools
+
+- `POST /v1/tools/register` registers an HTTP- or MCP-backed application tool.
+- `GET /v1/mcps` lists connected MCP servers.
+- `POST /v1/mcps/{name}/call` invokes a connected MCP tool through the daemon.
+- `tool_search` and `explore_tools` help an agent discover a large catalog
+  without loading every schema into its context.
+
+See [Tools, MCP, Hooks, Agents, And Code Graph](../rest/endpoints/tools.md) for
+the complete REST contract.
+
+## Failure Rules
+
+- Unknown tool: refresh discovery/metadata; do not retry the same name.
+- Tool not direct-callable: move the request to an agent loop.
+- `401` or `403`: fix bearer auth or scope; do not expose the key in output.
+- Version `412`: update the Omnius daemon before resubmitting work.
+- Provider/tool unavailable: report the prerequisite; do not silently
+  substitute another network service.

package/docs/index.md

@@ -2,11 +2,22 @@
 
 Omnius is an autonomous local-first agent runtime with a TUI, REST daemon, P2P sponsor mesh, Telegram bridge, realtime conversation mode, media generation routes, and AIWG-compatible documentation skills.
 
+## Discover Before Navigating
+
+- [Discovery Cascade](./DISCOVERY.md)
+- [Machine Discovery Catalog](./DISCOVERY.json)
+- [Agent And Service Integration](./guides/agent-integration.md)
+
+Agents should begin with `omnius discover "<need>"`, expand a result with
+`omnius show <id>`, and read only the referenced artifact needed for the
+current task.
+
 ## Start Here
 
 - [Install](./getting-started/install.md)
 - [First Run](./getting-started/first-run.md)
 - [Model Providers](./getting-started/model-providers.md)
+- [Bring Your Own Inference](./guides/bring-your-own-inference.md)
 - [Architecture](./architecture/overview.md)
 
 ## Workflows
@@ -16,18 +27,21 @@ Omnius is an autonomous local-first agent runtime with a TUI, REST daemon, P2P s
 - [Realtime Conversation](./guides/realtime.md)
 - [Telegram](./guides/telegram.md)
 - [Media Generation](./guides/media-generation.md)
+- [Tools And Web Search](./guides/tools-and-web-search.md)
 
 ## Reference
 
 - [REST API](./reference/rest-api.md)
 - [Slash Commands](./reference/slash-commands.md)
 - [Configuration](./reference/configuration.md)
+- [Authentication Map](./reference/auth-map.md)
 - [Agent Memory Index](./agent-memory/)
 
 ## Operations
 
 - [Security And Remote Access](./operations/security-and-remote-access.md)
 - [Runtime Hygiene](./operations/runtime-hygiene.md)
+- [Service Version Compatibility](./operations/version-compatibility.md)
 
 ## Proposals