@letta-ai/letta-agent-sdk 0.3.2 → 0.5.0

package/AGENTS.md

@@ -0,0 +1,44 @@
+# Letta Agent SDK contributor map
+
+## Canonical source
+
+Work in `src/`. `dist/` is generated by `bun run build`, ignored by Git, and
+published as a bundle. A repeated class or method in `dist/index.js` or
+`dist/client-entry.js` can represent separate source-layer responsibilities
+that Bun placed in one file; trace it back to `src/` before changing it.
+
+## Session architecture
+
+- `client-base.ts` selects the backend and constructs a session.
+- Remote, Cloud, and the default local app-server path share
+  `remote-client-session-core.ts`.
+- `remote-session-protocol.ts` owns portable protocol types, validation, and
+  wire-to-domain normalization.
+- `remote-turn-coordinator.ts` owns active/queued turn correlation and the
+  `SDKMessage` stream queue.
+- `app-server-session.ts` adapts an app-server connection to the runtime
+  controller used by the portable session core.
+- `cloud-session.ts` resolves Cloud runtimes and managed sandboxes, then uses
+  the same runtime controller and portable session core.
+- `types.ts` defines the stable public SDK surface. Internal protocol types
+  belong beside their implementation rather than in the public type barrel.
+
+For `session.listMessages()` on an app-server or Cloud session, the call path
+is:
+
+`RemoteClientSessionCore.listMessages` →
+`RemoteClientRuntimeController.listMessages` →
+the selected transport adapter.
+
+Those methods operate at different layers and should not be combined merely
+because they share a name.
+
+## Change discipline
+
+- Keep transport parsing out of the session facade.
+- Keep turn correlation and stream buffering in `RemoteTurnCoordinator`.
+- Preserve exports from the package root and `/client` unless a change is
+  explicitly intended to be breaking.
+- Treat source-size exceptions in `scripts/check-source-size.ts` as debt
+  ceilings: reduce them when a file shrinks and do not raise them casually.
+- Run `bun run check`, `bun test`, and `bun run build` before opening a PR.

package/README.md

@@ -10,6 +10,12 @@ Build applications with stateful agents powered by the [Letta agent harness](htt
 npm install @letta-ai/letta-agent-sdk
 ```
 
+The `0.4.x` SDK line requires the matching single-socket
+`@letta-ai/letta-code` app-server release. Release `letta-code` first, then
+replace the SDK's package dependency with that published version before
+publishing `0.4.0`; the development branch intentionally does not name an
+unpublished package version.
+
 Local execution requires Node.js 22.19 or newer.
 
 ## Quick start
@@ -38,6 +44,12 @@ for await (const message of session.stream()) {
 }
 ```
 
+Assistant and reasoning messages are incremental text fragments. Reconcile
+fragments by `type` and `otid` when `otid` is available; `uuid` is a legacy
+transport identifier and is not a portable lineage key. After reconnecting,
+use `(runId, seqId)` to suppress replayed fragments. Sequence IDs are scoped to
+their run and must not be compared across runs.
+
 An agent is the persistent entity with memory. A conversation is a thread on that agent. A session is the active connection used to send messages, stream events, execute tools, and handle approvals.
 
 - `createSession(agentId)` starts a new conversation.
@@ -108,6 +120,23 @@ await using session = client.createSession(agentId, {
 });
 ```
 
+### Managed Cloud sandbox repositories
+
+Cloud sessions can clone up to 10 GitHub repositories into the managed
+sandbox. Public repositories clone directly; private repositories require
+access through the organization's GitHub integration.
+
+```ts
+await using session = client.createSession(agentId, {
+  sandbox: {
+    githubRepositories: [
+      { owner: "letta-ai", repo: "letta-docs-md" },
+      { owner: "letta-ai", repo: "letta-code" },
+    ],
+  },
+});
+```
+
 ### Remote App Server
 
 ```ts

package/dist/app-server-management.d.ts

@@ -8,51 +8,18 @@ type OwnedConnection = {
 export type AppServerManagementOptions = Partial<LettaCodeRemoteClientOptions> & {
     url?: string;
     connect?: () => Promise<OwnedConnection>;
-    /**
-     * How long (in milliseconds) an idle control connection lingers before it
-     * is released. Defaults to {@link DEFAULT_IDLE_LINGER_MS}.
-     */
-    idleLingerMs?: number;
 };
-/**
- * Wait for every management transport targeting this app-server to release
- * its control connection. The registry is process-wide so a session created
- * by a different `LettaAgentClient` instance can still take the server's
- * single control slot safely.
- */
-export declare function releaseAppServerManagementConnections(url: string): Promise<void>;
 /**
  * Management transport that speaks the app-server control protocol.
  *
- * Connection lifecycle: the Letta Code app-server currently accepts a single
- * control client at a time — while one control socket is attached, additional
- * control sockets are rejected with close code 1008
- * `"control channel already connected"` (see letta-ai/letta-code
- * `src/websocket/app-server.ts`). Sessions (`AppServerSession`) need that same
- * control slot, so a management transport that holds an idle connection
- * starves any later `resumeSession()`/`createSession()` from the same process
- * (live-reproduced in the letta-mobile reference app, SDK-FEEDBACK.md #00).
- *
- * To stay out of the way, this transport pools a single lazily-connected
- * client while requests are in flight (bursts share one connection and one
- * request-id counter, so responses correlate correctly), then releases the
- * connection shortly after it goes idle ({@link DEFAULT_IDLE_LINGER_MS}) and
- * reconnects lazily on the next request. Before a session connects, all
- * management transports registered for the same app-server URL relinquish
- * their connections; the handoff waits for in-flight work and for the control
- * socket's close event. The inverse contention — a management request issued
- * while a session holds the control slot — cannot be solved client-side and
- * still fails until the app-server allows multiple control clients.
+ * The app-server assigns every client an independent connection, so management
+ * keeps one lazy pooled client while sessions connect alongside it. Unexpected
+ * disconnects discard the pool and the next management request reconnects.
  */
 export declare class AppServerManagementTransport implements ManagementTransport {
     private readonly options;
     private connectionPromise;
-    private releasePromise;
     private closingConnections;
-    private inFlightRequests;
-    private idleWaiters;
-    private idleTimer;
-    private readonly idleLingerMs;
     constructor(options: AppServerManagementOptions);
     listAgents(query: ManagementQuery): Promise<LettaAgent[]>;
     retrieveAgent(agentId: string): Promise<LettaAgent>;
@@ -64,23 +31,11 @@ export declare class AppServerManagementTransport implements ManagementTransport
     createConversation(body: Record<string, unknown>): Promise<LettaConversation>;
     updateConversation(conversationId: string, body: Record<string, unknown>): Promise<LettaConversation>;
     listConversationMessages(conversationId: string, query: ManagementQuery): Promise<ConversationMessagesResult>;
-    /**
-     * Release the pooled control connection instead of waiting out the idle
-     * linger. If requests are in flight, wait for them to settle first.
-     *
-     * The app-server accepts a single control client (see the class docs), so
-     * This is called before opening a session to hand the control slot over
-     * without a linger-sized or socket-close race window.
-     */
-    releaseIdleConnection(): Promise<void>;
     private request;
-    private releaseConnectionWhenIdle;
     private acquireConnection;
     private openConnection;
     private discardConnection;
     private trackClosingConnection;
-    private scheduleIdleRelease;
-    private clearIdleTimer;
 }
 export {};
 //# sourceMappingURL=app-server-management.d.ts.map

package/dist/app-server-management.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-server-management.d.ts","sourceRoot":"","sources":["../src/app-server-management.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EACV,0BAA0B,EAC1B,UAAU,EACV,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAEV,4BAA4B,EAC5B,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,KAAK,eAAe,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,IAAI,IAAI,CAAA;CAAE,CAAC;AAkCtD,MAAM,MAAM,0BAA0B,GACpC,OAAO,CAAC,4BAA4B,CAAC,GAAG;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;IACzC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AA8DJ;;;;;GAKG;AACH,wBAAsB,qCAAqC,CACzD,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CASf;AA8CD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,4BACX,YAAW,mBAAmB;IAUlB,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,OAAO,CAAC,iBAAiB,CAA0C;IACnE,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,kBAAkB,CAA4B;IACtD,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAET,OAAO,EAAE,0BAA0B;IAI1D,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAYzD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAanD,WAAW,CACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC;IAahB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3C,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC;IA0BvC,iBAAiB,CACrB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAYzB,oBAAoB,CACxB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,iBAAiB,CAAC;IAavB,kBAAkB,CACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,iBAAiB,CAAC;IAavB,kBAAkB,CACtB,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,iBAAiB,CAAC;IAavB,wBAAwB,CAC5B,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,0BAA0B,CAAC;IAgBtC;;;;;;;OAOG;IACH,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;YAqBxB,OAAO;YA0CP,yBAAyB;IAsBvC,OAAO,CAAC,iBAAiB;YAsBX,cAAc;IAqD5B,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,cAAc;CAKvB"}
+{"version":3,"file":"app-server-management.d.ts","sourceRoot":"","sources":["../src/app-server-management.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EACV,0BAA0B,EAC1B,UAAU,EACV,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAEV,4BAA4B,EAC5B,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,KAAK,eAAe,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,IAAI,IAAI,CAAA;CAAE,CAAC;AAkCtD,MAAM,MAAM,0BAA0B,GACpC,OAAO,CAAC,4BAA4B,CAAC,GAAG;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;CAC1C,CAAC;AAoDJ;;;;;;GAMG;AACH,qBAAa,4BACX,YAAW,mBAAmB;IAKlB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,iBAAiB,CAA0C;IACnE,OAAO,CAAC,kBAAkB,CAA4B;gBAEzB,OAAO,EAAE,0BAA0B;IAE1D,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAYzD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAanD,WAAW,CACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC;IAahB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3C,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC;IA0BvC,iBAAiB,CACrB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAYzB,oBAAoB,CACxB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,iBAAiB,CAAC;IAavB,kBAAkB,CACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,iBAAiB,CAAC;IAavB,kBAAkB,CACtB,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,iBAAiB,CAAC;IAavB,wBAAwB,CAC5B,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,0BAA0B,CAAC;YAgBxB,OAAO;IAwBrB,OAAO,CAAC,iBAAiB;YAsBX,cAAc;IA+C5B,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,sBAAsB;CAW/B"}

package/dist/app-server-session.d.ts

@@ -17,16 +17,10 @@ export type AppServerSessionOptions = Partial<LettaCodeRemoteClientOptions> & {
         url: string;
         close(): void;
     }>;
-    /**
-     * Internal handoff hook used to release a management connection owned by
-     * the same SDK client before this session opens its control socket.
-     */
-    beforeConnect?: () => Promise<void>;
     /** Whether SDK create-agent payloads should add the origin tag automatically. */
     includeSdkOriginTag?: boolean;
 };
 export type AppServerSessionMode = RuntimeSessionMode;
-export declare function assertRemoteSessionOptionsSupported(action: string, options: LettaCodeClientSessionOptions): void;
 export declare function createAgentBody(options: CreateAgentOptions, settings?: {
     includeSdkOriginTag?: boolean;
 }): Promise<Record<string, unknown>>;

package/dist/app-server-session.d.ts.map

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

package/dist/client-base.d.ts

@@ -1,13 +1,13 @@
 import { RepositoriesClient } from "./repositories.js";
 import { type ManagementTransport } from "./management.js";
 import type { AgentsClient, ConversationsClient, ModelsClient } from "./management-types.js";
-import type { CreateAgentOptions, CreateSessionOptions, LettaCodeBackend, LettaCodeClientOptions, LettaCodeClientSessionOptions, LettaCodeEnvironment, LettaCodeSession, SDKResultMessage, SendMessage } from "./types.js";
+import type { CreateAgentOptions, LettaCodeBackend, LettaCodeClientOptions, LettaCodeClientSessionOptions, LettaCodeEnvironment, LettaCodeSession, SDKResultMessage, SendMessage } from "./types.js";
 /**
  * Top-level Letta Agent SDK client.
  *
  * `backend` selects how the SDK reaches or runs the Letta Code harness.
  * `local` spawns an SDK-owned Letta Code app-server and speaks the websocket
- * protocol by default, with an explicit stdio fallback for legacy flows.
+ * protocol.
  * `remote` connects to a user-managed Letta Code app-server websocket endpoint.
  * `cloud` uses agents hosted on Letta Cloud, with an explicit remote
  * environment or SDK-managed sandbox.
@@ -33,10 +33,9 @@ export declare class LettaAgentClientBase {
     /**
      * Create a new conversation/session.
      *
-     * Without an agent id, this uses the default/LRU agent, matching the legacy
-     * top-level createSession() helper.
+     * The app-server protocol requires an explicit agent id.
      */
-    createSession(agentIdOrOptions?: string | LettaCodeClientSessionOptions, options?: LettaCodeClientSessionOptions): LettaCodeSession;
+    createSession(agentId: string, options?: LettaCodeClientSessionOptions): LettaCodeSession;
     /**
      * Resume an existing agent default conversation or a specific conversation.
      *
@@ -45,23 +44,16 @@ export declare class LettaAgentClientBase {
      */
     resumeSession(id: string, options?: LettaCodeClientSessionOptions): LettaCodeSession;
     /** One-shot prompt convenience helper using a new conversation. */
-    prompt(message: SendMessage, agentId?: string, options?: LettaCodeClientSessionOptions): Promise<SDKResultMessage>;
+    prompt(message: SendMessage, agentId: string, options?: LettaCodeClientSessionOptions): Promise<SDKResultMessage>;
     private assertSessionBackend;
-    protected useLegacyLocalStdio(): boolean;
     protected createLocalAgent(_options: CreateAgentOptions): Promise<string>;
-    protected createLocalSession(_agentId: string | undefined, _options: LettaCodeClientSessionOptions, _sessionOptions: CreateSessionOptions): LettaCodeSession;
-    protected resumeLocalSession(_id: string, _options: LettaCodeClientSessionOptions, _sessionOptions: CreateSessionOptions): LettaCodeSession;
+    protected createLocalSession(_agentId: string, _options: LettaCodeClientSessionOptions): LettaCodeSession;
+    protected resumeLocalSession(_id: string, _options: LettaCodeClientSessionOptions): LettaCodeSession;
     protected localBackendUnavailableError(): Error;
     protected createLocalManagementTransport(): ManagementTransport;
     private remoteOptions;
     private appServerSessionOptions;
     private getRepositoriesClient;
-    /**
-     * The app-server accepts a single control client at a time. Before a session
-     * connects, wait for this client's management work to settle and relinquish
-     * its pooled connection; management reconnects lazily on its next call.
-     */
-    protected releaseIdleManagementConnection(): Promise<void>;
     private getManagementTransport;
     private cloudOptions;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"client-base.d.ts","sourceRoot":"","sources":["../src/client-base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAcvD,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,6BAA6B,EAC7B,oBAAoB,EAIpB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACZ,MAAM,YAAY,CAAC;AAkDpB;;;;;;;;;GASG;AACH,qBAAa,oBAAoB;IAC/B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACnD,OAAO,CAAC,kBAAkB,CAAmC;IAC7D,OAAO,CAAC,mBAAmB,CAAoC;gBAEnD,OAAO,GAAE,sBAA2B;IAsFhD;;;;;OAKG;IACH,IAAI,YAAY,IAAI,kBAAkB,CAErC;IAEK,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBpE;;;;;OAKG;IACH,aAAa,CACX,gBAAgB,CAAC,EAAE,MAAM,GAAG,6BAA6B,EACzD,OAAO,GAAE,6BAAkC,GAC1C,gBAAgB;IAuCnB;;;;;OAKG;IACH,aAAa,CACX,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,6BAAkC,GAC1C,gBAAgB;IAsCnB,mEAAmE;IAC7D,MAAM,CACV,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,gBAAgB,CAAC;IAY5B,OAAO,CAAC,oBAAoB;IAsD5B,SAAS,CAAC,mBAAmB,IAAI,OAAO;IAIxC,SAAS,CAAC,gBAAgB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAIzE,SAAS,CAAC,kBAAkB,CAC1B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE,6BAA6B,EACvC,eAAe,EAAE,oBAAoB,GACpC,gBAAgB;IAInB,SAAS,CAAC,kBAAkB,CAC1B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,6BAA6B,EACvC,eAAe,EAAE,oBAAoB,GACpC,gBAAgB;IAInB,SAAS,CAAC,4BAA4B,IAAI,KAAK;IAM/C,SAAS,CAAC,8BAA8B,IAAI,mBAAmB;IAI/D,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,qBAAqB;IAQ7B;;;;OAIG;cACa,+BAA+B,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhE,OAAO,CAAC,sBAAsB;IAgB9B,OAAO,CAAC,YAAY;CAMrB"}
+{"version":3,"file":"client-base.d.ts","sourceRoot":"","sources":["../src/client-base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAavD,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,kBAAkB,EAElB,gBAAgB,EAChB,sBAAsB,EACtB,6BAA6B,EAC7B,oBAAoB,EAIpB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACZ,MAAM,YAAY,CAAC;AAmDpB;;;;;;;;;GASG;AACH,qBAAa,oBAAoB;IAC/B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACnD,OAAO,CAAC,kBAAkB,CAAmC;IAC7D,OAAO,CAAC,mBAAmB,CAAoC;gBAEnD,OAAO,GAAE,sBAA2B;IAuEhD;;;;;OAKG;IACH,IAAI,YAAY,IAAI,kBAAkB,CAErC;IAEK,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBpE;;;;OAIG;IACH,aAAa,CACX,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,6BAAkC,GAC1C,gBAAgB;IA2BnB;;;;;OAKG;IACH,aAAa,CACX,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,6BAAkC,GAC1C,gBAAgB;IAsCnB,mEAAmE;IAC7D,MAAM,CACV,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,gBAAgB,CAAC;IAU5B,OAAO,CAAC,oBAAoB;IA4E5B,SAAS,CAAC,gBAAgB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAIzE,SAAS,CAAC,kBAAkB,CAC1B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,6BAA6B,GACtC,gBAAgB;IAInB,SAAS,CAAC,kBAAkB,CAC1B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,6BAA6B,GACtC,gBAAgB;IAInB,SAAS,CAAC,4BAA4B,IAAI,KAAK;IAM/C,SAAS,CAAC,8BAA8B,IAAI,mBAAmB;IAI/D,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,sBAAsB;IAgB9B,OAAO,CAAC,YAAY;CAMrB"}