@letta-ai/letta-agent-sdk 0.2.5 → 0.2.6

package/README.md

@@ -116,9 +116,12 @@ for await (const msg of session.stream()) {
 ### Constellation
 
 Use `backend: "cloud"` to create or resume agents hosted on Constellation. If
-no `environment` is provided, the SDK creates an agent-scoped sandbox, waits for
-it to come online, refreshes it while the session is active, and cleans it up on
-close.
+no `environment` is provided, the SDK creates a managed sandbox, waits for it to
+come online, and refreshes it while the session is active. Non-default
+conversations request a conversation-scoped sandbox from supporting servers;
+the default conversation and legacy servers retain the agent-scoped lifecycle.
+Managed sandboxes are left for TTL cleanup by default so another session for the
+same conversation can reconnect to them.
 
 ```ts
 const client = new LettaAgentClient({
@@ -127,8 +130,8 @@ const client = new LettaAgentClient({
   sandbox: {
     // Optional: defaults to a 5-minute refresh TTL.
     ttlMinutes: 5,
-    // Optional: defaults true. Set false for concurrent same-agent sessions.
-    terminateOnClose: true,
+    // Optional: defaults false. Set true only with exclusive ownership.
+    terminateOnClose: false,
   },
 });
 
@@ -138,7 +141,7 @@ const agentId = await client.createAgent({
 });
 
 await using session = client.resumeSession(agentId, {
-  permissionMode: "bypassPermissions",
+  permissionMode: "unrestricted",
 });
 
 await session.send("Summarize this repository.");
@@ -180,10 +183,52 @@ await using session = client.resumeSession(agentId, {
 `environment` also accepts `{ id: "env-..." }` for an environment record or
 `{ deviceId: "device-..." }` for a stable device selector.
 
-`environment` and `sandbox` are mutually exclusive. Managed sandbox refresh and
-termination operate on the latest active sandbox for an agent; set
-`sandbox.terminateOnClose: false` when multiple SDK sessions may run
-concurrently against the same agent and rely on TTL cleanup instead.
+`environment` and `sandbox` are mutually exclusive. Conversation-scoped
+sandboxes refresh and terminate by sandbox ID. Legacy agent-scoped sandboxes
+retain the latest-active ownership check. Pass `sandbox.terminateOnClose: true`
+to request best-effort eager cleanup, but only when no other session or
+reconnecting client needs the sandbox.
+
+If Cloud reaps a conversation-scoped sandbox before the next refresh,
+`send()` throws `CloudManagedSandboxExpiredError` before transmitting the turn.
+Close the old SDK session and resume the same conversation to create a fresh
+connection, then retry safely:
+
+```ts
+import {
+  CloudManagedSandboxExpiredError,
+  LettaAgentClient,
+} from "@letta-ai/letta-agent-sdk";
+
+const client = new LettaAgentClient({
+  backend: "cloud",
+  apiKey: process.env.LETTA_API_KEY,
+});
+const conversationId = "conv-123";
+let session = client.resumeSession(conversationId);
+
+async function sendWithSandboxRecovery(message: string): Promise<void> {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      await session.send(message);
+      for await (const event of session.stream()) {
+        if (event.type === "assistant") console.log(event.content);
+      }
+      return;
+    } catch (error) {
+      if (!(error instanceof CloudManagedSandboxExpiredError) || attempt > 0) {
+        throw error;
+      }
+      session.close();
+      session = client.resumeSession(conversationId);
+    }
+  }
+}
+```
+
+Only retry automatically for this pre-send expiration error. If a connection
+fails after `send()` succeeds, inspect conversation history before retrying
+because the original message may already have reached the runtime.
 
 By default, websocket authentication uses `Authorization` headers. Set
 `webSocketAuth: "query"` for browser-style websocket clients that cannot send
@@ -238,7 +283,7 @@ const session = client.resumeSession("agent-123", {
   // For local sessions this may be a local path; for remote/Constellation
   // sessions, use a path inside the selected runtime environment.
   cwd: "/workspace/project",
-  permissionMode: "bypassPermissions",
+  permissionMode: "unrestricted",
   dreaming: {
     trigger: "step-count", // off | step-count | compaction-event
     stepCount: 8,
@@ -275,6 +320,85 @@ const sync = await session.sendCommand(
 );
 ```
 
+## Dreaming
+
+The dreaming API has three explicit components: collect normalized transcript
+snapshots, initialize a guarded memory filesystem, then run a dream over the
+exact transcript list. Reflection batches edit isolated clones and a final
+aggregation pass synthesizes their diffs into the dream agent's MemFS.
+
+```typescript
+import {
+  LettaAgentClient,
+  collectTranscripts,
+  dream,
+  initDreamAgent,
+} from "@letta-ai/letta-agent-sdk";
+
+const client = new LettaAgentClient({
+  backend: "local",
+  appServer: { harnessBackend: "api" },
+});
+
+// 1. Collect immutable snapshots after an exclusive cutoff. Limits apply per
+// source, so this selects the five newest eligible sessions from each store.
+const transcripts = await collectTranscripts({
+  after: "2026-07-01T00:00:00Z",
+  sources: [
+    { type: "claude", limit: 5 },
+    { type: "codex", limit: 5 },
+  ],
+});
+
+// 2. Initialize the complete starting MemFS. Seeded files may be modified but
+// not deleted. New files and directories are allowed only below skills/.
+const agent = await initDreamAgent(client, {
+  model: "anthropic/claude-opus-4-8",
+  memfs: {
+    directories: ["skills"],
+    files: {
+      "system/project/AGENTS.md":
+        "---\ndescription: Project guidance\n---\n\n# Project guidance\n",
+    },
+  },
+  guard: {
+    allowedNewFilePrefixes: ["skills"],
+  },
+});
+
+// 3. Run against the exact snapshots. The optional prompt is appended to each
+// reflection batch, not to the aggregation pass.
+const result = await dream({
+  client,
+  agentId: agent.agentId,
+  transcripts,
+  reflectionPrompt: "Only retain learnings relevant to this project.",
+});
+
+if (result.kind === "completed") {
+  console.log(result.success, result.runRoot, result.aggregation.report);
+}
+```
+
+Available transcript sources include `claude`, `codex`, `openhands`, `letta`,
+and already-normalized `transcript` files. `after` compares against each
+session's end time and is exclusive; `limit` keeps the latest eligible sessions
+for that source spec. Use `planOnly: true` to inspect transcript selection and
+batch packing without running agents.
+
+The pre-commit guard is installed on the canonical MemFS and every reflection
+clone. The SDK also validates every commit and the final working tree after
+each run, so `--no-verify` cannot bypass the policy. For finer control, pass
+`guard.allowedOperations` rules for exact or recursive paths. Every run records
+batch inputs, output clones, diffs, normalized worker trajectories, reports,
+and an immutable final aggregate snapshot under `runRoot`. See
+[`examples/dream.ts`](./examples/dream.ts).
+
+OpenHands conversations retain incremental cursors in the dream agent's SDK
+state; later dreams skip records at or before the last successfully reflected
+timestamp. Claude and Codex sessions are finite snapshots and remain
+cursor-free.
+
 ## Links
 
 - Docs: https://docs.letta.com/letta-agent-sdk

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/cloud-session.d.ts

@@ -1,5 +1,17 @@
 import { RemoteClientSessionCore, type RuntimeSessionInit, type RuntimeSessionMode } from "./remote-client-session-core.js";
 import type { CreateAgentOptions, LettaCodeClientSessionOptions, LettaCodeCloudClientOptions } from "./types.js";
+/**
+ * The Cloud API reaped a conversation-scoped managed sandbox before the SDK
+ * could refresh it. The failed refresh happens before the next turn is sent,
+ * so callers can safely create a new SDK session for {@link conversationId}
+ * and retry that turn.
+ */
+export declare class CloudManagedSandboxExpiredError extends Error {
+    readonly sandboxId: string;
+    readonly conversationId: string;
+    readonly code: "managed_sandbox_expired";
+    constructor(sandboxId: string, conversationId: string);
+}
 type CloudSessionMode = Extract<RuntimeSessionMode, {
     kind: "session";
 }>;
@@ -15,6 +27,7 @@ export declare class CloudEnvironmentSession extends RemoteClientSessionCore {
     private managedSandbox;
     private sandboxRefreshTimer;
     private sandboxRefreshInFlight;
+    private sandboxLifecycleClosing;
     private attachedRepositoryIds;
     private readonly cloudMode;
     constructor(cloudOptions: LettaCodeCloudClientOptions, mode: CloudSessionMode);

package/dist/cloud-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloud-session.d.ts","sourceRoot":"","sources":["../src/cloud-session.ts"],"names":[],"mappings":"AAoBA,OAAO,EACL,uBAAuB,EAIvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAEV,kBAAkB,EAClB,6BAA6B,EAC7B,2BAA2B,EAM5B,MAAM,YAAY,CAAC;AAkFpB,KAAK,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAmJzE,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,CAerF;AA8VD,wBAAsB,gBAAgB,CACpC,aAAa,EAAE,2BAA2B,EAC1C,YAAY,EAAE,kBAAkB,GAC/B,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,6BAA6B,GACrC,IAAI,CA0BN;AAED,qBAAa,uBAAwB,SAAQ,uBAAuB;IAYhE,OAAO,CAAC,QAAQ,CAAC,YAAY;IAX/B,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,yBAAyB,CAA6B;IAC9D,OAAO,CAAC,2BAA2B,CAA6B;IAChE,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,mBAAmB,CAA+C;IAC1E,OAAO,CAAC,sBAAsB,CAA8B;IAC5D,OAAO,CAAC,qBAAqB,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;gBAG1B,YAAY,EAAE,2BAA2B,EAC1D,IAAI,EAAE,gBAAgB;cAWC,2BAA2B,IAAI,OAAO,CAAC,kBAAkB,CAAC;YA8DrE,iBAAiB;cA2BN,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC;cAUxC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;cAMjC,WAAW,IAAI,IAAI;YASxB,cAAc;YAoCd,yBAAyB;YAsBzB,0BAA0B;IAYxC,OAAO,CAAC,mBAAmB;YAkBb,qBAAqB;YAoBrB,sBAAsB;YAYtB,mBAAmB;YAenB,qBAAqB;YAYrB,kBAAkB;YAkBlB,oBAAoB;YAepB,2BAA2B;YAc3B,yBAAyB;YAQzB,8BAA8B;YAiB9B,oBAAoB;YAyCpB,qBAAqB;YAcrB,yBAAyB;YAuBzB,uBAAuB;YAiBvB,+BAA+B;IA4B7C,OAAO,CAAC,0BAA0B;IAYlC,OAAO,CAAC,yBAAyB;YAMnB,qBAAqB;IAYnC,OAAO,CAAC,uBAAuB;IAS/B,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,sBAAsB;CAG/B"}
+{"version":3,"file":"cloud-session.d.ts","sourceRoot":"","sources":["../src/cloud-session.ts"],"names":[],"mappings":"AAoBA,OAAO,EACL,uBAAuB,EAIvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAEV,kBAAkB,EAClB,6BAA6B,EAC7B,2BAA2B,EAM5B,MAAM,YAAY,CAAC;AAwFpB;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IAItD,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM;IAJjC,QAAQ,CAAC,IAAI,EAAG,yBAAyB,CAAU;gBAGxC,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM;CAOlC;AAED,KAAK,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAmJzE,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,CAerF;AA8VD,wBAAsB,gBAAgB,CACpC,aAAa,EAAE,2BAA2B,EAC1C,YAAY,EAAE,kBAAkB,GAC/B,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,6BAA6B,GACrC,IAAI,CAuBN;AAED,qBAAa,uBAAwB,SAAQ,uBAAuB;IAahE,OAAO,CAAC,QAAQ,CAAC,YAAY;IAZ/B,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,yBAAyB,CAA6B;IAC9D,OAAO,CAAC,2BAA2B,CAA6B;IAChE,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,mBAAmB,CAA+C;IAC1E,OAAO,CAAC,sBAAsB,CAA8B;IAC5D,OAAO,CAAC,uBAAuB,CAAS;IACxC,OAAO,CAAC,qBAAqB,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;gBAG1B,YAAY,EAAE,2BAA2B,EAC1D,IAAI,EAAE,gBAAgB;cAWC,2BAA2B,IAAI,OAAO,CAAC,kBAAkB,CAAC;YAgErE,iBAAiB;cA8BN,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC;cAUxC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;cAMjC,WAAW,IAAI,IAAI;YASxB,cAAc;YAoCd,yBAAyB;YAsBzB,0BAA0B;IAYxC,OAAO,CAAC,mBAAmB;YAkBb,qBAAqB;YAoBrB,sBAAsB;YAYtB,mBAAmB;YAenB,qBAAqB;YAYrB,kBAAkB;YAkBlB,oBAAoB;YAepB,2BAA2B;YAc3B,yBAAyB;YAQzB,8BAA8B;YAiC9B,oBAAoB;YA2DpB,qBAAqB;YAcrB,yBAAyB;YAuDzB,uBAAuB;YAqCvB,+BAA+B;IA4B7C,OAAO,CAAC,0BAA0B;IAelC,OAAO,CAAC,yBAAyB;YAMnB,qBAAqB;IAuBnC,OAAO,CAAC,uBAAuB;IAS/B,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,sBAAsB;CAG/B"}

package/dist/dream/agent.d.ts

@@ -0,0 +1,55 @@
+import type { LettaAgentClient } from "../client.js";
+import { type MemfsGuardInstallation, type MemfsOperationRule, type MemfsStructure, type MemfsWritePolicy } from "./memfs.js";
+export interface DreamAgentConfig {
+    schema_version: "v1";
+    name?: string;
+    createdAt: string;
+    /** Model for the dream agent and its lazily-created reflection worker. */
+    model?: string;
+    reflectorAgentId?: string;
+    memfs: {
+        /** Empty directories that initialization must preserve across clones. */
+        directories: readonly string[];
+        /** Persistent write policy enforced for reflection and aggregation. */
+        policy: MemfsWritePolicy;
+    };
+}
+export interface DreamAgentGuardOptions {
+    /** Directory prefixes under which agents may create new files/folders. */
+    allowedNewFilePrefixes?: readonly string[];
+    /** Optional exact/recursive overrides for create, modify, and delete. */
+    allowedOperations?: readonly MemfsOperationRule[];
+}
+export interface InitDreamAgentOptions {
+    name?: string;
+    /** Model for the dream agent and its reflection worker. */
+    model?: string;
+    /** Complete initial contents and declared empty directories for MemFS. */
+    memfs?: MemfsStructure;
+    /** Restrict what later reflection/aggregation sessions may write. */
+    guard?: DreamAgentGuardOptions;
+    /** Override the harness agents directory (primarily for tests). */
+    agentsDir?: string;
+    /** Reuse an existing memfs-enabled Letta agent instead of creating one. */
+    agentId?: string;
+}
+export interface LoadedDreamAgent {
+    agentId: string;
+    memoryDir: string;
+    stateDir: string;
+    runsDir: string;
+    configPath: string;
+    config: DreamAgentConfig;
+}
+export declare function saveDreamAgentConfig(agent: LoadedDreamAgent): Promise<void>;
+export declare function loadDreamAgent(agentId: string, options?: {
+    agentsDir?: string;
+}): Promise<LoadedDreamAgent>;
+/** Reinstall the guard and recreate declared empty directories before a run. */
+export declare function prepareDreamAgentMemfs(agent: LoadedDreamAgent): Promise<MemfsGuardInstallation>;
+/**
+ * Create or bind a memfs-enabled Letta agent, seed its initial MemFS, commit
+ * that seed, and install the requested write guard.
+ */
+export declare function initDreamAgent(client: LettaAgentClient, options?: InitDreamAgentOptions): Promise<LoadedDreamAgent>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/dream/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/dream/agent.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAML,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE;QACL,yEAAyE;QACzE,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;QAC/B,uEAAuE;QACvE,MAAM,EAAE,gBAAgB,CAAC;KAC1B,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,qEAAqE;IACrE,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAqBD,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,OAAO,CAAC,gBAAgB,CAAC,CAwB3B;AAED,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,sBAAsB,CAAC,CAOjC;AAkCD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,gBAAgB,CAAC,CAgE3B"}

package/dist/dream/aggregate.d.ts

@@ -0,0 +1,38 @@
+import type { LettaAgentClient } from "../client.js";
+import { type MemfsWritePolicy } from "./memfs.js";
+import type { BatchReflectionResult } from "./reflect.js";
+export interface DreamAggregationOutcome {
+    success: boolean;
+    /** The aggregator's final report (or the skip reason). */
+    report: string;
+    error?: string;
+    conversationId?: string;
+    /** Commits the aggregator landed on the target, relative to the base. */
+    commitCount: number;
+}
+export declare function runDreamAggregation(params: {
+    client: LettaAgentClient;
+    aggregatorAgentId: string;
+    /** The target memory filesystem the synthesis lands on. */
+    memoryDir: string;
+    runRoot: string;
+    reflections: BatchReflectionResult[];
+    /** Write policy enforced on the canonical MemFS and checked afterward. */
+    memfsPolicy: MemfsWritePolicy;
+    /**
+     * Persona text prepended to the prompt when the aggregating agent doesn't
+     * carry a dedicated aggregator persona block (a dream agent synthesizing
+     * its own memory).
+     */
+    personaPreamble?: string;
+    /**
+     * Additional caller instruction. The aggregator is the only stage that
+     * edits the target memory, so instructions about maintaining specific
+     * files (e.g. a projected AGENTS.md) must reach it here.
+     */
+    instruction?: string;
+    /** Abort: close the aggregator session and stop nudging. */
+    signal?: AbortSignal;
+    log?: (line: string) => void;
+}): Promise<DreamAggregationOutcome>;
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/dream/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../../src/dream/aggregate.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAKpB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAI1D,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,MAAM,EAAE,gBAAgB,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,qBAAqB,EAAE,CAAC;IACrC,0EAA0E;IAC1E,WAAW,EAAE,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA+PnC"}

package/dist/dream/batching.d.ts

@@ -0,0 +1,12 @@
+import type { DiscoveredSession } from "./types.js";
+export declare const DEFAULT_BATCH_TOKEN_BUDGET = 60000;
+export declare const DEFAULT_MAX_SESSIONS_PER_BATCH = 10;
+export interface DreamBatch {
+    index: number;
+    sessions: DiscoveredSession[];
+    estTokens: number;
+    startTime: string;
+    endTime: string;
+}
+export declare function packDreamBatches(sessions: DiscoveredSession[], tokenBudget: number, maxSessions: number): DreamBatch[];
+//# sourceMappingURL=batching.d.ts.map

package/dist/dream/batching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batching.d.ts","sourceRoot":"","sources":["../../src/dream/batching.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,eAAO,MAAM,0BAA0B,QAAS,CAAC;AACjD,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,UAAU,EAAE,CAmCd"}

package/dist/dream/clone.d.ts

@@ -0,0 +1,14 @@
+export declare function gitOutput(cwd: string, args: string[]): Promise<string>;
+/**
+ * Clone the memory filesystem into outputDir and return the base revision the
+ * clone starts from (the revision batch diffs are taken against).
+ */
+export declare function cloneMemoryTree(memoryDir: string, outputDir: string): Promise<string>;
+/** Commits past the base revision, and whether the tree has uncommitted edits. */
+export declare function inspectMemoryTree(memoryDir: string, baseRevision: string): Promise<{
+    commitCount: number;
+    dirty: boolean;
+}>;
+/** Record an immutable checkout of the final memory tree with a run. */
+export declare function snapshotMemoryTree(memoryDir: string, outputDir: string): Promise<void>;
+//# sourceMappingURL=clone.d.ts.map

package/dist/dream/clone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone.d.ts","sourceRoot":"","sources":["../../src/dream/clone.ts"],"names":[],"mappings":"AAaA,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5E;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED,kFAAkF;AAClF,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAelD;AAED,wEAAwE;AACxE,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/dream/cursors.d.ts

@@ -0,0 +1,7 @@
+/** sessionKey ("openhands:<conversation-id>") → last reflected timestamp. */
+export type DreamCursors = Record<string, {
+    reflectedThrough: string;
+}>;
+export declare function loadDreamCursors(stateDir: string): Promise<DreamCursors>;
+export declare function saveDreamCursors(stateDir: string, cursors: DreamCursors): Promise<void>;
+//# sourceMappingURL=cursors.d.ts.map

package/dist/dream/cursors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursors.d.ts","sourceRoot":"","sources":["../../src/dream/cursors.ts"],"names":[],"mappings":"AAiBA,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAExE,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CAUvB;AAED,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/dream/index.d.ts

@@ -0,0 +1,67 @@
+import type { LettaAgentClient } from "../client.js";
+import { type DreamBatch } from "./batching.js";
+import { type DreamAggregationOutcome } from "./aggregate.js";
+import { type BatchReflectionResult } from "./reflect.js";
+import type { DiscoveredSession, NormalizedSession } from "./types.js";
+export type { DreamBatch } from "./batching.js";
+export type { DreamAggregationOutcome } from "./aggregate.js";
+export type { BatchReflectionResult } from "./reflect.js";
+export { packDreamBatches } from "./batching.js";
+export { AGGREGATOR_PERSONA, REFLECTION_SYSTEM_PROMPT, } from "./prompts.js";
+export { getTrajectorySource, listTrajectorySourceTypes } from "./registry.js";
+export { type DreamAgentConfig, type DreamAgentGuardOptions, type InitDreamAgentOptions, type LoadedDreamAgent, initDreamAgent, loadDreamAgent, } from "./agent.js";
+export { type MemfsOperation, type MemfsOperationRule, type MemfsStructure, type MemfsWritePolicy, } from "./memfs.js";
+export { collectTranscripts, type CollectTranscriptsOptions, type Transcript, type TranscriptSourceSpec, } from "./transcripts.js";
+export type { DiscoveredSession, NormalizedRecord, NormalizedSession, TrajectorySource, } from "./types.js";
+export interface DreamOptions {
+    client: LettaAgentClient;
+    /** Initialized dream-agent id returned by initDreamAgent(). */
+    agentId: string;
+    /** Immutable normalized transcript snapshots to reflect on. */
+    transcripts: readonly NormalizedSession[];
+    /**
+     * Additional caller instruction for the run, provided to every reflection
+     * batch AND to the aggregation pass. The aggregator is the stage that
+     * lands the final commit on the memory filesystem, so instructions about
+     * maintaining specific files (e.g. a projected AGENTS.md) reach it too —
+     * an instruction that steered only the batches would be unreliable.
+     */
+    instruction?: string;
+    /** Override the harness agents directory (tests). */
+    agentsDir?: string;
+    /** Per-batch token budget (default 60k, measured on normalized content). */
+    batchTokenBudget?: number;
+    /** Maximum transcripts in one batch (default 10). */
+    maxTranscriptsPerBatch?: number;
+    /** Concurrent reflection sessions; default: every batch at once. */
+    concurrency?: number;
+    /** Preview cursor filtering and batch packing without running agents. */
+    planOnly?: boolean;
+    /**
+     * Abort the run: in-flight reflector/aggregator sessions are closed, no
+     * new batches start, the run's artifacts (clones, runRoot) are removed,
+     * cursors are NOT advanced, and dream() rejects with the abort reason.
+     * Shutting down a spawned app-server remains the caller's job via
+     * client.close().
+     */
+    signal?: AbortSignal;
+    log?: (line: string) => void;
+}
+export type DreamResult = {
+    kind: "nothing_to_dream";
+} | {
+    kind: "plan";
+    transcripts: DiscoveredSession[];
+    batches: DreamBatch[];
+} | {
+    kind: "completed";
+    runRoot: string;
+    success: boolean;
+    transcripts: DiscoveredSession[];
+    batches: BatchReflectionResult[];
+    aggregation: DreamAggregationOutcome;
+    reflectorAgentId: string;
+    aggregatorAgentId: string;
+};
+export declare function dream(options: DreamOptions): Promise<DreamResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/dream/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dream/index.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAGL,KAAK,UAAU,EAEhB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,qBAAqB,EAE3B,MAAM,cAAc,CAAC;AAUtB,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAOpB,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EACL,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EACf,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,gBAAgB,CAAC;IACzB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC1C;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAKD,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,GAC5B;IACE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB,GACD;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,WAAW,EAAE,uBAAuB,CAAC;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC;AAuCN,wBAAsB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAyKvE"}

package/dist/dream/memfs.d.ts

@@ -0,0 +1,75 @@
+export interface MemfsStructure {
+    /** UTF-8 file contents keyed by path relative to the MemFS root. */
+    files?: Readonly<Record<string, string>>;
+    /** Directories to materialize even when they contain no tracked files. */
+    directories?: readonly string[];
+}
+export interface ValidatedMemfsStructure {
+    files: readonly {
+        path: string;
+        content: string;
+    }[];
+    directories: readonly string[];
+}
+export type MemfsOperation = "create" | "modify" | "delete";
+export interface MemfsOperationRule {
+    /** Exact relative path, or directory path when recursive is true. */
+    path: string;
+    recursive?: boolean;
+    operations: readonly MemfsOperation[];
+}
+/**
+ * Default policy semantics:
+ * - paths in existingPaths may be modified (but not created or deleted);
+ * - paths below allowedNewFilePrefixes may be created, modified, or deleted;
+ * - everything else is denied.
+ *
+ * A matching allowedOperations rule overrides those defaults. This permits,
+ * for example, an existing AGENTS.md to be modifiable but not deletable.
+ */
+export interface MemfsWritePolicy {
+    existingPaths: readonly string[];
+    allowedNewFilePrefixes?: readonly string[];
+    allowedOperations?: readonly MemfsOperationRule[];
+    /** Empty directories that must be recreated after a Git clone. */
+    declaredDirectories?: readonly string[];
+}
+export interface MemfsGuardInstallation {
+    hooksDir: string;
+    preCommitPath: string;
+    postCommitPath: string;
+    /** Directories present when the guard was installed, excluding .git. */
+    baselineDirectories: readonly string[];
+}
+export interface MemfsPolicyViolation {
+    path: string;
+    operation?: MemfsOperation;
+    source: "commit" | "working-tree" | "untracked" | "directory";
+    commit?: string;
+    reason: string;
+}
+export interface MemfsValidationResult {
+    valid: boolean;
+    violations: readonly MemfsPolicyViolation[];
+}
+export declare function validateMemfsStructure(structure: MemfsStructure): ValidatedMemfsStructure;
+export declare function createMemfsWritePolicy(structure: MemfsStructure | ValidatedMemfsStructure, options?: {
+    allowedNewFilePrefixes?: readonly string[];
+    allowedOperations?: readonly MemfsOperationRule[];
+}): MemfsWritePolicy;
+export declare function validateMemfsWritePolicy(policy: MemfsWritePolicy): MemfsWritePolicy;
+export declare function recreateMemfsDirectories(memoryDir: string, directories: readonly string[]): Promise<readonly string[]>;
+export declare function materializeMemfsStructure(memoryDir: string, structure: MemfsStructure): Promise<ValidatedMemfsStructure>;
+export declare function installMemfsGuard(memoryDir: string, policy: MemfsWritePolicy): Promise<MemfsGuardInstallation>;
+/** Configure a freshly cloned MemFS repo, whose hooks and local config Git did not copy. */
+export declare function configureMemfsCloneGuard(sourceMemoryDir: string, cloneMemoryDir: string, policy: MemfsWritePolicy): Promise<MemfsGuardInstallation>;
+/**
+ * Defense-in-depth validation after an agent run. Every commit is inspected,
+ * so an illegal add followed by a delete cannot disappear in an endpoint diff.
+ */
+export declare function validateMemfsChanges(memoryDir: string, baseRevision: string, policy: MemfsWritePolicy, options?: {
+    baselineDirectories?: readonly string[];
+}): Promise<MemfsValidationResult>;
+/** Read a materialized file in tests/callers without exposing path traversal. */
+export declare function readMemfsFile(memoryDir: string, path: string): Promise<string>;
+//# sourceMappingURL=memfs.d.ts.map

package/dist/dream/memfs.d.ts.map

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

package/dist/dream/normalize-core.d.ts

@@ -0,0 +1,67 @@
+import type { NormalizedRecord } from "./types.js";
+export declare const TOOL_INPUT_MAX_CHARS = 20000;
+export declare const TOOL_RESULT_MAX_CHARS = 2500;
+export declare const CODEX_INJECTED_PREFIXES: string[];
+export declare function truncateText(text: string, limit: number): string;
+/**
+ * Timestamp from the raw formats: ISO string or epoch millis. Suffix-less
+ * (naive) timestamps are treated as UTC so ordering is stable.
+ */
+export declare function parseTimestamp(value: unknown): Date | null;
+/**
+ * ISO timestamps for n records: real where present, interpolated in gaps,
+ * synthesized monotonically when the source recorded none.
+ */
+export declare function fillTimestamps(n: number, anchors: Map<number, Date>, createdAt: Date | null, durationSeconds: number | null): string[];
+/**
+ * Return the args string (and whether it was reshaped). Byte-verbatim when
+ * under the cap and already a JSON object; otherwise reshaped to a valid JSON
+ * object, trimming the longest string values until the serialization fits.
+ */
+export declare function shrinkArgs(rawInput: string): {
+    args: string;
+    shrunk: boolean;
+};
+/**
+ * Flatten a content field (string | block list) into text; image blocks
+ * render as a placeholder.
+ */
+export declare function blocksText(content: unknown): string;
+/** One raw content block, as emitted by a per-harness parser. */
+export interface PseudoRow {
+    role: "user" | "assistant" | "tool_use" | "tool_result";
+    turnType: "user_prompt" | "system_injected" | "assistant_thinking" | "assistant_response" | "tool_use" | "tool_result";
+    content?: string;
+    timestamp?: Date | null;
+    toolName?: string;
+    toolCallId?: string;
+    toolInputJson?: string;
+    model?: string;
+}
+/** Session-level context mined from the raw store during parsing. */
+export interface SessionContext {
+    source: string;
+    cwd?: string;
+    gitBranch?: string;
+    model?: string;
+    createdAt?: Date | null;
+    durationSeconds?: number | null;
+}
+export type NormalizeRowsResult = {
+    status: "ok";
+    records: NormalizedRecord[];
+} | {
+    status: string;
+    records?: undefined;
+};
+/**
+ * Normalize ordered pseudo-rows into v1 records. Returns `{status: "ok",
+ * records}` or a `skipped:…` / `invalid:…` status with no output records.
+ */
+export declare function normalizeSessionRows(rows: PseudoRow[], context: SessionContext): NormalizeRowsResult;
+/**
+ * Minimal structural validation of the normalized-v1 contract. Returns an
+ * error string, or null when valid.
+ */
+export declare function validateRecords(records: NormalizedRecord[]): string | null;
+//# sourceMappingURL=normalize-core.d.ts.map

package/dist/dream/normalize-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-core.d.ts","sourceRoot":"","sources":["../../src/dream/normalize-core.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAgB3C,eAAO,MAAM,uBAAuB,UAKnC,CAAC;AAYF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGhE;AAMD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAW1D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,EAC1B,SAAS,EAAE,IAAI,GAAG,IAAI,EACtB,eAAe,EAAE,MAAM,GAAG,IAAI,GAC7B,MAAM,EAAE,CAmCV;AAID;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;CACjB,CAuDA;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAmBnD;AAED,iEAAiE;AACjE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,CAAC;IACxD,QAAQ,EACJ,aAAa,GACb,iBAAiB,GACjB,oBAAoB,GACpB,oBAAoB,GACpB,UAAU,GACV,aAAa,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,gBAAgB,EAAE,CAAA;CAAE,GAC7C;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,EAAE,EACjB,OAAO,EAAE,cAAc,GACtB,mBAAmB,CA2GrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,MAAM,GAAG,IAAI,CAwD1E"}