Add Action Gateway TypeScript SDK surface

[tgillam-do]

Summary

• add the Action Gateway TypeScript SDK surface and MCP JSON-RPC transport
• support typed session policies, tool selection, config, approvals, and returned mcpUrl values
• expose Toolbelts through the generated DigitalOcean public API client at /v2/toolbelts
• preserve MCP approval metadata for direct and batched tool failures

Backend contract alignment

• sends actor_id, name, typed policy, optional tools, and optional config
• defaults the session policy to ask
• distinguishes omitted tools (all tools) from tools: [] (no tools)
• uses MCP protocol 2025-06-18 with X-Session-Id and X-Actor-Id
• approves or denies through POST /approvals/{id} and supports retrying the tool call
• identifies action-code execution as execute_code
• supports pinned Toolbelt references such as toolbelt:name@1

Validation

• npm run build
• npm run lint (one pre-existing unused eslint-disable warning)
• npm run test:mock (26 suites, 180 tests)
• git diff --check

[Copilot]

Pull request overview

Adds a new Action Gateway TypeScript SDK surface to the @digitalocean/dots package, including session creation, tool discovery/invocation helpers across multiple inference “tool” formats, and a generated Toolbelts CRUD surface wired into the existing Kiota-based DO API client.

Changes:

• Introduces ActionGatewayClient with session lifecycle, tool listing/search/invoke helpers, and provider adapters for Chat Completions / Messages / Responses tool formats.
• Adds generated v2.toolbelts request builders and associated model types/serializers to the DO API SDK.
• Adds docs, examples, and mocked tests covering session creation, gateway invocation, tool formatting, and toolbelt operations.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/mocked/action-gateway.test.ts	Adds mocked Jest/Nock coverage for Action Gateway sessions, tool invocation, tool formatting, and toolbelt CRUD wiring.
src/action-gateway/index.ts	Implements the Action Gateway SDK client, providers, session management, tool operations, and a createToolbelt convenience wrapper.
src/dots/v2/toolbelts/index.ts	Adds generated request builder for /v2/toolbelts list/create + navigation to item operations.
src/dots/v2/toolbelts/item/index.ts	Adds generated request builder for /v2/toolbelts/{name} get/delete + navigation to tools subresource.
src/dots/v2/toolbelts/item/tools/index.ts	Adds generated navigation request builder for /v2/toolbelts/{name}/tools with add/remove children.
src/dots/v2/toolbelts/item/tools/add/index.ts	Adds generated POST request builder for adding tools to a toolbelt version.
src/dots/v2/toolbelts/item/tools/remove/index.ts	Adds generated POST request builder for removing tools from a toolbelt version.
src/dots/v2/index.ts	Exposes the new toolbelts navigation property on the v2 request builder.
src/dots/models/index.ts	Adds toolbelt-related models + (de)serialization helpers used by the generated builders.
src/dots/kiota-lock.json	Updates Kiota lock hash to reflect spec/client generation changes.
README.md	Documents the new @digitalocean/dots/action_gateway entrypoint and pointers to docs/examples.
package.json	Exports ./action_gateway subpath to the Action Gateway SDK entry.
docs/action-gateway.md	Adds an Action Gateway guide covering sessions, tool invocation, and toolbelts.
examples/action-gateway/*.ts	Adds runnable examples for chat completions, messages, responses, direct tools, async usage, and toolbelt policy flows.

Comments suppressed due to low confidence (3)

src/action-gateway/index.ts:381

• GatewayTransport currently calls requestJSON with the API key, which means Gateway REST calls will include the bearer token (in addition to the session/actor headers). If the gateway domain only needs X-Session-Id/X-Actor-Id (as described in docs), omit Authorization for these requests.

class GatewayTransport {
    public readonly sessionId: string;

    public constructor(
        private readonly apiKey: string,

src/action-gateway/index.ts:592

• After removing the API key from GatewayTransport, update the constructor call accordingly.

        const transport = new GatewayTransport(this.apiKey, this.gatewayBaseURL, sessionUrn, actorId);

src/action-gateway/index.ts:459

• The META_INVOKE tool schema uses tool_slug, but ToolsOperations.invoke() only checks tool and toolSlug. If a model follows the provided schema and sends tool_slug, this will currently throw "each invoke entry requires tool".

        const normalized = tools.map((tool) => {
            const name = tool.tool ?? tool.toolSlug;
            if (!name) throw new Error("each invoke entry requires tool");
            return { tool: name, arguments: tool.arguments ?? {} };

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.