@nullsquare/agent-authority 0.4.7 → 0.4.8

package/README.md

@@ -8,9 +8,9 @@
 
 **Agent Authority is a small execution layer that lets an agent use existing account permissions only for the task the user actually gave it.**
 
-[Quickstart](docs/quickstart.md) · [Task-first API](#task-first-api) · [Product proof gate](docs/product-proof.md) · [Task Leases](docs/task-leases.md) · [Durability](docs/durable-task-leases.md) · [Evidence](docs/evidence.md) · [Transport invariance](docs/transport-invariance.md) · [Roadmap](ROADMAP.md)
+[Quickstart](docs/quickstart.md) · [Connected GitHub](docs/connected-github.md) · [Task-first API](#task-first-api) · [Product proof gate](docs/product-proof.md) · [Task Leases](docs/task-leases.md) · [Durability](docs/durable-task-leases.md) · [Evidence](docs/evidence.md) · [Transport invariance](docs/transport-invariance.md) · [Roadmap](ROADMAP.md)
 
-> **Status: public pre-alpha / v0.4.6 Developer Preview on npm.** The task-first API is published as `@nullsquare/agent-authority/task`. Agent Authority is not production-ready yet.
+> **Status: public pre-alpha / v0.4.7 Developer Preview on npm.** The task-first API is published as `@nullsquare/agent-authority/task`. Agent Authority is not production-ready yet.
 
 </div>
 
@@ -79,7 +79,7 @@ PASS -> useful task work ran; unrelated standing permission did not become task
 
 The quickstart uses the real published `createTask()` API and reviewed GitHub authority extractor. Only the provider callback is a local provider-shaped fixture so the first run needs no account.
 
-An automated blank-project gate independently installed `@nullsquare/agent-authority@0.4.6` from npm on Node 20 and ran this exact file successfully. That proves the current published package supports the documented path; it does **not** replace the still-open first-time-human under-10-minute adoption test.
+The fresh-install path is continuously checked from blank Node 20 consumers against the public npm package. That proves the published package supports the documented task-first surface; it does **not** replace the still-open first-time-human under-10-minute adoption test.
 
 ### Next: make one real GitHub call, still with no credential
 
@@ -103,9 +103,51 @@ PASS -> broader standing repo.read permission could not reach an unrelated repos
 
 This deliberately models the account/app capability as broader than the task. Mission-level `repo.read` can read repositories generally, while the Task authority root allows this task to reach only `Null-Square/agent-authority`. The first request makes one real public GitHub `fetch()`; the unrelated repository is stopped before a second network call.
 
-A separate blank-project CI gate has passed this exact live path against npm `0.4.6`. Authenticated/private-repository onboarding remains separate follow-on work.
+### Then: connect GitHub without putting the credential in task context
 
-See [Fresh-install quickstart](docs/quickstart.md).
+v0.4.7 adds the connected-provider task path. Initialize the local runtime and pipe a GitHub credential on stdin:
+
+```bash
+npx agent-authority setup
+printf %s "$GITHUB_TOKEN" | npx agent-authority connect github --token-stdin
+```
+
+Then an application can use the same task-first surface with broker-owned provider execution:
+
+```js
+import { createRuntimeEnvironment } from '@nullsquare/agent-authority/runtime-env';
+import { createTask } from '@nullsquare/agent-authority/task';
+
+const env = createRuntimeEnvironment();
+
+const task = createTask({
+  principal: env.config.principal_id,
+  agent: 'agent:assistant',
+  request: 'Inspect only acme/private',
+  permissions: {
+    github: { allow: ['repo.read'], constraints: {} }
+  },
+  authority: {
+    repository: { kind: 'github.repository', value: 'acme/private' }
+  },
+  bindings: [
+    { service: 'github', action: 'repo.read', field: 'repository', authority: 'repository' }
+  ],
+  runtime: env.runtime
+});
+
+const result = await task.execute({
+  service: 'github',
+  action: 'repo.read',
+  context: { repository: 'acme/private' }
+});
+```
+
+`task.run(request, callback)` is for application-owned SDK/provider effects. `task.execute(request)` is for Agent Authority connected-provider execution, where credential resolution stays behind the broker boundary. Both use the same Task Lease semantics and the same deny/step-up error model.
+
+The connected GitHub CI proof packs the candidate into a fresh Node 20 consumer, creates a fresh Agent Authority home, pipes the repository's GitHub Actions installation token through stdin, confirms no plaintext token appears under the home, executes one authorized live GitHub request, and blocks an unrelated repository at the Task Lease. A fine-grained PAT or GitHub App token can use the same path for repositories that credential is allowed to access. Public CI does **not** claim independent access to an unrelated private repository.
+
+See [Fresh-install quickstart](docs/quickstart.md) and [Connected GitHub](docs/connected-github.md).
 
 ## Task-first API
 
@@ -195,6 +237,8 @@ Example output:
 The task established authority for 42 but this action requested 7.
 ```
 
+For a connected provider, the same error/explanation flow applies to `task.execute(request)`. Successful connected execution also returns an ALLOW receipt and execution evidence, so reviewed provider outputs can feed `task.authorityFrom()` without copying the provider credential into the task.
+
 The task-first API is a facade over the existing Mission, Task Lease, execution-evidence and guard primitives. It does not weaken or replace them.
 
 ## Run the product demo
@@ -313,7 +357,7 @@ MCP gateway
 brokered provider execution
 ```
 
-A real Vercel AI SDK `ToolLoopAgent` integration also exercises the protected-tool boundary. See [Transport invariance](docs/transport-invariance.md).
+The task-first facade can now use both application-owned execution (`task.run`) and broker-owned connected execution (`task.execute`) without changing the underlying Task Lease. A real Vercel AI SDK `ToolLoopAgent` integration also exercises the protected-tool boundary. See [Transport invariance](docs/transport-invariance.md) and [Connected execution](docs/connected-execution-api.md).
 
 ## Durability
 
@@ -357,10 +401,12 @@ See [Durable Task Leases](docs/durable-task-leases.md).
 - automatic durable Task Lease sessions;
 - task-first public facade and deterministic utility regression gate;
 - self-contained support/communications and operations/finance product proofs;
-- blank-project fixture quickstart against the current npm package;
+- blank-project fixture quickstart against the public npm package;
 - blank-project real public GitHub onboarding with broader standing permission and narrower task authority;
+- encrypted connected-GitHub onboarding through `task.execute()` with the credential kept broker-internal;
+- safe sole-account default resolution while multiple connected accounts remain explicit/fail closed;
 - Node 20/22 CI, coverage, packed-consumer validation and CodeQL;
-- independent npm registry consumer verification.
+- independent npm registry consumer verification, including v0.4.7 connected execution.
 
 The lower-level evidence is documented under `docs/` and remains available for security review.
 
@@ -390,7 +436,8 @@ This is still a validation implementation.
 - Source-data changes do not yet automatically invalidate already-derived authority.
 - Approved authority deltas are surfaced but not automatically applied into a live durable task.
 - Current Task Lease bindings are exact equality. The finance proof therefore steps up for a partial refund as well as an over-refund; a derived numeric ceiling remains an evidence-driven product question rather than a general policy language.
-- Public GitHub onboarding is credential-free for read-only public repositories; authenticated/private-repository onboarding and production OAuth/KMS UX remain incomplete.
+- The local encrypted credential vault and stdin GitHub connection are trusted-host developer onboarding, not production OAuth/KMS credential lifecycle.
+- Public CI proves authenticated connected execution against the current repository but does not independently demonstrate access to an unrelated private repository.
 - Remote authenticated deployment and production approval UX remain incomplete.
 
 These are real limitations. They are not reasons to build every possible infrastructure layer before product adoption is proven.

package/ROADMAP.md

@@ -30,8 +30,9 @@ The engine has enough depth to test whether developers actually want this layer.
 - [x] task-first facade over Mission + Task Lease + Guard
 - [x] explicit service permissions without requiring hand-authored Mission JSON
 - [x] named task authority roots
-- [x] `task.run()` guarded effect boundary
-- [x] `task.authorityFrom()` strict evidence-derived authority
+- [x] `task.run()` guarded application-owned effect boundary
+- [x] `task.execute()` connected-provider effect boundary with broker-owned credential resolution
+- [x] `task.authorityFrom()` strict evidence-derived authority from `run()` or successful `execute()` output
 - [x] task-first binding of named authority to later effects
 - [x] human-readable authority-delta explanation
 - [x] same task-first calls can opt into durable local state by adding a store
@@ -42,6 +43,7 @@ The engine has enough depth to test whether developers actually want this layer.
 - [x] self-contained operations/finance proof: ticket -> order -> payment -> exact full refund
 - [x] automated blank-project quickstart against the current published npm package
 - [x] blank-project real-provider quickstart: broad standing `repo.read` -> one task-authorized public GitHub repository
+- [x] encrypted connected GitHub onboarding: stdin credential -> local vault/broker -> `task.execute()` -> live provider request
 - [ ] coding workflow: issue -> branch -> files -> PR, with merge/deploy outside authority
 - [ ] support/communications expansion: customer -> meeting + reply/CRM, or live task-first Google Actions proof
 - [ ] bounded finance refund: derived payment amount can authorize a smaller refund without authorizing an over-refund
@@ -54,9 +56,11 @@ The support/communications proof uses the same task-first API across Gmail and C
 
 The operations/finance proof keeps one evidence-derived chain from support ticket -> order -> payment -> exact refund. The exact payment ID, amount in minor units, and currency are all bound before the refund callback can execute. Unrelated payment, over-refund, wrong currency, partial refund under the current equality model, and post-completion refund all execute zero additional refund callbacks. This proof exposed a deliberate product gap: current bindings are exact equality, so a legitimate partial refund also steps up. Do not add a general expression language; add a narrow derived numeric ceiling only when real workflow/adoption evidence shows partial refunds are required.
 
-The fixture fresh-install quickstart is independently exercised from a blank Node 20 project against the latest public npm package. The passing proof installed `@nullsquare/agent-authority@0.4.6`, did not install the optional AI SDK, allowed the exact issue #42 effect, stepped up unrelated issue #7, and observed no unrelated callback. This is automated compatibility evidence, not a substitute for the still-open first-time-human under-10-minute test.
+The fixture fresh-install quickstart is independently exercised from blank Node 20 projects against the public npm package. The release-facing registry verifier for v0.4.7 installs that exact package, confirms the optional AI SDK is absent, and runs the ordinary public consumer contract plus the connected-execution consumer contract. This is automated compatibility evidence, not a substitute for the still-open first-time-human under-10-minute test.
 
-The live fresh-install quickstart goes one step further from another blank Node 20 project: Mission-level `github:repo.read` remains broader than the task, Task authority binds that action to `Null-Square/agent-authority`, one real public GitHub API call succeeds, and `octocat/Hello-World` produces `authority_delta_required` before a second `fetch()` can run. No credential is required for the default public-repository path. Authenticated/private-repository onboarding remains separate follow-on work.
+The live credential-free quickstart keeps Mission-level `github:repo.read` broader than the task, binds Task authority to `Null-Square/agent-authority`, performs one real public GitHub API call, and produces `authority_delta_required` for `octocat/Hello-World` before a second `fetch()` can run.
+
+v0.4.7 adds the authenticated connected path without creating an OAuth platform: a GitHub credential is accepted on stdin, stored in the encrypted trusted-local-host vault, resolved only inside the broker/provider runtime, and used by `task.execute()`. The live CI proof uses the repository's GitHub Actions installation token, confirms the raw token is not present in public task/connection state or plaintext under the Agent Authority home, executes the task-authorized repository read, and blocks the unrelated repository before connected provider execution. A fine-grained PAT or GitHub App token can use the same path for repositories it is allowed to access; public CI does not independently claim access to an unrelated private repository.
 
 Current utility regression metrics:
 
@@ -158,6 +162,7 @@ Do **not** build a general semantic policy language around this primitive.
 - [x] same Task Lease through direct guard/SDK execution
 - [x] same Task Lease through MCP gateway
 - [x] same Task Lease through brokered provider execution
+- [x] task-first connected-provider execution through `task.execute()`
 - [x] real Vercel AI SDK protected-tool path
 - [x] interoperability/adversarial vectors across transports
 
@@ -169,7 +174,10 @@ Prioritize only the UX needed by successful P0 workflows.
 
 - [x] credential-free fresh-install quickstart validated against the current public npm package
 - [x] one low-friction real provider onboarding path: public GitHub read from a blank npm project
-- [ ] authenticated/private-provider onboarding path
+- [x] authenticated connected-provider onboarding path: GitHub stdin credential + encrypted local vault + `task.execute()`
+- [x] safe sole-account default resolution; multiple connected accounts require explicit selection
+- [ ] independent private-repository onboarding proof with a credential that has private-repo access
+- [ ] production provider credential lifecycle / OAuth or GitHub App onboarding where real users require it
 - [ ] compact approval UI showing the exact authority delta
 - [ ] automatic short-lived agent session bootstrap where needed
 - [ ] framework integration starter focused on task-first API

package/docs/npm-release.md

@@ -13,14 +13,14 @@ Before any publication:
 After publication, verify from a fresh project with:
 
 ```bash
-npm install @nullsquare/agent-authority@0.4.6
+npm install @nullsquare/agent-authority@0.4.7
 ```
 
-Then run the same consumer smoke flow through the registry-installed package. Registry verification is part of the release gate; a successful `npm publish` command alone is not sufficient.
+Then run the same consumer smoke flows through the registry-installed package. Registry verification is part of the release gate; a successful `npm publish` command alone is not sufficient.
 
 The repository includes `.github/workflows/verify-npm-registry.yml`, which verifies registry visibility, a clean Node.js 20 install, and current public behavior from the registry artifact.
 
-For v0.4.6 the consumer exercises:
+For v0.4.7 the registry consumer exercises the existing v0.4.6 contract plus connected provider execution:
 
 - `createTask()` from `@nullsquare/agent-authority/task`;
 - explicit task permissions and named authority roots;
@@ -30,11 +30,15 @@ For v0.4.6 the consumer exercises:
 - execution evidence and the reviewed Google/GitHub authority extractors;
 - `ExecutingAuthorityRuntime.executeTaskLease()` and `MissionMcpGateway` transport surfaces;
 - `JsonFileTaskLeaseStore`, `DurableTaskLeaseSession`, and the lower-level Task Lease APIs;
+- `task.execute(request)` for connected-provider execution;
+- the public `@nullsquare/agent-authority/runtime-env` export;
+- safe sole-account connection resolution while multiple active accounts remain ambiguous/fail closed;
+- connected execution where the credential is broker-internal, the task-authorized resource executes, and an unrelated resource is blocked before a second provider call;
 - the requirement that the optional `ai` package is not installed as a production dependency.
 
-This makes the registry artifact verification cover the product-facing task-first API and the lower-level durability/evidence/transport surfaces it composes, rather than checking export names alone.
+This makes the registry artifact verification cover both application-owned task effects (`task.run`) and broker-owned connected provider effects (`task.execute`) together with the durability/evidence/transport surfaces they compose.
 
-The v0.4.6 independent registry verification passed after publication: npm visibility succeeded and the fresh Node.js 20 registry-installed consumer executed the current task-first + durable behavior smoke successfully.
+The v0.4.7 independent registry verification passed after publication: npm visibility succeeded, a fresh Node.js 20 consumer installed the exact `@nullsquare/agent-authority@0.4.7` artifact, the optional AI SDK was absent, and both the ordinary package smoke and connected-execution smoke passed.
 
 The deterministic task utility fixture is also part of the source-release gate. It currently requires:
 
@@ -52,7 +56,7 @@ This fixture is a regression gate, not a real-world performance benchmark.
 Publishing to the public npm registry does not automatically create either a GitHub Release or a GitHub Packages entry.
 
 - **npm registry** — `npm publish --access public` publishes `@nullsquare/agent-authority` to `registry.npmjs.org` / npmjs.com. This is the package users install with `npm install`.
-- **GitHub Releases** — a separate GitHub object, normally backed by a Git tag such as `v0.4.6`. A release must be created explicitly or by release automation.
+- **GitHub Releases** — a separate GitHub object, normally backed by a Git tag such as `v0.4.7`. A release must be created explicitly or by release automation.
 - **GitHub Packages** — a separate package registry. It only appears when the package is published to GitHub's npm registry (`npm.pkg.github.com`); publishing to npmjs.com does not populate it.
 
 Agent Authority currently uses npmjs.com as its public package registry. Therefore an empty GitHub **Packages** section is expected unless the project intentionally adopts dual publication. A GitHub **Release** is still useful for source-release discoverability and should track published versions, but it is independent from npm publication.

package/docs/release-v0.4.7.md

@@ -1,8 +1,8 @@
-# v0.4.7 connected-execution candidate
+# v0.4.7 connected execution
 
-This candidate closes a concrete adoption gap between the task-first API and the existing credential broker/provider runtime.
+v0.4.7 closes a concrete adoption gap between the task-first API and the existing credential broker/provider runtime.
 
-## Candidate changes
+## What shipped
 
 - `task.execute(request)` executes through an `ExecutingAuthorityRuntime` while preserving the current Task Lease as the narrowest authority object.
 - connected deny/step-up outcomes use the same public error classes as `task.run()`.
@@ -11,19 +11,28 @@ This candidate closes a concrete adoption gap between the task-first API and the
 - a sole active provider account can be resolved when requests omit `account_id`; multiple active accounts remain ambiguous and fail closed.
 - default disconnect can remove that sole connection without requiring the caller to know an auto-detected provider account ID.
 - the connected GitHub quickstart proves the local encrypted vault + credential broker + live provider path without copying credentials into task/model context.
+- the CLI version is now derived from `package.json` instead of a stale hard-coded constant.
 
 ## Security boundary
 
-This does not create a GitHub token, OAuth flow, GitHub App, KMS, or new identity format. Provider-side least privilege still comes from GitHub. Agent Authority adds a task boundary underneath that connected account authority.
+This release does not create a GitHub token, OAuth flow, GitHub App, KMS, or new identity format. Provider-side least privilege still comes from GitHub. Agent Authority adds a task boundary underneath that connected account authority.
 
 The local encrypted vault remains a trusted-local-host developer reference backend.
 
-## Release gate
+## Release evidence
 
-Before version publication:
+The exact v0.4.7 candidate passed:
 
-- unit/adversarial tests must prove credential isolation and zero provider execution on task authority delta;
-- packed consumer must import and execute the new public surfaces;
-- live connected GitHub workflow must pass through the encrypted local runtime;
-- Node 20/22, coverage, AI SDK, existing live GitHub proofs and CodeQL must remain green;
-- registry verification must be performed after npm publication before the public release marker is updated.
+- Node 20 and Node 22 test lanes;
+- coverage;
+- packed-package consumer smoke;
+- connected-execution packed consumer smoke;
+- Vercel AI SDK integration;
+- live GitHub read proof;
+- live evidence-derived GitHub mutation proof;
+- encrypted connected-GitHub onboarding proof;
+- CodeQL.
+
+After merge, the independent `Verify npm registry` workflow resolved version `0.4.7`, confirmed it was visible on npm, installed that exact registry artifact into a fresh Node 20 consumer, confirmed the optional AI SDK was absent, and successfully ran both the ordinary public package smoke and the connected-execution smoke.
+
+That registry proof is the basis for marking v0.4.7 published.

package/examples/task-first-coding.js

@@ -0,0 +1,238 @@
+import { AuthorityApprovalRequiredError, AuthorityDeniedError } from '../src/guard.js';
+import {
+  githubGitRefShaAuthorityExtractor,
+  githubIssueListSelectedNumberAuthorityExtractor,
+  githubPullRequestCreateNumberAuthorityExtractor
+} from '../src/providers/github.js';
+import {
+  githubContentsWritePathAuthorityExtractor,
+  githubGitRefCreateBranchAuthorityExtractor
+} from '../src/providers/github-coding.js';
+import { createTask } from '../src/task.js';
+
+const repository = 'acme/app';
+const marker = 'coding-fixture-42';
+const baseBranch = 'main';
+const plannedBranch = 'agent/issue-42';
+const targetPath = 'src/auth.js';
+const baseSha = 'a'.repeat(40);
+
+const task = createTask({
+  principal: 'user:demo',
+  agent: 'agent:coder',
+  request: 'Fix the selected issue on one task branch, change only src/auth.js, and open a draft PR. Do not merge or deploy.',
+  permissions: {
+    github: {
+      allow: ['issue.list', 'git.ref.read', 'git.ref.create', 'repo.contents.write', 'pull_request.create'],
+      deny: ['pull_request.merge', 'repo.delete'],
+      constraints: {}
+    }
+  },
+  authority: {
+    repository: { kind: 'github.repository', value: repository },
+    fixture_marker: { kind: 'github.issue.marker', value: marker },
+    base_branch: { kind: 'github.git.branch', value: baseBranch },
+    planned_branch: { kind: 'github.git.branch.intent', value: plannedBranch },
+    target_path: { kind: 'github.repository.path.intent', value: targetPath }
+  },
+  bindings: [
+    { service: 'github', action: 'issue.list', field: 'repository', authority: 'repository' },
+    { service: 'github', action: 'issue.list', field: 'fixture_marker', authority: 'fixture_marker' },
+    { service: 'github', action: 'git.ref.read', field: 'repository', authority: 'repository' },
+    { service: 'github', action: 'git.ref.read', field: 'branch', authority: 'base_branch' },
+    { service: 'github', action: 'git.ref.create', field: 'repository', authority: 'repository' },
+    { service: 'github', action: 'git.ref.create', field: 'branch', authority: 'planned_branch' },
+    { service: 'github', action: 'git.ref.create', field: 'sha', authority: 'base_sha' },
+    { service: 'github', action: 'git.ref.create', field: 'issue_number', authority: 'issue' },
+    { service: 'github', action: 'repo.contents.write', field: 'repository', authority: 'repository' },
+    { service: 'github', action: 'repo.contents.write', field: 'branch', authority: 'task_branch' },
+    { service: 'github', action: 'repo.contents.write', field: 'path', authority: 'target_path' },
+    { service: 'github', action: 'repo.contents.write', field: 'issue_number', authority: 'issue' },
+    { service: 'github', action: 'pull_request.create', field: 'repository', authority: 'repository' },
+    { service: 'github', action: 'pull_request.create', field: 'head', authority: 'task_branch' },
+    { service: 'github', action: 'pull_request.create', field: 'base', authority: 'base_branch' },
+    { service: 'github', action: 'pull_request.create', field: 'issue_number', authority: 'issue' },
+    { service: 'github', action: 'pull_request.create', field: 'changed_path', authority: 'changed_file' }
+  ]
+});
+
+let reads = 0;
+let mutations = 0;
+
+const discovery = await task.run({
+  service: 'github',
+  action: 'issue.list',
+  context: { repository, fixture_marker: marker, state: 'open' }
+}, async () => {
+  reads += 1;
+  return {
+    provider: 'github',
+    selected_issue_number: 42,
+    selected_issue_title: 'Fix auth edge case',
+    selected_issue_match_count: 1,
+    selected_issue_marker: marker
+  };
+});
+const issue = task.authorityFrom(discovery, {
+  name: 'issue',
+  kind: 'github.issue.number',
+  from: ['repository', 'fixture_marker'],
+  extractor: githubIssueListSelectedNumberAuthorityExtractor
+});
+console.log(`DISCOVER -> issue #${issue.value} became task authority`);
+
+const base = await task.run({
+  service: 'github',
+  action: 'git.ref.read',
+  context: { repository, branch: baseBranch }
+}, async () => {
+  reads += 1;
+  return { provider: 'github', branch: baseBranch, ref: `refs/heads/${baseBranch}`, sha: baseSha };
+});
+const baseAuthority = task.authorityFrom(base, {
+  name: 'base_sha',
+  kind: 'github.git.sha',
+  from: ['repository', 'base_branch'],
+  extractor: githubGitRefShaAuthorityExtractor
+});
+
+const branch = await task.run({
+  service: 'github',
+  action: 'git.ref.create',
+  context: { repository, branch: plannedBranch, sha: baseAuthority.value, issue_number: issue.value }
+}, async () => {
+  mutations += 1;
+  return { provider: 'github', branch: plannedBranch, ref: `refs/heads/${plannedBranch}`, sha: baseSha };
+});
+const taskBranch = task.authorityFrom(branch, {
+  name: 'task_branch',
+  kind: 'github.git.branch',
+  from: ['planned_branch', 'issue', 'base_sha'],
+  extractor: githubGitRefCreateBranchAuthorityExtractor
+});
+console.log(`ALLOW -> created only task branch ${taskBranch.value}`);
+
+async function expectStepUp(request, label) {
+  const before = mutations;
+  try {
+    await task.run(request, async () => { mutations += 1; });
+    throw new Error(`${label} unexpectedly executed`);
+  } catch (error) {
+    if (!(error instanceof AuthorityApprovalRequiredError)) throw error;
+    if (mutations !== before) throw new Error(`${label} reached the provider callback`);
+    console.log(`STEP-UP -> ${label}: ${task.explain(error).summary}`);
+  }
+}
+
+await expectStepUp({
+  service: 'github',
+  action: 'repo.contents.write',
+  context: {
+    repository,
+    branch: baseBranch,
+    path: targetPath,
+    issue_number: issue.value,
+    message: 'wrong branch',
+    content_base64: 'd3Jvbmc='
+  }
+}, 'write directly to main');
+
+await expectStepUp({
+  service: 'github',
+  action: 'repo.contents.write',
+  context: {
+    repository,
+    branch: taskBranch.value,
+    path: 'src/admin.js',
+    issue_number: issue.value,
+    message: 'wrong file',
+    content_base64: 'd3Jvbmc='
+  }
+}, 'change an unrelated file');
+
+const write = await task.run({
+  service: 'github',
+  action: 'repo.contents.write',
+  context: {
+    repository,
+    branch: taskBranch.value,
+    path: targetPath,
+    issue_number: issue.value,
+    message: 'Fix issue #42',
+    content_base64: Buffer.from('export const fixed = true;\n').toString('base64')
+  }
+}, async () => {
+  mutations += 1;
+  return {
+    provider: 'github',
+    body: { content: { path: targetPath, sha: 'b'.repeat(40) }, commit: { sha: 'c'.repeat(40) } }
+  };
+});
+const changedFile = task.authorityFrom(write, {
+  name: 'changed_file',
+  kind: 'github.repository.path',
+  from: ['task_branch', 'issue', 'target_path'],
+  extractor: githubContentsWritePathAuthorityExtractor
+});
+console.log(`ALLOW -> changed only ${changedFile.value} on ${taskBranch.value}`);
+
+await expectStepUp({
+  service: 'github',
+  action: 'pull_request.create',
+  context: {
+    repository,
+    head: 'agent/unrelated',
+    base: baseBranch,
+    issue_number: issue.value,
+    changed_path: changedFile.value,
+    title: 'Wrong PR head',
+    draft: true
+  }
+}, 'open PR from another branch');
+
+const pr = await task.run({
+  service: 'github',
+  action: 'pull_request.create',
+  context: {
+    repository,
+    head: taskBranch.value,
+    base: baseBranch,
+    issue_number: issue.value,
+    changed_path: changedFile.value,
+    title: 'Fix issue #42',
+    draft: true
+  }
+}, async () => {
+  mutations += 1;
+  return {
+    provider: 'github',
+    pull_request_number: 77,
+    head: taskBranch.value,
+    base: baseBranch,
+    draft: true
+  };
+});
+const pullRequest = task.authorityFrom(pr, {
+  name: 'pull_request',
+  kind: 'github.pull_request.number',
+  from: ['issue', 'task_branch', 'changed_file'],
+  extractor: githubPullRequestCreateNumberAuthorityExtractor
+});
+console.log(`ALLOW -> opened draft PR #${pullRequest.value}`);
+
+const beforeMerge = mutations;
+try {
+  await task.run({
+    service: 'github',
+    action: 'pull_request.merge',
+    context: { repository, pull_request_number: pullRequest.value }
+  }, async () => { mutations += 1; });
+  throw new Error('merge unexpectedly executed');
+} catch (error) {
+  if (!(error instanceof AuthorityDeniedError)) throw error;
+  if (mutations !== beforeMerge) throw new Error('merge reached provider callback');
+  console.log('DENY -> merge remains outside task authority');
+}
+
+task.complete('draft PR opened');
+console.log(`PASS -> reads=${reads}, authorized mutations=${mutations}; unrelated writes/PRs and merge executed zero callbacks`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullsquare/agent-authority",
-  "version": "0.4.7",
+  "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,6 +33,7 @@
     "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",
@@ -44,9 +45,9 @@
     "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 examples/quickstart-github-connected.mjs && 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",
@@ -80,6 +81,7 @@
     "./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/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;