Module wake 

Wake a seat when mail reaches it.

Mail waits in the pack until the recipient’s next prompt reads it, and an idle agent has no next prompt. A seat names how to wake it in wake.toml beside harnesses.toml: a command this machine runs, or a webhook it posts to. ljos send and ljos reply start that wake in its own session after the message is written, so the sender neither waits on it nor fails with it, and the sender needs to know nothing about the recipient’s runner.

A command runs as sh -c with the recipient’s seat in LJOS_SEAT, so ljos inbox in it reads the recipient’s mail. It is judged by the same guard a tool call is, when it is set and again each time it runs, and a deny or an ask keeps it from running: nobody is there to ask. A webhook gets only the envelope (seat, sender, message id, issue, interrupt), never the body, and its key is read from a file or an environment variable, never from wake.toml.

A key that ends in - is a prefix. Mail to a longer seat that starts with it uses that wake, so a run named ljosbot-review- plus its run id wakes the launcher. An exact key wins, and the longest prefix wins when several match. The envelope still names the run’s seat and carries the matched prefix as via.

In push mode the letter is in this machine’s pack and not yet on the tracker the other machine reads. The detached wake pushes the sealed log before it runs the command or posts the webhook, so the send itself does not wait. A refused push is a line in the wake log. The wake still runs, and the send still stands.

The envelope carries the tracker commit that holds the log, when push mode made one. A command sees LJOS_WAKE_COMMIT, and a webhook’s JSON has commit. The field is absent when no log commit was made. The other machine fetches that commit with ljos inbox --sync, imports the sealed logs, and then lists. With no remote the flag only lists.

Structs

Event

The message a wake is about.

Wake

One seat’s wake: a command or a webhook.

Constants

WAKE_TIMEOUT_SECS

How long a wake command may run before it is stopped, in seconds.

Functions

clear

Remove a seat’s wake.

envelope

The envelope a webhook gets. The body stays in the pack. When the log’s commit is known, read names ljos inbox --sync COMMIT.

fire

Run one seat’s wake now and say what happened. A prefix entry matches a longer seat that starts with it. The outcome is also a line in the wake log, since a detached wake has nobody to tell.

judge

The guard’s verdict on a wake command: the seat’s own guard, the trusted computing base (the static check, which includes the commit, push, and merge gates), then the pack’s rules and the ask pack. None lets it run.

load

Every seat’s wake, keyed by seat or by a prefix (a key ending in -). An absent or unreadable file is no wakes.

path

Where the wakes are kept: wake.toml beside harnesses.toml.

set_command

Set a seat’s wake command, after the guard passes it.

set_webhook

Set a seat’s webhook. The key stays in its file or variable.

show

What a seat’s wake is, in one line. A seat with no entry of its own uses the longest prefix entry, and the line names that prefix.

spawn

Start the wake of each recipient that has one, or whose seat matches a prefix entry, each in its own session, and name the seats woken. Nothing here fails the send: a wake that cannot start is a line in the wake log.