Skip to content
Sign up

flagon-io/g1t

public
00

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

g1t.sh
gitagentscloudflarerustforgemcp
1,171 linesCodeBlameRaw
1//! 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
21use crate::about::AboutOp;
22use crate::run_artifacts::ArtifactsOp;
23use crate::archives::ArchiveOp;
24use crate::customize::CustomizeOp;
25use crate::deploy_keys::DeployKeysOp;
26use crate::deployments::DeploymentsOp;
27use crate::telemetry::TelemetryOp;
28use crate::packages::PackagesOp;
29use crate::folios::FoliosOp;
30use crate::protection::ProtectionOp;
31use crate::token_policy::TokenOp;
32use crate::operations::Op;
33use crate::checks::ChecksOp;
34use crate::rules::RulesOp;
35use crate::security::SecurityOp;
36
37pub struct Action {
38 pub name: &'static str,
39 pub op: Op,
40 /// One line, for the `action` field's description.
41 pub summary: &'static str,
42}
43
44pub struct Tool {
45 pub name: &'static str,
46 pub title: &'static str,
47 /// What it is for, in a sentence or two.
48 pub description: &'static str,
49 pub actions: &'static [Action],
50 /// The action a call without one runs.
51 pub default_action: Option<&'static str>,
52}
53
54const fn a(name: &'static str, op: Op, summary: &'static str) -> Action {
55 Action { name, op, summary }
56}
57
58pub const TOOLS: &[Tool] = &[
59 Tool {
60 name: "search",
61 title: "Search",
62 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.",
63 default_action: Some("code"),
64 actions: &[
65 a("code", Op::Search, "Search all of g1t: repositories, code, issues, pull requests, people"),
66 a("context", Op::SearchContext, "Search a workspace's context hub by meaning"),
67 a("entity", Op::GetEntity, "One catalog entry and its relations"),
68 a("ticket", Op::GetContext, "A Jira, Linear or Sentry item the work refers to, as it is now"),
69 ],
70 },
71 Tool {
72 name: "repository",
73 title: "Repositories",
74 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`.",
75 default_action: None,
76 actions: &[
77 a("list", Op::ListRepos, "Repositories you can see"),
78 a("get", Op::GetRepo, "One repository"),
79 a("tarball", Op::Archives(ArchiveOp::DownloadTarball), "A 10-minute link to a branch, tag or commit as a .tar.gz"),
80 a("zipball", Op::Archives(ArchiveOp::DownloadZipball), "A 10-minute link to a branch, tag or commit as a .zip"),
81 a("create", Op::CreateRepo, "Create one, empty or copied from a public git URL"),
82 a("update", Op::UpdateRepo, "Change description, website, topics, default branch, protection"),
83 a("get_settings", Op::GetRepoSettings, "How pull requests merge, and the default branch's protection as its rules stack"),
84 a("update_settings", Op::UpdateRepoSettings, "Change how pull requests merge and the default branch protection ruleset"),
85 a("check_names", Op::ListCheckNames, "Check names reported lately, to require in a ruleset"),
86 a("list_rulesets", Op::Rules(RulesOp::ListRepoRulesets), "Its rulesets, and its workspace's that hold in it"),
87 a("get_ruleset", Op::Rules(RulesOp::GetRepoRuleset), "One ruleset"),
88 a("create_ruleset", Op::Rules(RulesOp::CreateRepoRuleset), "Create a ruleset for its branches or tags"),
89 a("update_ruleset", Op::Rules(RulesOp::UpdateRepoRuleset), "Change a ruleset"),
90 a("delete_ruleset", Op::Rules(RulesOp::DeleteRepoRuleset), "Delete a ruleset"),
91 a("branch_rules", Op::Rules(RulesOp::GetBranchRules), "Every rule that holds for a branch or tag, and where it comes from"),
92 a("rule_evaluations", Op::Rules(RulesOp::ListRuleEvaluations), "How its rules judged pushes and merges, with insights"),
93 a("codeowners", Op::GetCodeownersErrors, "Problems in its CODEOWNERS file, by line"),
94 a("list_labels", Op::ListLabels, "Labels, with colors and how many issues and pull requests carry each"),
95 a("create_label", Op::CreateLabel, "Create a label"),
96 a("update_label", Op::UpdateLabel, "Rename a label or change its color or description"),
97 a("delete_label", Op::DeleteLabel, "Delete a label, from everything that carries it"),
98 a("add_default_labels", Op::AddDefaultLabels, "Add the default labels it is missing"),
99 a("list_milestones", Op::ListMilestones, "Milestones, with progress and due dates"),
100 a("get_milestone", Op::GetMilestone, "One milestone with its issues and pull requests"),
101 a("create_milestone", Op::CreateMilestone, "Create a milestone"),
102 a("update_milestone", Op::UpdateMilestone, "Change a milestone's title, description, due date or state"),
103 a("delete_milestone", Op::DeleteMilestone, "Delete a milestone"),
104 a("list_events", Op::ListEvents, "Timeline: pushes, issues, pull requests, comments"),
105 a("languages", Op::About(AboutOp::GetLanguages), "Its languages by bytes, with colors and percentages"),
106 a("contributors", Op::About(AboutOp::ListContributors), "Who made it: commits per person, agent and author, by week"),
107 a("license", Op::About(AboutOp::GetLicense), "The license its LICENSE file holds"),
108 a("stargazers", Op::About(AboutOp::ListStargazers), "Who starred it"),
109 a("starred", Op::About(AboutOp::CheckStarred), "Whether you starred it, and how many have"),
110 a("star", Op::About(AboutOp::Star), "Star it"),
111 a("unstar", Op::About(AboutOp::Unstar), "Take your star back"),
112 a("list_starred", Op::About(AboutOp::ListStarred), "Repositories you starred"),
113 a("list_releases", Op::About(AboutOp::ListReleases), "Releases, newest first"),
114 a("latest_release", Op::About(AboutOp::GetLatestRelease), "The latest release"),
115 a("get_release", Op::About(AboutOp::GetRelease), "One release by id"),
116 a("get_release_by_tag", Op::About(AboutOp::GetReleaseByTag), "The release of a tag"),
117 a("create_release", Op::About(AboutOp::CreateRelease), "Publish a release of a tag, making the tag if needed"),
118 a("update_release", Op::About(AboutOp::UpdateRelease), "Change a release's title, notes, draft or prerelease"),
119 a("delete_release", Op::About(AboutOp::DeleteRelease), "Delete a release; its tag stays"),
120 a("rename_branch", Op::RenameBranch, "Rename a branch"),
121 a("create_branch", Op::CreateBranch, "Make a branch at a branch, tag or commit"),
122 a("delete_branch", Op::DeleteBranch, "Delete a branch; make it again at its commit to restore it"),
123 a("rename", Op::RenameRepo, "Rename it; old addresses redirect"),
124 a("transfer", Op::TransferRepo, "Move it to another workspace you own"),
125 a("archive", Op::ArchiveRepo, "Make it read-only"),
126 a("unarchive", Op::UnarchiveRepo, "Make it writable again"),
127 a("set_visibility", Op::SetRepoVisibility, "Make it public or private"),
128 a("delete", Op::DeleteRepo, "Delete it; restorable for 30 days"),
129 a("list_deleted", Op::ListDeletedRepos, "A workspace's deleted repositories"),
130 a("restore", Op::RestoreRepo, "Restore a deleted one"),
131 a("purge", Op::PurgeRepo, "Remove a deleted one for good"),
132 a("security_alerts", Op::ListSecurityAlerts, "Secret and dependency alerts, filtered by state"),
133 a("dismiss_alert", Op::DismissSecurityAlert, "Dismiss an alert with a reason"),
134 a("reopen_alert", Op::ReopenSecurityAlert, "Reopen a dismissed alert"),
135 ],
136 },
137 Tool {
138 name: "issue",
139 title: "Issues",
140 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.",
141 default_action: None,
142 actions: &[
143 a("list", Op::ListIssues, "Issues on a repository, newest first"),
144 a("get", Op::GetIssue, "One issue with comments and its pull requests"),
145 a("create", Op::CreateIssue, "Open an issue"),
146 a("update", Op::UpdateIssue, "Change title, body, labels, milestone or assignees"),
147 a("labels", Op::ListIssueLabels, "The labels an issue or pull request carries"),
148 a("add_labels", Op::AddIssueLabels, "Add labels to an issue or pull request"),
149 a("set_labels", Op::SetIssueLabels, "Replace the labels of an issue or pull request"),
150 a("remove_labels", Op::RemoveIssueLabels, "Take labels off an issue or pull request"),
151 a("close", Op::CloseIssue, "Close it without a pull request"),
152 a("reopen", Op::ReopenIssue, "Reopen it"),
153 a("comment", Op::AddComment, "Comment on an issue or pull request; path and line for one line of a change"),
154 a("edit_comment", Op::EditComment, "Change a comment's text: your own, or any with the Maintain role"),
155 a("delete_comment", Op::DeleteComment, "Delete a comment: your own, or any with the Maintain role"),
156 a("import", Op::ImportIssue, "Open an issue from a Jira, Linear or Sentry item"),
157 ],
158 },
159 Tool {
160 name: "pull_request",
161 title: "Pull requests",
162 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.",
163 default_action: None,
164 actions: &[
165 a("list", Op::ListPullRequests, "Pull requests on a repository, newest first"),
166 a("get", Op::GetPullRequest, "Status, checks and required checks, reviews, overlaps, whether it is behind"),
167 a("changes", Op::GetPullRequestChanges, "Files and line-by-line diff"),
168 a("create", Op::CreatePullRequest, "Start a draft with its own fork to push to, or open one from a pushed branch"),
169 a("update", Op::UpdatePullRequest, "Change its base branch, labels, milestone, assignees or reviewers"),
170 a("record_session", Op::RecordSession, "Append prompt, reasoning and tool entries to its session"),
171 a("read_session", Op::ReadSession, "Its recorded session"),
172 a("ready", Op::MarkPullRequestReady, "Mark a draft ready, with a summary"),
173 a("draft", Op::ConvertPullRequestToDraft, "Turn it back into a draft"),
174 a("request_reviewers", Op::RequestReviewers, "Ask people or teams to review it"),
175 a("remove_requested_reviewers", Op::RemoveRequestedReviewers, "Stop asking people or teams to review it"),
176 a("review", Op::ReviewPullRequest, "Approve or request changes"),
177 a("close", Op::ClosePullRequest, "Close without merging"),
178 a("reopen", Op::ReopenPullRequest, "Reopen a closed one"),
179 a("merge", Op::MergePullRequest, "Land it, or join the merge queue"),
180 a("merge_queue", Op::GetMergeQueue, "The repository's merge queue"),
181 ],
182 },
183 Tool {
184 name: "agent",
185 title: "g1t agents",
186 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.",
187 default_action: None,
188 actions: &[
189 a("delegate", Op::Delegate, "Open an issue and put an agent on it in one step"),
190 a("assign", Op::AssignIssue, "Put an agent on an existing issue"),
191 a("message", Op::MessageAgent, "Tell the agent on a pull request something, or ask another agent"),
192 a("answer", Op::AnswerMessage, "Answer a question or handoff sent to you"),
193 a("take_messages", Op::TakeMessages, "For a g1t agent: messages not seen yet"),
194 a("computer", Op::GetAgentComputer, "A workspace agent's own computer: state, disk, recent commands"),
195 a("wake_computer", Op::WakeAgentComputer, "Wake a workspace agent's computer (metered until it sleeps)"),
196 a("sleep_computer", Op::SleepAgentComputer, "Save its home and put it to sleep"),
197 a("reset_computer", Op::ResetAgentComputer, "Wipe its home; memory and artifacts are kept"),
198 a("computer_commands", Op::ListAgentComputerCommands, "The commands it ran most recently, with output"),
199 ],
200 },
201 Tool {
202 name: "plan",
203 title: "Plans",
204 description: "Turn an outcome into issues: an agent proposes them with what done means and their dependencies; nothing opens until you apply the plan.",
205 default_action: None,
206 actions: &[
207 a("create", Op::PlanWork, "Ask an agent for a plan; read it with get until ready"),
208 a("get", Op::GetPlan, "A plan and the issues it proposes"),
209 a("apply", Op::ApplyPlan, "Open its issues; with assign, agents start in dependency order"),
210 ],
211 },
212 Tool {
213 name: "memory",
214 title: "Memory",
215 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.",
216 default_action: None,
217 actions: &[
218 a("recall", Op::Recall, "Search memory, or list it all"),
219 a("remember", Op::Remember, "Save one fact"),
220 ],
221 },
222 Tool {
223 name: "workflow",
224 title: "Workflows",
225 description: "GitHub Actions workflows from .g1t/workflows: their runs, jobs and logs, and running, cancelling or rerunning them. Runs' artifacts: listing, a download link, deleting, and how long they are kept. Deployments wherever they run (reported from any CI, made by jobs with an `environment:`, or built on g1t.page), their statuses and environments, and reporting your own; environments' protection rules, approving or rejecting the jobs they hold, approving a pull request's run from outside, the token's default permissions, repository dispatch, and the workflows a workspace runs in its repositories without a file in them. Checks on commits: statuses, check runs (a g1t Actions job is one) and check suites, to read where a commit stands or report on it from CI or an integration. Also the self-hosted runners they run on: a workspace's (`workspace`) or a repository's own (`repo`), their groups, and where agent work runs.",
226 default_action: None,
227 actions: &[
228 a("list", Op::ListWorkflows, "Workflows on the default branch"),
229 a("list_runs", Op::ListWorkflowRuns, "Runs, newest first"),
230 a("get_run", Op::GetWorkflowRun, "One run with its jobs and steps; an earlier attempt with attempt"),
231 a("job_logs", Op::GetJobLogs, "A job's log after a sequence number"),
232 a("dispatch", Op::DispatchWorkflow, "Run a workflow_dispatch workflow"),
233 a("cancel", Op::CancelWorkflowRun, "Cancel a run, letting its jobs clean up; force stops them outright"),
234 a("rerun", Op::RerunWorkflowRun, "Run a finished run again: all, failed_only, or one job; debug for debug logging"),
235 a("update", Op::UpdateWorkflow, "Turn a workflow on or off"),
236 a("list_artifacts", Op::Artifacts(ArtifactsOp::ListArtifacts), "A repository's artifacts, newest first; or a run's with run_artifacts"),
237 a("run_artifacts", Op::Artifacts(ArtifactsOp::ListRunArtifacts), "One run's artifacts"),
238 a("get_artifact", Op::Artifacts(ArtifactsOp::GetArtifact), "One artifact: size, digest, expiry, run"),
239 a("download_artifact", Op::Artifacts(ArtifactsOp::DownloadArtifact), "A 10-minute link to an artifact's zip"),
240 a("delete_artifact", Op::Artifacts(ArtifactsOp::DeleteArtifact), "Delete an artifact before it expires"),
241 a("artifact_retention", Op::Artifacts(ArtifactsOp::GetArtifactRetention), "Days the repository keeps artifacts"),
242 a("set_artifact_retention", Op::Artifacts(ArtifactsOp::SetArtifactRetention), "Change the days the repository keeps artifacts"),
243 a("combined_status", Op::Checks(ChecksOp::GetCombinedStatus), "A commit's statuses and the state they add up to"),
244 a("list_statuses", Op::Checks(ChecksOp::ListCommitStatuses), "A commit's statuses, newest first"),
245 a("set_status", Op::Checks(ChecksOp::CreateCommitStatus), "Set a status on a commit"),
246 a("list_check_runs", Op::Checks(ChecksOp::ListCheckRunsForRef), "A commit's check runs, g1t Actions jobs included"),
247 a("get_check_run", Op::Checks(ChecksOp::GetCheckRun), "One check run with its report"),
248 a("check_run_annotations", Op::Checks(ChecksOp::ListCheckRunAnnotations), "What a check run says about lines of files"),
249 a("create_check_run", Op::Checks(ChecksOp::CreateCheckRun), "Report a check run on a commit"),
250 a("update_check_run", Op::Checks(ChecksOp::UpdateCheckRun), "Move a check run on, complete it, add annotations"),
251 a("rerequest_check_run", Op::Checks(ChecksOp::RerequestCheckRun), "Ask for a check run to run again"),
252 a("list_check_suites", Op::Checks(ChecksOp::ListCheckSuitesForRef), "A commit's check suites, one per reporter or workflow run"),
253 a("get_check_suite", Op::Checks(ChecksOp::GetCheckSuite), "One check suite"),
254 a("rerequest_check_suite", Op::Checks(ChecksOp::RerequestCheckSuite), "Ask for a check suite to run again"),
255 a("list_deployments", Op::Deployments(DeploymentsOp::ListDeployments), "Deployments wherever they run, newest first, filtered"),
256 a("get_deployment", Op::Deployments(DeploymentsOp::GetDeployment), "One deployment with every status it has had"),
257 a("create_deployment", Op::Deployments(DeploymentsOp::CreateDeployment), "Report a deployment of a ref to an environment"),
258 a("deployment_statuses", Op::Deployments(DeploymentsOp::ListDeploymentStatuses), "A deployment's statuses, newest first"),
259 a("create_deployment_status", Op::Deployments(DeploymentsOp::CreateDeploymentStatus), "Report where a deployment is: in_progress, success, failure"),
260 a("list_environments", Op::Deployments(DeploymentsOp::ListEnvironments), "Environments with their current and latest deployments"),
261 a("get_environment", Op::Deployments(DeploymentsOp::GetEnvironment), "One environment by name, with its protection rules"),
262 a("start_deployment_build", Op::Deployments(DeploymentsOp::StartDeploymentBuild), "From a workflow job: open a g1t.page build it runs itself"),
263 a("update_environment", Op::Protection(ProtectionOp::UpdateEnvironment), "Set an environment's reviewers, wait timer and branches"),
264 a("delete_environment", Op::Protection(ProtectionOp::DeleteEnvironment), "Remove an environment's protection rules"),
265 a("pending_deployments", Op::Protection(ProtectionOp::GetPendingDeployments), "The environments holding a run's jobs"),
266 a("review_deployments", Op::Protection(ProtectionOp::ReviewPendingDeployments), "Approve or reject a run's jobs for its environments"),
267 a("approve_run", Op::Protection(ProtectionOp::ApproveWorkflowRun), "Let a run of a pull request from outside start"),
268 a("get_permissions", Op::Protection(ProtectionOp::GetWorkflowPermissions), "What a job's token gets without `permissions:`"),
269 a("set_permissions", Op::Protection(ProtectionOp::SetWorkflowPermissions), "Set it: read or write"),
270 a("get_approval_policy", Op::Protection(ProtectionOp::GetForkPrApproval), "Which pull requests' runs wait for approval"),
271 a("set_approval_policy", Op::Protection(ProtectionOp::SetForkPrApproval), "Set which pull requests' runs wait for approval"),
272 a("get_access", Op::Protection(ProtectionOp::GetActionsAccess), "Which repositories may use this one's actions and workflows"),
273 a("set_access", Op::Protection(ProtectionOp::SetActionsAccess), "Let the workspace's private repositories use them, or not"),
274 a("repository_dispatch", Op::Protection(ProtectionOp::CreateRepositoryDispatch), "Start repository_dispatch workflows with an event"),
275 a("get_workspace_permissions", Op::Protection(ProtectionOp::GetWorkspaceWorkflowPermissions), "A workspace's default and maximum token permissions"),
276 a("set_workspace_permissions", Op::Protection(ProtectionOp::SetWorkspaceWorkflowPermissions), "Set them, and whether jobs may open pull requests"),
277 a("list_managed_workflows", Op::Protection(ProtectionOp::ListWorkspaceManagedWorkflows), "The workflows a workspace runs in its repositories"),
278 a("add_managed_workflow", Op::Protection(ProtectionOp::CreateWorkspaceManagedWorkflow), "Run a workflow in the workspace's repositories, required or default"),
279 a("update_managed_workflow", Op::Protection(ProtectionOp::UpdateWorkspaceManagedWorkflow), "Change one's repositories or mode, or copy its source again"),
280 a("remove_managed_workflow", Op::Protection(ProtectionOp::DeleteWorkspaceManagedWorkflow), "Take one out of the workspace's repositories"),
281 a("list_runners", Op::ListRunners, "Self-hosted runners, with status, labels and what each is doing"),
282 a("create_runner_token", Op::CreateRunnerRegistrationToken, "A one-hour token for g1t-runner register"),
283 a("remove_runner", Op::RemoveRunner, "Remove a self-hosted runner"),
284 a("list_runner_groups", Op::ListRunnerGroups, "A workspace's runner groups"),
285 a("create_runner_group", Op::CreateRunnerGroup, "Make a group, for some repositories"),
286 a("update_runner_group", Op::UpdateRunnerGroup, "Rename a group or change its repositories"),
287 a("delete_runner_group", Op::DeleteRunnerGroup, "Delete a group; its runners join the default"),
288 a("get_runner_settings", Op::GetRunnerSettings, "Where agent work runs; whether forks may use runners"),
289 a("update_runner_settings", Op::UpdateRunnerSettings, "Change them"),
290 ],
291 },
292 Tool {
293 name: "observability",
294 title: "Observability",
295 description: "What a project's running software did in production, to debug it: its requests, logs, traces, grouped errors and metrics, from its apps on g1t.page and from OpenTelemetry sent from anywhere. Name the project by workspace and project slug. Start with overview (error rate, latency, the routes and the deployment a regression began with) or errors, then follow a request or trace_id to its logs and spans. Times are RFC 3339 or Unix milliseconds; the last 24 hours unless you say. Needs a role of your own on the project's repository; resolving errors, Triage.",
296 default_action: None,
297 actions: &[
298 a("overview", Op::Telemetry(TelemetryOp::GetOverview), "Requests, errors, latency and CPU over a period, by route, deployment, service and region, against the period before"),
299 a("requests", Op::Telemetry(TelemetryOp::ListRequests), "Requests answered, newest first: q, status (5xx, 404), errors_only, route, min_duration_ms"),
300 a("request", Op::Telemetry(TelemetryOp::GetRequest), "One request with every log line it wrote"),
301 a("logs", Op::Telemetry(TelemetryOp::ListLogs), "Search a project's logs: words or a phrase in q, level (error,warn), trace_id, request_id"),
302 a("traces", Op::Telemetry(TelemetryOp::ListTraces), "Traces, newest first: q, errors_only, min_duration_ms"),
303 a("trace", Op::Telemetry(TelemetryOp::GetTrace), "One trace: every span, with its timing, status and attributes, and its logs"),
304 a("errors", Op::Telemetry(TelemetryOp::ListErrors), "Errors grouped by exception, most recent first, with the deployment that brought each in"),
305 a("update_error", Op::Telemetry(TelemetryOp::UpdateError), "Resolve, ignore or reopen an error group, or link the issue made for it"),
306 a("metrics", Op::Telemetry(TelemetryOp::ListMetrics), "The metrics the project's software sends"),
307 a("metric", Op::Telemetry(TelemetryOp::GetMetric), "One metric over time: aggregate (avg, sum, p95), group_by an attribute"),
308 ],
309 },
310 Tool {
311 name: "package",
312 title: "Packages",
313 description: "A workspace's packages in every registry (container images, npm, Cargo, Maven, NuGet, RubyGems, Composer): their versions and downloads, deleting and restoring them within 30 days, their visibility and repository, who has a role on them, and which repositories' workflows may use them (Manage Actions access). Name one by workspace, package_type and package_name.",
314 default_action: None,
315 actions: &[
316 a("list", Op::Packages(PackagesOp::ListPackages), "A workspace's packages; state deleted for restorable ones"),
317 a("get", Op::Packages(PackagesOp::GetPackage), "One package: address, visibility, repository, downloads"),
318 a("versions", Op::Packages(PackagesOp::ListVersions), "Its versions with tags and downloads; state deleted too"),
319 a("get_version", Op::Packages(PackagesOp::GetVersion), "One version by id, version, digest or tag"),
320 a("update", Op::Packages(PackagesOp::UpdatePackage), "Set visibility, or inherit_access for a linked one"),
321 a("link", Op::Packages(PackagesOp::LinkPackage), "Link it to a repository of its workspace"),
322 a("unlink", Op::Packages(PackagesOp::UnlinkPackage), "Unlink it: the workspace's, private"),
323 a("access", Op::Packages(PackagesOp::ListAccess), "People and teams with a role on it"),
324 a("set_access", Op::Packages(PackagesOp::SetAccess), "Give a person or team read, write or admin"),
325 a("remove_access", Op::Packages(PackagesOp::RemoveAccess), "Take a person's or team's role away"),
326 a("actions_access", Op::Packages(PackagesOp::ListActionsAccess), "Repositories whose workflows may use it"),
327 a("set_actions_access", Op::Packages(PackagesOp::SetActionsAccess), "Let a repository's workflows read or write it"),
328 a("remove_actions_access", Op::Packages(PackagesOp::RemoveActionsAccess), "Stop a repository's workflows using it"),
329 a("delete", Op::Packages(PackagesOp::DeletePackage), "Delete it; restorable for 30 days"),
330 a("restore", Op::Packages(PackagesOp::RestorePackage), "Restore a deleted package"),
331 a("delete_version", Op::Packages(PackagesOp::DeleteVersion), "Delete a version; restorable for 30 days"),
332 a("restore_version", Op::Packages(PackagesOp::RestoreVersion), "Restore a deleted version"),
333 ],
334 },
335 Tool {
336 name: "secret",
337 title: "Secrets and variables",
338 description: "A repository's or workspace's secrets and variables, read by workflows and deployments. Secret values are never returned.",
339 default_action: None,
340 actions: &[
341 a("list_secrets", Op::ListActionsSecrets, "Secrets, without values"),
342 a("set_secret", Op::SetActionsSecret, "Add or change a secret"),
343 a("delete_secret", Op::DeleteActionsSecret, "Remove a secret"),
344 a("list_variables", Op::ListActionsVariables, "Variables, with values"),
345 a("set_variable", Op::SetActionsVariable, "Add or change a variable"),
346 a("delete_variable", Op::DeleteActionsVariable, "Remove a variable"),
347 ],
348 },
349 Tool {
350 name: "webhook",
351 title: "Webhooks",
352 description: "HTTPS addresses sent signed events as they happen, for a repository or a whole workspace.",
353 default_action: None,
354 actions: &[
355 a("list", Op::ListWebhooks, "Webhooks, without secrets"),
356 a("create", Op::CreateWebhook, "Register one; a ping is sent"),
357 a("update", Op::UpdateWebhook, "Change address, events or active"),
358 a("delete", Op::DeleteWebhook, "Remove one"),
359 a("ping", Op::PingWebhook, "Send a ping"),
360 a("list_deliveries", Op::ListWebhookDeliveries, "Latest deliveries"),
361 a("redeliver", Op::RedeliverWebhook, "Send a delivery again"),
362 ],
363 },
364 Tool {
365 name: "access",
366 title: "Who has access",
367 description: "Who has access to a repository and with which role (read, triage, write, maintain, admin), outside collaborators, a workspace's base permission, and a repository's deploy keys.",
368 default_action: None,
369 actions: &[
370 a("list_collaborators", Op::ListCollaborators, "Everyone with a role, and pending invitations"),
371 a("get_permission", Op::GetCollaboratorPermission, "One person's role and capabilities"),
372 a("add_collaborator", Op::AddCollaborator, "Give someone a role, by username or email"),
373 a("update_collaborator", Op::UpdateCollaborator, "Change a direct role"),
374 a("remove_collaborator", Op::RemoveCollaborator, "Take away a direct role"),
375 a("list_invitations", Op::ListRepoInvitations, "Pending invitations to a repository"),
376 a("revoke_invitation", Op::RevokeRepoInvitation, "Withdraw one"),
377 a("set_base_permission", Op::SetBasePermission, "What every member gets on each repository"),
378 a("list_outside_collaborators", Op::ListOutsideCollaborators, "People with roles who are not members"),
379 a("list_deploy_keys", Op::DeployKeys(DeployKeysOp::ListDeployKeys), "SSH keys that reach this one repository"),
380 a("get_deploy_key", Op::DeployKeys(DeployKeysOp::GetDeployKey), "One deploy key, by id"),
381 a("add_deploy_key", Op::DeployKeys(DeployKeysOp::CreateDeployKey), "Add one; read-only unless read_only is false"),
382 a("remove_deploy_key", Op::DeployKeys(DeployKeysOp::DeleteDeployKey), "Delete one"),
383 ],
384 },
385 Tool {
386 name: "team",
387 title: "Teams",
388 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.",
389 default_action: None,
390 actions: &[
391 a("list", Op::ListTeams, "A workspace's teams you can see"),
392 a("get", Op::GetTeam, "One team"),
393 a("create", Op::CreateTeam, "Create a team; you become its maintainer"),
394 a("update", Op::UpdateTeam, "Change its name, slug, description, visibility, parent or notifications"),
395 a("delete", Op::DeleteTeam, "Delete it; its child teams move up"),
396 a("list_members", Op::ListTeamMembers, "Its people and their roles, child teams' with include_child_teams"),
397 a("set_member", Op::SetTeamMember, "Add a member of the workspace, or change their role"),
398 a("remove_member", Op::RemoveTeamMember, "Take someone out of it"),
399 a("list_child_teams", Op::ListChildTeams, "The teams nested under it"),
400 a("list_repos", Op::ListTeamRepos, "The repositories it has a role on"),
401 a("set_repo", Op::SetTeamRepo, "Give it a role on a repository"),
402 a("remove_repo", Op::RemoveTeamRepo, "Take its role on a repository away"),
403 a("set_review_assignment", Op::SetTeamReviewAssignment, "Whom it picks when asked to review"),
404 a("list_user_teams", Op::ListUserTeams, "The teams someone is in"),
405 ],
406 },
407 Tool {
408 name: "workspace",
409 title: "Workspaces",
410 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.",
411 default_action: None,
412 actions: &[
413 a("get", Op::GetWorkspace, "A workspace's details and settings"),
414 a("create", Op::CreateWorkspace, "Create a workspace"),
415 a("delete", Op::DeleteWorkspace, "Delete a workspace and everything in it (support can restore it for 30 days)"),
416 a("update", Op::UpdateWorkspace, "Change its name, description, base permission, who may create teams, member privileges or the two-factor requirement"),
417 a("list_members", Op::ListMembers, "Its members, owners first, with their roles"),
418 a("update_member", Op::UpdateMember, "Make someone an owner or a member, billing manager or security manager"),
419 a("remove_member", Op::RemoveMember, "Remove someone from it"),
420 a("transfer_ownership", Op::TransferOwnership, "Hand it to another member: they become an owner, you a member"),
421 a("leave", Op::LeaveWorkspace, "Leave it yourself"),
422 a("list_invites", Op::ListWorkspaceInvites, "Its invites"),
423 a("invite_member", Op::InviteMember, "Invite someone by username or email address"),
424 a("revoke_invite", Op::RevokeWorkspaceInvite, "Revoke a pending invite"),
425 a("list_integrations", Op::ListIntegrations, "Model providers, alert sources, trackers"),
426 a("connect_integration", Op::ConnectIntegration, "Connect one"),
427 a("update_integration", Op::UpdateIntegration, "Change one: rotate its key, choose its AI Gateway models"),
428 a("disconnect_integration", Op::DisconnectIntegration, "Remove one"),
429 a("test_integration", Op::TestIntegration, "Check its credentials"),
430 a("get_model_routes", Op::GetModelRoutes, "Where each kind of work's model requests go"),
431 a("set_model_routes", Op::SetModelRoutes, "Replace them"),
432 a("list_projects", Op::ListProjects, "Its projects you can see: what each is, where it runs, its links"),
433 a("get_project", Op::GetProject, "One project"),
434 a("update_project", Op::UpdateProject, "Change a project's name, description, kind, where it runs or its links"),
435 a("list_pinned_projects", Op::ListPinnedProjects, "Your pinned projects in it, in your order"),
436 a("pin_project", Op::PinProject, "Pin a project, at a position or the end"),
437 a("unpin_project", Op::UnpinProject, "Unpin a project"),
438 a("reorder_pinned_projects", Op::ReorderPinnedProjects, "Put your pins in a new order"),
439 a("list_rulesets", Op::Rules(RulesOp::ListWorkspaceRulesets), "Its rulesets, which hold across its repositories"),
440 a("get_ruleset", Op::Rules(RulesOp::GetWorkspaceRuleset), "One of its rulesets"),
441 a("create_ruleset", Op::Rules(RulesOp::CreateWorkspaceRuleset), "Create a ruleset for some or all of its repositories"),
442 a("update_ruleset", Op::Rules(RulesOp::UpdateWorkspaceRuleset), "Change one of its rulesets"),
443 a("delete_ruleset", Op::Rules(RulesOp::DeleteWorkspaceRuleset), "Delete one of its rulesets"),
444 a("rule_evaluations", Op::Rules(RulesOp::ListWorkspaceRuleEvaluations), "How rules judged changes across its repositories"),
445 a("get_token_policy", Op::Tokens(TokenOp::GetTokenPolicy), "Its rules for personal access tokens"),
446 a("set_token_policy", Op::Tokens(TokenOp::SetTokenPolicy), "Change them: which tokens reach it, approval, lifetime"),
447 a("list_member_tokens", Op::Tokens(TokenOp::ListMemberTokens), "Members' personal access tokens that reach it"),
448 a("list_token_requests", Op::Tokens(TokenOp::ListTokenRequests), "Tokens waiting for approval"),
449 a("review_token_request", Op::Tokens(TokenOp::ReviewTokenRequest), "Approve or deny one"),
450 a("revoke_member_token", Op::Tokens(TokenOp::RevokeMemberToken), "Revoke a member's token in it"),
451 ],
452 },
453 Tool {
454 name: "customize",
455 title: "Customize",
456 description: "What shapes how a workspace's agents work, in the formats Claude Code reads: the marketplaces it reads plugins from (`.claude-plugin/marketplace.json`), what Discover lists, the plugins it installed as `name@marketplace` (their skills join the library as `plugin:skill`, their subagents become templates, their remote MCP servers become connectors), and its connectors: MCP servers connected once with a key or a sign-in, then given to every agent, a team or one agent. Members read; owners change. `bundle` is what a job's Claude Code loads on a runner, for the job's own token.",
457 default_action: None,
458 actions: &[
459 a("list_marketplaces", Op::Customize(CustomizeOp::ListMarketplaces), "The marketplaces it reads plugins from"),
460 a("add_marketplace", Op::Customize(CustomizeOp::AddMarketplace), "Add one by owner/repo, workspace/name, a git address or a marketplace.json link"),
461 a("remove_marketplace", Op::Customize(CustomizeOp::RemoveMarketplace), "Remove one; its installed plugins stay"),
462 a("refresh_marketplace", Op::Customize(CustomizeOp::RefreshMarketplace), "Read its manifest again now"),
463 a("discover", Op::Customize(CustomizeOp::Discover), "Every plugin and skill it can add, with availability"),
464 a("list_plugins", Op::Customize(CustomizeOp::ListPlugins), "Installed plugins: pinned commit, components, updates"),
465 a("get_plugin", Op::Customize(CustomizeOp::GetPlugin), "One plugin's listing, install, components, README and agents"),
466 a("install_plugin", Op::Customize(CustomizeOp::InstallPlugin), "Install one at its listed commit"),
467 a("set_plugin_enabled", Op::Customize(CustomizeOp::SetPluginEnabled), "Switch an installed one on or off"),
468 a("uninstall_plugin", Op::Customize(CustomizeOp::UninstallPlugin), "Uninstall one, with its skills, templates and connectors"),
469 a("update_plugin", Op::Customize(CustomizeOp::UpdatePlugin), "Read one again at its marketplace's current commit"),
470 a("list_plugin_agents", Op::Customize(CustomizeOp::ListPluginAgents), "Subagents plugins brought, as templates to hire from"),
471 a("list_connectors", Op::Customize(CustomizeOp::ListConnectors), "MCP servers connected to the workspace, with state, tools and grants"),
472 a("get_connector", Op::Customize(CustomizeOp::GetConnector), "One connector"),
473 a("add_connector", Op::Customize(CustomizeOp::AddConnector), "Add one from the directory, a plugin's server or an address"),
474 a("set_connector_key", Op::Customize(CustomizeOp::SetConnectorKey), "Put a key on one; never returned"),
475 a("remove_connector", Op::Customize(CustomizeOp::RemoveConnector), "Remove one with its secrets and grants"),
476 a("refresh_connector", Op::Customize(CustomizeOp::RefreshConnector), "List its tools again now"),
477 a("grant_connector", Op::Customize(CustomizeOp::GrantConnector), "Give it to every agent, a team or one agent"),
478 a("revoke_connector", Op::Customize(CustomizeOp::RevokeConnector), "Take one grant back"),
479 a("bundle", Op::Customize(CustomizeOp::Bundle), "What a job's Claude Code loads: plugins, library skills, connectors with headers"),
480 ],
481 },
482 Tool {
483 name: "billing",
484 title: "Billing",
485 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.",
486 default_action: Some("usage"),
487 actions: &[
488 a("usage", Op::GetUsage, "Usage over a range of days, by product, meter, project and day, and what paid for it"),
489 a("budget", Op::GetBudget, "The monthly spend limit, what was spent, alerts and whether usage pauses at the limit"),
490 a("set_budget", Op::SetBudget, "Change the spend limit, alerts, pausing or the alert webhook"),
491 a("ai_credit", Op::GetAiCredit, "AI credit left, its grants, auto-reload and how to buy more"),
492 a("buy_ai_credit", Op::BuyAiCredit, "A payment page to buy AI credit, for a person to open"),
493 a("invoices", Op::ListInvoices, "Every invoice, the itemised usage invoices, and the next one so far"),
494 a("billing_details", Op::GetBillingDetails, "Who invoices are made out to and the payment method on file"),
495 a("gateway_requests", Op::ListGatewayRequests, "Recent AI Gateway requests: model, tokens, cost, status and token"),
496 ],
497 },
498 Tool {
499 name: "security",
500 title: "Security",
501 description: "A repository's security: secret scanning alerts and push protection bypasses, custom secret patterns, code scanning alerts and SARIF uploads, vulnerability alerts, the dependency graph and its SBOM, dependency review, settings, a workspace's overview, security advisories and private vulnerability reports. Fix an alert with g1t. Findings are shown to those who can change the code only; published advisories to anyone who can see the repository. Give `repo` (owner/name), or `workspace` for lists across one.",
502 default_action: Some("secret_alerts"),
503 actions: &[
504 a("secret_alerts", Op::Security(SecurityOp::ListSecretAlerts), "Secret scanning alerts; by state, secret_type, validity, bypassed"),
505 a("secret_alert", Op::Security(SecurityOp::GetSecretAlert), "One secret alert, with where it was found and its bypass requests"),
506 a("update_secret_alert", Op::Security(SecurityOp::UpdateSecretAlert), "Dismiss a secret alert with a reason, or reopen it"),
507 a("secret_locations", Op::Security(SecurityOp::ListSecretLocations), "Every file, line and commit a secret is in"),
508 a("bypass", Op::Security(SecurityOp::BypassPushProtection), "Push past push protection with a reason, or ask to"),
509 a("check_validity", Op::Security(SecurityOp::CheckSecretValidity), "Ask a secret's issuer whether it still works"),
510 a("bypass_requests", Op::Security(SecurityOp::ListBypassRequests), "A workspace's push protection bypass requests"),
511 a("review_bypass", Op::Security(SecurityOp::ReviewBypassRequest), "Approve, deny or cancel a bypass request"),
512 a("patterns", Op::Security(SecurityOp::ListCustomPatterns), "Custom secret patterns of a repository or workspace"),
513 a("create_pattern", Op::Security(SecurityOp::CreateCustomPattern), "Create a custom secret pattern, as a draft or published"),
514 a("update_pattern", Op::Security(SecurityOp::UpdateCustomPattern), "Change, publish or unpublish a custom pattern"),
515 a("delete_pattern", Op::Security(SecurityOp::DeleteCustomPattern), "Delete a custom pattern"),
516 a("dry_run_pattern", Op::Security(SecurityOp::DryRunCustomPattern), "Run a pattern over the default branch without saving it"),
517 a("code_alerts", Op::Security(SecurityOp::ListCodeAlerts), "Code scanning alerts; by state, severity, tool, rule_id"),
518 a("code_alert", Op::Security(SecurityOp::GetCodeAlert), "One code scanning alert by number"),
519 a("update_code_alert", Op::Security(SecurityOp::UpdateCodeAlert), "Dismiss a code scanning alert with a reason, or reopen it"),
520 a("analyses", Op::Security(SecurityOp::ListAnalyses), "Code scanning analyses, newest first"),
521 a("upload_sarif", Op::Security(SecurityOp::UploadSarif), "Upload a SARIF file, gzipped and base64-encoded"),
522 a("sarif_upload", Op::Security(SecurityOp::GetSarifUpload), "Whether a SARIF upload was read, and its analyses"),
523 a("vulnerability_alerts", Op::Security(SecurityOp::ListVulnerabilityAlerts), "Vulnerable dependencies; by state, severity, ecosystem, package"),
524 a("vulnerability_alert", Op::Security(SecurityOp::GetVulnerabilityAlert), "One vulnerability alert"),
525 a("update_vulnerability_alert", Op::Security(SecurityOp::UpdateVulnerabilityAlert), "Dismiss a vulnerability alert with a reason, or reopen it"),
526 a("fix", Op::Security(SecurityOp::FixAlert), "Put g1t on an issue to fix an alert"),
527 a("dependency_graph", Op::Security(SecurityOp::GetDependencyGraph), "Every package the lockfiles resolve, direct or transitive"),
528 a("sbom", Op::Security(SecurityOp::GetSbom), "The dependency graph as an SPDX 2.3 document"),
529 a("compare_dependencies", Op::Security(SecurityOp::CompareDependencies), "What changes in dependencies between base...head"),
530 a("settings", Op::Security(SecurityOp::GetSettings), "A repository's security settings"),
531 a("update_settings", Op::Security(SecurityOp::UpdateSettings), "Change when checks fail and dependency review's policy"),
532 a("workspace_settings", Op::Security(SecurityOp::GetWorkspaceSettings), "A workspace's delegated bypass and validity checks"),
533 a("update_workspace_settings", Op::Security(SecurityOp::UpdateWorkspaceSettings), "Turn delegated bypass or validity checks on or off"),
534 a("overview", Op::Security(SecurityOp::GetOverview), "A workspace's alerts, trends and coverage"),
535 a("advisories", Op::Security(SecurityOp::ListAdvisories), "A repository's security advisories; by state"),
536 a("advisory", Op::Security(SecurityOp::GetAdvisory), "One advisory by adv_… or G1TSA-… id"),
537 a("create_advisory", Op::Security(SecurityOp::CreateAdvisory), "Draft a security advisory"),
538 a("update_advisory", Op::Security(SecurityOp::UpdateAdvisory), "Change an advisory's fields"),
539 a("set_advisory_state", Op::Security(SecurityOp::SetAdvisoryState), "Publish or withdraw an advisory"),
540 a("reports", Op::Security(SecurityOp::ListReports), "Vulnerability reports sent to the maintainers; by state"),
541 a("report_vulnerability", Op::Security(SecurityOp::ReportVulnerability), "Report a vulnerability privately to a repository's maintainers"),
542 a("review_report", Op::Security(SecurityOp::ReviewReport), "Accept a report as a draft advisory, or decline it"),
543 ],
544 },
545 Tool {
546 name: "notifications",
547 title: "Notifications",
548 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.",
549 default_action: Some("list"),
550 actions: &[
551 a("list", Op::ListNotifications, "Unread threads, latest first; all, a view, a reason, a repository"),
552 a("get", Op::GetNotificationThread, "One thread with its recent activity and your subscription"),
553 a("mark_read", Op::MarkThreadRead, "Mark a thread read, or unread"),
554 a("mark_all_read", Op::MarkNotificationsRead, "Mark everything read up to a time, or one repository's"),
555 a("done", Op::MarkThreadDone, "Mark a thread done; new activity brings it back"),
556 a("save", Op::SaveThread, "Save a thread, or unsave it"),
557 a("snooze", Op::SnoozeThread, "Snooze a thread until a time, or bring it back"),
558 a("subscription", Op::GetThreadSubscription, "Your subscription to an issue or pull request"),
559 a("subscribe", Op::SetThreadSubscription, "Subscribe to an issue or pull request, or ignore it"),
560 a("unsubscribe", Op::DeleteThreadSubscription, "Unsubscribe until you comment or are mentioned"),
561 a("watching", Op::GetRepoSubscription, "How you watch a repository"),
562 a("watch", Op::SetRepoSubscription, "Watch a repository: participating, all, ignore or custom"),
563 a("unwatch", Op::DeleteRepoSubscription, "Stop watching a repository"),
564 a("watched", Op::ListWatchedRepos, "Repositories you watch other than the default way"),
565 ],
566 },
567 Tool {
568 name: "account",
569 title: "Your account",
570 description: "Who this token acts as and its workspaces (`whoami`), your email addresses, your invites, and invitations to workspaces and repositories waiting for you.",
571 default_action: Some("whoami"),
572 actions: &[
573 a("whoami", Op::Whoami, "Who the token acts as, and its workspaces"),
574 a("list_emails", Op::ListEmails, "Your addresses"),
575 a("add_email", Op::AddEmail, "Add an address"),
576 a("confirm_email", Op::ConfirmEmail, "Confirm an address with the code from its email"),
577 a("remove_email", Op::RemoveEmail, "Remove an address"),
578 a("update_email_settings", Op::UpdateEmailSettings, "Primary, backup and privacy"),
579 a("list_invites", Op::ListInvites, "Your invites to g1t"),
580 a("create_invite", Op::CreateInvite, "Make an invite"),
581 a("revoke_invite", Op::RevokeInvite, "Revoke one"),
582 a("list_workspace_invitations", Op::ListInvitations, "Invitations to workspaces for you"),
583 a("accept_workspace_invitation", Op::AcceptInvitation, "Accept one and join"),
584 a("decline_workspace_invitation", Op::DeclineInvitation, "Decline one"),
585 a("list_repository_invitations", Op::ListMyRepoInvitations, "Invitations to repositories for you"),
586 a("accept_repository_invitation", Op::AcceptRepoInvitation, "Accept one"),
587 a("decline_repository_invitation", Op::DeclineRepoInvitation, "Decline one"),
588 ],
589 },
590 Tool {
591 name: "artifact",
592 title: "Artifacts",
593 description: "A workspace's docs, slides, designs and dashboards (Artifacts mode), as you can open them: list, search and read them (a doc's content is Markdown, with block ids to target), make them, edit them (a change with the edit role, a suggestion with comment), move, trash and restore them, their versions, and who can open them. Name one by its id (fol_…) or its address. Not the `workflow` tool's run artifacts. Slides, designs and dashboards answer that they are not here yet.",
594 default_action: None,
595 actions: &[
596 a("list", Op::Folios(FoliosOp::List), "Artifacts you can open; tab, kind, space, q; state trashed for the trash"),
597 a("search", Op::Folios(FoliosOp::Search), "Search them by words and meaning, with the passage that matched"),
598 a("get", Op::Folios(FoliosOp::Get), "One artifact: kind, title, space, owner, your role, who it is shared with"),
599 a("read", Op::Folios(FoliosOp::GetContent), "Its content: a doc's Markdown and block ids, and what you may do"),
600 a("versions", Op::Folios(FoliosOp::ListVersions), "Its saved versions, newest first"),
601 a("access", Op::Folios(FoliosOp::GetAccess), "Who can open it, and how"),
602 a("templates", Op::Folios(FoliosOp::ListTemplates), "Templates to start one from"),
603 a("spaces", Op::Folios(FoliosOp::ListSpaces), "The spaces in your sidebar"),
604 a("query_data", Op::Folios(FoliosOp::QueryDataset), "Run a dataset query as you, over what you can read"),
605 a("create", Op::Folios(FoliosOp::Create), "Make one: in a space, under a doc, or in your Private"),
606 a("update", Op::Folios(FoliosOp::Update), "Rename it, change its icon, or move it"),
607 a("edit", Op::Folios(FoliosOp::Edit), "Change its content: append, replace it all, a section or blocks"),
608 a("trash", Op::Folios(FoliosOp::Trash), "Move it to the trash; restorable for 30 days"),
609 a("restore", Op::Folios(FoliosOp::Restore), "Bring it back from the trash"),
610 a("restore_version", Op::Folios(FoliosOp::RestoreVersion), "Make an earlier version its content again"),
611 a("share", Op::Folios(FoliosOp::SetAccess), "Share it, change general access, or take access away"),
612 a("purge", Op::Folios(FoliosOp::Purge), "Delete one in the trash for good"),
613 ],
614 },
615];
616
617/// Operations offered over REST alone, not as an action of any tool: how
618/// a project's telemetry is collected (settings, ingest tokens, exports,
619/// usage) is for people setting it up, not for agents debugging.
620pub const REST_ONLY: &[Op] = &[
621 Op::Telemetry(TelemetryOp::GetSettings),
622 Op::Telemetry(TelemetryOp::UpdateSettings),
623 Op::Telemetry(TelemetryOp::ListTokens),
624 Op::Telemetry(TelemetryOp::CreateToken),
625 Op::Telemetry(TelemetryOp::DeleteToken),
626 Op::Telemetry(TelemetryOp::ListExports),
627 Op::Telemetry(TelemetryOp::CreateExport),
628 Op::Telemetry(TelemetryOp::UpdateExport),
629 Op::Telemetry(TelemetryOp::DeleteExport),
630 Op::Telemetry(TelemetryOp::GetUsage),
631];
632
633/// Operations that cannot be undone, or reach beyond g1t's own records:
634/// clients ask before running a tool that has any of them.
635fn destructive(op: Op) -> bool {
636 matches!(
637 op,
638 Op::Security(SecurityOp::DeleteCustomPattern | SecurityOp::BypassPushProtection)
639 | Op::Rules(RulesOp::DeleteRepoRuleset | RulesOp::DeleteWorkspaceRuleset)
640 | Op::DeleteWorkspace
641 | Op::UpdateWorkspace
642 | Op::Tokens(TokenOp::RevokeMemberToken | TokenOp::SetTokenPolicy)
643 | Op::RemoveMember
644 | Op::TransferOwnership
645 | Op::LeaveWorkspace
646 | Op::DeleteRepo
647 | Op::PurgeRepo
648 | Op::TransferRepo
649 | Op::SetRepoVisibility
650 | Op::RemoveEmail
651 | Op::RemoveCollaborator
652 | Op::DisconnectIntegration
653 | Op::UpdateIntegration
654 | Op::DeleteWebhook
655 | Op::DeleteActionsSecret
656 | Op::DeleteActionsVariable
657 | Op::SetActionsSecret
658 | Op::SetActionsVariable
659 | Op::SetModelRoutes
660 | Op::SetBasePermission
661 | Op::DeleteTeam
662 | Op::RemoveTeamRepo
663 | Op::MergePullRequest
664 | Op::RemoveRunner
665 | Op::DeleteRunnerGroup
666 | Op::UpdateRunnerSettings
667 | Op::Folios(FoliosOp::SetAccess | FoliosOp::Purge)
668 | Op::Customize(CustomizeOp::RemoveMarketplace | CustomizeOp::UninstallPlugin | CustomizeOp::RemoveConnector)
669 )
670}
671
672/// Whether an operation only reads.
673pub fn reads_only(op: Op) -> bool {
674 NO_SCOPE.contains(&op.name())
675 || scope_for(op.name()).is_some_and(|scope| scope.level() == Level::Read)
676}
677
678/// What decides which actions a caller sees.
679pub enum Gate<'a> {
680 /// No limit beyond the person's own role.
681 Everything,
682 /// A g1t agent's token: the operations its run lists.
683 Agent(&'a AgentScope),
684 /// An access token with scopes.
685 Token(&'a TokenAccess),
686}
687
688impl Gate<'_> {
689 pub fn allows(&self, op: Op) -> bool {
690 match self {
691 Gate::Everything => true,
692 Gate::Agent(scope) => op.allowed_by(scope) && !NEVER.contains(&op.name()),
693 Gate::Token(access) => {
694 if NO_SCOPE.contains(&op.name()) {
695 return true;
696 }
697 match scope_for(op.name()) {
698 Some(scope) => access.allows(scope),
699 None => access.scopes.is_none(),
700 }
701 }
702 }
703 }
704}
705
706impl Tool {
707 pub fn by_name(name: &str) -> Option<&'static Tool> {
708 TOOLS.iter().find(|tool| tool.name == name)
709 }
710
711 pub fn action(&self, name: &str) -> Option<&'static Action> {
712 // The tools are 'static; find through TOOLS to keep the lifetime.
713 TOOLS
714 .iter()
715 .find(|tool| tool.name == self.name)
716 .and_then(|tool| tool.actions.iter().find(|action| action.name == name))
717 }
718
719 pub fn visible(&self, gate: &Gate) -> Vec<&'static Action> {
720 TOOLS
721 .iter()
722 .find(|tool| tool.name == self.name)
723 .map(|tool| tool.actions.iter().filter(|action| gate.allows(action.op)).collect())
724 .unwrap_or_default()
725 }
726
727 /// The flat input schema of the actions given.
728 pub fn input_schema(&self, actions: &[&Action]) -> Value {
729 let mut properties = Map::new();
730 let lines: Vec<String> = actions
731 .iter()
732 .map(|action| {
733 let required: Vec<String> = action.op.required();
734 if required.is_empty() {
735 format!("{}: {}.", action.name, action.summary)
736 } else {
737 format!("{} ({}): {}.", action.name, required.join(", "), action.summary)
738 }
739 })
740 .collect();
741 let mut action_schema = json!({
742 "type": "string",
743 "enum": actions.iter().map(|action| action.name).collect::<Vec<_>>(),
744 "description": lines.join("\n"),
745 });
746 if let Some(default) = self.default_action.filter(|name| actions.iter().any(|action| action.name == *name)) {
747 action_schema["default"] = json!(default);
748 }
749 properties.insert("action".to_owned(), action_schema);
750 for action in actions {
751 for (name, schema) in action.op.properties() {
752 merge_property(&mut properties, name, schema);
753 }
754 }
755 let mut required = vec![];
756 if self.default_action.is_none() {
757 required.push("action");
758 }
759 let mut schema = json!({ "type": "object", "properties": properties });
760 if !required.is_empty() {
761 schema["required"] = json!(required);
762 }
763 schema
764 }
765
766 /// The input schema keyed by action: one `oneOf` branch per action,
767 /// each with its own fields and the ones it needs.
768 pub fn discriminated(&self, actions: &[&Action]) -> Value {
769 let branches: Vec<Value> = actions
770 .iter()
771 .map(|action| {
772 let mut properties = Map::new();
773 properties.insert("action".to_owned(), json!({ "const": action.name }));
774 properties.extend(action.op.properties());
775 let mut required = vec![Value::String("action".to_owned())];
776 // The default action may leave `action` out.
777 if self.default_action == Some(action.name) {
778 required.clear();
779 }
780 required.extend(action.op.required().into_iter().map(Value::String));
781 json!({
782 "title": action.name,
783 "description": action.summary,
784 "type": "object",
785 "properties": properties,
786 "required": required,
787 })
788 })
789 .collect();
790 json!({ "type": "object", "oneOf": branches })
791 }
792
793 /// MCP's hints about the actions given: whether the tool only reads,
794 /// whether it can destroy something, and whether calling it twice is
795 /// the same as once.
796 pub fn annotations(&self, actions: &[&Action]) -> Value {
797 let read_only = actions.iter().all(|action| reads_only(action.op));
798 json!({
799 "title": self.title,
800 "readOnlyHint": read_only,
801 "destructiveHint": !read_only && actions.iter().any(|action| destructive(action.op)),
802 "idempotentHint": read_only,
803 "openWorldHint": false,
804 })
805 }
806
807 /// The tool as `tools/list` gives it, for a caller behind `gate`, or
808 /// `None` when it may use none of its actions.
809 pub fn listed(&self, gate: &Gate) -> Option<Value> {
810 let actions = self.visible(gate);
811 if actions.is_empty() {
812 return None;
813 }
814 Some(json!({
815 "name": self.name,
816 "title": self.title,
817 "description": self.description,
818 "inputSchema": self.input_schema(&actions),
819 "annotations": self.annotations(&actions),
820 }))
821 }
822}
823
824/// Adds a property to a tool's flat schema. The first action to use a name
825/// describes it; a later one with other allowed values adds them.
826fn merge_property(properties: &mut Map<String, Value>, name: String, schema: Value) {
827 match properties.get_mut(&name) {
828 None => {
829 properties.insert(name, schema);
830 }
831 Some(existing) => {
832 if let (Some(Value::Array(had)), Some(Value::Array(more))) =
833 (existing.get("enum").cloned(), schema.get("enum"))
834 {
835 let mut merged = had;
836 for value in more {
837 if !merged.contains(value) {
838 merged.push(value.clone());
839 }
840 }
841 existing["enum"] = Value::Array(merged);
842 }
843 // Different kinds of value under one name: say less, accept both.
844 if existing.get("type") != schema.get("type")
845 && let Some(fields) = existing.as_object_mut()
846 {
847 fields.remove("type");
848 fields.remove("items");
849 }
850 }
851 }
852}
853
854/// What a call to a tool runs: the operation its action names, or why not.
855pub fn resolve(tool: &Tool, arguments: &Value) -> Result<Op, String> {
856 let names = || {
857 tool.actions
858 .iter()
859 .map(|action| action.name)
860 .collect::<Vec<_>>()
861 .join(", ")
862 };
863 let Some(name) = arguments["action"].as_str().or(tool.default_action) else {
864 return Err(format!("Give an action: one of {}.", names()));
865 };
866 let Some(action) = tool.action(name) else {
867 return Err(format!("{} has no action {name}. Its actions: {}.", tool.name, names()));
868 };
869 let missing: Vec<String> = action
870 .op
871 .required()
872 .into_iter()
873 .filter(|field| arguments.get(field).is_none_or(Value::is_null))
874 .collect();
875 if !missing.is_empty() {
876 return Err(format!("{}.{name} needs {}.", tool.name, missing.join(", ")));
877 }
878 Ok(action.op)
879}
880
881#[cfg(test)]
882mod tests {
883 use super::*;
884 use g1t_contracts::scopes::{Preset, Scope};
885
886 fn listed(gate: &Gate) -> Vec<Value> {
887 TOOLS.iter().filter_map(|tool| tool.listed(gate)).collect()
888 }
889
890 fn token(scopes: Option<Vec<Scope>>) -> TokenAccess {
891 TokenAccess {
892 token_id: "tok_1".to_owned(),
893 scopes: scopes.map(|scopes| scopes.iter().map(|scope| scope.as_str().to_owned()).collect()),
894 legacy: false,
895 name: None,
896 ..TokenAccess::default()
897 }
898 }
899
900 #[test]
901 fn every_operation_is_exactly_one_action_of_one_tool() {
902 for op in Op::ALL {
903 let count = TOOLS
904 .iter()
905 .flat_map(|tool| tool.actions.iter())
906 .filter(|action| action.op == op)
907 .count();
908 let expected = usize::from(!REST_ONLY.contains(&op));
909 assert_eq!(count, expected, "{} is {count} actions", op.name());
910 }
911 for tool in TOOLS {
912 let mut names = std::collections::HashSet::new();
913 for action in tool.actions {
914 assert!(names.insert(action.name), "{}.{} twice", tool.name, action.name);
915 }
916 if let Some(default) = tool.default_action {
917 assert!(tool.action(default).is_some(), "{}", tool.name);
918 }
919 }
920 assert!(TOOLS.len() <= 21, "{} tools", TOOLS.len());
921 }
922
923 #[test]
924 fn every_operation_needs_exactly_one_scope_or_none() {
925 use g1t_contracts::scopes::OPERATIONS;
926 for op in Op::ALL {
927 let mapped = OPERATIONS.iter().filter(|(name, _)| *name == op.name()).count();
928 let free = NO_SCOPE.contains(&op.name());
929 assert_eq!(mapped + usize::from(free), 1, "{}", op.name());
930 }
931 for (name, _) in OPERATIONS {
932 assert!(Op::by_name(name).is_some(), "{name} is not an operation");
933 }
934 }
935
936 #[test]
937 fn each_tool_schema_is_valid_with_one_branch_per_action() {
938 for tool in TOOLS {
939 let actions: Vec<&Action> = tool.actions.iter().collect();
940 let flat = tool.input_schema(&actions);
941 assert_eq!(flat["type"], "object");
942 assert!(flat.get("oneOf").is_none(), "no oneOf at the top level");
943 let listed: Vec<&str> = flat["properties"]["action"]["enum"]
944 .as_array()
945 .unwrap()
946 .iter()
947 .map(|name| name.as_str().unwrap())
948 .collect();
949 assert_eq!(listed, tool.actions.iter().map(|action| action.name).collect::<Vec<_>>());
950 for action in tool.actions {
951 for field in action.op.required() {
952 assert!(flat["properties"].get(&field).is_some(), "{}.{}: {field}", tool.name, action.name);
953 }
954 }
955 let keyed = tool.discriminated(&actions);
956 let branches = keyed["oneOf"].as_array().unwrap();
957 assert_eq!(branches.len(), tool.actions.len());
958 for (branch, action) in branches.iter().zip(tool.actions) {
959 assert_eq!(branch["properties"]["action"]["const"], action.name);
960 for field in branch["required"].as_array().unwrap() {
961 assert!(branch["properties"].get(field.as_str().unwrap()).is_some(), "{}.{}: {field}", tool.name, action.name);
962 }
963 }
964 // A well-formed JSON Schema object throughout.
965 let text = serde_json::to_string(&flat).unwrap();
966 assert!(serde_json::from_str::<Value>(&text).is_ok());
967 }
968 }
969
970 #[test]
971 fn a_read_only_token_sees_read_actions_only() {
972 let access = token(Preset::ReadOnly.scopes());
973 let gate = Gate::Token(&access);
974 for tool in TOOLS {
975 for action in tool.visible(&gate) {
976 assert!(reads_only(action.op), "{}.{}", tool.name, action.name);
977 }
978 }
979 let tools = listed(&gate);
980 for tool in &tools {
981 assert_eq!(tool["annotations"]["readOnlyHint"], true, "{}", tool["name"]);
982 assert_eq!(tool["annotations"]["destructiveHint"], false);
983 }
984 let issue = tools.iter().find(|tool| tool["name"] == "issue").unwrap();
985 assert_eq!(issue["inputSchema"]["properties"]["action"]["enum"], json!(["list", "get", "labels"]));
986 // Nothing of the agent tool is a read.
987 assert!(!tools.iter().any(|tool| tool["name"] == "agent"));
988 }
989
990 #[test]
991 fn a_narrow_token_sees_only_its_tools() {
992 let access = token(Some(vec![Scope::IssuesWrite]));
993 let names: Vec<Value> = listed(&Gate::Token(&access)).into_iter().map(|tool| tool["name"].clone()).collect();
994 // Labels and milestones are the repository's, managed with issues:write.
995 assert_eq!(names, vec![json!("repository"), json!("issue"), json!("plan"), json!("account")]);
996 // Notifications are a resource of their own: reading them lists
997 // only what reads.
998 let reader = token(Some(vec![Scope::NotificationsRead]));
999 let tools = listed(&Gate::Token(&reader));
1000 let notifications = tools.iter().find(|tool| tool["name"] == "notifications").unwrap();
1001 assert_eq!(
1002 notifications["inputSchema"]["properties"]["action"]["enum"],
1003 json!(["list", "get", "subscription", "watching", "watched"])
1004 );
1005 assert_eq!(notifications["annotations"]["readOnlyHint"], true);
1006 let full = token(None);
1007 assert_eq!(listed(&Gate::Token(&full)).len(), TOOLS.len());
1008 assert_eq!(listed(&Gate::Everything).len(), TOOLS.len());
1009 }
1010
1011 #[test]
1012 fn a_tool_that_can_destroy_says_so() {
1013 let tools = listed(&Gate::Everything);
1014 let repository = tools.iter().find(|tool| tool["name"] == "repository").unwrap();
1015 assert_eq!(repository["annotations"]["destructiveHint"], true);
1016 assert_eq!(repository["annotations"]["readOnlyHint"], false);
1017 let memory = tools.iter().find(|tool| tool["name"] == "memory").unwrap();
1018 assert_eq!(memory["annotations"]["destructiveHint"], false);
1019 }
1020
1021 #[test]
1022 fn calls_resolve_to_their_operation_or_say_what_is_missing() {
1023 let issue = Tool::by_name("issue").unwrap();
1024 assert_eq!(resolve(issue, &json!({ "action": "get", "repo": "a/b", "number": 1 })), Ok(Op::GetIssue));
1025 assert_eq!(resolve(issue, &json!({ "action": "get", "repo": "a/b" })), Err("issue.get needs number.".to_owned()));
1026 assert!(resolve(issue, &json!({})).unwrap_err().starts_with("Give an action"));
1027 assert!(resolve(issue, &json!({ "action": "explode" })).unwrap_err().contains("no action explode"));
1028 let search = Tool::by_name("search").unwrap();
1029 assert_eq!(resolve(search, &json!({ "query": "x" })), Ok(Op::Search));
1030 let account = Tool::by_name("account").unwrap();
1031 assert_eq!(resolve(account, &json!({})), Ok(Op::Whoami));
1032 }
1033
1034 #[test]
1035 fn teams_are_one_tool_and_a_workspace_reader_sees_only_its_reads() {
1036 let team = Tool::by_name("team").unwrap();
1037 let names: Vec<&str> = team.actions.iter().map(|action| action.name).collect();
1038 assert_eq!(
1039 names,
1040 [
1041 "list",
1042 "get",
1043 "create",
1044 "update",
1045 "delete",
1046 "list_members",
1047 "set_member",
1048 "remove_member",
1049 "list_child_teams",
1050 "list_repos",
1051 "set_repo",
1052 "remove_repo",
1053 "set_review_assignment",
1054 "list_user_teams",
1055 ]
1056 );
1057 let reader = token(Some(vec![Scope::WorkspaceRead]));
1058 let tools = listed(&Gate::Token(&reader));
1059 let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap();
1060 assert_eq!(
1061 listed_team["inputSchema"]["properties"]["action"]["enum"],
1062 json!(["list", "get", "list_members", "list_child_teams", "list_repos", "list_user_teams"])
1063 );
1064 assert_eq!(listed_team["annotations"]["readOnlyHint"], true);
1065 // A team's role on a repository is who has access.
1066 let admin = token(Some(vec![Scope::WorkspaceAdmin]));
1067 let tools = listed(&Gate::Token(&admin));
1068 let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap();
1069 let actions = listed_team["inputSchema"]["properties"]["action"]["enum"].as_array().unwrap();
1070 assert!(actions.contains(&json!("set_review_assignment")) && !actions.contains(&json!("set_repo")));
1071 let access = token(Some(vec![Scope::AccessAdmin]));
1072 let tools = listed(&Gate::Token(&access));
1073 let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap();
1074 assert_eq!(listed_team["inputSchema"]["properties"]["action"]["enum"], json!(["set_repo", "remove_repo"]));
1075 // Both kinds of role a schema names are offered.
1076 let roles = &listed(&Gate::Everything).into_iter().find(|tool| tool["name"] == "team").unwrap()["inputSchema"]
1077 ["properties"]["role"]["enum"];
1078 for role in ["member", "maintainer", "read", "admin"] {
1079 assert!(roles.as_array().unwrap().contains(&json!(role)), "{role}");
1080 }
1081 assert_eq!(
1082 resolve(team, &json!({ "action": "set_repo", "workspace": "acme", "team": "backend", "repo": "rocket" })),
1083 Err("team.set_repo needs role.".to_owned())
1084 );
1085 }
1086
1087 #[test]
1088 fn reviewers_and_code_owners_are_actions_of_their_tools() {
1089 let pull = Tool::by_name("pull_request").unwrap();
1090 assert_eq!(
1091 resolve(pull, &json!({ "action": "request_reviewers", "repo": "a/b", "number": 1, "team_reviewers": ["backend"] })),
1092 Ok(Op::RequestReviewers)
1093 );
1094 assert_eq!(pull.action("remove_requested_reviewers").map(|action| action.op), Some(Op::RemoveRequestedReviewers));
1095 let repository = Tool::by_name("repository").unwrap();
1096 assert_eq!(resolve(repository, &json!({ "action": "codeowners", "repo": "a/b" })), Ok(Op::GetCodeownersErrors));
1097 assert!(reads_only(Op::GetCodeownersErrors));
1098 assert!(!reads_only(Op::RequestReviewers));
1099 }
1100
1101 /// The `artifact` tool offers each token only what its artifacts scope
1102 /// allows: reading, then changing, then sharing and deleting for good.
1103 /// Workflow runs' artifacts are the `workflow` tool's, under their own
1104 /// scope, and neither scope reaches the other's.
1105 #[test]
1106 fn the_artifact_tool_offers_what_the_artifacts_scope_allows() {
1107 let actions = |scopes: Vec<Scope>| -> Option<Value> {
1108 let access = token(Some(scopes));
1109 Tool::by_name("artifact").unwrap().listed(&Gate::Token(&access)).map(|tool| tool["inputSchema"]["properties"]["action"]["enum"].clone())
1110 };
1111 let reads = json!(["list", "search", "get", "read", "versions", "access", "templates", "spaces", "query_data"]);
1112 assert_eq!(actions(vec![Scope::ArtifactsRead]), Some(reads.clone()));
1113 let writes = actions(vec![Scope::ArtifactsWrite]).unwrap();
1114 for action in ["create", "update", "edit", "trash", "restore", "restore_version"] {
1115 assert!(writes.as_array().unwrap().contains(&json!(action)), "{action}");
1116 }
1117 assert!(!writes.as_array().unwrap().contains(&json!("share")) && !writes.as_array().unwrap().contains(&json!("purge")));
1118 let admin = actions(vec![Scope::ArtifactsAdmin]).unwrap();
1119 assert_eq!(admin.as_array().unwrap().len(), Tool::by_name("artifact").unwrap().actions.len());
1120 // Without an artifacts scope there is no artifact tool at all.
1121 assert_eq!(actions(vec![Scope::WorkflowsWrite, Scope::IssuesWrite]), None);
1122 // And an artifacts scope shows nothing of workflow runs' artifacts.
1123 let access = token(Some(vec![Scope::ArtifactsAdmin]));
1124 assert!(Tool::by_name("workflow").unwrap().listed(&Gate::Token(&access)).is_none());
1125 // The read-only and agent presets read artifacts and change none.
1126 for preset in [Preset::ReadOnly, Preset::Agent] {
1127 let access = token(preset.scopes());
1128 let tool = Tool::by_name("artifact").unwrap().listed(&Gate::Token(&access)).unwrap();
1129 assert_eq!(tool["inputSchema"]["properties"]["action"]["enum"], reads, "{}", preset.as_str());
1130 assert_eq!(tool["annotations"]["readOnlyHint"], true);
1131 }
1132 // Sharing and deleting for good can't be undone the same way.
1133 let tools = listed(&Gate::Everything);
1134 let artifact = tools.iter().find(|tool| tool["name"] == "artifact").unwrap();
1135 assert_eq!(artifact["annotations"]["destructiveHint"], true);
1136 assert!(artifact["description"].as_str().unwrap().contains("Not the `workflow` tool's run artifacts"));
1137 let tool = Tool::by_name("artifact").unwrap();
1138 assert_eq!(resolve(tool, &json!({ "action": "read", "workspace": "acme" })), Err("artifact.read needs artifact_id.".to_owned()));
1139 assert_eq!(
1140 resolve(tool, &json!({ "action": "edit", "workspace": "acme", "artifact_id": "fol_1", "markdown": "x" })),
1141 Ok(Op::Folios(FoliosOp::Edit))
1142 );
1143 }
1144
1145 /// How much smaller `tools/list` is than one tool per operation. Run
1146 /// with `--nocapture` to see the numbers.
1147 #[test]
1148 fn the_tool_list_is_much_smaller_than_one_tool_per_operation() {
1149 let before: Vec<Value> = Op::ALL
1150 .into_iter()
1151 .map(|op| json!({ "name": op.name(), "description": op.description(), "inputSchema": op.input() }))
1152 .collect();
1153 let after = listed(&Gate::Everything);
1154 let before_bytes = serde_json::to_string(&json!({ "tools": before })).unwrap().len();
1155 let after_bytes = serde_json::to_string(&json!({ "tools": after })).unwrap().len();
1156 let agent = token(Preset::Agent.scopes());
1157 let agent_bytes = serde_json::to_string(&json!({ "tools": listed(&Gate::Token(&agent)) })).unwrap().len();
1158 let read = token(Preset::ReadOnly.scopes());
1159 let read_bytes = serde_json::to_string(&json!({ "tools": listed(&Gate::Token(&read)) })).unwrap().len();
1160 println!(
1161 "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)",
1162 before.len(),
1163 before_bytes / 4,
1164 after.len(),
1165 after_bytes / 4,
1166 agent_bytes / 4,
1167 read_bytes / 4,
1168 );
1169 assert!(after_bytes * 2 < before_bytes, "{after_bytes} vs {before_bytes}");
1170 }
1171}