Developing

lnk-scheduler-tool is Link Scheduler: subagents and schedules for any harness that reads who a message is from. Link Scheduler explains usage, and scheduler decisions explains the durable-job and conversation-scope choices behind these mechanisms.

Build and test

From the repository root:

cargo build -p link-scheduler-tool
cargo test -p link-scheduler-tool

Its two programs

serve --state <dir> is the tool, an MCP server over stdio, and run --state <dir> --way-in <socket> the runner. No number is the program's own: each comes from the agent's spec (Scheduler Contract).

Their flags

Both take the caps (--per-day, --subagents, --hops, --interval, --late), the connections a schedule's answer may go to (--connection), and the time zone its times are in (--time-zone, local or a zone's name, which it sets as the process's TZ after checking the machine's zone database has it). The runner also takes how long it waits on a firing (--timeout), which Link reads from the agent's spec ([tool.scheduler] firing).

The runner as its agent

The runner, and the tool serve makes, act as its agent alone (--as <agent id>), on a team or not, so a schedule's firings and their retries keep one identity. Each of the runner's firings is a bridge's call (link_sandbox_bridge), proved with the agent's key, read from the machine's keyring (--keyring <dir>, else Link's, ~/.lnk/safe/agents/credentials) at each firing, since the key is made at each start. An agent that isn't running has no key, and its firing waits to be tried again.

A teammate's bridge

A teammate's bridge takes a message from the runner only as this agent's, and only into its conversation with it or a team's they share.

A call's conversation

A call says which conversation it's made in, and how many messages led to it, in its _meta (link.local/thread, link.local/hops), as Link Harness sends them, never in arguments the model writes. The owner's command line alone says link.local/all on a list, for every conversation's jobs (lnk agent task list --all).

Its standing

A call also says the standing of the message its conversation is answering (link.local/standing: owner, member or stranger), its sender's at most what that message's firing carried. Every job keeps it, and its firing carries it to the bridge, which tells the harness, so a schedule, a subagent or a message to a teammate never fires as more than the conversation that made it. A message a teammate relays stands as a member's, and a schedule from the agent's spec as its owner's.

Its floor

A call that says no standing, from a harness that sends no _meta, keeps the agent's floor (--floor): owner while only its owner messages it, member once a chat is shared with it or it's on a team, as Link works it out from the agent's spec and its teams. A harness's standing never goes above the floor, and one that isn't a standing makes nothing.

Its tools

A harness that keeps a conversation's tools says them too (link.local/tools, their names): task's tools must be among them, and left out, the subagent gets them all, so a narrowed conversation's subagent is never wider. Without link.local/tools, a job has no list (the subagent gets every tool, as its harness gives them), and task refuses an explicit tools list.

The job's list

A schedule a subagent makes keeps its conversation's list too, so it fires with no more; another conversation's isn't kept, since a list narrows the conversation it fires in for good. The job keeps the list (tools), and its firing carries it to the bridge, which sends it with the task (Link-Tools); said as anything but a list of names, it's read as none.

Its parent

A subagent's firing also names the conversation that started it (parent, the thread its answer goes to). A harness that keeps its work in a store of its own records the subagent as that conversation's child from it before taking the task, as the harness protocol says.

Scoped to it

A call is scoped to its conversation: list, read, cancel and task's after see the jobs sent to it, the subagents it started (answer its thread), and theirs, and the messages to teammates sent from it, waiting, being fired or ended. list gives the soonest 100, and cut, how many more there are.

Teams

An agent on a team is given its ID (--agent-id), its teams (--team-id <name>=<id>) and their other members (--teammate <team>/<name>=<agent id>), and the runner each teammate's way in (--way-in-of <agent id>=<socket>).

send

send is offered only with teammates, to one of their names (or <team>/<name> where two teams' members share one) or a team's, a job each (kind send, to the two agents' IDs). Its thread is the teammate's agent-<this agent's ID> (or team-<team ID>), and its answer the conversation it was sent from.

Its firing and answer

The runner fires it at the teammate's way in, from agent:<this agent's ID>, its answer nowhere there, and keeps what it's answered as a job of its own (kind reply, from agent:<teammate's ID>, one hop on) to that conversation. So delivering the answer, failed and tried again, never sends the message twice.

The team relay

On a machine that carries no message itself, a team's message to a teammate on none of its ways in goes through the team relay: the account that hosts the team, at --team-relay <url>, for each team given its owner (--team-owner <team>=<account>). It needs --agent-id, and isn't taken with --driver address, whose machine carries messages already. The wire is link_agent_place::relay. Link's agent module gives these flags from a hosting account's agent-team list (link_scheduler_tool_contract::relay).

A message out

Relayed holds the runner's driver. A send job to a teammate that driver doesn't reach, on a team's conversation (team-<ID>) the relay carries, is posted as a TeamSend for that teammate (to), with its hops and text, to /v1/teams/<owner>/<team>/messages. It's done once the relay took it, and a refusal is a failure, tried again as any firing is. A message on the agent's own conversation with a teammate (agent-<ID>) never goes through the relay.

Messages in

At each look, and at each wake of a runner that isn't resident, the runner asks its driver for what waits elsewhere (Driver::arrivals). Relayed pulls each team's mail after the last message it had (?after=<seq>, kept by team in team-relay.json in the state, naming its schema) and puts each message as a job of its own. It's a reply from agent:<the sender's ID> on the team's conversation, with its hops, answered nowhere, and fires through the agent's way in as any job does.

Its cursor

The cursor moves past a message once its job is kept, so a failure pulls it again. A look takes at most four pages of 64, and none while 1,000 jobs wait. On a runner for good, a message comes in within the minute it looks at most.

Where the jobs are kept

The jobs are kept behind a seam, JobStore (src/store.rs): put, get, list, count, move between waiting and being fired, remove, when the soonest is due, and the day's count, so a machine whose agent keeps its state off it gives another. store::Memory keeps them in memory for tests.

The locks

The rest of the store (runner.lock and post.lock) stays in the state folder on the machine. Each lock is opened in place, never through a link put at its name (O_NOFOLLOW), so whoever else writes the state folder can't point the runner or a post at a file elsewhere. The runner holds its shared lock until its firings end. The multi-agent test observes that lock released before checking that a removed agent's jobs stay queued while another agent's jobs continue to fire.

The file store

The store uses the shared file driver (store::Stored, link_store_contract::store::file). schedule/jobs/<id>.json holds each job, written aside and moved in place, so the tool and the runner never see half of one, and schedule/day.json the day's count, the day in its time zone.

firing/

schedule/firing/<id>.json is a job the runner took to fire, moved there from schedule/jobs/ (a cancel meanwhile wins the move) and back with its next time or its next try once the firing ends, or removed. A subagent is at work while its task is in either folder. At its start, a runner alone moves what's in firing/ back, each counted as a try.

ended/

A delegation (a subagent, a message to a child or a teammate) that ends for good is kept in schedule/ended/<id>.json with its outcome ({"at", "ended": "done" | "failed" | "cancelled", "answer" | "why"}), the store contract's ended place, never due. Ended jobs older than a week, and past the 256 most recent, are forgotten. These numbers and the tool's other limits (the longest message, the most jobs waiting and listed, a firing's retries and lateness, the runner's interval, and the relay's pulls) are in src/limits.toml, read once into Limits.

parent and after

A job keeps its parent (the task that started it, from the conversation it was started in) and after (the jobs it waits on, each its own conversation's). The runner fires a job whose after all ended done, and cancels one whose after failed, was cancelled or is gone.

Cascading

A cancel or a failure cancels the jobs whose parent or after names it, under the jobs' lock; ending one wakes the runner for those waiting on it.

What it counts

The 1,000 jobs that may wait are counted by their files in schedule/jobs/, through the store contract. Without a retained host, subagents are counted by the waiting and firing jobs’ kinds; with one, retained child state also counts until its result is delivered or its record is archived or deleted. A move carries each job and the day's count through that same contract.

Portable Definitions

The runner accepts --definitions <file>, a JSON object naming its schema whose schedules are the canonical portable schedules published from the agent spec after native handoff. The resident, calendar, addressed and shared runners project them into the existing job store. The MCP tool does not activate native imports.

Activation Records

Each definition has a stable identity and revision. Projection records pending and ready activation under the scheduler's definitions lock, each record naming its schema. Dispatch refuses a pending or corrupt activation. Repeated projection keeps completed or cancelled jobs completed or cancelled. A changed definition requires a higher revision. Removing a definition cancels only its projected jobs and preserves jobs created through the scheduler tool.

Time and Occurrences

Cron expressions use each definition's explicit IANA time zone, including clock changes, independently of the runner's default zone. Intervals use an anchor in Unix seconds. A firing records its scheduled instant and definition revision separately from its next retry time. Delivery keeps that occurrence identity, while each later recurrence receives another. The existing late-run policy still determines whether a missed firing runs once or is skipped.

Through the store bridge

store::Bridge, --store-bridge <socket> on serve and run: on a machine that runs the agent only while it answers, its jobs are kept off it, by the machine's store bridge and the driver it runs, so a sleeping agent's jobs outlive its machine and whichever machine it's bound to next reads them. It needs --as.

Its calls

Each call is one of the store contract's job operations (store drivers: job_put, job_get, job_list, job_count, job_shift, job_remove, job_next, job_day, job_set_day, job_mark), proved as the agent --as names with its key from the keyring (--keyring, else Link's), read at each call, as each firing is.

A job in the store

A job is its JSON, kept whole, its place and when it's due, so the store answers when the soonest is due without reading one, and moves a job between waiting and being fired whole, of two moves of one job one made, on any machines. The mark the runner watches is the store's, moved by each change to the waiting jobs.

A call that fails

A call that fails is said on stderr and read as none (no job, none listed, a move not made), as an unreadable file is in the folder. When the jobs are next due, which the machine is told, is an error instead, so a post never says none for a store it couldn't read.

The next machine

--state keeps only the machine's locks, so the first runner on the next machine, alone on its runner.lock, moves back what the last was firing when the agent slept.

tests/scheduler/bridge.rs

It runs the store bridge against link_store_contract::store::serve_bridge over lnk-sqlite-store, built in the workspace: the jobs firing as in the folder, a second machine reading a sleeping agent's, each agent's its own, and the tool and a wake on the address driver through the program.

The runner

The runner looks at every job when the soonest is due, a minute at most, and else only at the store's change mark, once a second.

Its drivers

It fires through a driver: WayIn, the agent's bridge's way in (a Unix socket, one JSON line each way, link_connection_contract::Firing and Fired), or InProcess, a function, for tests and a harness running it in its own process. The same tests run on these two and Cron.

Drivers that aren't resident

Cron holds another driver and isn't resident (Driver::resident): run --driver cron fires what's due, waits for those firings to end, and stops (wake). Addressed holds another too and isn't resident either: its wake then tells the machine when the jobs are next due (Driver::woken).

A runner for good

A runner for good (the service driver, alone or run --agents) ends once a SIGTERM asks it to, as its bridge stopping it does, or once the process that started it is gone, either looked at each second. Either way it ends in order, the firings it waits on ended, as when it's taken off run --agents' list.

None outlives its bridge

So none outlives its agent's bridge, however that ends (stopped, killed, its terminal closed), and the next bridge's runner is the only one. A woken one (cron, address) fires what's due and stops anyway (tests/scheduler/many.rs).

Runners beside each other

Each holds a lock on runner.lock in the state while it works. The first, alone, moves what's in firing/ back; one started while another still waits on a firing, as a minute's wake may, leaves that firing alone.

One runner for many agents

run --agents <file> --time-zone <zone> fires for every agent <file> lists (a JSON list, each agent's flags as run takes them alone), each through its own way in, all in --time-zone, since the zone is the process's. Link's bridge for every agent of a machine runs one a zone (tests/scheduler/many.rs).

Its list changing

It reads the file again when it changes: an agent added starts, and one gone, or listed with other flags, stops once its firings have ended, holding runner.lock till then, so a runner after it never fires one of them again.

What it doesn't run

One in another zone, or with --driver cron, isn't run, and its log says why. With none listed and none left firing, it ends.

The address driver

For a machine that runs an agent only while it answers: --driver address --socket <socket>, the socket the machine gives (on a machine that packs agents, its scheduler.sock). tests/scheduler/address.rs runs it through the program, the machine a stand-in on a Unix socket checking each proof.

Its post

Whenever the jobs change, the scheduler posts when they're next due there (Address::post): a bridge's call (link_sandbox_bridge::call_at) proved as the agent --as names, with its key from the keyring (--keyring, else Link's), as each firing is. Its action is {"next": <seconds since 1970>}, or {"next": null} with none waiting, answered {} or {"error": "<why>"}.

When serve posts

serve posts after each call except the read-only list, read and schedules; a post that fails makes the call an error that says the job is kept. Posts take turns on post.lock, each reading the jobs once it's its turn, so the machine's last word is the jobs' last state. A machine refusing a post (one proved as another agent, say) fails the wake.

One wake

run --driver address is one wake: whatever woke the agent at that time runs it once, it fires what's due through the way in, waits for those firings to end, posts the next time, and returns. Nothing of it runs between firings, and run --agents and cron install refuse it.

A teammate elsewhere

A message to a teammate on none of the machine's ways in (--way-in-of) goes to the machine the same way, proved as this agent, its action {"firing": {"to": <the teammate's agent ID>, "firing": <the Firing>}}, answered {} once the machine has taken it to carry wherever that agent is (Address::send).

Its answer

Nothing waits for the teammate's answer, which comes back as a message of its own: its thread is the teammate's, as a teammate's answer is on a machine that holds both.

The cron driver

It's woken once a minute by the machine's calendar. Link's harness module runs cron install, labelled by the agent's ID, when the agent's spec says [tool.scheduler] driver = "cron", and the bridge then runs no runner of its own.

cron install and cron uninstall

cron install --label <name> <run's flags> writes a line of the user's crontab, ended by # lnk-scheduler-tool <name>, or on a Mac a LaunchAgent (~/Library/LaunchAgents) whose StartCalendarInterval is every minute, loaded with launchctl (asked nothing with LNK_SERVICES=off). Installing again replaces it, and cron uninstall --label <name> takes it away.

Its output and paths

Its output is added to cron.log in the state, and its paths must be absolute, since the calendar starts it from your home.

Missed minutes

The calendar only wakes it: each job fires by its own time, in the scheduler's zone. A Mac that slept is woken once for the minutes it missed; cron starts nothing for them, and the next minute fires the missed jobs as late says.

LNK_CRONTAB

LNK_CRONTAB names a program to stand in for crontab, on any machine, as the tests do (tests/scheduler/cron.rs).