Skip to content

Latest commit

 

History

History
438 lines (369 loc) · 24.9 KB

inbox.md

File metadata and controls

438 lines (369 loc) · 24.9 KB
summary The inbox: one place per Bridge where everything that needs a person waits until it is done. Item and event layout, derived states, gates, closing probes, who writes and reads, CLI reference.
type guide
last_updated 2026-10-26
related
scripts/inbox.py
scripts/tests/test_inbox.py
scripts/tests/test_inbox_mute.py
work-system.md
../protocols/standing-orders/inbox.md
../work/templates/_schema.inbox-item.yaml
../agents/_runtime/approval.py
../scripts/inbox-approve.py
workplace.md
always-on-machine.md

Inbox

Why

A finding, a question from an agent, a decision, a draft waiting for its send: each used to live wherever it happened to be written down. A sentence in the log, a chat message, a mail from a scheduled job, a line in a STATUS.md. Nothing closed them. A briefing that re-read those places reported things as open that had been solved hours earlier, because the sentence saying "needed" was still there and the one saying "done" was further down.

The inbox is the single place for everything that needs a person. An item stays until it is done, and "done" is decided by the live source where possible (the PR is merged, the file exists), not by someone remembering to cross it out.

Layout

work/inbox/<id>/item.yaml          written once, never changed
work/inbox/<id>/events/*.yaml      one NEW file per change
work/inbox.md                      GENERATED view (python3 scripts/inbox.py render)

item.yaml carries schema_version, created, from, kind, summary, urgency, gate and optionally task, area, due, detail, key, action (argv and label, no shell), closes_when and waits_for. Schema: work/templates/_schema.inbox-item.yaml, annotated example: work/templates/inbox-item.yaml.

Every change is a new event file, never an edit. Verbs: seen, note, approve, reject, drop, defer, urgency, area, close, executed, failed, reopen, describe, wait, ready. Two machines writing the same inbox through git therefore never touch the same file, and an item id ends in a random tail, so two machines filing the same thing in the same minute still create two folders. This is the property the task folders already have, and work/board.md is derived from them for the same reason. The inbox state is derived from events and never stored.

Kinds: decision, question, finding, draft, result, idea. An idea waits on nobody: it ranks after every other kind and a briefing section can list ideas apart (kinds: [idea]) or leave them out (skip_kinds: [idea]). Urgency: now, today, later.

Area. An item linked to a task belongs to that task's area. One without a task may carry an area of its own: the name of a workspace in workplace.workspaces (workplace.md), given with add --area, changed with inbox.py area (the last area event wins, --clear takes it back). A name or alias in any case is stored as the workspace's name; area refuses one that names no workspace, add warns and files the item without it. The cockpit counts the item under that area instead of "No area", its detail page has a picker to put it right, and a tab started for it opens in that workspace.

With inbox.place_on_add: true in bridge-config.yaml, an item filed through the CLI (inbox.py add) with neither a task nor an area is placed by the router: add starts workplace.py place --pending detached, so the filer never waits. That waits two seconds for a burst to arrive, takes a lock so only one placer runs, and asks the configured workplace.router once about every open item without a task or an area, each item once per run; the answer is written as an area event by router with its reason. An item a person gave an area meanwhile, or one that closed, is left as it is. Without a router, or when it fails or names no configured workspace, the item stays without an area. Code that files through the Inbox class (the briefing's own items, which mostly name a task) places nothing; workplace.py place --unplaced catches up on every open item that has none yet (--dry-run shows the answer and writes nothing).

Brief. What an item is about, beyond its one-line summary: a goal, an optional user story and a few acceptance criteria, plus by (the model id), at, basis and edited. It is the same block a task carries as brief: in its STATUS.md (work/templates/_schema.status.yaml, $defs/Brief), written as a describe event with inbox.py describe <id> --brief-json '{...}'; the last one wins, --clear takes it back. A brief the gate (scripts/lib/bridge_cockpit/card_fields.py, validate_brief) finds anything wrong with is refused, and validate reports a hand-edited event that no longer passes it. closes_when stays the machine's probe and never becomes a criterion.

States

State Meaning
open nobody has answered
approved a person said yes, run may execute the action
waiting a conditional yes is recorded, run executes when the condition holds; or the item waits for its waits_for condition and asks nobody yet
deferred pushed to a later day with defer --until
done closed (by a person or by check) or executed
dropped rejected or dropped

open, approved and waiting count as active and show in list.

A close by mistake is taken back with reopen, one more event: the item is open again and every yes before it is void, so an executed action does not run a second time without a new yes. A later close closes it again.

Arts

A person sees an item as one of three arts, derived from its kind and never stored (scripts/lib/inbox_verbs.py ART_OF_KIND):

Art Kinds Means
ask decision, question, draft needs a person's yes, word or click
report finding, result how something stands; a probe or its reporter ends it
idea idea mentioned, nothing came of it yet

A kind the table does not know is an ask, so a person sees it rather than missing it. list --json carries the art of every row and list --art <art> shows one art only. The briefing's "N asks for you today" and the cockpit's "waits for you" count the asks: a row that is no inbox item (a task, a board item) counts as before, and of the inbox only an ask does. An idea or a report filed for today still shows in Do (Now in the cockpit); the briefing's headline counts those apart ("· 2 reports"), so its number explains itself.

Gates

  • free: the Bridge may act alone. run executes the action without a yes. A failed free action waits for a person instead of retrying on every tick.
  • your-yes: acts after a person's yes. A conditional yes is approve --when-json '{"gh_pr": "contoso/portal#70", "state": "green"}' ("merge once green"): the item is waiting, and run executes it when the condition holds.
  • only-you: send, publish, pay. run never executes it, whatever was recorded, and a conditional yes on it is refused. The item exists so a person does the click.

Probes (closes_when)

check evaluates each open item's closes_when against the live source and closes what holds. Probes: path_exists, command (exit code, optional expect_exit), after (a date), gh_pr (with state merged, closed, open or green), gh_issue (with state), task_status (with status), unseen_for (with hours), and all / any to combine them.

unseen_for ({hours: N}) is for reporters that refile the same key on every run while a condition holds (a daily health report): the item closes when no run has filed it for N hours, so a fixed finding leaves without anyone clearing a log. It reads the item's own sightings (seen events), so it needs the item and is unknown without one. A one-shot alarm does not carry it: that item waits for a person.

A probe that cannot be evaluated (no network, a typo, a missing task) is unknown, never true. The item stays open rather than vanishing on an error.

Waiting for a condition (waits_for)

Some items only ask once something has happened: "the quota was raised: switch over". Filed as an open item, it states the hoped-for outcome as a fact while the live source says otherwise, and a closes_when on that same condition would close it exactly when it becomes something to do. waits_for is a probe in the same language for that case:

python3 scripts/inbox.py add --from homebox/quota-watch --kind result \
    --summary "Quota raised: switch the service over" --task model-switch \
    --waits-for-json '{"command": ["scripts/quota-check.sh"]}'
python3 scripts/inbox.py wait <id> --for-json '{"gh_pr": "contoso/portal#70", "state": "merged"}'

While the probe does not hold, the item is waiting: it asks nobody, run executes nothing of it (a free action included), and the briefing lists it under waiting as "Waiting for:

". check evaluates it with the other probes; once it holds, check records a ready event (printed as ready <id>) and the item is open, asking the person like any other. A probe that cannot be evaluated is unknown, so the item keeps waiting. wait sets the condition on an item already filed (a wait event; the last one wins, ready ends it). Its closes_when still closes it while it waits, and only-you never runs a command probe here either.

What a person can do (actions, expires_at)

A notifier (a phone bot, the cockpit) shows buttons on an item. Derived from the gate alone they misfire: "tomorrow" on an answer that expires in an hour, no "approve" where one is needed. The filer knows better and says so:

  • actions: the verbs a person may take, in display order, each one of approve, reject, defer, drop, close. A notifier shows exactly these. actions: [] means nothing to do: show the item, no buttons. No field means unknown: the notifier keeps its old behaviour and derives buttons from the gate. A list with an unknown or repeated verb makes the item invalid.
  • expires_at: an ISO 8601 timestamp with an offset, when the item stops mattering. A notifier shows it ("valid until 14:30"). It changes no state by itself; whatever times out closes or drops the item as before.

The filer sets both at add: --action approve --action reject (repeatable), --no-actions for [], --expires-at 2026-10-04T14:30:00+02:00. scripts/inbox-approve.py files a held answer with [approve, reject] and expires_at at the end of its timeout. actions is not action, the command run executes once released.

Every item needs a way out (closer)

An item without a probe stays open until somebody remembers it. closer says who ends it instead: reporter (the job that filed it closes it by key once the condition is gone: inbox.py close --key <key>), person, or bot (a watcher that acts on it). add files an item with neither closes_when, closer nor an action as closer: person, written into item.yaml: nothing else would end it. It does not refuse, because filers run unattended and a refusal would lose the item. An item with an action keeps no closer, since the run that executes it closes it. A finding or a result filed that way is warned about on stderr: it waits for a person, though the job that found it would know when it is gone, so give it closes_when or --closer reporter and close it by key.

bot is also a routing promise: the item goes to a watcher that looks first. It investigates before a person hears about it and ends in one of three ways: nothing to do (the item closes with the cause as its note), a small fix it prepares itself (a person only approves the result), or a recommendation with options for the person. A report that already knows the answer says so when it files: a finding that only informs (bad data on the sender's side, a delivery that the retry recovered) stays in the report mail and becomes no item at all.

Each step of that work runs on a model chosen by weight, not habit, from bridge-config.yaml models: (reasoning plans and judges, analysis builds along a given path, routine sorts and extracts; the cockpit's mechanical and directed names are read ahead of routine and analysis when set): critical items and plans go to the reasoning tier, findings that can wait are sorted by the routine tier, a fix runs on the analysis tier.

An alarm path that announces both the trouble and its end should close by key: the all-clear carries the alarm's own title, so the receiver rebuilds the key it filed the alarm under and closes that item rather than filing a new one.

A reporter that repeats an alarm may pass --quiet-after-close-h N to add. When somebody closed an item under the same key within N hours and the detail is unchanged (timestamps aside), the new sighting is only recorded as seen on the closed item and nothing new is filed: the person who looked at it already answered that exact text. A close by a probe or by the reporter's own all-clear does not count, because then the trouble had ended and its return is news. An all-clear is a close text that begins with All clear, or with one of the words in bridge-config.yaml inbox.all_clear for reporters that write another language.

Who writes

  • A scheduled job on an always-on machine (a watcher that finds a red check or a stale PR).
  • An agent or a terminal tab that reached a point where it needs a person.
  • The briefing's own checks, when they find something to act on.
  • A peer Bridge, but only through its own front door (an A2A request that a local job files), never by writing into this repository.
  • The session itself, at the end of a unit of work (see the standing order inbox).

The rule: a finding files an item only when somebody has to act. Green stays quiet. Use --key for anything that can fire again: a repeat of an open item with the same key adds a seen event, not a second item.

Who reads

  • The briefing, first: it runs check and reads the inbox instead of re-deriving "open" from the log.
  • Phone and e-ink digests, as short views: python3 scripts/inbox.py list --short prints one line per item.
  • A control tab, which can show work/inbox.md or the JSON of list --json.
  • A notifier on a phone: the inbox-notify skill announces every open item with urgency now and a non-empty actions list once, as one text and one Signal poll whose options are those actions, and runs the vote through this script (skills/inbox-notify/SKILL.md).

CLI

python3 scripts/inbox.py add --from homebox/issue-radar --kind decision \
    --summary "PR #70 is green and waits for a merge" --task portal-relaunch \
    --action-json '{"argv": ["gh", "pr", "merge", "70", "-R", "contoso/portal"]}' \
    --closes-when-json '{"gh_pr": "contoso/portal#70", "state": "merged"}'
python3 scripts/inbox.py list [--all] [--json] [--short] [--art ask|report|idea]   # open items, most urgent first
python3 scripts/inbox.py show <id>                         # item plus its events; an unambiguous id prefix works
python3 scripts/inbox.py approve <id> [--when-json '{...}'] [--text "edited draft"]
python3 scripts/inbox.py reject|close|drop <id> [--note "why"]
python3 scripts/inbox.py drop <id> --reason once|duplicate|stale|done|outdated|unwanted|family|source   # family and source leave a mute rule
python3 scripts/inbox.py mute list [--json]                 # the mute rules in force
python3 scripts/inbox.py unmute <rule-id>                   # lift one
python3 scripts/inbox.py stats [--days 30] [--json]         # per source: filed, dropped by a person, muted
python3 scripts/inbox.py reopen <id> [--note "why"]           # take a close, drop or reject back
python3 scripts/inbox.py close --key <key> [--note "why"]     # every live item filed under that key
python3 scripts/inbox.py defer <id> --until 2026-10-08 [--on lena] [--check]   # --check: a check-in with --on
python3 scripts/inbox.py urgency <id> now|today|later       # re-rank; the latest urgency event wins
python3 scripts/inbox.py area <id> <workspace> | --clear    # the area of an item without a task
python3 scripts/inbox.py describe <id> --brief-json '{"goal": "..."}' | --clear   # what it is about
python3 scripts/inbox.py note <id> "Sam will answer on Monday"
python3 scripts/inbox.py wait <id> --for-json '{...}'           # asks nobody until the probe holds
python3 scripts/inbox.py check                             # close what is done, open what waited and now holds
python3 scripts/inbox.py probe --json '{"gh_issue": "org/repo#12", "state": "closed"}'   # one probe, read only
python3 scripts/inbox.py run [--dry-run]                   # execute what a person released
python3 scripts/inbox.py render                            # regenerate work/inbox.md
python3 scripts/inbox.py validate                          # structure of items and events
python3 scripts/inbox.py sync [--no-push]

--by (or $BRIDGE_ACTOR, default the host name) sets who an event is attributed to. add takes --area, --due, --detail, --key, --waits-for-json, --urgency (default today) and --gate (default your-yes).

A title that reads in a list. add warns on stderr, never refuses, where a title (--summary) is hard to read in a list: longer than 80 characters, with a path, a file name or an id in it (a long hex or numbered token), or with English words in a Bridge whose language is German. Each warning is one line that says what to change (title: 112 characters, at most 80: say what it is in a few words, the rest goes in --detail); the item is filed as given. The cockpit names an item by its brief's name where describe wrote one (bridge-cockpit.md), so a technical title is not lost, but a title that reads needs no brief to be understood.

A check-in. defer --until <day> --on <who> --check puts an item off as "in progress with someone until that day": the event stores check: true beside waits_on. Until the day the cockpit lists it under Running elsewhere ("with · asks on "); on the day it comes back as a check-in that asks how it stands. An answer ends the check-in: approve, reopen, or any close. A plain defer (without --check) stays a later, as before. The cockpit's In progress verb (work_on) sends exactly this for an inbox item. Items are from a machine and job (homebox/issue-radar), not a person.

Dropping with a reason, and muting a loud source

A drop that says nothing teaches nothing. drop --reason records why, as part of the drop event:

Reason Means Leaves
once not worth it this time nothing; the key stays dropped as before
duplicate already known elsewhere nothing
stale it went old without anybody acting on it (what a cleanup proposes) nothing
done already done elsewhere (the cockpit's Out of date: Already done) nothing
outdated no longer relevant (Out of date: No longer relevant) nothing
unwanted not needed like this, only this once (Out of date: Not needed like this) nothing
family never this kind again a rule: the source plus the key up to its last colon (health:crash:1a20 mutes health:crash:), or the source plus the kind when the key has no family (such a rule leaves keys with a family alone)
source this source is too loud a rule: everything of the source for 30 days (MUTE_SOURCE_DAYS)

A rule is a file of its own under work/inbox/_mutes/, so two machines never write the same file and sync carries it to the machine that files. The _ keeps the folder out of the item list. A finding that matches a rule is still filed and dropped at once by mute, with the rule's id on the event: nothing is lost, it counts in stats, and reopen brings it back. An item filed with --urgency now is never muted, so a muted source cannot swallow an outage, and a muted key that comes back as now, or after its rule is gone, is reopened. A source mute ends by itself, a family mute stays until unmute lifts it.

Sources that differ only in case (Host-A/notify, host-a/notify) are one source to the rules and to stats. Only the comparison folds the case: items and rules keep their source as written, and a stats row is named as the source was first written.

stats counts, per source, the items filed in the last N days: how many a person dropped (with the reasons, unknown for a drop without one), how many a rule muted, how many closed or are still open. share is what a person had to drop out of what was filed, the clicks the source cost; muted items are counted apart, so a source that was muted and then fixed comes down again. The loudest source is the filer to sharpen: a stable key, a tighter rule, or reports that belong in a digest rather than the inbox.

Two machines, one inbox

inbox.py sync stages and commits only work/inbox/, rebases onto the upstream and pushes. Nothing else in the working tree is committed, and the push is refused when the branch carries unpushed commits outside work/inbox/: syncing the inbox never ships unfinished work along with it. Because each change is its own new file, the rebase has nothing to merge; if it still fails it is aborted and the commit stays local for the next sync. The generated work/inbox.md is not part of a sync: every render rewrites its time stamp, so two machines committing it would conflict every time. Commit it like work/board.md, from the one machine you work on, or not at all.

Exactly one runner. run executes on every machine that calls it, and two machines would both see an approved item before the other's executed event arrived. Name the one that acts in bridge-config.yaml:

inbox:
  runner: homebox      # the actor (--by / $BRIDGE_ACTOR / host name) that executes actions
  all_clear: []        # further words an all-clear close text may begin with, besides "All clear"

Everywhere else run prints "not running" and does nothing. Without the key every machine runs, which is right for a Bridge on one machine only.

Trust. An item can carry a command (action.argv, a command probe). Anyone who can push into work/inbox/ can therefore make the runner execute something, exactly as anyone who can push a script the runner calls already can: the inbox is as trusted as the repository, and no more. Peer Bridges never write here. list, show and work/inbox.md always print the command a yes would run, and an only-you item executes nothing at all, not even a command probe.

Time. Events are stamped in UTC with an offset and ordered by that, so a laptop in one time zone and an always-on machine in another agree on what came first.

Relation to the approval runtime

agents/_runtime/approval.py holds an agent's outbound answer until a person approves it. An approver command can file the held answer as an inbox item (kind draft, gate only-you, actions approve and reject, expires_at when the approval times out) so it shows up where everything else waits, and the person's approve --text releases an edited version. That bridge is the script scripts/inbox-approve.py, written separately from this model.

Upgrading

From the release that brought the arts (2026-10). Nothing to migrate: no item, event or mute rule is rewritten, and every call that worked before works unchanged. What an existing instance notices:

  1. Default closer. A new item filed with neither closes_when, closer nor an action is stored with closer: person, and the old warning no way to close is gone. Items filed before keep what they had. A filer that relied on the warning to spot missing ways out reads the stored closer instead; one that means another closer passes --closer reporter or bot as before.
  2. The count. "N for you today" in the briefing headline and the cockpit's "waits for you" (the coloured Today number, the station, the area lines) count only the asks of the inbox. Ideas and reports still show in Do and Now, so the number can be smaller than the rows there. The two lists on the cockpit's start page that carry the label "waiting on you" (the station's panel and the shelf) list the asks only, so their count matches the tile beside them. A profile that wants an idea or a report counted files it as a question or decision.
  3. New filter. list --art ask|report|idea and an art field in every list --json row. A consumer that reads list --json with a fixed set of keys ignores the new one; nothing was renamed.
  4. Case of a source. stats merges sources that differ only in case, and a mute rule holds for every spelling of its source. To see the spellings apart, read from in list --all --json.
  5. stale. A new drop --reason. It leaves no rule; the cockpit's drop dialog does not offer it.

To check an instance after the update: python3 scripts/inbox.py validate is still clean, and python3 scripts/inbox.py list --art ask --short shows what now makes up the count.