# @coda/runner-api

ConnectRPC client and proto definitions for the sandboxed code execution service (ows-coda-runner). Supports bidirectional streaming for live code execution and unary RPCs for datasource refresh management.

## Installation

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

## Usage

```ts
import { RunnerClient } from "@coda/runner-api";

const runner = new RunnerClient({ baseUrl: "http://localhost:8092" });
```

### Bidirectional streaming — code execution

```ts
const events = runner.executeCode(inboundMessages, { signal });

for await (const event of events) {
  switch (event.event.case) {
    case "status":
      console.log("Status:", event.event.value);
      break;
    case "dataRequest":
      /* supply data back via inbound */ break;
    case "result":
      console.log("Result:", event.event.value);
      break;
    case "error":
      console.error("Error:", event.event.value);
      break;
  }
}
```

### Unary RPCs — datasource refresh

```ts
// Trigger refresh (no retry — mutation)
const refresh = await runner.refreshDataSource({
  datasourceId: "ds_123",
  triggeredBy: "u_456",
});

// Check status (retries on transient failures)
const status = await runner.getRefreshStatus({ datasourceId: "ds_123" });
if (status.ok) console.log(status.data.status);
```

## API Reference

### RunnerClient

| Method                           | Description                            | Transport   | Retries |
| -------------------------------- | -------------------------------------- | ----------- | ------- |
| `executeCode(inbound, options?)` | Bidirectional streaming code execution | gRPC stream | N/A     |
| `refreshDataSource(req)`         | Trigger a datasource refresh           | gRPC unary  | No      |
| `getRefreshStatus(req)`          | Check refresh status                   | gRPC unary  | Yes (3) |

Default timeout (unary only): **5 s**. Transport: **gRPC (HTTP/2)** — required for bidirectional streaming.

## Configuration

```ts
interface RunnerClientConfig {
  baseUrl: string; // Service URL
  interceptors?: Interceptor[]; // ConnectRPC interceptors
  defaultTimeoutMs?: number; // Override default timeout (unary only)
  onError?: (method: string, err: unknown) => void; // Error hook
}
```

Note: `transport` is always `"grpc"` — the `RunnerClient` sets this automatically.

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

## Exported Types

| Type                                        | Description                                                 |
| ------------------------------------------- | ----------------------------------------------------------- |
| `RunnerClientConfig`                        | Client config (like `BaseClientConfig` but always gRPC)     |
| `ExecuteCodeMessage`                        | Inbound stream message (request or data response)           |
| `ExecuteCodeEvent`                          | Outbound stream event (status, data request, result, error) |
| `ExecuteCodeRequest`                        | Initial code execution request                              |
| `DataResponse`                              | Data supplied back to the sandbox during execution          |
| `StatusEvent`                               | Execution status update                                     |
| `DataRequestEvent`                          | Sandbox requesting data from the caller                     |
| `ResultEvent`                               | Final execution result                                      |
| `ErrorEvent`                                | Execution error                                             |
| `ExecutionStats`                            | CPU, memory, and wall-clock statistics                      |
| `ToolPolicy`                                | Permissions for tool access within the sandbox              |
| `IsolateLimits` / `BridgeLimits`            | Resource limits for the isolate and bridge                  |
| `RefreshResponse` / `RefreshStatusResponse` | Datasource refresh results                                  |

## Proto sources

`proto/runner/` — `.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.