agents 0.7.4 → 0.7.6

package/dist/experimental/memory/session/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../../src/experimental/memory/utils/compaction.ts","../../../../src/experimental/memory/utils/tokens.ts","../../../../src/experimental/memory/session/session.ts","../../../../src/experimental/memory/session/providers/agent.ts"],"sourcesContent":["/**\n * MicroCompaction Utilities\n *\n * Internal pure functions for lightweight compaction (no LLM).\n * Not exported to users — used by the Session wrapper.\n */\n\nimport type { UIMessage } from \"ai\";\nimport type { MicroCompactionRules } from \"../session/types\";\n\n/** Default thresholds for microCompaction rules (in chars) */\nexport const DEFAULTS = {\n  truncateToolOutputs: 30000,\n  truncateText: 10000,\n  keepRecent: 4\n};\n\n/** Resolved microCompaction rules with actual numeric thresholds */\nexport interface ResolvedMicroCompactionRules {\n  truncateToolOutputs: number | false;\n  truncateText: number | false;\n  keepRecent: number;\n}\n\n/**\n * Parse microCompaction config into resolved rules.\n * Returns null if disabled.\n */\nexport function parseMicroCompactionRules(\n  config: boolean | MicroCompactionRules\n): ResolvedMicroCompactionRules | null {\n  if (config === false) return null;\n\n  if (config === true) {\n    return {\n      truncateToolOutputs: DEFAULTS.truncateToolOutputs,\n      truncateText: DEFAULTS.truncateText,\n      keepRecent: DEFAULTS.keepRecent\n    };\n  }\n\n  // Custom rules object — validate numeric values\n  const keepRecent = config.keepRecent ?? DEFAULTS.keepRecent;\n  if (!Number.isInteger(keepRecent) || keepRecent < 0) {\n    throw new Error(\"keepRecent must be a non-negative integer\");\n  }\n\n  const truncateToolOutputs =\n    config.truncateToolOutputs === false\n      ? false\n      : config.truncateToolOutputs === true ||\n          config.truncateToolOutputs === undefined\n        ? DEFAULTS.truncateToolOutputs\n        : config.truncateToolOutputs;\n  if (typeof truncateToolOutputs === \"number\" && truncateToolOutputs <= 0) {\n    throw new Error(\"truncateToolOutputs must be a positive number\");\n  }\n\n  const truncateText =\n    config.truncateText === false\n      ? false\n      : config.truncateText === true || config.truncateText === undefined\n        ? DEFAULTS.truncateText\n        : config.truncateText;\n  if (typeof truncateText === \"number\" && truncateText <= 0) {\n    throw new Error(\"truncateText must be a positive number\");\n  }\n\n  return { truncateToolOutputs, truncateText, keepRecent };\n}\n\n/**\n * Truncate oversized parts in a single message.\n * Returns the same reference if nothing changed (allows callers to skip no-op updates).\n */\nfunction truncateMessageParts(\n  msg: UIMessage,\n  rules: ResolvedMicroCompactionRules\n): UIMessage {\n  let changed = false;\n\n  const compactedParts = msg.parts.map((part) => {\n    // Truncate tool outputs\n    if (\n      rules.truncateToolOutputs !== false &&\n      (part.type.startsWith(\"tool-\") || part.type === \"dynamic-tool\") &&\n      \"output\" in part\n    ) {\n      const toolPart = part as { output?: unknown };\n      if (toolPart.output !== undefined) {\n        const outputJson = JSON.stringify(toolPart.output);\n        if (outputJson.length > rules.truncateToolOutputs) {\n          changed = true;\n          return {\n            ...part,\n            output: `[Truncated ${outputJson.length} bytes] ${outputJson.slice(0, 500)}...`\n          };\n        }\n      }\n    }\n\n    // Truncate long text parts\n    if (\n      rules.truncateText !== false &&\n      part.type === \"text\" &&\n      \"text\" in part\n    ) {\n      const textPart = part as { type: \"text\"; text: string };\n      if (textPart.text.length > rules.truncateText) {\n        changed = true;\n        return {\n          ...part,\n          text: `${textPart.text.slice(0, rules.truncateText)}... [truncated ${textPart.text.length} chars]`\n        };\n      }\n    }\n\n    return part;\n  });\n\n  return changed ? ({ ...msg, parts: compactedParts } as UIMessage) : msg;\n}\n\n/**\n * Apply microCompaction to an array of messages.\n * Returns same reference for unchanged messages (enables skip-update optimization).\n *\n * No keepRecent logic — the caller decides which messages to pass.\n */\nexport function microCompact(\n  messages: UIMessage[],\n  rules: ResolvedMicroCompactionRules\n): UIMessage[] {\n  return messages.map((msg) => truncateMessageParts(msg, rules));\n}\n","/**\n * Token Estimation Utilities\n *\n * IMPORTANT: These are heuristic estimates, not actual tokenizer counts.\n *\n * We intentionally avoid real tokenizers (e.g. tiktoken, sentencepiece) because:\n * - A single tiktoken instance costs ~80-120MB of heap\n * - Cloudflare Workers have tight memory limits (128MB)\n * - For compaction thresholds, a conservative estimate is sufficient\n *\n * The hybrid approach (max of character-based and word-based estimates) handles\n * both dense token content (JSON, code) and natural language reasonably well.\n *\n * Calibration notes:\n * - Character-based: ~4 chars per token (conservative, from OpenAI guidance)\n * - Word-based: ~1.3 tokens per word (empirical, from Mastra's memory system)\n * - Per-message overhead: ~4 tokens for role/framing (empirical)\n *\n * These ratios are tuned for English. CJK, emoji-heavy, or highly technical\n * content may have different ratios. The conservative estimates help ensure\n * compaction triggers before context windows are actually exceeded.\n */\n\nimport type { UIMessage } from \"ai\";\n\n/** Approximate characters per token for English text */\nexport const CHARS_PER_TOKEN = 4;\n\n/** Approximate token multiplier per whitespace-separated word */\nexport const WORDS_TOKEN_MULTIPLIER = 1.3;\n\n/** Approximate overhead tokens per message (role, framing) */\nexport const TOKENS_PER_MESSAGE = 4;\n\n/**\n * Estimate token count for a string using a hybrid heuristic.\n *\n * Takes the max of two estimates:\n * - Character-based: `length / 4` — better for dense content (JSON, code, URLs)\n * - Word-based: `words * 1.3` — better for natural language prose\n *\n * This is a heuristic. Do not use where exact counts are required.\n */\nexport function estimateStringTokens(text: string): number {\n  if (!text) return 0;\n  const charEstimate = text.length / CHARS_PER_TOKEN;\n  const wordEstimate =\n    text.split(/\\s+/).filter(Boolean).length * WORDS_TOKEN_MULTIPLIER;\n  return Math.ceil(Math.max(charEstimate, wordEstimate));\n}\n\n/**\n * Estimate total token count for an array of UIMessages.\n *\n * Walks each message's parts (text, tool invocations, tool results)\n * and applies per-message overhead.\n *\n * This is a heuristic. Do not use where exact counts are required.\n */\nexport function estimateMessageTokens(messages: UIMessage[]): number {\n  let tokens = 0;\n  for (const msg of messages) {\n    tokens += TOKENS_PER_MESSAGE;\n    for (const part of msg.parts) {\n      if (part.type === \"text\") {\n        tokens += estimateStringTokens(\n          (part as { type: \"text\"; text: string }).text\n        );\n      } else if (\n        part.type.startsWith(\"tool-\") ||\n        part.type === \"dynamic-tool\"\n      ) {\n        const toolPart = part as { input?: unknown; output?: unknown };\n        if (toolPart.input) {\n          tokens += estimateStringTokens(JSON.stringify(toolPart.input));\n        }\n        if (toolPart.output) {\n          tokens += estimateStringTokens(JSON.stringify(toolPart.output));\n        }\n      }\n    }\n  }\n  return tokens;\n}\n","/**\n * Session — top-level API for conversation history with compaction.\n *\n * Wraps any SessionProvider (pure storage) and orchestrates compaction:\n * - microCompaction on every append() — cheap, no LLM\n * - full compaction when token threshold exceeded — user-supplied fn\n */\n\nimport type { UIMessage } from \"ai\";\nimport type { SessionProvider } from \"./provider\";\nimport type {\n  MessageQueryOptions,\n  SessionProviderOptions,\n  CompactResult\n} from \"./types\";\nimport {\n  parseMicroCompactionRules,\n  microCompact,\n  type ResolvedMicroCompactionRules\n} from \"../utils/compaction\";\nimport { estimateMessageTokens } from \"../utils/tokens\";\n\nexport class Session {\n  private storage: SessionProvider;\n  private microCompactionRules: ResolvedMicroCompactionRules | null;\n  private compactionConfig: SessionProviderOptions[\"compaction\"] | null;\n\n  constructor(storage: SessionProvider, options?: SessionProviderOptions) {\n    this.storage = storage;\n\n    const mc = options?.microCompaction ?? true;\n    this.microCompactionRules = parseMicroCompactionRules(mc);\n    this.compactionConfig = options?.compaction ?? null;\n  }\n\n  // ── Read (delegated to storage) ────────────────────────────────────\n\n  getMessages(options?: MessageQueryOptions): UIMessage[] {\n    return this.storage.getMessages(options);\n  }\n\n  getMessage(id: string): UIMessage | null {\n    return this.storage.getMessage(id);\n  }\n\n  getLastMessages(n: number): UIMessage[] {\n    return this.storage.getLastMessages(n);\n  }\n\n  // ── Write (delegated + compaction) ─────────────────────────────────\n\n  async append(messages: UIMessage | UIMessage[]): Promise<void> {\n    // 1. Storage inserts\n    await this.storage.appendMessages(messages);\n\n    // 2. Full compaction if token threshold exceeded — runs instead of microCompaction\n    if (this.shouldAutoCompact()) {\n      const result = await this.compact();\n      if (result.success) return;\n      // Fall through to microCompaction if full compaction failed\n    }\n\n    // 3. MicroCompaction on older messages (only if no full compaction)\n    if (this.microCompactionRules) {\n      const rules = this.microCompactionRules;\n      const older = this.storage.getOlderMessages(rules.keepRecent);\n\n      if (older.length > 0) {\n        const compacted = microCompact(older, rules);\n        for (let i = 0; i < older.length; i++) {\n          if (compacted[i] !== older[i]) {\n            this.storage.updateMessage(compacted[i]);\n          }\n        }\n      }\n    }\n  }\n\n  updateMessage(message: UIMessage): void {\n    this.storage.updateMessage(message);\n  }\n\n  deleteMessages(messageIds: string[]): void {\n    this.storage.deleteMessages(messageIds);\n  }\n\n  clearMessages(): void {\n    this.storage.clearMessages();\n  }\n\n  // ── Compaction ─────────────────────────────────────────────────────\n\n  async compact(): Promise<CompactResult> {\n    const messages = this.storage.getMessages();\n\n    if (messages.length === 0) {\n      return { success: true };\n    }\n\n    try {\n      let result = messages;\n\n      if (this.compactionConfig?.fn) {\n        result = await this.compactionConfig.fn(result);\n      }\n\n      await this.storage.replaceMessages(result);\n\n      return { success: true };\n    } catch (err) {\n      return {\n        success: false,\n        error: err instanceof Error ? err.message : String(err)\n      };\n    }\n  }\n\n  /**\n   * Pre-check for auto-compaction using token estimate heuristic.\n   */\n  private shouldAutoCompact(): boolean {\n    if (!this.compactionConfig?.tokenThreshold) return false;\n\n    const messages = this.storage.getMessages();\n    const approxTokens = estimateMessageTokens(messages);\n    return approxTokens > this.compactionConfig.tokenThreshold;\n  }\n}\n","/**\n * Agent Session Provider\n *\n * Pure storage provider that uses the Agent's DO SQLite storage.\n * Compaction is orchestrated by the Session wrapper, not here.\n */\n\nimport type { UIMessage } from \"ai\";\nimport type { SessionProvider } from \"../provider\";\nimport type { MessageQueryOptions } from \"../types\";\n\n/**\n * Interface for objects that provide a sql tagged template method.\n * This matches the Agent class's sql method signature.\n */\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/**\n * Session provider that wraps an Agent's SQLite storage.\n * Provides pure CRUD — compaction is handled by the Session wrapper.\n *\n * @example\n * ```typescript\n * import { Session, AgentSessionProvider } from \"agents/experimental/memory/session\";\n *\n * // In your Agent class:\n * session = new Session(new AgentSessionProvider(this));\n *\n * // With compaction options:\n * session = new Session(new AgentSessionProvider(this), {\n *   microCompaction: { truncateToolOutputs: 2000, keepRecent: 10 },\n *   compaction: { tokenThreshold: 20000, fn: summarize }\n * });\n * ```\n */\nexport class AgentSessionProvider implements SessionProvider {\n  private agent: SqlProvider;\n  private initialized = false;\n\n  constructor(agent: SqlProvider) {\n    this.agent = agent;\n  }\n\n  /**\n   * Ensure the messages table exists\n   */\n  private ensureTable(): void {\n    if (this.initialized) return;\n\n    this.agent.sql`\n      CREATE TABLE IF NOT EXISTS cf_agents_session_messages (\n        id TEXT PRIMARY KEY,\n        message TEXT NOT NULL,\n        created_at DATETIME DEFAULT CURRENT_TIMESTAMP\n      )\n    `;\n    this.initialized = true;\n  }\n\n  /**\n   * Get all messages in AI SDK format\n   */\n  getMessages(options?: MessageQueryOptions): UIMessage[] {\n    this.ensureTable();\n\n    if (\n      options?.limit !== undefined &&\n      (!Number.isInteger(options.limit) || options.limit < 0)\n    ) {\n      throw new Error(\"limit must be a non-negative integer\");\n    }\n    if (\n      options?.offset !== undefined &&\n      (!Number.isInteger(options.offset) || options.offset < 0)\n    ) {\n      throw new Error(\"offset must be a non-negative integer\");\n    }\n\n    type Row = { id: string; message: string; created_at: string };\n    const role = options?.role ?? null;\n    const before = options?.before?.toISOString() ?? null;\n    const after = options?.after?.toISOString() ?? null;\n    const limit = options?.limit ?? -1;\n    const offset = options?.offset ?? 0;\n\n    const rows = this.agent.sql<Row>`\n      SELECT id, message, created_at FROM cf_agents_session_messages\n      WHERE (${role} IS NULL OR json_extract(message, '$.role') = ${role})\n        AND (${before} IS NULL OR created_at < ${before})\n        AND (${after} IS NULL OR created_at > ${after})\n      ORDER BY created_at ASC, rowid ASC\n      LIMIT ${limit} OFFSET ${offset}\n    `;\n\n    return this.parseRows(rows);\n  }\n\n  /**\n   * Append one or more messages to storage.\n   */\n  async appendMessages(messages: UIMessage | UIMessage[]): Promise<void> {\n    this.ensureTable();\n\n    const messageArray = Array.isArray(messages) ? messages : [messages];\n    const now = new Date().toISOString();\n\n    for (const message of messageArray) {\n      const json = JSON.stringify(message);\n      this.agent.sql`\n        INSERT INTO cf_agents_session_messages (id, message, created_at)\n        VALUES (${message.id}, ${json}, ${now})\n        ON CONFLICT(id) DO UPDATE SET message = excluded.message\n      `;\n    }\n  }\n\n  /**\n   * Update an existing message\n   */\n  updateMessage(message: UIMessage): void {\n    this.ensureTable();\n\n    const json = JSON.stringify(message);\n    this.agent.sql`\n      UPDATE cf_agents_session_messages\n      SET message = ${json}\n      WHERE id = ${message.id}\n    `;\n  }\n\n  /**\n   * Delete messages by their IDs\n   */\n  deleteMessages(messageIds: string[]): void {\n    this.ensureTable();\n\n    for (const id of messageIds) {\n      this.agent.sql`DELETE FROM cf_agents_session_messages WHERE id = ${id}`;\n    }\n  }\n\n  /**\n   * Clear all messages from the session\n   */\n  clearMessages(): void {\n    this.ensureTable();\n    this.agent.sql`DELETE FROM cf_agents_session_messages`;\n  }\n\n  /**\n   * Get a single message by ID\n   */\n  getMessage(id: string): UIMessage | null {\n    this.ensureTable();\n\n    const rows = this.agent.sql<{ message: string }>`\n      SELECT message FROM cf_agents_session_messages WHERE id = ${id}\n    `;\n\n    if (rows.length === 0) return null;\n\n    try {\n      const parsed = JSON.parse(rows[0].message);\n      return this.isValidMessage(parsed) ? parsed : null;\n    } catch {\n      return null;\n    }\n  }\n\n  /**\n   * Get the last N messages (most recent)\n   */\n  getLastMessages(n: number): UIMessage[] {\n    this.ensureTable();\n\n    const rows = this.agent.sql<{ message: string }>`\n      SELECT message FROM cf_agents_session_messages\n      ORDER BY created_at DESC, rowid DESC\n      LIMIT ${n}\n    `;\n\n    return this.parseRows([...rows].reverse());\n  }\n\n  /**\n   * Fetch messages outside the recent window (for microCompaction).\n   * Returns all messages except the most recent `keepRecent`.\n   */\n  getOlderMessages(keepRecent: number): UIMessage[] {\n    this.ensureTable();\n\n    type Row = { id: string; message: string };\n    const rows = this.agent.sql<Row>`\n      SELECT id, message FROM cf_agents_session_messages\n      WHERE rowid NOT IN (\n        SELECT rowid FROM cf_agents_session_messages\n        ORDER BY created_at DESC, rowid DESC\n        LIMIT ${keepRecent}\n      )\n    `;\n\n    return this.parseRows(rows);\n  }\n\n  /**\n   * Bulk replace all messages.\n   * Preserves original created_at timestamps for surviving messages.\n   */\n  async replaceMessages(messages: UIMessage[]): Promise<void> {\n    this.ensureTable();\n\n    // Build timestamp map from existing messages before clearing\n    type Row = { id: string; created_at: string };\n    const existingRows = this.agent.sql<Row>`\n      SELECT id, created_at FROM cf_agents_session_messages\n    `;\n    const timestampMap = new Map<string, string>();\n    for (const row of existingRows) {\n      timestampMap.set(row.id, row.created_at);\n    }\n\n    // Durable Objects auto-coalesces all synchronous SQL writes within\n    // a single I/O gate into one atomic batch — no explicit transaction needed.\n    this.agent.sql`DELETE FROM cf_agents_session_messages`;\n\n    const now = new Date().toISOString();\n    for (const message of messages) {\n      const json = JSON.stringify(message);\n      const created_at = timestampMap.get(message.id) ?? now;\n      this.agent.sql`\n        INSERT INTO cf_agents_session_messages (id, message, created_at)\n        VALUES (${message.id}, ${json}, ${created_at})\n        ON CONFLICT(id) DO UPDATE SET message = excluded.message\n      `;\n    }\n  }\n\n  /**\n   * Validate message structure\n   */\n  private isValidMessage(msg: unknown): msg is UIMessage {\n    if (typeof msg !== \"object\" || msg === null) return false;\n    const m = msg as Record<string, unknown>;\n\n    if (typeof m.id !== \"string\" || m.id.length === 0) return false;\n    if (m.role !== \"user\" && m.role !== \"assistant\" && m.role !== \"system\") {\n      return false;\n    }\n    if (!Array.isArray(m.parts)) return false;\n\n    return true;\n  }\n\n  /**\n   * Parse message rows from SQL results into UIMessages.\n   */\n  private parseRows(rows: { id?: string; message: string }[]): UIMessage[] {\n    const messages: UIMessage[] = [];\n    for (const row of rows) {\n      try {\n        const parsed = JSON.parse(row.message);\n        if (this.isValidMessage(parsed)) {\n          messages.push(parsed);\n        }\n      } catch {\n        if (row.id) {\n          console.warn(\n            `[AgentSessionProvider] Skipping malformed message ${row.id}`\n          );\n        }\n      }\n    }\n    return messages;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/experimental/memory/utils/compaction.ts","../../../../src/experimental/memory/utils/tokens.ts","../../../../src/experimental/memory/session/session.ts","../../../../src/experimental/memory/session/providers/agent.ts"],"sourcesContent":["/**\n * MicroCompaction Utilities\n *\n * Internal pure functions for lightweight compaction (no LLM).\n * Not exported to users — used by the Session wrapper.\n */\n\nimport type { UIMessage } from \"ai\";\nimport type { MicroCompactionRules } from \"../session/types\";\n\n/** Default thresholds for microCompaction rules (in chars) */\nexport const DEFAULTS = {\n  truncateToolOutputs: 30000,\n  truncateText: 10000,\n  keepRecent: 4\n};\n\n/** Resolved microCompaction rules with actual numeric thresholds */\nexport interface ResolvedMicroCompactionRules {\n  truncateToolOutputs: number | false;\n  truncateText: number | false;\n  keepRecent: number;\n}\n\n/**\n * Parse microCompaction config into resolved rules.\n * Returns null if disabled.\n */\nexport function parseMicroCompactionRules(\n  config: boolean | MicroCompactionRules\n): ResolvedMicroCompactionRules | null {\n  if (config === false) return null;\n\n  if (config === true) {\n    return {\n      truncateToolOutputs: DEFAULTS.truncateToolOutputs,\n      truncateText: DEFAULTS.truncateText,\n      keepRecent: DEFAULTS.keepRecent\n    };\n  }\n\n  // Custom rules object — validate numeric values\n  const keepRecent = config.keepRecent ?? DEFAULTS.keepRecent;\n  if (!Number.isInteger(keepRecent) || keepRecent < 0) {\n    throw new Error(\"keepRecent must be a non-negative integer\");\n  }\n\n  const truncateToolOutputs =\n    config.truncateToolOutputs === false\n      ? false\n      : config.truncateToolOutputs === true ||\n          config.truncateToolOutputs === undefined\n        ? DEFAULTS.truncateToolOutputs\n        : config.truncateToolOutputs;\n  if (typeof truncateToolOutputs === \"number\" && truncateToolOutputs <= 0) {\n    throw new Error(\"truncateToolOutputs must be a positive number\");\n  }\n\n  const truncateText =\n    config.truncateText === false\n      ? false\n      : config.truncateText === true || config.truncateText === undefined\n        ? DEFAULTS.truncateText\n        : config.truncateText;\n  if (typeof truncateText === \"number\" && truncateText <= 0) {\n    throw new Error(\"truncateText must be a positive number\");\n  }\n\n  return { truncateToolOutputs, truncateText, keepRecent };\n}\n\n/**\n * Truncate oversized parts in a single message.\n * Returns the same reference if nothing changed (allows callers to skip no-op updates).\n */\nfunction truncateMessageParts(\n  msg: UIMessage,\n  rules: ResolvedMicroCompactionRules\n): UIMessage {\n  let changed = false;\n\n  const compactedParts = msg.parts.map((part) => {\n    // Truncate tool outputs\n    if (\n      rules.truncateToolOutputs !== false &&\n      (part.type.startsWith(\"tool-\") || part.type === \"dynamic-tool\") &&\n      \"output\" in part\n    ) {\n      const toolPart = part as { output?: unknown };\n      if (toolPart.output !== undefined) {\n        const outputJson = JSON.stringify(toolPart.output);\n        if (outputJson.length > rules.truncateToolOutputs) {\n          changed = true;\n          return {\n            ...part,\n            output: `[Truncated ${outputJson.length} bytes] ${outputJson.slice(0, 500)}...`\n          };\n        }\n      }\n    }\n\n    // Truncate long text parts\n    if (\n      rules.truncateText !== false &&\n      part.type === \"text\" &&\n      \"text\" in part\n    ) {\n      const textPart = part as { type: \"text\"; text: string };\n      if (textPart.text.length > rules.truncateText) {\n        changed = true;\n        return {\n          ...part,\n          text: `${textPart.text.slice(0, rules.truncateText)}... [truncated ${textPart.text.length} chars]`\n        };\n      }\n    }\n\n    return part;\n  });\n\n  return changed ? ({ ...msg, parts: compactedParts } as UIMessage) : msg;\n}\n\n/**\n * Apply microCompaction to an array of messages.\n * Returns same reference for unchanged messages (enables skip-update optimization).\n *\n * No keepRecent logic — the caller decides which messages to pass.\n */\nexport function microCompact(\n  messages: UIMessage[],\n  rules: ResolvedMicroCompactionRules\n): UIMessage[] {\n  return messages.map((msg) => truncateMessageParts(msg, rules));\n}\n","/**\n * Token Estimation Utilities\n *\n * IMPORTANT: These are heuristic estimates, not actual tokenizer counts.\n *\n * We intentionally avoid real tokenizers (e.g. tiktoken, sentencepiece) because:\n * - A single tiktoken instance costs ~80-120MB of heap\n * - Cloudflare Workers have tight memory limits (128MB)\n * - For compaction thresholds, a conservative estimate is sufficient\n *\n * The hybrid approach (max of character-based and word-based estimates) handles\n * both dense token content (JSON, code) and natural language reasonably well.\n *\n * Calibration notes:\n * - Character-based: ~4 chars per token (conservative, from OpenAI guidance)\n * - Word-based: ~1.3 tokens per word (empirical, from Mastra's memory system)\n * - Per-message overhead: ~4 tokens for role/framing (empirical)\n *\n * These ratios are tuned for English. CJK, emoji-heavy, or highly technical\n * content may have different ratios. The conservative estimates help ensure\n * compaction triggers before context windows are actually exceeded.\n */\n\nimport type { UIMessage } from \"ai\";\n\n/** Approximate characters per token for English text */\nexport const CHARS_PER_TOKEN = 4;\n\n/** Approximate token multiplier per whitespace-separated word */\nexport const WORDS_TOKEN_MULTIPLIER = 1.3;\n\n/** Approximate overhead tokens per message (role, framing) */\nexport const TOKENS_PER_MESSAGE = 4;\n\n/**\n * Estimate token count for a string using a hybrid heuristic.\n *\n * Takes the max of two estimates:\n * - Character-based: `length / 4` — better for dense content (JSON, code, URLs)\n * - Word-based: `words * 1.3` — better for natural language prose\n *\n * This is a heuristic. Do not use where exact counts are required.\n */\nexport function estimateStringTokens(text: string): number {\n  if (!text) return 0;\n  const charEstimate = text.length / CHARS_PER_TOKEN;\n  const wordEstimate =\n    text.split(/\\s+/).filter(Boolean).length * WORDS_TOKEN_MULTIPLIER;\n  return Math.ceil(Math.max(charEstimate, wordEstimate));\n}\n\n/**\n * Estimate total token count for an array of UIMessages.\n *\n * Walks each message's parts (text, tool invocations, tool results)\n * and applies per-message overhead.\n *\n * This is a heuristic. Do not use where exact counts are required.\n */\nexport function estimateMessageTokens(messages: UIMessage[]): number {\n  let tokens = 0;\n  for (const msg of messages) {\n    tokens += TOKENS_PER_MESSAGE;\n    for (const part of msg.parts) {\n      if (part.type === \"text\") {\n        tokens += estimateStringTokens(\n          (part as { type: \"text\"; text: string }).text\n        );\n      } else if (\n        part.type.startsWith(\"tool-\") ||\n        part.type === \"dynamic-tool\"\n      ) {\n        const toolPart = part as { input?: unknown; output?: unknown };\n        if (toolPart.input) {\n          tokens += estimateStringTokens(JSON.stringify(toolPart.input));\n        }\n        if (toolPart.output) {\n          tokens += estimateStringTokens(JSON.stringify(toolPart.output));\n        }\n      }\n    }\n  }\n  return tokens;\n}\n","/**\n * Session — top-level API for conversation history with compaction.\n *\n * Wraps any SessionProvider (pure storage) and orchestrates compaction:\n * - microCompaction on every append() — cheap, no LLM\n * - full compaction when token threshold exceeded — user-supplied fn\n */\n\nimport type { UIMessage } from \"ai\";\nimport type { SessionProvider } from \"./provider\";\nimport type {\n  MessageQueryOptions,\n  SessionProviderOptions,\n  CompactResult\n} from \"./types\";\nimport {\n  parseMicroCompactionRules,\n  microCompact,\n  type ResolvedMicroCompactionRules\n} from \"../utils/compaction\";\nimport { estimateMessageTokens } from \"../utils/tokens\";\n\nexport class Session {\n  private storage: SessionProvider;\n  private microCompactionRules: ResolvedMicroCompactionRules | null;\n  private compactionConfig: SessionProviderOptions[\"compaction\"] | null;\n\n  constructor(storage: SessionProvider, options?: SessionProviderOptions) {\n    this.storage = storage;\n\n    const mc = options?.microCompaction ?? true;\n    this.microCompactionRules = parseMicroCompactionRules(mc);\n    this.compactionConfig = options?.compaction ?? null;\n  }\n\n  // ── Read (delegated to storage) ────────────────────────────────────\n\n  getMessages(options?: MessageQueryOptions): UIMessage[] {\n    return this.storage.getMessages(options);\n  }\n\n  getMessage(id: string): UIMessage | null {\n    return this.storage.getMessage(id);\n  }\n\n  getLastMessages(n: number): UIMessage[] {\n    return this.storage.getLastMessages(n);\n  }\n\n  // ── Write (delegated + compaction) ─────────────────────────────────\n\n  async append(messages: UIMessage | UIMessage[]): Promise<void> {\n    // 1. Storage inserts\n    await this.storage.appendMessages(messages);\n\n    // 2. Full compaction if token threshold exceeded — runs instead of microCompaction\n    if (this.shouldAutoCompact()) {\n      const result = await this.compact();\n      if (result.success) return;\n      // Fall through to microCompaction if full compaction failed\n    }\n\n    // 3. MicroCompaction on older messages (only if no full compaction)\n    if (this.microCompactionRules) {\n      const rules = this.microCompactionRules;\n      const older = this.storage.getOlderMessages(rules.keepRecent);\n\n      if (older.length > 0) {\n        const compacted = microCompact(older, rules);\n        for (let i = 0; i < older.length; i++) {\n          if (compacted[i] !== older[i]) {\n            this.storage.updateMessage(compacted[i]);\n          }\n        }\n      }\n    }\n  }\n\n  updateMessage(message: UIMessage): void {\n    this.storage.updateMessage(message);\n  }\n\n  deleteMessages(messageIds: string[]): void {\n    this.storage.deleteMessages(messageIds);\n  }\n\n  clearMessages(): void {\n    this.storage.clearMessages();\n  }\n\n  // ── Compaction ─────────────────────────────────────────────────────\n\n  async compact(): Promise<CompactResult> {\n    const messages = this.storage.getMessages();\n\n    if (messages.length === 0) {\n      return { success: true };\n    }\n\n    try {\n      let result = messages;\n\n      if (this.compactionConfig?.fn) {\n        result = await this.compactionConfig.fn(result);\n      }\n\n      await this.storage.replaceMessages(result);\n\n      return { success: true };\n    } catch (err) {\n      return {\n        success: false,\n        error: err instanceof Error ? err.message : String(err)\n      };\n    }\n  }\n\n  /**\n   * Pre-check for auto-compaction using token estimate heuristic.\n   */\n  private shouldAutoCompact(): boolean {\n    if (!this.compactionConfig?.tokenThreshold) return false;\n\n    const messages = this.storage.getMessages();\n    const approxTokens = estimateMessageTokens(messages);\n    return approxTokens > this.compactionConfig.tokenThreshold;\n  }\n}\n","/**\n * Agent Session Provider\n *\n * Pure storage provider that uses the Agent's DO SQLite storage.\n * Compaction is orchestrated by the Session wrapper, not here.\n */\n\nimport type { UIMessage } from \"ai\";\nimport type { SessionProvider } from \"../provider\";\nimport type { MessageQueryOptions } from \"../types\";\n\n/**\n * Interface for objects that provide a sql tagged template method.\n * This matches the Agent class's sql method signature.\n */\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/**\n * Session provider that wraps an Agent's SQLite storage.\n * Provides pure CRUD — compaction is handled by the Session wrapper.\n *\n * @example\n * ```typescript\n * import { Session, AgentSessionProvider } from \"agents/experimental/memory/session\";\n *\n * // In your Agent class:\n * session = new Session(new AgentSessionProvider(this));\n *\n * // With compaction options:\n * session = new Session(new AgentSessionProvider(this), {\n *   microCompaction: { truncateToolOutputs: 2000, keepRecent: 10 },\n *   compaction: { tokenThreshold: 20000, fn: summarize }\n * });\n * ```\n */\nexport class AgentSessionProvider implements SessionProvider {\n  private agent: SqlProvider;\n  private initialized = false;\n\n  constructor(agent: SqlProvider) {\n    this.agent = agent;\n  }\n\n  /**\n   * Ensure the messages table exists\n   */\n  private ensureTable(): void {\n    if (this.initialized) return;\n\n    this.agent.sql`\n      CREATE TABLE IF NOT EXISTS cf_agents_session_messages (\n        id TEXT PRIMARY KEY,\n        message TEXT NOT NULL,\n        created_at DATETIME DEFAULT CURRENT_TIMESTAMP\n      )\n    `;\n    this.initialized = true;\n  }\n\n  /**\n   * Get all messages in AI SDK format\n   */\n  getMessages(options?: MessageQueryOptions): UIMessage[] {\n    this.ensureTable();\n\n    if (\n      options?.limit !== undefined &&\n      (!Number.isInteger(options.limit) || options.limit < 0)\n    ) {\n      throw new Error(\"limit must be a non-negative integer\");\n    }\n    if (\n      options?.offset !== undefined &&\n      (!Number.isInteger(options.offset) || options.offset < 0)\n    ) {\n      throw new Error(\"offset must be a non-negative integer\");\n    }\n\n    type Row = { id: string; message: string; created_at: string };\n    const role = options?.role ?? null;\n    const before = options?.before?.toISOString() ?? null;\n    const after = options?.after?.toISOString() ?? null;\n    const limit = options?.limit ?? -1;\n    const offset = options?.offset ?? 0;\n\n    const rows = this.agent.sql<Row>`\n      SELECT id, message, created_at FROM cf_agents_session_messages\n      WHERE (${role} IS NULL OR json_extract(message, '$.role') = ${role})\n        AND (${before} IS NULL OR created_at < ${before})\n        AND (${after} IS NULL OR created_at > ${after})\n      ORDER BY created_at ASC, rowid ASC\n      LIMIT ${limit} OFFSET ${offset}\n    `;\n\n    return this.parseRows(rows);\n  }\n\n  /**\n   * Append one or more messages to storage.\n   */\n  async appendMessages(messages: UIMessage | UIMessage[]): Promise<void> {\n    this.ensureTable();\n\n    const messageArray = Array.isArray(messages) ? messages : [messages];\n    const now = new Date().toISOString();\n\n    for (const message of messageArray) {\n      const json = JSON.stringify(message);\n      this.agent.sql`\n        INSERT INTO cf_agents_session_messages (id, message, created_at)\n        VALUES (${message.id}, ${json}, ${now})\n        ON CONFLICT(id) DO UPDATE SET message = excluded.message\n      `;\n    }\n  }\n\n  /**\n   * Update an existing message\n   */\n  updateMessage(message: UIMessage): void {\n    this.ensureTable();\n\n    const json = JSON.stringify(message);\n    this.agent.sql`\n      UPDATE cf_agents_session_messages\n      SET message = ${json}\n      WHERE id = ${message.id}\n    `;\n  }\n\n  /**\n   * Delete messages by their IDs\n   */\n  deleteMessages(messageIds: string[]): void {\n    this.ensureTable();\n\n    for (const id of messageIds) {\n      this.agent.sql`DELETE FROM cf_agents_session_messages WHERE id = ${id}`;\n    }\n  }\n\n  /**\n   * Clear all messages from the session\n   */\n  clearMessages(): void {\n    this.ensureTable();\n    this.agent.sql`DELETE FROM cf_agents_session_messages`;\n  }\n\n  /**\n   * Get a single message by ID\n   */\n  getMessage(id: string): UIMessage | null {\n    this.ensureTable();\n\n    const rows = this.agent.sql<{ message: string }>`\n      SELECT message FROM cf_agents_session_messages WHERE id = ${id}\n    `;\n\n    if (rows.length === 0) return null;\n\n    try {\n      const parsed = JSON.parse(rows[0].message);\n      return this.isValidMessage(parsed) ? parsed : null;\n    } catch {\n      return null;\n    }\n  }\n\n  /**\n   * Get the last N messages (most recent)\n   */\n  getLastMessages(n: number): UIMessage[] {\n    this.ensureTable();\n\n    const rows = this.agent.sql<{ message: string }>`\n      SELECT message FROM cf_agents_session_messages\n      ORDER BY created_at DESC, rowid DESC\n      LIMIT ${n}\n    `;\n\n    return this.parseRows([...rows].reverse());\n  }\n\n  /**\n   * Fetch messages outside the recent window (for microCompaction).\n   * Returns all messages except the most recent `keepRecent`.\n   */\n  getOlderMessages(keepRecent: number): UIMessage[] {\n    this.ensureTable();\n\n    type Row = { id: string; message: string };\n    const rows = this.agent.sql<Row>`\n      SELECT id, message FROM cf_agents_session_messages\n      WHERE rowid NOT IN (\n        SELECT rowid FROM cf_agents_session_messages\n        ORDER BY created_at DESC, rowid DESC\n        LIMIT ${keepRecent}\n      )\n    `;\n\n    return this.parseRows(rows);\n  }\n\n  /**\n   * Bulk replace all messages.\n   * Preserves original created_at timestamps for surviving messages.\n   */\n  async replaceMessages(messages: UIMessage[]): Promise<void> {\n    this.ensureTable();\n\n    // Build timestamp map from existing messages before clearing\n    type Row = { id: string; created_at: string };\n    const existingRows = this.agent.sql<Row>`\n      SELECT id, created_at FROM cf_agents_session_messages\n    `;\n    const timestampMap = new Map<string, string>();\n    for (const row of existingRows) {\n      timestampMap.set(row.id, row.created_at);\n    }\n\n    // Durable Objects auto-coalesces all synchronous SQL writes within\n    // a single I/O gate into one atomic batch — no explicit transaction needed.\n    this.agent.sql`DELETE FROM cf_agents_session_messages`;\n\n    const now = new Date().toISOString();\n    for (const message of messages) {\n      const json = JSON.stringify(message);\n      const created_at = timestampMap.get(message.id) ?? now;\n      this.agent.sql`\n        INSERT INTO cf_agents_session_messages (id, message, created_at)\n        VALUES (${message.id}, ${json}, ${created_at})\n        ON CONFLICT(id) DO UPDATE SET message = excluded.message\n      `;\n    }\n  }\n\n  /**\n   * Validate message structure\n   */\n  private isValidMessage(msg: unknown): msg is UIMessage {\n    if (typeof msg !== \"object\" || msg === null) return false;\n    const m = msg as Record<string, unknown>;\n\n    if (typeof m.id !== \"string\" || m.id.length === 0) return false;\n    if (m.role !== \"user\" && m.role !== \"assistant\" && m.role !== \"system\") {\n      return false;\n    }\n    if (!Array.isArray(m.parts)) return false;\n\n    return true;\n  }\n\n  /**\n   * Parse message rows from SQL results into UIMessages.\n   */\n  private parseRows(rows: { id?: string; message: string }[]): UIMessage[] {\n    const messages: UIMessage[] = [];\n    for (const row of rows) {\n      try {\n        const parsed = JSON.parse(row.message);\n        if (this.isValidMessage(parsed)) {\n          messages.push(parsed);\n        }\n      } catch {\n        if (row.id) {\n          console.warn(\n            `[AgentSessionProvider] Skipping malformed message ${row.id}`\n          );\n        }\n      }\n    }\n    return messages;\n  }\n}\n"],"mappings":";;AAWA,MAAa,WAAW;CACtB,qBAAqB;CACrB,cAAc;CACd,YAAY;CACb;;;;;AAaD,SAAgB,0BACd,QACqC;AACrC,KAAI,WAAW,MAAO,QAAO;AAE7B,KAAI,WAAW,KACb,QAAO;EACL,qBAAqB,SAAS;EAC9B,cAAc,SAAS;EACvB,YAAY,SAAS;EACtB;CAIH,MAAM,aAAa,OAAO,cAAc,SAAS;AACjD,KAAI,CAAC,OAAO,UAAU,WAAW,IAAI,aAAa,EAChD,OAAM,IAAI,MAAM,4CAA4C;CAG9D,MAAM,sBACJ,OAAO,wBAAwB,QAC3B,QACA,OAAO,wBAAwB,QAC7B,OAAO,wBAAwB,KAAA,IAC/B,SAAS,sBACT,OAAO;AACf,KAAI,OAAO,wBAAwB,YAAY,uBAAuB,EACpE,OAAM,IAAI,MAAM,gDAAgD;CAGlE,MAAM,eACJ,OAAO,iBAAiB,QACpB,QACA,OAAO,iBAAiB,QAAQ,OAAO,iBAAiB,KAAA,IACtD,SAAS,eACT,OAAO;AACf,KAAI,OAAO,iBAAiB,YAAY,gBAAgB,EACtD,OAAM,IAAI,MAAM,yCAAyC;AAG3D,QAAO;EAAE;EAAqB;EAAc;EAAY;;;;;;AAO1D,SAAS,qBACP,KACA,OACW;CACX,IAAI,UAAU;CAEd,MAAM,iBAAiB,IAAI,MAAM,KAAK,SAAS;AAE7C,MACE,MAAM,wBAAwB,UAC7B,KAAK,KAAK,WAAW,QAAQ,IAAI,KAAK,SAAS,mBAChD,YAAY,MACZ;GACA,MAAM,WAAW;AACjB,OAAI,SAAS,WAAW,KAAA,GAAW;IACjC,MAAM,aAAa,KAAK,UAAU,SAAS,OAAO;AAClD,QAAI,WAAW,SAAS,MAAM,qBAAqB;AACjD,eAAU;AACV,YAAO;MACL,GAAG;MACH,QAAQ,cAAc,WAAW,OAAO,UAAU,WAAW,MAAM,GAAG,IAAI,CAAC;MAC5E;;;;AAMP,MACE,MAAM,iBAAiB,SACvB,KAAK,SAAS,UACd,UAAU,MACV;GACA,MAAM,WAAW;AACjB,OAAI,SAAS,KAAK,SAAS,MAAM,cAAc;AAC7C,cAAU;AACV,WAAO;KACL,GAAG;KACH,MAAM,GAAG,SAAS,KAAK,MAAM,GAAG,MAAM,aAAa,CAAC,iBAAiB,SAAS,KAAK,OAAO;KAC3F;;;AAIL,SAAO;GACP;AAEF,QAAO,UAAW;EAAE,GAAG;EAAK,OAAO;EAAgB,GAAiB;;;;;;;;AAStE,SAAgB,aACd,UACA,OACa;AACb,QAAO,SAAS,KAAK,QAAQ,qBAAqB,KAAK,MAAM,CAAC;;;ACxGhE,MAAa,yBAAyB;;;;;;;;;;AActC,SAAgB,qBAAqB,MAAsB;AACzD,KAAI,CAAC,KAAM,QAAO;CAClB,MAAM,eAAe,KAAK,SAAA;CAC1B,MAAM,eACJ,KAAK,MAAM,MAAM,CAAC,OAAO,QAAQ,CAAC,SAAS;AAC7C,QAAO,KAAK,KAAK,KAAK,IAAI,cAAc,aAAa,CAAC;;;;;;;;;;AAWxD,SAAgB,sBAAsB,UAA+B;CACnE,IAAI,SAAS;AACb,MAAK,MAAM,OAAO,UAAU;AAC1B,YAAA;AACA,OAAK,MAAM,QAAQ,IAAI,MACrB,KAAI,KAAK,SAAS,OAChB,WAAU,qBACP,KAAwC,KAC1C;WAED,KAAK,KAAK,WAAW,QAAQ,IAC7B,KAAK,SAAS,gBACd;GACA,MAAM,WAAW;AACjB,OAAI,SAAS,MACX,WAAU,qBAAqB,KAAK,UAAU,SAAS,MAAM,CAAC;AAEhE,OAAI,SAAS,OACX,WAAU,qBAAqB,KAAK,UAAU,SAAS,OAAO,CAAC;;;AAKvE,QAAO;;;;AC5DT,IAAa,UAAb,MAAqB;CAKnB,YAAY,SAA0B,SAAkC;AACtE,OAAK,UAAU;AAGf,OAAK,uBAAuB,0BADjB,SAAS,mBAAmB,KACkB;AACzD,OAAK,mBAAmB,SAAS,cAAc;;CAKjD,YAAY,SAA4C;AACtD,SAAO,KAAK,QAAQ,YAAY,QAAQ;;CAG1C,WAAW,IAA8B;AACvC,SAAO,KAAK,QAAQ,WAAW,GAAG;;CAGpC,gBAAgB,GAAwB;AACtC,SAAO,KAAK,QAAQ,gBAAgB,EAAE;;CAKxC,MAAM,OAAO,UAAkD;AAE7D,QAAM,KAAK,QAAQ,eAAe,SAAS;AAG3C,MAAI,KAAK,mBAAmB;QACX,MAAM,KAAK,SAAS,EACxB,QAAS;;AAKtB,MAAI,KAAK,sBAAsB;GAC7B,MAAM,QAAQ,KAAK;GACnB,MAAM,QAAQ,KAAK,QAAQ,iBAAiB,MAAM,WAAW;AAE7D,OAAI,MAAM,SAAS,GAAG;IACpB,MAAM,YAAY,aAAa,OAAO,MAAM;AAC5C,SAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,IAChC,KAAI,UAAU,OAAO,MAAM,GACzB,MAAK,QAAQ,cAAc,UAAU,GAAG;;;;CAOlD,cAAc,SAA0B;AACtC,OAAK,QAAQ,cAAc,QAAQ;;CAGrC,eAAe,YAA4B;AACzC,OAAK,QAAQ,eAAe,WAAW;;CAGzC,gBAAsB;AACpB,OAAK,QAAQ,eAAe;;CAK9B,MAAM,UAAkC;EACtC,MAAM,WAAW,KAAK,QAAQ,aAAa;AAE3C,MAAI,SAAS,WAAW,EACtB,QAAO,EAAE,SAAS,MAAM;AAG1B,MAAI;GACF,IAAI,SAAS;AAEb,OAAI,KAAK,kBAAkB,GACzB,UAAS,MAAM,KAAK,iBAAiB,GAAG,OAAO;AAGjD,SAAM,KAAK,QAAQ,gBAAgB,OAAO;AAE1C,UAAO,EAAE,SAAS,MAAM;WACjB,KAAK;AACZ,UAAO;IACL,SAAS;IACT,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;IACxD;;;;;;CAOL,oBAAqC;AACnC,MAAI,CAAC,KAAK,kBAAkB,eAAgB,QAAO;AAInD,SADqB,sBADJ,KAAK,QAAQ,aAAa,CACS,GAC9B,KAAK,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;ACrFhD,IAAa,uBAAb,MAA6D;CAI3D,YAAY,OAAoB;AAFhC,OAAQ,cAAc;AAGpB,OAAK,QAAQ;;;;;CAMf,cAA4B;AAC1B,MAAI,KAAK,YAAa;AAEtB,OAAK,MAAM,GAAG;;;;;;;AAOd,OAAK,cAAc;;;;;CAMrB,YAAY,SAA4C;AACtD,OAAK,aAAa;AAElB,MACE,SAAS,UAAU,KAAA,MAClB,CAAC,OAAO,UAAU,QAAQ,MAAM,IAAI,QAAQ,QAAQ,GAErD,OAAM,IAAI,MAAM,uCAAuC;AAEzD,MACE,SAAS,WAAW,KAAA,MACnB,CAAC,OAAO,UAAU,QAAQ,OAAO,IAAI,QAAQ,SAAS,GAEvD,OAAM,IAAI,MAAM,wCAAwC;EAI1D,MAAM,OAAO,SAAS,QAAQ;EAC9B,MAAM,SAAS,SAAS,QAAQ,aAAa,IAAI;EACjD,MAAM,QAAQ,SAAS,OAAO,aAAa,IAAI;EAC/C,MAAM,QAAQ,SAAS,SAAS;EAChC,MAAM,SAAS,SAAS,UAAU;EAElC,MAAM,OAAO,KAAK,MAAM,GAAQ;;eAErB,KAAK,gDAAgD,KAAK;eAC1D,OAAO,2BAA2B,OAAO;eACzC,MAAM,2BAA2B,MAAM;;cAExC,MAAM,UAAU,OAAO;;AAGjC,SAAO,KAAK,UAAU,KAAK;;;;;CAM7B,MAAM,eAAe,UAAkD;AACrE,OAAK,aAAa;EAElB,MAAM,eAAe,MAAM,QAAQ,SAAS,GAAG,WAAW,CAAC,SAAS;EACpE,MAAM,uBAAM,IAAI,MAAM,EAAC,aAAa;AAEpC,OAAK,MAAM,WAAW,cAAc;GAClC,MAAM,OAAO,KAAK,UAAU,QAAQ;AACpC,QAAK,MAAM,GAAG;;kBAEF,QAAQ,GAAG,IAAI,KAAK,IAAI,IAAI;;;;;;;;CAS5C,cAAc,SAA0B;AACtC,OAAK,aAAa;EAElB,MAAM,OAAO,KAAK,UAAU,QAAQ;AACpC,OAAK,MAAM,GAAG;;sBAEI,KAAK;mBACR,QAAQ,GAAG;;;;;;CAO5B,eAAe,YAA4B;AACzC,OAAK,aAAa;AAElB,OAAK,MAAM,MAAM,WACf,MAAK,MAAM,GAAG,qDAAqD;;;;;CAOvE,gBAAsB;AACpB,OAAK,aAAa;AAClB,OAAK,MAAM,GAAG;;;;;CAMhB,WAAW,IAA8B;AACvC,OAAK,aAAa;EAElB,MAAM,OAAO,KAAK,MAAM,GAAwB;kEACc,GAAG;;AAGjE,MAAI,KAAK,WAAW,EAAG,QAAO;AAE9B,MAAI;GACF,MAAM,SAAS,KAAK,MAAM,KAAK,GAAG,QAAQ;AAC1C,UAAO,KAAK,eAAe,OAAO,GAAG,SAAS;UACxC;AACN,UAAO;;;;;;CAOX,gBAAgB,GAAwB;AACtC,OAAK,aAAa;EAElB,MAAM,OAAO,KAAK,MAAM,GAAwB;;;cAGtC,EAAE;;AAGZ,SAAO,KAAK,UAAU,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC;;;;;;CAO5C,iBAAiB,YAAiC;AAChD,OAAK,aAAa;EAGlB,MAAM,OAAO,KAAK,MAAM,GAAQ;;;;;gBAKpB,WAAW;;;AAIvB,SAAO,KAAK,UAAU,KAAK;;;;;;CAO7B,MAAM,gBAAgB,UAAsC;AAC1D,OAAK,aAAa;EAIlB,MAAM,eAAe,KAAK,MAAM,GAAQ;;;EAGxC,MAAM,+BAAe,IAAI,KAAqB;AAC9C,OAAK,MAAM,OAAO,aAChB,cAAa,IAAI,IAAI,IAAI,IAAI,WAAW;AAK1C,OAAK,MAAM,GAAG;EAEd,MAAM,uBAAM,IAAI,MAAM,EAAC,aAAa;AACpC,OAAK,MAAM,WAAW,UAAU;GAC9B,MAAM,OAAO,KAAK,UAAU,QAAQ;GACpC,MAAM,aAAa,aAAa,IAAI,QAAQ,GAAG,IAAI;AACnD,QAAK,MAAM,GAAG;;kBAEF,QAAQ,GAAG,IAAI,KAAK,IAAI,WAAW;;;;;;;;CASnD,eAAuB,KAAgC;AACrD,MAAI,OAAO,QAAQ,YAAY,QAAQ,KAAM,QAAO;EACpD,MAAM,IAAI;AAEV,MAAI,OAAO,EAAE,OAAO,YAAY,EAAE,GAAG,WAAW,EAAG,QAAO;AAC1D,MAAI,EAAE,SAAS,UAAU,EAAE,SAAS,eAAe,EAAE,SAAS,SAC5D,QAAO;AAET,MAAI,CAAC,MAAM,QAAQ,EAAE,MAAM,CAAE,QAAO;AAEpC,SAAO;;;;;CAMT,UAAkB,MAAuD;EACvE,MAAM,WAAwB,EAAE;AAChC,OAAK,MAAM,OAAO,KAChB,KAAI;GACF,MAAM,SAAS,KAAK,MAAM,IAAI,QAAQ;AACtC,OAAI,KAAK,eAAe,OAAO,CAC7B,UAAS,KAAK,OAAO;UAEjB;AACN,OAAI,IAAI,GACN,SAAQ,KACN,qDAAqD,IAAI,KAC1D;;AAIP,SAAO"}

package/dist/experimental/workspace.d.ts

@@ -0,0 +1,273 @@
+import { Command, CommandContext, CustomCommand, ExecResult, NetworkConfig, defineCommand } from "just-bash";
+
+//#region src/experimental/workspace.d.ts
+/**
+ * Workspace — durable file storage for any Agent.
+ *
+ * Hybrid storage:
+ *   - Files < threshold: stored inline in SQLite (fast, no external calls)
+ *   - Files ≥ threshold: metadata in SQLite, content in R2 (avoids row limit)
+ *
+ * Usage:
+ *   ```ts
+ *   import { Agent } from "agents";
+ *   import { Workspace } from "agents/experimental/workspace";
+ *
+ *   class MyAgent extends Agent<Env> {
+ *     workspace = new Workspace(this, {
+ *       r2: this.env.WORKSPACE_FILES,
+ *       // r2Prefix defaults to this.name (the Durable Object ID)
+ *     });
+ *
+ *     async onMessage(conn, msg) {
+ *       await this.workspace.writeFile("/hello.txt", "world");
+ *       const content = await this.workspace.readFile("/hello.txt");
+ *     }
+ *   }
+ *   ```
+ *
+ * R2 is optional — if the configured binding isn't present, all files are
+ * stored inline regardless of size (with a warning for large files).
+ *
+ * @module agents/workspace
+ */
+interface WorkspaceHost {
+  sql: <T = Record<string, string | number | boolean | null>>(strings: TemplateStringsArray, ...values: (string | number | boolean | null)[]) => T[];
+  /** Durable Object ID / name — used as the default R2 key prefix when r2Prefix is not set. Read lazily (not at construction time). */
+  name?: string;
+}
+interface WorkspaceOptions {
+  /** Namespace to isolate this workspace's tables (default: "default"). */
+  namespace?: string;
+  /** R2 bucket for large-file storage (optional). */
+  r2?: R2Bucket;
+  /** Prefix for R2 object keys. Defaults to `host.name` (the Durable Object ID) when omitted. */
+  r2Prefix?: string;
+  /** Byte threshold for spilling files to R2 (default: 1_500_000 = 1.5 MB). */
+  inlineThreshold?: number;
+  /** Bash execution limits (requires just-bash). */
+  bashLimits?: {
+    maxCommandCount?: number;
+    maxLoopIterations?: number;
+    maxCallDepth?: number;
+  };
+  /** Custom commands available in every bash() call. */
+  commands?: CustomCommand[];
+  /** Environment variables available in every bash() call. */
+  env?: Record<string, string>;
+  /** Network configuration for curl (URL allow-list, methods, timeouts). */
+  network?: NetworkConfig;
+  /** Called when files/directories change. Wire to agent.broadcast() for real-time sync. */
+  onChange?: (event: WorkspaceChangeEvent) => void;
+}
+type EntryType = "file" | "directory" | "symlink";
+type FileInfo = {
+  path: string;
+  name: string;
+  type: EntryType;
+  mimeType: string;
+  size: number;
+  createdAt: number;
+  updatedAt: number;
+  target?: string;
+};
+type FileStat = FileInfo;
+type BashResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+interface BashOptions {
+  cwd?: string;
+  commands?: CustomCommand[];
+  env?: Record<string, string>;
+  network?: NetworkConfig;
+}
+/** @deprecated Use {@link BashOptions} instead. */
+type BashSessionOptions = BashOptions;
+type WorkspaceChangeType = "create" | "update" | "delete";
+type WorkspaceChangeEvent = {
+  type: WorkspaceChangeType;
+  path: string;
+  entryType: EntryType;
+};
+declare class Workspace {
+  private readonly host;
+  private readonly namespace;
+  private readonly tableName;
+  private readonly indexName;
+  private readonly r2;
+  private readonly r2Prefix;
+  private readonly threshold;
+  private readonly bashLimits;
+  private readonly commands;
+  private readonly env;
+  private readonly network;
+  private readonly onChange;
+  private initialized;
+  private readonly sqlCache;
+  /**
+   * @param host - Any object with a `sql` tagged-template method (typically your Agent: `this`).
+   * @param options - Optional configuration (namespace, R2 bucket, thresholds, etc.).
+   *
+   * ```ts
+   * class MyAgent extends Agent<Env> {
+   *   workspace = new Workspace(this, {
+   *     r2: this.env.WORKSPACE_FILES,
+   *     // r2Prefix defaults to this.name (the Durable Object ID)
+   *   });
+   * }
+   * ```
+   */
+  constructor(host: WorkspaceHost, options?: WorkspaceOptions);
+  private emit;
+  private _observe;
+  private sql;
+  private ensureInit;
+  private getR2;
+  private resolveR2Prefix;
+  private r2Key;
+  private resolveSymlink;
+  symlink(target: string, linkPath: string): void;
+  readlink(path: string): string;
+  lstat(path: string): FileStat | null;
+  stat(path: string): FileStat | null;
+  readFile(path: string): Promise<string | null>;
+  readFileBytes(path: string): Promise<Uint8Array | null>;
+  writeFileBytes(path: string, data: Uint8Array | ArrayBuffer, mimeType?: string): Promise<void>;
+  writeFile(path: string, content: string, mimeType?: string): Promise<void>;
+  readFileStream(path: string): Promise<ReadableStream<Uint8Array> | null>;
+  writeFileStream(path: string, stream: ReadableStream<Uint8Array>, mimeType?: string): Promise<void>;
+  appendFile(path: string, content: string, mimeType?: string): Promise<void>;
+  deleteFile(path: string): Promise<boolean>;
+  fileExists(path: string): boolean;
+  exists(path: string): boolean;
+  readDir(dir?: string, opts?: {
+    limit?: number;
+    offset?: number;
+  }): FileInfo[];
+  glob(pattern: string): FileInfo[];
+  mkdir(path: string, opts?: {
+    recursive?: boolean;
+  }, _depth?: number): void;
+  rm(path: string, opts?: {
+    recursive?: boolean;
+    force?: boolean;
+  }): Promise<void>;
+  cp(src: string, dest: string, opts?: {
+    recursive?: boolean;
+  }): Promise<void>;
+  mv(src: string, dest: string, opts?: {
+    recursive?: boolean;
+  }): Promise<void>;
+  diff(pathA: string, pathB: string): Promise<string>;
+  diffContent(path: string, newContent: string): Promise<string>;
+  private _resolveBashConfig;
+  bash(command: string, options?: BashOptions): Promise<BashResult>;
+  createBashSession(options?: BashOptions): BashSession;
+  getWorkspaceInfo(): {
+    fileCount: number;
+    directoryCount: number;
+    totalBytes: number;
+    r2FileCount: number;
+  };
+  /** @internal */
+  _getAllPaths(): string[];
+  /** @internal */
+  _updateModifiedAt(path: string, mtime: Date): void;
+  private ensureParentDir;
+  private deleteDescendants;
+}
+interface BashSessionInit {
+  ws: Workspace;
+  fs: WorkspaceFileSystem;
+  bashLimits: {
+    maxCommandCount: number;
+    maxLoopIterations: number;
+    maxCallDepth: number;
+  };
+  commands: CustomCommand[] | undefined;
+  env: Record<string, string>;
+  network: NetworkConfig | undefined;
+  cwd: string;
+  observe: (type: string, payload: Record<string, unknown>) => void;
+}
+declare class BashSession {
+  private readonly _ws;
+  private readonly _fs;
+  private readonly _bashLimits;
+  private readonly _customCommands;
+  private readonly _networkConfig;
+  private readonly _observe;
+  private _currentCwd;
+  private _currentEnv;
+  private _closed;
+  /** @internal — use workspace.createBashSession() instead */
+  constructor(init: BashSessionInit);
+  exec(command: string): Promise<BashResult>;
+  get cwd(): string;
+  get env(): Record<string, string>;
+  get isClosed(): boolean;
+  close(): void;
+  [Symbol.dispose](): void;
+}
+interface FsStat {
+  isFile: boolean;
+  isDirectory: boolean;
+  isSymbolicLink: boolean;
+  mode: number;
+  size: number;
+  mtime: Date;
+}
+interface DirentEntry {
+  name: string;
+  isFile: boolean;
+  isDirectory: boolean;
+  isSymbolicLink: boolean;
+}
+type FileContent = string | Uint8Array;
+type BufferEncoding = "utf-8" | "utf8" | "ascii" | "base64" | "hex" | "latin1";
+type ReadFileOptions = {
+  encoding?: BufferEncoding | null;
+};
+type WriteFileOptions = {
+  encoding?: BufferEncoding;
+};
+type MkdirOptions = {
+  recursive?: boolean;
+};
+type RmOptions = {
+  recursive?: boolean;
+  force?: boolean;
+};
+type CpOptions = {
+  recursive?: boolean;
+};
+declare class WorkspaceFileSystem {
+  private ws;
+  constructor(ws: Workspace);
+  readFile(path: string, _options?: ReadFileOptions | BufferEncoding): Promise<string>;
+  readFileBuffer(path: string): Promise<Uint8Array>;
+  writeFile(path: string, content: FileContent, _options?: WriteFileOptions | BufferEncoding): Promise<void>;
+  appendFile(path: string, content: FileContent, _options?: WriteFileOptions | BufferEncoding): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  stat(path: string): Promise<FsStat>;
+  lstat(path: string): Promise<FsStat>;
+  mkdir(path: string, options?: MkdirOptions): Promise<void>;
+  readdir(path: string): Promise<string[]>;
+  readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
+  rm(path: string, options?: RmOptions): Promise<void>;
+  cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+  mv(src: string, dest: string): Promise<void>;
+  resolvePath(base: string, path: string): string;
+  getAllPaths(): string[];
+  chmod(_path: string, _mode: number): Promise<void>;
+  symlink(target: string, linkPath: string): Promise<void>;
+  link(_existingPath: string, _newPath: string): Promise<void>;
+  readlink(path: string): Promise<string>;
+  realpath(path: string): Promise<string>;
+  utimes(_path: string, _atime: Date, mtime: Date): Promise<void>;
+}
+//#endregion
+export { BashOptions, BashResult, BashSession, BashSessionOptions, type Command, type CommandContext, EntryType, type ExecResult, FileInfo, FileStat, type NetworkConfig, Workspace, WorkspaceChangeEvent, WorkspaceChangeType, WorkspaceHost, WorkspaceOptions, defineCommand };
+//# sourceMappingURL=workspace.d.ts.map