@yachiyo-5i/xlyra-agent 0.2.0

package/README.md

@@ -0,0 +1,306 @@
+<div align="center">
+  <h1>xlyra-agent</h1>
+  <p>A general-purpose conversational agent runtime for TypeScript.</p>
+  <p>
+    <a href="README_zh.md">简体中文</a> ·
+    <a href="#quick-start">Quick Start</a> ·
+    <a href="LICENSE">License</a>
+  </p>
+  <p>
+    <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" />
+  </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.
+
+
+## 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.
+- **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.
+- **Command approval** — command tools can be pre-authorized or approved per session before execution.
+- **Context compaction** — automatically summarizes history near the model context limit while preserving recent user messages.
+- **Persistent sessions** — stores transcripts as JSONL and rebuilds the session index from the source records on startup.
+- **Resumable streaming** — exposes SSE events with `Last-Event-ID` replay, heartbeats, cancellation, and terminal-state guarantees.
+- **Library and service modes** — use the runtime as an npm library or run it behind the included HTTP service and CLI.
+
+## Quick Start
+
+### Requirements
+
+- Node.js 22 or later
+- pnpm
+- Bun only when building the standalone executable
+
+### Installation
+
+For npm users, install the published package globally:
+
+```bash
+npm i -g @yachiyo-5i/xlyra-agent
+xlyra --help
+xlyra config init
+xlyra serve
+```
+
+The package requires Node.js 22 or later and includes both the library and the `xlyra` CLI. To use it as a library:
+
+```bash
+npm i @yachiyo-5i/xlyra-agent
+```
+
+For source development, install dependencies and build locally:
+
+```bash
+pnpm install
+pnpm build
+```
+
+The build produces ESM, CommonJS, and TypeScript declarations in `dist/`.
+
+To build and install the standalone `xlyra` command locally:
+
+```bash
+pnpm install:local
+```
+
+This command requires Bun and links the executable to `~/.local/bin/xlyra`.
+
+## Library Usage
+
+```ts
+import { AgentRunner, EndpointResolver, builtinTools } from "@yachiyo-5i/xlyra-agent";
+
+const resolver = new EndpointResolver([
+  {
+    name: "anthropic",
+    protocol: "anthropic-messages",
+    base_url: "https://api.anthropic.com",
+    api_key: process.env.ANTHROPIC_API_KEY!,
+    default_model: "claude-sonnet-4-5",
+  },
+]);
+
+const runner = new AgentRunner({
+  resolver,
+  tools: builtinTools({ workdir: "./workspace" }),
+});
+
+for await (const event of runner.start({
+  input: "List the current directory and summarize the README.",
+})) {
+  if (event.type === "text_delta") process.stdout.write(event.delta ?? "");
+  if (event.type === "agent_done") console.log("\nUsage:", event.result?.usage);
+  if (event.type === "agent_error") console.error("Error:", event.error);
+}
+```
+
+A model can be selected with:
+
+- `endpoint/model-id` for an explicit endpoint
+- `model-id` when it resolves to a unique endpoint
+- an empty string to use the first endpoint's default model
+
+### Event Stream
+
+```text
+agent_start
+  → (thinking_delta | text_delta)*
+  → (tool_call_start → tool_call_delta* → tool_call → tool_result*)*
+  → agent_done | agent_error | agent_cancelled
+```
+
+`context_compacted` and `escalation_request` may appear at safe points during a run.
+
+## Service Usage
+
+### Configuration
+
+The default configuration file is `~/.xlyra-agent/config.json`.
+
+Create and manage it with the CLI:
+
+```bash
+xlyra config init
+xlyra config add
+xlyra config add openai
+xlyra config list
+xlyra config remove <name>
+xlyra config path
+```
+
+Interactive configuration commands require a TTY. For automated environments, write the configuration file directly:
+
+```json
+{
+  "endpoints": [
+    {
+      "name": "anthropic",
+      "protocol": "anthropic-messages",
+      "base_url": "https://api.anthropic.com",
+      "api_key": "${ANTHROPIC_API_KEY}",
+      "default_model": "claude-sonnet-4-5",
+      "models": {
+        "claude-sonnet-4-5": {
+          "context_window": 200000
+        }
+      }
+    },
+    {
+      "name": "openai",
+      "protocol": "openai-responses",
+      "base_url": "https://api.openai.com/v1",
+      "api_key": "${OPENAI_API_KEY}",
+      "default_model": "gpt-5"
+    }
+  ],
+  "server": {
+    "port": 3210,
+    "token": "replace-with-a-long-random-token"
+  },
+  "agent": {
+    "workdir": "~/.xlyra-agent/workspace",
+    "agent_name": "xlyra assistant",
+    "persona": "A concise software engineering assistant",
+    "enable_command_execution": false
+  }
+}
+```
+
+API keys support `${ENV_VAR}` interpolation. Configuration is validated at startup, and configuration writes use atomic replacement.
+
+### Start the Server
+
+```bash
+pnpm dev:serve
+```
+
+Or start the built CLI:
+
+```bash
+node dist/cli.js serve --port 3210
+```
+
+After global npm installation, the equivalent command is:
+
+```bash
+xlyra serve --port 3210
+```
+
+Runtime data is stored under `~/.xlyra-agent/`:
+
+```text
+~/.xlyra-agent/
+├── config.json
+├── index.json
+├── sessions/
+└── workspace/
+```
+
+### HTTP API
+
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/sessions` | Start a session or continue an existing session |
+| `GET` | `/sessions` | List recent sessions with pagination |
+| `GET` | `/sessions/:id/transcript` | Read the complete transcript and compaction records |
+| `PATCH` | `/sessions/:id` | Rename a session |
+| `DELETE` | `/sessions/:id` | Delete an idle session |
+| `POST` | `/sessions/:id/retry` | Retry from a selected user message |
+| `POST` | `/sessions/:id/compact-context` | Compact the current model context manually |
+| `POST` | `/sessions/:id/grant-access` | Approve or reject a path or command escalation |
+| `GET` | `/sessions/:id/events` | Follow events over SSE with replay support |
+| `POST` | `/sessions/:id/stop` | Stop the active run idempotently |
+| `GET` | `/health` | Check service health |
+| `GET` | `/config` | Read the configuration with masked API keys |
+| `PUT` | `/config` | Validate and save the configuration |
+| `POST` | `/config/test` | Test an endpoint with a minimal model request |
+
+When `server.token` is configured, requests must include:
+
+```http
+Authorization: Bearer <token>
+```
+
+Without a token, the service is unauthenticated and must not be exposed to untrusted networks.
+
+## Built-in Tools
+
+| Tool | Description |
+|---|---|
+| `list` | List files and directories with recursion and glob support |
+| `read` | Read text files in bounded chunks |
+| `search` | Search file contents and return matching paths and lines |
+| `create` | Create a new file and fail if the target already exists |
+| `edit` | Replace exact text with optional explicit multi-match replacement |
+| `write` | Atomically overwrite an existing file |
+| `apply_patch` | Validate and apply a multi-file patch as one operation |
+| `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 |
+
+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.
+
+## Persistence and Recovery
+
+- Each session is stored as an append-oriented JSONL transcript.
+- Final messages, tool results, compaction records, and escalation records are persisted.
+- Interrupted tool calls receive a synthetic error result so recovered history remains valid.
+- `index.json` is a query index, not the source of truth; it is rebuilt from session files at startup.
+- Configuration, indexes, retries, escalation updates, and file writes use temporary files followed by atomic rename where applicable.
+
+## Testing
+
+```bash
+pnpm test
+pnpm typecheck
+```
+
+The default test suite is offline and covers protocol adapters, SSE parsing, the agent loop, context compaction, persistence, tools, REST/SSE routes, configuration, and CLI behavior.
+
+Run smoke tests against configured model endpoints with:
+
+```bash
+pnpm test:smoke
+```
+
+Optional environment variables:
+
+```text
+XLYRA_SMOKE_CONFIG=<config-path>
+XLYRA_SMOKE_ENDPOINT=<endpoint-name>
+OPENAI_API_KEY=<key>
+OPENAI_MODEL=<model>
+ANTHROPIC_API_KEY=<key>
+ANTHROPIC_MODEL=<model>
+```
+
+Smoke tests make real model requests and may incur provider charges.
+
+## Publishing with GitHub Actions
+
+The repository includes CI verification, Release Please, and a GitHub Release-triggered npm publishing workflow. Publishing uses npm Trusted Publishing with GitHub OIDC, so no long-lived npm token is stored in GitHub.
+
+Before the first release:
+
+1. Push the repository and these workflows to `main`.
+2. On npm, add a Trusted Publisher for package `@yachiyo-5i/xlyra-agent`:
+   - GitHub owner: `Yachiyo-5i`
+   - Repository: `xLyra-agent`
+   - Workflow file: `.github/workflows/publish-npm.yml`
+   - Environment: `npm`
+3. In GitHub, create the `npm` environment. Require approval for this environment if releases should be manually reviewed.
+4. Configure branch protection for `main` as described above.
+5. Merge regular feature PRs into `main`. Release Please will create or update the release PR.
+6. Review and merge the Release Please PR. It creates the GitHub Release, which triggers npm publication.
+
+The publish workflow runs typecheck, tests, build, and package-content checks before publishing. It cannot publish the same package version twice; versions are managed by Release Please from Conventional Commits.
+
+xLyra Agent is licensed under the [GNU Affero General Public License v3.0](LICENSE).