Repository navigation
Releases
postbag v2.3.0
Clarifies peer authorization and send outcomes. Each letter reminds its
recipient to act within the human's existing authorization, and CLI receipts
distinguish submission from acceptance. Existing bags need no migration.
Reconnect MCP servers after upgrading to load the new instructions.
Changed
- CLI send receipts say "submitted" and state that acceptance is unconfirmed.
The ledger and MCP submission states are unchanged. - Ordinary and final letters carry guidance to act only within the human's
existing authorization. MCP instructions carry the same reminder. This is
model guidance, not an enforced permission boundary. - Documentation distinguishes submission from recipient acceptance, explains
per-send approval settings, and compares Postbag with A2A.
postbag v2.2.2
Documentation release. No runtime change beyond the version number.
Changed
- The README is a short product page about Codex and Claude Code talking to
each other: a one-line pitch, the demo, install and setup for both hosts,
a two-prompt quick start, the five MCP tools, and three security notes. - The demo shows two panes, Claude Code and Codex, each with its own MCP
calls and the letters it receives, from scripted calls to two real servers
with stand-in native doors. - A 1280x640 social preview image is in
docs/assets/social-preview.png.
postbag v2.2.1
Documentation and repository layout release. No runtime change beyond the
version number.
Changed
- The README is a short product page: install and connect for both hosts,
the two-prompt setup, the five tools, and what to know before use. Release
evidence and migration notes stay in this file,docs/mcp.mdand
docs/native-compatibility.md. - The demo shows scripted calls to two real
postbag mcpservers, one with
a Codex identity and one with a Claude Code identity, through fake native
doors, including the envelope each door receives. Its source is
docs/demo_mcp.py. The CLI demo environment script is removed. - Tests live in
tests/. CI, the installed-wheel check and the source
distribution follow the new paths.
postbag v2.2.0
The new postbag mcp launcher lets MCP installers run Postbag by its
package name. It exposes the same five tools as postbag-mcp. This release
adds agent installation guidance and official MCP Registry metadata.
Existing host configurations and bags need no changes. Reconnect MCP
servers after upgrading.
Added
postbag mcpstarts the existing stdio MCP server without changing the
five bag operations. It takes no bag option or operational arguments and keeps
the same optional MCP dependency and missing-extra guidance.- MCP Registry metadata and release automation, with a pinned uvx launch
command that installs the MCP extra from the same package version. - Agent installation instructions, marketplace artwork and a current CLI
demo using temporary state and fake native doors. - A Dockerfile for directory startup and tool-catalog checks. Native message
delivery from the container is unsupported and unverified.
Changed
- Refresh the README with direct installation, MCP setup and supported-host
information. Directory publication and tool introspection do not establish
native message delivery or expand the supported peers.
postbag v2.1.0
Leaving a bag is now a recorded withdrawal of the caller's name. MCP
inventory also reports the installed worker version. Upgrade both peers,
including their CLI and MCP installations, and reconnect each MCP server.
Bags containing a leave record require 2.1 readers. Older bags remain
unchanged and need no migration.
Added
- CLI
leaveand MCPpostbag_leavewithdraw the caller's current name
from one bag. They preserve its history and session, contact no native
transport, and append a leave record under the same lock as sending.
Queued letters can still arrive. Rejoin only when the human asks to resume. - MCP inventory data includes
versionfor the installed core loaded by
that call's worker, including empty and partial inventories. It does not
prove that the running parent has refreshed its tool catalog.
Changed
- Preserve the core refusal reason when directing an MCP caller to read
the bag, including departure times and names that moved to another door.
Compatibility
- Upgrade every reader of a bag before recording its first leave. Readers
older than 2.1 refuse a bag containing that record. Existing bags need no
rewrite. Downgrading does not undo a leave, and deleting leave rows would
restore withdrawn registrations. Unknown record kinds remain errors. - Reconnect MCP servers after upgrading to expose the new tool. The internal
worker protocol remains 2 and does not negotiate tool availability.
postbag v2.0.0
Postbag no longer uses letter budgets or exchanges. Upgrade both peers,
including their CLI and MCP installations, and reconnect each MCP server.
Existing bags read without migration. Historical open records remain as
inert history.
Removed
- Remove the
opencommand, exchanges, letter budgets and the human-only
command distinction. Postbag sets no limit on the number or rate of letters. - Remove derived exchange and remaining-budget fields from MCP results.
Added
- CLI
send --finaland MCPfinal=trueask for no reply to that letter.
The flag is a strict Boolean, absent meaning false. It is stored in the
ledger only when true and returned in send receipts and MCP letter records.
Its footer carries no reply command. It does not prevent a later send. - Internal worker protocol 2 uses a separate entry point. Old-server/new-worker
mismatch refuses before work. New-server/old-worker mismatch exits before
dispatch, but the parent conservatively reports an unknown send outcome
because an unstructured exit cannot prove that stage. Reconnect after
upgrading or downgrading. There is no fallback to the old entry point.
Changed
joincreates a missing default, named or path-selected bag. Argument and
identity refusals create nothing. Missing-bagsendandreadcreate no
files or directories and direct the caller tojoinorbags, respectively.
Once creation starts, an I/O failure can leave a directory or partial file.- Count letters cumulatively across each bag. Inventory reports letter counts
instead of budgets, and distinguishes bags with letters, bags without letters
and unavailable bags. - Ask recipients to reply only when doing so advances the task, without
courtesy acknowledgements, unsolicited delivery checks or unnecessary
questions. Human-requested receipts remain substantive work. - Preserve existing ledger modes. Mutations refuse files with group or other
access or without owner read and write. Only creation sets mode0600. - Keep MCP's body, page and worker-result depth caps and nonblocking locks,
along with native transport timeouts. The CLI does not apply MCP's body
cap. These resource controls do not prevent reply loops.
Compatibility
- Read historical bags without rewriting. Retain old
openrows and their
limitas inert history. Every record keeps its originaln, addressed by
MCPbeforeandnext_before. CLIread Nreturns the last N records.
Displayed letter numbers count only letters, including those before old
exchange boundaries. - Mixed 1.x/2.0 participants are unsupported and not negotiated. An old sender
still applies the last retained budget and counts 2.0 letters against it.
New bags have noopenrow, so old senders refuse there. Old readers hide
the final flag. Upgrade all participants before continuing. - Footer guidance, final flags and host approvals do not guarantee that models
stop. Closing a client does not revoke a persisted queue or recall a letter.
Mutations check existing ledger modes after taking the lock. If a ledger
becomes unwritable, a waiting mutation can refuse, while an operation past
that check may finish and read access can remain.
Validation
- The installed
8b87b4fcandidate passed native acceptance on its first run:
two-way receipt, a 30.0668-second final-letter observation and a deliberately
initiated ordinary round trip afterward. Native evidence
records exact provenance, runtime versions, permissions and limits. - The same candidate passed 586 full-suite tests, 157 installed-wheel MCP
tests and 55 extracted-sdisttest_core_2.pychecks. All 13 CI jobs passed.
Candidate CI.
postbag v1.4.0
Refusals now carry structured recovery guidance, so an MCP caller is told
which tool to call and who must act, and the envelope names the MCP send
tool for named and default bags. The native queue subprocess no longer
inherits the sender's inbox fields. Upgrade both peers to the same version
and reconnect their MCP servers. Existing ledgers need no migration.
Fixed
- Name MCP tools in recovery guidance and reply instructions for default and
named bags. Path-based bags keep their CLI reply command. Recovery identifies
whether the caller, recipient, or human must act. - Reject malformed Unicode before CLI submission while preserving legacy
ledger reads. Handle oversized JSON integers as clean ledger refusals. - Report uncertain recording after a flush or fsync failure without claiming
that the submitted letter is absent from the ledger. - Preserve structured unknown outcomes for malformed or excessively nested
worker responses. Warn shared-inbox subagents before they rename a peer. - Remove sender inbox and identity fields from the native queue subprocess
environment. Private fixtures verify this filtering, and a live cross-vendor
exchange with the installed candidate confirmed native delivery.
Changed
- Expand failure and cancellation regression coverage, isolate CLI test homes,
and test MCP against an installed wheel outside the source checkout. - Clarify partial inventory results, recorded-letter budget limits, and
full-suite dependency requirements.
postbag v1.3.0
MCP tools remove shell-command friction while retaining the existing bag,
native transports, and human-controlled letter budget. Upgrade both peers
to the same version, reconnect their MCP servers, and rejoin under the
same names. Existing ledgers and remaining budgets need no migration.
Added
- Optional
postbag[mcp]extra andpostbag-mcpstdio entry point with four
tools: join, send, read, and bag inventory. Budgets remain human-controlled.
Tools bind native caller identity, accept named bags, return structured
outcomes, and isolate each invocation in a subprocess. - MCP wire tests for current and legacy clients, sender binding, private
socket delivery, concurrency, budget limits, pagination, and cancellation. - Installed-package native acceptance with Claude Code 2.1.285 and Codex
0.157.1 / desktop 0.158.0-alpha.2.1, including default server discovery,
model-authored replies, observed receipt, and spent-budget refusal.
Live Claude/clear, native Linux delivery and restricted spawned-agent
targets remain unverified. Forced process-tree termination can leave an
unknown submission outcome. postbag bags --resumeshows Claude resume commands using optional conversation
IDs recorded atjoin. These snapshots do not change door identity or routing.
Older or invalid metadata gets one rejoin reminder after the inventory.
Known IDs add one copyable command per peer beneath the bag's ordinary row.postbag bags, a read-only inventory with a count of discovered paths, remaining budget,
last recorded letter timestamp, and registered names with vendors.- Scan the default ledger and valid named ledgers directly under
~/.postbag/bags, plus an explicitly selected existing custom path.
Unselected external paths cannot be discovered. A selected custom alias
of an already listed regular file is not repeated. - Unavailable ledgers remain in the count. Busy or unreadable ledgers and scan
errors do not hide other readable bags. The command reports them and exits 1.
It creates no files or index, probes no sessions, and changes no ledger format.
Budgets do not expire, and registered names do not imply live sessions. - Terminal inventory adapts to width, groups peers by vendor and orders bags
by their last recorded letter. It uses brief local times and optional styling.
Piped output keeps the original table, order and full ISO timestamps.
NO_COLORorTERM=dumbdisables terminal styling.
Changed
- Report uncertain native submissions without advice to blindly resend.
Timeouts, partial socket writes, and nonzero queue exits may have delivered.
Recording failures preserve the fact that native submission succeeded. - Keep
bags --resumein the ordinary compact inventory layout. Show missing-ID
guidance once and brighten secondary terminal text for readability. - Clarify that postbag records submission, does not read delivery notices,
and does not guarantee recipient acceptance. Claude's inbound policy may
hold or refuse a letter even in a bypass-permissions session. - Record runtime versions and recipient policy in native acceptance checks,
distinguishing live receipt from successful submission. - Verify the unchanged native transport between two headless Claude Code
2.1.278 sessions on macOS, with separate recipient-policy probes.
Fixed
- Prefer the concrete
CODEX_THREAD_IDover the shared root's
CODEX_SESSION_ID, keeping the latter as a fallback for older hosts.
Existing peers whose thread differs from that shared ID need to join again. - Refuse NUL-containing messages and oversized native command arguments with
actionable errors before submission. - Render stored timestamps in canonical form so legacy timestamp separators
cannot inject terminal controls.
postbag v1.2.1
Documentation release. No runtime change beyond the version number.
Changed
- The README is a manual again: the upgrade notes and the release-by-release
verification history moved out, this file keeps them. One sentence remains,
both sessions run the same postbag.
postbag v1.2.0
A bag has a name. Named bags let two conversations use separate ledgers,
nothing is separated automatically, and every command an agent is handed
says which bag it belongs to.
Added
- Named bags.
defaultis~/.postbag/ledger.jsonl, any other name is
~/.postbag/bags/<name>.jsonl, and an absolute path is a bag too. A bag
name follows the peer name grammar, anddefaultis reserved. --bag NAMEbefore every verb:postbag --bag acceptance read. It
overridesPOSTBAG_LEDGER, and a bare command selects as before.opencreates a named bag that does not exist.join,sendandread
refuse one and say which command the human should run.- Every success line, every refusal after bag selection and every envelope
names the bag,defaultincluded: "@bob (claude) joined in bag default",
"exchange open: 12 letters in bag acceptance", "in bag acceptance: @ada
(claude), @bob (claude). exchange 3: 8 of 12 letters left." The constant
refusal of an invalid path carries no bag label. - Every command postbag generates carries the bag: the reply command in a
letter, thejoina refusal asks a restarted session to run, theopen
it asks the human for, and thereadit points to. An absolute path is
single-quoted for the shell.
Changed
- The envelope's first line is "Letter 4 of 12 from @ada to @bob via
postbag (exchange 3, bag acceptance)", for the last letter too. - The reply command inside a non-final letter is
postbag --bag acceptance send @ada -. join,open,sendandreadname the bag on their first line:
"letter 4 of 12 in exchange 3 delivered to @bob in bag acceptance, 8 left".
Compatibility
- The ledger format is unchanged. Old ledgers read without rewriting, and
no version gate was added. - A 1.1
sendrefuses--bag, which every 1.2 reply command carries, so
scoped commands need 1.2 at both ends, the default bag included. An older
CLI reaches a bag by path:POSTBAG_LEDGER='/abs/path' postbag send .... POSTBAG_LEDGERis unchanged: a path,~expanded, used when--bagis
absent.- A ledger path must contain only printable characters. A custom path
holding a control character or a line separator is now refused.