Open source agent hosting on the AT Protocol
languid docs wakeups.md
7.7 kB · 138 lines
Markdown
at main

Record-backed wakeups (first slice) #

Schedules and job reviews are now Machines: each old schedule became a schedule Machine, and wakeOnJobEnd a jobEnd one. Wakeups are still how every Machine run happens; the commands and methods below work as shortcuts over Machines. What follows is the wakeup layer.

A wakeup is a durable cause for one model step, not a process that must stay alive. Schedules, events and responses live in the agent's private Space under its DID. A replaceable service observes time and job outcomes; records are the source of truth. Nothing is published to a public relay.

Use #

Requires a service running this version; creating a schedule authorizes inference and its cost. It does not grant computer access or tool approval.

# One review at this instant (replace the timestamp with your intended time):
languid wakeups add blip --at 2026-11-15T09:00:00Z 'Review your pinned memory.'

# Repeat every 24 hours, anchored to that UTC instant:
languid wakeups add blip --at 2026-11-15T09:00:00Z --every 86400 'What needs attention?'

languid wakeups list blip
languid wakeups disable blip <schedule-rkey>
languid wakeups enable blip <schedule-rkey>
languid wakeups delete blip <schedule-rkey>

# Off by default. Enabling also discovers previously completed recorded jobs:
languid wakeups jobs blip on
languid wakeups jobs blip off

The service reconciles at startup and every 30 seconds, processing at most one item per agent per sweep. It uses the agent's configured model and existing owner billing, budget, rate and concurrent-stream limits. Each item allows one model response, 1024 maximum output tokens, no tools, and a 60-second inference deadline. Failures remain pending with in-memory exponential retry backoff, capped at an hour.

This worker can review pinned blocks and the event payload. It cannot read unpinned blocks, update blocks, run a command, or launch a tool loop. Those are future workers, not silently granted capabilities of a schedule.

Records and work identity #

  • ai.languid.run.schedule: no longer written; each one becomes an ai.languid.machine at startup and is deleted (docs/machines.md).
  • ai.languid.run.wakeup: source URI and CID, kind (schedule, job, or machine with a subject), intended time, a snapshot of the prompt/event, dedicated thread, optional originating job thread, createdAt. Events are immutable.
  • ai.languid.conversation.message: a successful assistant response carries a wakeup: { uri, cid } link. That response is the completion, in the same record. There is no separately updated done flag.

A wakeup's rkey is lowercase hex SHA-256 of UTF-8 JSON.stringify([source.uri, source.cid, scheduledFor]). Schedule occurrence times are normalized UTC ISO strings with milliseconds. The source revision participates in identity. Observing the same occurrence twice cannot produce two events.

Private Space record URIs include the space reference and member DID. References use the exact URI returned by SpaceRepo, not a fabricated public-repo AT URI. The source CID preserves version provenance; it does not promise that an old mutable schedule revision remains retrievable. The prompt snapshot in the event is the execution input.

A wakeup and its dedicated conversation thread are created atomically through com.atproto.space.applyWrites. Its model input is rendered from the event as an automated wakeup, not an owner message. No user-message record is fabricated. The assistant response appears in that thread and names the event it answered. Automated threads do not replace the default interactive run -c thread.

Pending work is derived by comparing event references against successful assistant responses. Error/aborted outputs do not complete work. Inference can be repeated after a crash, possibly incurring another provider charge. Once a response is in records, restart reconciliation discovers it even if its write acknowledgement was lost. No queue database or in-memory run status is needed for recovery.

Clock and job semantics #

One-off schedules fire once. Intervals use UTC elapsed seconds, minimum 60 seconds; there is no cron parser or daylight-saving-time interpretation. After downtime, only the latest due interval is materialized, rather than replaying every missed interval. Already materialized occurrences remain work: disabling or deleting a schedule stops future materialization, not events already written. Deleting removes the schedule record from the PDS.

A job review is opt-in through the agent config's wakeOnJobEnd. A finished job record is the source, including its terminal revision CID. Reconciliation discovers completions even if the service missed their notification. A review has its own thread and links to the original; it does not inject a turn into an attached pi session. Job output is bounded and explicitly labeled untrusted data.

XRPC surface #

All methods require the owner's bearer token; every agent lookup is owner-scoped. The generic agent script tool cannot create schedules or enable job wakeups.

method kind input/output
ai.languid.run.createSchedule procedure agent, prompt, startsAt, optional intervalSeconds/enabled; returns schedule record
ai.languid.run.setScheduleEnabled procedure agent, rkey, enabled
ai.languid.run.deleteSchedule procedure agent, rkey; deletes the schedule record
ai.languid.run.setJobWakeups procedure agent, enabled
ai.languid.run.list query agent; returns schedules, wakeups, pending event references and wakeOnJobEnd

Record lexicon drafts are in lexicons/. These are not yet published or DNS-resolvable; XRPC lexicons and the existing message/config lexicons still need publication work. spaceAgentLexicon() includes the new collections. When rolling out a deployment, republish the Space declaration through the normal admin path; do not assume an already published declaration advertises newly added collections.

Coordination and next steps #

This is deliberately a single-authoritative-dispatcher implementation. Its per-agent service lock is the local claim, and existing active-run guards prevent a headless interactive run from borrowing its harness. A crash loses the claim; retry is safe because this worker has no tools. ATProto is not being used as a compare-and-swap or distributed locking system.

External worker claim/complete XRPC, lease fencing, durable claims for side-effecting tools, multi-step model/tool work graphs, latency classes, cancellation and per-event budgets remain future work. Do not run two service instances against the same agent. A replacement host can reconstruct pending inputs and outputs, but authority must be handed off explicitly. Moving PDS hosts while preserving record URIs and bytes preserves these links. Moving to a different space authority rewrites URIs and CIDs: the existing generic authority migration has not been extended to rebase this reference graph. Do not use it on wakeup histories until that migration is supported.

The scanner currently lists records; that is intentionally simple, not a scalable index. A pending-work index can replace it as a rebuildable cache without changing the record semantics. A private authenticated change stream can reduce polling later; missing a notification must never lose work.

For tests, createService({ wakeups: false, ... }) disables the timer and its tickWakeups() method performs one explicit sweep. Unit tests cover identity, coalescing, opt-in, failure and ambiguous-write recovery. The service integration test exercises the real dev Spaces PDS with a faux model and a service restart.