@labelbox/rl-sdk 0.0.0

package/dist/reference/tutorials.d.ts

@@ -0,0 +1,76 @@
+export type TutorialReferenceEntry = {
+    id: string;
+    title: string;
+    file: string;
+    format?: 'md' | 'ipynb';
+};
+export declare const TUTORIAL_REFERENCE: readonly [{
+    readonly id: "getting-started";
+    readonly title: "Getting started";
+    readonly file: "getting-started.md";
+}, {
+    readonly id: "set-up-an-environment";
+    readonly title: "Set up an environment";
+    readonly file: "set-up-an-environment.md";
+}, {
+    readonly id: "first-problem";
+    readonly title: "Your first problem";
+    readonly file: "first-problem.md";
+}, {
+    readonly id: "first-evaluation";
+    readonly title: "Your first evaluation";
+    readonly file: "first-evaluation.md";
+}, {
+    readonly id: "export-your-results";
+    readonly title: "Export your results";
+    readonly file: "export-your-results.md";
+}, {
+    readonly id: "author-a-problem-end-to-end";
+    readonly title: "Author a problem end to end";
+    readonly file: "author-a-problem-end-to-end.md";
+}, {
+    readonly id: "import-a-problem-set";
+    readonly title: "Import a problem set and evaluate it";
+    readonly file: "import-a-problem-set.md";
+}, {
+    readonly id: "run-a-problem-with-your-own-run-config";
+    readonly title: "Run a problem with your own run config";
+    readonly file: "run-a-problem-with-your-own-run-config.md";
+}, {
+    readonly id: "bring-a-real-agent";
+    readonly title: "Bring a real agent with Claude Code";
+    readonly file: "bring-a-real-agent.md";
+}, {
+    readonly id: "run-and-export-an-evaluation";
+    readonly title: "Run and export an evaluation";
+    readonly file: "run-and-export-an-evaluation.md";
+}, {
+    readonly id: "add-a-quality-gate";
+    readonly title: "Add a quality gate";
+    readonly file: "add-a-quality-gate.md";
+}, {
+    readonly id: "improve-problems-with-the-synthesizer";
+    readonly title: "Improve problems with the synthesizer";
+    readonly file: "improve-problems-with-the-synthesizer.md";
+}, {
+    readonly id: "control-your-costs";
+    readonly title: "Control your costs";
+    readonly file: "control-your-costs.md";
+}, {
+    readonly id: "ts-sdk-getting-started";
+    readonly title: "TypeScript SDK";
+    readonly file: "ts-sdk-getting-started.md";
+}, {
+    readonly id: "cli-getting-started";
+    readonly title: "CLI";
+    readonly file: "cli-getting-started.md";
+}, {
+    readonly id: "headless-recursion-runbook";
+    readonly title: "Headless runbook";
+    readonly file: "headless-recursion-runbook.ipynb";
+    readonly format: "ipynb";
+}, {
+    readonly id: "claude-code";
+    readonly title: "Claude Code";
+    readonly file: "claude-code.md";
+}];

package/dist/reference/tutorials.js

@@ -0,0 +1,65 @@
+// Canonical **tutorials registry** — the single source of truth for the docs
+// Tutorials quadrant (the getting-started learning arc + the SDK/CLI on-ramps).
+//
+// Consumed by both the frontend docs nav (`apps/recursion/web/src/features/docs/constants.ts`)
+// and the dx CLI-manifest generator (`tools/dx/src/commands/manifest.ts`), so
+// the two surfaces can never drift — a parity test pins the nav to this list.
+//
+// `file` is resolved relative to `apps/recursion/web/public/docs/`. Order is the docs nav
+// order (top → bottom). An `ipynb` entry is a notebook: it renders as an
+// "open in the app" link and its body is never dumped into the manifest JSON.
+export const TUTORIAL_REFERENCE = [
+    { id: 'getting-started', title: 'Getting started', file: 'getting-started.md' },
+    {
+        id: 'set-up-an-environment',
+        title: 'Set up an environment',
+        file: 'set-up-an-environment.md',
+    },
+    { id: 'first-problem', title: 'Your first problem', file: 'first-problem.md' },
+    { id: 'first-evaluation', title: 'Your first evaluation', file: 'first-evaluation.md' },
+    { id: 'export-your-results', title: 'Export your results', file: 'export-your-results.md' },
+    // Multi-recipe workflow tutorials — guided journeys that chain several recipes
+    // (the getting-started arc above covers each task once; these go deeper into a
+    // workflow). A tutorial can embed many recipes via the ```recipe fence.
+    {
+        id: 'author-a-problem-end-to-end',
+        title: 'Author a problem end to end',
+        file: 'author-a-problem-end-to-end.md',
+    },
+    {
+        id: 'import-a-problem-set',
+        title: 'Import a problem set and evaluate it',
+        file: 'import-a-problem-set.md',
+    },
+    {
+        id: 'run-a-problem-with-your-own-run-config',
+        title: 'Run a problem with your own run config',
+        file: 'run-a-problem-with-your-own-run-config.md',
+    },
+    {
+        id: 'bring-a-real-agent',
+        title: 'Bring a real agent with Claude Code',
+        file: 'bring-a-real-agent.md',
+    },
+    {
+        id: 'run-and-export-an-evaluation',
+        title: 'Run and export an evaluation',
+        file: 'run-and-export-an-evaluation.md',
+    },
+    { id: 'add-a-quality-gate', title: 'Add a quality gate', file: 'add-a-quality-gate.md' },
+    {
+        id: 'improve-problems-with-the-synthesizer',
+        title: 'Improve problems with the synthesizer',
+        file: 'improve-problems-with-the-synthesizer.md',
+    },
+    { id: 'control-your-costs', title: 'Control your costs', file: 'control-your-costs.md' },
+    { id: 'ts-sdk-getting-started', title: 'TypeScript SDK', file: 'ts-sdk-getting-started.md' },
+    { id: 'cli-getting-started', title: 'CLI', file: 'cli-getting-started.md' },
+    {
+        id: 'headless-recursion-runbook',
+        title: 'Headless runbook',
+        file: 'headless-recursion-runbook.ipynb',
+        format: 'ipynb',
+    },
+    { id: 'claude-code', title: 'Claude Code', file: 'claude-code.md' },
+];

package/dist/session-events.d.ts

@@ -0,0 +1,92 @@
+import { type RecursionClientOptions } from './client-options.js';
+import type { ManagedAgentsContentBlock, ManagedAgentsEvent, ManagedAgentsUsage } from './generated/index.js';
+/**
+ * One decoded frame from a session event stream.
+ *
+ * Field names are the wire's own, matching every other managed-agents type in
+ * this package: those are imported verbatim from the Go service's spec rather
+ * than derived from a camelCase DTO, and a stream frame that disagreed with
+ * `ManagedAgentsEvent` would be the odd one out.
+ */
+export interface ManagedAgentSessionStreamEvent {
+    /**
+     * Fields the service has added since this decoder was written.
+     *
+     * This type is hand-maintained rather than generated, so an index signature
+     * is what keeps the decoder a passthrough: a new field on the Go
+     * `managedStreamEvent` struct reaches the caller as `unknown` instead of
+     * being silently dropped while someone notices. The declared fields below
+     * stay precisely typed.
+     */
+    [key: string]: unknown;
+    /** Frame type, e.g. `session.status_running`, `message`, `session.error`. */
+    type: string;
+    /** Event id. Pass the last one seen as `afterEventId` to resume without gaps. */
+    id?: string;
+    session_id?: string;
+    session_thread_id?: string;
+    processed_at?: string;
+    content?: ManagedAgentsContentBlock[];
+    /** Provider-specific; shape varies by model and is deliberately not narrowed. */
+    stop_reason?: unknown;
+    usage?: ManagedAgentsUsage;
+    error?: Record<string, unknown>;
+    anchor_event_id?: string;
+    raw_event?: ManagedAgentsEvent;
+}
+export interface ManagedAgentSessionStreamParams {
+    /** Session id (UUID). Any id in the tree resolves to its root session. */
+    sessionId: string;
+    /**
+     * Resume cursor: only events after this id are delivered.
+     *
+     * Sent as the `after_event_id` query parameter rather than the `Last-Event-ID`
+     * header. The public gateway's cross-origin allowlist admits the query but not
+     * that non-safelisted header, and using one cursor everywhere keeps a browser
+     * caller and a server caller on the same code path.
+     */
+    afterEventId?: string;
+    /** Restrict delivery to these frame types. Omit for everything. */
+    types?: readonly string[];
+    /** Abort the request and end the iteration. */
+    signal?: AbortSignal;
+}
+/**
+ * Stream a managed agent session's events as they are produced.
+ *
+ * Iteration ends when the server closes the stream, which it does once the
+ * session reaches a terminal status. Aborting `signal` ends it early.
+ *
+ * @example
+ * for await (const event of streamManagedAgentSessionEvents(
+ *   { apiKey: process.env.LABELBOX_API_KEY! },
+ *   { sessionId },
+ * )) {
+ *   if (event.type === 'session.error') break;
+ *   console.log(event.type, event.content);
+ * }
+ */
+export declare function streamManagedAgentSessionEvents(options: RecursionClientOptions, params: ManagedAgentSessionStreamParams): AsyncGenerator<ManagedAgentSessionStreamEvent, void, undefined>;
+/** A stream that failed before any frame was delivered. */
+export declare class ManagedAgentSessionStreamError extends Error {
+    readonly status: number;
+    /** Stable machine-readable code from the service, when the body carried one. */
+    readonly code: string | undefined;
+    constructor(status: number, body: {
+        code?: string;
+        message?: string;
+    });
+}
+/**
+ * Decode an SSE byte stream into frames.
+ *
+ * Exported for the tests in this package only, and deliberately not re-exported
+ * from `index.ts`: it takes a raw `ReadableStream<Uint8Array>`, which is a
+ * transport detail rather than something a consumer of this SDK should have to
+ * hold.
+ *
+ * Buffering is required because a chunk boundary can fall anywhere, including
+ * mid-frame and mid-UTF-8-sequence, so decoding is incremental and frames are
+ * only emitted on a complete blank-line terminator.
+ */
+export declare function decodeEventStream(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<ManagedAgentSessionStreamEvent, void, undefined>;

package/dist/session-events.js

@@ -0,0 +1,213 @@
+// Hand-written transport for the one managed-agents operation the generated
+// client cannot express.
+//
+// `GET /managed-agents/v1/sessions/{session_id}/events/stream` returns
+// `text/event-stream`. The generated SDK is configured with
+// `responseStyle: 'data'`, so every generated method parses a JSON body and
+// resolves once — which is the opposite of what a long-lived stream needs.
+// Rather than leave the console holding a capability no API key could
+// reproduce, the operation is marked `sdkExcluded` in the backend proxy
+// contract and reached through this module instead.
+//
+// The frame format is produced by `writeSSEEvent` in
+// `apps/recursion/control-plane/internal/httpapi/streaming.go`: an optional
+// `event:` line carrying the type, an optional `id:` line, then a single
+// `data:` line holding the whole JSON payload. Comment frames (`: connected`,
+// heartbeats) carry no data and are skipped.
+import { DEFAULT_BASE_URL } from './client-options.js';
+/**
+ * Stream a managed agent session's events as they are produced.
+ *
+ * Iteration ends when the server closes the stream, which it does once the
+ * session reaches a terminal status. Aborting `signal` ends it early.
+ *
+ * @example
+ * for await (const event of streamManagedAgentSessionEvents(
+ *   { apiKey: process.env.LABELBOX_API_KEY! },
+ *   { sessionId },
+ * )) {
+ *   if (event.type === 'session.error') break;
+ *   console.log(event.type, event.content);
+ * }
+ */
+export async function* streamManagedAgentSessionEvents(options, params) {
+    const base = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const url = new URL(`${base}/managed-agents/v1/sessions/${encodeURIComponent(params.sessionId)}/events/stream`);
+    if (params.afterEventId !== undefined) {
+        url.searchParams.set('after_event_id', params.afterEventId);
+    }
+    for (const type of params.types ?? []) {
+        url.searchParams.append('types', type);
+    }
+    const response = await fetch(url, {
+        method: 'GET',
+        headers: {
+            ...options.headers,
+            Authorization: `Bearer ${options.apiKey}`,
+            Accept: 'text/event-stream',
+        },
+        ...(params.signal ? { signal: params.signal } : {}),
+    });
+    if (!response.ok || !response.body) {
+        // The error body is the Go envelope, `{ error: { code, message, ... } }`.
+        // `code` is the stable contract, so it is surfaced rather than the status.
+        throw new ManagedAgentSessionStreamError(response.status, await readErrorBody(response));
+    }
+    yield* decodeEventStream(response.body, params.signal);
+}
+/** A stream that failed before any frame was delivered. */
+export class ManagedAgentSessionStreamError extends Error {
+    status;
+    /** Stable machine-readable code from the service, when the body carried one. */
+    code;
+    constructor(status, body) {
+        super(body.message ?? `session event stream failed with status ${status}`);
+        this.name = 'ManagedAgentSessionStreamError';
+        this.status = status;
+        this.code = body.code;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Reads whichever error envelope came back.
+ *
+ * A stream request can fail at either hop and the two answer differently. The
+ * managed-agents service returns `{error: {code, message}}`, forwarded byte for
+ * byte. This API's own guards -- the ones a caller hits first, on a missing
+ * permission or an exhausted rate limit -- reject with the platform's
+ * `{statusCode, message}` before the request is forwarded at all. Understanding
+ * only the first shape meant the errors a caller is most likely to see arrived
+ * with no message.
+ */
+async function readErrorBody(response) {
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch {
+        return {};
+    }
+    if (!isRecord(parsed))
+        return {};
+    const nested = parsed['error'];
+    if (isRecord(nested))
+        return pickCodeAndMessage(nested);
+    // Platform envelope. `error` is a short status name ("Forbidden") rather than
+    // a stable code, so it is not surfaced as one; `message` is the useful part,
+    // and can be a Zod field-error object on a validation failure.
+    return pickCodeAndMessage({ message: parsed['message'] });
+}
+function pickCodeAndMessage(source) {
+    const code = source['code'];
+    const message = source['message'];
+    return {
+        ...(typeof code === 'string' ? { code } : {}),
+        ...(typeof message === 'string' ? { message } : {}),
+    };
+}
+/**
+ * Decode an SSE byte stream into frames.
+ *
+ * Exported for the tests in this package only, and deliberately not re-exported
+ * from `index.ts`: it takes a raw `ReadableStream<Uint8Array>`, which is a
+ * transport detail rather than something a consumer of this SDK should have to
+ * hold.
+ *
+ * Buffering is required because a chunk boundary can fall anywhere, including
+ * mid-frame and mid-UTF-8-sequence, so decoding is incremental and frames are
+ * only emitted on a complete blank-line terminator.
+ */
+export async function* decodeEventStream(body, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            if (signal?.aborted)
+                return;
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // `\r\n\r\n` is admitted alongside `\n\n` because the spec permits CRLF
+            // and an intermediary may rewrite line endings.
+            let boundary = findFrameBoundary(buffer);
+            while (boundary !== undefined) {
+                const frame = buffer.slice(0, boundary.index);
+                buffer = buffer.slice(boundary.index + boundary.length);
+                const event = parseFrame(frame);
+                if (event)
+                    yield event;
+                boundary = findFrameBoundary(buffer);
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+        // A consumer that breaks out of the loop leaves the socket open otherwise.
+        await body.cancel().catch(() => undefined);
+    }
+}
+function findFrameBoundary(buffer) {
+    const lf = buffer.indexOf('\n\n');
+    const crlf = buffer.indexOf('\r\n\r\n');
+    if (crlf !== -1 && (lf === -1 || crlf < lf))
+        return { index: crlf, length: 4 };
+    if (lf !== -1)
+        return { index: lf, length: 2 };
+    return undefined;
+}
+function parseFrame(frame) {
+    const dataLines = [];
+    let type;
+    let id;
+    for (const rawLine of frame.split('\n')) {
+        const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+        // A comment frame — the `: connected` preamble and the periodic heartbeat.
+        if (line.startsWith(':') || line === '')
+            continue;
+        const separator = line.indexOf(':');
+        const field = separator === -1 ? line : line.slice(0, separator);
+        const rawValue = separator === -1 ? '' : line.slice(separator + 1);
+        const value = rawValue.startsWith(' ') ? rawValue.slice(1) : rawValue;
+        if (field === 'data')
+            dataLines.push(value);
+        else if (field === 'event')
+            type = value;
+        else if (field === 'id')
+            id = value;
+    }
+    if (dataLines.length === 0)
+        return undefined;
+    let payload;
+    try {
+        payload = JSON.parse(dataLines.join('\n'));
+    }
+    catch {
+        // A frame the service did not produce, or a truncated body. Skipping keeps
+        // one bad frame from ending an otherwise healthy stream.
+        return undefined;
+    }
+    if (!isRecord(payload))
+        return undefined;
+    // The `event:`/`id:` lines and the JSON body carry the same values, but the
+    // body is authoritative: the lines are omitted when the field is empty.
+    const bodyType = payload['type'];
+    const resolvedType = typeof bodyType === 'string' ? bodyType : type;
+    if (resolvedType === undefined) {
+        // Not a frame this service produces: the Go writer marshals `type` without
+        // `omitempty`, so the body always carries it. Dropping the frame is what
+        // keeps `ManagedAgentSessionStreamEvent.type` a `string` the caller can
+        // switch on rather than one more field they have to null-check.
+        return undefined;
+    }
+    const bodyID = payload['id'];
+    const resolvedID = typeof bodyID === 'string' ? bodyID : id;
+    return {
+        ...payload,
+        type: resolvedType,
+        ...(resolvedID === undefined ? {} : { id: resolvedID }),
+    };
+}

package/package.json

@@ -0,0 +1,126 @@
+{
+  "name": "@labelbox/rl-sdk",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./nesting": {
+        "types": "./dist/nesting.d.ts",
+        "import": "./dist/nesting.js"
+      },
+      "./domains": {
+        "types": "./dist/reference/domains.d.ts",
+        "import": "./dist/reference/domains.js"
+      },
+      "./schema": {
+        "types": "./dist/reference/schema.d.ts",
+        "import": "./dist/reference/schema.js"
+      },
+      "./resources-schema": {
+        "types": "./dist/reference/resources-schema.d.ts",
+        "import": "./dist/reference/resources-schema.js"
+      },
+      "./reference": {
+        "types": "./dist/reference/sdk-reference.generated.d.ts",
+        "import": "./dist/reference/sdk-reference.generated.js"
+      },
+      "./resources-reference": {
+        "types": "./dist/reference/resources-reference.generated.d.ts",
+        "import": "./dist/reference/resources-reference.generated.js"
+      },
+      "./recipes-schema": {
+        "types": "./dist/reference/recipes-schema.d.ts",
+        "import": "./dist/reference/recipes-schema.js"
+      },
+      "./recipes-reference": {
+        "types": "./dist/reference/recipes-reference.generated.d.ts",
+        "import": "./dist/reference/recipes-reference.generated.js"
+      },
+      "./concepts": {
+        "types": "./dist/reference/concepts.d.ts",
+        "import": "./dist/reference/concepts.js"
+      },
+      "./tutorials": {
+        "types": "./dist/reference/tutorials.d.ts",
+        "import": "./dist/reference/tutorials.js"
+      }
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./nesting": {
+      "types": "./src/nesting.ts",
+      "import": "./dist/nesting.js"
+    },
+    "./domains": {
+      "types": "./src/reference/domains.ts",
+      "import": "./dist/reference/domains.js"
+    },
+    "./schema": {
+      "types": "./src/reference/schema.ts",
+      "import": "./dist/reference/schema.js"
+    },
+    "./resources-schema": {
+      "types": "./src/reference/resources-schema.ts",
+      "import": "./dist/reference/resources-schema.js"
+    },
+    "./reference": {
+      "types": "./src/reference/sdk-reference.generated.ts",
+      "import": "./dist/reference/sdk-reference.generated.js"
+    },
+    "./resources-reference": {
+      "types": "./src/reference/resources-reference.generated.ts",
+      "import": "./dist/reference/resources-reference.generated.js"
+    },
+    "./recipes-schema": {
+      "types": "./src/reference/recipes-schema.ts",
+      "import": "./dist/reference/recipes-schema.js"
+    },
+    "./recipes-reference": {
+      "types": "./src/reference/recipes-reference.generated.ts",
+      "import": "./dist/reference/recipes-reference.generated.js"
+    },
+    "./concepts": {
+      "types": "./src/reference/concepts.ts",
+      "import": "./dist/reference/concepts.js"
+    },
+    "./tutorials": {
+      "types": "./src/reference/tutorials.ts",
+      "import": "./dist/reference/tutorials.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "yarn lint && tsc --noEmit",
+    "lint": "biome ci --error-on-warnings --config-path ./biome.json .",
+    "lint:fix": "biome check --config-path ./biome.json --write .",
+    "test": "vitest run",
+    "prepare": "yarn build",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.6",
+    "@hey-api/client-fetch": "^0.13.1",
+    "@hey-api/openapi-ts": "^0.97.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}