@mastra/factory 0.24.0-alpha.11 → 0.24.0-alpha.13

package/dist/storage/domains/work-items/board-version.js.map

@@ -1 +1 @@
-{"version":3,"file":"board-version.js","names":["#scopes"],"sources":["../../../../src/storage/domains/work-items/board-version.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport type { CollectionSchema, CollectionWhere, FactoryStorageOps } from '@mastra/core/storage';\n\n/**\n * One row per project whose `version` is replaced after every committed write to that project's\n * `work_items`. Readers of the full card list compare it against the version their snapshot was\n * taken at, so an unchanged board costs one indexed row read instead of every card.\n */\nexport const FACTORY_BOARD_VERSIONS_SCHEMA: CollectionSchema = {\n  name: 'factory_board_versions',\n  columns: {\n    id: { type: 'uuid-pk' },\n    org_id: { type: 'text' },\n    factory_project_id: { type: 'text' },\n    version: { type: 'text' },\n    updated_at: { type: 'timestamp' },\n  },\n  uniqueIndexes: [{ name: 'factory_board_versions_scope_unique', columns: ['org_id', 'factory_project_id'] }],\n};\n\n/** A project, or every project in an org when a write's filter only names the org. */\nexport interface BoardScope {\n  orgId: string;\n  factoryProjectId?: string;\n}\n\nconst scopeKey = (scope: BoardScope) => `${scope.orgId}\\u0000${scope.factoryProjectId ?? ''}`;\n\nfunction scopeOfRow(row: Record<string, unknown> | null): BoardScope | undefined {\n  if (!row || typeof row.org_id !== 'string') return undefined;\n  return typeof row.factory_project_id === 'string'\n    ? { orgId: row.org_id, factoryProjectId: row.factory_project_id }\n    : { orgId: row.org_id };\n}\n\nfunction scopeOfWhere(where: CollectionWhere): BoardScope | undefined {\n  if (typeof where.org_id !== 'string') return undefined;\n  return typeof where.factory_project_id === 'string'\n    ? { orgId: where.org_id, factoryProjectId: where.factory_project_id }\n    : { orgId: where.org_id };\n}\n\n/**\n * Wrap `ops` so every write to `work_items` reports the board it changed, once the write has\n * resolved. Writes outside any tenant (`dangerouslyClearAll`) report nothing.\n */\nexport function trackBoardWrites(\n  ops: FactoryStorageOps,\n  changed: (scope: BoardScope) => void | Promise<void>,\n): FactoryStorageOps {\n  const report = async (scope: BoardScope | undefined) => {\n    if (scope) await changed(scope);\n  };\n  return new Proxy(ops, {\n    get(target, property, receiver) {\n      const value = Reflect.get(target, property, receiver);\n      if (typeof value !== 'function') return value;\n      switch (property) {\n        case 'updateAtomic':\n          return async (collection: string, where: unknown, updater: (row: unknown) => unknown, ...args: unknown[]) => {\n            let patched = false;\n            const row = await value.call(\n              target,\n              collection,\n              where,\n              async (current: unknown) => {\n                const patch = await updater(current);\n                patched = patch != null;\n                return patch;\n              },\n              ...args,\n            );\n            if (collection === 'work_items' && patched) await report(scopeOfRow(row));\n            return row;\n          };\n        case 'insertOne':\n        case 'upsertOne':\n          return async (collection: string, ...args: unknown[]) => {\n            const row = await value.call(target, collection, ...args);\n            if (collection === 'work_items') await report(scopeOfRow(row));\n            return row;\n          };\n        case 'updateMany':\n        case 'deleteMany':\n          return async (collection: string, where: CollectionWhere, ...args: unknown[]) => {\n            const count: number = await value.call(target, collection, where, ...args);\n            if (collection === 'work_items' && count > 0) await report(scopeOfWhere(where));\n            return count;\n          };\n        default:\n          return value.bind(target);\n      }\n    },\n  });\n}\n\n/** Collects the boards a transaction changed so they can be bumped once it has committed. */\nexport class BoardScopes {\n  readonly #scopes = new Map<string, BoardScope>();\n\n  add = (scope: BoardScope): void => {\n    this.#scopes.set(scopeKey(scope), scope);\n  };\n\n  values(): BoardScope[] {\n    return [...this.#scopes.values()];\n  }\n}\n\nexport async function bumpBoardVersions(ops: FactoryStorageOps, scopes: readonly BoardScope[]): Promise<void> {\n  for (const scope of scopes) {\n    const version = randomUUID();\n    const updated_at = new Date();\n    if (scope.factoryProjectId) {\n      await ops.upsertOne(FACTORY_BOARD_VERSIONS_SCHEMA.name, ['org_id', 'factory_project_id'], {\n        org_id: scope.orgId,\n        factory_project_id: scope.factoryProjectId,\n        version,\n        updated_at,\n      });\n    } else {\n      // Projects without a row yet have no version, which never matches a snapshot.\n      await ops.updateMany(FACTORY_BOARD_VERSIONS_SCHEMA.name, { org_id: scope.orgId }, { version, updated_at });\n    }\n  }\n}\n\nexport async function readBoardVersion(\n  ops: FactoryStorageOps,\n  orgId: string,\n  factoryProjectId: string,\n): Promise<string | undefined> {\n  const row = await ops.findOne<{ version: string }>(FACTORY_BOARD_VERSIONS_SCHEMA.name, {\n    org_id: orgId,\n    factory_project_id: factoryProjectId,\n  });\n  return row?.version;\n}\n"],"mappings":"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"}
+{"version":3,"file":"board-version.js","names":[],"sources":["../../../../src/storage/domains/work-items/board-version.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport type { CollectionSchema, CollectionWhere, FactoryStorageOps } from '@mastra/core/storage';\n\n/**\n * One row per project whose `version` is replaced after every committed write to that project's\n * `work_items`. Readers of the full card list compare it against the version their snapshot was\n * taken at, so an unchanged board costs one indexed row read instead of every card.\n */\nexport const FACTORY_BOARD_VERSIONS_SCHEMA: CollectionSchema = {\n  name: 'factory_board_versions',\n  columns: {\n    id: { type: 'uuid-pk' },\n    org_id: { type: 'text' },\n    factory_project_id: { type: 'text' },\n    version: { type: 'text' },\n    updated_at: { type: 'timestamp' },\n  },\n  uniqueIndexes: [{ name: 'factory_board_versions_scope_unique', columns: ['org_id', 'factory_project_id'] }],\n};\n\n/** A project, or every project in an org when a write's filter only names the org. */\nexport interface BoardScope {\n  orgId: string;\n  factoryProjectId?: string;\n}\n\nconst scopeKey = (scope: BoardScope) => `${scope.orgId}\\u0000${scope.factoryProjectId ?? ''}`;\n\nfunction scopeOfRow(row: Record<string, unknown> | null): BoardScope | undefined {\n  if (!row || typeof row.org_id !== 'string') return undefined;\n  return typeof row.factory_project_id === 'string'\n    ? { orgId: row.org_id, factoryProjectId: row.factory_project_id }\n    : { orgId: row.org_id };\n}\n\nfunction scopeOfWhere(where: CollectionWhere): BoardScope | undefined {\n  if (typeof where.org_id !== 'string') return undefined;\n  return typeof where.factory_project_id === 'string'\n    ? { orgId: where.org_id, factoryProjectId: where.factory_project_id }\n    : { orgId: where.org_id };\n}\n\n/**\n * Wrap `ops` so every write to `work_items` reports the board it changed, once the write has\n * resolved. Writes outside any tenant (`dangerouslyClearAll`) report nothing.\n */\nexport function trackBoardWrites(\n  ops: FactoryStorageOps,\n  changed: (scope: BoardScope) => void | Promise<void>,\n): FactoryStorageOps {\n  const report = async (scope: BoardScope | undefined) => {\n    if (scope) await changed(scope);\n  };\n  return new Proxy(ops, {\n    get(target, property, receiver) {\n      const value = Reflect.get(target, property, receiver);\n      if (typeof value !== 'function') return value;\n      switch (property) {\n        case 'updateAtomic':\n          return async (collection: string, where: unknown, updater: (row: unknown) => unknown, ...args: unknown[]) => {\n            let patched = false;\n            const row = await value.call(\n              target,\n              collection,\n              where,\n              async (current: unknown) => {\n                const patch = await updater(current);\n                patched = patch != null;\n                return patch;\n              },\n              ...args,\n            );\n            if (collection === 'work_items' && patched) await report(scopeOfRow(row));\n            return row;\n          };\n        case 'insertOne':\n        case 'upsertOne':\n          return async (collection: string, ...args: unknown[]) => {\n            const row = await value.call(target, collection, ...args);\n            if (collection === 'work_items') await report(scopeOfRow(row));\n            return row;\n          };\n        case 'updateMany':\n        case 'deleteMany':\n          return async (collection: string, where: CollectionWhere, ...args: unknown[]) => {\n            const count: number = await value.call(target, collection, where, ...args);\n            if (collection === 'work_items' && count > 0) await report(scopeOfWhere(where));\n            return count;\n          };\n        default:\n          return value.bind(target);\n      }\n    },\n  });\n}\n\n/** Collects the boards a transaction changed so they can be bumped once it has committed. */\nexport class BoardScopes {\n  readonly #scopes = new Map<string, BoardScope>();\n\n  add = (scope: BoardScope): void => {\n    this.#scopes.set(scopeKey(scope), scope);\n  };\n\n  values(): BoardScope[] {\n    return [...this.#scopes.values()];\n  }\n}\n\nexport async function bumpBoardVersions(ops: FactoryStorageOps, scopes: readonly BoardScope[]): Promise<void> {\n  for (const scope of scopes) {\n    const version = randomUUID();\n    const updated_at = new Date();\n    if (scope.factoryProjectId) {\n      await ops.upsertOne(FACTORY_BOARD_VERSIONS_SCHEMA.name, ['org_id', 'factory_project_id'], {\n        org_id: scope.orgId,\n        factory_project_id: scope.factoryProjectId,\n        version,\n        updated_at,\n      });\n    } else {\n      // Projects without a row yet have no version, which never matches a snapshot.\n      await ops.updateMany(FACTORY_BOARD_VERSIONS_SCHEMA.name, { org_id: scope.orgId }, { version, updated_at });\n    }\n  }\n}\n\nexport async function readBoardVersion(\n  ops: FactoryStorageOps,\n  orgId: string,\n  factoryProjectId: string,\n): Promise<string | undefined> {\n  const row = await ops.findOne<{ version: string }>(FACTORY_BOARD_VERSIONS_SCHEMA.name, {\n    org_id: orgId,\n    factory_project_id: factoryProjectId,\n  });\n  return row?.version;\n}\n"],"mappings":"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"}

package/dist/storage/domains/work-items/metrics.js.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.js","names":[],"sources":["../../../../src/storage/domains/work-items/metrics.ts"],"sourcesContent":["/**\n * Aggregation math for the Factory Overview page.\n *\n * Pure functions over `work_items` rows — throughput, lead time, in-flight\n * count, demand mix and per-stage agent coverage, all read from the\n * server-appended `stageHistory` log. Keeping this DB-free makes the math unit\n * testable and lets the route stay a thin shell.\n *\n * Everything windowed is counted as an event that happened inside the window,\n * never as \"the state the board happens to be in now\", so re-querying a past\n * window always returns the same numbers.\n */\n\nimport { isAgentActor } from './base.js';\nimport type { WorkItemRow } from './base.js';\n\n/** Default window span (days) when the request omits or malforms the range. */\nexport const DEFAULT_METRICS_WINDOW = 30;\n/** Hard cap on the range span (days) — bounds the gap-filled throughput array. */\nexport const MAX_METRICS_WINDOW = 366;\n\nconst DAY_MS = 86_400_000;\n\n/** Terminal stage — items here count as completed, not in-flight. */\nconst DONE_STAGE = 'done';\n\n/** Terminal stage for tracked non-completions — never a completion. */\nconst CANCELED_STAGE = 'canceled';\n\n/**\n * Terminal stages — items holding only these are not in-flight. `done` is a\n * completion (feeds throughput/lead time); `canceled` is a tracked\n * non-completion outcome and feeds neither.\n */\nconst TERMINAL_STAGES = new Set([DONE_STAGE, CANCELED_STAGE]);\n\nconst INTAKE_STAGE = 'intake';\n\n/**\n * Pipeline work excludes the inbox as well as the terminal stages: an intake\n * card is queued, not in flight, and its pass through is the poller filing it.\n */\nfunction isPipelineStage(stage: string): boolean {\n  return !TERMINAL_STAGES.has(stage) && stage !== INTAKE_STAGE;\n}\n\n/**\n * Cards the Factory ran: starting a run records its session on the row. The\n * integrations sync every issue and PR of a connected repo into the board and\n * those outnumber the Factory's own work by an order of magnitude, so counting\n * them reports the upstream repo's flow as the Factory's.\n */\nfunction hasFactoryRun(item: WorkItemRow): boolean {\n  return Object.keys(item.sessions).length > 0;\n}\n\n/**\n * Flow metrics over the cards the Factory ran ({@link hasFactoryRun}) — synced\n * upstream issues and PRs nobody started a run on are not the Factory's work\n * and are excluded from every field below.\n */\nexport interface FactoryMetrics {\n  /**\n   * Days the series covers: the requested window clipped to the board's life.\n   * Days before the first card could hold no completion, so counting them would\n   * drag the per-day rate toward zero on a young board.\n   */\n  daysCovered: number;\n  /** Entries into `done` per UTC day, gap-filled across the covered days. */\n  throughput: { date: string; count: number }[];\n  /** Card creation → `done` for every completion that landed in the window. */\n  leadTime: { medianMs: number | null; p90Ms: number | null; samples: number };\n  /** Distinct cards in a pipeline stage — past intake, not yet terminal. */\n  wipTotal: number;\n  /** Cards created in the window, by source. */\n  sourceMix: { source: string; count: number }[];\n  /** Per-stage agent coverage over first visits that ended in the window. */\n  agentCoverage: {\n    stage: string;\n    /**\n     * First visits to this stage that ended in the window. Repeat visits are\n     * excluded from both sides: they are rework, already reported as such, and\n     * counting them in the denominator alone caps a fully agent-run stage below\n     * 100%.\n     */\n    passes: number;\n    /**\n     * Of those: passes an agent finished (`exitedBy` is an agent actor). The\n     * entry actor is not required — the rules engine is what queues a card into\n     * a stage, so demanding both ends would report 0% for stages agents run\n     * end to end. Missing `exitedBy` (entries written before exit stamping)\n     * does not count.\n     */\n    byAgent: number;\n    /**\n     * Outcomes of the agent-finished passes' items as of the window's end,\n     * mutually exclusive, first match wins: `reworked` (a later visit to the\n     * same stage — deliberately outranks `done`: a pass that needed a redo is a\n     * failed pass even if the item eventually merged), then `done`, then\n     * `canceled`, then `inFlight`.\n     */\n    outcomes: { done: number; canceled: number; reworked: number; inFlight: number };\n  }[];\n}\n\nconst DATE_ONLY_RE = /^\\d{4}-\\d{2}-\\d{2}$/;\n/** Datetime carrying an explicit `Z` or `±HH:MM` offset. */\nconst ZONED_DATETIME_RE = /(?:[Zz]|[+-]\\d{2}:?\\d{2})$/;\n\nfunction parseRangeParam(value: unknown, boundary: 'from' | 'to'): number | undefined {\n  if (typeof value !== 'string' || value.length === 0) return undefined;\n  const dateOnly = DATE_ONLY_RE.test(value);\n  // Timezone-less datetimes are parsed as server-local by Date.parse, so the\n  // window would shift by deployment region — reject them as invalid.\n  if (!dateOnly && !ZONED_DATETIME_RE.test(value)) return undefined;\n  const time = Date.parse(value);\n  if (Number.isNaN(time)) return undefined;\n  return boundary === 'to' && dateOnly ? time + DAY_MS : time;\n}\n\nfunction utcDayStart(time: number): number {\n  return Date.parse(`${utcDay(time)}T00:00:00Z`);\n}\n\n/**\n * Resolve untrusted `from`/`to` into a bounded half-open UTC window. A date-only\n * `to` covers the whole day; an open/future end resolves to the end of the\n * current UTC day (not `now`) so an event at this instant stays inside the\n * window instead of on its excluded edge.\n */\nexport function parseMetricsRange(\n  fromParam: unknown,\n  toParam: unknown,\n  now: Date,\n): { windowStart: number; windowEnd: number } {\n  const nowMs = now.getTime();\n  const endOfToday = utcDayStart(nowMs) + DAY_MS;\n  const requestedEnd = parseRangeParam(toParam, 'to') ?? endOfToday;\n  const windowEnd = Math.min(requestedEnd, endOfToday);\n  const lastIncludedDay = utcDayStart(windowEnd - 1);\n  const defaultStart = lastIncludedDay - (DEFAULT_METRICS_WINDOW - 1) * DAY_MS;\n  const parsedFrom = parseRangeParam(fromParam, 'from');\n  let windowStart = parsedFrom !== undefined && parsedFrom < windowEnd ? parsedFrom : defaultStart;\n  const earliestStart = lastIncludedDay - (MAX_METRICS_WINDOW - 1) * DAY_MS;\n  if (windowStart < earliestStart) windowStart = earliestStart;\n  return { windowStart, windowEnd };\n}\n\n/** Stage history is server-appended, so an unparsable stamp is a corrupt row. */\nfunction parseTime(iso: string): number {\n  const time = Date.parse(iso);\n  if (Number.isNaN(time)) throw new Error(`Unparsable stage-history timestamp: ${iso}`);\n  return time;\n}\n\n/** Asserted up front so a corrupt row fails every window, not just the ones that read it. */\nfunction assertParsableHistory(items: WorkItemRow[]): void {\n  for (const item of items) {\n    for (const entry of item.stageHistory) {\n      parseTime(entry.enteredAt);\n      if (entry.exitedAt !== undefined) parseTime(entry.exitedAt);\n    }\n  }\n}\n\n/** Nearest-rank percentile over an unsorted sample list. */\nfunction percentile(samples: number[], fraction: number): number | null {\n  if (samples.length === 0) return null;\n  const sorted = [...samples].sort((a, b) => a - b);\n  const rank = Math.max(1, Math.ceil(fraction * sorted.length));\n  return sorted[rank - 1]!;\n}\n\n/** UTC `YYYY-MM-DD` for a timestamp. */\nfunction utcDay(time: number): string {\n  return new Date(time).toISOString().slice(0, 10);\n}\n\n/** Stages the item was holding at `time`, replayed from its history. */\nfunction stagesHeldAt(item: WorkItemRow, time: number): Set<string> {\n  const held = new Set<string>();\n  for (const entry of item.stageHistory) {\n    if (parseTime(entry.enteredAt) >= time) continue;\n    if (entry.exitedAt !== undefined && parseTime(entry.exitedAt) <= time) continue;\n    held.add(entry.stage);\n  }\n  return held;\n}\n\ntype Window = { windowStart: number; windowEnd: number };\n\n/**\n * Completions per UTC day, plus one lead-time sample each. A completion is an\n * entry *into* `done`, not the state of the card now: a card reopened today\n * must not erase the day it shipped, and a card that shipped twice shipped\n * twice. Days before the oldest card are left out rather than gap-filled with\n * zeroes that would drag the daily average down.\n */\nfunction completions(items: WorkItemRow[], { windowStart, windowEnd }: Window) {\n  let earliestItem = Infinity;\n  for (const item of items) earliestItem = Math.min(earliestItem, item.createdAt.getTime());\n  const boardStart = Number.isFinite(earliestItem) ? utcDayStart(earliestItem) : -Infinity;\n\n  const byDay = new Map<string, number>();\n  for (let day = Math.max(utcDayStart(windowStart), boardStart); day < windowEnd; day += DAY_MS) {\n    byDay.set(utcDay(day), 0);\n  }\n\n  const leadSamples: number[] = [];\n  for (const item of items) {\n    for (const entry of item.stageHistory) {\n      if (entry.stage !== DONE_STAGE) continue;\n      const doneAt = parseTime(entry.enteredAt);\n      if (doneAt < windowStart || doneAt >= windowEnd) continue;\n      byDay.set(utcDay(doneAt), (byDay.get(utcDay(doneAt)) ?? 0) + 1);\n      leadSamples.push(Math.max(0, doneAt - item.createdAt.getTime()));\n    }\n  }\n  return { byDay, leadSamples };\n}\n\n/** Cards holding at least one pipeline stage right now — window-independent. */\nfunction countInFlight(items: WorkItemRow[]): number {\n  return items.filter(item => item.stages.some(isPipelineStage)).length;\n}\n\n/** Where the window's cards came from, most common first. */\nfunction demandMix(items: WorkItemRow[], { windowStart, windowEnd }: Window): FactoryMetrics['sourceMix'] {\n  const counts = new Map<string, number>();\n  for (const item of items) {\n    const created = item.createdAt.getTime();\n    if (created < windowStart || created >= windowEnd) continue;\n    const source = item.externalSource ? `${item.externalSource.integrationId}:${item.externalSource.type}` : 'manual';\n    counts.set(source, (counts.get(source) ?? 0) + 1);\n  }\n  return [...counts.entries()].map(([source, count]) => ({ source, count })).sort((a, b) => b.count - a.count);\n}\n\n/**\n * How much of each stage's work an agent finished, counting a card's first\n * visit to a stage once. Rows appear in insertion order of each stage's first\n * counted exit; only pipeline stages get rows, since intake and terminal\n * stages have no pass to hand over.\n */\nfunction agentCoverage(items: WorkItemRow[], { windowStart, windowEnd }: Window): FactoryMetrics['agentCoverage'] {\n  const byStage = new Map<string, FactoryMetrics['agentCoverage'][number]>();\n  for (const item of items) {\n    const heldAtWindowEnd = stagesHeldAt(item, windowEnd);\n    const visited = new Set<string>();\n    for (let i = 0; i < item.stageHistory.length; i++) {\n      const entry = item.stageHistory[i]!;\n      if (!isPipelineStage(entry.stage) || visited.has(entry.stage)) continue;\n      visited.add(entry.stage);\n      if (entry.exitedAt === undefined) continue;\n      const exited = parseTime(entry.exitedAt);\n      if (exited < windowStart || exited >= windowEnd) continue;\n\n      let row = byStage.get(entry.stage);\n      if (!row) {\n        row = {\n          stage: entry.stage,\n          passes: 0,\n          byAgent: 0,\n          outcomes: { done: 0, canceled: 0, reworked: 0, inFlight: 0 },\n        };\n        byStage.set(entry.stage, row);\n      }\n      row.passes += 1;\n      if (!isAgentActor(entry.exitedBy)) continue;\n      row.byAgent += 1;\n\n      const reworked = item.stageHistory.some(\n        (later, j) => j > i && later.stage === entry.stage && parseTime(later.enteredAt) < windowEnd,\n      );\n      if (reworked) row.outcomes.reworked += 1;\n      else if (heldAtWindowEnd.has(DONE_STAGE)) row.outcomes.done += 1;\n      else if (heldAtWindowEnd.has(CANCELED_STAGE)) row.outcomes.canceled += 1;\n      else row.outcomes.inFlight += 1;\n    }\n  }\n  return [...byStage.values()];\n}\n\nexport function computeFactoryMetrics(boardItems: WorkItemRow[], window: Window): FactoryMetrics {\n  const items = boardItems.filter(hasFactoryRun);\n  assertParsableHistory(items);\n\n  const { byDay, leadSamples } = completions(items, window);\n\n  return {\n    daysCovered: byDay.size,\n    throughput: [...byDay.entries()]\n      .map(([date, count]) => ({ date, count }))\n      .sort((a, b) => a.date.localeCompare(b.date)),\n    leadTime: {\n      medianMs: percentile(leadSamples, 0.5),\n      p90Ms: percentile(leadSamples, 0.9),\n      samples: leadSamples.length,\n    },\n    wipTotal: countInFlight(items),\n    sourceMix: demandMix(items, window),\n    agentCoverage: agentCoverage(items, window),\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"metrics.js","names":[],"sources":["../../../../src/storage/domains/work-items/metrics.ts"],"sourcesContent":["/**\n * Aggregation math for the Factory Overview page.\n *\n * Pure functions over `work_items` rows — throughput, lead time, in-flight\n * count, demand mix and per-stage agent coverage, all read from the\n * server-appended `stageHistory` log. Keeping this DB-free makes the math unit\n * testable and lets the route stay a thin shell.\n *\n * Everything windowed is counted as an event that happened inside the window,\n * never as \"the state the board happens to be in now\", so re-querying a past\n * window always returns the same numbers.\n */\n\nimport { isAgentActor } from './base.js';\nimport type { WorkItemRow } from './base.js';\n\n/** Default window span (days) when the request omits or malforms the range. */\nexport const DEFAULT_METRICS_WINDOW = 30;\n/** Hard cap on the range span (days) — bounds the gap-filled throughput array. */\nexport const MAX_METRICS_WINDOW = 366;\n\nconst DAY_MS = 86_400_000;\n\n/** Terminal stage — items here count as completed, not in-flight. */\nconst DONE_STAGE = 'done';\n\n/** Terminal stage for tracked non-completions — never a completion. */\nconst CANCELED_STAGE = 'canceled';\n\n/**\n * Terminal stages — items holding only these are not in-flight. `done` is a\n * completion (feeds throughput/lead time); `canceled` is a tracked\n * non-completion outcome and feeds neither.\n */\nconst TERMINAL_STAGES = new Set([DONE_STAGE, CANCELED_STAGE]);\n\nconst INTAKE_STAGE = 'intake';\n\n/**\n * Pipeline work excludes the inbox as well as the terminal stages: an intake\n * card is queued, not in flight, and its pass through is the poller filing it.\n */\nfunction isPipelineStage(stage: string): boolean {\n  return !TERMINAL_STAGES.has(stage) && stage !== INTAKE_STAGE;\n}\n\n/**\n * Cards the Factory ran: starting a run records its session on the row. The\n * integrations sync every issue and PR of a connected repo into the board and\n * those outnumber the Factory's own work by an order of magnitude, so counting\n * them reports the upstream repo's flow as the Factory's.\n */\nfunction hasFactoryRun(item: WorkItemRow): boolean {\n  return Object.keys(item.sessions).length > 0;\n}\n\n/**\n * Flow metrics over the cards the Factory ran ({@link hasFactoryRun}) — synced\n * upstream issues and PRs nobody started a run on are not the Factory's work\n * and are excluded from every field below.\n */\nexport interface FactoryMetrics {\n  /**\n   * Days the series covers: the requested window clipped to the board's life.\n   * Days before the first card could hold no completion, so counting them would\n   * drag the per-day rate toward zero on a young board.\n   */\n  daysCovered: number;\n  /** Entries into `done` per UTC day, gap-filled across the covered days. */\n  throughput: { date: string; count: number }[];\n  /** Card creation → `done` for every completion that landed in the window. */\n  leadTime: { medianMs: number | null; p90Ms: number | null; samples: number };\n  /** Distinct cards in a pipeline stage — past intake, not yet terminal. */\n  wipTotal: number;\n  /** Cards created in the window, by source. */\n  sourceMix: { source: string; count: number }[];\n  /** Per-stage agent coverage over first visits that ended in the window. */\n  agentCoverage: {\n    stage: string;\n    /**\n     * First visits to this stage that ended in the window. Repeat visits are\n     * excluded from both sides: they are rework, already reported as such, and\n     * counting them in the denominator alone caps a fully agent-run stage below\n     * 100%.\n     */\n    passes: number;\n    /**\n     * Of those: passes an agent finished (`exitedBy` is an agent actor). The\n     * entry actor is not required — the rules engine is what queues a card into\n     * a stage, so demanding both ends would report 0% for stages agents run\n     * end to end. Missing `exitedBy` (entries written before exit stamping)\n     * does not count.\n     */\n    byAgent: number;\n    /**\n     * Outcomes of the agent-finished passes' items as of the window's end,\n     * mutually exclusive, first match wins: `reworked` (a later visit to the\n     * same stage — deliberately outranks `done`: a pass that needed a redo is a\n     * failed pass even if the item eventually merged), then `done`, then\n     * `canceled`, then `inFlight`.\n     */\n    outcomes: { done: number; canceled: number; reworked: number; inFlight: number };\n  }[];\n}\n\nconst DATE_ONLY_RE = /^\\d{4}-\\d{2}-\\d{2}$/;\n/** Datetime carrying an explicit `Z` or `±HH:MM` offset. */\nconst ZONED_DATETIME_RE = /(?:[Zz]|[+-]\\d{2}:?\\d{2})$/;\n\nfunction parseRangeParam(value: unknown, boundary: 'from' | 'to'): number | undefined {\n  if (typeof value !== 'string' || value.length === 0) return undefined;\n  const dateOnly = DATE_ONLY_RE.test(value);\n  // Timezone-less datetimes are parsed as server-local by Date.parse, so the\n  // window would shift by deployment region — reject them as invalid.\n  if (!dateOnly && !ZONED_DATETIME_RE.test(value)) return undefined;\n  const time = Date.parse(value);\n  if (Number.isNaN(time)) return undefined;\n  return boundary === 'to' && dateOnly ? time + DAY_MS : time;\n}\n\nfunction utcDayStart(time: number): number {\n  return Date.parse(`${utcDay(time)}T00:00:00Z`);\n}\n\n/**\n * Resolve untrusted `from`/`to` into a bounded half-open UTC window. A date-only\n * `to` covers the whole day; an open/future end resolves to the end of the\n * current UTC day (not `now`) so an event at this instant stays inside the\n * window instead of on its excluded edge.\n */\nexport function parseMetricsRange(\n  fromParam: unknown,\n  toParam: unknown,\n  now: Date,\n): { windowStart: number; windowEnd: number } {\n  const nowMs = now.getTime();\n  const endOfToday = utcDayStart(nowMs) + DAY_MS;\n  const requestedEnd = parseRangeParam(toParam, 'to') ?? endOfToday;\n  const windowEnd = Math.min(requestedEnd, endOfToday);\n  const lastIncludedDay = utcDayStart(windowEnd - 1);\n  const defaultStart = lastIncludedDay - (DEFAULT_METRICS_WINDOW - 1) * DAY_MS;\n  const parsedFrom = parseRangeParam(fromParam, 'from');\n  let windowStart = parsedFrom !== undefined && parsedFrom < windowEnd ? parsedFrom : defaultStart;\n  const earliestStart = lastIncludedDay - (MAX_METRICS_WINDOW - 1) * DAY_MS;\n  if (windowStart < earliestStart) windowStart = earliestStart;\n  return { windowStart, windowEnd };\n}\n\n/** Stage history is server-appended, so an unparsable stamp is a corrupt row. */\nfunction parseTime(iso: string): number {\n  const time = Date.parse(iso);\n  if (Number.isNaN(time)) throw new Error(`Unparsable stage-history timestamp: ${iso}`);\n  return time;\n}\n\n/** Asserted up front so a corrupt row fails every window, not just the ones that read it. */\nfunction assertParsableHistory(items: WorkItemRow[]): void {\n  for (const item of items) {\n    for (const entry of item.stageHistory) {\n      parseTime(entry.enteredAt);\n      if (entry.exitedAt !== undefined) parseTime(entry.exitedAt);\n    }\n  }\n}\n\n/** Nearest-rank percentile over an unsorted sample list. */\nfunction percentile(samples: number[], fraction: number): number | null {\n  if (samples.length === 0) return null;\n  const sorted = [...samples].sort((a, b) => a - b);\n  const rank = Math.max(1, Math.ceil(fraction * sorted.length));\n  return sorted[rank - 1]!;\n}\n\n/** UTC `YYYY-MM-DD` for a timestamp. */\nfunction utcDay(time: number): string {\n  return new Date(time).toISOString().slice(0, 10);\n}\n\n/** Stages the item was holding at `time`, replayed from its history. */\nfunction stagesHeldAt(item: WorkItemRow, time: number): Set<string> {\n  const held = new Set<string>();\n  for (const entry of item.stageHistory) {\n    if (parseTime(entry.enteredAt) >= time) continue;\n    if (entry.exitedAt !== undefined && parseTime(entry.exitedAt) <= time) continue;\n    held.add(entry.stage);\n  }\n  return held;\n}\n\ntype Window = { windowStart: number; windowEnd: number };\n\n/**\n * Completions per UTC day, plus one lead-time sample each. A completion is an\n * entry *into* `done`, not the state of the card now: a card reopened today\n * must not erase the day it shipped, and a card that shipped twice shipped\n * twice. Days before the oldest card are left out rather than gap-filled with\n * zeroes that would drag the daily average down.\n */\nfunction completions(items: WorkItemRow[], { windowStart, windowEnd }: Window) {\n  let earliestItem = Infinity;\n  for (const item of items) earliestItem = Math.min(earliestItem, item.createdAt.getTime());\n  const boardStart = Number.isFinite(earliestItem) ? utcDayStart(earliestItem) : -Infinity;\n\n  const byDay = new Map<string, number>();\n  for (let day = Math.max(utcDayStart(windowStart), boardStart); day < windowEnd; day += DAY_MS) {\n    byDay.set(utcDay(day), 0);\n  }\n\n  const leadSamples: number[] = [];\n  for (const item of items) {\n    for (const entry of item.stageHistory) {\n      if (entry.stage !== DONE_STAGE) continue;\n      const doneAt = parseTime(entry.enteredAt);\n      if (doneAt < windowStart || doneAt >= windowEnd) continue;\n      byDay.set(utcDay(doneAt), (byDay.get(utcDay(doneAt)) ?? 0) + 1);\n      leadSamples.push(Math.max(0, doneAt - item.createdAt.getTime()));\n    }\n  }\n  return { byDay, leadSamples };\n}\n\n/** Cards holding at least one pipeline stage right now — window-independent. */\nfunction countInFlight(items: WorkItemRow[]): number {\n  return items.filter(item => item.stages.some(isPipelineStage)).length;\n}\n\n/** Where the window's cards came from, most common first. */\nfunction demandMix(items: WorkItemRow[], { windowStart, windowEnd }: Window): FactoryMetrics['sourceMix'] {\n  const counts = new Map<string, number>();\n  for (const item of items) {\n    const created = item.createdAt.getTime();\n    if (created < windowStart || created >= windowEnd) continue;\n    const source = item.externalSource ? `${item.externalSource.integrationId}:${item.externalSource.type}` : 'manual';\n    counts.set(source, (counts.get(source) ?? 0) + 1);\n  }\n  return [...counts.entries()].map(([source, count]) => ({ source, count })).sort((a, b) => b.count - a.count);\n}\n\n/**\n * How much of each stage's work an agent finished, counting a card's first\n * visit to a stage once. Rows appear in insertion order of each stage's first\n * counted exit; only pipeline stages get rows, since intake and terminal\n * stages have no pass to hand over.\n */\nfunction agentCoverage(items: WorkItemRow[], { windowStart, windowEnd }: Window): FactoryMetrics['agentCoverage'] {\n  const byStage = new Map<string, FactoryMetrics['agentCoverage'][number]>();\n  for (const item of items) {\n    const heldAtWindowEnd = stagesHeldAt(item, windowEnd);\n    const visited = new Set<string>();\n    for (let i = 0; i < item.stageHistory.length; i++) {\n      const entry = item.stageHistory[i]!;\n      if (!isPipelineStage(entry.stage) || visited.has(entry.stage)) continue;\n      visited.add(entry.stage);\n      if (entry.exitedAt === undefined) continue;\n      const exited = parseTime(entry.exitedAt);\n      if (exited < windowStart || exited >= windowEnd) continue;\n\n      let row = byStage.get(entry.stage);\n      if (!row) {\n        row = {\n          stage: entry.stage,\n          passes: 0,\n          byAgent: 0,\n          outcomes: { done: 0, canceled: 0, reworked: 0, inFlight: 0 },\n        };\n        byStage.set(entry.stage, row);\n      }\n      row.passes += 1;\n      if (!isAgentActor(entry.exitedBy)) continue;\n      row.byAgent += 1;\n\n      const reworked = item.stageHistory.some(\n        (later, j) => j > i && later.stage === entry.stage && parseTime(later.enteredAt) < windowEnd,\n      );\n      if (reworked) row.outcomes.reworked += 1;\n      else if (heldAtWindowEnd.has(DONE_STAGE)) row.outcomes.done += 1;\n      else if (heldAtWindowEnd.has(CANCELED_STAGE)) row.outcomes.canceled += 1;\n      else row.outcomes.inFlight += 1;\n    }\n  }\n  return [...byStage.values()];\n}\n\nexport function computeFactoryMetrics(boardItems: WorkItemRow[], window: Window): FactoryMetrics {\n  const items = boardItems.filter(hasFactoryRun);\n  assertParsableHistory(items);\n\n  const { byDay, leadSamples } = completions(items, window);\n\n  return {\n    daysCovered: byDay.size,\n    throughput: [...byDay.entries()]\n      .map(([date, count]) => ({ date, count }))\n      .sort((a, b) => a.date.localeCompare(b.date)),\n    leadTime: {\n      medianMs: percentile(leadSamples, 0.5),\n      p90Ms: percentile(leadSamples, 0.9),\n      samples: leadSamples.length,\n    },\n    wipTotal: countInFlight(items),\n    sourceMix: demandMix(items, window),\n    agentCoverage: agentCoverage(items, window),\n  };\n}\n"],"mappings":"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"}

package/dist/tools/messaging-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messaging-tools.d.ts","sourceRoot":"","sources":["../../src/tools/messaging-tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAA4C,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAIjH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAExE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAM9E,OAAO,KAAK,EAAE,yBAAyB,EAAyB,MAAM,cAAc,CAAC;AAIrF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,qBAAqB,QAAiB,CAAC;AAKpD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,yBAAyB,CAAC;IACtC,aAAa,EAAE,IAAI,CAAC,oBAAoB,EAAE,mBAAmB,GAAG,iBAAiB,CAAC,CAAC;CACpF;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,EAAE,IAAI,CAAC,0BAA0B,EAAE,gBAAgB,GAAG,cAAc,GAAG,gBAAgB,CAAC,CAAC;IACjG,SAAS,EAAE,IAAI,CACb,gBAAgB,EACd,gCAAgC,GAChC,eAAe,GACf,yBAAyB,GACzB,0BAA0B,GAC1B,iBAAiB,GACjB,yBAAyB,CAC5B,CAAC;IACF,aAAa,EAAE,aAAa,CAAC;IAC7B,mHAAmH;IACnH,SAAS,EAAE,MAAM,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;CACnD;AAgBD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,gCAAgC,GACrC,gBAAgB,CA2XlB"}
+{"version":3,"file":"messaging-tools.d.ts","sourceRoot":"","sources":["../../src/tools/messaging-tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAGV,oBAAoB,EAErB,MAAM,4BAA4B,CAAC;AAIpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAExE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAM9E,OAAO,KAAK,EAAE,yBAAyB,EAAyB,MAAM,cAAc,CAAC;AAIrF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,qBAAqB,QAAiB,CAAC;AAyCpD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,yBAAyB,CAAC;IACtC,aAAa,EAAE,IAAI,CAAC,oBAAoB,EAAE,mBAAmB,GAAG,iBAAiB,CAAC,CAAC;CACpF;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,EAAE,IAAI,CAAC,0BAA0B,EAAE,gBAAgB,GAAG,cAAc,GAAG,gBAAgB,CAAC,CAAC;IACjG,SAAS,EAAE,IAAI,CACb,gBAAgB,EACd,gCAAgC,GAChC,eAAe,GACf,yBAAyB,GACzB,0BAA0B,GAC1B,iBAAiB,GACjB,yBAAyB,CAC5B,CAAC;IACF,aAAa,EAAE,aAAa,CAAC;IAC7B,mHAAmH;IACnH,SAAS,EAAE,MAAM,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;CACnD;AAgBD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,gCAAgC,GACrC,gBAAgB,CAohBlB"}

package/dist/tools/messaging-tools.js

@@ -8,10 +8,30 @@ import { createTool } from "@mastra/core/tools";
 //#region src/tools/messaging-tools.ts
 /** Messages plus replies, per sender session, per target thread, per window. */
 const SIGNAL_RATE_LIMIT = 10;
-const SIGNAL_RATE_WINDOW_MS = 600 * 1e3;
+const SIGNAL_RATE_WINDOW_MS = 6e5;
 /** How many recent `factory-session` notifications on a thread the rate and duplicate checks read. */
 const RECENT_SCAN = 100;
-const RATE_LIMITED = "Too many messages to that session in the last 10 minutes; wait before sending more.";
+/** How often a waiting queue is reconsidered. Delivery still waits for a free slot in the window. */
+const QUEUE_FLUSH_MS = 1e3;
+/**
+* Waiting messages, per sender session and target thread, oldest first.
+* Process-local: a restart drops what was still waiting, the same as a message
+* that had not been handed to the tool yet. Delivered messages live in the
+* notification store and are unaffected.
+*/
+const pendingQueues = /* @__PURE__ */ new Map();
+const flushTimers = /* @__PURE__ */ new Map();
+const queueOwners = /* @__PURE__ */ new WeakMap();
+let nextQueueOwnerId = 0;
+const queueKey = (owner, senderSessionId, threadId) => {
+	let id = queueOwners.get(owner);
+	if (id === void 0) {
+		nextQueueOwnerId += 1;
+		id = nextQueueOwnerId;
+		queueOwners.set(owner, id);
+	}
+	return `${id}\0${senderSessionId}\0${threadId}`;
+};
 const message = z.string().trim().min(1).max(4e3);
 function senderAttributes(scope) {
 	return {
@@ -53,16 +73,146 @@ function createFactoryMessagingTools(scope, deps) {
 		if (row.visibility === "private" && row.userId !== scope.userId) return "private";
 		return null;
 	};
-	/** Messages, replies and reports (not progress) this session put on a thread inside the rate window. */
-	const overRateLimit = (records) => {
+	const overRateLimit = (records) => countedInWindow(records).length >= 10;
+	/** This session's delivered messages on the thread that still sit inside the window, oldest first. */
+	const countedInWindow = (records) => {
 		const since = Date.now() - SIGNAL_RATE_WINDOW_MS;
-		return records.filter((record) => record.kind !== "progress" && record.kind !== "stage" && record.attributes?.["from-session"] === scope.sessionId && record.createdAt.getTime() >= since).length >= 10;
+		return records.filter((record) => record.kind !== "progress" && record.kind !== "stage" && record.attributes?.["from-session"] === scope.sessionId && record.createdAt.getTime() >= since).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+	};
+	/**
+	* When the next message can be delivered: one window after the oldest message
+	* that has to age out to free a slot, given how many are already waiting.
+	*/
+	const nextDeliveryAt = (counted, waiting) => {
+		const blocking = counted[counted.length + waiting - 10];
+		return (blocking ? blocking.createdAt.getTime() : Date.now()) + SIGNAL_RATE_WINDOW_MS;
 	};
+	const queuedResult = (deliverAt) => ({
+		delivered: "queued",
+		deliverAt: new Date(deliverAt).toISOString(),
+		note: `Queued; it will be delivered at about ${new Date(deliverAt).toISOString()}. Do not send it again.`
+	});
 	const recent = (notifications, threadId) => notifications.listNotifications({
 		threadId,
 		source: FACTORY_SESSION_NOTIFICATION_SOURCE,
 		limit: RECENT_SCAN
 	});
+	const actor = () => ({
+		actorId: human ? scope.userId : `agent:${scope.threadId}`,
+		actorType: human ? "human" : "agent"
+	});
+	/**
+	* Deliver now, or hold until the window has a slot. The cap limits how fast
+	* messages are delivered, not whether they are accepted.
+	*/
+	const accept = async (messaging, target, notification) => {
+		const counted = countedInWindow(await recent(messaging.notifications, target.threadId));
+		if (counted.length < 10) {
+			const result = await deliverFactorySessionNotification({
+				controller: messaging.controller,
+				sessions: deps.sessions,
+				runs: deps.workItems,
+				target,
+				notification
+			});
+			if (result.delivered === "skipped") throw unavailable(result);
+			await audit({
+				targetSessionId: target.sessionId,
+				priority: notification.priority ?? "medium",
+				kind: notification.kind,
+				delivery: result.delivered
+			});
+			return {
+				notificationId: result.notificationId,
+				delivered: result.delivered
+			};
+		}
+		const key = queueKey(deps, scope.sessionId, target.threadId);
+		const waiting = pendingQueues.get(key)?.length ?? 0;
+		const deliverAt = nextDeliveryAt(counted, waiting);
+		enqueue(key, {
+			notification,
+			acceptedAt: Date.now(),
+			actor: actor(),
+			deliverAt,
+			target
+		});
+		return queuedResult(deliverAt);
+	};
+	const enqueue = (key, delivery) => {
+		const queue = pendingQueues.get(key) ?? [];
+		queue.push(delivery);
+		queue.sort((a, b) => a.acceptedAt - b.acceptedAt);
+		pendingQueues.set(key, queue);
+		scheduleFlush(key);
+	};
+	/**
+	* Deliver the oldest waiting message once the window has a free slot, then
+	* the next, in the order they were accepted. A target that is gone by then
+	* is dropped and recorded, the same way an undeliverable live message is.
+	*/
+	const flush = async (key) => {
+		flushTimers.delete(key);
+		const queue = pendingQueues.get(key);
+		if (!queue || queue.length === 0) {
+			pendingQueues.delete(key);
+			return;
+		}
+		const messaging = await deps.messaging();
+		if (!messaging) {
+			scheduleFlush(key);
+			return;
+		}
+		const head = queue[0];
+		if (!head || head.deliverAt > Date.now()) {
+			scheduleFlush(key);
+			return;
+		}
+		if (countedInWindow(await recent(messaging.notifications, head.target.threadId)).length >= 10) {
+			scheduleFlush(key);
+			return;
+		}
+		queue.shift();
+		if (queue.length === 0) pendingQueues.delete(key);
+		const result = await deliverFactorySessionNotification({
+			controller: messaging.controller,
+			sessions: deps.sessions,
+			runs: deps.workItems,
+			target: head.target,
+			notification: head.notification
+		});
+		await deps.auditRecorder.record({
+			orgId: scope.orgId,
+			actorId: head.actor.actorId,
+			actorType: head.actor.actorType,
+			action: "factory.agent.signaled",
+			factoryProjectId: scope.factoryProjectId,
+			targets: [{
+				type: "session",
+				id: head.target.sessionId
+			}],
+			metadata: {
+				targetSessionId: head.target.sessionId,
+				priority: head.notification.priority ?? "medium",
+				kind: head.notification.kind,
+				delivery: result.delivered === "skipped" ? "dropped" : result.delivered,
+				...result.delivered === "skipped" ? { reason: result.reason } : {}
+			}
+		});
+		if (queue.length > 0) scheduleFlush(key);
+	};
+	function scheduleFlush(key) {
+		if (flushTimers.has(key)) return;
+		if (!pendingQueues.get(key)?.[0]) return;
+		const timer = setTimeout(() => {
+			flushTimers.delete(key);
+			flush(key).catch(() => {
+				if ((pendingQueues.get(key)?.length ?? 0) > 0) scheduleFlush(key);
+			});
+		}, QUEUE_FLUSH_MS);
+		timer.unref?.();
+		flushTimers.set(key, timer);
+	}
 	/** On turns nobody signed in started, only sessions working on items this session follows. */
 	const followedWorkers = async () => {
 		const project = {
@@ -126,38 +276,20 @@ function createFactoryMessagingTools(scope, deps) {
 				sessionId
 			});
 			if (!threadId) throw new Error("The session is not available (thread-not-found).");
-			if (overRateLimit(await recent(messaging.notifications, threadId))) throw new Error(RATE_LIMITED);
-			const result = await deliverFactorySessionNotification({
-				controller: messaging.controller,
-				sessions: deps.sessions,
-				runs: deps.workItems,
-				target: {
-					sessionId,
-					threadId
-				},
-				notification: {
-					kind: "message",
-					priority,
-					summary: text,
-					payload: { message: text },
-					sourceId: scope.sessionId,
-					attributes: {
-						...await workItemAttribute(sessionId, row.orgId, scope.factoryProjectId),
-						...senderAttributes(scope)
-					}
-				}
-			});
-			if (result.delivered === "skipped") throw unavailable(result);
-			await audit({
-				targetSessionId: sessionId,
-				priority,
+			return accept(messaging, {
+				sessionId,
+				threadId
+			}, {
 				kind: "message",
-				delivery: result.delivered
+				priority,
+				summary: text,
+				payload: { message: text },
+				sourceId: scope.sessionId,
+				attributes: {
+					...await workItemAttribute(sessionId, row.orgId, scope.factoryProjectId),
+					...senderAttributes(scope)
+				}
 			});
-			return {
-				notificationId: result.notificationId,
-				delivered: result.delivered
-			};
 		}
 	});
 	const reply = createTool({
@@ -193,41 +325,22 @@ function createFactoryMessagingTools(scope, deps) {
 			const blocked = unreachable(await deps.sessions.getBySessionId(fromSession));
 			if (blocked === "not-found") throw new Error(`Message ${inReplyTo} didn't come from a session in this Factory.`);
 			if (blocked === "private") throw new Error(`Message ${inReplyTo} came from a private session this session can't answer.`);
-			const onSenderThread = await recent(messaging.notifications, fromThread);
-			if (onSenderThread.some((record) => record.kind === "reply" && record.attributes?.["in-reply-to"] === inReplyTo && record.attributes?.["from-session"] === scope.sessionId)) throw new Error(`You already answered ${inReplyTo}.`);
-			if (overRateLimit(onSenderThread)) throw new Error(RATE_LIMITED);
-			const result = await deliverFactorySessionNotification({
-				controller: messaging.controller,
-				sessions: deps.sessions,
-				runs: deps.workItems,
-				target: {
-					sessionId: fromSession,
-					threadId: fromThread
-				},
-				notification: {
-					kind: "reply",
-					priority: "high",
-					summary: text,
-					payload: { message: text },
-					sourceId: scope.sessionId,
-					attributes: {
-						...senderAttributes(scope),
-						"in-reply-to": inReplyTo,
-						...status ? { status } : {}
-					}
-				}
-			});
-			if (result.delivered === "skipped") throw unavailable(result);
-			await audit({
-				targetSessionId: fromSession,
-				priority: "high",
+			if ((await recent(messaging.notifications, fromThread)).some((record) => record.kind === "reply" && record.attributes?.["in-reply-to"] === inReplyTo && record.attributes?.["from-session"] === scope.sessionId)) throw new Error(`You already answered ${inReplyTo}.`);
+			return accept(messaging, {
+				sessionId: fromSession,
+				threadId: fromThread
+			}, {
 				kind: "reply",
-				delivery: result.delivered
+				priority: "high",
+				summary: text,
+				payload: { message: text },
+				sourceId: scope.sessionId,
+				attributes: {
+					...senderAttributes(scope),
+					"in-reply-to": inReplyTo,
+					...status ? { status } : {}
+				}
 			});
-			return {
-				notificationId: result.notificationId,
-				delivered: result.delivered
-			};
 		}
 	});
 	/** A report with no message to answer: to the origin, else to the item's followers. */
@@ -280,10 +393,21 @@ function createFactoryMessagingTools(scope, deps) {
 		const results = [];
 		for (const recipient of recipients) {
 			if (status !== "progress" && overRateLimit(await recent(messaging.notifications, recipient.threadId))) {
+				const counted = countedInWindow(await recent(messaging.notifications, recipient.threadId));
+				const key = queueKey(deps, scope.sessionId, recipient.threadId);
+				const waiting = pendingQueues.get(key)?.length ?? 0;
+				const at = nextDeliveryAt(counted, waiting);
+				enqueue(key, {
+					notification,
+					acceptedAt: Date.now(),
+					actor: actor(),
+					deliverAt: at,
+					target: recipient
+				});
 				results.push({
 					sessionId: recipient.sessionId,
-					delivered: "skipped",
-					reason: "rate-limited"
+					delivered: "queued",
+					deliverAt: new Date(at).toISOString()
 				});
 				continue;
 			}
@@ -306,11 +430,15 @@ function createFactoryMessagingTools(scope, deps) {
 				delivery: result.delivered
 			});
 		}
-		const delivered = results.filter((result) => result.delivered !== "skipped").length;
-		if (delivered === 0 && results.every((result) => result.reason === "rate-limited")) throw new Error(RATE_LIMITED);
+		const delivered = results.filter((result) => result.delivered !== "skipped" && result.delivered !== "queued").length;
+		const queued = results.filter((result) => result.delivered === "queued").length;
 		return {
 			delivered,
-			recipients: results
+			recipients: results,
+			...queued > 0 ? {
+				queued,
+				note: "Queued past the delivery cap. It will be delivered when the window allows. Do not send it again."
+			} : {}
 		};
 	}
 	const listSide = createTool({