@darqlabs/curator-sdk 0.1.0

package/dist/esm/client.js

@@ -0,0 +1,411 @@
+/**
+ * Public surface of the Curator SDK.
+ *
+ *   const curator = new Curator({ apiKey, project, environment })
+ *   const reply = await curator.agent("support-bot").run("hello")
+ *
+ *   const chat = curator.agent("support-bot").chat()
+ *   const r1 = await chat.send("first")
+ *   const r2 = await chat.send("follow up")
+ *
+ *   const chat = curator.agent("support-bot").conversation("conv_xxx")
+ *   const r = await chat.send("continuing later")
+ *
+ * Both helpers route through `?wait=true` under the hood — the caller
+ * never sees `run_id` or has to poll. Non-completion states (HITL
+ * pause, terminal agent error, timeout) surface as typed errors from
+ * `./errors`. HITL approvals are NOT resolved through the SDK — the
+ * pause is surfaced as an error so the calling app can tell its user
+ * to contact an administrator, who handles it in the dashboard.
+ */
+import { CuratorAgentError, CuratorApprovalRequiredError, CuratorError, CuratorTimeoutError, } from "./errors.js";
+import { Files } from "./files.js";
+import { HttpClient } from "./http.js";
+import { parseSseStream } from "./sse.js";
+import { frameToStreamEvent } from "./streamEventParse.js";
+import { isTerminalStreamEvent } from "./streamEvents.js";
+const DEFAULT_BASE_URL = "https://app.darqlabs.ai";
+const DEFAULT_TIMEOUT_MS = 120_000;
+export class Curator {
+    http;
+    defaultProject;
+    defaultEnvironment;
+    defaultTimeoutMs;
+    /** File-upload surface — see {@link Files}. */
+    files;
+    constructor(opts) {
+        const baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;
+        // Same bind-to-host dance as HttpClient — needed because the bare
+        // `globalThis.fetch` reference loses its `this` when invoked through
+        // a stashed variable, and browsers reject that with "Illegal invocation".
+        const globalFetch = globalThis.fetch;
+        const fetchImpl = opts.fetch ?? (globalFetch ? globalFetch.bind(globalThis) : undefined);
+        this.http = new HttpClient({
+            apiKey: opts.apiKey,
+            baseUrl,
+            fetch: opts.fetch,
+            defaultHeaders: opts.defaultHeaders,
+            endUserJwt: opts.endUserJwt,
+        });
+        this.defaultProject = opts.project;
+        this.defaultEnvironment = opts.environment ?? "production";
+        this.defaultTimeoutMs = opts.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.files = new Files(this.http, stripTrailingSlash(baseUrl), fetchImpl);
+    }
+    /**
+     * Address an agent deployment by its slug. Project / environment fall
+     * back to the constructor defaults; pass overrides via the second arg.
+     */
+    agent(slug, locator = {}) {
+        return new Agent(this.http, this.defaultTimeoutMs, this.resolveRoute(slug, locator));
+    }
+    resolveRoute(deployment, locator) {
+        if (locator.system) {
+            if (locator.project) {
+                throw new CuratorError("Cannot combine `system: true` with `project`.");
+            }
+            return { kind: "system", deployment };
+        }
+        const project = locator.project ?? this.defaultProject;
+        const environment = locator.environment ?? this.defaultEnvironment;
+        if (!project) {
+            throw new CuratorError("No project specified. Set `project` on `new Curator({ ... })` or pass it as the second arg to `agent(slug, { project })`. " +
+                "If the deployment is system-scoped, pass `{ system: true }`.");
+        }
+        return { kind: "project", project, environment, deployment };
+    }
+}
+export class Agent {
+    http;
+    defaultTimeoutMs;
+    route;
+    /** @internal */
+    constructor(http, defaultTimeoutMs, route) {
+        this.http = http;
+        this.defaultTimeoutMs = defaultTimeoutMs;
+        this.route = route;
+    }
+    /**
+     * Open a fresh conversation, send `content`, await the reply, and
+     * return it. Equivalent to `agent.chat().send(content)` but one line.
+     */
+    async run(content, opts = {}) {
+        return this.chat().send(content, opts);
+    }
+    /**
+     * Open a fresh conversation and stream the reply as it's generated.
+     * Equivalent to `agent.chat().stream(content)`.
+     */
+    stream(content, opts = {}) {
+        return this.chat().stream(content, opts);
+    }
+    /**
+     * Return a Chat handle whose conversation is created lazily on the
+     * first `send(...)`. Subsequent sends reuse the same conversation.
+     */
+    chat() {
+        return new Chat(this.http, this.defaultTimeoutMs, this.route, null);
+    }
+    /**
+     * Reattach to an existing conversation by id (e.g. resuming a chat
+     * across processes or restoring from durable state).
+     */
+    conversation(conversationId) {
+        return new Chat(this.http, this.defaultTimeoutMs, this.route, conversationId);
+    }
+    /**
+     * Fetch this deployment's read-only client config (branding entitlements,
+     * etc.). Resolved server-side from the org's subscription tier. No side
+     * effects — safe to call on widget mount. `<CuratorChat />` uses this to
+     * decide whether to render the "Powered by Curator" footer.
+     */
+    async config() {
+        const envelope = await this.http.request(`${this.http.deploymentBase(this.route)}/config`, { method: "GET" });
+        return {
+            branding: {
+                hidePoweredBy: envelope.data.branding?.hide_powered_by === true,
+            },
+        };
+    }
+}
+export class Chat {
+    http;
+    defaultTimeoutMs;
+    route;
+    conversationId;
+    /** Cached promise for an in-flight `POST /conversations`. */
+    pendingCreate = null;
+    /** @internal */
+    constructor(http, defaultTimeoutMs, route, initialConversationId) {
+        this.http = http;
+        this.defaultTimeoutMs = defaultTimeoutMs;
+        this.route = route;
+        this.conversationId = initialConversationId;
+    }
+    /**
+     * Conversation id, or `null` until the first send creates one.
+     * Use `.ensureId()` if you need to materialize the conversation
+     * eagerly without sending a message.
+     */
+    get id() {
+        return this.conversationId;
+    }
+    /** Force conversation creation now and return its id. */
+    async ensureId() {
+        if (this.conversationId)
+            return this.conversationId;
+        if (this.pendingCreate)
+            return this.pendingCreate;
+        this.pendingCreate = this.createConversation().finally(() => {
+            this.pendingCreate = null;
+        });
+        return this.pendingCreate;
+    }
+    /**
+     * Send a user message and await the assistant's reply. Lazily creates
+     * the conversation if needed. Returns the final assistant message.
+     *
+     * Throws:
+     *   - CuratorApprovalRequiredError if the run pauses for HITL (an
+     *     administrator must resolve it in the dashboard)
+     *   - CuratorAgentError on terminal agent failure
+     *   - CuratorTimeoutError if the wait expires (the run keeps running)
+     */
+    async send(content, opts = {}) {
+        if (!content && !opts.files?.length) {
+            throw new CuratorError("Either `content` or `files` must be provided.");
+        }
+        const conversationId = await this.ensureId();
+        const timeoutMs = opts.timeoutMs ?? this.defaultTimeoutMs;
+        const body = { content };
+        if (opts.files?.length) {
+            body.files = opts.files.map(toServerFile);
+        }
+        const envelope = await this.http.request(`${this.http.deploymentBase(this.route)}/conversations/${encodeURIComponent(conversationId)}/messages`, {
+            method: "POST",
+            query: { wait: "true", timeout_ms: timeoutMs },
+            body,
+            // Give the underlying fetch a small slack window over the server
+            // timeout — the server returns a structured `status: 'timeout'`
+            // payload that we want to surface as CuratorTimeoutError rather
+            // than an aborted fetch.
+            signalTimeoutMs: timeoutMs + 10_000,
+        });
+        return this.unwrapWaitOutcome(envelope.data);
+    }
+    /**
+     * Send a user message and stream the agent's response back as it's
+     * generated. Each yielded event is one of `delta` / `tool_call.*` /
+     * `done` / `error` / `paused_for_approval`. The iterator ends on the
+     * first terminal event.
+     *
+     *   for await (const e of chat.stream("hello")) {
+     *     if (e.type === "delta") process.stdout.write(e.text)
+     *     if (e.type === "done") console.log("\nfinal:", e.message?.content)
+     *   }
+     *
+     * Aborting the iteration (breaking out of the loop, or calling
+     * `.return()`) closes the underlying HTTP connection — the server-
+     * side run keeps going independently. Use `chat.history()` later to
+     * fetch what landed.
+     */
+    async *stream(content, opts = {}) {
+        if (!content && !opts.files?.length) {
+            throw new CuratorError("Either `content` or `files` must be provided.");
+        }
+        const conversationId = await this.ensureId();
+        const body = { content };
+        if (opts.files?.length) {
+            body.files = opts.files.map(toServerFile);
+        }
+        const controller = new AbortController();
+        const response = await this.http.streamPost(`${this.http.deploymentBase(this.route)}/conversations/${encodeURIComponent(conversationId)}/messages`, {
+            body,
+            query: { stream: "true" },
+            signal: controller.signal,
+        });
+        try {
+            for await (const frame of parseSseStream(response.body)) {
+                const event = frameToStreamEvent(frame);
+                if (!event)
+                    continue;
+                yield event;
+                if (isTerminalStreamEvent(event))
+                    return;
+            }
+        }
+        finally {
+            try {
+                controller.abort();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    /** Fetch (paginated) conversation history. */
+    async history(opts = {}) {
+        const conversationId = await this.ensureId();
+        const envelope = await this.http.request(`${this.http.deploymentBase(this.route)}/conversations/${encodeURIComponent(conversationId)}`, {
+            query: {
+                limit: opts.limit,
+                before_sequence: opts.beforeSequence,
+            },
+        });
+        const messages = envelope.data.messages.map((m) => adaptHistoryMessage(m));
+        return {
+            messages,
+            hasMore: envelope.data.has_more_messages,
+            oldestSequence: envelope.data.oldest_loaded_sequence,
+            totalMessageCount: envelope.data.message_count,
+        };
+    }
+    // ── internals ────────────────────────────────────────────────────
+    async createConversation() {
+        const envelope = await this.http.request(`${this.http.deploymentBase(this.route)}/conversations`, {
+            method: "POST",
+        });
+        this.conversationId = envelope.data.conversation_id;
+        return this.conversationId;
+    }
+    /**
+     * Continue waiting for the next terminal state on an already-running
+     * conversation. Used to back `CuratorTimeoutError.continueWaiting()`.
+     *
+     * The server-side wait endpoint hangs off `POST /messages`, so to
+     * re-wait without sending a new user message we poll history for an
+     * assistant message whose `sequence` exceeds the baseline established
+     * before the wait began. For a still-in-flight run, the assistant
+     * reply typically lands within seconds.
+     */
+    async waitForNextReply(timeoutMs) {
+        const conversationId = await this.ensureId();
+        const deadline = Date.now() + timeoutMs;
+        let baseline = await this.latestSequence(conversationId);
+        while (Date.now() < deadline) {
+            await sleep(1_500);
+            const latest = await this.latestSequence(conversationId);
+            if (latest <= baseline)
+                continue;
+            const page = await this.history({ limit: 50 });
+            for (let i = page.messages.length - 1; i >= 0; i--) {
+                const m = page.messages[i];
+                if (m.role === "assistant" && m.sequence > baseline) {
+                    return {
+                        ...m,
+                        runId: "<resumed>",
+                        conversationId,
+                    };
+                }
+            }
+            baseline = latest;
+        }
+        throw new CuratorTimeoutError({
+            conversationId,
+            runId: "<resumed>",
+            continueWaiting: (next) => this.waitForNextReply(next ?? this.defaultTimeoutMs),
+        });
+    }
+    async latestSequence(conversationId) {
+        const envelope = await this.http.request(`${this.http.deploymentBase(this.route)}/conversations/${encodeURIComponent(conversationId)}`, { query: { limit: 1 } });
+        const list = envelope.data.messages;
+        return list.length > 0 ? list[list.length - 1].sequence : 0;
+    }
+    unwrapWaitOutcome(data) {
+        const { run_id, conversation_id, status } = data;
+        switch (status) {
+            case "completed": {
+                const msg = data.message;
+                if (!msg) {
+                    throw new CuratorError("Server returned `completed` without a message payload.");
+                }
+                return {
+                    role: "assistant",
+                    content: msg.content,
+                    sequence: msg.sequence,
+                    stepId: msg.step_id,
+                    createdAt: msg.created_at,
+                    runId: run_id,
+                    conversationId: conversation_id,
+                };
+            }
+            case "paused_for_approval": {
+                const approval = data.approval;
+                if (!approval) {
+                    throw new CuratorError("Server returned `paused_for_approval` without approval payload.");
+                }
+                throw new CuratorApprovalRequiredError({
+                    approval,
+                    conversationId: conversation_id,
+                    runId: run_id,
+                });
+            }
+            case "errored": {
+                const err = data.error;
+                if (!err) {
+                    throw new CuratorError("Server returned `errored` without error payload.");
+                }
+                throw new CuratorAgentError({
+                    message: err.message,
+                    failureClass: err.failure_class,
+                    isPermanent: err.is_permanent,
+                    stepId: err.step_id ?? null,
+                    conversationId: conversation_id,
+                    runId: run_id,
+                });
+            }
+            case "timeout":
+                throw new CuratorTimeoutError({
+                    conversationId: conversation_id,
+                    runId: run_id,
+                    continueWaiting: (next) => this.waitForNextReply(next ?? this.defaultTimeoutMs),
+                });
+        }
+    }
+}
+function adaptHistoryMessage(m) {
+    if (m.role === "assistant") {
+        return {
+            role: "assistant",
+            content: m.content,
+            sequence: m.sequence,
+            stepId: m.step_id,
+            createdAt: m.created_at,
+            // History endpoint doesn't return run_id / conversation_id per
+            // row — callers that need them should track separately.
+            runId: "<historical>",
+            conversationId: "<historical>",
+        };
+    }
+    if (m.role === "tool") {
+        return {
+            role: "tool",
+            content: m.content,
+            sequence: m.sequence,
+            toolCallId: m.tool_call_id,
+            createdAt: m.created_at,
+        };
+    }
+    return {
+        role: "user",
+        content: m.content,
+        sequence: m.sequence,
+        createdAt: m.created_at,
+    };
+}
+function toServerFile(f) {
+    return {
+        storageKey: f.storageKey,
+        mimeType: f.mimeType,
+        filename: f.filename,
+        size: f.size,
+        artifactId: f.artifactId,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function stripTrailingSlash(s) {
+    return s.replace(/\/+$/, "");
+}
+//# sourceMappingURL=client.js.map

package/dist/esm/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/esm/errors.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Typed errors the SDK throws.
+ *
+ * Happy-path code reads the return value of `agent.run(...)` or
+ * `chat.send(...)`. Anything else — HITL pauses, agent-side errors,
+ * timeouts, HTTP failures — surfaces as one of these. Catch the
+ * specific class you care about; everything inherits from
+ * `CuratorError` so a single `catch (err: CuratorError)` works as a
+ * backstop.
+ */
+import type { AssistantMessage, ApprovalDetails, AgentFailureClass } from "./types.js";
+export declare class CuratorError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** HTTP 401 from the API — your API key is missing, invalid, or revoked. */
+export declare class CuratorAuthError extends CuratorError {
+    constructor(message?: string);
+}
+/** HTTP 403 from the API — your API key doesn't have permission for this action. */
+export declare class CuratorForbiddenError extends CuratorError {
+    constructor(message?: string);
+}
+/** HTTP 404 from the API — the deployment slug or conversation id wasn't found. */
+export declare class CuratorNotFoundError extends CuratorError {
+    constructor(message?: string);
+}
+/** HTTP 410 from the API — the deployment was retired. */
+export declare class CuratorDeploymentRetiredError extends CuratorError {
+    readonly retiredAt: string | null;
+    constructor(message: string, retiredAt: string | null);
+}
+/** HTTP 429 from the API — back off. */
+export declare class CuratorRateLimitError extends CuratorError {
+    readonly retryAfterSeconds: number | null;
+    constructor(message?: string, retryAfterSeconds?: number | null);
+}
+/**
+ * Run paused waiting for human approval. Approval resolution is not
+ * exposed to API consumers — pauses are routed through the dashboard
+ * by an org administrator. The error carries the approval payload so
+ * the caller can surface a friendly "contact your administrator"
+ * message that mentions the specific tool.
+ */
+export declare class CuratorApprovalRequiredError extends CuratorError {
+    readonly approval: ApprovalDetails;
+    readonly conversationId: string;
+    readonly runId: string;
+    constructor(args: {
+        approval: ApprovalDetails;
+        conversationId: string;
+        runId: string;
+    });
+}
+/**
+ * The agent run reached a terminal error state (LLM quota, auth, 5xx
+ * exhausted retries, etc.). `failureClass` and `isPermanent` mirror the
+ * server's classification so callers can decide whether to retry.
+ */
+export declare class CuratorAgentError extends CuratorError {
+    readonly failureClass: AgentFailureClass;
+    readonly isPermanent: boolean;
+    readonly conversationId: string;
+    readonly runId: string;
+    readonly stepId: string | null;
+    constructor(args: {
+        message: string;
+        failureClass: AgentFailureClass;
+        isPermanent: boolean;
+        conversationId: string;
+        runId: string;
+        stepId?: string | null;
+    });
+}
+/**
+ * The synchronous wait expired. The agent run keeps running on the
+ * server; call `.continueWaiting()` to resume listening, or fetch
+ * history later via `chat.history()`.
+ */
+export declare class CuratorTimeoutError extends CuratorError {
+    readonly conversationId: string;
+    readonly runId: string;
+    readonly continueWaiting: (timeoutMs?: number) => Promise<AssistantMessage>;
+    constructor(args: {
+        conversationId: string;
+        runId: string;
+        continueWaiting: (timeoutMs?: number) => Promise<AssistantMessage>;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEtF,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQ3D;AAED,4EAA4E;AAC5E,qBAAa,gBAAiB,SAAQ,YAAY;gBACpC,OAAO,SAA+B;CAInD;AAED,oFAAoF;AACpF,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,OAAO,SAAsB;CAI1C;AAED,mFAAmF;AACnF,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,SAAuB;CAI3C;AAED,0DAA0D;AAC1D,qBAAa,6BAA8B,SAAQ,YAAY;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;gBACrB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;CAKtD;AAED,wCAAwC;AACxC,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;gBAC7B,OAAO,SAAwB,EAAE,iBAAiB,GAAE,MAAM,GAAG,IAAW;CAKrF;AAED;;;;;;GAMG;AACH,qBAAa,4BAA6B,SAAQ,YAAY;IAC5D,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;gBAEV,IAAI,EAAE;QAChB,QAAQ,EAAE,eAAe,CAAA;QACzB,cAAc,EAAE,MAAM,CAAA;QACtB,KAAK,EAAE,MAAM,CAAA;KACd;CAUF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAA;IACxC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;gBAElB,IAAI,EAAE;QAChB,OAAO,EAAE,MAAM,CAAA;QACf,YAAY,EAAE,iBAAiB,CAAA;QAC/B,WAAW,EAAE,OAAO,CAAA;QACpB,cAAc,EAAE,MAAM,CAAA;QACtB,KAAK,EAAE,MAAM,CAAA;QACb,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KACvB;CASF;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,eAAe,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAA;gBAE/D,IAAI,EAAE;QAChB,cAAc,EAAE,MAAM,CAAA;QACtB,KAAK,EAAE,MAAM,CAAA;QACb,eAAe,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAA;KACnE;CAOF"}

package/dist/esm/errors.js

@@ -0,0 +1,119 @@
+/**
+ * Typed errors the SDK throws.
+ *
+ * Happy-path code reads the return value of `agent.run(...)` or
+ * `chat.send(...)`. Anything else — HITL pauses, agent-side errors,
+ * timeouts, HTTP failures — surfaces as one of these. Catch the
+ * specific class you care about; everything inherits from
+ * `CuratorError` so a single `catch (err: CuratorError)` works as a
+ * backstop.
+ */
+export class CuratorError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = "CuratorError";
+        // Preserve the underlying error if the runtime supports it.
+        if (options?.cause !== undefined) {
+            ;
+            this.cause = options.cause;
+        }
+    }
+}
+/** HTTP 401 from the API — your API key is missing, invalid, or revoked. */
+export class CuratorAuthError extends CuratorError {
+    constructor(message = "Invalid or revoked API key") {
+        super(message);
+        this.name = "CuratorAuthError";
+    }
+}
+/** HTTP 403 from the API — your API key doesn't have permission for this action. */
+export class CuratorForbiddenError extends CuratorError {
+    constructor(message = "Permission denied") {
+        super(message);
+        this.name = "CuratorForbiddenError";
+    }
+}
+/** HTTP 404 from the API — the deployment slug or conversation id wasn't found. */
+export class CuratorNotFoundError extends CuratorError {
+    constructor(message = "Resource not found") {
+        super(message);
+        this.name = "CuratorNotFoundError";
+    }
+}
+/** HTTP 410 from the API — the deployment was retired. */
+export class CuratorDeploymentRetiredError extends CuratorError {
+    retiredAt;
+    constructor(message, retiredAt) {
+        super(message);
+        this.name = "CuratorDeploymentRetiredError";
+        this.retiredAt = retiredAt;
+    }
+}
+/** HTTP 429 from the API — back off. */
+export class CuratorRateLimitError extends CuratorError {
+    retryAfterSeconds;
+    constructor(message = "Rate limit exceeded", retryAfterSeconds = null) {
+        super(message);
+        this.name = "CuratorRateLimitError";
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+/**
+ * Run paused waiting for human approval. Approval resolution is not
+ * exposed to API consumers — pauses are routed through the dashboard
+ * by an org administrator. The error carries the approval payload so
+ * the caller can surface a friendly "contact your administrator"
+ * message that mentions the specific tool.
+ */
+export class CuratorApprovalRequiredError extends CuratorError {
+    approval;
+    conversationId;
+    runId;
+    constructor(args) {
+        super(`Run paused for approval — the '${args.approval.tool_name}' tool needs an administrator to review it. ` +
+            "Contact your administrator to resolve this in the Curator dashboard.");
+        this.name = "CuratorApprovalRequiredError";
+        this.approval = args.approval;
+        this.conversationId = args.conversationId;
+        this.runId = args.runId;
+    }
+}
+/**
+ * The agent run reached a terminal error state (LLM quota, auth, 5xx
+ * exhausted retries, etc.). `failureClass` and `isPermanent` mirror the
+ * server's classification so callers can decide whether to retry.
+ */
+export class CuratorAgentError extends CuratorError {
+    failureClass;
+    isPermanent;
+    conversationId;
+    runId;
+    stepId;
+    constructor(args) {
+        super(args.message);
+        this.name = "CuratorAgentError";
+        this.failureClass = args.failureClass;
+        this.isPermanent = args.isPermanent;
+        this.conversationId = args.conversationId;
+        this.runId = args.runId;
+        this.stepId = args.stepId ?? null;
+    }
+}
+/**
+ * The synchronous wait expired. The agent run keeps running on the
+ * server; call `.continueWaiting()` to resume listening, or fetch
+ * history later via `chat.history()`.
+ */
+export class CuratorTimeoutError extends CuratorError {
+    conversationId;
+    runId;
+    continueWaiting;
+    constructor(args) {
+        super("Timed out waiting for the agent to reply — the run is still in progress.");
+        this.name = "CuratorTimeoutError";
+        this.conversationId = args.conversationId;
+        this.runId = args.runId;
+        this.continueWaiting = args.continueWaiting;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"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"}