describe_run
Input and output schemas
{
"inputSchema": {
"type": "object",
"properties": {
"namespace": {
"type": "string",
"minLength": 1,
"description": "The namespace the workflow runs under. This is the authorization scope of the call, not a label: a namespace you do not hold is answered as not-found. Read it off a previous describe_run or list_runs result; never guess it."
},
"workflow_id": {
"type": "string",
"description": "The workflow to describe.",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
},
"run_id": {
"type": "string",
"description": "Which generation of the workflow to describe. Omit for the latest run of the chain \u2014 the usual choice. A workflow that continued-as-new has several runs and they do NOT share step numbering.",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
}
},
"required": [
"namespace",
"workflow_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"namespace": {
"type": "string"
},
"workflow_id": {
"type": "string"
},
"run_id": {
"type": "string",
"description": "The run this description is about \u2014 resolved for you when you omitted it. Carry it into every transcript read."
},
"workflow_type": {
"type": "string"
},
"display_name": {
"type": [
"string",
"null"
],
"description": "The operator-facing label this WORKFLOW currently wears, or null when it wears none and renders as its bare UUID. A label, never an address: nothing resolves a workflow by name, so carry the workflow_id \u2014 not this \u2014 into every other call."
},
"status": {
"type": "string",
"enum": [
"Running",
"Completed",
"Failed",
"Cancelled",
"TimedOut",
"ContinuedAsNew",
"Paused"
]
},
"started_at": {
"type": "string"
},
"ended_at": {
"type": [
"string",
"null"
]
},
"failed_step": {
"type": [
"string",
"null"
]
},
"failure_reason": {
"type": [
"string",
"null"
]
},
"current_worker": {
"type": [
"object",
"null"
],
"description": "The worker holding the run's most recently leased open attempt, by the durable names its ActivityLeased event recorded. Null is UNATTRIBUTED: nothing is outstanding, the run predates lease events, or this install failed to record the lease \u2014 compare `provenance.lease_record_failures_total` to tell the last two apart.",
"properties": {
"identity": {
"type": "string"
},
"task_queue": {
"type": "string"
},
"node": {
"type": [
"string",
"null"
]
},
"deployment": {
"type": [
"string",
"null"
]
},
"instance_id": {
"type": [
"string",
"null"
]
},
"transport": {
"type": "string",
"enum": [
"Grpc",
"Liminal"
]
}
},
"required": [
"identity",
"task_queue",
"transport"
],
"additionalProperties": false
},
"awaiting_worker": {
"type": [
"object",
"null"
],
"description": "The attempt most recently handed out by a recorded fact that nobody has taken since: the last ActivityStarted or ActivityAdoptionOffered in the current lease segment with no ActivityLeased or ActivityServedAtServer for that attempt and no terminal since. A workflow terminal ends every wait, so a run that has ended never names one. It reads recorded facts only: a worker-loss re-dispatch records nothing, so an attempt re-sent after its lessee was lost is not named. A command the server runs itself is never named while it runs: the server records ActivityServedAtServer before the command starts. Read beside current_worker: a run nobody holds that this names is, by the record, waiting for a worker on task_queue since `since`; task_queue is the queue its schedule or latest fallback hop named, null when neither sits in the current segment. Null or absent when nothing recorded is waiting. Not a status: the run stays Running. A statement of the record, never a liveness claim.",
"properties": {
"activity_id": {
"type": "integer"
},
"attempt": {
"type": "integer"
},
"task_queue": {
"type": [
"string",
"null"
]
},
"since": {
"type": "string"
}
},
"required": [
"activity_id",
"attempt",
"task_queue",
"since"
],
"additionalProperties": false
},
"package_version": {
"type": [
"string",
"null"
],
"description": "The 64-hex content hash of the package THIS run started under \u2014 the exact document that produced this history, never the type's current version. Null only for a run recorded before the field existed; it is never looked up."
},
"history_head_seq": {
"type": "integer"
},
"provenance": {
"type": "object",
"properties": {
"lease_record_failures_total": {
"type": "integer",
"description": "Leases this install knew and failed to record since it booted. Read against an unattributed attempt: 0 on a run that predates lease events means never recorded here; N > 0 means recorded here with N losses."
}
},
"required": [
"lease_record_failures_total"
],
"additionalProperties": false
},
"lease_recording": {
"type": "object",
"properties": {
"leases_recorded": {
"type": "integer"
},
"dispatched_attempts": {
"type": "integer"
},
"attempts_with_a_lease": {
"type": "integer"
}
},
"required": [
"leases_recorded",
"dispatched_attempts",
"attempts_with_a_lease"
],
"additionalProperties": false
},
"current_step": {
"type": [
"object",
"null"
],
"description": "The activity this run dispatched most recently that has recorded no terminal event. Null when nothing is in flight.",
"properties": {
"activity_id": {
"type": "integer"
},
"activity_type": {
"type": "string"
},
"attempt": {
"type": "integer"
},
"task_queue": {
"type": [
"string",
"null"
]
},
"node": {
"type": [
"string",
"null"
]
},
"dispatched_at": {
"type": "string"
},
"held_since": {
"type": [
"string",
"null"
]
}
},
"required": [
"activity_id",
"activity_type",
"attempt",
"dispatched_at"
],
"additionalProperties": false
},
"unserved": {
"type": "array",
"description": "Activities this run dispatched that NO live worker is serving. An entry whose reason is SERVED_AT_SERVER is not a fault: the server itself is running that step's declared body, so no worker is needed. Every other entry is the difference between 'a worker is working on it' and 'it is parked with nobody to take it' \u2014 which the status alone cannot express, because both project Running. An empty list is healthy.",
"items": {
"type": "object"
}
},
"transcripts": {
"type": "array",
"description": "One entry per retained agent-transcript stream of this run. Each carries the COMPLETE read_transcript handle, run_id included.",
"items": {
"type": "object",
"properties": {
"workflow_id": {
"type": "string"
},
"run_id": {
"type": "string"
},
"activity_id": {
"type": "integer"
},
"attempt": {
"type": "integer"
},
"head_seq": {
"type": "integer"
}
},
"required": [
"workflow_id",
"run_id",
"activity_id",
"attempt",
"head_seq"
],
"additionalProperties": false
}
}
},
"required": [
"namespace",
"workflow_id",
"run_id",
"workflow_type",
"status",
"started_at",
"history_head_seq",
"provenance",
"lease_recording",
"unserved",
"transcripts"
],
"additionalProperties": false
}
}read_transcript
Input and output schemas
{
"inputSchema": {
"type": "object",
"properties": {
"namespace": {
"type": "string",
"minLength": 1,
"description": "The namespace the workflow runs under. This is the authorization scope of the call, not a label: a namespace you do not hold is answered as not-found. Read it off a previous describe_run or list_runs result; never guess it."
},
"workflow_id": {
"type": "string",
"description": "The workflow that owns the step.",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
},
"run_id": {
"type": "string",
"description": "The run that dispatched this attempt. REQUIRED. Take it from describe_run; a run that never dispatched this activity/attempt is refused.",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
},
"activity_id": {
"type": "integer",
"minimum": 0,
"description": "The activity ordinal within the run."
},
"attempt": {
"type": "integer",
"minimum": 0,
"description": "The one-based delivery attempt. Each attempt is its own transcript."
},
"from_seq": {
"type": "integer",
"minimum": 0,
"description": "Read records with store_seq >= this. Omit to read from the start."
},
"limit": {
"type": "integer",
"minimum": 1,
"description": "Maximum records to return in this page."
}
},
"required": [
"namespace",
"workflow_id",
"run_id",
"activity_id",
"attempt"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"workflow_id": {
"type": "string"
},
"run_id": {
"type": "string"
},
"activity_id": {
"type": "integer"
},
"attempt": {
"type": "integer"
},
"events": {
"type": "array",
"items": {
"type": "object"
}
},
"next_from_seq": {
"type": [
"integer",
"null"
],
"description": "Pass back as from_seq for the next page. Null means this page reached the end of what is retained."
},
"head_seq": {
"type": "integer",
"description": "The stream head at read time: the next store_seq that will be written."
}
},
"required": [
"workflow_id",
"run_id",
"activity_id",
"attempt",
"events",
"head_seq"
],
"additionalProperties": false
}
}read_history
Input and output schemas
{
"inputSchema": {
"type": "object",
"properties": {
"namespace": {
"type": "string",
"minLength": 1,
"description": "The namespace the workflow runs under. This is the authorization scope of the call, not a label: a namespace you do not hold is answered as not-found. Read it off a previous describe_run or list_runs result; never guess it."
},
"workflow_id": {
"type": "string",
"description": "The workflow whose history to read.",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
},
"from_seq": {
"type": "integer",
"minimum": 0,
"description": "Read events with seq >= this. Omit to start at 0."
},
"limit": {
"type": "integer",
"minimum": 1,
"description": "Maximum events to return in this page."
},
"payload_limit_bytes": {
"type": "integer",
"minimum": 0,
"description": "Elide any payload larger than this many bytes to a size marker. 0 disables elision and returns payloads whole."
}
},
"required": [
"namespace",
"workflow_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"workflow_id": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "object"
}
},
"next_from_seq": {
"type": [
"integer",
"null"
]
},
"head_seq": {
"type": "integer"
},
"page_is_immutable": {
"type": "boolean",
"description": "TRUE when every event on this page sits strictly below the head at read time. History is append-only, so such a page can never change and may be cached indefinitely. FALSE means the page touches the head and more may follow."
}
},
"required": [
"workflow_id",
"events",
"head_seq",
"page_is_immutable"
],
"additionalProperties": false
}
}list_connected_workers
Input and output schemas
{
"inputSchema": {
"type": "object",
"properties": {
"namespace": {
"type": "string",
"description": "Namespace to authorize and list; omitted lists all namespaces and requires all-namespace authority."
},
"task_queue": {
"type": "string"
},
"activity_type": {
"type": "string"
}
},
"required": [],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"workers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"identity": {
"type": "string"
},
"pools": {
"type": "array",
"items": {
"type": "object"
}
},
"node": {
"type": [
"string",
"null"
]
},
"transport": {
"type": "string"
},
"connected_since": {
"type": "string"
},
"dispatch_eligible": {
"type": "boolean"
}
},
"required": [
"id",
"identity",
"pools",
"node",
"transport",
"connected_since",
"dispatch_eligible"
],
"additionalProperties": false
}
},
"pool_status": {
"type": [
"string",
"null"
],
"enum": [
"no_workers",
"workers_all_ineligible",
"workers_eligible",
null
]
}
},
"required": [
"workers",
"pool_status"
],
"additionalProperties": false
}
}list_runs
Input and output schemas
{
"inputSchema": {
"type": "object",
"properties": {
"namespace": {
"type": "string",
"minLength": 1,
"description": "The namespace the workflow runs under. This is the authorization scope of the call, not a label: a namespace you do not hold is answered as not-found. Read it off a previous describe_run or list_runs result; never guess it."
},
"workflow_type": {
"type": "string",
"description": "Exact workflow type."
},
"status": {
"type": "string",
"enum": [
"Running",
"Completed",
"Failed",
"Cancelled",
"TimedOut",
"ContinuedAsNew",
"Paused"
]
},
"started_after": {
"type": "string",
"description": "RFC 3339 instant; only runs started at or after it."
},
"started_before": {
"type": "string",
"description": "RFC 3339 instant; only runs started at or before it."
},
"limit": {
"type": "integer",
"minimum": 1,
"description": "Rows per page (required)."
},
"cursor": {
"type": "string",
"description": "The `next_cursor` of the previous page, under the same filter."
}
},
"required": [
"namespace",
"limit"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"namespace": {
"type": "string"
},
"runs": {
"type": "array",
"description": "One summary per run. `current_worker` names the worker holding the run's most recently leased open attempt and is ABSENT when the run is unattributed \u2014 hold that absence against `provenance`. `awaiting_worker` names the attempt most recently handed out by a recorded dispatch or adoption offer that nobody (no worker's lease, no server hand-over) has taken since and is ABSENT when nothing recorded waits; a run nobody holds that carries it is waiting for a worker on its queue. `package_version` is the content hash of the package the run started under, absent only for a row that predates the field.",
"items": {
"type": "object",
"properties": {
"workflow_id": {
"type": "string"
},
"run_id": {
"type": "string"
},
"workflow_type": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"Running",
"Completed",
"Failed",
"Cancelled",
"TimedOut",
"ContinuedAsNew",
"Paused"
]
},
"started_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"ended_at": {
"type": [
"string",
"null"
]
},
"parent": {
"type": [
"string",
"null"
]
},
"failed_step": {
"type": "string"
},
"failure_reason": {
"type": "string"
},
"display_name": {
"type": "string",
"description": "The operator-facing label this workflow wears. A label, never an address: carry the workflow_id into every other call."
},
"kind": {
"type": "string"
},
"outcome": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"current_worker": {
"type": [
"object",
"null"
],
"description": "The worker holding the run's most recently leased open attempt, by the durable names its ActivityLeased event recorded. Null is UNATTRIBUTED: nothing is outstanding, the run predates lease events, or this install failed to record the lease \u2014 compare `provenance.lease_record_failures_total` to tell the last two apart.",
"properties": {
"identity": {
"type": "string"
},
"task_queue": {
"type": "string"
},
"node": {
"type": [
"string",
"null"
]
},
"deployment": {
"type": [
"string",
"null"
]
},
"instance_id": {
"type": [
"string",
"null"
]
},
"transport": {
"type": "string",
"enum": [
"Grpc",
"Liminal"
]
}
},
"required": [
"identity",
"task_queue",
"transport"
],
"additionalProperties": false
},
"awaiting_worker": {
"type": [
"object",
"null"
],
"description": "The attempt most recently handed out by a recorded fact that nobody has taken since: the last ActivityStarted or ActivityAdoptionOffered in the current lease segment with no ActivityLeased or ActivityServedAtServer for that attempt and no terminal since. A workflow terminal ends every wait, so a run that has ended never names one. It reads recorded facts only: a worker-loss re-dispatch records nothing, so an attempt re-sent after its lessee was lost is not named. A command the server runs itself is never named while it runs: the server records ActivityServedAtServer before the command starts. Read beside current_worker: a run nobody holds that this names is, by the record, waiting for a worker on task_queue since `since`; task_queue is the queue its schedule or latest fallback hop named, null when neither sits in the current segment. Null or absent when nothing recorded is waiting. Not a status: the run stays Running. A statement of the record, never a liveness claim.",
"properties": {
"activity_id": {
"type": "integer"
},
"attempt": {
"type": "integer"
},
"task_queue": {
"type": [
"string",
"null"
]
},
"since": {
"type": "string"
}
},
"required": [
"activity_id",
"attempt",
"task_queue",
"since"
],
"additionalProperties": false
},
"package_version": {
"type": "string",
"description": "The 64-hex content hash of the package this run started under. Absent only for a row that predates the field."
}
},
"required": [
"workflow_id",
"run_id",
"workflow_type",
"status",
"started_at",
"updated_at",
"ended_at",
"parent",
"tags"
],
"additionalProperties": false
}
},
"count": {
"type": "integer"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"provenance": {
"type": "object",
"properties": {
"lease_record_failures_total": {
"type": "integer",
"description": "Leases this install knew and failed to record since it booted. Read against an unattributed attempt: 0 on a run that predates lease events means never recorded here; N > 0 means recorded here with N losses."
}
},
"required": [
"lease_record_failures_total"
],
"additionalProperties": false
}
},
"required": [
"namespace",
"runs",
"count",
"next_cursor",
"provenance"
],
"additionalProperties": false
}
}query
Input and output schemas
{
"inputSchema": {
"type": "object",
"properties": {
"namespace": {
"type": "string",
"minLength": 1,
"description": "The namespace the workflow runs under. This is the authorization scope of the call, not a label: a namespace you do not hold is answered as not-found. Read it off a previous describe_run or list_runs result; never guess it."
},
"workflow_id": {
"type": "string",
"description": "The workflow to query.",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
},
"run_id": {
"type": "string",
"description": "Which run. Omit for the latest.",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
},
"query_name": {
"type": "string",
"minLength": 1,
"description": "A query name the workflow registered. Not a free-text question."
},
"arguments": {
"description": "JSON handed to the query handler, whatever shape the handler expects. Omitted means the handler receives the canonical JSON null document."
}
},
"required": [
"namespace",
"workflow_id",
"query_name"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"workflow_id": {
"type": "string"
},
"query_name": {
"type": "string"
},
"result": {
"description": "The query's own result value, whatever shape the workflow returned."
}
},
"required": [
"workflow_id",
"query_name",
"result"
],
"additionalProperties": false
}
}list_documents
Input and output schemas
{
"inputSchema": {
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"documents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"path",
"name"
],
"additionalProperties": false
}
},
"count": {
"type": "integer"
}
},
"required": [
"documents",
"count"
],
"additionalProperties": false
}
}read_document
Input and output schemas
{
"inputSchema": {
"type": "object",
"properties": {
"path": {
"type": "string",
"minLength": 1,
"description": "The document to read. Workspace-relative, no `..` components, ending in `.awl` (e.g. `flows/etl.awl`)."
}
},
"required": [
"path"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"source": {
"type": "string"
},
"content_hash": {
"type": "string"
}
},
"required": [
"path",
"source",
"content_hash"
],
"additionalProperties": false
}
}check_document
Input and output schemas
{
"inputSchema": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "The AWL source to check, in full."
},
"path": {
"type": "string",
"minLength": 1,
"description": "Where this document lives (or will live) in the workspace, so its schema imports resolve. Workspace-relative, no `..` components, ending in `.awl` (e.g. `flows/etl.awl`)."
}
},
"required": [
"source"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"deploys_green": {
"type": "boolean"
},
"steps": {
"type": [
"integer",
"null"
]
},
"diagnostics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"class": {
"type": "string"
},
"message": {
"type": "string"
},
"line": {
"type": "integer"
},
"column": {
"type": "integer"
},
"range": {
"type": "object",
"properties": {
"start": {
"type": "object",
"properties": {
"line": {
"type": "integer"
},
"character": {
"type": "integer"
}
},
"required": [
"line",
"character"
],
"additionalProperties": false
},
"end": {
"type": "object",
"properties": {
"line": {
"type": "integer"
},
"character": {
"type": "integer"
}
},
"required": [
"line",
"character"
],
"additionalProperties": false
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
}
},
"required": [
"class",
"message",
"line",
"column",
"range"
],
"additionalProperties": false
}
}
},
"required": [
"ok",
"deploys_green",
"steps",
"diagnostics"
],
"additionalProperties": false
}
}Read the tool cards for behavior and the assistant for the editing loop.