@mastra/factory 0.10.0-alpha.2 → 0.10.0-alpha.8

package/dist/routes/attention.js

@@ -0,0 +1,305 @@
+import { factoryAttentionKey, factoryDecisionAttentionIdentity } from "../storage/domains/work-items/base.js";
+import { factoryDispatchFailureMetadata } from "../rules/dispatch-errors.js";
+import { registerApiRoute } from "@mastra/core/server";
+//#region src/routes/attention.ts
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DEFAULT_PAGE_SIZE = 25;
+const MAX_PAGE_SIZE = 50;
+const MAX_RECEIPT_SCAN_PAGES = 4;
+function factoryDecisionType(decision) {
+	return typeof decision.decision.type === "string" ? decision.decision.type.slice(0, 64) : "unknown";
+}
+function parseAttentionView(raw) {
+	if (!raw || raw === "open") return "open";
+	if (raw === "unread" || raw === "archived") return raw;
+}
+function parseAttentionLimit(raw) {
+	const parsed = raw ? Number.parseInt(raw, 10) : DEFAULT_PAGE_SIZE;
+	if (!Number.isFinite(parsed)) return DEFAULT_PAGE_SIZE;
+	return Math.max(1, Math.min(MAX_PAGE_SIZE, parsed));
+}
+function attentionIdentity(decision) {
+	return factoryDecisionAttentionIdentity(decision.id, decision.failureOccurrence);
+}
+function attentionKey(factoryProjectId, decision) {
+	return factoryAttentionKey(factoryProjectId, attentionIdentity(decision));
+}
+function failureOccurredAt(decision) {
+	return decision.completedAt ?? decision.updatedAt;
+}
+function encodeAttentionCursor(decision) {
+	return Buffer.from(JSON.stringify([failureOccurredAt(decision).toISOString(), decision.id]), "utf8").toString("base64url");
+}
+function parseAttentionCursor(raw) {
+	if (!raw) return void 0;
+	try {
+		const decoded = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+		if (!Array.isArray(decoded) || decoded.length !== 2 || typeof decoded[0] !== "string" || typeof decoded[1] !== "string") return;
+		const occurredAt = new Date(decoded[0]);
+		if (Number.isNaN(occurredAt.getTime()) || !UUID_RE.test(decoded[1])) return void 0;
+		return {
+			occurredAt,
+			id: decoded[1]
+		};
+	} catch {
+		return;
+	}
+}
+function parseFailureOccurrence(raw) {
+	if (!raw || !/^(0|[1-9]\d*)$/.test(raw)) return void 0;
+	const occurrence = Number(raw);
+	return Number.isSafeInteger(occurrence) ? occurrence : void 0;
+}
+function attentionTarget(decision, item) {
+	if (!item) return { kind: "rules" };
+	const role = typeof decision.decision.role === "string" ? decision.decision.role : void 0;
+	const session = role ? item.sessions[role] : void 0;
+	if (session) return {
+		kind: "thread",
+		sessionId: session.sessionId,
+		threadId: session.threadId
+	};
+	const review = item.externalSource?.integrationId === "github" && item.externalSource.type === "pull-request";
+	return {
+		kind: "work-item",
+		workItemId: item.id,
+		board: review ? "review" : "work"
+	};
+}
+function attentionItem(factoryProjectId, decision, item, receipt) {
+	const failure = factoryDispatchFailureMetadata(decision.failureCode);
+	return {
+		key: attentionKey(factoryProjectId, decision),
+		kind: "automation-failed",
+		decisionId: decision.id,
+		occurrence: decision.failureOccurrence,
+		workItemId: decision.workItemId,
+		title: item?.title ?? failure.label,
+		detail: decision.lastError?.slice(0, 512) ?? failure.label,
+		decisionType: factoryDecisionType(decision),
+		failureCode: decision.failureCode,
+		canRetry: failure.canRetry,
+		occurredAt: failureOccurredAt(decision).toISOString(),
+		read: receipt !== void 0,
+		archived: receipt?.state === "archived",
+		target: attentionTarget(decision, item)
+	};
+}
+function receiptRoute(dependencies, verb, action) {
+	return registerApiRoute(`/web/factory/projects/:id/attention/automation-failed/:decisionId/:occurrence/${verb}`, {
+		method: "POST",
+		requiresAuth: false,
+		handler: async (context) => {
+			const resolved = await dependencies.resolveProject(context);
+			if ("response" in resolved) return resolved.response;
+			const decisionId = context.req.param("decisionId");
+			const failureOccurrence = parseFailureOccurrence(context.req.param("occurrence"));
+			if (!decisionId || !UUID_RE.test(decisionId) || failureOccurrence === void 0) return context.json({ error: "invalid_attention_item" }, 422);
+			await dependencies.workItems.ensureReady();
+			const receipt = await dependencies.workItems.setAttentionReceipt({
+				orgId: resolved.orgId,
+				factoryProjectId: resolved.factoryProjectId,
+				userId: resolved.userId,
+				decisionId,
+				failureOccurrence,
+				action,
+				now: /* @__PURE__ */ new Date()
+			});
+			if (!receipt) return context.json({ error: "attention_item_not_current" }, 409);
+			return context.json({ receipt: {
+				key: factoryAttentionKey(resolved.factoryProjectId, receipt),
+				state: receipt.state,
+				readAt: receipt.readAt.toISOString(),
+				archivedAt: receipt.archivedAt?.toISOString() ?? null
+			} });
+		}
+	});
+}
+function buildAttentionRoutes(dependencies) {
+	const { workItems } = dependencies;
+	return [
+		registerApiRoute("/web/factory/projects/:id/attention", {
+			method: "GET",
+			requiresAuth: false,
+			handler: async (context) => {
+				const resolved = await dependencies.resolveProject(context);
+				if ("response" in resolved) return resolved.response;
+				const view = parseAttentionView(context.req.query("view"));
+				if (view === void 0) return context.json({ error: "invalid_attention_view" }, 400);
+				const cursorRaw = context.req.query("before");
+				const before = parseAttentionCursor(cursorRaw);
+				if (cursorRaw && !before) return context.json({ error: "invalid_cursor" }, 400);
+				await workItems.ensureReady();
+				const [failedCount, approvalCount, receiptCount, archivedCount, newestPage] = await Promise.all([
+					workItems.countDeferredDecisionsByStatuses({
+						orgId: resolved.orgId,
+						factoryProjectId: resolved.factoryProjectId,
+						statuses: ["failed"]
+					}),
+					workItems.countDeferredDecisionsByStatuses({
+						orgId: resolved.orgId,
+						factoryProjectId: resolved.factoryProjectId,
+						statuses: ["proposed"]
+					}),
+					workItems.countAttentionReceipts({
+						orgId: resolved.orgId,
+						factoryProjectId: resolved.factoryProjectId,
+						userId: resolved.userId
+					}),
+					workItems.countAttentionReceipts({
+						orgId: resolved.orgId,
+						factoryProjectId: resolved.factoryProjectId,
+						userId: resolved.userId,
+						state: "archived"
+					}),
+					workItems.listFailedDecisionPage({
+						orgId: resolved.orgId,
+						factoryProjectId: resolved.factoryProjectId,
+						limit: 1
+					})
+				]);
+				const failureOpenCount = Math.max(0, failedCount - archivedCount);
+				const openCount = failureOpenCount + approvalCount;
+				const unreadCount = Math.max(0, failedCount - receiptCount);
+				const badgeCount = unreadCount + approvalCount;
+				const newestFailure = newestPage.decisions[0];
+				const newestReceipt = newestFailure ? (await workItems.listAttentionReceipts({
+					orgId: resolved.orgId,
+					factoryProjectId: resolved.factoryProjectId,
+					userId: resolved.userId,
+					identities: [attentionIdentity(newestFailure)]
+				}))[0] : void 0;
+				const search = context.req.query("search")?.trim().toLowerCase().slice(0, 200);
+				const requestedLimit = parseAttentionLimit(context.req.query("limit"));
+				const visible = [];
+				let scanBefore = before;
+				let cursorDecision;
+				let continuationDecision;
+				let scannedPages = 0;
+				let hasMore = false;
+				scan: while (view === "open" && failureOpenCount > 0 || view === "unread" && unreadCount > 0 || view === "archived" && archivedCount > 0) {
+					const page = await workItems.listFailedDecisionPage({
+						orgId: resolved.orgId,
+						factoryProjectId: resolved.factoryProjectId,
+						before: scanBefore,
+						limit: MAX_PAGE_SIZE
+					});
+					scannedPages += 1;
+					if (page.decisions.length === 0) break;
+					const receipts = await workItems.listAttentionReceipts({
+						orgId: resolved.orgId,
+						factoryProjectId: resolved.factoryProjectId,
+						userId: resolved.userId,
+						identities: page.decisions.map(attentionIdentity)
+					});
+					const receiptByKey = new Map(receipts.map((receipt) => [factoryAttentionKey(resolved.factoryProjectId, receipt), receipt]));
+					const linkedItems = await workItems.listByIds({
+						orgId: resolved.orgId,
+						factoryProjectId: resolved.factoryProjectId,
+						ids: page.decisions.flatMap((decision) => decision.workItemId ? [decision.workItemId] : [])
+					});
+					const itemById = new Map(linkedItems.map((item) => [item.id, item]));
+					for (const decision of page.decisions) {
+						const receipt = receiptByKey.get(attentionKey(resolved.factoryProjectId, decision));
+						if (view === "archived" ? receipt?.state !== "archived" : view === "unread" ? receipt : receipt?.state === "archived") continue;
+						const item = decision.workItemId ? itemById.get(decision.workItemId) : void 0;
+						if (search && item?.title.toLowerCase().includes(search) !== true && decision.lastError?.toLowerCase().includes(search) !== true && !factoryDecisionType(decision).toLowerCase().includes(search)) continue;
+						if (visible.length === requestedLimit) {
+							hasMore = true;
+							continuationDecision = cursorDecision;
+							break scan;
+						}
+						visible.push({
+							decision,
+							item,
+							receipt
+						});
+						if (visible.length === requestedLimit) cursorDecision = decision;
+					}
+					const lastScanned = page.decisions.at(-1);
+					if (!page.hasMore || !lastScanned) break;
+					if (scannedPages === MAX_RECEIPT_SCAN_PAGES) {
+						hasMore = true;
+						continuationDecision = lastScanned;
+						break;
+					}
+					scanBefore = {
+						occurredAt: failureOccurredAt(lastScanned),
+						id: lastScanned.id
+					};
+				}
+				return context.json({
+					items: visible.map(({ decision, item, receipt }) => attentionItem(resolved.factoryProjectId, decision, item, receipt)),
+					openCount,
+					approvalCount,
+					badgeCount,
+					unreadCount,
+					latestOccurrenceKey: newestFailure ? attentionKey(resolved.factoryProjectId, newestFailure) : null,
+					latestOccurrenceAt: newestFailure ? failureOccurredAt(newestFailure).toISOString() : null,
+					latestOccurrenceUnread: newestFailure !== void 0 && newestReceipt === void 0,
+					hasMore,
+					...hasMore && continuationDecision ? { nextCursor: encodeAttentionCursor(continuationDecision) } : {}
+				});
+			}
+		}),
+		registerApiRoute("/web/factory/projects/:id/attention/read-all", {
+			method: "POST",
+			requiresAuth: false,
+			handler: async (context) => {
+				const resolved = await dependencies.resolveProject(context);
+				if ("response" in resolved) return resolved.response;
+				const cursorRaw = context.req.query("before");
+				const initialBefore = parseAttentionCursor(cursorRaw);
+				if (cursorRaw && !initialBefore) return context.json({ error: "invalid_cursor" }, 400);
+				await workItems.ensureReady();
+				let before = initialBefore;
+				let pages = 0;
+				let hasMore = false;
+				let nextCursor;
+				while (pages < MAX_RECEIPT_SCAN_PAGES) {
+					const page = await workItems.listFailedDecisionPage({
+						orgId: resolved.orgId,
+						factoryProjectId: resolved.factoryProjectId,
+						before,
+						limit: MAX_PAGE_SIZE
+					});
+					pages += 1;
+					if (page.decisions.length === 0) break;
+					await workItems.markAttentionReceiptsRead({
+						orgId: resolved.orgId,
+						factoryProjectId: resolved.factoryProjectId,
+						userId: resolved.userId,
+						occurrences: page.decisions.map((decision) => ({
+							decisionId: decision.id,
+							failureOccurrence: decision.failureOccurrence
+						})),
+						now: /* @__PURE__ */ new Date()
+					});
+					const last = page.decisions.at(-1);
+					if (!page.hasMore || !last) break;
+					if (pages === MAX_RECEIPT_SCAN_PAGES) {
+						hasMore = true;
+						nextCursor = encodeAttentionCursor(last);
+						break;
+					}
+					before = {
+						occurredAt: failureOccurredAt(last),
+						id: last.id
+					};
+				}
+				return context.json({
+					ok: true,
+					hasMore,
+					...nextCursor ? { nextCursor } : {}
+				});
+			}
+		}),
+		receiptRoute(dependencies, "read", "read"),
+		receiptRoute(dependencies, "archive", "archive"),
+		receiptRoute(dependencies, "restore", "restore")
+	];
+}
+//#endregion
+export { buildAttentionRoutes, factoryDecisionType };
+
+//# sourceMappingURL=attention.js.map

package/dist/routes/attention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention.js","names":[],"sources":["../../src/routes/attention.ts"],"sourcesContent":["import type { ApiRoute } from '@mastra/core/server';\nimport { registerApiRoute } from '@mastra/core/server';\n\nimport { factoryDispatchFailureMetadata } from '../rules/dispatch-errors.js';\nimport type {\n  FactoryAttentionReceiptAction,\n  FactoryAttentionReceiptRecord,\n  FactoryDeferredDecisionRecord,\n  WorkItemRow,\n  WorkItemsStorage,\n} from '../storage/domains/work-items/base.js';\nimport { factoryAttentionKey, factoryDecisionAttentionIdentity } from '../storage/domains/work-items/base.js';\n\nconst UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\nconst DEFAULT_PAGE_SIZE = 25;\nconst MAX_PAGE_SIZE = 50;\n// Receipt filtering is bounded to 200 failed decisions per request; the response cursor resumes after the last scan.\nconst MAX_RECEIPT_SCAN_PAGES = 4;\n\ntype FactoryAttentionView = 'open' | 'unread' | 'archived';\n\ninterface ResolvedAttentionProject {\n  orgId: string;\n  userId: string;\n  factoryProjectId: string;\n}\n\ninterface AttentionRouteDependencies {\n  workItems: WorkItemsStorage;\n  resolveProject(context: unknown): Promise<ResolvedAttentionProject | { response: Response }>;\n}\n\nexport function factoryDecisionType(decision: FactoryDeferredDecisionRecord): string {\n  return typeof decision.decision.type === 'string' ? decision.decision.type.slice(0, 64) : 'unknown';\n}\n\nfunction parseAttentionView(raw: string | undefined): FactoryAttentionView | undefined {\n  if (!raw || raw === 'open') return 'open';\n  if (raw === 'unread' || raw === 'archived') return raw;\n  return undefined;\n}\n\nfunction parseAttentionLimit(raw: string | undefined): number {\n  const parsed = raw ? Number.parseInt(raw, 10) : DEFAULT_PAGE_SIZE;\n  if (!Number.isFinite(parsed)) return DEFAULT_PAGE_SIZE;\n  return Math.max(1, Math.min(MAX_PAGE_SIZE, parsed));\n}\n\nfunction attentionIdentity(decision: FactoryDeferredDecisionRecord) {\n  return factoryDecisionAttentionIdentity(decision.id, decision.failureOccurrence);\n}\n\nfunction attentionKey(factoryProjectId: string, decision: FactoryDeferredDecisionRecord): string {\n  return factoryAttentionKey(factoryProjectId, attentionIdentity(decision));\n}\n\nfunction failureOccurredAt(decision: FactoryDeferredDecisionRecord): Date {\n  return decision.completedAt ?? decision.updatedAt;\n}\n\nfunction encodeAttentionCursor(decision: FactoryDeferredDecisionRecord): string {\n  return Buffer.from(JSON.stringify([failureOccurredAt(decision).toISOString(), decision.id]), 'utf8').toString(\n    'base64url',\n  );\n}\n\nfunction parseAttentionCursor(raw: string | undefined): { occurredAt: Date; id: string } | undefined {\n  if (!raw) return undefined;\n  try {\n    const decoded: unknown = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'));\n    if (\n      !Array.isArray(decoded) ||\n      decoded.length !== 2 ||\n      typeof decoded[0] !== 'string' ||\n      typeof decoded[1] !== 'string'\n    ) {\n      return undefined;\n    }\n    const occurredAt = new Date(decoded[0]);\n    if (Number.isNaN(occurredAt.getTime()) || !UUID_RE.test(decoded[1])) return undefined;\n    return { occurredAt, id: decoded[1] };\n  } catch {\n    return undefined;\n  }\n}\n\nfunction parseFailureOccurrence(raw: string | undefined): number | undefined {\n  if (!raw || !/^(0|[1-9]\\d*)$/.test(raw)) return undefined;\n  const occurrence = Number(raw);\n  return Number.isSafeInteger(occurrence) ? occurrence : undefined;\n}\n\nfunction attentionTarget(decision: FactoryDeferredDecisionRecord, item: WorkItemRow | undefined) {\n  if (!item) return { kind: 'rules' as const };\n  const role = typeof decision.decision.role === 'string' ? decision.decision.role : undefined;\n  const session = role ? item.sessions[role] : undefined;\n  if (session) {\n    return {\n      kind: 'thread' as const,\n      sessionId: session.sessionId,\n      threadId: session.threadId,\n    };\n  }\n  const review = item.externalSource?.integrationId === 'github' && item.externalSource.type === 'pull-request';\n  return {\n    kind: 'work-item' as const,\n    workItemId: item.id,\n    board: review ? ('review' as const) : ('work' as const),\n  };\n}\n\nfunction attentionItem(\n  factoryProjectId: string,\n  decision: FactoryDeferredDecisionRecord,\n  item: WorkItemRow | undefined,\n  receipt: FactoryAttentionReceiptRecord | undefined,\n) {\n  const failure = factoryDispatchFailureMetadata(decision.failureCode);\n  return {\n    key: attentionKey(factoryProjectId, decision),\n    kind: 'automation-failed' as const,\n    decisionId: decision.id,\n    occurrence: decision.failureOccurrence,\n    workItemId: decision.workItemId,\n    title: item?.title ?? failure.label,\n    detail: decision.lastError?.slice(0, 512) ?? failure.label,\n    decisionType: factoryDecisionType(decision),\n    failureCode: decision.failureCode,\n    canRetry: failure.canRetry,\n    occurredAt: failureOccurredAt(decision).toISOString(),\n    read: receipt !== undefined,\n    archived: receipt?.state === 'archived',\n    target: attentionTarget(decision, item),\n  };\n}\n\nfunction receiptRoute(\n  dependencies: AttentionRouteDependencies,\n  verb: 'read' | 'archive' | 'restore',\n  action: FactoryAttentionReceiptAction,\n): ApiRoute {\n  return registerApiRoute(`/web/factory/projects/:id/attention/automation-failed/:decisionId/:occurrence/${verb}`, {\n    method: 'POST',\n    requiresAuth: false,\n    handler: async context => {\n      const resolved = await dependencies.resolveProject(context);\n      if ('response' in resolved) return resolved.response;\n      const decisionId = context.req.param('decisionId');\n      const failureOccurrence = parseFailureOccurrence(context.req.param('occurrence'));\n      if (!decisionId || !UUID_RE.test(decisionId) || failureOccurrence === undefined) {\n        return context.json({ error: 'invalid_attention_item' }, 422);\n      }\n      await dependencies.workItems.ensureReady();\n      const receipt = await dependencies.workItems.setAttentionReceipt({\n        orgId: resolved.orgId,\n        factoryProjectId: resolved.factoryProjectId,\n        userId: resolved.userId,\n        decisionId,\n        failureOccurrence,\n        action,\n        now: new Date(),\n      });\n      if (!receipt) return context.json({ error: 'attention_item_not_current' }, 409);\n      return context.json({\n        receipt: {\n          key: factoryAttentionKey(resolved.factoryProjectId, receipt),\n          state: receipt.state,\n          readAt: receipt.readAt.toISOString(),\n          archivedAt: receipt.archivedAt?.toISOString() ?? null,\n        },\n      });\n    },\n  });\n}\n\nexport function buildAttentionRoutes(dependencies: AttentionRouteDependencies): ApiRoute[] {\n  const { workItems } = dependencies;\n  return [\n    registerApiRoute('/web/factory/projects/:id/attention', {\n      method: 'GET',\n      requiresAuth: false,\n      handler: async context => {\n        const resolved = await dependencies.resolveProject(context);\n        if ('response' in resolved) return resolved.response;\n        const view = parseAttentionView(context.req.query('view'));\n        if (view === undefined) return context.json({ error: 'invalid_attention_view' }, 400);\n        const cursorRaw = context.req.query('before');\n        const before = parseAttentionCursor(cursorRaw);\n        if (cursorRaw && !before) return context.json({ error: 'invalid_cursor' }, 400);\n        await workItems.ensureReady();\n        const [failedCount, approvalCount, receiptCount, archivedCount, newestPage] = await Promise.all([\n          workItems.countDeferredDecisionsByStatuses({\n            orgId: resolved.orgId,\n            factoryProjectId: resolved.factoryProjectId,\n            statuses: ['failed'],\n          }),\n          workItems.countDeferredDecisionsByStatuses({\n            orgId: resolved.orgId,\n            factoryProjectId: resolved.factoryProjectId,\n            statuses: ['proposed'],\n          }),\n          workItems.countAttentionReceipts({\n            orgId: resolved.orgId,\n            factoryProjectId: resolved.factoryProjectId,\n            userId: resolved.userId,\n          }),\n          workItems.countAttentionReceipts({\n            orgId: resolved.orgId,\n            factoryProjectId: resolved.factoryProjectId,\n            userId: resolved.userId,\n            state: 'archived',\n          }),\n          workItems.listFailedDecisionPage({\n            orgId: resolved.orgId,\n            factoryProjectId: resolved.factoryProjectId,\n            limit: 1,\n          }),\n        ]);\n        const failureOpenCount = Math.max(0, failedCount - archivedCount);\n        const openCount = failureOpenCount + approvalCount;\n        const unreadCount = Math.max(0, failedCount - receiptCount);\n        const badgeCount = unreadCount + approvalCount;\n        const newestFailure = newestPage.decisions[0];\n        const newestReceipt = newestFailure\n          ? (\n              await workItems.listAttentionReceipts({\n                orgId: resolved.orgId,\n                factoryProjectId: resolved.factoryProjectId,\n                userId: resolved.userId,\n                identities: [attentionIdentity(newestFailure)],\n              })\n            )[0]\n          : undefined;\n        const search = context.req.query('search')?.trim().toLowerCase().slice(0, 200);\n        const requestedLimit = parseAttentionLimit(context.req.query('limit'));\n        const visible: Array<{\n          decision: FactoryDeferredDecisionRecord;\n          item: WorkItemRow | undefined;\n          receipt: FactoryAttentionReceiptRecord | undefined;\n        }> = [];\n        let scanBefore = before;\n        let cursorDecision: FactoryDeferredDecisionRecord | undefined;\n        let continuationDecision: FactoryDeferredDecisionRecord | undefined;\n        let scannedPages = 0;\n        let hasMore = false;\n\n        scan: while (\n          (view === 'open' && failureOpenCount > 0) ||\n          (view === 'unread' && unreadCount > 0) ||\n          (view === 'archived' && archivedCount > 0)\n        ) {\n          const page = await workItems.listFailedDecisionPage({\n            orgId: resolved.orgId,\n            factoryProjectId: resolved.factoryProjectId,\n            before: scanBefore,\n            limit: MAX_PAGE_SIZE,\n          });\n          scannedPages += 1;\n          if (page.decisions.length === 0) break;\n          const receipts = await workItems.listAttentionReceipts({\n            orgId: resolved.orgId,\n            factoryProjectId: resolved.factoryProjectId,\n            userId: resolved.userId,\n            identities: page.decisions.map(attentionIdentity),\n          });\n          const receiptByKey = new Map(\n            receipts.map(receipt => [factoryAttentionKey(resolved.factoryProjectId, receipt), receipt]),\n          );\n          const linkedItems = await workItems.listByIds({\n            orgId: resolved.orgId,\n            factoryProjectId: resolved.factoryProjectId,\n            ids: page.decisions.flatMap(decision => (decision.workItemId ? [decision.workItemId] : [])),\n          });\n          const itemById = new Map(linkedItems.map(item => [item.id, item]));\n          for (const decision of page.decisions) {\n            const receipt = receiptByKey.get(attentionKey(resolved.factoryProjectId, decision));\n            if (\n              view === 'archived'\n                ? receipt?.state !== 'archived'\n                : view === 'unread'\n                  ? receipt\n                  : receipt?.state === 'archived'\n            ) {\n              continue;\n            }\n            const item = decision.workItemId ? itemById.get(decision.workItemId) : undefined;\n            if (\n              search &&\n              item?.title.toLowerCase().includes(search) !== true &&\n              decision.lastError?.toLowerCase().includes(search) !== true &&\n              !factoryDecisionType(decision).toLowerCase().includes(search)\n            ) {\n              continue;\n            }\n            if (visible.length === requestedLimit) {\n              hasMore = true;\n              continuationDecision = cursorDecision;\n              break scan;\n            }\n            visible.push({ decision, item, receipt });\n            if (visible.length === requestedLimit) cursorDecision = decision;\n          }\n          const lastScanned = page.decisions.at(-1);\n          if (!page.hasMore || !lastScanned) break;\n          if (scannedPages === MAX_RECEIPT_SCAN_PAGES) {\n            hasMore = true;\n            continuationDecision = lastScanned;\n            break;\n          }\n          scanBefore = { occurredAt: failureOccurredAt(lastScanned), id: lastScanned.id };\n        }\n\n        return context.json({\n          items: visible.map(({ decision, item, receipt }) =>\n            attentionItem(resolved.factoryProjectId, decision, item, receipt),\n          ),\n          openCount,\n          approvalCount,\n          badgeCount,\n          unreadCount,\n          latestOccurrenceKey: newestFailure ? attentionKey(resolved.factoryProjectId, newestFailure) : null,\n          latestOccurrenceAt: newestFailure ? failureOccurredAt(newestFailure).toISOString() : null,\n          latestOccurrenceUnread: newestFailure !== undefined && newestReceipt === undefined,\n          hasMore,\n          ...(hasMore && continuationDecision ? { nextCursor: encodeAttentionCursor(continuationDecision) } : {}),\n        });\n      },\n    }),\n    registerApiRoute('/web/factory/projects/:id/attention/read-all', {\n      method: 'POST',\n      requiresAuth: false,\n      handler: async context => {\n        const resolved = await dependencies.resolveProject(context);\n        if ('response' in resolved) return resolved.response;\n        const cursorRaw = context.req.query('before');\n        const initialBefore = parseAttentionCursor(cursorRaw);\n        if (cursorRaw && !initialBefore) return context.json({ error: 'invalid_cursor' }, 400);\n        await workItems.ensureReady();\n        let before = initialBefore;\n        let pages = 0;\n        let hasMore = false;\n        let nextCursor: string | undefined;\n        while (pages < MAX_RECEIPT_SCAN_PAGES) {\n          const page = await workItems.listFailedDecisionPage({\n            orgId: resolved.orgId,\n            factoryProjectId: resolved.factoryProjectId,\n            before,\n            limit: MAX_PAGE_SIZE,\n          });\n          pages += 1;\n          if (page.decisions.length === 0) break;\n          await workItems.markAttentionReceiptsRead({\n            orgId: resolved.orgId,\n            factoryProjectId: resolved.factoryProjectId,\n            userId: resolved.userId,\n            occurrences: page.decisions.map(decision => ({\n              decisionId: decision.id,\n              failureOccurrence: decision.failureOccurrence,\n            })),\n            now: new Date(),\n          });\n          const last = page.decisions.at(-1);\n          if (!page.hasMore || !last) break;\n          if (pages === MAX_RECEIPT_SCAN_PAGES) {\n            hasMore = true;\n            nextCursor = encodeAttentionCursor(last);\n            break;\n          }\n          before = { occurredAt: failureOccurredAt(last), id: last.id };\n        }\n        return context.json({ ok: true, hasMore, ...(nextCursor ? { nextCursor } : {}) });\n      },\n    }),\n    receiptRoute(dependencies, 'read', 'read'),\n    receiptRoute(dependencies, 'archive', 'archive'),\n    receiptRoute(dependencies, 'restore', 'restore'),\n  ];\n}\n"],"mappings":"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"}

package/dist/routes/surface.d.ts

@@ -23,7 +23,7 @@ import type { MemorySettingsStorage } from '../storage/domains/memory-settings/b
 import type { ModelPacksStorage } from '../storage/domains/model-packs/base.js';
 import type { FactoryProjectsStorage } from '../storage/domains/projects/base.js';
 import type { QueueHealthStorage } from '../storage/domains/queue-health/base.js';
-import type { SourceControlStorage } from '../storage/domains/source-control/base.js';
+import { type SourceControlStorage } from '../storage/domains/source-control/base.js';
 import type { WorkItemsStorage } from '../storage/domains/work-items/base.js';
 import type { RouteAuth } from './route.js';
 export interface IntegrationRegistration {
@@ -75,7 +75,6 @@ export interface FactoryApiRoutesDeps {
         prepareBinding?: (input: FactoryBindingPreparationInput) => Promise<void>;
     }) => void;
 }
-export declare function factoryRuleBranch(item: FactoryBindingPreparationInput['item']): string;
 /**
  * Start a factory run for a rule binding: ensure the source-control session the
  * coordinator requires, then hand it to `prepare` along with the factory's
@@ -83,7 +82,7 @@ export declare function factoryRuleBranch(item: FactoryBindingPreparationInput['
  * browser and no interactive user, so nothing else would catch a regression in
  * what it forwards.
  */
-export declare function prepareFactoryRuleBinding(github: GithubIntegration, coordinator: FactoryStartCoordinator, projects: FactoryProjectsStorage, input: FactoryBindingPreparationInput): Promise<void>;
+export declare function prepareFactoryRuleBinding(github: GithubIntegration, coordinator: Pick<FactoryStartCoordinator, 'prepare'>, projects: FactoryProjectsStorage, input: FactoryBindingPreparationInput): Promise<void>;
 /**
  * Build the {@link IntegrationContext} handed to an integration when the
  * factory collects its capabilities (routes, workers). One shape everywhere:

package/dist/routes/surface.d.ts.map

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

package/dist/routes/surface.js

@@ -1,10 +1,14 @@
-import { isFactoryRuleStage } from "../rules/types.js";
+import { MaterializeError } from "../integrations/github/sandbox.js";
+import { factoryRuleStage } from "../rules/types.js";
 import { getGithubFeatureDiagnostics } from "../integrations/github/config.js";
 import { invalidateCustomProvidersSnapshots } from "./custom-provider-source.js";
-import { ensureFactorySourceSession, resolveFactoryDefaultModelId } from "../session/factory-session.js";
+import { FactoryDispatchError } from "../rules/dispatch-errors.js";
+import { FactorySourceSessionResolutionError, ensureFactorySourceSession, resolveFactoryDefaultModelId } from "../session/factory-session.js";
 import { FactoryStartCoordinator } from "../rules/start-coordinator.js";
 import { FactoryTransitionService } from "../rules/transition-service.js";
 import { LiveSessions } from "../session/live-sessions.js";
+import { SourceControlConnectionNotFoundError } from "../storage/domains/source-control/base.js";
+import { workItemBranch, workItemBranchSource } from "../work-item-branch.js";
 import { ConfigRoutes } from "./config.js";
 import { buildFsRoutes } from "./fs.js";
 import { IntakeRoutes } from "./intake.js";
@@ -15,6 +19,16 @@ import { invalidateTenantCredentialSnapshots } from "./tenant-credentials.js";
 import { WorkItemRoutes } from "./work-items.js";
 import { registerApiRoute } from "@mastra/core/server";
 //#region src/routes/surface.ts
+const MATERIALIZE_FAILURE_CODE = {
+	"git-missing": "repository_git_missing",
+	"egress-blocked": "repository_egress_blocked",
+	"clone-failed": "repository_clone_failed",
+	"pull-failed": "repository_pull_failed",
+	"push-failed": "repository_push_failed",
+	"commit-failed": "repository_commit_failed",
+	"gh-missing": "repository_cli_missing",
+	"pr-failed": "repository_pr_failed"
+};
 function guardIntegrationRoutes({ integration, ready, ensureReady, routes }) {
 	if (ready) return routes;
 	return routes.map((route) => {
@@ -55,15 +69,6 @@ function guardIntegrationRoutes({ integration, ready, ensureReady, routes }) {
 		};
 	});
 }
-function factoryRuleBranch(item) {
-	const metadata = item.metadata ?? {};
-	const issueNumber = metadata.githubIssueNumber ?? metadata.number;
-	if (item.externalSource?.integrationId === "github" && item.externalSource.type === "issue" && typeof issueNumber === "number") return `factory/issue-${issueNumber}`;
-	const pullRequestNumber = metadata.githubPullRequestNumber ?? metadata.number;
-	if (item.externalSource?.integrationId === "github" && item.externalSource.type === "pull-request" && typeof pullRequestNumber === "number") return `factory/pr-${pullRequestNumber}`;
-	if (item.externalSource?.integrationId === "linear" && typeof metadata.identifier === "string") return `factory/linear-${metadata.identifier.toLowerCase()}`;
-	throw new Error("Factory skill invocation requires a supported issue or pull request identifier.");
-}
 /**
 * Start a factory run for a rule binding: ensure the source-control session the
 * coordinator requires, then hand it to `prepare` along with the factory's
@@ -72,39 +77,52 @@ function factoryRuleBranch(item) {
 * what it forwards.
 */
 async function prepareFactoryRuleBinding(github, coordinator, projects, input) {
-	const branch = factoryRuleBranch(input.item);
-	const repositorySlug = typeof input.item.metadata?.repository === "string" ? input.item.metadata.repository : void 0;
-	const preparedSession = await ensureFactorySourceSession({
-		sourceControl: github.sourceControlStorage,
-		orgId: input.record.orgId,
-		factoryProjectId: input.record.factoryProjectId,
-		repositorySlug,
-		branch
-	});
-	const destinationStage = input.item.stages.length === 1 ? input.item.stages[0] : void 0;
-	if (!isFactoryRuleStage(destinationStage)) throw new Error("Factory skill invocation requires one exclusive board stage.");
-	await coordinator.prepare({
-		orgId: input.record.orgId,
-		userId: preparedSession.userId,
-		factoryProjectId: input.record.factoryProjectId,
-		sessionId: preparedSession.sessionId,
-		defaultModelId: await resolveFactoryDefaultModelId(projects, input.record.factoryProjectId),
-		threadTitle: `${input.role === "review" ? "PR" : "Issue"}: ${input.item.title}`,
-		kickoffKey: input.record.id,
-		destinationStage,
-		workItem: {
+	try {
+		const branch = workItemBranch({
 			id: input.item.id,
-			role: input.role,
-			input: {
-				externalSource: input.item.externalSource,
-				parentWorkItemId: input.item.parentWorkItemId,
-				title: input.item.title,
-				stages: ["intake"],
-				sessions: input.item.sessions,
-				metadata: input.item.metadata
+			source: workItemBranchSource(input.item.externalSource),
+			metadata: input.item.metadata
+		});
+		const destinationStage = factoryRuleStage(input.item.stages);
+		if (!destinationStage) throw new FactoryDispatchError("unsupported_provider_item", "Factory skill invocation requires one exclusive board stage.");
+		const repositorySlug = typeof input.item.metadata?.repository === "string" ? input.item.metadata.repository : void 0;
+		const preparedSession = await ensureFactorySourceSession({
+			sourceControl: github.sourceControlStorage,
+			orgId: input.record.orgId,
+			factoryProjectId: input.record.factoryProjectId,
+			repositorySlug,
+			branch,
+			attributeToUserId: input.record.approvedBy ?? void 0
+		});
+		await coordinator.prepare({
+			orgId: input.record.orgId,
+			userId: preparedSession.userId,
+			factoryProjectId: input.record.factoryProjectId,
+			sessionId: preparedSession.sessionId,
+			defaultModelId: await resolveFactoryDefaultModelId(projects, input.record.factoryProjectId),
+			threadTitle: `${input.role === "review" ? "PR" : "Issue"}: ${input.item.title}`,
+			kickoffKey: input.record.id,
+			destinationStage,
+			workItem: {
+				id: input.item.id,
+				role: input.role,
+				input: {
+					externalSource: input.item.externalSource,
+					parentWorkItemId: input.item.parentWorkItemId,
+					title: input.item.title,
+					stages: ["intake"],
+					sessions: input.item.sessions,
+					metadata: input.item.metadata
+				}
 			}
-		}
-	});
+		});
+	} catch (error) {
+		if (error instanceof FactoryDispatchError) throw error;
+		if (error instanceof FactorySourceSessionResolutionError) throw new FactoryDispatchError(error.reason === "connection" ? "source_control_missing" : "source_repository_missing", error.message, { cause: error });
+		if (error instanceof SourceControlConnectionNotFoundError) throw new FactoryDispatchError("source_control_missing", error.message, { cause: error });
+		if (error instanceof MaterializeError) throw new FactoryDispatchError(MATERIALIZE_FAILURE_CODE[error.code], error.message, { cause: error });
+		throw error;
+	}
 }
 /**
 * Build the {@link IntegrationContext} handed to an integration when the
@@ -307,6 +325,6 @@ function assembleFactoryApiRoutes(deps) {
 	];
 }
 //#endregion
-export { assembleFactoryApiRoutes, buildIntegrationContext, factoryRuleBranch, prepareFactoryRuleBinding };
+export { assembleFactoryApiRoutes, buildIntegrationContext, prepareFactoryRuleBinding };
 
 //# sourceMappingURL=surface.js.map