docs: user documentation and headless sample host

2026-09-25 12:36:24 +00:00
parent c220428cb7
commit 018c92af49
7 changed files with 879 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,93 @@
 # VolcanicAgenticCore

+A headless, extensible agent harness for .NET, modelled on [earendil-works/pi](https://github.com/earendil-works/pi).
+It keeps the parts of pi that make it *extensible* and *provider-agnostic* and leaves out the terminal UI,
+so you can put any front end on top (a Telegram bot is the intended first one).
+
+It also ships a C# port of [chem/pi-claude-code-provider](https://github.com/chem/pi-claude-code-provider):
+an extension that drives the locally installed `claude` CLI on a Claude subscription, so the core can use
+Claude Code as a model provider without an API key.
+
+## What you get
+
+| Piece | Where | Notes |
+|---|---|---|
+| Contracts for extensions, providers, tools, sessions, UI | `src/Volcanic.AgenticCore.Abstractions` | The only assembly an extension needs to reference |
+| Runtime (vertical slices) | `src/Volcanic.AgenticCore` | Agent loop, sessions, models, tools, extensions, commands, compaction, system prompt, hosting |
+| Anthropic Messages API provider | `extensions/Volcanic.AgenticCore.Extensions.Anthropic` | `ANTHROPIC_API_KEY` |
+| OpenAI-compatible provider | `extensions/Volcanic.AgenticCore.Extensions.OpenAI` | OpenAI, OpenRouter, Groq, Ollama, llama.cpp, vLLM |
+| Claude Code (subscription) provider | `extensions/Volcanic.AgenticCore.Extensions.ClaudeCode` (+ `.Bridge`) | Spawns `claude -p`, MCP "proposal" bridge |
+| Reference headless host | `samples/Volcanic.AgenticCore.Sample.Headless` | Prompt in, JSON events out |
+| Tests | `tests/` | xunit; no test calls a paid API |
+
+## Quick start
+
+```bash
+dotnet build
+dotnet test
+
+# run the reference host with the scripted faux provider (no keys needed)
+dotnet run --project samples/Volcanic.AgenticCore.Sample.Headless -- --faux "Say hello"
+
+# with a real provider
+ANTHROPIC_API_KEY=sk-ant-... dotnet run --project samples/Volcanic.AgenticCore.Sample.Headless -- --model anthropic/claude-sonnet-4-5 "List the files here"
+
+# with a Claude subscription through the claude CLI
+dotnet run --project samples/Volcanic.AgenticCore.Sample.Headless -- --model claude-code/sonnet "List the files here"
+```
+
+Hosting it yourself:
+
+```csharp
+var services = new ServiceCollection();
+services.AddAgenticCore(o =>
+{
+    o.DefaultModel = "anthropic/claude-sonnet-4-5";
+    o.AddExtension<AnthropicProviderExtension>();
+    o.AddExtension<OpenAIProviderExtension>();
+    o.AddExtension<ClaudeCodeProviderExtension>();
+});
+var factory = services.BuildServiceProvider().GetRequiredService<IAgentSessionFactory>();
+
+await using var session = await factory.CreateAsync(new AgentSessionOptions { Cwd = "/path/to/project" });
+session.Subscribe(e =>
+{
+    if (e is AgentSessionEvent.MessageUpdate { AssistantMessageEvent: AssistantMessageEvent.TextDelta d }) Console.Write(d.Delta);
+});
+await session.PromptAsync("Explain this repository");
+```
+
+## Documentation
+
+- [Architecture](docs/architecture.md): projects, vertical slices, the agent loop and the event model.
+- [Writing extensions](docs/extensions.md): tools, commands, lifecycle hooks, providers, message injection, discovery.
+- [Providers and models](docs/providers.md): model keys, authentication, the built-in provider extensions.
+- [Building a UI (Telegram guide)](docs/ui-integration.md): how to put a chat front end on the core.
+- [Claude Code provider](docs/claude-code-provider.md): requirements, how the bridge works, limits, the doctor command.
+- Design spec and plan: `docs/superpowers/specs/`, `docs/superpowers/plans/`.
+
+## Layout of the agent directory
+
+Everything the runtime writes lives under `~/.volcanic/agent` (override with `VOLCANIC_AGENT_DIR` or `AgenticCoreOptions.AgentDir`):
+
+```
+~/.volcanic/agent/
+  sessions/<scope>/<session-id>.jsonl   one JSONL file per session
+  extensions/*.dll                      extension assemblies discovered at start
+  auth.json                             { "anthropic": { "apiKey": "sk-..." } }
+  settings.json                         { "extensions": ["path/to/Ext.dll"] }
+```
+
+A project can add `.volcanic/extensions/*.dll` and `.volcanic/settings.json` in its working directory.
+
+## Status
+
+Ported from pi: agent loop with parallel tool execution, steering and follow-up queues, abort, auto-retry,
+overflow recovery and threshold compaction; JSONL session trees with resume and branching; the extension
+event model; slash commands; provider registration; API key resolution; built-in `read`, `write`, `edit`,
+`bash`, `ls`, `grep`, `find` tools; system prompt assembly with `AGENTS.md`/`CLAUDE.md` project context.
+
+Not ported (by design): the terminal UI, themes, keybindings, renderers, skills and prompt templates,
+OAuth logins, image generation models, session tree navigation commands.
+
+License: MIT. Fixtures under `tests/.../ClaudeCode/Fixtures` are from pi-claude-code-provider (MIT).