@kana-ai/edgar-ext-github 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,35 +4,37 @@ The GitHub extension of EDGAR. It pushes `edgar/` branches from the run's sandbo
4
4
 
5
5
  ## Tools
6
6
 
7
- | Tool | Input | Output | Notes |
8
- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
- | `push_branch` | `repo`, and `branch` or `to` | `branch`, `commit` | Runs `git rev-parse` and `git push origin <branch>` in the sandbox, never forced. Refuses a branch outside `edgar/` or with `:`, `+` or `..`. Needs `git:push` and `sandbox:read`. |
10
- | `open_pull_request` | `repo`, `branch`, `title`, `body`, `review`; optional `base`, `card`, `labels`, `large_diff_lines`, `path_notices`, `checks`, `not_verified`, `proof`, `proof_passes`, `related` | `url`, `number` | Opens onto `base`, the service's default branch, or onto `default_base` when the call names none. The body ends with `edgar-operation: <operation id>`. Side effect, undone by `close_pull_request`, found by `find_pull_request`. See [Body notices and labels](#body-notices-and-labels). |
11
- | `close_pull_request` | `stage_output`: the output of `open_pull_request`; optional `text` | `url`, `state` | Closes without merging. A pull request that is merged or closed answers `skipped`, with no write. With `text`, the tool first adds it as one line of EDGAR's note, as `note_pull_request` does: the sweep gives the reason when a person closed the card of the pull request. |
12
- | `find_pull_request` | `operation_id`, `input`: the input of an `open_pull_request` call | `url`, `state` | `skipped` when the branch has no pull request. |
13
- | `linked_pull_requests` | `text`, `repo` | `pull_requests`: `url`, `state`, `title`, `body`, `files` (`path`, `patch`) | Reads each pull request of `repo` that `text` links, in any spelling of the repository: the first 5 links, 100 files each, and 4,000 characters of each patch. A link to another repository is left out with no call, so a card cannot bring code from elsewhere into the project's tracker. A link that answers 404 or 403 is left out. With no link to `repo`, the tool answers `skipped`, with no call. |
14
- | `note_pull_request` | `url`, `text`: one new item | `url`: the note | Adds an item to EDGAR's one note on the pull request, a comment that EDGAR finds by its hidden first line. The note's first sentence, "EDGAR's notes on this pull request, oldest first:", leads the list of items. The item keeps the lines of `text` under its bullet, so its paragraphs and lists stay. The first call makes the note. |
15
- | `update_pull_request` | `url`, `title`, `body`; optional `card`, `large_diff_lines`, `path_notices`, `checks`, `not_verified` | `url` | Gives an open pull request a new title and body, when a later change made them untrue. The body gets its notices and proof again, as `open_pull_request` writes them, and the operation line of this call. The review line of the first body is left out, because that review read the change before. A pull request that is merged or closed answers `skipped`, with no write. |
16
- | `attach_screenshot` | `url`; `shot`: `path`, `bytes` and `caption` of a PNG in the sandbox, with the `url` EDGAR serves it at when it is in `[storage]` and a flow's `video`, or `missing` | `attached`; `image` or `missing` | With a `url`, puts that address in the body and writes nothing to the repository. Otherwise stores the PNG on the branch `edgar/screenshots` of the pull request's repository, at `<run id>/preview-<hash>.png`, and puts it in the body pinned to the commit that holds it. The first picture of a repository starts that branch from an empty tree, so it shares no history with the code. A picture over 1 MB, one that cannot be read, or an upload that GitHub refuses gives the body one line, "The screenshot is missing:", with the reason, and the output says it too. A flow's `video` (`path`, `bytes`) goes to the same branch, at `<run id>/flow-<hash>.mp4`, as a link under the picture; a video over 1 MB or not stored gives the line "The video is missing:" with the reason, and the picture still shows. Only an input that is not a pull request fails. `update_pull_request` keeps the picture when it rewrites the body. |
17
- | `list_pull_requests` | `services`: a list of `repo`; optional `merged_within_hours` (1 to 720) | `pull_requests`: `url`, `branch`, `card`, `unmerged`; `complete` | One page of open pull requests per repository, read once however the services spell it (`git@github.com:o/r.git`, `https://github.com/o/r`, any letter case), on `edgar/<card>-<slug>` branches whose head is in that repository, so a fork's branch of that name is left out. With `merged_within_hours`, the pull requests merged within that many hours in place of the open ones, from one page of the 100 closed pull requests updated last. The engine passes the project's services. A service whose `repo` is not on github.com has none here, so `merge_watch` goes on for the others. With `merged_within_hours`, `unmerged` lists each pull request of the `Goes with:` line of the body that is not merged, as `url` and `state` (`open` or `closed`); one that answers 404 or 403 is `closed`. It is empty for the open ones and for a pull request that goes with none. `complete` is false when the page of a repository came back full, 100 pull requests, so one past them is not listed; the runtime log names that repository. |
18
- | `delete_closed_branches` | `services`: a list of `repo`; `closed_within_hours` (1 to 720) | `deleted`: `pull_request`, `branch` | Deletes the head branch of each pull request closed within that many hours, merged or not, from one page of the 100 closed pull requests updated last per repository. It deletes only an `edgar/<card>-<slug>` branch whose head is in that repository and that is not the base of its pull request, and only while the branch exists and no open pull request uses it, so `edgar/screenshots`, a fork's branch and a person's branch are never touched. A repository that deletes head branches on merge leaves those to GitHub, and a branch that a delete finds gone already (404 or 422) counts as done, with a log line. The built-in `merge_watch` calls it last, every 10 minutes, with `closed_within_hours = 24`. |
19
- | `pull_request_state` | `url` | `url`, `state`, `merged`, `review_state`, `approved_by`, `card`, `commit`, `branch`, `head_repo`, `mergeable`, `base_commit` | `review_state` comes from each reviewer's latest approval or change request. A change request made on a commit before the head is `pending` until its reviewer reviews again, whatever the others did, because a push answered it. `approved_by` lists the login of each reviewer whose latest one approves. `commit` is the merge commit once merged. `card` is `null` for a branch with no card. `branch` is the head branch and `head_repo` its repository as `owner/name`, a fork's for a fork, `null` when that repository was deleted. `mergeable` is `false` when the open pull request conflicts with its base branch, and `null` while GitHub computes it or once it is merged or closed. On a conflict, a third read gives `base_commit`, the newest commit of the base branch, to merge into the head. |
20
- | `wait_for_review` | `url` | as `pull_request_state` | The recheck of a `wait` stage for a review. This tool answers `skipped` while the pull request is open, no review has decided and it does not conflict with its base branch, and the output of `pull_request_state` once it is approved, has a change request, conflicts (`mergeable` is `false`), or is merged or closed. |
21
- | `wait_for_merge` | `url` | `url`, `merged`, `sha` | The recheck of a `wait` stage that ends on a merge or a close only. This tool answers `skipped` while the pull request is open, whatever its reviews say, `merged: true` with the merge commit as `sha` once it is merged, and `merged: false` with no `sha` once it is closed without a merge. |
22
- | `merge_pull_request` | `url`, `commit`, `changed_files` | `url`, `merged`, `commit` | Shipped turned off, approval `always`, no undo. Merges `commit` only, the head that `pull_request_state` gave and that the person approved; when the head has moved, GitHub merges nothing and the tool answers `invalid`. With `changed_files`, the call is EDGAR's own merge from a workflow stage: the engine runs it with no person when the count is under `[limits] self_merge_files`, and skips the stage at or past it. |
23
- | `merged_pull_request` | `repo`, `card` | `url`, `merged_at`, `commit` | The newest merged pull request of the card's `edgar/<card>-` branch, from the 100 closed pull requests updated last; a fork's is left out. `skipped` when there is none. |
24
- | `revert_pull_request` | `url` | `url`, `state` | Opens GitHub's revert of a merged pull request with GraphQL `revertPullRequest`, as a new pull request whose body says that a person merges it; no tool merges it. The revert already there, found by GitHub's branch name `revert-<number>-<branch>`, is answered instead of a second one. `skipped` when the pull request is not merged. Its undo is `close_pull_request`, its lookup `find_revert_pull_request`. A GraphQL error maps by its `type`: `NOT_FOUND` is `not_found`, `FORBIDDEN` `forbidden`, `UNPROCESSABLE` `invalid`, `RATE_LIMITED` a temporary `rate_limited`, and any other, or none, `tool_error`, with the type and message in `cause`. |
25
- | `find_revert_pull_request` | `operation_id`, `input`: the input of a `revert_pull_request` call | `url`, `state` | The lookup of `revert_pull_request`. `skipped` when there is no revert. |
26
- | `pull_request_checks` | `url` | `url`, `commit`, `state`, `merged`, `checks`, `failed`, `retry_after_seconds`, `summary`, `changed_files` | Reads the check runs and the commit statuses of the head commit, and `changed_files`, the files that the pull request changes. `state` is `failed` when one failed, else `pending` while one runs, else `passed`. A closed pull request, merged or not, is `closed` with no check read, `checks` 0 and `merged` from GitHub; `merged` is `false` while it is open. `failed` lists each failed check's `name` and details `url`. `retry_after_seconds` is 60 while pending, else `null`. `summary` is one sentence that a later stage posts as it is, such as `All 3 checks passed on 6dcb09b.`, `1 of 3 checks failed: test (<details url>).` or `2 checks still run.` See [Wait for CI](#wait-for-ci). |
27
- | `wait_for_checks` | `url` | as `pull_request_checks` | The recheck of a `wait` stage. A recheck that answers `done` ends the wait, so this tool answers `skipped` while a check runs, or while a pull request updated in the last 2 minutes has no check yet, and the output of `pull_request_checks` once every check has ended or the pull request is closed. |
28
- | `wait_for_passed_checks` | `url` | as `pull_request_checks` | The recheck of a `wait` stage that only passed checks end. It answers `skipped` while a check runs and also while a check has failed, so a later push or a rerun that passes ends the wait. A closed pull request ends it as `closed`. The built-in `remediate` uses it after its last repair: no review is asked for while a check is red. |
29
- | `ci_run` | `url` of a run, or of a job | `url`, `workflow`, `status`, `conclusion`, `commit`, `branch`, `attempt`, `jobs`, `logs`, `unread` | Reads a GitHub Actions run and each job of its latest attempt with its failed steps. For each failed job (`failure`, `timed_out`), at most 3, or for the job in a `/job/<id>` URL, it reads the log: the `##[error]` lines (at most 20) and an `excerpt` of the 120 lines up to the first error, at most 16,000 characters, with timestamps and colour codes removed. `gone` is `true` when GitHub no longer keeps the log. `unread` lists the failed jobs past the limit. |
30
- | `pull_request_discussion` | `url` | `url`, `reviews`, `threads`, `conversation`, `complete` | `reviews` holds each verdict, and each review with words; a wordless `COMMENTED` review is left out. `threads` holds each line comment with its `path`, `line`, the last 8 lines of its `hunk` and its `replies`. `conversation` holds the issue comments. EDGAR's own remarks stay, with `by`. A failed read is the failure, never an empty discussion. |
31
- | `dependabot_alerts` | `repo`; optional `number`, `state`, `package`, `ghsa`, `cve`, `limit` | `alerts`, `complete` | With `number`, that alert; the filters then must be empty, or `invalid_input`. Without it, newest first, every state unless `state` names some, at most `limit` (30, at most 100). Each alert has its `package`, `ecosystem`, `severity`, `vulnerable_range`, `first_patched`, `manifest`, `scope`, `ghsa`, `cve` and `summary`. `ghsa` and `cve` match within a page of 100. |
32
- | `branch_protection` | `repo`, `branch` | `branch`, `protected`, `pull_request_required`, `required_approvals`, `required_checks`, `rules`, `classic` | Joins the branch's own protection, each rule and ruleset that applies (`/rules/branches`), and the classic rule. GitHub shows the classic rule to admins only: `classic` is then `unreadable`, and `pull_request_required` and `required_approvals` are `null` unless a rule settles them. |
33
- | `dismiss_dependabot_alert` | `repo`, `number`, `reason`, `comment` | `repo`, `number`, `url`, `reason`, `reopen` | Approval `always`. Side effect, undone by `reopen_dependabot_alert`, found by `find_dependabot_dismissal`. `reason` is one of GitHub's reasons: `fix_started`, `inaccurate`, `no_bandwidth`, `not_used`, `tolerable_risk`. `comment` has 1 to 280 characters. See [Dismiss a Dependabot alert](#dismiss-a-dependabot-alert). |
34
- | `reopen_dependabot_alert` | `stage_output`: the output of `dismiss_dependabot_alert` | `repo`, `number`, `url`, `reopened` | The undo of `dismiss_dependabot_alert`. It opens the alert again when `reopen` is `true` and the alert is still dismissed. Otherwise it writes nothing and answers `reopened: false`. |
35
- | `find_dependabot_dismissal` | `operation_id`, `input`: the input of a `dismiss_dependabot_alert` call | as `dismiss_dependabot_alert` | The lookup of `dismiss_dependabot_alert`. `done` when the alert is dismissed with the `reason` and the `comment` of the call. `skipped` otherwise. |
7
+ | Tool | Input | Output | Notes |
8
+ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
+ | `push_branch` | `repo`, and `branch` or `to`; optional `suffix` | `branch`, `commit` | Runs `git rev-parse` and `git push origin <branch>` in the sandbox, never forced. With `to`, or with `branch` and `suffix`, it pushes the head of the sandbox to `to` or to `<branch>-<suffix>`, so one sandbox can open a second pull request, such as a companion. Refuses a branch outside `edgar/` or with `:`, `+` or `..`. Needs `git:push` and `sandbox:read`. |
10
+ | `open_pull_request` | `repo`, `branch`, `title`, `body`, `review`; optional `base`, `card`, `labels`, `large_diff_lines`, `path_notices`, `checks`, `not_verified`, `proof`, `proof_passes`, `related`, `after`, `first` | `url`, `number`, `commit` | Opens onto `base`, the service's default branch, or onto `default_base` when the call names none. The body ends with `edgar-operation: <operation id>`. With `after`, the URL of a companion pull request, the body names it on the `Goes with:` line and says to merge it first, because this one is built on it. With `first`, why the fix needs this companion, the body says to merge this one first. `commit` is the head commit of the pull request. Side effect, undone by `close_pull_request`, found by `find_pull_request`. See [Body notices and labels](#body-notices-and-labels). |
11
+ | `close_pull_request` | `stage_output`: the output of `open_pull_request`; optional `text` | `url`, `state` | Closes without merging. A pull request that is merged or closed answers `skipped`, with no write. With `text`, the tool first adds it as one line of EDGAR's note, as `note_pull_request` does: the sweep gives the reason when a person closed the card of the pull request. |
12
+ | `find_pull_request` | `operation_id`, `input`: the input of an `open_pull_request` call | `url`, `state` | `skipped` when the branch has no pull request. |
13
+ | `linked_pull_requests` | `text`, `repo` | `pull_requests`: `url`, `state`, `title`, `body`, `files` (`path`, `patch`) | Reads each pull request of `repo` that `text` links, in any spelling of the repository: the first 5 links, 100 files each, and 4,000 characters of each patch. A link to another repository is left out with no call, so a card cannot bring code from elsewhere into the project's tracker. A link that answers 404 or 403 is left out. With no link to `repo`, the tool answers `skipped`, with no call. |
14
+ | `note_pull_request` | `url`, `text`: one new item | `url`: the note | Adds an item to EDGAR's one note on the pull request, a comment that EDGAR finds by its hidden first line. The note's first sentence, "EDGAR's notes on this pull request, oldest first:", leads the list of items. The item keeps the lines of `text` under its bullet, so its paragraphs and lists stay. The first call makes the note. |
15
+ | `request_reviewers` | `url`, `reviewers`, `team_reviewers` | `url`, `requested` | Asks people (by login) and teams (by slug) to review the pull request. Skipped when both lists are empty, or when GitHub refuses the request with 422, such as for a person who can no longer review in the repository. A side effect with no undo: a review request only asks. |
16
+ | `update_pull_request` | `url`, `title`, `body`; optional `card`, `large_diff_lines`, `path_notices`, `checks`, `not_verified` | `url` | Gives an open pull request a new title and body, when a later change made them untrue. The body gets its notices and proof again, as `open_pull_request` writes them, and the operation line of this call. The review line of the first body is left out, because that review read the change before. A pull request that is merged or closed answers `skipped`, with no write. |
17
+ | `attach_screenshot` | `url`; `shot`: `path`, `bytes` and `caption` of a PNG in the sandbox, with the `url` EDGAR serves it at when it is in `[storage]` and a flow's `video`, or `missing` | `attached`; `image` or `missing` | With a `url`, puts that address in the body and writes nothing to the repository. Otherwise stores the PNG on the branch `edgar/screenshots` of the pull request's repository, at `<run id>/preview-<hash>.png`, and puts it in the body pinned to the commit that holds it. The first picture of a repository starts that branch from an empty tree, so it shares no history with the code. A picture over 1 MB, one that cannot be read, or an upload that GitHub refuses gives the body one line, "The screenshot is missing:", with the reason, and the output says it too. A flow's `video` (`path`, `bytes`) goes to the same branch, at `<run id>/flow-<hash>.mp4`, as a link under the picture; a video over 1 MB or not stored gives the line "The video is missing:" with the reason, and the picture still shows. Only an input that is not a pull request fails. `update_pull_request` keeps the picture when it rewrites the body. |
18
+ | `list_pull_requests` | `services`: a list of `repo`; optional `merged_within_hours` (1 to 720), and with it `unless_noted` | `pull_requests`: `url`, `branch`, `card`, `unmerged`; `complete` | One page of open pull requests per repository, read once however the services spell it (`git@github.com:o/r.git`, `https://github.com/o/r`, any letter case), on `edgar/<card>-<slug>` branches whose head is in that repository, so a fork's branch of that name is left out. With `merged_within_hours`, the pull requests merged within that many hours in place of the open ones, from one page of the 100 closed pull requests updated last. With `unless_noted` too, each merged pull request whose EDGAR note already holds that text as one of its lines is left out, after one read of its comments, so `merge_watch` handles a merge once. The engine passes the project's services. A service whose `repo` is not on github.com has none here, so `merge_watch` goes on for the others. With `merged_within_hours`, `unmerged` lists each pull request of the `Goes with:` line of the body that is not merged, as `url` and `state` (`open` or `closed`); one that answers 404 or 403 is `closed`. It is empty for the open ones and for a pull request that goes with none. With `merged_within_hours`, a pull request whose body opens the companion line of `first` has `companion: true`, so `merge_watch` leaves its card for the fix built on it. `complete` is false when the page of a repository came back full, 100 pull requests, so one past them is not listed; the runtime log names that repository. |
19
+ | `delete_closed_branches` | `services`: a list of `repo`; `closed_within_hours` (1 to 720) | `deleted`: `pull_request`, `branch` | Deletes the head branch of each pull request closed within that many hours, merged or not, from one page of the 100 closed pull requests updated last per repository. It deletes only an `edgar/<card>-<slug>` branch whose head is in that repository and that is not the base of its pull request, and only while the branch exists and no open pull request uses it, so `edgar/screenshots`, a fork's branch and a person's branch are never touched. A repository that deletes head branches on merge leaves those to GitHub, and a branch that a delete finds gone already (404 or 422) counts as done, with a log line. The built-in `merge_watch` calls it last, every 10 minutes, with `closed_within_hours = 24`. |
20
+ | `pull_request_state` | `url` | `url`, `state`, `merged`, `review_state`, `approved_by`, `card`, `commit`, `branch`, `head_repo`, `mergeable`, `base_commit` | `review_state` comes from each reviewer's latest approval or change request. A change request made on a commit before the head is `pending` until its reviewer reviews again, whatever the others did, because a push answered it. `approved_by` lists the login of each reviewer whose latest one approves. `commit` is the merge commit once merged. `card` is `null` for a branch with no card. `branch` is the head branch and `head_repo` its repository as `owner/name`, a fork's for a fork, `null` when that repository was deleted. `mergeable` is `false` when the open pull request conflicts with its base branch, and `null` while GitHub computes it or once it is merged or closed. On a conflict, a third read gives `base_commit`, the newest commit of the base branch, to merge into the head. |
21
+ | `wait_for_review` | `url` | as `pull_request_state` | The recheck of a `wait` stage for a review. This tool answers `skipped` while the pull request is open, no review has decided and it does not conflict with its base branch, and the output of `pull_request_state` once it is approved, has a change request, conflicts (`mergeable` is `false`), or is merged or closed. |
22
+ | `wait_for_merge` | `url` | `url`, `merged`, `sha` | The recheck of a `wait` stage that ends on a merge or a close only. This tool answers `skipped` while the pull request is open, whatever its reviews say, `merged: true` with the merge commit as `sha` once it is merged, and `merged: false` with no `sha` once it is closed without a merge. |
23
+ | `merge_pull_request` | `url`, `commit`, `changed_files` | `url`, `merged`, `commit` | Shipped turned off, approval `always`, no undo. Merges `commit` only, the head that `pull_request_state` gave and that the person approved; when the head has moved, GitHub merges nothing and the tool answers `invalid`. With `changed_files`, the call is EDGAR's own merge from a workflow stage: the engine runs it with no person when the count is under `[limits] self_merge_files`, and skips the stage at or past it. |
24
+ | `merged_pull_request` | `repo`, `card` | `url`, `merged_at`, `commit` | The newest merged pull request of the card's `edgar/<card>-` branch, from the 100 closed pull requests updated last; a fork's is left out. `skipped` when there is none. |
25
+ | `revert_pull_request` | `url` | `url`, `state` | Opens GitHub's revert of a merged pull request with GraphQL `revertPullRequest`, as a new pull request whose body says that a person merges it; no tool merges it. The revert already there, found by GitHub's branch name `revert-<number>-<branch>`, is answered instead of a second one. `skipped` when the pull request is not merged. Its undo is `close_pull_request`, its lookup `find_revert_pull_request`. A GraphQL error maps by its `type`: `NOT_FOUND` is `not_found`, `FORBIDDEN` `forbidden`, `UNPROCESSABLE` `invalid`, `RATE_LIMITED` a temporary `rate_limited`, and any other, or none, `tool_error`, with the type and message in `cause`. |
26
+ | `find_revert_pull_request` | `operation_id`, `input`: the input of a `revert_pull_request` call | `url`, `state` | The lookup of `revert_pull_request`. `skipped` when there is no revert. |
27
+ | `pull_request_checks` | `url` | `url`, `commit`, `state`, `merged`, `checks`, `failed`, `retry_after_seconds`, `summary`, `changed_files` | Reads the check runs and the commit statuses of the head commit, and `changed_files`, the files that the pull request changes. `state` is `failed` when one failed, else `pending` while one runs, else `passed`. A closed pull request, merged or not, is `closed` with no check read, `checks` 0 and `merged` from GitHub; `merged` is `false` while it is open. `failed` lists each failed check's `name` and details `url`. `retry_after_seconds` is 60 while pending, else `null`. `summary` is one sentence that a later stage posts as it is, such as `All 3 checks passed on 6dcb09b.`, `1 of 3 checks failed: test (<details url>).` or `2 checks still run.` See [Wait for CI](#wait-for-ci). |
28
+ | `wait_for_checks` | `url` | as `pull_request_checks` | The recheck of a `wait` stage. A recheck that answers `done` ends the wait, so this tool answers `skipped` while a check runs, or while a pull request updated in the last 2 minutes has no check yet, and the output of `pull_request_checks` once every check has ended or the pull request is closed. |
29
+ | `wait_for_passed_checks` | `url` | as `pull_request_checks` | The recheck of a `wait` stage that only passed checks end. It answers `skipped` while a check runs and also while a check has failed, so a later push or a rerun that passes ends the wait. A closed pull request ends it as `closed`. The built-in `remediate` uses it after its last repair: no review is asked for while a check is red. |
30
+ | `ci_run` | `url` of a run, or of a job | `url`, `workflow`, `status`, `conclusion`, `commit`, `branch`, `attempt`, `jobs`, `logs`, `unread` | Reads a GitHub Actions run and each job of its latest attempt with its failed steps. For each failed job (`failure`, `timed_out`), at most 3, or for the job in a `/job/<id>` URL, it reads the log: the `##[error]` lines (at most 20) and an `excerpt` of the 120 lines up to the first error, at most 16,000 characters, with timestamps and colour codes removed. `gone` is `true` when GitHub no longer keeps the log. `unread` lists the failed jobs past the limit. |
31
+ | `pull_request_discussion` | `url` | `url`, `reviews`, `threads`, `conversation`, `complete` | `reviews` holds each verdict, and each review with words; a wordless `COMMENTED` review is left out. `threads` holds each line comment with its `path`, `line`, the last 8 lines of its `hunk` and its `replies`. `conversation` holds the issue comments. EDGAR's own remarks stay, with `by`. A failed read is the failure, never an empty discussion. |
32
+ | `code_owners` | `url` | `source`, `reviewers`, `team_reviewers`, `who_can_act` | Finds who should review the pull request, at most two, never a bot or its author, who is EDGAR on its own pull request. The CODEOWNERS file of the base branch (`.github/CODEOWNERS`, `CODEOWNERS` or `docs/CODEOWNERS`, the first one found) gives them when it names an owner of a changed file, by the last pattern that matches each file: `source` is `codeowners`, and an owner who owns more of the files comes first. Else the history of the files gives them: each commit of the last 12 months to a changed file counts for its author, halved for each 90 days of its age, so a person who changed the files often and lately comes before the one who made the newest change; `source` is `history`. `who_can_act` says why each one, with `github` for a login and `name` for a team. Skipped when there is none. It reads the first 100 files, and the newest 100 commits of each of the first 10 files: at most 15 requests. |
33
+ | `dependabot_alerts` | `repo`; optional `number`, `state`, `package`, `ghsa`, `cve`, `limit` | `alerts`, `complete` | With `number`, that alert; the filters then must be empty, or `invalid_input`. Without it, newest first, every state unless `state` names some, at most `limit` (30, at most 100). Each alert has its `package`, `ecosystem`, `severity`, `vulnerable_range`, `first_patched`, `manifest`, `scope`, `ghsa`, `cve` and `summary`. `ghsa` and `cve` match within a page of 100. |
34
+ | `branch_protection` | `repo`, `branch` | `branch`, `protected`, `pull_request_required`, `required_approvals`, `required_checks`, `rules`, `classic` | Joins the branch's own protection, each rule and ruleset that applies (`/rules/branches`), and the classic rule. GitHub shows the classic rule to admins only: `classic` is then `unreadable`, and `pull_request_required` and `required_approvals` are `null` unless a rule settles them. |
35
+ | `dismiss_dependabot_alert` | `repo`, `number`, `reason`, `comment` | `repo`, `number`, `url`, `reason`, `reopen` | Approval `always`. Side effect, undone by `reopen_dependabot_alert`, found by `find_dependabot_dismissal`. `reason` is one of GitHub's reasons: `fix_started`, `inaccurate`, `no_bandwidth`, `not_used`, `tolerable_risk`. `comment` has 1 to 280 characters. See [Dismiss a Dependabot alert](#dismiss-a-dependabot-alert). |
36
+ | `reopen_dependabot_alert` | `stage_output`: the output of `dismiss_dependabot_alert` | `repo`, `number`, `url`, `reopened` | The undo of `dismiss_dependabot_alert`. It opens the alert again when `reopen` is `true` and the alert is still dismissed. Otherwise it writes nothing and answers `reopened: false`. |
37
+ | `find_dependabot_dismissal` | `operation_id`, `input`: the input of a `dismiss_dependabot_alert` call | as `dismiss_dependabot_alert` | The lookup of `dismiss_dependabot_alert`. `done` when the alert is dismissed with the `reason` and the `comment` of the call. `skipped` otherwise. |
36
38
 
37
39
  `repo` is `owner/name`, `git@github.com:owner/name.git` or `https://github.com/owner/name`.
38
40
 
@@ -84,19 +86,20 @@ A later stage reads `stages.ci.output.state`, and gives a failed check's `url` t
84
86
 
85
87
  Each extra is optional. With none, `open_pull_request` sends one request, as before.
86
88
 
87
- - `card`: the run's card, with its `id`, `title` and `url`. The title becomes `<id>: <card title>`, such as `ENG-12: Login times out`, in place of `title`, and the body opens with `Card: [ENG-12](<url>)`, or `Card: ENG-12` for a card with no address. `update_pull_request` writes both the same way. The built-in workflows pass the run's card.
89
+ - `card`: the run's card, with its `id`, `title` and `url`. The title becomes `<id>: <title>`, such as `ENG-12: Raise the login timeout`, and the body opens with `Card: [ENG-12](<url>)`, or `Card: ENG-12` for a card with no address. `update_pull_request` writes both the same way. The built-in workflows pass the run's card.
90
+ - A title past 72 characters is cut where a word ends, with no ellipsis, and a trailing tag in brackets, such as `[build-image]`, stays whole at its end: a repository can start a build from a tag in the merge commit's message, which holds the title. The built-in workflows pass the title that `implement` wrote, else the card's title.
88
91
  - `labels`: the labels the pull request gets, with each label of `[extensions.github] pr_labels` first, added after it opens (`POST /repos/{owner}/{repo}/issues/{number}/labels`), also when a retry reads the pull request back. A refused label is written to the runtime log and the outcome stays `done`, because the change is open and a label only sorts it.
89
92
  - `large_diff_lines`: when the change has more changed lines than this, the body says `This is a large change: 211 lines across 2 files.`
90
93
  - `path_notices`: a list of `{ prefix, notice }`. When a changed file's path starts with `prefix`, the body carries `notice`, once.
91
94
 
92
- - `checks`: the output of a check stage, such as `stages.checks.output`. The body lists each check that ended with exit code 0 under the `## Verified` heading, and says when one passed only on its second run, after a failure. Each other check goes under `## Not verified`, and a check that fails the same way on the base commit says that this change did not cause it. The lists come from the exit codes that the check stage recorded, and from no words of a model. The body shows the name and the exit code only, never the output of a check.
95
+ - `checks`: the output of a check stage, such as `stages.checks.output`. The body lists each check that ended with exit code 0 under the `## Verified` heading, and says when one passed only on its second run, after a failure. Each other check goes under `## Not verified`, and a check that fails the same way on the base commit says that this change did not cause it. The lists come from the exit codes that the check stage recorded, and from no words of a model. The body shows the name and the exit code only, never the output of a check. A check that sets `covers` in its service's config names the changed files it covers, such as `` `unit` passed, covering `src/a.rs` ``, or says `but it covers none of the changed files`, so a reader can tell a check that never read the change.
93
96
  - `not_verified`: a list of things that the author of the change did not check, one line each. They go under `## Not verified`, after the checks.
94
- - `proof`: the output of a `check = "proof"` stage. The body gets a `## The change's own proof` section that says whether the proof passed, failed or did not run, with its command, its exit code and the end of its output folded away. With `on_base`, it says how a proof that passed ended on the base commit: `failed` proves the change, and `passed` or `unknown` (EDGAR could not tell) does not. It is advice and blocks nothing. `proof_passes` adds what the author said passing looks like.
97
+ - `proof`: the output of a `check = "proof"` stage. The body gets a `## The change's own proof` section that says whether the proof passed, failed or did not run, with its command, its exit code and the end of its output folded away. With `on_base`, it says how a proof that passed ended on the base commit, without the change: `failed` shows the fault and the fix, and `passed` says that the proof also passes without the change, so it does not show the fault, as `unknown` (EDGAR could not tell) does. It is advice and blocks nothing. `proof_passes` adds what the author said passing looks like.
95
98
  - `related`: one `https:` URL, or a list of at most 5, of the pull requests that this one goes with. The body carries `Goes with: <url1>, <url2>` after the text of `body`. A list of more than 5, or a URL that is not `https:`, is refused as invalid input.
96
99
 
97
100
  The built-in `remediate` passes `large_diff_lines = 200`, and the `[[services.<name>.path_notices]]` of the card's service.
98
101
 
99
- The size and the paths come from `GET /repos/{owner}/{repo}/compare/{base}...{branch}`, read before the pull request opens. When the compare call fails, the pull request opens with no large-change line and no path notice, and the failure goes to the runtime log, because an optional warning never costs a finished fix its pull request. The notices go after `body`, then the proof, then the review line:
102
+ The size and the paths come from `GET /repos/{owner}/{repo}/compare/{base}...{branch}`, read before the pull request opens. When the compare call fails, the pull request opens with no large-change line and no path notice, and the failure goes to the runtime log, because an optional warning never costs a finished fix its pull request. The notices go after `body`, then the proof, then the review under its own `## Review` heading:
100
103
 
101
104
  ```toml
102
105
  input = { repo = "...", branch = "...", title = "...", body = "...", review = "", labels = [
@@ -431,6 +434,7 @@ Only an App's commits are signed. With no `app`, the calls use `GITHUB_TOKEN`, a
431
434
  | `attach_screenshot` | `contents: write`, `pull_requests: write` | `repo` (`public_repo` for a public repository) |
432
435
  | `labels` of `open_pull_request` | `issues: write` or `pull_requests: write` | `repo` |
433
436
  | `note_pull_request` | `issues: write` or `pull_requests: write` | `repo` |
437
+ | `request_reviewers` | `pull_requests: write` | `repo` |
434
438
  | `pull_request_*`, `wait_for_review`, `wait_for_merge`, `find_pull_request`, `linked_pull_requests`, `list_pull_requests` | `pull_requests: read` | `repo` |
435
439
  | `delete_closed_branches` | `contents: write`, `pull_requests: read` | `repo` (`public_repo` for a public repository) |
436
440
  | `revert_pull_request` | `contents: write`, `pull_requests: write` | `repo` (`public_repo` for a public repository) |
@@ -440,6 +444,7 @@ Only an App's commits are signed. With no `app`, the calls use `GITHUB_TOKEN`, a
440
444
  | `dependabot_alerts`, `find_dependabot_dismissal`, the Dependabot feed | `dependabot_alerts: read` | `security_events` or `repo` |
441
445
  | `dismiss_dependabot_alert`, `reopen_dependabot_alert` | `dependabot_alerts: write` | `security_events` or `repo` |
442
446
  | `branch_protection` | `metadata: read`; `administration: read` for the classic rule | `repo` |
447
+ | `code_owners` | `pull_requests: read`, `contents: read` | `repo` |
443
448
 
444
449
  No check reads a token's rights ahead of its first call: the engine runs no extension at `edgar check`. GitHub says what a refused call needs in `X-Accepted-GitHub-Permissions` (fine-grained tokens and Apps) or `X-Accepted-OAuth-Scopes` (classic tokens). A 403 that is not a rate limit is `permanent_failure(forbidden)`, which the engine does not retry, and its message names that header's value:
445
450
 
@@ -524,6 +529,7 @@ Run on 2026-11-11 in `packages/extensions/ext-github`. The answer shapes of chec
524
529
  - shortcut: the Dependabot feed closes only the cards that this process opened, so an alert fixed while EDGAR was stopped leaves its card open. Upgrade when a service can keep state.
525
530
  - shortcut: `dismiss_dependabot_alert` reads an alert that holds its own `reason` and `comment` as its own. A person who dismissed with the same words is read as the call, so the undo opens that alert again. Upgrade when GitHub's answer says which call dismissed the alert.
526
531
  - shortcut: the compare that the body notices read lists at most 300 files.
532
+ - shortcut: `code_owners` reads the first 100 files of a pull request, and the newest 100 commits of the base branch for each of its first 10 files, with no line-by-line blame. Upgrade to GraphQL blame when the owners of a large change are missed.
527
533
  - shortcut: pull request lists and reviews read one page of 100. Upgrade to `Link` pagination when a repository holds more than 100 open pull requests.
528
534
  - shortcut: `find_pull_request` matches by branch. The `edgar-operation` line is for people and audits. Upgrade to matching the line if two operations can share a branch.
529
535
  - shortcut: `push_branch` pushes the sandbox's `origin` and does not compare it with `repo`. Upgrade when one sandbox holds several repositories.
@@ -25,6 +25,7 @@ export declare const tools: {
25
25
  exit_code: number | null;
26
26
  pre_existing?: boolean | undefined;
27
27
  runs?: number | undefined;
28
+ covered?: string[] | undefined;
28
29
  }[];
29
30
  } | undefined;
30
31
  not_verified?: string[] | undefined;
@@ -38,9 +39,12 @@ export declare const tools: {
38
39
  } | undefined;
39
40
  proof_passes?: string | undefined;
40
41
  related?: string | string[] | undefined;
42
+ after?: string | undefined;
43
+ first?: string | undefined;
41
44
  }, {
42
45
  url: string;
43
46
  number: number;
47
+ commit?: string | undefined;
44
48
  }, "GITHUB_TOKEN">;
45
49
  update_pull_request: import("@kana-ai/edgar-sdk").Tool<{
46
50
  url: string;
@@ -63,6 +67,7 @@ export declare const tools: {
63
67
  exit_code: number | null;
64
68
  pre_existing?: boolean | undefined;
65
69
  runs?: number | undefined;
70
+ covered?: string[] | undefined;
66
71
  }[];
67
72
  } | undefined;
68
73
  not_verified?: string[] | undefined;
@@ -135,6 +140,7 @@ export declare const tools: {
135
140
  repo: string;
136
141
  }[];
137
142
  merged_within_hours?: number | undefined;
143
+ unless_noted?: string | undefined;
138
144
  }, {
139
145
  pull_requests: {
140
146
  url: string;
@@ -144,6 +150,7 @@ export declare const tools: {
144
150
  url: string;
145
151
  state: "closed" | "open";
146
152
  }[];
153
+ companion?: true | undefined;
147
154
  }[];
148
155
  complete: boolean;
149
156
  }, "GITHUB_TOKEN">;
@@ -375,6 +382,26 @@ export declare const tools: {
375
382
  }[];
376
383
  complete: boolean;
377
384
  }, "GITHUB_TOKEN">;
385
+ code_owners: import("@kana-ai/edgar-sdk").Tool<{
386
+ url: string;
387
+ }, {
388
+ source: "codeowners" | "history";
389
+ reviewers: string[];
390
+ team_reviewers: string[];
391
+ who_can_act: {
392
+ github?: string | undefined;
393
+ name?: string | undefined;
394
+ why: string;
395
+ }[];
396
+ }, "GITHUB_TOKEN">;
397
+ request_reviewers: import("@kana-ai/edgar-sdk").Tool<{
398
+ url: string;
399
+ reviewers: string[];
400
+ team_reviewers: string[];
401
+ }, {
402
+ url: string;
403
+ requested: string[];
404
+ }, "GITHUB_TOKEN">;
378
405
  merged_pull_request: import("@kana-ai/edgar-sdk").Tool<{
379
406
  repo: string;
380
407
  card: string;
@@ -441,6 +468,8 @@ export declare const tools: {
441
468
  thread: string;
442
469
  };
443
470
  trust?: "outside" | "team";
471
+ requested_by?: string;
472
+ requested_by_id?: string;
444
473
  };
445
474
  };
446
475
  parent?: string;
@@ -563,6 +592,7 @@ export declare const tools: {
563
592
  repo: string;
564
593
  branch?: string | undefined;
565
594
  to?: string | undefined;
595
+ suffix?: string | undefined;
566
596
  }, {
567
597
  branch: string;
568
598
  commit: string;
package/dist/src/index.js CHANGED
@@ -7,6 +7,7 @@ import { alertTools } from "#tools/alerts";
7
7
  import { deleteClosedBranches, pushBranch } from "#tools/branch";
8
8
  import { checkTools } from "#tools/checks";
9
9
  import { discussionTools } from "#tools/discussion";
10
+ import { ownerTools } from "#tools/owners";
10
11
  import { pullRequestTools } from "#tools/pull-request";
11
12
  import { repositoryTools } from "#tools/repository";
12
13
  import { revertTools } from "#tools/revert";
@@ -20,6 +21,7 @@ export const tools = {
20
21
  ...pullRequestTools,
21
22
  ...checkTools,
22
23
  ...discussionTools,
24
+ ...ownerTools,
23
25
  ...repositoryTools,
24
26
  ...revertTools,
25
27
  ...alertTools,
@@ -535,3 +535,56 @@ export declare const issueEvent: z.ZodObject<{
535
535
  type: z.ZodOptional<z.ZodString>;
536
536
  }, z.core.$strip>>>;
537
537
  }, z.core.$strip>;
538
+ /** A pull request with its writer and its base branch, which `code_owners` leaves out of the people it finds and reads the history of. */
539
+ export declare const authoredPull: z.ZodObject<{
540
+ html_url: z.ZodString;
541
+ number: z.ZodNumber;
542
+ state: z.ZodEnum<{
543
+ closed: "closed";
544
+ open: "open";
545
+ }>;
546
+ merged_at: z.ZodNullable<z.ZodString>;
547
+ merge_commit_sha: z.ZodNullable<z.ZodString>;
548
+ updated_at: z.ZodString;
549
+ head: z.ZodObject<{
550
+ ref: z.ZodString;
551
+ sha: z.ZodString;
552
+ repo: z.ZodOptional<z.ZodNullable<z.ZodObject<{
553
+ full_name: z.ZodString;
554
+ }, z.core.$strip>>>;
555
+ }, z.core.$strip>;
556
+ user: z.ZodNullable<z.ZodObject<{
557
+ login: z.ZodString;
558
+ type: z.ZodOptional<z.ZodString>;
559
+ }, z.core.$strip>>;
560
+ base: z.ZodObject<{
561
+ ref: z.ZodString;
562
+ }, z.core.$strip>;
563
+ }, z.core.$strip>;
564
+ /** A file of `GET /repos/{owner}/{repo}/contents/{path}`, its text in base64. */
565
+ export declare const fileContent: z.ZodObject<{
566
+ content: z.ZodString;
567
+ encoding: z.ZodLiteral<"base64">;
568
+ }, z.core.$strip>;
569
+ /** One commit of `GET /repos/{owner}/{repo}/commits`: `author` is the GitHub user of its author, `null` when the author's email matches none. */
570
+ export declare const listedCommit: z.ZodObject<{
571
+ sha: z.ZodString;
572
+ author: z.ZodNullable<z.ZodObject<{
573
+ login: z.ZodString;
574
+ type: z.ZodOptional<z.ZodString>;
575
+ }, z.core.$strip>>;
576
+ commit: z.ZodObject<{
577
+ author: z.ZodNullable<z.ZodObject<{
578
+ date: z.ZodString;
579
+ }, z.core.$strip>>;
580
+ }, z.core.$strip>;
581
+ }, z.core.$strip>;
582
+ /** The answer of `POST /repos/{owner}/{repo}/pulls/{n}/requested_reviewers`: the pull request with each person and team it now asks. */
583
+ export declare const reviewRequest: z.ZodObject<{
584
+ requested_reviewers: z.ZodDefault<z.ZodArray<z.ZodObject<{
585
+ login: z.ZodString;
586
+ }, z.core.$strip>>>;
587
+ requested_teams: z.ZodDefault<z.ZodArray<z.ZodObject<{
588
+ slug: z.ZodString;
589
+ }, z.core.$strip>>>;
590
+ }, z.core.$strip>;
@@ -249,3 +249,21 @@ export const issueEvent = z.object({
249
249
  actor: actor.nullable(),
250
250
  assignee: actor.nullish(),
251
251
  });
252
+ /** A pull request with its writer and its base branch, which `code_owners` leaves out of the people it finds and reads the history of. */
253
+ export const authoredPull = pull.extend({
254
+ user: actor.nullable(),
255
+ base: z.object({ ref: z.string() }),
256
+ });
257
+ /** A file of `GET /repos/{owner}/{repo}/contents/{path}`, its text in base64. */
258
+ export const fileContent = z.object({ content: z.string(), encoding: z.literal("base64") });
259
+ /** One commit of `GET /repos/{owner}/{repo}/commits`: `author` is the GitHub user of its author, `null` when the author's email matches none. */
260
+ export const listedCommit = z.object({
261
+ sha: z.string(),
262
+ author: actor.nullable(),
263
+ commit: z.object({ author: z.object({ date: z.string() }).nullable() }),
264
+ });
265
+ /** The answer of `POST /repos/{owner}/{repo}/pulls/{n}/requested_reviewers`: the pull request with each person and team it now asks. */
266
+ export const reviewRequest = z.object({
267
+ requested_reviewers: z.array(person).default([]),
268
+ requested_teams: z.array(z.object({ slug: z.string() })).default([]),
269
+ });