# API

> @taskbox/core public exports.

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

# API

## Running tasks

| Export           | Signature                                                                                | Summary                                                                                                             |
| ---------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `runTask`        | `(spec: unknown, adapter: RuntimeAdapter, opts?: RunTaskOptions) => Promise<TaskResult>` | Validates `spec`, mints a workspace, dispatches to the adapter, parses `result.json`, returns a typed `TaskResult`. |
| `RunTaskOptions` | `{ bus?: EventBus; onEvent?: (e: TaskEvent) => void; signal?: AbortSignal }`             | Optional event sink and cancellation.                                                                               |

## Workspace

| Export             | Signature                                                                                                  | Summary                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `createWorkspace`  | `(opts?: WorkspaceOptions) => Workspace`                                                                   | Creates `in/`, `out/`, `logs/` under `TASKBOX_WORKSPACE_DIR` (or `os.tmpdir()/taskbox-runs/<taskId>`). |
| `Workspace`        | `{ taskId, root, inputDir, outputDir, logsDir, taskJsonPath, resultJsonPath, eventsJsonlPath, cleanup() }` | The handle returned by `createWorkspace`.                                                              |
| `WorkspaceOptions` | `{ taskId?: string; root?: string; keep?: boolean }`                                                       | Override id/root or suppress cleanup.                                                                  |

## Events

| Export            | Signature                                    | Summary                                                                                         |
| ----------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `EventBus`        | `class EventBus(eventsJsonlPath: string)`    | Validates and appends `TaskEvent`s to JSONL while fanning out to listeners and async iterators. |
| `EventBus#emit`   | `(event: unknown) => void`                   | Validate via `TaskEventSchema`, append, broadcast.                                              |
| `EventBus#on`     | `(cb: (e: TaskEvent) => void) => () => void` | Subscribe; returns an unsubscribe.                                                              |
| `EventBus#events` | `() => AsyncIterableIterator<TaskEvent>`     | Drain events as they arrive; closes when `bus.close()` is called.                               |
| `EventBus#close`  | `() => void`                                 | Wakes pending iterators with `done: true`.                                                      |

## Errors

| Export                 | Signature                                                                      | Summary                                                                                |
| ---------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `TaskboxError`         | `class TaskboxError(init: TaskboxErrorInit)`                                   | Throwable error with stable `code` + `category`. `serialize()` returns the wire shape. |
| `TaskboxErrorInit`     | `{ code, message, category, retryable?, details?, stderrTail?, suggestions? }` | Constructor input.                                                                     |
| `wrap`                 | `(err: unknown, fallback: { code; category }) => TaskboxError`                 | Promotes any error to a `TaskboxError`, preserving stack as `details.stack`.           |
| `TaskboxErrorCode`     | type                                                                           | Re-export of the enum from `@taskbox/schemas`.                                         |
| `TaskboxErrorCategory` | type                                                                           | Re-export of the enum from `@taskbox/schemas`.                                         |

## Identifiers

| Export      | Signature      | Summary                                                                  |
| ----------- | -------------- | ------------------------------------------------------------------------ |
| `newTaskId` | `() => string` | 16-char uppercase task id (compact UUID). Used as workspace folder name. |

## Proxy

| Export           | Signature                                    | Summary                                                                    |
| ---------------- | -------------------------------------------- | -------------------------------------------------------------------------- |
| `proxyToEnv`     | `(p: ProxyConfig) => Record<string, string>` | Expands a `ProxyConfig` into `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, etc. |
| `redactProxyUrl` | `(url: string) => string`                    | Re-export from `@taskbox/schemas` — strips userinfo for logging.           |

## Runtime contract

| Export            | Signature                                                                            | Summary                                                     |
| ----------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| `defaultImageRef` | `"taskbox/kitchen-sink:0.1.0"`                                                       | Default image when a `TaskSpec` doesn't pin one.            |
| `RuntimeAdapter`  | `{ name, available(), prepareImage(ref), runTask({spec, workspace, bus, signal?}) }` | Interface every adapter implements (see `@taskbox/podman`). |

See the generated [JSDoc reference](/docs/core/jsdoc) for the full surface.