bismarck-engine

The agent engine of Bismarck: a Go implementation of pi (Mario Zechner, MIT) — pi’s unified LLM API, agent loop and coding agent, with pi’s extensions for MCP and agents — embedded as a library, with no Node.js runtime.

Origin

• The code started on 2026-10-15 from sky-valley/pi, a Go port of pi (MIT), at commit 1067024e7cce0028602e638bbf6676c6d2883cda (pi 0.99.2, pi source 5806068c2); its copyright stands in LICENSE. The history up to v0.1.0 is squashed into one commit; docs/UPSTREAM.md records the base and the sync ledger.
• This is an independent project, not a fork. The source of changes is pi itself. New pi commits are ported here directly; the sky-valley port is a reference while it is maintained, never a dependency.
• Scope tracked from pi: agent (pi-agent-core), ai (core and the OpenAI-compatible provider), coding (sessions, tools, compaction), and pi’s extensions for MCP and agents.
• pi removed its server, client and protocol packages on 2026-10-12 (7472cda0); the Go versions here no longer have an upstream.
• Each sync is planned in docs/sync-.md; commits that port pi say so: port(area): … (upstream ).

Layout

difftest/ is the differential harness: for identical inputs it captures the HTTP request body that real pi builds and the one this code builds, and diffs them. pi is ground truth. It is a separate Go module and is not part of the library.

Build and test

go build ./...
go test ./...          # live-API tests skip without keys
go build -o pi ./cmd/pi

CI runs gofmt, go vet and go test on Linux and Windows, and the race detector over the concurrent parts (codemode, MCP, nested tool calls, the tool registry) on Linux. The module’s dependencies are the standard library, golang.org/x/{image,text} and github.com/tetratelabs/wazero (Apache-2.0, pure Go, for codemode); internal/policy enforces the list.

Using the library

import (
    "github.com/aleksandrgradoboev-svg/bismarck-engine/ai"
    "github.com/aleksandrgradoboev-svg/bismarck-engine/coding"
)

// An OpenAI-compatible endpoint (a LiteLLM gateway, for example) needs no catalog entry.
model := &ai.Model{
    ID: "my-model", Api: ai.APIOpenAICompletions, Provider: "litellm",
    BaseURL: "https://gateway.example/v1", ContextWindow: 128000, MaxTokens: 8000,
}
sess := coding.NewSession(coding.SessionOptions{
    Model:          model,
    APIKey:         os.Getenv("LLM_API_KEY"),
    SystemPrompt:   "…",
    NoTools:        coding.NoToolsBuiltin, // or ToolNames: []string{"read"}
    CustomTools:    []agent.AgentTool{myTool},
    NoContextFiles: true,                  // a server must not pick up AGENTS.md from its directories
    NoSkills:       true,                  // nor skills from the home directory
    SkillPaths:     []string{"/srv/skills"},
    Compaction:     &coding.DefaultCompactionSettings,
})
res, err := sess.Run(ctx, "question")
// res.Text, res.ToolCalls, res.Messages, res.StopReason, res.Usage

sess.Subscribe streams events; mid-session SetModel, SetThinkingLevel, Steer, FollowUp, Continue and Abort are available, and sessions persist and resume through coding.StartSession / coding.LoadSessionTree. A runnable example is in examples/sdk.

MCP servers come from an mcp.json in the mcpServers format other MCP clients share. Register the codemode and tool_search tools first — the servers’ tools are reached through codemode by default — then bind a server manager to the session:

loaded := mcpext.LoadConfig("mcp.json", cwd, false)
manager := mcpext.NewManager(mcpext.ManagerOptions{Config: loaded, Cwd: cwd})
sess.RegisterTools(
    codemodetool.Definition(codemodetool.Options{Session: sess, Store: &codemodetool.Store{}}),
    toolsearch.Definition(sess),
)
unbind := mcpext.Bind(sess, manager, mcpext.BindOptions{Warn: log.Println})
manager.Start()
defer func() { unbind(); manager.Close() }()

Bind registers the servers’ tools as they connect, activates codemode or tool_search when the servers’ exposures need them, lists the servers in the mcp_servers prompt section, and makes calls wait for the servers they need.

The built-in providers register themselves when coding is imported. Using ai alone, blank-import them: import _ "github.com/aleksandrgradoboev-svg/bismarck-engine/ai/providers".

Differences from pi

• Provider attribution headers (HTTP-Referer: https://pi.dev, X-OpenRouter-Title, x-opencode-*) are sent only when PI_TELEMETRY is truthy; pi sends them by default.
• The grep tool reports model-facing paths with forward slashes on every OS.
• Project-local resources under /.pi load only with SessionOptions.TrustProject, pi’s answer for a host with no UI to ask the user.
• MCP calls wait for their servers in a session tool gate that runs before the tool executes (Session.AddToolGate), not in a tool_call hook: hooks run under the agent loop’s tool lock, and a wait there would stall the rest of a parallel batch.
• codemode’s store() keeps its values in memory for the session; pi writes them to the session file per branch.
• Not ported: the interactive TUI and its host layer, the JavaScript extensions runtime (pi’s built-in extensions are wired in Go instead), codemode’s models.* script globals (classifiers and image generation), MCP OAuth sign-in, and the wire APIs that would need a further third-party dependency (AWS Bedrock SigV4 and eventstream, OpenAI Codex WebSocket with zstd).

License

MIT. See LICENSE: this project’s notice, sky-valley’s and pi’s.