agent-letter-bridge 0.3.0__tar.gz

agent_letter_bridge-0.3.0/.githooks/commit-msg

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Assistant trailers must never reach a commit message.
+python3 scripts/privacy_scan.py "$1" || exit 1
+exec python3 scripts/editorial_check.py "$1"

agent_letter_bridge-0.3.0/.githooks/pre-commit

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Privacy discipline from commit one. See docs/ and scripts/privacy_scan.py.
+python3 scripts/privacy_scan.py || exit 1
+exec python3 scripts/editorial_check.py

agent_letter_bridge-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      # Runs on EVERY commit. A private repo's whole history becomes public if it
+      # is ever flipped, so this is enforcement, not a pre-release checkpoint.
+      - name: Privacy scan
+        run: python3 scripts/privacy_scan.py
+      # Binds TREE CONTENT on every commit path, web edits included. Commit
+      # MESSAGES are checked by the commit-msg hook only - a hook-less path
+      # can land a message the policy forbids, and reviewers read for that.
+      - name: Editorial tripwire
+        run: python3 scripts/editorial_check.py --worktree
+
+      # Asserts the PROPERTY (no runtime dependencies) rather than the
+      # absence of packaging. A build backend is install-time and never
+      # imported by the running daemon; a runtime dependency is. The gate
+      # explains that distinction so nobody bans pyproject.toml again.
+      - name: Dependency gate
+        run: python3 scripts/deps_check.py
+
+      # W5 vendors reviewed Letterbox conformance bytes. CI verifies the local
+      # manifest and inventory only; ordinary CI never fetches fixture data.
+      - name: Conformance fixture snapshot
+        run: python3 scripts/check_conformance_vendor.py
+
+      # A wheel that imports cleanly is proved by INSTALLING it, not by the
+      # suite - which runs from the source tree so mutations stay visible.
+      - name: Install smoke test
+        run: |
+          python3 -m venv /tmp/albvenv
+          /tmp/albvenv/bin/pip install --quiet .
+          /tmp/albvenv/bin/alb --help > /dev/null
+          /tmp/albvenv/bin/python -m alb --help > /dev/null
+          echo "wheel installs and both entry points run"
+
+      - name: Tests
+        run: python3 -m unittest discover -s tests -v
+        env:
+          PYTHONPATH: src
+
+      # A test that still passes with an invariant disabled is coverage without
+      # proof. This breaks each invariant in turn and asserts the suite goes red.
+      - name: Mutation gate
+        run: python3 scripts/mutation_check.py
+        env:
+          PYTHONPATH: src

agent_letter_bridge-0.3.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.env
+state/

agent_letter_bridge-0.3.0/CHANGELOG.md

@@ -0,0 +1,300 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] — 2026-09-10
+
+Two capabilities that were deliberately absent in the reply-only bridge, each
+added without loosening the guarantee that bounded it.
+
+### Added
+
+**Initiating send, gated by an explicit, revocable grant.** Until now the
+bridge could only answer a letter it already held — there was no way for an
+agent to start a conversation to a phone, by design. It can now, but only to a
+destination the operator has explicitly authorised with a *grant*
+(`alb --grant-create --as <owner> --platform telegram --chat-id <id>`), and a
+grant can be listed (`--grant-list`) and revoked (`--grant-disable`) at any
+time. With no grant, an initiating send fails closed. This narrows the old
+flat "no first-send command exists" guarantee to one that is still a guarantee:
+the bridge cannot originate contact anywhere the operator has not named, and a
+destination can be cut off without touching the code.
+
+**Initiating sends are budgeted, not open-ended.** Even with a grant an agent
+cannot flood a phone. Each destination admits only a small, refundable daily
+and hourly allowance with a cap on messages in flight; a send refused for
+budget is refused before anything leaves the machine. A send is idempotent on a
+caller-supplied intent id (`alb --send --id <intent>`), so a crash or a retry
+settles as exactly one message — or, when the outcome is genuinely unknown, as
+an explicitly ambiguous one that consumes its budget rather than risking a
+silent double-send.
+
+**Images, in and out.** An outbound reply or send may carry a photo from an
+allowlisted directory (`<root>/state/attach-roots.json` is a JSON object
+`{"roots": ["/absolute/dir", ...]}`; default deny), checked for real file type
+and sane dimensions before it leaves. An inbound photo becomes part of the letter as an opaque media
+reference plus its metadata — never a raw filesystem path, chat id, or original
+filename — so the archive gains the fact of the image without leaking where it
+lives. Photos stored before 0.3.0 have no `.ready` marker: after upgrade, stop
+the bridge and run `alb --grandfather-media --root <root>` once per seat.
+An unreadable existing media root is a failed grandfather (exit 1), not a
+successful empty run. The command takes the same root lock as the bridge:
+if a bridge is running it refuses (naming that pid) and writes nothing.
+
+## [0.2.5] — 2026-09-07
+
+Both of these were found by the first installation done for real, on a seat
+that had never had one, after the whole install path had already been audited
+against fixtures.
+
+**`init` could start a bridge from a different installation than the one that
+ran it.** The autostart command was the bare word `alb`, handed to a new
+shell, which resolves it from `PATH`. An operator who deliberately installed
+into a dedicated environment, and ran `init` from it, got a resident running
+whichever copy `PATH` found first — a different installation, possibly a
+different version, and on a machine with several bridges, one shared with
+another of them. The command now names the running installation absolutely:
+the console script beside the interpreter, quoted as one argv so a path
+containing a space survives the shell — a root with a space was rejected by
+argument parsing, and an interpreter with one failed to execute at all, both
+ordinary where a home directory carries somebody's name. What is printed and
+what the pane runs are still the same bytes.
+
+The bridge is started as `<interpreter> -I -m alb`. The isolation flag is the
+guarantee, not the absolute path: without it the launched process still honours
+`PYTHONPATH`, the user site directory and its own working directory, any of
+which can supply a different `alb`. The console script was friendlier to read
+and could not carry this — it is a shebang into an interpreter that will honour
+all three.
+
+The check is one of **identity, not availability**, and it is made under the
+same isolation the launch uses. Asking whether an
+interpreter can import `alb` establishes that some copy is reachable, not that
+it is the one running setup — an environment holding an older copy answers yes,
+and the command then starts that older copy. The interpreter is asked where its
+`alb` actually comes from, and the answer is compared with the code running
+`init`. Version strings are not compared, because two builds can agree about
+their name and differ. Proving identity under conditions the launch does not
+apply proves nothing about the launch: an approval obtained with `PYTHONPATH`
+stripped, for a command that honours it, describes a context that never
+happens.
+
+Where no command can be named that a fresh shell would resolve to this
+installation, `init` declines to start one and says why. Offering
+`<interpreter> -m alb` instead does not work for a source checkout: that
+process can import the package only because of the path it was started with,
+and a new shell inherits none of it. An autostart that reliably fails is worse
+than no offer.
+
+**The start warning reads the allowlist that was saved**, not the answers
+given during setup. On a re-run those differ, and both directions were wrong:
+an existing deny-all file is kept — correctly, nothing is clobbered — but if
+setup had read a chat id it did not save, it reported delivery as possible and
+offered to start; while an existing, populated allowlist was warned about as
+deny-all. The gate on disk after keep-or-write is the one that gets read, and a
+file that cannot be parsed counts as denying.
+
+The question is now asked of the allowlist itself rather than answered beside
+it. Setup used its own truthiness test, which read `{"chats": "42"}` and
+`{"chats": 42}` as permissive where the gate requires a non-empty list — so the
+gate denied everyone while setup offered to start. The gate was never weakened;
+there were two definitions of an allowlist, and now there is one.
+
+**Starting a bridge with a deny-all allowlist is now a deliberate answer
+rather than the default.** The gate is unchanged and still denies everyone
+until a chat id is added — that part worked exactly as intended, which is what
+made it confusing: a bridge reported as running, messages sent, nothing
+delivered, and no error anywhere to explain it. The offer now states plainly
+that nothing will arrive, and defaults to no. An operator who means it can
+still say yes.
+
+## [0.2.4] — 2026-09-06
+
+Two things a person installing this would have been misled by.
+
+**The setup wizard told a correct install it was not an install.** It gated
+on a terminal pane being chosen, but an integrated install does not ring
+through a pane — it rings through the letterbox's own doorbell, and the
+runtime asks for a pane only when there isn't one. So a correct install was
+told "a poller with nothing to ping is not an install" and refused a start,
+while working deployments ran exactly that configuration with a working
+doorbell. The wizard now recognises the helper as the ring it is, and stops
+asking integrated installs to pin a pane id that nothing ever reads.
+
+**The single-consumer probe now compares bots rather than process names.**
+The platform allows one consumer per token, so what matters is which bot a
+process holds. The probe matched on the executable's name alone, and so
+reported other relays that hold different bots and cannot compete. It now
+reads the identifying half of each candidate's token — never the secret half,
+which is dropped before any value is returned — and reports a process unless
+its bot is positively known to be a different one. An unreadable config is
+reported rather than cleared: being unable to prove a conflict is not the
+same as proving there is none.
+
+**A local network fault was reported as a Telegram outage.** Every transient
+that was not a rate limit was recorded as `upstream_5xx`, so a dropped wifi
+connection sent operators looking for a platform incident. `network` was
+already in the vocabulary and nothing emitted it. It does now, matched on the
+message prefix so a gateway error that merely contains the word cannot claim
+the code.
+
+> 0.2.2 and 0.2.3 were never published. Upgrading from 0.2.1 brings all three
+> sets of changes at once, which is why the notes below cover more than one
+> version.
+
+## [0.2.3] — unreleased
+
+The relay stops needing a person to notice it died - it needs an agent that wakes and asks.
+
+An agent asks `alb --check` when it wakes: exit 0 nothing to do, 2 the
+relay has been silent past a policy threshold, which is grounds to restart
+it rather than proof it is dead, and here is how; 3 something a restart
+will not fix. The allowance follows the state rather than one number for
+everything, because a bridge waiting out a rate limit is quiet BECAUSE it
+is behaving, and a bridge that has just started has not finished a poll
+yet. Both used to read as dead.
+
+`alb --stop` asks the running bridge to stand down and signals nothing.
+A request names the exact run it was meant for, so one written for a
+bridge that then crashes cannot stop the next bridge to start.
+
+Failures reach a log file as well as the terminal, timestamped, so "is
+it down" and "since when" have different answers. A broken log can never
+stop the bridge.
+
+The install refuses to finish without a bell. Pane discovery asks every
+multiplexer present and the notifier follows the pane the operator picks,
+so an id we never showed cannot be accepted and silently pointed at a
+multiplexer that is not there.
+
+## [0.2.2] — unreleased, canary only
+
+**Not a release.** The version exists so a running bridge can say which code
+it is, because a canary you cannot identify proves nothing.
+
+Recoverable platform conditions stop being terminal. 429 and 5xx on fetch and
+confirm are waited out rather than died on, honouring Telegram's documented
+`parameters.retry_after` as a floor; 401 and 403 stay fatal, and 409 still
+yields. A throttled send becomes `Throttled` rather than a permanent refusal,
+keeps its claim, survives a restart as a deferred state rather than being
+dead-lettered as ambiguous, and can be finished by retyping the same reply.
+
+Three further defects were found and fixed in the same work, each after the
+previous fix's gates were green: receipt ordering was lexical and broke past
+nine events; resume was check-then-act, so two resumers could both send; and
+the lock added to fix that built its path from unvalidated caller text.
+
+## [0.2.1] — 2026-09-04
+
+Package metadata correction. 0.2.0 shipped with `version = "0.1.1"` in
+`pyproject.toml`, so `alb --version` reported the previous release on a tree
+tagged v0.2.0 — a stranger could not tell which world they had cloned. The tag
+stands as published;
+this release makes the metadata tell the truth.
+
+Also in this release: the README no longer describes the ring as something that
+"only makes it faster" — letter first, then ring, and without a bell mail lands
+in a dead drop and nobody is told. The Design section no longer dates its
+isolation claim to v0.1.
+
+## [0.2.0] — 2026-09-04
+
+Durable outbound, correspondent identity and threading, and read-only
+retrieval. First release published to a public repository.
+
+### The letter is the claim
+
+An outbound reply is written as a letter — created `O_EXCL` — **before** the
+platform is touched. That create *is* the claim on the work, so a crash between
+send and record cannot produce a silent double-send: the second attempt finds
+the letter already there. Delivery events are immutable numbered files rather
+than appended lines, so a crash mid-write cannot tear the record. Startup
+reconciliation finds anything left in flight with no terminal event,
+dead-letters it, and says so.
+
+### Identity and threading
+
+Correspondents are provenance, not participants: `from` and `to` remain
+routable agent ids. Replies resolve on the exact `(platform, origin,
+message_id)` triple in both directions — no prefix matching. One thread per
+correspondent, stamped inside publish.
+
+### Retrieval
+
+`--list`, `--show`, `--search`, `--thread`, `--export`. Read-only, standard
+library, no config and no token: reading your own records never needs a
+credential.
+
+### Coverage
+
+The invariants are pinned by mutation testing. Automated coverage still uses
+fakes — the suite proves the invariants, live runs prove the transports, and
+those are different claims. The inbound path has real live mileage; the paths
+added here are covered and reviewed but newer.
+
+## [0.1.1] — 2026-09-02
+
+First complete release (0.1.0 tagged earlier the same day; 0.1.1 lands the
+findings of a full-repo consistency review —
+init writes the pasted pane id before the resident offer reads the config,
+claims scoped to what the envelope actually records, roles-not-processes
+stated honestly, integrated `--mail-root` documented with its true shape, and
+one voice across package metadata, CLI help and docs). Private until the
+repository owner flips it; the version marks "finished", not "published".
+
+### Highlights since the pre-release notes below
+- `alb --init`: interactive setup that owns every boilerplate step — 0700
+  state directory, mode-600 config, DENY-ALL allowlist — asks only what no
+  program can derive, never overwrites, never invents an allowlist entry,
+  never touches the network unless explicitly asked, and ends by starting
+  the bridge in its own cmux pane (or printing the exact command when it
+  cannot).
+- Integrated mode (`--mail-root`): letters delivered into a mailbox the
+  bridge does not own, private state strictly separated, ring through the
+  mailbox's own doorbell helper with the outcome parsed rather than assumed.
+  A missing mailbox is refused, never invented.
+- Cycle report: `fetched N · published N · denied N (allowlist)` — the deny
+  visible to the operator while the sender still hears silence; duplicates
+  counted apart from denials. Counts, never identities.
+- Refusals grown from live installs: placeholder `ALB_SURFACE` values
+  refused by name; unknown config keys refused; `--version` answers without
+  a state directory.
+- Two install routes: `INSTALL.md` for people, `docs/agent-install.md` as a
+  brief for a CLI agent installing on someone's behalf — the latter hardened
+  against the ways an install actually goes wrong.
+- `docs/COMPARE.md`: the field, checked against each tool's current code and
+  docs, our own limitations stated first, every citation dated.
+- Verified live: a full phone → letter → doorbell → read → reply loop, and an
+  install performed end-to-end by a CLI agent working from the docs.
+
+### Proven by
+Invariants pinned by mutation testing — each proved by disabling it and
+watching the suite go red — privacy and dependency gates in pre-commit and
+CI, and the live runs above.
+
+### Added
+- Durable-letter store: atomic publish, two-fence parsing, exact-id resolution,
+  path-shaped identifiers refused, delivered-ids ledger with a durable
+  update-id lookup behind it.
+- Fail-closed allowlist, deny-all by default, enforced at both inbound and send.
+- Untrusted poller: letter to disk, then acknowledge. Denied senders produce
+  silence and are still consumed.
+- Notifier: fixed content-free line to one explicitly identified surface.
+- Bounded outbound: replies only to a stored letter, claim before send,
+  ambiguous outcomes dead-letter and are never retried.
+- Watchdog reporting, and `alb --status` as the single should-I-worry surface.
+- `alb --doctor`: local single-consumer probe, daemon-context checks, and an
+  explicit statement of what it cannot prove.
+- `alb --canary`: proves the send path through the real send helper.
+- Telegram and cmux adapters. `examples/` unit files for launchd and systemd.
+- Mutation gate: every invariant is disabled in turn and the suite must go red.
+- Privacy enforcement from the first commit, in hooks and CI.
+
+### Notes
+- The ring requires a multiplexer. There is no notifier that works without one.
+- Verified live against a sacrificial bot. (Superseded above.)

agent_letter_bridge-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing
+
+## Non-negotiables
+
+Read `docs/invariants.md` first. The invariants are the product; a change that
+weakens one is not a change we can take, however tidy it is.
+
+**Zero third-party runtime dependencies in the core.** A PR that adds one to the
+poller, send helper, watchdog or doctor will be declined. This is a security
+property, not a style preference — the audit has to stay finishable.
+
+**Every invariant needs a mutation-proved test.** A test that passes when the
+invariant is disabled is not a test of that invariant.
+
+**Fixtures are synthetic.** Never copy a real message, chat id, username or path
+into a fixture. This is a privacy control, not a testing preference: git history
+makes a leak permanent.
+
+**Honest labelling.** A partially-met criterion is labelled PARTIAL. Do not pad
+it to look complete.
+
+## Repository editorial checks
+
+These are this repository's publication policy for all public prose — docs,
+README, CHANGELOG, and commit messages. `scripts/editorial_check.py` trips on
+known banned phrasings at commit and in CI; it is a **known-phrase tripwire,
+not a meaning checker**, so passing it does not certify compliance — reviewers
+still read for meaning. If it refuses your commit, reword per the rule below;
+the check names which one.
+
+**The doorbell is a required part of a working deployment.** Never write it as
+something a deployment can reasonably skip. Durability may be stated — a
+landed letter survives a failed bell — but not in a sentence that presents
+ringing as a choice. Violates the policy (a reviewer catches it even where the
+script does not): "you can disable the ring and rely on the inbox". Passes:
+"mail still lands if the bell fails; a bridge left in that state is not
+installed".
+
+**Comparisons name their subject.** A claim about another tool cites
+[`docs/COMPARE.md`](docs/COMPARE.md) and names the tool; sentences asserting
+something about all tools of a category are refused.
+
+**Public text carries product facts, defects and method.** No numeric test or
+invariant totals in prose or commit messages — state that behaviour is
+covered, don't count it. The script scans all tracked Markdown as it stands
+and your new commit message; historic commit messages are not rescanned. In
+CI only the tree is scanned — messages are checked by the commit-msg hook, so
+a hook-less commit path relies on review for its message.
+
+## Set up the hooks — they are not automatic
+
+Git hooks are per-clone local config. A fresh clone inherits nothing, so run this
+once after cloning:
+
+```sh
+git config core.hooksPath .githooks
+```
+
+That wires the `pre-commit` privacy scan and the `commit-msg` trailer check. CI is
+the real gate and runs regardless; the hooks just fail faster.
+
+## What the privacy scan does and does not cover
+
+The scan uses **structural** patterns — absolute home paths, volume paths,
+service-manager domains, token-shaped strings, assistant trailers, machine
+identifiers. It deliberately contains no list of private strings, because such a
+list in the repo would be the leak it exists to prevent.
+
+**It therefore cannot catch semantically private names** (an internal tool or host
+name that looks like an ordinary word). Supply those out of band via
+`ALB_EXTRA_PATTERNS`, a path to a newline-separated regex file that is never
+committed. **CI does not set it**, so that class is covered by review and the
+pre-release history audit — not by the automated gate. Do not assume CI covers it.
+
+## Claims
+
+Every claim in the docs must be traceable to the mechanism that makes it true.
+If you cannot point at the mechanism, narrow the claim. Absolutes that sound
+strong and are disprovable discredit the true claims beside them.
+
+## Style
+
+Python 3.11+, standard library only. Match the surrounding code.