@palai/sdk 0.1.0

package/dist/orchestrator.js

@@ -0,0 +1,159 @@
+// The orchestrator kit is server-only: it drives durable runs with the API-key client, so
+// importing it marks its importer server-only (never bundle it for the browser — see ./server-only.ts).
+import "./server-only.js";
+import { createHash } from "node:crypto";
+import { delay, ResponseStream } from "./stream.js";
+// ─────────────────────────────────────────────────────────────────────────────────────────
+// External-orchestrator kit — the §35.1 five-step contract as thin helpers over the client.
+//
+// This kit lets an EXTERNAL durable orchestrator (Temporal, Restate, a CI pipeline, or a plain
+// script) drive a Palai run through the canonical five steps without re-implementing any of the
+// client's HTTP, idempotent-retry, or reconnecting-SSE machinery — it composes `client.responses`
+// and `client.sessions.commands`. It writes NO vendor adapter: the contract it pins is the same
+// one ANY orchestrator follows (docs/orchestrator-kit.md, §35.2).
+//
+// The two identities the contract keeps SEPARATE — never conflated:
+//   • workflowId  — the EXTERNAL orchestrator's durable workflow identity. The orchestrator owns it
+//                   and may replay it from its own history any number of times (a retry storm).
+//   • runId / responseId / sessionId — Palai's CANONICAL run identity, minted by the server on the
+//                   FIRST admission. The workflow id never replaces it and is never inferred from it.
+//
+// The bridge between them is the idempotency key, derived deterministically from the workflow id
+// (workflowIdempotencyKey). It is the SINGLE retry owner (§35.2): every replay under the same
+// workflow id carries the same key, so the server settles exactly ONE run — a storm of retries does
+// not multiply runs (AUT-013). An orchestrator that lost its state re-derives the same key from its
+// own workflow id and reconciles to the same run without ever having persisted the run id.
+// ─────────────────────────────────────────────────────────────────────────────────────────
+// Terminal run statuses (spec §22.3): a run in one of these has settled. queued/running are the only
+// non-terminal states. A terminal-FAILED run is a real OUTCOME, so a wait RESOLVES with it (the caller
+// inspects `status` / `error`) rather than throwing.
+const TERMINAL_STATUSES = new Set(["completed", "failed", "canceled", "timed_out", "budget_exceeded", "expired"]);
+export function isTerminalStatus(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+// workflowIdempotencyKey derives the stable per-workflow key. Pure function of the workflow id: same id
+// ⇒ same key (replays reconcile), different id ⇒ different key. sha256-truncated so an arbitrary external
+// workflow id maps to a bounded, opaque key.
+// NOTE: the key carries no orchestrator-system namespace — two DISTINCT orchestrator systems under the
+// same principal that reuse the same workflow-id string collide on one key (identical body ⇒ silently
+// shared run; different body ⇒ a loud ErrIdempotencyMismatch). Pass StartOptions.idempotencyKey to
+// namespace them explicitly.
+export function workflowIdempotencyKey(workflowId) {
+    if (workflowId === "") {
+        throw new Error("@palai/sdk: an orchestrator workflow id must not be empty");
+    }
+    return "wf_" + createHash("sha256").update(workflowId).digest("hex").slice(0, 32);
+}
+// Orchestrator is the kit surface: one instance wraps a Palai client and exposes the five-step contract.
+export class Orchestrator {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    // start — STEP 1: create-with-workflow-ID-metadata + idempotency-key. The external workflow id rides
+    // `metadata.workflow_id` (untrusted external correlation, never an identity override — §38.6); the
+    // idempotency key is derived from it, so this exact call is safe to REPLAY. A callback in options wires
+    // the webhook wait mode. Returns the WorkflowRun carrying BOTH identities.
+    async start(workflowId, request, options = {}) {
+        const idempotencyKey = options.idempotencyKey ?? workflowIdempotencyKey(workflowId);
+        const body = {
+            ...request,
+            metadata: { ...request.metadata, workflow_id: workflowId },
+            ...(options.callback !== undefined ? { callback: options.callback } : {}),
+        };
+        const created = await this.#client.responses.create(body, {
+            idempotencyKey,
+            signal: options.signal,
+            ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        });
+        return toWorkflowRun(workflowId, idempotencyKey, created);
+    }
+    // reconcile — STEP 5: reconcile-by-key. Re-issues start under the SAME derived key. Because the key is
+    // the single retry owner, the server REPLAYS the original admission and returns the SAME run — so an
+    // orchestrator recovering from a crash (holding only its workflow id + the original request) resolves
+    // back to the one run it created, never a duplicate. This is start()'s idempotency made explicit as the
+    // recovery entrypoint; call it with the identical request the workflow first submitted.
+    reconcile(workflowId, request, options = {}) {
+        return this.start(workflowId, request, options);
+    }
+    // waitByPoll — STEP 2 (poll): polls the run to its terminal projection. The orchestrator owns this wait
+    // deadline; a timeout throws WITHOUT canceling the run (reconcile/result recover it later).
+    async waitByPoll(run, options = {}) {
+        const deadline = Date.now() + (options.timeoutMs ?? 60_000);
+        const interval = options.pollIntervalMs ?? 250;
+        for (;;) {
+            const resp = await this.#client.responses.retrieve(run.responseId, { signal: options.signal });
+            if (isTerminalStatus(resp.status)) {
+                return resp;
+            }
+            if (Date.now() + interval > deadline) {
+                throw new Error(`@palai/sdk: run ${run.runId} did not settle within the ${options.timeoutMs ?? 60_000}ms poll deadline`);
+            }
+            await delay(interval, options.signal);
+        }
+    }
+    // waitByStream — STEP 2 (SSE): drains the run's session event stream to its terminal event and returns
+    // the canonical terminal Response. It reuses ResponseStream, so a transport drop reconnects with
+    // Last-Event-ID (loss-less) — the kit adds no SSE code of its own. start() runs once here and returns
+    // the ALREADY-created identity, so the wait subscribes without minting a second run.
+    waitByStream(run, options = {}) {
+        const stream = new ResponseStream({
+            transport: this.#client,
+            start: async () => ({ responseID: run.responseId, sessionID: run.sessionId }),
+            signal: options.signal,
+            lastEventId: options.lastEventId ?? null,
+        });
+        return stream.finalResponse();
+    }
+    // result — reads the canonical terminal Response by run identity. The WEBHOOK wait mode resolves here:
+    // when Palai POSTs the callback, the orchestrator's handler calls result() to READ BACK the canonical
+    // outcome rather than trusting the (untrusted) webhook body. STEP 4's structured result + artifacts ride
+    // this Response (output + metadata; artifacts via client.artifacts.listForResponse).
+    result(run, options = {}) {
+        return this.#client.responses.retrieve(run.responseId, { signal: options.signal });
+    }
+    // sendMessage — STEP 3 (message command): delivers a steer message to the run's session. Durable +
+    // idempotent server-side (the command_id), so an orchestrator activity retry does not double-deliver.
+    sendMessage(run, message, options = {}) {
+        return this.#client.sessions.commands.steer(run.sessionId, { message, ...(options.commandId !== undefined ? { commandId: options.commandId } : {}) }, { ...(options.signal !== undefined ? { signal: options.signal } : {}) });
+    }
+    // cancel — STEP 3 (cancel command): propagates cancellation to the run. Naturally idempotent (a canceled
+    // terminal is monotonic), so a retried cancel settles once. This is cancel PROPAGATION: the orchestrator
+    // canceling its workflow tells Palai to cancel the run it owns.
+    cancel(run, options = {}) {
+        return this.#client.responses.cancel(run.responseId, { ...(options.signal !== undefined ? { signal: options.signal } : {}) });
+    }
+    // runActivity composes the happy path into ONE durable activity an orchestrator schedules: start
+    // (idempotent) → wait (chosen mode) → return the terminal Response (structured result + artifacts). On
+    // an orchestrator retry with the same workflowId it replays to the same run and resumes the wait — no
+    // duplicate run. The webhook mode returns the started (possibly still-running) Response immediately; the
+    // orchestrator's callback handler resolves it with result().
+    async runActivity(workflowId, request, options = {}) {
+        const run = await this.start(workflowId, request, options);
+        const waitOpts = {
+            signal: options.signal,
+            ...(options.waitTimeoutMs !== undefined ? { timeoutMs: options.waitTimeoutMs } : {}),
+            ...(options.pollIntervalMs !== undefined ? { pollIntervalMs: options.pollIntervalMs } : {}),
+        };
+        switch (options.wait ?? "poll") {
+            case "stream":
+                return this.waitByStream(run, waitOpts);
+            case "webhook":
+                return this.result(run, waitOpts);
+            default:
+                return this.waitByPoll(run, waitOpts);
+        }
+    }
+}
+// toWorkflowRun projects a created Response into the WorkflowRun handle, coercing the branded id types to
+// plain strings.
+function toWorkflowRun(workflowId, idempotencyKey, created) {
+    return {
+        workflowId,
+        idempotencyKey,
+        responseId: String(created.id),
+        runId: String(created.run_id ?? ""),
+        sessionId: String(created.session_id ?? ""),
+    };
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/orchestrator.js.map

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

package/dist/resources/agents.d.ts

@@ -0,0 +1,67 @@
+import type { Palai } from "../client.ts";
+import { type CallOptions, type ListParams, type Page } from "./shared.ts";
+export interface AgentProfile {
+    id: string;
+    object: string;
+    [key: string]: unknown;
+}
+export interface AgentRevision {
+    id: string;
+    object: string;
+    [key: string]: unknown;
+}
+export interface SubagentRef {
+    /** A published profile id. Mutually exclusive with `name`. */
+    ref?: string;
+    /** The model-visible name of an inline subagent. Mutually exclusive with `ref`. */
+    name?: string;
+    /** What this subagent is FOR — the routing signal a parent model reads. */
+    description?: string;
+    model?: string;
+    tools?: readonly string[];
+    instructions?: string;
+    skills?: readonly string[];
+    subagents?: SubagentRef[];
+}
+export interface DelegationLimits {
+    max_depth?: number;
+    max_children?: number;
+}
+export interface DefineAgentParams {
+    name: string;
+    description?: string;
+    instructions?: string;
+    model?: string;
+    tools?: readonly string[];
+    tool_sets?: readonly string[];
+    mcp_connections?: readonly string[];
+    skills?: readonly string[];
+    hooks?: readonly string[];
+    environment?: string;
+    subagents?: SubagentRef[];
+    delegation?: DelegationLimits;
+    [key: string]: unknown;
+}
+export interface PublishedAgent extends AgentProfile {
+    revisionId: string;
+}
+export interface AgentRevisionCreateParams {
+    instructions?: string;
+    model?: string;
+    [key: string]: unknown;
+}
+export declare class Agents {
+    #private;
+    constructor(client: Palai);
+    create(params: {
+        name: string;
+        description?: string;
+    }, options?: CallOptions): Promise<AgentProfile>;
+    createRevision(agentID: string, params: AgentRevisionCreateParams, options?: CallOptions): Promise<AgentRevision>;
+    list(params?: ListParams, options?: CallOptions): Promise<Page<AgentProfile>>;
+    retrieve(agentID: string, options?: CallOptions): Promise<AgentProfile>;
+    listRevisions(agentID: string, params?: ListParams, options?: CallOptions): Promise<Page<AgentRevision>>;
+    defineAgent(params: DefineAgentParams, options?: CallOptions): Promise<PublishedAgent>;
+    publishRevision(agentID: string, revisionID: string, options?: CallOptions): Promise<AgentRevision>;
+}
+//# sourceMappingURL=agents.d.ts.map

package/dist/resources/agents.d.ts.map

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

package/dist/resources/agents.js

@@ -0,0 +1,75 @@
+import { callArgs, enc, listPath } from "./shared.js";
+// Agents is the /v1/agents resource: author a profile and its revisions, read them back, and publish.
+//
+// ‼️ THE AUTHORING WRITES WERE ABSENT AND THE COMMENT HERE SAID SO — "out of this parity task's scope".
+// That was true of the task and false of the product: with only list/retrieve/publish, an SDK holder
+// could publish a revision they had no way to create, on a profile they had no way to open. The plane
+// has had POST /v1/agents and POST /v1/agents/{id}/revisions the whole time; what was missing was the
+// half of the SDK that reaches them, and "a customer creates an agent and opens a session with the key
+// we minted for them" is not a sentence the SDK could complete.
+export class Agents {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    // create opens a new agent-profile lineage. The profile is an IDENTITY and carries no behaviour: what
+    // an agent does lives on its revisions, which is why this takes a name and nothing else.
+    async create(params, options = {}) {
+        const r = await this.#client.request("POST", "/v1/agents", { body: params, ...callArgs(options) });
+        return r.body;
+    }
+    // createRevision adds a DRAFT revision to a profile (201). A draft steers no run — publishRevision is
+    // the transition that makes it the one a session resolves — so authoring and arming stay two calls a
+    // reader can tell apart.
+    //
+    // The 201 carries the id and NO Location header, and that is the plane's deliberate choice rather than
+    // an omission: `/v1/agent-revisions/{id}` is not a mounted address, and a correct-looking wrong URL is
+    // worse than none. Read it from the returned body.
+    async createRevision(agentID, params, options = {}) {
+        const r = await this.#client.request("POST", `/v1/agents/${enc(agentID)}/revisions`, { body: params, ...callArgs(options) });
+        return r.body;
+    }
+    // list returns a tenant-scoped page of agent-profile lineages.
+    async list(params = {}, options = {}) {
+        const result = await this.#client.request("GET", listPath("/v1/agents", params), callArgs(options));
+        return result.body;
+    }
+    // retrieve reads one agent-profile lineage; a foreign/unknown id is a 404.
+    async retrieve(agentID, options = {}) {
+        const result = await this.#client.request("GET", `/v1/agents/${enc(agentID)}`, callArgs(options));
+        return result.body;
+    }
+    // listRevisions pages one profile's revisions. The cursor is profile-scoped server-side, so a
+    // cursor from one profile does not validate on another.
+    async listRevisions(agentID, params = {}, options = {}) {
+        const result = await this.#client.request("GET", listPath(`/v1/agents/${enc(agentID)}/revisions`, params), callArgs(options));
+        return result.body;
+    }
+    // defineAgent folds create + revise + publish into one call, because they are one INTENT.
+    //
+    // ‼️ THE MIDDLE STATE IS ONE NOBODY ASKS FOR. A draft revision steers no run, so an agent created and
+    // revised but not published EXISTS and DOES NOTHING — it appears in every picker and runs the project
+    // default. That is the shape a client produces every time it forgets the third call, and it fails
+    // silently, which is why this exists as one call rather than as documentation saying "remember to
+    // publish".
+    //
+    // The identity/behaviour split is the SERVER's: the profile carries name and description, the revision
+    // carries everything a run executes. A caller who sent instructions to /v1/agents would have them
+    // accepted and ignored, so this routes each field to the half that reads it.
+    //
+    // agents.create / createRevision / publishRevision remain: a caller staging a draft for review needs
+    // the middle state this skips.
+    async defineAgent(params, options = {}) {
+        const { name, description, ...behaviour } = params;
+        const profile = await this.create(description === undefined ? { name } : { name, description }, options);
+        const revision = await this.createRevision(profile.id, behaviour, options);
+        await this.publishRevision(profile.id, revision.id, options);
+        return { ...profile, revisionId: revision.id };
+    }
+    // publishRevision publishes a draft revision, making it the profile's active config.
+    async publishRevision(agentID, revisionID, options = {}) {
+        const result = await this.#client.request("POST", `/v1/agents/${enc(agentID)}/revisions/${enc(revisionID)}/publish`, callArgs(options));
+        return result.body;
+    }
+}
+//# sourceMappingURL=agents.js.map

package/dist/resources/agents.js.map

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

package/dist/resources/approvals.d.ts

@@ -0,0 +1,33 @@
+import type { Palai } from "../client.ts";
+import { type CallOptions, type ListParams, type Page } from "./shared.ts";
+export interface PendingApproval {
+    id: string;
+    object: string;
+    tool_call_id: string;
+    run_id: string;
+    session_id: string;
+    response_id?: string;
+    request_hash: string;
+    expires_at?: string | null;
+    created_at: string;
+    [key: string]: unknown;
+}
+export interface ApprovalDecisionResult {
+    id: string;
+    object: string;
+    decision: string;
+}
+export interface ApproveParams {
+    requestHash: string;
+}
+export interface DenyParams extends ApproveParams {
+    reason?: string;
+}
+export declare class Approvals {
+    #private;
+    constructor(client: Palai);
+    list(params?: ListParams, options?: CallOptions): Promise<Page<PendingApproval>>;
+    approve(approvalID: string, params: ApproveParams, options?: CallOptions): Promise<ApprovalDecisionResult>;
+    deny(approvalID: string, params: DenyParams, options?: CallOptions): Promise<ApprovalDecisionResult>;
+}
+//# sourceMappingURL=approvals.d.ts.map

package/dist/resources/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../src/resources/approvals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAA2B,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,IAAI,EAAE,MAAM,aAAa,CAAC;AAkBpG,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IAIrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAGD,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAI5B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAW,SAAQ,aAAa;IAG/C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAGD,qBAAa,SAAS;;IAEpB,YAAY,MAAM,EAAE,KAAK,EAExB;IAGK,IAAI,CAAC,MAAM,GAAE,UAAe,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAO7F;IAID,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAE7G;IAGD,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAEvG;CAqBF"}

package/dist/resources/approvals.js

@@ -0,0 +1,33 @@
+import { callArgs, enc, listPath } from "./shared.js";
+// Approvals is the /v1/approvals resource: read what is waiting, and answer it.
+export class Approvals {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    // list returns the tenant's pending approvals, newest first, with the shared cursor.
+    async list(params = {}, options = {}) {
+        const result = await this.#client.request("GET", listPath("/v1/approvals", params), callArgs(options));
+        return result.body;
+    }
+    // approve lets the parked call run. Idempotent by the approval's own state machine: a second approve of
+    // an already-approved row is the same answer, and one whose arguments changed is refused by the hash.
+    approve(approvalID, params, options = {}) {
+        return this.#decide(approvalID, "approve", { request_hash: params.requestHash, reason: "" }, options);
+    }
+    // deny refuses it, with a reason the agent reads.
+    deny(approvalID, params, options = {}) {
+        return this.#decide(approvalID, "deny", { request_hash: params.requestHash, reason: params.reason ?? "" }, options);
+    }
+    async #decide(approvalID, verb, body, options) {
+        const result = await this.#client.request("POST", `/v1/approvals/${enc(approvalID)}/${verb}`, {
+            body,
+            // The decision is keyed by the approval id and its request hash, and the row's state machine
+            // settles once — so a connection torn after the server committed is safe to re-send.
+            idempotent: true,
+            ...callArgs(options),
+        });
+        return result.body;
+    }
+}
+//# sourceMappingURL=approvals.js.map

package/dist/resources/approvals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../../src/resources/approvals.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAgD,MAAM,aAAa,CAAC;AAsDpG,gFAAgF;AAChF,MAAM,OAAO,SAAS;IACpB,OAAO,CAAQ;IACf,YAAY,MAAa;QACvB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,qFAAqF;IACrF,KAAK,CAAC,IAAI,CAAC,MAAM,GAAe,EAAE,EAAE,OAAO,GAAgB,EAAE;QAC3D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CACvC,KAAK,EACL,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,EACjC,QAAQ,CAAC,OAAO,CAAC,CAClB,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAED,wGAAwG;IACxG,sGAAsG;IACtG,OAAO,CAAC,UAAkB,EAAE,MAAqB,EAAE,OAAO,GAAgB,EAAE;QAC1E,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,YAAY,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IACxG,CAAC;IAED,kDAAkD;IAClD,IAAI,CAAC,UAAkB,EAAE,MAAkB,EAAE,OAAO,GAAgB,EAAE;QACpE,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,YAAY,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IACtH,CAAC;IAED,KAAK,CAAC,OAAO,CACX,UAAkB,EAClB,IAAwB,EACxB,IAA8C,EAC9C,OAAoB;QAEpB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CACvC,MAAM,EACN,iBAAiB,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,EAAE,EAC1C;YACE,IAAI;YACJ,6FAA6F;YAC7F,qFAAqF;YACrF,UAAU,EAAE,IAAI;YAChB,GAAG,QAAQ,CAAC,OAAO,CAAC;SACrB,CACF,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;CACF"}

package/dist/resources/artifacts.d.ts

@@ -0,0 +1,36 @@
+import type { Palai } from "../client.ts";
+import { type CallOptions, type DownloadOptions, type ListView } from "./shared.ts";
+export interface Artifact {
+    id: string;
+    object: string;
+    [key: string]: unknown;
+}
+export interface ArtifactDownload {
+    stream: ReadableStream<Uint8Array>;
+    contentDigest: string | null;
+    contentType: string;
+    contentLength: number | null;
+    bytes(): Promise<Uint8Array>;
+}
+export declare class Artifacts {
+    #private;
+    constructor(client: Palai);
+    /**
+     * create uploads bytes and returns the artifact whose id a run's `image_ref` content item names.
+     *
+     * ‼️ THIS IS HOW A SCREENSHOT REACHES A MODEL, and its absence was the gap: the Go SDK has had this
+     * since E09 and the TypeScript one did not, so a browser app — the only kind that has a file picker —
+     * could download artifacts and never send one. The demo's chat could show what the agent produced and
+     * not what the operator was looking at.
+     *
+     * NO MEDIA TYPE IS SENT, deliberately. The server sniffs the bytes (http.DetectContentType) and
+     * refuses anything outside its allow-list, so a caller-declared type would be a claim the server
+     * ignores — a lie in a function signature. A caller who knows what it is holding still learns what the
+     * server decided, from the `media_type` on the artifact that comes back.
+     */
+    create(content: Uint8Array, options?: CallOptions): Promise<Artifact>;
+    retrieve(artifactID: string, options?: CallOptions): Promise<Artifact>;
+    download(artifactID: string, options?: DownloadOptions): Promise<ArtifactDownload>;
+    listForResponse(responseID: string, options?: CallOptions): Promise<ListView<Artifact>>;
+}
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/resources/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/resources/artifacts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAiB,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAKnG,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACnC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAC9B;AAMD,qBAAa,SAAS;;IAEpB,YAAY,MAAM,EAAE,KAAK,EAExB;IAED;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAW9E;IAGK,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAG/E;IAMK,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAU3F;IAIK,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAOhG;CACF"}

package/dist/resources/artifacts.js

@@ -0,0 +1,70 @@
+import { callArgs, enc } from "./shared.js";
+// Artifacts is the artifact retrieval resource (spec §22.6, E13 T5): the never-opened READ half of the
+// E09 write-path — metadata, an authenticated streaming download, and a run-scoped list. A wrong-tenant
+// or unknown id is an indistinguishable 404 (NotFoundError), so the surface leaks no cross-tenant
+// existence.
+export class Artifacts {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /**
+     * create uploads bytes and returns the artifact whose id a run's `image_ref` content item names.
+     *
+     * ‼️ THIS IS HOW A SCREENSHOT REACHES A MODEL, and its absence was the gap: the Go SDK has had this
+     * since E09 and the TypeScript one did not, so a browser app — the only kind that has a file picker —
+     * could download artifacts and never send one. The demo's chat could show what the agent produced and
+     * not what the operator was looking at.
+     *
+     * NO MEDIA TYPE IS SENT, deliberately. The server sniffs the bytes (http.DetectContentType) and
+     * refuses anything outside its allow-list, so a caller-declared type would be a claim the server
+     * ignores — a lie in a function signature. A caller who knows what it is holding still learns what the
+     * server decided, from the `media_type` on the artifact that comes back.
+     */
+    async create(content, options = {}) {
+        if (content.byteLength === 0) {
+            // Refused before the round trip: the server answers 400 for an empty body, and paying a request to
+            // be told what the caller already knows is a request nobody needed.
+            throw new TypeError("artifacts.create: the content carried no bytes");
+        }
+        const result = await this.#client.request("POST", "/v1/artifacts", {
+            ...callArgs(options),
+            bytes: content,
+        });
+        return result.body;
+    }
+    // retrieve returns an artifact's metadata; a foreign/unknown id is a 404.
+    async retrieve(artifactID, options = {}) {
+        const result = await this.#client.request("GET", `/v1/artifacts/${enc(artifactID)}`, callArgs(options));
+        return result.body;
+    }
+    // download opens the authenticated byte stream for an artifact. HONEST CEILING: this is a direct
+    // authenticated download — the object's bytes stream straight from the object store through the
+    // control-plane; a pre-signed URL + expiry policy is E13-H. The SSE primitive in stream.ts does NOT
+    // fit here (it frames an event stream, not raw bytes), so this reads the raw response body instead.
+    async download(artifactID, options = {}) {
+        const response = await this.#client.openDownload(`/v1/artifacts/${enc(artifactID)}/content`, options);
+        const contentLength = response.headers.get("Content-Length");
+        return {
+            stream: response.body ?? emptyStream(),
+            contentDigest: response.headers.get("Content-Digest"),
+            contentType: response.headers.get("Content-Type") ?? "application/octet-stream",
+            contentLength: contentLength === null ? null : Number(contentLength),
+            bytes: async () => new Uint8Array(await response.arrayBuffer()),
+        };
+    }
+    // listForResponse lists the artifacts a response's run produced. A known run with no artifacts is an
+    // empty list, not a miss; an unknown/foreign response id is a 404.
+    async listForResponse(responseID, options = {}) {
+        const result = await this.#client.request("GET", `/v1/responses/${enc(responseID)}/artifacts`, callArgs(options));
+        return result.body;
+    }
+}
+function emptyStream() {
+    return new ReadableStream({
+        start(controller) {
+            controller.close();
+        },
+    });
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/resources/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../src/resources/artifacts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAyD,MAAM,aAAa,CAAC;AAuBnG,uGAAuG;AACvG,wGAAwG;AACxG,kGAAkG;AAClG,aAAa;AACb,MAAM,OAAO,SAAS;IACpB,OAAO,CAAQ;IACf,YAAY,MAAa;QACvB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,MAAM,CAAC,OAAmB,EAAE,OAAO,GAAgB,EAAE;QACzD,IAAI,OAAO,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;YAC7B,mGAAmG;YACnG,oEAAoE;YACpE,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;QACxE,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAW,MAAM,EAAE,eAAe,EAAE;YAC3E,GAAG,QAAQ,CAAC,OAAO,CAAC;YACpB,KAAK,EAAE,OAAO;SACf,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAED,0EAA0E;IAC1E,KAAK,CAAC,QAAQ,CAAC,UAAkB,EAAE,OAAO,GAAgB,EAAE;QAC1D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAW,KAAK,EAAE,iBAAiB,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QAClH,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAED,iGAAiG;IACjG,gGAAgG;IAChG,oGAAoG;IACpG,oGAAoG;IACpG,KAAK,CAAC,QAAQ,CAAC,UAAkB,EAAE,OAAO,GAAoB,EAAE;QAC9D,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,iBAAiB,GAAG,CAAC,UAAU,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACtG,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAC7D,OAAO;YACL,MAAM,EAAE,QAAQ,CAAC,IAAI,IAAI,WAAW,EAAE;YACtC,aAAa,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;YACrD,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,0BAA0B;YAC/E,aAAa,EAAE,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;YACpE,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC;SAChE,CAAC;IACJ,CAAC;IAED,qGAAqG;IACrG,mEAAmE;IACnE,KAAK,CAAC,eAAe,CAAC,UAAkB,EAAE,OAAO,GAAgB,EAAE;QACjE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CACvC,KAAK,EACL,iBAAiB,GAAG,CAAC,UAAU,CAAC,YAAY,EAC5C,QAAQ,CAAC,OAAO,CAAC,CAClB,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;CACF;AAED,SAAS,WAAW;IAClB,OAAO,IAAI,cAAc,CAAa;QACpC,KAAK,CAAC,UAAU;YACd,UAAU,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/resources/model-routes.d.ts

@@ -0,0 +1,70 @@
+import type { ModelConnection, ModelRoute, ModelRouteRevision } from "../generated/types.ts";
+import type { Palai } from "../client.ts";
+import { type CallOptions, type ListView } from "./shared.ts";
+export interface ModelConnectionCreateParams {
+    provider: string;
+    secret_ref: string;
+    /**
+     * This connection's OWN endpoint. OPTIONAL on every protocol: empty means the vendor's own endpoint, and
+     * a value reaches an OpenAI-compatible target such as Grok, z.ai or Azure OpenAI.
+     *
+     * It used to be REQUIRED by an `openai-compatible` family and REFUSED on the others. That family was
+     * dissolved on 2026-08-11 — it was the same wire protocol wearing a second name, so reaching a new
+     * compatible target needed an adapter and a release rather than a row. The protocols a deployment speaks
+     * are served by `GET /v1/model-protocols`; this SDK carries no copy of the list.
+     */
+    base_url?: string;
+}
+/**
+ * One credential probe's finding (E29). `outcome` is the verdict; `not_probed` means NOTHING was checked
+ * and must never be rendered as a pass. `checked` is the server's own sentence about what a probe does not
+ * establish — the model id's validity above all — carried in the payload so a UI cannot overstate it.
+ */
+export interface ModelConnectionVerification {
+    object: string;
+    connection_id: string;
+    provider: string;
+    outcome: "credential_accepted" | "credential_rejected" | "unreachable" | "transient" | "not_probed";
+    status?: number;
+    endpoint?: string;
+    detail?: string;
+    checked?: string;
+}
+export interface ModelRouteCreateParams {
+    name: string;
+}
+export interface ModelRouteRevisionCreateParams {
+    model: string;
+    connection_id: string;
+    /**
+     * How hard runs on this route think, and whether a person sees the reasoning.
+     *
+     * ‼️ THEY ARE TYPED HERE BECAUSE THE PLANE'S DECODER IS STRICT AND SILENT ABOUT IT. A field this SDK
+     * does not name cannot be smuggled through — strictDecodeBody is DisallowUnknownFields and these params
+     * carry no escape hatch — so an untyped knob is a knob no SDK caller can turn at all. `thinking` shipped
+     * exactly that way and stayed write-only-by-curl; `effort` is not repeating it.
+     *
+     * `effort` is the canonical ladder: none | minimal | low | medium | high | xhigh | max. Which rungs a
+     * given model accepts is the PROVIDER's answer — Anthropic has no none/minimal — and the plane refuses
+     * an unmappable rung rather than quietly substituting a more expensive one.
+     */
+    effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    /** Ask the provider to return the model's reasoning where a person can read it. */
+    thinking?: "visible";
+}
+export declare class ModelRoutes {
+    #private;
+    constructor(client: Palai);
+    createConnection(params: ModelConnectionCreateParams, options?: CallOptions): Promise<ModelConnection>;
+    verifyConnection(connectionID: string, options?: CallOptions): Promise<ModelConnectionVerification>;
+    createRoute(params: ModelRouteCreateParams, options?: CallOptions): Promise<ModelRoute>;
+    createRevision(routeID: string, params: ModelRouteRevisionCreateParams, options?: CallOptions): Promise<ModelRouteRevision>;
+    publishRevision(routeID: string, revisionID: string, options?: CallOptions): Promise<ModelRouteRevision>;
+    listConnections(options?: CallOptions): Promise<ListView<ModelConnection>>;
+    getConnection(connectionID: string, options?: CallOptions): Promise<ModelConnection>;
+    listRoutes(options?: CallOptions): Promise<ListView<ModelRoute>>;
+    getRoute(routeID: string, options?: CallOptions): Promise<ModelRoute>;
+    listRevisions(routeID: string, options?: CallOptions): Promise<ListView<ModelRouteRevision>>;
+    getRevision(routeID: string, revisionID: string, options?: CallOptions): Promise<ModelRouteRevision>;
+}
+//# sourceMappingURL=model-routes.d.ts.map

package/dist/resources/model-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-routes.d.ts","sourceRoot":"","sources":["../../src/resources/model-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC7F,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAiB,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQ7E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,qBAAqB,GAAG,qBAAqB,GAAG,aAAa,GAAG,WAAW,GAAG,YAAY,CAAC;IACpG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AACD,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;IAC1E,mFAAmF;IACnF,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAQD,qBAAa,WAAW;;IAEtB,YAAY,MAAM,EAAE,KAAK,EAExB;IAGK,gBAAgB,CAAC,MAAM,EAAE,2BAA2B,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAG/G;IAOK,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAG5G;IAGK,WAAW,CAAC,MAAM,EAAE,sBAAsB,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAGhG;IAGK,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,8BAA8B,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAGpI;IAGK,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAGjH;IAKK,eAAe,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAGnF;IAGK,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAG7F;IAGK,UAAU,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAGzE;IAGK,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAG9E;IAGK,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC,CAGrG;IAGK,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAG7G;CACF"}