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

package/dist/audio.d.ts

@@ -0,0 +1,63 @@
+import { HttpClient } from "./http.js";
+import { OutcomeUnknownError } from "./errors.js";
+import type { BillingTag, ClarificationItem } from "./session.js";
+import type { OperationRecord, TurnFailure } from "./history.js";
+import type { RequestOptions } from "./organization.js";
+export interface AudioTurnInput extends RequestOptions {
+    bytes: Uint8Array;
+    filename: string;
+    contentType?: string;
+    /** Omit to inherit, null to clear the Session's default for this audio Turn. */
+    billingTag?: BillingTag | null;
+}
+type AudioEnvelope<Name extends string, Payload> = {
+    event: Name;
+    sessionId: string;
+    turnId: string;
+    agentRunId?: string;
+    seq: number;
+    createdAt: string;
+    payload: Payload;
+};
+export type AudioTurnEvent = AudioEnvelope<"turn_started", {
+    execution?: {
+        model: string;
+    };
+    inputId?: string;
+}> | AudioEnvelope<"progress", {
+    text: string;
+}> | AudioEnvelope<"assistant_draft", {
+    text: string;
+}> | AudioEnvelope<"operation_step", {
+    operationId: string;
+    status: OperationRecord["status"];
+    label: string;
+    category?: OperationRecord["category"];
+    skill?: OperationRecord["skill"];
+    source?: OperationRecord["source"];
+}> | AudioEnvelope<"assistant_message", {
+    messageId: string;
+    text: string;
+    clarificationItem?: ClarificationItem;
+}> | AudioEnvelope<"turn_error", TurnFailure> | AudioEnvelope<"turn_finished", {
+    status: "succeeded" | "failed" | "interrupted";
+}>;
+export type AudioTurnResult = {
+    sessionId: string;
+    turnId: string;
+    messageId: string;
+    text: string;
+} & ({
+    type: "answer";
+} | {
+    type: "clarification";
+    clarification: ClarificationItem;
+});
+/** Audio owns its response: losing or closing it may request remote interruption. */
+export declare class AudioTurnStoppedError extends OutcomeUnknownError {
+    constructor(sessionId: string, turnId?: string, requestId?: string, cause?: unknown);
+}
+export declare function streamAudio(http: HttpClient, sessionId: string, input: AudioTurnInput): AsyncGenerator<AudioTurnEvent>;
+export declare function audioTurn(http: HttpClient, sessionId: string, input: AudioTurnInput): Promise<AudioTurnResult>;
+export {};
+//# sourceMappingURL=audio.d.ts.map

package/dist/audio.d.ts.map

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

package/dist/audio.js

@@ -0,0 +1,163 @@
+import { HttpClient, requireKnownKeys } from "./http.js";
+import { OutcomeUnknownError, TiDBLinkApiError, TurnFailedError, TurnInterruptedError, TiDBLinkError, } from "./errors.js";
+import { decodeSse } from "./sse.js";
+import { validClarification } from "./turn.js";
+/** Audio owns its response: losing or closing it may request remote interruption. */
+export class AudioTurnStoppedError extends OutcomeUnknownError {
+    constructor(sessionId, turnId, requestId, cause) {
+        super("Audio response stopped before a confirmed terminal outcome; closing it may request interruption. Inspect saved history before submitting audio again.", {
+            sessionId,
+            ...(turnId ? { turnId } : {}),
+            ...(requestId ? { requestId } : {}),
+            ...(cause ? { cause } : {}),
+        });
+    }
+}
+const multipart = (input) => {
+    requireKnownKeys(input, ["bytes", "filename", "contentType", "billingTag", "signal", "requestId"], "Audio input");
+    if (!(input.bytes instanceof Uint8Array) ||
+        input.bytes.byteLength < 1 ||
+        input.bytes.byteLength > 25 * 1024 * 1024)
+        throw new TypeError("Audio requires 1 byte to 25 MiB of prerecorded data");
+    if (typeof input.filename !== "string" ||
+        !input.filename.trim() ||
+        input.filename.length > 255)
+        throw new TypeError("Audio requires a filename of 1-255 characters");
+    const contentType = input.contentType ?? "application/octet-stream";
+    if (!/^[A-Za-z0-9!#$&^_.+-]+\/[A-Za-z0-9!#$&^_.+-]+$/.test(contentType))
+        throw new TypeError("Audio contentType must be a media type without parameters");
+    const boundary = `tidb-link-audio-${crypto.randomUUID()}`;
+    const filename = input.filename
+        .replace(/\r/g, "%0D")
+        .replace(/\n/g, "%0A")
+        .replace(/"/g, "%22");
+    const parts = [];
+    if (input.billingTag !== undefined)
+        parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="billingTag"\r\nContent-Type: application/json\r\n\r\n${JSON.stringify(input.billingTag)}\r\n`);
+    parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${filename}"\r\nContent-Type: ${contentType}\r\n\r\n`, Uint8Array.from(input.bytes), `\r\n--${boundary}--\r\n`);
+    return {
+        body: new Blob(parts),
+        contentType: `multipart/form-data; boundary=${boundary}`,
+    };
+};
+export async function* streamAudio(http, sessionId, input) {
+    const upload = multipart(input);
+    input.signal?.throwIfAborted();
+    let turnId;
+    let requestId;
+    let sequence = -1;
+    let response;
+    try {
+        ({ response, requestId } = await http.rawResponse(`/api/v1/user/sessions/${encodeURIComponent(sessionId)}/turns/audio`, {
+            method: "POST",
+            body: upload.body,
+            headers: {
+                accept: "text/event-stream",
+                "content-type": upload.contentType,
+            },
+            ...(input.signal ? { signal: input.signal } : {}),
+            ...(input.requestId ? { requestId: input.requestId } : {}),
+        }));
+        if (response.status !== 201 ||
+            response.headers
+                .get("content-type")
+                ?.split(";")[0]
+                ?.trim()
+                .toLowerCase() !== "text/event-stream" ||
+            !response.body)
+            throw new TiDBLinkError("Audio response omitted its event stream");
+        for await (const frame of decodeSse(response.body)) {
+            const event = JSON.parse(frame.data);
+            if (!event ||
+                event.sessionId !== sessionId ||
+                typeof event.turnId !== "string" ||
+                !event.turnId ||
+                (turnId && event.turnId !== turnId) ||
+                !Number.isSafeInteger(event.seq) ||
+                event.seq <= sequence ||
+                typeof event.createdAt !== "string" ||
+                !event.payload ||
+                typeof event.payload !== "object" ||
+                Array.isArray(event.payload) ||
+                frame.event !== event.event ||
+                ![
+                    "turn_started",
+                    "progress",
+                    "assistant_draft",
+                    "operation_step",
+                    "assistant_message",
+                    "turn_error",
+                    "turn_finished",
+                ].includes(event.event))
+                throw new TiDBLinkError("Audio response returned an invalid or mismatched event envelope");
+            turnId = event.turnId;
+            sequence = event.seq;
+            if ((event.event === "assistant_draft" || event.event === "progress") &&
+                typeof event.payload.text !== "string")
+                throw new TiDBLinkError("Audio response returned invalid text");
+            if (event.event === "assistant_message" &&
+                (typeof event.payload.messageId !== "string" ||
+                    !event.payload.messageId ||
+                    typeof event.payload.text !== "string" ||
+                    (event.payload.clarificationItem !== undefined &&
+                        !validClarification(event.payload.clarificationItem))))
+                throw new TiDBLinkError("Audio response returned an invalid final Message");
+            if (event.event === "turn_finished" &&
+                !["succeeded", "failed", "interrupted"].includes(event.payload.status))
+                throw new TiDBLinkError("Audio response returned an invalid terminal status");
+            yield event;
+            if (event.event === "turn_finished")
+                return;
+        }
+        throw new AudioTurnStoppedError(sessionId, turnId, requestId);
+    }
+    catch (cause) {
+        if (cause instanceof TiDBLinkApiError ||
+            cause instanceof AudioTurnStoppedError)
+            throw cause;
+        throw new AudioTurnStoppedError(sessionId, turnId, requestId ??
+            (cause instanceof TiDBLinkError ? cause.requestId : input.requestId), cause);
+    }
+    finally {
+        if (response?.body && !response.body.locked)
+            await response.body.cancel().catch(() => undefined);
+    }
+}
+export async function audioTurn(http, sessionId, input) {
+    let message;
+    let failure;
+    for await (const event of streamAudio(http, sessionId, input)) {
+        if (event.event === "assistant_message")
+            message = event;
+        if (event.event === "turn_error")
+            failure = event.payload;
+        if (event.event === "turn_finished") {
+            if (event.payload.status === "failed")
+                throw new TurnFailedError({
+                    sessionId,
+                    turnId: event.turnId,
+                    code: failure?.code ?? "turn_failed",
+                    message: failure?.message ?? "Audio Turn failed",
+                });
+            if (event.payload.status === "interrupted")
+                throw new TurnInterruptedError(event.turnId, "Audio Turn was interrupted", sessionId);
+            if (!message)
+                throw new AudioTurnStoppedError(sessionId, event.turnId);
+            const identity = {
+                sessionId,
+                turnId: event.turnId,
+                messageId: message.payload.messageId,
+                text: message.payload.text,
+            };
+            return message.payload.clarificationItem
+                ? {
+                    ...identity,
+                    type: "clarification",
+                    clarification: message.payload.clarificationItem,
+                }
+                : { ...identity, type: "answer" };
+        }
+    }
+    throw new AudioTurnStoppedError(sessionId);
+}
+//# sourceMappingURL=audio.js.map

package/dist/audio.js.map

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

package/dist/client-tools.d.ts

@@ -0,0 +1,46 @@
+import { type SessionInteraction } from "./history.js";
+import { HttpClient } from "./http.js";
+import type { RequestOptions } from "./organization.js";
+export interface ClientToolDeclaration {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export interface ClientToolSet {
+    revision: number;
+    tools: ClientToolDeclaration[];
+    /** Pass this exact value when replacing the complete set. */
+    etag: string;
+}
+export interface ReplaceClientToolsOptions extends RequestOptions {
+    ifMatch: string;
+}
+export declare function validateClientTools(tools: readonly ClientToolDeclaration[]): void;
+export declare function getClientTools(http: HttpClient, sessionId: string, options?: RequestOptions): Promise<ClientToolSet>;
+export declare function replaceClientTools(http: HttpClient, sessionId: string, tools: readonly ClientToolDeclaration[], options: ReplaceClientToolsOptions): Promise<ClientToolSet>;
+export interface PendingClientToolCall {
+    callId: string;
+    turnId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    publishedAt: string;
+    deadlineAt: string;
+}
+export type ClientToolOutputInput = RequestOptions & {
+    /** Persist a separate command identity; callId identifies the call, not this submission. */
+    clientEventId: string;
+    turnId: string;
+    callId: string;
+} & ({
+    output: string;
+    error?: never;
+} | {
+    error: {
+        message: string;
+    };
+    output?: never;
+});
+export declare function listPendingClientToolCalls(http: HttpClient, sessionId: string, options?: RequestOptions): Promise<PendingClientToolCall[]>;
+export declare function submitClientToolOutput(http: HttpClient, sessionId: string, input: ClientToolOutputInput): Promise<SessionInteraction>;
+//# sourceMappingURL=client-tools.d.ts.map

package/dist/client-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-tools.d.ts","sourceRoot":"","sources":["../src/client-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAE3E,OAAO,EACL,UAAU,EAKX,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,qBAAqB,EAAE,CAAC;IAC/B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAA0B,SAAQ,cAAc;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,qBAAqB,EAAE,GACtC,IAAI,CAuBN;AAkBD,wBAAsB,cAAc,CAClC,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC,CAQxB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,qBAAqB,EAAE,EACvC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CAqBxB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,qBAAqB,GAAG,cAAc,GAAG;IACnD,4FAA4F;IAC5F,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,CACE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GACjC;IAAE,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,CACjD,CAAC;AAEJ,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAYlC;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAkF7B"}

package/dist/client-tools.js

@@ -0,0 +1,114 @@
+import { requireInteraction } from "./history.js";
+import { OutcomeUnknownError, TiDBLinkError } from "./errors.js";
+import { HttpClient, requireEtag, requireKnownKeys, requireCreationKey, } from "./http.js";
+export function validateClientTools(tools) {
+    if (!Array.isArray(tools) || tools.length > 64)
+        throw new TypeError("tools must be an array of at most 64 declarations");
+    for (const tool of tools) {
+        requireKnownKeys(tool, ["type", "name", "description", "parameters"], "Client Tool declaration");
+        if (tool.type !== "function" ||
+            typeof tool.name !== "string" ||
+            !tool.name ||
+            typeof tool.description !== "string" ||
+            !tool.description ||
+            typeof tool.parameters !== "object" ||
+            tool.parameters === null ||
+            Array.isArray(tool.parameters))
+            throw new TypeError("Client Tools require a function name, description and JSON Schema parameters");
+    }
+}
+const toolSet = (result) => {
+    if (!Number.isSafeInteger(result.data?.revision) ||
+        result.data.revision < 0 ||
+        !Array.isArray(result.data.tools))
+        throw new TiDBLinkError("TiDB Link returned an invalid Client Tool set", {
+            requestId: result.requestId,
+        });
+    return { ...result.data, etag: requireEtag(result) };
+};
+const toolsPath = (sessionId) => `/api/v1/user/sessions/${encodeURIComponent(sessionId)}/tools`;
+export async function getClientTools(http, sessionId, options) {
+    if (options)
+        requireKnownKeys(options, ["signal", "requestId"], "Client Tool read options");
+    return toolSet(await http.getResponse(toolsPath(sessionId), options));
+}
+export async function replaceClientTools(http, sessionId, tools, options) {
+    validateClientTools(tools);
+    requireKnownKeys(options, ["ifMatch", "signal", "requestId"], "Client Tool replacement options");
+    if (typeof options.ifMatch !== "string" || !options.ifMatch)
+        throw new TypeError("Client Tool replacement requires ifMatch");
+    const result = await http.response(toolsPath(sessionId), { method: "PUT", body: { tools }, outcomeUnknown: true, ...options });
+    try {
+        return toolSet(result);
+    }
+    catch (cause) {
+        throw new OutcomeUnknownError("Client Tool replacement returned no usable receipt; read the current set before retrying", { sessionId, requestId: result.requestId, cause });
+    }
+}
+export async function listPendingClientToolCalls(http, sessionId, options) {
+    if (options)
+        requireKnownKeys(options, ["signal", "requestId"], "Pending Client Tool call options");
+    const result = await http.get(`/api/v1/user/sessions/${encodeURIComponent(sessionId)}/client-tool-calls`, options);
+    return result.calls;
+}
+export async function submitClientToolOutput(http, sessionId, input) {
+    requireKnownKeys(input, [
+        "clientEventId",
+        "turnId",
+        "callId",
+        "output",
+        "error",
+        "signal",
+        "requestId",
+    ], "Client Tool output");
+    requireCreationKey(input.clientEventId);
+    for (const id of [input.turnId, input.callId])
+        if (typeof id !== "string" || !id || id.length > 64)
+            throw new TypeError("Client Tool output requires turnId and callId containing 1-64 characters");
+    if (Object.hasOwn(input, "output") === Object.hasOwn(input, "error"))
+        throw new TypeError("Provide exactly one Client Tool output or error");
+    if ("output" in input) {
+        if (typeof input.output !== "string" || input.output.length > 65536)
+            throw new TypeError("Client Tool output must be a string of at most 65536 characters");
+    }
+    else {
+        requireKnownKeys(input.error, ["message"], "Client Tool error");
+        if (typeof input.error.message !== "string" ||
+            !input.error.message ||
+            input.error.message.length > 4096)
+            throw new TypeError("Client Tool error.message must contain 1-4096 characters");
+    }
+    const { clientEventId, signal, requestId, ...data } = input;
+    const turnId = data.turnId;
+    signal?.throwIfAborted();
+    try {
+        const result = await http.postResponse(`/api/v1/user/sessions/${encodeURIComponent(sessionId)}/events`, { type: "agent.session.input.client_tool_output", clientEventId, data }, {
+            outcomeUnknown: true,
+            ...(signal ? { signal } : {}),
+            ...(requestId ? { requestId } : {}),
+        });
+        try {
+            const receipt = requireInteraction(result.data?.interaction, clientEventId, result.requestId);
+            if (receipt.kind !== "client_tool_output" ||
+                receipt.turnId !== turnId ||
+                receipt.message !== null)
+                throw new TiDBLinkError("Client Tool output receipt identifies a different command");
+            return receipt;
+        }
+        catch (cause) {
+            throw new OutcomeUnknownError("Client Tool output 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,
+            turnId,
+            ...(cause.requestId ? { requestId: cause.requestId } : {}),
+            cause,
+        });
+    }
+}
+//# sourceMappingURL=client-tools.js.map

package/dist/client-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-tools.js","sourceRoot":"","sources":["../src/client-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAA2B,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EACL,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,kBAAkB,GAEnB,MAAM,WAAW,CAAC;AAqBnB,MAAM,UAAU,mBAAmB,CACjC,KAAuC;IAEvC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE;QAC5C,MAAM,IAAI,SAAS,CAAC,mDAAmD,CAAC,CAAC;IAC3E,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,gBAAgB,CACd,IAAI,EACJ,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,CAAC,EAC7C,yBAAyB,CAC1B,CAAC;QACF,IACE,IAAI,CAAC,IAAI,KAAK,UAAU;YACxB,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;YAC7B,CAAC,IAAI,CAAC,IAAI;YACV,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ;YACpC,CAAC,IAAI,CAAC,WAAW;YACjB,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ;YACnC,IAAI,CAAC,UAAU,KAAK,IAAI;YACxB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;YAE9B,MAAM,IAAI,SAAS,CACjB,8EAA8E,CAC/E,CAAC;IACN,CAAC;AACH,CAAC;AAED,MAAM,OAAO,GAAG,CACd,MAA+C,EAChC,EAAE;IACjB,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC;QACxB,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;QAEjC,MAAM,IAAI,aAAa,CAAC,+CAA+C,EAAE;YACvE,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;IACL,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;AACvD,CAAC,CAAC;AACF,MAAM,SAAS,GAAG,CAAC,SAAiB,EAAE,EAAE,CACtC,yBAAyB,kBAAkB,CAAC,SAAS,CAAC,QAAQ,CAAC;AAEjE,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAgB,EAChB,SAAiB,EACjB,OAAwB;IAExB,IAAI,OAAO;QACT,gBAAgB,CACd,OAAO,EACP,CAAC,QAAQ,EAAE,WAAW,CAAC,EACvB,0BAA0B,CAC3B,CAAC;IACJ,OAAO,OAAO,CAAC,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAgB,EAChB,SAAiB,EACjB,KAAuC,EACvC,OAAkC;IAElC,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC3B,gBAAgB,CACd,OAAO,EACP,CAAC,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,EAClC,iCAAiC,CAClC,CAAC;IACF,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,OAAO;QACzD,MAAM,IAAI,SAAS,CAAC,0CAA0C,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAChC,SAAS,CAAC,SAAS,CAAC,EACpB,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CACrE,CAAC;IACF,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,mBAAmB,CAC3B,0FAA0F,EAC1F,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,KAAK,EAAE,CAClD,CAAC;IACJ,CAAC;AACH,CAAC;AAqBD,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,IAAgB,EAChB,SAAiB,EACjB,OAAwB;IAExB,IAAI,OAAO;QACT,gBAAgB,CACd,OAAO,EACP,CAAC,QAAQ,EAAE,WAAW,CAAC,EACvB,kCAAkC,CACnC,CAAC;IACJ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAC3B,yBAAyB,kBAAkB,CAAC,SAAS,CAAC,oBAAoB,EAC1E,OAAO,CACR,CAAC;IACF,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,IAAgB,EAChB,SAAiB,EACjB,KAA4B;IAE5B,gBAAgB,CACd,KAAK,EACL;QACE,eAAe;QACf,QAAQ;QACR,QAAQ;QACR,QAAQ;QACR,OAAO;QACP,QAAQ;QACR,WAAW;KACZ,EACD,oBAAoB,CACrB,CAAC;IACF,kBAAkB,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IACxC,KAAK,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;QAC3C,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,GAAG,EAAE;YACjD,MAAM,IAAI,SAAS,CACjB,0EAA0E,CAC3E,CAAC;IACN,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC;QAClE,MAAM,IAAI,SAAS,CAAC,iDAAiD,CAAC,CAAC;IACzE,IAAI,QAAQ,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,KAAK;YACjE,MAAM,IAAI,SAAS,CACjB,iEAAiE,CAClE,CAAC;IACN,CAAC;SAAM,CAAC;QACN,gBAAgB,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC,CAAC;QAChE,IACE,OAAO,KAAK,CAAC,KAAK,CAAC,OAAO,KAAK,QAAQ;YACvC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO;YACpB,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI;YAEjC,MAAM,IAAI,SAAS,CACjB,0DAA0D,CAC3D,CAAC;IACN,CAAC;IACD,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;IAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CACpC,yBAAyB,kBAAkB,CAAC,SAAS,CAAC,SAAS,EAC/D,EAAE,IAAI,EAAE,wCAAwC,EAAE,aAAa,EAAE,IAAI,EAAE,EACvE;YACE,cAAc,EAAE,IAAI;YACpB,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7B,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpC,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,oBAAoB;gBACrC,OAAO,CAAC,MAAM,KAAK,MAAM;gBACzB,OAAO,CAAC,OAAO,KAAK,IAAI;gBAExB,MAAM,IAAI,aAAa,CACrB,2DAA2D,CAC5D,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,MAAM;YACN,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"}

package/dist/control.d.ts

@@ -0,0 +1,17 @@
+import { HttpClient } from "./http.js";
+import { type SessionInteraction } from "./history.js";
+import type { RequestOptions } from "./organization.js";
+export interface TurnCommandInput extends RequestOptions {
+    /** Persist this new Session-local command identity before dispatch. */
+    clientEventId: string;
+    turnId: string;
+}
+export interface RetryReceipt {
+    clientEventId: string;
+    sessionId: string;
+    turnId: string;
+    disposition: "retrying";
+}
+export declare function submitTurnCommand(http: HttpClient, sessionId: string, kind: "cancel", input: TurnCommandInput): Promise<SessionInteraction>;
+export declare function submitTurnCommand(http: HttpClient, sessionId: string, kind: "retry", input: TurnCommandInput): Promise<RetryReceipt>;
+//# sourceMappingURL=control.d.ts.map

package/dist/control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAwC,MAAM,WAAW,CAAC;AAC7E,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,UAAU,CAAC;CACzB;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAC/B,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC"}

package/dist/control.js

@@ -0,0 +1,52 @@
+import { OutcomeUnknownError } from "./errors.js";
+import { HttpClient, requireCreationKey, requireKnownKeys } from "./http.js";
+import { requireInteraction } from "./history.js";
+export async function submitTurnCommand(http, sessionId, kind, input) {
+    requireKnownKeys(input, ["clientEventId", "turnId", "signal", "requestId"], "Turn command");
+    requireCreationKey(input.clientEventId);
+    if (typeof input.turnId !== "string" ||
+        !input.turnId ||
+        input.turnId.length > 64)
+        throw new TypeError("Turn command requires a turnId containing 1-64 characters");
+    const { clientEventId, turnId, signal, requestId } = input;
+    signal?.throwIfAborted();
+    try {
+        const result = await http.postResponse(`/api/v1/user/sessions/${encodeURIComponent(sessionId)}/events`, { type: `agent.session.input.${kind}`, clientEventId, data: { turnId } }, {
+            outcomeUnknown: true,
+            ...(signal ? { signal } : {}),
+            ...(requestId ? { requestId } : {}),
+        });
+        try {
+            if (kind === "cancel") {
+                const receipt = requireInteraction(result.data?.interaction, clientEventId, result.requestId);
+                if (receipt.kind !== kind ||
+                    receipt.turnId !== turnId ||
+                    receipt.message !== null)
+                    throw new Error("Cancellation receipt identifies a different command");
+                return receipt;
+            }
+            const receipt = result.data?.event;
+            if (receipt?.clientEventId !== clientEventId ||
+                receipt.sessionId !== sessionId ||
+                receipt.turnId !== turnId ||
+                receipt.disposition !== "retrying")
+                throw new Error("Retry receipt identifies a different command");
+            return receipt;
+        }
+        catch (cause) {
+            throw new OutcomeUnknownError("Turn command returned no usable receipt; query its original identity", { requestId: result.requestId, cause });
+        }
+    }
+    catch (cause) {
+        if (!(cause instanceof OutcomeUnknownError))
+            throw cause;
+        throw new OutcomeUnknownError(cause.message, {
+            sessionId,
+            inputId: clientEventId,
+            turnId,
+            ...(cause.requestId ? { requestId: cause.requestId } : {}),
+            cause,
+        });
+    }
+}
+//# sourceMappingURL=control.js.map

package/dist/control.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,80 @@
+export declare class TiDBLinkError extends Error {
+    readonly requestId: string | undefined;
+    constructor(message: string, options?: {
+        requestId?: string;
+        cause?: unknown;
+    });
+}
+export declare class TiDBLinkApiError extends TiDBLinkError {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    readonly retryAfter: string | undefined;
+    constructor(input: {
+        status: number;
+        code: string;
+        message: string;
+        requestId?: string;
+        details?: unknown;
+        retryAfter?: string;
+    });
+}
+export declare class ConflictError extends TiDBLinkApiError {
+}
+export declare class ConnectionError extends TiDBLinkError {
+}
+/** The request may have succeeded, so repeating it could create another effect. */
+export declare class OutcomeUnknownError extends TiDBLinkError {
+    readonly turnId: string | undefined;
+    readonly sessionId: string | undefined;
+    readonly inputId: string | undefined;
+    constructor(message: string, options?: {
+        requestId?: string;
+        turnId?: string;
+        sessionId?: string;
+        inputId?: string;
+        cause?: unknown;
+    });
+}
+export declare class TurnWaitTimeoutError extends OutcomeUnknownError {
+}
+export declare class InputNotAppliedError extends TiDBLinkError {
+    readonly sessionId: string;
+    readonly inputId: string;
+    readonly turnId: string;
+    constructor(sessionId: string, inputId: string, turnId: string);
+}
+export declare class TurnFailedError extends TiDBLinkError {
+    readonly code: string;
+    readonly turnId: string;
+    readonly sessionId: string | undefined;
+    readonly inputId: string | undefined;
+    constructor(input: {
+        code: string;
+        message: string;
+        turnId: string;
+        sessionId?: string;
+        inputId?: string;
+    });
+}
+export declare class TurnInterruptedError extends TiDBLinkError {
+    readonly sessionId?: string | undefined;
+    readonly inputId?: string | undefined;
+    readonly turnId: string;
+    constructor(turnId: string, message?: string, sessionId?: string | undefined, inputId?: string | undefined);
+}
+/** Observation stopped locally; the original command can still be queried or observed. */
+export declare class ObservationStoppedError extends OutcomeUnknownError {
+    readonly cursor: string | undefined;
+    readonly timedOut: boolean;
+    constructor(message: string, options: {
+        sessionId: string;
+        inputId: string;
+        turnId?: string;
+        cursor?: string;
+        requestId?: string;
+        timedOut?: boolean;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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