Skip to content
Sign in

flagon-io/g1t

public
0
953 linesCodeBlameRaw

Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.

Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step1//! The MCP server's tools: a few resource tools, each with an `action`.
2//!
3//! Every operation is one action of one tool. A call is dispatched to the
4//! operation it names, so permissions, the audit log, billing and outcomes
5//! are exactly those of the REST API. A token sees only the actions its
6//! scopes allow, and a tool none of whose actions it may use is not listed.
7//!
8//! The listed input schema is one flat object: `action`, then every field
9//! any of its actions takes. Which fields each action needs is in the
10//! `action` field's description and checked on every call. Claude's API,
11//! and so most MCP clients, refuse a tool whose input schema has `oneOf`
12//! at its top level, so the schema keyed by action, with each action's
13//! required fields, is [`discriminated`], published on the server's card
14//! and in the docs.
15
16use g1t_contracts::credentials::NEVER;
17use g1t_contracts::identity::AgentScope;
18use g1t_contracts::scopes::{Level, NO_SCOPE, TokenAccess, scope_for};
19use serde_json::{Map, Value, json};
20
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9721use crate::about::AboutOp;
Merge main into the run-protection branch22use crate::artifacts::ArtifactsOp;
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9723use crate::deployments::DeploymentsOp;
Actions: keep workflow runs safe24use crate::protection::ProtectionOp;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step25use crate::operations::Op;
Merge checks: statuses and check runs on every commit26use crate::checks::ChecksOp;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge27use crate::rules::RulesOp;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar28use crate::security::SecurityOp;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step29
30pub struct Action {
31 pub name: &'static str,
32 pub op: Op,
33 /// One line, for the `action` field's description.
34 pub summary: &'static str,
35}
36
37pub struct Tool {
38 pub name: &'static str,
39 pub title: &'static str,
40 /// What it is for, in a sentence or two.
41 pub description: &'static str,
42 pub actions: &'static [Action],
43 /// The action a call without one runs.
44 pub default_action: Option<&'static str>,
45}
46
47const fn a(name: &'static str, op: Op, summary: &'static str) -> Action {
48 Action { name, op, summary }
49}
50
51pub const TOOLS: &[Tool] = &[
52 Tool {
53 name: "search",
54 title: "Search",
55 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. `context` searches one workspace's catalog, docs, issues and memory by meaning.",
56 default_action: Some("code"),
57 actions: &[
58 a("code", Op::Search, "Search all of g1t: repositories, code, issues, pull requests, people"),
59 a("context", Op::SearchContext, "Search a workspace's context hub by meaning"),
60 a("entity", Op::GetEntity, "One catalog entry and its relations"),
61 a("ticket", Op::GetContext, "A Jira, Linear or Sentry item the work refers to, as it is now"),
62 ],
63 },
64 Tool {
65 name: "repository",
66 title: "Repositories",
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9767 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, and publish releases. Name one as \"owner/name\". Deleting, transferring and changing visibility need `confirm`.",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step68 default_action: None,
69 actions: &[
70 a("list", Op::ListRepos, "Repositories you can see"),
71 a("get", Op::GetRepo, "One repository"),
72 a("create", Op::CreateRepo, "Create one, empty or copied from a public git URL"),
73 a("update", Op::UpdateRepo, "Change description, website, topics, default branch, protection"),
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge74 a("get_settings", Op::GetRepoSettings, "How pull requests merge, and the default branch's protection as its rules stack"),
75 a("update_settings", Op::UpdateRepoSettings, "Change how pull requests merge and the default branch protection ruleset"),
76 a("check_names", Op::ListCheckNames, "Check names reported lately, to require in a ruleset"),
77 a("list_rulesets", Op::Rules(RulesOp::ListRepoRulesets), "Its rulesets, and its workspace's that hold in it"),
78 a("get_ruleset", Op::Rules(RulesOp::GetRepoRuleset), "One ruleset"),
79 a("create_ruleset", Op::Rules(RulesOp::CreateRepoRuleset), "Create a ruleset for its branches or tags"),
80 a("update_ruleset", Op::Rules(RulesOp::UpdateRepoRuleset), "Change a ruleset"),
81 a("delete_ruleset", Op::Rules(RulesOp::DeleteRepoRuleset), "Delete a ruleset"),
82 a("branch_rules", Op::Rules(RulesOp::GetBranchRules), "Every rule that holds for a branch or tag, and where it comes from"),
83 a("rule_evaluations", Op::Rules(RulesOp::ListRuleEvaluations), "How its rules judged pushes and merges, with insights"),
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar84 a("codeowners", Op::GetCodeownersErrors, "Problems in its CODEOWNERS file, by line"),
85 a("list_labels", Op::ListLabels, "Labels, with colors and how many issues and pull requests carry each"),
86 a("create_label", Op::CreateLabel, "Create a label"),
87 a("update_label", Op::UpdateLabel, "Rename a label or change its color or description"),
88 a("delete_label", Op::DeleteLabel, "Delete a label, from everything that carries it"),
89 a("add_default_labels", Op::AddDefaultLabels, "Add the default labels it is missing"),
90 a("list_milestones", Op::ListMilestones, "Milestones, with progress and due dates"),
91 a("get_milestone", Op::GetMilestone, "One milestone with its issues and pull requests"),
92 a("create_milestone", Op::CreateMilestone, "Create a milestone"),
93 a("update_milestone", Op::UpdateMilestone, "Change a milestone's title, description, due date or state"),
94 a("delete_milestone", Op::DeleteMilestone, "Delete a milestone"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step95 a("list_events", Op::ListEvents, "Timeline: pushes, issues, pull requests, comments"),
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9796 a("languages", Op::About(AboutOp::GetLanguages), "Its languages by bytes, with colors and percentages"),
97 a("contributors", Op::About(AboutOp::ListContributors), "Who made it: commits per person, agent and author, by week"),
98 a("license", Op::About(AboutOp::GetLicense), "The license its LICENSE file holds"),
99 a("stargazers", Op::About(AboutOp::ListStargazers), "Who starred it"),
100 a("starred", Op::About(AboutOp::CheckStarred), "Whether you starred it, and how many have"),
101 a("star", Op::About(AboutOp::Star), "Star it"),
102 a("unstar", Op::About(AboutOp::Unstar), "Take your star back"),
103 a("list_starred", Op::About(AboutOp::ListStarred), "Repositories you starred"),
104 a("list_releases", Op::About(AboutOp::ListReleases), "Releases, newest first"),
105 a("latest_release", Op::About(AboutOp::GetLatestRelease), "The latest release"),
106 a("get_release", Op::About(AboutOp::GetRelease), "One release by id"),
107 a("get_release_by_tag", Op::About(AboutOp::GetReleaseByTag), "The release of a tag"),
108 a("create_release", Op::About(AboutOp::CreateRelease), "Publish a release of a tag, making the tag if needed"),
109 a("update_release", Op::About(AboutOp::UpdateRelease), "Change a release's title, notes, draft or prerelease"),
110 a("delete_release", Op::About(AboutOp::DeleteRelease), "Delete a release; its tag stays"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step111 a("rename_branch", Op::RenameBranch, "Rename a branch"),
112 a("rename", Op::RenameRepo, "Rename it; old addresses redirect"),
113 a("transfer", Op::TransferRepo, "Move it to another workspace you own"),
114 a("archive", Op::ArchiveRepo, "Make it read-only"),
115 a("unarchive", Op::UnarchiveRepo, "Make it writable again"),
116 a("set_visibility", Op::SetRepoVisibility, "Make it public or private"),
117 a("delete", Op::DeleteRepo, "Delete it; restorable for 30 days"),
118 a("list_deleted", Op::ListDeletedRepos, "A workspace's deleted repositories"),
119 a("restore", Op::RestoreRepo, "Restore a deleted one"),
120 a("purge", Op::PurgeRepo, "Remove a deleted one for good"),
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily121 a("security_alerts", Op::ListSecurityAlerts, "Secret and dependency alerts, filtered by state"),
122 a("dismiss_alert", Op::DismissSecurityAlert, "Dismiss an alert with a reason"),
123 a("reopen_alert", Op::ReopenSecurityAlert, "Reopen a dismissed alert"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step124 ],
125 },
126 Tool {
127 name: "issue",
128 title: "Issues",
129 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.",
130 default_action: None,
131 actions: &[
132 a("list", Op::ListIssues, "Issues on a repository, newest first"),
Fast pages, required checks on the branch, self-hosted runners, honest incidents133 a("get", Op::GetIssue, "One issue with comments and its pull requests"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step134 a("create", Op::CreateIssue, "Open an issue"),
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar135 a("update", Op::UpdateIssue, "Change title, body, labels, milestone or assignees"),
136 a("labels", Op::ListIssueLabels, "The labels an issue or pull request carries"),
137 a("add_labels", Op::AddIssueLabels, "Add labels to an issue or pull request"),
138 a("set_labels", Op::SetIssueLabels, "Replace the labels of an issue or pull request"),
139 a("remove_labels", Op::RemoveIssueLabels, "Take labels off an issue or pull request"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step140 a("close", Op::CloseIssue, "Close it without a pull request"),
141 a("reopen", Op::ReopenIssue, "Reopen it"),
142 a("comment", Op::AddComment, "Comment on an issue or pull request; path and line for one line of a change"),
143 a("import", Op::ImportIssue, "Open an issue from a Jira, Linear or Sentry item"),
144 ],
145 },
146 Tool {
147 name: "pull_request",
148 title: "Pull requests",
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar149 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.",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step150 default_action: None,
151 actions: &[
152 a("list", Op::ListPullRequests, "Pull requests on a repository, newest first"),
Fast pages, required checks on the branch, self-hosted runners, honest incidents153 a("get", Op::GetPullRequest, "Status, checks and required checks, reviews, overlaps, whether it is behind"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step154 a("changes", Op::GetPullRequestChanges, "Files and line-by-line diff"),
155 a("create", Op::CreatePullRequest, "Start a draft with its own fork to push to, or open one from a pushed branch"),
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar156 a("update", Op::UpdatePullRequest, "Change its base branch, labels, milestone, assignees or reviewers"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step157 a("record_session", Op::RecordSession, "Append prompt, reasoning and tool entries to its session"),
158 a("read_session", Op::ReadSession, "Its recorded session"),
159 a("ready", Op::MarkPullRequestReady, "Mark a draft ready, with a summary"),
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar160 a("request_reviewers", Op::RequestReviewers, "Ask people or teams to review it"),
161 a("remove_requested_reviewers", Op::RemoveRequestedReviewers, "Stop asking people or teams to review it"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step162 a("review", Op::ReviewPullRequest, "Approve or request changes"),
163 a("close", Op::ClosePullRequest, "Close without merging"),
164 a("merge", Op::MergePullRequest, "Land it, or join the merge queue"),
165 a("merge_queue", Op::GetMergeQueue, "The repository's merge queue"),
166 ],
167 },
168 Tool {
169 name: "agent",
170 title: "g1t agents",
171 description: "Put g1t's agent to work and talk to it. One agent per issue; to do more at once, use more issues. Starting an agent uses the workspace's money.",
172 default_action: None,
173 actions: &[
174 a("delegate", Op::Delegate, "Open an issue and put an agent on it in one step"),
175 a("assign", Op::AssignIssue, "Put an agent on an existing issue"),
176 a("message", Op::MessageAgent, "Tell the agent on a pull request something, or ask another agent"),
177 a("answer", Op::AnswerMessage, "Answer a question or handoff sent to you"),
178 a("take_messages", Op::TakeMessages, "For a g1t agent: messages not seen yet"),
179 ],
180 },
181 Tool {
182 name: "plan",
183 title: "Plans",
Fast pages, required checks on the branch, self-hosted runners, honest incidents184 description: "Turn an outcome into issues: an agent proposes them with what done means and their dependencies; nothing opens until you apply the plan.",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step185 default_action: None,
186 actions: &[
187 a("create", Op::PlanWork, "Ask an agent for a plan; read it with get until ready"),
188 a("get", Op::GetPlan, "A plan and the issues it proposes"),
189 a("apply", Op::ApplyPlan, "Open its issues; with assign, agents start in dependency order"),
190 ],
191 },
192 Tool {
193 name: "memory",
194 title: "Memory",
195 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.",
196 default_action: None,
197 actions: &[
198 a("recall", Op::Recall, "Search memory, or list it all"),
199 a("remember", Op::Remember, "Save one fact"),
200 ],
201 },
202 Tool {
203 name: "workflow",
204 title: "Workflows",
Merge main into the run-protection branch205 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 and repository dispatch. 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`), their groups, and where agent work runs.",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step206 default_action: None,
207 actions: &[
208 a("list", Op::ListWorkflows, "Workflows on the default branch"),
209 a("list_runs", Op::ListWorkflowRuns, "Runs, newest first"),
210 a("get_run", Op::GetWorkflowRun, "One run with its jobs and steps"),
211 a("job_logs", Op::GetJobLogs, "A job's log after a sequence number"),
212 a("dispatch", Op::DispatchWorkflow, "Run a workflow_dispatch workflow"),
213 a("cancel", Op::CancelWorkflowRun, "Cancel a run"),
214 a("rerun", Op::RerunWorkflowRun, "Run a finished run again"),
215 a("update", Op::UpdateWorkflow, "Turn a workflow on or off"),
Merge main into the run-protection branch216 a("list_artifacts", Op::Artifacts(ArtifactsOp::ListArtifacts), "A repository's artifacts, newest first; or a run's with run_artifacts"),
217 a("run_artifacts", Op::Artifacts(ArtifactsOp::ListRunArtifacts), "One run's artifacts"),
218 a("get_artifact", Op::Artifacts(ArtifactsOp::GetArtifact), "One artifact: size, digest, expiry, run"),
219 a("download_artifact", Op::Artifacts(ArtifactsOp::DownloadArtifact), "A 10-minute link to an artifact's zip"),
220 a("delete_artifact", Op::Artifacts(ArtifactsOp::DeleteArtifact), "Delete an artifact before it expires"),
221 a("artifact_retention", Op::Artifacts(ArtifactsOp::GetArtifactRetention), "Days the repository keeps artifacts"),
222 a("set_artifact_retention", Op::Artifacts(ArtifactsOp::SetArtifactRetention), "Change the days the repository keeps artifacts"),
Merge checks: statuses and check runs on every commit223 a("combined_status", Op::Checks(ChecksOp::GetCombinedStatus), "A commit's statuses and the state they add up to"),
224 a("list_statuses", Op::Checks(ChecksOp::ListCommitStatuses), "A commit's statuses, newest first"),
225 a("set_status", Op::Checks(ChecksOp::CreateCommitStatus), "Set a status on a commit"),
226 a("list_check_runs", Op::Checks(ChecksOp::ListCheckRunsForRef), "A commit's check runs, g1t Actions jobs included"),
227 a("get_check_run", Op::Checks(ChecksOp::GetCheckRun), "One check run with its report"),
228 a("check_run_annotations", Op::Checks(ChecksOp::ListCheckRunAnnotations), "What a check run says about lines of files"),
229 a("create_check_run", Op::Checks(ChecksOp::CreateCheckRun), "Report a check run on a commit"),
230 a("update_check_run", Op::Checks(ChecksOp::UpdateCheckRun), "Move a check run on, complete it, add annotations"),
231 a("rerequest_check_run", Op::Checks(ChecksOp::RerequestCheckRun), "Ask for a check run to run again"),
232 a("list_check_suites", Op::Checks(ChecksOp::ListCheckSuitesForRef), "A commit's check suites, one per reporter or workflow run"),
233 a("get_check_suite", Op::Checks(ChecksOp::GetCheckSuite), "One check suite"),
234 a("rerequest_check_suite", Op::Checks(ChecksOp::RerequestCheckSuite), "Ask for a check suite to run again"),
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97235 a("list_deployments", Op::Deployments(DeploymentsOp::ListDeployments), "Deployments wherever they run, newest first, filtered"),
236 a("get_deployment", Op::Deployments(DeploymentsOp::GetDeployment), "One deployment with every status it has had"),
237 a("create_deployment", Op::Deployments(DeploymentsOp::CreateDeployment), "Report a deployment of a ref to an environment"),
238 a("deployment_statuses", Op::Deployments(DeploymentsOp::ListDeploymentStatuses), "A deployment's statuses, newest first"),
239 a("create_deployment_status", Op::Deployments(DeploymentsOp::CreateDeploymentStatus), "Report where a deployment is: in_progress, success, failure"),
240 a("list_environments", Op::Deployments(DeploymentsOp::ListEnvironments), "Environments with their current and latest deployments"),
Actions: keep workflow runs safe241 a("get_environment", Op::Deployments(DeploymentsOp::GetEnvironment), "One environment by name, with its protection rules"),
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("repository_dispatch", Op::Protection(ProtectionOp::CreateRepositoryDispatch), "Start repository_dispatch workflows with an event"),
Merge main into the run-protection branch252 a("get_workspace_permissions", Op::Protection(ProtectionOp::GetWorkspaceWorkflowPermissions), "A workspace's default and maximum token permissions"),
253 a("set_workspace_permissions", Op::Protection(ProtectionOp::SetWorkspaceWorkflowPermissions), "Set them, and whether jobs may open pull requests"),
Fast pages, required checks on the branch, self-hosted runners, honest incidents254 a("list_runners", Op::ListRunners, "Self-hosted runners, with status, labels and what each is doing"),
255 a("create_runner_token", Op::CreateRunnerRegistrationToken, "A one-hour token for g1t-runner register"),
256 a("remove_runner", Op::RemoveRunner, "Remove a self-hosted runner"),
257 a("list_runner_groups", Op::ListRunnerGroups, "A workspace's runner groups"),
258 a("create_runner_group", Op::CreateRunnerGroup, "Make a group, for some repositories"),
259 a("update_runner_group", Op::UpdateRunnerGroup, "Rename a group or change its repositories"),
260 a("delete_runner_group", Op::DeleteRunnerGroup, "Delete a group; its runners join the default"),
261 a("get_runner_settings", Op::GetRunnerSettings, "Where agent work runs; whether forks may use runners"),
262 a("update_runner_settings", Op::UpdateRunnerSettings, "Change them"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step263 ],
264 },
265 Tool {
266 name: "secret",
267 title: "Secrets and variables",
268 description: "A repository's or workspace's secrets and variables, read by workflows and deployments. Secret values are never returned.",
269 default_action: None,
270 actions: &[
271 a("list_secrets", Op::ListActionsSecrets, "Secrets, without values"),
272 a("set_secret", Op::SetActionsSecret, "Add or change a secret"),
273 a("delete_secret", Op::DeleteActionsSecret, "Remove a secret"),
274 a("list_variables", Op::ListActionsVariables, "Variables, with values"),
275 a("set_variable", Op::SetActionsVariable, "Add or change a variable"),
276 a("delete_variable", Op::DeleteActionsVariable, "Remove a variable"),
277 ],
278 },
279 Tool {
280 name: "webhook",
281 title: "Webhooks",
282 description: "HTTPS addresses sent signed events as they happen, for a repository or a whole workspace.",
283 default_action: None,
284 actions: &[
285 a("list", Op::ListWebhooks, "Webhooks, without secrets"),
286 a("create", Op::CreateWebhook, "Register one; a ping is sent"),
287 a("update", Op::UpdateWebhook, "Change address, events or active"),
288 a("delete", Op::DeleteWebhook, "Remove one"),
289 a("ping", Op::PingWebhook, "Send a ping"),
290 a("list_deliveries", Op::ListWebhookDeliveries, "Latest deliveries"),
291 a("redeliver", Op::RedeliverWebhook, "Send a delivery again"),
292 ],
293 },
294 Tool {
295 name: "access",
296 title: "Who has access",
297 description: "Who has access to a repository and with which role (read, triage, write, maintain, admin), outside collaborators, and a workspace's base permission.",
298 default_action: None,
299 actions: &[
300 a("list_collaborators", Op::ListCollaborators, "Everyone with a role, and pending invitations"),
301 a("get_permission", Op::GetCollaboratorPermission, "One person's role and capabilities"),
302 a("add_collaborator", Op::AddCollaborator, "Give someone a role, by username or email"),
303 a("update_collaborator", Op::UpdateCollaborator, "Change a direct role"),
304 a("remove_collaborator", Op::RemoveCollaborator, "Take away a direct role"),
305 a("list_invitations", Op::ListRepoInvitations, "Pending invitations to a repository"),
306 a("revoke_invitation", Op::RevokeRepoInvitation, "Withdraw one"),
307 a("set_base_permission", Op::SetBasePermission, "What every member gets on each repository"),
308 a("list_outside_collaborators", Op::ListOutsideCollaborators, "People with roles who are not members"),
309 ],
310 },
311 Tool {
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar312 name: "team",
313 title: "Teams",
314 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.",
315 default_action: None,
316 actions: &[
317 a("list", Op::ListTeams, "A workspace's teams you can see"),
318 a("get", Op::GetTeam, "One team"),
319 a("create", Op::CreateTeam, "Create a team; you become its maintainer"),
320 a("update", Op::UpdateTeam, "Change its name, slug, description, visibility, parent or notifications"),
321 a("delete", Op::DeleteTeam, "Delete it; its child teams move up"),
322 a("list_members", Op::ListTeamMembers, "Its people and their roles, child teams' with include_child_teams"),
323 a("set_member", Op::SetTeamMember, "Add a member of the workspace, or change their role"),
324 a("remove_member", Op::RemoveTeamMember, "Take someone out of it"),
325 a("list_child_teams", Op::ListChildTeams, "The teams nested under it"),
326 a("list_repos", Op::ListTeamRepos, "The repositories it has a role on"),
327 a("set_repo", Op::SetTeamRepo, "Give it a role on a repository"),
328 a("remove_repo", Op::RemoveTeamRepo, "Take its role on a repository away"),
329 a("set_review_assignment", Op::SetTeamReviewAssignment, "Whom it picks when asked to review"),
330 a("list_user_teams", Op::ListUserTeams, "The teams someone is in"),
331 ],
332 },
333 Tool {
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step334 name: "workspace",
335 title: "Workspaces",
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97336 description: "Workspaces own repositories (g1t.sh/{workspace}/{repo}): create, update or delete one, invite members, connect integrations and model providers, 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.",
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step337 default_action: None,
338 actions: &[
Merge branch 'worktree-agent-ad7c6d88d93adc817'339 a("get", Op::GetWorkspace, "A workspace's details and settings"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step340 a("create", Op::CreateWorkspace, "Create a workspace"),
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member341 a("delete", Op::DeleteWorkspace, "Delete a workspace and everything in it (support can restore it for 30 days)"),
Merge branch 'worktree-agent-ad7c6d88d93adc817'342 a("update", Op::UpdateWorkspace, "Change its name, description, base permission or who may create teams"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step343 a("list_invites", Op::ListWorkspaceInvites, "Its invites"),
344 a("invite_member", Op::InviteMember, "Invite an email address"),
345 a("revoke_invite", Op::RevokeWorkspaceInvite, "Revoke a pending invite"),
346 a("list_integrations", Op::ListIntegrations, "Model providers, alert sources, trackers"),
347 a("connect_integration", Op::ConnectIntegration, "Connect one"),
AI Gateway: OpenAI's format, open models, and your own providers348 a("update_integration", Op::UpdateIntegration, "Change one: rotate its key, choose its AI Gateway models"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step349 a("disconnect_integration", Op::DisconnectIntegration, "Remove one"),
350 a("test_integration", Op::TestIntegration, "Check its credentials"),
351 a("get_model_routes", Op::GetModelRoutes, "Where each kind of work's model requests go"),
352 a("set_model_routes", Op::SetModelRoutes, "Replace them"),
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb97353 a("list_projects", Op::ListProjects, "Its projects you can see: what each is, where it runs, its links"),
354 a("get_project", Op::GetProject, "One project"),
355 a("update_project", Op::UpdateProject, "Change a project's name, description, kind, where it runs or its links"),
API: pinned projects over REST and MCP356 a("list_pinned_projects", Op::ListPinnedProjects, "Your pinned projects in it, in your order"),
357 a("pin_project", Op::PinProject, "Pin a project, at a position or the end"),
358 a("unpin_project", Op::UnpinProject, "Unpin a project"),
359 a("reorder_pinned_projects", Op::ReorderPinnedProjects, "Put your pins in a new order"),
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge360 a("list_rulesets", Op::Rules(RulesOp::ListWorkspaceRulesets), "Its rulesets, which hold across its repositories"),
361 a("get_ruleset", Op::Rules(RulesOp::GetWorkspaceRuleset), "One of its rulesets"),
362 a("create_ruleset", Op::Rules(RulesOp::CreateWorkspaceRuleset), "Create a ruleset for some or all of its repositories"),
363 a("update_ruleset", Op::Rules(RulesOp::UpdateWorkspaceRuleset), "Change one of its rulesets"),
364 a("delete_ruleset", Op::Rules(RulesOp::DeleteWorkspaceRuleset), "Delete one of its rulesets"),
365 a("rule_evaluations", Op::Rules(RulesOp::ListWorkspaceRuleEvaluations), "How rules judged changes across its repositories"),
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step366 ],
367 },
368 Tool {
Usage, Billing settings and prepaid AI credit; fixes from the UX audit369 name: "billing",
370 title: "Billing",
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens371 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), its AI credit, its invoices, and its AI Gateway requests. Amounts are whole millionths of a dollar (`_micros`), or cents (`_cents`) where named. Members read it; changing the budget and buying credit are for owners, as people, and never for g1t's agents.",
Usage, Billing settings and prepaid AI credit; fixes from the UX audit372 default_action: Some("usage"),
373 actions: &[
374 a("usage", Op::GetUsage, "Usage over a range of days, by product, meter, project and day, and what paid for it"),
375 a("budget", Op::GetBudget, "The monthly spend limit, what was spent, alerts and whether usage pauses at the limit"),
376 a("set_budget", Op::SetBudget, "Change the spend limit, alerts, pausing or the alert webhook"),
377 a("ai_credit", Op::GetAiCredit, "AI credit left, its grants, auto-reload and how to buy more"),
378 a("buy_ai_credit", Op::BuyAiCredit, "A payment page to buy AI credit, for a person to open"),
379 a("invoices", Op::ListInvoices, "Every invoice, the itemised usage invoices, and the next one so far"),
380 a("billing_details", Op::GetBillingDetails, "Who invoices are made out to and the payment method on file"),
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens381 a("gateway_requests", Op::ListGatewayRequests, "Recent AI Gateway requests: model, tokens, cost, status and token"),
Usage, Billing settings and prepaid AI credit; fixes from the UX audit382 ],
383 },
384 Tool {
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar385 name: "security",
386 title: "Security",
387 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, and a workspace's overview. Fix an alert with g1t. Findings are shown to those who can change the code only. Give `repo` (owner/name), or `workspace` for lists across one.",
388 default_action: Some("secret_alerts"),
389 actions: &[
390 a("secret_alerts", Op::Security(SecurityOp::ListSecretAlerts), "Secret scanning alerts; by state, secret_type, validity, bypassed"),
391 a("secret_alert", Op::Security(SecurityOp::GetSecretAlert), "One secret alert, with where it was found and its bypass requests"),
392 a("update_secret_alert", Op::Security(SecurityOp::UpdateSecretAlert), "Dismiss a secret alert with a reason, or reopen it"),
393 a("secret_locations", Op::Security(SecurityOp::ListSecretLocations), "Every file, line and commit a secret is in"),
394 a("bypass", Op::Security(SecurityOp::BypassPushProtection), "Push past push protection with a reason, or ask to"),
395 a("check_validity", Op::Security(SecurityOp::CheckSecretValidity), "Ask a secret's issuer whether it still works"),
396 a("bypass_requests", Op::Security(SecurityOp::ListBypassRequests), "A workspace's push protection bypass requests"),
397 a("review_bypass", Op::Security(SecurityOp::ReviewBypassRequest), "Approve, deny or cancel a bypass request"),
398 a("patterns", Op::Security(SecurityOp::ListCustomPatterns), "Custom secret patterns of a repository or workspace"),
399 a("create_pattern", Op::Security(SecurityOp::CreateCustomPattern), "Create a custom secret pattern, as a draft or published"),
400 a("update_pattern", Op::Security(SecurityOp::UpdateCustomPattern), "Change, publish or unpublish a custom pattern"),
401 a("delete_pattern", Op::Security(SecurityOp::DeleteCustomPattern), "Delete a custom pattern"),
402 a("dry_run_pattern", Op::Security(SecurityOp::DryRunCustomPattern), "Run a pattern over the default branch without saving it"),
403 a("code_alerts", Op::Security(SecurityOp::ListCodeAlerts), "Code scanning alerts; by state, severity, tool, rule_id"),
404 a("code_alert", Op::Security(SecurityOp::GetCodeAlert), "One code scanning alert by number"),
405 a("update_code_alert", Op::Security(SecurityOp::UpdateCodeAlert), "Dismiss a code scanning alert with a reason, or reopen it"),
406 a("analyses", Op::Security(SecurityOp::ListAnalyses), "Code scanning analyses, newest first"),
407 a("upload_sarif", Op::Security(SecurityOp::UploadSarif), "Upload a SARIF file, gzipped and base64-encoded"),
408 a("sarif_upload", Op::Security(SecurityOp::GetSarifUpload), "Whether a SARIF upload was read, and its analyses"),
409 a("vulnerability_alerts", Op::Security(SecurityOp::ListVulnerabilityAlerts), "Vulnerable dependencies; by state, severity, ecosystem, package"),
410 a("vulnerability_alert", Op::Security(SecurityOp::GetVulnerabilityAlert), "One vulnerability alert"),
411 a("update_vulnerability_alert", Op::Security(SecurityOp::UpdateVulnerabilityAlert), "Dismiss a vulnerability alert with a reason, or reopen it"),
412 a("fix", Op::Security(SecurityOp::FixAlert), "Put g1t on an issue to fix an alert"),
413 a("dependency_graph", Op::Security(SecurityOp::GetDependencyGraph), "Every package the lockfiles resolve, direct or transitive"),
414 a("sbom", Op::Security(SecurityOp::GetSbom), "The dependency graph as an SPDX 2.3 document"),
415 a("compare_dependencies", Op::Security(SecurityOp::CompareDependencies), "What changes in dependencies between base...head"),
416 a("settings", Op::Security(SecurityOp::GetSettings), "A repository's security settings"),
417 a("update_settings", Op::Security(SecurityOp::UpdateSettings), "Change when checks fail and dependency review's policy"),
418 a("workspace_settings", Op::Security(SecurityOp::GetWorkspaceSettings), "A workspace's delegated bypass and validity checks"),
419 a("update_workspace_settings", Op::Security(SecurityOp::UpdateWorkspaceSettings), "Turn delegated bypass or validity checks on or off"),
420 a("overview", Op::Security(SecurityOp::GetOverview), "A workspace's alerts, trends and coverage"),
421 ],
422 },
423 Tool {
API: notifications over REST and MCP, with notifications scopes424 name: "notifications",
425 title: "Notifications",
426 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`): an agent waiting on you, 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.",
427 default_action: Some("list"),
428 actions: &[
429 a("list", Op::ListNotifications, "Unread threads, latest first; all, a view, a reason, a repository"),
430 a("get", Op::GetNotificationThread, "One thread with its recent activity and your subscription"),
431 a("mark_read", Op::MarkThreadRead, "Mark a thread read, or unread"),
432 a("mark_all_read", Op::MarkNotificationsRead, "Mark everything read up to a time, or one repository's"),
433 a("done", Op::MarkThreadDone, "Mark a thread done; new activity brings it back"),
434 a("save", Op::SaveThread, "Save a thread, or unsave it"),
435 a("snooze", Op::SnoozeThread, "Snooze a thread until a time, or bring it back"),
436 a("subscription", Op::GetThreadSubscription, "Your subscription to an issue or pull request"),
437 a("subscribe", Op::SetThreadSubscription, "Subscribe to an issue or pull request, or ignore it"),
438 a("unsubscribe", Op::DeleteThreadSubscription, "Unsubscribe until you comment or are mentioned"),
439 a("watching", Op::GetRepoSubscription, "How you watch a repository"),
440 a("watch", Op::SetRepoSubscription, "Watch a repository: participating, all, ignore or custom"),
441 a("unwatch", Op::DeleteRepoSubscription, "Stop watching a repository"),
442 a("watched", Op::ListWatchedRepos, "Repositories you watch other than the default way"),
443 ],
444 },
445 Tool {
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step446 name: "account",
447 title: "Your account",
448 description: "Who this token acts as and its workspaces (`whoami`), your email addresses, your invites, and invitations to repositories waiting for you.",
449 default_action: Some("whoami"),
450 actions: &[
451 a("whoami", Op::Whoami, "Who the token acts as, and its workspaces"),
452 a("list_emails", Op::ListEmails, "Your addresses"),
453 a("add_email", Op::AddEmail, "Add an address"),
454 a("remove_email", Op::RemoveEmail, "Remove an address"),
455 a("update_email_settings", Op::UpdateEmailSettings, "Primary, backup and privacy"),
456 a("list_invites", Op::ListInvites, "Your invites to g1t"),
457 a("create_invite", Op::CreateInvite, "Make an invite"),
458 a("revoke_invite", Op::RevokeInvite, "Revoke one"),
459 a("list_repository_invitations", Op::ListMyRepoInvitations, "Invitations to repositories for you"),
460 a("accept_repository_invitation", Op::AcceptRepoInvitation, "Accept one"),
461 a("decline_repository_invitation", Op::DeclineRepoInvitation, "Decline one"),
462 ],
463 },
464];
465
466/// Operations that cannot be undone, or reach beyond g1t's own records:
467/// clients ask before running a tool that has any of them.
468fn destructive(op: Op) -> bool {
469 matches!(
470 op,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar471 Op::Security(SecurityOp::DeleteCustomPattern | SecurityOp::BypassPushProtection)
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge472 | Op::Rules(RulesOp::DeleteRepoRuleset | RulesOp::DeleteWorkspaceRuleset)
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar473 | Op::DeleteWorkspace
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily474 | Op::UpdateWorkspace
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step475 | Op::DeleteRepo
476 | Op::PurgeRepo
477 | Op::TransferRepo
478 | Op::SetRepoVisibility
479 | Op::RemoveEmail
480 | Op::RemoveCollaborator
481 | Op::DisconnectIntegration
AI Gateway: OpenAI's format, open models, and your own providers482 | Op::UpdateIntegration
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step483 | Op::DeleteWebhook
484 | Op::DeleteActionsSecret
485 | Op::DeleteActionsVariable
486 | Op::SetActionsSecret
487 | Op::SetActionsVariable
488 | Op::SetModelRoutes
489 | Op::SetBasePermission
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar490 | Op::DeleteTeam
491 | Op::RemoveTeamRepo
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step492 | Op::MergePullRequest
Fast pages, required checks on the branch, self-hosted runners, honest incidents493 | Op::RemoveRunner
494 | Op::DeleteRunnerGroup
495 | Op::UpdateRunnerSettings
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step496 )
497}
498
499/// Whether an operation only reads.
500pub fn reads_only(op: Op) -> bool {
501 NO_SCOPE.contains(&op.name())
502 || scope_for(op.name()).is_some_and(|scope| scope.level() == Level::Read)
503}
504
505/// What decides which actions a caller sees.
506pub enum Gate<'a> {
507 /// No limit beyond the person's own role.
508 Everything,
509 /// A g1t agent's token: the operations its run lists.
510 Agent(&'a AgentScope),
511 /// An access token with scopes.
512 Token(&'a TokenAccess),
513}
514
515impl Gate<'_> {
516 pub fn allows(&self, op: Op) -> bool {
517 match self {
518 Gate::Everything => true,
519 Gate::Agent(scope) => op.allowed_by(scope) && !NEVER.contains(&op.name()),
520 Gate::Token(access) => {
521 if NO_SCOPE.contains(&op.name()) {
522 return true;
523 }
524 match scope_for(op.name()) {
525 Some(scope) => access.allows(scope),
526 None => access.scopes.is_none(),
527 }
528 }
529 }
530 }
531}
532
533impl Tool {
534 pub fn by_name(name: &str) -> Option<&'static Tool> {
535 TOOLS.iter().find(|tool| tool.name == name)
536 }
537
538 pub fn action(&self, name: &str) -> Option<&'static Action> {
539 // The tools are 'static; find through TOOLS to keep the lifetime.
540 TOOLS
541 .iter()
542 .find(|tool| tool.name == self.name)
543 .and_then(|tool| tool.actions.iter().find(|action| action.name == name))
544 }
545
546 pub fn visible(&self, gate: &Gate) -> Vec<&'static Action> {
547 TOOLS
548 .iter()
549 .find(|tool| tool.name == self.name)
550 .map(|tool| tool.actions.iter().filter(|action| gate.allows(action.op)).collect())
551 .unwrap_or_default()
552 }
553
554 /// The flat input schema of the actions given.
555 pub fn input_schema(&self, actions: &[&Action]) -> Value {
556 let mut properties = Map::new();
557 let lines: Vec<String> = actions
558 .iter()
559 .map(|action| {
560 let required: Vec<String> = action.op.required();
561 if required.is_empty() {
562 format!("{}: {}.", action.name, action.summary)
563 } else {
564 format!("{} ({}): {}.", action.name, required.join(", "), action.summary)
565 }
566 })
567 .collect();
568 let mut action_schema = json!({
569 "type": "string",
570 "enum": actions.iter().map(|action| action.name).collect::<Vec<_>>(),
571 "description": lines.join("\n"),
572 });
573 if let Some(default) = self.default_action.filter(|name| actions.iter().any(|action| action.name == *name)) {
574 action_schema["default"] = json!(default);
575 }
576 properties.insert("action".to_owned(), action_schema);
577 for action in actions {
578 for (name, schema) in action.op.properties() {
579 merge_property(&mut properties, name, schema);
580 }
581 }
582 let mut required = vec![];
583 if self.default_action.is_none() {
584 required.push("action");
585 }
586 let mut schema = json!({ "type": "object", "properties": properties });
587 if !required.is_empty() {
588 schema["required"] = json!(required);
589 }
590 schema
591 }
592
593 /// The input schema keyed by action: one `oneOf` branch per action,
594 /// each with its own fields and the ones it needs.
595 pub fn discriminated(&self, actions: &[&Action]) -> Value {
596 let branches: Vec<Value> = actions
597 .iter()
598 .map(|action| {
599 let mut properties = Map::new();
600 properties.insert("action".to_owned(), json!({ "const": action.name }));
601 properties.extend(action.op.properties());
602 let mut required = vec![Value::String("action".to_owned())];
603 // The default action may leave `action` out.
604 if self.default_action == Some(action.name) {
605 required.clear();
606 }
607 required.extend(action.op.required().into_iter().map(Value::String));
608 json!({
609 "title": action.name,
610 "description": action.summary,
611 "type": "object",
612 "properties": properties,
613 "required": required,
614 })
615 })
616 .collect();
617 json!({ "type": "object", "oneOf": branches })
618 }
619
620 /// MCP's hints about the actions given: whether the tool only reads,
621 /// whether it can destroy something, and whether calling it twice is
622 /// the same as once.
623 pub fn annotations(&self, actions: &[&Action]) -> Value {
624 let read_only = actions.iter().all(|action| reads_only(action.op));
625 json!({
626 "title": self.title,
627 "readOnlyHint": read_only,
628 "destructiveHint": !read_only && actions.iter().any(|action| destructive(action.op)),
629 "idempotentHint": read_only,
630 "openWorldHint": false,
631 })
632 }
633
634 /// The tool as `tools/list` gives it, for a caller behind `gate`, or
635 /// `None` when it may use none of its actions.
636 pub fn listed(&self, gate: &Gate) -> Option<Value> {
637 let actions = self.visible(gate);
638 if actions.is_empty() {
639 return None;
640 }
641 Some(json!({
642 "name": self.name,
643 "title": self.title,
644 "description": self.description,
645 "inputSchema": self.input_schema(&actions),
646 "annotations": self.annotations(&actions),
647 }))
648 }
649}
650
651/// Adds a property to a tool's flat schema. The first action to use a name
652/// describes it; a later one with other allowed values adds them.
653fn merge_property(properties: &mut Map<String, Value>, name: String, schema: Value) {
654 match properties.get_mut(&name) {
655 None => {
656 properties.insert(name, schema);
657 }
658 Some(existing) => {
659 if let (Some(Value::Array(had)), Some(Value::Array(more))) =
660 (existing.get("enum").cloned(), schema.get("enum"))
661 {
662 let mut merged = had;
663 for value in more {
664 if !merged.contains(value) {
665 merged.push(value.clone());
666 }
667 }
668 existing["enum"] = Value::Array(merged);
669 }
670 // Different kinds of value under one name: say less, accept both.
671 if existing.get("type") != schema.get("type")
672 && let Some(fields) = existing.as_object_mut()
673 {
674 fields.remove("type");
675 fields.remove("items");
676 }
677 }
678 }
679}
680
681/// What a call to a tool runs: the operation its action names, or why not.
682pub fn resolve(tool: &Tool, arguments: &Value) -> Result<Op, String> {
683 let names = || {
684 tool.actions
685 .iter()
686 .map(|action| action.name)
687 .collect::<Vec<_>>()
688 .join(", ")
689 };
690 let Some(name) = arguments["action"].as_str().or(tool.default_action) else {
691 return Err(format!("Give an action: one of {}.", names()));
692 };
693 let Some(action) = tool.action(name) else {
694 return Err(format!("{} has no action {name}. Its actions: {}.", tool.name, names()));
695 };
696 let missing: Vec<String> = action
697 .op
698 .required()
699 .into_iter()
700 .filter(|field| arguments.get(field).is_none_or(Value::is_null))
701 .collect();
702 if !missing.is_empty() {
703 return Err(format!("{}.{name} needs {}.", tool.name, missing.join(", ")));
704 }
705 Ok(action.op)
706}
707
708#[cfg(test)]
709mod tests {
710 use super::*;
711 use g1t_contracts::scopes::{Preset, Scope};
712
713 fn listed(gate: &Gate) -> Vec<Value> {
714 TOOLS.iter().filter_map(|tool| tool.listed(gate)).collect()
715 }
716
717 fn token(scopes: Option<Vec<Scope>>) -> TokenAccess {
718 TokenAccess {
719 token_id: "tok_1".to_owned(),
720 scopes: scopes.map(|scopes| scopes.iter().map(|scope| scope.as_str().to_owned()).collect()),
721 legacy: false,
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens722 name: None,
Actions: keep workflow runs safe723 ..TokenAccess::default()
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step724 }
725 }
726
727 #[test]
728 fn every_operation_is_exactly_one_action_of_one_tool() {
729 for op in Op::ALL {
730 let count = TOOLS
731 .iter()
732 .flat_map(|tool| tool.actions.iter())
733 .filter(|action| action.op == op)
734 .count();
735 assert_eq!(count, 1, "{} is {count} actions", op.name());
736 }
737 for tool in TOOLS {
738 let mut names = std::collections::HashSet::new();
739 for action in tool.actions {
740 assert!(names.insert(action.name), "{}.{} twice", tool.name, action.name);
741 }
742 if let Some(default) = tool.default_action {
743 assert!(tool.action(default).is_some(), "{}", tool.name);
744 }
745 }
Usage, Billing settings and prepaid AI credit; fixes from the UX audit746 assert!(TOOLS.len() <= 17, "{} tools", TOOLS.len());
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step747 }
748
749 #[test]
750 fn every_operation_needs_exactly_one_scope_or_none() {
751 use g1t_contracts::scopes::OPERATIONS;
752 for op in Op::ALL {
753 let mapped = OPERATIONS.iter().filter(|(name, _)| *name == op.name()).count();
754 let free = NO_SCOPE.contains(&op.name());
755 assert_eq!(mapped + usize::from(free), 1, "{}", op.name());
756 }
757 for (name, _) in OPERATIONS {
758 assert!(Op::by_name(name).is_some(), "{name} is not an operation");
759 }
760 }
761
762 #[test]
763 fn each_tool_schema_is_valid_with_one_branch_per_action() {
764 for tool in TOOLS {
765 let actions: Vec<&Action> = tool.actions.iter().collect();
766 let flat = tool.input_schema(&actions);
767 assert_eq!(flat["type"], "object");
768 assert!(flat.get("oneOf").is_none(), "no oneOf at the top level");
769 let listed: Vec<&str> = flat["properties"]["action"]["enum"]
770 .as_array()
771 .unwrap()
772 .iter()
773 .map(|name| name.as_str().unwrap())
774 .collect();
775 assert_eq!(listed, tool.actions.iter().map(|action| action.name).collect::<Vec<_>>());
776 for action in tool.actions {
777 for field in action.op.required() {
778 assert!(flat["properties"].get(&field).is_some(), "{}.{}: {field}", tool.name, action.name);
779 }
780 }
781 let keyed = tool.discriminated(&actions);
782 let branches = keyed["oneOf"].as_array().unwrap();
783 assert_eq!(branches.len(), tool.actions.len());
784 for (branch, action) in branches.iter().zip(tool.actions) {
785 assert_eq!(branch["properties"]["action"]["const"], action.name);
786 for field in branch["required"].as_array().unwrap() {
787 assert!(branch["properties"].get(field.as_str().unwrap()).is_some(), "{}.{}: {field}", tool.name, action.name);
788 }
789 }
790 // A well-formed JSON Schema object throughout.
791 let text = serde_json::to_string(&flat).unwrap();
792 assert!(serde_json::from_str::<Value>(&text).is_ok());
793 }
794 }
795
796 #[test]
797 fn a_read_only_token_sees_read_actions_only() {
798 let access = token(Preset::ReadOnly.scopes());
799 let gate = Gate::Token(&access);
800 for tool in TOOLS {
801 for action in tool.visible(&gate) {
802 assert!(reads_only(action.op), "{}.{}", tool.name, action.name);
803 }
804 }
805 let tools = listed(&gate);
806 for tool in &tools {
807 assert_eq!(tool["annotations"]["readOnlyHint"], true, "{}", tool["name"]);
808 assert_eq!(tool["annotations"]["destructiveHint"], false);
809 }
810 let issue = tools.iter().find(|tool| tool["name"] == "issue").unwrap();
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar811 assert_eq!(issue["inputSchema"]["properties"]["action"]["enum"], json!(["list", "get", "labels"]));
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step812 // Nothing of the agent tool is a read.
813 assert!(!tools.iter().any(|tool| tool["name"] == "agent"));
814 }
815
816 #[test]
817 fn a_narrow_token_sees_only_its_tools() {
818 let access = token(Some(vec![Scope::IssuesWrite]));
819 let names: Vec<Value> = listed(&Gate::Token(&access)).into_iter().map(|tool| tool["name"].clone()).collect();
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar820 // Labels and milestones are the repository's, managed with issues:write.
821 assert_eq!(names, vec![json!("repository"), json!("issue"), json!("plan"), json!("account")]);
API: notifications over REST and MCP, with notifications scopes822 // Notifications are a resource of their own: reading them lists
823 // only what reads.
824 let reader = token(Some(vec![Scope::NotificationsRead]));
825 let tools = listed(&Gate::Token(&reader));
826 let notifications = tools.iter().find(|tool| tool["name"] == "notifications").unwrap();
827 assert_eq!(
828 notifications["inputSchema"]["properties"]["action"]["enum"],
829 json!(["list", "get", "subscription", "watching", "watched"])
830 );
831 assert_eq!(notifications["annotations"]["readOnlyHint"], true);
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step832 let full = token(None);
833 assert_eq!(listed(&Gate::Token(&full)).len(), TOOLS.len());
834 assert_eq!(listed(&Gate::Everything).len(), TOOLS.len());
835 }
836
837 #[test]
838 fn a_tool_that_can_destroy_says_so() {
839 let tools = listed(&Gate::Everything);
840 let repository = tools.iter().find(|tool| tool["name"] == "repository").unwrap();
841 assert_eq!(repository["annotations"]["destructiveHint"], true);
842 assert_eq!(repository["annotations"]["readOnlyHint"], false);
843 let memory = tools.iter().find(|tool| tool["name"] == "memory").unwrap();
844 assert_eq!(memory["annotations"]["destructiveHint"], false);
845 }
846
847 #[test]
848 fn calls_resolve_to_their_operation_or_say_what_is_missing() {
849 let issue = Tool::by_name("issue").unwrap();
850 assert_eq!(resolve(issue, &json!({ "action": "get", "repo": "a/b", "number": 1 })), Ok(Op::GetIssue));
851 assert_eq!(resolve(issue, &json!({ "action": "get", "repo": "a/b" })), Err("issue.get needs number.".to_owned()));
852 assert!(resolve(issue, &json!({})).unwrap_err().starts_with("Give an action"));
853 assert!(resolve(issue, &json!({ "action": "explode" })).unwrap_err().contains("no action explode"));
854 let search = Tool::by_name("search").unwrap();
855 assert_eq!(resolve(search, &json!({ "query": "x" })), Ok(Op::Search));
856 let account = Tool::by_name("account").unwrap();
857 assert_eq!(resolve(account, &json!({})), Ok(Op::Whoami));
858 }
859
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar860 #[test]
861 fn teams_are_one_tool_and_a_workspace_reader_sees_only_its_reads() {
862 let team = Tool::by_name("team").unwrap();
863 let names: Vec<&str> = team.actions.iter().map(|action| action.name).collect();
864 assert_eq!(
865 names,
866 [
867 "list",
868 "get",
869 "create",
870 "update",
871 "delete",
872 "list_members",
873 "set_member",
874 "remove_member",
875 "list_child_teams",
876 "list_repos",
877 "set_repo",
878 "remove_repo",
879 "set_review_assignment",
880 "list_user_teams",
881 ]
882 );
883 let reader = token(Some(vec![Scope::WorkspaceRead]));
884 let tools = listed(&Gate::Token(&reader));
885 let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap();
886 assert_eq!(
887 listed_team["inputSchema"]["properties"]["action"]["enum"],
888 json!(["list", "get", "list_members", "list_child_teams", "list_repos", "list_user_teams"])
889 );
890 assert_eq!(listed_team["annotations"]["readOnlyHint"], true);
891 // A team's role on a repository is who has access.
892 let admin = token(Some(vec![Scope::WorkspaceAdmin]));
893 let tools = listed(&Gate::Token(&admin));
894 let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap();
895 let actions = listed_team["inputSchema"]["properties"]["action"]["enum"].as_array().unwrap();
896 assert!(actions.contains(&json!("set_review_assignment")) && !actions.contains(&json!("set_repo")));
897 let access = token(Some(vec![Scope::AccessAdmin]));
898 let tools = listed(&Gate::Token(&access));
899 let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap();
900 assert_eq!(listed_team["inputSchema"]["properties"]["action"]["enum"], json!(["set_repo", "remove_repo"]));
901 // Both kinds of role a schema names are offered.
902 let roles = &listed(&Gate::Everything).into_iter().find(|tool| tool["name"] == "team").unwrap()["inputSchema"]
903 ["properties"]["role"]["enum"];
904 for role in ["member", "maintainer", "read", "admin"] {
905 assert!(roles.as_array().unwrap().contains(&json!(role)), "{role}");
906 }
907 assert_eq!(
908 resolve(team, &json!({ "action": "set_repo", "workspace": "acme", "team": "backend", "repo": "rocket" })),
909 Err("team.set_repo needs role.".to_owned())
910 );
911 }
912
913 #[test]
914 fn reviewers_and_code_owners_are_actions_of_their_tools() {
915 let pull = Tool::by_name("pull_request").unwrap();
916 assert_eq!(
917 resolve(pull, &json!({ "action": "request_reviewers", "repo": "a/b", "number": 1, "team_reviewers": ["backend"] })),
918 Ok(Op::RequestReviewers)
919 );
920 assert_eq!(pull.action("remove_requested_reviewers").map(|action| action.op), Some(Op::RemoveRequestedReviewers));
921 let repository = Tool::by_name("repository").unwrap();
922 assert_eq!(resolve(repository, &json!({ "action": "codeowners", "repo": "a/b" })), Ok(Op::GetCodeownersErrors));
923 assert!(reads_only(Op::GetCodeownersErrors));
924 assert!(!reads_only(Op::RequestReviewers));
925 }
926
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step927 /// How much smaller `tools/list` is than one tool per operation. Run
928 /// with `--nocapture` to see the numbers.
929 #[test]
930 fn the_tool_list_is_much_smaller_than_one_tool_per_operation() {
931 let before: Vec<Value> = Op::ALL
932 .into_iter()
933 .map(|op| json!({ "name": op.name(), "description": op.description(), "inputSchema": op.input() }))
934 .collect();
935 let after = listed(&Gate::Everything);
936 let before_bytes = serde_json::to_string(&json!({ "tools": before })).unwrap().len();
937 let after_bytes = serde_json::to_string(&json!({ "tools": after })).unwrap().len();
938 let agent = token(Preset::Agent.scopes());
939 let agent_bytes = serde_json::to_string(&json!({ "tools": listed(&Gate::Token(&agent)) })).unwrap().len();
940 let read = token(Preset::ReadOnly.scopes());
941 let read_bytes = serde_json::to_string(&json!({ "tools": listed(&Gate::Token(&read)) })).unwrap().len();
942 println!(
943 "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)",
944 before.len(),
945 before_bytes / 4,
946 after.len(),
947 after_bytes / 4,
948 agent_bytes / 4,
949 read_bytes / 4,
950 );
951 assert!(after_bytes * 2 < before_bytes, "{after_bytes} vs {before_bytes}");
952 }
953}

This file's history is long; its oldest lines are credited to the oldest commit read.