Beer Can Labs
Staff / Timekeeper
Operations

Timekeeper

Scheduler

Decides when an agent is due, so no agent needs a clock running inside its container. Each minute the Timekeeper looks at every cartridge cron and every schedule an agent created, and tells the Landlord who is due.

Design rules
§6.15
Contracts offered
1
Key flows
2

On the job

  • Checks cartridge cron expressions each minute
  • Stores schedules agents create, with time zones
  • Validates cron and time zone input
  • Calls fire with a request for each due item

Not my job

  • Start a run. fire is the Landlord’s side.
  • Import the control plane. Only the composition root calls it.
Key product flows

What Timekeeper does, step by step

Flow

Fire a cartridge cron

The cron lives in the cartridge. The clock lives in the factory.

  1. Every minute createTimekeeper asks which agents’ cron expressions match the current time in their time zone.

  2. For each due agent it calls fire with a cartridge request.

  3. The Landlord wakes the agent, unless it is already running, in which case that tick is skipped.

    Works with Landlord· contractcreateTimekeeper →
Flow

Let an agent schedule itself

An agent creates a schedule through the schedules API with its run token.

  1. The request is checked against the run token’s scope.

    Works with Gatekeeper· contractAuthProvider / Principal →Run-token scoping is the Gatekeeper’s.

  2. The route asks for its privilege.

    Works with Bouncer· contractauthorize →

  3. cronIssue and isTimeZone validate the input. The schedule is saved to schedules.json.

  4. The creation is ledgered.

    Works with Auditor· contractLedgerStore / verifyChain →

  5. When the schedule is due, checkDue yields it once and fire wakes the agent.

    Works with Landlord· contractcreateTimekeeper →

Contracts Timekeeper keeps 1 offered