@nullsquare/agent-authority 0.4.5 → 0.4.6

package/docs/product-proof.md

@@ -0,0 +1,185 @@
+# Product proof gate
+
+Agent Authority has enough security machinery to validate its core thesis. The next risk is no longer "can we make the invariant stronger?" It is "will an agent developer actually install and keep this layer?"
+
+The product thesis is:
+
+> **Your agent may use the permissions it already has only for the task the user actually gave it.**
+
+The differentiated mechanism is narrower:
+
+> **Authority may follow exact resources discovered through already-authorized execution, without turning those resources into standing account permissions.**
+
+Everything else in the repository exists to make those two statements true.
+
+## Developer mental model
+
+The preferred public experience should stay close to three concepts:
+
+```text
+Task -> Effect -> Authority
+```
+
+A developer should not need to understand Mission internals, Task Lease hashing, execution evidence envelopes, CAS persistence or transport adapters before getting value.
+
+Those primitives remain available for advanced integrations and audits.
+
+## Product-facing API
+
+The task-first facade intentionally composes the existing primitives instead of replacing them:
+
+```js
+import { createTask } from '@nullsquare/agent-authority/task';
+
+const task = createTask({
+  principal: 'user:me',
+  agent: 'agent:assistant',
+  request: 'Handle issue #42',
+  permissions: {
+    github: {
+      allow: ['issue.list', 'issue.comment'],
+      deny: ['repo.delete'],
+      constraints: { repository: ['acme/app'] }
+    }
+  },
+  authority: {
+    repository: { kind: 'github.repository', value: 'acme/app' }
+  }
+});
+
+const discovery = await task.run(request, () => github.listIssues());
+const issue = task.authorityFrom(discovery, {
+  name: 'issue',
+  kind: 'github.issue.number',
+  from: 'repository',
+  extractor
+});
+
+task.bind({
+  service: 'github',
+  action: 'issue.comment',
+  field: 'issue_number',
+  authority: 'issue'
+});
+```
+
+The low-level Mission and Task Lease APIs remain the source of truth. The facade must never add authority that those lower layers would reject.
+
+## Adoption gate
+
+Do not prioritize another deep authorization subsystem until the following are demonstrated:
+
+- [ ] a new developer can run a meaningful task-first example in under 10 minutes;
+- [ ] at least three real workflow examples exist: coding, support/communications, and operations/finance;
+- [ ] the same task-first API works in-memory and with durable local state;
+- [ ] useful-task completion stays high under the product benchmark;
+- [ ] normal task actions do not trigger unnecessary approvals;
+- [ ] unrelated-resource effects execute zero provider callbacks;
+- [ ] approval/step-up output explains the established authority and requested delta clearly;
+- [ ] at least one external developer uses the package without project-author assistance.
+
+## Utility metrics
+
+Security tests remain required, but product work should additionally track:
+
+```text
+normal task completion rate
+false approval rate
+true authority-delta step-up rate
+unauthorized effect rate
+provider effects per completed task
+integration lines required for a representative workflow
+```
+
+`npm run benchmark:task` is the first deterministic fixture for these metrics. It is not a real-world benchmark and must not be marketed as one. Its purpose is to make utility regressions visible alongside security regressions.
+
+The current fixture target is:
+
+```text
+normal task completion rate = 100%
+false approval rate = 0%
+true authority-delta step-up rate = 100%
+unauthorized effect rate = 0%
+```
+
+Real provider/harness benchmarks should replace or supplement the fixture as the product matures.
+
+## Three product proofs
+
+### Coding agent
+
+Task:
+
+> Fix issue #42 and open a PR. Do not merge or deploy.
+
+Desired authority lineage:
+
+```text
+repository -> issue -> task branch -> changed files -> pull request
+```
+
+Unrelated repositories, issues, merge and deploy remain outside the task.
+
+### Support / communications agent
+
+Task:
+
+> Handle this customer email.
+
+Desired authority lineage:
+
+```text
+email thread -> customer -> meeting / CRM record / reply target
+```
+
+The underlying connected account may have broad access; task authority follows only the customer/resource discovered through the authorized thread.
+
+### Operations / finance agent
+
+Task:
+
+> Resolve this ticket and refund the affected order.
+
+Desired authority lineage:
+
+```text
+ticket -> customer -> order -> payment -> refund <= original payment
+```
+
+This is the strongest long-term proof because it combines resource lineage with an amount ceiling.
+
+## Freeze list
+
+Until the adoption gate moves, the following remain research backlog unless a real workflow proves they are blocking adoption or safety:
+
+- distributed Task Lease databases;
+- generic storage abstraction layers;
+- provider-signed attestation protocols;
+- another token or identity format;
+- a general delegation standard;
+- a proprietary policy DSL;
+- broad OAuth/OIDC platform work;
+- another MCP control plane;
+- A2A protocol implementation;
+- large connector-count expansion;
+- full distributed transaction semantics across arbitrary remote providers.
+
+The existing durability, evidence, transport and credential primitives should be reused rather than deepened by default.
+
+## Boundary discipline
+
+Agent Authority should integrate with identity providers, OAuth systems, MCP gateways, policy engines and agent frameworks rather than compete with all of them.
+
+The intended position is:
+
+```text
+agent reasoning
+      |
+      v
+Agent Authority
+      |
+      v
+existing SDK / MCP / gateway / OAuth / provider
+```
+
+The product wins if that middle layer is small to adopt, preserves useful autonomy, and technically prevents the same standing account permission from becoming unrelated task authority.

package/examples/task-first-github.js

@@ -0,0 +1,102 @@
+import { createTask } from '../src/task.js';
+import { AuthorityApprovalRequiredError } from '../src/guard.js';
+
+const repository = 'Null-Square/agent-authority';
+
+function issueNumberExtractor({ receipt, output } = {}) {
+  if (receipt?.service !== 'github' || receipt?.action !== 'issue.list') {
+    const error = new Error('extractor only accepts github:issue.list');
+    error.code = 'trusted_extractor_operation_mismatch';
+    throw error;
+  }
+  if (!Number.isSafeInteger(output?.selected_issue_number)) {
+    const error = new Error('discovery did not produce a canonical issue number');
+    error.code = 'trusted_extractor_output_invalid';
+    throw error;
+  }
+  return {
+    extractor_id: 'demo.github.selected-issue.v1',
+    selector: 'output.selected_issue_number'
+  };
+}
+
+const task = createTask({
+  principal: 'user:demo',
+  agent: 'agent:demo',
+  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: [repository] }
+    }
+  },
+  authority: {
+    repository: { kind: 'github.repository', value: repository }
+  },
+  bindings: [
+    { service: 'github', action: 'issue.list', field: 'repository', authority: 'repository' },
+    { service: 'github', action: 'issue.comment', field: 'repository', authority: 'repository' }
+  ]
+});
+
+let providerEffects = 0;
+
+console.log('Task: Find issue #42 and leave one comment only on that issue');
+console.log('1. Discover the task resource through an authorized read');
+const discovery = await task.run({
+  service: 'github',
+  action: 'issue.list',
+  context: { repository }
+}, async () => {
+  providerEffects += 1;
+  // Replace this callback with your existing GitHub SDK/provider call.
+  return { selected_issue_number: 42, selected_issue_title: 'Example issue' };
+});
+
+console.log(`   ALLOW -> discovered issue #${discovery.output.selected_issue_number}`);
+
+const issue = task.authorityFrom(discovery, {
+  name: 'issue',
+  kind: 'github.issue.number',
+  from: 'repository',
+  extractor: issueNumberExtractor
+});
+
+task.bind({
+  service: 'github',
+  action: 'issue.comment',
+  field: 'issue_number',
+  authority: 'issue'
+});
+
+console.log(`2. Authority follows the guarded result -> issue #${issue.value}`);
+
+await task.run({
+  service: 'github',
+  action: 'issue.comment',
+  context: { repository, issue_number: issue.value, body: 'Handled by the task.' }
+}, async () => {
+  providerEffects += 1;
+  return { comment_id: 1001 };
+});
+console.log('3. ALLOW -> comment on issue #42 executed');
+
+try {
+  await task.run({
+    service: 'github',
+    action: 'issue.comment',
+    context: { repository, issue_number: 7, body: 'This must not execute.' }
+  }, async () => {
+    providerEffects += 1;
+    return { comment_id: 1002 };
+  });
+} catch (error) {
+  if (!(error instanceof AuthorityApprovalRequiredError)) throw error;
+  const explanation = task.explain(error);
+  console.log('4. STEP-UP -> unrelated issue blocked before the provider callback');
+  console.log(`   ${explanation.summary}`);
+}
+
+console.log(`Provider effects executed: ${providerEffects} (expected: 2)`);
+console.log('PASS -> useful task actions proceed while unrelated account authority does not become task authority');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullsquare/agent-authority",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Task-bounded authority runtime for AI agents: give agents tasks, not standing account permissions.",
   "license": "Apache-2.0",
   "type": "module",
@@ -32,18 +32,20 @@
     "setup": "node src/cli.js setup",
     "doctor": "node src/cli.js doctor",
     "demo": "node examples/demo.js",
+    "demo:task": "node examples/task-first-github.js",
     "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",
+    "benchmark:task": "node benchmarks/task-utility.mjs",
     "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/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: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/task.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-first-github.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 && node --check benchmarks/task-utility.mjs",
     "check:package": "npm pack --dry-run",
-    "check": "npm run check:syntax && npm test && npm run demo:task-lease && npm run check:package"
+    "check": "npm run check:syntax && npm test && npm run demo:task && npm run benchmark:task && npm run demo:task-lease && npm run check:package"
   },
   "dependencies": {
     "@modelcontextprotocol/client": "^2.0.0",
@@ -73,11 +75,12 @@
     "./mcp-server": "./src/mcp-server.js",
     "./sdk": "./src/sdk.js",
     "./storage": "./src/storage.js",
+    "./task": "./src/task.js",
     "./task-lease": "./src/task-lease.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"],
+  "files": ["src", "docs", "examples", "benchmarks", "README.md", "LICENSE", "SECURITY.md", "ROADMAP.md", "CONTRIBUTING.md"],
   "repository": { "type": "git", "url": "git+https://github.com/Null-Square/agent-authority.git" },
   "bugs": { "url": "https://github.com/Null-Square/agent-authority/issues" },
   "homepage": "https://github.com/Null-Square/agent-authority#readme"

package/src/task.js

@@ -0,0 +1,238 @@
+import { randomUUID } from 'node:crypto';
+
+import { AuthorityRuntime } from './index.js';
+import { createTaskLease } from './task-lease.js';
+import { createTaskLeaseGuard } from './guard.js';
+import { createDurableTaskLeaseSession } from './durable-task-lease.js';
+
+function requiredString(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') throw new Error(`${label} is required`);
+  return value.trim();
+}
+
+function principalRecord(value) {
+  if (typeof value === 'string') return { id: requiredString(value, 'principal') };
+  if (value?.id) return structuredClone(value);
+  throw new Error('principal must be an id string or { id } object');
+}
+
+function agentRecord(value) {
+  if (typeof value === 'string') return { id: requiredString(value, 'agent') };
+  if (value?.id) return structuredClone(value);
+  throw new Error('agent must be an id string or { id } object');
+}
+
+function factId(name) {
+  const normalized = requiredString(name, 'authority name');
+  return normalized.startsWith('fact:') ? normalized : `fact:${normalized}`;
+}
+
+function normalizePermissions(permissions) {
+  if (!permissions || typeof permissions !== 'object' || Array.isArray(permissions)) {
+    throw new Error('permissions must be a service -> policy object');
+  }
+
+  const resources = Object.entries(permissions).map(([service, policy]) => {
+    requiredString(service, 'permission service');
+    if (!policy || typeof policy !== 'object' || Array.isArray(policy)) {
+      throw new Error(`permissions.${service} must be an object`);
+    }
+    if (!Array.isArray(policy.allow) || policy.allow.length === 0) {
+      throw new Error(`permissions.${service}.allow must contain at least one action`);
+    }
+    return {
+      service,
+      allow: [...policy.allow],
+      deny: Array.isArray(policy.deny) ? [...policy.deny] : [],
+      constraints: structuredClone(policy.constraints || {})
+    };
+  });
+
+  if (resources.length === 0) throw new Error('permissions must contain at least one service');
+  return resources;
+}
+
+function normalizeAuthorityRoots(authority = {}) {
+  if (!authority || typeof authority !== 'object' || Array.isArray(authority)) {
+    throw new Error('authority must be a name -> value definition object');
+  }
+
+  return Object.entries(authority).map(([name, definition]) => {
+    const normalized = definition && typeof definition === 'object' && !Array.isArray(definition) && Object.hasOwn(definition, 'value')
+      ? definition
+      : { value: definition };
+    if (normalized.value === undefined) throw new Error(`authority.${name}.value is required`);
+    return {
+      fact_id: factId(name),
+      kind: normalized.kind || 'opaque',
+      value: structuredClone(normalized.value),
+      source: normalized.source || 'task-entry'
+    };
+  });
+}
+
+function normalizeBinding(binding) {
+  if (!binding || typeof binding !== 'object') throw new Error('binding must be an object');
+  return {
+    service: requiredString(binding.service, 'binding.service'),
+    action: requiredString(binding.action, 'binding.action'),
+    context_field: requiredString(binding.field || binding.context_field, 'binding.field'),
+    fact_id: factId(binding.authority || binding.fact_id)
+  };
+}
+
+function buildMission({
+  mission,
+  principal,
+  agent,
+  request,
+  objective,
+  permissions,
+  constraints = {},
+  approvals = [],
+  mission_id
+}) {
+  if (mission) return structuredClone(mission);
+
+  return {
+    version: '0.1',
+    mission_id: mission_id || `mission:task:${randomUUID()}`,
+    principal: principalRecord(principal),
+    agent: agentRecord(agent),
+    objective: objective || requiredString(request, 'request'),
+    resources: normalizePermissions(permissions),
+    constraints: structuredClone(constraints || {}),
+    approvals: structuredClone(approvals || [])
+  };
+}
+
+function resultFrom(value) {
+  if (!value) return null;
+  if (value.result?.decision) return value.result;
+  if (value.decision) return value;
+  return null;
+}
+
+/**
+ * Product-facing task authority facade.
+ *
+ * It intentionally does not replace Mission/TaskLease. It composes those
+ * primitives into the small surface most agent developers need: run an effect,
+ * derive named authority from guarded output, bind that authority to later
+ * effects, explain step-up decisions, and complete the task.
+ */
+export class AgentTask {
+  constructor({ lease, runtime = new AuthorityRuntime() } = {}) {
+    if (!lease || typeof lease.evaluate !== 'function') throw new Error('task lease/session is required');
+    if (!runtime || typeof runtime.evaluate !== 'function') throw new Error('authority runtime is required');
+    this._lease = lease;
+    this.runtime = runtime;
+    this.guard = createTaskLeaseGuard({ lease, runtime });
+  }
+
+  get id() { return this._lease.lease_id; }
+  get status() { return this._lease.status; }
+  get mission() { return structuredClone(this._lease.mission); }
+
+  run(request, effect) {
+    return this.guard.run(request, effect);
+  }
+
+  authorityFrom(execution, { name, fact_id, kind = 'opaque', from = [], extractor } = {}) {
+    if (!execution?.receipt || !execution?.evidence || !Object.hasOwn(execution, 'output')) {
+      throw new Error('authorityFrom() requires the result returned by task.run()');
+    }
+    const parents = Array.isArray(from) ? from : [from];
+    return this._lease.deriveFromEvidence({
+      fact_id: factId(fact_id || name),
+      kind,
+      from: parents.map(factId),
+      receipt: execution.receipt,
+      evidence: execution.evidence,
+      output: execution.output,
+      extractor
+    });
+  }
+
+  bind(binding) {
+    return this._lease.bind(normalizeBinding(binding));
+  }
+
+  authority(name) {
+    return this._lease.fact(factId(name));
+  }
+
+  authorities() {
+    return this._lease.listFacts();
+  }
+
+  complete(reason = 'task completed') {
+    return this._lease.complete(reason);
+  }
+
+  explain(value) {
+    const result = resultFrom(value);
+    if (!result) return { decision: 'unknown', code: 'unknown', summary: 'No Agent Authority decision was available.' };
+
+    if (result.code === 'authority_delta_required') {
+      const delta = result.authority_delta || {};
+      const established = delta.current_fact_id ? this._lease.fact(delta.current_fact_id) : null;
+      return {
+        decision: result.decision,
+        code: result.code,
+        summary: `The task established authority for ${JSON.stringify(established?.value)} but this action requested ${JSON.stringify(delta.requested_value)}.`,
+        service: delta.service,
+        action: delta.action,
+        field: delta.context_field,
+        established_authority: established,
+        requested_value: structuredClone(delta.requested_value)
+      };
+    }
+
+    return {
+      decision: result.decision,
+      code: result.code || null,
+      summary: result.reason || 'Agent Authority returned a decision.'
+    };
+  }
+}
+
+export function createTask({
+  mission = null,
+  principal = null,
+  agent = null,
+  request,
+  objective = null,
+  permissions = null,
+  constraints = {},
+  approvals = [],
+  mission_id = null,
+  authority = {},
+  bindings = [],
+  expires_at = null,
+  runtime = new AuthorityRuntime(),
+  store = null
+} = {}) {
+  const resolvedMission = buildMission({
+    mission,
+    principal,
+    agent,
+    request,
+    objective,
+    permissions,
+    constraints,
+    approvals,
+    mission_id
+  });
+
+  const lease = createTaskLease({
+    mission: resolvedMission,
+    request,
+    roots: normalizeAuthorityRoots(authority),
+    bindings: bindings.map(normalizeBinding),
+    expires_at
+  });
+
+  const authorityLease = store ? createDurableTaskLeaseSession({ store, lease }) : lease;
+  return new AgentTask({ lease: authorityLease, runtime });
+}