83ad683bd1
McpServerConnection starts the session's server lazily through PrepareProcessAsync, applies the call timeout, reports exits with the stderr tail and restarts on the next call, stops when idle, and supports StopAsync (reusable) and idempotent DisposeAsync. McpTool exposes a catalogue entry as an ITool and maps results with McpResultMapper. Spec change (§5, Decisions): ModelContextProtocol.Core 2.2.0 does not send notifications/cancelled when a request's token fires (verified against the fake server), so calls go out through SendRequestAsync with their own request id and the connection sends notifications/cancelled itself on abort and timeout. Also documents exit detection, StopAsync vs DisposeAsync and JSON-RPC errors as ordinary error results, per the plan.
VolcanicAgenticCore
A headless, extensible agent harness for .NET, modelled on 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 ships as the first one.
It also ships a C# port of 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 |
| Telegram bot | hosts/Volcanic.AgenticCore.Telegram |
Chat with the agent from Telegram; long polling, Claude Code, allow-list |
| Reference headless host | samples/Volcanic.AgenticCore.Sample.Headless |
Prompt in, JSON events out |
| Tests | tests/ |
xunit; no test calls a paid API |
Quick start
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-opus-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"
# the Telegram bot (see docs/telegram-bot.md)
TELEGRAM_BOT_TOKEN=123:abc TELEGRAM_ALLOWED_USER_IDS=111111111 dotnet run --project hosts/Volcanic.AgenticCore.Telegram
Hosting it yourself:
var services = new ServiceCollection();
services.AddAgenticCore(o =>
{
o.DefaultModel = "anthropic/claude-opus-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: projects, vertical slices, the agent loop and the event model.
- Writing extensions: tools, commands, lifecycle hooks, providers, message injection, discovery.
- Providers and models: model keys, authentication, the built-in provider extensions.
- Telegram bot: setup, commands, security, connection recovery.
- Building a UI (Telegram guide): how to put a chat front end on the core.
- Claude Code provider: requirements, how the bridge works, limits, the doctor command, automatic re-login when the subscription session expires.
- 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 (or, if absent, CLAUDE.md) project context.
Beyond pi: the working directory may also hold PERSONA.md (the agent's personality) and MEMORY.md (memories
the agent maintains itself with edit/write); both are appended to the system prompt when present. File names
match case-insensitively.
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).