@nullsquare/agent-authority 0.4.4 → 0.4.6

package/README.md

@@ -6,64 +6,29 @@
 
 ### Give your agent a task, not your account.
 
-**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.**
+**Agent Authority is a small execution layer that lets an agent use existing account permissions only for the task the user actually gave it.**
 
-[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-first API](#task-first-api) · [Product proof gate](docs/product-proof.md) · [Task Leases](docs/task-leases.md) · [Durability](docs/durable-task-leases.md) · [Evidence](docs/evidence.md) · [Transport invariance](docs/transport-invariance.md) · [Roadmap](ROADMAP.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.5 Developer Preview on npm.** The `main` branch may contain unreleased work for the next preview. Agent Authority 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.
+## Why this exists
 
-A user says:
+A user gives an agent a narrow task:
 
-> **Handle the demo request in this email thread.**
+> **Handle this customer email.**
 
-The agent may need to:
-
-```text
-Gmail -> read one thread
-          |
-          v
-       discover sender
-          |
-          v
-Calendar -> create one meeting with that sender
-          |
-          v
-Gmail -> reply in the originating thread
-```
+But the connected account may give the application broad standing permission to read every email, create meetings with anyone, update any CRM record, or send mail to anyone.
 
-The underlying OAuth connections may permit reading every email, creating meetings with anyone, or sending mail to anyone.
-
-Traditional authorization answers:
+OAuth and IAM answer:
 
 > Can this application use Calendar?
 
-Agent Authority asks a narrower question immediately before the side effect:
-
-> **Is this exact effect justified by the task the human authorized?**
-
-## Task-bounded autonomy
+Agent Authority asks immediately before the effect:
 
-Agent Authority is trying to make this trade-off unnecessary:
-
-```text
-broad standing permissions
-        OR
-approve every tool call
-```
+> **Is this exact Calendar action justified by the task the user authorized?**
 
 The target is:
 
@@ -73,344 +38,335 @@ one meaningful task approval
         v
 temporary bounded authority
         |
-        +--> safe task actions proceed
-        +--> unrelated resources are blocked
-        +--> real authority expansion requires step-up
+        +--> useful task actions proceed normally
+        +--> authority may follow resources discovered through authorized work
+        +--> unrelated resources require step-up
         |
         v
-task completes -> authority disappears
+task completes -> task authority disappears
 ```
 
 The provider credential may continue to exist. The **task authority does not**.
 
-## The key idea: authority can follow trusted task data
+## Install
 
-Many resources do not exist in the original prompt. The agent discovers them while working.
+Requires Node.js 20+.
 
-Agent Authority models this with a **Task Lease**:
+```bash
+npm install @nullsquare/agent-authority
+```
+
+## Task-first API
+
+The preferred developer surface is intentionally small:
 
 ```text
-Human-approved task
-        |
-        v
-  authority root
-  Gmail thread #91
-        |
- authorized read
-        |
-        +--> ALLOW receipt
-        +--> exact output hash evidence
-        |
-        v
- reviewed adapter extractor
-        |
-        v
- derived fact
- customer@example.com
-        |
-        v
- exact binding
- Calendar attendee must equal that sender
+Task -> Effect -> Authority
 ```
 
-A request for `customer@example.com` can proceed.
+```js
+import { createTask } from '@nullsquare/agent-authority/task';
+
+const task = createTask({
+  principal: 'user:me',
+  agent: 'agent:assistant',
+  request: 'Find issue #42 and leave one comment only on that issue',
+
+  permissions: {
+    github: {
+      allow: ['issue.list', 'issue.comment'],
+      deny: ['issue.close', 'repo.delete'],
+      constraints: { repository: ['acme/app'] }
+    }
+  },
 
-A request for `other@example.com` does not silently inherit the same authority. It becomes an **authority delta** and requires step-up.
+  authority: {
+    repository: {
+      kind: 'github.repository',
+      value: 'acme/app'
+    }
+  },
 
-This is **derived authority**: authority follows a resource discovered through authorized execution, but never broadens into a standing wildcard permission.
+  bindings: [
+    {
+      service: 'github',
+      action: 'issue.list',
+      field: 'repository',
+      authority: 'repository'
+    }
+  ]
+});
 
-See [Task Leases and Derived Authority](docs/task-leases.md).
+const discovery = await task.run({
+  service: 'github',
+  action: 'issue.list',
+  context: { repository: 'acme/app' }
+}, () => github.listIssues());
+
+const issue = task.authorityFrom(discovery, {
+  name: 'issue',
+  kind: 'github.issue.number',
+  from: 'repository',
+  extractor: selectedIssueExtractor
+});
 
-## Core invariant
+task.bind({
+  service: 'github',
+  action: 'issue.comment',
+  field: 'issue_number',
+  authority: 'issue'
+});
 
-```text
-Task Lease authority <= Mission authority
+await task.run({
+  service: 'github',
+  action: 'issue.comment',
+  context: {
+    repository: 'acme/app',
+    issue_number: issue.value,
+    body: 'Handled.'
+  }
+}, () => github.comment(issue.value, 'Handled.'));
 ```
 
-The mission remains the ceiling. A Task Lease may narrow an action to resources discovered during the task, but it cannot grant an action that the mission already denies or never allowed.
+If the agent changes `issue_number` to an unrelated issue, the callback does not run. Agent Authority returns an authority-delta step-up that can be explained to a human:
 
-More generally:
+```js
+try {
+  await task.run(unrelatedRequest, effect);
+} catch (error) {
+  console.log(task.explain(error).summary);
+}
+```
 
-> **Authority may stay the same or shrink as it moves through agents, tools and transports. It must never silently grow.**
+Example output:
 
-## Run the derived-authority demo
+```text
+The task established authority for 42 but this action requested 7.
+```
+
+The task-first API is a facade over the existing Mission, Task Lease, execution-evidence and guard primitives. It does not weaken or replace them.
 
-Requirements: Node.js 20+.
+## Run the product demo
+
+From a checkout:
 
 ```bash
-git clone https://github.com/Null-Square/agent-authority.git
-cd agent-authority
 npm install
-npm test
-npm run demo:task-lease
+npm run demo:task
 ```
 
-The demo performs this flow without provider credentials:
+The self-contained GitHub-shaped demo performs:
 
 ```text
-1. ALLOW read of one task-authorized Gmail thread
-2. derive sender email from that same Task Lease receipt
-3. ALLOW Calendar event for that sender
-4. REQUIRE_APPROVAL for a different attendee
-5. complete task
-6. DENY subsequent actions
+1. authorized issue discovery
+2. exact guarded result becomes downstream authority
+3. comment on the discovered issue succeeds
+4. comment on an unrelated issue requires step-up
+5. blocked attempt executes zero provider callbacks
 ```
 
-The side-effect callbacks for blocked actions never run.
+The callback bodies are intentionally replaceable with the SDK/provider calls an application already uses.
 
-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).
+## Utility benchmark
 
-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).
+Security is necessary but not sufficient. Agent Authority also tracks whether normal agent work still succeeds without approval fatigue.
 
-## Minimal developer API
+```bash
+npm run benchmark:task
+```
 
-```js
-import { AuthorityRuntime } from '@nullsquare/agent-authority';
-import { createTaskLease } from '@nullsquare/agent-authority/task-lease';
-import { createTaskLeaseGuard } from '@nullsquare/agent-authority/guard';
-import { gmailThreadSenderAuthorityExtractor } from '@nullsquare/agent-authority/providers/google';
-
-const lease = createTaskLease({
-  mission,
-  request: 'Handle the demo request in thread:demo-91',
-  roots: [
-    { fact_id: 'fact:thread', kind: 'gmail.thread', value: 'thread:demo-91' }
-  ],
-  bindings: [
-    {
-      service: 'calendar',
-      action: 'event.create',
-      context_field: 'attendee_email',
-      fact_id: 'fact:sender-email'
-    }
-  ]
-});
+The first deterministic fixture measures:
 
-const guard = createTaskLeaseGuard({
-  lease,
-  runtime: new AuthorityRuntime()
-});
+- normal task completion rate;
+- false approval rate;
+- true authority-delta step-up rate;
+- unauthorized effect rate;
+- provider effects required for completed tasks.
 
-const read = await guard.run({
-  service: 'gmail',
-  action: 'thread.read',
-  context: { thread_id: 'thread:demo-91' }
-}, () => gmail.readThread('thread:demo-91'));
-
-const senderFact = lease.deriveFromEvidence({
-  fact_id: 'fact:sender-email',
-  kind: 'email.address',
-  from: ['fact:thread'],
-  receipt: read.receipt,
-  evidence: read.evidence,
-  output: read.output,
-  extractor: gmailThreadSenderAuthorityExtractor
-});
+Its current regression target is:
 
-await guard.run({
-  service: 'calendar',
-  action: 'event.create',
-  context: { attendee_email: senderFact.value }
-}, () => calendar.createEvent({ attendee: senderFact.value }));
+```text
+normal task completion rate = 100%
+false approval rate = 0%
+true authority-delta step-up rate = 100%
+unauthorized effect rate = 0%
 ```
 
-`deriveFromEvidence()` does not accept the authority value. The reviewed extractor selects a normalized output field, and Task Lease resolves that value only after verifying that the output still matches the exact allowed execution evidence.
-
-The older `derive()` API remains available as the explicitly **host-trusted compatibility path**.
+This is a deterministic product regression fixture, **not a real-world benchmark**. Real provider and harness workloads should replace or supplement it as adoption grows.
 
-The host keeps its existing SDK, connector and authentication. Agent Authority controls whether the effect may happen.
+See [Product proof gate](docs/product-proof.md).
 
-## Three integration modes, one authority model
+## The differentiated mechanism
 
-Agent Authority is deliberately **not tied to MCP, OAuth, or one agent framework**.
+Many task resources are unknown when the user gives the instruction. They are discovered during execution.
 
-### 1. In-process guard
+Agent Authority lets authority follow those resources only when the value comes from already-authorized work:
 
 ```text
-agent code -> guard.run() -> existing SDK / API
+human-approved task
+        |
+        v
+ authority root
+ repository = acme/app
+        |
+ authorized issue discovery
+        |
+        +--> ALLOW receipt
+        +--> exact output evidence
+        |
+ reviewed extractor
+        |
+        v
+ derived authority
+ issue = 42
+        |
+        v
+ later effect may bind issue_number == 42
 ```
 
-Best when the application already owns the provider connection. This is the primary v0.4 adoption path.
+A request for issue `42` can proceed.
+
+A request for issue `7` does not inherit the same authority simply because the underlying GitHub credential can access it.
 
-### 2. MCP gateway
+That is the core contribution we are testing:
+
+> **Authority may follow the task's proven execution path without becoming ambient account authority.**
+
+## Core invariant
 
 ```text
-MCP host -> Agent Authority -> existing MCP server
+Task Lease authority <= Mission authority
 ```
 
-Best when the harness already speaks MCP. MCP is an integration transport, not the product identity.
+The Mission remains the ceiling. Task authority may stay the same or shrink as work crosses tools, transports and durable state. It must never silently grow.
+
+## Existing stack, not a replacement stack
 
-### 3. Brokered execution
+Agent Authority is not trying to replace OAuth, IAM, MCP, gateways or agent frameworks.
 
 ```text
-agent -> Agent Authority -> isolated credential -> provider
+agent reasoning
+      |
+      v
+Agent Authority
+      |
+      v
+existing SDK / MCP / gateway / OAuth / 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**.
-
-## What is implemented
-
-### Task authority
-
-- mission validation and deterministic `ALLOW / DENY / REQUIRE_APPROVAL`
-- explicit deny precedence
-- resource/context constraints
-- expiry and cumulative budgets
-- delegation attenuation
-- durable mission revocation
-- Task Lease prototype
-- explicit authority roots
-- same-lease provenance-bound derived facts
-- execution evidence binding an allowed receipt, request and exact output hash
-- strict `deriveFromEvidence()` path where the caller cannot provide the authority value
-- reviewed Gmail sender authority extractor bound to `gmail:thread.read`
-- reviewed GitHub selected-issue-number extractor bound to marker-scoped `github:issue.list`
-- shared Google/GitHub authority-extractor conformance suite
-- legacy host-trusted `derive()` compatibility path
-- required parent lineage and extraction selector
-- exact context-field bindings
-- authority-delta step-up signal
-- immediate task completion/expiry enforcement
-- Task Lease IDs/hashes in decision receipts
-
-### Enforcement
-
-- protocol-neutral `guard.run()` wrapper
-- blocked side effects never invoke their callback
-- successful guarded effects return separate execution evidence
-- one-time human approvals bound to exact request
-- mutation idempotency
-- conservative uncertain-state handling
-- signed harness action grants
-- MCP v2 read-only gateway/proxy
-
-### Credentials and runtime
-
-- persistent connection metadata
-- AES-256-GCM local encrypted secret store
-- safe reconnect cleanup
-- GitHub brokered execution without returning the token to the agent
-- GitHub REST mappings for repository access plus evidence-derived `issue.list` / `issue.comment`
-- Google REST provider mappings for Gmail thread reads and Calendar event mutations
-- short-lived signed local agent-instance tokens
-- local CLI/daemon
-
-### Engineering quality
-
-- adversarial authorization tests
-- execution-evidence substitution, tampering, replay, cross-lease and selector tests
-- the same provider-derived-authority conformance attacks against Google and GitHub
-- Node 20 and Node 22 CI
-- coverage run
-- package checks
-- clean-consumer npm registry verification
-- live GitHub read and evidence-derived mutation proofs
-- CodeQL
-
-## What is different from OAuth, IAM and MCP authorization?
-
-Agent Authority is **not trying to replace them**.
-
-OAuth/IAM answer who or what may access a provider and with which standing scopes. MCP authorization protects an MCP transport. Agent Authority operates at a different boundary:
+Three execution modes already share the same Task Lease semantics:
 
 ```text
-human task
-    |
-    v
-temporary task authority
-    |
-    v
-exact agent-originated effect
-    |
-    +--> existing OAuth / IAM / MCP / SDK / CLI
+in-process guard
+MCP gateway
+brokered provider execution
 ```
 
-The project should consume existing identity/authentication mechanisms and emerging standards rather than invent another login or token format.
-
-The contribution we are testing is operational: **make task-scoped, provenance-aware least privilege usable inside ordinary agent stacks.**
+A real Vercel AI SDK `ToolLoopAgent` integration also exercises the protected-tool boundary. See [Transport invariance](docs/transport-invariance.md).
 
-## Example use cases
+## Durability
 
-### Support / sales
+For local workflows that must survive process restarts, pass a `JsonFileTaskLeaseStore` to the same task-first API:
 
-> Handle this customer request.
+```js
+import { JsonFileTaskLeaseStore } from '@nullsquare/agent-authority/storage';
+import { createTask } from '@nullsquare/agent-authority/task';
 
-Bind later actions to the customer, thread, ticket or meeting discovered from the authorized task path.
+const store = new JsonFileTaskLeaseStore({
+  dir: config.paths.task_leases,
+  keyPath: config.paths.master_key
+});
 
-### Finance
+const task = createTask({
+  ...taskDefinition,
+  store
+});
+```
 
-> Refund the customer from this ticket, but never more than the original charge.
+The task facade then uses the durable Task Lease session internally. Normal task calls do not change.
 
-Discover customer -> order -> charge through authorized reads, then bind the refund to those concrete facts and amount ceiling.
+Durable state currently provides authenticated local recovery, exact Mission binding, atomic whole-state replacement, per-lease local locking, stale-writer compare-and-swap protection, durable completion/expiry, and refresh before authority evaluation.
 
-### Coding / operations
+See [Durable Task Leases](docs/durable-task-leases.md).
 
-> Fix issue #42, open a PR, do not merge or deploy production.
+## What is already proven
 
-Keep repo/issue/branch authority bounded as subagents and tools change.
+- deterministic allow / deny / require-approval decisions;
+- explicit deny precedence and Mission ceiling;
+- execution evidence bound to exact guarded output;
+- strict evidence-derived authority where callers do not provide the derived value;
+- reviewed Google Gmail-sender and GitHub selected-issue extractors;
+- shared two-provider adversarial conformance tests;
+- live GitHub read and evidence-derived comment mutation proofs;
+- connected Gmail -> Calendar smoke proof;
+- direct SDK / MCP / broker transport invariance;
+- real Vercel AI SDK protected-tool execution proof;
+- authenticated durable Task Lease recovery;
+- stale-writer/CAS and mission-alias protection;
+- automatic durable Task Lease sessions;
+- Node 20/22 CI, coverage, packed-consumer validation and CodeQL;
+- independent npm registry consumer verification.
 
-### Personal / company operating agents
+The lower-level evidence is documented under `docs/` and remains available for security review.
 
-> Handle this email.
+## Product direction
 
-Allow a natural workflow across mail, calendar, CRM and internal systems without turning every connected account into ambient agent authority.
+The next product risk is **not lack of another security subsystem**. It is adoption and useful autonomy.
 
-## Security principles
+Before deeper distributed/crypto infrastructure becomes a priority, Agent Authority should prove:
 
-1. **Task before credential.** A provider token is not task authority.
-2. **Mission is the ceiling.** Task Leases cannot override explicit denies.
-3. **No side effect before authorization.** Denied and step-up actions never execute.
-4. **Authority lineage matters.** Provider-derived authority should bind the exact allowed receipt and guarded output to a reviewed extractor; legacy host-trusted derivation remains identifiable in provenance.
-5. **No silent resource expansion.** A different concrete resource becomes an authority delta.
-6. **Task authority ends with the task.** Completion and expiry are independent from provider credential lifetime.
-7. **Authority may shrink, never silently grow.** Delegation and transport changes must preserve non-amplification.
-8. **The evaluated request must be the executed request.** Request hashes, grants and idempotency protect the boundary.
-9. **Credentials stay out of model context where Agent Authority owns them.**
-10. **Security gaps are documented, not marketed away.**
+1. a new developer can get a meaningful workflow running in under 10 minutes;
+2. coding, support/communications and operations/finance workflows all fit the task-first model;
+3. normal task completion stays high without approval spam;
+4. unrelated-resource effects still execute zero provider callbacks;
+5. at least one external developer adopts the package without project-author assistance.
 
-See [SECURITY.md](SECURITY.md).
+See [Product proof gate](docs/product-proof.md) and [Roadmap](ROADMAP.md).
 
 ## Current limitations
 
 This is still a validation implementation.
 
-- Task Lease state is currently process-local.
-- `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.
-- Bindings currently target top-level request context fields.
-- Approved authority deltas are surfaced but not automatically applied back into a live lease.
-- GitHub token-stdin is a developer bridge, not final browser OAuth onboarding.
-- The encrypted local vault is not an OS keychain/KMS/HSM backend.
-- Remote authenticated deployment and a production approval UX are not complete.
+- Durable persistence is a trusted-local-host reference backend, not distributed consensus or hostile-host containment.
+- Another worker can still change durable state after an `ALLOW` decision and before asynchronous remote provider I/O begins. Remote effect + receipt + Task Lease state are not one distributed transaction.
+- A crashed local worker may leave a per-lease lock requiring explicit recovery.
+- Transport/harness proofs do not contain a malicious host that deliberately exposes a separate unguarded tool, shell, network path or credential.
+- Provider outputs are evidence-bound inside the trusted Agent Authority runtime but are not provider-signed remote attestations.
+- Source-data changes do not yet automatically invalidate already-derived authority.
+- Approved authority deltas are surfaced but not automatically applied into a live durable task.
+- GitHub token-stdin and the local encrypted vault are developer bridges, not final production OAuth/KMS UX.
+- Remote authenticated deployment and production approval UX remain incomplete.
+
+These are real limitations. They are not reasons to build every possible infrastructure layer before product adoption is proven.
 
-These are follow-on validation problems. We are intentionally not solving them with a giant policy language or another agent framework.
+## What we are deliberately not prioritizing now
 
-## What we are deliberately not building
+Unless a real workflow proves otherwise:
 
-- another agent harness
-- another OAuth or identity protocol
-- an MCP replacement
-- a connector marketplace
-- a giant proprietary policy DSL
-- an enterprise dashboard before the enforcement primitive proves adoption
+- another agent harness;
+- a new OAuth/identity/token protocol;
+- an MCP replacement/control plane;
+- a connector marketplace;
+- a proprietary universal policy DSL;
+- distributed Task Lease databases;
+- provider-attestation protocol design;
+- A2A implementation;
+- dashboard-first enterprise product work.
 
 ## Contributing
 
-The best contribution is not another abstract feature. It is a real integration or adversarial case that answers:
+The most valuable contribution answers:
 
-> **Can this agent complete the intended task while being technically unable to use the same underlying account authority for an unrelated effect?**
+> **Can this agent complete the intended task while being technically unable to use the same standing account authority for an unrelated effect?**
 
-We especially want:
+Especially useful:
 
-- framework integrations around `guard.run()`;
-- trustworthy operation -> resource-context mappings;
-- Task Lease examples from real workflows;
+- real task-first workflows;
+- trustworthy operation -> resource mappings;
+- utility-regression cases that cause unnecessary approvals;
 - derived-authority / provenance attacks;
-- MCP and non-MCP conformance cases;
-- secure persistence and extraction-verification designs that stay simple.
+- transport or multi-worker attacks;
+- feedback from developers trying to integrate the package for the first time.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).