Scheduling & Scheduled Events
Scion includes a robust, project-scoped scheduling system that allows you to trigger future events. You can schedule a message to be delivered to an agent—either at a specific time (one-shot) or repeatedly on a calendar schedule (recurring)—or, when the hub.exec_schedules and hub.conduit experiments are enabled, schedule a one-shot or recurring command to run directly in an agent’s container without an LLM turn (--type exec).
All schedules are project-scoped. An agent can only create, list, and manage schedules within its own project.
Two Ways to Schedule
Section titled “Two Ways to Schedule”There are two primary ways to schedule future activities in Scion. They solve different problems:
scion schedule create --in/--at (one-shot) |
scion schedule create-recurring |
|
|---|---|---|
| Nature | Fire-once scheduled event | Durable, recurring event |
| Manageable | ✅ List, inspect, cancel | ✅ List, inspect, pause, resume, delete, history |
| Visibility | ✅ Users with scheduled_event list permission in the project; for an agent caller, only events whose recorded authority is that agent |
✅ Users with scheduled_event list permission in the project; for an agent caller, only schedules whose recorded authority is that agent |
| Recurrence | ❌ No | ✅ Yes (--cron) |
When to use which:
Section titled “When to use which:”- Use a one-shot
scion schedule create --infor simple self-callbacks or quick, one-off delays within an agent’s session (e.g., “ping me in 5 minutes to check CI status”). - Use
scion schedule create-recurringwhen the event is recurring, when the wait outlives the current agent session, or when you need execution history and failure tracking.
One-Shot Events
Section titled “One-Shot Events”One-shot events fire exactly once and are then cleaned up. You can specify the timing in two ways:
- Relative Delay (
--in): Specify a duration such as15m(minutes),2h(hours), or1d(days). - Absolute Timestamp (
--at): Specify an absolute ISO 8601 timestamp in UTC (e.g.,2026-08-03T14:00:00Z).
Creating a One-Shot Schedule via CLI
Section titled “Creating a One-Shot Schedule via CLI”scion schedule create \ --type message \ --agent "deploy-agent" \ --message "Recheck system health" \ --in 15mWhen the hub.exec_schedules and hub.conduit experiments are enabled (both off by default), scion schedule create --type exec (or POST /api/v1/projects/{projectId}/scheduled-events with eventType: "exec") can also run a non-interactive command inside an agent’s container over Conduit without sending a message or starting an LLM turn; see Exec Schedules (Experimental).
Recurring Schedules
Section titled “Recurring Schedules”Recurring schedules fire repeatedly on a 5-field cron expression (Minute, Hour, Day of Month, Month, Day of Week).
Time zones
Section titled “Time zones”By default a cron expression is evaluated in UTC. A schedule can instead carry an IANA time zone (for example America/Los_Angeles): the expression is then matched against local wall-clock time in that zone, so a schedule keeps its local run time across daylight saving changes instead of shifting by an hour. Set it with --time-zone on scion schedule create-recurring, the Time zone field in the Web schedule form, or timeZone in the API. An empty zone, or UTC, means UTC. Next-run times in the API are always UTC instants; the CLI and Web show them in your display zone.
Daylight saving changes create local times that do not exist or that happen twice. For a schedule with a zone:
- A matching local time that is skipped when the clocks go forward (for example 02:30 on the night clocks jump from 02:00 to 03:00) runs once, at the moment of the change (03:00 local). The day is not lost, and several matches inside the skipped hour run once.
- A matching local time that happens twice when the clocks go back (for example 01:30) runs once, at its first occurrence. A schedule that runs more often than hourly (for example every 15 minutes) therefore does not run again during the repeated hour.
- If the next run is computed during the repeated hour after the first occurrence has passed (for example when you create, edit or resume the schedule then), the second occurrence is used: the next run is always in the future.
An unknown zone name, Local, or a name with leading or trailing spaces is refused with 400. Changing a schedule’s zone recomputes its next run and, like changing its cron expression, records your authority for the schedule.
A zone cannot be written inside the expression: an expression that starts with a CRON_TZ= or TZ= prefix is rejected with 400. Schedules created with such a prefix by an older Hub were paused when the Hub upgraded, with a warning in the Hub log. To bring one back, remove the prefix, set the schedule’s time zone instead, and resume it; a prefixed schedule cannot be resumed or enabled as is.
For how Scion handles times and zones elsewhere (API timestamps, display zone, agent TZ), see Times and Timezones.
Schedules paused by the Hub
Section titled “Schedules paused by the Hub”The Hub pauses a recurring schedule on its own in three cases, and records why in the schedule’s status reason (statusReason in the API). scion schedule list shows it after the status, for example paused (creator_deleted), scion schedule get prints it on a Reason: line, and the Web schedule list shows it under the status badge.
| Reason | Cause | To bring it back |
|---|---|---|
creator_deleted |
The agent or user the schedule runs under was deleted, or that user is being deleted, so no fire could be authorized. | Resume it. Resuming records your authority, and the schedule then runs as you. |
cron_zone_unsupported |
The cron expression carries a CRON_TZ= or TZ= prefix. |
Remove the prefix and set the schedule’s time zone instead, then resume it. |
target_deleted |
The target agent of a recurring exec schedule was deleted (checked before creator_deleted, so a self-targeted exec schedule records target_deleted). |
Edit the schedule via PATCH to name a live target agent together with a replacement command (or payload), then resume it (scion schedule resume <id> or POST .../resume, or include "status": "active" in the PATCH). Resuming without re-targeting first fails with 404 because the stored target no longer exists. |
A schedule you pause yourself has no status reason. Any pause, resume or status edit by a user clears the reason.
Creating a Recurring Schedule via CLI
Section titled “Creating a Recurring Schedule via CLI”scion schedule create-recurring \ --name "nightly-cleanup" \ --cron "0 2 * * *" \ --type message \ --agent "cleanup-agent" \ --message "Run database vacuum and log compression"To run at a local time in a time zone, add --time-zone; this one runs at 19:00 Pacific time all year:
scion schedule create-recurring \ --name "evening-report" \ --cron "0 19 * * *" \ --time-zone America/Los_Angeles \ --type message \ --agent "report-agent" \ --message "Post the daily report"scion schedule get shows the zone on a Zone: line (UTC when none is set), and scion schedule list shows it after the expression when it is not UTC. The CLI sets the zone only at creation; change it later in the Web schedule form or with PATCH and timeZone (an empty string sets it back to UTC).
Waking a suspended agent
Section titled “Waking a suspended agent”By default a scheduled message is not delivered to a suspended agent: the fire is recorded as failed. Add --wake to scion schedule create or create-recurring (the Wake agent option in the Web forms, or "wake": true in the API request or message payload) to resume the agent first and then deliver the message. The agent can suspend itself again afterwards, or be auto-suspended. wake applies to message events only; it is refused (400) on a dispatch_agent event or schedule.
scion schedule create-recurring \ --name "morning-check" \ --cron "0 8 * * *" \ --agent "watcher" \ --message "Check the overnight builds" \ --wake- Permission: a fire that resumes the agent needs the permission to start it (
agent.lifecycle), asscion message --wakedoes, checked under the schedule’s recorded authority (see Scheduled Message Authority below). The permission ceiling recorded with that authority must also include it, so a schedule an agent created without the permission does not wake anyone after that agent is given broader rights. Without it, the fire is refused (scheduled_message_denied: message delivery refused), and nothing is started or delivered. An agent that is already running needs no extra permission. - Refusals: a held agent is never woken (the fire is refused), and an agent that is migrating (
scion reincarnate) fails as without--wake. A stopped, errored or halted agent is not resumed: the fire fails withfailed to wake agent <name>: ..., the same reasonscion message --wakegives. Any refusal of the start itself (a delete in progress, capacity, broker placement) fails the fire the same way, and nothing is delivered. - Start already in progress: if the agent is already starting, or another start of it (or a stop) is in progress, when the message fires, the fire does not start it again: it waits for that start to bring the agent up and then delivers. If the agent does not become ready, the fire fails with
target agent was already starting or stopping and did not become ready; message not delivered. - Status while running: a wake fire shows status
firinguntil its delivery outcome is written (fired,expiredorfailed). If the Hub stops before the outcome can be written, recovery marks the eventfailedwithhub stopped before the wake fire completed(and counts the error on the parent recurring schedule). - Auto-wake under
lifecycle.idle_suspend: when thelifecycle.idle_suspendexperiment is enabled, a scheduled message to an agent the Hub suspended (suspendReasonidleorstalled) resumes it automatically even without--wakeand without requiringagent.lifecycleon the schedule’s authority.--wakeis still required to wake an agent a user suspended (suspendReasonuser) or whilelifecycle.idle_suspendis disabled. - Scheduled chat messages are separate from the project scheduler and have their own opt-in Wake the agent if it is suspended option for the primary recipient.
Exec Schedules (Experimental)
Section titled “Exec Schedules (Experimental)”When a one-shot event or recurring schedule only needs to run a deterministic command or script inside an agent’s container—without waking an LLM or consuming a model turn—use --type exec. Scheduled exec dispatches the command (argv) over the target agent’s Conduit session to sciontool inside the container.
Prerequisites
Section titled “Prerequisites”- Hub experiments: Both
hub.conduitandhub.exec_schedulesmust be enabled on the Hub (see Experiments). - Agents launched or restarted with the flag:
sciontoolregisters and advertises theexec-startandexec-statuscontrol routes only when the agent started withhub.exec_schedulesenabled in its launch environment. Agents started before the experiment was enabled do not advertise those routes until restarted; fires targeting them record statusskipped(agent executor unavailable). - NTP-synchronised clocks:
sciontoolenforces a fail-closed start deadline (not_afterplus a 10-second clock tolerance). Agent hosts and containers must run NTP-synchronised clocks; clock skew beyond the 10-second tolerance causes starts to fail closed (start expired (check agent clock)) rather than run late. - Supported runtimes: Container runtimes with Conduit sessions are supported. Managed agent runtimes (
managed:*) are refused with422at authoring (create,PATCH, andresume) andskippedat fire time.
Creating One-Shot and Recurring Exec Schedules
Section titled “Creating One-Shot and Recurring Exec Schedules”Pass the command and its arguments after --. Everything after -- is sent as an argv array (1–64 arguments, non-empty argv[0], no NUL bytes, at most 4,096 bytes per argument and 16,384 bytes total) and executed directly with execve—no shell is invoked unless you name one explicitly (for example -- sh -c '...').
- One-shot (
scion schedule create): requires--inor--at,--type exec,--agent <name>, optional--timeout <duration>(1s–60m, whole seconds, default60s), and-- <argv...>(POST /api/v1/projects/{projectId}/scheduled-eventswitheventType: "exec",fireInorfireAt,agentIdoragentName,command, and optionaltimeoutSeconds, or rawpayload). - Recurring (
scion schedule create-recurring): requires--name <name>,--cron "<5-field>", optional--time-zone <IANA>(defaultUTC),--type exec,--agent <name>, optional--timeout <duration>(1s–60m, whole seconds, default60s), and-- <argv...>(POST /api/v1/projects/{projectId}/scheduleswitheventType: "exec",name,cronExpr, optionaltimeZone,agentIdoragentName,command, and optionaltimeoutSeconds, or rawpayload).--message,--interrupt, and--wakeare rejected with--type exec.
# One-shot exec event in 10 minutes (default 60s timeout)scion schedule create \ --type exec \ --agent "worker" \ --in 10m \ --timeout 60s \ -- /usr/local/bin/check-queue --strict
# Recurring exec schedule every 6 hours in UTC (55m timeout)scion schedule create-recurring \ --name "alt-image-pull" \ --cron "0 */6 * * *" \ --time-zone UTC \ --type exec \ --agent "ops-runner" \ --timeout 55m \ -- /usr/local/bin/pull-images.shIn the Web UI, the project’s Recurring Schedules and Scheduled Events forms also offer the exec event type while hub.exec_schedules is enabled, with an attachable-agent picker, per-argument argv inputs, optional timeout, and run-summary detail and history views.
Execution Environment and Output
Section titled “Execution Environment and Output”- User and groups: Runs as the container’s Conduit PTY user (
scion) with its supplementary groups, never with PID 1 credentials (if privilege drop cannot be established, the run fails closed). - Working directory:
/workspaceif it exists, otherwise thescionuser’s home directory. - Environment: The same environment
sciontoolgives the harness shell in the agent’s tmux session at launch, so scheduled commands see the samePATH, workspace variables, and credentials as commands typed in the agent’s shell. - Standard streams and no stored output:
stdinis/dev/null.stdoutandstderrare continuously drained and discarded inside the container—no command output is stored or returned in the database, API, CLI, or Hub/broker logs. - Run summary (
execSummary): Once an exec event’s run is admitted,ScheduledEventResponse(GET /scheduled-events,GET /scheduled-events/{id}, andGET /schedules/{id}/history) includesexecSummarywithoutcome,exitCode,durationMs,outputBytes,startedAt, andfinishedAt(nevercommand,commandSha256, or command output).scion schedule get <event-id>printsOutcome,Exit Code,Duration, andOutput;scion schedule get <schedule-id>printsLast OutcomeandLast Exit Codefrom the latest history entry; andscion schedule history <schedule-id>rendersSTATUS,OUTCOME,EXIT,DURATION,OUTPUT,FIRED AT, andERROR. Jobs that need readable logs or failure alerts should write their own log file (for example in/workspaceor a shared volume) and, if needed, send alerts from the script withscion message.
Timeouts, Outcomes, Overlap, and Accounting
Section titled “Timeouts, Outcomes, Overlap, and Accounting”- Timeouts:
--timeoutaccepts whole-second durations from1sup to60m(3600s), defaulting to60swhen omitted. Each command runs in its own process group. On timeout,sciontoolsendsSIGTERMto the process group andSIGKILL5 seconds later, recording event statusfailed(timed out after Ns,outcome: timeout). - Exit codes: Exit code
0recordsfired(outcome: ok). Any non-zero exit code recordsfailedwithexit status N(outcome: nonzero). - Target state: The target agent must be
runningwhen the event fires. Stopped, suspended, or reincarnating targets are not woken (--wakeis not supported with--type exec); the fire recordsskipped(target not running). Fires delayed more than 10 minutes past their scheduled time also recordskipped(missed window). A held target is refused asfailed(exec refused). - Recurring overlap lease: Recurring
execfires run detached from the schedule evaluator (nextRunAtadvances before dispatch, so slow starts or hour-long runs never delay other due schedules). While a previous run of the same recurring schedule is still running, a new due fire isskippedwithprevious run in progress—enforced both at the Hub via a per-schedule database overlap lease (an unfinished run row for thatscheduleIdwith an unexpiredleaseUntil = startedAt + timeout + 120s) and inside the container bysciontoolwhile the previous run’s main process is still alive (409overlap). - Recurring run accounting: Each completed fire of a recurring
execschedule updates its counters and last-run fields atomically with the run/event outcome:runCount(run_count) increments by1on every completed fire (success,skipped, orerror).errorCount(error_count) increments by1only on failed fires (non-zero exit, timeout,abandoned, start/dispatch failure, fire-timeexec refused, shutdown abort, or unadmitted crash recovery);skippedfires and exit-0fires do not incrementerrorCount.lastRunAt,lastRunStatus(success,skipped, orerror), andlastRunError(cleared onsuccess; set to the skip or failure reason otherwise) advance monotonically whenever a run’s timestamp is newer thanlastRunAt.
- Container concurrency and authoring quotas: At most 2 live scheduled exec runs per container (
skippedwithcapacity). Authoring quotas cap active exec items—pending one-shotexecevents plus active recurringexecschedules—at20per target agent and200per project (429quota_exceededwhen exceeded; updating or resuming an active schedule excludes itself from the count).
Long-Running Work and flock Mutual Exclusion
Section titled “Long-Running Work and flock Mutual Exclusion”Tracked runs support timeouts up to 60 minutes (--timeout 60m), which is the preferred mode whenever a job fits within an hour because event status, schedule errorCount, overlap leases, and exit codes track the real job directly.
If a job can legitimately run longer than 60 minutes, have a short wrapper script launch the work detached in the background (setsid ... </dev/null >>/workspace/job.log 2>&1 &). When the main process exits normally, sciontool records the outcome immediately and does not kill backgrounded children.
Because detached or daemonized descendants (setsid, double-fork) escape process-group tracking on timeout and release the per-schedule overlap lease as soon as the wrapper exits—allowing a later fire to overlap while the background job is still active—guard detached jobs (and any script touching shared external resources) with flock -n:
#!/usr/bin/env bashset -euo pipefail
exec 9>/tmp/nightly-sync.lockif ! flock -n 9; then # Previous run still holds fd 9; exit cleanly without overlapping. exit 0fi
/usr/local/bin/nightly-sync >>/workspace/nightly-sync.log 2>&1Permissions, Updates (PATCH / resume), Target Deletion, and Redaction
Section titled “Permissions, Updates (PATCH / resume), Target Deletion, and Redaction”- Live
agent.attachauthority: Creating or resuming anexecevent or schedule requiresscheduled_event.create(orscheduled_event.updateonresume/PATCH) in the project and a user or agent that may attach to the agent (agent.attach—for example its owner or an ancestor, a role that grantsagent.attach, or an agent with thefullrole in the same delegation chain; user access tokens also require theagent:attachscope, and delegated agent tokens are refused). That authority is re-checked on every fire against the resolvedagentIdunder the recorded authorization revision and frozen permission ceiling; if revoked, the fire is refused (failedwithexec refused). - Target deletion (
target_deleted): Deleting an agent cancels its pending one-shotexecevents (matched strictly by resolvedagentId) and pauses every active recurringexecschedule targeting thatagentIdwithstatusReason: "target_deleted"(see Schedules paused by the Hub). - Resuming (
POST .../resume/scion schedule resume): Resuming a paused recurringexecschedule requireshub.exec_schedulesandhub.conduitenabled and re-authorizes the caller with liveagent.attachon the stored target agent, clearingstatusReason, recomputingnextRunAt, checking active quotas, and recording a new authorization revision and ceiling. A schedule paused withtarget_deletedcannot be resumed until it has been re-targeted viaPATCH(404while the stored target is deleted). - Updating (
PATCH /api/v1/projects/{projectId}/schedules/{id}): Only user callers withscheduled_event.updatemayPATCHschedule definitions (403for agent callers).eventTypecannot be changed to or fromexec(400,eventType cannot be changed to or from exec), andPATCHon anexecschedule is refused whilehub.exec_schedulesorhub.conduitis off (pauseanddeleteremain operable). AnyPATCHon anexecschedule that suppliespayloador exec convenience fields (agentId,agentName,command,timeoutSeconds) or changes future dispatch (cronExpr,timeZone,payload, or enablingstatus: "active") requires liveagent.attachon the stored target agent (when that target still exists) as well as liveagent.attachon the effective target, and records a new authorization revision and ceiling; metadata-only edits (name, or pausing viastatus: "paused") do not re-attribute. When the previous target agent was deleted, re-targeting to anotheragentIdoragentNamerequires supplying an explicit replacementcommandorpayload(400,retargeting an exec schedule whose previous target was deleted requires command or payload). - Command (
argv) redaction andcommandSha256: Every/scheduled-events,/schedules(includinghistory,create,PATCH,pause, andresume), and/admin/schedulerresponse redactspayloadfail-closed unless the reading caller’s current credential holds liveagent.attachon the stored target agent at read time (/admin/scheduleralways redacts, and the creator is not exempt if they later lose attach permission or read with a token lackingagent:attach). Redacted responses omitcommandfrompayloadand return{"agentId":...,"agentName":...,"timeoutSeconds":...,"commandRedacted":true,"argc":N,"commandSha256":"..."}, whichscion schedule getdisplays onCommand:as<redacted, N args, sha256:...>.commandSha256matchesagentcontrol.ExecArgvDigest: the lowercase hex SHA-256 digest of the canonical UTF-8 JSON array encoding ofcommand(argv), serialized with compact separators, no HTML escaping (SetEscapeHTML(false), so&,<, and>stay literal UTF-8 rather than\u0026,\u003c, or\u003e), and the trailing newline trimmed (niltreated as[]). The same digest is recorded ascommand_sha256on exec audit events (execSummaryitself carries onlyoutcome,exitCode,durationMs,outputBytes,startedAt, andfinishedAt).
Documented Limitations
Section titled “Documented Limitations”- No in-flight cancellation: Cancelling an event, pausing or deleting a schedule, revoking authority, or placing a hold on the target stops future fires from starting, but does not cancel an exec run already admitted in the container; that run continues until it exits or reaches its local timeout.
- Outcome recovery when
hub.conduitis turned off: Turninghub.exec_schedulesoff stops new starts whileexec-statusrecovery for already-admitted runs continues. Turninghub.conduitoff also refuses new or reconnecting agent Conduit sessions, so outcome recovery continues only over agent sessions that stay connected; if the session drops (or the Hub restarts whilehub.conduitis off), the agent cannot reconnect and the run endsabandonedwhen its lease (timeout + 120s) expires.
Patterns and Recipes
Section titled “Patterns and Recipes”1. Self-Scheduling (The Whoami Recipe)
Section titled “1. Self-Scheduling (The Whoami Recipe)”An agent can schedule a message to itself. To do this, resolve your own agent name first:
scion schedule create --non-interactive --type message \ --agent "$(scion whoami --non-interactive --format json | jq -r .name)" \ --message "Check if migration completed" \ --in 15m2. Waiting on External Processes (The Blocked-Wait Pairing Rule)
Section titled “2. Waiting on External Processes (The Blocked-Wait Pairing Rule)”When an agent needs to wait on an external, non-agent process (such as a CI/CD build, cloud deployment, or a third-party API):
- Calling
sciontool status blocked "..."alone is not sufficient. This command only updates your status to satisfy the stall detector — it does not poll or wake the agent up. - You must pair
status blockedwith a scheduled self-callback to act as a wake-up signal.
# 1. Schedule a self-callback message in 5 minutesscion schedule create --non-interactive --type message \ --agent "$(scion whoami --non-interactive --format json | jq -r .name)" \ --message "Recheck CI build status" \ --in 5m
# 2. Set your status to blocked to avoid the stall detectorsciontool status blocked "Waiting for CI run 9428 to complete"status blockedalone → Stall detector is happy, but you go idle forever because nothing wakes you up.- Self-callback alone → You wake up, but the stall detector may flag you as stalled during the 5-minute silent window.
- Both together → Safe, reliable asynchronous polling.
3. Message-to-Orchestrator Pattern
Section titled “3. Message-to-Orchestrator Pattern”To orchestrate agents on a timer (for example, starting a test runner every hour), message a long-lived orchestrator agent rather than scheduling direct agent starts. The orchestrator agent receives the scheduled message and creates/dispatches task agents as needed — keeping agent lifecycle owned by an agent that can reason about failures and state.
Lifecycle Management Commands
Section titled “Lifecycle Management Commands”Use these commands to manage schedules and events in your project:
| Action | Command |
|---|---|
| List all events and schedules | scion schedule list |
| List only recurring schedules | scion schedule list --show recurring |
| List only one-shot events | scion schedule list --show events |
| Inspect a schedule | scion schedule get <id-or-name> |
| Cancel a one-shot event | scion schedule cancel <id> |
| Pause a recurring schedule | scion schedule pause <id-or-name> |
| Resume a recurring schedule | scion schedule resume <id-or-name> |
| Delete a recurring schedule | scion schedule delete <id-or-name> |
| View execution history | scion schedule history <id-or-name> |
Tip: All 6 schedule subcommands (get, cancel, pause, resume, delete, history) support client-side prefix matching. You can provide a truncated schedule ID (e.g. scion schedule cancel a1b2) instead of the full ID.
Gotchas & Best Practices
Section titled “Gotchas & Best Practices”- Unique Names: Schedule names must be unique within the project.
- Cleanup obligation: Recurring schedules fire indefinitely until paused or deleted. Always delete them when the task or project they serve is completed.
- Check before creating: Run
scion schedule listto check for existing schedules before creating new ones. Duplicate schedules will deliver duplicate messages. - Command mismatch:
cancelis strictly for one-shot events.pauseanddeleteare strictly for recurring schedules. Using the wrong command on a schedule type will return an error. - Event retention: The Hub deletes every completed scheduled event (excluding
pendingandfiringevents), including the fires listed byscion schedule history, 7 days after it completed (fired, expired or failed), or 7 days after it was created if it never fired (for example, a cancelled event), whatever its soft-delete retention. Fire and failure outcomes are also written to the Hub log.
Security & Authorization
Section titled “Security & Authorization”To ensure platform security and isolate team activities, schedules and scheduled events are protected by project-scoped role permissions:
- Role-Based Access: Each request on a project’s schedules or scheduled events is checked against the caller’s
scheduled_eventpermission for that action (read,list,create,updateordelete) in the project, granted through the caller’s roles (see Project-Scoped Role Permissions below). A caller without the permission gets403. An agent needs theproject:readscope and reaches only its own project’s schedules and scheduled events; within that project, an agent caller can list, inspect, view history for, pause, resume, cancel, and delete only the schedules and scheduled events whose current recorded authority (initiatorPrincipalKindagent,initiatorPrincipalId) is that agent (a schedule or event with no recorded principal is held by no agent, and any other answers403), and cannot edit schedule definitions (PATCHreturns403). Creating or resuming still passes the event type’s target checks. - Scheduled Agent Identity: An agent created by a schedule is attributed to the schedule’s creator:
CreatorNameis set to the creator’s agent name or user email, as with manual creation. It also receives the project’s default GCP identity. The same service-account authorization checks as manual agent creation run against the creator, and agent creation fails if they do not pass. On adispatch_agentone-shot event or recurring schedule,template(when set) must be a single-path-component template name or a template ID (400,template must be a template name or ID); at fire time, a project default template (scion.io/default-template) in another form fails the dispatch withthe project's default template setting must be a template name or ID, while a Hub default template (agent_defaults.default_template) in another form is ignored with a warning. - Scheduled Agent Runtime Broker: A
dispatch_agentfire picks its Runtime Broker through the same broker selection as a manual agent creation that names no broker, checked against the schedule’s recorded authority: the project default first, with no fallback when it is offline or the creator may not use it. When no Runtime Broker is selected, the fire fails before any agent is created. The recorded error (inscion schedule history) gives the reason manual creation gives, followed by what to do instead, because a schedule cannot name a Runtime Broker: set the project’s default Runtime Broker to an online one the schedule’s creator may use; if a default is set, bring it online, give the creator use of it, or change it; if the project has no Runtime Broker, link one and make it the default. A project with several Runtime Brokers and no default refuses every scheduled fire until a default is set. - Token Authoring: A user access token can create a scheduled event or recurring schedule with
scheduled_event:create, and update, re-target, pause or resume a schedule withscheduled_event:update, on a project or hub token whose boundary contains the project. It must also pass the same target checks as a signed-in request for that event type. The revision records the token, and each fire runs within that token’s permission ceiling and boundary. A fire fails once that token is revoked, deleted or has expired, so a recurring schedule authored with a token stops firing at the token’s expiry; pause and resume it with a sign-in or a newer token to record new authority. This does not cover messages scheduled in a chat conversation, which still refuse every user access token. - Authority recorded per revision (
dispatch_agent): Creating adispatch_agentevent or schedule, and any update, re-target or resume that changes what a future dispatch does, records an authorization revision: who made the request, which credential they used, and that credential’s permission ceiling at the time. Each fire runs under the latest revision. When the event fires, the creator’s principal must be valid at that time: a user principal must be active and holdagent.createin the project, or an agent principal must exist in the project, and an access token the revision was recorded with must not be revoked, deleted or expired. If any check fails, that fire is recorded as failed. For a recurring schedule whose recorded authority is an agent, deleting that agent pauses the schedule withstatusReasoncreator_deleted, and deleting a user does the same for every schedule whose recorded authority is that user, in any project (and the evaluator pauses such a schedule as a backstop if it comes due; see Schedules paused by the Hub). Pausing, deleting and edits that change only metadata write no revision. - Scheduled Message Authority: A scheduled message is sent under the authority recorded by the last request that created the event or schedule, changed what, where or when it sends, or resumed or re-enabled it — not under the original creator’s identity. When the message fires, that principal must be active and admitted to the project, an access token it was recorded with must be live, and the send must pass the same messaging rules as a direct send. For a recurring schedule whose recorded authority is an agent or a user, deleting that agent or user pauses the schedule with
statusReasoncreator_deleted(see Schedules paused by the Hub). A request to create, change or resume a message event or schedule with a credential whose authority cannot be recorded is denied with a 403, as for an agent-dispatch schedule, and nothing is written. A message event or schedule without recorded authority (written before authority was recorded) does not fire, and its event recordsschedule authority not recorded; pause and resume the schedule, or recreate the event. Pausing and resuming the schedule, or recreating the event, records the caller’s authority. - Project-Scoped Role Permissions: Scheduled event permissions come from project-scoped roles. The built-in
project-memberrole carriesscheduled_event.create,scheduled_event.listandscheduled_event.read, andproject-adminalso carriesscheduled_event.update.project-ownercarries all five, includingscheduled_event.delete, and so does the hub-widehub-adminrole. Cancelling or deleting an event or schedule needsscheduled_event.deletefor every user caller, signed in or with a token, including the user who created it, so aproject-membercan create events but not cancel or delete them. An agent is not checked against this permission (see Role-Based Access above). - Required Permissions: To perform scheduler actions, the caller’s token must have the appropriate permission in the project scope:
- Creating/Scheduling: Requires
scheduled_event.create - Listing/Viewing: Requires
scheduled_event.listandscheduled_event.read - Modifying/Pausing: Requires
scheduled_event.update - Deleting/Cancelling: Requires
scheduled_event.delete
- Creating/Scheduling: Requires