Skip to content
Sign in

flagon-io/g1t

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

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