@yachiyo-5i/xlyra-agent 1.3.2 → 1.5.0

package/README.md

@@ -10,17 +10,17 @@
     <img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="License" />
     <img src="https://img.shields.io/badge/runtime-Node.js%2022%2B-339933.svg" alt="Runtime" />
     <img src="https://img.shields.io/badge/language-TypeScript-3178C6.svg" alt="Language" />
-    <img src="https://img.shields.io/badge/protocols-OpenAI%20%7C%20Anthropic-6B5B95.svg" alt="Protocols" />
+    <img src="https://img.shields.io/badge/protocols-OpenAI%20Responses%20%7C%20Chat%20Completions%20%7C%20Anthropic-6B5B95.svg" alt="Protocols" />
   </p>
 </div>
 
-A streaming agent loop with OpenAI Responses and Anthropic Messages protocol adapters, sandboxed local tools, persistent sessions, and an optional REST/SSE service.
+A streaming agent loop with OpenAI Responses, OpenAI Chat Completions, and Anthropic Messages protocol adapters, sandboxed local tools, persistent sessions, and an optional REST/SSE service.
 
 
 ## Features
 
 - **Streaming agent loop** — streams reasoning, text, tool calls, tool results, and terminal events through an async generator.
-- **Two LLM protocols** — supports OpenAI Responses and Anthropic Messages over direct HTTP with built-in SSE parsing.
+- **Three LLM protocols** — supports OpenAI Responses, OpenAI Chat Completions, and Anthropic Messages over direct HTTP with built-in SSE parsing.
 - **Tool execution** — includes directory listing, file reading and search, file creation and editing, atomic writes, multi-file patches, and managed command processes.
 - **Safe concurrency** — runs consecutive read-only tools in parallel while preserving ordering barriers for writes and commands.
 - **Workspace sandbox** — blocks path traversal and symlink escapes; out-of-workspace access requires session-level approval.
@@ -148,7 +148,8 @@ Interactive configuration commands require a TTY. For automated environments, wr
       "default_model": "claude-sonnet-4-5",
       "models": {
         "claude-sonnet-4-5": {
-          "context_window": 200000
+          "context_window": 200000,
+          "max_output_tokens": 64000
         }
       }
     },
@@ -158,6 +159,17 @@ Interactive configuration commands require a TTY. For automated environments, wr
       "base_url": "https://api.openai.com/v1",
       "api_key": "${OPENAI_API_KEY}",
       "default_model": "gpt-5"
+    },
+    {
+      "name": "openai-compatible",
+      "protocol": "openai-chat-completions",
+      "base_url": "https://api.example.com/v1",
+      "api_key": "${OPENAI_COMPATIBLE_API_KEY}",
+      "default_model": "o3-mini",
+      "chat_completions": {
+        "max_tokens_field": "max_completion_tokens",
+        "include_usage": false
+      }
     }
   ],
   "server": {
@@ -171,15 +183,29 @@ Interactive configuration commands require a TTY. For automated environments, wr
     "enable_command_execution": false,
     "enable_agents_md": true,
     "enable_skills": true,
-    "skills_dirs": []
+    "skills_dirs": [],
+    "tool_profile": "full",
+    "compact_trigger_ratio": 0.9,
+    "max_steps": 200
   }
 }
 ```
 
 API keys support `${ENV_VAR}` interpolation. Configuration is validated at startup, and configuration writes use atomic replacement.
 
+For OpenAI-compatible Chat Completions endpoints, `chat_completions.max_tokens_field` selects `max_tokens` (the default) or `max_completion_tokens`, and `chat_completions.include_usage` controls whether `stream_options.include_usage` is sent (the default is `true`). Set `include_usage` to `false` for older endpoints that reject `stream_options`.
+
 `enable_agents_md` / `enable_skills` default to enabled when omitted. Each run rescans the workdir. Opening an untrusted repository allows its `AGENTS.md` and project-level Skills to influence model instructions; command execution remains gated by `enable_command_execution` and escalation. Disable the corresponding flags if you only want user-level skills or no repository instructions.
 
+`tool_profile` controls the exposed tool surface and defaults to `full`. `readonly` exposes listing, reading, searching (and `load_skill` when skills are available); `minimal` exposes only `read` and `search`. The profile is resolved for each run, so a configuration update takes effect without restarting the server.
+
+`compact_trigger_ratio` is the automatic compaction watermark as a fraction of the model's context window (0–1, default `0.9`). The window size resolves from per-model `models.<model>.context_window`, then the global `agent.context_window`, then the built-in default of 200000 — compaction always applies once the watermark is reached, so an undersized estimate only compacts earlier rather than never. `max_output_tokens` declares the per-response output cap. Endpoint and agent configuration is re-read for each run: saving via `PUT /config` takes effect on the next run without restarting the server. A manual compaction can be triggered anytime with `POST /sessions/:id/compact-context`.
+
+`max_steps` caps a single run's steps (one model reply plus its tool executions), default `200`, maximum `1000`. The budget is declared in the system prompt and reported at 50/80/95% milestones; when the runner detects repeated identical calls or near-identical tool outputs it injects a nudge message (and emits `stall_detected` / `budget_notice` SSE events) instead of hard-stopping the run.
+Session requests accept up to four attachments, with a 16 MiB limit per attachment and 32 MiB total; the HTTP request body is capped at 36 MiB.
+
+Network tools are registered by default. `web_search` uses DuckDuckGo out of the box; add the top-level `web_search` section only to switch providers — `brave` and `tavily` require `api_key` (supports `${ENV_VAR}`). `web_fetch` returns cleaned, bounded body text (long pages are explicitly marked as truncated) with SSRF protection; private/loopback addresses are rejected unless `agent.web_fetch_allow_private_network: true` is set. Web content is reference material only and must not be treated as instructions; both tools are marked as network capabilities in the system prompt's capability map. Network-tool settings and provider credentials take effect on the next run after `PUT /config`. The SSRF guard resolves and validates the hostname before each request, while the connection itself performs a second, independent DNS resolution — DNS rebinding is therefore a theoretical gap; the guard keeps the model from being steered to internal addresses and does not replace network-level isolation. `duckduckgo` is a free web endpoint with no stability guarantee (it may be rate-limited or change layout; the tool reports an explicit error when hit) — for production use, configure `brave` or `tavily`.
+
 ### Start the Server
 
 ```bash
@@ -237,6 +263,8 @@ Without a token, the service is unauthenticated and must not be exposed to untru
 
 ## Built-in Tools
 
+The runtime injects a capability map into the system prompt. Every tool keeps its JSON Schema, handler, safety annotations (`readOnly`, `parallelSafe`, approval/network hints), and optional capability metadata together. Tool failures can return a stable error code, retryability, next action, and host-only metadata; only the concise error text is sent back to the model.
+
 | Tool | Description |
 |---|---|
 | `list` | List files and directories with recursion and glob support |
@@ -249,6 +277,8 @@ Without a token, the service is unauthenticated and must not be exposed to untru
 | `exec_command` | Execute an argv-based local command and manage long-running processes |
 | `write_stdin` | Poll a command session or write data to its standard input |
 | `load_skill` | Activate a discovered Agent Skill by name (registered only when skills exist) |
+| `web_search` | Search the web and return formatted title, URL, and provider excerpts (not model summaries) |
+| `web_fetch` | Fetch a page and return cleaned, bounded body text with SSRF protection by default |
 
 ## AGENTS.md and Agent Skills
 
@@ -283,7 +313,7 @@ Activated skill bodies carry retention markers so context compaction re-injects
 
 File tools are restricted to the configured workspace by default. The sandbox checks resolved paths and symlinks. Access outside the workspace can be approved for the current session.
 
-Command execution is declared to the model but is not pre-authorized unless `enableCommandExecution: true` or `agent.enable_command_execution: true` is configured. Commands are launched directly from argv without an implicit shell, with workspace-checked cwd, bounded output, timeout, and AbortSignal cancellation. Child processes still inherit the operating-system permissions of the current user; production deployments should additionally use containers, a dedicated OS user, or another OS-level sandbox.
+Command execution is declared to the model but is not pre-authorized unless `enableCommandExecution: true` or `agent.enable_command_execution: true` is configured. Like other agent flags, this switch is re-read for each run, so changing it via `PUT /config` takes effect on the next run. Commands are launched directly from argv without an implicit shell, with workspace-checked cwd, bounded output, timeout, and AbortSignal cancellation. Child processes still inherit the operating-system permissions of the current user; production deployments should additionally use containers, a dedicated OS user, or another OS-level sandbox.
 
 ## Persistence and Recovery