refactor(actions): type consolidated MCP tools

README.md

@@ -616,13 +616,17 @@ The following sets of tools are available:
 
 ## Tools
 
-Repository tools expose output schemas and typed `structuredContent` to clients using MCP protocol `2026-07-28` or later. Older clients, or clients with an unknown protocol version, receive the existing content without an output schema or structured output.
+Repository tools expose output schemas and typed `structuredContent` when the negotiated MCP protocol version is a supported version `2026-07-28` or newer. Older clients, clients with an unknown protocol version, and clients omitting the version receive the existing content without an output schema or structured output. Unknown versions are not treated as supported merely because they sort after `2026-07-28`.
 
 For `get_file_contents`, directory results (including field projections) are structured arrays. File downloads and metadata-only responses use a `content` array of typed text, embedded-resource, or resource-link blocks, preserving status messages, text, base64 blobs, empty files, and download links. Text-only repository mutations such as starring and deletion also return a structured `message`; fork responses distinguish a repository reference from an in-progress message. Repository deletion still requires its existing confirmation flow before returning a completed result.
 
 Structured repository results use compact DTOs rather than raw REST objects. Release lookups share the compact release shape with release listings; Git references retain the ref, object type, and SHA; annotated tags retain tag/message/tagger/target information; deletion commits retain SHA, message, authors, tree SHA, parent SHAs, and a human-facing `html_url` when available. Directory entries retain file metadata and useful HTML/download links, but omit API and hypermedia routing URLs even when those fields were requested in a projection. Legacy and unknown protocol versions retain the original text byte-for-byte; modern text-only JSON responses serialize the same compact DTO as `structuredContent`. Non-text resource blocks and tool errors retain their existing content behavior. Structured projections use the same sanitized and filtered source as the legacy formatter.
 
-The issue metadata (`list_issue_types`, `list_issue_fields`), comment (`add_issue_comment`, `update_issue_comment`), dependency (`issue_dependency_read`, `issue_dependency_write`), and duplicate-detection (`find_duplicate`) tools provide typed `outputSchema` and `structuredContent` for protocol `2026-07-28` and newer. Older or unknown protocol versions retain the same text responses without these fields. Tool errors do not return structured content. Dependency and duplicate-detection tools retain their existing feature gates.
+For `get_repository_tree`, `list_gists`, `get_gist`, `create_gist`, and `update_gist`, gist results retain file names, contents, sizes, language/type information, timestamps, visibility, and compact owner profiles, while omitting API/node and Git transport URLs. Tree entries omit their derivable API URLs. Create/update gist results contain the gist ID and HTML URL. Modern JSON text and structured content serialize the same compact result. Older or unknown protocol versions retain byte-for-byte legacy text without an output schema or structured content.
+
+The issue metadata (`list_issue_types`, `list_issue_fields`), comment (`add_issue_comment`, `update_issue_comment`), dependency (`issue_dependency_read`, `issue_dependency_write`), and duplicate-detection (`find_duplicate`) tools provide typed `outputSchema` and `structuredContent` for negotiated supported protocol versions `2026-07-28` or newer. Older or unknown protocol versions retain the same text responses without these fields. Tool errors do not return structured content. Dependency and duplicate-detection tools retain their existing feature gates.
+
+For negotiated supported protocol versions `2026-07-28` or newer, the consolidated Actions tools (`actions_list`, `actions_get`, `actions_run_trigger`) return structured objects with a `method` discriminant and a method-specific typed field; JSON text contains the same compact projection. Workflow, job, and artifact projections omit API/hypermedia URLs while retaining browser links and useful identifiers, states, timestamps, and usage durations. Run usage lists billable runner environments in deterministic name order. Older and unknown-protocol text responses remain unchanged; `get_job_logs` retains its typed content, URL, or failed-job collection variants.
 
 <!-- START AUTOMATED TOOLS -->
 <details>

docs/error-handling.md

@@ -60,10 +60,12 @@ return ghErrors.NewGitHubGraphQLErrorResponse(ctx, message, err), nil
 ### Typed Tool Results
 
 Tools registered with concrete `NewTool[In, Out]` types expose output schemas and
-`structuredContent` only when the negotiated protocol is `2026-07-28` or newer.
-Older or unknown protocols retain the original text responses without these
-typed-output additions. Ordinary API and validation errors never expose the
-SDK-generated zero-value structured output.
+`structuredContent` when the negotiated protocol version is a supported version
+`2026-07-28` or newer. Older, unknown, or omitted protocol versions retain the
+original text responses without these typed-output additions. Unknown versions
+are not treated as supported merely because they sort after `2026-07-28`.
+Ordinary API and validation errors never expose the SDK-generated zero-value
+structured output.
 
 Handler-provided structured statuses are distinct from generated error output.
 For example, `issue_write` can return `IsError: true` with

docs/feature-flags.md

@@ -237,23 +237,23 @@ as output formatting) won't appear here.
   - `path`: The relative path of the file to comment on (string, required)
   - `pullNumber`: The pull request number (number, required)
   - `repo`: Repository name (string, required)
-  - `side`: The side of the diff to comment on (LEFT or RIGHT, optional) (string, optional)
+  - `side`: The side of the diff to comment on (optional) (string, optional)
   - `startLine`: The start line of a multi-line comment (optional) (number, optional)
-  - `startSide`: The start side of a multi-line comment (LEFT or RIGHT, optional) (string, optional)
-  - `subjectType`: The subject type of the comment (FILE or LINE) (string, required)
+  - `startSide`: The start side of a multi-line comment (optional) (string, optional)
+  - `subjectType`: The subject type of the comment (string, required)
 
 - **add_pull_request_review_comment_reaction** - Add Pull Request Review Comment Reaction
   - **OAuth Challenge Scopes**: `repo`
   - `comment_id`: The numeric pull request review comment ID. Use the number from a #discussion_r... anchor, not the GraphQL thread node ID (PRRT_...). (number, required)
-  - `content`: The emoji reaction type (+1, -1, laugh, confused, heart, hooray, rocket, or eyes) (string, required)
+  - `content`: The emoji reaction type (string, required)
   - `owner`: Repository owner (username or organization) (string, required)
   - `repo`: Repository name (string, required)
 
 - **create_pull_request_review** - Create Pull Request Review
   - **OAuth Challenge Scopes**: `repo`
   - `body`: The review body text (optional) (string, optional)
   - `commitID`: The SHA of the commit to review (optional, defaults to latest) (string, optional)
-  - `event`: The review action to perform (APPROVE, REQUEST_CHANGES, or COMMENT). If omitted, creates a pending review. (string, optional)
+  - `event`: The review action to perform. If omitted, creates a pending review. (string, optional)
   - `owner`: Repository owner (username or organization) (string, required)
   - `pullNumber`: The pull request number (number, required)
   - `repo`: Repository name (string, required)
@@ -300,7 +300,7 @@ as output formatting) won't appear here.
 - **submit_pending_pull_request_review** - Submit Pending Pull Request Review
   - **OAuth Challenge Scopes**: `repo`
   - `body`: The review body text (optional) (string, optional)
-  - `event`: The review action to perform (APPROVE, REQUEST_CHANGES, or COMMENT) (string, required)
+  - `event`: The review action to perform (string, required)
   - `owner`: Repository owner (username or organization) (string, required)
   - `pullNumber`: The pull request number (number, required)
   - `repo`: Repository name (string, required)
@@ -341,7 +341,7 @@ as output formatting) won't appear here.
   - `owner`: Repository owner (username or organization) (string, required)
   - `pullNumber`: The pull request number (number, required)
   - `repo`: Repository name (string, required)
-  - `state`: The new state for the pull request (open or closed) (string, required)
+  - `state`: The new state for the pull request (string, required)
 
 - **update_pull_request_title** - Update Pull Request Title
   - **OAuth Challenge Scopes**: `repo`
@@ -402,8 +402,8 @@ as output formatting) won't appear here.
   - `confidence_threshold`: Minimum similarity threshold a candidate must meet to be returned; higher values are stricter. When omitted, the API's high-precision default is used. The scale is defined by the API, so no client-side bounds are enforced. (number, optional)
   - `issue_number`: The number of the existing issue to find duplicates for (number, required)
   - `owner`: The owner of the repository (string, required)
-  - `page`: Page number for pagination (min 1). An explicit 0 is forwarded to the API as-is rather than being replaced with 1. (number, optional)
-  - `perPage`: Results per page for pagination (min 1, max 100). An explicit 0 is forwarded to the API as-is rather than being replaced with 30. (number, optional)
+  - `page`: Page number for pagination (min 1) (number, optional)
+  - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: The name of the repository (string, required)
 
 ### `thread_resolution_reason`

docs/typed-tool-schemas.md

@@ -1,9 +1,9 @@
 # Typed tool schemas
 
 Typed tool registrations use concrete Go input and output types with the MCP
-Go SDK's `mcp.AddTool` path. The SDK infers schemas when the tool definition
-does not provide them, validates arguments before the handler runs, and
-validates typed output. Keep business rules that JSON Schema cannot express
+Go SDK's `mcp.AddTool` path. Inventory infers missing schemas and validates
+arguments against the cached input schema before the handler runs; the SDK
+adapts and validates typed output. Keep business rules that JSON Schema cannot express
 in the handler or a preflight callback.
 
 Input inference unwraps one pointer level, matching the SDK's object input
@@ -31,13 +31,13 @@ schemas; do not mutate the returned pointers.
 
 When compatibility requires a broader runtime input contract than the one
 advertised to clients, provide `ValidationInputSchema`. The tool's declared
-`InputSchema` remains visible while the SDK validates calls against the
+`InputSchema` remains visible while inventory validates calls against the
 runtime-only schema. Use `Preflight` for checks that need raw arguments or
 request dependencies before typed decoding; it may return a derived context
 for the handler. Input normalizers are only for compatibility transformations,
 not a replacement for schema validation.
 
-The SDK applies defaults from the runtime input schema before decoding. If an
+Inventory applies defaults from the runtime input schema before decoding. If an
 omitted field must remain omitted, build the runtime schema with
 `inventory.CloneSchemaWithoutDefaults` before applying validation-only
 changes. Use `inventory.CloneSchema` when deriving other runtime-only schema
@@ -46,6 +46,14 @@ subschemas. Default removal visits each child once per parent. The advertised
 schema can retain its defaults; the constructor caches the runtime schema
 without mutating either caller-owned schema.
 
+Availability and authorization guards run before preflight, normalization,
+and input validation. A guard or preflight result is passed through the
+registered SDK handler without decoding the original arguments or invoking
+user code, so the SDK still finalizes multi-round-trip results with
+`resultType: "input_required"` (or `"complete"`). The permissive SDK input
+envelope used for this handoff is never advertised and does not replace the
+original validation schema for real calls.
+
 The output schema and `structuredContent` are exposed only for a negotiated,
 SDK-supported protocol version `2026-07-28` or later. Unknown versions are
 treated as legacy, including unsupported future dates; older, absent, and
@@ -58,4 +66,7 @@ request-scoped server.
 If a handler intentionally returns non-JSON text or content blocks, set
 `PreserveHandlerContent` in `TypedSchemaOptions`, or call
 `inventory.PreserveToolHandlerContent(ctx)` from the handler middleware for
-request-dependent output such as CSV.
+request-dependent output such as CSV. This is for intentional non-DTO responses
+such as resources, errors, or CSV; ordinary declared structured success must
+retain shared DTO serialization, with modern JSON text equal to
+`structuredContent`, even when legacy handler text was a plain mutation message.

go.mod

@@ -12,6 +12,7 @@ require (
 	github.com/microcosm-cc/bluemonday v1.0.27
 	github.com/modelcontextprotocol/go-sdk v1.8.0
 	github.com/muesli/cache2go v0.0.0-20221011235721-518229cd8021
+	github.com/segmentio/encoding v0.5.4
 	github.com/shurcooL/githubv4 v0.0.0-20260209031235-2402fdf4a9ed
 	github.com/shurcooL/graphql v0.0.0-20240915155400-7ee5256398cf
 	github.com/spf13/cobra v1.10.2
@@ -32,7 +33,6 @@ require (
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
 	github.com/sagikazarmark/locafero v0.11.0 // indirect
 	github.com/segmentio/asm v1.1.3 // indirect
-	github.com/segmentio/encoding v0.5.4 // indirect
 	github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect