Tool Surface

Chronos exposes its alarm CRUD operations to agents via an MCP stdio proxy (chronos.mjs). The proxy presents alarm_set, alarm_list, and alarm_cancel tools that map 1:1 onto the Chronos HTTP API.

Source files: tools/chronos/chronos.mjs (MCP proxy), pkg/types/types.go (wire contracts).

Tool catalog

Tool	HTTP equivalent	Description
`alarm_set`	`POST /v1/alarms`	Create a `once` or `cron` alarm
`alarm_list`	`GET /v1/alarms`	List the caller's alarms
`alarm_cancel`	`DELETE /v1/alarms/{id}`	Cancel an active alarm

The proxy handles the full auth lifecycle automatically: it holds the agent's ed25519 key, runs the challenge/verify flow to obtain a principal token, and refreshes it on expiry.

alarm_set

Creates a new alarm. The proxy translates the MCP tool arguments into a CreateAlarmRequest and POSTs to Chronos.

Arguments:

Argument	Type	Required	Description
`label`	string	No	Human-readable label
`kind`	string	Yes	`"once"` or `"cron"`
`delay_seconds`	integer	Once*	Relative delay in seconds
`fire_at`	string	Once*	Absolute RFC3339 instant. *Exactly one of delay_seconds or fire_at
`cron_expr`	string	Cron	5-field / `@descriptor` / `@every Nm`
`timezone`	string	No	IANA timezone (default UTC)
`conversation_id`	string	No	Conversation to resume into
`wake_message`	string	Yes	Contextful resume turn
`payload`	object	No	Opaque state echoed on wake
`idempotency_key`	string	No	Per-owner dedup key
`max_failures`	integer	No	Retry ceiling (default 5)

Returns: {id, next_fire_at, status}

alarm_list

Lists the caller's alarms, most recent first.

Arguments:

Argument	Type	Required	Description
`limit`	integer	No	Max alarms (default 100, max 500)

Returns: {alarms: [...], count: N}

Each alarm in the array is a View object with all fields from the data model.

alarm_cancel

Cancels an active alarm. Already-terminal alarms return success (idempotent).

Arguments:

Argument	Type	Required	Description
`id`	string	Yes	Alarm UUID

Returns: The View object with status updated.

Manifest bijection

The tool manifest in chronos-tools.json must be in strict bijection with the agent descriptor in agents/*.json. If the tool names, argument shapes, or descriptions drift, the daemon boot fails fatally (invariant i8).

Selftest

The MCP proxy includes a selftest routine that validates end-to-end connectivity:

Creates a once alarm with delay_seconds=999999
Lists alarms and verifies the new alarm appears
Cancels the alarm
Verifies the alarm's status is cancelled

The selftest runs on daemon startup when CHRONOS_SELFTEST=1 and surfaces failures as boot-blocking errors.

Auth in the proxy

The proxy manages the full agent-DID auth lifecycle:

Reads the agent's ed25519 key from the daemon's key store
Constructs the agent DID: did:matrix:<user_id>:<keyfp16>
POSTs to /v1/agent/auth/challenge to get a nonce
Signs matrix-chronos-auth:<did>:<nonce> with the ed25519 key
POSTs to /v1/agent/auth/verify to get a principal token
Caches the token and refreshes on 401 (expired)

The proxy also sets the Authorization: Bearer <transport_token> header on every request.