mcp-state-sidecar

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

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.

Retrieve the workflow context saved for a session_id.

Persist the full workflow context for a session_id.

Check sidecar liveness and get backend diagnostics.

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

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).

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.

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.

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'.

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).

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.

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.

List all registered workflows (all statuses). For filtered listing, use workflow_discover(status=..., tags={...}) instead.

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).