github

Typed GitHub tools for agents. Each operation (ghPrGet, ghIssueComment, ...) raises its own effect, so a policy can approve exactly the operations it means to. Approving a pull request is its own effect, separate from reviewing it, so it can be forbidden by name. Every write puts the text it is about to post in the interrupt payload, since it goes out under the approver's name. GitHub treats a pull request as an issue, so the issue tools (ghIssueComment, ghIssueClose, ghIssueLabel) take pull request numbers too. There is no function to create, update, or merge a pull request. Every tool operates on one repository. With owner and repo left empty it uses the origin remote of the agent working directory, which agency agent sets for you; under plain agency run nothing sets it, so pass both names or call setAgentCwd first. Approving an effect "always" pins the approval to that one repository. The coding agent carries all of these tools and the review agent carries the reads, through the githubTools and githubReadTools bundles in std::agents/lib/toolkits.

The credential comes from GITHUB_TOKEN / GH_TOKEN, then gh auth token, then the system keyring (setSecret("github-token", ...)). No tool ever takes or returns a token.

import { ghPrGet, ghPrFiles, ghPrReview } from "std::github"

node main() {
  const pr = ghPrGet(1002) with approve
  print(pr.title)
  const files = ghPrFiles(1002) with approve
  for (file in files) {
    print("${file.path}: +${file.additions} -${file.deletions}")
  }
  // One interrupt, one request, however many inline comments.
  ghPrReview(1002, "COMMENT", "Two small things.", [
    { path: "lib/a.ts", line: 12, body: "This can be a const." },
  ]) with approve
}

Types

PrState

export type PrState = "open" | "closed" | "all"

(source)

IssueState

export type IssueState = "open" | "closed" | "all"

(source)

ReviewEvent

export type ReviewEvent = "COMMENT" | "REQUEST_CHANGES"

(source)

DiffSide

export type DiffSide = "LEFT" | "RIGHT"

(source)

CloseReason

export type CloseReason = "completed" | "not_planned"

(source)

ReviewComment

export type ReviewComment = {
  path: string;
  line: number;
  body: string;
  side?: DiffSide
}

(source)

PrListItem

export type PrListItem = {
  number: number;
  title: string;
  state: string;
  author: string;
  base: string;
  head: string;
  headSha: string;
  draft: boolean;
  body: string;
  url: string
}

(source)

PrSummary

export type PrSummary = {
  number: number;
  title: string;
  state: string;
  author: string;
  base: string;
  head: string;
  headSha: string;
  draft: boolean;
  body: string;
  url: string;
  additions: number;
  deletions: number;
  changedFiles: number
}

(source)

PrFile

export type PrFile = {
  path: string;
  status: string;
  additions: number;
  deletions: number;
  patch: string
}

(source)

ReviewSummary

export type ReviewSummary = {
  id: number;
  author: string;
  state: string;
  body: string;
  submittedAt: string
}

(source)

ReviewCommentInfo

export type ReviewCommentInfo = {
  id: number;
  path: string;
  line?: number;
  author: string;
  body: string;
  url: string
}

(source)

CheckRun

export type CheckRun = {
  name: string;
  status: string;
  conclusion?: string;
  url: string
}

(source)

IssueSummary

export type IssueSummary = {
  number: number;
  title: string;
  state: string;
  author: string;
  labels: string[];
  assignees: string[];
  body: string;
  url: string
}

(source)

CommentInfo

export type CommentInfo = {
  id: number;
  author: string;
  body: string;
  createdAt: string;
  url: string
}

(source)

Effects

std::github::prGet

@always(owner, repo)
effect std::github::prGet {
  owner: string;
  repo: string;
  number: number
}

(source)

std::github::prList

@always(owner, repo)
effect std::github::prList {
  owner: string;
  repo: string;
  state: string;
  base: string;
  perPage: number;
  page: number
}

(source)

std::github::prDiff

@always(owner, repo)
effect std::github::prDiff {
  owner: string;
  repo: string;
  number: number
}

(source)

std::github::prFiles

@always(owner, repo)
effect std::github::prFiles {
  owner: string;
  repo: string;
  number: number;
  perPage: number;
  page: number
}

(source)

std::github::prReviewList

@always(owner, repo)
effect std::github::prReviewList {
  owner: string;
  repo: string;
  number: number;
  perPage: number;
  page: number
}

(source)

std::github::prReviewCommentList

@always(owner, repo)
effect std::github::prReviewCommentList {
  owner: string;
  repo: string;
  number: number;
  perPage: number;
  page: number
}

(source)

std::github::prChecks

@always(owner, repo)
effect std::github::prChecks {
  owner: string;
  repo: string;
  number: number;
  perPage: number;
  page: number
}

(source)

std::github::issueGet

@always(owner, repo)
effect std::github::issueGet {
  owner: string;
  repo: string;
  number: number
}

(source)

std::github::issueList

@always(owner, repo)
effect std::github::issueList {
  owner: string;
  repo: string;
  state: string;
  labels: string[];
  perPage: number;
  page: number
}

(source)

std::github::issueCommentList

@always(owner, repo)
effect std::github::issueCommentList {
  owner: string;
  repo: string;
  number: number;
  perPage: number;
  page: number
}

(source)

std::github::issueSearch

@always(owner, repo)
effect std::github::issueSearch {
  owner: string;
  repo: string;
  query: string;
  perPage: number;
  page: number
}

(source)

std::github::prReviewComment

@always(owner, repo)
effect std::github::prReviewComment {
  owner: string;
  repo: string;
  number: number;
  path: string;
  line: number;
  body: string
}

(source)

std::github::prReview

@always(owner, repo)
effect std::github::prReview {
  owner: string;
  repo: string;
  number: number;
  event: string;
  body: string;
  comments: ReviewComment[]
}

(source)

std::github::prApprove

@always(owner, repo)
effect std::github::prApprove {
  owner: string;
  repo: string;
  number: number;
  body: string
}

(source)

std::github::issueCreate

@always(owner, repo)
effect std::github::issueCreate {
  owner: string;
  repo: string;
  title: string;
  body: string;
  labels: string[];
  assignees: string[]
}

(source)

std::github::issueComment

@always(owner, repo)
effect std::github::issueComment {
  owner: string;
  repo: string;
  number: number;
  body: string
}

(source)

std::github::issueUpdate

@always(owner, repo)
effect std::github::issueUpdate {
  owner: string;
  repo: string;
  number: number;
  state: string;
  reason: string
}

(source)

std::github::issueLabel

@always(owner, repo)
effect std::github::issueLabel {
  owner: string;
  repo: string;
  number: number;
  labels: string[]
}

(source)

Functions

ghPrGet

ghPrGet(
  number: number,
  owner: string = "",
  repo: string = "",
): PrSummary raises <std::github::prGet>

Read one pull request: title, state, author, branches, and body. @param number - The pull request number. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
owner	string	""
repo	string	""

Returns: PrSummary

Throws: std::github::prGet

(source)

ghPrList

ghPrList(
  state: PrState = "open",
  base: string = "",
  perPage: number = 30,
  page: number = 1,
  owner: string = "",
  repo: string = "",
): PrListItem[] raises <std::github::prList>

List pull requests. Each item has no change counts; ghPrGet returns those. @param state - Filter by state: "open", "closed", or "all". @param base - Only pull requests targeting this base branch ("" for any). @param perPage - Results per page, at most 100. @param page - Page number, starting at 1. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
state	PrState	"open"
base	string	""
perPage	number	30
page	number	1
owner	string	""
repo	string	""

Returns: PrListItem[]

Throws: std::github::prList

(source)

ghPrDiff

ghPrDiff(
  number: number,
  owner: string = "",
  repo: string = "",
): string raises <std::github::prDiff>

Read the full unified diff of a pull request as one string. GitHub refuses this for very large pull requests; use ghPrFiles for those. @param number - The pull request number. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
owner	string	""
repo	string	""

Returns: string

Throws: std::github::prDiff

(source)

ghPrFiles

ghPrFiles(
  number: number,
  perPage: number = 100,
  page: number = 1,
  owner: string = "",
  repo: string = "",
): PrFile[] raises <std::github::prFiles>

List the files a pull request changes, with per-file add/delete counts and patch hunks. @param number - The pull request number. @param perPage - Results per page, at most 100. @param page - Page number, starting at 1. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
perPage	number	100
page	number	1
owner	string	""
repo	string	""

Returns: PrFile[]

Throws: std::github::prFiles

(source)

ghPrReviews

ghPrReviews(
  number: number,
  perPage: number = 30,
  page: number = 1,
  owner: string = "",
  repo: string = "",
): ReviewSummary[] raises <std::github::prReviewList>

List the reviews on a pull request: verdicts, authors, and bodies. @param number - The pull request number. @param perPage - Results per page, at most 100. @param page - Page number, starting at 1. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
perPage	number	30
page	number	1
owner	string	""
repo	string	""

Returns: ReviewSummary[]

Throws: std::github::prReviewList

(source)

ghPrReviewComments

ghPrReviewComments(
  number: number,
  perPage: number = 30,
  page: number = 1,
  owner: string = "",
  repo: string = "",
): ReviewCommentInfo[] raises <std::github::prReviewCommentList>

List the inline review comments on a pull request, with file and line. @param number - The pull request number. @param perPage - Results per page, at most 100. @param page - Page number, starting at 1. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
perPage	number	30
page	number	1
owner	string	""
repo	string	""

Returns: ReviewCommentInfo[]

Throws: std::github::prReviewCommentList

(source)

ghPrChecks

ghPrChecks(
  number: number,
  perPage: number = 30,
  page: number = 1,
  owner: string = "",
  repo: string = "",
): CheckRun[] raises <std::github::prChecks>

List the CI check runs on the head commit of a pull request. @param number - The pull request number. @param perPage - Results per page, at most 100. @param page - Page number, starting at 1. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
perPage	number	30
page	number	1
owner	string	""
repo	string	""

Returns: CheckRun[]

Throws: std::github::prChecks

(source)

ghIssueGet

ghIssueGet(
  number: number,
  owner: string = "",
  repo: string = "",
): IssueSummary raises <std::github::issueGet>

Read one issue: title, state, author, labels, and body. Fails if the number belongs to a pull request; use ghPrGet for those. @param number - The issue number. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
owner	string	""
repo	string	""

Returns: IssueSummary

Throws: std::github::issueGet

(source)

ghIssueList

ghIssueList(
  state: IssueState = "open",
  labels: string[] = [],
  perPage: number = 30,
  page: number = 1,
  owner: string = "",
  repo: string = "",
): IssueSummary[] raises <std::github::issueList>

List issues, optionally filtered by labels. GitHub counts pull requests toward each page and this tool drops them, so a page can come back short or empty while later pages still hold issues. To page through every issue exactly, use ghIssueSearch with "is:issue". @param state - Filter by state: "open", "closed", or "all". @param labels - Only issues carrying all of these labels ([] for any). @param perPage - Results per page, at most 100. @param page - Page number, starting at 1. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
state	IssueState	"open"
labels	string[]	[]
perPage	number	30
page	number	1
owner	string	""
repo	string	""

Returns: IssueSummary[]

Throws: std::github::issueList

(source)

ghIssueComments

ghIssueComments(
  number: number,
  perPage: number = 30,
  page: number = 1,
  owner: string = "",
  repo: string = "",
): CommentInfo[] raises <std::github::issueCommentList>

List the comments on an issue. @param number - The issue number. @param perPage - Results per page, at most 100. @param page - Page number, starting at 1. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
perPage	number	30
page	number	1
owner	string	""
repo	string	""

Returns: CommentInfo[]

Throws: std::github::issueCommentList

(source)

ghIssueSearch

ghIssueSearch(
  query: string,
  perPage: number = 30,
  page: number = 1,
  owner: string = "",
  repo: string = "",
): IssueSummary[] raises <std::github::issueSearch>

Search issues and pull requests in one repository. The query must not contain a repo:, org:, or user: qualifier. @param query - GitHub search syntax, e.g. "crash in:title label:bug". @param perPage - Results per page, at most 100. @param page - Page number, starting at 1. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
query	string
perPage	number	30
page	number	1
owner	string	""
repo	string	""

Returns: IssueSummary[]

Throws: std::github::issueSearch

(source)

ghPrReviewComment

ghPrReviewComment(
  number: number,
  path: string,
  line: number,
  body: string,
  side: DiffSide = "RIGHT",
  commitSha: string = "",
  owner: string = "",
  repo: string = "",
): ReviewCommentInfo raises <std::github::prReviewComment>

Post one inline review comment on a line of a pull request. For several comments at once, use ghPrReview: one call, one approval. @param number - The pull request number. @param path - The file the comment attaches to. @param line - The line number in the diff. @param body - The comment text (markdown). @param side - Which side of the diff: "RIGHT" (new code) or "LEFT" (old). @param commitSha - The commit to anchor to. Empty means the PR head commit. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
path	string
line	number
body	string
side	DiffSide	"RIGHT"
commitSha	string	""
owner	string	""
repo	string	""

Returns: ReviewCommentInfo

Throws: std::github::prReviewComment

(source)

ghPrReview

ghPrReview(
  number: number,
  event: ReviewEvent = "COMMENT",
  body: string = "",
  comments: ReviewComment[] = [],
  owner: string = "",
  repo: string = "",
): ReviewSummary raises <std::github::prReview>

Submit a review on a pull request: a verdict, an overall body, and any number of inline comments, in one call. To approve a pull request, use ghPrApprove; approving is its own permission. @param number - The pull request number. @param event - "COMMENT" or "REQUEST_CHANGES". @param body - The overall review text (markdown). @param comments - Inline comments, each with path, line, body, and an optional side. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
event	ReviewEvent	"COMMENT"
body	string	""
comments	ReviewComment[]	[]
owner	string	""
repo	string	""

Returns: ReviewSummary

Throws: std::github::prReview

(source)

ghPrApprove

ghPrApprove(
  number: number,
  body: string = "",
  owner: string = "",
  repo: string = "",
): ReviewSummary raises <std::github::prApprove>

Approve a pull request. This is a formal review approval that can satisfy branch protection and unblock a merge. @param number - The pull request number. @param body - Optional approval text (markdown). @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
body	string	""
owner	string	""
repo	string	""

Returns: ReviewSummary

Throws: std::github::prApprove

(source)

ghIssueCreate

ghIssueCreate(
  title: string,
  body: string,
  labels: string[] = [],
  assignees: string[] = [],
  owner: string = "",
  repo: string = "",
): IssueSummary raises <std::github::issueCreate>

Create an issue. @param title - The issue title. @param body - The issue body (markdown). @param labels - Labels to apply on creation. @param assignees - Usernames to assign on creation. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
title	string
body	string
labels	string[]	[]
assignees	string[]	[]
owner	string	""
repo	string	""

Returns: IssueSummary

Throws: std::github::issueCreate

(source)

ghIssueComment

ghIssueComment(
  number: number,
  body: string,
  owner: string = "",
  repo: string = "",
): CommentInfo raises <std::github::issueComment>

Post a comment on an issue or pull request. @param number - The issue or pull request number. @param body - The comment text (markdown). @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
body	string
owner	string	""
repo	string	""

Returns: CommentInfo

Throws: std::github::issueComment

(source)

ghIssueClose

ghIssueClose(
  number: number,
  reason: CloseReason = "completed",
  owner: string = "",
  repo: string = "",
): IssueSummary raises <std::github::issueUpdate>

Close an issue or pull request. @param number - The issue or pull request number. @param reason - Why it is closing: "completed" or "not_planned". @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
reason	CloseReason	"completed"
owner	string	""
repo	string	""

Returns: IssueSummary

Throws: std::github::issueUpdate

(source)

ghIssueLabel

ghIssueLabel(
  number: number,
  labels: string[],
  owner: string = "",
  repo: string = "",
): string[] raises <std::github::issueLabel>

Add labels to an issue or pull request. Returns the full label list after the change. @param number - The issue or pull request number. @param labels - The labels to add. @param owner - Repository owner. Defaults to the origin remote of the agent working directory. @param repo - Repository name. Defaults to the origin remote of the agent working directory.

Parameters:

Name	Type	Default
number	number
labels	string[]
owner	string	""
repo	string	""

Returns: string[]

Throws: std::github::issueLabel

(source)