@nullsquare/agent-authority 0.4.3 → 0.4.5

package/docs/transport-invariance.md

@@ -0,0 +1,153 @@
+# Task Lease transport invariance
+
+Agent Authority treats SDK calls, MCP calls and brokered provider execution as execution paths, not separate authority models.
+
+The property under test is:
+
+```text
+same Task Lease + same established authority fact
+                     |
+          +----------+----------+
+          |          |          |
+       direct       MCP      brokered
+       guard.run()  gateway   provider
+          |          |          |
+          +----------+----------+
+                     |
+              same authority
+```
+
+Changing the transport must not broaden task authority.
+
+## Executable transport proof
+
+`test/transport-invariance.test.js` creates one Task Lease and one derived authority fact.
+
+The fact is first established from a brokered provider result using the strict evidence path:
+
+```text
+Task Lease root
+    |
+    v
+brokered item.discover
+    |
+    +--> Task-Lease ALLOW receipt
+    +--> exact output hash evidence
+    |
+    v
+reviewed test extractor
+    |
+    v
+deriveFromEvidence()
+    |
+    v
+fact:selected-item = alpha
+```
+
+That exact Task Lease and fact are then used through three execution paths:
+
+1. ordinary in-process `guard.run()`;
+2. `MissionMcpGateway` configured with the Task Lease;
+3. `ExecutingAuthorityRuntime.executeTaskLease()` with a brokered provider adapter.
+
+For `item = alpha`, every path allows execution.
+
+For `item = beta`, every path returns the same task-level authority delta:
+
+```text
+authority_delta_required
+```
+
+The blocked direct callback, MCP upstream call and brokered provider operation all remain unexecuted.
+
+After the Task Lease is completed, all three paths return:
+
+```text
+task_lease_completed
+```
+
+Again, no blocked execution reaches the host callback or provider boundary.
+
+## Broker behavior
+
+`ExecutingAuthorityRuntime.executeTaskLease()` evaluates the Task Lease before adapter readiness or provider execution.
+
+A lease-level `require_approval` result is returned as-is. Brokered execution does not consume a mission-level one-time approval to bypass the narrower Task Lease. Applying an explicitly approved authority delta back into a live Task Lease is separate roadmap work.
+
+Successful brokered Task Lease execution returns execution evidence bound to the Task-Lease receipt and exact provider output, so strict derived authority can originate from brokered execution as well as from `guard.run()`.
+
+## MCP behavior
+
+`MissionMcpGateway` remains backward-compatible with Mission-only use, but now accepts exactly one authority source:
+
+```text
+mission OR lease
+```
+
+When configured with a Task Lease, each tool call is evaluated through that lease before `upstream.callTool()` can run.
+
+MCP result metadata includes:
+
+```text
+io.nullsquare.agent-authority/decision
+io.nullsquare.agent-authority/code
+io.nullsquare.agent-authority/receipt_hash
+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 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 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.
+
+It also does not yet prove that:
+
+- Task Lease state survives process restart;
+- 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.
+
+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.3",
+  "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",

package/src/durable-task-lease.js

@@ -0,0 +1,185 @@
+import { TaskLease } from './task-lease.js';
+
+function sessionError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function assertStore(store) {
+  if (!store || typeof store !== 'object') {
+    throw new Error('durable Task Lease store is required');
+  }
+  for (const method of ['save', 'load', 'transact']) {
+    if (typeof store[method] !== 'function') {
+      throw new Error(`durable Task Lease store must implement ${method}()`);
+    }
+  }
+  return store;
+}
+
+function assertLease(lease) {
+  if (!(lease instanceof TaskLease)) throw new Error('TaskLease instance is required');
+  return lease;
+}
+
+/**
+ * A small stateful facade over JsonFileTaskLeaseStore-style transactional
+ * persistence.
+ *
+ * The session never exposes its mutable TaskLease instance. Reads come from the
+ * cached recovered lease, explicit refresh() reloads authenticated state, and
+ * evaluate() refreshes before every security decision so another worker's
+ * completion or narrowing is observed before the next guarded effect.
+ *
+ * Mutations use optimistic compare-and-swap against the session's current lease
+ * hash. A stale session receives task_lease_state_conflict and must refresh and
+ * reconsider the intended authority mutation; semantic mutations are never
+ * silently replayed against a newer authority state.
+ */
+export class DurableTaskLeaseSession {
+  constructor({ store, mission, lease_id, lease, lease_hash } = {}) {
+    this.store = assertStore(store);
+    if (!mission || typeof mission !== 'object') throw new Error('mission is required');
+    if (!lease_id) throw new Error('lease_id is required');
+    assertLease(lease);
+    if (lease.lease_id !== lease_id || lease.mission.mission_id !== mission.mission_id) {
+      throw sessionError('durable_task_lease_identity_mismatch', 'session lease identity does not match mission and lease_id');
+    }
+
+    this._mission = structuredClone(mission);
+    this.lease_id = lease_id;
+    this._lease = lease;
+    this._leaseHash = lease_hash || lease.hash();
+    if (this._leaseHash !== lease.hash()) {
+      throw sessionError('durable_task_lease_hash_mismatch', 'session lease hash does not match recovered Task Lease state');
+    }
+  }
+
+  get mission() {
+    return structuredClone(this._mission);
+  }
+
+  get status() {
+    return this._lease.status;
+  }
+
+  get expires_at() {
+    return this._lease.expires_at;
+  }
+
+  get completed_at() {
+    return this._lease.completed_at;
+  }
+
+  get completion_reason() {
+    return this._lease.completion_reason;
+  }
+
+  hash() {
+    return this._leaseHash;
+  }
+
+  snapshot() {
+    return structuredClone(this._lease.snapshot());
+  }
+
+  fact(factId) {
+    return this._lease.fact(factId);
+  }
+
+  listFacts() {
+    return this._lease.listFacts();
+  }
+
+  refresh() {
+    const lease = this.store.load({
+      mission: this._mission,
+      lease_id: this.lease_id
+    });
+    if (!lease) {
+      throw sessionError(
+        'task_lease_state_missing',
+        `task lease ${this.lease_id} has no durable state`,
+        { lease_id: this.lease_id }
+      );
+    }
+    this._lease = lease;
+    this._leaseHash = lease.hash();
+    return this;
+  }
+
+  evaluate(runtime, request, now = new Date()) {
+    this.refresh();
+    return this._lease.evaluate(runtime, request, now);
+  }
+
+  _commit(mutator) {
+    const result = this.store.transact({
+      mission: this._mission,
+      lease_id: this.lease_id,
+      expected_lease_hash: this._leaseHash,
+      mutate: mutator
+    });
+    this._lease = result.lease;
+    this._leaseHash = result.lease_hash;
+    return result.value;
+  }
+
+  addRoot(options) {
+    return this._commit((lease) => lease.addRoot(options));
+  }
+
+  derive(options) {
+    return this._commit((lease) => lease.derive(options));
+  }
+
+  deriveFromEvidence(options) {
+    return this._commit((lease) => lease.deriveFromEvidence(options));
+  }
+
+  bind(binding) {
+    return this._commit((lease) => lease.bind(binding));
+  }
+
+  complete(reason = 'task completed') {
+    return this._commit((lease) => lease.complete(reason));
+  }
+}
+
+export function createDurableTaskLeaseSession({ store, lease } = {}) {
+  assertStore(store);
+  assertLease(lease);
+  const mission = structuredClone(lease.mission);
+  const saved = store.save(lease);
+  const recovered = store.load({ mission, lease_id: lease.lease_id });
+  if (!recovered) {
+    throw sessionError('task_lease_state_missing', `task lease ${lease.lease_id} was not recoverable after creation`);
+  }
+  return new DurableTaskLeaseSession({
+    store,
+    mission,
+    lease_id: lease.lease_id,
+    lease: recovered,
+    lease_hash: saved.lease_hash
+  });
+}
+
+export function openDurableTaskLeaseSession({ store, mission, lease_id } = {}) {
+  assertStore(store);
+  if (!mission || typeof mission !== 'object') throw new Error('mission is required');
+  if (!lease_id) throw new Error('lease_id is required');
+  const missionSnapshot = structuredClone(mission);
+  const lease = store.load({ mission: missionSnapshot, lease_id });
+  if (!lease) {
+    throw sessionError('task_lease_state_missing', `task lease ${lease_id} has no durable state`, { lease_id });
+  }
+  return new DurableTaskLeaseSession({
+    store,
+    mission: missionSnapshot,
+    lease_id,
+    lease,
+    lease_hash: lease.hash()
+  });
+}

package/src/execution.js

@@ -1,4 +1,5 @@
 import { AuthorityRuntime, createReceipt } from './index.js';
+import { createExecutionEvidence } from './authority-evidence.js';
 
 function executionFailure(mission, request, code, reason, extra = {}) {
   const result = { decision: 'deny', code, reason, ...extra };
@@ -115,10 +116,39 @@ export class ExecutingAuthorityRuntime extends AuthorityRuntime {
     }
   }
 
-  async execute(missionInput, request) {
-    let evaluation = this.evaluate(missionInput, request);
+  /**
+   * Execute through the broker while preserving Task Lease narrowing.
+   *
+   * A lease-level REQUIRE_APPROVAL is returned before adapter readiness or
+   * provider execution. It is not converted into a mission-level one-time
+   * approval because applying an authority delta back into a live lease is a
+   * separate, not-yet-implemented capability.
+   */
+  async executeTaskLease(lease, request) {
+    if (!lease || typeof lease.evaluate !== 'function' || !lease.mission) {
+      throw new Error('task lease with mission and evaluate() is required');
+    }
+    return this.execute(lease.mission, request, { lease });
+  }
+
+  async execute(missionInput, request, { lease = null } = {}) {
+    if (lease && lease.mission?.mission_id !== missionInput?.mission_id) {
+      throw new Error('task lease mission does not match execution mission');
+    }
+
+    let evaluation = lease
+      ? lease.evaluate(this, request)
+      : this.evaluate(missionInput, request);
+
     if (evaluation.result.decision === 'deny') return { ...evaluation, output: null };
 
+    // A Task Lease is the narrowest authority object. Do not let brokered
+    // execution reinterpret a lease-level authority delta as a broader mission
+    // approval. This keeps broker behavior aligned with guard.run() and MCP.
+    if (lease && evaluation.result.decision !== 'allow') {
+      return { ...evaluation, output: null };
+    }
+
     const adapter = this.adapters.resolve(request.service);
     if (!adapter) {
       return executionFailure(missionInput, request, 'adapter_unavailable', `no adapter is registered for ${request.service}`);
@@ -148,6 +178,7 @@ export class ExecutingAuthorityRuntime extends AuthorityRuntime {
 
     try {
       const output = await adapter.execute({ mission: missionInput, request });
+      const evidence = createExecutionEvidence({ receipt: evaluation.receipt, output });
       let usage = null;
       if (budgetCheck && !budgetCheck.result) {
         const spent = this.usage.record(missionInput.mission_id, budgetCheck.currency, budgetCheck.amount);
@@ -160,7 +191,7 @@ export class ExecutingAuthorityRuntime extends AuthorityRuntime {
       if (executionRecord && this.executions) {
         this.executions.complete({ mission: missionInput, request, receipt_id: evaluation.receipt?.receipt_id || null });
       }
-      return { ...evaluation, output, usage, execution: executionRecord || null };
+      return { ...evaluation, output, evidence, usage, execution: executionRecord || null };
     } catch (error) {
       if (executionRecord && this.executions) {
         this.executions.uncertain({ mission: missionInput, request, error_code: error.code || 'provider_error' });

package/src/mcp-gateway.js

@@ -31,6 +31,15 @@ export function isDeclaredReadOnlyTool(tool) {
   return tool?.annotations?.readOnlyHint === true;
 }
 
+function authorityMeta(evaluation = {}) {
+  return {
+    'io.nullsquare.agent-authority/decision': evaluation.result?.decision || 'deny',
+    'io.nullsquare.agent-authority/code': evaluation.result?.code || null,
+    'io.nullsquare.agent-authority/receipt_hash': evaluation.receipt?.receipt_hash || null,
+    'io.nullsquare.agent-authority/task_lease_id': evaluation.receipt?.task_lease_id || null
+  };
+}
+
 function deniedToolResult(result, extra = {}) {
   return {
     content: [{
@@ -47,32 +56,43 @@ function deniedToolResult(result, extra = {}) {
 }
 
 /**
- * Small, transport-neutral policy gateway for MCP tools.
+ * Small policy gateway for MCP tools.
  *
  * The upstream object only needs two methods:
  *   listTools(params?) -> { tools: [...] }
  *   callTool(params)   -> MCP CallToolResult
  *
- * v0.1 deliberately defaults to read-only enforcement. A tool is considered
+ * The gateway accepts either a Mission or a Task Lease. When a Task Lease is
+ * supplied, every MCP tool call is evaluated through that exact lease before
+ * the upstream callback can run. This keeps transport changes from bypassing
+ * task-level narrowing.
+ *
+ * The gateway still defaults to read-only enforcement. A tool is considered
  * read-only only when its MCP annotations explicitly set readOnlyHint=true.
- * Write support belongs behind the existing approval + idempotency runtime and
- * is intentionally not inferred from tool names.
+ * Write support must be enabled deliberately; it is never inferred from names.
  */
 export class MissionMcpGateway {
   constructor({
     mission,
+    lease,
     runtime,
     upstream,
     service = 'mcp:upstream',
     readOnly = true,
     contextMapper = contextFromToolArguments
   } = {}) {
-    if (!mission) throw new Error('mission is required');
+    if ((mission && lease) || (!mission && !lease)) {
+      throw new Error('provide exactly one of mission or lease');
+    }
+    if (lease && (typeof lease.evaluate !== 'function' || !lease.mission)) {
+      throw new Error('lease must provide mission and evaluate(runtime, request)');
+    }
     if (!runtime || typeof runtime.evaluate !== 'function') throw new Error('authority runtime is required');
     if (!upstream || typeof upstream.listTools !== 'function' || typeof upstream.callTool !== 'function') {
       throw new Error('upstream MCP client must implement listTools() and callTool()');
     }
-    this.mission = mission;
+    this.mission = mission || lease.mission;
+    this.lease = lease || null;
     this.runtime = runtime;
     this.upstream = upstream;
     this.service = service;
@@ -81,6 +101,12 @@ export class MissionMcpGateway {
     this.tools = new Map();
   }
 
+  evaluate(request) {
+    return this.lease
+      ? this.lease.evaluate(this.runtime, request)
+      : this.runtime.evaluate(this.mission, request);
+  }
+
   async refreshTools(params = undefined) {
     const listed = await this.upstream.listTools(params);
     for (const tool of listed.tools || []) this.tools.set(tool.name, tool);
@@ -122,11 +148,9 @@ export class MissionMcpGateway {
       action: mcpToolAction(toolName),
       context
     };
-    const evaluation = this.runtime.evaluate(this.mission, request);
+    const evaluation = this.evaluate(request);
     if (evaluation.result.decision !== 'allow') {
-      return deniedToolResult(evaluation.result, {
-        'io.nullsquare.agent-authority/receipt_hash': evaluation.receipt?.receipt_hash || null
-      });
+      return deniedToolResult(evaluation.result, authorityMeta(evaluation));
     }
 
     const output = await this.upstream.callTool(params);
@@ -134,8 +158,7 @@ export class MissionMcpGateway {
       ...output,
       _meta: {
         ...(output?._meta || {}),
-        'io.nullsquare.agent-authority/decision': 'allow',
-        'io.nullsquare.agent-authority/receipt_hash': evaluation.receipt?.receipt_hash || null
+        ...authorityMeta(evaluation)
       }
     };
   }

package/src/mcp-remote.js

@@ -54,6 +54,7 @@ export class RemoteMcpUpstream {
 
 export function createMcpGatewayHandler({
   mission,
+  lease,
   runtime,
   upstream,
   upstreamUrl,
@@ -63,6 +64,7 @@ export function createMcpGatewayHandler({
   const resolvedUpstream = upstream || new RemoteMcpUpstream({ url: upstreamUrl });
   const gateway = new MissionMcpGateway({
     mission,
+    lease,
     runtime,
     upstream: resolvedUpstream,
     service,
@@ -74,7 +76,9 @@ export function createMcpGatewayHandler({
       {
         name: 'agent-authority-gateway',
         version: '0.3.0',
-        description: 'Mission-aware policy gateway for MCP tools'
+        description: lease
+          ? 'Task-Lease-aware policy gateway for MCP tools'
+          : 'Mission-aware policy gateway for MCP tools'
       },
       { capabilities: { tools: {} } }
     );

package/src/mcp-server.js

@@ -30,6 +30,7 @@ function sendJson(res, status, value) {
  */
 export function createMcpProxyServer({
   mission,
+  lease,
   runtime,
   upstream,
   upstreamUrl,
@@ -43,6 +44,7 @@ export function createMcpProxyServer({
 
   const gateway = createMcpGatewayHandler({
     mission,
+    lease,
     runtime,
     upstream,
     upstreamUrl,
@@ -64,6 +66,7 @@ export function createMcpProxyServer({
           ok: true,
           service: 'agent-authority-mcp-gateway',
           mode: 'read-only',
+          authority: lease ? 'task-lease' : 'mission',
           upstream: upstreamUrl || 'injected'
         });
       }