@papillon6814/pi-gh 0.1.1 → 0.2.0

package/README.md

@@ -1,54 +1,135 @@
 # pi-gh
 
-Piの会話から、共通YAMLに沿ったGitHub Issue案・ラベル変更を検証し、画面で承認した内容だけ実行するPi拡張です。MIT。CLIのbinは提供しません。既存gh-issueflowは削除・変更不要です。
+PiからGitHubを操作するTypeScript製の基盤拡張です。個別ツールを別のPi拡張から組み合わせられます。Scaffoldの工程・ウェーブ・専用テンプレートやHerdr操作は、利用側の拡張が担当します。MIT。CLIのbinは提供しません。既存gh-issueflowを削除・変更する必要はありません。
 
 ## 要件と導入
-- Node.js >=22.19.0、Pi 1.0.4、GitHub CLI gh。実機検証はmacOS。
-- 変更には通常のgh認証が必要です。認証情報・tokenをこの拡張へ渡す設定はありません。
-- 通常Piへ導入: `pi install npm:@papillon6814/pi-gh@0.1.1`。Profileを使わない通常の共通導入の例です。
-- pi-profileのDevelopmentだけで使う: `pi-profile packages add --profile developer npm:@papillon6814/pi-gh@0.1.1`、`pi-profile packages install --profile developer`。共通settingsへは追加しません。
-- ソース利用時は先に `npm install --ignore-scripts && npm run build`。Piホスト提供APIはpeerで、配布に本体を含めません。
-
-## ツール
-| 名前 | 主な入力 | 動作 |
+- Node.js >=22.19.0、Pi 1.0.4、認証済みGitHub CLI gh。実機検証はmacOS。
+- 認証情報・tokenをpi-ghへ渡す設定はありません。Projectsには対象Projectへのアクセスと`project`相当の権限が必要です。権限不足時は停止し、自動再認証しません。
+- 新機能を含むnpm版：`pi install npm:@papillon6814/pi-gh@0.2.0`。
+- Developmentだけで使う場合：`pi-profile packages add --profile developer npm:@papillon6814/pi-gh@0.2.0 --replace`、`pi-profile packages install --profile developer`。共通settingsへは追加しません。
+- Profileの割り当て変更後はPiを再起動してください。起動済みプロセスは元のsource指定を保持するため、`/reload`だけでは新しい版の指定へ切り替わりません。
+- ソース利用は`npm install --ignore-scripts && npm run build`後、`pi -e /absolute/path/to/pi-gh`。
+- Piホスト提供APIはpeerで、本体を配布へ含めません。
+
+## 個別ツール（契約バージョン1）
+
+すべての結果に`outputSchema`とマスク済み`structuredContent`があります。対応版・機能は`gh_capabilities`で確認してください。変更ツールも`direct`で登録され、Piの通常のツール検証・hooksを経由して呼べます。
+
+| 名前 | 入力 | 動作 |
 |---|---|---|
-| gh_issue_validate | draftPath、template/templatePath | オフラインの構造/policy検証 |
-| gh_issue_preview | 同上 | マスク済みプレビューとdigest。ラベル付きはremote確認 |
-| gh_issue_submit | 同上 | TUIで人間確認後にIssue作成 |
-| gh_labels_validate | changePath | オフラインの構造検証 |
+| gh_capabilities | `{}` | contractVersionと対応操作。remoteアクセスなし |
+| gh_issue_validate | draftPath、template/templatePath | オフラインの構造・モデルpolicy検証 |
+| gh_issue_preview | 同上 | 投稿内容・digest。ラベル付きはremote確認 |
+| gh_issue_submit | 同上 | 検証・許可・再確認を経てIssue作成 |
+| gh_labels_validate | changePath | ラベル変更案のオフライン検証 |
 | gh_labels_preview | changePath | 対象・before/after・影響対象・digest |
-| gh_labels_apply | changePath | TUI確認後にラベル変更 |
-| gh_issue_form | template/templatePath | GitHub Issue FormのYAML文字列を返す。ファイル上書きなし |
+| gh_labels_apply | changePath | 検証・許可・再確認を経てラベル変更 |
+| gh_issue_form | template/templatePath | Issue Form YAMLを返す。ファイル上書きなし |
+| gh_issue_get | repo、issue | 指定Issueを取得。PRは拒否 |
+| gh_issue_list | repo、任意state | Issue一覧。stateはopen/closed/all（既定all）。PRは除外 |
+| gh_issue_edit | changePath | 既存Issueのtitle/body更新 |
+| gh_issue_close | changePath | 既存Issueをclose |
+| gh_subissues_list | repo、issue | native子Issue一覧 |
+| gh_subissue_add | changePath | native親子関係の追加 |
+| gh_dependencies_list | repo、issue | 指定Issueのblocked_by一覧 |
+| gh_dependency_add | changePath | 指定Issueをブロックする先行Issueを追加 |
+| gh_project_get | projectId | Projects V2のtitle・field一覧 |
+| gh_project_items | projectId | Projectの項目・field値一覧 |
+| gh_project_add_issue | changePath | 指定IssueをProjectへ登録 |
+| gh_project_field_update | changePath | text/number/date/single-select field値更新 |
+
+パスは実行時cwd基準。標準templateはtask（既定）/parent。独自templatePathと同時指定できません。Epic/Feature/Task専用テンプレートは利用側で用意します。examplesのexample/demoは架空です。
+
+## 別拡張からの呼び出し
+
+利用側は、pi-ghのロードと必要ツールの存在を確認し、不在・版不一致では停止してください。内部`dist/src/*`の直接importは公開SDK契約ではありません。
+
+```typescript
+// 利用側ツールのexecute内。信頼済みpi-ghが同じPiにロードされている前提。
+const capabilities = await ctx.executeTool("gh_capabilities", {});
+if (capabilities.isError) throw new Error("pi-gh unavailable");
+const info = capabilities.result.structuredContent as {
+  data?: { contractVersion?: number; operations?: string[] };
+};
+if (info.data?.contractVersion !== 1 ||
+    !info.data.operations?.includes("gh_issue_get")) {
+  throw new Error("Unsupported pi-gh contract");
+}
+const nested = await ctx.executeTool("gh_issue_get", {
+  repo: "example/demo", issue: 10,
+}, { signal });
+return { ...nested.result, isError: nested.isError };
+```
+
+`ctx.executeTool()`の戻り値は結果そのものではなく`{ result, isError, toolCall }`です。結果をモデルへ返すのは呼び出し側の責務です。Piはネスト呼び出しをhooksへ通します。機能照会は登録が正しいことの保証ではないため、ロードする拡張は信頼済みのものに限ってください。
+
+## 変更JSON
 
-パスは作業ディレクトリ基準。標準templateはtask（既定）/parent。独自templatePathと同時指定はできません。examplesは架空のexample/demoなので、実行前に対象repoと内容を直してください。
+新規Issue・ラベル変更は従来の入力を維持します。新しい変更ツールは`{ changePath: "change.json" }`を受け、以下のJSONを読みます。未知・重複キーやツールとoperationの不一致は拒否します。
 
-## 操作の流れ
-1. 案JSONを用意しvalidate。
-2. previewを読み、必要なら案・template・policyを直す。
-3. submit/applyを呼び、Piの確認画面で対象と内容を確認。上下/Pageキーで全文を読めます。
-4. 既定はCancel。左右でApproveを明示選択してEnter。Escape/Ctrl-Cは取消。
+| operation | 必須フィールド（version:1、repo以外） | 任意フィールド |
+|---|---|---|
+| issue-edit | issue、title/bodyの少なくとも一方 | — |
+| issue-close | issue | reason: completed（既定）/not_planned |
+| subissue-add | issue（親）、relatedIssue（子） | — |
+| dependency-add | issue（後続）、relatedIssue（先行） | — |
+| project-add-issue | issue、projectId | — |
+| project-field-update | projectId、itemId、fieldId、value | — |
+
+```json
+{"version":1,"repo":"example/demo","operation":"issue-edit","issue":10,"title":"Updated","body":"Revised specification"}
+```
+
+```json
+{"version":1,"repo":"example/demo","operation":"project-field-update","projectId":"PVT_example","itemId":"PVTI_example","fieldId":"PVTSSF_example","value":{"singleSelectOptionId":"option_done"}}
+```
+
+valueは`text`、有限の`number`、実在するISO日付`date`、`singleSelectOptionId`のうち1つ。fieldの種類、Project所属、option所属、項目のIssue/repo所属を照合します。親子・依存追加は同一repo内のみ、自己参照は禁止。入力のIssue番号をGitHubのdatabase ID/node IDへ解決します。従来の`parentIssue`は本文リンクであり、native親子関係は`gh_subissue_add`で別途設定します。
+
+## 人間承認と自動実行許可
 
-初版ではTUIのローカル人間確認が必要です。RPC、print/JSON、子エージェントは変更を拒否します。読み取りツールとフォーム生成はUIなしでも使えます。外部変更ツールはmodel-onlyで、codemodeスクリプトから呼べません。承認hashやapprovedフラグをモデルから渡す経路はありません。
+既定は従来と同じローカルTUI承認です。全文を読んでApproveを明示選択してください。既定Cancel、Escape/Ctrl-Cは取消。RPC・print/JSON・子エージェントは、対応するローカル許可がなければ変更を拒否します。`approved`フラグやdigestをAIが渡して承認する入口はありません。
 
-入力bytes/template/policyとremote identity/stateを承認後にも再検査します。変更・取消・会話切替・tree移動・reload/shutdownで旧承認は使えません。承認は保存・再開・別sessionへ引き継ぎません。GitHub APIの検査とwriteの間の競合を完全には防げないため、同じ対象の並行編集は避けてください。
+所有者が`~/.pi/agent/pi-gh-permissions.json`を配置した場合だけ、許可範囲内の操作を自動実行できます。PiのagentDir/Profileの設定とは独立した、HOME配下の固定パスです。リポジトリ内の設定は許可として読みません。
 
-## 入力とモデルpolicy
-templates/parent.yml、task.ymlが正本、formsは生成物です。fieldsのrequired/options/順序/制限とpolicies/models.ymlを読み直します。担当はmodel/thinking/reason、上位tierはupperTierApprovalを含めます。配布モデル表は例で、実際の利用可能性や予算承認を保証しません。upperTierApprovalの文字列だけで人間の真正な課金承認は証明できません。
+```json
+{
+  "version": 1,
+  "grants": [{
+    "repo": "example/demo",
+    "operations": ["gh_issue_edit", "gh_issue_close", "gh_project_field_update"],
+    "allowHeadless": true,
+    "allowChild": true,
+    "projectIds": ["PVT_example"]
+  }]
+}
+```
 
-Issue JSONはversion/template/repo/title/fields/agents、任意labelsとparentIssue。labelsは既存ラベルのみで、暗黙に作成しません。ラベル変更はversion:1とrepo、operationがissue-labels/label-create/label-edit/label-delete。詳しい例はexamples/labels-*.jsonです。指定外ラベルは維持し、PRへのissue-labelsは拒否します。
+- ファイルは現在のOSユーザー所有・mode 0600以下のregular file。ファイルと親ディレクトリのsymlinkは拒否します。未配置は通常の承認経路へ戻ります。壊れたJSON・権限不備は停止します。
+- repo・operationは完全指定。ワイルドカード不可。Project変更にはprojectIdsの完全一致も必要です。
+- 子にはallowChild、UIのない実行にはallowHeadlessがそれぞれ必要です。省略はfalse。
+- 許可できる操作：`gh_issue_submit`、新しい変更ツール6種、`gh_label_create`、`gh_label_edit`、`gh_issue_labels`。最後の3種は`gh_labels_apply`の操作別許可名です。ラベル削除は自動許可できません。
+- 許可ファイルの内容・inode・modeを固定し、変更前とghプロセス起動直前に再照合します。取り消された許可は再利用しません。許可ファイルは自動生成・変更しません。
+- 許可はこのツール群の境界です。任意のshell/ファイル編集権限を持つAIや同じOSユーザーの悪意あるプロセスを隔離するサンドボックスではありません。
 
-## 安全境界と結果
-秘密情報検出はヒューリスティックです。raw inputだけでなくdecoded文字列・object key・remote metadataをマスクし、候補があれば変更を拒否します。秘密漏洩ゼロや自由なbashからの直接gh実行防止を保証するものではありません。
+## 安全境界と制限
 
-未知/重複JSON・YAMLキー、独自tag/alias、32段超階層、外部policy参照、入力1MiB超を拒否。policyのsymlink/descriptor検査を維持します。ghはshellなし、固定argv/stdin、GH_HOST=github.comで起動。60秒期限、各stdio1MiB、cleanup猶予100ms、POSIX所有process groupを停止します。Windowsの子孫全体停止は保証しません。
+入力bytes・template・モデルpolicy・関連remote状態を固定し、承認後に再検査します。会話切り替え・tree移動・reload/shutdown・取消で保留中の処理は失効します。変更は同一拡張runtime内で直列化します。別Piプロセス間のロックやGitHub側のatomic compare-and-swapは提供しません。同じ対象の並行編集は避けてください。
 
-ラベル一覧・影響対象は各100ページ/合計1MiBまで。上限・権限不足・検査失敗では変更しません。改名・削除・説明/色編集の影響を確認します。
+秘密検出はヒューリスティックです。decoded文字列・object key・remote metadataもマスクし、秘密候補があれば変更を拒否します。秘密漏洩ゼロ、直接gh実行の防止、チェックと実write間の全競合防止は保証しません。
 
-結果はvalidated/preview/generated/created/applied/noop/rejected/not-started/unknown。unknownは既に変更済みの可能性があるため、GitHubを手動確認し、再preview・再承認してください。自動再試行・自動取消はありません。既存コアのIssue URL検証と、ラベル付きIssue/ラベル変更の事後確認を維持しています。
+ghはshellなし・固定argv/stdin・github.com固定。RESTは明示methodとAPI version 2026-03-10、GraphQLは固定queryとJSON variablesを使い、任意endpoint/query入力はありません。各プロセス60秒、各stdio1MiB、cleanup猶予100ms。POSIX所有process groupを停止しますが、Windowsの子孫全体停止は保証しません。新規read操作は最大100ページ・合計1MiB、反復cursor・field値の切り捨てを拒否します。
 
-既存Issue本文/タイトル編集、sub-issue、assignee/Project、一括操作は対象外です。
+結果はread/validated/preview/generated/created/applied/noop/rejected/not-started/unknown。`unknown`は変更済みの可能性があります。GitHubを確認するまで再実行しないでください。自動再試行・自動取消はありません。新変更操作は要求した状態を事後確認し、不一致・確認失敗はunknownにします。
+
+Issue用YAMLはfieldsのrequired/options/順序/制限とmodels policyを正本にします。従来の上位tierにはupperTierApprovalが必要ですが、その文字列だけで真正な課金承認は証明できません。テンプレートと利用可能なモデルは別問題です。
+
+対象外：assignee変更、コメント投稿、クロスrepo親子・依存、関係解除、Project作成/削除/field定義/view変更、iteration等のfield更新、一括write、Herdr/Scaffoldの工程判断。
 
 ## 開発・検証
-`npm run build`、`npm run typecheck`、`npm test`。元コアの回帰はtest/core、承認・lifecycleはservice tests、ツール/UIはextension testsです。
-`python3 scripts/test-pi-gh-cli.py --pi /absolute/path/to/pi`は合成HOME、偽gh、loopbackモデルだけで実Piを検証します。実アカウントや実GitHubへ投稿しません。
-`npm pack`にはentry、compiled core、templates、架空examples、README、LICENSEだけを含めます。docs/test/認証は含めません。
+
+`npm run build`、`npm run typecheck`、`npm test`。
+`python3 scripts/test-pi-gh-cli.py --pi /absolute/path/to/pi`は合成HOME・偽gh・loopbackモデルで実PiのTUI/RPC/print・ネスト呼び出し・許可付き子実行・hooksを検証します。実アカウントや実GitHubへの試験投稿はしません。GitHubのライブ変更互換性は未実測です。
+`npm pack`にはentry、compiled core、templates、架空examples、README、LICENSEだけを含め、docs/test/認証は含めません。
+
+GitHub API参照：[sub-issues](https://docs.github.com/en/rest/issues/sub-issues)、[dependencies](https://docs.github.com/en/rest/issues/issue-dependencies)、[Projects V2](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects)。

package/dist/src/core/gh-process.d.ts

@@ -5,6 +5,7 @@ export type GhOptions = {
     env?: NodeJS.ProcessEnv;
     signal?: AbortSignal;
     beforeStart?: () => boolean;
+    beforeStartAsync?: () => Promise<boolean>;
 };
 export type GhResult = {
     status: 'ok' | 'not-started' | 'unknown';

package/dist/src/core/gh-process.js

@@ -1,8 +1,15 @@
 import { spawn } from 'node:child_process';
-export function runGh(args, body, options = {}) {
+export async function runGh(args, body, options = {}) {
     const timeout = options.timeoutMs ?? 60000, max = options.maxOutputBytes ?? 1048576;
     if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 60000 || !Number.isSafeInteger(max) || max < 1 || max > 1048576 || Buffer.byteLength(body) > 1048576)
         return Promise.resolve({ status: 'not-started', stdout: '' });
+    try {
+        if (options.beforeStartAsync && !await options.beforeStartAsync())
+            return { status: 'not-started', stdout: '' };
+    }
+    catch {
+        return { status: 'not-started', stdout: '' };
+    }
     return new Promise(resolve => {
         const group = process.platform !== 'win32';
         let child;

package/dist/src/github-api.d.ts

@@ -0,0 +1,28 @@
+import { type GhOptions } from './core/gh-process.js';
+export type JsonObject = Record<string, unknown>;
+export declare function object(value: unknown): JsonObject;
+export declare function array(value: unknown): unknown[];
+export declare const projectFieldsQuery = "query($projectId:ID!,$cursor:String){node(id:$projectId){__typename ... on ProjectV2{id title fields(first:100,after:$cursor){nodes{__typename ... on ProjectV2Field{id name dataType} ... on ProjectV2SingleSelectField{id name dataType options{id name}} ... on ProjectV2IterationField{id name dataType}} pageInfo{hasNextPage endCursor}}}}}";
+export declare const projectItemsQuery = "query($projectId:ID!,$cursor:String){node(id:$projectId){__typename ... on ProjectV2{id title items(first:100,after:$cursor){nodes{id content{__typename ... on Issue{id number repository{nameWithOwner}}} fieldValues(first:100){nodes{__typename ... on ProjectV2ItemFieldTextValue{text field{... on ProjectV2Field{id}}} ... on ProjectV2ItemFieldNumberValue{number field{... on ProjectV2Field{id}}} ... on ProjectV2ItemFieldDateValue{date field{... on ProjectV2Field{id}}} ... on ProjectV2ItemFieldSingleSelectValue{optionId field{... on ProjectV2SingleSelectField{id}}}} pageInfo{hasNextPage endCursor}}} pageInfo{hasNextPage endCursor}}}}}";
+export declare const addProjectIssueMutation = "mutation($projectId:ID!,$contentId:ID!){addProjectV2ItemById(input:{projectId:$projectId,contentId:$contentId}){item{id}}}";
+export declare const updateProjectFieldMutation = "mutation($projectId:ID!,$itemId:ID!,$fieldId:ID!,$value:ProjectV2FieldValue!){updateProjectV2ItemFieldValue(input:{projectId:$projectId,itemId:$itemId,fieldId:$fieldId,value:$value}){projectV2Item{id}}}";
+export declare class GithubApi {
+    private options;
+    private bytes;
+    constructor(options: GhOptions);
+    private args;
+    private decode;
+    rest(endpoint: string): Promise<unknown>;
+    restList(endpoint: string): Promise<unknown[]>;
+    issue(repo: string, number: number): Promise<JsonObject>;
+    graphql(query: string, variables: JsonObject): Promise<JsonObject>;
+    project(projectId: string, kind: 'fields' | 'items'): Promise<JsonObject>;
+    mutateRest(endpoint: string, method: 'POST' | 'PATCH', body: JsonObject): Promise<{
+        status: 'ok' | 'not-started' | 'unknown';
+        data?: unknown;
+    }>;
+    mutateGraphql(query: string, variables: JsonObject): Promise<{
+        status: 'ok' | 'not-started' | 'unknown';
+        data?: unknown;
+    }>;
+}

package/dist/src/github-api.js

@@ -0,0 +1,100 @@
+import { runGh } from './core/gh-process.js';
+import { fail, parseJson, record } from './core/data.js';
+export function object(value) { if (!record(value))
+    fail('GITHUB_RESPONSE', '', 'Expected a GitHub object.'); return value; }
+export function array(value) { if (!Array.isArray(value))
+    fail('GITHUB_RESPONSE', '', 'Expected a GitHub array.'); return value; }
+export const projectFieldsQuery = `query($projectId:ID!,$cursor:String){node(id:$projectId){__typename ... on ProjectV2{id title fields(first:100,after:$cursor){nodes{__typename ... on ProjectV2Field{id name dataType} ... on ProjectV2SingleSelectField{id name dataType options{id name}} ... on ProjectV2IterationField{id name dataType}} pageInfo{hasNextPage endCursor}}}}}`;
+export const projectItemsQuery = `query($projectId:ID!,$cursor:String){node(id:$projectId){__typename ... on ProjectV2{id title items(first:100,after:$cursor){nodes{id content{__typename ... on Issue{id number repository{nameWithOwner}}} fieldValues(first:100){nodes{__typename ... on ProjectV2ItemFieldTextValue{text field{... on ProjectV2Field{id}}} ... on ProjectV2ItemFieldNumberValue{number field{... on ProjectV2Field{id}}} ... on ProjectV2ItemFieldDateValue{date field{... on ProjectV2Field{id}}} ... on ProjectV2ItemFieldSingleSelectValue{optionId field{... on ProjectV2SingleSelectField{id}}}} pageInfo{hasNextPage endCursor}}} pageInfo{hasNextPage endCursor}}}}}`;
+export const addProjectIssueMutation = `mutation($projectId:ID!,$contentId:ID!){addProjectV2ItemById(input:{projectId:$projectId,contentId:$contentId}){item{id}}}`;
+export const updateProjectFieldMutation = `mutation($projectId:ID!,$itemId:ID!,$fieldId:ID!,$value:ProjectV2FieldValue!){updateProjectV2ItemFieldValue(input:{projectId:$projectId,itemId:$itemId,fieldId:$fieldId,value:$value}){projectV2Item{id}}}`;
+export class GithubApi {
+    options;
+    bytes = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    args(endpoint, method) { return ['api', '--hostname', 'github.com', '--method', method, '-H', 'Accept: application/vnd.github+json', '-H', 'X-GitHub-Api-Version: 2026-03-10', endpoint]; }
+    decode(stdout) { this.bytes += Buffer.byteLength(stdout); if (this.bytes > 1048576)
+        fail('GITHUB_LIMIT', '', 'Combined response limit exceeded.'); return parseJson(Buffer.from(stdout)); }
+    async rest(endpoint) { const r = await runGh(this.args(endpoint, 'GET'), '', this.options); if (r.status !== 'ok')
+        fail('GITHUB_READ', '', 'GitHub read failed.'); return this.decode(r.stdout); }
+    async restList(endpoint) {
+        const all = [];
+        for (let page = 1; page <= 100; page++) {
+            const items = array(await this.rest(endpoint + (endpoint.includes('?') ? '&' : '?') + 'per_page=100&page=' + page));
+            all.push(...items);
+            if (items.length < 100)
+                return all;
+        }
+        fail('GITHUB_LIMIT', '', 'Pagination limit exceeded.');
+    }
+    async issue(repo, number) {
+        const v = object(await this.rest('repos/' + repo + '/issues/' + number));
+        if (v.pull_request !== undefined || v.number !== number || !Number.isSafeInteger(v.id) || v.id < 1 || typeof v.node_id !== 'string' || !/^I_[A-Za-z0-9_-]+$/.test(v.node_id) || typeof v.html_url !== 'string' || v.html_url.toLowerCase() !== ('https://github.com/' + repo + '/issues/' + number).toLowerCase())
+            fail('GITHUB_IDENTITY', '', 'Expected the exact GitHub Issue, not a PR.');
+        return v;
+    }
+    async graphql(query, variables) {
+        const r = await runGh([...this.args('graphql', 'POST'), '--input', '-'], JSON.stringify({ query, variables }), this.options);
+        if (r.status !== 'ok')
+            fail('GITHUB_READ', '', 'GraphQL read failed.');
+        const v = object(this.decode(r.stdout));
+        if (v.errors !== undefined)
+            fail('GITHUB_READ', '', 'GraphQL returned errors.');
+        return object(v.data);
+    }
+    async project(projectId, kind) {
+        const nodes = [];
+        const cursors = new Set();
+        let cursor = null, title;
+        for (let page = 0; page < 100; page++) {
+            const response = await this.graphql(kind === 'fields' ? projectFieldsQuery : projectItemsQuery, { projectId, cursor });
+            const project = object(response.node);
+            if (project.__typename !== 'ProjectV2' || project.id !== projectId)
+                fail('GITHUB_IDENTITY', '', 'Expected the exact Projects V2 node.');
+            title = project.title;
+            const connection = object(project[kind]), items = array(connection.nodes);
+            nodes.push(...items);
+            if (kind === 'items')
+                for (const raw of items) {
+                    const item = object(raw), values = object(item.fieldValues);
+                    if (values.pageInfo !== undefined && object(values.pageInfo).hasNextPage !== false)
+                        fail('GITHUB_LIMIT', '', 'Item field values were truncated.');
+                }
+            const info = object(connection.pageInfo);
+            if (info.hasNextPage === false)
+                return { id: projectId, title, [kind]: nodes };
+            if (info.hasNextPage !== true || typeof info.endCursor !== 'string' || !info.endCursor || cursors.has(info.endCursor))
+                fail('GITHUB_LIMIT', '', 'Invalid or repeated pagination cursor.');
+            cursor = info.endCursor;
+            cursors.add(cursor);
+        }
+        fail('GITHUB_LIMIT', '', 'Pagination limit exceeded.');
+    }
+    async mutateRest(endpoint, method, body) {
+        const r = await runGh([...this.args(endpoint, method), '--input', '-'], JSON.stringify(body), this.options);
+        if (r.status !== 'ok')
+            return { status: r.status };
+        try {
+            return { status: 'ok', data: this.decode(r.stdout) };
+        }
+        catch {
+            return { status: 'unknown' };
+        }
+    }
+    async mutateGraphql(query, variables) {
+        const r = await runGh([...this.args('graphql', 'POST'), '--input', '-'], JSON.stringify({ query, variables }), this.options);
+        if (r.status !== 'ok')
+            return { status: r.status };
+        try {
+            const v = object(this.decode(r.stdout));
+            if (v.errors !== undefined)
+                return { status: 'unknown' };
+            return { status: 'ok', data: object(v.data) };
+        }
+        catch {
+            return { status: 'unknown' };
+        }
+    }
+}

package/dist/src/operation-input.d.ts

@@ -0,0 +1,35 @@
+import type { CapturedInput } from './core/types.js';
+export declare const githubReads: readonly ["gh_issue_get", "gh_issue_list", "gh_subissues_list", "gh_dependencies_list", "gh_project_get", "gh_project_items"];
+export declare const githubWrites: readonly ["gh_issue_edit", "gh_issue_close", "gh_subissue_add", "gh_dependency_add", "gh_project_add_issue", "gh_project_field_update"];
+export type GithubOperation = typeof githubReads[number] | typeof githubWrites[number];
+export type GithubArgs = {
+    repo?: string;
+    issue?: number;
+    state?: 'open' | 'closed' | 'all';
+    projectId?: string;
+    changePath?: string;
+};
+export type FieldValue = {
+    text?: string;
+    number?: number;
+    date?: string;
+    singleSelectOptionId?: string;
+};
+export type Change = {
+    version: 1;
+    repo: string;
+    operation: string;
+    issue?: number;
+    title?: string;
+    body?: string;
+    reason?: 'completed' | 'not_planned';
+    relatedIssue?: number;
+    projectId?: string;
+    itemId?: string;
+    fieldId?: string;
+    value?: FieldValue;
+};
+export declare function positive(value: unknown): asserts value is number;
+export declare function nodeId(value: unknown, prefix: string): asserts value is string;
+export declare function validateGithubArgs(name: GithubOperation, args: unknown): asserts args is GithubArgs;
+export declare function validateChange(name: GithubOperation, input: CapturedInput): Change;

package/dist/src/operation-input.js

@@ -0,0 +1,88 @@
+import { fail, keys, record, parseJson } from './core/data.js';
+import { validateRepo } from './core/labels-input.js';
+export const githubReads = ['gh_issue_get', 'gh_issue_list', 'gh_subissues_list', 'gh_dependencies_list', 'gh_project_get', 'gh_project_items'];
+export const githubWrites = ['gh_issue_edit', 'gh_issue_close', 'gh_subissue_add', 'gh_dependency_add', 'gh_project_add_issue', 'gh_project_field_update'];
+export function positive(value) { if (!Number.isSafeInteger(value) || value < 1)
+    fail('ARGUMENT', '', 'Expected a positive Issue number.'); }
+export function nodeId(value, prefix) { if (typeof value !== 'string' || !new RegExp('^' + prefix + '[A-Za-z0-9_-]{1,200}$').test(value))
+    fail('ARGUMENT', '', 'Invalid GitHub node ID.'); }
+export function validateGithubArgs(name, args) {
+    if (!record(args))
+        fail('ARGUMENT', '', 'Expected an argument object.');
+    if (githubWrites.includes(name)) {
+        keys(args, ['changePath'], 'arguments');
+        if (typeof args.changePath !== 'string' || !args.changePath.trim())
+            fail('ARGUMENT', '', 'Expected changePath.');
+        return;
+    }
+    if (name.startsWith('gh_project_')) {
+        keys(args, ['projectId'], 'arguments');
+        nodeId(args.projectId, 'PVT_');
+        return;
+    }
+    keys(args, name === 'gh_issue_list' ? ['repo', 'state'] : ['repo', 'issue'], 'arguments');
+    validateRepo(args.repo);
+    if (name === 'gh_issue_list') {
+        if (args.state !== undefined && !['open', 'closed', 'all'].includes(args.state))
+            fail('ARGUMENT', '', 'Unknown Issue state.');
+    }
+    else
+        positive(args.issue);
+}
+const changes = {
+    'issue-edit': { name: 'gh_issue_edit', keys: ['issue', 'title', 'body'] },
+    'issue-close': { name: 'gh_issue_close', keys: ['issue', 'reason'] },
+    'subissue-add': { name: 'gh_subissue_add', keys: ['issue', 'relatedIssue'] },
+    'dependency-add': { name: 'gh_dependency_add', keys: ['issue', 'relatedIssue'] },
+    'project-add-issue': { name: 'gh_project_add_issue', keys: ['issue', 'projectId'] },
+    'project-field-update': { name: 'gh_project_field_update', keys: ['projectId', 'itemId', 'fieldId', 'value'] }
+};
+export function validateChange(name, input) {
+    const raw = parseJson(input.bytes);
+    if (!record(raw) || raw.version !== 1 || typeof raw.operation !== 'string')
+        fail('ARGUMENT', '', 'Expected version 1 change.');
+    const definition = changes[raw.operation];
+    if (!definition || definition.name !== name)
+        fail('ARGUMENT', '', 'Change does not match the tool operation.');
+    keys(raw, ['version', 'repo', 'operation', ...definition.keys], 'change');
+    validateRepo(raw.repo);
+    if (raw.operation !== 'project-field-update')
+        positive(raw.issue);
+    if (raw.operation === 'issue-edit') {
+        if (raw.title === undefined && raw.body === undefined)
+            fail('ARGUMENT', '', 'No edit requested.');
+        if (raw.title !== undefined && (typeof raw.title !== 'string' || !raw.title.trim() || raw.title.length > 256 || /[\u0000-\u001f\u007f]/.test(raw.title)))
+            fail('ARGUMENT', '', 'Invalid title.');
+        if (raw.body !== undefined && (typeof raw.body !== 'string' || raw.body.length > 65536))
+            fail('ARGUMENT', '', 'Invalid body.');
+    }
+    if (raw.operation === 'issue-close' && raw.reason !== undefined && !['completed', 'not_planned'].includes(raw.reason))
+        fail('ARGUMENT', '', 'Invalid close reason.');
+    if (raw.operation === 'subissue-add' || raw.operation === 'dependency-add') {
+        positive(raw.relatedIssue);
+        if (raw.relatedIssue === raw.issue)
+            fail('ARGUMENT', '', 'Self-links are forbidden.');
+    }
+    if (raw.operation.startsWith('project-'))
+        nodeId(raw.projectId, 'PVT_');
+    if (raw.operation === 'project-field-update') {
+        nodeId(raw.itemId, 'PVTI_');
+        if (typeof raw.fieldId !== 'string' || !/^PVT(F|SSF)_[A-Za-z0-9_-]{1,200}$/.test(raw.fieldId))
+            fail('ARGUMENT', '', 'Invalid field ID.');
+        if (!record(raw.value) || Object.keys(raw.value).length !== 1)
+            fail('ARGUMENT', '', 'Expected one typed field value.');
+        keys(raw.value, ['text', 'number', 'date', 'singleSelectOptionId'], 'field value');
+        const v = raw.value;
+        if ('text' in v && (typeof v.text !== 'string' || v.text.length > 20000))
+            fail('ARGUMENT', '', 'Invalid text.');
+        if ('number' in v && (typeof v.number !== 'number' || !Number.isFinite(v.number)))
+            fail('ARGUMENT', '', 'Invalid number.');
+        if ('date' in v) {
+            if (typeof v.date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(v.date) || !Number.isFinite(Date.parse(v.date)) || new Date(v.date).toISOString().slice(0, 10) !== v.date)
+                fail('ARGUMENT', '', 'Invalid ISO date.');
+        }
+        if ('singleSelectOptionId' in v && (typeof v.singleSelectOptionId !== 'string' || !/^[A-Za-z0-9_-]{1,200}$/.test(v.singleSelectOptionId)))
+            fail('ARGUMENT', '', 'Invalid option ID.');
+    }
+    return raw;
+}

package/dist/src/operations.d.ts

@@ -0,0 +1,3 @@
+import { type GithubOperation, type GithubArgs } from './operation-input.js';
+import type { OperationContext, OperationResult } from './service-types.js';
+export declare function runGithubOperation(name: GithubOperation, args: GithubArgs, ctx: OperationContext): Promise<OperationResult>;

package/dist/src/operations.js

@@ -0,0 +1,137 @@
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { loadDraft } from './core/draft.js';
+import { maskDecodedSecrets } from './core/secrets.js';
+import { fail } from './core/data.js';
+import { safeResult, errorResult, rejected } from './result.js';
+import { authorize, recheckAuthority } from './service.js';
+import { GithubApi, object, array, addProjectIssueMutation, updateProjectFieldMutation } from './github-api.js';
+import { githubReads, githubWrites, validateGithubArgs, validateChange } from './operation-input.js';
+function active(ctx) { return !ctx.signal.aborted && ctx.isCurrent(); }
+function requireActive(ctx) { if (!active(ctx))
+    fail('STALE_OPERATION', '', 'Session changed or operation was cancelled.'); }
+function digest(bytes, before) { return createHash('sha256').update(bytes).update(JSON.stringify(before)).digest('hex'); }
+function fieldValue(item, fieldId) {
+    return array(object(item.fieldValues).nodes).map(object).find(v => v.field !== undefined && object(v.field).id === fieldId);
+}
+function equalField(item, c) { const value = fieldValue(item, c.fieldId); if (!value)
+    return false; const [key, wanted] = Object.entries(c.value)[0]; return value[key === 'singleSelectOptionId' ? 'optionId' : key] === wanted; }
+function verifyItem(item, repo) { const content = object(item.content); if (content.__typename !== 'Issue' || object(content.repository).nameWithOwner?.toString().toLowerCase() !== repo.toLowerCase())
+    fail('GITHUB_IDENTITY', '', 'Project item does not belong to the specified repository Issue.'); }
+async function snapshot(api, c) {
+    const s = { noop: false };
+    if (c.issue !== undefined)
+        s.issue = await api.issue(c.repo, c.issue);
+    if (c.operation === 'issue-edit') {
+        s.noop = (c.title === undefined || c.title === s.issue.title) && (c.body === undefined || c.body === s.issue.body);
+        return s;
+    }
+    if (c.operation === 'issue-close') {
+        s.noop = s.issue.state === 'closed' && s.issue.state_reason === (c.reason ?? 'completed');
+        return s;
+    }
+    if (c.operation === 'subissue-add' || c.operation === 'dependency-add') {
+        s.related = await api.issue(c.repo, c.relatedIssue);
+        const suffix = c.operation === 'subissue-add' ? 'sub_issues' : 'dependencies/blocked_by';
+        s.relations = await api.restList('repos/' + c.repo + '/issues/' + c.issue + '/' + suffix);
+        s.noop = s.relations.some(v => object(v).id === s.related.id);
+        return s;
+    }
+    const fields = await api.project(c.projectId, 'fields'), items = await api.project(c.projectId, 'items');
+    s.project = { id: fields.id };
+    if (c.operation === 'project-add-issue') {
+        s.item = array(items.items).map(object).find(item => item.content !== null && object(item.content).id === s.issue.node_id);
+        if (s.item) {
+            verifyItem(s.item, c.repo);
+            s.noop = true;
+        }
+        return s;
+    }
+    s.item = array(items.items).map(object).find(item => item.id === c.itemId);
+    if (!s.item)
+        fail('GITHUB_IDENTITY', '', 'Item is not in the specified project.');
+    verifyItem(s.item, c.repo);
+    s.field = array(fields.fields).map(object).find(field => field.id === c.fieldId);
+    if (!s.field)
+        fail('GITHUB_IDENTITY', '', 'Field is not in the specified project.');
+    const key = Object.keys(c.value)[0], types = { text: 'TEXT', number: 'NUMBER', date: 'DATE', singleSelectOptionId: 'SINGLE_SELECT' };
+    if (s.field.dataType !== types[key])
+        fail('ARGUMENT', '', 'Field type does not match the supplied value.');
+    if (key === 'singleSelectOptionId' && !array(s.field.options).some(v => object(v).id === c.value.singleSelectOptionId))
+        fail('ARGUMENT', '', 'Option is not in the specified field.');
+    s.noop = equalField(s.item, c);
+    const current = fieldValue(s.item, c.fieldId);
+    s.item = { id: s.item.id, content: s.item.content, fieldValues: { nodes: current ? [current] : [] } };
+    s.field = { id: s.field.id, name: s.field.name, dataType: s.field.dataType, ...(key === 'singleSelectOptionId' ? { options: array(s.field.options).filter(v => object(v).id === c.value.singleSelectOptionId) } : {}) };
+    return s;
+}
+async function apply(api, c, before) {
+    const endpoint = 'repos/' + c.repo + '/issues/' + c.issue;
+    switch (c.operation) {
+        case 'issue-edit': return api.mutateRest(endpoint, 'PATCH', { ...(c.title !== undefined ? { title: c.title } : {}), ...(c.body !== undefined ? { body: c.body } : {}) });
+        case 'issue-close': return api.mutateRest(endpoint, 'PATCH', { state: 'closed', state_reason: c.reason ?? 'completed' });
+        case 'subissue-add': return api.mutateRest(endpoint + '/sub_issues', 'POST', { sub_issue_id: before.related.id });
+        case 'dependency-add': return api.mutateRest(endpoint + '/dependencies/blocked_by', 'POST', { issue_id: before.related.id });
+        case 'project-add-issue': return api.mutateGraphql(addProjectIssueMutation, { projectId: c.projectId, contentId: before.issue.node_id });
+        case 'project-field-update': return api.mutateGraphql(updateProjectFieldMutation, { projectId: c.projectId, itemId: c.itemId, fieldId: c.fieldId, value: c.value });
+        default: fail('ARGUMENT', '', 'Unknown change.');
+    }
+}
+export async function runGithubOperation(name, args, ctx) {
+    let mutationStarted = false;
+    try {
+        if (![...githubReads, ...githubWrites].includes(name))
+            return rejected('ARGUMENT', 'Unknown operation.');
+        validateGithubArgs(name, args);
+        requireActive(ctx);
+        const write = githubWrites.includes(name);
+        if (write && !ctx.interactive && !ctx.permissions)
+            return rejected('APPROVAL_UI_REQUIRED', 'External changes require local approval or an exact permission grant.');
+        let machineAuthority = false;
+        const api = new GithubApi({ signal: ctx.signal, beforeStart: () => active(ctx), beforeStartAsync: async () => !machineAuthority || !!ctx.permissions && await ctx.permissions.isCurrent() });
+        if (!write) {
+            let data;
+            if (name === 'gh_project_get' || name === 'gh_project_items')
+                data = await api.project(args.projectId, name === 'gh_project_get' ? 'fields' : 'items');
+            else if (name === 'gh_issue_list')
+                data = (await api.restList('repos/' + args.repo + '/issues?state=' + (args.state ?? 'all'))).filter(v => object(v).pull_request === undefined);
+            else {
+                const issue = await api.issue(args.repo, args.issue);
+                data = name === 'gh_issue_get' ? issue : await api.restList('repos/' + args.repo + '/issues/' + args.issue + '/' + (name === 'gh_subissues_list' ? 'sub_issues' : 'dependencies/blocked_by'));
+            }
+            requireActive(ctx);
+            return safeResult({ status: 'read', data });
+        }
+        const path = resolve(ctx.cwd, args.changePath), input = await loadDraft(path), change = validateChange(name, input);
+        if (maskDecodedSecrets(change).sensitive)
+            return rejected('SENSITIVE', 'Remove secret candidates before applying.');
+        if (!ctx.interactive && !ctx.permissions?.allows(name, change.repo, change.projectId))
+            return rejected('PERMISSION_DENIED', 'No matching operation/repository/project/actor permission.');
+        const before = await snapshot(api, change);
+        requireActive(ctx);
+        const preview = { operation: name, change, before };
+        if (maskDecodedSecrets(preview).sensitive)
+            return rejected('SENSITIVE', 'Remove secret candidates before applying.');
+        if (before.noop)
+            return safeResult({ status: 'noop', data: { repo: change.repo, operation: name } });
+        const hash = digest(input.bytes, before), machine = await authorize({ operation: name, text: JSON.stringify(preview, null, 2), digest: hash }, ctx, change.repo, name, change.projectId);
+        machineAuthority = machine;
+        const latest = await loadDraft(path), nextChange = validateChange(name, latest), next = await snapshot(api, nextChange);
+        requireActive(ctx);
+        if (digest(latest.bytes, next) !== hash || maskDecodedSecrets({ change: nextChange, before: next }).sensitive)
+            return rejected('APPROVAL_MISMATCH', 'Input or remote state changed; preview again.');
+        await recheckAuthority(ctx, machine);
+        mutationStarted = true;
+        const result = await apply(api, change, before);
+        if (result.status !== 'ok')
+            return safeResult({ status: result.status, message: result.status === 'unknown' ? 'Change outcome is uncertain; inspect GitHub before retrying.' : 'Change did not start.' });
+        const verified = await snapshot(api, change);
+        requireActive(ctx);
+        if (!verified.noop)
+            return safeResult({ status: 'unknown', message: 'Write returned, but the requested state could not be verified. Inspect GitHub before retrying.' });
+        return safeResult({ status: 'applied', data: { repo: change.repo, operation: name, ...(change.projectId ? { projectId: change.projectId } : {}), ...(verified.issue ? { issue: verified.issue } : {}), ...(verified.item ? { itemId: verified.item.id } : {}) } });
+    }
+    catch (error) {
+        return mutationStarted ? safeResult({ status: 'unknown', message: 'Change or its verification was interrupted; inspect GitHub before retrying.' }) : errorResult(error);
+    }
+}

package/dist/src/permissions.d.ts

@@ -0,0 +1,10 @@
+export type PermissionLease = {
+    allows: (operation: string, repo: string, projectId?: string) => boolean;
+    isCurrent: () => Promise<boolean>;
+};
+export type Actor = {
+    child: boolean;
+    headless: boolean;
+};
+export declare function permissionPath(): string;
+export declare function loadPermissions(path: string, actor: Actor): Promise<PermissionLease | undefined>;

package/dist/src/permissions.js

@@ -0,0 +1,100 @@
+import { constants } from 'node:fs';
+import { open, lstat } from 'node:fs/promises';
+import { resolve, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { fail, keys, record, parseJson } from './core/data.js';
+import { validateRepo } from './core/labels-input.js';
+const allowed = new Set(['gh_issue_submit', 'gh_label_create', 'gh_label_edit', 'gh_issue_labels', 'gh_issue_edit', 'gh_issue_close', 'gh_subissue_add', 'gh_dependency_add', 'gh_project_add_issue', 'gh_project_field_update']);
+export function permissionPath() { return join(homedir(), '.pi', 'agent', 'pi-gh-permissions.json'); }
+async function capture(path) {
+    const absolute = resolve(path);
+    let parent = dirname(absolute);
+    try {
+        const named = await lstat(absolute);
+        if (!named.isFile() || named.size > 65536 || (named.mode & 0o077) !== 0 || (process.getuid && named.uid !== process.getuid()))
+            fail('PERMISSION_FILE', '', 'Use an owner-only regular permission file.');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    while (true) {
+        const s = await lstat(parent);
+        if (!s.isDirectory() || s.isSymbolicLink())
+            fail('PERMISSION_FILE', '', 'Permission parents must be real directories.');
+        const next = dirname(parent);
+        if (next === parent)
+            break;
+        parent = next;
+    }
+    let handle;
+    try {
+        handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    try {
+        const s = await handle.stat();
+        if (!s.isFile() || s.size > 65536 || (s.mode & 0o077) !== 0 || (process.getuid && s.uid !== process.getuid()))
+            fail('PERMISSION_FILE', '', 'Use an owner-only regular permission file.');
+        const buffer = Buffer.alloc(65537);
+        let used = 0;
+        while (used < buffer.length) {
+            const read = await handle.read(buffer, used, buffer.length - used, used);
+            if (read.bytesRead === 0)
+                break;
+            used += read.bytesRead;
+        }
+        if (used > 65536)
+            fail('PERMISSION_FILE', '', 'Permission file exceeds limit.');
+        const bytes = buffer.subarray(0, used), after = await handle.stat(), named = await lstat(absolute);
+        if (named.isSymbolicLink() || s.ino !== named.ino || s.dev !== named.dev || s.size !== after.size || s.size !== used || s.mode !== after.mode || s.uid !== after.uid || s.mode !== named.mode || s.mtimeMs !== after.mtimeMs)
+            fail('PERMISSION_FILE', '', 'Permission file changed while reading.');
+        return JSON.stringify({ inode: s.ino, device: s.dev, mode: s.mode, bytes: bytes.toString('base64') });
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function loadPermissions(path, actor) {
+    const captured = await capture(path);
+    if (captured === undefined)
+        return undefined;
+    const encoded = JSON.parse(captured);
+    const raw = parseJson(Buffer.from(encoded.bytes, 'base64'));
+    if (!record(raw))
+        fail('PERMISSION_FORMAT', '', 'Expected permission object.');
+    keys(raw, ['version', 'grants'], 'permissions');
+    if (raw.version !== 1 || !Array.isArray(raw.grants) || raw.grants.length > 100)
+        fail('PERMISSION_FORMAT', '', 'Expected version 1 and at most 100 grants.');
+    const grants = raw.grants.map(value => {
+        if (!record(value))
+            fail('PERMISSION_FORMAT', '', 'Expected grant object.');
+        keys(value, ['repo', 'operations', 'allowChild', 'allowHeadless', 'projectIds'], 'grant');
+        validateRepo(value.repo);
+        if (!Array.isArray(value.operations) || !value.operations.length || value.operations.some(x => typeof x !== 'string' || !allowed.has(x)) || new Set(value.operations).size !== value.operations.length)
+            fail('PERMISSION_FORMAT', '', 'Unknown or repeated operation.');
+        for (const key of ['allowChild', 'allowHeadless'])
+            if (value[key] !== undefined && typeof value[key] !== 'boolean')
+                fail('PERMISSION_FORMAT', '', 'Actor flags must be booleans.');
+        if (value.projectIds !== undefined && (!Array.isArray(value.projectIds) || value.projectIds.length > 100 || value.projectIds.some(x => typeof x !== 'string' || !/^PVT_[A-Za-z0-9_-]+$/.test(x))))
+            fail('PERMISSION_FORMAT', '', 'Expected exact project IDs.');
+        return { repo: value.repo, operations: value.operations, allowChild: value.allowChild === true, allowHeadless: value.allowHeadless === true, projectIds: (value.projectIds ?? []) };
+    });
+    const digest = createHash('sha256').update(captured).digest('hex');
+    return {
+        allows: (operation, repo, projectId) => grants.some(g => g.repo.toLowerCase() === repo.toLowerCase() && g.operations.includes(operation) && (!actor.child || g.allowChild) && (!actor.headless || g.allowHeadless) && (!projectId || g.projectIds.includes(projectId))),
+        isCurrent: async () => { try {
+            const next = await capture(path);
+            return next !== undefined && createHash('sha256').update(next).digest('hex') === digest;
+        }
+        catch {
+            return false;
+        } }
+    };
+}

package/dist/src/service-types.d.ts

@@ -1,4 +1,5 @@
 import type { ValidationProblem } from './core/types.js';
+import type { PermissionLease } from './permissions.js';
 export type Operation = 'gh_issue_validate' | 'gh_issue_preview' | 'gh_issue_submit' | 'gh_labels_validate' | 'gh_labels_preview' | 'gh_labels_apply' | 'gh_issue_form';
 export type IssueArgs = {
     draftPath: string;
@@ -13,7 +14,7 @@ export type FormArgs = {
     templatePath?: string;
 };
 export type ApprovalView = {
-    operation: Operation;
+    operation: string;
     text: string;
     digest: string;
 };
@@ -21,6 +22,7 @@ export type OperationContext = {
     cwd: string;
     packageRoot: string;
     interactive: boolean;
+    permissions?: PermissionLease;
     signal: AbortSignal;
     stamp: string;
     isCurrent: () => boolean;
@@ -31,4 +33,5 @@ export type OperationResult = {
     data?: unknown;
     problems?: ValidationProblem[];
     message?: string;
+    candidateUrl?: string;
 };

package/dist/src/service.d.ts

@@ -1,2 +1,4 @@
-import type { Operation, IssueArgs, LabelsArgs, FormArgs, OperationContext, OperationResult } from './service-types.js';
+import type { Operation, IssueArgs, LabelsArgs, FormArgs, OperationContext, OperationResult, ApprovalView } from './service-types.js';
+export declare function authorize(view: ApprovalView, ctx: OperationContext, repo: string, permissionOperation?: string, projectId?: string): Promise<boolean>;
+export declare function recheckAuthority(ctx: OperationContext, machine: boolean): Promise<void>;
 export declare function runOperation(operation: Operation, args: IssueArgs | LabelsArgs | FormArgs, ctx: OperationContext): Promise<OperationResult>;

package/dist/src/service.js

@@ -26,6 +26,23 @@ async function confirm(view, ctx) {
         ctx.signal.removeEventListener('abort', listener);
     }
 }
+export async function authorize(view, ctx, repo, permissionOperation = view.operation, projectId) {
+    requireActive(ctx);
+    if (ctx.permissions?.allows(permissionOperation, repo, projectId)) {
+        if (!await ctx.permissions.isCurrent())
+            fail('PERMISSION_CHANGED', '', 'Permission file changed.');
+        return true;
+    }
+    if (!ctx.interactive || !await confirm(view, ctx))
+        fail('APPROVAL_DENIED', '', 'Change was not approved.');
+    return false;
+}
+export async function recheckAuthority(ctx, machine) {
+    requireActive(ctx);
+    if (machine && (!ctx.permissions || !await ctx.permissions.isCurrent()))
+        fail('PERMISSION_CHANGED', '', 'Permission file changed.');
+    requireActive(ctx);
+}
 async function issue(args, ctx, withPreview = true) {
     const input = await loadDraft(inputPath(args.draftPath, ctx)), bundle = await loadTemplate(templatePath(args, ctx)), checked = validateDraft(input, bundle);
     if (!checked.issue)
@@ -43,9 +60,10 @@ export async function runOperation(operation, args, ctx) {
         validateArguments(operation, args);
         requireActive(ctx);
         const write = operation === 'gh_issue_submit' || operation === 'gh_labels_apply';
-        if (write && !ctx.interactive)
+        if (write && !ctx.interactive && !ctx.permissions)
             return rejected('APPROVAL_UI_REQUIRED', 'External changes require a local human confirmation screen.');
-        const options = { signal: ctx.signal, beforeStart: () => active(ctx) };
+        let machineAuthority = false;
+        const options = { signal: ctx.signal, beforeStart: () => active(ctx), beforeStartAsync: async () => !machineAuthority || !!ctx.permissions && await ctx.permissions.isCurrent() };
         if (operation === 'gh_issue_form') {
             const bundle = await loadTemplate(templatePath(args, ctx));
             requireActive(ctx);
@@ -65,13 +83,15 @@ export async function runOperation(operation, args, ctx) {
                 return safeResult({ status: 'preview', data: displayed });
             if (sensitive)
                 return rejected('SENSITIVE', 'Remove secret candidates before applying.');
-            if (!await confirm({ operation, text: JSON.stringify(maskDecodedSecrets(displayed).value, null, 2), digest: preview.digest }, ctx))
-                return rejected('APPROVAL_DENIED', 'Change was not approved.');
+            const change = validateLabelChange(input), permissionOperation = change.operation === 'label-delete' ? 'forbidden-delete' : change.operation === 'issue-labels' ? 'gh_issue_labels' : change.operation === 'label-create' ? 'gh_label_create' : 'gh_label_edit';
+            const machine = await authorize({ operation, text: JSON.stringify(maskDecodedSecrets(displayed).value, null, 2), digest: preview.digest }, ctx, change.repo, permissionOperation);
+            machineAuthority = machine;
             requireActive(ctx);
             const latest = await loadDraft(path), next = await previewLabelChange(latest, options);
             requireActive(ctx);
             if (next.digest !== preview.digest || next.sensitive || maskDecodedSecrets(parseJson(latest.bytes)).sensitive)
                 return rejected('APPROVAL_MISMATCH', 'Input or GitHub state changed; preview and approve again.');
+            await recheckAuthority(ctx, machine);
             const result = await applyLabelChange(latest, preview.digest, options);
             return safeResult({ ...result });
         }
@@ -86,13 +106,14 @@ export async function runOperation(operation, args, ctx) {
             return safeResult({ status: 'preview', data: preview });
         if (preview.sensitive)
             return rejected('SENSITIVE', 'Remove secret candidates before submitting.');
-        if (!await confirm({ operation, text: JSON.stringify(maskDecodedSecrets(preview).value, null, 2), digest: preview.digest }, ctx))
-            return rejected('APPROVAL_DENIED', 'Issue was not approved.');
+        const machine = await authorize({ operation, text: JSON.stringify(maskDecodedSecrets(preview).value, null, 2), digest: preview.digest }, ctx, preview.repo);
+        machineAuthority = machine;
         requireActive(ctx);
         const latest = await issue(args, ctx);
         requireActive(ctx);
         if (!latest.checked.issue || latest.preview.digest !== preview.digest || latest.preview.sensitive)
             return rejected('APPROVAL_MISMATCH', 'Input or GitHub state changed; preview and approve again.');
+        await recheckAuthority(ctx, machine);
         const result = await submitIssue(latest.checked.issue, preview.digest, options);
         return safeResult(result.status === 'created' ? { status: 'created', data: { url: result.url } } : { ...result });
     }

package/extensions/tools.ts

@@ -1,35 +1,51 @@
 import {Type} from '@earendil-works/pi-ai';
 import type {ExtensionAPI,ExtensionToolContext} from '@earendil-works/pi-coding-agent';
 import {runOperation} from '../dist/src/service.js';
-import {safeResult} from '../dist/src/result.js';
-import type {Operation,IssueArgs,LabelsArgs,FormArgs} from '../src/service-types.js';
+import {safeResult,errorResult} from '../dist/src/result.js';
+import {loadPermissions,permissionPath} from '../dist/src/permissions.js';
+import {runGithubOperation} from '../dist/src/operations.js';
+import {githubReads,githubWrites} from '../dist/src/operation-input.js';
+import type {GithubOperation,GithubArgs} from '../src/operation-input.js';
+import type {Operation,IssueArgs,LabelsArgs,FormArgs,OperationResult} from '../src/service-types.js';
 import {showApproval} from './approval-ui.ts';
 import {RuntimeScope} from './runtime-scope.ts';
 const template={template:Type.Optional(Type.Union([Type.Literal('parent'),Type.Literal('task')])),templatePath:Type.Optional(Type.String({minLength:1}))};
 const issue=Type.Object({draftPath:Type.String({minLength:1}),...template},{additionalProperties:false});
 const labels=Type.Object({changePath:Type.String({minLength:1})},{additionalProperties:false});
 const form=Type.Object(template,{additionalProperties:false});
-const operations:Operation[]=['gh_issue_validate','gh_issue_preview','gh_issue_submit','gh_labels_validate','gh_labels_preview','gh_labels_apply','gh_issue_form'];
+const output=Type.Object({status:Type.String(),data:Type.Optional(Type.Unknown()),problems:Type.Optional(Type.Array(Type.Object({code:Type.String(),path:Type.String(),message:Type.String()}))),message:Type.Optional(Type.String()),candidateUrl:Type.Optional(Type.String())},{additionalProperties:false});
+const operations:Array<Operation|GithubOperation>=['gh_issue_validate','gh_issue_preview','gh_issue_submit','gh_labels_validate','gh_labels_preview','gh_labels_apply','gh_issue_form',...githubReads,...githubWrites];
+const repo=Type.String({minLength:3});
+const issueRead=Type.Object({repo,issue:Type.Integer({minimum:1})},{additionalProperties:false});
+const issueList=Type.Object({repo,state:Type.Optional(Type.Union([Type.Literal('open'),Type.Literal('closed'),Type.Literal('all')]))},{additionalProperties:false});
+const projectRead=Type.Object({projectId:Type.String({pattern:'^PVT_[A-Za-z0-9_-]+$'})},{additionalProperties:false});
 function identity(ctx:ExtensionToolContext){return ctx.sessionManager.getSessionId()+':'+ctx.sessionManager.getLeafId();}
+function render(result:OperationResult){
+ const safe=safeResult(result),full=JSON.stringify(safe),limit=32768;
+ return {content:[{type:'text' as const,text:full.length<=limit?full:full.slice(0,limit)+'\n[truncated; complete masked data in structuredContent]'}],details:safe,structuredContent:safe as never,isError:['rejected','not-started','unknown'].includes(safe.status)};
+}
 export function registerTools(pi:ExtensionAPI,scope:RuntimeScope,packageRoot:string){
+ pi.registerTool({name:'gh_capabilities',label:'GitHub capabilities',description:'Return pi-gh tool contract version and supported operations. No remote access.',parameters:Type.Object({},{additionalProperties:false}),outputSchema:output,annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false},async execute(){return render({status:'read',data:{contractVersion:1,operations:[...operations,'gh_capabilities']}});}});
  for(const name of operations){
-  const write=name==='gh_issue_submit'||name==='gh_labels_apply';
+  const write=name==='gh_issue_submit'||name==='gh_labels_apply'||(githubWrites as readonly string[]).includes(name);
   pi.registerTool({
-   name,label:name,description:write?'Preview and obtain local human approval for this one GitHub change. Refuses headless/RPC/child modes; never auto-retries unknown outcomes.':name==='gh_issue_form'?'Return GitHub Issue Form YAML without writing a file.':'Validate or preview a GitHub workflow. Preview may read remote metadata; never changes GitHub.',
-   parameters:name.startsWith('gh_labels_')?labels:name==='gh_issue_form'?form:issue,
-   exposure:write?'model-only':'direct',executionMode:write?'sequential':'parallel',
+   name,label:name,description:write?'Preview and apply one GitHub change after local human approval or an exact owner-configured permission grant. Never auto-retries unknown outcomes.':'Validate or preview a GitHub workflow. Preview may read remote metadata; never changes GitHub.',
+   parameters:(githubWrites as readonly string[]).includes(name)?labels:(githubReads as readonly string[]).includes(name)?(name==='gh_issue_list'?issueList:name.startsWith('gh_project_')?projectRead:issueRead):name.startsWith('gh_labels_')?labels:name==='gh_issue_form'?form:issue,outputSchema:output,
+   exposure:'direct',executionMode:write?'sequential':'parallel',
    annotations:{readOnlyHint:!write,destructiveHint:write,idempotentHint:!write,openWorldHint:name!=='gh_issue_validate'&&name!=='gh_labels_validate'&&name!=='gh_issue_form'},
    async execute(_id,args,signal,_update,ctx){
     const captured=identity(ctx),lease=scope.acquire(signal),isCurrent=()=>scope.isCurrent(lease.stamp)&&identity(ctx)===captured;
-    const work=()=>runOperation(name,args as IssueArgs|LabelsArgs|FormArgs,{
-     cwd:ctx.cwd,packageRoot,interactive:ctx.mode==='tui'&&ctx.hasUI&&!process.env.PI_SUBAGENT_CHILD,signal:lease.signal,stamp:lease.stamp,isCurrent,
-     confirm:view=>showApproval(view,{signal:lease.signal,isCurrent},ctx.ui)
-    });
-    try{
-     const result=safeResult(write?await scope.runExclusive(work):await work());
-     const full=JSON.stringify(result),limit=32768;
-     return {content:[{type:'text' as const,text:full.length<=limit?full:full.slice(0,limit)+'\n[truncated; complete masked data in structuredContent]'}],details:result,structuredContent:result as never,isError:['rejected','not-started','unknown'].includes(result.status)};
-    }catch{return {content:[{type:'text' as const,text:'Session changed or operation was cancelled.'}],details:{status:'rejected'},isError:true};}
+    const work=async()=>{
+     const child=!!process.env.PI_SUBAGENT_CHILD,headless=ctx.mode!=='tui'||!ctx.hasUI;
+     const permissions=write?await loadPermissions(permissionPath(),{child,headless}):undefined;
+     const context={
+      cwd:ctx.cwd,packageRoot,interactive:!headless&&!child,permissions,signal:lease.signal,stamp:lease.stamp,isCurrent,
+      confirm:(view:import('../src/service-types.js').ApprovalView)=>showApproval(view,{signal:lease.signal,isCurrent},ctx.ui)
+     };
+     return (githubReads as readonly string[]).includes(name)||(githubWrites as readonly string[]).includes(name)?runGithubOperation(name as GithubOperation,args as GithubArgs,context):runOperation(name as Operation,args as IssueArgs|LabelsArgs|FormArgs,context);
+    };
+    try{return render(write?await scope.runExclusive(work):await work());}
+    catch(error){return render(errorResult(error));}
     finally{lease.dispose();}
    }
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papillon6814/pi-gh",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Prepare and approve GitHub issue workflows inside Pi",
   "type": "module",
   "license": "MIT",