@lionhummer/constellation 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# Constellation TypeScript SDK
+
+The SDK submits durable requests, observes events, responds to tool/context inputs, and records caller telemetry. Obvious owns prompts, conversation history, tool implementations and continuation decisions. Constellation connects to providers directly over HTTP.
+
+The package builds JavaScript and type declarations in `dist` for npm. It has
+not been published yet. The web test page imports its source through the
+`@lionhummer/constellation` alias while this monorepo is under development.
+External SDK calls use `/v1/*` with a bearer key. The first-party console sets
+`apiPrefix: "/internal"` and supplies its session-aware fetch adapter; that
+prefix is for the signed-in console, not third-party integrations.
+
+```ts
+import { Constellation, uuid7 } from "@lionhummer/constellation";
+
+const client = new Constellation({ baseUrl: "https://constellation.example", apiKey });
+const request = await client.submit({
+  idempotencyKey: uuid7(), // Persist and reuse this key when retrying submission.
+  externalId: threadId,   // Search/group identifier; no shared history.
+  workspaceId,
+  model: "obvious/fusion-1p0", // Physical model or virtual SKU.
+  kind: "run",
+  messages: [{ role: "user", text: "Echo hello using the tool." }],
+  tools: [{
+    name: "echo",
+    inputSchema: {
+      type: "object",
+      properties: { text: { type: "string" } },
+      required: ["text"],
+      additionalProperties: false,
+    },
+  }],
+});
+
+const result = await client.drive(request.id, {
+  consumerId: stableConsumerId, // UUIDv7; reuse when reconnecting this consumer.
+  tools: {
+    echo: async (args, { inputId, signal }) => {
+      // Use inputId as the idempotency key for external tool side effects.
+      signal?.throwIfAborted();
+      return args;
+    },
+  },
+});
+console.log(result.request.status, result.request.customerCost);
+```
+
+For a single model call, use `kind: "generate"` without tools. Poll `inspect(id)` or consume `events(id, { after, signal })` to reconnect from a stored event cursor. Disconnecting an observer does not cancel execution; use `cancel(id)` explicitly. Waiting inputs survive restarts; claimed inputs remain assigned to their consumer. Tool handlers must honor cancellation and implement idempotency themselves.
+
+Explicit span times support instrumentation outside Constellation:
+
+```ts
+const span = await client.startSpan(request.id, "application.lookup", {
+  startedAt: lookupStartedAt,
+  attributes: { source: "obvious" },
+});
+await span.end({ endedAt: lookupEndedAt, status: "ok" });
+await client.addLogs(request.id, [{
+  id: uuid7(), spanId: span.id, level: "info", message: "Lookup completed",
+  timestamp: lookupEndedAt, attributes: {},
+}]);
+```
+
+Keep execution keys on a trusted server unless intentionally scoped for a client. Provider credentials never belong in this SDK. See [the execution contract](../../docs/execution.md) for rule snapshots, pricing, waits, limits and recovery behavior.
+
+Run SDK checks with `bun test packages/sdk` from the repository root. The web build also checks SDK types.
+
+Resolve the exact execution input without creating a request or calling a provider:
+
+```ts
+const preview = await client.resolve(input);
+if (!preview.allowed) console.log(preview.rules);
+const page = await client.list({ q: "external-id-or-request-id", limit: 25 });
+```
+
+`resolve` does not verify provider credentials or future availability. The console
+at `/test` is the SDK playground, with real LLM calls and local mock tools. Its
+Resolve only option calls this same method. Inspection includes original `input`
+and the current `effectiveInput` after application context refreshes.
+
+For paginated monitoring, use `inspectSummary(id)` for request context, then
+`records(id, "logs", { level: "error", q: "tool", offset: 0, limit: 25 })`.
+Supported record kinds are `steps`, `attempts`, `inputs`, `spans`, and `logs`;
+responses contain `items`, `total`, `offset`, and `limit`. Summary inspection
+intentionally contains empty telemetry arrays; `inspect` retains its full behavior.
+
+## Client reference
+
+| Method | Behavior |
+| --- | --- |
+| `submit(input, signal?)` | Submit a durable `generate` or `run` request and return `{ id }`. Persist `idempotencyKey` for retries. |
+| `resolve(input, signal?)` | Return the current resolution and rule snapshot without dispatch. |
+| `list(query?, signal?)` | Page requests; filter by `q`, `requestId`, `externalId`, `workspaceId`, `userId`, or `status`. |
+| `inspect(id, signal?)` | Get full request context and telemetry. |
+| `inspectSummary(id, signal?)` | Get context without loading historical telemetry arrays. |
+| `records(id, kind, query?, signal?)` | Page one record kind with `id`, `q`, `level`, `offset`, and `limit`. |
+| `events(id, { after?, signal? })` | Async iterator over live SSE with durable cursor replay. Persist `seq` to resume. |
+| `drive(id, options)` | Claim and answer pending inputs until terminal; supports `tools`, `prepareStep`, `consumerId`, `toolTimeoutMs`, `onUpdate`, and `signal`. |
+| `claim(id, inputId, claimId, signal?)` / `respond(id, inputId, response, signal?)` | Manually handle a waiting input. |
+| `cancel(id, signal?)` | Explicitly cancel a durable request. |
+| `addSpans(id, spans, signal?)` / `startSpan(id, name, options?, signal?)` | Upsert caller spans; `startSpan` returns an `end()` handle. |
+| `addLogs(id, logs, signal?)` | Append caller logs. |
+
+`RequestInput` requires `idempotencyKey`, `workspaceId`, `model`, `kind`, and
+`messages`. It also accepts `externalId`, `userId`, `planId`, `instructions`,
+`tools`, `parameters`, `maxSteps`, `timeoutMs`, `maxOutputTokens`,
+`prepareStep` and `cache`. Set `cache.mode` to `automatic` for provider-native
+prefix caching or `explicit` with up to four `points` for exact breakpoints.
+Points target tools, instructions, or a message index and optional `partIndex`
+within `contentParts`. Optional `affinityKey` and `isolationKey` are sent only
+through fields configured on the selected provider. An isolation key excludes
+providers without a mapping; explicit mode excludes providers without exact
+marker support. The selected attempt records whether affinity was applied.
+`kind: "generate"` is a single generation;
+`kind: "run"` can pause for tools or context refreshes. The SDK exports
+`uuid7`, typed request/inspection records, and `ConstellationError` with HTTP status,
+error code, and message. All calls use the configured timeout (30 seconds by
+default) and an optional abort signal.
+
+This package covers execution requests. Model discovery (`GET /v1/models`,
+`POST /v1/registry/resolve`), provider HTTP capture, the management APIs, and
+operator APIs are available over HTTP; see the [HTTP API guide](../../docs/registry-api.md)
+and the in-app Documentation page for those endpoint contracts. `events()` uses
+SSE and reconnects from the durable cursor. Aborting `drive()` disconnects the consumer but does not
+cancel the Constellation request.

package/dist/index.d.ts

@@ -0,0 +1,306 @@
+/** Durable request client. No provider credentials or agent definitions live here. */
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type Tool = {
+    name: string;
+    description?: string;
+    inputSchema: Json;
+};
+export type ToolCall = {
+    id: string;
+    name: string;
+    arguments: Json;
+};
+export type Message = {
+    role: "system" | "user" | "assistant" | "tool";
+    text?: string;
+    /** Ordered text parts, used when a cache point must end within a message. */
+    contentParts?: string[];
+    nativeContent?: Json;
+    toolCalls?: ToolCall[];
+    toolResults?: {
+        id: string;
+        result: Json;
+        isError?: boolean;
+    }[];
+};
+export type RequestInput = {
+    idempotencyKey: string;
+    externalId?: string;
+    workspaceId: string;
+    userId?: string;
+    planId?: string;
+    model: string;
+    kind: "generate" | "run";
+    instructions?: string;
+    messages: Message[];
+    tools?: Tool[];
+    parameters?: Record<string, Json>;
+    maxSteps?: number;
+    timeoutMs?: number;
+    maxOutputTokens?: number;
+    prepareStep?: boolean;
+    cache?: {
+        mode: "automatic" | "explicit";
+        points?: ({
+            target: "tools" | "instructions";
+        } | {
+            target: "message";
+            index: number;
+            partIndex?: number;
+        })[];
+        affinityKey?: string;
+        isolationKey?: string;
+    };
+};
+export type Status = "queued" | "running" | "waiting" | "completed" | "failed" | "cancelled";
+export type RequestRecord = {
+    id: string;
+    externalId: string | null;
+    workspaceId: string;
+    userId: string | null;
+    kind: "generate" | "run";
+    requestedModel: string;
+    virtualModel: boolean;
+    planId: string | null;
+    catalogRevision: number;
+    status: Status;
+    reason: string | null;
+    error: Json;
+    output: {
+        text: string;
+        reasoning: string;
+        toolCalls: ToolCall[];
+    } | null;
+    stepCount: number;
+    customerCost: string | null;
+    supplierCost: string | null;
+    resolution: Json;
+    rules: Json;
+    createdAt: string;
+    endedAt: string | null;
+    deadline: string;
+};
+export type Step = {
+    id: string;
+    requestId: string;
+    idx: number;
+    input: Json;
+    inputHash: string;
+    status: string;
+    output: Json;
+    usage: Json;
+    customerPrice: Json;
+    customerCost: string | null;
+    supplierCost: string | null;
+    finishReason: string | null;
+    startedAt: string;
+    endedAt: string | null;
+};
+export type Attempt = {
+    id: string;
+    requestId: string;
+    stepId: string;
+    idx: number;
+    requestedModel: string;
+    actualModel: string;
+    providerId: string;
+    offeringId: string;
+    providerModel: string;
+    connectionKind: string;
+    endpoint: string;
+    fallback: boolean;
+    status: string;
+    committed: boolean;
+    supplierPrice: Json;
+    customerPrice: Json;
+    parameters: Json;
+    usage: Json;
+    supplierCost: string | null;
+    customerCost: string | null;
+    error: Json;
+    finishReason: string | null;
+    httpStatus: number | null;
+    ttfbMs: number | null;
+    ttftMs: number | null;
+    startedAt: string;
+    endedAt: string | null;
+};
+export type PendingInput = {
+    id: string;
+    requestId: string;
+    stepId: string | null;
+    kind: "tool" | "prepare_step" | "user_input";
+    payload: {
+        providerCallId?: string;
+        name?: string;
+        arguments?: Json;
+        validationError?: string | null;
+    };
+    claimId: string | null;
+    response: Json;
+    resolvedAt: string | null;
+};
+export type Span = {
+    id: string;
+    stepId?: string | null;
+    attemptId?: string | null;
+    parentSpanId?: string | null;
+    name: string;
+    startedAt: string;
+    endedAt?: string | null;
+    status: "running" | "ok" | "error" | "cancelled";
+    attributes?: Record<string, Json>;
+};
+export type Log = {
+    id: string;
+    stepId?: string | null;
+    spanId?: string | null;
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+    timestamp: string;
+    attributes?: Record<string, Json>;
+};
+export type Inspection = {
+    usage?: Json;
+    input?: Json;
+    effectiveInput?: Json;
+    request: RequestRecord;
+    steps: Step[];
+    attempts: Attempt[];
+    inputs: PendingInput[];
+    spans: Span[];
+    logs: Log[];
+};
+export type RecordTypes = {
+    steps: Step;
+    attempts: Attempt;
+    inputs: PendingInput;
+    spans: Span;
+    logs: Log;
+};
+export type InputResponse = {
+    claimId?: string;
+    result?: Json;
+    isError?: boolean;
+    instructions?: string;
+    tools?: Tool[];
+    action?: "continue" | "refresh_context" | "wait_for_user" | "complete";
+};
+export type RequestEvent = {
+    seq: number;
+    type: string;
+    data: Record<string, Json>;
+    timestamp: string;
+};
+export declare class ConstellationError extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare function uuid7(): string;
+export declare class Constellation {
+    private options;
+    private fetcher;
+    constructor(options: {
+        baseUrl: string;
+        apiKey?: string;
+        apiPrefix?: "/v1" | "/internal";
+        fetch?: typeof fetch;
+        timeoutMs?: number;
+    });
+    private url;
+    private call;
+    submit(input: RequestInput, signal?: AbortSignal): Promise<{
+        id: string;
+    }>;
+    inspect(id: string, signal?: AbortSignal): Promise<Inspection>;
+    /** Request context without loading historical telemetry. Fetch records by page. */
+    inspectSummary(id: string, signal?: AbortSignal): Promise<Inspection>;
+    records<K extends keyof RecordTypes>(id: string, kind: K, query?: {
+        id?: string;
+        q?: string;
+        level?: Log["level"];
+        offset?: number;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<{
+        items: RecordTypes[K][];
+        total: number;
+        offset: number;
+        limit: number;
+    }>;
+    resolve(input: RequestInput, signal?: AbortSignal): Promise<{
+        revision: number;
+        resolution: Record<string, Json>;
+        rules: Record<string, Json>;
+        allowed: boolean;
+        dispatched: false;
+    }>;
+    list(query?: {
+        q?: string;
+        requestId?: string;
+        requestIdNot?: string;
+        externalId?: string;
+        externalIdNot?: string;
+        externalIdContains?: string;
+        externalIdNotContains?: string;
+        workspaceId?: string;
+        workspaceIdNot?: string;
+        userId?: string;
+        userIdNot?: string;
+        status?: Status;
+        statusNot?: Status;
+        requestedModel?: string;
+        requestedModelNot?: string;
+        requestedModelContains?: string;
+        requestedModelNotContains?: string;
+        limit?: number;
+        offset?: number;
+    }, signal?: AbortSignal): Promise<{
+        items: RequestRecord[];
+        total: number;
+        offset: number;
+        limit: number;
+    }>;
+    cancel(id: string, signal?: AbortSignal): Promise<void>;
+    claim(id: string, inputId: string, claimId: string, signal?: AbortSignal): Promise<void>;
+    respond(id: string, inputId: string, response: InputResponse, signal?: AbortSignal): Promise<void>;
+    addSpans(id: string, spans: Span[], signal?: AbortSignal): Promise<void>;
+    addLogs(id: string, logs: Log[], signal?: AbortSignal): Promise<void>;
+    startSpan(id: string, name: string, options?: {
+        stepId?: string;
+        attemptId?: string;
+        parentSpanId?: string;
+        startedAt?: string;
+        attributes?: Record<string, Json>;
+    }, signal?: AbortSignal): Promise<{
+        id: string;
+        end: (options?: {
+            endedAt?: string;
+            status?: "ok" | "error" | "cancelled";
+            attributes?: Record<string, Json>;
+        }, signal?: AbortSignal) => Promise<void>;
+    }>;
+    /** Live SSE delivery with durable cursor replay after disconnects. */
+    events(id: string, options?: {
+        after?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<RequestEvent>;
+    /** Disconnecting this consumer leaves unresolved inputs durably waiting in Constellation. */
+    drive(id: string, options?: {
+        tools?: Record<string, (args: Json, context: {
+            inputId: string;
+            requestId: string;
+            signal?: AbortSignal;
+        }) => Promise<Json>>;
+        prepareStep?: (state: Inspection, context: {
+            inputId: string;
+            signal: AbortSignal;
+        }) => Promise<Pick<InputResponse, "instructions" | "tools" | "action">>;
+        signal?: AbortSignal;
+        consumerId?: string;
+        toolTimeoutMs?: number;
+        onUpdate?: (state: Inspection) => void;
+    }): Promise<Inspection>;
+}

package/dist/index.js

@@ -0,0 +1,314 @@
+export class ConstellationError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "ConstellationError";
+    }
+}
+export function uuid7() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    let ms = Date.now();
+    for (let i = 5; i >= 0; i--) {
+        bytes[i] = ms % 256;
+        ms = Math.floor(ms / 256);
+    }
+    bytes[6] = 0x70 | (bytes[6] & 0x0f);
+    bytes[8] = 0x80 | (bytes[8] & 0x3f);
+    const h = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+const terminal = (s) => ["completed", "failed", "cancelled"].includes(s);
+async function pause(ms, signal) {
+    signal?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason ?? new DOMException("Aborted", "AbortError"));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+async function bounded(promise, signal) {
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+        promise
+            .then(resolve, reject)
+            .finally(() => signal.removeEventListener("abort", abort));
+    });
+}
+export class Constellation {
+    options;
+    fetcher;
+    constructor(options) {
+        this.options = options;
+        this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    url(path) {
+        return `${this.options.baseUrl.replace(/\/$/, "")}${path.replace(/^\/v1(?=\/)/, this.options.apiPrefix ?? "/v1")}`;
+    }
+    async call(path, method = "GET", body, signal) {
+        const response = await this.fetcher(this.url(path), {
+            method,
+            headers: {
+                ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+                ...(this.options.apiKey
+                    ? { Authorization: `Bearer ${this.options.apiKey}` }
+                    : {}),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: signal
+                ? AbortSignal.any([
+                    signal,
+                    AbortSignal.timeout(this.options.timeoutMs ?? 30000),
+                ])
+                : AbortSignal.timeout(this.options.timeoutMs ?? 30000),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            throw new ConstellationError(response.status, body.error?.code ?? "http_error", body.error?.message ?? `Constellation returned ${response.status}`);
+        }
+        return response.status === 204
+            ? undefined
+            : response.json();
+    }
+    submit(input, signal) {
+        return this.call("/v1/requests", "POST", input, signal);
+    }
+    inspect(id, signal) {
+        return this.call(`/v1/requests/${encodeURIComponent(id)}`, "GET", undefined, signal);
+    }
+    /** Request context without loading historical telemetry. Fetch records by page. */
+    inspectSummary(id, signal) {
+        return this.call(`/v1/requests/${encodeURIComponent(id)}?summary=true`, "GET", undefined, signal);
+    }
+    records(id, kind, query = {}, signal) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(query))
+            if (value !== undefined)
+                params.set(key, String(value));
+        return this.call(`/v1/requests/${encodeURIComponent(id)}/records/${kind}?${params}`, "GET", undefined, signal);
+    }
+    resolve(input, signal) {
+        return this.call("/v1/requests/resolve", "POST", input, signal);
+    }
+    list(query = {}, signal) {
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(query))
+            if (v !== undefined)
+                params.set(k, String(v));
+        return this.call(`/v1/requests?${params}`, "GET", undefined, signal);
+    }
+    cancel(id, signal) {
+        return this.call(`/v1/requests/${encodeURIComponent(id)}/cancel`, "POST", {}, signal);
+    }
+    claim(id, inputId, claimId, signal) {
+        return this.call(`/v1/requests/${encodeURIComponent(id)}/inputs/${encodeURIComponent(inputId)}/claim`, "POST", { claimId }, signal);
+    }
+    respond(id, inputId, response, signal) {
+        return this.call(`/v1/requests/${encodeURIComponent(id)}/inputs/${encodeURIComponent(inputId)}`, "POST", response, signal);
+    }
+    addSpans(id, spans, signal) {
+        return this.call(`/v1/requests/${encodeURIComponent(id)}/spans`, "POST", spans, signal);
+    }
+    addLogs(id, logs, signal) {
+        return this.call(`/v1/requests/${encodeURIComponent(id)}/logs`, "POST", logs, signal);
+    }
+    async startSpan(id, name, options = {}, signal) {
+        const span = {
+            id: uuid7(),
+            name,
+            startedAt: options.startedAt ?? new Date().toISOString(),
+            status: "running",
+            ...options,
+        };
+        await this.addSpans(id, [span], signal);
+        let closed;
+        return {
+            id: span.id,
+            end: (options = {}, signal) => {
+                closed = {
+                    ...span,
+                    endedAt: options.endedAt ?? closed?.endedAt ?? new Date().toISOString(),
+                    status: options.status ?? closed?.status ?? "ok",
+                    attributes: options.attributes ?? closed?.attributes ?? span.attributes,
+                };
+                return this.addSpans(id, [closed], signal);
+            },
+        };
+    }
+    /** Live SSE delivery with durable cursor replay after disconnects. */
+    async *events(id, options = {}) {
+        let after = options.after ?? 0;
+        while (true) {
+            options.signal?.throwIfAborted();
+            const connecting = new AbortController();
+            const connectTimeout = setTimeout(() => connecting.abort(), this.options.timeoutMs ?? 30000);
+            const response = await Promise.resolve().then(() => this.fetcher(this.url(`/v1/requests/${encodeURIComponent(id)}/stream?after=${after}`), {
+                headers: {
+                    Accept: "text/event-stream",
+                    ...(this.options.apiKey ? { Authorization: `Bearer ${this.options.apiKey}` } : {}),
+                },
+                signal: options.signal ? AbortSignal.any([options.signal, connecting.signal]) : connecting.signal,
+            })).catch(async () => {
+                clearTimeout(connectTimeout);
+                options.signal?.throwIfAborted();
+                await pause(500, options.signal);
+                return null;
+            });
+            clearTimeout(connectTimeout);
+            if (!response)
+                continue;
+            if (!response.ok || !response.body) {
+                throw new ConstellationError(response.status, "stream_error", `Event stream returned ${response.status}`);
+            }
+            const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+            let buffer = "";
+            try {
+                while (true) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += value.replace(/\r\n/g, "\n");
+                    let boundary;
+                    while ((boundary = buffer.indexOf("\n\n")) >= 0) {
+                        const frame = buffer.slice(0, boundary);
+                        buffer = buffer.slice(boundary + 2);
+                        const data = frame.split("\n").filter((line) => line.startsWith("data:"))
+                            .map((line) => line.slice(5).trimStart()).join("\n");
+                        if (!data)
+                            continue;
+                        const event = JSON.parse(data);
+                        if (event.seq <= after)
+                            continue;
+                        after = event.seq;
+                        yield event;
+                        if (["request.completed", "request.failed", "request.cancelled"].includes(event.type))
+                            return;
+                    }
+                }
+            }
+            catch {
+                options.signal?.throwIfAborted();
+                // A broken live connection resumes from the last delivered sequence.
+            }
+            finally {
+                await reader.cancel().catch(() => { });
+            }
+            const inspection = await this.inspect(id, options.signal);
+            if (terminal(inspection.request.status)) {
+                const tail = await this.call(`/v1/requests/${encodeURIComponent(id)}/events?after=${after}`, "GET", undefined, options.signal);
+                for (const event of tail.items) {
+                    if (event.seq <= after)
+                        continue;
+                    after = event.seq;
+                    yield event;
+                }
+                if (tail.items.length < 500)
+                    return;
+                continue;
+            }
+            await pause(500, options.signal);
+        }
+    }
+    /** Disconnecting this consumer leaves unresolved inputs durably waiting in Constellation. */
+    async drive(id, options = {}) {
+        const consumerId = options.consumerId ?? uuid7();
+        while (true) {
+            const state = await this.inspect(id, options.signal);
+            options.onUpdate?.(state);
+            if (terminal(state.request.status))
+                return state;
+            for (const pending of state.inputs.filter((i) => !i.resolvedAt)) {
+                if (pending.claimId && pending.claimId !== consumerId)
+                    continue;
+                if (pending.kind === "prepare_step" && options.prepareStep) {
+                    try {
+                        await this.claim(id, pending.id, consumerId, options.signal);
+                    }
+                    catch (error) {
+                        if (error instanceof ConstellationError && error.status === 409)
+                            continue;
+                        throw error;
+                    }
+                    let closed = false;
+                    const preparation = await this.startSpan(id, "caller.prepare_step", { attributes: { inputId: pending.id } }, options.signal);
+                    try {
+                        const signal = options.signal
+                            ? AbortSignal.any([
+                                options.signal,
+                                AbortSignal.timeout(options.toolTimeoutMs ?? 30000),
+                            ])
+                            : AbortSignal.timeout(options.toolTimeoutMs ?? 30000);
+                        const response = await bounded(options.prepareStep(state, { inputId: pending.id, signal }), signal);
+                        await preparation.end({}, options.signal);
+                        closed = true;
+                        await this.respond(id, pending.id, { ...response, claimId: consumerId }, options.signal);
+                    }
+                    catch (error) {
+                        if (!options.signal?.aborted && !closed)
+                            await preparation
+                                .end({ status: "error" }, options.signal)
+                                .catch(() => { });
+                        throw error;
+                    }
+                    continue;
+                }
+                if (pending.kind !== "tool")
+                    continue;
+                const tool = options.tools?.[pending.payload.name ?? ""];
+                if (!tool && !pending.payload.validationError)
+                    continue;
+                try {
+                    await this.claim(id, pending.id, consumerId, options.signal);
+                }
+                catch (error) {
+                    if (error instanceof ConstellationError && error.status === 409)
+                        continue;
+                    throw error;
+                }
+                const span = await this.startSpan(id, `tool.${pending.payload.name}`, {
+                    stepId: pending.stepId ?? undefined,
+                    attributes: { inputId: pending.id },
+                }, options.signal);
+                let result;
+                let isError = false;
+                try {
+                    if (pending.payload.validationError)
+                        throw new Error(pending.payload.validationError);
+                    if (!tool)
+                        throw new Error("Tool unavailable");
+                    const toolSignal = options.signal
+                        ? AbortSignal.any([
+                            options.signal,
+                            AbortSignal.timeout(options.toolTimeoutMs ?? 30000),
+                        ])
+                        : AbortSignal.timeout(options.toolTimeoutMs ?? 30000);
+                    result = await bounded(tool(pending.payload.arguments ?? {}, {
+                        inputId: pending.id,
+                        requestId: id,
+                        signal: toolSignal,
+                    }), toolSignal);
+                }
+                catch (error) {
+                    options.signal?.throwIfAborted();
+                    isError = true;
+                    result = {
+                        error: error instanceof Error ? error.message : "Tool failed",
+                    };
+                }
+                await span.end({ status: isError ? "error" : "ok" }, options.signal);
+                await this.respond(id, pending.id, { result, isError, claimId: consumerId }, options.signal);
+            }
+            await pause(500, options.signal);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@lionhummer/constellation",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FlatFilers/constellation.git",
+    "directory": "packages/sdk"
+  },
+  "files": ["dist", "README.md"],
+  "publishConfig": { "access": "public" },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution Bundler --lib ES2022,DOM src/index.ts"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0"
+  }
+}