ed026ac6c8
McpProcess starts a server through the SDK stdio client under the startup timeout and keeps a stderr tail for its errors. McpCatalogCache runs one shared discovery per server config in a temp dir, with the environment from the process spawn policy. It keeps successes for the process lifetime and failures for 60 s. Deviation from the plan: the discovery process is disposed and its temp dir deleted in the background, after the catalogue is returned. SDK 2.2 waits the whole ShutdownTimeout (5 s) with stdin still open before it kills the process, so an awaited dispose held every first activation for 5 s. A new test (Discovery_returns_without_waiting_for_the_server_shutdown) covers this. Spec section 3 gets the new GetAsync signature, the detached discovery and the background cleanup. Section 5 now describes the SDK's shutdown order correctly.
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).