@tidblink/server 0.0.0-stage → 0.4.0-rc.0

package/dist/turn.js

@@ -0,0 +1,210 @@
+import { OutcomeUnknownError, TiDBLinkApiError, TiDBLinkError, TurnFailedError, TurnInterruptedError, TurnWaitTimeoutError, InputNotAppliedError, } from "./errors.js";
+import { HttpClient, sleep, requireCreationKey, requireKnownKeys, } from "./http.js";
+import { getInteraction, getTurn, requireInteraction, } from "./history.js";
+export const validClarification = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const item = value;
+    const strings = (items, min, max) => Array.isArray(items) &&
+        items.length >= min &&
+        items.length <= max &&
+        items.every((text) => typeof text === "string" && text.length > 0);
+    if (typeof item.prompt !== "string" ||
+        !item.prompt ||
+        (item.selectionMode !== "single" && item.selectionMode !== "multiple") ||
+        !strings(item.answerChoices, 2, item.selectionMode === "single" ? 3 : 8))
+        return false;
+    if (item.response === undefined)
+        return true;
+    if (typeof item.response !== "object" ||
+        item.response === null ||
+        Array.isArray(item.response))
+        return false;
+    const response = item.response;
+    return (Object.keys(response).sort().join(",") === "answers,responseTurnId" &&
+        typeof response.responseTurnId === "string" &&
+        response.responseTurnId.length > 0 &&
+        strings(response.answers, 1, item.selectionMode === "single" ? 1 : 9));
+};
+/** Check message data before dispatch. */
+export function validateMessageData(data) {
+    const texts = typeof data.text === "string" ? [data.text] : data.text;
+    if (!Array.isArray(texts) ||
+        texts.length < 1 ||
+        texts.length > 9 ||
+        texts.some((t) => typeof t !== "string" || !t))
+        throw new TypeError("text must contain 1-9 non-empty values");
+    if (data.userFileIds !== undefined &&
+        (!Array.isArray(data.userFileIds) ||
+            data.userFileIds.length > 20 ||
+            data.userFileIds.some((id) => typeof id !== "string" || !id || id.length > 64)))
+        throw new TypeError("userFileIds must contain at most 20 non-empty IDs");
+    if (data.clarificationSourceTurnId !== undefined &&
+        (typeof data.clarificationSourceTurnId !== "string" ||
+            !data.clarificationSourceTurnId ||
+            data.clarificationSourceTurnId.length > 64))
+        throw new TypeError("clarificationSourceTurnId must contain 1-64 characters");
+}
+export const submitMessage = async (http, sessionId, input) => {
+    requireKnownKeys(input, [
+        "clientEventId",
+        "text",
+        "userFileIds",
+        "clarificationSourceTurnId",
+        "billingTag",
+        "requestId",
+        "signal",
+    ], "Message input");
+    requireCreationKey(input.clientEventId);
+    const { clientEventId, requestId, signal, ...data } = input;
+    validateMessageData(data);
+    signal?.throwIfAborted();
+    try {
+        const result = await http.postResponse(`/sessions/${encodeURIComponent(sessionId)}/events`, { type: "agent.session.input.message", clientEventId, data }, {
+            ...(requestId ? { requestId } : {}),
+            ...(signal ? { signal } : {}),
+            outcomeUnknown: true,
+        });
+        try {
+            const receipt = requireInteraction(result.data?.interaction, clientEventId, result.requestId);
+            if (receipt.kind !== "message" ||
+                !receipt.message ||
+                receipt.message.role !== "user")
+                throw new TiDBLinkError("Message submission returned a different command receipt");
+            return receipt;
+        }
+        catch (cause) {
+            throw new OutcomeUnknownError("Message submission returned no usable receipt; query the original input", { requestId: result.requestId, cause });
+        }
+    }
+    catch (cause) {
+        if (!(cause instanceof OutcomeUnknownError))
+            throw cause;
+        throw new OutcomeUnknownError(cause.message, {
+            sessionId,
+            inputId: clientEventId,
+            ...(cause.requestId ? { requestId: cause.requestId } : {}),
+            cause,
+        });
+    }
+};
+export const validateWaitOptions = (options = {}) => {
+    requireKnownKeys(options, ["timeoutMs", "pollIntervalMs", "requestId", "signal"], "Wait options");
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    const pollIntervalMs = options.pollIntervalMs ?? 250;
+    if (!Number.isSafeInteger(timeoutMs) ||
+        timeoutMs < 0 ||
+        timeoutMs > 2_147_483_647)
+        throw new TypeError("timeoutMs must be an integer between 0 and 2147483647");
+    if (!Number.isSafeInteger(pollIntervalMs) ||
+        pollIntervalMs < 1 ||
+        pollIntervalMs > 2_147_483_647)
+        throw new TypeError("pollIntervalMs must be an integer between 1 and 2147483647");
+    return { timeoutMs, pollIntervalMs };
+};
+export const waitForResult = async (http, sessionId, inputId, options = {}) => {
+    const { timeoutMs, pollIntervalMs } = validateWaitOptions(options);
+    requireCreationKey(inputId);
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
+    const signal = options.signal
+        ? AbortSignal.any([options.signal, deadline.signal])
+        : deadline.signal;
+    let turnId;
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const interaction = await getInteraction(http, sessionId, inputId, {
+                signal,
+                ...(options.requestId ? { requestId: options.requestId } : {}),
+            });
+            turnId = interaction.turnId;
+            if ((interaction.kind !== "message" && interaction.kind !== "retry") ||
+                (interaction.kind === "message" &&
+                    (!interaction.message || interaction.message.role !== "user")) ||
+                (interaction.kind === "retry" && interaction.message !== null))
+                throw new TiDBLinkError("Waiting for a result requires a message or checkpoint retry receipt");
+            if (interaction.rejection || interaction.mode === "rejected")
+                throw new InputNotAppliedError(sessionId, inputId, turnId);
+            if (interaction.result.status !== "running" &&
+                !interaction.result.completedAt)
+                throw new TiDBLinkError("Original terminal receipt omitted its completion time");
+            if (interaction.result.status === "failed")
+                throw new TurnFailedError({
+                    code: "turn_failed",
+                    message: "The original Turn execution failed",
+                    turnId,
+                    sessionId,
+                    inputId,
+                });
+            if (interaction.result.status === "interrupted")
+                throw new TurnInterruptedError(turnId, undefined, sessionId, inputId);
+            if (interaction.result.status === "succeeded") {
+                if (interaction.kind === "message" && !interaction.appliedAt)
+                    throw new InputNotAppliedError(sessionId, inputId, turnId);
+                const turn = await getTurn(http, sessionId, turnId, {
+                    signal,
+                    ...(options.requestId ? { requestId: options.requestId } : {}),
+                });
+                const message = turn.assistantMessage;
+                if (turn.executor === "realtime_model" ||
+                    turn.status !== "succeeded" ||
+                    !interaction.result.completedAt ||
+                    turn.completedAt !== interaction.result.completedAt ||
+                    !message ||
+                    message.role !== "assistant" ||
+                    typeof message.id !== "string" ||
+                    !message.id ||
+                    typeof message.content !== "string" ||
+                    message.turnId !== turnId ||
+                    message.sessionId !== sessionId ||
+                    (turn.clarificationItem !== undefined &&
+                        !validClarification(turn.clarificationItem)))
+                    throw new TiDBLinkError("Saved Turn does not match the original successful execution");
+                const identity = {
+                    sessionId,
+                    inputId,
+                    turnId,
+                    messageId: message.id,
+                    text: message.content,
+                    interaction,
+                };
+                return turn.clarificationItem
+                    ? {
+                        ...identity,
+                        type: "clarification",
+                        clarification: turn.clarificationItem,
+                    }
+                    : { ...identity, type: "answer" };
+            }
+            await sleep(pollIntervalMs, signal);
+        }
+    }
+    catch (cause) {
+        if (cause instanceof TurnFailedError ||
+            cause instanceof TurnInterruptedError ||
+            cause instanceof InputNotAppliedError ||
+            cause instanceof TiDBLinkApiError)
+            throw cause;
+        const ErrorClass = deadline.signal.aborted && !options.signal?.aborted
+            ? TurnWaitTimeoutError
+            : OutcomeUnknownError;
+        throw new ErrorClass(ErrorClass === TurnWaitTimeoutError
+            ? "Local wait timed out; query or wait for the original input"
+            : "Local wait stopped before the original result was established", {
+            sessionId,
+            inputId,
+            ...(turnId ? { turnId } : {}),
+            ...(cause instanceof TiDBLinkError && cause.requestId
+                ? { requestId: cause.requestId }
+                : options.requestId
+                    ? { requestId: options.requestId }
+                    : {}),
+            cause,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+//# sourceMappingURL=turn.js.map

package/dist/turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.js","sourceRoot":"","sources":["../src/turn.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,UAAU,EACV,KAAK,EACL,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,cAAc,EACd,OAAO,EACP,kBAAkB,GAEnB,MAAM,cAAc,CAAC;AAoCtB,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAc,EAA8B,EAAE;IAC/E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACrE,OAAO,KAAK,CAAC;IACf,MAAM,IAAI,GAAG,KAAgC,CAAC;IAC9C,MAAM,OAAO,GAAG,CACd,KAAc,EACd,GAAW,EACX,GAAW,EACQ,EAAE,CACrB,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACpB,KAAK,CAAC,MAAM,IAAI,GAAG;QACnB,KAAK,CAAC,MAAM,IAAI,GAAG;QACnB,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrE,IACE,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ;QAC/B,CAAC,IAAI,CAAC,MAAM;QACZ,CAAC,IAAI,CAAC,aAAa,KAAK,QAAQ,IAAI,IAAI,CAAC,aAAa,KAAK,UAAU,CAAC;QACtE,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,EAAE,IAAI,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAExE,OAAO,KAAK,CAAC;IACf,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC7C,IACE,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ;QACjC,IAAI,CAAC,QAAQ,KAAK,IAAI;QACtB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;QAE5B,OAAO,KAAK,CAAC;IACf,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAmC,CAAC;IAC1D,OAAO,CACL,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,wBAAwB;QACnE,OAAO,QAAQ,CAAC,cAAc,KAAK,QAAQ;QAC3C,QAAQ,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACtE,CAAC;AACJ,CAAC,CAAC;AAKF,0CAA0C;AAC1C,MAAM,UAAU,mBAAmB,CAAC,IAAiB;IACnD,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IACtE,IACE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACrB,KAAK,CAAC,MAAM,GAAG,CAAC;QAChB,KAAK,CAAC,MAAM,GAAG,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC;QAE9C,MAAM,IAAI,SAAS,CAAC,wCAAwC,CAAC,CAAC;IAChE,IACE,IAAI,CAAC,WAAW,KAAK,SAAS;QAC9B,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC;YAC/B,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,EAAE;YAC5B,IAAI,CAAC,WAAW,CAAC,IAAI,CACnB,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,GAAG,EAAE,CACxD,CAAC;QAEJ,MAAM,IAAI,SAAS,CAAC,mDAAmD,CAAC,CAAC;IAC3E,IACE,IAAI,CAAC,yBAAyB,KAAK,SAAS;QAC5C,CAAC,OAAO,IAAI,CAAC,yBAAyB,KAAK,QAAQ;YACjD,CAAC,IAAI,CAAC,yBAAyB;YAC/B,IAAI,CAAC,yBAAyB,CAAC,MAAM,GAAG,EAAE,CAAC;QAE7C,MAAM,IAAI,SAAS,CACjB,wDAAwD,CACzD,CAAC;AACN,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAChC,IAAgB,EAChB,SAAiB,EACjB,KAAsB,EACO,EAAE;IAC/B,gBAAgB,CACd,KAAK,EACL;QACE,eAAe;QACf,MAAM;QACN,aAAa;QACb,2BAA2B;QAC3B,YAAY;QACZ,WAAW;QACX,QAAQ;KACT,EACD,eAAe,CAChB,CAAC;IACF,kBAAkB,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IACxC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;IAC5D,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CACpC,aAAa,kBAAkB,CAAC,SAAS,CAAC,SAAS,EACnD,EAAE,IAAI,EAAE,6BAA6B,EAAE,aAAa,EAAE,IAAI,EAAE,EAC5D;YACE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7B,cAAc,EAAE,IAAI;SACrB,CACF,CAAC;QACF,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,kBAAkB,CAChC,MAAM,CAAC,IAAI,EAAE,WAAW,EACxB,aAAa,EACb,MAAM,CAAC,SAAS,CACjB,CAAC;YACF,IACE,OAAO,CAAC,IAAI,KAAK,SAAS;gBAC1B,CAAC,OAAO,CAAC,OAAO;gBAChB,OAAO,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM;gBAE/B,MAAM,IAAI,aAAa,CACrB,yDAAyD,CAC1D,CAAC;YACJ,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,mBAAmB,CAC3B,yEAAyE,EACzE,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,KAAK,EAAE,CACvC,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,mBAAmB,CAAC;YAAE,MAAM,KAAK,CAAC;QACzD,MAAM,IAAI,mBAAmB,CAAC,KAAK,CAAC,OAAO,EAAE;YAC3C,SAAS;YACT,OAAO,EAAE,aAAa;YACtB,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1D,KAAK;SACN,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,UAAgC,EAAE,EACa,EAAE;IACjD,gBAAgB,CACd,OAAO,EACP,CAAC,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,QAAQ,CAAC,EACtD,cAAc,CACf,CAAC;IACF,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;IAC9C,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,GAAG,CAAC;IACrD,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC;QAChC,SAAS,GAAG,CAAC;QACb,SAAS,GAAG,aAAa;QAEzB,MAAM,IAAI,SAAS,CACjB,uDAAuD,CACxD,CAAC;IACJ,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC;QACrC,cAAc,GAAG,CAAC;QAClB,cAAc,GAAG,aAAa;QAE9B,MAAM,IAAI,SAAS,CACjB,4DAA4D,CAC7D,CAAC;IACJ,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC;AACvC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAChC,IAAgB,EAChB,SAAiB,EACjB,OAAe,EACf,UAAgC,EAAE,EACb,EAAE;IACvB,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACnE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5B,MAAM,QAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;IACvC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM;QAC3B,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;QACpD,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;IACpB,IAAI,MAA0B,CAAC;IAC/B,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,WAAW,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE;gBACjE,MAAM;gBACN,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC/D,CAAC,CAAC;YACH,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC;YAC5B,IACE,CAAC,WAAW,CAAC,IAAI,KAAK,SAAS,IAAI,WAAW,CAAC,IAAI,KAAK,OAAO,CAAC;gBAChE,CAAC,WAAW,CAAC,IAAI,KAAK,SAAS;oBAC7B,CAAC,CAAC,WAAW,CAAC,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;gBAChE,CAAC,WAAW,CAAC,IAAI,KAAK,OAAO,IAAI,WAAW,CAAC,OAAO,KAAK,IAAI,CAAC;gBAE9D,MAAM,IAAI,aAAa,CACrB,qEAAqE,CACtE,CAAC;YACJ,IAAI,WAAW,CAAC,SAAS,IAAI,WAAW,CAAC,IAAI,KAAK,UAAU;gBAC1D,MAAM,IAAI,oBAAoB,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YAC7D,IACE,WAAW,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS;gBACvC,CAAC,WAAW,CAAC,MAAM,CAAC,WAAW;gBAE/B,MAAM,IAAI,aAAa,CACrB,uDAAuD,CACxD,CAAC;YACJ,IAAI,WAAW,CAAC,MAAM,CAAC,MAAM,KAAK,QAAQ;gBACxC,MAAM,IAAI,eAAe,CAAC;oBACxB,IAAI,EAAE,aAAa;oBACnB,OAAO,EAAE,oCAAoC;oBAC7C,MAAM;oBACN,SAAS;oBACT,OAAO;iBACR,CAAC,CAAC;YACL,IAAI,WAAW,CAAC,MAAM,CAAC,MAAM,KAAK,aAAa;gBAC7C,MAAM,IAAI,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;YACxE,IAAI,WAAW,CAAC,MAAM,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;gBAC9C,IAAI,WAAW,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,WAAW,CAAC,SAAS;oBAC1D,MAAM,IAAI,oBAAoB,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;gBAC7D,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE;oBAClD,MAAM;oBACN,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC/D,CAAC,CAAC;gBACH,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB,CAAC;gBACtC,IACE,IAAI,CAAC,QAAQ,KAAK,gBAAgB;oBAClC,IAAI,CAAC,MAAM,KAAK,WAAW;oBAC3B,CAAC,WAAW,CAAC,MAAM,CAAC,WAAW;oBAC/B,IAAI,CAAC,WAAW,KAAK,WAAW,CAAC,MAAM,CAAC,WAAW;oBACnD,CAAC,OAAO;oBACR,OAAO,CAAC,IAAI,KAAK,WAAW;oBAC5B,OAAO,OAAO,CAAC,EAAE,KAAK,QAAQ;oBAC9B,CAAC,OAAO,CAAC,EAAE;oBACX,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;oBACnC,OAAO,CAAC,MAAM,KAAK,MAAM;oBACzB,OAAO,CAAC,SAAS,KAAK,SAAS;oBAC/B,CAAC,IAAI,CAAC,iBAAiB,KAAK,SAAS;wBACnC,CAAC,kBAAkB,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;oBAE9C,MAAM,IAAI,aAAa,CACrB,6DAA6D,CAC9D,CAAC;gBACJ,MAAM,QAAQ,GAAG;oBACf,SAAS;oBACT,OAAO;oBACP,MAAM;oBACN,SAAS,EAAE,OAAO,CAAC,EAAE;oBACrB,IAAI,EAAE,OAAO,CAAC,OAAO;oBACrB,WAAW;iBACZ,CAAC;gBACF,OAAO,IAAI,CAAC,iBAAiB;oBAC3B,CAAC,CAAC;wBACE,GAAG,QAAQ;wBACX,IAAI,EAAE,eAAe;wBACrB,aAAa,EAAE,IAAI,CAAC,iBAAiB;qBACtC;oBACH,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YACtC,CAAC;YACD,MAAM,KAAK,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IACE,KAAK,YAAY,eAAe;YAChC,KAAK,YAAY,oBAAoB;YACrC,KAAK,YAAY,oBAAoB;YACrC,KAAK,YAAY,gBAAgB;YAEjC,MAAM,KAAK,CAAC;QACd,MAAM,UAAU,GACd,QAAQ,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO;YACjD,CAAC,CAAC,oBAAoB;YACtB,CAAC,CAAC,mBAAmB,CAAC;QAC1B,MAAM,IAAI,UAAU,CAClB,UAAU,KAAK,oBAAoB;YACjC,CAAC,CAAC,4DAA4D;YAC9D,CAAC,CAAC,+DAA+D,EACnE;YACE,SAAS;YACT,OAAO;YACP,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7B,GAAG,CAAC,KAAK,YAAY,aAAa,IAAI,KAAK,CAAC,SAAS;gBACnD,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE;gBAChC,CAAC,CAAC,OAAO,CAAC,SAAS;oBACjB,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE;oBAClC,CAAC,CAAC,EAAE,CAAC;YACT,KAAK;SACN,CACF,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC,CAAC"}

package/dist/usage.d.ts

@@ -0,0 +1,278 @@
+import type { RequestOptions } from "./organization.js";
+import type { BillingTag } from "./session.js";
+export type BillingUsageFactKind = "llm" | "sandbox" | "web_search";
+export type BillingCostBearer = "platform" | "customer" | "unknown";
+export type BillingPrincipalBucket = "human" | "user_api_key" | "organization_machine" | "organization_user";
+export type BillingAttributionKind = "user_level" | "system" | "unattributed";
+export type BillingLlmRequestPurpose = "agent_turn" | "compaction" | "auto_title" | "manual_title" | "asr" | "voice_realtime";
+export type LlmPricingStatus = "estimated" | "unknown";
+export type LlmPricingContextTier = "short" | "long" | "all_context" | "unknown";
+export type SandboxUsageStatus = "running" | "closed" | "close_failed" | "abandoned";
+export type BillingUsageEvidenceStatus = "complete" | "partial" | "missing" | "unsupported";
+export type BillingValuationStatus = "priced" | "unpriced";
+export interface BillingValuationSummary {
+    status: "complete" | "incomplete";
+    pricedUsageCount: number;
+    unpricedUsageCount: number;
+    pricedCostMicros: number;
+}
+export interface BillingValuationBreakdown extends BillingValuationSummary {
+    byKind: Partial<Record<BillingUsageFactKind, BillingValuationSummary>>;
+}
+export interface BillingFactCompletenessCounters {
+    status: "complete" | "incomplete";
+    projectedFactCount: number;
+    pendingIntentCount: number;
+    indeterminateIntentCount: number;
+    failedIntentCount: number;
+}
+export interface BillingFactCompleteness extends BillingFactCompletenessCounters {
+    byKind: Partial<Record<BillingUsageFactKind, BillingFactCompletenessCounters>>;
+}
+export interface UsageTotals {
+    /** The single currency of this deployment. */
+    currency: "USD" | "CNY";
+    /** Platform-borne priced cost; other bearers remain in costByBearer. */
+    totalCostMicros: number;
+    llmCostMicros: number;
+    sandboxCostMicros: number;
+    webSearchCostMicros: number;
+    costByBearer: Record<BillingCostBearer, BillingBearerCostTotals>;
+    organizationMachineCostMicros: number;
+    llmRequestCount: number;
+    unknownLlmRequestCount: number;
+    sandboxUsageCount: number;
+    webSearchRequestCount: number;
+    unsettledCount: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    unpricedLlmTokens: {
+        inputTokens: number;
+        cachedInputTokens: number;
+        outputTokens: number;
+    };
+    sandboxDurationSeconds: number;
+    valuation: BillingValuationBreakdown;
+    attribution: BillingAttributionBreakdown;
+}
+export interface BillingBearerCostTotals {
+    totalCostMicros: number;
+    llmCostMicros: number;
+    sandboxCostMicros: number;
+    webSearchCostMicros: number;
+}
+export interface BillingAttributionCounters {
+    status: "complete" | "incomplete";
+    classifiedUsageCount: number;
+    userLevelUsageCount: number;
+    systemUsageCount: number;
+    unattributedUsageCount: number;
+}
+export interface BillingAttributionBreakdown extends BillingAttributionCounters {
+    byKind: Partial<Record<BillingUsageFactKind, BillingAttributionCounters>>;
+}
+export interface LlmUsageAggregate {
+    costBearer: BillingCostBearer;
+    provider: string;
+    model: string;
+    requestPurpose: BillingLlmRequestPurpose;
+    principalBucket: BillingPrincipalBucket;
+    requestCount: number;
+    unknownRequestCount: number;
+    costMicros: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    valuation: BillingValuationSummary;
+}
+export interface SandboxUsageAggregate {
+    costBearer: BillingCostBearer;
+    provider: "e2b" | "tencent_ags" | "run9";
+    profileId: string;
+    specKey: string;
+    principalBucket: BillingPrincipalBucket;
+    usageCount: number;
+    settledUsageCount: number;
+    unsettledCount: number;
+    costMicros: number;
+    durationSeconds: number;
+    valuation: BillingValuationSummary;
+}
+export interface WebSearchUsageAggregate {
+    costBearer: BillingCostBearer;
+    provider: "exa";
+    searchType: "auto";
+    principalBucket: BillingPrincipalBucket;
+    requestCount: number;
+    requestedResultCount: number;
+    returnedResultCount: number;
+    costMicros: number;
+    valuation: BillingValuationSummary;
+}
+export type BillingUsageSeriesInterval = "hour" | "day" | "week" | "month";
+export interface BillingUsageSeriesRange {
+    from: string;
+    to: string;
+    interval: BillingUsageSeriesInterval;
+}
+interface BillingUsageSeriesBreakdownCommon {
+    provider: string;
+    costMicros: number;
+    truncatedCombinations?: number;
+}
+export interface BillingUsageSeriesLlmBreakdown extends BillingUsageSeriesBreakdownCommon {
+    kind: "llm";
+    model?: string;
+    usage: {
+        inputTokens: number;
+        cachedInputTokens: number;
+        outputTokens: number;
+    };
+}
+export interface BillingUsageSeriesSandboxBreakdown extends BillingUsageSeriesBreakdownCommon {
+    kind: "sandbox";
+    usage: {
+        durationSeconds: number;
+        usageCount: number;
+    };
+}
+export interface BillingUsageSeriesWebSearchBreakdown extends BillingUsageSeriesBreakdownCommon {
+    kind: "web_search";
+    usage: {
+        requestCount: number;
+    };
+}
+export type BillingUsageSeriesBreakdown = BillingUsageSeriesLlmBreakdown | BillingUsageSeriesSandboxBreakdown | BillingUsageSeriesWebSearchBreakdown;
+export type BillingUsageSeriesBreakdownGroups = Record<BillingCostBearer, BillingUsageSeriesBreakdown[]>;
+export interface BillingUsageSeriesPoint {
+    bucketStart: string;
+    costMicros: number;
+    llmCostMicros: number;
+    sandboxCostMicros: number;
+    webSearchCostMicros: number;
+    unknownLlmRequestCount: number;
+    unsettledCount: number;
+    breakdown: BillingUsageSeriesBreakdownGroups;
+    valuation: BillingValuationSummary;
+}
+export interface OrganizationUserUsageSummary {
+    range: BillingUsageSeriesRange;
+    factCompleteness: BillingFactCompleteness;
+    totals: UsageTotals;
+    llm: {
+        aggregates: LlmUsageAggregate[];
+    };
+    sandbox: {
+        aggregates: SandboxUsageAggregate[];
+    };
+    webSearch: {
+        aggregates: WebSearchUsageAggregate[];
+    };
+    series: BillingUsageSeriesPoint[];
+}
+interface OrganizationUsageCommon {
+    id: string;
+    occurredAt: string;
+    sessionId: string;
+    /** Null for `voice_realtime` usage. */
+    turnId: string | null;
+    /** The Realtime connection of `voice_realtime` usage; null otherwise. */
+    realtimeConnectionId?: string | null;
+    agentRunId: string | null;
+    /** The Template admitted for the usage's Turn; null when it has none. */
+    agentTemplateId: string | null;
+    attributionKind: BillingAttributionKind;
+    costMicros: number | null;
+    currency: string | null;
+    pricingVersion: string;
+    pricingEffectiveAt: string;
+    valuationStatus: BillingValuationStatus;
+    valuationReason: string | null;
+    rateCardDigest: string | null;
+    billingTag: BillingTag | null;
+}
+export interface OrganizationLlmUsage extends OrganizationUsageCommon {
+    kind: "llm";
+    realtimeConnectionId: string | null;
+    /**
+     * For `voice_realtime` usage, whether its Realtime connection was still live
+     * when read; a live connection reports usage in interim items. Null otherwise.
+     */
+    realtimeConnectionLive: boolean | null;
+    operationId: string | null;
+    requestPurpose: BillingLlmRequestPurpose;
+    provider: string;
+    model: string;
+    observedResponseModel: string | null;
+    inputTokens: number;
+    cachedInputTokens: number;
+    uncachedInputTokens: number;
+    cacheReadTokens: number;
+    cacheWrite5mTokens: number;
+    cacheWrite1hTokens: number;
+    cacheWriteUnspecifiedTokens: number;
+    outputTokens: number;
+    inputCostMicros: number | null;
+    cachedInputCostMicros: number | null;
+    cacheWrite5mCostMicros: number | null;
+    cacheWrite1hCostMicros: number | null;
+    cacheWriteUnspecifiedCostMicros: number | null;
+    outputCostMicros: number | null;
+    pricingStatus: LlmPricingStatus;
+    estimateBasis: "public_list_placeholder" | "contract" | null;
+    contextTier: LlmPricingContextTier;
+}
+export interface OrganizationSandboxUsage extends OrganizationUsageCommon {
+    kind: "sandbox";
+    turnId: string;
+    provider: "e2b" | "tencent_ags" | "run9";
+    profileId: string;
+    specKey: string;
+    startedAt: string;
+    endedAt: string | null;
+    durationSeconds: number | null;
+    status: SandboxUsageStatus;
+}
+export interface OrganizationWebSearchUsage extends OrganizationUsageCommon {
+    kind: "web_search";
+    turnId: string;
+    operationId: string;
+    provider: "exa";
+    searchType: "auto";
+    requestCount: 1;
+    requestedResultCount: number;
+    returnedResultCount: number | null;
+    contentTextRequested: true;
+    requestOutcome: "succeeded" | "failed" | "aborted";
+    usageEvidenceStatus: BillingUsageEvidenceStatus;
+}
+export type OrganizationUsageItem = OrganizationLlmUsage | OrganizationSandboxUsage | OrganizationWebSearchUsage;
+export interface OrganizationUserUsageDetails {
+    items: OrganizationUsageItem[];
+    nextCursor: string | null;
+    factCompleteness: BillingFactCompleteness;
+}
+export interface OrganizationUserUsageOptions extends RequestOptions {
+    /** Exact inclusive UTC timestamp with milliseconds; maximum range is 31 days. */
+    from: string;
+    /** Exact exclusive UTC timestamp with milliseconds. */
+    to: string;
+    interval?: BillingUsageSeriesInterval;
+    /** Only usage admitted under this Template. */
+    templateId?: string;
+    tagKey?: string;
+    tagValue?: string;
+}
+export interface OrganizationUserUsageDetailsOptions extends Omit<OrganizationUserUsageOptions, "interval"> {
+    kind?: BillingUsageFactKind;
+    limit?: number;
+    cursor?: string;
+}
+export declare const usageQuery: (options: object, allowed: readonly string[]) => string;
+export declare const userUsagePath: (userId: string, options: {
+    from: string;
+    to: string;
+}) => string;
+export {};
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

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

package/dist/usage.js

@@ -0,0 +1,22 @@
+import { requireKnownKeys, setTemplateFilter } from "./http.js";
+export const usageQuery = (options, allowed) => {
+    requireKnownKeys(options, [...allowed, "signal", "requestId"], "Usage options");
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(options))
+        if (key !== "templateId" && allowed.includes(key) && value !== undefined)
+            query.set(key, String(value));
+    if (allowed.includes("templateId"))
+        setTemplateFilter(query, options.templateId);
+    return query.size ? `?${query}` : "";
+};
+export const userUsagePath = (userId, options) => {
+    if (typeof userId !== "string" || !/^[a-z0-9_-]{1,64}$/.test(userId))
+        throw new TypeError("Organization usage requires an explicit User ID");
+    if (typeof options?.from !== "string" ||
+        !options.from ||
+        typeof options.to !== "string" ||
+        !options.to)
+        throw new TypeError("Organization usage requires from and to UTC timestamps");
+    return `/users/${encodeURIComponent(userId)}/billing/usage`;
+};
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AA2UhE,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,OAAe,EACf,OAA0B,EAClB,EAAE;IACV,gBAAgB,CACd,OAAO,EACP,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,EACnC,eAAe,CAChB,CAAC;IACF,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;IACpC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;QAChD,IAAI,GAAG,KAAK,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,KAAK,SAAS;YACtE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAClC,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;QAChC,iBAAiB,CAAC,KAAK,EAAG,OAAoC,CAAC,UAAU,CAAC,CAAC;IAC7E,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACvC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,MAAc,EACd,OAAqC,EAC7B,EAAE;IACV,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC;QAClE,MAAM,IAAI,SAAS,CAAC,iDAAiD,CAAC,CAAC;IACzE,IACE,OAAO,OAAO,EAAE,IAAI,KAAK,QAAQ;QACjC,CAAC,OAAO,CAAC,IAAI;QACb,OAAO,OAAO,CAAC,EAAE,KAAK,QAAQ;QAC9B,CAAC,OAAO,CAAC,EAAE;QAEX,MAAM,IAAI,SAAS,CACjB,wDAAwD,CACzD,CAAC;IACJ,OAAO,UAAU,kBAAkB,CAAC,MAAM,CAAC,gBAAgB,CAAC;AAC9D,CAAC,CAAC"}

package/dist/user.d.ts

@@ -0,0 +1,55 @@
+import { UserFiles } from "./files.js";
+import { HttpClient, type ListOptions } from "./http.js";
+import type { RequestOptions } from "./organization.js";
+import { type CreateSessionOptions, Session } from "./session.js";
+import type { RealtimeModelCatalog } from "./realtime.js";
+export interface AgentTemplate {
+    agentTemplateId: string;
+    displayName: string;
+    description: string;
+    contentDigest: string;
+}
+export interface AgentTemplatePage {
+    templates: AgentTemplate[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+export interface AgentModelCatalog {
+    defaultModel: string;
+    models: {
+        model: string;
+        label: string;
+        availability: "available" | "provider_unconfigured";
+    }[];
+    organizationDefaultModel: string;
+    effectiveDefaultModel: string;
+    organizationAllowedModels: string[];
+    effectiveAllowedModels: string[];
+}
+export interface SessionListOptions extends ListOptions {
+    /** Only Sessions currently on this Template. */
+    templateId?: string;
+}
+export interface SessionPage {
+    sessions: Session[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+/** Ordinary End User resources under the caller's authority. */
+export declare class EndUserClient {
+    #private;
+    get files(): UserFiles;
+    constructor(http: HttpClient);
+    /**
+     * Create a Session from an explicit Template. The Session freezes the
+     * Template recipe, digest and these creation options.
+     */
+    createSession(options: CreateSessionOptions): Promise<Session>;
+    listAgentTemplates(options?: ListOptions): Promise<AgentTemplatePage>;
+    listModels(options?: RequestOptions): Promise<AgentModelCatalog>;
+    listRealtimeModels(options?: RequestOptions): Promise<RealtimeModelCatalog>;
+    listSessions(options?: SessionListOptions): Promise<SessionPage>;
+    session(id: string): Session;
+    getSession(id: string, options?: RequestOptions): Promise<Session>;
+}
+//# sourceMappingURL=user.d.ts.map

package/dist/user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../src/user.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAEL,UAAU,EAIV,KAAK,WAAW,EACjB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAEL,KAAK,oBAAoB,EACzB,OAAO,EAER,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,WAAW,GAAG,uBAAuB,CAAC;KACrD,EAAE,CAAC;IACJ,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,yBAAyB,EAAE,MAAM,EAAE,CAAC;IACpC,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,gEAAgE;AAChE,qBAAa,aAAa;;IAIxB,IAAI,KAAK,IAAI,SAAS,CAErB;gBAEW,IAAI,EAAE,UAAU;IAK5B;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAI9D,kBAAkB,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAOrE,UAAU,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAMhE,kBAAkB,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAIrE,YAAY,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IAuBtE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAG5B,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;CAGnE"}

package/dist/user.js

@@ -0,0 +1,52 @@
+import { UserFiles } from "./files.js";
+import { requestOptions, HttpClient, paginationQuery, requireKnownKeys, setTemplateFilter, } from "./http.js";
+import { createSession, Session, } from "./session.js";
+/** Ordinary End User resources under the caller's authority. */
+export class EndUserClient {
+    #http;
+    #files;
+    get files() {
+        return this.#files;
+    }
+    constructor(http) {
+        this.#http = http;
+        this.#files = new UserFiles(http);
+    }
+    /**
+     * Create a Session from an explicit Template. The Session freezes the
+     * Template recipe, digest and these creation options.
+     */
+    createSession(options) {
+        return createSession(this.#http, options);
+    }
+    listAgentTemplates(options) {
+        return this.#http.get(`/agent-templates${paginationQuery(options)}`, options);
+    }
+    listModels(options) {
+        if (options)
+            requireKnownKeys(options, ["signal", "requestId"], "Model list options");
+        return this.#http.get("/agent-models", options);
+    }
+    listRealtimeModels(options) {
+        return this.#http.get("/realtime-models", requestOptions(options));
+    }
+    async listSessions(options) {
+        if (options)
+            requireKnownKeys(options, ["templateId", "limit", "cursor", "signal", "requestId"], "Session list options");
+        const { templateId, ...page } = options ?? {};
+        const query = new URLSearchParams(paginationQuery(page));
+        setTemplateFilter(query, templateId);
+        const response = await this.#http.get(`/sessions${query.size ? `?${query}` : ""}`, options);
+        return {
+            ...response,
+            sessions: response.sessions.map((record) => new Session(this.#http, record.sessionId, record)),
+        };
+    }
+    session(id) {
+        return new Session(this.#http, id);
+    }
+    getSession(id, options) {
+        return this.session(id).refresh(options);
+    }
+}
+//# sourceMappingURL=user.js.map