Skip to main content

​
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

FieldTypeDescription
idWorkItemIdUnique work item id
realm_idstringRealm that owns the item
namespaceWorkNamespaceNamespace within the realm, default default
titlestringShort title
descriptionstring?Optional detail
statusWorkStatusLifecycle status
priority`lowmediumhigh`Priority
completion_policyWorkCompletionPolicyClosure policy for goal-like work
labelsstring[]Filtering and grouping labels
ownerWorkOwner?Intended owner or assignee
claimWorkClaim?Active claim owner and optional lease
machine_stateobjectGenerated WorkGraph lifecycle machine state
revisionu64CAS revision for write tools
due_atRFC3339 timestamp?Due time
not_beforeRFC3339 timestamp?Earliest eligibility time
snoozed_untilRFC3339 timestamp?Snooze gate
created_atRFC3339 timestampCreation time
updated_atRFC3339 timestampLast update time
terminal_atRFC3339 timestamp?Terminal time
external_refsExternalWorkRef[]Typed pointers to external objects
evidence_refsWorkEvidenceRef[]Typed evidence pointers

​
Statuses

StatusMeaning
openCreated and not currently claimed
in_progressClaimed or actively being worked
blockedNot ready because a block exists or machine state is blocked
completedTerminal success
cancelledTerminal cancellation
failedTerminal failure
Terminal items cannot be claimed.

​
Completion Policies

PolicyMeaning
self_attestThe assigned attention target can request closure directly
host_confirmedHost confirmation evidence is required before closure
principal_confirmedA named principal must confirm before closure
supervisorA supervisor owner key must authorize closure
reviewer_quorumThe required reviewer threshold must be satisfied

​
Edge Kinds

KindMeaning
blocksSource must resolve before target can be ready
parentHierarchical grouping
relatedNon-blocking association
supersedesSource replaces target
derived_fromSource 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:
FieldTypeDescription
kindstringEvidence type, such as artifact, pr, log, summary, or notification
idstringExternal or Meerkat-owned artifact id
labelstring?Human label
summarystring?Short explanation
Evidence refs are pointers. WorkGraph does not own the artifact content.

​
Agent Tools

ToolPurpose
workgraph_createCreate a work item
workgraph_getRead one item
workgraph_listList items
workgraph_readyList machine-derived ready items
workgraph_snapshotRead items, edges, ready ids, scope, timestamp, and event high-water mark
workgraph_eventsRead event history
workgraph_claimClaim an item with CAS revision
workgraph_releaseRelease an active claim
workgraph_updateUpdate mutable item fields
workgraph_blockPut an item into blocked state
workgraph_closeClose as completed, cancelled, or failed
workgraph_linkAdd a graph edge
workgraph_add_evidenceAdd an evidence reference

​
RPC

MethodPurpose
workgraph/getRead one item
workgraph/listList items
workgraph/readyList ready items
workgraph/snapshotRead graph snapshot
workgraph/eventsRead event history
workgraph/goal/statusRead goal and attention status
workgraph/attention/listList attention bindings
General WorkGraph item mutation remains tool-owned. The goal and attention mutation methods are trusted host-control methods and are not part of the public REST or JSON-RPC catalog.

​
REST

MethodPathPurpose
GET/workgraph/itemsList items
GET/workgraph/items/{id}Read one item
GET/workgraph/readyList ready items
GET/workgraph/snapshotRead graph snapshot
GET/workgraph/eventsRead event history
POST/workgraph/goal/statusRead goal and attention status
POST/workgraph/attention/listList 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.