@nullsquare/agent-authority 0.4.5 → 0.4.7

package/examples/task-first-finance.js

@@ -0,0 +1,223 @@
+import { AuthorityApprovalRequiredError, AuthorityDeniedError } from '../src/guard.js';
+import { createTask } from '../src/task.js';
+
+const ticketId = 'ticket:4821';
+
+function operationExtractor({ service, action, selector, extractorId, validate }) {
+  return ({ receipt, output } = {}) => {
+    if (receipt?.service !== service || receipt?.action !== action) {
+      const error = new Error(`${extractorId} received the wrong operation`);
+      error.code = 'trusted_extractor_operation_mismatch';
+      throw error;
+    }
+    const value = selector.split('.').slice(1).reduce((current, key) => current?.[key], output);
+    if (!validate(value)) {
+      const error = new Error(`${extractorId} received invalid normalized output`);
+      error.code = 'trusted_extractor_output_invalid';
+      throw error;
+    }
+    return { extractor_id: extractorId, selector };
+  };
+}
+
+const orderIdExtractor = operationExtractor({
+  service: 'helpdesk',
+  action: 'ticket.read',
+  selector: 'output.order_id',
+  extractorId: 'demo.helpdesk.ticket.order-id.v1',
+  validate: (value) => typeof value === 'string' && value.startsWith('order:')
+});
+
+const paymentIdExtractor = operationExtractor({
+  service: 'commerce',
+  action: 'order.read',
+  selector: 'output.payment_id',
+  extractorId: 'demo.commerce.order.payment-id.v1',
+  validate: (value) => typeof value === 'string' && value.startsWith('payment:')
+});
+
+const paymentAmountExtractor = operationExtractor({
+  service: 'payments',
+  action: 'payment.read',
+  selector: 'output.amount_minor',
+  extractorId: 'demo.payments.payment.amount-minor.v1',
+  validate: (value) => Number.isSafeInteger(value) && value >= 0
+});
+
+const paymentCurrencyExtractor = operationExtractor({
+  service: 'payments',
+  action: 'payment.read',
+  selector: 'output.currency',
+  extractorId: 'demo.payments.payment.currency.v1',
+  validate: (value) => typeof value === 'string' && /^[A-Z]{3}$/.test(value)
+});
+
+const task = createTask({
+  principal: 'user:finance-demo',
+  agent: 'agent:finance-demo',
+  request: 'Resolve this support ticket by refunding only its affected payment',
+  permissions: {
+    helpdesk: {
+      allow: ['ticket.read'],
+      constraints: { ticket_id: [ticketId] }
+    },
+    commerce: {
+      allow: ['order.read'],
+      constraints: {}
+    },
+    payments: {
+      allow: ['payment.read', 'refund.create'],
+      deny: ['payment.capture', 'refund.delete'],
+      constraints: {}
+    }
+  },
+  authority: {
+    ticket: { kind: 'helpdesk.ticket', value: ticketId }
+  },
+  bindings: [
+    { service: 'helpdesk', action: 'ticket.read', field: 'ticket_id', authority: 'ticket' },
+    { service: 'commerce', action: 'order.read', field: 'order_id', authority: 'order' },
+    { service: 'payments', action: 'payment.read', field: 'payment_id', authority: 'payment' },
+    { service: 'payments', action: 'refund.create', field: 'payment_id', authority: 'payment' },
+    { service: 'payments', action: 'refund.create', field: 'amount_minor', authority: 'paymentAmount' },
+    { service: 'payments', action: 'refund.create', field: 'currency', authority: 'paymentCurrency' }
+  ]
+});
+
+let ticketReads = 0;
+let orderReads = 0;
+let paymentReads = 0;
+let refunds = 0;
+
+console.log('Task: Resolve one support ticket by refunding only the payment discovered through that ticket');
+
+console.log('1. Read the exact authorized ticket');
+const ticket = await task.run({
+  service: 'helpdesk',
+  action: 'ticket.read',
+  context: { ticket_id: ticketId }
+}, async () => {
+  ticketReads += 1;
+  return { ticket_id: ticketId, customer_id: 'customer:77', order_id: 'order:991' };
+});
+
+const order = task.authorityFrom(ticket, {
+  name: 'order',
+  kind: 'commerce.order',
+  from: 'ticket',
+  extractor: orderIdExtractor
+});
+console.log(`   authority -> ${order.value}`);
+
+console.log('2. Read only the order established by the ticket');
+const orderRead = await task.run({
+  service: 'commerce',
+  action: 'order.read',
+  context: { order_id: order.value }
+}, async () => {
+  orderReads += 1;
+  return { order_id: order.value, payment_id: 'payment:abc123' };
+});
+
+const payment = task.authorityFrom(orderRead, {
+  name: 'payment',
+  kind: 'payments.payment',
+  from: 'order',
+  extractor: paymentIdExtractor
+});
+console.log(`   authority -> ${payment.value}`);
+
+console.log('3. Read only the payment established by the order');
+const paymentRead = await task.run({
+  service: 'payments',
+  action: 'payment.read',
+  context: { payment_id: payment.value }
+}, async () => {
+  paymentReads += 1;
+  return { payment_id: payment.value, amount_minor: 12500, currency: 'USD' };
+});
+
+const amount = task.authorityFrom(paymentRead, {
+  name: 'paymentAmount',
+  kind: 'money.minor-units',
+  from: 'payment',
+  extractor: paymentAmountExtractor
+});
+const currency = task.authorityFrom(paymentRead, {
+  name: 'paymentCurrency',
+  kind: 'money.currency',
+  from: 'payment',
+  extractor: paymentCurrencyExtractor
+});
+console.log(`   authority -> ${amount.value} minor units ${currency.value}`);
+
+console.log('4. Refund exactly the payment established by the authorized chain');
+await task.run({
+  service: 'payments',
+  action: 'refund.create',
+  context: {
+    payment_id: payment.value,
+    amount_minor: amount.value,
+    currency: currency.value
+  }
+}, async () => {
+  refunds += 1;
+  return { refund_id: 'refund:full-1', status: 'succeeded' };
+});
+console.log('   ALLOW -> exact full refund executed');
+
+async function proveRefundBlocked(label, context) {
+  try {
+    await task.run({ service: 'payments', action: 'refund.create', context }, async () => {
+      refunds += 1;
+      return { refund_id: 'must-not-exist' };
+    });
+    throw new Error(`${label} unexpectedly executed`);
+  } catch (error) {
+    if (!(error instanceof AuthorityApprovalRequiredError) || error.code !== 'authority_delta_required') {
+      throw error;
+    }
+    console.log(`   STEP-UP -> ${label} blocked before refund callback`);
+    console.log(`   ${task.explain(error).summary}`);
+  }
+}
+
+console.log('5. Prove unrelated payment and amount changes do not inherit the task authority');
+await proveRefundBlocked('unrelated payment', {
+  payment_id: 'payment:other',
+  amount_minor: amount.value,
+  currency: currency.value
+});
+await proveRefundBlocked('over-refund', {
+  payment_id: payment.value,
+  amount_minor: 15000,
+  currency: currency.value
+});
+await proveRefundBlocked('partial refund under the current exact-binding model', {
+  payment_id: payment.value,
+  amount_minor: 5000,
+  currency: currency.value
+});
+
+if (refunds !== 1) throw new Error(`expected exactly one refund callback, got ${refunds}`);
+
+console.log('6. Complete the task and remove the remaining refund authority');
+task.complete('ticket refund completed');
+try {
+  await task.run({
+    service: 'payments',
+    action: 'refund.create',
+    context: { payment_id: payment.value, amount_minor: amount.value, currency: currency.value }
+  }, async () => {
+    refunds += 1;
+    return { refund_id: 'must-not-run-after-completion' };
+  });
+  throw new Error('post-completion refund unexpectedly executed');
+} catch (error) {
+  if (!(error instanceof AuthorityDeniedError) || error.code !== 'task_lease_completed') throw error;
+  console.log('   DENY -> completed task cannot refund again');
+}
+
+console.log(`Provider-shaped callbacks: tickets=${ticketReads}, orders=${orderReads}, payments=${paymentReads}, refunds=${refunds}`);
+console.log('PASS -> ticket -> order -> payment -> exact refund authority stayed on one evidence-derived lineage');
+console.log('PRODUCT GAP -> partial refunds currently step up because Task Lease bindings are exact equality; derived numeric <= is intentionally not implemented yet');

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/examples/task-first-support.js

@@ -0,0 +1,127 @@
+import { AuthorityApprovalRequiredError, AuthorityDeniedError } from '../src/guard.js';
+import { gmailThreadSenderAuthorityExtractor } from '../src/providers/google.js';
+import { createTask } from '../src/task.js';
+
+const threadId = 'thread:demo-91';
+const calendarId = 'primary';
+
+const task = createTask({
+  principal: 'user:demo',
+  agent: 'agent:support-demo',
+  request: 'Handle the customer request in this email thread and schedule the requested meeting',
+  permissions: {
+    gmail: {
+      allow: ['thread.read'],
+      deny: ['email.delete'],
+      constraints: { thread_id: [threadId] }
+    },
+    calendar: {
+      allow: ['event.create'],
+      deny: ['event.delete'],
+      constraints: { calendar_id: [calendarId] }
+    }
+  },
+  authority: {
+    originThread: { kind: 'gmail.thread', value: threadId },
+    calendar: { kind: 'calendar.id', value: calendarId }
+  },
+  bindings: [
+    { service: 'gmail', action: 'thread.read', field: 'thread_id', authority: 'originThread' },
+    { service: 'calendar', action: 'event.create', field: 'calendar_id', authority: 'calendar' }
+  ]
+});
+
+let gmailReads = 0;
+let calendarMutations = 0;
+
+console.log('Task: Handle one customer email and schedule only the meeting justified by that thread');
+console.log('1. Read the exact task-authorized Gmail thread');
+const read = await task.run({
+  service: 'gmail',
+  action: 'thread.read',
+  context: { thread_id: threadId }
+}, async () => {
+  gmailReads += 1;
+  // Replace with the existing Gmail adapter/SDK call. This shape matches the
+  // normalized output produced by createGoogleProviderAdapter().
+  return {
+    provider: 'gmail',
+    sender_email: 'customer@example.com',
+    thread_id: threadId,
+    message_count: 1
+  };
+});
+console.log(`   ALLOW -> sender discovered: ${read.output.sender_email}`);
+
+const customer = task.authorityFrom(read, {
+  name: 'customerEmail',
+  kind: 'email.address',
+  from: 'originThread',
+  extractor: gmailThreadSenderAuthorityExtractor
+});
+
+task.bind({
+  service: 'calendar',
+  action: 'event.create',
+  field: 'attendee_email',
+  authority: 'customerEmail'
+});
+console.log(`2. Authority follows the guarded Gmail result -> ${customer.value}`);
+
+const meetingContext = {
+  calendar_id: calendarId,
+  attendee_email: customer.value,
+  start_time: '2030-01-15T10:00:00Z',
+  end_time: '2030-01-15T10:30:00Z'
+};
+
+const meeting = await task.run({
+  service: 'calendar',
+  action: 'event.create',
+  context: meetingContext
+}, async () => {
+  calendarMutations += 1;
+  return { provider: 'calendar', event_id: 'event:customer-demo' };
+});
+console.log(`3. ALLOW -> Calendar event ${meeting.output.event_id} for ${customer.value}`);
+
+try {
+  await task.run({
+    service: 'calendar',
+    action: 'event.create',
+    context: { ...meetingContext, attendee_email: 'other@example.com' }
+  }, async () => {
+    calendarMutations += 1;
+    return { event_id: 'must-not-exist' };
+  });
+  throw new Error('unrelated attendee 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 mutation');
+  console.log(`   ${task.explain(error).summary}`);
+}
+
+if (calendarMutations !== 1) {
+  throw new Error(`expected exactly one Calendar mutation, got ${calendarMutations}`);
+}
+
+task.complete('customer request handled');
+try {
+  await task.run({
+    service: 'calendar',
+    action: 'event.create',
+    context: meetingContext
+  }, async () => {
+    calendarMutations += 1;
+    return { event_id: '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 -> task completion removed the meeting authority');
+}
+
+console.log(`Provider-shaped callbacks: gmail_reads=${gmailReads}, calendar_mutations=${calendarMutations}`);
+console.log('PASS -> one authorized email established exactly one downstream Calendar attendee');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullsquare/agent-authority",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Task-bounded authority runtime for AI agents: give agents tasks, not standing account permissions.",
   "license": "Apache-2.0",
   "type": "module",
@@ -32,18 +32,21 @@
     "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",
+    "demo:connected-github": "node examples/quickstart-github-connected.mjs",
+    "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 examples/quickstart-github-connected.mjs && 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",
@@ -71,13 +74,15 @@
     "./mcp-gateway": "./src/mcp-gateway.js",
     "./mcp-remote": "./src/mcp-remote.js",
     "./mcp-server": "./src/mcp-server.js",
+    "./runtime-env": "./src/runtime-env.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/cli.js

@@ -6,7 +6,7 @@ import { createAgentToken, parseTtl } from './agent-auth.js';
 import { createRuntimeEnvironment } from './runtime-env.js';
 import { authorityHome, ensureAuthorityHome, loadConfig, saveConfig } from './storage.js';
 
-const VERSION = '0.3.0';
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 
 function fail(message, code = 1) {
   console.error(`error: ${message}`);
@@ -144,7 +144,7 @@ async function connectionsCommand(args) {
 }
 
 async function connectGitHub(args) {
-  if (!has(args, '--token-stdin')) throw new Error('GitHub currently requires --token-stdin; browser OAuth/PKCE is the next provider-onboarding milestone');
+  if (!has(args, '--token-stdin')) throw new Error('GitHub local onboarding currently requires --token-stdin');
   const home = homeFrom(args);
   const env = createRuntimeEnvironment({ home });
   const token = await readStdinSecret();
@@ -184,7 +184,7 @@ async function disconnectGitHub(args) {
   const accountId = flag(args, '--account', 'default');
   const result = env.broker.disconnect({ principal_id: env.config.principal_id, service: 'github', account_id: accountId });
   if (!result) throw new Error(`GitHub account ${accountId} is not connected`);
-  console.log(`✓ GitHub ${accountId} disconnected and local credential removed`);
+  console.log(`✓ GitHub ${result.account_id} disconnected and local credential removed`);
 }
 
 async function agentCommand(args) {

package/src/connections.js

@@ -116,8 +116,19 @@ export class CredentialBroker {
     return connection;
   }
 
+  resolveConnection({ principal_id, service, account_id = 'default' }) {
+    const exact = this.connections.get({ principal_id, service, account_id });
+    if (exact) return exact;
+    if (account_id !== 'default') return null;
+
+    const candidates = this.connections.list(principal_id)
+      .filter((connection) => connection.service === service && connection.status === 'active');
+
+    return candidates.length === 1 ? candidates[0] : null;
+  }
+
   getConnection({ principal_id, service, account_id = 'default' }) {
-    return this.connections.get({ principal_id, service, account_id });
+    return this.resolveConnection({ principal_id, service, account_id });
   }
 
   listConnections(principal_id) {
@@ -125,7 +136,7 @@ export class CredentialBroker {
   }
 
   resolveInternal({ principal_id, service, account_id = 'default' }) {
-    const connection = this.connections.get({ principal_id, service, account_id });
+    const connection = this.resolveConnection({ principal_id, service, account_id });
     if (!connection || connection.status !== 'active') {
       const error = new Error(`no active ${service} connection for this principal`);
       error.code = 'connection_required';
@@ -139,10 +150,14 @@ export class CredentialBroker {
   }
 
   disconnect({ principal_id, service, account_id = 'default' }) {
-    const current = this.connections.get({ principal_id, service, account_id });
+    const current = this.resolveConnection({ principal_id, service, account_id });
     if (!current) return null;
     this.secrets.delete(current.credential_ref);
-    const connection = this.connections.disconnect({ principal_id, service, account_id });
+    const connection = this.connections.disconnect({
+      principal_id,
+      service,
+      account_id: current.account_id
+    });
     if (!connection) return null;
     const { credential_ref, ...safe } = connection;
     return safe;