@nullsquare/agent-authority 0.4.6 → 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-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.6",
+  "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",
@@ -39,11 +39,12 @@
     "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/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: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 && npm run benchmark:task && npm run demo:task-lease && npm run check:package"
   },
@@ -73,6 +74,7 @@
     "./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",

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;

package/src/task.js

@@ -2,7 +2,11 @@ import { randomUUID } from 'node:crypto';
 
 import { AuthorityRuntime } from './index.js';
 import { createTaskLease } from './task-lease.js';
-import { createTaskLeaseGuard } from './guard.js';
+import {
+  AuthorityApprovalRequiredError,
+  AuthorityDeniedError,
+  createTaskLeaseGuard
+} from './guard.js';
 import { createDurableTaskLeaseSession } from './durable-task-lease.js';
 
 function requiredString(value, label) {
@@ -113,13 +117,32 @@ function resultFrom(value) {
   return null;
 }
 
+function assertAllowedExecution(execution) {
+  const decision = execution?.result?.decision;
+  if (decision === 'deny') throw new AuthorityDeniedError(execution);
+  if (decision === 'require_approval') throw new AuthorityApprovalRequiredError(execution);
+  if (decision !== 'allow') {
+    throw new AuthorityDeniedError({
+      ...execution,
+      result: {
+        ...(execution?.result || {}),
+        decision: 'deny',
+        code: 'unknown_decision',
+        reason: 'authority returned an unsupported decision'
+      }
+    });
+  }
+  return execution;
+}
+
 /**
  * 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.
+ * execute through a connected provider, 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() } = {}) {
@@ -134,13 +157,31 @@ export class AgentTask {
   get status() { return this._lease.status; }
   get mission() { return structuredClone(this._lease.mission); }
 
+  /**
+   * Guard an application-owned effect callback.
+   */
   run(request, effect) {
     return this.guard.run(request, effect);
   }
 
+  /**
+   * Execute through an Agent Authority connected-provider runtime.
+   *
+   * Credentials remain inside the runtime/broker. The caller receives only the
+   * sanitized provider output, ALLOW receipt and execution evidence. Deny and
+   * step-up decisions use the same public error classes as run().
+   */
+  async execute(request) {
+    if (typeof this.runtime.executeTaskLease !== 'function') {
+      throw new Error('task runtime does not support connected provider execution');
+    }
+    const execution = await this.runtime.executeTaskLease(this._lease, request);
+    return assertAllowedExecution(execution);
+  }
+
   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()');
+      throw new Error('authorityFrom() requires the result returned by task.run() or task.execute()');
     }
     const parents = Array.isArray(from) ? from : [from];
     return this._lease.deriveFromEvidence({