@nullsquare/agent-authority 0.4.0

package/docs/integration-contract.md

@@ -0,0 +1,132 @@
+# Integration contract
+
+Agent Authority should fit an existing agent stack without becoming its harness, connector catalog, or identity provider.
+
+The core contract is intentionally small:
+
+```text
+human task
+   |
+   v
+Task Lease
+   |
+   v
+proposed action
+   |
+   v
+Agent Authority evaluation
+   |
+   +-- DENY ------------> no side effect
+   |
+   +-- REQUIRE_APPROVAL -> no side effect until authority expands explicitly
+   |
+   +-- ALLOW -----------> execute through the host's existing connection
+   |
+   v
+receipt / derived facts / task completion
+```
+
+The mission remains the static authority ceiling. The Task Lease is the temporary task boundary developers should normally integrate against.
+
+## Action model
+
+A proposed action is described semantically:
+
+```json
+{
+  "service": "calendar",
+  "action": "event.create",
+  "context": {
+    "attendee": "customer@example.com"
+  }
+}
+```
+
+A Task Lease may bind that context value to a fact legitimately discovered earlier in the same task.
+
+```text
+Gmail thread root
+      |
+authorized read receipt
+      |
+derived sender fact
+      |
+Calendar attendee binding
+```
+
+A different attendee is not silently authorized. It becomes an authority delta.
+
+## 1. In-process guard — primary developer path
+
+For an application that already owns its SDK/client connection:
+
+```js
+import { AuthorityRuntime } from '@nullsquare/agent-authority';
+import { createTaskLease } from '@nullsquare/agent-authority/task-lease';
+import { createTaskLeaseGuard } from '@nullsquare/agent-authority/guard';
+
+const lease = createTaskLease({ mission, roots, bindings });
+const guard = createTaskLeaseGuard({ lease, runtime: new AuthorityRuntime() });
+
+await guard.run({
+  service: 'calendar',
+  action: 'event.create',
+  context: { attendee: 'customer@example.com' }
+}, () => calendar.createEvent(...));
+```
+
+The callback is never invoked on `DENY` or `REQUIRE_APPROVAL`. The host retains its provider credentials.
+
+This is the clearest adoption path today because it does not require MCP, a daemon, or a new authentication flow.
+
+## 2. MCP gateway — adapter for MCP hosts
+
+For ChatGPT, Claude, Codex, OpenClaw, IDEs, or other MCP-capable hosts:
+
+```text
+host -> Agent Authority MCP gateway -> existing MCP server
+```
+
+The gateway should enforce the same Task Lease immediately before forwarding `tools/call`. MCP is an adapter, not Agent Authority's core abstraction.
+
+## 3. Brokered execution — credential isolation
+
+When the host should not own the provider credential:
+
+```text
+agent -> Agent Authority -> credential broker -> provider
+```
+
+Agent Authority resolves the connected account internally and returns only sanitized provider output. The same Task Lease semantics must still apply.
+
+## Conformance invariant
+
+Regardless of transport, an integration is conformant only if:
+
+1. the side effect cannot occur before an `ALLOW` decision or completed step-up;
+2. the request evaluated is the request executed;
+3. the mission remains the authority ceiling;
+4. derived authority is anchored to an `ALLOW` receipt from the same Task Lease and existing parent facts;
+5. a different concrete resource cannot silently inherit authority;
+6. task completion or expiry stops later task actions;
+7. switching transport cannot broaden authority;
+8. a receipt can identify the mission, Task Lease, agent, service, action, and request hash.
+
+This invariant is more important than any specific protocol.
+
+## What Agent Authority does not require
+
+Adopting Agent Authority should not require replacing:
+
+- the agent harness;
+- OAuth/OIDC;
+- MCP;
+- provider SDKs;
+- existing secret storage;
+- an organization's IAM system.
+
+Those systems can remain in place. Agent Authority adds the temporary task-authority decision immediately before an agent-originated side effect.
+
+## Current trust boundary
+
+The v0.4 prototype records provenance for derived facts, including source receipt and selector. The trusted host/adapter still supplies the extracted value. This is an explicit validation-stage trust assumption, not a cryptographic guarantee.

package/docs/integrations/vercel-ai-sdk.md

@@ -0,0 +1,161 @@
+# Vercel AI SDK integration
+
+Agent Authority can protect existing Vercel AI SDK tools without replacing `ToolLoopAgent`, changing the model provider, or moving credentials into Agent Authority.
+
+The integration wraps each executable AI SDK tool at its `execute(input, options)` boundary. The tool keeps its existing description, input schema, approval metadata, and execution implementation.
+
+```text
+ToolLoopAgent
+     |
+     | model selects tool
+     v
+AI SDK tool.execute(input)
+     |
+     v
+Agent Authority Task Lease
+     |
+ ALLOW / DENY / STEP-UP
+     |
+     v
+existing tool effect / provider SDK
+```
+
+## Install
+
+```bash
+npm install @nullsquare/agent-authority ai
+```
+
+Current AI SDK 7 requires Node.js 22+. Agent Authority itself remains Node.js 20+ and does not depend on `ai` at runtime.
+
+## Wrap existing tools
+
+Start with normal AI SDK tools:
+
+```js
+import { ToolLoopAgent, tool } from 'ai';
+import { z } from 'zod';
+
+const tools = {
+  commentIssue: tool({
+    description: 'Comment on a GitHub issue',
+    inputSchema: z.object({
+      repository: z.string(),
+      issue_number: z.number(),
+      body: z.string()
+    }),
+    execute: ({ repository, issue_number, body }) =>
+      github.issues.createComment({
+        owner: repository.split('/')[0],
+        repo: repository.split('/')[1],
+        issue_number,
+        body
+      })
+  })
+};
+```
+
+Create a Task Lease and guard as usual, then wrap the tools:
+
+```js
+import { AuthorityRuntime } from '@nullsquare/agent-authority';
+import { createTaskLeaseGuard } from '@nullsquare/agent-authority/guard';
+import { protectAiSdkTools } from '@nullsquare/agent-authority/integrations/ai-sdk';
+
+const guard = createTaskLeaseGuard({
+  lease,
+  runtime: new AuthorityRuntime()
+});
+
+const protectedTools = protectAiSdkTools({
+  tools,
+  guard,
+  requests: {
+    commentIssue: ({ repository, issue_number }) => ({
+      service: 'github',
+      action: 'issue.comment',
+      context: { repository, issue_number }
+    })
+  }
+});
+
+const agent = new ToolLoopAgent({
+  model,
+  tools: protectedTools
+});
+```
+
+The rest of the AI SDK application remains unchanged.
+
+## Fail-closed behavior
+
+Every tool with an `execute` function must have an authority request mapper.
+
+If a developer forgets to map an executable tool, Agent Authority replaces its execution path with a failure:
+
+```text
+ai_sdk_tool_unmapped
+```
+
+The original tool effect is not called.
+
+Tools without an `execute` function are preserved because AI SDK does not automatically execute them in-process.
+
+## Resource expansion
+
+Suppose the Task Lease binds `issue_number` to issue `9`.
+
+The model may call:
+
+```json
+{
+  "repository": "Null-Square/agent-authority",
+  "issue_number": 9,
+  "body": "hello"
+}
+```
+
+and the existing tool effect can run.
+
+If the model changes only the issue number:
+
+```json
+{
+  "repository": "Null-Square/agent-authority",
+  "issue_number": 1,
+  "body": "hello"
+}
+```
+
+Agent Authority returns `authority_delta_required` before the tool's original `execute` function is invoked.
+
+## What CI proves
+
+The repository has a dedicated Node 22 integration job using the current `ai@7` package, the real `ToolLoopAgent`, the real `tool()` helper, and AI SDK's deterministic mock language model.
+
+It proves:
+
+1. `ToolLoopAgent` selects and automatically executes a protected tool through Agent Authority.
+2. The authorized effect executes exactly once.
+3. A different task resource executes zero effects.
+4. An executable tool without a request mapping executes zero effects.
+
+No model API key is needed for this validation.
+
+## Security boundary
+
+This wrapper protects the tool execution path that is actually passed to the agent. It cannot protect a separate provider client or unwrapped tool that the agent can reach through another path.
+
+```text
+GOOD
+
+ToolLoopAgent -> protectedTools -> Agent Authority -> provider
+
+BYPASSABLE
+
+ToolLoopAgent -> protectedTools -> Agent Authority -> provider
+       \
+        -> separate unwrapped provider/tool path
+```
+
+Use the wrapper as the only executable path for the protected capability.

package/docs/launch-checklist.md

@@ -0,0 +1,29 @@
+# Developer-preview launch checklist
+
+Agent Authority should not be announced as a production-ready security product. The first public release is a developer preview, and the announcement is gated on executable evidence.
+
+## Required evidence
+
+- [x] Task Lease cannot exceed its mission ceiling.
+- [x] Derived authority requires same-lease provenance, a parent lineage, and an extraction selector.
+- [x] A real GitHub resource can be discovered dynamically and become derived task authority.
+- [x] A real GitHub mutation can execute against that derived resource.
+- [x] An unrelated mutation is blocked before the provider call.
+- [x] Task completion blocks later provider calls even while the underlying credential remains available.
+- [x] Current Vercel AI SDK `ToolLoopAgent` executes protected tools through Agent Authority.
+- [x] Unmapped executable AI SDK tools fail closed.
+- [x] The packed npm artifact installs in a clean consumer project using only public exports.
+- [x] Optional framework integrations do not become production dependencies of the core package.
+- [ ] Release-candidate CI and CodeQL are green on the exact commit to be published.
+- [ ] npm registry publication is verified from a clean install.
+
+## Claims we can make
+
+For execution paths that are actually placed behind Agent Authority, the runtime can enforce task-bound resource constraints immediately before a side effect, including resources derived from authorized earlier execution.
+
+## Claims we must not make
+
+- Agent Authority is not a complete sandbox for an agent that also has an unguarded route to the same provider.
+- Recorded derivation provenance is not yet cryptographic proof that a provider response contained the extracted value.
+- The project is not production-ready and has not yet proven durable multi-process Task Lease state.
+- Task-scoped agent authorization as a research concept was not invented by NullSquare.

package/docs/npm-release.md

@@ -0,0 +1,19 @@
+# npm release contract
+
+The public package name is `@nullsquare/agent-authority`.
+
+Before any publication:
+
+1. the release commit must pass CI, CodeQL, live GitHub validation, current AI SDK integration validation, and packed-consumer validation;
+2. `npm pack` must contain the documented public exports;
+3. a fresh Node.js 20 consumer must install the tarball and run the core Task Lease smoke test;
+4. the optional AI SDK integration must import without making `ai` a production dependency;
+5. the registry package must be public and its repository metadata must point to `https://github.com/Null-Square/agent-authority`.
+
+After publication, verify from a fresh project with:
+
+```bash
+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.

package/docs/openclaw-integration.md

@@ -0,0 +1,97 @@
+# OpenClaw Integration Blueprint
+
+Agent Authority should integrate with OpenClaw as a **tool/service authority layer**, not as a replacement agent harness.
+
+## Why
+
+OpenClaw's agent harness abstraction owns execution of an agent turn. Agent Authority owns a different concern: whether a human-authorized agent may perform a sensitive external action and which connected credential may be used to perform it.
+
+## Recommended v1
+
+```text
+OpenClaw agent/runtime
+      |
+      | proposed sensitive action
+      v
+Agent Authority OpenClaw tool/plugin
+      |
+      v
+Agent Authority sidecar
+      |
+      +-- mission policy
+      +-- resource constraints
+      +-- approval
+      +-- account connection
+      +-- credential broker
+      +-- receipt
+      |
+      v
+provider adapter / MCP / connector
+      |
+      v
+external service
+```
+
+### Installation shape
+
+1. User installs Agent Authority once on the OpenClaw host or points OpenClaw to a hosted Agent Authority endpoint.
+2. User connects GitHub/Google/etc. once to Agent Authority.
+3. OpenClaw installs/enables a small trusted Agent Authority plugin.
+4. The plugin exposes authority-aware tools or wraps sensitive tool execution.
+5. Codex, Claude Code, ACP agents, or embedded OpenClaw runtimes can all reuse the same connected accounts.
+
+## v1 plugin responsibilities
+
+The OpenClaw plugin should remain intentionally thin:
+
+- resolve the current Agent Authority endpoint
+- attach the current mission id / agent session identity
+- translate OpenClaw tool calls into normalized service/action/context requests
+- call `/v1/execute`
+- surface `deny` and `require_approval` outcomes cleanly
+- return sanitized provider output
+
+It should **not** store OAuth refresh tokens, duplicate the connection registry, or implement provider-specific credentials itself.
+
+## Example mapping
+
+```text
+OpenClaw tool: github_read_file
+repository: Null-Square/agent-authority
+path: src/index.js
+
+=>
+
+service: github
+action: repo.contents.read
+context.repository: Null-Square/agent-authority
+params.path: src/index.js
+```
+
+The authority runtime then checks mission policy and repository constraints before the GitHub adapter is allowed to use the connected credential.
+
+## Native Codex vs ACP
+
+The integration should work identically whether OpenClaw is using its native Codex harness or an external ACP harness such as Claude Code. Harness identity is metadata supplied to Agent Authority; it is not where the provider credentials live.
+
+```text
+OpenClaw native Codex ----\
+                          \
+OpenClaw Claude ACP --------> Agent Authority ----> GitHub
+                          /
+OpenClaw Gemini ACP ------/
+```
+
+This is an important interoperability proof: switching harnesses must not require reconnecting GitHub.
+
+## Security properties
+
+- Provider secrets never enter the LLM prompt or OpenClaw transcript.
+- A denied tool call causes no provider dispatch.
+- Mission resource constraints bind access to the intended repo/account/project.
+- Revocation applies across all OpenClaw harnesses using the mission.
+- Provider responses are sanitized before returning to the model.
+
+## Future deeper integration
+
+If OpenClaw exposes a stable trusted pre-tool execution/policy hook, Agent Authority can integrate there so existing tools are governed transparently. This should remain a plugin integration over the same sidecar/control-plane API rather than moving the authority database or credential vault into the harness.

package/docs/package-consumer-validation.md

@@ -0,0 +1,18 @@
+# Packed consumer validation
+
+Before publishing Agent Authority, CI validates the exact npm artifact from a completely separate temporary project.
+
+The validation does not import repository-relative source files. It:
+
+1. runs `npm pack`;
+2. creates a fresh project outside the package source tree;
+3. installs the generated tarball with production dependencies only;
+4. imports Agent Authority through documented package exports;
+5. runs an allowed Task Lease effect;
+6. verifies a different bound resource cannot execute the effect;
+7. completes the Task Lease and verifies the previously allowed effect can no longer execute;
+8. imports the optional Vercel AI SDK integration wrapper without installing `ai`.
+
+This catches missing files, bad `exports`, accidental repository-relative imports, undeclared production dependencies, and accidental coupling between the framework-neutral package and optional framework integrations.
+
+The CI job runs on Node.js 20 so the package-consumer contract remains independent of current AI SDK runtime requirements.

package/docs/release-candidate-status.md

@@ -0,0 +1,3 @@
+# v0.4 release candidate status
+
+This file exists to make the release-candidate boundary explicit in the repository. The candidate is ready to merge only after all required CI jobs and CodeQL are green on the final head commit.

package/docs/release-guardrails.md

@@ -0,0 +1,8 @@
+# Release guardrails
+
+- Do not publish if packed-consumer validation fails.
+- Do not publish if live derived GitHub mutation validation fails.
+- Do not publish if current AI SDK integration validation fails.
+- Do not describe the release as production-ready.
+- Do not claim NullSquare invented task-scoped agent authorization.
+- Do not hide the unguarded-path bypass limitation or trusted-extraction limitation.

package/docs/release-notes-v0.4.md

@@ -0,0 +1,26 @@
+# Agent Authority v0.4 — Developer Preview
+
+**Give your agent a task, not your account.**
+
+v0.4 is the first developer-preview milestone centered on Task Leases and task-bounded side effects.
+
+## What is new
+
+- Task Lease runtime layered under the existing mission ceiling.
+- Same-lease derived authority with explicit parent lineage and extraction selectors.
+- Exact resource/context bindings and `authority_delta_required` step-up signals.
+- Immediate completion and expiry enforcement independent of credential lifetime.
+- Real GitHub validation: discover a live issue, derive its issue number as authority, mutate exactly that issue, block an unrelated issue before the provider call, then block the previously authorized issue after task completion.
+- Vercel AI SDK integration for wrapping existing `ToolLoopAgent` tools at the `execute` boundary.
+- Fail-closed behavior for unmapped executable AI SDK tools.
+- Packed-package consumer validation using only public npm exports.
+
+## Security boundary
+
+Agent Authority only protects execution paths routed through its enforcement boundary. If an agent can reach the same provider through an unguarded tool, SDK client, shell command, or credential path, that route is outside the guarantee.
+
+Derived-value extraction is currently trusted to the host/adapter. v0.4 records provenance and lineage but does not cryptographically prove that the selected provider-output field contained the claimed value.
+
+## Status
+
+This is a developer preview, not a production-ready security control. The goal of v0.4 is to make task-bounded, provenance-aware least privilege executable and easy to test inside ordinary agent stacks.

package/docs/release-scope.md

@@ -0,0 +1,3 @@
+# v0.4 release scope
+
+The v0.4 developer preview release includes only the task-bounded runtime, public evidence, Vercel AI SDK wrapper, and package-consumer validation. Persistent leases, automatic approved-delta application, cryptographic extraction proof, hosted UI, additional frameworks, and broader connector work remain outside this release.

package/docs/ship-criteria.md

@@ -0,0 +1,3 @@
+# Ship criteria
+
+The release is shippable only when the final release-candidate commit has green CI and CodeQL, the packed artifact works in a clean consumer project, and registry publication can be authenticated under the NullSquare npm scope.