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 |