Typescript SDK for ACP extension methods (#7319)

This commit is contained in:
Jack Amadeo
2026-02-18 21:08:26 -05:00
committed by GitHub
parent 4b3eef0c9a
commit f425ea7474
23 changed files with 3740 additions and 34 deletions
+230
View File
@@ -0,0 +1,230 @@
#!/usr/bin/env node
/**
* Generates TypeScript types + Zod validators for Goose custom extension methods.
*
* Usage:
* npm run generate # build Rust schema, then generate TS
*/
import { createClient } from "@hey-api/openapi-ts";
import { execSync } from "child_process";
import * as fs from "fs/promises";
import { dirname, resolve } from "path";
import { fileURLToPath } from "url";
import * as prettier from "prettier";
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const ROOT = resolve(__dirname, "../..");
const SCHEMA_PATH = resolve(ROOT, "crates/goose-acp/acp-schema.json");
const META_PATH = resolve(ROOT, "crates/goose-acp/acp-meta.json");
const OUTPUT_DIR = resolve(__dirname, "src/generated");
main().catch((err) => {
console.error(err);
process.exit(1);
});
async function main() {
const schemaSrc = await fs.readFile(SCHEMA_PATH, "utf8");
const jsonSchema = JSON.parse(
// Convert JSON Schema $defs refs to OpenAPI component refs
schemaSrc.replaceAll("#/$defs/", "#/components/schemas/"),
);
const metaSrc = await fs.readFile(META_PATH, "utf8");
const meta = JSON.parse(metaSrc);
await createClient({
input: {
openapi: "3.1.0",
info: {
title: "Goose Extensions",
version: "1.0.0",
},
components: {
schemas: jsonSchema.$defs,
},
},
output: {
path: OUTPUT_DIR,
},
plugins: ["zod", "@hey-api/typescript"],
});
await postProcessTypes();
await postProcessIndex(meta);
await generateClient(meta);
console.log(`\nGenerated Goose extension schema in ${OUTPUT_DIR}`);
}
async function postProcessTypes() {
const tsPath = resolve(OUTPUT_DIR, "types.gen.ts");
let src = await fs.readFile(tsPath, "utf8");
// Remove the ClientOptions type block injected by @hey-api (not part of our schema)
src = src.replace(/\nexport type ClientOptions =[\s\S]*?^};\n/m, "\n");
await fs.writeFile(tsPath, src);
}
async function postProcessIndex(meta: { methods: unknown[] }) {
const indexPath = resolve(OUTPUT_DIR, "index.ts");
let src = await fs.readFile(indexPath, "utf8");
// Strip ClientOptions from re-exports
src = src.replace(/,?\s*ClientOptions\s*,?/g, (match) => {
if (match.startsWith(",") && match.endsWith(",")) return ",";
if (match.startsWith(",")) return "";
return "";
});
// Fix bare relative imports to use .js extensions (required by nodenext consumers)
src = fixRelativeImports(src);
// Append method constants
const methodConstants = await prettier.format(
`
export const GOOSE_EXT_METHODS = ${JSON.stringify(meta.methods, null, 2)} as const;
export type GooseExtMethod = (typeof GOOSE_EXT_METHODS)[number];
`,
{ parser: "typescript" },
);
await fs.writeFile(indexPath, `${src}\n${methodConstants}`);
// Also fix imports in zod.gen.ts (it may import from types.gen)
for (const file of ["zod.gen.ts", "types.gen.ts"]) {
const filePath = resolve(OUTPUT_DIR, file);
try {
const content = await fs.readFile(filePath, "utf8");
const fixed = fixRelativeImports(content);
if (fixed !== content) {
await fs.writeFile(filePath, fixed);
}
} catch {
// File may not exist
}
}
}
function fixRelativeImports(src: string): string {
return src.replace(
/from\s+['"](\.[^'"]+)['"]/g,
(_match, importPath: string) => {
if (importPath.endsWith(".js") || importPath.endsWith(".json")) {
return `from '${importPath}'`;
}
return `from '${importPath}.js'`;
},
);
}
interface MethodMeta {
method: string;
requestType: string | null;
responseType: string | null;
}
/**
* Convert a method path like "session/list" or "working_dir/update" to camelCase "sessionList", "workingDirUpdate".
*/
function methodToCamelCase(method: string): string {
return method
.split(/[/_]/)
.map((part, i) =>
i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1),
)
.join("");
}
/**
* Generate a typed GooseClient class that wraps ClientSideConnection.extMethod()
* with proper TypeScript types and Zod runtime validation.
*/
async function generateClient(meta: { methods: MethodMeta[] }) {
const typeImports = new Set<string>();
const zodImports = new Set<string>();
const methodDefs: string[] = [];
for (const m of meta.methods) {
const fnName = methodToCamelCase(m.method);
const fullMethod = `_goose/${m.method}`;
// Build param type and arg
let paramType = "";
let paramArg = "";
let callParams = "{}";
if (m.requestType) {
typeImports.add(m.requestType);
paramType = m.requestType;
paramArg = `params: ${paramType}`;
callParams = "params";
}
// Build return type and validation
let returnType: string;
let bodyLines: string[];
if (m.responseType && m.responseType !== "EmptyResponse") {
typeImports.add(m.responseType);
const zodName = `z${m.responseType}`;
zodImports.add(zodName);
returnType = m.responseType;
bodyLines = [
`const raw = await this.conn.extMethod("${fullMethod}", ${callParams});`,
`return ${zodName}.parse(raw) as ${returnType};`,
];
} else if (m.responseType === "EmptyResponse") {
returnType = "void";
bodyLines = [
`await this.conn.extMethod("${fullMethod}", ${callParams});`,
];
} else {
// Both request and response are untyped (serde_json::Value)
returnType = "Record<string, unknown>";
bodyLines = [
`return await this.conn.extMethod("${fullMethod}", ${callParams ? callParams : "{}"});`,
];
}
methodDefs.push(`
async ${fnName}(${paramArg}): Promise<${returnType}> {
${bodyLines.join("\n ")}
}`);
}
const typeImportLine = typeImports.size
? `import type { ${[...typeImports].sort().join(", ")} } from "./types.gen.js";`
: "";
const zodImportLine = zodImports.size
? `import { ${[...zodImports].sort().join(", ")} } from "./zod.gen.js";`
: "";
let src = `// This file is auto-generated — do not edit manually.
export interface ExtMethodProvider {
extMethod(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
}
${typeImportLine}
${zodImportLine}
/**
* Typed client for Goose custom extension methods.
* Wraps an ExtMethodProvider (e.g. ClientSideConnection) with proper types and Zod validation.
*/
export class GooseClient {
constructor(private conn: ExtMethodProvider) {}
${methodDefs.join("\n")}
}
`;
src = await prettier.format(src, { parser: "typescript" });
src = fixRelativeImports(src);
const clientPath = resolve(OUTPUT_DIR, "client.gen.ts");
await fs.writeFile(clientPath, src);
}
+1277
View File
File diff suppressed because it is too large Load Diff
+26
View File
@@ -0,0 +1,26 @@
{
"name": "goose-acp-types",
"version": "0.1.0",
"private": true,
"type": "module",
"main": "./src/index.ts",
"types": "./src/index.ts",
"scripts": {
"generate": "tsx generate-schema.ts",
"lint": "tsc --noEmit",
"format": "prettier --write src/"
},
"dependencies": {
"zod": "^3.25.76"
},
"peerDependencies": {
"@agentclientprotocol/sdk": "*"
},
"devDependencies": {
"@agentclientprotocol/sdk": "^0.14.1",
"@hey-api/openapi-ts": "^0.92.3",
"prettier": "^3.8.1",
"tsx": "^4.21.0",
"typescript": "~5.9.3"
}
}
+129
View File
@@ -0,0 +1,129 @@
// This file is auto-generated — do not edit manually.
export interface ExtMethodProvider {
extMethod(
method: string,
params: Record<string, unknown>,
): Promise<Record<string, unknown>>;
}
import type {
AddExtensionRequest,
DeleteSessionRequest,
ExportSessionRequest,
ExportSessionResponse,
GetExtensionsResponse,
GetSessionRequest,
GetSessionResponse,
GetToolsRequest,
GetToolsResponse,
ImportSessionRequest,
ImportSessionResponse,
ListSessionsResponse,
ReadResourceRequest,
ReadResourceResponse,
RemoveExtensionRequest,
UpdateWorkingDirRequest,
} from './types.gen.js';
import {
zExportSessionResponse,
zGetExtensionsResponse,
zGetSessionResponse,
zGetToolsResponse,
zImportSessionResponse,
zListSessionsResponse,
zReadResourceResponse,
} from './zod.gen.js';
/**
* Typed client for Goose custom extension methods.
* Wraps an ExtMethodProvider (e.g. ClientSideConnection) with proper types and Zod validation.
*/
export class GooseClient {
constructor(private conn: ExtMethodProvider) {}
async extensionsAdd(params: AddExtensionRequest): Promise<void> {
await this.conn.extMethod("_goose/extensions/add", params);
}
async extensionsRemove(params: RemoveExtensionRequest): Promise<void> {
await this.conn.extMethod("_goose/extensions/remove", params);
}
async tools(params: GetToolsRequest): Promise<GetToolsResponse> {
const raw = await this.conn.extMethod("_goose/tools", params);
return zGetToolsResponse.parse(raw) as GetToolsResponse;
}
async resourceRead(
params: ReadResourceRequest,
): Promise<ReadResourceResponse> {
const raw = await this.conn.extMethod("_goose/resource/read", params);
return zReadResourceResponse.parse(raw) as ReadResourceResponse;
}
async workingDirUpdate(params: UpdateWorkingDirRequest): Promise<void> {
await this.conn.extMethod("_goose/working_dir/update", params);
}
async sessionList(): Promise<ListSessionsResponse> {
const raw = await this.conn.extMethod("_goose/session/list", {});
return zListSessionsResponse.parse(raw) as ListSessionsResponse;
}
async sessionGet(params: GetSessionRequest): Promise<GetSessionResponse> {
const raw = await this.conn.extMethod("_goose/session/get", params);
return zGetSessionResponse.parse(raw) as GetSessionResponse;
}
async sessionDelete(params: DeleteSessionRequest): Promise<void> {
await this.conn.extMethod("_goose/session/delete", params);
}
async sessionExport(
params: ExportSessionRequest,
): Promise<ExportSessionResponse> {
const raw = await this.conn.extMethod("_goose/session/export", params);
return zExportSessionResponse.parse(raw) as ExportSessionResponse;
}
async sessionImport(
params: ImportSessionRequest,
): Promise<ImportSessionResponse> {
const raw = await this.conn.extMethod("_goose/session/import", params);
return zImportSessionResponse.parse(raw) as ImportSessionResponse;
}
async configExtensions(): Promise<GetExtensionsResponse> {
const raw = await this.conn.extMethod("_goose/config/extensions", {});
return zGetExtensionsResponse.parse(raw) as GetExtensionsResponse;
}
async toolCall(): Promise<Record<string, unknown>> {
return await this.conn.extMethod("_goose/tool/call", {});
}
async providerUpdate(): Promise<Record<string, unknown>> {
return await this.conn.extMethod("_goose/provider/update", {});
}
async containerSet(): Promise<Record<string, unknown>> {
return await this.conn.extMethod("_goose/container/set", {});
}
async appsList(): Promise<Record<string, unknown>> {
return await this.conn.extMethod("_goose/apps/list", {});
}
async appsExport(): Promise<Record<string, unknown>> {
return await this.conn.extMethod("_goose/apps/export", {});
}
async appsImport(): Promise<Record<string, unknown>> {
return await this.conn.extMethod("_goose/apps/import", {});
}
async configProviders(): Promise<Record<string, unknown>> {
return await this.conn.extMethod("_goose/config/providers", {});
}
}
+98
View File
@@ -0,0 +1,98 @@
// This file is auto-generated by @hey-api/openapi-ts
export type { AddExtensionRequest, DeleteSessionRequest, EmptyResponse, ExportSessionRequest, ExportSessionResponse, ExtRequest, ExtResponse, GetExtensionsResponse, GetSessionRequest, GetSessionResponse, GetToolsRequest, GetToolsResponse, ImportSessionRequest, ImportSessionResponse, ListSessionsResponse, ReadResourceRequest, ReadResourceResponse, RemoveExtensionRequest, UpdateWorkingDirRequest } from './types.gen.js';
export const GOOSE_EXT_METHODS = [
{
method: "extensions/add",
requestType: "AddExtensionRequest",
responseType: "EmptyResponse",
},
{
method: "extensions/remove",
requestType: "RemoveExtensionRequest",
responseType: "EmptyResponse",
},
{
method: "tools",
requestType: "GetToolsRequest",
responseType: "GetToolsResponse",
},
{
method: "resource/read",
requestType: "ReadResourceRequest",
responseType: "ReadResourceResponse",
},
{
method: "working_dir/update",
requestType: "UpdateWorkingDirRequest",
responseType: "EmptyResponse",
},
{
method: "session/list",
requestType: null,
responseType: "ListSessionsResponse",
},
{
method: "session/get",
requestType: "GetSessionRequest",
responseType: "GetSessionResponse",
},
{
method: "session/delete",
requestType: "DeleteSessionRequest",
responseType: "EmptyResponse",
},
{
method: "session/export",
requestType: "ExportSessionRequest",
responseType: "ExportSessionResponse",
},
{
method: "session/import",
requestType: "ImportSessionRequest",
responseType: "ImportSessionResponse",
},
{
method: "config/extensions",
requestType: null,
responseType: "GetExtensionsResponse",
},
{
method: "tool/call",
requestType: null,
responseType: null,
},
{
method: "provider/update",
requestType: null,
responseType: null,
},
{
method: "container/set",
requestType: null,
responseType: null,
},
{
method: "apps/list",
requestType: null,
responseType: null,
},
{
method: "apps/export",
requestType: null,
responseType: null,
},
{
method: "apps/import",
requestType: null,
responseType: null,
},
{
method: "config/providers",
requestType: null,
responseType: null,
},
] as const;
export type GooseExtMethod = (typeof GOOSE_EXT_METHODS)[number];
+165
View File
@@ -0,0 +1,165 @@
// This file is auto-generated by @hey-api/openapi-ts
/**
* Add an extension to an active session.
* Method: `_agent/extensions/add`
*/
export type AddExtensionRequest = {
session_id: string;
/**
* Extension configuration (see ExtensionConfig variants: Stdio, StreamableHttp, Builtin, Platform).
*/
config: unknown;
};
/**
* Empty success response for operations that return no data.
*/
export type EmptyResponse = {
[key: string]: unknown;
};
/**
* Remove an extension from an active session.
* Method: `_agent/extensions/remove`
*/
export type RemoveExtensionRequest = {
session_id: string;
name: string;
};
/**
* List all tools available in a session.
* Method: `_agent/tools`
*/
export type GetToolsRequest = {
session_id: string;
};
export type GetToolsResponse = {
/**
* Array of tool info objects with `name`, `description`, `parameters`, and optional `permission`.
*/
tools: Array<unknown>;
};
/**
* Read a resource from an extension.
* Method: `_agent/resource/read`
*/
export type ReadResourceRequest = {
session_id: string;
uri: string;
extension_name: string;
};
export type ReadResourceResponse = {
/**
* The resource result from the extension (MCP ReadResourceResult).
*/
result: unknown;
};
/**
* Update the working directory for a session.
* Method: `_agent/working_dir/update`
*/
export type UpdateWorkingDirRequest = {
session_id: string;
working_dir: string;
};
/**
* List all sessions.
* Method: `_session/list`
*/
export type ListSessionsResponse = {
sessions: Array<unknown>;
};
/**
* Get a session by ID.
* Method: `_session/get`
*/
export type GetSessionRequest = {
session_id: string;
include_messages?: boolean;
};
/**
* Get a session response.
*/
export type GetSessionResponse = {
/**
* The session object with id, name, working_dir, timestamps, tokens, etc.
*/
session: unknown;
};
/**
* Delete a session.
* Method: `_session/delete`
*/
export type DeleteSessionRequest = {
session_id: string;
};
/**
* Export a session as a JSON string.
* Method: `_session/export`
*/
export type ExportSessionRequest = {
session_id: string;
};
export type ExportSessionResponse = {
data: string;
};
/**
* Import a session from a JSON string.
* Method: `_session/import`
*/
export type ImportSessionRequest = {
data: string;
};
export type ImportSessionResponse = {
/**
* The imported session object.
*/
session: unknown;
};
/**
* List configured extensions and any warnings.
* Method: `_config/extensions`
*/
export type GetExtensionsResponse = {
/**
* Array of ExtensionEntry objects with `enabled` flag and config details.
*/
extensions: Array<unknown>;
warnings: Array<string>;
};
export type ExtRequest = {
id: string;
method: string;
params?: AddExtensionRequest | RemoveExtensionRequest | GetToolsRequest | ReadResourceRequest | UpdateWorkingDirRequest | GetSessionRequest | DeleteSessionRequest | ExportSessionRequest | ImportSessionRequest | {
[key: string]: unknown;
} | null;
};
export type ExtResponse = {
id: string;
result?: EmptyResponse | GetToolsResponse | ReadResourceResponse | ListSessionsResponse | GetSessionResponse | ExportSessionResponse | ImportSessionResponse | GetExtensionsResponse | unknown;
} | {
error: {
code: number;
message: string;
data?: unknown;
};
id: string;
};
+175
View File
@@ -0,0 +1,175 @@
// This file is auto-generated by @hey-api/openapi-ts
import { z } from 'zod';
/**
* Add an extension to an active session.
* Method: `_agent/extensions/add`
*/
export const zAddExtensionRequest = z.object({
session_id: z.string(),
config: z.unknown()
});
/**
* Empty success response for operations that return no data.
*/
export const zEmptyResponse = z.record(z.unknown());
/**
* Remove an extension from an active session.
* Method: `_agent/extensions/remove`
*/
export const zRemoveExtensionRequest = z.object({
session_id: z.string(),
name: z.string()
});
/**
* List all tools available in a session.
* Method: `_agent/tools`
*/
export const zGetToolsRequest = z.object({
session_id: z.string()
});
export const zGetToolsResponse = z.object({
tools: z.array(z.unknown())
});
/**
* Read a resource from an extension.
* Method: `_agent/resource/read`
*/
export const zReadResourceRequest = z.object({
session_id: z.string(),
uri: z.string(),
extension_name: z.string()
});
export const zReadResourceResponse = z.object({
result: z.unknown()
});
/**
* Update the working directory for a session.
* Method: `_agent/working_dir/update`
*/
export const zUpdateWorkingDirRequest = z.object({
session_id: z.string(),
working_dir: z.string()
});
/**
* List all sessions.
* Method: `_session/list`
*/
export const zListSessionsResponse = z.object({
sessions: z.array(z.unknown())
});
/**
* Get a session by ID.
* Method: `_session/get`
*/
export const zGetSessionRequest = z.object({
session_id: z.string(),
include_messages: z.boolean().optional().default(false)
});
/**
* Get a session response.
*/
export const zGetSessionResponse = z.object({
session: z.unknown()
});
/**
* Delete a session.
* Method: `_session/delete`
*/
export const zDeleteSessionRequest = z.object({
session_id: z.string()
});
/**
* Export a session as a JSON string.
* Method: `_session/export`
*/
export const zExportSessionRequest = z.object({
session_id: z.string()
});
export const zExportSessionResponse = z.object({
data: z.string()
});
/**
* Import a session from a JSON string.
* Method: `_session/import`
*/
export const zImportSessionRequest = z.object({
data: z.string()
});
export const zImportSessionResponse = z.object({
session: z.unknown()
});
/**
* List configured extensions and any warnings.
* Method: `_config/extensions`
*/
export const zGetExtensionsResponse = z.object({
extensions: z.array(z.unknown()),
warnings: z.array(z.string())
});
export const zExtRequest = z.object({
id: z.string(),
method: z.string(),
params: z.union([
z.union([
zAddExtensionRequest,
zRemoveExtensionRequest,
zGetToolsRequest,
zReadResourceRequest,
zUpdateWorkingDirRequest,
zGetSessionRequest,
zDeleteSessionRequest,
zExportSessionRequest,
zImportSessionRequest
]),
z.union([
z.record(z.unknown()),
z.null()
])
]).optional()
});
export const zExtResponse = z.union([
z.object({
id: z.string(),
result: z.union([
z.union([
zEmptyResponse,
zGetToolsResponse,
zReadResourceResponse,
zListSessionsResponse,
zGetSessionResponse,
zExportSessionResponse,
zImportSessionResponse,
zGetExtensionsResponse
]),
z.unknown()
]).optional()
}),
z.object({
error: z.object({
code: z.number().int(),
message: z.string(),
data: z.unknown().optional()
}),
id: z.string()
})
]);
+3
View File
@@ -0,0 +1,3 @@
export * from "./generated/index.js";
export * from "./generated/zod.gen.js";
export { GooseClient } from "./generated/client.gen.js";
+14
View File
@@ -0,0 +1,14 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"declaration": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src"]
}