Getting Started

@taskbox/schemas is a leaf package — it has no Taskbox runtime dependencies and is safe to use anywhere you need to validate or type Taskbox JSON.

1. Install

npm i @taskbox/schemas zod

The package re-exports the zod instance it built its schemas with, so you can do import { z } from "@taskbox/schemas" if you only need one zod in your tree.

2. Validate a TaskSpec

import { TaskSpecSchema } from "@taskbox/schemas";

const spec = TaskSpecSchema.parse({
  tool: "media.downloadSubtitles",
  input: { url: "https://youtu.be/jNQXAC9IVRw", languages: ["en"] },
  network: { mode: "direct" },
  runtime: { backend: "podman" },
});

If parsing fails, zod throws a ZodError with the path of every mismatch.

3. Type a callback

import type { TaskEvent, TaskResult } from "@taskbox/schemas";

function onEvent(e: TaskEvent) {
  if (e.type === "process.stdout") process.stdout.write(e.data + "\n");
}

function reportResult(r: TaskResult) {
  if (!r.ok) console.error(r.error.code, r.error.message);
}

4. Build a TaskboxError shape by hand

import { TaskboxErrorSchema } from "@taskbox/schemas";

const err = TaskboxErrorSchema.parse({
  code: "E_TIMEOUT",
  category: "timeout",
  message: "task exceeded 30s",
  retryable: true,
  suggestions: ["raise resources.timeoutMs"],
});

The schemas are the same ones the in-container runner serializes, so anything you parse here matches what @taskbox/core produces in result.json.

Getting Started

1. Install

2. Validate a TaskSpec

3. Type a callback

4. Build a TaskboxError shape by hand

On this page