@creatornader/agent-bridge 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/CHANGELOG.md +73 -1
  2. package/README.md +73 -7
  3. package/ROADMAP.md +29 -0
  4. package/SECURITY.md +23 -0
  5. package/SKILL.md +5 -1
  6. package/dist/archive.d.ts +2 -2
  7. package/dist/{bridge-service-YTjGr91A.d.ts → bridge-service-CNBKdYXh.d.ts} +2 -1
  8. package/dist/{bridge-store-Boaj-ZbO.d.ts → bridge-store-ByJ6CaJk.d.ts} +1 -0
  9. package/dist/bridge.d.ts +15 -8
  10. package/dist/bridge.js +10 -8
  11. package/dist/{chunk-PDIHDBP3.js → chunk-7VJI2MXI.js} +116 -26
  12. package/dist/chunk-7VJI2MXI.js.map +1 -0
  13. package/dist/{chunk-4VB44KJU.js → chunk-AWE3DFZV.js} +3 -2
  14. package/dist/chunk-AWE3DFZV.js.map +1 -0
  15. package/dist/{chunk-IHZFI7TH.js → chunk-E4OWHGUE.js} +5 -2
  16. package/dist/chunk-E4OWHGUE.js.map +1 -0
  17. package/dist/{chunk-SYGONYMM.js → chunk-HUHG7XTB.js} +6 -5
  18. package/dist/chunk-HUHG7XTB.js.map +1 -0
  19. package/dist/{chunk-DQOZJJZ2.js → chunk-IVG4XWWS.js} +5 -5
  20. package/dist/{chunk-DQOZJJZ2.js.map → chunk-IVG4XWWS.js.map} +1 -1
  21. package/dist/{chunk-3YHVUPU2.js → chunk-P635FAN4.js} +4 -4
  22. package/dist/chunk-P635FAN4.js.map +1 -0
  23. package/dist/{chunk-6BTJE6D4.js → chunk-QNXHDOJ5.js} +56 -23
  24. package/dist/chunk-QNXHDOJ5.js.map +1 -0
  25. package/dist/{chunk-MCKKVNCE.js → chunk-QPC6JHA3.js} +5 -5
  26. package/dist/{chunk-SV3SVBYS.js → chunk-SN7PIVDF.js} +2 -2
  27. package/dist/{chunk-2DFNOLMO.js → chunk-XDNT6ZNZ.js} +9 -6
  28. package/dist/chunk-XDNT6ZNZ.js.map +1 -0
  29. package/dist/{chunk-LAHNQZDN.js → chunk-Z6JP6MYD.js} +2 -2
  30. package/dist/cli.js +9 -9
  31. package/dist/cli.js.map +1 -1
  32. package/dist/client-runtime.d.ts +3 -3
  33. package/dist/client-runtime.js +6 -6
  34. package/dist/contracts/generate.js +1 -1
  35. package/dist/dr.js +3 -3
  36. package/dist/{gateway-BQHpV-MZ.d.ts → gateway-CW-61lvs.d.ts} +2 -2
  37. package/dist/gateway-main.js +5 -5
  38. package/dist/gateway.d.ts +3 -3
  39. package/dist/gateway.js +3 -3
  40. package/dist/index.js +7 -7
  41. package/dist/{postgres-bridge-store-WASumj26.d.ts → postgres-bridge-store-C9KG9Z69.d.ts} +1 -1
  42. package/dist/postgres-production-preflight.d.ts +32 -0
  43. package/dist/postgres-production-preflight.js +249 -0
  44. package/dist/postgres-production-preflight.js.map +1 -0
  45. package/dist/server.js +7 -7
  46. package/dist/{sqlite-edge-store-Bc15DvpX.d.ts → sqlite-edge-store-CdMIOrho.d.ts} +1 -1
  47. package/dist/sqlite.d.ts +3 -3
  48. package/dist/sqlite.js +2 -2
  49. package/docs/architecture-v2.md +36 -5
  50. package/docs/deployment.md +144 -0
  51. package/llms.txt +2 -1
  52. package/openapi/agent-bridge-v2.openapi.json +5 -1
  53. package/package.json +5 -1
  54. package/schemas/agent-bridge-v2.capabilities.json +2 -1
  55. package/schemas/agent-bridge-v2.mcp.json +5 -1
  56. package/schemas/agent-bridge-v2.schema.json +4 -0
  57. package/sql/migrations/007_runtime_role.sql +8 -4
  58. package/sql/migrations/013_row_isolation.sql +71 -8
  59. package/sql/migrations/014_owner_control_plane.sql +124 -31
  60. package/sql/migrations/015_portable_archives.sql +143 -41
  61. package/sql/migrations/016_native_dr_fence.sql +102 -35
  62. package/sql/migrations/018_endpoint_migration_challenges.sql +36 -10
  63. package/sql/migrations/019_endpoint_migration_same_successor.sql +34 -10
  64. package/sql/migrations/020_managed_authority_compat.sql +698 -0
  65. package/sql/migrations/021_native_backup_reader.sql +421 -0
  66. package/sql/setup.sql +1 -3
  67. package/dist/chunk-2DFNOLMO.js.map +0 -1
  68. package/dist/chunk-3YHVUPU2.js.map +0 -1
  69. package/dist/chunk-4VB44KJU.js.map +0 -1
  70. package/dist/chunk-6BTJE6D4.js.map +0 -1
  71. package/dist/chunk-IHZFI7TH.js.map +0 -1
  72. package/dist/chunk-PDIHDBP3.js.map +0 -1
  73. package/dist/chunk-SYGONYMM.js.map +0 -1
  74. /package/dist/{chunk-MCKKVNCE.js.map → chunk-QPC6JHA3.js.map} +0 -0
  75. /package/dist/{chunk-SV3SVBYS.js.map → chunk-SN7PIVDF.js.map} +0 -0
  76. /package/dist/{chunk-LAHNQZDN.js.map → chunk-Z6JP6MYD.js.map} +0 -0
package/CHANGELOG.md CHANGED
@@ -6,6 +6,77 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.5.0] - 2026-07-20
10
+
11
+ ### Added
12
+
13
+ - Add migration 020 to converge databases released through migration 019 on the managed-authority
14
+ function and attestation contract. Migration readiness accepts only the exact
15
+ released checksums or the current checksums for changed migrations, so existing
16
+ databases can advance without allowing arbitrary ledger drift.
17
+
18
+ - Add migration 021 with an attested, database-derived backup-reader role. The role is
19
+ `NOLOGIN`, receives read-only access to Agent Bridge tables and sequences, and is
20
+ granted only to the schema owner so managed PostgreSQL can produce complete native
21
+ backups without exposing backup access to runtime or control principals. Migrations
22
+ accept `CREATEROLE`, while source native backups require a true superuser or
23
+ `BYPASSRLS`. A restore target superuser can validate a suspended restored schema owner.
24
+
25
+ - Add a PostgreSQL 15 through 18 integration path that applies every migration as a
26
+ non-superuser with `CREATEROLE` and `BYPASSRLS`, matching the authority available on
27
+ managed providers such as Supabase.
28
+
29
+ - Add a read-only production PostgreSQL preflight. It rejects unsupported server
30
+ majors, insufficient migration authority, migration-ledger drift, derived-role
31
+ collisions, and incompatible legacy import tables before any schema change runs.
32
+ It reports migration authority separately from native DR authority. Reports omit
33
+ connection URLs and database identities.
34
+
35
+ - Add a manual production proof workflow for an existing Agent Bridge gateway. It
36
+ uses separate sender, receiver, Fly machine-cycle, and verifier jobs behind the
37
+ `agent-bridge-production-proof` environment. A versioned, phase-specific receipt
38
+ contract records offline queue replay, exact idempotency, cross-host claim and
39
+ acknowledgment, a changed Fly runtime instance ID, and fresh-edge verification without
40
+ storing credentials, message content, database URLs, or SQLite files.
41
+ - Add an optional `messageId` filter to HTTP 2.1, MCP, and CLI delivery claims. It
42
+ atomically selects and maintains only that eligible recipient delivery. Omitting the
43
+ filter preserves claim-next behavior, and HTTP 2.0 rejects the new field.
44
+
45
+ - Add a maintained Fly.io reference config with one always-running shared VM, HTTPS
46
+ ingress, `/readyz` checks, and a 30-second SIGTERM budget. Add a read-only preflight
47
+ that checks the local contract and, when an app is supplied, reports value-safe Fly
48
+ account and app observations. The deployment docs keep migration, restricted-runtime
49
+ bootstrap, secret changes, deployment, and cross-machine proof behind operator gates.
50
+
51
+ ### Fixed
52
+
53
+ - Support managed PostgreSQL role administration without restating protected role
54
+ attributes. PostgreSQL 16 and newer may split one schema-owner membership across an
55
+ administrator grant and a separate inherit-and-set grant. Readiness and native DR
56
+ now validate and preserve the effective authority while rejecting unexpected grant
57
+ shapes. Ownership transfers receive schema `CREATE` only for the transaction that
58
+ needs it, and runtime bootstrap verifies an existing login before changing its
59
+ password or membership.
60
+
61
+ - Make runtime bootstrap transactional and reject derived authority names, object
62
+ owners, unexpected memberships, and reverse membership edges before changing an
63
+ existing login.
64
+
65
+ - Suspend restored runtime, control, and archive principals as `NOLOGIN` roles without
66
+ authority memberships. Control and archive registration histories receive explicit
67
+ revocation events. Restore may reuse one preexisting role only when it is the source
68
+ schema owner, the target session user, and a true superuser.
69
+
70
+ - Resolve the Fly Dockerfile from the deployment config directory and reject missing
71
+ configured build files during the production preflight.
72
+
73
+ - Check the client TLS socket during the production PostgreSQL preflight when a
74
+ session pooler terminates TLS before opening its database connection.
75
+
76
+ - Fix the legacy Supabase setup script's column comment so PostgreSQL accepts the
77
+ checked-in schema without manual editing. The PostgreSQL integration suite now runs
78
+ that script before testing the v2 legacy import.
79
+
9
80
  ## [0.4.0] - 2026-07-19
10
81
 
11
82
  ### Added
@@ -284,7 +355,8 @@ First tagged release. Marks the point where agent-bridge has shipped its initial
284
355
  - Narrative-leak detection in CI + on commit via `creatornader/textleaks@v0.2.0` (renamed from leakguard).
285
356
 
286
357
  [0.1.0]: https://github.com/creatornader/agent-bridge/releases/tag/v0.1.0
287
- [Unreleased]: https://github.com/creatornader/agent-bridge/compare/v0.4.0...HEAD
358
+ [Unreleased]: https://github.com/creatornader/agent-bridge/compare/v0.5.0...HEAD
359
+ [0.5.0]: https://github.com/creatornader/agent-bridge/compare/v0.4.0...v0.5.0
288
360
  [0.4.0]: https://github.com/creatornader/agent-bridge/compare/v0.3.1...v0.4.0
289
361
  [0.3.1]: https://github.com/creatornader/agent-bridge/compare/v0.3.0...v0.3.1
290
362
  [0.3.0]: https://github.com/creatornader/agent-bridge/compare/v0.2.0...v0.3.0
package/README.md CHANGED
@@ -63,6 +63,51 @@ a production TLS deployment. Read [the deployment guide](docs/deployment.md) bef
63
63
  exposing a gateway, changing network bindings, upgrading the schema, or relying on the
64
64
  named volume for persistent data.
65
65
 
66
+ The repository also maintains a provider-neutral Fly.io reference at
67
+ [`deploy/fly.toml`](deploy/fly.toml). It deliberately omits an app name and release
68
+ command. Check the local contract before creating or changing any Fly resource:
69
+
70
+ ```bash
71
+ npm run preflight:fly -- --json
72
+ ```
73
+
74
+ Before migrating an existing PostgreSQL database, run the read-only production
75
+ preflight with schema-owner authority:
76
+
77
+ ```bash
78
+ AGENT_BRIDGE_DATABASE_URL="..." npm run preflight:postgres:production -- --json --require-ssl
79
+ ```
80
+
81
+ The command checks the PostgreSQL major, database and role authority, existing
82
+ migration ledger, derived-role collisions, and the legacy `shared_context` import
83
+ shape inside a read-only transaction. `authority.roles` reports migration capability:
84
+ the schema owner may be a true superuser or a managed-provider administrator with
85
+ `CREATEROLE`. `authority.native_dr` reports source-backup capability. The source normally
86
+ connects as the schema owner, which must be a true superuser or hold `BYPASSRLS`, so
87
+ `CREATEROLE` alone can run migrations but cannot create a native backup. A restore target
88
+ uses its superuser session to validate a suspended restored schema-owner shell. The
89
+ migration suite tests both authority forms on PostgreSQL 15 through
90
+ 18. The command does not print the connection URL or apply DDL. `--require-ssl` rejects
91
+ an unencrypted public database connection. Passing the preflight does not replace a
92
+ backup or authorize migration. When a session pooler terminates TLS, the check inspects
93
+ the client socket instead of the pooler's separate database connection.
94
+
95
+ After an operator supplies an existing app, `npm run preflight:fly -- --app <app>
96
+ --json` adds read-only account, app, machine, config, and secret-name observations.
97
+ The command does not deploy, migrate, scale, restart, or print environment-variable
98
+ values. The [Fly production procedure](docs/deployment.md#flyio-reference-hosting)
99
+ keeps database migration and runtime-role bootstrap outside the gateway process.
100
+
101
+ The manual `gateway production proof` workflow tests an existing gateway after its
102
+ deployment gate has passed. GitHub must run it from `main` in the protected
103
+ `agent-bridge-production-proof` environment. Separate sender and receiver jobs prove
104
+ offline outbox replay, exact idempotency, claim, and acknowledgment. The workflow then
105
+ restarts the single Fly machine, requires a new runtime instance ID, and verifies the
106
+ message and settled delivery with a fresh receiver instance and a new SQLite edge file.
107
+ Its versioned receipts contain only identifiers, times, principal and workspace labels,
108
+ the gateway origin, checks, and SHA-256 host evidence. They omit credentials, database
109
+ URLs, message content, and SQLite files.
110
+
66
111
  ## What v2 provides
67
112
 
68
113
  - Immutable messages with UUIDv7 IDs and opaque server cursors.
@@ -364,10 +409,15 @@ PostgreSQL restore executes SQL from the dump, so use `--accept-source-sql-risk`
364
409
  for a bundle from a source you trust. The target must be a dedicated fresh database
365
410
  with the same database name and PostgreSQL major as the backup. Restore requires a
366
411
  superuser because it recreates object owners, role shells, memberships, and default
367
- privileges. It never enables login on restored external principals. If a restore fails
368
- after mutation begins, Agent Bridge disables new target connections and reports any
369
- residual roles or recovery paths. Inspect and clean those artifacts before retrying.
370
- Never run the source and restored target as active authorities at the same time.
412
+ privileges. It never enables login on restored external principals. Runtime principals
413
+ lose their runtime membership. Active control and archive registrations receive a new
414
+ revocation event, and their principals lose those memberships. Re-enable a principal
415
+ and register it again only after inspecting the restored target. A restore may reuse a
416
+ preexisting role only when it is the source schema owner, the target session user, and
417
+ a true superuser. Every other role collision fails. If a restore fails after mutation
418
+ begins, Agent Bridge disables new target connections and reports any residual roles or
419
+ recovery paths. Inspect and clean those artifacts before retrying. Never run the source
420
+ and restored target as active authorities at the same time.
371
421
 
372
422
  Backup publication never replaces an existing output. Deterministic adjacent staging
373
423
  paths use the backup or request UUID. A retry with the same UUID reports retained
@@ -785,9 +835,18 @@ followed by capability locks in operator-before-auditor order. Registration and
785
835
  revocation use the same order. A stale session that remains in a revoked role cannot
786
836
  continue operating. The schema owner is the only bootstrap holder of all three control
787
837
  roles and the only role with ordinary execution authority on the registration
788
- functions. PostgreSQL superusers remain inside this trusted database-administration
789
- boundary. Readiness checks the running PostgreSQL major on every call, so upgrading an
790
- already-migrated database to an uncertified major disables the runtime.
838
+ functions. PostgreSQL 16 and newer may represent its effective admin, inherit, and set
839
+ authority with a bootstrap administrator row plus a schema-owner row. A native DR
840
+ restore may recreate the same authority as one combined bootstrap-superuser grant.
841
+ Readiness validates either physical form and its effective authority. True superusers
842
+ and managed-provider schema owners remain inside this trusted database-administration
843
+ boundary. A separate `NOLOGIN` backup-reader role grants only table and sequence read
844
+ access to the schema owner. Runtime, control, archive, and external principals cannot
845
+ inherit it. Native backups require the schema owner to be a true superuser or hold
846
+ `BYPASSRLS`. A target restore superuser can validate the intentionally suspended
847
+ schema-owner shell. `CREATEROLE` alone remains sufficient for migrations. Readiness checks the
848
+ running PostgreSQL major on every call, so upgrading an already-migrated database to an
849
+ uncertified major disables the runtime.
791
850
 
792
851
  Direct credential inserts default to empty scopes rather than full access. Issued
793
852
  identity, scope, label, expiry, and lineage fields cannot be edited directly. Existing
@@ -858,6 +917,7 @@ agent-bridge get --since 24h --unacked-by codex
858
917
  agent-bridge history --thread-id release-1
859
918
  agent-bridge acknowledge --ids <message-uuid>
860
919
  agent-bridge claim --lease-ms 30000
920
+ agent-bridge claim --message-id <message-uuid> --lease-ms 30000
861
921
  agent-bridge send --target worker --delivery-policy '{"mode":"leased","maxAttempts":3,"retryBaseDelayMs":1000,"retryMaxDelayMs":60000,"retryJitterRatio":0.2}' "work"
862
922
  agent-bridge deliveries --state dead
863
923
  agent-bridge delivery-events --delivery-id <uuid>
@@ -882,6 +942,12 @@ History defaults to mailbox `inbox`: broadcasts plus messages targeted to the co
882
942
 
883
943
  Publishers set `deliveryPolicy` on the message. Leased policy uses `maxAttempts`, `retryBaseDelayMs`, `retryMaxDelayMs`, `retryJitterRatio`, and optional `notBefore`. Consumers cannot override those values. Consumer-side `maxAttempts` on claim and `retryPolicy` on nack remain validated but ignored for one compatibility release. New code should omit both fields.
884
944
 
945
+ Claims normally select the next due delivery by priority. HTTP 2.1, MCP, and CLI
946
+ callers may supply `messageId` or `--message-id` to atomically select only that due,
947
+ recipient-visible delivery. The filter also scopes lease-expiry and exhaustion
948
+ maintenance performed by that claim. Released HTTP 2.0 request shapes remain frozen
949
+ and reject the field.
950
+
885
951
  The legacy Supabase adapter applies mailbox and receipt rules cooperatively. A holder of the legacy publishable key can bypass the adapter through PostgREST or its receipt RPC. Use the authenticated v2 gateway when the authorization boundary must be enforced.
886
952
 
887
953
  `agent-bridge pending` is a cheap shell gate for agent startup. It exits 0 when unread candidates or due delivery work are visible, 1 only for an authoritative empty result, and 2 when an empty remote state cannot be confirmed. Its JSON result separates unread context from executable delivery work and labels the state as `available`, `empty`, or `unknown`.
package/ROADMAP.md CHANGED
@@ -88,6 +88,32 @@ The published npm version is the authority for whether this package line has shi
88
88
  - A production deployment guide covering TLS, network exposure, secret separation,
89
89
  backups, upgrade order, and schema rollback limits.
90
90
 
91
+ ### 0.5.0 package contents
92
+
93
+ - Read-only PostgreSQL and Fly production preflights. The database preflight reports
94
+ migration authority separately from native DR authority. The Fly preflight checks
95
+ the maintained deployment contract and existing app state without exposing secret
96
+ values.
97
+ - A maintained Fly.io reference config. The repository contract keeps schema-owner
98
+ and operator authority out of the gateway, but creating an app, provisioning
99
+ PostgreSQL, setting secrets, migrating, and deploying still require an operator
100
+ gate.
101
+ - A manual, approval-protected production proof harness for an existing Fly gateway.
102
+ It separates sender, receiver, machine restart, and fresh-edge verification,
103
+ and publishes versioned receipts that exclude credentials and message content.
104
+ - Managed PostgreSQL schema-owner and native-backup compatibility across PostgreSQL 15
105
+ through 18. Migrations accept either a true superuser or a non-superuser with the
106
+ required role-administration authority. Native DR separately requires the schema
107
+ owner to be a true superuser or hold `BYPASSRLS`. A restore target superuser can
108
+ validate the intentionally suspended restored schema-owner shell. PostgreSQL 16 and
109
+ newer split grants are normalized to one effective membership for readiness and native DR. A
110
+ dedicated read-only role lets the schema owner back up protected tables without
111
+ granting that access to the gateway or control principals. Exact released migration
112
+ checksums remain accepted during upgrade, while unrelated checksum drift still fails
113
+ closed.
114
+ - Optional exact-message delivery claims in HTTP 2.1, MCP, and the CLI. HTTP 2.0 keeps
115
+ the released claim-next contract.
116
+
91
117
  ### Post-release validation and adoption
92
118
 
93
119
  - Move the project's own normal traffic to the authenticated gateway while retaining a
@@ -97,6 +123,9 @@ The published npm version is the authority for whether this package line has shi
97
123
  check covered startup, private mailbox sends, caller-scoped history, receipts, and
98
124
  client restart through the legacy compatibility backend. It did not prove
99
125
  gateway-only behavior.
126
+ - Run the manual Fly proof against an operator-owned app and retain its sender,
127
+ receiver, machine-cycle, and verifier receipts. The repository harness is ready,
128
+ but the external proof remains incomplete until an approved workflow run succeeds.
100
129
  - Replace remaining direct legacy table pollers with the v2 cursor protocol.
101
130
  - Confirm the README, npm metadata, GitHub metadata, release notes, and package contents
102
131
  match the released artifact.
package/SECURITY.md CHANGED
@@ -74,6 +74,29 @@ Keep the schema-owner, runtime, operator, archive, backup, and restore database
74
74
  authorities separate. Do not copy one client's token or backend file into another
75
75
  client's configuration.
76
76
 
77
+ Managed PostgreSQL may expose a schema-owner administrator with `CREATEROLE` instead
78
+ of true superuser authority. That capability is sufficient for migrations. Native backup
79
+ requires the schema owner to be a true superuser or hold `BYPASSRLS`, because the source
80
+ backup must read tables protected by RLS. A restore target validates a suspended restored
81
+ schema-owner shell through its own superuser session. Agent Bridge creates internal roles with safe
82
+ defaults and fails if an existing role has elevated attributes. PostgreSQL 16 and newer
83
+ may split the schema owner's admin, inherit, and set authority across two catalog rows.
84
+ Native DR may restore the same authority as one combined bootstrap-superuser row.
85
+ Security readiness accepts only those documented grant shapes, then checks their
86
+ effective authority. Registered runtime, control, and archive logins do not receive
87
+ that exception.
88
+
89
+ The database-derived backup-reader role is `NOLOGIN` and has read-only access to Agent
90
+ Bridge tables and sequences. Only the schema owner may inherit it. The runtime role,
91
+ control and archive roles, and external principals must not hold it. Native-backup
92
+ readiness fails on a missing object grant, an added privilege, an unexpected member, or
93
+ a source schema owner without true-superuser or `BYPASSRLS` authority. A restricted
94
+ runtime login cannot validate a suspended restored schema owner.
95
+
96
+ PostgreSQL native restore does not reactivate external identities. Runtime memberships
97
+ are omitted. Active control and archive memberships are replaced by explicit revocation
98
+ events after the restored history. Re-enrollment requires a separate operator action.
99
+
77
100
  Run migrations as a one-shot schema-owner job before starting a new gateway image.
78
101
  Take and verify a native DR backup first. Gateway readiness checks the exact migration
79
102
  plan and protected catalog state. Once a migration changes the database, starting an
package/SKILL.md CHANGED
@@ -39,7 +39,11 @@ Use v2 delivery tools for executable work. MCP `ack_context` and CLI `acknowledg
39
39
 
40
40
  Publish executable work with `deliveryPolicy`; consumers never select retry limits or backoff. Leased policy accepts `maxAttempts`, `retryBaseDelayMs`, `retryMaxDelayMs`, `retryJitterRatio`, and optional `notBefore`. Untargeted messages default to mailbox mode and targeted messages to leased mode. Only publishers cancel or requeue. Publishers and recipients can inspect delivery history. Requeue starts a new cycle without resetting lifetime attempts. Consumer `maxAttempts` on claim and `retryPolicy` on nack are validated but ignored for one compatibility release. External task completion stays outside Agent Bridge.
41
41
 
42
- Claim a delivery before acting. Renew a long lease only to retain ownership. A lease extension does not report progress or success. Record external task completion through the application or A2A protocol, then settle the Agent Bridge delivery separately.
42
+ Claim a delivery before acting. Use `messageId` or CLI `--message-id` when the caller
43
+ must atomically claim one known message instead of the next due item. Renew a long
44
+ lease only to retain ownership. A lease extension does not report progress or success.
45
+ Record external task completion through the application or A2A protocol, then settle
46
+ the Agent Bridge delivery separately.
43
47
 
44
48
  Use `agent-bridge pending` as a cheap process gate before starting an agent. Exit 0 means unread candidates or due delivery work are visible. Exit 1 means the authoritative state is empty. Exit 2 means the remote state is unknown. During a gateway outage, cached unacknowledged results are degraded candidates with unknown acknowledgement state.
45
49
 
package/dist/archive.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { J as JsonValue, i as MessagePriority, f as DeliveryPolicy } from './bridge-domain-CBX3IVqC.js';
2
- import { P as PgQueryable } from './postgres-bridge-store-WASumj26.js';
3
- import './bridge-store-Boaj-ZbO.js';
2
+ import { P as PgQueryable } from './postgres-bridge-store-C9KG9Z69.js';
3
+ import './bridge-store-ByJ6CaJk.js';
4
4
 
5
5
  interface PortableArchiveMessage {
6
6
  id: string;
@@ -1,4 +1,4 @@
1
- import { a as BridgeStore, I as InsertMessageResult, d as MessageQuery, M as MessagePage, c as DeliveryQuery, b as DeliveryPage, D as DeliveryEventPage } from './bridge-store-Boaj-ZbO.js';
1
+ import { a as BridgeStore, I as InsertMessageResult, d as MessageQuery, M as MessagePage, c as DeliveryQuery, b as DeliveryPage, D as DeliveryEventPage } from './bridge-store-ByJ6CaJk.js';
2
2
  import { c as BridgePrincipal, M as MessageDraft, B as BridgeDelivery, A as AgentPresence } from './bridge-domain-CBX3IVqC.js';
3
3
 
4
4
  type PublicMessageQuery = MessageQuery & {
@@ -12,6 +12,7 @@ declare class BridgeService {
12
12
  acknowledge(principalInput: BridgePrincipal, messageIds: string[]): Promise<number>;
13
13
  claim(principalInput: BridgePrincipal, options?: {
14
14
  leaseMs?: number;
15
+ messageId?: string;
15
16
  maxAttempts?: number;
16
17
  }): Promise<{
17
18
  delivery: BridgeDelivery;
@@ -44,6 +44,7 @@ interface BridgeDiagnostics {
44
44
  }
45
45
  interface ClaimOptions {
46
46
  leaseMs: number;
47
+ messageId?: string;
47
48
  now?: Date;
48
49
  maxAttempts?: number;
49
50
  }
package/dist/bridge.d.ts CHANGED
@@ -1,12 +1,12 @@
1
1
  import { b as BridgeMessage, c as BridgePrincipal, B as BridgeDelivery, R as RetryPolicy, A as AgentPresence } from './bridge-domain-CBX3IVqC.js';
2
2
  export { a as BridgeDeliveryEvent, d as BridgePrincipalMismatchError, e as BridgeValidationError, D as DeliveryAction, f as DeliveryPolicy, g as DeliveryState, h as DeliveryStateConflictError, J as JsonValue, L as LeasedDeliveryPolicy, M as MessageDraft, i as MessagePriority, j as cursorScope, k as decodeCursor, l as decodeScopedCursor, m as encodeCursor, n as encodeScopedCursor, s as scopedCursorScope, u as uuidv7, v as validateDeliveryCursorPosition, o as validateDeliveryPolicy, p as validateEventCursorPosition, q as validateLeasedDeliveryPolicy, r as validateMessageDraft, t as validatePrincipal, w as validateProject, x as validateUuid } from './bridge-domain-CBX3IVqC.js';
3
- import { a as BridgeStore, I as InsertMessageResult, d as MessageQuery, M as MessagePage, C as ClaimOptions, B as BridgeDiagnostics, c as DeliveryQuery } from './bridge-store-Boaj-ZbO.js';
4
- export { D as DeliveryEventPage, b as DeliveryPage } from './bridge-store-Boaj-ZbO.js';
5
- export { B as BridgeService, P as PublicMessageQuery } from './bridge-service-YTjGr91A.js';
6
- import { P as PgQueryable } from './postgres-bridge-store-WASumj26.js';
7
- export { a as PgTransactionClient, b as PostgresBridgeStore } from './postgres-bridge-store-WASumj26.js';
8
- export { A as AuthenticatedCredential, C as CredentialResolver, G as GatewayOptions, P as PostgresCredentialResolver, b as bearerToken, c as createGateway, h as hashCredential, s as safeTokenHashEqual } from './gateway-BQHpV-MZ.js';
9
- export { E as EdgeConflictError, a as EdgeDrainLease, b as EdgeEnqueueResult, c as EdgeMigrationDrainingError, d as EdgeMigrationGate, e as EdgeMigrationGateState, f as EdgeMigrationLeaseError, g as EdgeMigrationRetiredError, h as EdgeOutboxRecord, i as EdgeReadOnlyInspection, j as EdgeScope, k as EdgeStats, P as PendingMessage, S as SQLiteEdgeStore, l as edgeMessageFingerprint, m as edgeScopeKey, n as inspectEdgeScopeReadOnly, s as stableIdempotency } from './sqlite-edge-store-Bc15DvpX.js';
3
+ import { a as BridgeStore, I as InsertMessageResult, d as MessageQuery, M as MessagePage, C as ClaimOptions, B as BridgeDiagnostics, c as DeliveryQuery } from './bridge-store-ByJ6CaJk.js';
4
+ export { D as DeliveryEventPage, b as DeliveryPage } from './bridge-store-ByJ6CaJk.js';
5
+ export { B as BridgeService, P as PublicMessageQuery } from './bridge-service-CNBKdYXh.js';
6
+ import { P as PgQueryable } from './postgres-bridge-store-C9KG9Z69.js';
7
+ export { a as PgTransactionClient, b as PostgresBridgeStore } from './postgres-bridge-store-C9KG9Z69.js';
8
+ export { A as AuthenticatedCredential, C as CredentialResolver, G as GatewayOptions, P as PostgresCredentialResolver, b as bearerToken, c as createGateway, h as hashCredential, s as safeTokenHashEqual } from './gateway-CW-61lvs.js';
9
+ export { E as EdgeConflictError, a as EdgeDrainLease, b as EdgeEnqueueResult, c as EdgeMigrationDrainingError, d as EdgeMigrationGate, e as EdgeMigrationGateState, f as EdgeMigrationLeaseError, g as EdgeMigrationRetiredError, h as EdgeOutboxRecord, i as EdgeReadOnlyInspection, j as EdgeScope, k as EdgeStats, P as PendingMessage, S as SQLiteEdgeStore, l as edgeMessageFingerprint, m as edgeScopeKey, n as inspectEdgeScopeReadOnly, s as stableIdempotency } from './sqlite-edge-store-CdMIOrho.js';
10
10
  export { CachedMessagePage, SQLiteBridgeStore, SyncDiagnostics, SyncInsertResult, SyncReport, SyncingBridgeStore, SyncingBridgeStoreOptions, isRetryableSyncError } from './sqlite.js';
11
11
  import 'node:http';
12
12
 
@@ -102,6 +102,7 @@ interface AppliedMigration {
102
102
  interface MigrationPlanEntry extends AppliedMigration {
103
103
  source: string;
104
104
  }
105
+ declare function migrationRecordMatches(recorded: Pick<AppliedMigration, "version" | "name" | "checksum">, required: Pick<AppliedMigration, "version" | "name" | "checksum">): boolean;
105
106
  declare const REQUIRED_MIGRATIONS: readonly [{
106
107
  readonly version: 1;
107
108
  readonly name: "schema_state";
@@ -159,6 +160,12 @@ declare const REQUIRED_MIGRATIONS: readonly [{
159
160
  }, {
160
161
  readonly version: 19;
161
162
  readonly name: "endpoint_migration_same_successor";
163
+ }, {
164
+ readonly version: 20;
165
+ readonly name: "managed_authority_compat";
166
+ }, {
167
+ readonly version: 21;
168
+ readonly name: "native_backup_reader";
162
169
  }];
163
170
  declare function loadMigrationPlan(directory: string): Promise<MigrationPlanEntry[]>;
164
171
  declare function migrationsReady(db: PgQueryable, expected: ReadonlyArray<Pick<MigrationPlanEntry, "version" | "name" | "checksum">>): Promise<boolean>;
@@ -168,4 +175,4 @@ declare function runtimeSchemaReady(db: PgQueryable, options?: {
168
175
  }): Promise<boolean>;
169
176
  declare function runMigrations(db: PgQueryable, directory: string): Promise<AppliedMigration[]>;
170
177
 
171
- export { AgentPresence, type AppliedMigration, BridgeDelivery, BridgeDiagnostics, BridgeHttpError, BridgeMessage, BridgePrincipal, BridgeStore, ClaimOptions, DeliveryQuery, HttpBridgeStore, type HttpBridgeStoreOptions, InsertMessageResult, LegacySupabaseError, LegacySupabaseRestStore, MessagePage, MessageQuery, type MigrationPlanEntry, NATIVE_DR_ADVISORY_LOCK_KEY, PgQueryable, REQUIRED_MIGRATIONS, RetryPolicy, loadMigrationPlan, migrationsReady, rowIsolationReady, runMigrations, runtimeSchemaReady };
178
+ export { AgentPresence, type AppliedMigration, BridgeDelivery, BridgeDiagnostics, BridgeHttpError, BridgeMessage, BridgePrincipal, BridgeStore, ClaimOptions, DeliveryQuery, HttpBridgeStore, type HttpBridgeStoreOptions, InsertMessageResult, LegacySupabaseError, LegacySupabaseRestStore, MessagePage, MessageQuery, type MigrationPlanEntry, NATIVE_DR_ADVISORY_LOCK_KEY, PgQueryable, REQUIRED_MIGRATIONS, RetryPolicy, loadMigrationPlan, migrationRecordMatches, migrationsReady, rowIsolationReady, runMigrations, runtimeSchemaReady };
package/dist/bridge.js CHANGED
@@ -4,7 +4,7 @@ import {
4
4
  HttpBridgeStore,
5
5
  LegacySupabaseError,
6
6
  LegacySupabaseRestStore
7
- } from "./chunk-LAHNQZDN.js";
7
+ } from "./chunk-Z6JP6MYD.js";
8
8
  import {
9
9
  EdgeConflictError,
10
10
  EdgeMigrationDrainingError,
@@ -17,23 +17,24 @@ import {
17
17
  inspectEdgeScopeReadOnly,
18
18
  isRetryableSyncError,
19
19
  stableIdempotency
20
- } from "./chunk-SV3SVBYS.js";
20
+ } from "./chunk-SN7PIVDF.js";
21
21
  import {
22
22
  SQLiteBridgeStore
23
- } from "./chunk-DQOZJJZ2.js";
23
+ } from "./chunk-IVG4XWWS.js";
24
24
  import "./chunk-GTK4KOED.js";
25
25
  import {
26
26
  PostgresBridgeStore
27
- } from "./chunk-2DFNOLMO.js";
27
+ } from "./chunk-XDNT6ZNZ.js";
28
28
  import {
29
29
  NATIVE_DR_ADVISORY_LOCK_KEY,
30
30
  REQUIRED_MIGRATIONS,
31
31
  loadMigrationPlan,
32
+ migrationRecordMatches,
32
33
  migrationsReady,
33
34
  rowIsolationReady,
34
35
  runMigrations,
35
36
  runtimeSchemaReady
36
- } from "./chunk-6BTJE6D4.js";
37
+ } from "./chunk-QNXHDOJ5.js";
37
38
  import "./chunk-VOQIDTCJ.js";
38
39
  import {
39
40
  PostgresCredentialResolver,
@@ -41,11 +42,11 @@ import {
41
42
  createGateway,
42
43
  hashCredential,
43
44
  safeTokenHashEqual
44
- } from "./chunk-3YHVUPU2.js";
45
+ } from "./chunk-P635FAN4.js";
45
46
  import {
46
47
  BridgeService
47
- } from "./chunk-4VB44KJU.js";
48
- import "./chunk-IHZFI7TH.js";
48
+ } from "./chunk-AWE3DFZV.js";
49
+ import "./chunk-E4OWHGUE.js";
49
50
  import {
50
51
  BridgePrincipalMismatchError,
51
52
  BridgeValidationError,
@@ -99,6 +100,7 @@ export {
99
100
  inspectEdgeScopeReadOnly,
100
101
  isRetryableSyncError,
101
102
  loadMigrationPlan,
103
+ migrationRecordMatches,
102
104
  migrationsReady,
103
105
  rowIsolationReady,
104
106
  runMigrations,