Core Concepts

Understanding the primary entities in Codara is essential for both integration and management.

1. Workspaces

A Workspace represents a dedicated directory on the filesystem where a coding agent performs its tasks.

  • Isolation: Each workspace is isolated from others, preventing cross-task interference.
  • Initialization: Workspaces can be initialized from templates (e.g., default, python).
  • Tracking: The Workspace Engine monitors changes. If the directory is a Git repository, it uses Git metadata for diffs; otherwise, it falls back to SHA-256 hash comparison.
  • Users: Workspaces are bound to a specific user_id.

2. Sessions

A Session tracks a long-lived conversation or interaction sequence between a user and a provider.

  • Client Session ID: A stable ID provided by the client (e.g., a thread ID).
  • Backend ID: The internal ID generated by the provider (e.g., Gemini's session ID). Codara maps the stable Client ID to the volatile Backend ID.
  • Status:
    • idle: Ready for a new turn.
    • active: Currently executing an agent turn.
    • dirty: An execution failed or timed out, potentially leaving the workspace or provider state inconsistent.
  • Persistence: Session metadata is stored in SQLite, allowing stateful resumption even after gateway restarts.

3. Tasks

A Task is created for every single inference request. It represents the lifecycle of a single "turn."

  • Audit Trail: Tasks provide a detailed history of what was asked and what the agent did.
  • States: pending, running, completed, failed.
  • Result: Once completed, the task stores a TurnResult, which includes:
    • The raw output from the agent.
    • The list of modified files.
    • The unified diff of the changes.
    • Extracted ATR (Agent Tool Result) actions.

4. Providers & Adapters

Codara supports multiple underlying runtimes through a pluggable Adapter system.

  • Codex: Adapter for OpenAI's Codex CLI.
  • Gemini: Adapter for Google's Gemini CLI.
  • OpenCode: Adapter for the OpenCode AI CLI.

Adapters handle the specifics of: - Constructing CLI commands. - Parsing stdout/stderr. - Managing session resumption flags (like --resume). - Detecting stalls and auth failures.

5. ATR (Agent Tool Results)

Codara automatically parses agent outputs for structured tool calls or result markers. These are stored as Actions within the Task result, enabling the dashboard to display interactive widgets or summaries of what the agent "did" beyond just producing text.