# Tools API reference

> Exports of @taskbox/tools.

Source: https://taskbox.n.yatsyk.com/docs/tools/jsdoc

## Classes

### TaskboxError

```ts
class TaskboxError
```

- `code: "E_SCHEMA_INVALID" | "E_RUNTIME_UNAVAILABLE" | "E_IMAGE_PULL_FAILED" | "E_PROXY_INVALID" | "E_PROXY_CONNECT_FAILED" | "E_NETWORK_FAILED" | "E_TIMEOUT" | "E_OUTPUT_TOO_LARGE" | "E_TOOL_EXIT_NONZERO" | "E_ARTIFACT_MISSING" | "E_UNSUPPORTED_FORMAT"`
- `category: "proxy" | "validation" | "runtime" | "image" | "network" | "timeout" | "resource" | "tool" | "artifact" | "unknown"`
- `retryable: boolean`
- `details: Record<string, unknown>`
- `stderrTail: string`
- `suggestions: string[]`
- `constructor(init: TaskboxErrorInit): TaskboxError`
- `serialize(): TaskboxError$1`

### EventBus

```ts
class EventBus
```

- `constructor(eventsJsonlPath: string): EventBus`
- `emit(event: unknown): void`
- `on(cb: EventCallback): () => void`
- `close(): void`
- `events(): AsyncIterableIterator<TaskEvent>`
- `[Symbol.asyncIterator](): AsyncIterableIterator<TaskEvent>`

## Functions

### createTaskbox

```ts
createTaskbox(config: TaskboxConfig): { prepare(): Promise<PrepareResult>; runTask(spec: unknown, opts?: { onEvent?: (e: TaskEvent) => void; }): Promise<TaskResult>; media: { downloadSubtitles(input: unknown, opts?: DownloadSubtitlesOptions): Promise<TaskResult>; }; }
```

## Interfaces

### RuntimeAdapter

```ts
interface RuntimeAdapter
```

- `name: string`
- `available(): Promise<{ ok: boolean; details?: Record<string, unknown>; }>`
- `prepareImage(ref: string): Promise<{ digest?: string; }>`
- `runTask(args: { spec: TaskSpec; workspace: Workspace; bus: EventBus; signal?: AbortSignal; }): Promise<{ exitCode: number; durationMs: number; rawResult?: unknown; }>`

### TaskboxConfig

```ts
interface TaskboxConfig
```

- `runtime: RuntimeAdapter`
- `image: string`
- `defaults: { timeoutMs?: number; networkMode?: "none" | "direct" | "proxy"; defaultProxy?: ProxyConfig; }`

### DownloadSubtitlesOptions

```ts
interface DownloadSubtitlesOptions
```

- `onEvent: (e: TaskEvent) => void`

### PrepareResult

```ts
interface PrepareResult
```

- `runtime: string`
- `image: { ref: string; digest?: string; }`

## Constants

### defaultImageRef

```ts
const defaultImageRef: "taskbox/kitchen-sink:0.1.0"
```

### TaskboxErrorSchema

```ts
const TaskboxErrorSchema: z.ZodObject<{ code: z$1.ZodEnum<["E_SCHEMA_INVALID", "E_RUNTIME_UNAVAILABLE", "E_IMAGE_PULL_FAILED", "E_PROXY_INVALID", "E_PROXY_CONNECT_FAILED", "E_NETWORK_FAILED", "E_TIMEOUT", "E_OUTPUT_TOO_LARGE", "E_TOOL_EXIT_NONZERO", "E_ARTIFACT_MISSING", "E_UNSUPPORTED_FORMAT"]>; message: z$1.ZodString; retryable: z$1.ZodDefault<z$1.ZodBoolean>; category: z$1.ZodEnum<["validation", "runtime", "image", "network", "proxy", "timeout", "resource", "tool", "artifact", "unknown"]>; details: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodUnknown>>; stderrTail: z$1.ZodOptional<z$1.ZodString>; suggestions: z$1.ZodDefault<z$1.ZodArray<z$1.ZodString, "many">>; }, "strip", z.ZodTypeAny, { code: "E_SCHEMA_INVALID" | "E_RUNTIME_UNAVAILABLE" | "E_IMAGE_PULL_FAILED" | "E_PROXY_INVALID" | "E_PROXY_CONNECT_FAILED" | "E_NETWORK_FAILED" | "E_TIMEOUT" | "E_OUTPUT_TOO_LARGE" | "E_TOOL_EXIT_NONZERO" | "E_ARTIFACT_MISSING" | "E_UNSUPPORTED_FORMAT"; message: string; retryable: boolean; category: "validation" | "unknown" | "proxy" | "image" | "runtime" | "network" | "timeout" | "resource" | "tool" | "artifact"; suggestions: string[]; details?: Record<string, unknown> | undefined; stderrTail?: string | undefined; }, { code: "E_SCHEMA_INVALID" | "E_RUNTIME_UNAVAILABLE" | "E_IMAGE_PULL_FAILED" | "E_PROXY_INVALID" | "E_PROXY_CONNECT_FAILED" | "E_NETWORK_FAILED" | "E_TIMEOUT" | "E_OUTPUT_TOO_LARGE" | "E_TOOL_EXIT_NONZERO" | "E_ARTIFACT_MISSING" | "E_UNSUPPORTED_FORMAT"; message: string; category: "validation" | "unknown" | "proxy" | "image" | "runtime" | "network" | "timeout" | "resource" | "tool" | "artifact"; retryable?: boolean | undefined; details?: Record<string, unknown> | undefined; stderrTail?: string | undefined; suggestions?: string[] | undefined; }>
```