omnius 1.0.322 → 1.0.323

package/README.md

@@ -77,6 +77,53 @@ omnius serve
 | Architecture | [Architecture overview](docs/architecture/overview.md) |
 | Agent-explorable docs | [Agent memory docs index](docs/agent-memory/INDEX.md) |
 
+## Shared Media Dependencies
+
+Image, video, audio, and music generation share a **single, system-wide dependency store** instead of duplicating heavy runtimes per project or per Telegram group.
+
+Earlier 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.
+
+Everything now resolves to one source of truth under `~/.omnius` (override with `OMNIUS_HOME`):
+
+| Location | Holds |
+| --- | --- |
+| `~/.omnius/runtimes/<kind>/.venv-<backend>` | One shared Python venv per kind+backend (image/video/audio) |
+| `~/.omnius/models/huggingface/{hub,transformers,diffusers}` | Shared model weights — downloaded once, reused everywhere |
+| `~/.omnius/models/{torch,cache,pip-cache}` | Shared Torch hub, XDG, and pip caches |
+| `~/.omnius/models/_meta.json` | LRU usage index for automatic disk-pressure eviction |
+| `~/.omnius/media/{images,videos,audio,music}` | Global generated-media gallery (project-independent) |
+
+Project directories keep only lightweight session artifacts; no venvs or model weights are written per project.
+
+**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:
+
+```bash
+# TUI — current project only
+/models cleanup
+# TUI — every project + nested scoped group on this machine (dry-run first)
+/models cleanup --all --dry-run
+/models cleanup --all
+```
+
+```bash
+# REST — preview, then apply
+curl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{"dryRun":true}'
+curl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{}'
+# Inspect store + reclaimable legacy caches
+curl -s localhost:11435/v1/media/store
+```
+
+**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:
+
+```bash
+curl -s localhost:11435/v1/media/models
+curl -s -X POST localhost:11435/v1/media/image -H 'content-type: application/json' -d '{"prompt":"a compact robot painter"}'
+curl -s -X POST localhost:11435/v1/media/music -H 'content-type: application/json' -d '{"prompt":"warm lo-fi piano loop"}'
+curl -s localhost:11435/v1/media/gallery
+```
+
+The 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.
+
 ## Recent Highlights
 
 - `/realtime` and REST `realtime: true` provide short, natural, SOUL.md-aware conversation for ASR/TTS clients.
@@ -90,33 +137,189 @@ omnius serve
 
 ## REST API
 
-Start:
+Start the daemon (default `http://127.0.0.1:11435`; interactive docs at `/docs`, machine spec at `/openapi.json`):
 
 ```bash
 omnius serve
 ```
 
-Useful entrypoints:
-
-```text
-GET  /docs
-GET  /openapi.json
-POST /v1/chat
-POST /v1/chat/completions
-POST /v1/run
-GET  /v1/events
-GET  /v1/skills
-POST /v1/tools/{name}/call
-WS   /v1/voicechat/ws
-```
-
-For shared deployments, use bearer keys:
+For shared deployments, gate access with scoped bearer keys (`read` < `run` < `admin`):
 
 ```bash
 OMNIUS_REST_API_KEYS="read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops" omnius serve
+# then: Authorization: Bearer <key>
 ```
 
-See [docs/reference/rest-api.md](docs/reference/rest-api.md) for the maintained endpoint inventory. The canonical machine contract is generated from [packages/cli/src/api/openapi.ts](packages/cli/src/api/openapi.ts).
+The 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).
+
+### Docs and compatibility aliases
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/docs` · `/api/docs` · `/swagger-ui` | Swagger UI |
+| `GET` | `/openapi.json` · `/openapi.yaml` · `/v3/api-docs` · `/swagger.json` · `/api-docs` | OpenAPI spec (JSON/YAML + aliases) |
+| `GET` | `/redoc` | ReDoc renderer |
+
+### Health and observability
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/health` · `/health/ready` · `/health/startup` | Liveness, backend readiness, startup probes |
+| `GET` | `/version` | Package version and platform |
+| `GET` | `/metrics` | Prometheus metrics |
+| `GET` | `/v1/events` | Server-sent event stream |
+| `GET` | `/v1/usage` | Token usage and rate limits |
+| `GET` | `/v1/audit` | Audit log query |
+| `GET` | `/v1/cost` | Cost tracker |
+| `GET` | `/v1/system` | CPU, RAM, GPU, and system snapshot |
+
+### Inference and chat
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/models` · `/api/tags` | Aggregated model list (OpenAI + Ollama tags) |
+| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completion |
+| `POST` | `/v1/chat` | Stateful Omnius chat |
+| `POST` | `/api/chat` | Ollama-compatible chat alias |
+| `POST` | `/v1/generate` · `/api/generate` | One-shot generation (Ollama-compatible) |
+| `POST` | `/v1/embeddings` · `/api/embed` | Embeddings (OpenAI + Ollama aliases) |
+| `GET` | `/v1/chat/sessions` | Active chat sessions |
+| `POST` | `/v1/chat/check-in` | Steering check-in for active chat |
+
+### Agentic runs
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/v1/run` | Submit agentic task |
+| `GET` | `/v1/runs` · `/v1/runs/{id}` | List runs · get run details |
+| `DELETE` | `/v1/runs/{id}` | Abort run |
+| `POST`/`GET` | `/v1/todos` | Create/update · list sessions with todos |
+| `GET`/`DELETE` | `/v1/todos/{session_id}` | Get · delete session todos |
+| `POST` | `/v1/evaluate` | Evaluate a run |
+| `POST` | `/v1/index` | Trigger repository indexing |
+
+### Configuration, keys, profiles, projects
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET`/`PATCH` | `/v1/config` | Read · update daemon config |
+| `GET`/`PUT` | `/v1/config/model` | Current model · switch model |
+| `POST` | `/v1/config/model/check` | Probe model readiness |
+| `GET`/`PUT` | `/v1/config/endpoint` | Current endpoint · switch endpoint |
+| `POST` | `/v1/config/endpoint/test` | Probe endpoint |
+| `GET`/`DELETE` | `/v1/config/endpoint/history` | Endpoint history · remove item |
+| `POST` | `/v1/share/generate` | Generate remote-access share URL |
+| `GET`/`POST` | `/v1/keys` | List · mint runtime API keys |
+| `DELETE` | `/v1/keys/{prefix}` | Revoke runtime keys by prefix |
+| `GET`/`POST` | `/v1/profiles` | List · create tool profiles |
+| `GET`/`DELETE` | `/v1/profiles/{name}` | Get · delete profile |
+| `GET`/`DELETE` | `/v1/projects` | List · unregister projects |
+| `GET` | `/v1/projects/current` | Current project |
+| `POST` | `/v1/projects/switch` · `/v1/projects/register` · `/v1/projects/rename` | Switch · register · rename project |
+| `GET`/`PUT`/`DELETE` | `/v1/projects/preferences` | Read · patch · reset project preferences |
+
+### Skills, commands, tools, MCP
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/skills` · `/v1/skills/{name}` | List · load skill content |
+| `GET` | `/v1/commands` | List slash commands |
+| `POST` | `/v1/commands/{cmd}` | Execute slash command |
+| `GET` | `/v1/tools` · `/v1/tools/{name}` | List · tool metadata |
+| `POST` | `/v1/tools/{name}/call` | Call tool |
+| `GET` | `/v1/mcps` · `/v1/mcps/{name}` | List · MCP server details |
+| `POST` | `/v1/mcps/{name}/call` | Call MCP tool |
+| `GET` | `/v1/hooks` · `/v1/agents` | Hook registry · agent type registry |
+| `GET` | `/v1/codegraph/snapshot` · `/v1/codegraph/events` | Code graph snapshot · SSE |
+
+### AIWG
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/aiwg` | AIWG root and control map |
+| `GET` | `/v1/aiwg/frameworks` · `/v1/aiwg/frameworks/{name}` · `/v1/aiwg/frameworks/{name}/content` | List · details · tier-aware content |
+| `GET` | `/v1/aiwg/skills` · `/v1/aiwg/skills/{name}` | List · load AIWG skill |
+| `GET` | `/v1/aiwg/agents` · `/v1/aiwg/agents/{name}` | List · load AIWG agent |
+| `GET` | `/v1/aiwg/addons` | List AIWG addons |
+| `POST` | `/v1/aiwg/use` · `/v1/aiwg/expand` | Activation bundle · expand item |
+
+### Memory, sessions, context
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/memory` | Memory backend summary |
+| `POST` | `/v1/memory/search` · `/v1/memory/write` | Search · write memory |
+| `GET` | `/v1/memory/episodes` · `/v1/memory/failures` | List episodes · failures |
+| `GET` | `/v1/sessions` · `/v1/sessions/{id}` | List task sessions · get history |
+| `GET` | `/v1/context` | Current context snapshot |
+| `POST` | `/v1/context/save` · `/v1/context/compact` | Save entry · request compaction |
+| `GET` | `/v1/context/restore` | Build restore prompt |
+
+### Files, nexus, ollama pool
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/files` | List workspace directory |
+| `POST` | `/v1/files/read` | Read workspace file |
+| `GET` | `/v1/nexus/status` | Nexus peer state |
+| `GET` | `/v1/sponsors` | Sponsor directory cache |
+| `GET` | `/v1/ollama/pool/processes` | Ollama process inventory |
+| `POST` | `/v1/ollama/pool/cleanup` | Cleanup stale Ollama pool processes |
+
+### Voice, audio, vision
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/voice/state` | Voice runtime status |
+| `GET`/`POST` | `/v1/voice/models` · `/v1/voice/models/switch` | List · switch TTS model |
+| `GET`/`POST` | `/v1/voice/supertonic-settings` | Read · update voice tuning |
+| `GET`/`POST` | `/v1/voice/asr-models` · `/v1/voice/asr-models/switch` | List · switch ASR model |
+| `POST` | `/v1/voice/tts` · `/v1/audio/speech` | Synthesize speech (+ OpenAI alias) |
+| `POST` | `/v1/voice/transcribe` · `/v1/audio/transcriptions` · `/v1/voice/transcribe/stream` | Transcribe (+ alias + streaming) |
+| `GET`/`POST` | `/v1/voice/clone-refs` | List · upload clone reference |
+| `POST` | `/v1/voice/clone-refs/upload` · `/v1/voice/clone-refs/from-url` | Upload · fetch clone reference |
+| `POST` | `/v1/voice/clone-refs/{filename}/activate` · `/v1/voice/clone-refs/{filename}/rename` | Activate · rename clone reference |
+| `DELETE` | `/v1/voice/clone-refs/{filename}` | Delete clone reference |
+| `POST` | `/v1/voice/speak` | Broadcast speech to voicechat clients |
+| `GET` | `/v1/voicechat/ws` | WebSocket upgrade for full-duplex voicechat |
+| `POST` | `/v1/vision/describe` | Vision describe placeholder |
+
+### Generative media
+
+Backed 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}`.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/media/models` | List available image/video/audio/music models |
+| `GET` | `/v1/media/store` | Unified store disk usage + reclaimable legacy caches |
+| `POST` | `/v1/media/migrate` | Dedup + migrate legacy per-group caches into the unified store |
+| `POST` | `/v1/media/image` · `/v1/media/video` · `/v1/media/audio` · `/v1/media/music` | Generate media (run scope) |
+| `GET` | `/v1/media/gallery` | List previously generated media (global, newest first) |
+| `GET` | `/v1/media/file` | Stream one generated media file |
+
+### Engines and scheduled jobs
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/engines` | Long-running engine status |
+| `GET` | `/v1/scheduled` · `/v1/scheduled/all` · `/v1/scheduled/status` | List · list all · scheduler status |
+| `POST` | `/v1/scheduled/kill` · `/v1/scheduled/fixup` · `/v1/scheduled/reconcile` | Kill · reconcile · force reconcile |
+| `GET` | `/v1/services/systemd` | Systemd service status |
+| `GET` | `/v1/update` | Self-update status |
+
+### AIMS governance (ISO/IEC 42001:2023)
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/aims` | AIMS root and endpoint index |
+| `GET`/`PUT` | `/v1/aims/policies` | Policy register · replace |
+| `GET` | `/v1/aims/roles` · `/v1/aims/resources` | Roles · resource inventory |
+| `GET`/`POST` | `/v1/aims/impact-assessments` | List · file impact assessment |
+| `GET` | `/v1/aims/lifecycle` · `/v1/aims/data-quality` · `/v1/aims/transparency` · `/v1/aims/usage` · `/v1/aims/suppliers` | Lifecycle, data quality, transparency, usage, suppliers |
+| `GET`/`POST` | `/v1/aims/incidents` | List · file incident |
+| `GET` | `/v1/aims/oversight` · `/v1/aims/decisions` · `/v1/aims/config-history` | Oversight gates · decision log · config history |
+
+For 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).
 
 ## Agent-Explorable Documentation