> 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/talus-docs-v2.1.0/reference/move/nexus_scheduler/scheduler.md).

# nexus\_scheduler::scheduler

* [Struct `TaskCreatedEvent`](#struct-taskcreatedevent)
* [Struct `TaskPausedEvent`](#struct-taskpausedevent)
* [Struct `TaskResumedEvent`](#struct-taskresumedevent)
* [Struct `TaskCanceledEvent`](#struct-taskcanceledevent)
* [Struct `TaskRejectedEvent`](#struct-taskrejectedevent)
* [Struct `TaskClosedEvent`](#struct-taskclosedevent)
* [Struct `OccurrenceScheduledEvent`](#struct-occurrencescheduledevent)
* [Struct `OccurrenceAdvertisedEvent`](#struct-occurrenceadvertisedevent)
* [Struct `OccurrenceWithdrawnEvent`](#struct-occurrencewithdrawnevent)
* [Struct `OccurrenceMissedEvent`](#struct-occurrencemissedevent)
* [Struct `OccurrenceDispatchedEvent`](#struct-occurrencedispatchedevent)
* [Struct `OccurrenceSettledEvent`](#struct-occurrencesettledevent)
* [Enum `SettlementStatus`](#enum-settlementstatus)
* [Constants](#constants)
* [Function `bind_runtime`](#function-bind_runtime)
* [Function `activate_runtime`](#function-activate_runtime)
* [Function `new_user_task`](#function-new_user_task)
* [Function `new_agent_task`](#function-new_agent_task)
* [Function `new_default_task`](#function-new_default_task)
* [Function `share`](#function-share)
* [Function `schedule`](#function-schedule)
* [Function `schedule_as_agent`](#function-schedule_as_agent)
* [Function `set_recurrence`](#function-set_recurrence)
* [Function `set_recurrence_as_agent`](#function-set_recurrence_as_agent)
* [Function `clear_recurrence`](#function-clear_recurrence)
* [Function `clear_recurrence_as_agent`](#function-clear_recurrence_as_agent)
* [Function `pause`](#function-pause)
* [Function `pause_as_agent`](#function-pause_as_agent)
* [Function `resume`](#function-resume)
* [Function `resume_as_agent`](#function-resume_as_agent)
* [Function `cancel`](#function-cancel)
* [Function `cancel_as_agent`](#function-cancel_as_agent)
* [Function `refill`](#function-refill)
* [Function `refill_from_agent`](#function-refill_from_agent)
* [Function `expire`](#function-expire)
* [Function `expire_with_gas_charge`](#function-expire_with_gas_charge)
* [Function `admit_next`](#function-admit_next)
* [Function `reject_next`](#function-reject_next)
* [Function `settle`](#function-settle)
* [Function `close`](#function-close)
* [Function `close_as_agent`](#function-close_as_agent)
* [Function `continue_on_failure`](#function-continue_on_failure)
* [Function `pause_on_failure`](#function-pause_on_failure)
* [Function `is_continue`](#function-is_continue)
* [Function `advertised_occurrence`](#function-advertised_occurrence)
* [Function `is_idle`](#function-is_idle)
* [Function `is_exhausted`](#function-is_exhausted)
* [Function `is_awaiting_funds`](#function-is_awaiting_funds)
* [Function `can_close`](#function-can_close)
* [Function `settlement_is_pending`](#function-settlement_is_pending)
* [Function `settlement_is_succeeded`](#function-settlement_is_succeeded)
* [Function `settlement_is_failed`](#function-settlement_is_failed)

### Struct `TaskCreatedEvent`

Emitted when a \[`Task`] is created.

```move
public struct TaskCreatedEvent has copy, drop
```

<details>

<summary>Fields</summary>

`task_id: sui::object::IDcontroller:` [`nexus_scheduler::task::TaskController`](/talus-docs-v2.1.0/reference/move/nexus_scheduler/task.md#nexus_scheduler_task_TaskController)`agent_id: sui::object::IDskill_id: u64`

</details>

#### Struct `TaskPausedEvent`

Emitted when a \[`Task`] is paused.

```move
public struct TaskPausedEvent has copy, drop
```

<details>

<summary>Fields</summary>

`task_id: sui::object::ID`

</details>

#### Struct `TaskResumedEvent`

Emitted when a \[`Task`] is resumed.

```move
public struct TaskResumedEvent has copy, drop
```

<details>

<summary>Fields</summary>

`task_id: sui::object::ID`

</details>

#### Struct `TaskCanceledEvent`

Emitted when future \[`Task`] work is canceled.

```move
public struct TaskCanceledEvent has copy, drop
```

<details>

<summary>Fields</summary>

`task_id: sui::object::ID`

</details>

#### Struct `TaskRejectedEvent`

Emitted when current runtime permanently rejects a proposal.

Existing \[`DAGExecution`] obligations remain valid. The controller can reclaim the proposal reserve through \[[`close`](#nexus_scheduler_scheduler_close)] or \[[`close_as_agent`](#nexus_scheduler_scheduler_close_as_agent)] after all admitted obligations drain.

```move
public struct TaskRejectedEvent has copy, drop
```

<details>

<summary>Fields</summary>

`task_id: sui::object::IDreason:` [`nexus_scheduler::task::TaskRejectionReason`](/talus-docs-v2.1.0/reference/move/nexus_scheduler/task.md#nexus_scheduler_task_TaskRejectionReason)

</details>

#### Struct `TaskClosedEvent`

Emitted when a \[`Task`] is finalized and releases its owned resources.

```move
public struct TaskClosedEvent has copy, drop
```

<details>

<summary>Fields</summary>

`task_id: sui::object::ID`

</details>

#### Struct `OccurrenceScheduledEvent`

Emitted when a \[`Task`] allocates one \[`Occurrence`] identity.

```move
public struct OccurrenceScheduledEvent has copy, drop
```

<details>

<summary>Fields</summary>

`task_id: sui::object::IDoccurrence_id: u64start_time_ms: u64deadline_ms: std::option::Option<u64>priority_fee_percentage: u64source:` [`nexus_scheduler::schedule::OccurrenceSource`](/talus-docs-v2.1.0/reference/move/nexus_scheduler/schedule.md#nexus_scheduler_schedule_OccurrenceSource)

</details>

#### Struct `OccurrenceAdvertisedEvent`

Emitted when an \[`Occurrence`] becomes the Task's dispatch candidate.

Allocation and dispatch readiness are distinct. An occurrence may exist while another execution occupies the Task's capacity. Every transition into the advertised state emits this event so leaders can discover the candidate after capacity is restored.

```move
public struct OccurrenceAdvertisedEvent has copy, drop
```

<details>

<summary>Fields</summary>

`task_id: sui::object::IDoccurrence_id: u64effective_start_time_ms: u64deadline_ms: std::option::Option<u64>priority_fee_percentage: u64`

</details>

#### Struct `OccurrenceWithdrawnEvent`

Emitted when an \[`Occurrence`] leaves its schedule without dispatch.

```move
public struct OccurrenceWithdrawnEvent has copy, drop
```

<details>

<summary>Fields</summary>

`task_id: sui::object::IDoccurrence_id: u64reason:` [`nexus_scheduler::schedule::OccurrenceWithdrawalReason`](/talus-docs-v2.1.0/reference/move/nexus_scheduler/schedule.md#nexus_scheduler_schedule_OccurrenceWithdrawalReason)

</details>

#### Struct `OccurrenceMissedEvent`

Emitted when an advertised occurrence expires.

```move
public struct OccurrenceMissedEvent has copy, drop
```

<details>

<summary>Fields</summary>

`task_id: sui::object::IDoccurrence_id: u64missed_at_ms: u64`

</details>

#### Struct `OccurrenceDispatchedEvent`

Emitted when a leader dispatches an occurrence.

```move
public struct OccurrenceDispatchedEvent has copy, drop
```

<details>

<summary>Fields</summary>

`task_id: sui::object::IDoccurrence_id: u64execution_id: sui::object::IDdispatched_at_ms: u64`

</details>

#### Struct `OccurrenceSettledEvent`

Emitted after terminal occurrence settlement.

```move
public struct OccurrenceSettledEvent has copy, drop
```

<details>

<summary>Fields</summary>

`task_id: sui::object::IDoccurrence_id: u64execution_id: sui::object::IDsucceeded: bool`

</details>

#### Enum `SettlementStatus`

Settlement state visible to Task callers.

```move
public enum SettlementStatus has copy, drop
```

<details>

<summary>Variants</summary>

Variant `Pending`Variant `Succeeded`Variant `Failed`

</details>

#### Constants

```move
#[error]
const EExecutionTargetMismatch: vector<u8> = b"Task execution target does not match authority";
```

```move
#[error]
const EDAGMismatch: vector<u8> = b"Task execution config does not select the provided DAG";
```

```move
#[error]
const EInvokerMismatch: vector<u8> = b"Task invoker must be the transaction sender";
```

```move
#[error]
const EDeadlineInvalid: vector<u8> = b"Occurrence deadline is before its start";
```

```move
#[error]
const EOccurrenceExecutionMismatch: vector<u8> = b"Execution does not match the Task occurrence";
```

```move
#[error]
const EOccurrenceBudgetInvalid: vector<u8> = b"Occurrence budget must be greater than zero";
```

```move
#[error]
const ENetworkMismatch: vector<u8> = b"Leader capability does not match the Task network";
```

```move
#[error]
const EUnsupportedWorkAdmission: vector<u8> = b"Task selects an unsupported WorkAdmission contract";
```

```move
#[error]
const EWorkAdmissionDisabled: vector<u8> = b"Task WorkAdmission contract is disabled";
```

```move
#[error]
const ESkillContractStale: vector<u8> = b"Task no longer matches the current Agent skill contract";
```

```move
#[error]
const ESkillContractInactive: vector<u8> = b"Task Agent or skill is inactive";
```

```move
#[error]
const ELeaderNotSelected: vector<u8> = b"Leader is not selected for this Task occurrence";
```

```move
#[error]
const ENoPermanentRejection: vector<u8> = b"Task has no proven permanent rejection reason";
```

#### Function `bind_runtime`

Bind the immutable authority root to this Scheduler package lineage.

This is a one time deployment transition. Later Scheduler releases use \[[`activate_runtime`](#nexus_scheduler_scheduler_activate_runtime)] with the same stable \[`UpgradeCap`] object.

```move
public fun bind_runtime(authority: &mut nexus_kernel::runtime_authority::RuntimeAuthority, authority_cap: &nexus_kernel::runtime_authority::RuntimeAuthorityCap, scheduler_cap: &sui::package::UpgradeCap)
```

#### Function `activate_runtime`

Activate this Scheduler release as the only protocol effect facade.

```move
public fun activate_runtime(authority: &mut nexus_kernel::runtime_authority::RuntimeAuthority, scheduler_cap: &sui::package::UpgradeCap)
```

#### Function `new_user_task`

Creates an address controlled and user funded \[`Task`] for one agent skill.

```move
public fun new_user_task(registry: &nexus_registry::agent_registry::AgentRegistry, dag: &nexus_interface::dag::DAG, tool_registry: &nexus_tool::tool_registry::ToolRegistry, agent: &nexus_interface::agent::Agent, config: nexus_interface::agent::AgentExecutionConfig, prepayment: sui::coin::Coin<sui::sui::SUI>, refund_recipient: address, occurrence_budget_mist: u64, failure_mode: nexus_scheduler::task::FailureMode, ctx: &mut sui::tx_context::TxContext): (nexus_scheduler::task::Task, nexus_scheduler::task::TaskPointer)
```

#### Function `new_agent_task`

Creates an Agent controlled \[`Task`] funded by its payment vault.

```move
public fun new_agent_task(registry: &nexus_registry::agent_registry::AgentRegistry, dag: &nexus_interface::dag::DAG, tool_registry: &nexus_tool::tool_registry::ToolRegistry, agent: &mut nexus_interface::agent::Agent, config: nexus_interface::agent::AgentExecutionConfig, prepay_amount_mist: u64, occurrence_budget_mist: u64, failure_mode: nexus_scheduler::task::FailureMode, ctx: &mut sui::tx_context::TxContext): (nexus_scheduler::task::Task, nexus_scheduler::task::TaskPointer)
```

#### Function `new_default_task`

Creates an address controlled \[`Task`] for the default executor.

```move
public fun new_default_task(registry: &nexus_registry::agent_registry::AgentRegistry, dag: &nexus_interface::dag::DAG, tool_registry: &nexus_tool::tool_registry::ToolRegistry, config: nexus_interface::agent::AgentExecutionConfig, prepayment: sui::coin::Coin<sui::sui::SUI>, refund_recipient: address, occurrence_budget_mist: u64, failure_mode: nexus_scheduler::task::FailureMode, ctx: &mut sui::tx_context::TxContext): (nexus_scheduler::task::Task, nexus_scheduler::task::TaskPointer)
```

#### Function `share`

Shares a fully composed Task.

```move
public fun share(task: nexus_scheduler::task::Task)
```

#### Function `schedule`

Atomically accepts one occurrence under an address controller.

The fixed authority read makes an explicit WorkAdmission disable roll back this entire caller transaction before any proposal state can persist.

```move
public fun schedule(authority: &nexus_kernel::runtime_authority::RuntimeAuthority, task: &mut nexus_scheduler::task::Task, start_time_ms: u64, deadline_ms: std::option::Option<u64>, priority_fee_percentage: u64, ctx: &mut sui::tx_context::TxContext)
```

#### Function `schedule_as_agent`

Atomically accepts one occurrence under an Agent controller.

```move
public fun schedule_as_agent(authority: &nexus_kernel::runtime_authority::RuntimeAuthority, task: &mut nexus_scheduler::task::Task, agent: &nexus_interface::agent::Agent, start_time_ms: u64, deadline_ms: std::option::Option<u64>, priority_fee_percentage: u64)
```

#### Function `set_recurrence`

Atomically accepts one lazy recurrence under an address controller.

```move
public fun set_recurrence(authority: &nexus_kernel::runtime_authority::RuntimeAuthority, task: &mut nexus_scheduler::task::Task, start_time_ms: u64, deadline_ms: std::option::Option<u64>, interval_ms: u64, max_occurrences: std::option::Option<u64>, priority_fee_percentage: u64, ctx: &mut sui::tx_context::TxContext)
```

#### Function `set_recurrence_as_agent`

Atomically accepts one lazy recurrence under an Agent controller.

```move
public fun set_recurrence_as_agent(authority: &nexus_kernel::runtime_authority::RuntimeAuthority, task: &mut nexus_scheduler::task::Task, agent: &nexus_interface::agent::Agent, start_time_ms: u64, deadline_ms: std::option::Option<u64>, interval_ms: u64, max_occurrences: std::option::Option<u64>, priority_fee_percentage: u64)
```

#### Function `clear_recurrence`

Clears recurring work under an address controller.

```move
public fun clear_recurrence(task: &mut nexus_scheduler::task::Task, ctx: &mut sui::tx_context::TxContext)
```

#### Function `clear_recurrence_as_agent`

Clears recurring work under an Agent controller.

```move
public fun clear_recurrence_as_agent(task: &mut nexus_scheduler::task::Task, agent: &nexus_interface::agent::Agent)
```

#### Function `pause`

Pauses address controlled dispatch.

```move
public fun pause(task: &mut nexus_scheduler::task::Task, ctx: &mut sui::tx_context::TxContext)
```

#### Function `pause_as_agent`

Pauses Agent controlled dispatch.

```move
public fun pause_as_agent(task: &mut nexus_scheduler::task::Task, agent: &nexus_interface::agent::Agent)
```

#### Function `resume`

Resumes address controlled dispatch.

```move
public fun resume(task: &mut nexus_scheduler::task::Task, ctx: &mut sui::tx_context::TxContext)
```

#### Function `resume_as_agent`

Resumes Agent controlled dispatch.

```move
public fun resume_as_agent(task: &mut nexus_scheduler::task::Task, agent: &nexus_interface::agent::Agent)
```

#### Function `cancel`

Cancels future work under an address controller.

```move
public fun cancel(task: &mut nexus_scheduler::task::Task, ctx: &mut sui::tx_context::TxContext)
```

#### Function `cancel_as_agent`

Cancels future work under an Agent controller.

```move
public fun cancel_as_agent(task: &mut nexus_scheduler::task::Task, agent: &nexus_interface::agent::Agent)
```

#### Function `refill`

Refills an address funded Task reserve and advertises restored work.

```move
public fun refill(task: &mut nexus_scheduler::task::Task, funds: sui::coin::Coin<sui::sui::SUI>, ctx: &mut sui::tx_context::TxContext)
```

#### Function `refill_from_agent`

Refills an Agent funded Task reserve and advertises restored work.

```move
public fun refill_from_agent(task: &mut nexus_scheduler::task::Task, agent: &mut nexus_interface::agent::Agent, amount: u64)
```

#### Function `expire`

Expires exactly the advertised occurrence.

```move
public fun expire(authority: &nexus_kernel::runtime_authority::RuntimeAuthority, task: &mut nexus_scheduler::task::Task, expected_occurrence_id: u64, clock: &sui::clock::Clock, ctx: &mut sui::tx_context::TxContext)
```

#### Function `expire_with_gas_charge`

Expires the advertised occurrence and consumes its leader submission gas charge.

```move
public fun expire_with_gas_charge(authority: &nexus_kernel::runtime_authority::RuntimeAuthority, task: &mut nexus_scheduler::task::Task, leader_registry: &nexus_registry::leader::LeaderRegistry, leader_cap: &nexus_primitives::owner_cap::CloneableOwnerCap<nexus_registry::leader_cap::OverNetwork>, expected_occurrence_id: u64, gas_charge: u64, clock: &sui::clock::Clock, ctx: &mut sui::tx_context::TxContext)
```

#### Function `admit_next`

Admits exactly one accepted occurrence into a funded protocol obligation.

Proposal metadata is never runtime authority. The current runtime revalidates its contract, Agent skill revision, policies, leader, DAG, authorization, and funding before \[`DAGExecution`] creation. A later WorkAdmission disable does not revoke an occurrence whose scheduling transaction already succeeded.

```move
public fun admit_next(authority: &nexus_kernel::runtime_authority::RuntimeAuthority, task: &mut nexus_scheduler::task::Task, dag: &nexus_interface::dag::DAG, registry: &nexus_registry::agent_registry::AgentRegistry, tool_registry: &nexus_tool::tool_registry::ToolRegistry, leader_registry: &nexus_registry::leader::LeaderRegistry, leader_cap: &nexus_primitives::owner_cap::CloneableOwnerCap<nexus_registry::leader_cap::OverNetwork>, expected_occurrence_id: u64, gas_charge: u64, clock: &sui::clock::Clock, ctx: &mut sui::tx_context::TxContext): nexus_workflow::execution::DAGExecution
```

#### Function `reject_next`

Commits a proven permanent rejection and makes the reserve reclaimable.

An abort cannot represent rejection because it would roll back the Task transition and any charge. Only the selected current leader may commit this transition, and the reason is derived entirely from onchain state. Selection derives from the Task and occurrence identity, then alternates the stake-weighted primary and backup every 30-second submission window using the supplied Clock. The budget check runs before the Task mutation.

```move
public fun reject_next(authority: &nexus_kernel::runtime_authority::RuntimeAuthority, task: &mut nexus_scheduler::task::Task, dag: &nexus_interface::dag::DAG, registry: &nexus_registry::agent_registry::AgentRegistry, leader_registry: &nexus_registry::leader::LeaderRegistry, leader_cap: &nexus_primitives::owner_cap::CloneableOwnerCap<nexus_registry::leader_cap::OverNetwork>, expected_occurrence_id: u64, gas_charge: u64, clock: &sui::clock::Clock, ctx: &mut sui::tx_context::TxContext): nexus_scheduler::task::TaskRejectionReason
```

#### Function `settle`

Settles one execution back into its owning Task.

```move
public fun settle(authority: &nexus_kernel::runtime_authority::RuntimeAuthority, task: &mut nexus_scheduler::task::Task, execution: &mut nexus_workflow::execution::DAGExecution, clock: &sui::clock::Clock): nexus_scheduler::scheduler::SettlementStatus
```

#### Function `close`

Finalizes an address controlled \[`Task`] and refunds its recorded source.

```move
public fun close(task: &mut nexus_scheduler::task::Task, ctx: &mut sui::tx_context::TxContext)
```

#### Function `close_as_agent`

Finalizes an Agent controlled \[`Task`] and refunds its vault.

```move
public fun close_as_agent(task: &mut nexus_scheduler::task::Task, agent: &mut nexus_interface::agent::Agent)
```

#### Function `continue_on_failure`

Returns the default continue behavior.

```move
public fun continue_on_failure(): nexus_scheduler::task::FailureMode
```

#### Function `pause_on_failure`

Returns explicit pause behavior.

```move
public fun pause_on_failure(): nexus_scheduler::task::FailureMode
```

#### Function `is_continue`

Returns whether a failure mode continues.

```move
public fun is_continue(mode: nexus_scheduler::task::FailureMode): bool
```

#### Function `advertised_occurrence`

Returns the advertised occurrence.

```move
public fun advertised_occurrence(task: &nexus_scheduler::task::Task): std::option::Option<nexus_scheduler::schedule::Occurrence>
```

#### Function `is_idle`

Returns whether no future occurrence exists.

```move
public fun is_idle(task: &nexus_scheduler::task::Task): bool
```

#### Function `is_exhausted`

Returns whether the skill occurrence quota is exhausted.

```move
public fun is_exhausted(task: &nexus_scheduler::task::Task): bool
```

#### Function `is_awaiting_funds`

Returns whether one occurrence cannot currently be funded.

```move
public fun is_awaiting_funds(task: &nexus_scheduler::task::Task): bool
```

#### Function `can_close`

Returns whether the Task may be closed.

```move
public fun can_close(task: &nexus_scheduler::task::Task): bool
```

#### Function `settlement_is_pending`

Returns whether settlement is pending.

```move
public fun settlement_is_pending(status: nexus_scheduler::scheduler::SettlementStatus): bool
```

#### Function `settlement_is_succeeded`

Returns whether settlement succeeded.

```move
public fun settlement_is_succeeded(status: nexus_scheduler::scheduler::SettlementStatus): bool
```

#### Function `settlement_is_failed`

Returns whether settlement failed.

```move
public fun settlement_is_failed(status: nexus_scheduler::scheduler::SettlementStatus): bool
```


---

# 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/talus-docs-v2.1.0/reference/move/nexus_scheduler/scheduler.md?ask=<question>&goal=<user_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.