LibraLibra
LibraLibra
DocsBlogLibra
Getting Started
Architecture
Design
IntentSpec DesignAI Object Model ReferenceAgent Workflow: From Intent to ReleaseAI Object Model Reference
Commands
API Reference
Policy
Design

AI Object Model Reference

Consolidated reference for Libra Agent object model and boundaries

AI Object Model Reference

This document is the consolidated reference for the current Libra Agent design.

Core Boundary

git-internal: immutable facts
Libra: current state / scheduling state / index projections

The system is split into three layers:

  • git-internal snapshot objects answer: "what was defined at this revision?"
  • git-internal event objects answer: "what happened later?"
  • Libra projections answer: "what is the current operational view?"

Mutable runtime coordination must not be implemented by rewriting snapshot objects.

Layer Model

+--------------------------------------------------------------------------------------+
|                                      Libra [L]                                       |
|--------------------------------------------------------------------------------------|
| Thread / Scheduler / UI / Query Index                                                |
|                                                                                      |
|  current_intent_id                                                                   |
|  latest_intent_id                                                                    |
|  selected_plan_id                                                                    |
|  current_plan_heads[]                                                                |
|  active_task_id / active_run_id                                                      |
|  live_context_window                                                                 |
|  reverse indexes: intent->plans, task->runs, run->events, run->patchsets, ...       |
+--------------------------------------------+-----------------------------------------+
                                             |
                                             v
+--------------------------------------------------------------------------------------+
|                               git-internal : Event [E]                               |
|--------------------------------------------------------------------------------------|
|  IntentEvent / TaskEvent / RunEvent / PlanStepEvent / RunUsage                       |
|  ToolInvocation / Evidence / Decision / ContextFrame                                 |
|                                                                                      |
|  Rule: append-only execution facts and audit records                                 |
+--------------------------------------------+-----------------------------------------+
                                             |
                                             v
+--------------------------------------------------------------------------------------+
|                              git-internal : Snapshot [S]                             |
|--------------------------------------------------------------------------------------|
|  Intent / Plan / Task / Run / PatchSet / ContextSnapshot / Provenance                |
|                                                                                      |
|  Rule: immutable definitions and revisioned structure                                |
+--------------------------------------------------------------------------------------+

Placement Rules

Snapshot objects in git-internal

  • Intent
  • Plan
  • Task
  • Run
  • PatchSet
  • ContextSnapshot
  • Provenance

Event objects in git-internal

  • IntentEvent
  • TaskEvent
  • RunEvent
  • PlanStepEvent
  • RunUsage
  • ToolInvocation
  • Evidence
  • Decision
  • ContextFrame

Projection and runtime state in Libra

  • Thread
  • Scheduler
  • UI-facing current view
  • query indexes and reverse indexes
  • live context window
  • ready queue / parallel groups / checkpoints / retry routing

Main Relationship Graph

Snapshot layer
==============

Intent[S] --parents------------------------> Intent[S]
Intent[S] --analysis_context_frames-------> ContextFrame[E]
Plan[S]   --intent_id----------------------> Intent[S]
Plan[S]   --parents------------------------> Plan[S]
Plan[S]   --context_frames-----------------> ContextFrame[E]
Task[S]   --intent_id?---------------------> Intent[S]
Task[S]   --parent_task_id?----------------> Task[S]
Task[S]   --origin_step_id?---------------> Plan[S].step_id
Task[S]   --dependencies-------------------> Task[S]
Run[S]    --task_id------------------------> Task[S]
Run[S]    --plan_id?-----------------------> Plan[S]
Run[S]    --context_snapshot_id?-----------> ContextSnapshot[S]
PatchSet[S]   --run_id---------------------> Run[S]
Provenance[S] --run_id---------------------> Run[S]

Event layer
===========

IntentEvent[E]   --intent_id---------------> Intent[S]
IntentEvent[E]   --next_intent_id?---------> Intent[S]
TaskEvent[E]     --task_id-----------------> Task[S]
RunEvent[E]      --run_id------------------> Run[S]
RunUsage[E]      --run_id------------------> Run[S]
PlanStepEvent[E] --plan_id-----------------> Plan[S]
PlanStepEvent[E] --step_id-----------------> Plan[S].step_id
PlanStepEvent[E] --run_id?-----------------> Run[S]
ToolInvocation[E] --run_id-----------------> Run[S]
Evidence[E]       --run_id-----------------> Run[S]
Evidence[E]       --patchset_id?----------> PatchSet[S]
Decision[E]       --run_id-----------------> Run[S]
Decision[E]       --chosen_patchset_id?---> PatchSet[S]
ContextFrame[E]   --intent_id?-------------> Intent[S]
ContextFrame[E]   --run_id?----------------> Run[S]
ContextFrame[E]   --plan_id?---------------> Plan[S]
ContextFrame[E]   --step_id?---------------> Plan[S].step_id

Libra layer
===========

Thread[L] --------current_intent_id-------> Intent[S]
Thread[L] --------latest_intent_id--------> Intent[S]
Thread[L] --------intents[].intent_id-----> Intent[S]
Thread[L] --------intents[].is_head-------> marks current branch heads

Scheduler[L] -----selected_plan_id--------> Plan[S]
Scheduler[L] -----current_plan_heads------> Plan[S]
Scheduler[L] -----active_task_id----------> Task[S]
Scheduler[L] -----active_run_id-----------> Run[S]
Scheduler[L] -----live_context_window-----> ContextFrame[E]

Libra Runtime Terms

Thread

Thread is the conversation-level projection root over a related Intent DAG.

It owns the current conversational view, not immutable history.

Current design fields:

FieldTypeMeaning
thread_idUuidLibra-side primary key
titleOption<String>Human-readable title
ownerActorRefConversation creator
participantsVec<ThreadParticipant>Human and agent participants with thread-local metadata
current_intent_idOption<Uuid>Intent currently focused by UI / Scheduler
latest_intent_idOption<Uuid>Most recently linked Intent; resume fallback
intentsVec<ThreadIntentRef>Ordered membership with ordinal, is_head, linked_at, link_reason
metadataOption<serde_json::Value>UI and routing hints
archivedboolClosed thread marker

Notes:

  • participants is not just Vec<ActorRef>; it carries thread-local role and join time metadata.
  • head_intent_ids is represented by ThreadIntentRef.is_head, not by a duplicated standalone array.
  • current_intent_id is the current focus.
  • latest_intent_id is the latest linked revision and default resume fallback when no current focus is set.

Scheduler

Scheduler is the runtime scheduling projection.

It answers: what should run now, what is active, and which plan branch is currently selected.

Current design fields:

FieldTypeMeaning
selected_plan_idOption<Uuid>Current canonical plan head in UI / runtime
current_plan_headsVec<Uuid>Active plan leaves
active_task_idOption<Uuid>Task currently emphasized by Scheduler / UI
active_run_idOption<Uuid>Live run attempt
live_context_windowVec<Uuid>Current visible ContextFrame ids

Scheduler may also derive or cache:

  • ready queue
  • parallel groups
  • checkpoints
  • retry routing
  • staging / integration state
  • replanning decisions

Query Index

Query Index is a rebuildable denormalized lookup layer for fast reads.

Typical indexes:

  • intent -> plans
  • intent -> context_frames
  • task -> runs
  • run -> events
  • run -> patchsets

Indexes are not historical truth and must be safe to rebuild.

Object Notes

Intent

Immutable snapshot of the user request and analyzed specification.

  • keeps parents, prompt, spec, analysis_context_frames
  • does not keep mutable lifecycle, selected plan pointers, or final execution outcomes
  • lifecycle belongs to IntentEvent

Plan

Immutable snapshot of strategy and step structure.

  • keeps intent, parents, steps, context_frames
  • PlanStep.step_id is the stable logical step identity across plan revisions
  • runtime step progress belongs to PlanStepEvent

There is no mutable ExecutionPlan object in git-internal.

Task

Stable work-unit definition.

  • keeps immutable provenance links: intent, parent, origin_step_id, dependencies
  • runtime status, retries, and active run belong to events or Libra projection

Run

Immutable execution-attempt envelope.

  • keeps task, optional plan, commit, optional snapshot, environment
  • status transitions and failure details belong to RunEvent
  • usage and cost belong to RunUsage

PatchSet

Immutable candidate diff snapshot.

  • keeps run, sequence, commit, format, artifact, touched, rationale
  • acceptance, rejection, and final selection belong to Decision or Libra projection

Provenance

Immutable model / provider / execution-parameter record for one run.

  • keeps provider, model, and execution parameters
  • usage accounting is tracked separately by RunUsage

ContextSnapshot

Optional stable environment baseline.

  • used when the system needs a frozen starting or ending context
  • not required for every phase
  • should not be used as a mutable runtime context container

ContextFrame

Immutable incremental context fact.

  • replaces the old mutable ContextPipeline runtime concept
  • may be attached to intent analysis, planning, execution, or step-level context
  • Libra keeps only the current live_context_window

Workflow Mapping

PhaseLibra runtime / projectionSnapshot writes (git-internal)Event writes (git-internal)
Phase 0Thread bootstrap, Scheduler bootstrap, live context bootstrapIntent, optional ContextSnapshotnone
Phase 1selected plan head, ready queue, checkpointsPlan, Tasknone
Phase 2live context window, retry / replan loop, staging areaRun, PatchSet, ProvenanceTaskEvent, RunEvent, PlanStepEvent, ToolInvocation, Evidence, ContextFrame, RunUsage
Phase 3audit indexing, release candidate viewoptional final ContextSnapshotEvidence, Decision, terminal TaskEvent / RunEvent / IntentEvent
Phase 4review UI, current thread pointersnoneDecision, optional terminal IntentEvent

Rebuild and Read Contract

Projection loss must not block read access.

Rules:

  1. Thread, Scheduler, and Query Index are rebuildable from immutable snapshots and events.
  2. Missing projection rows mean "projection missing or stale", not necessarily "the logical object does not exist".
  3. Read paths should prefer Libra projection first, then fall back to rebuild or history traversal when projection data is missing.

Examples:

  • Thread can be rebuilt from Intent, Intent.parents, and IntentEvent.next_intent_id edges.
  • Scheduler can be rebuilt from Plan, Task, Run, PlanStepEvent, and related execution events.
  • query indexes can be regenerated by scanning snapshot and event history.

Deprecated or Removed Concepts

The current design intentionally removes several older patterns:

  • no mutable ContextPipeline; use live_context_window + ContextFrame
  • no mutable in-object lifecycle fields on Intent, Task, or Run
  • no mutable ExecutionPlan object in git-internal
  • no "accepted" field written back to PatchSet

Summary Rule

1. Snapshot stores "what it is"
2. Event stores "what happened"
3. Libra stores "what is current"

Agent Workflow: From Intent to Release

The runtime workflow after the snapshot/event/Libra split

Commands

Detailed command reference for the Libra CLI

On this page

AI Object Model ReferenceCore BoundaryLayer ModelPlacement RulesSnapshot objects in git-internalEvent objects in git-internalProjection and runtime state in LibraMain Relationship GraphLibra Runtime TermsThreadSchedulerQuery IndexObject NotesIntentPlanTaskRunPatchSetProvenanceContextSnapshotContextFrameWorkflow MappingRebuild and Read ContractDeprecated or Removed ConceptsSummary Rule