Scheduler Contract

link-scheduler-tool-contract turns an agent's spec ([tool.scheduler]) and its teams into the flags Link Scheduler takes, so its numbers are always the spec's, never the program's nor the machine's. The agent module starts the agent's scheduler with them, and any machine running the scheduler for an agent passes them too.

Its flags

What lnk-scheduler-tool serve and run are given, each read from the spec's [tool.scheduler] (spec.tool("scheduler")).

caps

--per-day, --subagents, --hops, --interval, --late (run or skip) and --time-zone, from the spec's per_day, subagents, hops, interval, late and zone. Missing per_day, subagents, hops, or zone is refused by name. An omitted interval sets no minimum, and an omitted late uses run. Link’s own spec sets all six to 100, 5, 8, 5m, run, and local.

teams

--agent-id <id>, then for each team the agent is on --team-id <name>=<id> and each other member as --teammate <team>/<name>=<agent id>, whom send may reach. An agent on no team gets none of them.

floor_of

--floor owner or --floor member, the agent's floor: the least standing anyone reaches it with. It's member once the spec shares a chat with the agent ([access] message) or it's on a team, and owner otherwise. A call to the scheduler that says no standing makes jobs that keep it, and a call's own standing never goes above it. serve_flags and run_flags include it, and the agent's own serve line does too.

relay

--team-relay <url>, then --team-owner <team>=<account> for each team the agent is on that the relay carries (RelayedTeam, from a hosting account's agent-team list). The runner takes one relay: the first, by the order of the agent's teams, so a team another relay carries is left out. An agent on no relayed team gets none of them.

timeout

--timeout, the spec's [tool.scheduler] firing, how long the runner waits on a firing (30 minutes in Link's spec), a duration read as the spec reads it. It's the runner's alone, never serve's, and none when the spec sets none.

serve_flags and run_flags

serve_flags is the caps, the teams, and the floor. run_flags is those, then --timeout, which run requires: a spec with no [tool.scheduler] firing is refused for it, while serve needs none.

Typed lines

Each of these returns the typed Flags the tool's actions.toml declares for its group, never strings: a caller joins two with with, and writes a line once, with serve(program) or run(program), through the generated argv(). Runner is a program and its Flags, the line an agent runs its jobs with; its argv() is that line. run's --agents file (listed::Listed) is a JSON object naming its schema whose agents are the same Flags, one runner per time zone.

What never asks you

allowed names the calls of its tool that never ask you: list, read and schedules, which only read, and, unless the spec says [tool.scheduler] ask = true, task, message, schedule, send, cancel and unschedule. A recurring schedule asks you whatever allowed says, unless the spec lets it through.

ask_if

ask_if names the calls that ask by an argument, as the sandbox takes them (--ask-if schedule.recurring): each argument the tool declares that asks, but none of the recurring argument when the spec says [tool.scheduler] recurring = "allow".

sandbox_flags

sandbox_flags is what lnk sandbox tool add is given before the tool's command: an --allow for each call allowed names, then, while any call asks by an argument, --ask-if-hint and an --ask-if for each. The hint, from asking.toml, names the setting that lets a recurring schedule through, so a refusal with no one to answer points there rather than at --allow, which an argument that asks doesn't heed.

tool_of

The tool an agent's scheduler is served as on its proxy (lnk sandbox tool add) is scheduler-<agent id>.

Portable Timing

The contract also validates canonical schedule timing and calculates the next occurrence. cron::Cron::in_zone uses an explicit IANA time zone. timing::next preserves an interval's anchor and calculates its next instant independently of the runner's default zone. Import and execution use these same rules, so an unsupported zone or malformed cron is refused before the managed native source is cleared.