Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,11 @@ jobs:
bash skills/mail-draft/run-tests.sh --mutate
MAIL_DRAFT_ROOT=skills/mail-draft/tests/fixtures/bridge skills/mail-draft/mail-draft.sh validate

# The inbox notifier (skills/inbox-notify). Hermetic: signal-cli is a fake on
# PATH that records calls and replays scripted votes; no message leaves the runner.
- name: Run inbox-notify skill suite
run: bash skills/inbox-notify/run-tests.sh

- name: Validate briefing profiles
run: python3 scripts/briefing.py validate && python3 scripts/briefing.py --root examples/portfolio validate

Expand Down
5 changes: 5 additions & 0 deletions docs/channels.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,11 @@ cron/launchd/systemd job on a machine is a workload, owned by `/workload`
([`skills/workload/SKILL.md`](../skills/workload/SKILL.md),
[`docs/workloads.md`](workloads.md)).

A channel that rings for the inbox (an urgent item as a Signal poll, the vote runs the
item's verb) is declared like any other channel file and driven by the `inbox-notify`
skill ([`skills/inbox-notify/SKILL.md`](../skills/inbox-notify/SKILL.md)); the file it
reads is `skills/inbox-notify/assets/channel.yaml`.

## Setup

1. Enable channels: set `channels.enabled: true` in bridge-config.yaml
Expand Down
1 change: 1 addition & 0 deletions docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ which ones is per-instance, so the live list is the skill listing itself.
| `/workload` | | `workload` | Declared runs: `declare`, `validate`, `render`, `provision`, `list`, `show`, `reconcile`, `view`, `publish`, `adopt`, `retire` |
| `/schedule` | | `schedule` | Scheduled tasks: list, create, deploy, disable |
| `/channel` | | `channel` | Channel management: list, health, deploy, start/stop |
| `/inbox-notify` | | `inbox-notify` | Inbox items that need a person now reach the phone as a Signal poll with the item's actions; the vote runs the verb: `tick`, `test`, `show` |
| `/board-pilot` | | `board-pilot` | Board-driven pipeline: arms an item a person drags into the trigger column, advances it one stage per tick, stops at a draft PR for review |

## Upstream and quality
Expand Down
16 changes: 8 additions & 8 deletions docs/explore.html
Original file line number Diff line number Diff line change
Expand Up @@ -503,8 +503,8 @@ <h2 class="h2" id="h-core-user" tabindex="-1"><span data-lang="en">The CORE / US
<canvas id="brain" aria-hidden="true"></canvas>
<button type="button" class="brain-spin" id="brain-spin" aria-pressed="true">Pause</button>
<p class="brain-foot">
<span data-lang="en"><b>1942 files ship. 27 are yours.</b> Each bright dot is one tracked file; the faint field is the body, not data. Drag to turn it.</span>
<span data-lang="de"><b>1942 Dateien kommen mit, 27 sind deine.</b> Jeder helle Punkt ist eine versionierte Datei, das schwache Feld ist der Körper, keine Daten. Zum Drehen ziehen.</span>
<span data-lang="en"><b>1949 files ship. 27 are yours.</b> Each bright dot is one tracked file; the faint field is the body, not data. Drag to turn it.</span>
<span data-lang="de"><b>1949 Dateien kommen mit, 27 sind deine.</b> Jeder helle Punkt ist eine versionierte Datei, das schwache Feld ist der Körper, keine Daten. Zum Drehen ziehen.</span>
<script>
/* The hero guide repeats the CORE/USER counts. check-figure-counts.py keeps the
caption above true to the git tree; the guide reads its numbers from that
Expand All @@ -520,8 +520,8 @@ <h2 class="h2" id="h-core-user" tabindex="-1"><span data-lang="en">The CORE / US
</script>
</p>
<p class="brain-sr">
<span data-lang="en">Two halves of one bridge, side by side. The left half is CORE, everything open-bridge ships: 1942 tracked files, one dot each, grouped by top level folder, with skills at 839 files and scripts at 514 the largest by far. The right half is USER, one instance of your own, here the shipped example in examples/agency: 27 files, one dot each. Six folder names appear in both halves and are joined across the middle: the repository root, identity, infra, workflow, protocols and work. On the CORE side each holds a template and a schema. On the USER side each holds files you name yourself, for example infra/channels/email.yaml. Use the folder list in the panel beside the figure to read each pair.</span>
<span data-lang="de">Zwei Hälften einer Bridge, nebeneinander. Die linke Hälfte ist CORE, alles was open-bridge mitliefert: 1942 versionierte Dateien, je Datei ein Punkt, nach Ordner der obersten Ebene gruppiert, mit skills bei 839 Dateien und scripts bei 514 als mit Abstand größten. Die rechte Hälfte ist USER, eine eigene Instanz, hier das mitgelieferte Beispiel in examples/agency: 27 Dateien, je Datei ein Punkt. Sechs Ordnernamen kommen in beiden Hälften vor und sind über die Mitte verbunden: die Repo-Wurzel, identity, infra, workflow, protocols und work. Auf der CORE-Seite hält jeder eine Vorlage und ein Schema. Auf der USER-Seite hält jeder Dateien, die du selbst benennst, etwa infra/channels/email.yaml. Die Ordnerliste im Panel neben der Grafik führt jedes Paar auf.</span>
<span data-lang="en">Two halves of one bridge, side by side. The left half is CORE, everything open-bridge ships: 1949 tracked files, one dot each, grouped by top level folder, with skills at 846 files and scripts at 514 the largest by far. The right half is USER, one instance of your own, here the shipped example in examples/agency: 27 files, one dot each. Six folder names appear in both halves and are joined across the middle: the repository root, identity, infra, workflow, protocols and work. On the CORE side each holds a template and a schema. On the USER side each holds files you name yourself, for example infra/channels/email.yaml. Use the folder list in the panel beside the figure to read each pair.</span>
<span data-lang="de">Zwei Hälften einer Bridge, nebeneinander. Die linke Hälfte ist CORE, alles was open-bridge mitliefert: 1949 versionierte Dateien, je Datei ein Punkt, nach Ordner der obersten Ebene gruppiert, mit skills bei 846 Dateien und scripts bei 514 als mit Abstand größten. Die rechte Hälfte ist USER, eine eigene Instanz, hier das mitgelieferte Beispiel in examples/agency: 27 Dateien, je Datei ein Punkt. Sechs Ordnernamen kommen in beiden Hälften vor und sind über die Mitte verbunden: die Repo-Wurzel, identity, infra, workflow, protocols und work. Auf der CORE-Seite hält jeder eine Vorlage und ein Schema. Auf der USER-Seite hält jeder Dateien, die du selbst benennst, etwa infra/channels/email.yaml. Die Ordnerliste im Panel neben der Grafik führt jedes Paar auf.</span>
</p>
</div>
</div>
Expand Down Expand Up @@ -1201,10 +1201,10 @@ <h4 data-lang="de">Links</h4>
];
/* CORE only, 628 files. 628 + 166 in PAIRS = 794. */
var CORE_ONLY = [
{ id:"skills", n:"skills/", c:839, x:-0.30, y:-0.04, z:0.02, key:1,
{ id:"skills", n:"skills/", c:846, x:-0.30, y:-0.04, z:0.02, key:1,
ex:["skills/bridge-onboard/SKILL.md","skills/briefing/SKILL.md","skills/debrief/SKILL.md","skills/github-projects-manager/SKILL.md","skills/remote/SKILL.md","skills/workload/SKILL.md"],
d_en:"839 files. The largest thing open-bridge ships, and the one you extend most: each skill is a SKILL.md plus the reference files it loads only when triggered.",
d_de:"839 Dateien. Das Größte, was open-bridge mitliefert, und das, was du am meisten erweiterst: jeder Skill ist eine SKILL.md plus die Referenzdateien, die er nur bei Bedarf lädt." },
d_en:"846 files. The largest thing open-bridge ships, and the one you extend most: each skill is a SKILL.md plus the reference files it loads only when triggered.",
d_de:"846 Dateien. Das Größte, was open-bridge mitliefert, und das, was du am meisten erweiterst: jeder Skill ist eine SKILL.md plus die Referenzdateien, die er nur bei Bedarf lädt." },
{ id:"scripts", n:"scripts/", c:514, x:-0.46, y:0.26, z:-0.12, key:1,
ex:["scripts/validate-bridge.py","scripts/gen-board.py","scripts/measure-context.py","scripts/check-figure-counts.py","scripts/categorize-commits.py"],
d_en:"514 files. The validators and generators. They are what makes a claim in this repo checkable rather than asserted.",
Expand Down Expand Up @@ -1598,7 +1598,7 @@ <h4 data-lang="de">Links</h4>
// the two headers, in the bottom corners, clear of the controls above
var hy = H - fs*2 - 54;
ctx.textAlign="left"; ctx.fillStyle=CORECOL; ctx.fillText("main (CORE)", 14, hy);
ctx.fillStyle=DIM; ctx.fillText(L()==="de" ? "1942 Dateien, alle mitgeliefert" : "1942 files, all shipped", 14, hy+fs+4);
ctx.fillStyle=DIM; ctx.fillText(L()==="de" ? "1949 Dateien, alle mitgeliefert" : "1949 files, all shipped", 14, hy+fs+4);
ctx.textAlign="right"; ctx.fillStyle=USERCOL; ctx.fillText("user/<you>", W-14, hy);
ctx.fillStyle=DIM; ctx.fillText(L()==="de" ? "27 Dateien, alle deine" : "27 files, all yours", W-14, hy+fs+4);

Expand Down
4 changes: 4 additions & 0 deletions docs/inbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,6 +262,10 @@ with the same key adds a `seen` event, not a second item.
- 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`](../skills/inbox-notify/SKILL.md)).

## CLI

Expand Down
1 change: 1 addition & 0 deletions docs/where-things-live.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,7 @@ searches again.
| What goes into the memory base, and where is it on disk? | [`docs/memory.md`](memory.md) |
| Where does a task live, and what does its status mean? | [`docs/work-system.md`](work-system.md#status-semantics) |
| What still needs me, and how does an open item get closed? | [`docs/inbox.md`](inbox.md) |
| How does a held answer or another urgent inbox item reach my phone, and how do I approve it there? | [`skills/inbox-notify/SKILL.md`](../skills/inbox-notify/SKILL.md) |
| What does my briefing show, from which trackers, and how do I change it? | [`docs/briefings.md`](briefings.md) |
| How do I choose the cockpit's tabs, columns, marks and language? | [`docs/bridge-cockpit.md`](bridge-cockpit.md) § 8 |
| How do I see and steer the whole Bridge in a browser (inbox, tasks, agent tabs, machines)? | [`docs/bridge-cockpit.md`](bridge-cockpit.md) (early version) |
Expand Down
95 changes: 95 additions & 0 deletions skills/inbox-notify/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
---
name: inbox-notify
description: >-
Puts an inbox item that needs a person now on that person's phone as a Signal
poll whose options are the item's own actions, and executes the vote through
the inbox. Config in infra/channels/<slug>.yaml, runs as a declared workload.
Trigger: "/inbox-notify", "notify me about approvals", "held answer on my
phone", "approve from Signal", "inbox poll", "the approval never reached me".
metadata:
scope: core
allowed-tools:
- Bash(python3:*)
- Bash(bash:*)
- Read
- Grep
- Glob
---

# Inbox notify

The inbox holds what needs a person ([`docs/inbox.md`](../../docs/inbox.md)). Nothing in
it rings. A held answer of a Bridge-Agent, filed by `scripts/inbox-approve.py` with
urgency `now` and the actions `approve` and `reject`, waited unseen until it expired.
This skill is the generic notifier: one text and one poll per item, the poll's options
are the item's `actions`, the vote runs that verb, the result lands on the item.

The engine is `skills/inbox-notify/scripts/inbox_notify.py`. Nothing instance specific
lives in it: the channel comes from `infra/channels/<slug>.yaml`, the slug from
`inbox.notify_via` in `bridge-config.yaml`, the cadence from the workload declaration.
Read the referenced file ONLY when the branch below sends you there.

## Commands

```
python3 skills/inbox-notify/scripts/inbox_notify.py [--channel SLUG] tick [--dry-run] [--all]
python3 skills/inbox-notify/scripts/inbox_notify.py [--channel SLUG] test
python3 skills/inbox-notify/scripts/inbox_notify.py [--channel SLUG] show
```

| Command | Does |
|---|---|
| `tick` | announce every open item that needs a person now and has no poll yet; read the channel; run each vote (`approve`, `reject`, `drop`, `close`, `defer`); terminate the poll of an item decided elsewhere. The workload runs this every two minutes |
| `tick --dry-run` | print the texts and polls a tick would send; send nothing, read nothing, note nothing |
| `tick --all` | announce already announced items again (a new poll), after a lost phone or a changed recipient |
| `test` | one test text and one two-option test poll to the recipient, to prove the channel before the workload exists |
| `show` | the resolved configuration, handles included (they are handles, not secrets) |

Exit `0` after a tick, `2` on a config or usage problem before anything was sent, `1` when
the transport failed.

## Three invariants

1. **One announcement per item.** The poll's timestamp goes onto the item as a note
(`notify poll <ts> <uuid> via <slug> options approve,reject`). That note is the only
state: it keeps a second tick from announcing again and maps a vote back to its item.
An item decided through the poll is noted `notify decided <verb> via <slug>`; one
decided elsewhere has its poll terminated and is noted `notify closed-elsewhere`.
2. **One reader per account.** `signal-cli receive` consumes. Nothing else may run it on
this account, or it swallows the votes. The tick holds a lock and the workload runs
`single_flight: true`; a tick that finds the lock exits `0` and says so.
3. **One voter.** Only a vote from the recipient the poll was sent to counts (its uuid is
in the note). Anyone else's vote, a vote on an unknown poll, a withdrawn vote and a
vote on an item already decided do nothing but log a line.

## Decision tree

```
What does the user want?
├── "Tell me on my phone when an answer waits" → references/setup.md (channel file, test, workload)
├── "The approval never reached me" → `tick --dry-run` shows what is due; `show` the config;
│ is the workload running? (`/workload reconcile`);
│ does anything else run `receive` on the account?
├── Other wording, other language on the phone → notify.labels and notify.texts in the channel file
├── Ring for more than held answers → notify.urgencies / notify.sources in the channel file
├── A second transport (Telegram, Matrix, …) → one class next to SignalCli in the engine; the
│ contract is send_text, send_poll, terminate_poll, receive
└── What the phone shows and why → this file § Three invariants; docs/inbox.md § actions
```

## Files

| File | Holds |
|---|---|
| `scripts/inbox_notify.py` | the engine: selection, texts, the signal-cli transport, vote execution |
| `assets/channel.yaml` | the channel file to copy to `infra/channels/<slug>.yaml` |
| `assets/workload.yaml` | the declaration to copy to `workflow/workloads/inbox-notify.yaml` |
| `references/setup.md` | setting it up on one machine, step by step, and the trap list |
| `tests/test_inbox_notify.py` | hermetic tests with a fake `signal-cli`, `bash skills/inbox-notify/run-tests.sh` |

## Related

- [`docs/inbox.md`](../../docs/inbox.md) § What a person can do: `actions` and `expires_at`, which this skill renders
- [`scripts/inbox-approve.py`](../../scripts/inbox-approve.py): files the held answers this skill most often announces; note that it maps `close` to reject
- [`skills/workload/SKILL.md`](../workload/SKILL.md): provisions the tick as a declared run
- [`skills/channel/SKILL.md`](../channel/SKILL.md): inventory and health of the channel file
54 changes: 54 additions & 0 deletions skills/inbox-notify/assets/channel.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# yaml-language-server: $schema=../../../infra/channels/_schema.yaml
# Copy to infra/channels/signal.yaml (or another slug) and fill the two handles.
# A channel file is USER tier: handles may stand here in plain text, or as
# file://<path> and env://<NAME> references when the number must stay out of git.
# Validate: check-jsonschema --schemafile infra/channels/_schema.yaml infra/channels/signal.yaml
schema_version: 1
scope: user
name: signal
display_name: "Signal (own phone)"
description: >-
Open inbox items that need a person now reach this phone as one text and one poll;
the vote runs the item's verb. The only reader of this signal-cli account.
type: bot

implementation:
skill: inbox-notify

runtime:
remote: local
mode: launchd # the workload declaration provides the unit
service_label: org.example.inbox-notify # <label_prefix>.inbox-notify after `workload provision`

transport:
kind: signal-cli # the only transport implemented
# binary: signal-cli # when it is not on PATH under that name
account: "+10000000000" # the number this signal-cli is registered or linked with
recipient: "u:yourname.12" # the ONE person who may vote: a username (u:…) or a number
receive_timeout_sec: 20 # how long one tick listens for votes

notify:
urgencies: [now] # which open items ring: inbox urgency values
# sources: [agent-approval/] # optional: only items whose `from` starts with one of these
defer_days: 1 # a Defer vote defers until today + this
# cockpit_url: http://127.0.0.1:8797/ # shown under every announcement when set
# labels: {approve: Approve, reject: Reject, defer: Defer, drop: Drop, close: Close, later: Later}
# texts: # any of these, with {summary}, {id}, {when}, {url}, {label}, {host}
# heading: "Waiting for you: {summary}"
# valid_until: "Valid until {when}"
# poll: "{summary}"
# decided: "{label}: {summary}"

access:
policy: allowlist
self: "u:yourname.12"

behavior:
auto_response: false
signature: false
business_hours_only: false

verify:
service_check: "" # derived: launchctl list | grep <service_label>

status: pending # active once `inbox_notify.py test` reached the phone and the workload runs
40 changes: 40 additions & 0 deletions skills/inbox-notify/assets/workload.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# yaml-language-server: $schema=../../../workflow/workloads/_schema.yaml
# Copy to workflow/workloads/inbox-notify.yaml, replace /usr/bin/python3 and /path/to/bridge
# with absolute paths (a launchd unit expands nothing), then:
# bash skills/workload/workload.sh validate inbox-notify --strict
# bash skills/workload/workload.sh provision inbox-notify --yes --enable
schema_version: 1
scope: user

id: inbox-notify
title: Inbox notifier
purpose: "Announces every open inbox item that needs a person now on the configured channel, once, as a poll with the item's own actions, and executes the vote through the inbox."

persona_ref: _infrastructure
system: inbox
reports_to: none

placement:
host: local
kind: interval
runtime: launchd
owner: bridge
provisioned_at: null

schedule:
every_sec: 120
timezone: Etc/UTC # your IANA zone

execution:
command: ["/usr/bin/python3", "/path/to/bridge/skills/inbox-notify/scripts/inbox_notify.py", "--channel", "signal", "tick"]
working_dir: /path/to/bridge
timeout_sec: 300
isolation: process-group
single_flight: true # the account has ONE reader; a second tick would swallow votes
on_timeout: report

response:
evidence: log-trace
notify_on: [failure, timeout]

learned_from: "A held answer of a Bridge-Agent waited unseen in the inbox until it expired; three instances built three notifiers before this one became CORE (open-bridge#449)."
Loading
Loading