@nullsquare/agent-authority 0.4.6 → 0.4.8

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.8",
   "description": "Task-bounded authority runtime for AI agents: give agents tasks, not standing account permissions.",
   "license": "Apache-2.0",
   "type": "module",
@@ -33,19 +33,21 @@
     "doctor": "node src/cli.js doctor",
     "demo": "node examples/demo.js",
     "demo:task": "node examples/task-first-github.js",
+    "demo:task-coding": "node examples/task-first-coding.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/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/github-coding.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-first-coding.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"
+    "check": "npm run check:syntax && npm test && npm run demo:task && npm run demo:task-coding && npm run benchmark:task && npm run demo:task-lease && npm run check:package"
   },
   "dependencies": {
     "@modelcontextprotocol/client": "^2.0.0",
@@ -73,11 +75,13 @@
     "./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/github-coding": "./src/providers/github-coding.js",
     "./providers/google": "./src/providers/google.js"
   },
   "files": ["src", "docs", "examples", "benchmarks", "README.md", "LICENSE", "SECURITY.md", "ROADMAP.md", "CONTRIBUTING.md"],

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/providers/github-coding.js

@@ -0,0 +1,101 @@
+function providerError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function safeBranch(value, name = 'branch') {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 255) {
+    throw providerError('trusted_extractor_output_invalid', `${name} must be a non-empty Git branch name`);
+  }
+  const segments = value.split('/');
+  const invalidCharacter = [...value].some((char) => {
+    const code = char.charCodeAt(0);
+    return code <= 32 || code === 127 || '~^:?*[\\'.includes(char);
+  });
+  if (
+    value === '@' ||
+    value.startsWith('/') ||
+    value.endsWith('/') ||
+    value.startsWith('.') ||
+    value.endsWith('.') ||
+    value.includes('//') ||
+    value.includes('..') ||
+    value.includes('@{') ||
+    invalidCharacter ||
+    segments.some((segment) => !segment || segment === '.' || segment === '..' || segment.endsWith('.lock'))
+  ) {
+    throw providerError('trusted_extractor_output_invalid', `${name} is not a safe Git branch name`);
+  }
+  return value;
+}
+
+function safePath(value, name = 'path') {
+  if (typeof value !== 'string' || value.length === 0 || value.startsWith('/') || value.endsWith('/') || value.includes('\\')) {
+    throw providerError('trusted_extractor_output_invalid', `${name} must be a relative repository path`);
+  }
+  const segments = value.split('/');
+  if (
+    segments.some((segment) => !segment || segment === '.' || segment === '..') ||
+    [...value].some((char) => {
+      const code = char.charCodeAt(0);
+      return code === 0 || code === 127;
+    })
+  ) {
+    throw providerError('trusted_extractor_output_invalid', `${name} contains an unsafe path segment`);
+  }
+  return value;
+}
+
+function gitSha(value, name = 'sha') {
+  if (typeof value !== 'string' || !/^[0-9a-f]{40}$/i.test(value)) {
+    throw providerError('trusted_extractor_output_invalid', `${name} must be a 40-character Git SHA`);
+  }
+  return value.toLowerCase();
+}
+
+/**
+ * Establish downstream task authority for the exact branch GitHub confirms was
+ * created by an already-authorized git.ref.create operation.
+ */
+export function githubGitRefCreateBranchAuthorityExtractor({ receipt, output } = {}) {
+  if (receipt?.service !== 'github' || receipt?.action !== 'git.ref.create') {
+    throw providerError(
+      'trusted_extractor_operation_mismatch',
+      'GitHub created-branch extractor only accepts github:git.ref.create receipts'
+    );
+  }
+  if (output?.provider !== 'github') {
+    throw providerError('trusted_extractor_output_invalid', 'normalized GitHub ref output is required');
+  }
+  const branch = safeBranch(output.branch, 'normalized GitHub branch');
+  if (output.ref !== `refs/heads/${branch}`) {
+    throw providerError('trusted_extractor_output_invalid', 'normalized GitHub ref does not match its branch');
+  }
+  gitSha(output.sha, 'normalized GitHub ref sha');
+  return {
+    extractor_id: 'github.git.ref.create.branch.v1',
+    selector: 'output.branch'
+  };
+}
+
+/**
+ * Establish downstream task authority for the exact repository path GitHub
+ * reports as changed by an already-authorized repo.contents.write operation.
+ */
+export function githubContentsWritePathAuthorityExtractor({ receipt, output } = {}) {
+  if (receipt?.service !== 'github' || receipt?.action !== 'repo.contents.write') {
+    throw providerError(
+      'trusted_extractor_operation_mismatch',
+      'GitHub changed-path extractor only accepts github:repo.contents.write receipts'
+    );
+  }
+  if (output?.provider !== 'github' || !output?.body?.content) {
+    throw providerError('trusted_extractor_output_invalid', 'GitHub contents-write output is required');
+  }
+  safePath(output.body.content.path, 'GitHub changed path');
+  return {
+    extractor_id: 'github.repo.contents.write.path.v1',
+    selector: 'output.body.content.path'
+  };
+}

package/src/providers/github.js

@@ -1,6 +1,12 @@
 import { brokeredProviderAdapter } from '../connections.js';
 
-const MUTATING_ACTIONS = new Set(['issue.create', 'issue.comment', 'pull_request.create', 'repo.contents.write']);
+const MUTATING_ACTIONS = new Set([
+  'issue.create',
+  'issue.comment',
+  'git.ref.create',
+  'pull_request.create',
+  'repo.contents.write'
+]);
 const ISSUE_STATES = new Set(['open', 'closed', 'all']);
 
 function required(value, name) {
@@ -21,14 +27,69 @@ function repoParts(context = {}) {
   return { owner, repo };
 }
 
+function repositoryPath(value, name = 'context.path') {
+  const path = String(required(value, name));
+  if (path.startsWith('/') || path.endsWith('/') || path.includes('\\')) {
+    throw providerError('invalid_repository_path', `${name} must be a relative repository path`);
+  }
+  const segments = path.split('/');
+  if (
+    segments.some((segment) => segment === '' || segment === '.' || segment === '..') ||
+    [...path].some((char) => {
+      const code = char.charCodeAt(0);
+      return code === 0 || code === 127;
+    })
+  ) {
+    throw providerError('invalid_repository_path', `${name} contains an unsafe path segment`);
+  }
+  return path;
+}
+
 function encodedPath(path) {
-  return String(path)
+  return repositoryPath(path)
     .split('/')
-    .filter(Boolean)
     .map(encodeURIComponent)
     .join('/');
 }
 
+function branchName(value, name = 'context.branch') {
+  const branch = String(required(value, name));
+  const segments = branch.split('/');
+  const hasInvalidCharacter = [...branch].some((char) => {
+    const code = char.charCodeAt(0);
+    return code <= 32 || code === 127 || '~^:?*[\\'.includes(char);
+  });
+
+  if (
+    branch.length > 255 ||
+    branch === '@' ||
+    branch.startsWith('/') ||
+    branch.endsWith('/') ||
+    branch.startsWith('.') ||
+    branch.endsWith('.') ||
+    branch.includes('//') ||
+    branch.includes('..') ||
+    branch.includes('@{') ||
+    hasInvalidCharacter ||
+    segments.some((segment) => !segment || segment === '.' || segment === '..' || segment.endsWith('.lock'))
+  ) {
+    throw providerError('invalid_git_branch', `${name} is not a safe Git branch name`);
+  }
+  return branch;
+}
+
+function encodedBranch(value, name = 'context.branch') {
+  return branchName(value, name).split('/').map(encodeURIComponent).join('/');
+}
+
+function gitSha(value, name = 'context.sha') {
+  const sha = String(required(value, name));
+  if (!/^[0-9a-f]{40}$/i.test(sha)) {
+    throw providerError('invalid_git_sha', `${name} must be a 40-character Git SHA`);
+  }
+  return sha.toLowerCase();
+}
+
 function issueNumber(value) {
   const number = Number(value);
   if (!Number.isSafeInteger(number) || number <= 0) {
@@ -59,8 +120,8 @@ function buildOperation(request) {
       return { method: 'GET', path: root };
 
     case 'repo.contents.read': {
-      const path = required(context.path, 'context.path');
-      const query = context.ref ? `?ref=${encodeURIComponent(context.ref)}` : '';
+      const path = repositoryPath(context.path);
+      const query = context.ref ? `?ref=${encodeURIComponent(branchName(context.ref, 'context.ref'))}` : '';
       return { method: 'GET', path: `${root}/contents/${encodedPath(path)}${query}` };
     }
 
@@ -86,21 +147,38 @@ function buildOperation(request) {
         body: { body: required(context.body, 'context.body') }
       };
 
+    case 'git.ref.read': {
+      const branch = encodedBranch(context.branch);
+      return { method: 'GET', path: `${root}/git/ref/heads/${branch}` };
+    }
+
+    case 'git.ref.create': {
+      const branch = branchName(context.branch);
+      return {
+        method: 'POST',
+        path: `${root}/git/refs`,
+        body: {
+          ref: `refs/heads/${branch}`,
+          sha: gitSha(context.sha)
+        }
+      };
+    }
+
     case 'pull_request.create':
       return {
         method: 'POST',
         path: `${root}/pulls`,
         body: {
           title: required(context.title, 'context.title'),
-          head: required(context.head, 'context.head'),
-          base: required(context.base, 'context.base'),
+          head: branchName(context.head, 'context.head'),
+          base: branchName(context.base, 'context.base'),
           body: context.body || undefined,
           draft: Boolean(context.draft)
         }
       };
 
     case 'repo.contents.write': {
-      const path = required(context.path, 'context.path');
+      const path = repositoryPath(context.path);
       const content = required(context.content_base64, 'context.content_base64');
       return {
         method: 'PUT',
@@ -109,7 +187,7 @@ function buildOperation(request) {
           message: required(context.message, 'context.message'),
           content,
           sha: context.sha || undefined,
-          branch: context.branch || undefined
+          branch: context.branch ? branchName(context.branch) : undefined
         }
       };
     }
@@ -158,6 +236,40 @@ function normalizeIssueList(request, body) {
   };
 }
 
+function normalizeGitRef(request, body) {
+  const expectedBranch = branchName(request.context?.branch);
+  const ref = typeof body?.ref === 'string' ? body.ref : null;
+  const expectedRef = `refs/heads/${expectedBranch}`;
+  if (ref !== expectedRef) {
+    throw providerError('github_git_ref_invalid', `GitHub ${request.action} response did not match requested branch`);
+  }
+  return {
+    branch: expectedBranch,
+    ref,
+    sha: gitSha(body?.object?.sha, 'provider git ref sha')
+  };
+}
+
+function normalizePullRequest(request, body) {
+  const number = issueNumber(body?.number);
+  const head = typeof body?.head?.ref === 'string'
+    ? branchName(body.head.ref, 'provider pull request head')
+    : branchName(request.context?.head, 'context.head');
+  const base = typeof body?.base?.ref === 'string'
+    ? branchName(body.base.ref, 'provider pull request base')
+    : branchName(request.context?.base, 'context.base');
+  if (head !== branchName(request.context?.head, 'context.head') || base !== branchName(request.context?.base, 'context.base')) {
+    throw providerError('github_pull_request_invalid', 'GitHub pull request response did not match requested head/base');
+  }
+  return {
+    pull_request_number: number,
+    html_url: body?.html_url || null,
+    head,
+    base,
+    draft: Boolean(body?.draft)
+  };
+}
+
 function normalizedOutput(request, response, body) {
   const common = {
     provider: 'github',
@@ -179,6 +291,14 @@ function normalizedOutput(request, response, body) {
     };
   }
 
+  if (request.action === 'git.ref.read' || request.action === 'git.ref.create') {
+    return { ...common, ...normalizeGitRef(request, body) };
+  }
+
+  if (request.action === 'pull_request.create') {
+    return { ...common, ...normalizePullRequest(request, body) };
+  }
+
   return { ...common, body: sanitizeBody(body) };
 }
 
@@ -213,6 +333,49 @@ export function githubIssueListSelectedNumberAuthorityExtractor({ receipt, outpu
   };
 }
 
+/**
+ * Reviewed extractor for the exact commit SHA returned by a guarded Git ref read.
+ */
+export function githubGitRefShaAuthorityExtractor({ receipt, output } = {}) {
+  if (receipt?.service !== 'github' || receipt?.action !== 'git.ref.read') {
+    throw providerError(
+      'trusted_extractor_operation_mismatch',
+      'GitHub ref SHA authority extractor only accepts github:git.ref.read receipts'
+    );
+  }
+  if (output?.provider !== 'github') {
+    throw providerError('trusted_extractor_output_invalid', 'normalized GitHub ref output is required');
+  }
+  gitSha(output.sha, 'normalized GitHub ref sha');
+  branchName(output.branch, 'normalized GitHub ref branch');
+  return {
+    extractor_id: 'github.git.ref.sha.v1',
+    selector: 'output.sha'
+  };
+}
+
+/**
+ * Reviewed extractor for the exact PR number created by a guarded GitHub request.
+ */
+export function githubPullRequestCreateNumberAuthorityExtractor({ receipt, output } = {}) {
+  if (receipt?.service !== 'github' || receipt?.action !== 'pull_request.create') {
+    throw providerError(
+      'trusted_extractor_operation_mismatch',
+      'GitHub PR-number authority extractor only accepts github:pull_request.create receipts'
+    );
+  }
+  if (output?.provider !== 'github') {
+    throw providerError('trusted_extractor_output_invalid', 'normalized GitHub pull request output is required');
+  }
+  issueNumber(output.pull_request_number);
+  branchName(output.head, 'normalized GitHub pull request head');
+  branchName(output.base, 'normalized GitHub pull request base');
+  return {
+    extractor_id: 'github.pull-request.create.number.v1',
+    selector: 'output.pull_request_number'
+  };
+}
+
 export function createGitHubProviderAdapter({ broker, fetchImpl = globalThis.fetch, baseUrl = 'https://api.github.com' } = {}) {
   if (!broker) throw new Error('credential broker is required');
   if (typeof fetchImpl !== 'function') throw new Error('fetch implementation is required');
@@ -273,6 +436,12 @@ export function createGitHubProviderAdapter({ broker, fetchImpl = globalThis.fet
     ) {
       return githubIssueListSelectedNumberAuthorityExtractor;
     }
+    if (request?.service === 'github' && request?.action === 'git.ref.read' && kind === 'github.git.sha') {
+      return githubGitRefShaAuthorityExtractor;
+    }
+    if (request?.service === 'github' && request?.action === 'pull_request.create' && kind === 'github.pull_request.number') {
+      return githubPullRequestCreateNumberAuthorityExtractor;
+    }
     return null;
   };
   return adapter;