agents 0.21.0 → 0.23.0

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/context/search.ts","../../src/context/blocks.ts","../../src/context/sqlite-provider.ts"],"sourcesContent":["/**\n * Search Provider — full-text searchable context blocks.\n *\n * Extends ContextProvider with `search()` for querying indexed content\n * and a keyed `set()` for indexing individual entries.\n *\n * Duck-typed: if a provider has a `search` method, it's a SearchProvider.\n */\n\nimport type { ContextProvider } from \"./blocks\";\nimport type { SqlProvider } from \"./sqlite-provider\";\n\n/**\n * Storage interface for searchable context.\n *\n * - `get()` returns a summary of indexed content (rendered into system prompt)\n * - `search(query)` full-text search (via search_context tool)\n * - `set(key, content)` indexes content under a key (via set_context tool)\n */\nexport interface SearchProvider extends ContextProvider {\n  search(query: string): Promise<string | null>;\n  set?(key: string, content: string): Promise<void>;\n}\n\n/**\n * Check if a provider is a SearchProvider (has a `search` method).\n */\nexport function isSearchProvider(\n  provider: unknown\n): provider is SearchProvider {\n  return (\n    typeof provider === \"object\" &&\n    provider !== null &&\n    \"search\" in provider &&\n    typeof (provider as SearchProvider).search === \"function\"\n  );\n}\n\n// ── Agent Search Provider (DO SQLite FTS5) ─────────────────────────\n\n/**\n * SearchProvider backed by Durable Object SQLite with FTS5.\n *\n * - `get()` returns a count of indexed entries\n * - `search(query)` full-text search using FTS5\n * - `set(key, content)` indexes or replaces content under a key\n *\n * Entries live in one namespaced FTS5 table, separate from the session\n * message index.\n *\n * @example\n * ```ts\n * const context = new ContextBlocks([\n *   { label: \"knowledge\", provider: new AgentSearchProvider(this) }\n * ]);\n * ```\n */\nexport class AgentSearchProvider implements SearchProvider {\n  private agent: SqlProvider;\n  private label = \"\";\n  private initialized = false;\n\n  constructor(agent: SqlProvider) {\n    this.agent = agent;\n  }\n\n  init(label: string): void {\n    this.label = label;\n  }\n\n  private ensureTable(): void {\n    if (this.initialized) return;\n    // The FTS table is the only store: a mirror row table would double the\n    // billed writes of every indexed entry to serve a count and a lookup the\n    // index already answers.\n    this.agent.sql`\n      CREATE VIRTUAL TABLE IF NOT EXISTS cf_agents_search_fts\n      USING fts5(\n        label UNINDEXED,\n        key UNINDEXED,\n        content,\n        tokenize='porter unicode61'\n      )\n    `;\n    this.agent.sql`DROP TABLE IF EXISTS cf_agents_search_entries`;\n    this.initialized = true;\n  }\n\n  async get(): Promise<string | null> {\n    this.ensureTable();\n    const rows = this.agent.sql<{ count: number }>`\n      SELECT COUNT(*) as count FROM cf_agents_search_fts\n      WHERE label = ${this.label}\n    `;\n    const count = rows[0]?.count ?? 0;\n    if (count === 0) return null;\n    return `${count} entries indexed.`;\n  }\n\n  async search(query: string): Promise<string | null> {\n    this.ensureTable();\n    // Quote each word individually to prevent FTS5 syntax injection\n    // while preserving implicit AND between terms\n    const sanitized = query\n      .split(/\\s+/)\n      .filter(Boolean)\n      .map((w) => `\"${w.replace(/\"/g, '\"\"')}\"`)\n      .join(\" \");\n    if (!sanitized) return null;\n    try {\n      const rows = this.agent.sql<{\n        key: string;\n        content: string;\n      }>`\n        SELECT f.key, f.content\n        FROM cf_agents_search_fts f\n        WHERE cf_agents_search_fts MATCH ${sanitized}\n          AND f.label = ${this.label}\n        ORDER BY rank\n        LIMIT 10\n      `;\n      if (rows.length === 0) return null;\n      return rows.map((r) => `[${r.key}]\\n${r.content}`).join(\"\\n\\n\");\n    } catch {\n      // Malformed FTS query\n      return null;\n    }\n  }\n\n  async set(key: string, content: string): Promise<void> {\n    this.ensureTable();\n    this.agent.sql`\n      DELETE FROM cf_agents_search_fts\n      WHERE label = ${this.label} AND key = ${key}\n    `;\n    this.agent.sql`\n      INSERT INTO cf_agents_search_fts (label, key, content)\n      VALUES (${this.label}, ${key}, ${content})\n    `;\n  }\n}\n","/**\n * Context Block Management\n *\n * Persistent key-value blocks (MEMORY, USER, SOUL, etc.) that are:\n * - Loaded from their providers at init\n * - Frozen into a snapshot when toSystemPrompt() is called\n * - Updated via setBlock() which writes to the provider immediately\n *   but does NOT update the frozen snapshot (preserves LLM prefix cache)\n * - Re-snapshotted on next toSystemPrompt() call\n *\n * Provider type determines behavior:\n * - ContextProvider (get only)        → readonly block in system prompt\n * - WritableContextProvider (get+set) → writable via set_context tool\n * - SearchProvider (get+search+set?)  → searchable via search_context tool\n */\n\nimport type { ToolSet } from \"ai\";\nimport { z } from \"zod\";\nimport { estimateStringTokens } from \"../sessions/tokens\";\nimport { isSearchProvider, type SearchProvider } from \"./search\";\n\nfunction slugify(text: string): string {\n  return text\n    .slice(0, 60)\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, \"-\")\n    .replace(/^-|-$/g, \"\");\n}\n\nfunction stableHash(text: string): string {\n  let hash = 0x811c9dc5;\n  for (let i = 0; i < text.length; i++) {\n    hash ^= text.charCodeAt(i);\n    hash = Math.imul(hash, 0x01000193);\n  }\n  return (hash >>> 0).toString(36);\n}\n\nfunction contextEntryKey(metadataTitle: string | undefined, content: string) {\n  if (metadataTitle?.trim()) {\n    const slug = slugify(metadataTitle);\n    return slug || `entry-${stableHash(metadataTitle)}`;\n  }\n\n  const slug = slugify(content) || \"entry\";\n  return `${slug}-${stableHash(content)}`;\n}\n\n/**\n * Base storage interface for a context block.\n * A provider with only `get()` is readonly.\n */\nexport interface ContextProvider {\n  get(): Promise<string | null>;\n  /** Called by the context system to provide the block label before first use. */\n  init?(label: string): void;\n}\n\n/**\n * Writable context provider — extends ContextProvider with `set()`.\n * Blocks backed by this provider are writable via the `set_context` tool.\n */\nexport interface WritableContextProvider extends ContextProvider {\n  set(content: string): Promise<void>;\n}\n\n/**\n * Check if a provider is writable (has a `set` method).\n */\nexport function isWritableProvider(\n  provider: unknown\n): provider is WritableContextProvider {\n  return (\n    typeof provider === \"object\" &&\n    provider !== null &&\n    \"set\" in provider &&\n    typeof (provider as WritableContextProvider).set === \"function\"\n  );\n}\n\n/**\n * Configuration for a context block.\n */\nexport interface ContextConfig {\n  /** Block label — used as key and in tool descriptions */\n  label: string;\n  /** Human-readable description (shown to AI in tool) */\n  description?: string;\n  /** Maximum tokens allowed. Enforced on set. */\n  maxTokens?: number;\n  /** Storage provider. Determines block behavior:\n   *  - ContextProvider (get only) → readonly\n   *  - WritableContextProvider (get+set) → writable via set_context\n   *  - SearchProvider (get+search+set?) → searchable via search_context\n   *  If omitted, auto-wired to writable SQLite when using builder. */\n  provider?: ContextProvider | WritableContextProvider | SearchProvider;\n}\n\n/**\n * A loaded context block with computed token count.\n */\nexport interface ContextBlock {\n  label: string;\n  description?: string;\n  content: string;\n  tokens: number;\n  maxTokens?: number;\n  /** True if provider is writable (has set) */\n  writable: boolean;\n  /** True if backed by a SearchProvider */\n  isSearchable: boolean;\n}\n\n/**\n * Manages context blocks with frozen snapshot support.\n */\nexport class ContextBlocks {\n  private configs: ContextConfig[];\n  private blocks = new Map<string, ContextBlock>();\n  private snapshot: string | null = null;\n  private loaded = false;\n  private promptStore: WritableContextProvider | null;\n  private defaultProvider: ((label: string) => ContextProvider) | null;\n\n  /**\n   * @param configs Blocks to load on first use.\n   * @param promptStore Persists the frozen system prompt, keeping the\n   *   provider's prefix cache warm across wakes.\n   * @param defaultProvider Supplies storage for blocks declared without a\n   *   provider, so a host can offer durable writable blocks by label alone.\n   */\n  constructor(\n    configs: ContextConfig[],\n    promptStore?: WritableContextProvider,\n    defaultProvider?: (label: string) => ContextProvider\n  ) {\n    this.configs = configs;\n    this.promptStore = promptStore ?? null;\n    this.defaultProvider = defaultProvider ?? null;\n  }\n\n  /** Fill in the host's storage for a block declared without a provider. */\n  private withDefaultProvider(config: ContextConfig): ContextConfig {\n    if (config.provider || !this.defaultProvider) return config;\n    return { ...config, provider: this.defaultProvider(config.label) };\n  }\n\n  /**\n   * Load all blocks from their providers. Hosts call this once at startup;\n   * every other entry point loads lazily.\n   */\n  async load(): Promise<void> {\n    this.configs = this.configs.map((config) =>\n      this.withDefaultProvider(config)\n    );\n    for (const config of this.configs) {\n      this.blocks.set(config.label, await this.loadBlock(config));\n    }\n    this.loaded = true;\n  }\n\n  /** Initialize a block's provider and read its current content. */\n  private async loadBlock(config: ContextConfig): Promise<ContextBlock> {\n    const provider = config.provider;\n    provider?.init?.(config.label);\n    const content = provider ? ((await provider.get()) ?? \"\") : \"\";\n    const searchable = isSearchProvider(provider);\n    return {\n      label: config.label,\n      description: config.description,\n      content,\n      tokens: estimateStringTokens(content),\n      maxTokens: config.maxTokens,\n      writable: isWritableProvider(provider) || (searchable && !!provider?.set),\n      isSearchable: searchable\n    };\n  }\n\n  /**\n   * Dynamically register a new context block after initialization.\n   * Used by extensions to contribute context at runtime.\n   *\n   * If blocks have already been loaded, the new block's provider is\n   * initialized and loaded immediately. The snapshot is NOT updated\n   * automatically — call `refreshSystemPrompt()` to rebuild.\n   */\n  async addBlock(input: ContextConfig): Promise<ContextBlock> {\n    if (!this.loaded) await this.load();\n\n    if (this.configs.some((c) => c.label === input.label)) {\n      throw new Error(`Block \"${input.label}\" already exists`);\n    }\n\n    const config = this.withDefaultProvider(input);\n    this.configs.push(config);\n    const block = await this.loadBlock(config);\n    this.blocks.set(config.label, block);\n    return block;\n  }\n\n  /**\n   * Remove a dynamically registered context block.\n   * Used during extension unload cleanup.\n   *\n   * Returns true if the block existed and was removed.\n   * The snapshot is NOT updated automatically — call\n   * `refreshSystemPrompt()` to rebuild.\n   */\n  removeBlock(label: string): boolean {\n    const idx = this.configs.findIndex((c) => c.label === label);\n    if (idx === -1) return false;\n\n    this.configs.splice(idx, 1);\n    this.blocks.delete(label);\n    return true;\n  }\n\n  /**\n   * Get a block by label.\n   */\n  getBlock(label: string): ContextBlock | null {\n    return this.blocks.get(label) ?? null;\n  }\n\n  /**\n   * Get all blocks.\n   */\n  getBlocks(): ContextBlock[] {\n    return Array.from(this.blocks.values());\n  }\n\n  /**\n   * Set block content. Writes to provider immediately.\n   * Does NOT update the frozen snapshot.\n   */\n  async setBlock(label: string, content: string): Promise<ContextBlock> {\n    if (!this.loaded) await this.load();\n    const config = this.configs.find((c) => c.label === label);\n    const existing = this.blocks.get(label);\n\n    if (!existing?.writable) {\n      throw new Error(`Block \"${label}\" is readonly`);\n    }\n\n    if (existing.isSearchable) {\n      throw new Error(\n        `Block \"${label}\" is a keyed provider. Use setSearchEntry() instead.`\n      );\n    }\n\n    const tokens = estimateStringTokens(content);\n    const maxTokens = config?.maxTokens ?? existing?.maxTokens;\n\n    if (maxTokens !== undefined && tokens > maxTokens) {\n      throw new Error(\n        `Block \"${label}\" exceeds maxTokens: ${tokens} > ${maxTokens}`\n      );\n    }\n\n    const block: ContextBlock = {\n      label,\n      description: config?.description ?? existing?.description,\n      content,\n      tokens,\n      maxTokens,\n      writable: true,\n      isSearchable: false\n    };\n\n    this.blocks.set(label, block);\n\n    // Write to provider immediately (durable)\n    if (config?.provider && isWritableProvider(config.provider)) {\n      await config.provider.set(content);\n    }\n\n    return block;\n  }\n\n  /** Index a search entry within a searchable block. */\n  private async setSearchEntry(\n    label: string,\n    key: string,\n    content: string\n  ): Promise<void> {\n    if (!this.loaded) await this.load();\n    const config = this.configs.find((c) => c.label === label);\n    const existing = this.blocks.get(label);\n\n    if (!existing?.isSearchable) {\n      throw new Error(`Block \"${label}\" is not a search provider`);\n    }\n\n    const provider = config?.provider;\n    if (!provider || !isSearchProvider(provider) || !provider.set) {\n      throw new Error(`Block \"${label}\" does not support writes`);\n    }\n\n    await provider.set(key, content);\n\n    // Refresh summary\n    const summary = await provider.get();\n    existing.content = summary ?? \"\";\n    existing.tokens = estimateStringTokens(existing.content);\n  }\n\n  /** Search a searchable block. */\n  private async searchContext(\n    label: string,\n    query: string\n  ): Promise<string | null> {\n    if (!this.loaded) await this.load();\n    const config = this.configs.find((c) => c.label === label);\n\n    if (!config?.provider || !isSearchProvider(config.provider)) {\n      throw new Error(`Block \"${label}\" is not a search provider`);\n    }\n\n    return config.provider.search(query);\n  }\n\n  /**\n   * Append content to a block.\n   */\n  async appendToBlock(label: string, content: string): Promise<ContextBlock> {\n    if (!this.loaded) await this.load();\n    const existing = this.blocks.get(label);\n    if (!existing) {\n      throw new Error(`Block \"${label}\" not found`);\n    }\n    const needsSep = existing.content.length > 0 && !content.startsWith(\"\\n\");\n    return this.setBlock(\n      label,\n      existing.content + (needsSep ? \"\\n\" : \"\") + content\n    );\n  }\n\n  private renderPrompt(): string {\n    const parts: string[] = [];\n    const sep = \"═\".repeat(46);\n\n    for (const block of this.blocks.values()) {\n      // Skip empty readonly blocks — writable and searchable blocks always\n      // render so the LLM knows which tools can address them.\n      if (!block.content && !block.writable && !block.isSearchable) continue;\n\n      let header = block.label.toUpperCase();\n      if (block.description) header += ` (${block.description})`;\n      if (block.maxTokens) {\n        const pct = Math.round((block.tokens / block.maxTokens) * 100);\n        header += ` [${pct}% — ${block.tokens}/${block.maxTokens} tokens]`;\n      }\n      if (block.isSearchable) header += \" [searchable]\";\n      else if (!block.writable) header += \" [readonly]\";\n      else header += \" [writable]\";\n\n      parts.push(`${sep}\\n${header}\\n${sep}\\n${block.content}`);\n    }\n\n    return parts.join(\"\\n\\n\");\n  }\n\n  // ── Public API ──────────────────────────────────────────────────\n\n  /**\n   * The frozen system prompt. The first call renders the blocks and stores\n   * the result; every later call returns that same string, so the model\n   * provider's prefix cache stays warm. Block edits do not change it until\n   * `refreshSystemPrompt()` is called.\n   */\n  async freezeSystemPrompt(): Promise<string> {\n    if (this.promptStore) {\n      const stored = await this.promptStore.get();\n      if (stored !== null) return stored;\n    }\n    if (this.snapshot !== null) return this.snapshot;\n\n    if (!this.loaded) await this.load();\n    this.snapshot = this.renderPrompt();\n    await this.promptStore?.set(this.snapshot);\n    return this.snapshot;\n  }\n\n  /**\n   * Reload every block from its provider, re-render the system prompt, and\n   * persist it. Use this after block content has changed.\n   */\n  async refreshSystemPrompt(): Promise<string> {\n    this.loaded = false;\n    await this.load();\n    this.snapshot = this.renderPrompt();\n    await this.promptStore?.set(this.snapshot);\n    return this.snapshot;\n  }\n\n  /**\n   * AI tools for context blocks.\n   *\n   * Auto-wired based on provider capabilities:\n   * - `set_context` — when any block is writable\n   * - `search_context` — when any block is a search provider\n   */\n  async tools(): Promise<ToolSet> {\n    if (!this.loaded) await this.load();\n\n    const blocks = Array.from(this.blocks.values());\n    const writable = blocks.filter((b) => b.writable);\n    const searchLabels = blocks\n      .filter((b) => b.isSearchable)\n      .map((b) => b.label);\n    const toolSet: ToolSet = {};\n\n    // ── set_context ──────────────────────────────────────────────\n\n    if (writable.length > 0) {\n      const blockDescriptions = writable.map((b) => {\n        const kind = b.isSearchable ? \"searchable, keyed entries\" : \"writable\";\n        return `- \"${b.label}\" (${kind}): ${b.description ?? \"no description\"}`;\n      });\n      const keyedBlocks = writable.filter((b) => b.isSearchable);\n\n      const properties: Record<string, unknown> = {\n        label: {\n          type: \"string\" as const,\n          enum: writable.map((b) => b.label),\n          description: \"Block label to write to\"\n        },\n        content: {\n          type: \"string\" as const,\n          description: \"The main content to write to the block.\"\n        },\n        action: {\n          type: \"string\" as const,\n          enum: [\"replace\", \"append\"],\n          description: \"replace (default) or append\"\n        }\n      };\n\n      if (keyedBlocks.length > 0) {\n        properties.metadata = {\n          type: \"object\" as const,\n          description:\n            \"Optional metadata for keyed entries (searchable blocks: \" +\n            keyedBlocks.map((b) => `\"${b.label}\"`).join(\", \") +\n            \"). A title keeps updates stable; a description helps the model \" +\n            \"pick the right entry.\",\n          properties: {\n            title: {\n              type: \"string\" as const,\n              description:\n                \"Short title. Used as a stable identifier — entries with the \" +\n                \"same title are updated in place, different titles create new entries.\"\n            },\n            description: {\n              type: \"string\" as const,\n              description:\n                \"One-line summary shown alongside the title in the system prompt \" +\n                \"so the model can decide when to load the entry.\"\n            }\n          }\n        };\n      }\n\n      const metadataHint =\n        keyedBlocks.length > 0\n          ? \"\\n\\nFor searchable blocks, pass `metadata: { title, description }` \" +\n            \"— title stabilises updates, description helps the model pick \" +\n            \"entries. Metadata is optional.\"\n          : \"\";\n\n      toolSet.set_context = {\n        description: `Write to a context block. Available blocks:\\n${blockDescriptions.join(\"\\n\")}\\n\\nWrites are durable and persist across sessions.${metadataHint}`,\n        inputSchema: z.fromJSONSchema({\n          type: \"object\" as const,\n          properties: properties as Record<string, Record<string, unknown>>,\n          required: [\"label\", \"content\"]\n        }),\n        execute: async ({\n          label,\n          content,\n          metadata,\n          action\n        }: {\n          label: string;\n          content: string;\n          metadata?: { title?: string; description?: string };\n          action?: string;\n        }) => {\n          try {\n            const block = this.blocks.get(label);\n            if (!block) return `Error: block \"${label}\" not found`;\n\n            if (block.isSearchable) {\n              const key = contextEntryKey(metadata?.title, content);\n              await this.setSearchEntry(label, key, content);\n              return `Indexed \"${key}\" in ${label}.`;\n            }\n\n            const updated =\n              action === \"append\"\n                ? await this.appendToBlock(label, content)\n                : await this.setBlock(label, content);\n            const usage = updated.maxTokens\n              ? `${Math.round((updated.tokens / updated.maxTokens) * 100)}% (${updated.tokens}/${updated.maxTokens} tokens)`\n              : `${updated.tokens} tokens`;\n            return `Written to ${label}. Usage: ${usage}`;\n          } catch (err) {\n            return `Error: ${err instanceof Error ? err.message : String(err)}`;\n          }\n        }\n      };\n    }\n\n    // ── search_context ────────────────────────────────────────────\n\n    if (searchLabels.length > 0) {\n      toolSet.search_context = {\n        description:\n          \"Search for information in a searchable context block. \" +\n          \"ONLY these blocks are searchable: \" +\n          searchLabels.map((l) => `\"${l}\"`).join(\", \") +\n          \". Other blocks cannot be searched.\",\n        inputSchema: z.fromJSONSchema({\n          type: \"object\" as const,\n          properties: {\n            label: {\n              type: \"string\" as const,\n              enum: searchLabels,\n              description: \"Searchable block label\"\n            },\n            query: {\n              type: \"string\" as const,\n              description: \"Search query\"\n            }\n          },\n          required: [\"label\", \"query\"]\n        }),\n        execute: async ({ label, query }: { label: string; query: string }) => {\n          try {\n            if (!searchLabels.includes(label)) {\n              return `Error: \"${label}\" is not searchable. Searchable blocks: ${searchLabels.join(\", \")}`;\n            }\n            const results = await this.searchContext(label, query);\n            return results ?? \"No results found.\";\n          } catch (err) {\n            return `Error: ${err instanceof Error ? err.message : String(err)}`;\n          }\n        }\n      };\n    }\n\n    return toolSet;\n  }\n}\n","/**\n * SQLite Context Block Provider\n *\n * Default durable storage for context blocks using DO SQLite.\n * Each block is a row in cf_agents_context_blocks.\n */\n\nimport type { WritableContextProvider } from \"./blocks\";\n\n/** Minimal tagged-template SQL surface used by SQLite context providers. */\nexport interface SqlProvider {\n  sql<T = Record<string, string | number | boolean | null>>(\n    strings: TemplateStringsArray,\n    ...values: (string | number | boolean | null)[]\n  ): T[];\n}\n\n/** SQLite-backed writable context block provider. */\nexport class AgentContextProvider implements WritableContextProvider {\n  private agent: SqlProvider;\n  private label: string;\n  private initialized = false;\n\n  constructor(agent: SqlProvider, label?: string) {\n    this.agent = agent;\n    this.label = label ?? \"\";\n  }\n\n  init(label: string): void {\n    if (!this.label) {\n      this.label = label;\n    }\n  }\n\n  private ensureTable(): void {\n    if (this.initialized) return;\n    this.agent.sql`\n      CREATE TABLE IF NOT EXISTS cf_agents_context_blocks (\n        label TEXT PRIMARY KEY,\n        content TEXT NOT NULL,\n        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP\n      )\n    `;\n    this.initialized = true;\n  }\n\n  async get(): Promise<string | null> {\n    this.ensureTable();\n    const rows = this.agent.sql<{ content: string }>`\n      SELECT content FROM cf_agents_context_blocks WHERE label = ${this.label}\n    `;\n    return rows[0]?.content ?? null;\n  }\n\n  async set(content: string): Promise<void> {\n    this.ensureTable();\n    this.agent.sql`\n      INSERT INTO cf_agents_context_blocks (label, content)\n      VALUES (${this.label}, ${content})\n      ON CONFLICT(label) DO UPDATE SET content = ${content}, updated_at = CURRENT_TIMESTAMP\n    `;\n  }\n}\n"],"mappings":"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"}

package/dist/current-agent-Da_C9a3b.d.ts

@@ -0,0 +1,266 @@
+import {
+  _ as LifecycleJobOutcome,
+  b as Connection,
+  g as LifecycleJobContext,
+  i as DurableObjectCapability,
+  o as MemoryLimitContext,
+  u as LifecycleRouteAddress,
+  w as WSMessage,
+  y as LifecycleJobs
+} from "./capability-runner-Be_-PLR1.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { DurableObject } from "cloudflare:workers";
+
+//#region src/lifecycle/durable-object-lifecycle.d.ts
+/** Internal envelope transported between routed Lifecycle instances. */
+type LifecycleRouteEnvelope = {
+  readonly capability: string;
+  readonly source: LifecycleRouteAddress | undefined;
+  readonly payload: unknown;
+};
+/** Configuration accepted when constructing a {@link Lifecycle}. */
+type LifecycleOptions = {
+  /**
+   * Consecutive alarm invocations that may end in a Durable Object
+   * memory-limit reset before the circuit breaker (#1825) seals recovery
+   * work instead of backing it off. Default: 3.
+   */
+  readonly maxAlarmMemoryLimitStrikes?: number;
+};
+/** Placement of a capability in the dispatch order. */
+type LifecycleUseOptions = {
+  /**
+   * Dispatch after every non-fallback capability, whenever it was
+   * installed. For a host's catch-all, such as a WebSockets capability
+   * that claims every upgrade, so middleware installed later still runs
+   * first.
+   */
+  readonly fallback?: boolean;
+};
+/**
+ * Installs and coordinates the runtime lifecycle for a Durable Object.
+ *
+ * Construct this as an instance field on a class that directly extends
+ * `DurableObject`, then call {@link Lifecycle.installHandlers}
+ * from that class's constructor.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class Lifecycle<
+  Env extends object = Cloudflare.Env,
+  Props extends Record<string, unknown> = Record<string, unknown>
+> {
+  #private;
+  /**
+   * Construct and install a lifecycle in one explicit operation.
+   *
+   * @param host - The Durable Object whose runtime handlers the lifecycle owns.
+   * @returns The installed lifecycle.
+   */
+  static install<
+    Env extends object,
+    Props extends Record<string, unknown> = Record<string, unknown>
+  >(
+    host: DurableObject<Env>,
+    options?: LifecycleOptions
+  ): Lifecycle<Env, Props>;
+  /**
+   * Bind a lifecycle to a Durable Object instance without mutating its handlers.
+   *
+   * @param host - The Durable Object whose runtime lifecycle this object owns.
+   * @param options - Policy configuration for this lifecycle.
+   */
+  constructor(host: DurableObject<Env>, options?: LifecycleOptions);
+  /**
+   * Install platform fetch, alarm, and hibernating WebSocket handlers.
+   *
+   * Existing handlers are preserved for framework-owned dispatch such as the
+   * Agent's sub-agent router and alarm circuit breaker. Calling this method
+   * more than once is an error.
+   */
+  installHandlers(): void;
+  /**
+   * Add a reusable capability before this lifecycle starts.
+   *
+   * Capabilities dispatch in registration order, except that fallbacks
+   * always come after non-fallbacks.
+   *
+   * @param capability - The capability to add.
+   * @param options - Dispatch placement.
+   * @returns This lifecycle.
+   */
+  use(
+    capability: DurableObjectCapability<Props>,
+    options?: LifecycleUseOptions
+  ): this;
+  /** @internal Deliver a generic capability envelope to this Lifecycle. */
+  route(envelope: LifecycleRouteEnvelope): Promise<unknown>;
+  /**
+   * Execute SQL queries against the Durable Object's database
+   * @template T Type of the returned rows
+   * @param strings SQL query template strings
+   * @param values Values to be inserted into the query
+   * @returns Array of query results
+   */
+  sql<T = Record<string, string | number | boolean | null>>(
+    strings: TemplateStringsArray,
+    ...values: (string | number | boolean | null)[]
+  ): T[];
+  /**
+   * Handle an incoming request for the owning Durable Object.
+   *
+   * Non-upgrade requests run through the capability middleware chain first,
+   * then fall through to the host's `onRequest`.
+   */
+  fetch(request: Request): Promise<Response>;
+  /** @internal Dispatch a hibernating WebSocket message. */
+  webSocketMessage(ws: WebSocket, message: WSMessage): Promise<void>;
+  /** @internal Dispatch a hibernating WebSocket close. */
+  webSocketClose(
+    ws: WebSocket,
+    code: number,
+    reason: string,
+    wasClean: boolean
+  ): Promise<void>;
+  /** @internal Dispatch a hibernating WebSocket error. */
+  webSocketError(ws: WebSocket, error: unknown): Promise<void>;
+  /**
+   * Start lifecycle capabilities and the owning Durable Object.
+   *
+   * Runtime fetch, alarm, and WebSocket entry points call this automatically.
+   * RPC methods may call it explicitly because native RPC bypasses fetch.
+   *
+   * @param props - Optional properties supplied to capability and host startup.
+   */
+  start(props?: Props): Promise<void>;
+  /**
+   * The name used to address this Durable Object.
+   *
+   * Native `ctx.id.name` is authoritative. A read-only legacy storage fallback
+   * lets objects created by older PartyServer releases migrate without new
+   * name writes.
+   */
+  get name(): string;
+  /**
+   * The host's scoped access to the Lifecycle work queue. Items pushed here
+   * are dispatched to the host's `onJob` inside the host invocation
+   * boundary.
+   */
+  get jobs(): LifecycleJobs;
+  /**
+   * Recompute the physical Durable Object alarm from job-queue state.
+   *
+   * Concurrent requests are serialized so a later durable-state change cannot
+   * be overwritten by an earlier alarm calculation. Queue mutations call this
+   * automatically; it stays public for composition roots and tests.
+   */
+  rearmAlarm(): Promise<void>;
+  /**
+   * Keep work a job handed off at a bounded return inside the current
+   * alarm's memory-limit breaker domain (#1825). Hosts call this where a
+   * queue-driven callback detaches long work and returns.
+   *
+   * @returns True when called during an alarm invocation; false otherwise.
+   */
+  trackAlarmWork(work: Promise<unknown>): boolean;
+  /** Dispose installed capabilities in reverse registration order. */
+  dispose(): Promise<void>;
+  /** Permanently disable and clear alarms during explicit object teardown. */
+  disableAlarms(): Promise<void>;
+  /**
+   * Run one alarm invocation. The job driver owns the event loop — deadman
+   * pre-arm, due-job dispatch with retry and deferral policy, the alarm
+   * memory-limit circuit breaker (#1825) — and re-arms the physical alarm
+   * from queue state. The host's `onAlarm()` runs after due jobs, inside
+   * the host invocation boundary.
+   */
+  alarm(): Promise<void>;
+}
+//#endregion
+//#region src/lifecycle/current-agent.d.ts
+/**
+ * A Durable Object that has installed the Agents SDK Lifecycle.
+ *
+ * Pass a more specific Lifecycle Object type to {@link getCurrentAgent} when
+ * shared host code needs APIs implemented by a particular object.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface LifecycleObject<
+  Env extends object = Cloudflare.Env,
+  Props extends Record<string, unknown> = Record<string, unknown>
+> extends DurableObject<Env> {
+  readonly lifecycle: Lifecycle<Env, Props>;
+  onStart?(props?: Props): void | Promise<void>;
+  onRequest?(request: Request): Response | Promise<Response>;
+  onAlarm?(): void | Promise<void>;
+  onJob?(
+    context: LifecycleJobContext
+  ): LifecycleJobOutcome | void | Promise<LifecycleJobOutcome | void>;
+  /**
+   * Host domain policy applied when the alarm memory-limit circuit breaker
+   * records a strike (#1825), after every capability's `onMemoryLimit` hook.
+   *
+   * Lifecycle dispatches host hooks structurally through its internal host
+   * cast, so TS visibility is the host's to choose: a framework host whose
+   * implementation is internal machinery declares the hook `protected` (the
+   * pattern — see `AIChatAgent`/`Think`) and keeps the real work in a
+   * `private _cf_`-prefixed method, without falling out of this contract at
+   * runtime.
+   */
+  onAlarmMemoryLimit?(context: MemoryLimitContext): void | Promise<void>;
+}
+/** Values associated with the currently executing Lifecycle host. */
+type AgentContextStore = {
+  /** Lifecycle host selected for this invocation. */ agent: unknown /** WebSocket connection selected for this invocation, when applicable. */;
+  connection:
+    | Connection
+    | undefined /** HTTP request selected for this invocation, when applicable. */;
+  request:
+    | Request
+    | undefined /** Extension-owned value selected for this invocation, when applicable. */;
+  email: unknown;
+};
+/** Values returned by {@link getCurrentAgent}. */
+type CurrentAgentContext<
+  Host extends DurableObject = LifecycleObject,
+  Email = unknown
+> = {
+  agent: Host | undefined;
+  connection: Connection | undefined;
+  request: Request | undefined;
+  email: Email | undefined;
+};
+/**
+ * Shared invocation context for Lifecycle, Agent, AIChatAgent, and Think.
+ *
+ * @internal Importing or relying on this symbol will break your code in a
+ * future release. Use {@link getCurrentAgent} to read the public context.
+ */
+declare const __DO_NOT_USE_WILL_BREAK__agentContext: AsyncLocalStorage<AgentContextStore>;
+/**
+ * Return the current Agent or Lifecycle Object and invocation-specific values.
+ *
+ * Lifecycle host startup and alarm hooks receive the current object with no
+ * request. Request hooks additionally receive the request being handled.
+ * Lifecycle-managed WebSocket hooks receive their connection and, during
+ * connect, its upgrade request. Agent extensions may also establish context
+ * for email, chat turns, callable methods, and detached work. Capability hooks
+ * do not run in this ambient context.
+ */
+declare function getCurrentAgent<
+  Host extends DurableObject = LifecycleObject
+>(): CurrentAgentContext<Host>;
+//#endregion
+export {
+  getCurrentAgent as a,
+  LifecycleRouteEnvelope as c,
+  __DO_NOT_USE_WILL_BREAK__agentContext as i,
+  LifecycleUseOptions as l,
+  CurrentAgentContext as n,
+  Lifecycle as o,
+  LifecycleObject as r,
+  LifecycleOptions as s,
+  AgentContextStore as t
+};
+//# sourceMappingURL=current-agent-Da_C9a3b.d.ts.map

package/dist/current-agent-DhoDkSnH.js

@@ -0,0 +1,51 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/lifecycle/current-agent.ts
+/**
+* Shared invocation context for Lifecycle, Agent, AIChatAgent, and Think.
+*
+* @internal Importing or relying on this symbol will break your code in a
+* future release. Use {@link getCurrentAgent} to read the public context.
+*/
+const __DO_NOT_USE_WILL_BREAK__agentContext = new AsyncLocalStorage();
+/**
+* Return the current Agent or Lifecycle Object and invocation-specific values.
+*
+* Lifecycle host startup and alarm hooks receive the current object with no
+* request. Request hooks additionally receive the request being handled.
+* Lifecycle-managed WebSocket hooks receive their connection and, during
+* connect, its upgrade request. Agent extensions may also establish context
+* for email, chat turns, callable methods, and detached work. Capability hooks
+* do not run in this ambient context.
+*/
+function getCurrentAgent() {
+	const store = __DO_NOT_USE_WILL_BREAK__agentContext.getStore();
+	if (!store) return {
+		agent: void 0,
+		connection: void 0,
+		request: void 0,
+		email: void 0
+	};
+	return {
+		agent: store.agent,
+		connection: store.connection,
+		request: store.request,
+		email: store.email
+	};
+}
+/** Run one host hook in the context of its Lifecycle Object. */
+function runInLifecycleHostContext(context, operation) {
+	return __DO_NOT_USE_WILL_BREAK__agentContext.run({
+		agent: context.host,
+		connection: context.connection,
+		request: context.request,
+		email: void 0
+	}, operation);
+}
+/** Run a capability hook without inheriting a current Agent or host context. */
+function runWithoutCurrentAgent(operation) {
+	return __DO_NOT_USE_WILL_BREAK__agentContext.exit(operation);
+}
+//#endregion
+export { runWithoutCurrentAgent as i, getCurrentAgent as n, runInLifecycleHostContext as r, __DO_NOT_USE_WILL_BREAK__agentContext as t };
+
+//# sourceMappingURL=current-agent-DhoDkSnH.js.map

package/dist/current-agent-DhoDkSnH.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"current-agent-DhoDkSnH.js","names":[],"sources":["../src/lifecycle/current-agent.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\nimport type { DurableObject } from \"cloudflare:workers\";\n\nimport type { MemoryLimitContext } from \"./capability-runner\";\nimport type { Lifecycle } from \"./durable-object-lifecycle\";\nimport type { Connection } from \"./types\";\nimport type { LifecycleJobContext, LifecycleJobOutcome } from \"./job-queue\";\n\n/**\n * A Durable Object that has installed the Agents SDK Lifecycle.\n *\n * Pass a more specific Lifecycle Object type to {@link getCurrentAgent} when\n * shared host code needs APIs implemented by a particular object.\n *\n * @experimental The API surface may change before stabilizing.\n */\nexport interface LifecycleObject<\n  Env extends object = Cloudflare.Env,\n  Props extends Record<string, unknown> = Record<string, unknown>\n> extends DurableObject<Env> {\n  readonly lifecycle: Lifecycle<Env, Props>;\n  onStart?(props?: Props): void | Promise<void>;\n  onRequest?(request: Request): Response | Promise<Response>;\n  onAlarm?(): void | Promise<void>;\n  onJob?(\n    context: LifecycleJobContext\n  ): LifecycleJobOutcome | void | Promise<LifecycleJobOutcome | void>;\n  /**\n   * Host domain policy applied when the alarm memory-limit circuit breaker\n   * records a strike (#1825), after every capability's `onMemoryLimit` hook.\n   *\n   * Lifecycle dispatches host hooks structurally through its internal host\n   * cast, so TS visibility is the host's to choose: a framework host whose\n   * implementation is internal machinery declares the hook `protected` (the\n   * pattern — see `AIChatAgent`/`Think`) and keeps the real work in a\n   * `private _cf_`-prefixed method, without falling out of this contract at\n   * runtime.\n   */\n  onAlarmMemoryLimit?(context: MemoryLimitContext): void | Promise<void>;\n}\n\n/** Values associated with the currently executing Lifecycle host. */\nexport type AgentContextStore = {\n  /** Lifecycle host selected for this invocation. */\n  agent: unknown;\n  /** WebSocket connection selected for this invocation, when applicable. */\n  connection: Connection | undefined;\n  /** HTTP request selected for this invocation, when applicable. */\n  request: Request | undefined;\n  /** Extension-owned value selected for this invocation, when applicable. */\n  email: unknown;\n};\n\n/** Values returned by {@link getCurrentAgent}. */\nexport type CurrentAgentContext<\n  Host extends DurableObject = LifecycleObject,\n  Email = unknown\n> = {\n  agent: Host | undefined;\n  connection: Connection | undefined;\n  request: Request | undefined;\n  email: Email | undefined;\n};\n\n/**\n * Shared invocation context for Lifecycle, Agent, AIChatAgent, and Think.\n *\n * @internal Importing or relying on this symbol will break your code in a\n * future release. Use {@link getCurrentAgent} to read the public context.\n */\nexport const __DO_NOT_USE_WILL_BREAK__agentContext =\n  new AsyncLocalStorage<AgentContextStore>();\n\n/**\n * Return the current Agent or Lifecycle Object and invocation-specific values.\n *\n * Lifecycle host startup and alarm hooks receive the current object with no\n * request. Request hooks additionally receive the request being handled.\n * Lifecycle-managed WebSocket hooks receive their connection and, during\n * connect, its upgrade request. Agent extensions may also establish context\n * for email, chat turns, callable methods, and detached work. Capability hooks\n * do not run in this ambient context.\n */\nexport function getCurrentAgent<\n  Host extends DurableObject = LifecycleObject\n>(): CurrentAgentContext<Host> {\n  const store = __DO_NOT_USE_WILL_BREAK__agentContext.getStore();\n  if (!store) {\n    return {\n      agent: undefined,\n      connection: undefined,\n      request: undefined,\n      email: undefined\n    };\n  }\n\n  return {\n    agent: store.agent as Host,\n    connection: store.connection,\n    request: store.request,\n    email: store.email\n  };\n}\n\ntype LifecycleHostContext<\n  Env extends object,\n  Props extends Record<string, unknown>\n> = {\n  readonly host: LifecycleObject<Env, Props>;\n  readonly connection?: Connection;\n  readonly request?: Request;\n};\n\n/** Run one host hook in the context of its Lifecycle Object. */\nexport function runInLifecycleHostContext<\n  Env extends object,\n  Props extends Record<string, unknown>,\n  T\n>(context: LifecycleHostContext<Env, Props>, operation: () => T): T {\n  return __DO_NOT_USE_WILL_BREAK__agentContext.run(\n    {\n      agent: context.host,\n      connection: context.connection,\n      request: context.request,\n      email: undefined\n    },\n    operation\n  );\n}\n\n/** Run a capability hook without inheriting a current Agent or host context. */\nexport function runWithoutCurrentAgent<T>(operation: () => T): T {\n  return __DO_NOT_USE_WILL_BREAK__agentContext.exit(operation);\n}\n"],"mappings":";;;;;;;;AAsEA,MAAa,wCACX,IAAI,kBAAqC;;;;;;;;;;;AAY3C,SAAgB,kBAEe;CAC7B,MAAM,QAAQ,sCAAsC,SAAS;CAC7D,IAAI,CAAC,OACH,OAAO;EACL,OAAO,KAAA;EACP,YAAY,KAAA;EACZ,SAAS,KAAA;EACT,OAAO,KAAA;CACT;CAGF,OAAO;EACL,OAAO,MAAM;EACb,YAAY,MAAM;EAClB,SAAS,MAAM;EACf,OAAO,MAAM;CACf;AACF;;AAYA,SAAgB,0BAId,SAA2C,WAAuB;CAClE,OAAO,sCAAsC,IAC3C;EACE,OAAO,QAAQ;EACf,YAAY,QAAQ;EACpB,SAAS,QAAQ;EACjB,OAAO,KAAA;CACT,GACA,SACF;AACF;;AAGA,SAAgB,uBAA0B,WAAuB;CAC/D,OAAO,sCAAsC,KAAK,SAAS;AAC7D"}

package/dist/diagnostics-BzvaX2UT.js

@@ -0,0 +1,45 @@
+import { channel } from "node:diagnostics_channel";
+//#region src/observability/diagnostics.ts
+/** Diagnostics channels for Agent and Lifecycle telemetry. */
+const channels = {
+	state: channel("agents:state"),
+	rpc: channel("agents:rpc"),
+	message: channel("agents:message"),
+	chat: channel("agents:chat"),
+	transcript: channel("agents:transcript"),
+	fiber: channel("agents:fiber"),
+	task: channel("agents:task"),
+	stream: channel("agents:stream"),
+	agentTool: channel("agents:agent_tool"),
+	schedule: channel("agents:schedule"),
+	lifecycle: channel("agents:lifecycle"),
+	workflow: channel("agents:workflow"),
+	mcp: channel("agents:mcp"),
+	email: channel("agents:email"),
+	channel: channel("agents:channel")
+};
+function getChannel(type) {
+	if (type.startsWith("mcp:")) return channels.mcp;
+	if (type.startsWith("workflow:")) return channels.workflow;
+	if (type.startsWith("fiber:")) return channels.fiber;
+	if (type.startsWith("task:")) return channels.task;
+	if (type.startsWith("stream:")) return channels.stream;
+	if (type.startsWith("transcript:") || type.startsWith("chat:transcript:")) return channels.transcript;
+	if (type.startsWith("chat:")) return channels.chat;
+	if (type.startsWith("agent_tool:")) return channels.agentTool;
+	if (type.startsWith("schedule:") || type.startsWith("queue:")) return channels.schedule;
+	if (type.startsWith("message:") || type.startsWith("tool:") || type.startsWith("submission:") || type.startsWith("action:")) return channels.message;
+	if (type === "rpc" || type.startsWith("rpc:")) return channels.rpc;
+	if (type.startsWith("state:")) return channels.state;
+	if (type.startsWith("email:")) return channels.email;
+	if (type.startsWith("channel:") || type.startsWith("notice:")) return channels.channel;
+	return channels.lifecycle;
+}
+/** Publish one event to its existing diagnostics channel. */
+function publishDiagnosticsEvent(event) {
+	getChannel(event.type).publish(event);
+}
+//#endregion
+export { publishDiagnosticsEvent as n, channels as t };
+
+//# sourceMappingURL=diagnostics-BzvaX2UT.js.map

package/dist/diagnostics-BzvaX2UT.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics-BzvaX2UT.js","names":[],"sources":["../src/observability/diagnostics.ts"],"sourcesContent":["import { channel, type Channel } from \"node:diagnostics_channel\";\n\n/** Event shape accepted by the diagnostics-channel publisher. */\nexport type DiagnosticsEvent = {\n  readonly type: string;\n  readonly source?: string;\n  readonly agent?: string;\n  readonly name?: string;\n  readonly payload: unknown;\n  readonly timestamp: number;\n};\n\n/** Diagnostics channels for Agent and Lifecycle telemetry. */\nexport const channels = {\n  state: channel(\"agents:state\"),\n  rpc: channel(\"agents:rpc\"),\n  message: channel(\"agents:message\"),\n  chat: channel(\"agents:chat\"),\n  transcript: channel(\"agents:transcript\"),\n  fiber: channel(\"agents:fiber\"),\n  task: channel(\"agents:task\"),\n  stream: channel(\"agents:stream\"),\n  agentTool: channel(\"agents:agent_tool\"),\n  schedule: channel(\"agents:schedule\"),\n  lifecycle: channel(\"agents:lifecycle\"),\n  workflow: channel(\"agents:workflow\"),\n  mcp: channel(\"agents:mcp\"),\n  email: channel(\"agents:email\"),\n  channel: channel(\"agents:channel\")\n} as const;\n\nfunction getChannel(type: string): Channel {\n  if (type.startsWith(\"mcp:\")) return channels.mcp;\n  if (type.startsWith(\"workflow:\")) return channels.workflow;\n  if (type.startsWith(\"fiber:\")) return channels.fiber;\n  if (type.startsWith(\"task:\")) return channels.task;\n  if (type.startsWith(\"stream:\")) return channels.stream;\n  if (type.startsWith(\"transcript:\") || type.startsWith(\"chat:transcript:\"))\n    return channels.transcript;\n  if (type.startsWith(\"chat:\")) return channels.chat;\n  if (type.startsWith(\"agent_tool:\")) return channels.agentTool;\n  if (type.startsWith(\"schedule:\") || type.startsWith(\"queue:\"))\n    return channels.schedule;\n  if (\n    type.startsWith(\"message:\") ||\n    type.startsWith(\"tool:\") ||\n    type.startsWith(\"submission:\") ||\n    type.startsWith(\"action:\")\n  )\n    return channels.message;\n  if (type === \"rpc\" || type.startsWith(\"rpc:\")) return channels.rpc;\n  if (type.startsWith(\"state:\")) return channels.state;\n  if (type.startsWith(\"email:\")) return channels.email;\n  if (type.startsWith(\"channel:\") || type.startsWith(\"notice:\"))\n    return channels.channel;\n  return channels.lifecycle;\n}\n\n/** Publish one event to its existing diagnostics channel. */\nexport function publishDiagnosticsEvent(event: DiagnosticsEvent): void {\n  getChannel(event.type).publish(event);\n}\n"],"mappings":";;;AAaA,MAAa,WAAW;CACtB,OAAO,QAAQ,cAAc;CAC7B,KAAK,QAAQ,YAAY;CACzB,SAAS,QAAQ,gBAAgB;CACjC,MAAM,QAAQ,aAAa;CAC3B,YAAY,QAAQ,mBAAmB;CACvC,OAAO,QAAQ,cAAc;CAC7B,MAAM,QAAQ,aAAa;CAC3B,QAAQ,QAAQ,eAAe;CAC/B,WAAW,QAAQ,mBAAmB;CACtC,UAAU,QAAQ,iBAAiB;CACnC,WAAW,QAAQ,kBAAkB;CACrC,UAAU,QAAQ,iBAAiB;CACnC,KAAK,QAAQ,YAAY;CACzB,OAAO,QAAQ,cAAc;CAC7B,SAAS,QAAQ,gBAAgB;AACnC;AAEA,SAAS,WAAW,MAAuB;CACzC,IAAI,KAAK,WAAW,MAAM,GAAG,OAAO,SAAS;CAC7C,IAAI,KAAK,WAAW,WAAW,GAAG,OAAO,SAAS;CAClD,IAAI,KAAK,WAAW,QAAQ,GAAG,OAAO,SAAS;CAC/C,IAAI,KAAK,WAAW,OAAO,GAAG,OAAO,SAAS;CAC9C,IAAI,KAAK,WAAW,SAAS,GAAG,OAAO,SAAS;CAChD,IAAI,KAAK,WAAW,aAAa,KAAK,KAAK,WAAW,kBAAkB,GACtE,OAAO,SAAS;CAClB,IAAI,KAAK,WAAW,OAAO,GAAG,OAAO,SAAS;CAC9C,IAAI,KAAK,WAAW,aAAa,GAAG,OAAO,SAAS;CACpD,IAAI,KAAK,WAAW,WAAW,KAAK,KAAK,WAAW,QAAQ,GAC1D,OAAO,SAAS;CAClB,IACE,KAAK,WAAW,UAAU,KAC1B,KAAK,WAAW,OAAO,KACvB,KAAK,WAAW,aAAa,KAC7B,KAAK,WAAW,SAAS,GAEzB,OAAO,SAAS;CAClB,IAAI,SAAS,SAAS,KAAK,WAAW,MAAM,GAAG,OAAO,SAAS;CAC/D,IAAI,KAAK,WAAW,QAAQ,GAAG,OAAO,SAAS;CAC/C,IAAI,KAAK,WAAW,QAAQ,GAAG,OAAO,SAAS;CAC/C,IAAI,KAAK,WAAW,UAAU,KAAK,KAAK,WAAW,SAAS,GAC1D,OAAO,SAAS;CAClB,OAAO,SAAS;AAClB;;AAGA,SAAgB,wBAAwB,OAA+B;CACrE,WAAW,MAAM,IAAI,CAAC,CAAC,QAAQ,KAAK;AACtC"}