omnius 1.0.159 → 1.0.160

package/docs/rest/endpoints/files.md

@@ -0,0 +1,18 @@
+# Files
+
+## Endpoint Summary
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/files` | List a workspace directory |
+| `GET` | `/v1/files/read` | Read a workspace file |
+
+## Directory Listing
+
+`GET /v1/files?path=<relative-or-absolute>` returns directory entries for the active or requested workspace.
+
+## File Read
+
+`GET /v1/files/read?path=<path>` reads file content where policy permits.
+
+File operations are subject to workspace, auth, and profile restrictions. Remote clients should not assume arbitrary filesystem access.

package/docs/rest/endpoints/memory.md

@@ -0,0 +1,42 @@
+# Memory, Sessions, And Context
+
+## Endpoint Summary
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/memory` | Memory backend summary |
+| `POST` | `/v1/memory/search` | Search memory |
+| `POST` | `/v1/memory/write` | Write memory |
+| `GET` | `/v1/memory/episodes` | List episodes |
+| `GET` | `/v1/memory/failures` | List captured failures |
+| `GET` | `/v1/sessions` | List Omnius task sessions |
+| `GET` | `/v1/sessions/{id}` | Get session history |
+| `GET` | `/v1/context` | Show current session context |
+| `POST` | `/v1/context/save` | Save a context entry |
+| `GET` | `/v1/context/restore` | Build a restore prompt |
+| `POST` | `/v1/context/compact` | Request context compaction |
+
+## Memory Search
+
+Use memory search for persistent knowledge, failures, prior decisions, and scoped context. Public connector surfaces such as Telegram should keep scope explicit so one chat does not pollute another.
+
+## Memory Write
+
+Memory writes require run or admin scope where enforced. Prefer structured, scoped writes over dumping entire transcripts.
+
+## Failures
+
+Failure records let the agent learn from raw observed outputs. The design goal is to pass failure output through as evidence, not convert platform-specific strings into hardcoded policy shortcuts.
+
+## Context
+
+Context endpoints expose the TUI context stack:
+
+- `GET /v1/context`: current context snapshot.
+- `POST /v1/context/save`: persist a context entry.
+- `GET /v1/context/restore`: build a restore prompt.
+- `POST /v1/context/compact`: request compaction.
+
+## Sessions
+
+Session endpoints expose archived task turns, which can be used by dashboards, replay tooling, or state restoration.

package/docs/rest/endpoints/run.md

@@ -0,0 +1,52 @@
+# Runs, Jobs, Todos, And Scheduled Work
+
+## Endpoint Summary
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/v1/run` | Submit an agentic task |
+| `GET` | `/v1/runs` | List runs |
+| `GET` | `/v1/runs/{id}` | Get run details |
+| `DELETE` | `/v1/runs/{id}` | Abort a run |
+| `GET` | `/v1/todos` | List sessions with todo lists |
+| `GET` | `/v1/todos/{session_id}` | Get todos for a session |
+| `POST` | `/v1/todos/{session_id}` | Replace or update todos for a session |
+| `POST` | `/v1/evaluate` | Evaluate a run by ID |
+| `POST` | `/v1/index` | Trigger repository indexing |
+| `GET` | `/v1/scheduled` | List scheduled jobs |
+| `GET` | `/v1/scheduled/all` | List all scheduled jobs |
+| `GET` | `/v1/scheduled/status` | Scheduled runner status |
+| `POST` | `/v1/scheduled/kill` | Kill a scheduled job |
+| `POST` | `/v1/scheduled/fixup` | Reconcile scheduled job state |
+| `POST` | `/v1/scheduled/reconcile` | Force reconciliation |
+
+## `/v1/run`
+
+Submits a long-running task to the daemon and returns an accepted job record. Runs are tracked under `.omnius/jobs/`.
+
+Common body fields:
+
+| Field | Purpose |
+| --- | --- |
+| `task` | Natural language task |
+| `repo` or `working_dir` | Workspace root |
+| `model` | Optional model override |
+| `sandbox` | Execution sandbox mode |
+| `profile` | Tool profile |
+| `timeout_s` | Wall-clock timeout |
+
+## Abort
+
+`DELETE /v1/runs/{id}` aborts the job. The daemon signals the process group, escalates if needed, updates the job record, and decrements per-key active job counters.
+
+## Handoff And Adoption
+
+When a daemon restarts gracefully, live child runs can be adopted from the handoff file. The daemon polls foreign PIDs, re-arms timeouts, and finalizes job records when those processes exit.
+
+## Todos
+
+Todo endpoints expose the same checklist state the TUI and agent loop use. They are useful for dashboards and run supervision.
+
+## Scheduled Jobs
+
+Scheduled endpoints report and repair the long-running scheduler state. Use admin-scoped controls for kill or reconciliation operations.

package/docs/rest/endpoints/skills.md

@@ -0,0 +1,41 @@
+# Skills And Commands
+
+## Endpoint Summary
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/skills` | List skills |
+| `GET` | `/v1/skills/{name}` | Load skill content |
+| `GET` | `/v1/commands` | List slash commands |
+| `POST` | `/v1/commands/{cmd}` | Execute a slash command in an isolated subprocess |
+
+## Skills
+
+Omnius discovers skills from:
+
+- AIWG package frameworks, addons, and plugins.
+- AIWG user data frameworks, addons, and plugins.
+- Project `.aiwg/skills`.
+- Project `.aiwg/commands`.
+- Project-local AIWG bundles: `.aiwg/addons/*/skills`, `.aiwg/extensions/*/skills`, `.aiwg/frameworks/*/skills`, `.aiwg/plugins/*/skills`.
+- Project `.omnius/skills`.
+
+The REST docs bundle is available as:
+
+```text
+omnius-rest-docs
+```
+
+Use `/v1/skills/omnius-rest-docs` or the agent tool `skill_execute`.
+
+## Commands
+
+Command execution is isolated in a subprocess and subject to command policy. Dangerous or denied commands require admin controls and may be blocked by profile policy.
+
+## Small-Context Pattern
+
+For agents:
+
+1. Use `skill_list` or `/v1/skills` to find the skill.
+2. Load only the specific skill that matches the current task.
+3. Use `skill_extract` where available to pull targeted sections instead of full documents.

package/docs/rest/endpoints/tools.md

@@ -0,0 +1,62 @@
+# Tools, MCP, Hooks, Agents, And Code Graph
+
+## Endpoint Summary
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/tools` | List tool registry with security metadata |
+| `GET` | `/v1/tools/{name}` | Get one tool definition |
+| `POST` | `/v1/tools/{name}/call` | Invoke a tool |
+| `GET` | `/v1/mcps` | List MCP servers |
+| `GET` | `/v1/mcps/{name}` | Get MCP server details |
+| `POST` | `/v1/mcps/{name}/call` | Invoke an MCP tool |
+| `GET` | `/v1/hooks` | List hook types and counts |
+| `GET` | `/v1/agents` | List agent types |
+| `GET` | `/v1/codegraph/snapshot` | Code graph stats and recent events |
+| `GET` | `/v1/codegraph/events` | Code graph live event stream |
+
+## Tool Metadata
+
+`GET /v1/tools` returns each tool's:
+
+- name
+- class
+- description
+- JSON-schema parameters
+- security categories
+- risk
+- required scope
+- off-device allowance
+- rationale
+
+Filters include:
+
+```text
+?category=read|write|exec|network|hardware|agent|sensitive
+?scope=read|run|admin
+?risk=low|medium|high|critical
+?limit=200&offset=0
+```
+
+## Tool Calls
+
+`POST /v1/tools/{name}/call` body:
+
+```json
+{
+  "args": {},
+  "working_dir": "/path/to/repo"
+}
+```
+
+`args` is the canonical wrapper. The schema from `/v1/tools/{name}` describes the fields inside `args`.
+
+Tool calls are gated by auth scope, tool policy, off-device policy, and profile restrictions.
+
+## MCP
+
+MCP endpoints list connected Model Context Protocol servers and invoke tools through the daemon with the same auth and audit envelope.
+
+## Code Graph
+
+Code graph endpoints expose repository indexing state and live graph events for GUI or dashboard clients.

package/docs/rest/endpoints/voice-vision.md

@@ -0,0 +1,80 @@
+# Voice, Audio, Vision, And Voicechat
+
+## Endpoint Summary
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/voice/state` | Voice runtime status |
+| `GET` | `/v1/voice/models` | List TTS voice models |
+| `POST` | `/v1/voice/models/switch` | Switch active TTS model |
+| `GET`/`PUT` | `/v1/voice/supertonic-settings` | Voice tuning settings |
+| `GET` | `/v1/voice/asr-models` | List Whisper ASR models |
+| `POST` | `/v1/voice/asr-models/switch` | Switch active ASR model |
+| `POST` | `/v1/voice/tts` | Synthesize text |
+| `POST` | `/v1/audio/speech` | OpenAI-compatible TTS alias |
+| `POST` | `/v1/voice/transcribe` | Transcribe audio |
+| `POST` | `/v1/audio/transcriptions` | OpenAI-compatible transcription alias |
+| `POST` | `/v1/voice/transcribe/stream` | Streaming transcription |
+| `GET` | `/v1/voice/clone-refs` | List clone references |
+| `POST` | `/v1/voice/clone-refs/upload` | Upload clone reference |
+| `POST` | `/v1/voice/clone-refs/from-url` | Fetch clone reference server-side |
+| `POST` | `/v1/voice/clone-refs/{filename}/activate` | Activate clone reference |
+| `POST` | `/v1/voice/clone-refs/{filename}/rename` | Rename clone reference |
+| `DELETE` | `/v1/voice/clone-refs/{filename}` | Delete clone reference |
+| `POST` | `/v1/voice/speak` | Synthesize and broadcast to voicechat clients |
+| `WS` | `/v1/voicechat/ws` | Full-duplex voicechat WebSocket |
+| `POST` | `/v1/vision/describe` | Vision describe placeholder/deferred endpoint |
+
+## TTS
+
+`POST /v1/voice/tts` returns audio bytes. `format` can be `wav` or `pcm`. `X-Sample-Rate` reports the sample rate.
+
+OpenAI-compatible alias:
+
+```text
+POST /v1/audio/speech
+```
+
+## ASR
+
+`POST /v1/voice/transcribe` transcribes uploaded audio. The OpenAI-compatible alias is:
+
+```text
+POST /v1/audio/transcriptions
+```
+
+## Voicechat WebSocket
+
+`/v1/voicechat/ws` supports full-duplex realtime voice.
+
+Client to server:
+
+- Binary PCM Int16 mono 16 kHz mic audio.
+- JSON text frame `{ "type": "start" }`.
+- JSON text frame `{ "type": "stop" }`.
+- JSON text frame `{ "type": "speak", "text": "..." }`.
+- JSON text frame `{ "type": "ping" }`.
+
+Server to client:
+
+- `hello`
+- `loaded`
+- `transcript`
+- `agent_text`
+- `tts_header`
+- binary TTS PCM
+- `tts_start`
+- `tts_end`
+- `state`
+- `session_state`
+- `error`
+- `keepalive`
+- `pong`
+- `session_started`
+- `session_stopped`
+
+Each binary TTS batch is preceded by a `tts_header` frame that announces the sample rate.
+
+## Realtime REST Plus Voice
+
+For ASR/TTS clients that do not use `/v1/voicechat/ws`, call `/v1/chat` with `realtime: true` and send the text transcript as `message`.

package/docs/rest/errors-pagination-etags.md

@@ -0,0 +1,84 @@
+# Errors, Pagination, ETags, And Request IDs
+
+## Error Shape
+
+The OpenAPI contract documents RFC 7807 Problem Details for common errors:
+
+```json
+{
+  "type": "https://omnius.nexus/problems/not-found",
+  "title": "Resource not found",
+  "status": 404,
+  "detail": "Optional detail",
+  "instance": "request-id",
+  "aims:control": "Optional ISO/IEC 42001 control reference"
+}
+```
+
+Some legacy endpoints may still return simpler `{ "error": "..." }` shapes. Prefer the live `/openapi.json` and endpoint behavior when writing strict clients.
+
+## Common Status Codes
+
+| Code | Meaning |
+| --- | --- |
+| `400` | Invalid request body or query |
+| `401` | Missing or invalid bearer token |
+| `403` | Authenticated but scope or tool policy is insufficient |
+| `404` | Resource not found |
+| `429` | Rate limit exceeded |
+| `500` | Internal daemon error |
+| `501` | Endpoint intentionally not implemented yet |
+
+## Pagination
+
+List endpoints generally use:
+
+```json
+{
+  "data": [],
+  "pagination": {
+    "limit": 50,
+    "offset": 0,
+    "total": 0,
+    "has_more": false
+  }
+}
+```
+
+Use:
+
+```text
+?limit=50&offset=0
+```
+
+Some list endpoints support family-specific filters such as `status`, `category`, `scope`, `risk`, or `type`.
+
+## ETags
+
+Cacheable GET endpoints may return an `ETag` header. Send it back with:
+
+```text
+If-None-Match: "<etag>"
+```
+
+When unchanged, the daemon can return `304 Not Modified`.
+
+## Request Correlation
+
+Clients can send:
+
+```text
+X-Request-ID: client-generated-id
+```
+
+The daemon echoes the request ID where middleware applies and writes it into audit/event surfaces where available.
+
+## API Version Header
+
+Responses carry:
+
+```text
+X-API-Version: <semver>
+```
+
+Use this for compatibility checks in dashboards and remote clients.

package/docs/rest/examples/curl.md

@@ -0,0 +1,84 @@
+# Curl Examples
+
+Set base:
+
+```bash
+BASE=http://127.0.0.1:11435
+```
+
+## Health
+
+```bash
+curl -s "$BASE/health"
+```
+
+## OpenAPI
+
+```bash
+curl -s "$BASE/openapi.json" | jq '.info.title, .info.version'
+```
+
+## Chat
+
+```bash
+curl -s "$BASE/v1/chat" \
+  -H 'content-type: application/json' \
+  -d '{"message":"What files define the REST API?","tools":true}'
+```
+
+## Realtime
+
+```bash
+curl -s "$BASE/v1/chat" \
+  -H 'content-type: application/json' \
+  -d '{
+    "message": "Answer like this is a live voice call.",
+    "realtime": true,
+    "realtime_options": {
+      "max_history_messages": 8,
+      "max_tokens": 120
+    }
+  }'
+```
+
+## OpenAI-Compatible Chat
+
+```bash
+curl -s "$BASE/v1/chat/completions" \
+  -H 'content-type: application/json' \
+  -d '{
+    "model": "qwen3:4b",
+    "messages": [
+      {"role": "user", "content": "Return one sentence."}
+    ]
+  }'
+```
+
+## Agentic Run
+
+```bash
+curl -s -X POST "$BASE/v1/run" \
+  -H 'content-type: application/json' \
+  -d '{"task":"List the test files related to skill discovery."}'
+```
+
+## Events
+
+```bash
+curl -N "$BASE/v1/events?type=run.*"
+```
+
+## Skill Docs
+
+```bash
+curl -s "$BASE/v1/skills/omnius-rest-docs"
+```
+
+## Runtime Key
+
+```bash
+curl -s -X POST "$BASE/v1/keys" \
+  -H 'authorization: Bearer admin-secret' \
+  -H 'content-type: application/json' \
+  -d '{"scope":"run","owner":"ci","rpm":60,"tpd":100000,"max_jobs":3}'
+```

package/docs/rest/examples/openai-sdk.md

@@ -0,0 +1,59 @@
+# OpenAI SDK Examples
+
+Omnius exposes an OpenAI-compatible chat-completions endpoint at `/v1/chat/completions`.
+
+## JavaScript
+
+```ts
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  baseURL: "http://127.0.0.1:11435/v1",
+  apiKey: process.env.OMNIUS_API_KEY ?? "local-dev",
+});
+
+const response = await client.chat.completions.create({
+  model: "qwen3:4b",
+  messages: [
+    { role: "user", content: "Summarize the current project." },
+  ],
+});
+
+console.log(response.choices[0]?.message?.content);
+```
+
+## JavaScript Realtime Flag
+
+The SDK may not know Omnius-specific fields. Pass them through with a typed escape hatch if needed:
+
+```ts
+const response = await client.chat.completions.create({
+  model: "qwen3:4b",
+  messages: [
+    { role: "user", content: "Keep it short enough for TTS." },
+  ],
+  realtime: true,
+  realtime_options: {
+    max_history_messages: 8,
+    max_tokens: 120,
+  },
+} as any);
+```
+
+## Python
+
+```py
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://127.0.0.1:11435/v1",
+    api_key="local-dev",
+)
+
+response = client.chat.completions.create(
+    model="qwen3:4b",
+    messages=[{"role": "user", "content": "Return one sentence."}],
+)
+
+print(response.choices[0].message.content)
+```

package/docs/rest/openapi-source.md

@@ -0,0 +1,36 @@
+# OpenAPI Source And Renderers
+
+The canonical REST contract is generated by:
+
+```text
+packages/cli/src/api/openapi.ts
+```
+
+Runtime docs:
+
+| Path | Purpose |
+| --- | --- |
+| `/openapi.json` | Canonical OpenAPI 3.0 JSON |
+| `/openapi.yaml` | YAML form of the same spec |
+| `/v3/api-docs` | OpenAPI alias |
+| `/swagger.json` | Swagger-era alias |
+| `/api-docs` | OpenAPI alias |
+| `/docs` | Swagger UI |
+| `/api/docs` | Swagger UI alias |
+| `/swagger-ui` | Swagger UI alias |
+| `/redoc` | ReDoc renderer |
+
+Swagger UI attempts local assets first and can fall back to a CDN if available. Offline clients should prefer `/openapi.json`.
+
+## Contract Rule
+
+When docs and behavior differ:
+
+1. Check the live daemon `/openapi.json`.
+2. Check `packages/cli/src/api/openapi.ts`.
+3. Check route implementation in `packages/cli/src/api/serve.ts` and `packages/cli/src/api/routes-v1.ts`.
+4. Patch this docs directory after the behavior is confirmed.
+
+## AsyncAPI
+
+The voicechat WebSocket has an AsyncAPI description generated from the same schema definitions. See `docs/rest/endpoints/voice-vision.md`.

package/npm-shrinkwrap.json

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