# Core API reference

> Exports of @taskbox/core.

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

## Classes

### 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>`

### 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: "validation" | "runtime" | "image" | "network" | "proxy" | "timeout" | "resource" | "tool" | "artifact" | "unknown"`
- `retryable: boolean`
- `details: Record<string, unknown>`
- `stderrTail: string`
- `suggestions: string[]`
- `constructor(init: TaskboxErrorInit): TaskboxError`
- `serialize(): TaskboxErrorShape`

## Functions

### newTaskId

```ts
newTaskId(): string
```

### createWorkspace

```ts
createWorkspace(opts?: WorkspaceOptions): Workspace
```

### wrap

```ts
wrap(err: unknown, fallback: { code: TaskboxErrorCode; category: TaskboxErrorCategory; }): TaskboxError
```

### proxyToEnv

```ts
proxyToEnv(p: ProxyConfig): Record<string, string>
```

### redactProxyUrl

```ts
redactProxyUrl(url: string): string
```

### runTask

```ts
runTask(specInput: unknown, adapter: RuntimeAdapter, opts?: RunTaskOptions): Promise<TaskResult>
```

## Types

### TaskboxErrorCode

```ts
type TaskboxErrorCode = "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"
```

### TaskboxErrorCategory

```ts
type TaskboxErrorCategory = "validation" | "runtime" | "image" | "network" | "proxy" | "timeout" | "resource" | "tool" | "artifact" | "unknown"
```

## Interfaces

### Workspace

```ts
interface Workspace
```

- `taskId: string`
- `root: string`
- `inputDir: string`
- `outputDir: string`
- `logsDir: string`
- `taskJsonPath: string`
- `resultJsonPath: string`
- `eventsJsonlPath: string`
- `cleanup(): Promise<void>`

### WorkspaceOptions

```ts
interface WorkspaceOptions
```

- `taskId: string`
- `root: string`
- `keep: boolean`

### TaskboxErrorInit

```ts
interface TaskboxErrorInit
```

- `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" | "runtime" | "image" | "network" | "proxy" | "timeout" | "resource" | "tool" | "artifact" | "unknown"`
- `retryable: boolean`
- `details: Record<string, unknown>`
- `stderrTail: string`
- `suggestions: string[]`

### 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; }>`

### RunTaskOptions

```ts
interface RunTaskOptions
```

- `bus: EventBus`
- `onEvent: (e: TaskEvent) => void`
- `signal: AbortSignal`

## Constants

### defaultImageRef

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