Scheduling System

Status: Design landing Reference epics: INK-831 ADRs: ADR-016

Scheduled agent work is how the World Agent acts without a conversation turn kicking it off — a daily catch-up summary, a consolidation pass on memory, a weekly re-validation sweep. This page describes how such work is declared, what permission shape it takes, and how it runs against the same agent graph as any other turn.

Task-runner drives; agent executes

There are two pieces that together make a scheduled agent run happen:

• The Rust task-runner (see Task Runner System) owns schedules, triggers, and catch-up policy. It decides when a scheduled task fires and emits a trigger event.
• The agent runtime (see Agent Core System) executes the task by starting or resuming a turn on a thread_id.

The split is clean. The task-runner knows nothing about LangGraph, subagents, or tool surfaces; it knows about cron expressions, fire times, and missed-fire handling. The agent knows nothing about schedules; it receives “start a turn on thread T with payload P” and runs the graph.

Triggers cross the sidecar IPC surface described in Process Model. They carry the thread_id, the scheduled-task identifier, a timestamp, and the task’s payload. The agent’s response to a scheduled trigger is the same shape as its response to a conversation message — run the graph, checkpoint progress, produce output.

A scheduled run is a turn

A scheduled run is not a separate runtime mode. It is an ordinary turn of the agent graph against a persistent thread_id. The fact that it was triggered by the task-runner rather than by an author message changes nothing about how the graph runs.

Concretely, a scheduled turn:

• Loads the same four tiers of memory (see Agent Memory System).
• Uses the same tool surface (see MCP System).
• Can dispatch the same subagent subgraphs (see Agent Core System).
• Produces output into the same conversation surface (see Conversation System).
• Crosses the same Submit Boundary for writes with the same origin and lifecycle defaults — agent-produced and candidate.

This uniformity is intentional. A scheduled task that wants to write to the workspace does so as a candidate, same as any other agent write. The author triages its output through the same conversation surface. There is no elevated “automation” posture.

Checkpoint resumption on trigger

Scheduled tasks commonly span multiple fires. A weekly research sweep has a natural shape of “pick up where we left off.” The scheduling system handles that through the same LangGraph checkpointer described in Agent Core System.

When a trigger fires, the agent starts or resumes the turn against the task’s thread_id:

• If the previous turn on that thread reached END, the new trigger starts a fresh turn; the graph loads the thread’s memory tiers and begins.
• If the previous turn was interrupted (for an author decision, a permission prompt, or a bounded pause), the trigger resumes via Command(resume=…) if the interrupt is tied to a specific input, or starts a fresh turn if the interrupt has been resolved through another path.
• If the previous turn was canceled or errored, the trigger starts a fresh turn from the thread’s last checkpoint, with context that includes the prior state.

The task-runner does not inspect graph state. It fires on schedule; the agent decides what “start or resume” means based on the checkpoint.

Multi-fire tasks use the channel memory tier to carry durable context across fires. That tier is what makes “pick up where we left off” describable without holding an open run between fires.

Category-based scope grants

Scheduled tasks require a declared category. The category determines what scopes the task is allowed to use when it runs.

A task’s category is declared at creation. The category names a bundle of scopes — which tools are available to that task, what kinds of writes it can produce, which memory tiers it can reach, whether it can dispatch specific subagent subgraphs. Categories are a control-plane concept: they are how the author grants an autonomous task standing up-front, without having to approve each tool call individually on every fire.

Representative categories (the specific set is workspace-level configurable):

• Memory consolidation. Can reach the memory tiers’ read, put, update, and forget tools. Can read workspace content as needed. Cannot write workspace content.
• Catch-up summary. Can read the workspace and memory tiers. Can write candidate summaries scoped to a channel’s conversation surface. Cannot propose canonical content.
• Re-validation walk. Can read the corpus and the re-validation queue (Retroactive Revision). Can produce deviation records and candidate writes. Cannot resolve deviations on behalf of the author.
• Research sweep. Can reach external-read tools (web fetch, attachment body). Can produce candidate pages with derivation links. Cannot promote content to canonical.
• Author-defined. Categories the author creates for their own recurring tasks, with scopes they select explicitly.

Each category’s scope bundle is ordinary capability sets from the Permission System. The novelty here is that the bundle is named and declared once, at task creation, rather than being negotiated per tool call.

The agent running a scheduled task cannot escalate beyond its category’s scope. If the task needs something its category does not grant, the task interrupts for an author decision — which surfaces in the conversation associated with the task, just like any other permission interrupt (see Conversation System).

Autonomous-task categories

Some categories are flagged autonomous. An autonomous category means the task is allowed to complete its work without an author in the loop — its writes remain candidates, its deviation records and callouts surface in the conversation, but the task itself does not wait for a human on every decision within its scope.

Autonomous does not mean unbounded:

• Writes still default to candidate, never canonical. The author always decides which proposals land.
• Interrupts still fire for out-of-category capabilities. The task stops and waits when it hits its scope ceiling.
• Deviations still produce records. The task does not self-dismiss contradictions it finds.

The flag distinguishes tasks that should run to completion whenever they fire (consolidation, re-validation sweeps, scheduled summaries) from tasks whose entire purpose is to produce a proposal for the author to triage immediately (a daily “items needing your attention” digest that is meant to halt before acting).

Autonomous-category flagging is declared at the category level; the author chooses which categories their workspace allows to run autonomously.

Declaring a scheduled task

A scheduled task, at creation, carries:

• A schedule — a cron-like expression or a trigger description.
• A category — from the workspace’s configured category set.
• A channel — the channel whose memory tier and conversation surface the task reads and writes to.
• A prompt or task description — what the agent should do when triggered.
• A catch-up policy — what happens if a fire is missed (skip, run-once-on-restart, run-all-missed).

The task-runner owns the schedule and catch-up policy. The agent owns the category and the prompt — it is what the graph executes when the trigger fires.

See Task Runner System for the full task lifecycle; this page covers only the agent-facing half.

Where output surfaces

A scheduled task’s output goes into its associated channel’s conversation (see Conversation System). Each fire produces at least one turn — the agent’s summary of what it did, or the agent’s candidate-content proposals, or a “nothing to do this fire” note.

The first turn of each fire is marked with the trigger identity so the author sees “this turn was triggered by [schedule name] at [time].” Interactive continuation works: the author replying to the thread turns into a regular conversational turn on the same thread_id. The task-runner does not own the thread exclusively; the thread is just a thread.

Some scheduled tasks do not produce visible turns every fire — consolidation tasks, for example, do their work and may produce only a silent log entry. The conversation surface is authoritative: if the author did not see a turn, no turn was produced.

Cancellation

An author can cancel a scheduled task at any time. Cancellation has two pieces:

• The task-runner stops firing new triggers.
• The currently-running turn, if any, is canceled at its next await. The graph checkpoints where it is; the thread remains resumable if the task is later re-enabled.

Disabling a task does not delete its thread, its channel, or its conversation history. Re-enabling resumes against the same thread.

Failure modes

When a scheduled run fails:

• Tool failure. Handled the same as in any turn. The planner sees the failed tool call, decides whether to retry, work around, or surface a failure note in the conversation.
• Category-scope denial. The turn interrupts for author decision. The thread sits in interrupted state; the next fire does not start a new turn until the interrupt is resolved, per the catch-up policy.
• Sidecar crash. The turn checkpoint remains; when the sidecar comes back, the task-runner’s next scheduled fire resumes against the checkpoint.
• Missed fire. Governed by the catch-up policy on the task. The task-runner applies the policy; from the agent’s perspective, a missed fire that gets caught up looks the same as a normal fire with a delayed timestamp.

What scheduling is not

• Not a separate agent. There is no “scheduler agent” or “autonomous agent” distinct from the World Agent. Scheduled tasks are this workspace’s World Agent, running.
• Not elevated privilege. Category scopes are bounded; the task cannot write canonical, cannot bypass the submit boundary, cannot exceed its category.
• Not a queue. The task-runner fires on schedule; it is not a FIFO backlog that agents pull from. See Task Runner System for the actual scheduling model.
• Not a replacement for subagents. A subagent runs within a turn; a scheduled task is a trigger that starts a turn. A long task is not modeled as “schedule a task to re-fire itself.” It is a single turn with subagent dispatch and checkpoint pauses.

Relationship to other systems

• Task Runner System — owns schedules, triggers, and catch-up policy.
• Agent Core System — executes the triggered turn on the task’s thread_id.
• Agent Memory System — the channel memory tier is how multi-fire tasks carry context.
• Conversation System — scheduled output surfaces in the task’s channel conversation.
• Permission System — category scope bundles are ordinary capabilities.
• Submit Boundary — scheduled writes cross this boundary with origin agent-produced and lifecycle candidate, same as any agent write.

What this page does not do

• It does not describe the cron parser, missed-fire bookkeeping, or catch-up policy internals. See Task Runner System.
• It does not describe how the task-runner is exposed to the UI for authoring schedules. That is a frontend concern.
• It does not describe call-scoped prompt-overlay roles applied at task trigger time. See Role Primitive.
• It does not describe pre-action checkpointing and compact-result substitution within a scheduled turn. See Checkpoint Rewind and Compaction.
• It does not describe subagent dispatch within a scheduled run. See Agent Core System.
• It does not describe the full permission-system model. See Permission System.