> ## Documentation Index > Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt > Use this file to discover all available pages before exploring further. # WorkGraph Reference > WorkGraph item fields, statuses, edges, evidence, tools, and host surfaces. # 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:`. 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 ```bash theme={null} rkat workgraph list [--namespace ] [--all-namespaces] [--status ] [--label