@ai-agent-forge/agent-forge 0.85.0

package/README.md

@@ -0,0 +1,629 @@
+# Agent Forge
+<p align="center">
+  <a href="https://discord.com/invite/3cU7Bz4UPx"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
+  <a href="https://www.npmjs.com/package/@ai-agent-forge/agent-forge"><img alt="npm" src="https://img.shields.io/npm/v/@ai-agent-forge/agent-forge?style=flat-square" /></a>
+</p>
+
+> New issues and PRs from new contributors are auto-closed by default. Maintainers review auto-closed issues daily. See [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+---
+
+Agent Forge 是一个极简的终端编程 Agent。内核只提供模型流、会话、工具、事件、生命周期与可版本化公共 API；MCP、Skill、CLI 工具、多 Agent、Goal、Plan 和策略均通过插件接入。将工作流适配给自己，无须修改内核。
+
+默认能力保持最小：Agent Forge 以交互、print/JSON、RPC 和 SDK 方式运行。扩展能力通过 [插件](#plugins)、[Skills](#skills)、提示模板与主题安装或实现。
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Providers & Models](#providers--models)
+- [Interactive Mode](#interactive-mode)
+  - [Editor](#editor)
+  - [Commands](#commands)
+  - [Keyboard Shortcuts](#keyboard-shortcuts)
+  - [Message Queue](#message-queue)
+- [Sessions](#sessions)
+  - [Branching](#branching)
+  - [Compaction](#compaction)
+- [Settings](#settings)
+- [Context Files](#context-files)
+- [Customization](#customization)
+  - [Prompt Templates](#prompt-templates)
+  - [Skills](#skills)
+  - [Extensions](#extensions)
+  - [Themes](#themes)
+  - [Plugins](#plugins)
+- [Programmatic Usage](#programmatic-usage)
+- [Philosophy](#philosophy)
+- [CLI Reference](#cli-reference)
+
+---
+
+## Quick Start
+
+```bash
+npm install -g --ignore-scripts @ai-agent-forge/agent-forge
+```
+
+`--ignore-scripts` disables dependency lifecycle scripts during install. Agent Forge 的正常安装不依赖安装脚本。
+
+Authenticate with an API key:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+agent-forge
+```
+
+Or use your existing subscription:
+
+```bash
+agent-forge
+/login  # Then select provider
+```
+
+然后直接与 Agent Forge 对话。默认工具由可替换的首方插件提供：`read`、`write`、`edit` 与 `bash`。通过 [插件](#plugins)、[Skills](#skills) 或提示模板增加能力。
+
+**Platform notes:** [Windows](docs/windows.md) | [Termux (Android)](docs/termux.md) | [tmux](docs/tmux.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md)
+
+---
+
+## Providers & Models
+
+Agent Forge 为已配置 provider 维护可用模型目录；运行 `agent-forge update --models` 可手动刷新。通过订阅（`/login`）或 API key 认证后，可用 `/model`（或 Ctrl+L）选择模型；在模型选择器中按 Ctrl+S 可保存启动默认值。
+
+**Subscriptions:**
+- Anthropic Claude Pro/Max
+- OpenAI ChatGPT Plus/Pro (Codex)
+- GitHub Copilot
+
+**API keys:**
+- Anthropic
+- Ant Ling
+- OpenAI
+- Azure OpenAI
+- DeepSeek
+- NVIDIA NIM
+- Google Gemini
+- Google Vertex
+- Amazon Bedrock
+- Mistral
+- Groq
+- Cerebras
+- Cloudflare AI Gateway
+- Cloudflare Workers AI
+- xAI
+- OpenRouter
+- Vercel AI Gateway
+- ZAI Coding Plan (Global)
+- ZAI Coding Plan (China)
+- OpenCode Zen
+- OpenCode Go
+- Hugging Face
+- Fireworks
+- Together AI
+- Baseten
+- Kimi For Coding
+- MiniMax
+- Xiaomi MiMo
+- Xiaomi MiMo Token Plan (China)
+- Xiaomi MiMo Token Plan (Amsterdam)
+- Xiaomi MiMo Token Plan (Singapore)
+
+Agent Forge 也支持 llama.cpp router server。用 `/login llama.cpp` 配置、用 `/llama` 管理下载和已加载模型，再用 `/model` 选择模型。参见 [docs/llama-cpp.md](docs/llama-cpp.md)。
+
+See [docs/providers.md](docs/providers.md) for other provider setup instructions.
+
+**Custom providers & models:** Add providers via `~/.agent-forge/agent/models.json` if they speak a supported API (OpenAI, Anthropic, Google). Custom API implementations and OAuth flows existed only through the legacy ExtensionAPI and were removed together with it (D-066); there is currently no plugin-face equivalent. See [docs/models.md](docs/models.md).
+
+---
+
+## Interactive Mode
+
+<p align="center"><img src="docs/images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
+
+The interface from top to bottom:
+
+- **Startup header** - Shows shortcuts (`/hotkeys` for all), loaded AGENTS.md files, prompt templates, skills, and themes
+- **Messages** - Your messages, assistant responses, tool calls and results, notifications, and errors
+- **Editor** - Where you type; border color indicates thinking level
+- **Footer** - Working directory, session name, total token/cache usage (`↑` input, `↓` output, `R` cache read, `W` cache write, `CH` latest cache hit rate), cost, context usage, current model. Totals include assistant responses, usage reported by tools, and summary generation.
+
+The editor can be temporarily replaced by built-in UI, such as the `/settings` or `/model` selectors. Capability plugins cannot host custom TUI components; they interact with the user through the built-in `notify`, `confirm`, `select`, and `input` prompts.
+
+### Editor
+
+| Feature | How |
+|---------|-----|
+| File reference | Type `@` to fuzzy-search project files |
+| Path completion | Tab to complete paths |
+| Multi-line | Shift+Enter (or Ctrl+Enter on Windows Terminal) |
+| External editor | Ctrl+G opens `externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere |
+| Clipboard | Ctrl+V to paste an image or text (Alt+V on Windows), or drag images onto terminal |
+| Bash commands | `!command` runs and sends output to LLM, `!!command` runs without sending |
+
+Standard editing keybindings for delete word, undo, etc. See [docs/keybindings.md](docs/keybindings.md).
+
+### Commands
+
+Type `/` in the editor to trigger commands. [Extensions](#extensions) can register custom commands, [skills](#skills) are available as `/skill:name`, and [prompt templates](#prompt-templates) expand via `/templatename`.
+
+| Command | Description |
+|---------|-------------|
+| `/login`, `/logout` | Manage provider credentials |
+| [`/llama`](docs/llama-cpp.md) | Download, load, and unload llama.cpp router models |
+| `/model` | Switch models; Ctrl+S in the picker saves the startup default |
+| `/thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
+| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
+| `/settings` | Theme, message delivery, transport, and other preferences |
+| `/resume` | Pick from previous sessions |
+| `/new` | Start a new session |
+| `/name <name>` | Set session display name |
+| `/session` | Show session info (file, ID, messages, tokens, cost) |
+| `/tree` | Jump to any point in the session and continue from there |
+| `/fork` | Create a new session from a previous user message |
+| `/clone` | Duplicate the current active branch into a new session |
+| `/compact [prompt]` | Manually compact context, optional custom instructions |
+| `/copy` | Copy last assistant message to clipboard |
+| `/export [file]` | Export session to HTML or JSONL file |
+| `/import <file>` | Import and resume a session from a JSONL file |
+| `/share` | 由显式安装的 session-share 插件提供；核心不内置 |
+| `/reload` | Reload keybindings, extensions, skills, prompts, themes, and context files |
+| `/hotkeys` | Show all keyboard shortcuts |
+| `/changelog` | Display version history |
+| `/quit` | 退出 Agent Forge |
+
+### Keyboard Shortcuts
+
+See `/hotkeys` for the full list. Customize via `~/.agent-forge/agent/keybindings.json`. See [docs/keybindings.md](docs/keybindings.md).
+
+**Commonly used:**
+
+| Key | Action |
+|-----|--------|
+| Ctrl+C | Clear editor |
+| Ctrl+C twice | Quit |
+| Escape | Cancel/abort |
+| Escape twice | Open `/tree` |
+| Ctrl+L | Open model selector |
+| Ctrl+P / Shift+Ctrl+P | Cycle scoped models forward/backward |
+| Shift+Tab | Cycle thinking level |
+| Ctrl+O | Collapse/expand tool output |
+| Ctrl+T | Collapse/expand thinking blocks |
+| Ctrl+X | Copy the last assistant message; with fullscreen copy-on-select disabled, copy the active text selection |
+
+### Message Queue
+
+Submit messages while the agent is working:
+
+- **Enter** queues a *steering* message, delivered after the current assistant turn finishes executing its tool calls
+- **Alt+Enter** queues a *follow-up* message, delivered only after the agent finishes all work
+- **Escape** aborts and restores queued messages to editor
+- **Alt+Up** retrieves queued messages back to editor
+
+On Windows Terminal, `Alt+Enter` is fullscreen by default. Remap it in [docs/terminal-setup.md](docs/terminal-setup.md) so Agent Forge can receive the follow-up shortcut.
+
+Configure delivery in [settings](docs/settings.md): `steeringMode` and `followUpMode` can be `"one-at-a-time"` (default, waits for response) or `"all"` (delivers all queued at once). `transport` selects provider transport preference (`"sse"`, `"websocket"`, or `"auto"`) for providers that support multiple transports.
+
+---
+
+## Sessions
+
+Sessions are stored as JSONL files with a tree structure. Each entry has an `id` and `parentId`, enabling in-place branching without creating new files. See [docs/session-format.md](docs/session-format.md) for file format.
+
+### Management
+
+Sessions auto-save to `~/.agent-forge/agent/sessions/` organized by working directory.
+
+```bash
+agent-forge -c                  # Continue most recent session
+agent-forge -r                  # Browse and select from past sessions
+agent-forge --no-session        # Ephemeral mode (don't save)
+agent-forge --name "my task"    # Set session display name at startup
+agent-forge --session <path|id> # Use specific session file or ID
+agent-forge --fork <path|id>    # Fork specific session file or ID into a new session
+```
+
+Use `/session` in interactive mode to see the current session ID before reusing it with `--session <id>` or `--fork <id>`.
+
+### Branching
+
+**`/tree`** - Navigate the session tree in-place. Select any previous point, continue from there, and switch between branches. All history preserved in a single file.
+
+<p align="center"><img src="docs/images/tree-view.png" alt="Tree View" width="600"></p>
+
+- Search by typing, fold/unfold and jump between branches with Ctrl+←/Ctrl+→ or Alt+←/Alt+→, page with ←/→
+- Filter modes (Ctrl+O): default → no-tools → user-only → labeled-only → all
+- Press Ctrl+X to copy the selected message
+- Press Shift+L to label entries as bookmarks and Shift+T to toggle label timestamps
+
+**`/fork`** - Create a new session file from a previous user message on the active branch. Opens a selector, copies the active path up to that point, and places the selected prompt in the editor for modification.
+
+**`/clone`** - Duplicate the current active branch into a new session file at the current position. The new session keeps the full active-path history and opens with an empty editor.
+
+**`--fork <path|id>`** - Fork an existing session file or partial session UUID directly from the CLI. This copies the full source session into a new session file in the current project.
+
+### Compaction
+
+Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.
+
+**Manual:** `/compact` or `/compact <custom instructions>`
+
+**Automatic:** Enabled by default. Triggers on context overflow (recovers and retries) or when approaching the limit (proactive). Configure via `/settings` or `settings.json`.
+
+Compaction is lossy. The full history remains in the JSONL file; use `/tree` to revisit. Customize compaction behavior via [extensions](#extensions). See [docs/compaction.md](docs/compaction.md) for internals.
+
+---
+
+## Settings
+
+Use `/settings` to modify common options, or edit JSON files directly:
+
+| Location | Scope |
+|----------|-------|
+| `~/.agent-forge/agent/settings.json` | Global (all projects) |
+| `.agent-forge/settings.json` | Project (overrides global) |
+
+See [docs/settings.md](docs/settings.md) for all options.
+
+### 联网行为
+
+Agent Forge 不配置默认版本检查上游。只有用户显式设置 `AGENT_FORGE_VERSION_CHECK_URL` 时，才会查询该地址；用 `AGENT_FORGE_SKIP_VERSION_CHECK=1` 或 `AGENT_FORGE_OFFLINE=1` 禁用该可选查询。
+
+---
+
+## Context Files
+
+Agent Forge loads `AGENTS.md` (or `CLAUDE.md`) at startup from:
+- `~/.agent-forge/agent/AGENTS.md` (global)
+- Parent directories (walking up from cwd)
+- Current directory
+
+If a directory contains `AGENTS.override.md`, Agent Forge loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory. Context files from other directories are still concatenated.
+
+Use for project instructions (`AGENTS.md`/`CLAUDE.md`), conventions, common commands. All matching files are concatenated.
+
+Disable context file loading with `--no-context-files` (or `-nc`).
+
+### System Prompt
+
+Replace the default system prompt with `.agent-forge/SYSTEM.md` (project) or `~/.agent-forge/agent/SYSTEM.md` (global). Append without replacing via `APPEND_SYSTEM.md`.
+
+---
+
+## Customization
+
+### Prompt Templates
+
+Reusable prompts as Markdown files. Type `/name` to expand.
+
+```markdown
+<!-- ~/.agent-forge/agent/prompts/review.md -->
+Review this code for bugs, security issues, and performance problems.
+Focus on: {{focus}}
+```
+
+Place in `~/.agent-forge/agent/prompts/`, `.agent-forge/prompts/`, or a [plugin](#plugins) package to share with others. See [docs/prompt-templates.md](docs/prompt-templates.md).
+
+### Skills
+
+On-demand capability packages following the [Agent Skills standard](https://agentskills.io). Invoke via `/skill:name` or let the agent load them automatically.
+
+```markdown
+<!-- ~/.agent-forge/agent/skills/my-skill/SKILL.md -->
+# My Skill
+Use this skill when the user asks about X.
+
+## Steps
+1. Do this
+2. Then that
+```
+
+Place in `~/.agent-forge/agent/skills/`, `~/.agents/skills/`, `.agent-forge/skills/`, or `.agents/skills/` (from `cwd` up through parent directories) or a [plugin](#plugins) package to share with others. See [docs/skills.md](docs/skills.md).
+
+### Themes
+
+Built-in: `dark`, `light`. Themes hot-reload: modify the active theme file and Agent Forge immediately applies changes.
+
+Place in `~/.agent-forge/agent/themes/`, `.agent-forge/themes/`, or a plugin package to share with others. See [docs/themes.md](docs/themes.md).
+
+### Plugins
+
+Plugins bundle optional capabilities such as MCP bridges, CLI tools, Skills, Goal/Plan workflows and multi-Agent orchestration. A plugin is self-describing through `plugin.json` and can be installed, disabled, replaced or removed without modifying the core.
+
+> **Execution model:** Plugins run with the process capabilities available in `readonly` or `full-control`. The core does not provide approval or trust policy; install a policy plugin when that behavior is required.
+
+Create a plugin directory under `~/.agent-forge/agent/plugins/` or `.agent-forge/plugins/`:
+
+```json
+{
+  "id": "example.my-plugin",
+  "version": "0.1.0",
+  "apiVersion": "1-draft",
+  "entry": "./index.ts",
+  "requiredCapabilities": ["tools"]
+}
+```
+
+Capability plugin manifests are validated before loading. See [examples/extensions/](examples/extensions/) for MCP, CLI bridge, Goal/Plan and multi-Agent templates. The pre-plugin `pi` package manifest is supported only as legacy compatibility and is not the recommended extension path.
+
+See [docs/packages.md](docs/packages.md).
+
+---
+
+## Programmatic Usage
+
+### SDK
+
+```typescript
+import { createStableAgentSession, ModelRuntime, SessionManager } from "@agent-forge/agent-forge";
+
+const modelRuntime = await ModelRuntime.create();
+const { facade } = await createStableAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  modelRuntime,
+});
+
+await facade.prompt("What files are in the current directory?");
+```
+
+For advanced multi-session runtime replacement, use `createStableAgentSessionRuntime()` and `CodingAgentRuntimeFacadeV1`. The result has no raw runtime or session on the surface: `runtimeFacade.getSessionFacade()` returns the current session's `CodingAgentFacadeV1` and follows every replacement, so callers re-read instead of caching it. The legacy `createAgentSessionRuntime()` stays available as the lower-level entry.
+
+See [docs/sdk.md](docs/sdk.md) and [examples/sdk/](examples/sdk/).
+
+### RPC Mode
+
+For non-Node.js integrations, use RPC mode over stdin/stdout:
+
+```bash
+agent-forge --mode rpc
+```
+
+RPC mode uses strict LF-delimited JSONL framing. Clients must split records on `\n` only. Do not use generic line readers like Node `readline`, which also split on Unicode separators inside JSON payloads.
+
+See [docs/rpc.md](docs/rpc.md) for the protocol.
+
+### Remote Server (experimental)
+
+Serve the coding-agent session runtime over TCP from the CLI:
+
+```bash
+agent-forge --serve 8787
+```
+
+实验功能，仅适合单用户本机信任环境：监听默认绑定 loopback（`127.0.0.1`），没有默认鉴权，本机任何进程都能驱动该 agent。可用 `--serve-workspace-root <dir>`（可重复）把远程 create 限制在指定目录树内；省略时客户端可提交任意 cwd。
+
+持久化 journal 写入 `<agentDir>/remote-server-journal.jsonl`（默认在 `~/.agent-forge/agent/` 下），不落在进程 cwd。未装配 durable 时 operation 面返回 `durable_unavailable`；完整的 durable 与 executor 装配走 programmatic 入口 `startCodingAgentRemoteServer()`。
+
+用 `@agent-forge/client` 连接：
+
+```typescript
+import { PiClient } from "@agent-forge/client";
+import { createTcpTransportFactory } from "@agent-forge/client/tcp";
+
+const client = new PiClient({
+  transportFactory: createTcpTransportFactory({ host: "127.0.0.1", port: 8787 }),
+});
+await client.connect();
+
+const session = await client.createSession({ cwd: process.cwd() }); // or attachSession(existingId)
+session.subscribe((snapshot) => console.log(`revision ${snapshot.revision}`));
+await session.prompt("What files are in the current directory?");
+```
+
+完整可运行示例（临时端口、快照订阅与优雅关闭）见 [examples/remote-client.ts](examples/remote-client.ts)；客户端 transport、`requestTimeoutMs` 与 `SessionLease` operation 方法的完整说明见 [packages/client/README.md](../client/README.md)。
+
+`prompt`、`attach` 等等待完整 agent turn 的请求是长运行请求：客户端默认 `requestTimeoutMs` 为 5 分钟（300000 ms），这是防挂死兜底而非长任务上限；更长任务可调大该值，设 `0` 完全禁用超时。
+
+---
+
+## Philosophy
+
+Agent Forge 保持可扩展而不规定工作流。其它工具内置的能力都应通过 [插件](#plugins)、[Skills](#skills) 或外部工具接入；这样内核保持最小，工作流由用户塑造。
+
+**No core MCP.** 通过 MCP 插件接入。
+
+**No core multi-Agent workflow.** 通过插件实现编排与生命周期策略。
+
+**No core approval policy.** 如有需要，通过策略插件实现确认、审计或隔离。
+
+**No core Plan mode.** 通过 Goal/Plan 插件实现。
+
+**No built-in to-dos.** They confuse models. Use a TODO.md file, or build your own with [extensions](#extensions).
+
+**No background bash.** Use tmux. Full observability, direct interaction.
+
+完整原则见仓库的 [核心架构宪法](../../docs/核心架构宪法.md)。
+
+---
+
+## CLI Reference
+
+```bash
+agent-forge [options] [--] [@files...] [messages...]
+```
+
+### Package Commands
+
+```bash
+agent-forge install <source> [-l]     # Install package, -l for project-local
+agent-forge remove <source> [-l]      # Remove package
+agent-forge uninstall <source> [-l]   # Alias for remove
+agent-forge update [source|self|agent-forge] # Update Agent Forge or one package source
+agent-forge update --all              # Update Agent Forge and packages
+agent-forge update --packages        # Update packages only
+agent-forge update --models           # Refresh model catalogs only
+agent-forge update --self             # Update Agent Forge only
+agent-forge update --self --force     # Reinstall Agent Forge even if current
+agent-forge update --package <src>   # Update one package
+agent-forge list                      # List installed packages
+agent-forge config                    # Enable/disable package resources
+```
+
+
+### Modes
+
+| Flag | Description |
+|------|-------------|
+| (default) | Interactive mode |
+| `-p`, `--print` | Print response and exit |
+| `--mode json` | Output all events as JSON lines (see [docs/json.md](docs/json.md)) |
+| `--mode rpc` | RPC mode for process integration (see [docs/rpc.md](docs/rpc.md)) |
+| `--export <in> [out]` | Export session to HTML |
+
+In print mode, Agent Forge also reads piped stdin and merges it into the initial prompt:
+
+```bash
+cat README.md | agent-forge -p "Summarize this text"
+```
+
+### Model Options
+
+| Option | Description |
+|--------|-------------|
+| `--provider <name>` | Provider (anthropic, openai, google, etc.) |
+| `--model <pattern>` | Model pattern or ID (supports `provider/id` and optional `:<thinking>`) |
+| `--api-key <key>` | API key (overrides env vars) |
+| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
+| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
+| `--list-models [search]` | List available models |
+
+### Session Options
+
+| Option | Description |
+|--------|-------------|
+| `-c`, `--continue` | Continue most recent session |
+| `-r`, `--resume` | Browse and select session |
+| `--session <path\|id>` | Use specific session file or partial UUID |
+| `--fork <path\|id>` | Fork specific session file or partial UUID into a new session |
+| `--session-dir <dir>` | Custom session storage directory |
+| `--no-session` | Ephemeral mode (don't save) |
+| `--name <name>`, `-n <name>` | Set session display name at startup |
+
+### Tool Options
+
+| Option | Description |
+|--------|-------------|
+| `--tools <list>`, `-t <list>` | Allowlist specific tool names across built-in, plugin, and custom tools |
+| `--exclude-tools <list>`, `-xt <list>` | Disable specific tool names across built-in, plugin, and custom tools |
+| `--no-builtin-tools`, `-nbt` | Disable built-in tools by default but keep plugin/custom tools enabled |
+| `--no-tools`, `-nt` | Disable all tools by default |
+
+Available built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`
+
+### Resource Options
+
+| Option | Description |
+|--------|-------------|
+| `--skill <path>` | Load skill (repeatable) |
+| `--no-skills` | Disable skill discovery |
+| `--prompt-template <path>` | Load prompt template (repeatable) |
+| `--no-prompt-templates` | Disable prompt template discovery |
+| `--theme <path>` | Load theme (repeatable) |
+| `--no-themes` | Disable theme discovery |
+| `--no-context-files`, `-nc` | Disable AGENTS.md and CLAUDE.md context file discovery |
+
+Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings.json (e.g., `--no-skills --no-prompt-templates`).
+
+### Other Options
+
+| Option | Description |
+|--------|-------------|
+| `--system-prompt <text>` | Replace default prompt (context files and skills still appended) |
+| `--append-system-prompt <text>` | Append to system prompt |
+| `--tui-mode <mode>` | TUI mode: `regular` (default) or experimental `fullscreen` |
+| `--use-theme <name[/name]>` | Set the initial interactive theme for this run without changing settings |
+| `--verbose` | Force verbose startup |
+| `--` | Stop option parsing; remaining arguments are prompts or `@file` inputs |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show version |
+
+### File Arguments
+
+Prefix files with `@` to include in the message:
+
+```bash
+agent-forge @prompt.md "Answer this"
+agent-forge -p @screenshot.png "What's in this image?"
+agent-forge @code.ts @test.ts "Review these files"
+```
+
+### Examples
+
+```bash
+# Interactive with initial prompt
+agent-forge "List all .ts files in src/"
+
+# Non-interactive
+agent-forge -p "Summarize this codebase"
+
+# Prompt beginning with a dash
+agent-forge -p -- "- Summarize these points"
+
+# Non-interactive with piped stdin
+cat README.md | agent-forge -p "Summarize this text"
+
+# Named one-shot session
+agent-forge --name "release audit" -p "Audit this repository"
+
+# Different model
+agent-forge --provider openai --model gpt-4o "Help me refactor"
+
+# Model with provider prefix (no --provider needed)
+agent-forge --model openai/gpt-4o "Help me refactor"
+
+# Model with thinking level shorthand
+agent-forge --model sonnet:high "Solve this complex problem"
+
+# Limit model cycling
+agent-forge --models "claude-*,gpt-4o"
+
+# Read-only mode
+agent-forge --tools read,grep,find,ls -p "Review the code"
+
+# Disable one extension or built-in tool while keeping the rest available
+agent-forge --exclude-tools ask_question
+
+# High thinking level
+agent-forge --thinking high "Solve this complex problem"
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AI_AGENT` | CLI 与 RPC 入口设为 `agent-forge`，供通用工具识别启动它的 Agent |
+| `AGENT_FORGE` | CLI 与 RPC 入口设为 `true`，供子进程识别 Agent Forge 运行环境 |
+| `AGENT_FORGE_DIR` | Override config directory (default: `~/.agent-forge/agent`) |
+| `AGENT_FORGE_SESSION_DIR` | Override session storage directory (overridden by `--session-dir`) |
+| `AGENT_FORGE_PACKAGE_DIR` | Override package directory (useful for Nix/Guix where store paths tokenize poorly) |
+| `AGENT_FORGE_OFFLINE` | 禁用可选联网操作，包括用户配置的版本检查地址 |
+| `AGENT_FORGE_SKIP_VERSION_CHECK` | 禁用用户配置的版本检查地址查询 |
+| `AGENT_FORGE_CACHE_RETENTION` | Set to `long` for extended prompt cache (Anthropic: 1h, OpenAI: 24h) |
+| `VISUAL`, `EDITOR` | Fallback external editor for Ctrl+G when `externalEditor` is unset; defaults to Notepad on Windows and `nano` elsewhere |
+
+Commands run by the LLM-callable `bash` and `powershell` tools also receive current session metadata:
+
+| Variable | Description |
+|----------|-------------|
+| `AGENT_FORGE_SESSION_ID` | Current session ID |
+| `AGENT_FORGE_SESSION_FILE` | Absolute session JSONL path; unset for ephemeral sessions |
+| `AGENT_FORGE_PROVIDER` | Currently selected model provider |
+| `AGENT_FORGE_MODEL` | Currently selected model ID |
+| `AGENT_FORGE_REASONING_LEVEL` | Current effective reasoning level |
+
+These values are resolved when each command starts. See [Environment Variables](docs/environment-variables.md#shell-tool-session-environment) for semantics, examples, and custom-tool opt-out.
+
+---
+
+## Contributing & Development
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines and [docs/development.md](docs/development.md) for setup, forking, and debugging.
+
+## License
+
+MIT
+
+## See Also
+
+- [@agent-forge/ai](https://www.npmjs.com/package/@agent-forge/ai): Core LLM toolkit
+- [@agent-forge/agent-core](https://www.npmjs.com/package/@agent-forge/agent-core): Agent framework
+- [@agent-forge/tui](https://www.npmjs.com/package/@agent-forge/tui): Terminal UI components

package/dist/artifacts/artifact-store.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Artifact store (2.6a) — session export artifacts with refs, a bounded
+ * read boundary, and an explicit end-of-life.
+ *
+ * Writers store bytes once and hand out serializable refs (id, session,
+ * operation, kind, media type, size). Readers get the bytes only through
+ * `read`, which is scoped to the owning session; `stat` exposes metadata
+ * only. `endLifecycle` terminates an artifact explicitly: later reads fail
+ * with a structured `ended` error and stats report the terminal state —
+ * nothing is silently deleted or silently kept alive. Renderers and share
+ * transports belong to later slices (2.6b-d).
+ */
+import type { ArtifactRefV1 } from "../core/agent-capability-contract.ts";
+export type { ArtifactRefV1 };
+export interface ArtifactStatV1 {
+    readonly artifactId: string;
+    readonly sessionId: string;
+    readonly operationId: string;
+    readonly kind: string;
+    readonly mediaType: string;
+    readonly sizeBytes?: number;
+    readonly state: "available" | "ended";
+    readonly endReason?: string;
+}
+export interface ArtifactStoreV1 {
+    write(input: {
+        readonly sessionId: string;
+        readonly operationId: string;
+        readonly kind: string;
+        readonly mediaType: string;
+        readonly bytes: Uint8Array;
+    }): {
+        readonly ref: ArtifactRefV1;
+    };
+    read(input: {
+        readonly artifactId: string;
+        readonly sessionId: string;
+    }): {
+        readonly mediaType: string;
+        readonly bytes: Uint8Array;
+    };
+    stat(artifactId: string): ArtifactStatV1 | undefined;
+    list(sessionId: string): readonly ArtifactStatV1[];
+    endLifecycle(artifactId: string, input: {
+        readonly reason: string;
+    }): ArtifactStatV1;
+}
+export declare function createArtifactStore(options?: {
+    readonly now?: () => number;
+}): ArtifactStoreV1;
+//# sourceMappingURL=artifact-store.d.ts.map