@finalai/agents 0.8.0

package/dist/modules/agent-client/index.d.mts

@@ -0,0 +1,17 @@
+export * from '@finalai/agent-protocol/agent-platform';
+export { AcpAuthMode, type AcpApiIface, type AcpConnectArgsIface } from "./acp.mjs";
+export { createTextCollector, isUserMessageFor, sessionUpdateOf, textOf, turnEndOf, type AcpSessionUpdateIface, type TurnEndIface, } from "./acp-frames.mjs";
+export type { ComputerSetupGuidesApiIface, DefinitionRefIface, DefinitionsApiIface, ProvidersApiIface, ScheduleRef, SchedulesApiIface, } from "./build.mjs";
+export { createClient, type AgentClientIface, type AgentHandleIface, type AgentsApiIface, type CreateClientOptionsIface, type PendingApiIface, type PeopleApiIface, type RealtimeApiIface, } from "./client.mjs";
+export { CollectionEventKind, CollectionResyncReason, type CollectionEvent, type CollectionEventsOptionsIface, type CollectionResyncEventIface, } from "./collection-events.mjs";
+export { ConfigOptionCategory, configSelectFor, configSelectsOf, type ConfigSelectChoiceIface, type ConfigSelectIface, type SessionConfigOptionIface, } from "./config-options.mjs";
+export type { EnumInput, SignalOptionsIface } from "./context.mjs";
+export { TURN_OPEN_SESSION_STATES, isNewerMessageVersion, messageVersionOf, type MessageVersionIface, } from "./conversations.mjs";
+export type { ConversationAgentTurnIface, ConversationEvent, ConversationEventMetaIface, ConversationEventsOptionsIface, ConversationHandleIface, ConversationsApiIface, CreateConversationArgsIface, ListMessagesOptionsIface, OpenedConversationIface, ParticipantCreateInput, SandboxFileContentArgsIface, SandboxFileContentRequestIface, SendMessageOptionsIface, SentMessageIface, UploadAttachmentArgsIface, } from "./conversations.mjs";
+export { AgentClientErrorName, ClientErrorCode, PendingRequestErrorReason, clientError, isClientError, isPendingRequestError, isRealtimeSubscriptionError, isTerminalRealtimeError, isTurnRejectedError, pendingRequestError, realtimeSubscriptionError, turnRejectedError, type AgentClientError, type ClientErrorIface, type PendingRequestErrorIface, type RealtimeSubscriptionErrorIface, type TurnRejectedErrorIface, } from "./errors.mjs";
+export { defaultStreamTiming, type StreamTimingIface } from "./frame-stream.mjs";
+export type { AgentClientAuth, FetchIface, HeadersOption } from "./http.mjs";
+export { SessionLiveEventKind, type SessionLiveEvent } from "./live-stream.mjs";
+export { createGatewayRealtimeTransport, type GatewayConnect, type GatewayConnectionIface, type GatewayRealtimeTransportOptionsIface, type RealtimeSubscribeOptionsIface, type RealtimeTransportFrameIface, type RealtimeTransportIface, } from "./realtime.mjs";
+export { SANDBOX_FILE_URI_SCHEME, createSandboxFileUri, parseSandboxFileUri, type SandboxFileTargetIface, } from "./sandbox-uri.mjs";
+export type { CreateSessionArgsIface, CreatedSessionIface, ForkSessionOptionsIface, RespondArgs, SendOptionsIface, SessionHandleIface, SessionsApiIface, StreamOptionsIface, TurnHandleIface, TurnResultIface, } from "./sessions.mjs";

package/dist/modules/agent-client/index.mjs

@@ -0,0 +1,86 @@
+export * from "@finalai/agent-protocol/agent-platform";
+import { AcpAuthMode } from "./acp.mjs";
+import {
+  createTextCollector,
+  isUserMessageFor,
+  sessionUpdateOf,
+  textOf,
+  turnEndOf
+} from "./acp-frames.mjs";
+import {
+  createClient
+} from "./client.mjs";
+import {
+  CollectionEventKind,
+  CollectionResyncReason
+} from "./collection-events.mjs";
+import {
+  ConfigOptionCategory,
+  configSelectFor,
+  configSelectsOf
+} from "./config-options.mjs";
+import {
+  TURN_OPEN_SESSION_STATES,
+  isNewerMessageVersion,
+  messageVersionOf
+} from "./conversations.mjs";
+import {
+  AgentClientErrorName,
+  ClientErrorCode,
+  PendingRequestErrorReason,
+  clientError,
+  isClientError,
+  isPendingRequestError,
+  isRealtimeSubscriptionError,
+  isTerminalRealtimeError,
+  isTurnRejectedError,
+  pendingRequestError,
+  realtimeSubscriptionError,
+  turnRejectedError
+} from "./errors.mjs";
+import { defaultStreamTiming } from "./frame-stream.mjs";
+import { SessionLiveEventKind } from "./live-stream.mjs";
+import {
+  createGatewayRealtimeTransport
+} from "./realtime.mjs";
+import {
+  SANDBOX_FILE_URI_SCHEME,
+  createSandboxFileUri,
+  parseSandboxFileUri
+} from "./sandbox-uri.mjs";
+export {
+  AcpAuthMode,
+  AgentClientErrorName,
+  ClientErrorCode,
+  CollectionEventKind,
+  CollectionResyncReason,
+  ConfigOptionCategory,
+  PendingRequestErrorReason,
+  SANDBOX_FILE_URI_SCHEME,
+  SessionLiveEventKind,
+  TURN_OPEN_SESSION_STATES,
+  clientError,
+  configSelectFor,
+  configSelectsOf,
+  createClient,
+  createGatewayRealtimeTransport,
+  createSandboxFileUri,
+  createTextCollector,
+  defaultStreamTiming,
+  isClientError,
+  isNewerMessageVersion,
+  isPendingRequestError,
+  isRealtimeSubscriptionError,
+  isTerminalRealtimeError,
+  isTurnRejectedError,
+  isUserMessageFor,
+  messageVersionOf,
+  parseSandboxFileUri,
+  pendingRequestError,
+  realtimeSubscriptionError,
+  sessionUpdateOf,
+  textOf,
+  turnEndOf,
+  turnRejectedError
+};
+//# sourceMappingURL=index.mjs.map

package/dist/modules/agent-client/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/agent-client/index.ts"],
+  "sourcesContent": ["// `@finalai/agents/client`: the agent platform client SDK.\n// Wire types come from `@finalai/agent-protocol/agent-platform`, re-exported\n// here so consumers need one import.\n\nexport * from '@finalai/agent-protocol/agent-platform';\nexport { AcpAuthMode, type AcpApiIface, type AcpConnectArgsIface } from \"./acp.mjs\";\nexport {\n  createTextCollector,\n  isUserMessageFor,\n  sessionUpdateOf,\n  textOf,\n  turnEndOf,\n  type AcpSessionUpdateIface,\n  type TurnEndIface,\n} from \"./acp-frames.mjs\";\nexport type {\n  ComputerSetupGuidesApiIface,\n  DefinitionRefIface,\n  DefinitionsApiIface,\n  ProvidersApiIface,\n  ScheduleRef,\n  SchedulesApiIface,\n} from \"./build.mjs\";\nexport {\n  createClient,\n  type AgentClientIface,\n  type AgentHandleIface,\n  type AgentsApiIface,\n  type CreateClientOptionsIface,\n  type PendingApiIface,\n  type PeopleApiIface,\n  type RealtimeApiIface,\n} from \"./client.mjs\";\nexport {\n  CollectionEventKind,\n  CollectionResyncReason,\n  type CollectionEvent,\n  type CollectionEventsOptionsIface,\n  type CollectionResyncEventIface,\n} from \"./collection-events.mjs\";\nexport {\n  ConfigOptionCategory,\n  configSelectFor,\n  configSelectsOf,\n  type ConfigSelectChoiceIface,\n  type ConfigSelectIface,\n  type SessionConfigOptionIface,\n} from \"./config-options.mjs\";\nexport type { EnumInput, SignalOptionsIface } from \"./context.mjs\";\nexport {\n  TURN_OPEN_SESSION_STATES,\n  isNewerMessageVersion,\n  messageVersionOf,\n  type MessageVersionIface,\n} from \"./conversations.mjs\";\nexport type {\n  ConversationAgentTurnIface,\n  ConversationEvent,\n  ConversationEventMetaIface,\n  ConversationEventsOptionsIface,\n  ConversationHandleIface,\n  ConversationsApiIface,\n  CreateConversationArgsIface,\n  ListMessagesOptionsIface,\n  OpenedConversationIface,\n  ParticipantCreateInput,\n  SandboxFileContentArgsIface,\n  SandboxFileContentRequestIface,\n  SendMessageOptionsIface,\n  SentMessageIface,\n  UploadAttachmentArgsIface,\n} from \"./conversations.mjs\";\nexport {\n  AgentClientErrorName,\n  ClientErrorCode,\n  PendingRequestErrorReason,\n  clientError,\n  isClientError,\n  isPendingRequestError,\n  isRealtimeSubscriptionError,\n  isTerminalRealtimeError,\n  isTurnRejectedError,\n  pendingRequestError,\n  realtimeSubscriptionError,\n  turnRejectedError,\n  type AgentClientError,\n  type ClientErrorIface,\n  type PendingRequestErrorIface,\n  type RealtimeSubscriptionErrorIface,\n  type TurnRejectedErrorIface,\n} from \"./errors.mjs\";\nexport { defaultStreamTiming, type StreamTimingIface } from \"./frame-stream.mjs\";\nexport type { AgentClientAuth, FetchIface, HeadersOption } from \"./http.mjs\";\nexport { SessionLiveEventKind, type SessionLiveEvent } from \"./live-stream.mjs\";\nexport {\n  createGatewayRealtimeTransport,\n  type GatewayConnect,\n  type GatewayConnectionIface,\n  type GatewayRealtimeTransportOptionsIface,\n  type RealtimeSubscribeOptionsIface,\n  type RealtimeTransportFrameIface,\n  type RealtimeTransportIface,\n} from \"./realtime.mjs\";\nexport {\n  SANDBOX_FILE_URI_SCHEME,\n  createSandboxFileUri,\n  parseSandboxFileUri,\n  type SandboxFileTargetIface,\n} from \"./sandbox-uri.mjs\";\nexport type {\n  CreateSessionArgsIface,\n  CreatedSessionIface,\n  ForkSessionOptionsIface,\n  RespondArgs,\n  SendOptionsIface,\n  SessionHandleIface,\n  SessionsApiIface,\n  StreamOptionsIface,\n  TurnHandleIface,\n  TurnResultIface,\n} from \"./sessions.mjs\";\n"],
+  "mappings": "AAIA,cAAc;AACd,SAAS,mBAA+D;AACxE;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AASP;AAAA,EACE;AAAA,OAQK;AACP;AAAA,EACE;AAAA,EACA;AAAA,OAIK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AAkBP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAMK;AACP,SAAS,2BAAmD;AAE5D,SAAS,4BAAmD;AAC5D;AAAA,EACE;AAAA,OAOK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAEK;",
+  "names": []
+}

package/dist/modules/agent-client/live-stream.d.mts

@@ -0,0 +1,18 @@
+import { type AcpLiveFrameEventIface, type AcpLiveResetEventIface } from '@finalai/agent-protocol/agent-platform';
+import type { ClientContextIface } from "./context.mjs";
+export declare enum SessionLiveEventKind {
+    Frame = "frame",
+    Reset = "reset"
+}
+export type SessionLiveEvent = {
+    kind: SessionLiveEventKind.Frame;
+    frame: AcpLiveFrameEventIface;
+} | {
+    kind: SessionLiveEventKind.Reset;
+    reset: AcpLiveResetEventIface;
+};
+export declare const streamSessionLiveEvents: (args: {
+    context: ClientContextIface;
+    sessionId: string;
+    signal?: AbortSignal;
+}) => AsyncIterableIterator<SessionLiveEvent>;

package/dist/modules/agent-client/live-stream.mjs

@@ -0,0 +1,94 @@
+import {
+  AgentRealtimeFrameType,
+  AgentRealtimeKind,
+  acpLiveFrameEventSchema,
+  acpLiveResetEventSchema,
+  agentRealtimeFrameSchema,
+  agentRealtimeTopics
+} from "@finalai/agent-protocol/agent-platform";
+import { createAsyncQueue, failOnAbort } from "./async-queue.mjs";
+import { isTerminalRealtimeError, realtimeSubscriptionError } from "./errors.mjs";
+var SessionLiveEventKind = /* @__PURE__ */ ((SessionLiveEventKind2) => {
+  SessionLiveEventKind2["Frame"] = "frame";
+  SessionLiveEventKind2["Reset"] = "reset";
+  return SessionLiveEventKind2;
+})(SessionLiveEventKind || {});
+const streamSessionLiveEvents = (args) => {
+  const topic = agentRealtimeTopics.session(args.sessionId);
+  let unsubscribe = null;
+  let detachAbort = () => void 0;
+  let detachClose = () => void 0;
+  let bufferedBytes = 0;
+  let bufferedFrames = 0;
+  const queue = createAsyncQueue(() => {
+    unsubscribe?.();
+    detachAbort();
+    detachClose();
+  });
+  const push = (event) => {
+    const bytes = JSON.stringify(event).length * 3;
+    if (bufferedFrames >= 256 || bufferedBytes + bytes > 8 * 1024 * 1024) {
+      queue.fail(new Error("Live frame capacity exceeded; reconnect and replay durable frames"));
+      return;
+    }
+    bufferedBytes += bytes;
+    bufferedFrames += 1;
+    queue.push({ event, bytes });
+  };
+  const onFrame = (raw) => {
+    const frame = agentRealtimeFrameSchema.safeParse(raw);
+    if (!frame.success || queue.closed()) return;
+    if (frame.data.type === AgentRealtimeFrameType.Error && isTerminalRealtimeError(frame.data)) {
+      queue.fail(
+        realtimeSubscriptionError({
+          topic: frame.data.topic ?? topic,
+          code: frame.data.code ?? "unknown",
+          message: frame.data.message ?? "Realtime subscription was refused"
+        })
+      );
+      return;
+    }
+    if (frame.data.type === AgentRealtimeFrameType.Subscribed || frame.data.type === AgentRealtimeFrameType.ResyncRequired || frame.data.type === AgentRealtimeFrameType.Error) {
+      push({
+        kind: "reset" /* Reset */,
+        reset: { streamId: null, throughSeq: null, reason: "reconnect" }
+      });
+      return;
+    }
+    if (frame.data.type !== AgentRealtimeFrameType.Event) return;
+    if (frame.data.kind === AgentRealtimeKind.AcpLiveFrame) {
+      const payload = acpLiveFrameEventSchema.safeParse(frame.data.payload);
+      if (payload.success) push({ kind: "frame" /* Frame */, frame: payload.data });
+    } else if (frame.data.kind === AgentRealtimeKind.AcpLiveReset) {
+      const payload = acpLiveResetEventSchema.safeParse(frame.data.payload);
+      if (payload.success) push({ kind: "reset" /* Reset */, reset: payload.data });
+    }
+  };
+  detachAbort = failOnAbort(queue, args.signal);
+  detachClose = failOnAbort(queue, args.context.closeSignal);
+  if (!queue.closed()) {
+    const stop = args.context.realtime().subscribe(topic, onFrame);
+    if (queue.closed()) stop();
+    else unsubscribe = stop;
+  }
+  const iterator = {
+    next: async () => {
+      const value = await queue.iterator.next();
+      if (value.done === true) return value;
+      bufferedBytes -= value.value.bytes;
+      bufferedFrames -= 1;
+      return { done: false, value: value.value.event };
+    },
+    return: async () => {
+      await queue.iterator.return?.();
+      return { done: true, value: void 0 };
+    },
+    [Symbol.asyncIterator]: () => iterator
+  };
+  return iterator;
+};
+export {
+  SessionLiveEventKind,
+  streamSessionLiveEvents
+};
+//# sourceMappingURL=live-stream.mjs.map

package/dist/modules/agent-client/live-stream.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/agent-client/live-stream.ts"],
+  "sourcesContent": ["import {\n  AgentRealtimeFrameType,\n  AgentRealtimeKind,\n  acpLiveFrameEventSchema,\n  acpLiveResetEventSchema,\n  agentRealtimeFrameSchema,\n  agentRealtimeTopics,\n  type AcpLiveFrameEventIface,\n  type AcpLiveResetEventIface,\n} from '@finalai/agent-protocol/agent-platform';\nimport { createAsyncQueue, failOnAbort } from \"./async-queue.mjs\";\nimport type { ClientContextIface } from \"./context.mjs\";\nimport { isTerminalRealtimeError, realtimeSubscriptionError } from \"./errors.mjs\";\nimport type { RealtimeTransportFrameIface } from \"./realtime.mjs\";\n\nexport enum SessionLiveEventKind {\n  Frame = 'frame',\n  Reset = 'reset',\n}\n\nexport type SessionLiveEvent =\n  | { kind: SessionLiveEventKind.Frame; frame: AcpLiveFrameEventIface }\n  | { kind: SessionLiveEventKind.Reset; reset: AcpLiveResetEventIface };\n\n// Provisional rendering only. Replay positions and completed operations come\n// from the ordinary durable stream, never from this iterator's seq values.\nexport const streamSessionLiveEvents = (args: {\n  context: ClientContextIface;\n  sessionId: string;\n  signal?: AbortSignal;\n}): AsyncIterableIterator<SessionLiveEvent> => {\n  const topic = agentRealtimeTopics.session(args.sessionId);\n  let unsubscribe: (() => void) | null = null;\n  let detachAbort: () => void = () => undefined;\n  let detachClose: () => void = () => undefined;\n  let bufferedBytes = 0;\n  let bufferedFrames = 0;\n  const queue = createAsyncQueue<{ event: SessionLiveEvent; bytes: number }>(() => {\n    unsubscribe?.();\n    detachAbort();\n    detachClose();\n  });\n  const push = (event: SessionLiveEvent): void => {\n    const bytes = JSON.stringify(event).length * 3;\n    if (bufferedFrames >= 256 || bufferedBytes + bytes > 8 * 1024 * 1024) {\n      queue.fail(new Error('Live frame capacity exceeded; reconnect and replay durable frames'));\n      return;\n    }\n    bufferedBytes += bytes;\n    bufferedFrames += 1;\n    queue.push({ event, bytes });\n  };\n  const onFrame = (raw: RealtimeTransportFrameIface): void => {\n    const frame = agentRealtimeFrameSchema.safeParse(raw);\n    if (!frame.success || queue.closed()) return;\n    if (frame.data.type === AgentRealtimeFrameType.Error && isTerminalRealtimeError(frame.data)) {\n      queue.fail(\n        realtimeSubscriptionError({\n          topic: frame.data.topic ?? topic,\n          code: frame.data.code ?? 'unknown',\n          message: frame.data.message ?? 'Realtime subscription was refused',\n        }),\n      );\n      return;\n    }\n    if (\n      frame.data.type === AgentRealtimeFrameType.Subscribed ||\n      frame.data.type === AgentRealtimeFrameType.ResyncRequired ||\n      frame.data.type === AgentRealtimeFrameType.Error\n    ) {\n      push({\n        kind: SessionLiveEventKind.Reset,\n        reset: { streamId: null, throughSeq: null, reason: 'reconnect' },\n      });\n      return;\n    }\n    if (frame.data.type !== AgentRealtimeFrameType.Event) return;\n    if (frame.data.kind === AgentRealtimeKind.AcpLiveFrame) {\n      const payload = acpLiveFrameEventSchema.safeParse(frame.data.payload);\n      if (payload.success) push({ kind: SessionLiveEventKind.Frame, frame: payload.data });\n    } else if (frame.data.kind === AgentRealtimeKind.AcpLiveReset) {\n      const payload = acpLiveResetEventSchema.safeParse(frame.data.payload);\n      if (payload.success) push({ kind: SessionLiveEventKind.Reset, reset: payload.data });\n    }\n  };\n  detachAbort = failOnAbort(queue, args.signal);\n  detachClose = failOnAbort(queue, args.context.closeSignal);\n  if (!queue.closed()) {\n    const stop = args.context.realtime().subscribe(topic, onFrame);\n    if (queue.closed()) stop();\n    else unsubscribe = stop;\n  }\n  const iterator: AsyncIterableIterator<SessionLiveEvent> = {\n    next: async () => {\n      const value = await queue.iterator.next();\n      if (value.done === true) return value;\n      bufferedBytes -= value.value.bytes;\n      bufferedFrames -= 1;\n      return { done: false, value: value.value.event };\n    },\n    return: async () => {\n      await queue.iterator.return?.();\n      return { done: true, value: undefined };\n    },\n    [Symbol.asyncIterator]: () => iterator,\n  };\n  return iterator;\n};\n"],
+  "mappings": "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",
+  "names": ["SessionLiveEventKind"]
+}

package/dist/modules/agent-client/realtime.d.mts

@@ -0,0 +1,72 @@
+import type { RealtimeSessionResponseIface } from '@finalai/agent-protocol/agent-platform';
+/**
+ * One frame a topic subscriber receives: a realtime event envelope
+ * (`type: 'event'`), `subscribed` (after every (re)subscription), `resync_required`
+ * or `error`. The SDK parses it with the contract's `agentRealtimeFrameSchema`,
+ * so console clients can forward their gateway frames unchanged.
+ */
+export interface RealtimeTransportFrameIface {
+    type: string;
+    topic?: string;
+    cursor?: string | null;
+    eventKey?: string;
+    kind?: string;
+    payload?: unknown;
+    createdAt?: string;
+    reason?: string;
+    code?: string;
+    message?: string;
+    retryable?: boolean;
+}
+export interface RealtimeSubscribeOptionsIface {
+    /** Gateway cursor to resume after; omitted means live only. */
+    afterCursor?: string;
+}
+export interface RealtimeTransportIface {
+    subscribe: (topic: string, onFrame: (frame: RealtimeTransportFrameIface) => void, options?: RealtimeSubscribeOptionsIface) => () => void;
+}
+interface GatewayMessageIface {
+    data: unknown;
+    cursor: string | null;
+}
+interface GatewayTopicIface {
+    subscribe: (handler: (message: GatewayMessageIface) => void, options?: {
+        afterCursor?: string;
+        onSubscribed?: () => void;
+        onResyncRequired?: () => void;
+        onError?: (error: {
+            code: string;
+            message: string;
+            retryable: boolean;
+        }) => void;
+    }) => () => void;
+}
+export interface GatewayConnectionIface {
+    realtime: (topic: string) => GatewayTopicIface;
+    close: (code?: number, reason?: string) => void;
+}
+export interface GatewayConnectOptionsIface {
+    url: string;
+    auth: () => Promise<string>;
+    reconnect: boolean;
+}
+export type GatewayConnect = (options: GatewayConnectOptionsIface) => Promise<GatewayConnectionIface>;
+export interface GatewayRealtimeTransportOptionsIface {
+    /** Mints a gateway token (`POST /api/v1/realtime/session`). */
+    createSession: () => Promise<RealtimeSessionResponseIface>;
+    /** Seam for tests; defaults to `@finalai/websockets`'s `client.connect`. */
+    connect?: GatewayConnect;
+    /** Refresh the gateway token this long before it expires. */
+    refreshMarginMs?: number;
+    /** First retry delay after a failed connect or a retryable subscription error; doubles per attempt. */
+    retryBaseMs?: number;
+    retryMaxMs?: number;
+    /** Close the gateway connection once no topic has been subscribed for this long. */
+    idleCloseMs?: number;
+}
+/** The default transport; `close` tears down its connection and cancels every retry. */
+export interface GatewayRealtimeTransportIface extends RealtimeTransportIface {
+    close: () => void;
+}
+export declare const createGatewayRealtimeTransport: (options: GatewayRealtimeTransportOptionsIface) => GatewayRealtimeTransportIface;
+export {};

package/dist/modules/agent-client/realtime.mjs

@@ -0,0 +1,186 @@
+import { client as gatewayClient } from "@finalai/websockets";
+import * as z from "zod";
+const DEFAULT_REFRESH_MARGIN_MS = 6e4;
+const DEFAULT_RETRY_BASE_MS = 500;
+const DEFAULT_RETRY_MAX_MS = 15e3;
+const DEFAULT_IDLE_CLOSE_MS = 1e4;
+const eventDataSchema = z.object({
+  type: z.string(),
+  topic: z.string().optional(),
+  eventKey: z.string().optional(),
+  kind: z.string().optional(),
+  payload: z.unknown(),
+  createdAt: z.string().optional(),
+  reason: z.string().optional()
+});
+const errorMessageSchema = z.object({ message: z.string() });
+const createGatewayRealtimeTransport = (options) => {
+  const connect = options.connect ?? gatewayClient.connect;
+  const refreshMarginMs = options.refreshMarginMs ?? DEFAULT_REFRESH_MARGIN_MS;
+  let session = null;
+  let connection = null;
+  const topics = /* @__PURE__ */ new Map();
+  const idleCloseMs = options.idleCloseMs ?? DEFAULT_IDLE_CLOSE_MS;
+  let idleTimer = null;
+  let transportClosed = false;
+  const closeConnection = (reason) => {
+    const pending = connection;
+    connection = null;
+    void pending?.then(
+      (live) => live.close(1e3, reason),
+      () => {
+      }
+    );
+  };
+  const cancelIdleClose = () => {
+    if (idleTimer != null) clearTimeout(idleTimer);
+    idleTimer = null;
+  };
+  const scheduleIdleClose = () => {
+    if (transportClosed || topics.size > 0 || idleTimer != null || connection == null) return;
+    idleTimer = setTimeout(() => {
+      idleTimer = null;
+      if (topics.size === 0) closeConnection("agent realtime idle");
+    }, idleCloseMs);
+    idleTimer.unref?.();
+  };
+  const freshSession = async () => {
+    if (session != null && Date.parse(session.expiresAt) - Date.now() > refreshMarginMs) {
+      return session;
+    }
+    session = await options.createSession();
+    return session;
+  };
+  const open = () => {
+    if (connection != null) return connection;
+    const pending = freshSession().then(
+      (initial) => connect({
+        url: initial.url,
+        auth: async () => (await freshSession()).token,
+        reconnect: true
+      })
+    );
+    connection = pending;
+    pending.catch(() => {
+      if (connection === pending) connection = null;
+    });
+    return pending;
+  };
+  const emit = (entry, frame) => {
+    for (const listener of [...entry.listeners]) listener(frame);
+  };
+  const retryBaseMs = options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;
+  const retryMaxMs = options.retryMaxMs ?? DEFAULT_RETRY_MAX_MS;
+  const detach = (entry) => {
+    entry.ready = false;
+    entry.unsubscribe?.();
+    entry.unsubscribe = null;
+  };
+  const close = (entry) => {
+    entry.closed = true;
+    if (entry.retryTimer != null) clearTimeout(entry.retryTimer);
+    entry.retryTimer = null;
+    detach(entry);
+    if (topics.get(entry.topic) === entry) topics.delete(entry.topic);
+    scheduleIdleClose();
+  };
+  const scheduleRetry = (entry) => {
+    if (entry.closed || entry.retryTimer != null) return;
+    const delay = Math.min(retryMaxMs, retryBaseMs * 2 ** entry.attempts);
+    entry.attempts += 1;
+    entry.retryTimer = setTimeout(() => {
+      entry.retryTimer = null;
+      void attach(entry);
+    }, delay);
+  };
+  const attach = async (entry) => {
+    const { topic } = entry;
+    try {
+      const live = await open();
+      if (entry.closed) return;
+      detach(entry);
+      entry.unsubscribe = live.realtime(topic).subscribe(
+        (message) => {
+          const data = eventDataSchema.safeParse(message.data);
+          if (!data.success) return;
+          if (message.cursor != null) entry.cursor = message.cursor;
+          emit(entry, { ...data.data, cursor: message.cursor });
+        },
+        {
+          afterCursor: entry.cursor,
+          onSubscribed: () => {
+            entry.attempts = 0;
+            entry.ready = true;
+            emit(entry, { type: "subscribed", topic });
+          },
+          onResyncRequired: () => {
+            entry.cursor = void 0;
+            emit(entry, { type: "resync_required", topic });
+          },
+          onError: (error) => {
+            emit(entry, { type: "error", topic, ...error });
+            if (error.retryable) {
+              detach(entry);
+              scheduleRetry(entry);
+            } else {
+              close(entry);
+            }
+          }
+        }
+      );
+    } catch (cause) {
+      if (entry.closed) return;
+      emit(entry, {
+        type: "error",
+        topic,
+        code: "connect_failed",
+        message: errorMessageSchema.safeParse(cause).data?.message ?? "realtime connection failed",
+        retryable: true
+      });
+      scheduleRetry(entry);
+    }
+  };
+  const subscribe = (topic, onFrame, subscribeOptions) => {
+    if (transportClosed) return () => {
+    };
+    cancelIdleClose();
+    let entry = topics.get(topic);
+    if (entry == null) {
+      entry = {
+        topic,
+        listeners: /* @__PURE__ */ new Set(),
+        unsubscribe: null,
+        closed: false,
+        cursor: subscribeOptions?.afterCursor,
+        attempts: 0,
+        retryTimer: null,
+        ready: false
+      };
+      topics.set(topic, entry);
+      void attach(entry);
+    }
+    const current = entry;
+    current.listeners.add(onFrame);
+    if (current.ready) {
+      queueMicrotask(() => {
+        if (current.ready && current.listeners.has(onFrame)) onFrame({ type: "subscribed", topic });
+      });
+    }
+    return () => {
+      current.listeners.delete(onFrame);
+      if (current.listeners.size === 0) close(current);
+    };
+  };
+  const closeTransport = () => {
+    if (transportClosed) return;
+    transportClosed = true;
+    cancelIdleClose();
+    for (const entry of [...topics.values()]) close(entry);
+    closeConnection("agent client closed");
+  };
+  return { subscribe, close: closeTransport };
+};
+export {
+  createGatewayRealtimeTransport
+};
+//# sourceMappingURL=realtime.mjs.map

package/dist/modules/agent-client/realtime.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/agent-client/realtime.ts"],
+  "sourcesContent": ["import type { RealtimeSessionResponseIface } from '@finalai/agent-protocol/agent-platform';\nimport { client as gatewayClient } from '@finalai/websockets';\nimport * as z from 'zod';\n\n// Streams ride websocket-gateway topic subscriptions. console-web and\n// console-mobile pass their existing realtime clients as a\n// RealtimeTransportIface; everyone else gets the default gateway transport,\n// which mints a gateway token at `POST /api/v1/realtime/session`.\n\n/**\n * One frame a topic subscriber receives: a realtime event envelope\n * (`type: 'event'`), `subscribed` (after every (re)subscription), `resync_required`\n * or `error`. The SDK parses it with the contract's `agentRealtimeFrameSchema`,\n * so console clients can forward their gateway frames unchanged.\n */\nexport interface RealtimeTransportFrameIface {\n  type: string;\n  topic?: string;\n  cursor?: string | null;\n  eventKey?: string;\n  kind?: string;\n  payload?: unknown;\n  createdAt?: string;\n  reason?: string;\n  code?: string;\n  message?: string;\n  retryable?: boolean;\n}\n\nexport interface RealtimeSubscribeOptionsIface {\n  /** Gateway cursor to resume after; omitted means live only. */\n  afterCursor?: string;\n}\n\nexport interface RealtimeTransportIface {\n  subscribe: (\n    topic: string,\n    onFrame: (frame: RealtimeTransportFrameIface) => void,\n    options?: RealtimeSubscribeOptionsIface,\n  ) => () => void;\n}\n\ninterface GatewayMessageIface {\n  data: unknown;\n  cursor: string | null;\n}\n\ninterface GatewayTopicIface {\n  subscribe: (\n    handler: (message: GatewayMessageIface) => void,\n    options?: {\n      afterCursor?: string;\n      onSubscribed?: () => void;\n      onResyncRequired?: () => void;\n      onError?: (error: { code: string; message: string; retryable: boolean }) => void;\n    },\n  ) => () => void;\n}\n\nexport interface GatewayConnectionIface {\n  realtime: (topic: string) => GatewayTopicIface;\n  close: (code?: number, reason?: string) => void;\n}\n\nexport interface GatewayConnectOptionsIface {\n  url: string;\n  auth: () => Promise<string>;\n  reconnect: boolean;\n}\n\nexport type GatewayConnect = (\n  options: GatewayConnectOptionsIface,\n) => Promise<GatewayConnectionIface>;\n\nexport interface GatewayRealtimeTransportOptionsIface {\n  /** Mints a gateway token (`POST /api/v1/realtime/session`). */\n  createSession: () => Promise<RealtimeSessionResponseIface>;\n  /** Seam for tests; defaults to `@finalai/websockets`'s `client.connect`. */\n  connect?: GatewayConnect;\n  /** Refresh the gateway token this long before it expires. */\n  refreshMarginMs?: number;\n  /** First retry delay after a failed connect or a retryable subscription error; doubles per attempt. */\n  retryBaseMs?: number;\n  retryMaxMs?: number;\n  /** Close the gateway connection once no topic has been subscribed for this long. */\n  idleCloseMs?: number;\n}\n\n/** The default transport; `close` tears down its connection and cancels every retry. */\nexport interface GatewayRealtimeTransportIface extends RealtimeTransportIface {\n  close: () => void;\n}\n\nconst DEFAULT_REFRESH_MARGIN_MS = 60_000;\nconst DEFAULT_RETRY_BASE_MS = 500;\nconst DEFAULT_RETRY_MAX_MS = 15_000;\n// Long enough that a view swapping one stream for another reuses the socket.\nconst DEFAULT_IDLE_CLOSE_MS = 10_000;\n\nconst eventDataSchema = z.object({\n  type: z.string(),\n  topic: z.string().optional(),\n  eventKey: z.string().optional(),\n  kind: z.string().optional(),\n  payload: z.unknown(),\n  createdAt: z.string().optional(),\n  reason: z.string().optional(),\n});\n\nconst errorMessageSchema = z.object({ message: z.string() });\n\ninterface TopicEntryIface {\n  topic: string;\n  listeners: Set<(frame: RealtimeTransportFrameIface) => void>;\n  unsubscribe: (() => void) | null;\n  /** The last listener left, or the gateway refused the topic for good. */\n  closed: boolean;\n  /** Newest retained cursor delivered, so a retry resumes after it. */\n  cursor: string | undefined;\n  attempts: number;\n  retryTimer: ReturnType<typeof setTimeout> | null;\n  /** The gateway acknowledged the current subscription; late listeners get their own `subscribed`. */\n  ready: boolean;\n}\n\nexport const createGatewayRealtimeTransport = (\n  options: GatewayRealtimeTransportOptionsIface,\n): GatewayRealtimeTransportIface => {\n  const connect = options.connect ?? gatewayClient.connect;\n  const refreshMarginMs = options.refreshMarginMs ?? DEFAULT_REFRESH_MARGIN_MS;\n  let session: RealtimeSessionResponseIface | null = null;\n  let connection: Promise<GatewayConnectionIface> | null = null;\n  const topics = new Map<string, TopicEntryIface>();\n  const idleCloseMs = options.idleCloseMs ?? DEFAULT_IDLE_CLOSE_MS;\n  let idleTimer: ReturnType<typeof setTimeout> | null = null;\n  let transportClosed = false;\n\n  const closeConnection = (reason: string): void => {\n    const pending = connection;\n    connection = null;\n    void pending?.then(\n      (live) => live.close(1000, reason),\n      () => {},\n    );\n  };\n\n  const cancelIdleClose = (): void => {\n    if (idleTimer != null) clearTimeout(idleTimer);\n    idleTimer = null;\n  };\n\n  // With no topics left the socket only keeps the process (and a server slot) busy;\n  // the next subscribe reconnects.\n  const scheduleIdleClose = (): void => {\n    if (transportClosed || topics.size > 0 || idleTimer != null || connection == null) return;\n    idleTimer = setTimeout(() => {\n      idleTimer = null;\n      if (topics.size === 0) closeConnection('agent realtime idle');\n    }, idleCloseMs);\n    // An idle socket waiting to close must not keep a Node process alive.\n    idleTimer.unref?.();\n  };\n\n  const freshSession = async (): Promise<RealtimeSessionResponseIface> => {\n    if (session != null && Date.parse(session.expiresAt) - Date.now() > refreshMarginMs) {\n      return session;\n    }\n    session = await options.createSession();\n    return session;\n  };\n\n  const open = (): Promise<GatewayConnectionIface> => {\n    if (connection != null) return connection;\n    const pending = freshSession().then((initial) =>\n      connect({\n        url: initial.url,\n        auth: async () => (await freshSession()).token,\n        reconnect: true,\n      }),\n    );\n    connection = pending;\n    pending.catch(() => {\n      if (connection === pending) connection = null;\n    });\n    return pending;\n  };\n\n  const emit = (entry: TopicEntryIface, frame: RealtimeTransportFrameIface): void => {\n    for (const listener of [...entry.listeners]) listener(frame);\n  };\n\n  const retryBaseMs = options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;\n  const retryMaxMs = options.retryMaxMs ?? DEFAULT_RETRY_MAX_MS;\n\n  const detach = (entry: TopicEntryIface): void => {\n    entry.ready = false;\n    entry.unsubscribe?.();\n    entry.unsubscribe = null;\n  };\n\n  const close = (entry: TopicEntryIface): void => {\n    entry.closed = true;\n    if (entry.retryTimer != null) clearTimeout(entry.retryTimer);\n    entry.retryTimer = null;\n    detach(entry);\n    if (topics.get(entry.topic) === entry) topics.delete(entry.topic);\n    scheduleIdleClose();\n  };\n\n  // Retries run only while the entry has listeners; the last unsubscribe cancels them.\n  const scheduleRetry = (entry: TopicEntryIface): void => {\n    if (entry.closed || entry.retryTimer != null) return;\n    const delay = Math.min(retryMaxMs, retryBaseMs * 2 ** entry.attempts);\n    entry.attempts += 1;\n    entry.retryTimer = setTimeout(() => {\n      entry.retryTimer = null;\n      void attach(entry);\n    }, delay);\n  };\n\n  const attach = async (entry: TopicEntryIface): Promise<void> => {\n    const { topic } = entry;\n    try {\n      const live = await open();\n      if (entry.closed) return;\n      detach(entry);\n      entry.unsubscribe = live.realtime(topic).subscribe(\n        (message) => {\n          const data = eventDataSchema.safeParse(message.data);\n          if (!data.success) return;\n          if (message.cursor != null) entry.cursor = message.cursor;\n          // The gateway's cursor wins: non-retained messages carry null.\n          emit(entry, { ...data.data, cursor: message.cursor });\n        },\n        {\n          afterCursor: entry.cursor,\n          onSubscribed: () => {\n            entry.attempts = 0;\n            entry.ready = true;\n            emit(entry, { type: 'subscribed', topic });\n          },\n          onResyncRequired: () => {\n            entry.cursor = undefined;\n            emit(entry, { type: 'resync_required', topic });\n          },\n          onError: (error) => {\n            emit(entry, { type: 'error', topic, ...error });\n            if (error.retryable) {\n              detach(entry);\n              scheduleRetry(entry);\n            } else {\n              // Refused for good: a later subscribe to this topic starts a fresh attempt.\n              close(entry);\n            }\n          },\n        },\n      );\n    } catch (cause) {\n      if (entry.closed) return;\n      // `open` dropped the failed connection, so the retry reconnects (and re-mints the token).\n      emit(entry, {\n        type: 'error',\n        topic,\n        code: 'connect_failed',\n        message: errorMessageSchema.safeParse(cause).data?.message ?? 'realtime connection failed',\n        retryable: true,\n      });\n      scheduleRetry(entry);\n    }\n  };\n\n  const subscribe: RealtimeTransportIface['subscribe'] = (topic, onFrame, subscribeOptions) => {\n    if (transportClosed) return () => {};\n    cancelIdleClose();\n    let entry = topics.get(topic);\n    if (entry == null) {\n      entry = {\n        topic,\n        listeners: new Set(),\n        unsubscribe: null,\n        closed: false,\n        cursor: subscribeOptions?.afterCursor,\n        attempts: 0,\n        retryTimer: null,\n        ready: false,\n      };\n      topics.set(topic, entry);\n      void attach(entry);\n    }\n    const current = entry;\n    current.listeners.add(onFrame);\n    if (current.ready) {\n      // Streams start recovery (and non-following streams finish) on `subscribed`, so a\n      // listener joining a live topic gets its own, after `subscribe` has returned.\n      queueMicrotask(() => {\n        if (current.ready && current.listeners.has(onFrame)) onFrame({ type: 'subscribed', topic });\n      });\n    }\n    return () => {\n      current.listeners.delete(onFrame);\n      if (current.listeners.size === 0) close(current);\n    };\n  };\n\n  const closeTransport = (): void => {\n    if (transportClosed) return;\n    transportClosed = true;\n    cancelIdleClose();\n    for (const entry of [...topics.values()]) close(entry);\n    closeConnection('agent client closed');\n  };\n\n  return { subscribe, close: closeTransport };\n};\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/agent-client/sandbox-uri.d.mts

@@ -0,0 +1,19 @@
+type ResultIface<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+export interface SandboxFileTargetIface {
+    conversationId: string;
+    bindingId: string;
+}
+export interface SandboxFileUriIface {
+    target: SandboxFileTargetIface;
+    path: string;
+}
+export declare const SANDBOX_FILE_URI_SCHEME = "final-sandbox:";
+export declare const createSandboxFileUri: (location: SandboxFileUriIface) => string;
+export declare const parseSandboxFileUri: (value: string) => ResultIface<SandboxFileUriIface>;
+export {};

package/dist/modules/agent-client/sandbox-uri.mjs

@@ -0,0 +1,43 @@
+import { base58Decode } from "@finalai/agent-protocol/base58";
+const err = (error) => ({ ok: false, error });
+const ok = (data) => ({ ok: true, data });
+const SANDBOX_FILE_URI_SCHEME = "final-sandbox:";
+const wireIdValid = (prefix, value) => {
+  if (!value.startsWith(prefix + "_")) return false;
+  const body = value.slice(prefix.length + 1);
+  if (body.length === 0 || body.length > 22) return false;
+  try {
+    return base58Decode(body).length === 16;
+  } catch {
+    return false;
+  }
+};
+const targetValid = (target) => wireIdValid("conv", target.conversationId) && wireIdValid("sbnd", target.bindingId);
+const pathValid = (path) => path.length > 0 && path.length <= 4096 && !path.includes("\0");
+const createSandboxFileUri = (location) => {
+  if (!targetValid(location.target) || !pathValid(location.path))
+    throw new Error("Invalid sandbox file location");
+  const query = new URLSearchParams({ path: location.path });
+  return `final-sandbox://${location.target.conversationId}/${location.target.bindingId}?${query}`;
+};
+const parseSandboxFileUri = (value) => {
+  try {
+    const uri = new URL(value);
+    const bindingId = uri.pathname.slice(1);
+    const target = { conversationId: uri.hostname, bindingId };
+    const paths = uri.searchParams.getAll("path");
+    if (uri.protocol !== SANDBOX_FILE_URI_SCHEME || uri.username.length > 0 || uri.password.length > 0 || uri.port.length > 0 || uri.hash.length > 0 || !targetValid(target) || paths.length !== 1 || [...uri.searchParams.keys()].some((key) => key !== "path"))
+      return err("Invalid sandbox file URI");
+    const path = paths[0];
+    if (path == null || !pathValid(path)) return err("Invalid sandbox file path");
+    return ok({ target, path });
+  } catch {
+    return err("Invalid sandbox file URI");
+  }
+};
+export {
+  SANDBOX_FILE_URI_SCHEME,
+  createSandboxFileUri,
+  parseSandboxFileUri
+};
+//# sourceMappingURL=sandbox-uri.mjs.map

package/dist/modules/agent-client/sandbox-uri.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/agent-client/sandbox-uri.ts"],
+  "sourcesContent": ["import { base58Decode } from '@finalai/agent-protocol/base58';\ntype ResultIface<T> = { ok: true; data: T } | { ok: false; error: string };\nconst err = (error: string): { ok: false; error: string } => ({ ok: false, error });\nconst ok = <T>(data: T): { ok: true; data: T } => ({ ok: true, data });\n\nexport interface SandboxFileTargetIface {\n  conversationId: string;\n  bindingId: string;\n}\n\nexport interface SandboxFileUriIface {\n  target: SandboxFileTargetIface;\n  path: string;\n}\n\nexport const SANDBOX_FILE_URI_SCHEME = 'final-sandbox:';\n\nconst wireIdValid = (prefix: string, value: string): boolean => {\n  if (!value.startsWith(prefix + '_')) return false;\n  const body = value.slice(prefix.length + 1);\n  if (body.length === 0 || body.length > 22) return false;\n  try {\n    return base58Decode(body).length === 16;\n  } catch {\n    return false;\n  }\n};\n\nconst targetValid = (target: SandboxFileTargetIface): boolean =>\n  wireIdValid('conv', target.conversationId) && wireIdValid('sbnd', target.bindingId);\n\nconst pathValid = (path: string): boolean =>\n  path.length > 0 && path.length <= 4096 && !path.includes('\\0');\n\nexport const createSandboxFileUri = (location: SandboxFileUriIface): string => {\n  if (!targetValid(location.target) || !pathValid(location.path))\n    throw new Error('Invalid sandbox file location');\n  const query = new URLSearchParams({ path: location.path });\n  return `final-sandbox://${location.target.conversationId}/${location.target.bindingId}?${query}`;\n};\n\nexport const parseSandboxFileUri = (value: string): ResultIface<SandboxFileUriIface> => {\n  try {\n    const uri = new URL(value);\n    const bindingId = uri.pathname.slice(1);\n    const target = { conversationId: uri.hostname, bindingId };\n    const paths = uri.searchParams.getAll('path');\n    if (\n      uri.protocol !== SANDBOX_FILE_URI_SCHEME ||\n      uri.username.length > 0 ||\n      uri.password.length > 0 ||\n      uri.port.length > 0 ||\n      uri.hash.length > 0 ||\n      !targetValid(target) ||\n      paths.length !== 1 ||\n      [...uri.searchParams.keys()].some((key) => key !== 'path')\n    )\n      return err('Invalid sandbox file URI');\n    const path = paths[0];\n    if (path == null || !pathValid(path)) return err('Invalid sandbox file path');\n    return ok({ target, path });\n  } catch {\n    return err('Invalid sandbox file URI');\n  }\n};\n"],
+  "mappings": "AAAA,SAAS,oBAAoB;AAE7B,MAAM,MAAM,CAAC,WAAiD,EAAE,IAAI,OAAO,MAAM;AACjF,MAAM,KAAK,CAAI,UAAoC,EAAE,IAAI,MAAM,KAAK;AAY7D,MAAM,0BAA0B;AAEvC,MAAM,cAAc,CAAC,QAAgB,UAA2B;AAC9D,MAAI,CAAC,MAAM,WAAW,SAAS,GAAG,EAAG,QAAO;AAC5C,QAAM,OAAO,MAAM,MAAM,OAAO,SAAS,CAAC;AAC1C,MAAI,KAAK,WAAW,KAAK,KAAK,SAAS,GAAI,QAAO;AAClD,MAAI;AACF,WAAO,aAAa,IAAI,EAAE,WAAW;AAAA,EACvC,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,MAAM,cAAc,CAAC,WACnB,YAAY,QAAQ,OAAO,cAAc,KAAK,YAAY,QAAQ,OAAO,SAAS;AAEpF,MAAM,YAAY,CAAC,SACjB,KAAK,SAAS,KAAK,KAAK,UAAU,QAAQ,CAAC,KAAK,SAAS,IAAI;AAExD,MAAM,uBAAuB,CAAC,aAA0C;AAC7E,MAAI,CAAC,YAAY,SAAS,MAAM,KAAK,CAAC,UAAU,SAAS,IAAI;AAC3D,UAAM,IAAI,MAAM,+BAA+B;AACjD,QAAM,QAAQ,IAAI,gBAAgB,EAAE,MAAM,SAAS,KAAK,CAAC;AACzD,SAAO,mBAAmB,SAAS,OAAO,cAAc,IAAI,SAAS,OAAO,SAAS,IAAI,KAAK;AAChG;AAEO,MAAM,sBAAsB,CAAC,UAAoD;AACtF,MAAI;AACF,UAAM,MAAM,IAAI,IAAI,KAAK;AACzB,UAAM,YAAY,IAAI,SAAS,MAAM,CAAC;AACtC,UAAM,SAAS,EAAE,gBAAgB,IAAI,UAAU,UAAU;AACzD,UAAM,QAAQ,IAAI,aAAa,OAAO,MAAM;AAC5C,QACE,IAAI,aAAa,2BACjB,IAAI,SAAS,SAAS,KACtB,IAAI,SAAS,SAAS,KACtB,IAAI,KAAK,SAAS,KAClB,IAAI,KAAK,SAAS,KAClB,CAAC,YAAY,MAAM,KACnB,MAAM,WAAW,KACjB,CAAC,GAAG,IAAI,aAAa,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,QAAQ,MAAM;AAEzD,aAAO,IAAI,0BAA0B;AACvC,UAAM,OAAO,MAAM,CAAC;AACpB,QAAI,QAAQ,QAAQ,CAAC,UAAU,IAAI,EAAG,QAAO,IAAI,2BAA2B;AAC5E,WAAO,GAAG,EAAE,QAAQ,KAAK,CAAC;AAAA,EAC5B,QAAQ;AACN,WAAO,IAAI,0BAA0B;AAAA,EACvC;AACF;",
+  "names": []
+}