@nullsquare/agent-authority 0.4.0 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-![Agent Authority](docs/assets/agent-authority-cover.svg)
+![Agent Authority](docs/assets/agent-authority-cover-editorial-v2.png)
 
 # Agent Authority
 
@@ -10,10 +10,18 @@
 
 [Task Leases](docs/task-leases.md) · [Validate](docs/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 validation candidate.** The repository has a working policy runtime, protocol-neutral guard, Task Lease prototype with provenance-bound derived facts, approvals, revocation, idempotency, credential isolation, MCP v2 gateway, GitHub brokered execution, CI and CodeQL. It is not production-ready yet.
+> **Status: public pre-alpha / v0.4.0 Developer Preview.** Published on npm as `@nullsquare/agent-authority`. The repository has a working policy runtime, protocol-neutral guard, Task Lease prototype with provenance-bound derived facts, approvals, revocation, idempotency, credential isolation, MCP v2 gateway, GitHub brokered execution, CI and CodeQL. It is not production-ready yet.
 
 </div>
 
+## Install
+
+Requires Node.js 20+.
+
+```bash
+npm install @nullsquare/agent-authority
+```
+
 ## The problem
 
 AI agents increasingly receive broad provider permissions so they can complete narrow human tasks.

package/ROADMAP.md

@@ -55,10 +55,15 @@ never silently grow
 - [x] independent task-lease expiry
 - [x] task-lease ID/hash in receipts
 - [x] self-contained cross-system demo: Gmail-thread fact -> Calendar attendee
-- [ ] exercise the same pattern against two real provider operations
+- [x] reusable Google REST adapter for Gmail thread reads and Calendar event mutations
+- [x] adversarial Gmail -> Calendar test proving unrelated and post-completion effects never invoke provider callbacks
+- [x] real connected-account smoke: Gmail self-test fixture -> exact attendee -> temporary Calendar event -> cleanup
+- [ ] rerun the same proof as a public GitHub Actions job after repository Google OAuth secrets are configured
 
 **Success criterion:** a real multi-step agent workflow discovers a resource during an authorized read and can use exactly that resource in a later side effect, while an unrelated resource is technically blocked without requiring approval for every normal task step.
 
+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
 
 Build only what the real M1 workflow proves necessary.
@@ -117,7 +122,7 @@ Only after the task-bound enforcement model is validated.
 - [ ] framework integration examples
 - [ ] `good first issue` tasks based on real mappings/tests
 - [ ] independent contributor implementation of one adapter
-- [ ] release packaging and npm publication
+- [x] release packaging and npm publication
 - [ ] documentation site only when README/docs become too large
 
 ## M7 — Standards interoperability

package/docs/announcement-draft.md

@@ -1,4 +1,4 @@
-# Announcement draft — hold until registry verification
+# Announcement draft — v0.4.0 Developer Preview
 
 NullSquare is open-sourcing **Agent Authority**, an experimental runtime for task-bounded AI agent side effects.
 
@@ -8,6 +8,12 @@ A Task Lease can follow resources discovered through authorized execution withou
 
 The developer preview also includes a Vercel AI SDK integration that wraps ordinary `ToolLoopAgent` tools at their existing `execute` boundary.
 
+Install the published developer preview with:
+
+```bash
+npm install @nullsquare/agent-authority@0.4.0
+```
+
 **Give your agent a task, not your account.**
 
 This is a developer preview, not a claim that NullSquare invented task-scoped authorization and not a production-ready security control. The repository documents the current trust assumptions and bypass boundaries explicitly.

package/docs/evidence.md

@@ -10,6 +10,102 @@ This page records the strongest properties the repository currently demonstrates
 
 The guarantee applies to effects that actually pass through the Agent Authority enforcement boundary. A separate unguarded provider path is outside this guarantee.
 
+## Cross-provider derived authority — Gmail → Calendar
+
+Agent Authority now includes a real Google provider mapping, an adversarial cross-provider test, a live validation script, and an opt-in GitHub Actions workflow.
+
+The task shape is:
+
+```text
+Task root
+one Gmail thread
+        |
+        v
+ALLOW Gmail thread.read
+        |
+        v
+discover sender email
+        |
+        v
+derive fact: sender_email
+        |
+        v
+ALLOW Calendar event.create
+attendee == derived sender
+        |
+        +--> different attendee
+        |      -> authority_delta_required
+        |      -> Calendar mutation callback does not run
+        |
+        v
+complete Task Lease
+        |
+        +--> same attendee again
+               -> task_lease_completed
+               -> Calendar mutation callback does not run
+```
+
+### Connected-account smoke — 2026-08-22
+
+A controlled self-test was exercised against the connected NullSquare Gmail and Google Calendar accounts:
+
+1. a temporary validation message was sent from the validation account to itself;
+2. Gmail returned the self-test message with sender `null@nullsquare.net`;
+3. one private, transparent Calendar event was created with exactly `null@nullsquare.net` as attendee;
+4. the temporary Calendar event was deleted immediately after the proof;
+5. the validation email was moved to Trash after cleanup.
+
+No unrelated external person was invited. The smoke test establishes that the concrete Gmail and Calendar operations used by the validation are available and compatible with the intended data shape.
+
+The live connected-account smoke is not presented as a public CI proof of the repository script. The Task Lease zero-call assertions are separately executable in `test/google-cross-provider.test.js`, and `.github/workflows/live-google-validation.yml` is provided for a rerunnable provider-backed proof once repository Google OAuth secrets are configured.
+
+### Executable local/CI assertions
+
+`test/google-cross-provider.test.js` proves deterministically that:
+
+- the approved Gmail thread callback runs exactly once;
+- its sender becomes a same-lease derived authority fact;
+- one Calendar mutation for that sender runs exactly once;
+- a different attendee produces `authority_delta_required` and the Calendar callback is not invoked;
+- after lease completion, the previously valid attendee produces `task_lease_completed` and the Calendar callback is not invoked again.
+
+`test/google-provider.test.js` separately validates the Google REST mappings, metadata-only Gmail sender extraction, Calendar attendee body, default `sendUpdates=none`, credential redaction, unsupported-action failure, and mutation classification.
+
+### Public workflow
+
+The manual workflow `Live Google cross-provider validation` mints a short-lived access token from repository secrets and runs `npm run demo:live-google`.
+
+It expects:
+
+```text
+AA_GOOGLE_OAUTH_CLIENT_ID
+AA_GOOGLE_OAUTH_CLIENT_SECRET
+AA_GOOGLE_OAUTH_REFRESH_TOKEN
+```
+
+The refresh token should be restricted to the practical Gmail read-only and Calendar event scopes documented in `docs/live-google-validation.md`.
+
+The connected GitHub tool does not expose repository Actions-secret management, so those secrets are intentionally not installed automatically from this development session.
+
+### What this proves
+
+Taken together, the deterministic Task Lease test plus the controlled provider smoke show that:
+
+- the Gmail → Calendar derived-authority shape is implemented, not just diagrammed;
+- the exact attendee binding is enforced before the Calendar mutation callback;
+- provider operations exist and work against real Gmail and Calendar accounts;
+- cleanup can keep the live proof reversible and self-contained.
+
+### What this does not prove yet
+
+- a public GitHub Actions run has executed the full repository live script;
+- host-side extraction of `sender_email` is cryptographically attested by Gmail;
+- the agent cannot bypass Agent Authority if it independently holds a Google credential;
+- Task Lease state is durable across process failure;
+- the refresh-token setup is production credential onboarding.
+
+See [Live Gmail → Calendar validation](live-google-validation.md).
+
 ## Live derived-authority mutation — GitHub
 
 Public fixture: [issue #9](https://github.com/Null-Square/agent-authority/issues/9)
@@ -129,8 +225,11 @@ Current pull requests run:
 - coverage;
 - live GitHub read validation;
 - live derived GitHub mutation validation for trusted in-repository branches;
+- Google provider and cross-provider adversarial tests;
 - CodeQL.
 
+The live Google provider mutation workflow is manual because it requires repository-owned Google OAuth secrets. It should be added to the public evidence list after its first successful run.
+
 ## Evidence standard for new claims
 
 A new security claim should ideally include all four:

package/docs/live-google-validation.md

@@ -0,0 +1,100 @@
+# Live Gmail → Calendar validation
+
+This validation turns the README's Gmail → Calendar Task Lease example into a real cross-provider proof.
+
+The narrow claim is:
+
+> A sender discovered from one authorized Gmail thread can become exact Task Lease authority for one Calendar event attendee, while a different attendee and any post-completion retry are blocked before the Calendar mutation callback runs.
+
+It is intentionally not a general Google OAuth product or a production onboarding flow.
+
+## Safe fixture
+
+Use a one-message thread sent from the validation account to itself. This keeps the proof real without inviting an unrelated person.
+
+The live script:
+
+1. reads the approved Gmail thread through `users.threads.get` using metadata format and only the `From` header;
+2. derives `fact:sender-email` from the same-lease `ALLOW` receipt;
+3. creates one private, transparent Calendar event whose attendee is exactly that derived sender;
+4. attempts a different attendee and requires `authority_delta_required` before the provider callback;
+5. completes the Task Lease and proves the previously authorized attendee can no longer be used;
+6. deletes the temporary event as harness cleanup outside the agent-authority proof.
+
+The event uses `sendUpdates=none` and is deleted after validation. The cleanup call is counted separately from task-side provider mutations.
+
+## Required Google OAuth scopes
+
+The validation credential needs only the Google permissions required for the two provider operations:
+
+```text
+https://www.googleapis.com/auth/gmail.readonly
+https://www.googleapis.com/auth/calendar.events
+```
+
+Do not put an access token in the repository or workflow inputs.
+
+## GitHub Actions secrets
+
+The manual workflow `.github/workflows/live-google-validation.yml` mints a short-lived access token at runtime from these repository secrets:
+
+```text
+AA_GOOGLE_OAUTH_CLIENT_ID
+AA_GOOGLE_OAUTH_CLIENT_SECRET
+AA_GOOGLE_OAUTH_REFRESH_TOKEN
+```
+
+The refresh token should have been granted the Gmail read-only and Calendar event scopes above. The access token is masked and exists only for the workflow run.
+
+## Run from GitHub Actions
+
+Open **Actions → Live Google cross-provider validation → Run workflow** and provide:
+
+- `gmail_thread_id`: the approved self-test Gmail thread ID;
+- `calendar_id`: normally `primary`;
+- `expected_sender`: optional, but recommended for a deterministic fixture.
+
+A successful run should record the following shape:
+
+```text
+ALLOW -> Gmail returned sender <fixture account>
+Derived authority -> Calendar attendee <fixture account>
+ALLOW -> real Calendar event mutation executed
+STEP-UP -> unrelated attendee blocked before Calendar provider mutation
+DENY -> post-completion Calendar mutation blocked
+Provider calls observed before cleanup: gmail_reads=1, calendar_task_mutations=1
+Cleanup -> deleted temporary Calendar event
+```
+
+## Run locally with a short-lived token
+
+```bash
+export GOOGLE_ACCESS_TOKEN='...'
+export AA_GOOGLE_GMAIL_THREAD_ID='...'
+export AA_GOOGLE_CALENDAR_ID='primary'
+export AA_GOOGLE_EXPECTED_SENDER='validation@example.com'
+npm run demo:live-google
+```
+
+Prefer the refresh-token GitHub Actions workflow for repeatable validation. Do not persist the short-lived access token in shell history, source files, screenshots, or issue comments.
+
+## What this proves
+
+When the real provider calls are placed inside the Task Lease guard callbacks, the validation demonstrates:
+
+- cross-provider derived authority from Gmail to Calendar;
+- one exact derived attendee can be used for the real Calendar effect;
+- a different attendee does not silently inherit authority;
+- blocked attempts create zero additional task-side Calendar provider mutations;
+- task completion removes the previously valid derived authority;
+- the Google credential can remain broader than the Task Lease.
+
+## What this does not prove
+
+- the current host-side extraction of `sender_email` is cryptographically attested by Gmail;
+- Task Lease state survives process failure;
+- an agent holding an independent Google credential cannot bypass the guard;
+- the validation refresh-token setup is a production credential-onboarding design;
+- `sendUpdates=none` is a general invitation-delivery strategy for user-facing calendar workflows.
+
+The purpose of this proof is to close the real cross-provider M1 validation gap and expose the next implementation problem with evidence rather than speculation.

package/docs/npm-release.md

@@ -17,3 +17,13 @@ npm install @nullsquare/agent-authority@0.4.0
 ```
 
 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.
+
+## 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.0`. 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/examples/live-google-cross-provider.js

@@ -0,0 +1,256 @@
+import { AuthorityRuntime } from '../src/index.js';
+import {
+  AuthorityApprovalRequiredError,
+  AuthorityDeniedError,
+  createTaskLeaseGuard
+} from '../src/guard.js';
+import { gmailThreadSenderEmail } from '../src/providers/google.js';
+import { createTaskLease } from '../src/task-lease.js';
+
+const token = process.env.GOOGLE_ACCESS_TOKEN;
+const threadId = process.env.AA_GOOGLE_GMAIL_THREAD_ID;
+const calendarId = process.env.AA_GOOGLE_CALENDAR_ID || 'primary';
+const expectedSender = process.env.AA_GOOGLE_EXPECTED_SENDER?.trim().toLowerCase() || null;
+
+if (!token) throw new Error('GOOGLE_ACCESS_TOKEN is required for live Google validation');
+if (!threadId) throw new Error('AA_GOOGLE_GMAIL_THREAD_ID is required for live Google validation');
+
+const now = Date.now();
+const startTime = new Date(now + 10 * 60_000).toISOString();
+const endTime = new Date(now + 25 * 60_000).toISOString();
+const marker = `Agent Authority live Google validation ${new Date(now).toISOString()}`;
+
+const mission = {
+  version: '0.1',
+  mission_id: `mission:live-google-cross-provider:${now}`,
+  principal: { id: 'user:google-validation' },
+  agent: { id: 'agent:google-cross-provider-validation' },
+  objective: 'Read one authorized Gmail thread and create one Calendar event only for the sender discovered from that thread',
+  resources: [
+    {
+      service: 'gmail',
+      allow: ['thread.read'],
+      deny: ['message.send', 'message.delete', 'thread.delete'],
+      constraints: { thread_id: [threadId] }
+    },
+    {
+      service: 'calendar',
+      allow: ['event.create'],
+      deny: ['event.delete', 'calendar.delete'],
+      constraints: { calendar_id: [calendarId] }
+    }
+  ],
+  constraints: { expires_at: new Date(now + 15 * 60_000).toISOString() }
+};
+
+const lease = createTaskLease({
+  mission,
+  request: 'Schedule one temporary validation event with the sender in the approved Gmail thread',
+  roots: [
+    {
+      fact_id: 'fact:gmail-thread',
+      kind: 'gmail.thread',
+      value: threadId,
+      source: 'validation-task'
+    },
+    {
+      fact_id: 'fact:calendar',
+      kind: 'google.calendar',
+      value: calendarId,
+      source: 'validation-task'
+    }
+  ],
+  bindings: [
+    {
+      service: 'gmail',
+      action: 'thread.read',
+      context_field: 'thread_id',
+      fact_id: 'fact:gmail-thread'
+    },
+    {
+      service: 'calendar',
+      action: 'event.create',
+      context_field: 'calendar_id',
+      fact_id: 'fact:calendar'
+    },
+    {
+      service: 'calendar',
+      action: 'event.create',
+      context_field: 'attendee_email',
+      fact_id: 'fact:sender-email'
+    }
+  ],
+  expires_at: new Date(now + 10 * 60_000).toISOString()
+});
+
+const guard = createTaskLeaseGuard({ lease, runtime: new AuthorityRuntime() });
+const providerHeaders = {
+  accept: 'application/json',
+  authorization: `Bearer ${token}`,
+  'content-type': 'application/json',
+  'user-agent': 'agent-authority-live-google-validation/0.4'
+};
+
+let providerReadCalls = 0;
+let providerMutationCalls = 0;
+let cleanupCalls = 0;
+let createdEventId = null;
+
+async function googleResponse(url, options = {}) {
+  const response = await fetch(url, {
+    ...options,
+    headers: { ...providerHeaders, ...(options.headers || {}) }
+  });
+  const text = await response.text();
+  let body = null;
+  if (text) {
+    try { body = JSON.parse(text); } catch { body = text; }
+  }
+  if (!response.ok) {
+    throw new Error(`Google API ${response.status}: ${typeof body === 'string' ? body.slice(0, 300) : JSON.stringify(body).slice(0, 300)}`);
+  }
+  return body;
+}
+
+async function readAuthorizedThread() {
+  return guard.run(
+    {
+      service: 'gmail',
+      action: 'thread.read',
+      context: { thread_id: threadId }
+    },
+    async () => {
+      providerReadCalls += 1;
+      const query = new URLSearchParams({ format: 'metadata' });
+      query.append('metadataHeaders', 'From');
+      const thread = await googleResponse(
+        `https://gmail.googleapis.com/gmail/v1/users/me/threads/${encodeURIComponent(threadId)}?${query}`
+      );
+      const sender = gmailThreadSenderEmail(thread);
+      return {
+        thread_id: thread.id,
+        sender_email: sender.email,
+        sender_raw: sender.raw,
+        sender_message_id: sender.message_id,
+        message_count: Array.isArray(thread.messages) ? thread.messages.length : 0
+      };
+    }
+  );
+}
+
+async function createCalendarEvent(attendeeEmail, suffix) {
+  const request = {
+    service: 'calendar',
+    action: 'event.create',
+    context: {
+      calendar_id: calendarId,
+      attendee_email: attendeeEmail,
+      start_time: startTime,
+      end_time: endTime,
+      summary: `${marker} — ${suffix}`,
+      transparency: 'transparent',
+      visibility: 'private',
+      send_updates: 'none'
+    }
+  };
+
+  return guard.run(request, async () => {
+    providerMutationCalls += 1;
+    const event = await googleResponse(
+      `https://www.googleapis.com/calendar/v3/calendars/${encodeURIComponent(calendarId)}/events?sendUpdates=none`,
+      {
+        method: 'POST',
+        body: JSON.stringify({
+          summary: request.context.summary,
+          description: 'Temporary event created by the Agent Authority live Gmail → Calendar validation. Cleanup deletes it after the proof.',
+          start: { dateTime: startTime },
+          end: { dateTime: endTime },
+          attendees: [{ email: attendeeEmail }],
+          transparency: 'transparent',
+          visibility: 'private'
+        })
+      }
+    );
+    return { event_id: event.id, html_link: event.htmlLink || null };
+  });
+}
+
+async function cleanupEvent(eventId) {
+  cleanupCalls += 1;
+  const response = await fetch(
+    `https://www.googleapis.com/calendar/v3/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}?sendUpdates=none`,
+    { method: 'DELETE', headers: providerHeaders }
+  );
+  if (!response.ok && response.status !== 404) {
+    const body = await response.text();
+    throw new Error(`Google Calendar cleanup ${response.status}: ${body.slice(0, 300)}`);
+  }
+}
+
+try {
+  console.log(`Task root Gmail thread: ${threadId}`);
+  console.log(`Task root Calendar: ${calendarId}`);
+  console.log('1. Read the approved Gmail thread through the Task Lease');
+  const discovered = await readAuthorizedThread();
+  console.log(`   ALLOW -> Gmail returned sender ${discovered.output.sender_email}`);
+
+  if (expectedSender && discovered.output.sender_email !== expectedSender) {
+    throw new Error(`expected sender ${expectedSender}, got ${discovered.output.sender_email}`);
+  }
+
+  lease.derive({
+    fact_id: 'fact:sender-email',
+    kind: 'email.address',
+    value: discovered.output.sender_email,
+    from: ['fact:gmail-thread'],
+    receipt: discovered.receipt,
+    selector: 'output.sender_email'
+  });
+  console.log(`2. Derived authority -> Calendar attendee ${discovered.output.sender_email}`);
+
+  const allowed = await createCalendarEvent(discovered.output.sender_email, 'authorized');
+  createdEventId = allowed.output.event_id;
+  console.log(`3. ALLOW -> real Calendar event mutation executed (${createdEventId})`);
+
+  try {
+    await createCalendarEvent('blocked@example.invalid', 'must-never-run');
+    throw new Error('unrelated attendee mutation unexpectedly executed');
+  } catch (error) {
+    if (!(error instanceof AuthorityApprovalRequiredError) || error.code !== 'authority_delta_required') {
+      throw error;
+    }
+    console.log('4. STEP-UP -> unrelated attendee blocked before Calendar provider mutation');
+  }
+
+  if (providerMutationCalls !== 1) {
+    throw new Error(`expected exactly one task-side Calendar mutation before completion, got ${providerMutationCalls}`);
+  }
+
+  lease.complete('live Gmail to Calendar validation complete');
+  try {
+    await createCalendarEvent(discovered.output.sender_email, 'must-not-run-after-completion');
+    throw new Error('post-completion Calendar mutation unexpectedly executed');
+  } catch (error) {
+    if (!(error instanceof AuthorityDeniedError) || error.code !== 'task_lease_completed') {
+      throw error;
+    }
+    console.log('5. DENY -> post-completion Calendar mutation blocked');
+  }
+
+  if (providerReadCalls !== 1) {
+    throw new Error(`expected exactly one Gmail provider read, got ${providerReadCalls}`);
+  }
+  if (providerMutationCalls !== 1) {
+    throw new Error(`expected exactly one Calendar provider mutation after blocked attempts, got ${providerMutationCalls}`);
+  }
+
+  console.log('PASS -> a sender discovered from real Gmail became exact derived authority for one real Calendar mutation');
+  console.log('PASS -> unrelated and post-completion attempts caused zero additional Calendar provider mutations');
+} finally {
+  if (createdEventId) {
+    await cleanupEvent(createdEventId);
+    console.log(`Cleanup -> deleted temporary Calendar event ${createdEventId} outside the agent authority proof`);
+  }
+  console.log(`Provider calls observed before cleanup: gmail_reads=${providerReadCalls}, calendar_task_mutations=${providerMutationCalls}`);
+  console.log(`Harness cleanup calls: ${cleanupCalls}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullsquare/agent-authority",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Task-bounded authority runtime for AI agents: give agents tasks, not standing account permissions.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,12 +35,13 @@
     "demo:task-lease": "node examples/task-lease-demo.js",
     "demo:live-github": "node examples/live-github-task-lease.js",
     "demo:live-derived-github": "node examples/live-github-derived-mutation.js",
+    "demo:live-google": "node examples/live-google-cross-provider.js",
     "demo:mcp-upstream": "node examples/validation-mcp-upstream.js",
     "demo:guard": "node examples/direct-guard.js",
     "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/connections.js && node --check src/execution.js && node --check src/providers/github.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",
+    "check:syntax": "node --check src/index.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:package": "npm pack --dry-run",
     "check": "npm run check:syntax && npm test && npm run demo:task-lease && npm run check:package"
   },
@@ -71,7 +72,8 @@
     "./sdk": "./src/sdk.js",
     "./storage": "./src/storage.js",
     "./task-lease": "./src/task-lease.js",
-    "./providers/github": "./src/providers/github.js"
+    "./providers/github": "./src/providers/github.js",
+    "./providers/google": "./src/providers/google.js"
   },
   "files": ["src", "docs", "examples", "README.md", "LICENSE", "SECURITY.md", "ROADMAP.md", "CONTRIBUTING.md"],
   "repository": { "type": "git", "url": "git+https://github.com/Null-Square/agent-authority.git" },

package/src/providers/google.js

@@ -0,0 +1,201 @@
+import { brokeredProviderAdapter } from '../connections.js';
+
+const MUTATING_ACTIONS = new Set(['event.create', 'event.delete']);
+const SEND_UPDATES = new Set(['all', 'externalOnly', 'none']);
+
+function required(value, name) {
+  if (value === undefined || value === null || value === '') throw new Error(`${name} is required`);
+  return value;
+}
+
+function providerError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function fromHeader(message) {
+  const headers = message?.payload?.headers;
+  if (!Array.isArray(headers)) return null;
+  const header = headers.find((item) => String(item?.name || '').toLowerCase() === 'from');
+  return typeof header?.value === 'string' ? header.value : null;
+}
+
+export function extractEmailAddress(value) {
+  if (typeof value !== 'string') return null;
+  const match = value.match(/([A-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Z0-9.-]+\.[A-Z]{2,})/i);
+  return match ? match[1].trim().toLowerCase() : null;
+}
+
+export function gmailThreadSenderEmail(thread) {
+  const messages = thread?.messages;
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw providerError('gmail_thread_empty', 'Gmail thread does not contain any messages');
+  }
+
+  for (const message of messages) {
+    const raw = fromHeader(message);
+    const email = extractEmailAddress(raw);
+    if (email) return { email, raw, message_id: message.id || null };
+  }
+
+  throw providerError('gmail_sender_missing', 'Gmail thread does not contain a usable From header');
+}
+
+function validateSendUpdates(value) {
+  const normalized = value || 'none';
+  if (!SEND_UPDATES.has(normalized)) {
+    throw providerError('invalid_send_updates', 'context.send_updates must be all, externalOnly, or none');
+  }
+  return normalized;
+}
+
+function buildOperation(request, {
+  gmailBaseUrl = 'https://gmail.googleapis.com',
+  calendarBaseUrl = 'https://www.googleapis.com/calendar/v3'
+} = {}) {
+  const context = request?.context || {};
+
+  if (request?.service === 'gmail' && request?.action === 'thread.read') {
+    const threadId = required(context.thread_id, 'context.thread_id');
+    const query = new URLSearchParams({ format: 'metadata' });
+    query.append('metadataHeaders', 'From');
+    return {
+      method: 'GET',
+      url: `${gmailBaseUrl}/gmail/v1/users/me/threads/${encodeURIComponent(threadId)}?${query}`
+    };
+  }
+
+  if (request?.service === 'calendar' && request?.action === 'event.create') {
+    const calendarId = context.calendar_id || 'primary';
+    const attendeeEmail = required(context.attendee_email, 'context.attendee_email');
+    const startTime = required(context.start_time, 'context.start_time');
+    const endTime = required(context.end_time, 'context.end_time');
+    const sendUpdates = validateSendUpdates(context.send_updates);
+
+    return {
+      method: 'POST',
+      url: `${calendarBaseUrl}/calendars/${encodeURIComponent(calendarId)}/events?sendUpdates=${encodeURIComponent(sendUpdates)}`,
+      body: {
+        summary: context.summary || 'Agent Authority task event',
+        description: context.description || undefined,
+        start: { dateTime: startTime },
+        end: { dateTime: endTime },
+        attendees: [{ email: attendeeEmail }],
+        transparency: context.transparency || undefined,
+        visibility: context.visibility || undefined
+      }
+    };
+  }
+
+  if (request?.service === 'calendar' && request?.action === 'event.delete') {
+    const calendarId = context.calendar_id || 'primary';
+    const eventId = required(context.event_id, 'context.event_id');
+    const sendUpdates = validateSendUpdates(context.send_updates);
+    return {
+      method: 'DELETE',
+      url: `${calendarBaseUrl}/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}?sendUpdates=${encodeURIComponent(sendUpdates)}`
+    };
+  }
+
+  throw providerError(
+    'unsupported_action',
+    `Google action ${request?.service || 'unknown'}:${request?.action || 'unknown'} has no provider operation mapping`
+  );
+}
+
+function accessToken(credential) {
+  const token = typeof credential === 'string' ? credential : credential?.access_token;
+  if (!token) throw providerError('credential_invalid', 'Google credential does not contain an access token');
+  return token;
+}
+
+async function responseBody(response) {
+  const text = await response.text();
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+function normalizedOutput(request, response, body) {
+  const common = {
+    provider: request.service,
+    status: response.status,
+    ok: response.ok,
+    request_id: response.headers?.get?.('x-request-id') || null
+  };
+
+  if (request.service === 'gmail' && request.action === 'thread.read') {
+    const sender = gmailThreadSenderEmail(body);
+    return {
+      ...common,
+      thread_id: body?.id || request.context?.thread_id || null,
+      message_count: Array.isArray(body?.messages) ? body.messages.length : 0,
+      sender_email: sender.email,
+      sender_raw: sender.raw,
+      sender_message_id: sender.message_id
+    };
+  }
+
+  if (request.service === 'calendar' && request.action === 'event.create') {
+    return {
+      ...common,
+      event_id: body?.id || null,
+      html_link: body?.htmlLink || null,
+      attendees: Array.isArray(body?.attendees)
+        ? body.attendees.map((item) => item?.email).filter(Boolean)
+        : []
+    };
+  }
+
+  if (request.service === 'calendar' && request.action === 'event.delete') {
+    return { ...common, deleted: response.ok };
+  }
+
+  return { ...common, body };
+}
+
+export function createGoogleProviderAdapter({
+  broker,
+  fetchImpl = globalThis.fetch,
+  gmailBaseUrl = 'https://gmail.googleapis.com',
+  calendarBaseUrl = 'https://www.googleapis.com/calendar/v3'
+} = {}) {
+  if (!broker) throw new Error('credential broker is required');
+  if (typeof fetchImpl !== 'function') throw new Error('fetch implementation is required');
+
+  const operationFor = (request) => buildOperation(request, { gmailBaseUrl, calendarBaseUrl });
+
+  const adapter = brokeredProviderAdapter({
+    kind: 'google-rest',
+    services: ['gmail', 'calendar'],
+    broker,
+    async execute({ request, credential }) {
+      const operation = operationFor(request);
+      const response = await fetchImpl(operation.url, {
+        method: operation.method,
+        headers: {
+          accept: 'application/json',
+          authorization: `Bearer ${accessToken(credential)}`,
+          'content-type': 'application/json',
+          'user-agent': 'nullsquare-agent-authority/0.4'
+        },
+        body: operation.body ? JSON.stringify(operation.body) : undefined
+      });
+
+      const body = await responseBody(response);
+      const output = normalizedOutput(request, response, body);
+
+      if (!response.ok) {
+        const error = providerError('provider_error', `${request.service} API ${response.status}`);
+        error.provider_output = output;
+        throw error;
+      }
+
+      return output;
+    }
+  });
+
+  adapter.validateRequest = (request) => operationFor(request);
+  adapter.isMutation = (request) => MUTATING_ACTIONS.has(request?.action);
+  return adapter;
+}

package/docs/assets/agent-authority-cover.svg

@@ -1,41 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="640" viewBox="0 0 1600 640" role="img" aria-label="Agent Authority — mission scoped authorization for AI agents">
-  <defs>
-    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
-      <stop offset="0" stop-color="#07111f"/><stop offset="1" stop-color="#121a36"/>
-    </linearGradient>
-    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
-      <stop offset="0" stop-color="#7c5cff"/><stop offset="1" stop-color="#4ecbff"/>
-    </linearGradient>
-  </defs>
-  <rect width="1600" height="640" rx="36" fill="url(#bg)"/>
-  <g font-family="Arial, Helvetica, sans-serif" fill="#fff">
-    <text x="100" y="120" font-size="28" font-weight="700" letter-spacing="3">NULLSQUARE / OPEN SOURCE</text>
-    <text x="100" y="220" font-size="78" font-weight="800">Agent Authority</text>
-    <text x="100" y="285" font-size="34" fill="#b9c7e6">Mission-scoped authorization for AI agents</text>
-    <text x="100" y="355" font-size="27" fill="#8fe1ff">One mission · Any agent · Any auth system</text>
-  </g>
-  <g transform="translate(930 95)" font-family="Arial, Helvetica, sans-serif">
-    <rect x="120" y="0" width="330" height="72" rx="16" fill="#111c34" stroke="#6d85ff"/>
-    <text x="285" y="44" text-anchor="middle" font-size="24" fill="#fff">Human-approved mission</text>
-    <path d="M285 72 V120" stroke="#7786a8" stroke-width="3"/>
-    <rect x="80" y="120" width="410" height="90" rx="18" fill="#171842" stroke="#8b67ff" stroke-width="2"/>
-    <text x="285" y="158" text-anchor="middle" font-size="25" font-weight="700" fill="#fff">AUTHORITY RUNTIME</text>
-    <text x="285" y="190" text-anchor="middle" font-size="20" fill="#b9c7e6">allow · deny · approve · revoke</text>
-    <path d="M285 210 V260" stroke="#7786a8" stroke-width="3"/>
-    <rect x="80" y="260" width="410" height="72" rx="16" fill="#101b30" stroke="#4ecbff"/>
-    <text x="285" y="304" text-anchor="middle" font-size="23" fill="#fff">Adapters / connectors</text>
-    <path d="M285 332 V382" stroke="#7786a8" stroke-width="3"/>
-    <g fill="#101b30" stroke="#4b628c">
-      <rect x="0" y="382" width="135" height="64" rx="14"/><rect x="145" y="382" width="135" height="64" rx="14"/>
-      <rect x="290" y="382" width="135" height="64" rx="14"/><rect x="435" y="382" width="135" height="64" rx="14"/>
-    </g>
-    <g font-size="20" fill="#fff" text-anchor="middle">
-      <text x="67" y="422">OAuth</text><text x="212" y="422">MCP</text><text x="357" y="422">API / CLI</text><text x="502" y="422">Legacy</text>
-    </g>
-  </g>
-  <rect x="100" y="430" width="690" height="2" fill="url(#accent)"/>
-  <g font-family="Arial, Helvetica, sans-serif" font-size="22" fill="#b9c7e6">
-    <text x="100" y="485">Delegation attenuation</text><text x="330" y="485">Human approvals</text><text x="555" y="485">Action receipts</text>
-    <text x="100" y="530">Credential isolation</text><text x="330" y="530">Legacy compatibility</text><text x="555" y="530">Protocol neutral</text>
-  </g>
-</svg>