> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/guides/agent-usage/schedule-asset-management-flow.md). # Schedule an Asset-Management Flow {% hint style="info" %} **Audience:** Nexus adopters and integrators. **Goal:** Create a scheduled asset-management Task and verify its controller, reserve, Occurrences, and safe recovery boundary. {% endhint %} Scheduling uses `nexus task`. The retired `nexus scheduler` and `nexus tap schedule-task` command families, per-gas-unit priority flags, and default-zero priority model do not apply to this interface. ### Model * A `Task` owns reusable work, reserve funding, immutable controller identity, and one Schedule. * An `Occurrence` is one permanent scheduling opportunity with start/deadline, priority-fee percentage, dispatch/Execution reference, and settlement state. * A recurrence lazily allocates occurrences; it is not a list of eagerly created executions. * A `TaskPointer` is discovery metadata for `nexus task list`, not controller authority. Address or Agent checks authorize controller-gated Schedule and lifecycle mutations; settlement and zero-charge expiration are permissionless maintenance once their preconditions hold. The ownership and runtime path is:
Select policy and publish an eligible Occurrence

Phase 1: Select policy and publish an eligible Occurrence. Keyed facts: Controller selects a default DAG or registered Skill; Scheduler resolves the operation schedule policy from Registered Skill policy before creating the Task Schedule, reserve, and eligible Occurrence.

Resolve Invocation and settle its ExecutionPayment

Phase 2: Dispatch one occurrence and settle its exact payment. Keyed facts: Leader dispatches through Scheduler to DAGExecution; Scheduler creates ExecutionPayment with an exact vertex lock; Invocation applies the exact policy and charges or refunds; ToolCashier receives the completed result.

Record settlement and continue a recurring schedule

Phase 3: Reconcile settlement and continue a recurring schedule. Keyed facts: Maintainer settles finished work; Scheduler reconciles the ExecutionPayment charge/refund lock; the payment returns through TaskPaymentReserve by source; Task starts the Next Execution with the next Skill policy.

The permanent occurrence record moves through this operator-facing lifecycle: ```mermaid stateDiagram-v2 [*] --> Pending: allocated Pending --> Advertised: selected Advertised --> Pending: no longer advertised Advertised --> Executing: dispatched Advertised --> Missed: deadline expires Pending --> Withdrawn: future work removed Advertised --> Withdrawn: future work removed Executing --> Finished: runtime terminates Finished --> Settled: Task accounting reconciled Settled --> [*] Missed --> [*] Withdrawn --> [*] ``` Timing flags map directly to scheduler concepts: | Setting | Meaning | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `--now`, `--at-ms`, `--after-ms` | Start at the current Sui Clock, an absolute millisecond timestamp, or an offset from the current Clock. | | `--deadline-at-ms`, `--deadline-after-ms` | Last dispatch time, expressed absolutely or relative to the resolved start. | | `--priority-fee-percentage` | Standalone ordering and payment percentage; defaults to 20. | | `--recurrence-interval-ms` | Positive spacing between recurring starts, subject to the skill minimum. | | `--recurrence-occurrences` | Optional total number of recurring occurrences, including the first. | | `--recurrence-deadline-*` | Deadline rule applied to recurring candidates. | | `--recurrence-priority-fee-percentage` | Ordering and payment percentage copied to each recurring candidate. | | `--pause-on-failure` | Pause later dispatch after an unsuccessful occurrence; omission uses continue-on-failure. | #### Persist the task input ```bash jq -cS . input.json > task-input.json sha256sum task-input.json > task-input.sha256 ``` If `--remote VERTEX.PORT` materializes input outside the transaction, persist the canonical source input, its checksum, the exact remote-port selection, the command, and the resulting Task receipt. The command does not emit a separate storage receipt; the materialized Task input carries its content digest. #### Create and schedule atomically The default-DAG example below requires the deployment-operator-provisioned, registry-owned default executor. Run `nexus tap default-agent show --json` first and record its Agent/skill target. If it reports `AgentRegistry missing default agent` or the on-chain read raises `EDefaultDagExecutorMissing`, stop and hand the bootstrap/recovery to the deployment operator; a builder cannot create the shared executor through `nexus task schedule`. One delayed default-DAG occurrence: ```bash nexus task schedule \ --dag-id "$DAG_ID" \ --entry-group "$ENTRY_GROUP" \ --input-json "$(jq -c . task-input.json)" \ --prepay-amount-mist 1500000000 \ --occurrence-budget-mist 300000000 \ --after-ms 30000 \ --deadline-after-ms 60000 \ --priority-fee-percentage 20 \ --json > task-receipt.json ``` One Agent-controlled recurring schedule funded from its vault: ```bash nexus task schedule \ --agent-id "$AGENT_ID" \ --skill-id "$SKILL_ID" \ --agent-funded \ --entry-group "$ENTRY_GROUP" \ --input-json "$(jq -c . task-input.json)" \ --prepay-amount-mist 7500000000 \ --occurrence-budget-mist 300000000 \ --recurrence-after-ms 30000 \ --recurrence-interval-ms 3600000 \ --recurrence-occurrences 24 \ --recurrence-deadline-after-ms 60000 \ --recurrence-priority-fee-percentage 20 \ --pause-on-failure \ --json > task-receipt.json ``` Omitting `--agent-funded` makes the active signer address the funding source and controller. The percentage defaults to 20 when omitted and valid explicit values are 10 through 10,000. `occurrence_budget_mist` is the signed total budget for an occurrence: the execution payment later carves its gas budget and priority-fee reserve from that amount. Priority is an accounting charge, not an independent funding source or an amount to add again to the occurrence budget. Of the 7,500,000,000 MIST prepayment, 7,200,000,000 covers 24 full occurrence budgets and 300,000,000 is illustrative headroom, not a protocol guarantee. Size a production reserve as `planned occurrence budgets + an expiration-gas allowance`, then monitor and refill it because the number and cost of missed-occurrence reimbursements are workload-dependent. Capture the Task and first recurring occurrence from the receipt: ```bash export TASK_ID="$(jq -er '.task_id' task-receipt.json)" export OCCURRENCE_ID="$(jq -er '.delta.scheduled[0].reference.occurrence_id' task-receipt.json)" ``` #### Compose a Task in separate transactions Create an empty address-controlled Task: ```bash nexus task create \ --dag-id "$DAG_ID" \ --entry-group "$ENTRY_GROUP" \ --input-json "$(jq -c . task-input.json)" \ --prepay-amount-mist 7800000000 \ --occurrence-budget-mist 300000000 \ --json > task-create.json export TASK_ID="$(jq -er '.task_id' task-create.json)" ``` Add one occurrence and then a recurrence: ```bash nexus task occurrence add \ --task-id "$TASK_ID" \ --after-ms 30000 \ --deadline-after-ms 60000 \ --priority-fee-percentage 20 \ --json > occurrence-add.json export OCCURRENCE_ID="$(jq -er '.delta.scheduled[0].reference.occurrence_id' occurrence-add.json)" nexus task recurrence set \ --task-id "$TASK_ID" \ --after-ms 3600000 \ --deadline-after-ms 60000 \ --priority-fee-percentage 20 \ --interval-ms 3600000 \ --occurrences 24 \ --json > recurrence-set.json ``` Of the 7,800,000,000 MIST prepayment, 7,500,000,000 covers the one standalone plus 24 recurring occurrence budgets and 300,000,000 is the same illustrative, non-guaranteed expiration-gas allowance. Each command is a separate transaction. If recurrence setup fails after Task creation or after the standalone occurrence commits, read authoritative Task and occurrence state before retrying; do not assume an atomic reversal across commands. The recurrence receipt contains its own first occurrence under `.delta.scheduled[0]`; select that ID when you want to follow the recurring candidate rather than the standalone one. #### Observe the schedule and runtime ```bash nexus task inspect --task-id "$TASK_ID" --json > task.json nexus task occurrence list --task-id "$TASK_ID" --json > occurrences.json nexus task occurrence inspect \ --task-id "$TASK_ID" \ --occurrence-id "$OCCURRENCE_ID" \ --follow \ --json > occurrence.json nexus execution inspect \ --task-id "$TASK_ID" \ --occurrence-id "$OCCURRENCE_ID" \ --json > execution.json ``` After runtime finishes, settle and inspect refund accounting: ```bash nexus task occurrence cost --task-id "$TASK_ID" --occurrence-id "$OCCURRENCE_ID" --json > cost-before.json nexus task occurrence settle --task-id "$TASK_ID" --occurrence-id "$OCCURRENCE_ID" --json > settlement.json nexus task occurrence cost --task-id "$TASK_ID" --occurrence-id "$OCCURRENCE_ID" --json > cost-after.json nexus task inspect --task-id "$TASK_ID" --json > task-after.json ``` The Execution is runtime history; the occurrence is the durable scheduling/refund record. Continue lifecycle operations through the Task/occurrence tree. #### Lifecycle controls ```bash nexus task pause --task-id "$TASK_ID" nexus task resume --task-id "$TASK_ID" nexus task refill --task-id "$TASK_ID" --amount-mist 500000000 nexus task recurrence clear --task-id "$TASK_ID" nexus task cancel --task-id "$TASK_ID" nexus task close --task-id "$TASK_ID" ``` * `pause` blocks future dispatch but retains pending work and reserve. * `resume` restores eligible retained work. * `recurrence clear` removes future recurring work without erasing permanent occurrence history. * `cancel` withdraws future work and retains history; it does not erase an in-flight Execution. * `close` is final cleanup only after the Task is non-finalized, has no advertised occurrence, and has no pending or in-flight occurrences. #### Failure recovery * If an advertised occurrence passes its deadline without dispatch, use `nexus task occurrence expire`. * The public CLI expiration is zero-charge maintenance. The leader service may instead reimburse expiration submission gas directly from the Task reserve, so keep reserve headroom beyond the sum of planned occurrence budgets. * If runtime work passes the workflow timeout, use the timeout/refund surface and the execution/walk/payment readback. Retain the exact `invocation_id` and receipt; do not select a cashier candidate by FQN or ToolCashier ID. If a hosted view omits the receipt, use matching CLI/SDK object reads and transaction effects. * If a finished Execution is not reflected in Task accounting, use `nexus task occurrence settle`. * If a state-changing command fails, re-read `task inspect` and `occurrence inspect` before retrying. Earlier transactions may already be committed. * Permissionless example-package wrappers can race operational maintenance. Snapshot Task/state immediately before and after each transaction and bind the snapshots to transaction digests. For each Tool vertex, retain the Task, Occurrence, ExecutionPayment lock, exact Invocation ID and policy terms, settlement/refund receipt, ToolCashier state, and transaction effects. A timeout refunds that exact Invocation before scheduler accounting can settle the Occurrence. A policy update or a new Task cannot repair a stale Invocation identity. See [Invocation policy and settlement model](/concepts/06-payment-vaults-reserves-and-settlement.md#invocation-policy-and-settlement-model) for the policy and receipt contract. For exact flags, see [`nexus task`](/reference/cli/task.md) and [`nexus execution`](/reference/cli/execution.md). For state diagnosis, see [DAG execution diagnosis](/concepts/05-workflow-dag-execution.md#diagnosing-a-stuck-or-failed-run). #### Verification and recovery Record the Task and Occurrence identifiers, then inspect them after dispatch to confirm the expected controller, budget, and execution result. If a scheduled path cannot dispatch, inspect its durable Task and Occurrence state before retrying; do not assume a fresh schedule can repair an active or unsettled occurrence. #### Next * [Execute and settle an Agent](/guides/agent-usage/execute-and-settle-agent.md) * [Register a skill package](/guides/agent-usage/register-skill-package.md) * [Scheduling](/concepts/12-scheduling.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.talus.network/guides/agent-usage/schedule-asset-management-flow.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.