Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

▶️Inspecting Tasks and Executions

Audience: Anyone following a run — from the moment it was scheduled to the moment its payment settled.

Goal: Trace one run across its three objects: the Task that scheduled it, the Execution a leader dispatched, and the payment that funded and settled it.

Running a agent skill creates a Task; a leader dispatches an eligible occurrence of it into an Execution; an execution payment funds and settles the work. These are three objects, three pages, and one story: every page links sideways to the other two, so start from whichever id you have. To create and verify this chain through wallet-authorized surfaces, follow Execute and Settle an Agent.

When Vision omits Invocation fields: Inspect the exact policy-backed Invocation through matching CLI/SDK bindings and effects. The Execution owns the Invocation after the lock receipt is consumed; a non-refund Finalize outcome sends the completed object to the ToolCashier inbox and charges the snapshotted FixedPrice amount, while a Refund outcome unlocks SUI and may transfer a reserve-carrying Invocation before Task/Occurrence cleanup. A timeout is a defined refund path, but a Tool or evidence failure is not automatically a refund: inspect the matching settlement receipt or was_refunded field. Correlate the Invocation ID and policy with the Tool, payment lock, and amount.

Invocation view availability

The retained Vision screenshots and provisional deployment URL do not prove that Explorer exposes an Invocation ID, policy witness, lock receipt, or refund control. The UI evidence is authoritative only for the Task, Occurrence, Execution, and payment views it visibly contains. When the hosted projection omits Invocation fields, use nexus execution authorize, the exact invocation_id, InvocationPolicyCall, direct object reads, and transaction effects from a client whose bindings match the selected network. Do not infer Invocation settlement from a historical payment screenshot.

Tasks

Activity → Tasks lists tasks newest first, each with its id, Creator, the Workflow it runs, and a shape badge: Single run (a task registered to fire once — a run wearing a task's clothes), Scheduled (a queue of occurrences), Recurring, Completed, or No work queued.

The task page

/explorer/task/<taskId> is the authoritative view of one task, live-polled:

  • Run — the lifecycle of the active or latest occurrence: Submitted → Advertised → Executing → Finished → Settled, with the execution linked as soon as a dispatch creates one. The retained UI derives this lifecycle from the Task, Occurrence, and Execution objects rather than treating a local display state as authoritative.

  • Occurrences — every occurrence with its status, start, and deadline, and a link to the transaction that recorded each change. The status is read straight off the task's own occurrence record, not reassembled from event streams.

  • Periodic Schedule — the recurrence, if any: interval, start, remaining runs, per-run cap, and the reserve behind it.

  • Metadata and Input Data — what the task was created with.

  • Close and release funds — offered once the task is idle. When it is not yet closable, the card names which condition blocks it: work still scheduled, a recurrence still set, or an occurrence still in flight.

  • A reserve notice when the task has future work its payment reserve cannot fund, with a refill action.

The retained Explorer surface may not expose TaskStatus::Rejected { reason } or TaskRejectedEvent fields. Until a Vision build projects them, inspect the Task/Occurrence/Execution/payment objects and transaction effects through matching CLI/SDK bindings and do not infer permanent rejection from an unavailable leader or failed submission.

A task page with the Run lifecycle card and occurrences table
The task page: Run card's lifecycle, occurrence table behind it.
Read and record permanent rejection before dispatch
Phase 1: Read and record rejection before dispatch. Keyed facts: Reader observes the Leader-authorized rejection; Task withdraws the Occurrence with TaskRejected ID + reason before dispatch, and no Execution ID is created.
Charge bounded maintenance gas, emit event, drain, and close
Phase 2: Charge bounded maintenance gas, emit the rejection event, drain, and close. Keyed facts: Task → TaskPaymentReserve consumes bounded maintenance gas; Task → Events emits TaskRejectedEvent independently; Controller → Task waits for in-flight work to drain and then closes through the address or Agent authority; Task → Controller returns the remaining reserve. TaskRejectedEvent does not drive Controller close.

If the selected build still has the deployed four-state SDK/CLI snapshot, do not invent the missing status or decoder: inspect Task/Occurrence/Execution/payment objects and transaction effects, report the rejection surface as unavailable, and never infer permanent rejection from an unavailable leader or failed submission. A retained screenshot that lacks this control is historical UI evidence, not contrary protocol state.

Reading an occurrence's status

Status
Meaning

Pending

Recorded on the task, not yet offered to leaders

Advertised

Offered to leaders, waiting to be dispatched

Executing

Dispatched; an execution exists — the trace link is live

Finished

The runtime work is done

Settled

A separate transaction has settled the occurrence back onto its task

Missed

A dry reserve alone remains advertised/awaiting funds; after an applicable deadline, an explicit expire transaction may record the occurrence as Missed

Withdrawn

Removed: its recurrence was replaced or cleared, or the task was cancelled

Three rules for reading this table honestly:

  • Finished is not settled. Settlement is a later transaction; a run is not closed out until the chain reports Settled, so do not infer completion from browser timing.

  • A future start waits. An immediate occurrence has no protocol latency guarantee; one whose start is in the future stays Advertised until then. Advertised is not a failure.

  • An elapsed deadline is not a state change. The occurrence stays advertised until an expire transaction records it Missed, and that is not reliably automatic. The page shows the deadline and the status and leaves the verdict to the chain — it will not compare the deadline to your browser's clock and declare the run dead.

Executions

Activity → Executions lists runs — each with its id, the Workflow and Agent it ran under, an outcome badge (Success, Failed, Aborted), and its time.

The captured Protocol / interface version fields in the execution details are historical UI evidence from the retained Explorer surface, not proof that a selected deployment treats a mutable Protocol object or displayed version as live runtime authority. Resolve RuntimeAuthority, interface version, package era, and object witness from matching bindings and transaction effects; see Protocol Upgrades and Compatibility and the authorization reference.

The execution page

/explorer/execution/<executionId> — one run through the DAG, top to bottom:

  • Execution Summary — the outcome, with a plain-language recap of the data flow: which vertex ran, what it received, what it produced.

  • Execution Details — Agent, Skill (with a diagram preview), Task, Occurrence, Leader, Invoker, Entry group, Started, Priority fee, Vertices evaluated, and the historical Protocol / interface fields retained by this UI. This block is the sideways index: every available field is a link; live authority still comes from RuntimeAuthority/interface/era evidence in the selected build.

  • Execution Inputs — the values each entry port received.

  • Data Flow — the walk through the vertices, each with its Input and Output ports and values. A value rendered from the tool's returned vector is marked as such; one that arrived from outside the run over a static edge is marked too. A vertex where the walk stopped says so (Never produced output, Terminal failure), and a walk that ran out of money reads Stalled — insufficient budget with Required, Available, and Short by.

  • Execution Log — every step structurally, as a collapsible list: the tool invoked, the leader, the verifier's Decision where one ran, Failure evidence where a tool failed, each step's Outcome. A partial read is labelled Trace incomplete rather than passed off as the whole run.

  • Execution Output — the workflow's final output (or Execution Failed with the failure).

  • Transaction History — the raw Sui transactions behind the run, each openable on the transaction page. Their success rate is separate from whether the DAG itself finished, and the page says so.

While a run is in progress the page updates live; it settles into Execution completed successfully or Execution failed when the run rests.

The Data Flow section of an execution, vertex by vertex
Data Flow: every vertex with the ports it received and produced.
The execution output card showing the workflow's result
Execution Output: the run's result, stated as precisely as its failures are.

Payments

Activity → Payments is a feed of payment events rather than a list of objects — Funded, Settled, Refilled, Refunded, Canceled, Gas Consumed — each naming the Execution and Agent it belongs to and the Amount. It is built from the same scan as the home feed and the dashboard's Payment Volume chart, so the three agree.

Settlement decision before payment recovery

The payment page’s failure or timeout label is not the settlement decision. Inspect the Task/Occurrence/Execution, ExecutionPaymentVertexLock { vertex_key, invocation_id, amount }, exact Invocation, settlement receipt, and transaction effects. Read was_refunded: Finalize charges the snapshotted amount even when terminal evidence is not a success variant, while Refund releases locked SUI back into ExecutionPayment and may route a policy reserve to refund_to for a later claim. Choose the ToolCashier inbox, refund destination, or entitlement claim from that receipt, not from the Explorer failure badge or historical screenshot.

Explorer reads settlement evidence
Phase 1: Explorer reads settlement evidence.
Finalize a paid Invocation after exact lock removal
Phase 2: Finalize a paid Invocation after exact lock removal. Keyed facts: ExecutionPayment settles the exact lock into InvocationSettlementReceipt plus Paid Balance; Invocation::resolve consumes receipt + paid balance after the Exact ID check; paid equals the snapshot and ToolCashier performs join + receive.
Refund an Invocation after exact lock removal
Phase 3: Refund an Invocation after exact lock removal. Keyed facts: the refunded ExecutionPayment retains SUI; InvocationSettlementReceipt carries was_refunded=true; Invocation::resolve consumes the receipt and zero Paid Balance after the Exact ID check; refund_to transfers to Invocation, while no refund_to destroys the empty alternative outcome.

The sequence keeps terminal evidence and accounting status separate, so a failure can be charged or refunded only according to the recorded settlement decision.

The payment page

/explorer/payment/<executionId> — the execution payment behind one run:

  • The hero — Max Budget, Budget Used, Gas Consumed, and, for an agent-funded run, Agent Vault Available, with links to the funding transaction and the funder's profile.

  • Payment Timeline — funding, per-vertex locks and settlements, refills, and the final accomplishment or refund, in order.

  • Cost breakdown — where the money went: Tool fees, Leader fee, gas for the prepare transaction, the vault total, and what came from the wallet versus the budget vault, with any share charged to a tool developer called out.

  • Payment Actions — the write side, below.

A run with no execution payment says No Execution Payment For This Execution rather than rendering zeros; the page must not infer an Invocation or Tool charge from an absent payment object.

A historical payment page with timeline and cost breakdown
Historical UI evidence only: this captured payment page is not authoritative for Invocation arithmetic, lock state, or settlement totals. Verify live values from the selected build's exact objects and transaction effects.

Resolving a stalled run

Under Payment Actions, first confirm the selected build's help/readback and transaction effects expose the relevant write path. Do not sign from a screenshot or assume that a control in a retained Vision deployment exists in another build.

  • Top up budget — first prove the state: “no Execution” may mean permanent rejection rather than Task reserve shortage. Refill the Task only when Task/Occurrence inspection or dispatch effects prove the reserve shortfall; otherwise refill the exact ExecutionPayment and retry the failed authorization/settlement transition. Topping up does not pay the wallet’s immediate Sui transaction gas.

  • Settlement — after a walk settles its ExecutionPayment, there is no separate ExecutionPayment settle step to submit. A finished scheduler occurrence may still need nexus task occurrence settle before its Task is idle and can close; verify the occurrence reports Settled and zero in-flight work. Exact Invocation settlement/refund happens first and does not replace scheduler occurrence settlement.

  • Cleanup — for an execution past its expiry, use Abort expired only when at least one active walk is beyond the double-timeout boundary, no committed result awaits settlement, and payment locks are cleared by exact Invocation refund. The client may pass finalized invalid-stamp results into the same abort transaction for atomic cleanup; a consumable or unfinalized raw result blocks it. Anyone may submit the eligible permissionless path; submitting early aborts with the protocol’s own error and changes nothing.

The page works out which resolution applies before opening your wallet. Two rules it holds that are easy to get wrong by eye: the active DAG walk stores its timeout_ms snapshot when the walk is created or advanced, the effective walk timeout is that captured value plus the five-second leader-evaluation buffer, and the abort window is double that effective timeout, judged against the on-chain clock, not your browser’s. A later Tool timeout update does not rewrite an existing walk; use execution/walk readback and transaction effects rather than the Tool-directory card at inspection time. Only an active walk is abortable—one already awaiting settlement is settled, never aborted. A walk stalled on an on-chain tool can leave a result object behind that the abort must clean up in the same transaction; the page scans for those and either fills them in or reports what blocks the abort. When a policy-backed Invocation is locked, timeout recovery names the exact invocation_id and refunds it before applying the abort transition, but the owning occurrence may still need a separate nexus task occurrence settle --task-id <task-id> --occurrence-id <occurrence-id> transaction; verify Settled and zero in-flight work before closing the Task. See Invocation policy and settlement model and DAG execution diagnosis.

Last updated