agents/ — Agents and their Routines

An Agent is a named colleague a realm proposes: a job, the routines that do its work, and the duties it keeps. Where events/ produces signals, an agent’s Routines react to them or to a cron schedule. Everything here is a proposal. The world that installs the realm decides who answers for the agent, what it may do, and whether it runs, so a realm never declares those things.

name: reviewer                        # stable id; the world shadows a realm agent of the same name
job: Make sure nobody waits on a review from me
routing: Pull requests, review requests, who is waiting on whom   # "ask me about…"
persona: terse                        # optional; a personality the host already has
routines:
  - name: pr-review                   # stable within the agent
    description: When a review is requested on one of my PRs, notify me
    match:
      signalType: github.pr_review_request   # a Signal type name (from events/ or types/); "*" = any
    schedule: "0 0 8 * * *"          # optional 6-field cron; fires on a schedule too (omit for signal-only)
    spec:
      kind: typescript
      module: pr-review.routine.ts    # sibling file under agents/, inlined at load (or inline `source: |`)
duties:                               # forward-looking: declared and shown, not yet kept by a host
  - name: no-stale-reviews
    text: No review request waits more than a working day
    holds: StaleReviewRequest         # a view, lens or DERIVE label that should stay empty
    every: "0 0 * * * *"
sweeps:                               # cold materializations it keeps filled — see below
  - name: review-history
    view: stale-review-sweep          # a view of this realm's, taking no arguments
    budgetPerTick: 60

Field	Required	Meaning
`name`	yes	Stable id. A world agent of the same name shadows the realm’s.
`job`	yes	One sentence, in the words of the person who will answer for it.
`routing`	no	What to ask this agent about, for a host that routes questions to colleagues.
`persona`	no	A personality the host already has, or one this realm ships under `personalities/`, named `<realm>/<slug>` to say which realm’s (`realm-bible/jonathon`). A persona confers no authority, but it is part of what the sponsor signs: for an agent people talk to it is the behaviour, guardrails included (see Signed versions).
`conversation`	no	How the agent is talked to: the realms it reaches, the host tools it keeps, the skills it brings in by name, its model role and the sampling a caller may ask for. See Talking to an agent.
`routines[]`	no	The work it does without being asked. Fields below.
`duties[]`	no	Conditions it keeps true, each naming the view, lens or DERIVE label that should hold. Forward-looking.
`sweeps[]`	no	Cold materializations it keeps filled, each naming a view of this realm’s. See Sweeps.
`state`	no	Only `retired`, to withdraw an agent the realm used to ship. Any other value is ignored.

What a realm does not declare. sponsor, owners, operators, the agent’s stage, and a routine’s or duty’s stage are the world’s to decide, and a host ignores them in a realm’s agent file. A realm that could name who answers for its own agent would be vouching for itself, and one that could set its own stage would go on duty the moment it was signed. A realm agent arrives off duty with no sponsor.

A routine may declare match (signal-triggered), schedule (cron-triggered), or both.

Routine field	Required	Meaning
`name`	yes	Stable id within the agent.
`description`	no	One line shown with the agent.
`match.signalType`	no	Signal type that fires it — a host signal or a realm signal (`github.pr_review_request`). `*`/omitted = any signal.
`schedule`	no	6-field cron expression, registered on the host’s normal cron path.
`spec.kind`	yes	`typescript`, or `function` to target a manifest-declared Realm Function (below).
`spec.source` / `spec.module`	for `typescript`	Inline TS, or a sibling file inlined at load.