omnius 1.0.605 → 1.0.607

package/dist/update-worker.js

@@ -216904,7 +216904,7 @@ var require_path_browserify = __commonJS({
       _makeLong: function _makeLong(path) {
         return path;
       },
-      dirname: function dirname10(path) {
+      dirname: function dirname11(path) {
         assertPath(path);
         if (path.length === 0) return ".";
         var code = path.charCodeAt(0);
@@ -245063,7 +245063,7 @@ import { join as join14 } from "node:path";
 import { homedir as homedir14 } from "node:os";
 import { createServer as createNetServer } from "node:net";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { dirname as dirname7 } from "node:path";
+import { dirname as dirname8 } from "node:path";
 
 // packages/execution/dist/index.js
 init_model_broker();
@@ -291263,11 +291263,16 @@ init_hf_media_models();
 
 // packages/execution/dist/tools/transcribe-tool.js
 init_model_broker();
-import { join as join4, basename, extname, resolve as resolve4 } from "node:path";
+import { join as join4, basename, dirname as dirname3, extname, resolve as resolve4 } from "node:path";
 import { homedir as homedir5, tmpdir as tmpdir2 } from "node:os";
 init_cuda_device_filter();
 init_process_async();
 init_venv_paths();
+
+// packages/execution/dist/transcribe-python-runtime.js
+init_process_async();
+
+// packages/execution/dist/tools/transcribe-tool.js
 var MAX_TRANSCRIBE_URL_BYTES = 100 * 1024 * 1024;
 var MANAGED_ASR_VENV = join4(homedir5(), ".omnius", "runtimes", "asr", ".venv-whisper");
 var MANAGED_TRANSCRIBE_CLI_DIR = join4(homedir5(), ".omnius", "runtimes", "asr", "transcribe-cli-node");
@@ -293014,7 +293019,7 @@ init_process_async();
 var MAX_IMAGE_BYTES = 8 * 1024 * 1024;
 
 // packages/execution/dist/tools/ocr-image-advanced.js
-import { resolve as resolve5, basename as basename2, dirname as dirname3, join as join5 } from "node:path";
+import { resolve as resolve5, basename as basename2, dirname as dirname4, join as join5 } from "node:path";
 init_system_deps();
 init_venv_paths();
 import { homedir as homedir6, tmpdir as tmpdir3 } from "node:os";
@@ -293023,10 +293028,10 @@ var OCR_VENV_DIR = join5(homedir6(), ".omnius", "venv");
 // packages/execution/dist/tools/browser-action.js
 init_process_lifecycle();
 import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2 } from "node:fs";
-import { basename as basename3, dirname as dirname4, join as join6, resolve as resolve6 } from "node:path";
+import { basename as basename3, dirname as dirname5, join as join6, resolve as resolve6 } from "node:path";
 import { fileURLToPath } from "node:url";
 init_model_store();
-var __dirname2 = dirname4(fileURLToPath(import.meta.url));
+var __dirname2 = dirname5(fileURLToPath(import.meta.url));
 var DEFAULT_PORT = 8130;
 function findScrapeScript() {
   const candidates = [
@@ -293377,7 +293382,7 @@ init_venv_paths();
 var YT_DLP_VENV2 = join10(homedir10(), ".omnius", "runtimes", "media-tools", ".venv-ytdlp");
 
 // packages/execution/dist/tools/video-scan.js
-import { resolve as resolve9, dirname as dirname5, join as join11, basename as basename6 } from "node:path";
+import { resolve as resolve9, dirname as dirname6, join as join11, basename as basename6 } from "node:path";
 import { homedir as homedir11 } from "node:os";
 var CONFIG_PATH = join11(homedir11(), ".omnius", "video-scan.json");
 
@@ -293391,7 +293396,7 @@ var LIVE_MEDIA_ROOT = join12(homedir12(), ".omnius", "runtimes", "live-media");
 var YOLO26_VENV = join12(LIVE_MEDIA_ROOT, ".venv-yolo26");
 
 // packages/execution/dist/tools/lance.js
-import { resolve as resolve11, dirname as dirname6, join as join13, basename as basename8 } from "node:path";
+import { resolve as resolve11, dirname as dirname7, join as join13, basename as basename8 } from "node:path";
 import { homedir as homedir13 } from "node:os";
 var CONFIG_PATH2 = join13(homedir13(), ".omnius", "lance.json");
 var RUN_TIMEOUT_MS = 30 * 60 * 1e3;
@@ -293874,7 +293879,7 @@ function commandForEntrypoint(path, nodeExe) {
 }
 async function resolveDaemonCommand(nodeExe) {
   const candidates = [];
-  const thisDir = dirname7(fileURLToPath2(import.meta.url));
+  const thisDir = dirname8(fileURLToPath2(import.meta.url));
   candidates.push(join14(thisDir, "index.js"));
   if (process.argv[1]) candidates.push(process.argv[1]);
   try {
@@ -293981,7 +293986,7 @@ import {
   writeSync as writeSync2
 } from "node:fs";
 import { homedir as homedir15 } from "node:os";
-import { dirname as dirname8, join as join15 } from "node:path";
+import { dirname as dirname9, join as join15 } from "node:path";
 
 // packages/cli/src/service-version.ts
 var OmniusVersionError = class extends Error {
@@ -294115,7 +294120,7 @@ function assertExactUpdateTarget(targetVersion, fromVersion) {
   return target;
 }
 function npmCandidates(execPath = process.execPath) {
-  const nodeDir = dirname8(execPath);
+  const nodeDir = dirname9(execPath);
   return process.platform === "win32" ? [join15(nodeDir, "npm.cmd"), join15(nodeDir, "npm.exe"), "npm.cmd", "npm"] : [join15(nodeDir, "npm"), "/usr/local/bin/npm", "/usr/bin/npm", "npm"];
 }
 function runnableCommand(candidate) {
@@ -294255,7 +294260,7 @@ async function runVerifiedUpdateTransaction(initial, dependencies, paths = resol
   const npmPath = resolveNpmPath();
   const env = {
     ...process.env,
-    PATH: [dirname8(process.execPath), process.env.PATH ?? ""].filter(Boolean).join(process.platform === "win32" ? ";" : ":"),
+    PATH: [dirname9(process.execPath), process.env.PATH ?? ""].filter(Boolean).join(process.platform === "win32" ? ";" : ":"),
     NPM_CONFIG_CACHE: paths.cacheDir,
     npm_config_cache: paths.cacheDir,
     npm_config_prefer_online: "true",
@@ -294349,7 +294354,7 @@ import {
   writeSync as writeSync3
 } from "node:fs";
 import { homedir as homedir16, tmpdir as tmpdir8 } from "node:os";
-import { basename as basename9, dirname as dirname9, join as join17 } from "node:path";
+import { basename as basename9, dirname as dirname10, join as join17 } from "node:path";
 
 // packages/cli/src/updater.ts
 import { join as join16 } from "node:path";

package/docs/DISCOVERY.json

@@ -5019,6 +5019,44 @@
         }
       ]
     },
+    {
+      "id": "api.v1-voice-asr",
+      "kind": "api",
+      "title": "/v1/voice/asr",
+      "summary": "Omnius REST API route /v1/voice/asr. Inspect the live OpenAPI document for methods and wire schemas.",
+      "aliases": [
+        "/v1/voice/asr"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "v1",
+        "voice",
+        "asr"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "/v1/voice/asr"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ]
+    },
     {
       "id": "api.v1-voice-asr-models",
       "kind": "api",
@@ -5446,6 +5484,44 @@
         }
       ]
     },
+    {
+      "id": "api.v1-voice-start",
+      "kind": "api",
+      "title": "/v1/voice/start",
+      "summary": "Omnius REST API route /v1/voice/start. Inspect the live OpenAPI document for methods and wire schemas.",
+      "aliases": [
+        "/v1/voice/start"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "v1",
+        "voice",
+        "start"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "/v1/voice/start"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ]
+    },
     {
       "id": "api.v1-voice-state",
       "kind": "api",
@@ -5484,6 +5560,44 @@
         }
       ]
     },
+    {
+      "id": "api.v1-voice-stop",
+      "kind": "api",
+      "title": "/v1/voice/stop",
+      "summary": "Omnius REST API route /v1/voice/stop. Inspect the live OpenAPI document for methods and wire schemas.",
+      "aliases": [
+        "/v1/voice/stop"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "v1",
+        "voice",
+        "stop"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "/v1/voice/stop"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ]
+    },
     {
       "id": "api.v1-voice-supertonic-settings",
       "kind": "api",

package/docs/DISCOVERY.md

@@ -153,6 +153,7 @@ Daemon equivalents are `GET /v1/discovery?q=<intent>` and `GET /v1/discovery/{id
 | `api.v1-update` | /v1/update | Omnius REST API route /v1/update. Inspect the live OpenAPI document for methods and wire schemas. |
 | `api.v1-usage` | /v1/usage | Omnius REST API route /v1/usage. Inspect the live OpenAPI document for methods and wire schemas. |
 | `api.v1-vision-describe` | /v1/vision/describe | Omnius REST API route /v1/vision/describe. Inspect the live OpenAPI document for methods and wire schemas. |
+| `api.v1-voice-asr` | /v1/voice/asr | Omnius REST API route /v1/voice/asr. Inspect the live OpenAPI document for methods and wire schemas. |
 | `api.v1-voice-asr-models` | /v1/voice/asr-models | Omnius REST API route /v1/voice/asr-models. Inspect the live OpenAPI document for methods and wire schemas. |
 | `api.v1-voice-asr-models-switch` | /v1/voice/asr-models/switch | Omnius REST API route /v1/voice/asr-models/switch. Inspect the live OpenAPI document for methods and wire schemas. |
 | `api.v1-voice-clone-refs` | /v1/voice/clone-refs | Omnius REST API route /v1/voice/clone-refs. Inspect the live OpenAPI document for methods and wire schemas. |
@@ -164,7 +165,9 @@ Daemon equivalents are `GET /v1/discovery?q=<intent>` and `GET /v1/discovery/{id
 | `api.v1-voice-models` | /v1/voice/models | Omnius REST API route /v1/voice/models. Inspect the live OpenAPI document for methods and wire schemas. |
 | `api.v1-voice-models-switch` | /v1/voice/models/switch | Omnius REST API route /v1/voice/models/switch. Inspect the live OpenAPI document for methods and wire schemas. |
 | `api.v1-voice-speak` | /v1/voice/speak | Omnius REST API route /v1/voice/speak. Inspect the live OpenAPI document for methods and wire schemas. |
+| `api.v1-voice-start` | /v1/voice/start | Omnius REST API route /v1/voice/start. Inspect the live OpenAPI document for methods and wire schemas. |
 | `api.v1-voice-state` | /v1/voice/state | Omnius REST API route /v1/voice/state. Inspect the live OpenAPI document for methods and wire schemas. |
+| `api.v1-voice-stop` | /v1/voice/stop | Omnius REST API route /v1/voice/stop. Inspect the live OpenAPI document for methods and wire schemas. |
 | `api.v1-voice-supertonic-settings` | /v1/voice/supertonic-settings | Omnius REST API route /v1/voice/supertonic-settings. Inspect the live OpenAPI document for methods and wire schemas. |
 | `api.v1-voice-transcribe` | /v1/voice/transcribe | Omnius REST API route /v1/voice/transcribe. Inspect the live OpenAPI document for methods and wire schemas. |
 | `api.v1-voice-transcribe-stream` | /v1/voice/transcribe/stream | Omnius REST API route /v1/voice/transcribe/stream. Inspect the live OpenAPI document for methods and wire schemas. |

package/docs/reference/rest-api.md

@@ -182,8 +182,10 @@ pnpm docs:check
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `GET` | `/v1/voice/state` | Voice runtime status |
+| `POST` | `/v1/voice/start` | Select an optional model, enable voice, and wait for readiness |
+| `POST` | `/v1/voice/stop` | Pause daemon voice input while leaving TTS warm |
 | `GET` | `/v1/voice/models` | TTS models |
-| `POST` | `/v1/voice/models/switch` | Switch TTS model |
+| `POST` | `/v1/voice/models/switch` | Switch and enable an exact TTS model by default |
 | `GET` | `/v1/voice/supertonic-settings` | Voice tuning settings |
 | `POST` | `/v1/voice/supertonic-settings` | Update voice tuning settings |
 | `GET` | `/v1/voice/asr-models` | ASR models |
@@ -204,6 +206,14 @@ pnpm docs:check
 | `GET` | `/v1/voicechat/ws` | WebSocket upgrade for full-duplex voicechat |
 | `POST` | `/v1/vision/describe` | Vision describe placeholder |
 
+`POST /v1/voice/tts` and `/v1/audio/speech` automatically warm the daemon.
+An explicit model must render exactly or the request fails; Omnius does not
+silently synthesize with another voice. Responses include `X-Voice-Model`,
+`X-Voice-Backend`, and `X-Sample-Rate`. Available models include GLaDOS,
+Overwatch, `luxtts:announcer-testchamber03`, and the selected Voicebox suite.
+Set `OMNIUS_VOICEBOX_MODELS=all` for every carried-in Voicebox model, leave it
+at `stable` for the default set, or provide a comma-separated subset.
+
 ## Generative Media
 
 All generation is backed by the unified `~/.omnius` model store and shared venvs (single source of truth — no per-project duplication). Generated files are consolidated into the global gallery at `~/.omnius/media/{images,videos,audio,music}`.

package/docs/reference/slash-commands.md

@@ -1381,7 +1381,7 @@ Toggle TTS voice feedback
 Signatures:
 
 - `/voice` - Toggle TTS voice feedback
-- `/voice <model>` - Set voice: glados, overwatch, kokoro, luxtts, misotts, supertonic
+- `/voice <model>` - Set and enable a voice: glados, overwatch, luxtts:announcer-testchamber03, kokoro, luxtts, misotts, supertonic, or a selected voicebox_* model
 - `/voice clone <file>` - Set voice clone reference audio (wav/mp3/ogg/flac)
 - `/voice clone glados` - Generate clone ref from GLaDOS for LuxTTS/MisoTTS voice cloning
 - `/voice clone overwatch` - Generate clone ref from Overwatch for LuxTTS/MisoTTS voice cloning

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "omnius",
-  "version": "1.0.605",
+  "version": "1.0.607",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omnius",
-      "version": "1.0.605",
+      "version": "1.0.607",
       "bundleDependencies": [
         "image-to-ascii"
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omnius",
-  "version": "1.0.605",
+  "version": "1.0.607",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/library.js",
@@ -161,5 +161,5 @@
     "transcribe-cli": "^2.0.1",
     "viem": "2.47.4"
   },
-  "readme": "# Omnius\n\nOmnius is a local-first agentic coding runtime: terminal UI, autonomous coding loop, REST daemon, model router, memory layer, media tools, Telegram bridge, and peer-to-peer inference mesh in one CLI.\n\nIt is designed for open-weight and user-controlled models first, while still routing cleanly through Ollama, vLLM, OpenAI-compatible endpoints, OpenRouter, Groq, Chutes, sponsor peers, COHERE peers, and other configured providers.\n\n[![npm](https://img.shields.io/npm/v/omnius.svg)](https://www.npmjs.com/package/omnius)\n[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/license-CC--BY--NC--4.0-blue.svg)](LICENSE)\n\n## Install\n\n```bash\nnpm install -g omnius\nomnius\n```\n\nRequirements:\n\n- Node.js 22 or newer\n- npm 10 or newer for published CLI use\n- pnpm 9 or newer for workspace development\n- A local model or configured remote endpoint\n\nStart the REST daemon:\n\n```bash\nomnius serve\n```\n\nThe daemon defaults to `http://127.0.0.1:11435`. Open the interactive API docs at `http://127.0.0.1:11435/docs`.\n\nRegister the native system tray indicator (Linux, macOS, and Windows x64):\n\n```bash\nomnius tray install\nomnius tray status\n```\n\nThe per-login indicator observes the daemon over loopback and provides health,\ndashboard, logs, and explicit daemon controls. See the\n[system tray guide](docs/guides/system-tray.md), including Ubuntu/GNOME setup.\n\n## Agent Discovery\n\nThe npm package ships its complete documentation and a machine-readable\ncapability catalog. An agent does not need to inspect Omnius source or guess\nwhich endpoint owns a capability:\n\n```bash\nomnius discover \"bring your own inference\"\nomnius show provider.anthropic\nomnius show provider.gemini\nomnius show tool.web-search\nomnius discover \"osint research\"\nomnius show capability.osint-research\nomnius capabilities --json\n```\n\nWith the daemon running, the same discovery cascade is available at\n`GET /v1/discovery`, with exact entry expansion at\n`GET /v1/discovery/{id}`. The live API contract remains available at\n`/openapi.json`, direct tool metadata at `/v1/tools`, and skills at\n`/v1/skills`.\n\nStart with [the discovery guide](docs/DISCOVERY.md) when integrating another\nagent or service. Use [bring-your-own inference](docs/guides/bring-your-own-inference.md)\nfor provider protocols and keys, and [tools and web search](docs/guides/tools-and-web-search.md)\nfor the distinction between direct tools and agent-bound tools. The\n[categorized OSINT research guide](docs/guides/osint-research.md) documents\nthe local discover → exact expansion → explicit web-tool workflow.\n\n## What Omnius Does\n\n- Runs autonomous coding tasks, edits files, executes tools, tests changes, and iterates on failures.\n- Provides a dense terminal UI for model selection, endpoint routing, task control, shell output, voice, sponsors, Telegram, and system telemetry.\n- Exposes a REST daemon with OpenAI/Ollama-compatible inference, agentic task execution, memory, skills, tools, MCP, events, voice, projects, and governance endpoints.\n- Routes models through local, cloud, sponsor, and peer-to-peer endpoints without assuming local Ollama is the only source.\n- Supports realtime spoken conversation for ASR/TTS clients through `/realtime` and REST `realtime: true`.\n- Supports image, video, sound, music, TTS, ASR, voice clone references, Telegram media workflows, and sponsor-provided media generation.\n- Keeps project runtime state in `.omnius/`, which is intentionally ignored by git.\n\n## Common Workflows\n\n```bash\nomnius \"inspect this repo and summarize the main entrypoints\"\nomnius serve\n```\n\n```text\n/help                 command help\n/model                select or inspect the active model\n/endpoint             select or configure local, cloud, sponsor, or peer endpoints\n/realtime             toggle short ASR/TTS-oriented conversation mode\n/broker               inspect model broker, RAM/VRAM thresholds, and loaded models\n/sponsor              expose local or upstream capacity to peers\n/cohere               participate in distributed COHERE inference\n/telegram             configure or toggle the Telegram bridge\n/skills               list explorable skills and docs memories\n/pause                pause after the current turn boundary\n/stop                 interrupt the active run\n/resume               resume saved state\n```\n\n## Current Feature Areas\n\n| Area | What to read |\n| --- | --- |\n| Install and setup | [Install](docs/getting-started/install.md), [First run](docs/getting-started/first-run.md), [Model providers](docs/getting-started/model-providers.md) |\n| Agent discovery | [Discovery cascade](docs/DISCOVERY.md), [machine catalog](docs/DISCOVERY.json), [agent integration](docs/guides/agent-integration.md) |\n| Bring your own inference | [Provider protocols and keys](docs/guides/bring-your-own-inference.md) |\n| Tools and web search | [Tool discovery and invocation](docs/guides/tools-and-web-search.md) |\n| Terminal workflows | [TUI workflows](docs/guides/tui-workflows.md), [Slash commands](docs/reference/slash-commands.md) |\n| REST daemon | [REST reference](docs/reference/rest-api.md), [REST quickref](docs/rest/QUICKREF.md), [OpenAPI source](docs/rest/openapi-source.md) |\n| System tray | [Cross-platform tray and Ubuntu setup](docs/guides/system-tray.md) |\n| Realtime voice chat | [Realtime guide](docs/guides/realtime.md) |\n| Sponsor and COHERE mesh | [Sponsor and COHERE guide](docs/guides/sponsor-and-cohere.md) |\n| Telegram bridge | [Telegram guide](docs/guides/telegram.md) |\n| Media generation | [Media guide](docs/guides/media-generation.md) |\n| Operations | [Runtime hygiene](docs/operations/runtime-hygiene.md), [Security and remote access](docs/operations/security-and-remote-access.md) |\n| Service compatibility | [Runtime version gate](docs/operations/version-compatibility.md) |\n| Architecture | [Architecture overview](docs/architecture/overview.md) |\n| Agent-explorable docs | [Agent memory docs index](docs/agent-memory/INDEX.md) |\n\n## Shared Media Dependencies\n\nImage, video, audio, and music generation share a **single, system-wide dependency store** instead of duplicating heavy runtimes per project or per Telegram group.\n\nEarlier builds wrote a private Python venv plus Hugging Face / Torch / pip caches under every scoped working directory (for example `…/telegram-creative/<group-id>/.omnius/image-gen/.venv`). On a busy machine the same multi-gigabyte diffusers stack and model weights were re-downloaded once per group — tens of gigabytes of pure duplication.\n\nEverything now resolves to one source of truth under `~/.omnius` (override with `OMNIUS_HOME`):\n\n| Location | Holds |\n| --- | --- |\n| `~/.omnius/runtimes/<kind>/.venv-<backend>` | One shared Python venv per kind+backend (image/video/audio) |\n| `~/.omnius/models/huggingface/{hub,transformers,diffusers}` | Shared model weights — downloaded once, reused everywhere |\n| `~/.omnius/models/{torch,cache,pip-cache}` | Shared Torch hub, XDG, and pip caches |\n| `~/.omnius/models/_meta.json` | LRU usage index for automatic disk-pressure eviction |\n| `~/.omnius/media/{images,videos,audio,music}` | Global generated-media gallery (project-independent) |\n\nProject directories keep only lightweight session artifacts; no venvs or model weights are written per project.\n\n**Migrate and dedup existing machines.** A one-time cleanup consolidates any legacy per-group caches into the unified store — unique weights are moved (never re-downloaded), duplicates and stale venvs are reclaimed:\n\n```bash\n# TUI — current project only\n/models cleanup\n# TUI — every project + nested scoped group on this machine (dry-run first)\n/models cleanup --all --dry-run\n/models cleanup --all\n```\n\n```bash\n# REST — preview, then apply\ncurl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{\"dryRun\":true}'\ncurl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{}'\n# Inspect store + reclaimable legacy caches\ncurl -s localhost:11435/v1/media/store\n```\n\n**Generate over REST.** The daemon (default `127.0.0.1:11435`, a port in the IANA dynamic/private range that avoids common system-service collisions) exposes the local generators so any user on the machine can list models, generate, and browse the global gallery without the CLI:\n\n```bash\ncurl -s localhost:11435/v1/media/models\ncurl -s -X POST localhost:11435/v1/media/image -H 'content-type: application/json' -d '{\"prompt\":\"a compact robot painter\"}'\ncurl -s -X POST localhost:11435/v1/media/music -H 'content-type: application/json' -d '{\"prompt\":\"warm lo-fi piano loop\"}'\ncurl -s localhost:11435/v1/media/gallery\n```\n\nThe same surface drives the **Generate** tab in the web UI (`http://127.0.0.1:11435`) — pick a kind (image/video/audio/music), choose a model loaded from the system, generate, and review every previously generated file in one global gallery.\n\n## Recent Highlights\n\n- `/realtime` and REST `realtime: true` provide short, natural, SOUL.md-aware conversation for ASR/TTS clients.\n- Endpoint setup and sponsor setup aggregate models from all enabled endpoints, including external OpenAI-compatible routers.\n- `/sponsor` can expose text inference and media generation for image, video, sound, and music with per-modality limits.\n- Sponsor and COHERE status surfaces now use shared telemetry concepts: concurrency, request rate, daily tokens, peer usage, model usage, and remote system metrics.\n- The TUI reports token production rate as `t/s`, supports Shift+Enter multiline input, and renders dynamic shell output inside bounded Unicode cards.\n- Telegram state is scoped by user and group, supports durable reply preferences, and feeds raw platform/tool failures back into the agent loop.\n- Ollama pool cleanup now accounts for process groups and orphan runner processes that can keep VRAM pinned.\n- REST documentation is available both as human docs and as Omnius-discoverable docs skills.\n\n## REST API\n\nStart the daemon (default `http://127.0.0.1:11435`; interactive docs at `/docs`, machine spec at `/openapi.json`):\n\n```bash\nomnius serve\n```\n\nFor shared deployments, gate access with scoped bearer keys (`read` < `run` < `admin`):\n\n```bash\nOMNIUS_REST_API_KEYS=\"read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops\" omnius serve\n# then: Authorization: Bearer <key>\n```\n\nThe complete endpoint inventory follows. It is kept in lockstep with the served OpenAPI spec by `pnpm docs:check`; the canonical machine contract is generated from [`packages/cli/src/api/openapi.ts`](packages/cli/src/api/openapi.ts) and mirrored in [`docs/reference/rest-api.md`](docs/reference/rest-api.md).\n\n### Docs and compatibility aliases\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/docs` · `/api/docs` · `/swagger-ui` | Swagger UI |\n| `GET` | `/openapi.json` · `/openapi.yaml` · `/v3/api-docs` · `/swagger.json` · `/api-docs` | OpenAPI spec (JSON/YAML + aliases) |\n| `GET` | `/redoc` | ReDoc renderer |\n\n### Health and observability\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/health` · `/health/ready` · `/health/startup` | Liveness, backend readiness, startup probes |\n| `GET` | `/version` | Package version and platform |\n| `GET` | `/metrics` | Prometheus metrics |\n| `GET` | `/v1/events` | Server-sent event stream |\n| `GET` | `/v1/usage` | Token usage and rate limits |\n| `GET` | `/v1/audit` | Audit log query |\n| `GET` | `/v1/cost` | Cost tracker |\n| `GET` | `/v1/system` | CPU, RAM, GPU, and system snapshot |\n\n### Discovery\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/discovery` | Search or list the bundled capability catalog |\n| `GET` | `/v1/discovery/{id}` | Expand one stable capability entry |\n\n### Inference and chat\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/models` · `/api/tags` | Aggregated model list (OpenAI + Ollama tags) |\n| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completion |\n| `POST` | `/v1/chat` | Stateful Omnius chat |\n| `POST` | `/api/chat` | Ollama-compatible chat alias |\n| `POST` | `/v1/generate` · `/api/generate` | One-shot generation (Ollama-compatible) |\n| `POST` | `/v1/embeddings` · `/api/embed` | Embeddings (OpenAI + Ollama aliases) |\n| `GET` | `/v1/chat/sessions` | Active chat sessions |\n| `POST` | `/v1/chat/check-in` | Steering check-in for active chat |\n\n### Agentic runs\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `POST` | `/v1/run` | Submit agentic task |\n| `GET` | `/v1/runs` · `/v1/runs/{id}` | List runs · get run details |\n| `DELETE` | `/v1/runs/{id}` | Abort run |\n| `POST`/`GET` | `/v1/todos` | Create/update · list sessions with todos |\n| `GET`/`DELETE` | `/v1/todos/{session_id}` | Get · delete session todos |\n| `POST` | `/v1/evaluate` | Evaluate a run |\n| `POST` | `/v1/index` | Trigger repository indexing |\n\n### Configuration, keys, profiles, projects\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET`/`PATCH` | `/v1/config` | Read · update daemon config |\n| `GET`/`PUT` | `/v1/config/model` | Current model · switch model |\n| `POST` | `/v1/config/model/check` | Probe model readiness |\n| `GET`/`PUT` | `/v1/config/endpoint` | Current endpoint · switch endpoint |\n| `POST` | `/v1/config/endpoint/test` | Probe endpoint |\n| `GET`/`DELETE` | `/v1/config/endpoint/history` | Endpoint history · remove item |\n| `POST` | `/v1/share/generate` | Generate remote-access share URL |\n| `GET`/`POST` | `/v1/keys` | List · mint runtime API keys |\n| `DELETE` | `/v1/keys/{prefix}` | Revoke runtime keys by prefix |\n| `GET`/`POST` | `/v1/profiles` | List · create tool profiles |\n| `GET`/`DELETE` | `/v1/profiles/{name}` | Get · delete profile |\n| `GET`/`DELETE` | `/v1/projects` | List · unregister projects |\n| `GET` | `/v1/projects/current` | Current project |\n| `POST` | `/v1/projects/switch` · `/v1/projects/register` · `/v1/projects/rename` | Switch · register · rename project |\n| `GET`/`PUT`/`DELETE` | `/v1/projects/preferences` | Read · patch · reset project preferences |\n\n### Skills, commands, tools, MCP\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/skills` · `/v1/skills/{name}` | List · load skill content |\n| `GET` | `/v1/commands` | List slash commands |\n| `POST` | `/v1/commands/{cmd}` | Execute slash command |\n| `GET` | `/v1/tools` · `/v1/tools/{name}` | List (built-in + external) · tool metadata |\n| `POST` | `/v1/tools/register` | Register an application-specific external tool |\n| `DELETE` | `/v1/tools/{name}` | Unregister an external tool |\n| `POST` | `/v1/tools/{name}/call` | Call tool |\n| `POST` | `/v1/tools/{name}/eval` | Evaluate an external tool against test cases |\n| `GET` | `/v1/mcps` · `/v1/mcps/{name}` | List · MCP server details |\n| `POST` | `/v1/mcps/{name}/call` | Call MCP tool |\n| `GET` | `/v1/hooks` · `/v1/agents` | Hook registry · agent type registry |\n| `GET` | `/v1/codegraph/snapshot` · `/v1/codegraph/events` | Code graph snapshot · SSE |\n\n### Registering application-specific tools\n\nAgents integrating Omnius into their own stack can register tools at runtime so the Omnius agent loop can call them alongside built-ins. Registration is a single unified contract — `transport.type` selects how Omnius reaches the implementation:\n\n- **`http`** — Omnius POSTs `{name, args, session_id}` to a `callback_url` your app hosts and relays the response.\n- **`mcp`** — the tool proxies to a named tool on an MCP server (auto-connected when you pass `connect`).\n\nRegistered tools are persisted per working directory (`.omnius/external-tools.json`), surface in `GET /v1/tools`, and respect the same scope/off-device security gate as built-ins. Registration needs `run` scope (remote callers need `admin`).\n\n```bash\n# Register an HTTP-backed tool\ncurl -s -X POST localhost:11435/v1/tools/register -H 'content-type: application/json' -d '{\n  \"name\": \"lookup_order\",\n  \"description\": \"Look up an order by id in the billing system\",\n  \"parameters\": {\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"}},\"required\":[\"id\"]},\n  \"security\": {\"requires_scope\":\"run\",\"risk\":\"low\"},\n  \"transport\": {\"type\":\"http\",\"callback_url\":\"https://app.internal/tools/lookup_order\",\"auth_header\":\"Bearer …\"}\n}'\n\n# It now appears in the registry and is directly callable\ncurl -s localhost:11435/v1/tools/lookup_order\ncurl -s -X POST localhost:11435/v1/tools/lookup_order/call -H 'content-type: application/json' -d '{\"args\":{\"id\":\"A-1001\"}}'\n\n# Evaluate it against cases during development (pass/fail + metrics)\ncurl -s -X POST localhost:11435/v1/tools/lookup_order/eval -H 'content-type: application/json' -d '{\n  \"cases\": [\n    {\"name\":\"known order\",\"args\":{\"id\":\"A-1001\"},\"expect\":{\"success\":true,\"output_contains\":\"A-1001\"}},\n    {\"name\":\"missing order\",\"args\":{\"id\":\"nope\"},\"expect\":{\"success\":false}}\n  ]\n}'\n\n# Unregister when done\ncurl -s -X DELETE localhost:11435/v1/tools/lookup_order\n```\n\nThe same registration accepts an MCP transport, e.g. `\"transport\":{\"type\":\"mcp\",\"server\":\"acme\",\"tool\":\"search\",\"connect\":{\"url\":\"https://app.internal/mcp\",\"transport\":\"streamable-http\"}}`.\n\n### AIWG\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/aiwg` | AIWG root and control map |\n| `GET` | `/v1/aiwg/frameworks` · `/v1/aiwg/frameworks/{name}` · `/v1/aiwg/frameworks/{name}/content` | List · details · tier-aware content |\n| `GET` | `/v1/aiwg/skills` · `/v1/aiwg/skills/{name}` | List · load AIWG skill |\n| `GET` | `/v1/aiwg/agents` · `/v1/aiwg/agents/{name}` | List · load AIWG agent |\n| `GET` | `/v1/aiwg/addons` | List AIWG addons |\n| `POST` | `/v1/aiwg/use` · `/v1/aiwg/expand` | Activation bundle · expand item |\n\n### Memory, sessions, context\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/memory` | Memory backend summary |\n| `POST` | `/v1/memory/search` · `/v1/memory/write` | Search · write memory |\n| `GET` | `/v1/memory/episodes` · `/v1/memory/failures` | List episodes · failures |\n| `GET` | `/v1/sessions` · `/v1/sessions/{id}` | List task sessions · get history |\n| `GET` | `/v1/context` | Current context snapshot |\n| `GET` | `/v1/context/window-dumps` · `/v1/context/window-dumps/{id}` | List/fetch full outbound model context-window dumps |\n| `POST` | `/v1/context/save` · `/v1/context/compact` | Save entry · request compaction |\n| `GET` | `/v1/context/restore` | Build restore prompt |\n\nContext-window dumps are written for main agents, sub-agents, internal runners, and adversary audits before backend inference. Use `GET /v1/context/window-dumps?agent_type=main` for summaries with signal/noise metrics, or `GET /v1/context/window-dumps/latest` for the full request payload. Dumps include focus-supervisor state when the runner is enforcing a next-action contract. Set `OMNIUS_CONTEXT_WINDOW_DUMP_DIR` to relocate dumps, `OMNIUS_DISABLE_CONTEXT_WINDOW_DUMPS=1` to disable them, or `OMNIUS_FOCUS_SUPERVISOR=off|auto|strict` to tune small-model focus enforcement.\n\n### Files, nexus, ollama pool\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/files` | List workspace directory |\n| `POST` | `/v1/files/read` | Read workspace file |\n| `GET` | `/v1/nexus/status` | Nexus peer state |\n| `GET` | `/v1/sponsors` | Sponsor directory cache |\n| `GET` | `/v1/ollama/pool/processes` | Ollama process inventory |\n| `POST` | `/v1/ollama/pool/cleanup` | Cleanup stale Ollama pool processes |\n\n### Voice, audio, vision\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/voice/state` | Voice runtime status |\n| `GET`/`POST` | `/v1/voice/models` · `/v1/voice/models/switch` | List · switch TTS model |\n| `GET`/`POST` | `/v1/voice/supertonic-settings` | Read · update voice tuning |\n| `GET`/`POST` | `/v1/voice/asr-models` · `/v1/voice/asr-models/switch` | List · switch ASR model |\n| `POST` | `/v1/voice/tts` · `/v1/audio/speech` | Synthesize speech (+ OpenAI alias) |\n| `POST` | `/v1/voice/transcribe` · `/v1/audio/transcriptions` · `/v1/voice/transcribe/stream` | Transcribe (+ alias + streaming) |\n| `GET`/`POST` | `/v1/voice/clone-refs` | List · upload clone reference |\n| `POST` | `/v1/voice/clone-refs/upload` · `/v1/voice/clone-refs/from-url` | Upload · fetch clone reference |\n| `POST` | `/v1/voice/clone-refs/{filename}/activate` · `/v1/voice/clone-refs/{filename}/rename` | Activate · rename clone reference |\n| `DELETE` | `/v1/voice/clone-refs/{filename}` | Delete clone reference |\n| `POST` | `/v1/voice/speak` | Broadcast speech to voicechat clients |\n| `GET` | `/v1/voicechat/ws` | WebSocket upgrade for full-duplex voicechat |\n| `POST` | `/v1/vision/describe` | Vision describe placeholder |\n\n### Generative media\n\nBacked by the unified `~/.omnius` store and shared venvs (see [Shared Media Dependencies](#shared-media-dependencies)). Outputs land in the global gallery at `~/.omnius/media/{images,videos,audio,music}`.\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/media/models` | List available image/video/audio/music models |\n| `GET` | `/v1/media/store` | Unified store disk usage + reclaimable legacy caches |\n| `POST` | `/v1/media/migrate` | Dedup + migrate legacy per-group caches into the unified store |\n| `POST` | `/v1/media/image` · `/v1/media/video` · `/v1/media/audio` · `/v1/media/music` | Generate media (run scope) |\n| `GET` | `/v1/media/gallery` | List previously generated media (global, newest first) |\n| `GET` | `/v1/media/file` | Stream one generated media file |\n\n### Engines and scheduled jobs\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/engines` | Long-running engine status |\n| `GET` | `/v1/scheduled` · `/v1/scheduled/all` · `/v1/scheduled/status` | List · list all · scheduler status |\n| `POST` | `/v1/scheduled/kill` · `/v1/scheduled/fixup` · `/v1/scheduled/reconcile` | Kill · reconcile · force reconcile |\n| `GET` | `/v1/services/systemd` | Systemd service status |\n| `GET` | `/v1/update` | Self-update status |\n\n### AIMS governance (ISO/IEC 42001:2023)\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/aims` | AIMS root and endpoint index |\n| `GET`/`PUT` | `/v1/aims/policies` | Policy register · replace |\n| `GET` | `/v1/aims/roles` · `/v1/aims/resources` | Roles · resource inventory |\n| `GET`/`POST` | `/v1/aims/impact-assessments` | List · file impact assessment |\n| `GET` | `/v1/aims/lifecycle` · `/v1/aims/data-quality` · `/v1/aims/transparency` · `/v1/aims/usage` · `/v1/aims/suppliers` | Lifecycle, data quality, transparency, usage, suppliers |\n| `GET`/`POST` | `/v1/aims/incidents` | List · file incident |\n| `GET` | `/v1/aims/oversight` · `/v1/aims/decisions` · `/v1/aims/config-history` | Oversight gates · decision log · config history |\n\nFor per-endpoint schemas, parameters, and response shapes, see the served `/openapi.json` and the maintained inventory in [`docs/reference/rest-api.md`](docs/reference/rest-api.md).\n\n## Agent-Explorable Documentation\n\nOmnius discovers project-local docs skills from `.aiwg/addons/*/skills`. The docs bundles in this repo expose high-signal entrypoints for agents:\n\n```text\n/skills omnius docs\nskill_execute name=\"omnius-docs\"\nskill_execute name=\"omnius-rest-docs\"\nskill_extract name=\"omnius-realtime-docs\" query=\"How does realtime REST mode work?\"\n```\n\nThe intended pattern is index first, targeted document second, not loading the whole manual into the active context.\n\n## Development\n\n```bash\npnpm install\npnpm -r build\npnpm docs:check\n```\n\nFocused checks used for the docs skill surface:\n\n```bash\npnpm --filter @omnius/execution exec vitest run tests/skill-discovery.test.ts\npnpm --filter omnius exec vitest run tests/realtime-mode.test.ts tests/command-registry.test.ts\n```\n\n## Publishing\n\nPublish only from `publish/`.\n\n```bash\ncd omnius\npnpm -r clean || true\nfind . -name 'tsconfig.tsbuildinfo' -not -path '*/node_modules/*' -delete\npnpm -r build\nnode scripts/build-publish.mjs\ncd publish\nmkdir -p .npm-cache\nNPM_CONFIG_CACHE=$(pwd)/.npm-cache npm pack --prefer-online --cache-min=0 --registry https://registry.npmjs.org/\nNPM_CONFIG_CACHE=$(pwd)/.npm-cache npm publish --access public --prefer-online --cache-min=0 --registry https://registry.npmjs.org/\n```\n\nBefore publishing, verify `README.md`, `package.json`, `dist/index.js`, and `dist/launcher.cjs` are in the tarball, and that `package.json` includes `readmeFilename: \"README.md\"` plus a string `readme`.\n\n## License\n\nOmnius is released under [CC-BY-NC-4.0](LICENSE) for non-commercial use. Commercial use, redistribution, hosted services, and enterprise deployment require a commercial license.\n"
+  "readme": "# Omnius\n\nOmnius is a local-first agentic coding runtime: terminal UI, autonomous coding loop, REST daemon, model router, memory layer, media tools, Telegram bridge, and peer-to-peer inference mesh in one CLI.\n\nIt is designed for open-weight and user-controlled models first, while still routing cleanly through Ollama, vLLM, OpenAI-compatible endpoints, OpenRouter, Groq, Chutes, sponsor peers, COHERE peers, and other configured providers.\n\n[![npm](https://img.shields.io/npm/v/omnius.svg)](https://www.npmjs.com/package/omnius)\n[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/license-CC--BY--NC--4.0-blue.svg)](LICENSE)\n\n## Install\n\n```bash\nnpm install -g omnius\nomnius\n```\n\nRequirements:\n\n- Node.js 22 or newer\n- npm 10 or newer for published CLI use\n- pnpm 9 or newer for workspace development\n- A local model or configured remote endpoint\n\nStart the REST daemon:\n\n```bash\nomnius serve\n```\n\nThe daemon defaults to `http://127.0.0.1:11435`. Open the interactive API docs at `http://127.0.0.1:11435/docs`.\n\nRegister the native system tray indicator (Linux, macOS, and Windows x64):\n\n```bash\nomnius tray install\nomnius tray status\n```\n\nThe per-login indicator observes the daemon over loopback and provides health,\ndashboard, logs, and explicit daemon controls. See the\n[system tray guide](docs/guides/system-tray.md), including Ubuntu/GNOME setup.\n\n## Agent Discovery\n\nThe npm package ships its complete documentation and a machine-readable\ncapability catalog. An agent does not need to inspect Omnius source or guess\nwhich endpoint owns a capability:\n\n```bash\nomnius discover \"bring your own inference\"\nomnius show provider.anthropic\nomnius show provider.gemini\nomnius show tool.web-search\nomnius discover \"osint research\"\nomnius show capability.osint-research\nomnius capabilities --json\n```\n\nWith the daemon running, the same discovery cascade is available at\n`GET /v1/discovery`, with exact entry expansion at\n`GET /v1/discovery/{id}`. The live API contract remains available at\n`/openapi.json`, direct tool metadata at `/v1/tools`, and skills at\n`/v1/skills`.\n\nStart with [the discovery guide](docs/DISCOVERY.md) when integrating another\nagent or service. Use [bring-your-own inference](docs/guides/bring-your-own-inference.md)\nfor provider protocols and keys, and [tools and web search](docs/guides/tools-and-web-search.md)\nfor the distinction between direct tools and agent-bound tools. The\n[categorized OSINT research guide](docs/guides/osint-research.md) documents\nthe local discover → exact expansion → explicit web-tool workflow.\n\n## What Omnius Does\n\n- Runs autonomous coding tasks, edits files, executes tools, tests changes, and iterates on failures.\n- Provides a dense terminal UI for model selection, endpoint routing, task control, shell output, voice, sponsors, Telegram, and system telemetry.\n- Exposes a REST daemon with OpenAI/Ollama-compatible inference, agentic task execution, memory, skills, tools, MCP, events, voice, projects, and governance endpoints.\n- Routes models through local, cloud, sponsor, and peer-to-peer endpoints without assuming local Ollama is the only source.\n- Supports realtime spoken conversation for ASR/TTS clients through `/realtime` and REST `realtime: true`.\n- Supports image, video, sound, music, TTS, ASR, voice clone references, Telegram media workflows, and sponsor-provided media generation.\n- Keeps project runtime state in `.omnius/`, which is intentionally ignored by git.\n\n## Common Workflows\n\n```bash\nomnius \"inspect this repo and summarize the main entrypoints\"\nomnius serve\n```\n\n```text\n/help                 command help\n/model                select or inspect the active model\n/endpoint             select or configure local, cloud, sponsor, or peer endpoints\n/realtime             toggle short ASR/TTS-oriented conversation mode\n/broker               inspect model broker, RAM/VRAM thresholds, and loaded models\n/sponsor              expose local or upstream capacity to peers\n/cohere               participate in distributed COHERE inference\n/telegram             configure or toggle the Telegram bridge\n/skills               list explorable skills and docs memories\n/pause                pause after the current turn boundary\n/stop                 interrupt the active run\n/resume               resume saved state\n```\n\n## Current Feature Areas\n\n| Area | What to read |\n| --- | --- |\n| Install and setup | [Install](docs/getting-started/install.md), [First run](docs/getting-started/first-run.md), [Model providers](docs/getting-started/model-providers.md) |\n| Agent discovery | [Discovery cascade](docs/DISCOVERY.md), [machine catalog](docs/DISCOVERY.json), [agent integration](docs/guides/agent-integration.md) |\n| Bring your own inference | [Provider protocols and keys](docs/guides/bring-your-own-inference.md) |\n| Tools and web search | [Tool discovery and invocation](docs/guides/tools-and-web-search.md) |\n| Terminal workflows | [TUI workflows](docs/guides/tui-workflows.md), [Slash commands](docs/reference/slash-commands.md) |\n| REST daemon | [REST reference](docs/reference/rest-api.md), [REST quickref](docs/rest/QUICKREF.md), [OpenAPI source](docs/rest/openapi-source.md) |\n| System tray | [Cross-platform tray and Ubuntu setup](docs/guides/system-tray.md) |\n| Realtime voice chat | [Realtime guide](docs/guides/realtime.md) |\n| Sponsor and COHERE mesh | [Sponsor and COHERE guide](docs/guides/sponsor-and-cohere.md) |\n| Telegram bridge | [Telegram guide](docs/guides/telegram.md) |\n| Media generation | [Media guide](docs/guides/media-generation.md) |\n| Operations | [Runtime hygiene](docs/operations/runtime-hygiene.md), [Security and remote access](docs/operations/security-and-remote-access.md) |\n| Service compatibility | [Runtime version gate](docs/operations/version-compatibility.md) |\n| Architecture | [Architecture overview](docs/architecture/overview.md) |\n| Agent-explorable docs | [Agent memory docs index](docs/agent-memory/INDEX.md) |\n\n## Shared Media Dependencies\n\nImage, video, audio, and music generation share a **single, system-wide dependency store** instead of duplicating heavy runtimes per project or per Telegram group.\n\nEarlier builds wrote a private Python venv plus Hugging Face / Torch / pip caches under every scoped working directory (for example `…/telegram-creative/<group-id>/.omnius/image-gen/.venv`). On a busy machine the same multi-gigabyte diffusers stack and model weights were re-downloaded once per group — tens of gigabytes of pure duplication.\n\nEverything now resolves to one source of truth under `~/.omnius` (override with `OMNIUS_HOME`):\n\n| Location | Holds |\n| --- | --- |\n| `~/.omnius/runtimes/<kind>/.venv-<backend>` | One shared Python venv per kind+backend (image/video/audio) |\n| `~/.omnius/models/huggingface/{hub,transformers,diffusers}` | Shared model weights — downloaded once, reused everywhere |\n| `~/.omnius/models/{torch,cache,pip-cache}` | Shared Torch hub, XDG, and pip caches |\n| `~/.omnius/models/_meta.json` | LRU usage index for automatic disk-pressure eviction |\n| `~/.omnius/media/{images,videos,audio,music}` | Global generated-media gallery (project-independent) |\n\nProject directories keep only lightweight session artifacts; no venvs or model weights are written per project.\n\n**Migrate and dedup existing machines.** A one-time cleanup consolidates any legacy per-group caches into the unified store — unique weights are moved (never re-downloaded), duplicates and stale venvs are reclaimed:\n\n```bash\n# TUI — current project only\n/models cleanup\n# TUI — every project + nested scoped group on this machine (dry-run first)\n/models cleanup --all --dry-run\n/models cleanup --all\n```\n\n```bash\n# REST — preview, then apply\ncurl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{\"dryRun\":true}'\ncurl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{}'\n# Inspect store + reclaimable legacy caches\ncurl -s localhost:11435/v1/media/store\n```\n\n**Generate over REST.** The daemon (default `127.0.0.1:11435`, a port in the IANA dynamic/private range that avoids common system-service collisions) exposes the local generators so any user on the machine can list models, generate, and browse the global gallery without the CLI:\n\n```bash\ncurl -s localhost:11435/v1/media/models\ncurl -s -X POST localhost:11435/v1/media/image -H 'content-type: application/json' -d '{\"prompt\":\"a compact robot painter\"}'\ncurl -s -X POST localhost:11435/v1/media/music -H 'content-type: application/json' -d '{\"prompt\":\"warm lo-fi piano loop\"}'\ncurl -s localhost:11435/v1/media/gallery\n```\n\nThe same surface drives the **Generate** tab in the web UI (`http://127.0.0.1:11435`) — pick a kind (image/video/audio/music), choose a model loaded from the system, generate, and review every previously generated file in one global gallery.\n\n## Recent Highlights\n\n- `/realtime` and REST `realtime: true` provide short, natural, SOUL.md-aware conversation for ASR/TTS clients.\n- Endpoint setup and sponsor setup aggregate models from all enabled endpoints, including external OpenAI-compatible routers.\n- `/sponsor` can expose text inference and media generation for image, video, sound, and music with per-modality limits.\n- Sponsor and COHERE status surfaces now use shared telemetry concepts: concurrency, request rate, daily tokens, peer usage, model usage, and remote system metrics.\n- The TUI reports token production rate as `t/s`, supports Shift+Enter multiline input, and renders dynamic shell output inside bounded Unicode cards.\n- Telegram state is scoped by user and group, supports durable reply preferences, and feeds raw platform/tool failures back into the agent loop.\n- Ollama pool cleanup now accounts for process groups and orphan runner processes that can keep VRAM pinned.\n- REST documentation is available both as human docs and as Omnius-discoverable docs skills.\n\n## REST API\n\nStart the daemon (default `http://127.0.0.1:11435`; interactive docs at `/docs`, machine spec at `/openapi.json`):\n\n```bash\nomnius serve\n```\n\nFor shared deployments, gate access with scoped bearer keys (`read` < `run` < `admin`):\n\n```bash\nOMNIUS_REST_API_KEYS=\"read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops\" omnius serve\n# then: Authorization: Bearer <key>\n```\n\nThe complete endpoint inventory follows. It is kept in lockstep with the served OpenAPI spec by `pnpm docs:check`; the canonical machine contract is generated from [`packages/cli/src/api/openapi.ts`](packages/cli/src/api/openapi.ts) and mirrored in [`docs/reference/rest-api.md`](docs/reference/rest-api.md).\n\n### Docs and compatibility aliases\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/docs` · `/api/docs` · `/swagger-ui` | Swagger UI |\n| `GET` | `/openapi.json` · `/openapi.yaml` · `/v3/api-docs` · `/swagger.json` · `/api-docs` | OpenAPI spec (JSON/YAML + aliases) |\n| `GET` | `/redoc` | ReDoc renderer |\n\n### Health and observability\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/health` · `/health/ready` · `/health/startup` | Liveness, backend readiness, startup probes |\n| `GET` | `/version` | Package version and platform |\n| `GET` | `/metrics` | Prometheus metrics |\n| `GET` | `/v1/events` | Server-sent event stream |\n| `GET` | `/v1/usage` | Token usage and rate limits |\n| `GET` | `/v1/audit` | Audit log query |\n| `GET` | `/v1/cost` | Cost tracker |\n| `GET` | `/v1/system` | CPU, RAM, GPU, and system snapshot |\n\n### Discovery\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/discovery` | Search or list the bundled capability catalog |\n| `GET` | `/v1/discovery/{id}` | Expand one stable capability entry |\n\n### Inference and chat\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/models` · `/api/tags` | Aggregated model list (OpenAI + Ollama tags) |\n| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completion |\n| `POST` | `/v1/chat` | Stateful Omnius chat |\n| `POST` | `/api/chat` | Ollama-compatible chat alias |\n| `POST` | `/v1/generate` · `/api/generate` | One-shot generation (Ollama-compatible) |\n| `POST` | `/v1/embeddings` · `/api/embed` | Embeddings (OpenAI + Ollama aliases) |\n| `GET` | `/v1/chat/sessions` | Active chat sessions |\n| `POST` | `/v1/chat/check-in` | Steering check-in for active chat |\n\n### Agentic runs\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `POST` | `/v1/run` | Submit agentic task |\n| `GET` | `/v1/runs` · `/v1/runs/{id}` | List runs · get run details |\n| `DELETE` | `/v1/runs/{id}` | Abort run |\n| `POST`/`GET` | `/v1/todos` | Create/update · list sessions with todos |\n| `GET`/`DELETE` | `/v1/todos/{session_id}` | Get · delete session todos |\n| `POST` | `/v1/evaluate` | Evaluate a run |\n| `POST` | `/v1/index` | Trigger repository indexing |\n\n### Configuration, keys, profiles, projects\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET`/`PATCH` | `/v1/config` | Read · update daemon config |\n| `GET`/`PUT` | `/v1/config/model` | Current model · switch model |\n| `POST` | `/v1/config/model/check` | Probe model readiness |\n| `GET`/`PUT` | `/v1/config/endpoint` | Current endpoint · switch endpoint |\n| `POST` | `/v1/config/endpoint/test` | Probe endpoint |\n| `GET`/`DELETE` | `/v1/config/endpoint/history` | Endpoint history · remove item |\n| `POST` | `/v1/share/generate` | Generate remote-access share URL |\n| `GET`/`POST` | `/v1/keys` | List · mint runtime API keys |\n| `DELETE` | `/v1/keys/{prefix}` | Revoke runtime keys by prefix |\n| `GET`/`POST` | `/v1/profiles` | List · create tool profiles |\n| `GET`/`DELETE` | `/v1/profiles/{name}` | Get · delete profile |\n| `GET`/`DELETE` | `/v1/projects` | List · unregister projects |\n| `GET` | `/v1/projects/current` | Current project |\n| `POST` | `/v1/projects/switch` · `/v1/projects/register` · `/v1/projects/rename` | Switch · register · rename project |\n| `GET`/`PUT`/`DELETE` | `/v1/projects/preferences` | Read · patch · reset project preferences |\n\n### Skills, commands, tools, MCP\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/skills` · `/v1/skills/{name}` | List · load skill content |\n| `GET` | `/v1/commands` | List slash commands |\n| `POST` | `/v1/commands/{cmd}` | Execute slash command |\n| `GET` | `/v1/tools` · `/v1/tools/{name}` | List (built-in + external) · tool metadata |\n| `POST` | `/v1/tools/register` | Register an application-specific external tool |\n| `DELETE` | `/v1/tools/{name}` | Unregister an external tool |\n| `POST` | `/v1/tools/{name}/call` | Call tool |\n| `POST` | `/v1/tools/{name}/eval` | Evaluate an external tool against test cases |\n| `GET` | `/v1/mcps` · `/v1/mcps/{name}` | List · MCP server details |\n| `POST` | `/v1/mcps/{name}/call` | Call MCP tool |\n| `GET` | `/v1/hooks` · `/v1/agents` | Hook registry · agent type registry |\n| `GET` | `/v1/codegraph/snapshot` · `/v1/codegraph/events` | Code graph snapshot · SSE |\n\n### Registering application-specific tools\n\nAgents integrating Omnius into their own stack can register tools at runtime so the Omnius agent loop can call them alongside built-ins. Registration is a single unified contract — `transport.type` selects how Omnius reaches the implementation:\n\n- **`http`** — Omnius POSTs `{name, args, session_id}` to a `callback_url` your app hosts and relays the response.\n- **`mcp`** — the tool proxies to a named tool on an MCP server (auto-connected when you pass `connect`).\n\nRegistered tools are persisted per working directory (`.omnius/external-tools.json`), surface in `GET /v1/tools`, and respect the same scope/off-device security gate as built-ins. Registration needs `run` scope (remote callers need `admin`).\n\n```bash\n# Register an HTTP-backed tool\ncurl -s -X POST localhost:11435/v1/tools/register -H 'content-type: application/json' -d '{\n  \"name\": \"lookup_order\",\n  \"description\": \"Look up an order by id in the billing system\",\n  \"parameters\": {\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"}},\"required\":[\"id\"]},\n  \"security\": {\"requires_scope\":\"run\",\"risk\":\"low\"},\n  \"transport\": {\"type\":\"http\",\"callback_url\":\"https://app.internal/tools/lookup_order\",\"auth_header\":\"Bearer …\"}\n}'\n\n# It now appears in the registry and is directly callable\ncurl -s localhost:11435/v1/tools/lookup_order\ncurl -s -X POST localhost:11435/v1/tools/lookup_order/call -H 'content-type: application/json' -d '{\"args\":{\"id\":\"A-1001\"}}'\n\n# Evaluate it against cases during development (pass/fail + metrics)\ncurl -s -X POST localhost:11435/v1/tools/lookup_order/eval -H 'content-type: application/json' -d '{\n  \"cases\": [\n    {\"name\":\"known order\",\"args\":{\"id\":\"A-1001\"},\"expect\":{\"success\":true,\"output_contains\":\"A-1001\"}},\n    {\"name\":\"missing order\",\"args\":{\"id\":\"nope\"},\"expect\":{\"success\":false}}\n  ]\n}'\n\n# Unregister when done\ncurl -s -X DELETE localhost:11435/v1/tools/lookup_order\n```\n\nThe same registration accepts an MCP transport, e.g. `\"transport\":{\"type\":\"mcp\",\"server\":\"acme\",\"tool\":\"search\",\"connect\":{\"url\":\"https://app.internal/mcp\",\"transport\":\"streamable-http\"}}`.\n\n### AIWG\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/aiwg` | AIWG root and control map |\n| `GET` | `/v1/aiwg/frameworks` · `/v1/aiwg/frameworks/{name}` · `/v1/aiwg/frameworks/{name}/content` | List · details · tier-aware content |\n| `GET` | `/v1/aiwg/skills` · `/v1/aiwg/skills/{name}` | List · load AIWG skill |\n| `GET` | `/v1/aiwg/agents` · `/v1/aiwg/agents/{name}` | List · load AIWG agent |\n| `GET` | `/v1/aiwg/addons` | List AIWG addons |\n| `POST` | `/v1/aiwg/use` · `/v1/aiwg/expand` | Activation bundle · expand item |\n\n### Memory, sessions, context\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/memory` | Memory backend summary |\n| `POST` | `/v1/memory/search` · `/v1/memory/write` | Search · write memory |\n| `GET` | `/v1/memory/episodes` · `/v1/memory/failures` | List episodes · failures |\n| `GET` | `/v1/sessions` · `/v1/sessions/{id}` | List task sessions · get history |\n| `GET` | `/v1/context` | Current context snapshot |\n| `GET` | `/v1/context/window-dumps` · `/v1/context/window-dumps/{id}` | List/fetch full outbound model context-window dumps |\n| `POST` | `/v1/context/save` · `/v1/context/compact` | Save entry · request compaction |\n| `GET` | `/v1/context/restore` | Build restore prompt |\n\nContext-window dumps are written for main agents, sub-agents, internal runners, and adversary audits before backend inference. Use `GET /v1/context/window-dumps?agent_type=main` for summaries with signal/noise metrics, or `GET /v1/context/window-dumps/latest` for the full request payload. Dumps include focus-supervisor state when the runner is enforcing a next-action contract. Set `OMNIUS_CONTEXT_WINDOW_DUMP_DIR` to relocate dumps, `OMNIUS_DISABLE_CONTEXT_WINDOW_DUMPS=1` to disable them, or `OMNIUS_FOCUS_SUPERVISOR=off|auto|strict` to tune small-model focus enforcement.\n\n### Files, nexus, ollama pool\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/files` | List workspace directory |\n| `POST` | `/v1/files/read` | Read workspace file |\n| `GET` | `/v1/nexus/status` | Nexus peer state |\n| `GET` | `/v1/sponsors` | Sponsor directory cache |\n| `GET` | `/v1/ollama/pool/processes` | Ollama process inventory |\n| `POST` | `/v1/ollama/pool/cleanup` | Cleanup stale Ollama pool processes |\n\n### Voice, audio, vision\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/voice/state` | Voice runtime status |\n| `POST` | `/v1/voice/start` · `/v1/voice/stop` | Enable/warm voice · pause voice input |\n| `GET`/`POST` | `/v1/voice/models` · `/v1/voice/models/switch` | List · switch and enable an exact TTS model |\n| `GET`/`POST` | `/v1/voice/supertonic-settings` | Read · update voice tuning |\n| `GET`/`POST` | `/v1/voice/asr-models` · `/v1/voice/asr-models/switch` | List · switch ASR model |\n| `POST` | `/v1/voice/tts` · `/v1/audio/speech` | Synthesize speech (+ OpenAI alias) |\n| `POST` | `/v1/voice/transcribe` · `/v1/audio/transcriptions` · `/v1/voice/transcribe/stream` | Transcribe (+ alias + streaming) |\n| `GET`/`POST` | `/v1/voice/clone-refs` | List · upload clone reference |\n| `POST` | `/v1/voice/clone-refs/upload` · `/v1/voice/clone-refs/from-url` | Upload · fetch clone reference |\n| `POST` | `/v1/voice/clone-refs/{filename}/activate` · `/v1/voice/clone-refs/{filename}/rename` | Activate · rename clone reference |\n| `DELETE` | `/v1/voice/clone-refs/{filename}` | Delete clone reference |\n| `POST` | `/v1/voice/speak` | Broadcast speech to voicechat clients |\n| `GET` | `/v1/voicechat/ws` | WebSocket upgrade for full-duplex voicechat |\n| `POST` | `/v1/vision/describe` | Vision describe placeholder |\n\nTTS requests auto-warm the daemon and never silently fall back to a different\nvoice. The built-in registry includes GLaDOS, Overwatch, and the packaged\n`luxtts:announcer-testchamber03` clone source. Voicebox defaults to its stable\nsub-model set; use `OMNIUS_VOICEBOX_MODELS=all` for the full suite or a\ncomma-separated list of `voicebox_*` IDs for an explicit subset.\n\n### Generative media\n\nBacked by the unified `~/.omnius` store and shared venvs (see [Shared Media Dependencies](#shared-media-dependencies)). Outputs land in the global gallery at `~/.omnius/media/{images,videos,audio,music}`.\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/media/models` | List available image/video/audio/music models |\n| `GET` | `/v1/media/store` | Unified store disk usage + reclaimable legacy caches |\n| `POST` | `/v1/media/migrate` | Dedup + migrate legacy per-group caches into the unified store |\n| `POST` | `/v1/media/image` · `/v1/media/video` · `/v1/media/audio` · `/v1/media/music` | Generate media (run scope) |\n| `GET` | `/v1/media/gallery` | List previously generated media (global, newest first) |\n| `GET` | `/v1/media/file` | Stream one generated media file |\n\n### Engines and scheduled jobs\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/engines` | Long-running engine status |\n| `GET` | `/v1/scheduled` · `/v1/scheduled/all` · `/v1/scheduled/status` | List · list all · scheduler status |\n| `POST` | `/v1/scheduled/kill` · `/v1/scheduled/fixup` · `/v1/scheduled/reconcile` | Kill · reconcile · force reconcile |\n| `GET` | `/v1/services/systemd` | Systemd service status |\n| `GET` | `/v1/update` | Self-update status |\n\n### AIMS governance (ISO/IEC 42001:2023)\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/aims` | AIMS root and endpoint index |\n| `GET`/`PUT` | `/v1/aims/policies` | Policy register · replace |\n| `GET` | `/v1/aims/roles` · `/v1/aims/resources` | Roles · resource inventory |\n| `GET`/`POST` | `/v1/aims/impact-assessments` | List · file impact assessment |\n| `GET` | `/v1/aims/lifecycle` · `/v1/aims/data-quality` · `/v1/aims/transparency` · `/v1/aims/usage` · `/v1/aims/suppliers` | Lifecycle, data quality, transparency, usage, suppliers |\n| `GET`/`POST` | `/v1/aims/incidents` | List · file incident |\n| `GET` | `/v1/aims/oversight` · `/v1/aims/decisions` · `/v1/aims/config-history` | Oversight gates · decision log · config history |\n\nFor per-endpoint schemas, parameters, and response shapes, see the served `/openapi.json` and the maintained inventory in [`docs/reference/rest-api.md`](docs/reference/rest-api.md).\n\n## Agent-Explorable Documentation\n\nOmnius discovers project-local docs skills from `.aiwg/addons/*/skills`. The docs bundles in this repo expose high-signal entrypoints for agents:\n\n```text\n/skills omnius docs\nskill_execute name=\"omnius-docs\"\nskill_execute name=\"omnius-rest-docs\"\nskill_extract name=\"omnius-realtime-docs\" query=\"How does realtime REST mode work?\"\n```\n\nThe intended pattern is index first, targeted document second, not loading the whole manual into the active context.\n\n## Development\n\n```bash\npnpm install\npnpm -r build\npnpm docs:check\n```\n\nFocused checks used for the docs skill surface:\n\n```bash\npnpm --filter @omnius/execution exec vitest run tests/skill-discovery.test.ts\npnpm --filter omnius exec vitest run tests/realtime-mode.test.ts tests/command-registry.test.ts\n```\n\n## Publishing\n\nPublish only from `publish/`.\n\n```bash\ncd omnius\npnpm -r clean || true\nfind . -name 'tsconfig.tsbuildinfo' -not -path '*/node_modules/*' -delete\npnpm -r build\nnode scripts/build-publish.mjs\ncd publish\nmkdir -p .npm-cache\nNPM_CONFIG_CACHE=$(pwd)/.npm-cache npm pack --prefer-online --cache-min=0 --registry https://registry.npmjs.org/\nNPM_CONFIG_CACHE=$(pwd)/.npm-cache npm publish --access public --prefer-online --cache-min=0 --registry https://registry.npmjs.org/\n```\n\nBefore publishing, verify `README.md`, `package.json`, `dist/index.js`, and `dist/launcher.cjs` are in the tarball, and that `package.json` includes `readmeFilename: \"README.md\"` plus a string `readme`.\n\n## License\n\nOmnius is released under [CC-BY-NC-4.0](LICENSE) for non-commercial use. Commercial use, redistribution, hosted services, and enterprise deployment require a commercial license.\n"
 }