Skip to content

All guides and decisions

For a first run, follow Run your first tool call. For package-level references, see the repository documentation.

Start here

Document Purpose
Concepts How agent, adapters, catalog, dials, tools, RAG, evals and durable runs fit together; vendors, runtimes and adapters
Message parts Part kinds per role, sources and locators, sending each modality, part deltas and the aggregator, wire versions 1 and 2, persistence and externalized media
Deployment One PostgreSQL 18 server with pgvector and pg_search, migrations, hybrid search, licensing

Models and configuration

Document Purpose
Model catalog and presets Catalog JSON schema, sources and layers, merge rules, precedence, validation, building a preset, CLI
Dials Model-neutral creativity, reasoning depth, max output, tools, seed, cache and modality, compiled per model
Modality conversion Media a model cannot take: reject by default, or convert, transcribe, describe, extract or omit; scopes, routing, memoization, budget, reports
Model capabilities Capability declarations, tool and cost handling per vendor, and the gaps that remain open

Tools and orchestration

Document Purpose
Tool calling Tool call lifecycle, client and server tools, parallel and sequential execution, tool choice, where each knob lives
Harness tools The built-in toolset: file, code, and fetch tools, sandboxes, approvals, spill, CLI --tools
Typed function tools agent.Func, RunContext, schema-hash versions, agent.AIFunc
Nullable tool properties Optional and nullable parameters across vendor APIs and MCP
Handoffs and subagents Handoff vs delegate vs spawn: context in, data out, transcripts, size and iteration limits, sub-agent budgets, scratch, and references
Orchestration policies Conversation ownership, subagent results, handoff return links, sticky routing, approval limits
Context management Compaction strategies, chains, triggers, summary budget, records, per-agent policy and handoff groups
Agent definitions An agent as a versioned Markdown file: format, sources and trust, resolution and pinning, binding, CLI and MCP server
Harnesses Running a saige agent in Claude Code, Codex, Gemini CLI, opencode, Cursor and ACP editors: export, launch, acp, held approvals
Approval policy and grants Grants by scope and expiry, denial limits, capability defaults, replay
Run hooks Lifecycle events that observe, change or abort a run; ordering, timeouts, durable replay, inheritance
Guardrails Input and output checks that pass, block or rewrite; parallel mode, tripwires, built-ins, budget, relation to gates and redaction
MCP client Pooled sessions, retries, drift detection, .mcp.json loading
Memory Host scope, approval-gated writes, recall modes, Postgres hybrid recall, conversation recall, retention, post-run extraction

Runs, caching and operations

Document Purpose
Batch processing Vendor batch APIs at half price, the local fallback, durable jobs, budget, evals, agent.RunBatch
Durable execution Local engine and anchor on Postgres, saved approvals, uncertain steps, reconciliation, budget receipts
Durable engine durable/: ledger, queue, worker and replay, the Postgres adapters, capabilities
Flow flow/: events on a channel bus and the durable turn: stopping, compaction, usage, parking
Event union The envelope, types and catalog, channels, definitions and pins, the Runtime seam
Agent sessions Session keys, child calls, governance, budgets
Slack connector What Slack publishes, references, delivery, stopping a session
GitHub connector Webhooks, mentions, reviews (never approvals), check runs, credentials
GitHub feedback Reactions, replies, resolutions and suggestions as feedback; review recovery
Sandbox sandbox/: confined tools, NGAC, pools, isolated instances, the egress gate
Replay design Record identity, the claim protocol, failure modes, park and resume
Cache contracts Cache identity, provider cache modes, known limits
Observability OpenTelemetry spans and metrics, error attributes, redaction
Print a conversation tree tree.Print: one JSON document with nodes, branches, checkpoints and metadata
Load and concurrency testing The stress build tag, Postgres and live burst tests, -cpu benchmarks, nightly workflow

Changes

Document Purpose
Upgrade notes Upgrading to this release: breaking changes, ordered migration steps, renamed symbols, stored data, wire clients and catalogs
System hardening What the hardening release changed and how each fix was verified

Decisions

These decisions describe saige's orchestration and cache boundaries. See the API guide and the cache audit for examples and known limits. Each ADR was first recorded as D-NN in DESIGN_DECISIONS.md; ADR 00NN is D-NN, and code comments and docs still cite them by that name.

ADR Title Status
0001 Keep branches separate from workers Accepted
0002 Make delegation a call-and-return contract Accepted
0003 Treat handoff as ownership transfer Accepted
0004 Add direct return links by default Accepted
0005 Select complete model configurations Accepted
0006 Separate cache contracts Accepted
0007 Default to private response-cache identity Accepted
0008 Keep policies separate Accepted
0009 Reserve budget before dispatch Accepted
0010 Save approvals and release local workers Accepted
0011 Fail closed on handoff compaction Accepted
0012 Reject unsupported request controls Accepted
0013 Own catalog snapshots at the boundary Accepted
0014 Keep uncertain effects explicit Accepted
0015 Copy cache values at ownership boundaries Accepted
0016 Use a local engine before a distributed scheduler Accepted
0017 Allow one run per branch Accepted
0018 Contain tool failures in the tool result Accepted
0019 Rank composed gate verdicts Accepted
0020 Bound delegations separately from tools Accepted
0021 Apply response schemas to the final answer Accepted
0022 Compact on input pressure and never drop context silently Accepted
0023 Commit truncated turns, never their tool calls Accepted
0024 Force behavior for one turn and bound unproductive loops Accepted
0025 Join active runs only at safe points Accepted
0026 Escalate on outcomes through the tree Accepted
0027 Disclose tools by search, permit them by gate Accepted
0028 Skills supply content and never grant permission Accepted
0029 Spawn background children with handles Accepted
0030 Address every decision as an interrupt Accepted
0031 Swap personal data for placeholders at the tool boundary Accepted
0032 Address scratch artifacts by content Accepted
0033 Scope memory by host, write it by approval Accepted
0034 Keep shadow traffic out of the caller's run Accepted
0035 Keep the wire format a stable contract Accepted
0036 Report malformed tool arguments to the model, truncated ones to the caller Accepted
0037 Declare presets as data and validate every chain entry Accepted
0038 Let approvals grant scope, and record every grant Accepted
0039 Give hooks one seam and record what they change Accepted
0040 Guard the conversation's edges, gate the tools Accepted
0041 Compose compaction strategies and record every compaction Accepted
0042 Save a batch job before submitting it, and batch single turns only Accepted
0043 Define an agent as a versioned file and pin what a run resolves Accepted
0044 Messages are ordered typed parts Accepted
0045 Convert the view, never the record; reject by default Accepted
0046 An offering is a model on an endpoint, and its parameters are data Accepted
0047 Never take a vendor file ID from an untrusted client Accepted
0048 Host an agent in other harnesses through one session layer Accepted