Set a key-value pair in the shared state store.

The value can be any JSON-serialisable type (dict, list, str, int, …). If ttl_seconds is provided, the entry will expire automatically after that many seconds. Existing entries are overwritten silently. If agent_id is provided, it is recorded in the audit history so the caller can be identified in history_log results.

Use a structured key prefix to avoid collisions in multi-workflow deployments, e.g. 'shared:my_namespace:my_key' or simply 'fact_1'.

Get the value stored under key.

Returns found=True and the value if the key exists and has not expired. Returns found=False and value=None if the key is missing or expired.

Delete a key from the state store.

Returns ok=True if the key existed and was removed, ok=False if the key was not found (idempotent — safe to call multiple times).

List all live (non-expired) keys, optionally filtered by prefix.

Example: state_list(prefix='fact_') returns all keys starting with 'fact_'. Returns an empty list if no keys match.

Register a new workflow and get back a unique run_id.

Call this from the orchestrator before spawning workers. The returned run_id is stored in the sidecar — workers do NOT need to receive it out-of-band; they use workflow_discover() to find it.

Tags are arbitrary key-value metadata used for discovery filtering: e.g. tags={'pipeline': 'data-etl', 'customer': 'acme', 'priority': 'high'}

Status starts as 'created'. Lifecycle: created → claimed → running → done/failed.

Find workflows available for a worker to pick up.

Filters by tag key/value pairs (AND semantics) and/or status. Common usage: workflow_discover(status='created') to find unclaimed work.

Workers should follow this with workflow_claim() to atomically take ownership of one of the returned workflows.

Returns an empty list if no matching workflows are found.

Atomically claim a workflow for this agent.

Only succeeds if the workflow is in 'created' status. If two agents call this concurrently for the same run_id, exactly one will succeed.

After claiming, call workflow_checkpoint() as each step completes. If this agent crashes, use workflow_discover() + workflow_claim() from a replacement agent to resume — the sidecar preserves all checkpoint state.

Returns claimed=False with a reason if the workflow is already taken or does not exist.

Atomically persist a completed step's output and advance the step counter.

Call this immediately after each pipeline step completes, before starting the next one. A replacement agent can resume from the last checkpoint using workflow_resume().

The output can be any JSON-serialisable value (dict, list, str, …). If step N was already checkpointed, calling again with the same step overwrites the stored output (idempotent replay support).

Get everything a replacement agent needs to resume a crashed workflow.

Returns:

• last_step: the highest step that was successfully checkpointed

• step_outputs: dict mapping step number (as string) to its output

• meta: full workflow metadata (name, tags, status, agent_id, …)

Get the current status of a workflow — lightweight alternative to workflow_resume.

Returns the status, last completed step, assigned agent, and timestamps. Does NOT return step outputs (use workflow_resume for that).

List all registered workflows (all statuses).

For filtered listing, use workflow_discover(status=..., tags={...}) instead.

Try to acquire an exclusive, TTL-based lease on a named resource.

Use this to prevent split-brain when multiple agents could simultaneously work on the same resource. Only one holder can hold the lease at a time.

If the current holder crashes, the lease expires automatically after ttl_seconds and another agent can acquire it.

Returns acquired=True on success with the expiry timestamp. Returns acquired=False with the current holder's ID on failure.

Voluntarily release a lease this agent holds.

Only the current holder can release their own lease (holder_id must match). No-op if the lease has already expired or belongs to someone else.

Extend an existing lease's TTL while still holding it.

Call this periodically from long-running agents to prevent their lease from expiring mid-execution. The holder_id must match the current holder.

Check sidecar liveness and get backend diagnostics.

Wipe all sidecar state: kv_store, leases, workflows, step_outputs, history, and sessions.

Persist the full workflow context for a session_id.

Retrieve the workflow context saved for a session_id.

Return the last N state-transition records in reverse chronological order.