OpenProgram Docs
Design Documents#
Current design notes for OpenProgram, grouped by subsystem to mirror the code
layout under openprogram/. Read this index first, then the doc you need.
Each subdirectory collects the designs for one area. Within a group, the doc that defines the current implementation is listed first; the rest are supporting notes / investigations that should not override it.
context/ — context engine, commits, tool aging#
| Doc | Topic |
|---|---|
context/overview.md |
Context layer: pipeline + DAG storage + ContextCommit + compaction/render + attach/merge + cross-turn tool + gaps |
context/composition.md |
Target state: per-call layering (L0/L1/L2) + situational context |
context/comparison.md |
Context approaches compared against reference projects |
context/context-compaction.html |
Context compaction (rendered) |
memory/ — memory system (entity + abstract)#
| Doc | Topic |
|---|---|
memory/README.md |
Memory system overview: architecture, design principles, implementation status |
memory/overview.md |
Memory subsystem: entity/virtual two-tier + provenance-navigated recall, and the chain running today (visualization) |
memory/entity-memory.md |
Entity memory: Session-Git + Project-Git, organized by lifecycle |
memory/git-as-entity-memory.md |
Entity memory on Git: Session-Git + Project-Git |
memory/virtual-memory.md |
Abstract memory: Timeline + Graph + Core, organized by type × lifecycle |
proactive/ — event layer + proactivity (event-driven)#
Two parts: the event base (one unified event stream for the whole framework) and proactivity applications (rules subscribe to the stream and act). They are decoupled, so the base is usable alone. Read event-layer first for the overall picture.
Event base:
| Doc | Topic |
|---|---|
proactive/event-layer.md |
Unified Event model, framework placement, diagram, event boundaries (landed: class A/B events all emitted, gate can block, visualization) |
proactive/framework-evolution.md |
Framework evolution: current → target → five migration steps (steps 1·2·3 done, visualization) |
Proactivity applications (built on the base):
| Doc | Topic |
|---|---|
proactive/overview.md |
One scenario end to end (blocking rm -rf), introducing rules / actions / state in place |
proactive/events-and-state.md |
How state folds out of events — why a rule can remember the past |
proactive/execution-model.md |
How to write a Policy; blocking vs observing rules |
proactive/policies-mvp.md |
Three sample rules to copy when writing new ones |
proactive/invariants.md |
Invariants the framework itself must hold (chiefly: no feedback loops) |
Paper/production-grade material (offline replay validation, adversarial safety, evaluation skeleton) is archived under
proactive/_research_archive/.
runtime/ — agent execution, DAG, async, revert, controllability#
| Doc | Topic |
|---|---|
runtime/overview.md |
Runtime API behaviour (see also ../api/runtime.md) |
runtime/operations/user-input-requests.md |
User input via runtime.ask/confirm |
runtime/controllability-and-three-surface-sync.md |
Attended/unattended toggle, mid-run intervention, graceful stop, three-surface sync |
runtime/p3-three-surface-sync.md |
P3 three-surface sync implementation detail |
runtime/unified-session-context.md |
Unified session context |
runtime/execution/agent-worktree.md |
Agent worktree behaviour |
runtime/execution/async-task-lifecycle.md |
Async task lifecycle |
runtime/agent-resource-governance.html |
Agent runtime quotas and task lifecycle governance: current implementation audit, reference comparison, admission, budgets, recovery, visibility, and implementation gates |
runtime/operations/streaming-resume.md |
Streaming + resume |
runtime/operations/file-management.md |
Revert layers (commit / worktree) |
runtime/operations/multi-agent-revert-todo.md |
Multi-agent revert TODO |
runtime/dag/overview.md |
authoritative Session DAG data model (one graph / 3 node roles user·llm·code / caller+predecessor edges / spawn / rendering / assembly / compaction) |
runtime/dag/rendering.md |
authoritative rendering spec: layout / edges / legend / default visibility, 12 scenarios |
runtime/dag/branch-collaboration.md |
Branch collaboration (communication / dispatch / merge) design and implementation steps |
runtime/execution/dispatcher-split.md |
Dispatcher split design |
runtime/execution/next-step-decision.md |
Next-step decision (how the model picks what runs next) |
runtime/execution/agentic-self-recursion.md |
Agentic self-recursion (rendered) |
runtime/operations/rewind.md |
Rewind |
runtime/operations/branch-naming.md |
Branch naming (rendered) |
runtime/session/README.md |
Session subsystem: data model, storage, naming, listing, lifecycle |
runtime/self-update.md |
Self-update: staying usable while OpenProgram modifies itself |
runtime/permission-model.md |
Permission system design |
runtime/sandbox.md |
Sandbox: the boundary on both platforms, where the switch is lost, coverage, how eight reference harnesses compare, repair order (rendered) |
runtime/ssrf-protection.html |
Outbound URL and SSRF design: current gaps, Hermes/OpenClaw/OWASP comparison, scoped trust policy, transport requirements, and full acceptance gates |
runtime/agent-collaboration.md |
Agent collaboration: cross-branch communication primitives (tool surface, eight reference implementations compared) |
runtime/agent-resource-governance.html |
Agent resource governance: current implementation, framework comparison, durable scheduling and enforceable budget plan |
runtime/tool-toggle-management.md |
Tool toggles / toolset management design |
runtime/additional-working-directories.md |
Multiple working directories per session |
providers/ — LLM providers, credentials, model catalog, thinking/effort#
| Doc | Topic |
|---|---|
providers/request-build.md |
Request build pipeline |
providers/models/overview.md |
Model catalog, final design |
providers/models/thinking-effort.md |
Thinking / effort subsystem (level definitions, data flow, per-provider wire formats, UI picker) |
providers/models/fast-tier.md |
The Fast tier: two-tier detection, storage, wires |
providers/auth/claude-code-direct-oauth.md |
claude-code direct subscription auth (Meridian dropped) |
providers/auth/credential-validation-unification.md |
Unified credential validation |
providers/auth/unified-auth-storage.md |
Unified auth storage |
providers/auth/unified-account-management.md |
Unified account management + rotation |
providers/auth/credential-file-hardening.html |
File credential persistence hardening: current inventory, user-flow risks, atomic private-write contract, backup/restore boundary, and implementation gates |
providers/auth/credential-status-redesign.md |
Credential status |
providers/auth/api-key-resolution-unification.md |
API key resolution unification |
providers/reliability/error-retry.md |
Error + retry handling |
providers/reliability/error-taxonomy-propagation.md |
Error taxonomy + propagation |
providers/reliability/llm-fault-tolerance.md |
LLM fault tolerance (investigation) |
providers/reliability/error-and-timeout-mechanism.html |
Error + timeout mechanism (rendered) |
providers/network-proxy.md |
Outbound network proxy |
providers/auth/credential-connection-unification.md |
Credential/connection unification |
providers/PROBLEM-models-and-bailian.md |
Model list and the Bailian provider |
function/ — function & tool calling#
| Doc | Topic |
|---|---|
function/calling-unification.md |
Tool/function calling framework (current) |
Authoring-facing docs (
@agentic_functionusage, function metadata, tool-calling loop, next-step decision, pure-python helpers) moved to the user guide at../agentic-programming/README.md.
cli/ — CLI / TUI, slash commands, ports#
| Doc | Topic |
|---|---|
cli/redesign.md |
CLI / TUI redesign (schema-driven settings, config panel) — current |
cli/ports.md |
Web UI port (config surface, conflict handling) |
cli/slash-commands.md |
Slash commands |
cli/slash-commands-references.md |
Slash-command reference snapshot |
cli/drop-run-command.md |
Function execution path from the Web UI |
cli/naming.md |
CLI naming |
cli/single-port.md |
Single-port architecture |
cli/config-write-safety.md |
Config write safety — atomic update_config |
cli/tui-upgrade.md |
TUI upgrade |
channels/ — messaging channels#
| Doc | Topic |
|---|---|
channels/design.md |
Channel design (current) |
channels/audit.md |
Channel audit / reference snapshot |
ui/ — surfaces, indicators, attachments, GUI agent#
| Doc | Topic |
|---|---|
ui/invariants.md |
Cross-module UI invariants |
ui/chat-turn-visual-spec.html |
Chat-turn visual spec (execution timeline + manual runs + message minimap) |
ui/interaction-feedback.md |
The 0ms interaction-feedback rule |
ui/surface-system.md |
Surface system |
ui/indicator-dots.md |
Indicator dots |
ui/attachment-handling.md |
Attachment handling (rendered) |
ui/composer-interaction-modes.md |
Composer interaction modes |
ui/gui-agent-context.md |
GUI agent context flow |
ui/state-layer.md |
Web state layer: per-session vs global stores, session-scope container plan |
ui/project-workspace.md |
Project workspace — files, tabs, multi-session (prototype) |
integrations/ — MCP, skills/plugins, harness standard#
| Doc | Topic |
|---|---|
integrations/harness-standard.md |
Harness standard (plug-in + auto-detect); install: ../installing-harnesses.md |
integrations/mcp-integration.md |
MCP integration |
integrations/skills-and-plugins.md |
Skills and plugins |
extension-gating/#
Extension gating design + reference comparison — see
extension-gating/README.md.
Cross-cutting#
| Doc | Topic |
|---|---|
usage-metering.md |
Usage subsystem (token/cost accounting, ledger, collection point, subprocesses, consumers) |
framework-overview.md |
Framework overview: one conversation from input to output |
framework-comparison.html |
Whole-framework comparison against twelve reference implementations by design axis: where we lead, where we lag, and what they have that we never considered (rendered) |
feature-matrix.html |
The same twelve implementations scanned by feature list instead of design axis: 160 user-facing features in one grid, what only they have, what only we have (rendered) |
docs-site.md |
The documentation site itself (build, nav, bilingual routing) |
research/ — investigations#
| Doc | Topic |
|---|---|
research/execution-trace-model-selection.md |
Choosing the data model for agent execution traces (span concept, what's novel) |
plans/ — dated implementation plans#
| Doc | Topic |
|---|---|
plans/proactive-implementation.md |
Proactive layer implementation plan |
plans/cache-control-passthrough.md |
Per-block passthrough of Anthropic cache_control (landed) |
plans/2026-07-08-credential-connection-unification.md |
Credential/connection unification migration |
Removed docs#
There is no archive/ directory: superseded docs were deleted outright rather
than moved aside. Recover them from git history if needed.
Previously removed:
model-catalog-dynamic.md/model-catalog-per-provider.md— iteration drafts, superseded bymodels.mdclaude-code-meridian-profile.md— the Meridian proxy was dropped; purely historical*-references.md— investigation snapshots / raw research notes (slash-commands / tui-upgrade / user-input-requests)
TODO-doc-code-gaps.md#
TODO-doc-code-gaps.md — Places where the docs and the code disagree, ordered by priority. Delete an entry once it is fixed.
Conventions#
- One subdirectory per subsystem, mirroring
openprogram/. New design docs go into the matching group, not the flat root. Add a group when a topic grows past a couple of files. - Each group lists the current source first; supporting notes follow.
- API reference belongs under
docs/api/; design rationale belongs here. - For function-authoring rules,
../agentic-programming/writing-functions/function-metadata.mdis the source of truth — shorter files link to it rather than repeating it. - The decorator field is
render_range={"callers": N, "subcalls": M}—callerscaps pre-frame nodes by seq,subcallscaps in-frame nodes by seq. Both code and docs use these names exclusively.
Last updated · 2026-08-13