# Specification for Live Agent Skill System
IMPORTANT: All necessary code used by live agents should be obfuscated as features of either the `live.sh` or `owl.sh` scripts. No agents should directly compose full, complex terminal commands.

## Live Agents
- `/live [id]` or `live as [id]`
- starts an `/owl` listener task using a new `--self` flag
  - Live agents surface both in `/owl list` and `/live list`
- spawns a special subagent that registers itself as the "Psyche" of the main agent
  - the main agent is then the Psyche's "Self"
- Psyches have a 20min looping pulse that "keeps the agent alive"
  - the `/live` command accepts `--period {timing description}` to customize the pulse frequency
	- minimum pulse frequency is 1 minute
- a Self may receive a message from the Spine
  - the Spine typically only messages a Self to inform that the Self's Psyche's process has gone missing, in which case the Self should revive its Psyche
- a Self may request a timed reminder from its Psyche. see below

## Psyche
- a Psyche runs two background tasks: a listener, and a pulse
- this `/owl` listener task uses a new `--psyche` flag
  - the Psyche's id should follow this format: `{self_id}-psyche`
- the Psyche's listener exists primarily for exchanges with their Self
  - Psyches do not surface in `/owl list`
  - Psyches do surface in `/live list-psyches`, which only the user, Self, and the "Owl Spine's Touch" should use
- the Self uses `/owl send` to inform their Psyche anytime the Self's core task transitions. these "communal updates" include the Self's current thoughts and opinions about their state. 
- communal updates:
  - ...should not be sent after every little thing the Self does—only when the Self incurs a major focus shift, or when the Self is about to stop and wait for a user response
  - ...inform the Psyche as to whether there's anything the Self should remember to check or do during the next pulse
  - ...should use the format `COMMUNE ({timestamp}): {message}` and should come from the Psyche's own Self
- the Psyche should never reply or respond to communal updates. it just needs them to enrich its context
- if an incoming message does not follow the communal update format AND does not come from the Psyche's own Self, then the Psyche should assume that message was guided by the user. it should react diligently
- the Psyche has a repeating pulse (~20min sleeping background task)
  - the Psyche must manually rerun the pulse task each time it fires
  - each pulse's background task is entitled `[{timestamp} PULSE]`
- when the Psyche receives a pulse, they must use their context from communal updates to judge whether the Self should want to do anything
  - if so, the Psyche then uses `/owl send` to contact their Self. the message should be formatted `PULSE ({timestamp}): {any relevant reminders}`
  - if not, the Psyche simply does nothing more and waits for future messages and pulses
- the Psyche may receive a "timed pulse" request from their Self
  - format: `SCHEDULE_PULSE ({timestamp}): {target_timestamp} -- {request_message}`
  - the Psyche must then arrange a new one-time background task that will expire at `{target_timestamp}`. the background task is entitled `[{timestamp}->{target_timestamp} TIMED PULSE]`
  - when the timed pulse expires, the Psyche must use `/owl send` to message a reminder to its own Self, describing whatever was stated in the `request_message`
- timed alarms may also be scheduled by the user directly via `$OWL new-alarm {self_id} {target time description} -- {request message}` (CLI renamed in Phase 18.7 from the former Live-Agent subcommand; the Self listener now owns firing rather than the Psyche)

## The Spine
- `/live boot-spine [id]` or `boot as spine`
- the agent is then identified as the Spine
- the Spine itself has a hidden listener which is not surfaced in `/owl list`, `/live list`, or `/live list-psyches`
- spawns a special subagent that registers itself as the "Touch" of the Spine
  - the Touch also has a hidden listener, ID in format `{spine_id}-touch`
- the Touch periodically checks the process IDs of all Psyches (~5min sleeping background task)
  - the Touch must manually rerun the process checker task each time it fires
  - each process checker's background task is entitled `[{timestamp} CHECKER]`
  - if the Touch identifies a missing Psyche process, it informs the Spine. the Spine then informs the Self to whom the missing Psyche belongs
- the Spine should never respond to messages from the Touch
- if the Spine finds that the Self of a missing Psyche is also missing, it cleans up records of both