# @coda/tools-api

ConnectRPC client and proto definitions for the tool execution service. Provides discovery and execution of AI agent tools.

## Installation

```jsonc
// package.json
{ "dependencies": { "@coda/tools-api": "workspace:*" } }
```

## Usage

```ts
import { ToolClient } from "@coda/tools-api";

const tools = new ToolClient({ baseUrl: "http://localhost:8080" });

// List available tools
const list = await tools.listTools({ page: { pageSize: 50 } });
if (list.ok) {
  for (const tool of list.data.tools) {
    console.log(tool.id, tool.description);
  }
}

// Execute a tool
const result = await tools.runTool({
  toolId: "sql_query",
  params: { query: "SELECT COUNT(*) FROM accounts" },
});
if (result.ok) console.log(result.data.output);
```

## API Reference

### ToolClient

| Method           | Description                      | Default Timeout | Retries |
| ---------------- | -------------------------------- | --------------- | ------- |
| `listTools(req)` | List available tools (paginated) | 10 s            | Yes (3) |
| `runTool(req)`   | Execute a tool by ID             | 10 s            | No      |

## Configuration

All clients accept `BaseClientConfig` from `@coda/api-common`:

```ts
interface BaseClientConfig {
  baseUrl: string;
  transport?: "connect" | "grpc";
  interceptors?: Interceptor[];
  defaultTimeoutMs?: number;
  onError?: (method: string, err: unknown) => void;
}
```

All methods return `RpcResult<T>` — a discriminated union that never throws. See `@coda/api-common` for details.

## Exported Types

| Type                 | Description                                            |
| -------------------- | ------------------------------------------------------ |
| `ToolClientConfig`   | Client constructor config (extends `BaseClientConfig`) |
| `RunToolRequest`     | Tool execution request (tool ID + JSON params)         |
| `RunToolResponse`    | Tool execution result                                  |
| `ToolExecutionStats` | Execution statistics                                   |
| `ListToolsRequest`   | Paginated tool listing request                         |
| `ListToolsResponse`  | Tool listing response                                  |
| `ToolInfo`           | Metadata for a single tool                             |

## Proto sources

`proto/tools/` — `.proto` files defining the RPC service and message types.

## Generated code

`gen/` — auto-generated TypeScript. Do not edit manually.

## Regenerate

```bash
pnpm buf:generate
```

Requires [Buf CLI](https://buf.build/). Generated output is committed to the repo.