Module wstore 

WaveStore: generic OID-based CRUD for WaveObj types. Port of Go’s pkg/wstore/wstore_dbops.go + wstore_dbsetup.go.

Uses Mutex<Connection> matching Go’s MaxOpenConns(1). SQLite WAL mode + 5s busy timeout (same as Go).

Structs

AgentContent

A content blob associated with a agent definition.

AgentDefinition

A user-defined AI agent in the user’s agent-definition catalog.

AgentHistory

An append-only session history entry for a agent definition.

AgentIdentityLink

Junction row: which identity an agent uses for a given provider.

AgentInstance

One row per running/historical execution of an agent definition. block_id / session_id / github_context are modelled as empty strings on the wire rather than Option<String> to match the existing schema conventions (NOT NULL DEFAULT ''). Callers that need structured absence can use .is_empty().

AgentSkill

A reusable skill/capability attached to a agent definition.

GitHubContext

Optional context describing which GitHub-side unit of work a specific instance is operating on. Stored as JSON in db_agent_instances.github_context (empty string when unset).

Identity

A named credential bundle. Contains zero or more accounts via the db_identity_bindings junction. is_blank tags the seeded singleton row that the launch UI uses as the default option.

IdentityAccount

An identity account (reusable credential, linked to agents via the db_agent_identity_links junction). Replaces the browser localStorage identity store.

IdentityBinding

Junction row binding an account to an identity for a given provider.

Memory

A Memory bundle — the agent’s personality and capability stack. Provider, model, instructions, and JSON-encoded arrays of context files / MCP servers / skills. Agent definitions shadow-migrate into this table during the v7 migration.

StoreTx

A borrowed connection handle for use inside WaveStore::with_tx. Provides the same CRUD methods as WaveStore but operates on the already-locked connection without additional Mutex acquisition.

WaveStore

SQLite-backed object store for WaveObj types.

Enums

InstanceStatus

Instance lifecycle status. Serialised lowercase to match the DB text.

SecretRef

Provider-specific credential reference. Stored as JSON in db_identity_accounts.secret_ref. backend is the discriminator. The actual secret value is NEVER stored in the DB — only how to look it up at launch time (env var, secrets-manager path, etc.). PlaintextDev exists for local dev convenience and must never be the default path in production builds.

Functions

agent_instance_to_record 🔒

Build a registry record from an AgentInstance. Returns an error if the working directory can’t be expressed as a path relative to the canonical shared agents root (e.g. user pointed an agent at ~/projects/foo, which would also fail a naive "agents" segment-scan that happened to match ~/projects/agents/foo). Caller logs + skips — agent stays in SQLite, just not in the cross-version dropdown.

default_agent_type 🔒

default_context_json 🔒

default_identity_status 🔒

default_json_array_string 🔒

derive_slug

Derive a filesystem-safe slug from a display name. Lowercase, ASCII alphanumeric + dash/underscore, consecutive dashes collapsed, trimmed to 64 chars. Returns "agent" if the input has no valid characters (defensive fallback).

empty_to_none 🔒

format_epoch_date 🔒

Format days-since-epoch as YYYY-MM-DD string. Simple implementation without chrono dependency.

map_agent_definition_row 🔒

Phase 3b — row mapper for db_agents rows projected back into the AgentDefinition shape. The column order MUST match the SELECT in agent_def_list. parent_template_id maps to parent_id because the consolidated table renamed the field to clarify its semantics (template lineage), but the wire shape kept the old name.

map_instance_row 🔒

map_memory_row 🔒

relative_workdir 🔒

Express abs as a path relative to agents_root. Returns None when abs is empty, not under agents_root, or after stripping resolves to an empty path. Anchors against the resolved shared root (passed in by the caller) — never scans for a path segment named “agents”, which would match unrelated user directories like /home/me/projects/agents/foo.