WorkGraph Reference

WorkGraph is an optional realm-scoped subsystem. Agents mutate general work items through tools. Public RPC and REST expose observability/operator lookup. CLI and trusted in-process hosts add narrow goal and attention controls.

WorkItem

Field	Type	Description
`id`	`WorkItemId`	Unique work item id
`realm_id`	`string`	Realm that owns the item
`namespace`	`WorkNamespace`	Namespace within the realm, default `default`
`title`	`string`	Short title
`description`	`string?`	Optional detail
`status`	`WorkStatus`	Lifecycle status
`priority`	`low	medium	high`	Priority
`completion_policy`	`WorkCompletionPolicy`	Closure policy for goal-like work
`labels`	`string[]`	Filtering and grouping labels
`owner`	`WorkOwner?`	Intended owner or assignee
`claim`	`WorkClaim?`	Active claim owner and optional lease
`machine_state`	object	Generated WorkGraph lifecycle machine state
`revision`	`u64`	CAS revision for write tools
`due_at`	RFC3339 timestamp?	Due time
`not_before`	RFC3339 timestamp?	Earliest eligibility time
`snoozed_until`	RFC3339 timestamp?	Snooze gate
`created_at`	RFC3339 timestamp	Creation time
`updated_at`	RFC3339 timestamp	Last update time
`terminal_at`	RFC3339 timestamp?	Terminal time
`external_refs`	`ExternalWorkRef[]`	Typed pointers to external objects
`evidence_refs`	`WorkEvidenceRef[]`	Typed evidence pointers

Statuses

Status	Meaning
`open`	Created and not currently claimed
`in_progress`	Claimed or actively being worked
`blocked`	Not ready because a block exists or machine state is blocked
`completed`	Terminal success
`cancelled`	Terminal cancellation
`failed`	Terminal failure

Terminal items cannot be claimed.

Completion Policies

Policy	Meaning
`self_attest`	The assigned attention target can request closure directly
`host_confirmed`	Host confirmation evidence is required before closure
`principal_confirmed`	A named principal must confirm before closure
`supervisor`	A supervisor owner key must authorize closure
`reviewer_quorum`	The required reviewer threshold must be satisfied

Edge Kinds

Kind	Meaning
`blocks`	Source must resolve before target can be ready
`parent`	Hierarchical grouping
`related`	Non-blocking association
`supersedes`	Source replaces target
`derived_from`	Source was derived from target

WorkGraph rejects invalid endpoints, self edges, duplicate edges, and cycles for blocks and parent.

Owners And Claims

WorkOwnerKey.kind is one of:

principal
agent
session
mob
label

Claims are revision-based. Mutating tools require the current expected_revision. Optional leases allow abandoned work to become recoverable through machine- approved transitions.

Evidence Refs

WorkEvidenceRef contains:

Field	Type	Description
`kind`	`string`	Evidence type, such as `artifact`, `pr`, `log`, `summary`, or `notification`
`id`	`string`	External or Meerkat-owned artifact id
`label`	`string?`	Human label
`summary`	`string?`	Short explanation

Evidence refs are pointers. WorkGraph does not own the artifact content.

Flow Execution Bindings

WorkExecutionBinding durably associates one item with one exact Mob Flow attempt.

Field	Type	Description
`binding_id`	`WorkExecutionBindingId`	Stable binding identity
`work_ref`	`WorkItemRef`	Realm, namespace, and item identity
`target`	`mob_flow` target	Mob id, Flow id and digest, run id, and opaque activation parameters
`idempotency_key`	`string`	Caller-stable launch identity
`correlation_id`	UUID	Stable delivery correlation
`supersedes`	binding id?	Previous terminal attempt in the retry chain
`machine_state`	object	Generated execution-handoff lifecycle authority
`created_at`	RFC3339 timestamp	Store-owned creation time

The lifecycle phases distinguish launch request, uncertain launch, running, evidence projection, closure request, terminal Flow failure or cancellation, policy-refused closure, and successful WorkGraph closure. A retry may supersede only a terminal binding. The store enforces a single append-only retry chain with CAS machine revisions. A machine-derived, indexed recovery projection contains only nonterminal obligations, so host reconciliation does not scan or deserialize historical terminal bindings. The crash-safe launch sequence is binding commit, external-delivery begin, deterministic pending-run persistence, delivery realization claim, and Mob run start. realizing therefore implies that the exact run was already persisted. begun without a run is an abandonable uncertain launch. realizing without a run is quarantined as an invariant breach or legacy-corruption case. The WorkGraph bridge has no caller-asserted break-glass transition out of that state. It fails closed until the exact run is observed or a future sealed host authority is introduced. Every terminal Flow outcome creates evidence kind mob_flow_run_completed, mob_flow_run_failed, or mob_flow_run_canceled with the deterministic id work_execution:<binding_id>. Only completed-run evidence proceeds to a WorkGraph closure request. Exact evidence replay is a no-op; different content under the same evidence id fails closed. The typed execution_binding_id provenance is reserved to the execution bridge; the display id is never read as authority. If a completed run disappears before its evidence commits, the execution machine converts the attempt to a run-lost failure rather than closing the WorkGraph item without proof.

Public MCP

Tool	Purpose
`meerkat_workgraph_flow_launch`	Commit a binding before launch, start its exact Mob Flow run, and reconcile visible results
`meerkat_workgraph_flow_reconcile`	Resume the machine-owned handoff from its first incomplete durable boundary
`meerkat_workgraph_flow_abandon_uncertain`	Under binding-revision CAS and host custody, resolve an ambiguous launch only after its deterministic run is absent, then require a superseding retry
`meerkat_workgraph_flow_binding_get`	Read one redacted execution linkage
`meerkat_workgraph_flow_binding_list`	List bounded redacted execution linkages

meerkat_mob_flow_status includes the corresponding redacted execution binding when the run was created by this bridge. Activation parameters, idempotency keys, correlation ids, and execution principals remain internal to the trusted realm host. The durable store journal retains full execution events for deterministic rebuild, but the general workgraph_events projection omits those event kinds. Public consumers observe execution through the redacted binding and Flow-status projections, so activation parameters and execution principals never cross the coarse WorkGraph event-read boundary. expected_item_revision is required when creating a new binding. An exact idempotent replay selects the existing binding even if later evidence changed the item revision. A changed effective Flow run configuration cannot be launched under an older binding digest.

Agent Tools

Tool	Purpose
`workgraph_create`	Create a work item
`workgraph_get`	Read one item
`workgraph_list`	List items
`workgraph_ready`	List machine-derived ready items
`workgraph_snapshot`	Read items, edges, ready ids, scope, timestamp, and event high-water mark
`workgraph_events`	Read event history
`workgraph_claim`	Claim an item with CAS revision
`workgraph_release`	Release an active claim
`workgraph_update`	Update mutable item fields
`workgraph_block`	Put an item into blocked state
`workgraph_close`	Close as `completed`, `cancelled`, or `failed`
`workgraph_link`	Add a graph edge
`workgraph_add_evidence`	Add an evidence reference

RPC

Method	Purpose
`workgraph/get`	Read one item
`workgraph/list`	List items
`workgraph/ready`	List ready items
`workgraph/snapshot`	Read graph snapshot
`workgraph/events`	Read event history
`workgraph/goal/status`	Read goal and attention status
`workgraph/attention/list`	List attention bindings

General WorkGraph item mutation remains tool-owned. Attention reassignment and policy escalation are authority-bearing WorkGraph tool operations injected into turns with active attention, not public RPC methods.

REST

Method	Path	Purpose
`GET`	`/workgraph/items`	List items
`GET`	`/workgraph/items/{id}`	Read one item
`GET`	`/workgraph/ready`	List ready items
`GET`	`/workgraph/snapshot`	Read graph snapshot
`GET`	`/workgraph/events`	Read event history
`POST`	`/workgraph/goal/status`	Read goal and attention status
`POST`	`/workgraph/attention/list`	List attention bindings

The GET routes use query parameters such as realm_id, namespace, all_namespaces, statuses, labels, include_terminal, limit, and after_seq for events. The POST /workgraph/goal/status and POST /workgraph/attention/list routes accept JSON request bodies.

CLI

rkat workgraph list [--namespace <NS>] [--all-namespaces] [--status <STATUS>] [--label <LABEL>] [--include-terminal] [--limit <N>] [--json]
rkat workgraph show <ID> [--namespace <NS>] [--json]
rkat workgraph ready [--namespace <NS>] [--label <LABEL>] [--limit <N>] [--json]
rkat workgraph snapshot [--namespace <NS>] [--all-namespaces] [--status <STATUS>] [--label <LABEL>] [--include-terminal] [--limit <N>] [--json]
rkat workgraph events [--namespace <NS>] [--all-namespaces] [--after-seq <N>] [--limit <N>] [--json]
rkat workgraph goal-create <SESSION_ID> <TITLE> [--namespace <NS>] [--description <TEXT>] [--mode <MODE>] [--completion-policy self-attest|host-confirmed] [--json]
rkat workgraph goal-status <BINDING_ID> [--namespace <NS>] [--json]
rkat workgraph goal-confirm <BINDING_ID> --expected-revision <N> --kind <KIND> --id <ID> [--namespace <NS>] [--label <TEXT>] [--summary <TEXT>] [--json]
rkat workgraph goal-close <BINDING_ID> --expected-revision <N> [--status completed|cancelled|failed] [--namespace <NS>] [--json]
rkat workgraph attention-list [--namespace <NS>] [--status <STATUS>] [--json]
rkat workgraph attention-pause <BINDING_ID> --expected-revision <N> [--namespace <NS>] [--json]
rkat workgraph attention-resume <BINDING_ID> --expected-revision <N> [--namespace <NS>] [--json]

CLI commands use the same realm flags as other rkat commands.

Companion Skill

workgraph-workflow is an embedded builtin companion skill gated by the work_graph capability. It teaches agents how to use the WorkGraph tool family. It is discoverable through the normal skills inventory and is not automatically preloaded.

Reference

Architecture

Operations

WorkGraph Reference

WorkGraph Reference

WorkItem

Statuses

Completion Policies

Edge Kinds

Owners And Claims

Evidence Refs

Flow Execution Bindings

Public MCP

Agent Tools

RPC

REST

CLI

Companion Skill

​WorkGraph Reference

​WorkItem

​Statuses

​Completion Policies

​Edge Kinds

​Owners And Claims

​Evidence Refs

​Flow Execution Bindings

​Public MCP

​Agent Tools

​RPC

​REST

​CLI

​Companion Skill

WorkGraph Reference

WorkItem

Statuses

Completion Policies

Edge Kinds

Owners And Claims

Evidence Refs

Flow Execution Bindings

Public MCP

Agent Tools

RPC

REST

CLI

Companion Skill