@nullsquare/agent-authority 0.4.4 → 0.4.5

package/README.md

@@ -8,9 +8,9 @@
 
 **Agent Authority turns a human-approved task into temporary execution authority, then keeps that authority bounded as the agent discovers resources, crosses tools, and performs side effects.**
 
-[Task Leases](docs/task-leases.md) · [Executable evidence](docs/evidence.md) · [Extractor conformance](docs/authority-extractor-conformance.md) · [Google proof](docs/live-google-validation.md) · [Integration contract](docs/integration-contract.md) · [CLI](docs/cli.md) · [Architecture](docs/architecture.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md)
+[Task Leases](docs/task-leases.md) · [Executable evidence](docs/evidence.md) · [Extractor conformance](docs/authority-extractor-conformance.md) · [Transport invariance](docs/transport-invariance.md) · [Google proof](docs/live-google-validation.md) · [Integration contract](docs/integration-contract.md) · [CLI](docs/cli.md) · [Architecture](docs/architecture.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md)
 
-> **Status: public pre-alpha / v0.4.3 Developer Preview.** Published on npm as `@nullsquare/agent-authority`. The repository has a working policy runtime, protocol-neutral guard, Task Lease prototype, execution-bound derived facts, reviewed Google and GitHub authority extractors, two-provider conformance tests, approvals, revocation, idempotency, credential isolation, MCP v2 gateway, live GitHub proofs, CI and CodeQL. It is not production-ready yet.
+> **Status: public pre-alpha / v0.4.4 Developer Preview.** Published on npm as `@nullsquare/agent-authority`. The repository has a working policy runtime, protocol-neutral guard, Task Lease prototype, execution-bound derived facts, reviewed Google and GitHub authority extractors, two-provider conformance tests, Task-Lease-aware SDK/MCP/broker execution, a real Vercel AI SDK harness proof, approvals, revocation, idempotency, credential isolation, live GitHub proofs, CI and CodeQL. It is not production-ready yet.
 
 </div>
 
@@ -160,7 +160,9 @@ The side-effect callbacks for blocked actions never run.
 
 The repository also includes a real Gmail → Calendar validation path and a reusable Google provider adapter. The strict path binds the derived sender to the exact guarded output before it becomes authority. See [Live Gmail → Calendar validation](docs/live-google-validation.md) and [Executable Evidence](docs/evidence.md).
 
-v0.4.3 applies the **same primitive to GitHub**: a root-bound repository + fixture marker are used by the reviewed GitHub adapter to select one issue from a real `issue.list` response; `deriveFromEvidence()` establishes that exact issue number as downstream authority; one real comment mutation succeeds; unrelated and post-completion issue mutations never reach the provider. Google and GitHub are now exercised by the same [authority extractor conformance contract](docs/authority-extractor-conformance.md).
+v0.4.3 applied the **same evidence-derived authority primitive to GitHub**: a root-bound repository + fixture marker are used by the reviewed GitHub adapter to select one issue from a real `issue.list` response; `deriveFromEvidence()` establishes that exact issue number as downstream authority; one real comment mutation succeeds; unrelated and post-completion issue mutations never reach the provider. Google and GitHub are exercised by the same [authority extractor conformance contract](docs/authority-extractor-conformance.md).
+
+v0.4.4 adds the **transport-invariance proof**: one `execution-evidence-v1` derived fact is established under one Task Lease, then that exact lease and fact constrain ordinary `guard.run()`, the MCP gateway and brokered provider execution. The same allowed resource succeeds, an unrelated resource produces `authority_delta_required` with zero blocked callbacks/provider calls, and task completion produces `task_lease_completed` across all three paths. The repository also drives a real Vercel AI SDK `ToolLoopAgent` through `protectAiSdkTools()`: unrelated resources, unmapped executable tools and completed leases are surfaced as tool errors while the underlying side-effect counters remain zero. See [Task Lease transport invariance](docs/transport-invariance.md).
 
 ## Minimal developer API
 
@@ -230,7 +232,7 @@ Agent Authority is deliberately **not tied to MCP, OAuth, or one agent framework
 agent code -> guard.run() -> existing SDK / API
 ```
 
-Best when the application already owns the provider connection. This is the primary v0.4 adoption path.
+Best when the application already owns the provider connection.
 
 ### 2. MCP gateway
 
@@ -248,7 +250,7 @@ agent -> Agent Authority -> isolated credential -> provider
 
 Best when the agent should not receive the provider credential at all.
 
-The long-term validation target is the **same Task Lease and authority lineage across all three paths**.
+v0.4.4 demonstrates the **same Task Lease and authority fact across all three paths in-process**, plus the configured Vercel AI SDK `ToolLoopAgent` protected-tool path. M4 is complete at this execution-boundary level. A malicious host that deliberately exposes a separate unguarded tool or credential remains outside Agent Authority's security boundary.
 
 ## What is implemented
 
@@ -280,6 +282,12 @@ The long-term validation target is the **same Task Lease and authority lineage a
 - protocol-neutral `guard.run()` wrapper
 - blocked side effects never invoke their callback
 - successful guarded effects return separate execution evidence
+- Task-Lease-aware MCP gateway/proxy evaluation
+- Task-Lease-aware brokered execution via `ExecutingAuthorityRuntime.executeTaskLease()`
+- brokered execution evidence bound to Task-Lease receipts
+- SDK/MCP/broker transport-invariance conformance test
+- real Vercel AI SDK `ToolLoopAgent` protected-tool harness proof
+- unmapped executable AI SDK tools fail closed before their effect executes
 - one-time human approvals bound to exact request
 - mutation idempotency
 - conservative uncertain-state handling
@@ -302,6 +310,8 @@ The long-term validation target is the **same Task Lease and authority lineage a
 - adversarial authorization tests
 - execution-evidence substitution, tampering, replay, cross-lease and selector tests
 - the same provider-derived-authority conformance attacks against Google and GitHub
+- cross-transport invariance test for direct SDK, MCP and brokered execution
+- real AI SDK agent-loop tests for unauthorized, unmapped and completed-lease tool calls with zero underlying effects
 - Node 20 and Node 22 CI
 - coverage run
 - package checks
@@ -377,6 +387,7 @@ See [SECURITY.md](SECURITY.md).
 This is still a validation implementation.
 
 - Task Lease state is currently process-local.
+- Transport and harness proofs cover configured Agent Authority execution boundaries, not a malicious host that exposes a separate unguarded tool, credential, shell or network path.
 - `deriveFromEvidence()` proves consistency with the exact output returned through the trusted Agent Authority guard, but the output is not cryptographically attested by Gmail, GitHub, or another remote provider.
 - The legacy `derive()` API remains host-trusted for compatibility; audit provenance distinguishes it from `execution-evidence-v1` derivation.
 - Source-data changes do not yet automatically invalidate already-derived authority facts.

package/ROADMAP.md

@@ -64,18 +64,33 @@ never silently grow
 
 The core cross-provider behavior is now implemented and exercised against connected Gmail and Calendar accounts. Public Actions reproducibility remains the final M1 evidence gate because GitHub cannot reuse an interactive ChatGPT connector credential; the manual workflow is committed and expects a refresh token stored only as repository secrets.
 
-## M2 — Durable task execution
+## M2 — Durable task execution — durable session established
 
-Build only what the real M1 workflow proves necessary.
+Build only what the real Task Lease workflows prove necessary.
 
-- [ ] durable Task Lease persistence/recovery
-- [ ] atomic fact/binding updates
+- [x] authenticated local Task Lease persistence/recovery
+- [x] atomic authenticated fact/binding/status transaction primitive
+- [x] stale-writer compare-and-swap protection for independent recovered worker views
+- [x] local per-lease transaction lock that fails closed on overlap
+- [x] ordinary running Task Lease mutations can use the durable transaction boundary through `DurableTaskLeaseSession`
+- [x] security-critical session evaluation refreshes current durable state before the next authority decision
 - [ ] approved authority delta can safely attenuate/update a live lease
-- [ ] completion state survives process restart
+- [x] completion state survives process restart
 - [ ] durable lineage query: why was this exact action authorized?
-- [ ] concurrency tests for multiple agent workers operating under one lease
+- [ ] multi-process stress/recovery tests for multiple agent workers operating under one lease
+- [ ] crash-safe coupling between remote provider side effects, receipts and durable Task Lease state
 
-**Success criterion:** a Task Lease survives daemon/process restarts without gaining authority or losing its provenance lineage.
+`JsonFileTaskLeaseStore` writes the complete lease snapshot atomically and authenticates it with a purpose-derived HMAC key from the local Agent Authority master key. Recovery verifies the envelope before authority hydration, binds the snapshot to the exact mission hash, validates status/timestamps and the authority-fact DAG, restores evidence-derived provenance hashes, and verifies the reconstructed Task Lease hash.
+
+`JsonFileTaskLeaseStore.transact()` is the local durable mutation boundary: acquire one per-lease filesystem lock, reload authenticated current state, compare an optional expected lease hash, apply one synchronous Task Lease mutation, validate the complete authority graph, and atomically replace the authenticated snapshot. Stale writers receive `task_lease_state_conflict`; overlapping local transactions receive `task_lease_state_locked`.
+
+`DurableTaskLeaseSession` is the normal mutation facade over that primitive. `addRoot()`, legacy `derive()`, strict `deriveFromEvidence()`, `bind()` and `complete()` commit through compare-and-swap and update the session only after durable success. The session exposes detached mission/snapshot/fact views rather than its mutable internal Task Lease. It never auto-replays a stale semantic mutation after a conflict.
+
+The session also implements the Task Lease `evaluate(runtime, request)` shape used by guard/MCP/broker paths. Evaluation refreshes authenticated durable state first, so another worker's already-committed completion or narrowing is observed before the next decision. Tests also prove that execution evidence captured at H0 cannot be automatically converted into a derived fact after another worker commits H1; derivation fails on CAS and requires explicit reconsideration.
+
+This does **not** yet turn a remote provider side effect and a local Task Lease transition into one distributed transaction. A different worker can still change durable state after an ALLOW decision and before an asynchronous provider effect begins. That TOCTOU/effect-coupling problem remains explicit follow-on M2 work rather than being hidden behind the local filesystem lock. See `docs/durable-task-leases.md`.
+
+**Success criterion:** a Task Lease survives restart without gaining authority or losing provenance, cooperating local workers cannot silently overwrite newer authority, and ordinary durable mutations use the CAS boundary by default through the session API. Authenticated recovery, local transactions and the durable session are now demonstrated; approved deltas, stronger multi-process stress and remote-effect coupling remain open.
 
 ## M3 — Trustworthy derived facts — two-provider proof established
 
@@ -97,21 +112,25 @@ Do **not** build a general semantic policy language unless real integrations req
 
 **Success criterion:** provider-derived authority cannot be established through the strict path unless the exact guarded output, ALLOW receipt and reviewed extractor contract agree on the selected value. This behavior is now exercised across two provider mappings. Stronger provider attestation and source invalidation remain separate follow-on problems.
 
-## M4 — Same task, multiple transports — first proof established
+## M4 — Same task, multiple transports — complete
 
 Prove Agent Authority is not an MCP product or SDK wrapper.
 
 - [x] same Task Lease through ordinary `guard.run()` SDK call
 - [x] same Task Lease through MCP gateway
 - [x] same Task Lease through brokered provider execution
-- [ ] at least one non-bypassable harness/tool-middleware integration
+- [x] at least one harness/tool-middleware integration whose configured executable tool path cannot bypass the Task Lease
 - [x] interoperability test vectors across transports
 
 `test/transport-invariance.test.js` establishes one `execution-evidence-v1` derived fact from brokered execution, then reuses that exact Task Lease and fact through direct SDK, MCP and brokered execution. The three paths produce the same `allow`, `authority_delta_required` and `task_lease_completed` outcomes, and blocked attempts execute zero host callbacks, MCP upstream calls or brokered provider operations.
 
+`test/integrations/ai-sdk.integration.mjs` drives the real Vercel AI SDK `ToolLoopAgent` through the protected tool set. An authorized task-bound tool executes once; an unrelated resource, an executable tool with no Agent Authority mapping, and a completed Task Lease are surfaced by the harness as `tool-error` results while the underlying side-effect counters remain zero. This proves the configured AI SDK tool execution path cannot silently bypass the Task Lease.
+
+The harness claim is intentionally bounded: a malicious host that deliberately gives the model a separate unguarded executable channel remains outside Agent Authority's enforcement boundary.
+
 Brokered Task Lease execution deliberately does not consume mission-level one-time approval to override a lease-level authority delta. Updating a live Task Lease after explicit approval remains separate M2 work.
 
-**Success criterion:** changing transport or harness does not expand the task's authority. The SDK/MCP/broker portion is now demonstrated in-process; an external non-bypassable harness/tool-middleware integration remains the final M4 proof.
+**Success criterion:** changing transport or the configured harness execution path does not expand the task's authority. This is now demonstrated across direct SDK, MCP, brokered execution and the Vercel AI SDK `ToolLoopAgent` protected-tool path.
 
 ## M5 — Production credential and approval UX
 
@@ -161,4 +180,4 @@ Only after operational evidence.
 2. How should an approved authority delta update a running task without opening a broader wildcard permission?
 3. How should source-data changes invalidate downstream derived authority?
 4. What provider/tool metadata is required to map operations to resource context reliably?
-5. Can the same non-amplification conformance suite work across SDK, MCP, CLI and brokered execution?
+5. How should a local ALLOW decision be coupled to an asynchronous remote effect without holding a filesystem lease lock across network I/O?

package/docs/durable-task-leases.md

@@ -0,0 +1,336 @@
+# Durable Task Leases
+
+Agent Authority v0.4.x originally kept Task Lease state only in process memory. That was useful for proving task-bounded authority, but process restart could lose task completion, expiry state, bindings and provenance lineage.
+
+M2 now has three local-host durability layers:
+
+1. authenticated recovery of Task Lease authority state;
+2. transactional mutation with local serialization and stale-writer compare-and-swap protection;
+3. `DurableTaskLeaseSession`, which routes normal Task Lease mutations through that transaction boundary automatically.
+
+The core authority model is unchanged.
+
+## Security goal
+
+Restart or concurrent local workers must never increase authority by reconstructing, overwriting or racing durable state.
+
+```text
+live Task Lease
+      |
+      v
+atomic authenticated snapshot
+      |
+ process restart
+      |
+      v
+authenticate + validate + recover
+      |
+      v
+recovered Task Lease authority
+      <=
+pre-restart Task Lease authority
+```
+
+For updates:
+
+```text
+worker view @ hash H0
+        |
+        v
+acquire per-lease lock
+        |
+reload authenticated current state
+        |
+expected hash == current hash ?
+        |
+      yes
+        v
+apply one synchronous lease mutation
+        |
+validate complete authority snapshot
+        |
+atomic authenticated replacement -> H1
+```
+
+A stale worker that still expects `H0` after another worker committed `H1` receives `task_lease_state_conflict`. It does not overwrite `H1`.
+
+A state file is not authority merely because it contains plausible JSON.
+
+## Snapshot contents
+
+`TaskLease.snapshot()` preserves:
+
+- lease ID;
+- exact mission ID and mission hash;
+- principal and agent IDs;
+- original task request;
+- active/completed status;
+- creation, expiry and completion timestamps;
+- completion reason;
+- exact context bindings;
+- root authority facts;
+- derived facts and parent lineage;
+- strict execution-evidence provenance, including receipt, request, provider-output and evidence hashes.
+
+Snapshots do **not** contain provider credentials.
+
+## Recovery validation
+
+`TaskLease.restore()` / `restoreTaskLease()` validate the recovered state before reconstructing a lease.
+
+Recovery rejects:
+
+- a different mission ID;
+- the same mission ID paired with a different mission definition/hash;
+- a different principal or agent;
+- unsupported snapshot versions;
+- invalid active/completed state;
+- invalid timestamps;
+- duplicate authority fact IDs;
+- missing parent facts;
+- cyclic authority lineage;
+- derived facts claiming another Task Lease ID;
+- derived facts missing receipt/request/selector provenance;
+- `execution-evidence-v1` facts missing extractor/output/evidence hashes.
+
+`restoreTaskLease()` validates state structure and mission identity, but it does not authenticate where arbitrary caller-supplied JSON came from. Durable applications should load persisted authority through an authenticated store.
+
+## Authenticated local store
+
+`JsonFileTaskLeaseStore` is the first reference persistence backend.
+
+```js
+import { JsonFileTaskLeaseStore } from '@nullsquare/agent-authority/storage';
+
+const store = new JsonFileTaskLeaseStore({
+  dir: config.paths.task_leases,
+  keyPath: config.paths.master_key
+});
+
+const created = store.save(lease);
+
+// Later, after process restart:
+const recovered = store.load({
+  mission,
+  lease_id: leaseId
+});
+```
+
+The store snapshots the whole lease, records its hash, authenticates the envelope with HMAC-SHA256 using a purpose-derived local key, atomically writes it, then verifies identity/MAC/mission hash/fact graph/reconstructed lease hash before returning recovered authority.
+
+The default local configuration reserves:
+
+```text
+~/.agent-authority/state/task-leases/
+```
+
+## Save semantics
+
+`save()` is deliberately not last-writer-wins.
+
+For a lease that does not yet exist, `store.save(lease)` creates the authenticated durable state.
+
+For an existing lease:
+
+- saving an unchanged recovered state is idempotent;
+- replacing changed state requires `expected_lease_hash`;
+- attempting to replace changed state without an expected hash fails with `task_lease_state_conflict`.
+
+For normal authority mutations, prefer `transact()` or `DurableTaskLeaseSession` rather than mutating a recovered lease and then saving it.
+
+## Transactional mutation
+
+`store.transact()` is the low-level durable read-modify-write boundary.
+
+```js
+const view = store.load({ mission, lease_id });
+
+const committed = store.transact({
+  mission,
+  lease_id,
+  expected_lease_hash: view.hash(),
+  mutate: (lease) => {
+    lease.addRoot({
+      fact_id: 'fact:region',
+      kind: 'demo.region',
+      value: 'us-east'
+    });
+
+    lease.bind({
+      service: 'demo',
+      action: 'item.access',
+      context_field: 'region',
+      fact_id: 'fact:region'
+    });
+  }
+});
+```
+
+A transaction acquires a per-lease local lock, reloads/authenticates current state, checks the expected hash, applies one synchronous mutation, validates the full authority graph, atomically writes a new authenticated envelope, and returns the previous/new hashes. Throwing or async callbacks do not persist mutated state.
+
+The mutation callback should modify **Task Lease state only**. Provider calls, network requests and other external side effects do not belong inside this synchronous local transaction.
+
+## DurableTaskLeaseSession
+
+Most callers should not manually orchestrate `load()` + `transact()` for ordinary Task Lease changes. `DurableTaskLeaseSession` keeps the current recovered hash and applies normal Task Lease mutations through compare-and-swap automatically.
+
+```js
+import {
+  createDurableTaskLeaseSession,
+  openDurableTaskLeaseSession
+} from '@nullsquare/agent-authority/durable-task-lease';
+import { createTaskLeaseGuard } from '@nullsquare/agent-authority/guard';
+
+const session = createDurableTaskLeaseSession({
+  store,
+  lease
+});
+
+const guard = createTaskLeaseGuard({
+  lease: session,
+  runtime
+});
+
+const read = await guard.run(
+  {
+    service: 'gmail',
+    action: 'thread.read',
+    context: { thread_id: 'thread:demo-91' }
+  },
+  () => gmail.readThread('thread:demo-91')
+);
+
+session.deriveFromEvidence({
+  fact_id: 'fact:sender-email',
+  kind: 'email.address',
+  from: ['fact:thread'],
+  receipt: read.receipt,
+  evidence: read.evidence,
+  output: read.output,
+  extractor: gmailThreadSenderAuthorityExtractor
+});
+```
+
+The session exposes durable equivalents of the ordinary state-changing methods:
+
+- `addRoot()`;
+- legacy `derive()`;
+- `deriveFromEvidence()`;
+- `bind()`;
+- `complete()`.
+
+Each mutation uses the session's current lease hash as `expected_lease_hash`. On success the session adopts the committed lease and new hash. On conflict it does **not** auto-retry or replay the mutation. The caller must `refresh()` and reconsider the intended change against the newer authority state.
+
+The session does not expose its mutable internal `TaskLease`. `mission`, snapshots and facts are returned as detached values so mutating a caller-visible object does not mutate durable authority by reference.
+
+### Guard behavior
+
+`DurableTaskLeaseSession` implements `evaluate(runtime, request)`, so it can be passed anywhere a Task Lease is accepted by the current guard/MCP/broker interfaces.
+
+Security-critical `evaluate()` calls `refresh()` first. That means a stale worker which another worker has already completed or narrowed will observe the durable state before the next authority decision.
+
+Example:
+
+```text
+worker B cached active H0
+worker A complete() -> H1 completed
+worker B guard.run(...)
+    -> session.evaluate()
+    -> refresh H1
+    -> task_lease_completed
+    -> effect callback never runs
+```
+
+### Evidence race behavior
+
+Suppose worker B receives an ALLOW receipt and execution evidence at H0, but worker A changes durable Task Lease state to H1 before B calls `deriveFromEvidence()`.
+
+The session does not silently derive against H1:
+
+```text
+B guarded read @ H0 -> receipt + evidence
+A commits authority state H1
+B deriveFromEvidence(... expected H0 ...)
+    -> task_lease_state_conflict
+    -> no derived fact persisted
+```
+
+B must refresh and explicitly reconsider whether the old provider result still justifies a derived authority fact under H1.
+
+## Local worker concurrency
+
+The local lock prevents two cooperating Agent Authority processes from entering the same per-lease durable mutation window at the same time.
+
+If a worker observes an already-held lock, it fails closed with:
+
+```text
+task_lease_state_locked
+```
+
+The lock is intentionally local-filesystem scoped. A crashed process may leave a lock directory behind; this is an availability failure rather than an authority-expansion failure and should be repaired explicitly rather than silently deleting a lock that might still belong to a live worker.
+
+The expected lease hash adds optimistic stale-view protection:
+
+```text
+worker A loads H0
+worker B loads H0
+worker A transact(H0) -> H1
+worker B transact(H0) -> task_lease_state_conflict
+```
+
+Worker B must reload H1 and reconsider its intended mutation against the new authority state.
+
+## Properties under test
+
+`test/task-lease-persistence.test.js` and `test/durable-task-lease-session.test.js` prove that:
+
+- strict `execution-evidence-v1` facts survive recovery with provenance hashes unchanged;
+- unrelated resources still require step-up after restart;
+- completion and expiry survive restart;
+- disk tampering, changed mission definitions and malformed lineage fail closed;
+- fact+binding changes can commit as one authenticated snapshot;
+- stale worker views cannot overwrite newer authority;
+- raw changed saves cannot bypass compare-and-swap;
+- overlapping local transactions fail closed;
+- throwing or async transactions leave durable state unchanged;
+- a durable session can perform strict evidence derivation and reopen with identical authority behavior;
+- another worker's completion is observed before the stale session's next guarded effect;
+- stale semantic mutations are not automatically replayed;
+- evidence captured at H0 cannot be automatically derived after another worker commits H1;
+- caller-visible mission/snapshot objects do not expose mutable aliases to the session's internal authority state.
+
+## Trust boundary
+
+This persistence mechanism protects authority state on the **trusted local Agent Authority host** against accidental corruption, caller-controlled state-file modification without the authentication key, and stale cooperating local writers.
+
+It is not hostile-host containment. An attacker or malicious host process that can read the Agent Authority master key can authenticate modified local state and remains outside this guarantee.
+
+The HMAC does not make provider output cryptographically attested by the provider. The per-lease lock is local filesystem coordination, not distributed consensus.
+
+## Important remaining TOCTOU boundary
+
+Refreshing before `evaluate()` closes stale-state decisions, but it does **not** make an asynchronous external provider effect and Task Lease state transition one distributed transaction.
+
+There is still a possible sequence:
+
+```text
+worker B refresh/evaluate -> ALLOW
+worker A completes lease
+worker B provider effect begins
+```
+
+The ordinary guard correctly checks authority immediately before invoking its effect callback, but another process can change durable state after that decision. Agent Authority does not yet hold the local lease lock across a network/provider effect, and it should not do so casually.
+
+Crash-safe/provider-side coordination, idempotency and execution receipts need a dedicated design rather than pretending a filesystem transaction covers remote side effects.
+
+## What is not durable yet
+
+Still open:
+
+- crash-safe coupling between provider side effects, execution receipts and Task Lease state changes;
+- durable application of an explicitly approved authority delta;
+- a durable lineage query/index across many leases;
+- stronger multi-process stress tests and recovery tooling for abandoned local locks;
+- remote/KMS-backed persistence and distributed coordination where required.
+
+The next M2 work should tackle approved authority deltas and execution/effect coupling as separate explicit problems rather than broadening the persistence layer into a general database abstraction.

package/docs/npm-release.md

@@ -13,24 +13,26 @@ Before any publication:
 After publication, verify from a fresh project with:
 
 ```bash
-npm install @nullsquare/agent-authority@0.4.3
+npm install @nullsquare/agent-authority@0.4.4
 ```
 
 Then run the same consumer smoke flow through the registry-installed package. Registry verification is part of the release gate; a successful `npm publish` command alone is not sufficient.
 
-The repository also includes `.github/workflows/verify-npm-registry.yml`, which verifies registry visibility and a clean consumer install. For v0.4.3 it additionally verifies the public `@nullsquare/agent-authority/authority-evidence` API plus both reviewed provider authority extractors:
+The repository also includes `.github/workflows/verify-npm-registry.yml`, which verifies registry visibility and a clean consumer install. For v0.4.4 it verifies the public execution-evidence and two-provider authority-extractor APIs plus the Task-Lease-aware transport surfaces:
 
 - `gmailThreadSenderAuthorityExtractor` from `@nullsquare/agent-authority/providers/google`;
-- `githubIssueListSelectedNumberAuthorityExtractor` from `@nullsquare/agent-authority/providers/github`.
+- `githubIssueListSelectedNumberAuthorityExtractor` from `@nullsquare/agent-authority/providers/github`;
+- `ExecutingAuthorityRuntime.executeTaskLease()` from `@nullsquare/agent-authority/execution`;
+- `MissionMcpGateway` from `@nullsquare/agent-authority/mcp-gateway`.
 
-This makes the registry artifact verification cover the same two-provider execution-evidence surface exercised by the repository conformance suite.
+This makes the registry artifact verification cover both the two-provider execution-evidence surface and the SDK/MCP/broker transport-invariance surface exercised by the repository conformance tests.
 
 ## npm vs GitHub release surfaces
 
 Publishing to the public npm registry does not automatically create either a GitHub Release or a GitHub Packages entry.
 
 - **npm registry** — `npm publish --access public` publishes `@nullsquare/agent-authority` to `registry.npmjs.org` / npmjs.com. This is the package users install with `npm install`.
-- **GitHub Releases** — a separate GitHub object, normally backed by a Git tag such as `v0.4.3`. A release must be created explicitly or by release automation.
+- **GitHub Releases** — a separate GitHub object, normally backed by a Git tag such as `v0.4.4`. A release must be created explicitly or by release automation.
 - **GitHub Packages** — a separate package registry. It only appears when the package is published to GitHub's npm registry (`npm.pkg.github.com`); publishing to npmjs.com does not populate it.
 
 Agent Authority currently uses npmjs.com as its public package registry. Therefore an empty GitHub **Packages** section is expected unless the project intentionally adopts dual publication. A GitHub **Release** is still useful for source-release discoverability and should track published versions, but it is independent from npm publication.

package/docs/transport-invariance.md

@@ -19,7 +19,7 @@ same Task Lease + same established authority fact
 
 Changing the transport must not broaden task authority.
 
-## Executable proof
+## Executable transport proof
 
 `test/transport-invariance.test.js` creates one Task Lease and one derived authority fact.
 
@@ -97,21 +97,57 @@ io.nullsquare.agent-authority/task_lease_id
 
 The remote MCP handler and loopback proxy can pass the same Task Lease into the gateway.
 
+## AI SDK harness proof
+
+`test/integrations/ai-sdk.integration.mjs` drives the current Vercel AI SDK `ToolLoopAgent` with the output of `protectAiSdkTools()` as its executable tool set.
+
+The positive path asks the model to use the task-bound GitHub issue. The protected tool executes exactly once.
+
+The same real agent loop then exercises three adversarial paths:
+
+```text
+unrelated issue
+    -> AuthorityApprovalRequiredError
+    -> authority_delta_required
+    -> underlying effect count remains 0
+
+executable tool with no Agent Authority mapping
+    -> UnmappedAiSdkToolError
+    -> ai_sdk_tool_unmapped
+    -> underlying effect count remains 0
+
+completed Task Lease
+    -> AuthorityDeniedError
+    -> task_lease_completed
+    -> underlying effect count remains 0
+```
+
+The AI SDK represents tool execution failures in the generated result as `tool-error` content parts rather than requiring `agent.generate()` itself to reject. The proof therefore checks both sides of the boundary: the harness records the exact Agent Authority error and the protected underlying side effect never runs.
+
+This matters because the model is not calling the wrapped function directly in these cases. The real `ToolLoopAgent` selects and invokes the tool through its normal tool loop, and the Agent Authority wrapper remains the executable boundary.
+
 ## What this proves
 
-- Task-Lease narrowing is no longer specific to the direct SDK guard;
+- Task-Lease narrowing is not specific to the direct SDK guard;
 - MCP cannot silently fall back to Mission-only authority when explicitly configured with a Task Lease;
-- brokered provider execution can enforce the same Task Lease before credential-backed execution;
-- one derived fact can constrain all three execution paths;
-- task completion invalidates the same authority across all three paths;
-- broker credentials may remain connected after task authority disappears.
+- brokered provider execution enforces the same Task Lease before credential-backed execution;
+- one evidence-derived fact can constrain direct SDK, MCP and brokered execution;
+- task completion invalidates the same authority across those execution paths;
+- broker credentials may remain connected after task authority disappears;
+- a configured Vercel AI SDK `ToolLoopAgent` whose executable tool set is passed through `protectAiSdkTools()` cannot use its normal tool path to bypass Task-Lease narrowing;
+- executable AI SDK tools without an Agent Authority request mapping fail closed before their underlying effect executes.
+
+## Boundary of the claim
+
+This is an execution-boundary guarantee, not hostile-host containment.
+
+It does **not** prove that a malicious application host cannot deliberately give the model another unwrapped tool, direct provider credential, shell, network client or other execution channel outside Agent Authority.
 
-## What this does not prove yet
+It also does not yet prove that:
 
-- a hostile harness cannot bypass Agent Authority through an entirely separate unguarded tool path;
 - Task Lease state survives process restart;
-- the same lease is serialized and recovered across separate processes or hosts;
+- the same lease can be serialized and safely recovered across separate processes or hosts;
 - an approved authority delta is durably applied back into a running lease;
 - provider outputs are cryptographically attested by providers.
 
-The remaining M4 target is at least one real harness/tool-middleware integration where executable tool calls cannot bypass the Task Lease boundary.
+M4 is complete for configured Agent Authority execution boundaries: direct SDK, MCP, brokered execution and the Vercel AI SDK `ToolLoopAgent` protected-tool path now preserve task authority without silent expansion. Durability, cross-process recovery and hostile-host containment are separate problems.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullsquare/agent-authority",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Task-bounded authority runtime for AI agents: give agents tasks, not standing account permissions.",
   "license": "Apache-2.0",
   "type": "module",
@@ -41,7 +41,7 @@
     "test": "node --test test/*.test.js",
     "test:ai-sdk": "node --test test/integrations/ai-sdk.integration.mjs",
     "test:coverage": "node --experimental-test-coverage --test test/*.test.js",
-    "check:syntax": "node --check src/index.js && node --check src/authority-evidence.js && node --check src/connections.js && node --check src/execution.js && node --check src/providers/github.js && node --check src/providers/google.js && node --check src/storage.js && node --check src/runtime-env.js && node --check src/sdk.js && node --check src/server.js && node --check src/cli.js && node --check src/agent-auth.js && node --check src/approvals.js && node --check src/idempotency.js && node --check src/keys.js && node --check src/harness-bridge.js && node --check src/guard.js && node --check src/task-lease.js && node --check src/mcp-gateway.js && node --check src/mcp-remote.js && node --check src/mcp-server.js && node --check src/integrations/ai-sdk.js && node --check examples/validation-mcp-upstream.js && node --check examples/direct-guard.js && node --check examples/task-lease-demo.js && node --check examples/live-github-task-lease.js && node --check examples/live-github-derived-mutation.js && node --check examples/live-google-cross-provider.js",
+    "check:syntax": "node --check src/index.js && node --check src/authority-evidence.js && node --check src/connections.js && node --check src/execution.js && node --check src/providers/github.js && node --check src/providers/google.js && node --check src/storage.js && node --check src/durable-task-lease.js && node --check src/runtime-env.js && node --check src/sdk.js && node --check src/server.js && node --check src/cli.js && node --check src/agent-auth.js && node --check src/approvals.js && node --check src/idempotency.js && node --check src/keys.js && node --check src/harness-bridge.js && node --check src/guard.js && node --check src/task-lease.js && node --check src/mcp-gateway.js && node --check src/mcp-remote.js && node --check src/mcp-server.js && node --check src/integrations/ai-sdk.js && node --check examples/validation-mcp-upstream.js && node --check examples/direct-guard.js && node --check examples/task-lease-demo.js && node --check examples/live-github-task-lease.js && node --check examples/live-github-derived-mutation.js && node --check examples/live-google-cross-provider.js",
     "check:package": "npm pack --dry-run",
     "check": "npm run check:syntax && npm test && npm run demo:task-lease && npm run check:package"
   },
@@ -62,6 +62,7 @@
     "./approvals": "./src/approvals.js",
     "./authority-evidence": "./src/authority-evidence.js",
     "./connections": "./src/connections.js",
+    "./durable-task-lease": "./src/durable-task-lease.js",
     "./execution": "./src/execution.js",
     "./guard": "./src/guard.js",
     "./harness-bridge": "./src/harness-bridge.js",