apps/api/src/tools.rs · flagon-io/g1t

description: "Find things. `code` (the default) searches all of g1t you can see: repositories, code, issues, pull requests and people, with qualifiers like repo:owner/name, language:rust, is:issue. `ticket` reads a Jira, Linear or Sentry item the work refers to.",

63

default_action: Some("code"),

64

actions: &[

65

a("code", Op::Search, "Search all of g1t: repositories, code, issues, pull requests, people"),

66

a("ticket", Op::GetContext, "A Jira, Linear or Sentry item the work refers to, as it is now"),

],

},

Tool {

title: "Repositories",

72

description: "Repositories: find, read and create them, change their settings and rulesets (what may happen to branches and tags, and what a pull request needs to merge), check their CODEOWNERS file, manage their labels and milestones, see and dismiss their security alerts (secrets and vulnerable dependencies), read what their default branch says (languages, contributors, license), star them, publish releases, and look after their mirroring (take a mirror over, hand it back, or move it to g1t for good). Name one as \"owner/name\". Deleting, transferring and changing visibility need `confirm`.",

73

default_action: None,

74

actions: &[

75

a("list", Op::ListRepos, "Repositories you can see"),

76

a("get", Op::GetRepo, "One repository"),

77

a("tarball", Op::Archives(ArchiveOp::DownloadTarball), "A 10-minute link to a branch, tag or commit as a .tar.gz"),

78

a("zipball", Op::Archives(ArchiveOp::DownloadZipball), "A 10-minute link to a branch, tag or commit as a .zip"),

79

a("create", Op::CreateRepo, "Create one, empty or copied from a public git URL"),

80

a("update", Op::UpdateRepo, "Change description, website, topics, default branch, protection"),

81

a("get_settings", Op::GetRepoSettings, "How pull requests merge, and the default branch's protection as its rules stack"),

82

a("update_settings", Op::UpdateRepoSettings, "Change how pull requests merge and the default branch protection ruleset"),

83

a("check_names", Op::ListCheckNames, "Check names reported lately, to require in a ruleset"),

84

a("list_rulesets", Op::Rules(RulesOp::ListRepoRulesets), "Its rulesets, and its workspace's that hold in it"),

85

a("get_ruleset", Op::Rules(RulesOp::GetRepoRuleset), "One ruleset"),

86

a("create_ruleset", Op::Rules(RulesOp::CreateRepoRuleset), "Create a ruleset for its branches or tags"),

87

a("update_ruleset", Op::Rules(RulesOp::UpdateRepoRuleset), "Change a ruleset"),

88

a("delete_ruleset", Op::Rules(RulesOp::DeleteRepoRuleset), "Delete a ruleset"),

89

a("branch_rules", Op::Rules(RulesOp::GetBranchRules), "Every rule that holds for a branch or tag, and where it comes from"),

90

a("rule_evaluations", Op::Rules(RulesOp::ListRuleEvaluations), "How its rules judged pushes and merges, with insights"),

91

a("codeowners", Op::GetCodeownersErrors, "Problems in its CODEOWNERS file, by line"),

92

a("list_labels", Op::ListLabels, "Labels, with colors and how many issues and pull requests carry each"),

93

a("create_label", Op::CreateLabel, "Create a label"),

94

a("update_label", Op::UpdateLabel, "Rename a label or change its color or description"),

95

a("delete_label", Op::DeleteLabel, "Delete a label, from everything that carries it"),

96

a("add_default_labels", Op::AddDefaultLabels, "Add the default labels it is missing"),

97

a("list_milestones", Op::ListMilestones, "Milestones, with progress and due dates"),

98

a("get_milestone", Op::GetMilestone, "One milestone with its issues and pull requests"),

99

a("create_milestone", Op::CreateMilestone, "Create a milestone"),

100

a("update_milestone", Op::UpdateMilestone, "Change a milestone's title, description, due date or state"),

101

a("delete_milestone", Op::DeleteMilestone, "Delete a milestone"),

102

a("list_events", Op::ListEvents, "Timeline: pushes, issues, pull requests, comments"),

103

a("languages", Op::About(AboutOp::GetLanguages), "Its languages by bytes, with colors and percentages"),

104

a("contributors", Op::About(AboutOp::ListContributors), "Who made it: commits per person, agent and author, by week"),

105

a("license", Op::About(AboutOp::GetLicense), "The license its LICENSE file holds"),

106

a("stargazers", Op::About(AboutOp::ListStargazers), "Who starred it"),

107

a("starred", Op::About(AboutOp::CheckStarred), "Whether you starred it, and how many have"),

108

a("star", Op::About(AboutOp::Star), "Star it"),

109

a("unstar", Op::About(AboutOp::Unstar), "Take your star back"),

110

a("list_starred", Op::About(AboutOp::ListStarred), "Repositories you starred"),

111

a("list_releases", Op::About(AboutOp::ListReleases), "Releases, newest first"),

112

a("latest_release", Op::About(AboutOp::GetLatestRelease), "The latest release"),

113

a("get_release", Op::About(AboutOp::GetRelease), "One release by id"),

114

a("get_release_by_tag", Op::About(AboutOp::GetReleaseByTag), "The release of a tag"),

115

a("create_release", Op::About(AboutOp::CreateRelease), "Publish a release of a tag, making the tag if needed"),

116

a("update_release", Op::About(AboutOp::UpdateRelease), "Change a release's title, notes, draft or prerelease"),

117

a("delete_release", Op::About(AboutOp::DeleteRelease), "Delete a release; its tag stays"),

118

a("rename_branch", Op::RenameBranch, "Rename a branch"),

119

a("create_branch", Op::CreateBranch, "Make a branch at a branch, tag or commit"),

120

a("delete_branch", Op::DeleteBranch, "Delete a branch; make it again at its commit to restore it"),

121

a("rename", Op::RenameRepo, "Rename it; old addresses redirect"),

122

a("transfer", Op::TransferRepo, "Move it to another workspace you own"),

123

a("mirror", Op::Mirrors(MirrorsOp::GetMirror), "Its remotes: what it mirrors or is mirrored to"),

124

a("mirror_hand_back_plan", Op::Mirrors(MirrorsOp::GetHandBackPlan), "What handing a takeover back would do, ref by ref"),

125

a("mirror_take_over", Op::Mirrors(MirrorsOp::TakeOver), "Make g1t lead a mirror for now"),

126

a("mirror_ci", Op::Mirrors(MirrorsOp::SetCiFailover), "Run a mirror's workflows on g1t (on), or stop (off)"),

127

a("mirror_hand_back", Op::Mirrors(MirrorsOp::HandBack), "Send a takeover back, deciding diverged refs"),

128

a("mirror_move_to_g1t", Op::Mirrors(MirrorsOp::MoveToG1t), "Stop tracking the remote; g1t leads for good"),

129

a("mirror_sync", Op::Mirrors(MirrorsOp::SyncMirror), "Bring its remotes in step now"),

130

a("mirror_add_remote", Op::Mirrors(MirrorsOp::AddRemote), "Link another g1t or git host"),

131

a("mirror_update_remote", Op::Mirrors(MirrorsOp::UpdateRemote), "Change a remote's settings"),

132

a("mirror_remove_remote", Op::Mirrors(MirrorsOp::RemoveRemote), "Unlink a remote"),

133

a("archive", Op::ArchiveRepo, "Make it read-only"),

134

a("unarchive", Op::UnarchiveRepo, "Make it writable again"),

135

a("set_visibility", Op::SetRepoVisibility, "Make it public or private"),

136

a("delete", Op::DeleteRepo, "Delete it; restorable for 30 days"),

137

a("list_deleted", Op::ListDeletedRepos, "A workspace's deleted repositories"),

138

a("restore", Op::RestoreRepo, "Restore a deleted one"),

139

a("purge", Op::PurgeRepo, "Remove a deleted one for good"),

140

a("security_alerts", Op::ListSecurityAlerts, "Secret and dependency alerts, filtered by state"),

141

a("dismiss_alert", Op::DismissSecurityAlert, "Dismiss an alert with a reason"),

142

a("reopen_alert", Op::ReopenSecurityAlert, "Reopen a dismissed alert"),

],

},

Tool {

title: "Issues",

description: "Issues: what should change. Read one before working on it to see the pull requests already made for it. Issues and pull requests share numbers; `comment` works on either.",

149

default_action: None,

150

actions: &[

151

a("list", Op::ListIssues, "Issues on a repository, newest first"),

152

a("get", Op::GetIssue, "One issue with comments and its pull requests"),

153

a("create", Op::CreateIssue, "Open an issue"),

154

a("update", Op::UpdateIssue, "Change title, body, labels, milestone or assignees"),

155

a("labels", Op::ListIssueLabels, "The labels an issue or pull request carries"),

156

a("add_labels", Op::AddIssueLabels, "Add labels to an issue or pull request"),

157

a("set_labels", Op::SetIssueLabels, "Replace the labels of an issue or pull request"),

158

a("remove_labels", Op::RemoveIssueLabels, "Take labels off an issue or pull request"),

159

a("close", Op::CloseIssue, "Close it without a pull request"),

160

a("reopen", Op::ReopenIssue, "Reopen it"),

161

a("comment", Op::AddComment, "Comment on an issue or pull request; path and line for one line of a change"),

162

a("edit_comment", Op::EditComment, "Change a comment's text: your own, or any with the Maintain role"),

163

a("delete_comment", Op::DeleteComment, "Delete a comment: your own, or any with the Maintain role"),

164

a("import", Op::ImportIssue, "Open an issue from a Jira, Linear or Sentry item"),

],

},

Tool {

title: "Pull requests",

170

description: "Pull requests: start a change for an issue, record your session, mark it ready, ask people and teams to review, review and merge. Read `overlaps` and `behind` on `get` before going far, and `code_owners` for whose approval it needs.",

171

default_action: None,

172

actions: &[

173

a("list", Op::ListPullRequests, "Pull requests on a repository, newest first"),

174

a("get", Op::GetPullRequest, "Status, checks and required checks, reviews, overlaps, whether it is behind"),

175

a("changes", Op::GetPullRequestChanges, "Files and line-by-line diff"),

176

a("create", Op::CreatePullRequest, "Start a draft with its own fork to push to, or open one from a pushed branch"),

177

a("update", Op::UpdatePullRequest, "Change its base branch, labels, milestone, assignees or reviewers"),

178

a("record_session", Op::RecordSession, "Append prompt, reasoning and tool entries to its session"),

179

a("read_session", Op::ReadSession, "Its recorded session"),

180

a("ready", Op::MarkPullRequestReady, "Mark a draft ready, with a summary"),

181

a("draft", Op::ConvertPullRequestToDraft, "Turn it back into a draft"),

182

a("request_reviewers", Op::RequestReviewers, "Ask people or teams to review it"),

183

a("remove_requested_reviewers", Op::RemoveRequestedReviewers, "Stop asking people or teams to review it"),

184

a("review", Op::ReviewPullRequest, "Approve or request changes"),

185

a("close", Op::ClosePullRequest, "Close without merging"),

186

a("reopen", Op::ReopenPullRequest, "Reopen a closed one"),

187

a("merge", Op::MergePullRequest, "Land it, or join the merge queue"),

188

a("merge_queue", Op::GetMergeQueue, "The repository's merge queue"),

],

},

Tool {

title: "Memory",

description: "What the project and its workspace remember for the next agent: how to build, conventions, decisions, traps. Recall before you start; remember one short fact at a time, never a secret.",

195

default_action: None,

196

actions: &[

197

a("recall", Op::Recall, "Search memory, or list it all"),

198

a("remember", Op::Remember, "Save one fact"),

],

},

Tool {

title: "Workflows",

description: "GitHub Actions workflows from .g1t/workflows: their runs, jobs and logs, and running, cancelling or rerunning them. Runs' artifacts: listing, a download link, deleting, and how long they are kept. Deployments wherever they run (reported from any CI, made by jobs with an `environment:`, or built on g1t.page), their statuses and environments, and reporting your own; environments' protection rules, approving or rejecting the jobs they hold, approving a pull request's run from outside, the token's default permissions, repository dispatch, and the workflows a workspace runs in its repositories without a file in them. Checks on commits: statuses, check runs (a g1t Actions job is one) and check suites, to read where a commit stands or report on it from CI or an integration. Also the self-hosted runners they run on: a workspace's (`workspace`) or a repository's own (`repo`), and their groups.",

205

default_action: None,

206

actions: &[

207

a("list", Op::ListWorkflows, "Workflows on the default branch"),

208

a("list_runs", Op::ListWorkflowRuns, "Runs, newest first"),

209

a("get_run", Op::GetWorkflowRun, "One run with its jobs and steps; an earlier attempt with attempt"),

210

a("job_logs", Op::GetJobLogs, "A job's log after a sequence number"),

211

a("dispatch", Op::DispatchWorkflow, "Run a workflow_dispatch workflow"),

212

a("cancel", Op::CancelWorkflowRun, "Cancel a run, letting its jobs clean up; force stops them outright"),

213

a("rerun", Op::RerunWorkflowRun, "Run a finished run again: all, failed_only, or one job; debug for debug logging"),

214

a("update", Op::UpdateWorkflow, "Turn a workflow on or off"),

215

a("list_artifacts", Op::Artifacts(ArtifactsOp::ListArtifacts), "A repository's artifacts, newest first; or a run's with run_artifacts"),

216

a("run_artifacts", Op::Artifacts(ArtifactsOp::ListRunArtifacts), "One run's artifacts"),

217

a("get_artifact", Op::Artifacts(ArtifactsOp::GetArtifact), "One artifact: size, digest, expiry, run"),

218

a("download_artifact", Op::Artifacts(ArtifactsOp::DownloadArtifact), "A 10-minute link to an artifact's zip"),

219

a("delete_artifact", Op::Artifacts(ArtifactsOp::DeleteArtifact), "Delete an artifact before it expires"),

220

a("artifact_retention", Op::Artifacts(ArtifactsOp::GetArtifactRetention), "Days the repository keeps artifacts"),

221

a("set_artifact_retention", Op::Artifacts(ArtifactsOp::SetArtifactRetention), "Change the days the repository keeps artifacts"),

222

a("combined_status", Op::Checks(ChecksOp::GetCombinedStatus), "A commit's statuses and the state they add up to"),

223

a("list_statuses", Op::Checks(ChecksOp::ListCommitStatuses), "A commit's statuses, newest first"),

224

a("set_status", Op::Checks(ChecksOp::CreateCommitStatus), "Set a status on a commit"),

225

a("list_check_runs", Op::Checks(ChecksOp::ListCheckRunsForRef), "A commit's check runs, g1t Actions jobs included"),

226

a("get_check_run", Op::Checks(ChecksOp::GetCheckRun), "One check run with its report"),

227

a("check_run_annotations", Op::Checks(ChecksOp::ListCheckRunAnnotations), "What a check run says about lines of files"),

228

a("create_check_run", Op::Checks(ChecksOp::CreateCheckRun), "Report a check run on a commit"),

229

a("update_check_run", Op::Checks(ChecksOp::UpdateCheckRun), "Move a check run on, complete it, add annotations"),

230

a("rerequest_check_run", Op::Checks(ChecksOp::RerequestCheckRun), "Ask for a check run to run again"),

231

a("list_check_suites", Op::Checks(ChecksOp::ListCheckSuitesForRef), "A commit's check suites, one per reporter or workflow run"),

232

a("get_check_suite", Op::Checks(ChecksOp::GetCheckSuite), "One check suite"),

233

a("rerequest_check_suite", Op::Checks(ChecksOp::RerequestCheckSuite), "Ask for a check suite to run again"),

234

a("list_deployments", Op::Deployments(DeploymentsOp::ListDeployments), "Deployments wherever they run, newest first, filtered"),

235

a("get_deployment", Op::Deployments(DeploymentsOp::GetDeployment), "One deployment with every status it has had"),

236

a("create_deployment", Op::Deployments(DeploymentsOp::CreateDeployment), "Report a deployment of a ref to an environment"),

237

a("deployment_statuses", Op::Deployments(DeploymentsOp::ListDeploymentStatuses), "A deployment's statuses, newest first"),

238

a("create_deployment_status", Op::Deployments(DeploymentsOp::CreateDeploymentStatus), "Report where a deployment is: in_progress, success, failure"),

239

a("list_environments", Op::Deployments(DeploymentsOp::ListEnvironments), "Environments with their current and latest deployments"),

240

a("get_environment", Op::Deployments(DeploymentsOp::GetEnvironment), "One environment by name, with its protection rules"),

241

a("start_deployment_build", Op::Deployments(DeploymentsOp::StartDeploymentBuild), "From a workflow job: open a g1t.page build it runs itself"),

242

a("update_environment", Op::Protection(ProtectionOp::UpdateEnvironment), "Set an environment's reviewers, wait timer and branches"),

243

a("delete_environment", Op::Protection(ProtectionOp::DeleteEnvironment), "Remove an environment's protection rules"),

244

a("pending_deployments", Op::Protection(ProtectionOp::GetPendingDeployments), "The environments holding a run's jobs"),

245

a("review_deployments", Op::Protection(ProtectionOp::ReviewPendingDeployments), "Approve or reject a run's jobs for its environments"),

246

a("approve_run", Op::Protection(ProtectionOp::ApproveWorkflowRun), "Let a run of a pull request from outside start"),

247

a("get_permissions", Op::Protection(ProtectionOp::GetWorkflowPermissions), "What a job's token gets without `permissions:`"),

248

a("set_permissions", Op::Protection(ProtectionOp::SetWorkflowPermissions), "Set it: read or write"),

249

a("get_approval_policy", Op::Protection(ProtectionOp::GetForkPrApproval), "Which pull requests' runs wait for approval"),

250

a("set_approval_policy", Op::Protection(ProtectionOp::SetForkPrApproval), "Set which pull requests' runs wait for approval"),

251

a("get_access", Op::Protection(ProtectionOp::GetActionsAccess), "Which repositories may use this one's actions and workflows"),

252

a("set_access", Op::Protection(ProtectionOp::SetActionsAccess), "Let the workspace's private repositories use them, or not"),

253

a("repository_dispatch", Op::Protection(ProtectionOp::CreateRepositoryDispatch), "Start repository_dispatch workflows with an event"),

254

a("get_workspace_permissions", Op::Protection(ProtectionOp::GetWorkspaceWorkflowPermissions), "A workspace's default and maximum token permissions"),

255

a("set_workspace_permissions", Op::Protection(ProtectionOp::SetWorkspaceWorkflowPermissions), "Set them, and whether jobs may open pull requests"),

256

a("list_managed_workflows", Op::Protection(ProtectionOp::ListWorkspaceManagedWorkflows), "The workflows a workspace runs in its repositories"),

257

a("add_managed_workflow", Op::Protection(ProtectionOp::CreateWorkspaceManagedWorkflow), "Run a workflow in the workspace's repositories, required or default"),

258

a("update_managed_workflow", Op::Protection(ProtectionOp::UpdateWorkspaceManagedWorkflow), "Change one's repositories or mode, or copy its source again"),

259

a("remove_managed_workflow", Op::Protection(ProtectionOp::DeleteWorkspaceManagedWorkflow), "Take one out of the workspace's repositories"),

260

a("list_runners", Op::ListRunners, "Self-hosted runners, with status, labels and what each is doing"),

261

a("create_runner_token", Op::CreateRunnerRegistrationToken, "A one-hour token for g1t-runner register"),

262

a("remove_runner", Op::RemoveRunner, "Remove a self-hosted runner"),

263

a("list_runner_groups", Op::ListRunnerGroups, "A workspace's runner groups"),

264

a("create_runner_group", Op::CreateRunnerGroup, "Make a group, for some repositories"),

265

a("update_runner_group", Op::UpdateRunnerGroup, "Rename a group or change its repositories"),

266

a("delete_runner_group", Op::DeleteRunnerGroup, "Delete a group; its runners join the default"),

267

a("get_runner_settings", Op::GetRunnerSettings, "Where checks and the merge queue run; whether forks may use runners"),

268

a("update_runner_settings", Op::UpdateRunnerSettings, "Change them"),

],

},

Tool {

title: "Observability",

274

description: "What a project's running software did in production, to debug it: its requests, logs, traces, grouped errors and metrics, from its apps on g1t.page and from OpenTelemetry sent from anywhere. Name the project by workspace and project slug. Start with overview (error rate, latency, the routes and the deployment a regression began with) or errors, then follow a request or trace_id to its logs and spans. Times are RFC 3339 or Unix milliseconds; the last 24 hours unless you say. Needs a role of your own on the project's repository; resolving errors, Triage.",

275

default_action: None,

276

actions: &[

277

a("overview", Op::Telemetry(TelemetryOp::GetOverview), "Requests, errors, latency and CPU over a period, by route, deployment, service and region, against the period before"),

278

a("requests", Op::Telemetry(TelemetryOp::ListRequests), "Requests answered, newest first: q, status (5xx, 404), errors_only, route, min_duration_ms"),

279

a("request", Op::Telemetry(TelemetryOp::GetRequest), "One request with every log line it wrote"),

280

a("logs", Op::Telemetry(TelemetryOp::ListLogs), "Search a project's logs: words or a phrase in q, level (error,warn), trace_id, request_id"),

281

a("traces", Op::Telemetry(TelemetryOp::ListTraces), "Traces, newest first: q, errors_only, min_duration_ms"),

282

a("trace", Op::Telemetry(TelemetryOp::GetTrace), "One trace: every span, with its timing, status and attributes, and its logs"),

283

a("errors", Op::Telemetry(TelemetryOp::ListErrors), "Errors grouped by exception, most recent first, with the deployment that brought each in"),

284

a("update_error", Op::Telemetry(TelemetryOp::UpdateError), "Resolve, ignore or reopen an error group, or link the issue made for it"),

285

a("metrics", Op::Telemetry(TelemetryOp::ListMetrics), "The metrics the project's software sends"),

286

a("metric", Op::Telemetry(TelemetryOp::GetMetric), "One metric over time: aggregate (avg, sum, p95), group_by an attribute"),

],

},

Tool {

title: "Packages",

description: "A workspace's packages in every registry (container images, npm, Cargo, Maven, NuGet, RubyGems, Composer): their versions and downloads, deleting and restoring them within 30 days, their visibility and repository, who has a role on them, and which repositories' workflows may use them (Manage Actions access). Name one by workspace, package_type and package_name.",

293

default_action: None,

294

actions: &[

295

a("list", Op::Packages(PackagesOp::ListPackages), "A workspace's packages; state deleted for restorable ones"),

296

a("get", Op::Packages(PackagesOp::GetPackage), "One package: address, visibility, repository, downloads"),

297

a("versions", Op::Packages(PackagesOp::ListVersions), "Its versions with tags and downloads; state deleted too"),

298

a("get_version", Op::Packages(PackagesOp::GetVersion), "One version by id, version, digest or tag"),

299

a("update", Op::Packages(PackagesOp::UpdatePackage), "Set visibility, or inherit_access for a linked one"),

300

a("link", Op::Packages(PackagesOp::LinkPackage), "Link it to a repository of its workspace"),

301

a("unlink", Op::Packages(PackagesOp::UnlinkPackage), "Unlink it: the workspace's, private"),

302

a("access", Op::Packages(PackagesOp::ListAccess), "People and teams with a role on it"),

303

a("set_access", Op::Packages(PackagesOp::SetAccess), "Give a person or team read, write or admin"),

304

a("remove_access", Op::Packages(PackagesOp::RemoveAccess), "Take a person's or team's role away"),

305

a("actions_access", Op::Packages(PackagesOp::ListActionsAccess), "Repositories whose workflows may use it"),

306

a("set_actions_access", Op::Packages(PackagesOp::SetActionsAccess), "Let a repository's workflows read or write it"),

307

a("remove_actions_access", Op::Packages(PackagesOp::RemoveActionsAccess), "Stop a repository's workflows using it"),

308

a("delete", Op::Packages(PackagesOp::DeletePackage), "Delete it; restorable for 30 days"),

309

a("restore", Op::Packages(PackagesOp::RestorePackage), "Restore a deleted package"),

310

a("delete_version", Op::Packages(PackagesOp::DeleteVersion), "Delete a version; restorable for 30 days"),

311

a("restore_version", Op::Packages(PackagesOp::RestoreVersion), "Restore a deleted version"),

],

},

Tool {

title: "Secrets and variables",

317

description: "A repository's or workspace's secrets and variables, read by workflows and deployments. Secret values are never returned.",

318

default_action: None,

319

actions: &[

320

a("list_secrets", Op::ListActionsSecrets, "Secrets, without values"),

321

a("set_secret", Op::SetActionsSecret, "Add or change a secret"),

322

a("delete_secret", Op::DeleteActionsSecret, "Remove a secret"),

323

a("list_variables", Op::ListActionsVariables, "Variables, with values"),

324

a("set_variable", Op::SetActionsVariable, "Add or change a variable"),

325

a("delete_variable", Op::DeleteActionsVariable, "Remove a variable"),

],

},

Tool {

title: "Webhooks",

description: "HTTPS addresses sent signed events as they happen, for a repository or a whole workspace.",

332

default_action: None,

333

actions: &[

334

a("list", Op::ListWebhooks, "Webhooks, without secrets"),

335

a("create", Op::CreateWebhook, "Register one; a ping is sent"),

336

a("update", Op::UpdateWebhook, "Change address, events or active"),

337

a("delete", Op::DeleteWebhook, "Remove one"),

338

a("ping", Op::PingWebhook, "Send a ping"),

339

a("list_deliveries", Op::ListWebhookDeliveries, "Latest deliveries"),

340

a("redeliver", Op::RedeliverWebhook, "Send a delivery again"),

],

},

Tool {

title: "Who has access",

346

description: "Who has access to a repository and with which role (read, triage, write, maintain, admin), outside collaborators, a workspace's base permission, and a repository's deploy keys.",

347

default_action: None,

348

actions: &[

349

a("list_collaborators", Op::ListCollaborators, "Everyone with a role, and pending invitations"),

350

a("get_permission", Op::GetCollaboratorPermission, "One person's role and capabilities"),

351

a("add_collaborator", Op::AddCollaborator, "Give someone a role, by username or email"),

352

a("update_collaborator", Op::UpdateCollaborator, "Change a direct role"),

353

a("remove_collaborator", Op::RemoveCollaborator, "Take away a direct role"),

354

a("list_invitations", Op::ListRepoInvitations, "Pending invitations to a repository"),

355

a("revoke_invitation", Op::RevokeRepoInvitation, "Withdraw one"),

356

a("set_base_permission", Op::SetBasePermission, "What every member gets on each repository"),

357

a("list_outside_collaborators", Op::ListOutsideCollaborators, "People with roles who are not members"),

358

a("list_deploy_keys", Op::DeployKeys(DeployKeysOp::ListDeployKeys), "SSH keys that reach this one repository"),

359

a("get_deploy_key", Op::DeployKeys(DeployKeysOp::GetDeployKey), "One deploy key, by id"),

360

a("add_deploy_key", Op::DeployKeys(DeployKeysOp::CreateDeployKey), "Add one; read-only unless read_only is false"),

361

a("remove_deploy_key", Op::DeployKeys(DeployKeysOp::DeleteDeployKey), "Delete one"),

],

},

Tool {

title: "Teams",

description: "Teams: groups of a workspace's members, given roles on repositories together, mentioned as @workspace/team and asked to review together. Name one by `workspace` and its slug (`team`). Any member may create a team; the workspace's owners and the team's maintainers manage it. A secret team is seen only by its people and the owners.",

368

default_action: None,

369

actions: &[

370

a("list", Op::ListTeams, "A workspace's teams you can see"),

371

a("get", Op::GetTeam, "One team"),

372

a("create", Op::CreateTeam, "Create a team; you become its maintainer"),

373

a("update", Op::UpdateTeam, "Change its name, slug, description, visibility, parent or notifications"),

374

a("delete", Op::DeleteTeam, "Delete it; its child teams move up"),

375

a("list_members", Op::ListTeamMembers, "Its people and their roles, child teams' with include_child_teams"),

376

a("set_member", Op::SetTeamMember, "Add a member of the workspace, or change their role"),

377

a("remove_member", Op::RemoveTeamMember, "Take someone out of it"),

378

a("list_child_teams", Op::ListChildTeams, "The teams nested under it"),

379

a("list_repos", Op::ListTeamRepos, "The repositories it has a role on"),

380

a("set_repo", Op::SetTeamRepo, "Give it a role on a repository"),

381

a("remove_repo", Op::RemoveTeamRepo, "Take its role on a repository away"),

382

a("set_review_assignment", Op::SetTeamReviewAssignment, "Whom it picks when asked to review"),

383

a("list_user_teams", Op::ListUserTeams, "The teams someone is in"),

],

},

Tool {

title: "Workspaces",

description: "Workspaces own repositories (g1t.sh/{workspace}/{repo}): create, update or delete one, invite members, connect integrations, set rulesets that hold across its repositories, read and change its projects (what each is, where it runs, its links), and keep your own pinned projects at the top of its sidebar.",

390

default_action: None,

391

actions: &[

392

a("get", Op::GetWorkspace, "A workspace's details and settings"),

393

a("create", Op::CreateWorkspace, "Create a workspace"),

394

a("delete", Op::DeleteWorkspace, "Delete a workspace and everything in it (support can restore it for 30 days)"),

395

a("update", Op::UpdateWorkspace, "Change its name, description, base permission, who may create teams, member privileges or the two-factor requirement"),

396

a("list_members", Op::ListMembers, "Its members, owners first, with their roles"),

397

a("update_member", Op::UpdateMember, "Make someone an owner or a member, billing manager or security manager"),

398

a("remove_member", Op::RemoveMember, "Remove someone from it"),

399

a("transfer_ownership", Op::TransferOwnership, "Hand it to another member: they become an owner, you a member"),

400

a("leave", Op::LeaveWorkspace, "Leave it yourself"),

401

a("list_invites", Op::ListWorkspaceInvites, "Its invites"),

402

a("invite_member", Op::InviteMember, "Invite someone by username or email address"),

403

a("revoke_invite", Op::RevokeWorkspaceInvite, "Revoke a pending invite"),

404

a("list_integrations", Op::ListIntegrations, "Alert sources and issue trackers"),

405

a("connect_integration", Op::ConnectIntegration, "Connect one"),

406

a("update_integration", Op::UpdateIntegration, "Change one: rotate its key or its settings"),

407

a("disconnect_integration", Op::DisconnectIntegration, "Remove one"),

408

a("test_integration", Op::TestIntegration, "Check its credentials"),

409

a("list_projects", Op::ListProjects, "Its projects you can see: what each is, where it runs, its links"),

410

a("get_project", Op::GetProject, "One project"),

411

a("update_project", Op::UpdateProject, "Change a project's name, description, kind, where it runs or its links"),

412

a("list_pinned_projects", Op::ListPinnedProjects, "Your pinned projects in it, in your order"),

413

a("pin_project", Op::PinProject, "Pin a project, at a position or the end"),

414

a("unpin_project", Op::UnpinProject, "Unpin a project"),

415

a("reorder_pinned_projects", Op::ReorderPinnedProjects, "Put your pins in a new order"),

416

a("list_rulesets", Op::Rules(RulesOp::ListWorkspaceRulesets), "Its rulesets, which hold across its repositories"),

417

a("get_ruleset", Op::Rules(RulesOp::GetWorkspaceRuleset), "One of its rulesets"),

418

a("create_ruleset", Op::Rules(RulesOp::CreateWorkspaceRuleset), "Create a ruleset for some or all of its repositories"),

419

a("update_ruleset", Op::Rules(RulesOp::UpdateWorkspaceRuleset), "Change one of its rulesets"),

420

a("delete_ruleset", Op::Rules(RulesOp::DeleteWorkspaceRuleset), "Delete one of its rulesets"),

421

a("rule_evaluations", Op::Rules(RulesOp::ListWorkspaceRuleEvaluations), "How rules judged changes across its repositories"),

422

a("get_token_policy", Op::Tokens(TokenOp::GetTokenPolicy), "Its rules for personal access tokens"),

423

a("set_token_policy", Op::Tokens(TokenOp::SetTokenPolicy), "Change them: which tokens reach it, approval, lifetime"),

424

a("list_member_tokens", Op::Tokens(TokenOp::ListMemberTokens), "Members' personal access tokens that reach it"),

425

a("list_token_requests", Op::Tokens(TokenOp::ListTokenRequests), "Tokens waiting for approval"),

426

a("review_token_request", Op::Tokens(TokenOp::ReviewTokenRequest), "Approve or deny one"),

427

a("revoke_member_token", Op::Tokens(TokenOp::RevokeMemberToken), "Revoke a member's token in it"),

],

},

Tool {

title: "Billing",

description: "A workspace's billing: its usage by product, project and day, its budget (the monthly spend limit, alerts and whether usage pauses at it) and its invoices. Amounts are whole millionths of a dollar (`_micros`), or cents (`_cents`) where named. Members read it; changing the budget is for owners, as people, and never for a run's token.",

434

default_action: Some("usage"),

435

actions: &[

436

a("usage", Op::GetUsage, "Usage over a range of days, by product, meter, project and day, and what paid for it"),

437

a("budget", Op::GetBudget, "The monthly spend limit, what was spent, alerts and whether usage pauses at the limit"),

438

a("set_budget", Op::SetBudget, "Change the spend limit, alerts, pausing or the alert webhook"),

439

a("invoices", Op::ListInvoices, "Every invoice, the itemised usage invoices, and the next one so far"),

440

a("billing_details", Op::GetBillingDetails, "Who invoices are made out to and the payment method on file"),

],

},

Tool {

title: "Security",

description: "A repository's security: secret scanning alerts and push protection bypasses, custom secret patterns, code scanning alerts and SARIF uploads, vulnerability alerts, the dependency graph and its SBOM, dependency review, settings, a workspace's overview, security advisories and private vulnerability reports. Findings are shown to those who can change the code only; published advisories to anyone who can see the repository. Give `repo` (owner/name), or `workspace` for lists across one.",

447

default_action: Some("secret_alerts"),

448

actions: &[

449

a("secret_alerts", Op::Security(SecurityOp::ListSecretAlerts), "Secret scanning alerts; by state, secret_type, validity, bypassed"),

450

a("secret_alert", Op::Security(SecurityOp::GetSecretAlert), "One secret alert, with where it was found and its bypass requests"),

451

a("update_secret_alert", Op::Security(SecurityOp::UpdateSecretAlert), "Dismiss a secret alert with a reason, or reopen it"),

452

a("secret_locations", Op::Security(SecurityOp::ListSecretLocations), "Every file, line and commit a secret is in"),

453

a("bypass", Op::Security(SecurityOp::BypassPushProtection), "Push past push protection with a reason, or ask to"),

454

a("check_validity", Op::Security(SecurityOp::CheckSecretValidity), "Ask a secret's issuer whether it still works"),

455

a("bypass_requests", Op::Security(SecurityOp::ListBypassRequests), "A workspace's push protection bypass requests"),

456

a("review_bypass", Op::Security(SecurityOp::ReviewBypassRequest), "Approve, deny or cancel a bypass request"),

457

a("patterns", Op::Security(SecurityOp::ListCustomPatterns), "Custom secret patterns of a repository or workspace"),

458

a("create_pattern", Op::Security(SecurityOp::CreateCustomPattern), "Create a custom secret pattern, as a draft or published"),

459

a("update_pattern", Op::Security(SecurityOp::UpdateCustomPattern), "Change, publish or unpublish a custom pattern"),

460

a("delete_pattern", Op::Security(SecurityOp::DeleteCustomPattern), "Delete a custom pattern"),

461

a("dry_run_pattern", Op::Security(SecurityOp::DryRunCustomPattern), "Run a pattern over the default branch without saving it"),

462

a("code_alerts", Op::Security(SecurityOp::ListCodeAlerts), "Code scanning alerts; by state, severity, tool, rule_id"),

463

a("code_alert", Op::Security(SecurityOp::GetCodeAlert), "One code scanning alert by number"),

464

a("update_code_alert", Op::Security(SecurityOp::UpdateCodeAlert), "Dismiss a code scanning alert with a reason, or reopen it"),

465

a("analyses", Op::Security(SecurityOp::ListAnalyses), "Code scanning analyses, newest first"),

466

a("upload_sarif", Op::Security(SecurityOp::UploadSarif), "Upload a SARIF file, gzipped and base64-encoded"),

467

a("sarif_upload", Op::Security(SecurityOp::GetSarifUpload), "Whether a SARIF upload was read, and its analyses"),

468

a("vulnerability_alerts", Op::Security(SecurityOp::ListVulnerabilityAlerts), "Vulnerable dependencies; by state, severity, ecosystem, package"),

469

a("vulnerability_alert", Op::Security(SecurityOp::GetVulnerabilityAlert), "One vulnerability alert"),

470

a("update_vulnerability_alert", Op::Security(SecurityOp::UpdateVulnerabilityAlert), "Dismiss a vulnerability alert with a reason, or reopen it"),

471

a("dependency_graph", Op::Security(SecurityOp::GetDependencyGraph), "Every package the lockfiles resolve, direct or transitive"),

472

a("sbom", Op::Security(SecurityOp::GetSbom), "The dependency graph as an SPDX 2.3 document"),

473

a("compare_dependencies", Op::Security(SecurityOp::CompareDependencies), "What changes in dependencies between base...head"),

474

a("settings", Op::Security(SecurityOp::GetSettings), "A repository's security settings"),

475

a("update_settings", Op::Security(SecurityOp::UpdateSettings), "Change when checks fail and dependency review's policy"),

476

a("workspace_settings", Op::Security(SecurityOp::GetWorkspaceSettings), "A workspace's delegated bypass and validity checks"),

477

a("update_workspace_settings", Op::Security(SecurityOp::UpdateWorkspaceSettings), "Turn delegated bypass or validity checks on or off"),

478

a("overview", Op::Security(SecurityOp::GetOverview), "A workspace's alerts, trends and coverage"),

479

a("advisories", Op::Security(SecurityOp::ListAdvisories), "A repository's security advisories; by state"),

480

a("advisory", Op::Security(SecurityOp::GetAdvisory), "One advisory by adv_… or G1TSA-… id"),

481

a("create_advisory", Op::Security(SecurityOp::CreateAdvisory), "Draft a security advisory"),

482

a("update_advisory", Op::Security(SecurityOp::UpdateAdvisory), "Change an advisory's fields"),

483

a("set_advisory_state", Op::Security(SecurityOp::SetAdvisoryState), "Publish or withdraw an advisory"),

484

a("reports", Op::Security(SecurityOp::ListReports), "Vulnerability reports sent to the maintainers; by state"),

485

a("report_vulnerability", Op::Security(SecurityOp::ReportVulnerability), "Report a vulnerability privately to a repository's maintainers"),

486

a("review_report", Op::Security(SecurityOp::ReviewReport), "Accept a report as a draft advisory, or decline it"),

],

},

Tool {

title: "Notifications",

492

description: "Your inbox: what needs you, and what you follow. One thread per issue, pull request, workflow or deployment, with why you were told (`reason`): a review asked of you, an assignment, a mention, your work's checks, or what you subscribe to and watch. Mark threads read or done once handled, and choose what you hear of with subscribe, unsubscribe and watch. Your own: a personal token.",

493

default_action: Some("list"),

494

actions: &[

495

a("list", Op::ListNotifications, "Unread threads, latest first; all, a view, a reason, a repository"),

496

a("get", Op::GetNotificationThread, "One thread with its recent activity and your subscription"),

497

a("mark_read", Op::MarkThreadRead, "Mark a thread read, or unread"),

498

a("mark_all_read", Op::MarkNotificationsRead, "Mark everything read up to a time, or one repository's"),

499

a("done", Op::MarkThreadDone, "Mark a thread done; new activity brings it back"),

500

a("save", Op::SaveThread, "Save a thread, or unsave it"),

501

a("snooze", Op::SnoozeThread, "Snooze a thread until a time, or bring it back"),

502

a("subscription", Op::GetThreadSubscription, "Your subscription to an issue or pull request"),

503

a("subscribe", Op::SetThreadSubscription, "Subscribe to an issue or pull request, or ignore it"),

504

a("unsubscribe", Op::DeleteThreadSubscription, "Unsubscribe until you comment or are mentioned"),

505

a("watching", Op::GetRepoSubscription, "How you watch a repository"),

506

a("watch", Op::SetRepoSubscription, "Watch a repository: participating, all, ignore or custom"),

507

a("unwatch", Op::DeleteRepoSubscription, "Stop watching a repository"),

508

a("watched", Op::ListWatchedRepos, "Repositories you watch other than the default way"),

],

},

Tool {

title: "Your account",

514

description: "Who this token acts as and its workspaces (`whoami`), your email addresses, your invites, and invitations to workspaces and repositories waiting for you.",

515

default_action: Some("whoami"),

516

actions: &[

517

a("whoami", Op::Whoami, "Who the token acts as, and its workspaces"),

518

a("list_emails", Op::ListEmails, "Your addresses"),

519

a("add_email", Op::AddEmail, "Add an address"),

520

a("confirm_email", Op::ConfirmEmail, "Confirm an address with the code from its email"),

521

a("remove_email", Op::RemoveEmail, "Remove an address"),

522

a("update_email_settings", Op::UpdateEmailSettings, "Primary, backup and privacy"),

523

a("list_invites", Op::ListInvites, "Your invites to g1t"),

524

a("create_invite", Op::CreateInvite, "Make an invite"),

525

a("revoke_invite", Op::RevokeInvite, "Revoke one"),

526

a("list_workspace_invitations", Op::ListInvitations, "Invitations to workspaces for you"),

527

a("accept_workspace_invitation", Op::AcceptInvitation, "Accept one and join"),

528

a("decline_workspace_invitation", Op::DeclineInvitation, "Decline one"),

529

a("list_repository_invitations", Op::ListMyRepoInvitations, "Invitations to repositories for you"),

530

a("accept_repository_invitation", Op::AcceptRepoInvitation, "Accept one"),

531

a("decline_repository_invitation", Op::DeclineRepoInvitation, "Decline one"),

],

},

Tool {

title: "Artifacts",

description: "A workspace's docs, slides, designs and dashboards (Artifacts mode), as you can open them: list, search and read them (a doc's content is Markdown, with block ids to target), make them, edit them (a change with the edit role, a suggestion with comment), move, trash and restore them, their versions, and who can open them. Name one by its id (fol_…) or its address. Not the `workflow` tool's run artifacts. Slides, designs and dashboards answer that they are not here yet.",

538

default_action: None,

539

actions: &[

540

a("list", Op::Folios(FoliosOp::List), "Artifacts you can open; tab, kind, space, q; state trashed for the trash"),

541

a("search", Op::Folios(FoliosOp::Search), "Search them by words and meaning, with the passage that matched"),

542

a("get", Op::Folios(FoliosOp::Get), "One artifact: kind, title, space, owner, your role, who it is shared with"),

543

a("read", Op::Folios(FoliosOp::GetContent), "Its content: a doc's Markdown and block ids, and what you may do"),

544

a("versions", Op::Folios(FoliosOp::ListVersions), "Its saved versions, newest first"),

545

a("access", Op::Folios(FoliosOp::GetAccess), "Who can open it, and how"),

546

a("templates", Op::Folios(FoliosOp::ListTemplates), "Templates to start one from"),

547

a("spaces", Op::Folios(FoliosOp::ListSpaces), "The spaces in your sidebar"),

548

a("query_data", Op::Folios(FoliosOp::QueryDataset), "Run a dataset query as you, over what you can read"),

549

a("create", Op::Folios(FoliosOp::Create), "Make one: in a space, under a doc, or in your Private"),

550

a("update", Op::Folios(FoliosOp::Update), "Rename it, change its icon, or move it"),

551

a("edit", Op::Folios(FoliosOp::Edit), "Change its content: append, replace it all, a section or blocks"),

552

a("trash", Op::Folios(FoliosOp::Trash), "Move it to the trash; restorable for 30 days"),

553

a("restore", Op::Folios(FoliosOp::Restore), "Bring it back from the trash"),

554

a("restore_version", Op::Folios(FoliosOp::RestoreVersion), "Make an earlier version its content again"),

555

a("share", Op::Folios(FoliosOp::SetAccess), "Share it, change general access, or take access away"),

556

a("purge", Op::Folios(FoliosOp::Purge), "Delete one in the trash for good"),

],

},

];

/// Operations offered over REST alone, not as an action of any tool: how

562

/// a project's telemetry is collected (settings, ingest tokens, exports,

563

/// usage) is for people setting it up, not for agents debugging.

564

pub const REST_ONLY: &[Op] = &[

565

Op::Telemetry(TelemetryOp::GetSettings),

566

Op::Telemetry(TelemetryOp::UpdateSettings),

567

Op::Telemetry(TelemetryOp::ListTokens),

568

Op::Telemetry(TelemetryOp::CreateToken),

569

Op::Telemetry(TelemetryOp::DeleteToken),

570

Op::Telemetry(TelemetryOp::ListExports),

571

Op::Telemetry(TelemetryOp::CreateExport),

572

Op::Telemetry(TelemetryOp::UpdateExport),

573

Op::Telemetry(TelemetryOp::DeleteExport),

574

Op::Telemetry(TelemetryOp::GetUsage),

575

];

576

577

/// Operations that cannot be undone, or reach beyond g1t's own records:

578

/// clients ask before running a tool that has any of them.

579

fn destructive(op: Op) -> bool {

580

matches!(

581

op,

582

Op::Security(SecurityOp::DeleteCustomPattern | SecurityOp::BypassPushProtection)

583

| Op::Rules(RulesOp::DeleteRepoRuleset | RulesOp::DeleteWorkspaceRuleset)

584

| Op::DeleteWorkspace

585

| Op::UpdateWorkspace

586

| Op::Tokens(TokenOp::RevokeMemberToken | TokenOp::SetTokenPolicy)

587

| Op::RemoveMember

588

| Op::TransferOwnership

| Op::LeaveWorkspace

| Op::DeleteRepo

| Op::PurgeRepo

| Op::TransferRepo

| Op::SetRepoVisibility

594

| Op::RemoveEmail

595

| Op::RemoveCollaborator

596

| Op::DisconnectIntegration

597

| Op::UpdateIntegration

598

| Op::DeleteWebhook

599

| Op::DeleteActionsSecret

600

| Op::DeleteActionsVariable

601

| Op::SetActionsSecret

602

| Op::SetActionsVariable

603

| Op::SetBasePermission

604

| Op::DeleteTeam

605

| Op::RemoveTeamRepo

606

| Op::MergePullRequest

607

| Op::RemoveRunner

608

| Op::DeleteRunnerGroup

609

| Op::UpdateRunnerSettings

610

| Op::Folios(FoliosOp::SetAccess | FoliosOp::Purge)

)

}

/// Whether an operation only reads.

615

pub fn reads_only(op: Op) -> bool {

616

NO_SCOPE.contains(&op.name())

617

|| scope_for(op.name()).is_some_and(|scope| scope.level() == Level::Read)

618

}

619

620

/// What decides which actions a caller sees.

621

pub enum Gate<'a> {

622

/// No limit beyond the person's own role.

623

Everything,

624

/// A run's token (a checks, merge queue or deploy job): the

625

/// operations its run lists.

626

Agent(&'a AgentScope),

627

/// An access token with scopes.

628

Token(&'a TokenAccess),

}

impl Gate<'_> {

pub fn allows(&self, op: Op) -> bool {

633

match self {

634

Gate::Everything => true,

635

Gate::Agent(scope) => op.allowed_by(scope) && !NEVER.contains(&op.name()),

636

Gate::Token(access) => {

637

if NO_SCOPE.contains(&op.name()) {

638

return true;

639

}

640

match scope_for(op.name()) {

641

Some(scope) => access.allows(scope),

642

None => access.scopes.is_none(),

}

}

}

}

}

impl Tool {

pub fn by_name(name: &str) -> Option<&'static Tool> {

651

TOOLS.iter().find(|tool| tool.name == name)

652

}

653

654

pub fn action(&self, name: &str) -> Option<&'static Action> {

655

// The tools are 'static; find through TOOLS to keep the lifetime.

656

TOOLS

657

.iter()

658

.find(|tool| tool.name == self.name)

659

.and_then(|tool| tool.actions.iter().find(|action| action.name == name))

660

}

661

662

pub fn visible(&self, gate: &Gate) -> Vec<&'static Action> {

663

TOOLS

664

.iter()

665

.find(|tool| tool.name == self.name)

666

.map(|tool| tool.actions.iter().filter(|action| gate.allows(action.op)).collect())

.unwrap_or_default()

}

/// The flat input schema of the actions given.

671

pub fn input_schema(&self, actions: &[&Action]) -> Value {

672

let mut properties = Map::new();

673

let lines: Vec<String> = actions

674

.iter()

675

.map(|action| {

676

let required: Vec<String> = action.op.required();

677

if required.is_empty() {

678

format!("{}: {}.", action.name, action.summary)

679

} else {

680

format!("{} ({}): {}.", action.name, required.join(", "), action.summary)

}

})

.collect();

let mut action_schema = json!({

685

"type": "string",

686

"enum": actions.iter().map(|action| action.name).collect::<Vec<_>>(),

687

"description": lines.join("\n"),

688

});

689

if let Some(default) = self.default_action.filter(|name| actions.iter().any(|action| action.name == *name)) {

690

action_schema["default"] = json!(default);

691

}

692

properties.insert("action".to_owned(), action_schema);

693

for action in actions {

694

for (name, schema) in action.op.properties() {

695

merge_property(&mut properties, name, schema);

696

}

697

}

698

let mut required = vec![];

699

if self.default_action.is_none() {

700

required.push("action");

701

}

702

let mut schema = json!({ "type": "object", "properties": properties });

703

if !required.is_empty() {

704

schema["required"] = json!(required);

}

schema

}

/// The input schema keyed by action: one `oneOf` branch per action,

710

/// each with its own fields and the ones it needs.

711

pub fn discriminated(&self, actions: &[&Action]) -> Value {

712

let branches: Vec<Value> = actions

713

.iter()

714

.map(|action| {

715

let mut properties = Map::new();

716

properties.insert("action".to_owned(), json!({ "const": action.name }));

717

properties.extend(action.op.properties());

718

let mut required = vec![Value::String("action".to_owned())];

719

// The default action may leave `action` out.

720

if self.default_action == Some(action.name) {

721

required.clear();

722

}

723

required.extend(action.op.required().into_iter().map(Value::String));

724

json!({

725

"title": action.name,

726

"description": action.summary,

727

"type": "object",

728

"properties": properties,

729

"required": required,

})

})

.collect();

json!({ "type": "object", "oneOf": branches })

734

}

735

736

/// MCP's hints about the actions given: whether the tool only reads,

737

/// whether it can destroy something, and whether calling it twice is

738

/// the same as once.

739

pub fn annotations(&self, actions: &[&Action]) -> Value {

740

let read_only = actions.iter().all(|action| reads_only(action.op));

741

json!({

742

"title": self.title,

743

"readOnlyHint": read_only,

744

"destructiveHint": !read_only && actions.iter().any(|action| destructive(action.op)),

745

"idempotentHint": read_only,

746

"openWorldHint": false,

})

}

/// The tool as `tools/list` gives it, for a caller behind `gate`, or

751

/// `None` when it may use none of its actions.

752

pub fn listed(&self, gate: &Gate) -> Option<Value> {

753

let actions = self.visible(gate);

754

if actions.is_empty() {

return None;

}

Some(json!({

"name": self.name,

"title": self.title,

"description": self.description,

761

"inputSchema": self.input_schema(&actions),

762

"annotations": self.annotations(&actions),

}))

}

}

/// Adds a property to a tool's flat schema. The first action to use a name

768

/// describes it; a later one with other allowed values adds them.

769

fn merge_property(properties: &mut Map<String, Value>, name: String, schema: Value) {

770

match properties.get_mut(&name) {

771

None => {

772

properties.insert(name, schema);

773

}

774

Some(existing) => {

775

if let (Some(Value::Array(had)), Some(Value::Array(more))) =

776

(existing.get("enum").cloned(), schema.get("enum"))

777

{

778

let mut merged = had;

779

for value in more {

780

if !merged.contains(value) {

781

merged.push(value.clone());

782

}

783

}

784

existing["enum"] = Value::Array(merged);

785

}

786

// Different kinds of value under one name: say less, accept both.

787

if existing.get("type") != schema.get("type")

788

&& let Some(fields) = existing.as_object_mut()

789

{

790

fields.remove("type");

791

fields.remove("items");

}

}

}

}

/// What a call to a tool runs: the operation its action names, or why not.

798

pub fn resolve(tool: &Tool, arguments: &Value) -> Result<Op, String> {

let names = || {

tool.actions

.iter()

.map(|action| action.name)

.collect::<Vec<_>>()

.join(", ")

};

let Some(name) = arguments["action"].as_str().or(tool.default_action) else {

807

return Err(format!("Give an action: one of {}.", names()));

808

};

809

let Some(action) = tool.action(name) else {

810

return Err(format!("{} has no action {name}. Its actions: {}.", tool.name, names()));

811

};

812

let missing: Vec<String> = action

.op

.required()

.into_iter()

.filter(|field| arguments.get(field).is_none_or(Value::is_null))

817

.collect();

818

if !missing.is_empty() {

819

return Err(format!("{}.{name} needs {}.", tool.name, missing.join(", ")));

}

Ok(action.op)

}

#[cfg(test)]

mod tests {

use super::*;

use g1t_contracts::scopes::{Preset, Scope};

828

829

/// Operations g1t no longer has, which the scopes table in

830

/// g1t-contracts still names until it is trimmed.

831

const RETIRED: &[&str] = &[

"message_agent",

"answer_message",

"take_messages",

"search_context",

"get_entity",

"assign_issue",

"delegate",

"plan_work",

"get_plan",

"apply_plan",

"get_model_routes",

"set_model_routes",

"get_agent_computer",

845

"wake_agent_computer",

846

"sleep_agent_computer",

847

"reset_agent_computer",

848

"list_agent_computer_commands",

849

"list_gateway_requests",

850

"fix_security_alert",

851

"list_marketplaces",

852

"add_marketplace",

853

"remove_marketplace",

854

"refresh_marketplace",

"discover",

"list_plugins",

"get_plugin",

"install_plugin",

"set_plugin_enabled",

"uninstall_plugin",

"update_plugin",

"get_ai_credit",

"buy_ai_credit",

"list_plugin_agents",

"list_connectors",

"get_connector",

"add_connector",

"set_connector_key",

"remove_connector",

"refresh_connector",

"grant_connector",

"revoke_connector",

"customize_bundle",

];

fn listed(gate: &Gate) -> Vec<Value> {

877

TOOLS.iter().filter_map(|tool| tool.listed(gate)).collect()

878

}

879

880

fn token(scopes: Option<Vec<Scope>>) -> TokenAccess {

881

TokenAccess {

882

token_id: "tok_1".to_owned(),

883

scopes: scopes.map(|scopes| scopes.iter().map(|scope| scope.as_str().to_owned()).collect()),

884

legacy: false,

885

886

..TokenAccess::default()

}

}

#[test]

fn every_operation_is_exactly_one_action_of_one_tool() {

for op in Op::ALL {

let count = TOOLS

.iter()

.flat_map(|tool| tool.actions.iter())

896

.filter(|action| action.op == op)

897

.count();

898

let expected = usize::from(!REST_ONLY.contains(&op));

899

assert_eq!(count, expected, "{} is {count} actions", op.name());

900

}

901

for tool in TOOLS {

902

let mut names = std::collections::HashSet::new();

903

for action in tool.actions {

904

assert!(names.insert(action.name), "{}.{} twice", tool.name, action.name);

905

}

906

if let Some(default) = tool.default_action {

907

assert!(tool.action(default).is_some(), "{}", tool.name);

908

}

909

}

910

assert!(TOOLS.len() <= 18, "{} tools", TOOLS.len());

}

#[test]

fn every_operation_needs_exactly_one_scope_or_none() {

915

use g1t_contracts::scopes::OPERATIONS;

916

for op in Op::ALL {

917

let mapped = OPERATIONS.iter().filter(|(name, _)| *name == op.name()).count();

918

let free = NO_SCOPE.contains(&op.name());

919

assert_eq!(mapped + usize::from(free), 1, "{}", op.name());

920

}

921

for (name, _) in OPERATIONS {

922

assert!(Op::by_name(name).is_some() || RETIRED.contains(name), "{name} is not an operation");

}

}

#[test]

fn each_tool_schema_is_valid_with_one_branch_per_action() {

928

for tool in TOOLS {

929

let actions: Vec<&Action> = tool.actions.iter().collect();

930

let flat = tool.input_schema(&actions);

931

assert_eq!(flat["type"], "object");

932

assert!(flat.get("oneOf").is_none(), "no oneOf at the top level");

933

let listed: Vec<&str> = flat["properties"]["action"]["enum"]

.as_array()

.unwrap()

.iter()

.map(|name| name.as_str().unwrap())

938

.collect();

939

assert_eq!(listed, tool.actions.iter().map(|action| action.name).collect::<Vec<_>>());

940

for action in tool.actions {

941

for field in action.op.required() {

942

assert!(flat["properties"].get(&field).is_some(), "{}.{}: {field}", tool.name, action.name);

943

}

944

}

945

let keyed = tool.discriminated(&actions);

946

let branches = keyed["oneOf"].as_array().unwrap();

947

assert_eq!(branches.len(), tool.actions.len());

948

for (branch, action) in branches.iter().zip(tool.actions) {

949

assert_eq!(branch["properties"]["action"]["const"], action.name);

950

for field in branch["required"].as_array().unwrap() {

951

assert!(branch["properties"].get(field.as_str().unwrap()).is_some(), "{}.{}: {field}", tool.name, action.name);

952

}

953

}

954

// A well-formed JSON Schema object throughout.

955

let text = serde_json::to_string(&flat).unwrap();

956

assert!(serde_json::from_str::<Value>(&text).is_ok());

}

}

#[test]

fn a_read_only_token_sees_read_actions_only() {

962

let access = token(Preset::ReadOnly.scopes());

963

let gate = Gate::Token(&access);

964

for tool in TOOLS {

965

for action in tool.visible(&gate) {

966

assert!(reads_only(action.op), "{}.{}", tool.name, action.name);

967

}

968

}

969

let tools = listed(&gate);

970

for tool in &tools {

971

assert_eq!(tool["annotations"]["readOnlyHint"], true, "{}", tool["name"]);

972

assert_eq!(tool["annotations"]["destructiveHint"], false);

973

}

974

let issue = tools.iter().find(|tool| tool["name"] == "issue").unwrap();

975

assert_eq!(issue["inputSchema"]["properties"]["action"]["enum"], json!(["list", "get", "labels"]));

}

#[test]

fn a_narrow_token_sees_only_its_tools() {

980

let access = token(Some(vec![Scope::IssuesWrite]));

981

let names: Vec<Value> = listed(&Gate::Token(&access)).into_iter().map(|tool| tool["name"].clone()).collect();

982

// Labels and milestones are the repository's, managed with issues:write.

983

assert_eq!(names, vec![json!("repository"), json!("issue"), json!("account")]);

984

// Notifications are a resource of their own: reading them lists

985

// only what reads.

986

let reader = token(Some(vec![Scope::NotificationsRead]));

987

let tools = listed(&Gate::Token(&reader));

988

let notifications = tools.iter().find(|tool| tool["name"] == "notifications").unwrap();

989

assert_eq!(

990

notifications["inputSchema"]["properties"]["action"]["enum"],

991

json!(["list", "get", "subscription", "watching", "watched"])

992

);

993

assert_eq!(notifications["annotations"]["readOnlyHint"], true);

994

let full = token(None);

995

assert_eq!(listed(&Gate::Token(&full)).len(), TOOLS.len());

996

assert_eq!(listed(&Gate::Everything).len(), TOOLS.len());

}

#[test]

fn a_tool_that_can_destroy_says_so() {

1001

let tools = listed(&Gate::Everything);

1002

let repository = tools.iter().find(|tool| tool["name"] == "repository").unwrap();

1003

assert_eq!(repository["annotations"]["destructiveHint"], true);

1004

assert_eq!(repository["annotations"]["readOnlyHint"], false);

1005

let memory = tools.iter().find(|tool| tool["name"] == "memory").unwrap();

1006

assert_eq!(memory["annotations"]["destructiveHint"], false);

}

#[test]

fn calls_resolve_to_their_operation_or_say_what_is_missing() {

1011

let issue = Tool::by_name("issue").unwrap();

1012

assert_eq!(resolve(issue, &json!({ "action": "get", "repo": "a/b", "number": 1 })), Ok(Op::GetIssue));

1013

assert_eq!(resolve(issue, &json!({ "action": "get", "repo": "a/b" })), Err("issue.get needs number.".to_owned()));

1014

assert!(resolve(issue, &json!({})).unwrap_err().starts_with("Give an action"));

1015

assert!(resolve(issue, &json!({ "action": "explode" })).unwrap_err().contains("no action explode"));

1016

let search = Tool::by_name("search").unwrap();

1017

assert_eq!(resolve(search, &json!({ "query": "x" })), Ok(Op::Search));

1018

let account = Tool::by_name("account").unwrap();

1019

assert_eq!(resolve(account, &json!({})), Ok(Op::Whoami));

}

#[test]

fn teams_are_one_tool_and_a_workspace_reader_sees_only_its_reads() {

1024

let team = Tool::by_name("team").unwrap();

1025

let names: Vec<&str> = team.actions.iter().map(|action| action.name).collect();

assert_eq!(

names,

[

"list",

"get",

"create",

"update",

"delete",

"list_members",

"set_member",

"remove_member",

"list_child_teams",

"list_repos",

"set_repo",

"remove_repo",

"set_review_assignment",

"list_user_teams",

]

);

let reader = token(Some(vec![Scope::WorkspaceRead]));

1046

let tools = listed(&Gate::Token(&reader));

1047

let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap();

1048

assert_eq!(

1049

listed_team["inputSchema"]["properties"]["action"]["enum"],

1050

json!(["list", "get", "list_members", "list_child_teams", "list_repos", "list_user_teams"])

1051

);

1052

assert_eq!(listed_team["annotations"]["readOnlyHint"], true);

1053

// A team's role on a repository is who has access.

1054

let admin = token(Some(vec![Scope::WorkspaceAdmin]));

1055

let tools = listed(&Gate::Token(&admin));

1056

let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap();

1057

let actions = listed_team["inputSchema"]["properties"]["action"]["enum"].as_array().unwrap();

1058

assert!(actions.contains(&json!("set_review_assignment")) && !actions.contains(&json!("set_repo")));

1059

let access = token(Some(vec![Scope::AccessAdmin]));

1060

let tools = listed(&Gate::Token(&access));

1061

let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap();

1062

assert_eq!(listed_team["inputSchema"]["properties"]["action"]["enum"], json!(["set_repo", "remove_repo"]));

1063

// Both kinds of role a schema names are offered.

1064

let roles = &listed(&Gate::Everything).into_iter().find(|tool| tool["name"] == "team").unwrap()["inputSchema"]

1065

["properties"]["role"]["enum"];

1066

for role in ["member", "maintainer", "read", "admin"] {

1067

assert!(roles.as_array().unwrap().contains(&json!(role)), "{role}");

1068

}

1069

assert_eq!(

1070

resolve(team, &json!({ "action": "set_repo", "workspace": "acme", "team": "backend", "repo": "rocket" })),

1071

Err("team.set_repo needs role.".to_owned())

);

}

#[test]

fn reviewers_and_code_owners_are_actions_of_their_tools() {

1077

let pull = Tool::by_name("pull_request").unwrap();

1078

assert_eq!(

1079

resolve(pull, &json!({ "action": "request_reviewers", "repo": "a/b", "number": 1, "team_reviewers": ["backend"] })),

1080

Ok(Op::RequestReviewers)

1081

);

1082

assert_eq!(pull.action("remove_requested_reviewers").map(|action| action.op), Some(Op::RemoveRequestedReviewers));

1083

let repository = Tool::by_name("repository").unwrap();

1084

assert_eq!(resolve(repository, &json!({ "action": "codeowners", "repo": "a/b" })), Ok(Op::GetCodeownersErrors));

1085

assert!(reads_only(Op::GetCodeownersErrors));

1086

assert!(!reads_only(Op::RequestReviewers));

1087

}

1088

1089

/// The `artifact` tool offers each token only what its artifacts scope

1090

/// allows: reading, then changing, then sharing and deleting for good.

1091

/// Workflow runs' artifacts are the `workflow` tool's, under their own

1092

/// scope, and neither scope reaches the other's.

1093

#[test]

1094

fn the_artifact_tool_offers_what_the_artifacts_scope_allows() {

1095

let actions = |scopes: Vec<Scope>| -> Option<Value> {

1096

let access = token(Some(scopes));

1097

Tool::by_name("artifact").unwrap().listed(&Gate::Token(&access)).map(|tool| tool["inputSchema"]["properties"]["action"]["enum"].clone())

1098

};

1099

let reads = json!(["list", "search", "get", "read", "versions", "access", "templates", "spaces", "query_data"]);

1100

assert_eq!(actions(vec![Scope::ArtifactsRead]), Some(reads.clone()));

1101

let writes = actions(vec![Scope::ArtifactsWrite]).unwrap();

1102

for action in ["create", "update", "edit", "trash", "restore", "restore_version"] {

1103

assert!(writes.as_array().unwrap().contains(&json!(action)), "{action}");

1104

}

1105

assert!(!writes.as_array().unwrap().contains(&json!("share")) && !writes.as_array().unwrap().contains(&json!("purge")));

1106

let admin = actions(vec![Scope::ArtifactsAdmin]).unwrap();

1107

assert_eq!(admin.as_array().unwrap().len(), Tool::by_name("artifact").unwrap().actions.len());

1108

// Without an artifacts scope there is no artifact tool at all.

1109

assert_eq!(actions(vec![Scope::WorkflowsWrite, Scope::IssuesWrite]), None);

1110

// And an artifacts scope shows nothing of workflow runs' artifacts.

1111

let access = token(Some(vec![Scope::ArtifactsAdmin]));

1112

assert!(Tool::by_name("workflow").unwrap().listed(&Gate::Token(&access)).is_none());

1113

// The read-only and agent presets read artifacts and change none.

1114

for preset in [Preset::ReadOnly, Preset::Agent] {

1115

let access = token(preset.scopes());

1116

let tool = Tool::by_name("artifact").unwrap().listed(&Gate::Token(&access)).unwrap();

1117

assert_eq!(tool["inputSchema"]["properties"]["action"]["enum"], reads, "{}", preset.as_str());

1118

assert_eq!(tool["annotations"]["readOnlyHint"], true);

1119

}

1120

// Sharing and deleting for good can't be undone the same way.

1121

let tools = listed(&Gate::Everything);

1122

let artifact = tools.iter().find(|tool| tool["name"] == "artifact").unwrap();

1123

assert_eq!(artifact["annotations"]["destructiveHint"], true);

1124

assert!(artifact["description"].as_str().unwrap().contains("Not the `workflow` tool's run artifacts"));

1125

let tool = Tool::by_name("artifact").unwrap();

1126

assert_eq!(resolve(tool, &json!({ "action": "read", "workspace": "acme" })), Err("artifact.read needs artifact_id.".to_owned()));

1127

assert_eq!(

1128

resolve(tool, &json!({ "action": "edit", "workspace": "acme", "artifact_id": "fol_1", "markdown": "x" })),

1129

Ok(Op::Folios(FoliosOp::Edit))

);

}

/// How much smaller `tools/list` is than one tool per operation. Run

1134

/// with `--nocapture` to see the numbers.

1135

#[test]

1136

fn the_tool_list_is_much_smaller_than_one_tool_per_operation() {

1137

let before: Vec<Value> = Op::ALL

1138

.into_iter()

1139

.map(|op| json!({ "name": op.name(), "description": op.description(), "inputSchema": op.input() }))

1140

.collect();

1141

let after = listed(&Gate::Everything);

1142

let before_bytes = serde_json::to_string(&json!({ "tools": before })).unwrap().len();

1143

let after_bytes = serde_json::to_string(&json!({ "tools": after })).unwrap().len();

1144

let agent = token(Preset::Agent.scopes());

1145

let agent_bytes = serde_json::to_string(&json!({ "tools": listed(&Gate::Token(&agent)) })).unwrap().len();

1146

let read = token(Preset::ReadOnly.scopes());

1147

let read_bytes = serde_json::to_string(&json!({ "tools": listed(&Gate::Token(&read)) })).unwrap().len();

1148

println!(

1149

"tools/list: before {} tools, {before_bytes} bytes (~{} tokens); after {} tools, {after_bytes} bytes (~{} tokens); agent preset {agent_bytes} bytes (~{} tokens); read only {read_bytes} bytes (~{} tokens)",

before.len(),

before_bytes / 4,

after.len(),

after_bytes / 4,

agent_bytes / 4,

read_bytes / 4,