Module store

Expand description

Unified task store — SQLite as single source of truth.

TaskStore replaces the legacy internal_tasks table and GitHub labels as the authoritative task state. External backends (GitHub, Linear) become sync adapters that mirror state changes outward.

Uses sqlx for async SQLite access with file-based migrations.

All task state, metrics, KV, and rate limits flow through this module.

§Safety Warning: Never Use `SELECT *`

Using SELECT * with sqlx-sqlite’s prepared statement cache can cause OOB (out-of-bounds) panics when the schema changes (e.g., new migration adds a column).

The issue occurs because:

SQLite caches prepared statements with column metadata at prepare time
When a migration adds a new column, sqlite3_column_count() returns the updated count
The cached statement’s column metadata vector was built with the old count
Accessing column index N when only N columns exist (0..N-1) causes a panic

Solution: Always use explicit column lists via constants like TASK_COLS, CONTROL_MESSAGE_COLS, JOB_STATE_COLS, etc. See tasks.rs and control.rs for examples. CI will fail if SELECT * is detected in store files.

Structs§

AgentStat: Agent statistics from metrics.
ChatCostSummary: Cost summary for a chat session.
CompleteRun: Parameters for completing a run.
ControlMessage: A message in the control session conversation history.
CostByGroup: Cost breakdown by a grouping dimension (agent, model, etc.).
CostEstimate: Cost estimate in USD.
CostPeriod: Cost data for a single time period.
CostSummary: Cost summary across multiple time periods.
ErrorStat: Error type distribution for pattern detection.
HighReviewCycleTask: Task with high review cycle count (persistent review loop).
InsertTaskMetric: Parameters for inserting a new task metric record.
JobState: Runtime state for a scheduled job, stored in SQLite (not in .orch.yml).
MemoryEntry: A single memory entry from a task attempt.
MetricsSummary: Metrics summary for the CLI output.
ModelPricing: Per-1M token pricing in USD.
NewTask: Parameters for creating a new task.
RunTokenUsage: Token usage for a run.
SlowTaskInfo: Slow task info for pattern detection.
StartRun: Parameters for starting a new run.
StoreRoute: Parameters for storing a route result.
Task: Unified task record — single row in the tasks table.
TaskActivity: A single task lifecycle activity event.
TaskRun: A single run (agent execution, review, or routing attempt).
TaskStore: The unified task store backed by SQLite (via sqlx).
TokenUsage: Token usage for an agent run.
UpsertExternal: Parameters for upserting an external task.

Enums§

TaskStatus

Functions§

default_db_path: Default database path: ~/.orch/orch.db
get_cost_estimate: Get cost estimate from the store.
get_cost_estimate_result: Get cost estimate from the store, surfacing DB read errors.
get_recent_memory: Get recent memory entries for a task.
get_recent_memory_result: Get recent memory entries for a task, surfacing DB read errors.
get_task_field: Read a specific string field from a task record.
get_task_field_direct: Read a specific string field from a task record (store always available).
get_token_usage: Get token usage from the store.
get_token_usage_result: Get token usage from the store, surfacing DB read errors.
opt_store_get_task: Load the full Task record from the store.
opt_store_get_task_by_id: Load the full Task record from the store.
parse_since_duration: Parse a human-readable duration string into an RFC3339 timestamp representing now - duration.
pricing_for_model: Resolve model pricing using a built-in table and normalized model aliases.
resolve_store_id: Resolve a task’s numeric store ID from its external identifier.
review_session_expected
set_review_session_expected
store_increment: Increment a counter in the task store.
store_increment_by_id: Increment a counter in the task store.
store_log_activity: Append a lifecycle activity event to a task timeline.
store_reset_counters: Reset all task counters in the task store.
store_reset_failure_counters: Reset transient failure/retry counters, preserving review_cycles.
store_set: Write fields to the task store.
store_set_by_id: Write fields to the task store.
store_set_result: Write fields to the task store, returning an error if the write fails.
store_set_result_by_id: Write fields to the task store, returning an error if the write fails.
store_touch_updated_at: Touch updated_at to now so the stuck-task timer is reset after a session exits.
store_touch_updated_at_by_id: Touch updated_at to now so the stuck-task timer is reset after a session exits.

Type Aliases§

StoreResult: Result type for helpers that distinguish “not found” from “read error”.

Module store

Module store Copy item path

§Safety Warning: Never Use SELECT *

Structs§

Enums§

Functions§

Type Aliases§

Module store

§Safety Warning: Never Use `SELECT *`