@mastra/factory 0.24.0-alpha.0 → 0.24.0-alpha.10

package/dist/tools/reports.js

@@ -0,0 +1,380 @@
+import { FACTORY_SESSION_NOTIFICATION_SOURCE } from "./deliver.js";
+import { workItemNumber } from "./read-tools.js";
+//#region src/tools/reports.ts
+/** How each report status travels. Final reports never coalesce, so a later report can't overwrite them. */
+const FACTORY_REPORT_FORMS = {
+	failed: {
+		kind: "failed",
+		priority: "urgent",
+		coalesce: false
+	},
+	blocked: {
+		kind: "blocked",
+		priority: "urgent",
+		coalesce: false
+	},
+	done: {
+		kind: "done",
+		priority: "high",
+		coalesce: false
+	},
+	progress: {
+		kind: "progress",
+		priority: "low",
+		coalesce: true
+	},
+	report: {
+		kind: "report",
+		priority: "high",
+		coalesce: false
+	}
+};
+/** How many recent `factory-session` notifications on a recipient thread the final-report check reads. */
+const FINAL_REPORT_SCAN = 100;
+/**
+* Whether `senderSessionId` already put a report of one of `kinds` on the
+* recipient thread since `since`. Reads the durable notifications store, so it
+* holds across restarts. `listNotifications` has no time filter: records come
+* newest-updated first, and the scan stops at the first one last updated
+* before `since` (nothing after it can have been created later).
+*/
+async function hasFinalReport(notifications, { senderSessionId, recipientThreadId, since, kinds, agentOnly = false }) {
+	const records = await notifications.listNotifications({
+		threadId: recipientThreadId,
+		source: FACTORY_SESSION_NOTIFICATION_SOURCE,
+		limit: FINAL_REPORT_SCAN
+	});
+	for (const record of records) {
+		if (record.updatedAt < since) break;
+		if (record.attributes?.["from-session"] === senderSessionId && !(agentOnly && record.attributes?.backstop === "true") && (kinds.includes(record.kind) || record.kind === "reply" && typeof record.attributes?.status === "string" && kinds.includes(record.attributes.status)) && record.createdAt >= since) return true;
+	}
+	return false;
+}
+/**
+* Whether the newest report `senderSessionId` put on the recipient thread is
+* already this exact `failed` backstop. A session stuck failing the same way
+* (a run that dies before the model, restarted over and over) then reports
+* once, not once per attempt; any other report in between resets it.
+*/
+async function repeatsLastFailure(notifications, { senderSessionId, recipientThreadId, summary }) {
+	const last = (await notifications.listNotifications({
+		threadId: recipientThreadId,
+		source: FACTORY_SESSION_NOTIFICATION_SOURCE,
+		limit: FINAL_REPORT_SCAN
+	})).filter((record) => record.attributes?.["from-session"] === senderSessionId).reduce((newest, record) => !newest || record.createdAt > newest.createdAt ? record : newest, void 0);
+	return last?.kind === "failed" && last.attributes?.backstop === "true" && last.summary === summary;
+}
+function reportNotification({ sender, status, message, attributes = {} }) {
+	const form = FACTORY_REPORT_FORMS[status ?? "report"];
+	return {
+		kind: form.kind,
+		priority: form.priority,
+		summary: message,
+		payload: { message },
+		sourceId: sender.sessionId,
+		...form.coalesce ? { coalesceKey: `factory-session:${sender.sessionId}:${form.kind}` } : {},
+		attributes: {
+			...attributes,
+			...status ? { status } : {},
+			"from-session": sender.sessionId,
+			"from-thread": sender.threadId,
+			"from-user": sender.userId
+		}
+	};
+}
+/** Everyone following a work item, except the session doing the reporting. */
+async function workItemReportRecipients(workItems, { orgId, workItemId, senderSessionId }) {
+	return (await workItems.listWorkItemSubscribers({
+		orgId,
+		workItemId
+	})).filter((subscriber) => subscriber.sessionId !== senderSessionId).map((subscriber) => ({
+		sessionId: subscriber.sessionId,
+		threadId: subscriber.threadId
+	}));
+}
+/** How reports name an item: `#n`, else its quoted title, else its id. */
+async function workItemReference(workItems, { orgId, factoryProjectId, workItemId }) {
+	const item = await workItems.getForProject(orgId, factoryProjectId, workItemId);
+	const number = item ? workItemNumber(item) : null;
+	if (number !== null) return {
+		label: `#${number}`,
+		ref: `#${number}`
+	};
+	return {
+		label: item ? `"${item.title}"` : workItemId,
+		ref: workItemId
+	};
+}
+/** Attributes that say which item and role a worker's report is about. */
+async function workItemReportAttributes(workItems, { orgId, factoryProjectId, workItemId, role }) {
+	const { label, ref } = await workItemReference(workItems, {
+		orgId,
+		factoryProjectId,
+		workItemId
+	});
+	return {
+		label,
+		attributes: {
+			"work-item": ref,
+			role
+		}
+	};
+}
+/**
+* The run-end backstop: send `outcome` to each recipient that hasn't had a
+* final report from this sender since the run started. An agent's own `done`
+* or `failed` report wins. A run that completes after the agent's own
+* `blocked` sends nothing: the agent ended its turn to wait for an answer, and
+* its `done` comes from a later run. A `failed` backstop still goes out after an
+* earlier `blocked`.
+*/
+async function sendRunEndReport(reporting, { sender, recipients, since, outcome, subject, attributes = {} }) {
+	const kinds = outcome.status === "blocked" ? ["blocked"] : ["done", "failed"];
+	const message = outcome.status === "done" ? `${subject} finished.` : outcome.status === "failed" ? `${subject} failed${outcome.failureCode ? ` (${outcome.failureCode})` : ""}: ${outcome.reason}` : outcome.approval ? `${subject} is waiting for someone to approve ${outcome.toolName ?? "a tool call"} in that session.` : `${subject} is waiting${outcome.toolName ? ` on ${outcome.toolName}` : ""} and needs an answer.`;
+	const notification = reportNotification({
+		sender,
+		status: outcome.status,
+		message,
+		attributes: {
+			...attributes,
+			backstop: "true",
+			...outcome.status === "failed" && outcome.failureCode ? { "failure-code": outcome.failureCode } : {},
+			...outcome.status === "blocked" && outcome.toolName ? { "parked-tool": outcome.toolName } : {},
+			...outcome.status === "blocked" && outcome.approval ? { "waiting-for": "approval" } : {}
+		}
+	});
+	const report = (recipient, reportKinds, agentOnly = false) => hasFinalReport(reporting.notifications, {
+		senderSessionId: sender.sessionId,
+		recipientThreadId: recipient.threadId,
+		since,
+		kinds: reportKinds,
+		agentOnly
+	});
+	let waiting = outcome.status === "blocked";
+	const deliveries = [];
+	for (const recipient of recipients) {
+		if (await report(recipient, outcome.status === "done" ? [...kinds, "reply"] : kinds, true)) continue;
+		if (outcome.status === "done" && await report(recipient, ["blocked"], true)) {
+			waiting = true;
+			continue;
+		}
+		if (outcome.status === "failed" && await repeatsLastFailure(reporting.notifications, {
+			senderSessionId: sender.sessionId,
+			recipientThreadId: recipient.threadId,
+			summary: message
+		})) continue;
+		deliveries.push(await reporting.deliver(recipient, notification));
+	}
+	return {
+		waiting,
+		deliveries
+	};
+}
+/** The backstop for a work-item run: reports to the item's subscribers. Failures are logged, never thrown. */
+function createWorkItemRunEndReporter({ workItems, reporting }) {
+	return async (input) => {
+		try {
+			const resolved = await reporting();
+			if (!resolved) return { waiting: false };
+			const recipients = await workItemReportRecipients(workItems, {
+				orgId: input.orgId,
+				workItemId: input.workItemId,
+				senderSessionId: input.sender.sessionId
+			});
+			if (recipients.length === 0) return { waiting: false };
+			const { label, attributes } = await workItemReportAttributes(workItems, input);
+			return await sendRunEndReport(resolved, {
+				sender: input.sender,
+				recipients,
+				since: input.since,
+				outcome: input.outcome,
+				subject: `The ${input.role} session for ${label}`,
+				attributes
+			});
+		} catch (error) {
+			console.warn("[Factory reports] Unable to send the run-end report.", error);
+			return { waiting: false };
+		}
+	};
+}
+/**
+* Tells a work item's subscribers it moved, at `low` priority. Only sessions
+* already live hear it: a stage change never brings a session online; an
+* offline subscriber sees the stage in its state signal on its next turn.
+*/
+function createStageChangeNotifier({ workItems, reporting }) {
+	return async (change) => {
+		const subscribers = await workItems.listWorkItemSubscribers({
+			orgId: change.orgId,
+			workItemId: change.workItemId
+		});
+		if (subscribers.length === 0) return;
+		const resolved = await reporting();
+		if (!resolved) return;
+		const { label, ref } = await workItemReference(workItems, change);
+		const summary = change.fromStage ? `${label} moved from ${change.fromStage} to ${change.toStage}.` : `${label} moved to ${change.toStage}.`;
+		const notification = {
+			kind: "stage",
+			priority: "low",
+			summary,
+			payload: { message: summary },
+			sourceId: change.workItemId,
+			coalesceKey: `factory-stage:${change.workItemId}`,
+			attributes: {
+				"work-item": ref,
+				...change.fromStage ? { "from-stage": change.fromStage } : {},
+				"to-stage": change.toStage
+			}
+		};
+		for (const subscriber of subscribers) try {
+			await resolved.deliver({
+				sessionId: subscriber.sessionId,
+				threadId: subscriber.threadId
+			}, notification, { onlyIfLive: true });
+		} catch (error) {
+			console.warn(`[Factory reports] Unable to tell ${subscriber.sessionId} that ${label} moved.`, error);
+		}
+	};
+}
+/** How much of a gated call's arguments an approval notice quotes. */
+const APPROVAL_ARGS_LENGTH = 3e3;
+/**
+* Who hears from a session: a work session (one with an active run binding)
+* reports to its item's followers, a side session to the session that started
+* it. Any other session (a person's own) has nobody to tell.
+*/
+async function sessionAudience({ sessions, workItems }, sessionId, threadId, since) {
+	const row = await sessions.getBySessionId(sessionId);
+	if (!row?.factoryProjectId) return null;
+	let binding = await workItems.findActiveRunBindingForSession({
+		orgId: row.orgId,
+		factoryProjectId: row.factoryProjectId,
+		sessionId: row.sessionId
+	});
+	if (!binding && since && threadId) for (const resourceId of /* @__PURE__ */ new Set([
+		row.factoryProjectId,
+		row.sessionId,
+		row.userId
+	])) {
+		const latest = await workItems.findRunBindingBySession({
+			factoryProjectId: row.factoryProjectId,
+			threadId,
+			resourceId,
+			sessionId: row.sessionId
+		});
+		if (latest?.orgId === row.orgId && latest.revokedAt && latest.revokedAt >= since) {
+			binding = latest;
+			break;
+		}
+	}
+	if (binding) return {
+		kind: "work-item",
+		binding,
+		sender: {
+			sessionId: row.sessionId,
+			threadId: binding.threadId,
+			userId: row.userId
+		}
+	};
+	if (!row.originSessionId || !row.originThreadId || !threadId) return null;
+	return {
+		kind: "origin",
+		sender: {
+			sessionId: row.sessionId,
+			threadId,
+			userId: row.userId
+		},
+		recipient: {
+			sessionId: row.originSessionId,
+			threadId: row.originThreadId
+		},
+		subject: `The side session "${row.title ?? row.sessionId}"`,
+		mutedAt: row.originMutedAt ?? null
+	};
+}
+/** Reports each run end of a work or side session to whoever follows it. */
+function createSessionRunEndReporter(deps) {
+	const workItemRunEnd = createWorkItemRunEndReporter(deps);
+	return async ({ sessionId, threadId, outcome, since }) => {
+		const audience = await sessionAudience(deps, sessionId, threadId, since);
+		if (!audience) return;
+		if (audience.kind === "work-item") {
+			const { binding, sender } = audience;
+			await workItemRunEnd({
+				orgId: binding.orgId,
+				factoryProjectId: binding.factoryProjectId,
+				workItemId: binding.workItemId,
+				role: binding.role,
+				sender,
+				since,
+				outcome
+			});
+			return;
+		}
+		if (audience.mutedAt && outcome.status !== "blocked") return;
+		const resolved = await deps.reporting();
+		if (!resolved) return;
+		await sendRunEndReport(resolved, {
+			sender: audience.sender,
+			recipients: [audience.recipient],
+			since,
+			outcome,
+			subject: audience.subject
+		});
+	};
+}
+/**
+* Tells whoever follows a session, urgently, the moment its run holds a tool
+* call for approval. The run stays open on the gate, so no run end would say
+* so; the notice names the session and call so a follower can answer it with
+* `factory_answer_approval`.
+*/
+function createSessionApprovalNotifier(deps) {
+	return async ({ sessionId, threadId, toolName, toolCallId, args }) => {
+		const audience = await sessionAudience(deps, sessionId, threadId);
+		if (!audience) return;
+		const resolved = await deps.reporting();
+		if (!resolved) return;
+		let subject;
+		let recipients;
+		let attributes = {};
+		if (audience.kind === "work-item") {
+			const { binding } = audience;
+			recipients = await workItemReportRecipients(deps.workItems, {
+				orgId: binding.orgId,
+				workItemId: binding.workItemId,
+				senderSessionId: audience.sender.sessionId
+			});
+			const named = await workItemReportAttributes(deps.workItems, binding);
+			subject = `The ${binding.role} session for ${named.label}`;
+			attributes = named.attributes;
+		} else {
+			recipients = [audience.recipient];
+			subject = audience.subject;
+		}
+		if (recipients.length === 0) return;
+		const argsText = JSON.stringify(args ?? {}) ?? "{}";
+		const quoted = argsText.length > APPROVAL_ARGS_LENGTH ? `${argsText.slice(0, APPROVAL_ARGS_LENGTH)}…` : argsText;
+		const message = [`${subject} is waiting for approval to run ${toolName} with ${quoted}.`, `Answer it with factory_answer_approval (sessionId "${audience.sender.sessionId}", toolCallId "${toolCallId}"), or open that session to approve or decline it there.`].join(" ");
+		const notification = {
+			...reportNotification({
+				sender: audience.sender,
+				message,
+				attributes: {
+					...attributes,
+					"waiting-for": "approval",
+					"tool-name": toolName,
+					"tool-call-id": toolCallId
+				}
+			}),
+			kind: "approval",
+			priority: "urgent",
+			dedupeKey: `factory-approval:${toolCallId}`
+		};
+		for (const recipient of recipients) await resolved.deliver(recipient, notification);
+	};
+}
+//#endregion
+export { FACTORY_REPORT_FORMS, createSessionApprovalNotifier, createSessionRunEndReporter, createStageChangeNotifier, createWorkItemRunEndReporter, hasFinalReport, repeatsLastFailure, reportNotification, sendRunEndReport, workItemReportAttributes, workItemReportRecipients };
+
+//# sourceMappingURL=reports.js.map

package/dist/tools/reports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reports.js","names":[],"sources":["../../src/tools/reports.ts"],"sourcesContent":["/**\n * Reports from sessions doing the work back to whoever follows it: a side\n * session's origin, or every subscriber of a work item. The agent reports with\n * `factory_message_origin`; when a run ends without one, the run-end backstop\n * sends it, so each run produces exactly one final report per recipient.\n */\n\nimport type {\n  NotificationPriority,\n  NotificationsStorage,\n  SendNotificationSignalInput,\n} from '@mastra/core/notifications';\n\nimport type { SourceControlSessionLookup } from '../session/factory-session.js';\nimport type { WorkItemsStorage } from '../storage/domains/work-items/base.js';\nimport { FACTORY_SESSION_NOTIFICATION_SOURCE } from './deliver.js';\nimport type { FactoryDeliveryResult, FactoryDeliveryTarget } from './deliver.js';\nimport { workItemNumber } from './read-tools.js';\n\nexport type FactoryReportStatus = 'progress' | 'blocked' | 'done' | 'failed';\n\n/** How each report status travels. Final reports never coalesce, so a later report can't overwrite them. */\nexport const FACTORY_REPORT_FORMS: Record<\n  FactoryReportStatus | 'report',\n  { kind: string; priority: NotificationPriority; coalesce: boolean }\n> = {\n  failed: { kind: 'failed', priority: 'urgent', coalesce: false },\n  blocked: { kind: 'blocked', priority: 'urgent', coalesce: false },\n  done: { kind: 'done', priority: 'high', coalesce: false },\n  progress: { kind: 'progress', priority: 'low', coalesce: true },\n  // Not `message`: only messages can be answered, so a report can't start a reply loop.\n  report: { kind: 'report', priority: 'high', coalesce: false },\n};\n\n/** How many recent `factory-session` notifications on a recipient thread the final-report check reads. */\nconst FINAL_REPORT_SCAN = 100;\n\nexport interface FactoryReportSender {\n  sessionId: string;\n  threadId: string;\n  userId: string;\n}\n\nexport type FactoryReportDeliver = (\n  target: FactoryDeliveryTarget,\n  notification: Omit<SendNotificationSignalInput, 'source'>,\n  options?: { onlyIfLive?: boolean },\n) => Promise<FactoryDeliveryResult>;\n\nexport interface FactoryReporting {\n  deliver: FactoryReportDeliver;\n  notifications: Pick<NotificationsStorage, 'listNotifications'>;\n}\n\n/**\n * Whether `senderSessionId` already put a report of one of `kinds` on the\n * recipient thread since `since`. Reads the durable notifications store, so it\n * holds across restarts. `listNotifications` has no time filter: records come\n * newest-updated first, and the scan stops at the first one last updated\n * before `since` (nothing after it can have been created later).\n */\nexport async function hasFinalReport(\n  notifications: FactoryReporting['notifications'],\n  {\n    senderSessionId,\n    recipientThreadId,\n    since,\n    kinds,\n    agentOnly = false,\n  }: {\n    senderSessionId: string;\n    recipientThreadId: string;\n    since: Date;\n    kinds: readonly string[];\n    /** Ignore reports Factory sent on the session's behalf (the backstop). */\n    agentOnly?: boolean;\n  },\n): Promise<boolean> {\n  const records = await notifications.listNotifications({\n    threadId: recipientThreadId,\n    source: FACTORY_SESSION_NOTIFICATION_SOURCE,\n    limit: FINAL_REPORT_SCAN,\n  });\n  for (const record of records) {\n    if (record.updatedAt < since) break;\n    if (\n      record.attributes?.['from-session'] === senderSessionId &&\n      !(agentOnly && record.attributes?.backstop === 'true') &&\n      // A reply carrying a final status counts like the report itself.\n      (kinds.includes(record.kind) ||\n        (record.kind === 'reply' &&\n          typeof record.attributes?.status === 'string' &&\n          kinds.includes(record.attributes.status))) &&\n      record.createdAt >= since\n    ) {\n      return true;\n    }\n  }\n  return false;\n}\n\n/**\n * Whether the newest report `senderSessionId` put on the recipient thread is\n * already this exact `failed` backstop. A session stuck failing the same way\n * (a run that dies before the model, restarted over and over) then reports\n * once, not once per attempt; any other report in between resets it.\n */\nexport async function repeatsLastFailure(\n  notifications: FactoryReporting['notifications'],\n  {\n    senderSessionId,\n    recipientThreadId,\n    summary,\n  }: { senderSessionId: string; recipientThreadId: string; summary: string },\n): Promise<boolean> {\n  const records = await notifications.listNotifications({\n    threadId: recipientThreadId,\n    source: FACTORY_SESSION_NOTIFICATION_SOURCE,\n    limit: FINAL_REPORT_SCAN,\n  });\n  // Storage orders by `updatedAt`, which moves when a report is read; the\n  // newest report is the one created last.\n  const last = records\n    .filter(record => record.attributes?.['from-session'] === senderSessionId)\n    .reduce<(typeof records)[number] | undefined>(\n      (newest, record) => (!newest || record.createdAt > newest.createdAt ? record : newest),\n      undefined,\n    );\n  return last?.kind === 'failed' && last.attributes?.backstop === 'true' && last.summary === summary;\n}\n\nexport function reportNotification({\n  sender,\n  status,\n  message,\n  attributes = {},\n}: {\n  sender: FactoryReportSender;\n  status?: FactoryReportStatus;\n  message: string;\n  attributes?: Record<string, string>;\n}): Omit<SendNotificationSignalInput, 'source'> {\n  const form = FACTORY_REPORT_FORMS[status ?? 'report'];\n  return {\n    kind: form.kind,\n    priority: form.priority,\n    // The whole text: a notification's summary is all the recipient's agent ever sees, even\n    // through notification_inbox (which hides payloads), so a cut-off report loses its verdict.\n    summary: message,\n    payload: { message },\n    sourceId: sender.sessionId,\n    ...(form.coalesce ? { coalesceKey: `factory-session:${sender.sessionId}:${form.kind}` } : {}),\n    attributes: {\n      ...attributes,\n      ...(status ? { status } : {}),\n      // Last, so nothing above can claim another sender.\n      'from-session': sender.sessionId,\n      'from-thread': sender.threadId,\n      'from-user': sender.userId,\n    },\n  };\n}\n\n/** Everyone following a work item, except the session doing the reporting. */\nexport async function workItemReportRecipients(\n  workItems: Pick<WorkItemsStorage, 'listWorkItemSubscribers'>,\n  { orgId, workItemId, senderSessionId }: { orgId: string; workItemId: string; senderSessionId: string },\n): Promise<FactoryDeliveryTarget[]> {\n  const subscribers = await workItems.listWorkItemSubscribers({ orgId, workItemId });\n  return subscribers\n    .filter(subscriber => subscriber.sessionId !== senderSessionId)\n    .map(subscriber => ({ sessionId: subscriber.sessionId, threadId: subscriber.threadId }));\n}\n\n/** How reports name an item: `#n`, else its quoted title, else its id. */\nasync function workItemReference(\n  workItems: Pick<WorkItemsStorage, 'getForProject'>,\n  { orgId, factoryProjectId, workItemId }: { orgId: string; factoryProjectId: string; workItemId: string },\n): Promise<{ label: string; ref: string }> {\n  const item = await workItems.getForProject(orgId, factoryProjectId, workItemId);\n  const number = item ? workItemNumber(item) : null;\n  if (number !== null) return { label: `#${number}`, ref: `#${number}` };\n  return { label: item ? `\"${item.title}\"` : workItemId, ref: workItemId };\n}\n\n/** Attributes that say which item and role a worker's report is about. */\nexport async function workItemReportAttributes(\n  workItems: Pick<WorkItemsStorage, 'getForProject'>,\n  {\n    orgId,\n    factoryProjectId,\n    workItemId,\n    role,\n  }: { orgId: string; factoryProjectId: string; workItemId: string; role: string },\n): Promise<{ label: string; attributes: Record<string, string> }> {\n  const { label, ref } = await workItemReference(workItems, { orgId, factoryProjectId, workItemId });\n  return { label, attributes: { 'work-item': ref, role } };\n}\n\nexport type FactoryRunOutcome =\n  | { status: 'done' }\n  | { status: 'failed'; reason: string; failureCode?: string }\n  | { status: 'blocked'; toolName?: string; approval?: boolean };\n\n/** `waiting`: the session is waiting for an answer, so a later run owes the final report. */\nexport interface FactoryRunEndResult {\n  waiting: boolean;\n  deliveries?: FactoryDeliveryResult[];\n}\n\n/**\n * The run-end backstop: send `outcome` to each recipient that hasn't had a\n * final report from this sender since the run started. An agent's own `done`\n * or `failed` report wins. A run that completes after the agent's own\n * `blocked` sends nothing: the agent ended its turn to wait for an answer, and\n * its `done` comes from a later run. A `failed` backstop still goes out after an\n * earlier `blocked`.\n */\nexport async function sendRunEndReport(\n  reporting: FactoryReporting,\n  {\n    sender,\n    recipients,\n    since,\n    outcome,\n    subject,\n    attributes = {},\n  }: {\n    sender: FactoryReportSender;\n    recipients: FactoryDeliveryTarget[];\n    since: Date;\n    outcome: FactoryRunOutcome;\n    /** Who finished, e.g. \"The work session for #12\". */\n    subject: string;\n    attributes?: Record<string, string>;\n  },\n): Promise<FactoryRunEndResult> {\n  const kinds = outcome.status === 'blocked' ? ['blocked'] : ['done', 'failed'];\n  const message =\n    outcome.status === 'done'\n      ? `${subject} finished.`\n      : outcome.status === 'failed'\n        ? `${subject} failed${outcome.failureCode ? ` (${outcome.failureCode})` : ''}: ${outcome.reason}`\n        : outcome.approval\n          ? `${subject} is waiting for someone to approve ${outcome.toolName ?? 'a tool call'} in that session.`\n          : `${subject} is waiting${outcome.toolName ? ` on ${outcome.toolName}` : ''} and needs an answer.`;\n  const notification = reportNotification({\n    sender,\n    status: outcome.status,\n    message,\n    attributes: {\n      ...attributes,\n      backstop: 'true',\n      ...(outcome.status === 'failed' && outcome.failureCode ? { 'failure-code': outcome.failureCode } : {}),\n      ...(outcome.status === 'blocked' && outcome.toolName ? { 'parked-tool': outcome.toolName } : {}),\n      ...(outcome.status === 'blocked' && outcome.approval ? { 'waiting-for': 'approval' } : {}),\n    },\n  });\n  const report = (recipient: FactoryDeliveryTarget, reportKinds: string[], agentOnly = false) =>\n    hasFinalReport(reporting.notifications, {\n      senderSessionId: sender.sessionId,\n      recipientThreadId: recipient.threadId,\n      since,\n      kinds: reportKinds,\n      agentOnly,\n    });\n  let waiting = outcome.status === 'blocked';\n  const deliveries: FactoryDeliveryResult[] = [];\n  for (const recipient of recipients) {\n    // Only the agent's own reports count: an earlier run's backstop lands after this\n    // run's window opened. A reply already told that follower how a finished run went.\n    if (await report(recipient, outcome.status === 'done' ? [...kinds, 'reply'] : kinds, true)) continue;\n    // Only the agent's own `blocked` means it ended its turn to wait; a backstop `blocked` from a parked run doesn't.\n    if (outcome.status === 'done' && (await report(recipient, ['blocked'], true))) {\n      waiting = true;\n      continue;\n    }\n    if (\n      outcome.status === 'failed' &&\n      (await repeatsLastFailure(reporting.notifications, {\n        senderSessionId: sender.sessionId,\n        recipientThreadId: recipient.threadId,\n        summary: message,\n      }))\n    ) {\n      continue;\n    }\n    deliveries.push(await reporting.deliver(recipient, notification));\n  }\n  return { waiting, deliveries };\n}\n\nexport interface FactoryRunEndInput {\n  orgId: string;\n  factoryProjectId: string;\n  workItemId: string;\n  role: string;\n  sender: FactoryReportSender;\n  since: Date;\n  outcome: FactoryRunOutcome;\n}\n\nexport type FactoryRunEndReporter = (input: FactoryRunEndInput) => Promise<FactoryRunEndResult>;\n\n/** The backstop for a work-item run: reports to the item's subscribers. Failures are logged, never thrown. */\nexport function createWorkItemRunEndReporter({\n  workItems,\n  reporting,\n}: {\n  workItems: Pick<WorkItemsStorage, 'listWorkItemSubscribers' | 'getForProject'>;\n  /** Resolved per report: the controller exists only once the mount is up. */\n  reporting: () => Promise<FactoryReporting | null>;\n}): FactoryRunEndReporter {\n  return async input => {\n    try {\n      const resolved = await reporting();\n      if (!resolved) return { waiting: false };\n      const recipients = await workItemReportRecipients(workItems, {\n        orgId: input.orgId,\n        workItemId: input.workItemId,\n        senderSessionId: input.sender.sessionId,\n      });\n      if (recipients.length === 0) return { waiting: false };\n      const { label, attributes } = await workItemReportAttributes(workItems, input);\n      return await sendRunEndReport(resolved, {\n        sender: input.sender,\n        recipients,\n        since: input.since,\n        outcome: input.outcome,\n        subject: `The ${input.role} session for ${label}`,\n        attributes,\n      });\n    } catch (error) {\n      console.warn('[Factory reports] Unable to send the run-end report.', error);\n      return { waiting: false };\n    }\n  };\n}\n\nexport interface FactoryStageChange {\n  orgId: string;\n  factoryProjectId: string;\n  workItemId: string;\n  fromStage: string | undefined;\n  toStage: string;\n}\n\n/**\n * Tells a work item's subscribers it moved, at `low` priority. Only sessions\n * already live hear it: a stage change never brings a session online; an\n * offline subscriber sees the stage in its state signal on its next turn.\n */\nexport function createStageChangeNotifier({\n  workItems,\n  reporting,\n}: {\n  workItems: Pick<WorkItemsStorage, 'listWorkItemSubscribers' | 'getForProject'>;\n  reporting: () => Promise<FactoryReporting | null>;\n}): (change: FactoryStageChange) => Promise<void> {\n  return async change => {\n    const subscribers = await workItems.listWorkItemSubscribers({\n      orgId: change.orgId,\n      workItemId: change.workItemId,\n    });\n    if (subscribers.length === 0) return;\n    const resolved = await reporting();\n    if (!resolved) return;\n    const { label, ref } = await workItemReference(workItems, change);\n    const summary = change.fromStage\n      ? `${label} moved from ${change.fromStage} to ${change.toStage}.`\n      : `${label} moved to ${change.toStage}.`;\n    const notification: Omit<SendNotificationSignalInput, 'source'> = {\n      kind: 'stage',\n      priority: 'low',\n      summary,\n      payload: { message: summary },\n      sourceId: change.workItemId,\n      coalesceKey: `factory-stage:${change.workItemId}`,\n      attributes: {\n        'work-item': ref,\n        ...(change.fromStage ? { 'from-stage': change.fromStage } : {}),\n        'to-stage': change.toStage,\n      },\n    };\n    for (const subscriber of subscribers) {\n      try {\n        await resolved.deliver({ sessionId: subscriber.sessionId, threadId: subscriber.threadId }, notification, {\n          onlyIfLive: true,\n        });\n      } catch (error) {\n        console.warn(`[Factory reports] Unable to tell ${subscriber.sessionId} that ${label} moved.`, error);\n      }\n    }\n  };\n}\n\n/** Reports one run end of a session; the thread is the one the run used. */\nexport type FactorySessionRunEndReporter = (input: {\n  sessionId: string;\n  threadId: string | null;\n  outcome: FactoryRunOutcome;\n  since: Date;\n}) => Promise<void>;\n\n/** A tool call a session's run is holding until someone approves or declines it. */\nexport interface FactoryApprovalRequest {\n  sessionId: string;\n  threadId: string | null;\n  toolName: string;\n  toolCallId: string;\n  args: unknown;\n}\n\nexport type FactoryApprovalNotifier = (request: FactoryApprovalRequest) => Promise<void>;\n\ninterface SessionReportDependencies {\n  sessions: Pick<SourceControlSessionLookup, 'getBySessionId'>;\n  workItems: Pick<\n    WorkItemsStorage,\n    'findActiveRunBindingForSession' | 'findRunBindingBySession' | 'listWorkItemSubscribers' | 'getForProject'\n  >;\n  reporting: () => Promise<FactoryReporting | null>;\n}\n\n/** How much of a gated call's arguments an approval notice quotes. */\nconst APPROVAL_ARGS_LENGTH = 3000;\n\n/**\n * Who hears from a session: a work session (one with an active run binding)\n * reports to its item's followers, a side session to the session that started\n * it. Any other session (a person's own) has nobody to tell.\n */\nasync function sessionAudience(\n  { sessions, workItems }: Omit<SessionReportDependencies, 'reporting'>,\n  sessionId: string,\n  threadId: string | null,\n  /** When the run started: a binding revoked since then (the run moved its card to a finished stage) still counts. */\n  since?: Date,\n): Promise<\n  | {\n      kind: 'work-item';\n      binding: NonNullable<Awaited<ReturnType<WorkItemsStorage['findActiveRunBindingForSession']>>>;\n      sender: FactoryReportSender;\n    }\n  | {\n      kind: 'origin';\n      sender: FactoryReportSender;\n      recipient: FactoryDeliveryTarget;\n      subject: string;\n      /** Set while the origin has muted this side session's reports (approval notices still go through). */\n      mutedAt: Date | null;\n    }\n  | null\n> {\n  const row = await sessions.getBySessionId(sessionId);\n  if (!row?.factoryProjectId) return null;\n  let binding = await workItems.findActiveRunBindingForSession({\n    orgId: row.orgId,\n    factoryProjectId: row.factoryProjectId,\n    sessionId: row.sessionId,\n  });\n  if (!binding && since && threadId) {\n    // The binding records the memory resource the run used: the Factory's, its\n    // own id for a run kept on its own resource, or its owner's for a person's\n    // session the run started in.\n    for (const resourceId of new Set([row.factoryProjectId, row.sessionId, row.userId])) {\n      const latest = await workItems.findRunBindingBySession({\n        factoryProjectId: row.factoryProjectId,\n        threadId,\n        resourceId,\n        sessionId: row.sessionId,\n      });\n      if (latest?.orgId === row.orgId && latest.revokedAt && latest.revokedAt >= since) {\n        binding = latest;\n        break;\n      }\n    }\n  }\n  if (binding) {\n    return {\n      kind: 'work-item',\n      binding,\n      sender: { sessionId: row.sessionId, threadId: binding.threadId, userId: row.userId },\n    };\n  }\n  if (!row.originSessionId || !row.originThreadId || !threadId) return null;\n  return {\n    kind: 'origin',\n    sender: { sessionId: row.sessionId, threadId, userId: row.userId },\n    recipient: { sessionId: row.originSessionId, threadId: row.originThreadId },\n    subject: `The side session \"${row.title ?? row.sessionId}\"`,\n    mutedAt: row.originMutedAt ?? null,\n  };\n}\n\n/** Reports each run end of a work or side session to whoever follows it. */\nexport function createSessionRunEndReporter(deps: SessionReportDependencies): FactorySessionRunEndReporter {\n  const workItemRunEnd = createWorkItemRunEndReporter(deps);\n  return async ({ sessionId, threadId, outcome, since }) => {\n    const audience = await sessionAudience(deps, sessionId, threadId, since);\n    if (!audience) return;\n    if (audience.kind === 'work-item') {\n      const { binding, sender } = audience;\n      await workItemRunEnd({\n        orgId: binding.orgId,\n        factoryProjectId: binding.factoryProjectId,\n        workItemId: binding.workItemId,\n        role: binding.role,\n        sender,\n        since,\n        outcome,\n      });\n      return;\n    }\n    // A muted origin still hears when the session is blocked: nothing else would tell it the session is waiting.\n    if (audience.mutedAt && outcome.status !== 'blocked') return;\n    const resolved = await deps.reporting();\n    if (!resolved) return;\n    await sendRunEndReport(resolved, {\n      sender: audience.sender,\n      recipients: [audience.recipient],\n      since,\n      outcome,\n      subject: audience.subject,\n    });\n  };\n}\n\n/**\n * Tells whoever follows a session, urgently, the moment its run holds a tool\n * call for approval. The run stays open on the gate, so no run end would say\n * so; the notice names the session and call so a follower can answer it with\n * `factory_answer_approval`.\n */\nexport function createSessionApprovalNotifier(deps: SessionReportDependencies): FactoryApprovalNotifier {\n  return async ({ sessionId, threadId, toolName, toolCallId, args }) => {\n    const audience = await sessionAudience(deps, sessionId, threadId);\n    if (!audience) return;\n    const resolved = await deps.reporting();\n    if (!resolved) return;\n    let subject: string;\n    let recipients: FactoryDeliveryTarget[];\n    let attributes: Record<string, string> = {};\n    if (audience.kind === 'work-item') {\n      const { binding } = audience;\n      recipients = await workItemReportRecipients(deps.workItems, {\n        orgId: binding.orgId,\n        workItemId: binding.workItemId,\n        senderSessionId: audience.sender.sessionId,\n      });\n      const named = await workItemReportAttributes(deps.workItems, binding);\n      subject = `The ${binding.role} session for ${named.label}`;\n      attributes = named.attributes;\n    } else {\n      recipients = [audience.recipient];\n      subject = audience.subject;\n    }\n    if (recipients.length === 0) return;\n    const argsText = JSON.stringify(args ?? {}) ?? '{}';\n    const quoted = argsText.length > APPROVAL_ARGS_LENGTH ? `${argsText.slice(0, APPROVAL_ARGS_LENGTH)}…` : argsText;\n    const message = [\n      `${subject} is waiting for approval to run ${toolName} with ${quoted}.`,\n      `Answer it with factory_answer_approval (sessionId \"${audience.sender.sessionId}\", toolCallId \"${toolCallId}\"), or open that session to approve or decline it there.`,\n    ].join(' ');\n    const notification = {\n      ...reportNotification({\n        sender: audience.sender,\n        message,\n        attributes: { ...attributes, 'waiting-for': 'approval', 'tool-name': toolName, 'tool-call-id': toolCallId },\n      }),\n      kind: 'approval',\n      priority: 'urgent' as const,\n      // One notice per held call, even if the gate is announced again.\n      dedupeKey: `factory-approval:${toolCallId}`,\n    };\n    for (const recipient of recipients) await resolved.deliver(recipient, notification);\n  };\n}\n"],"mappings":"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"}

package/dist/tools/run-watch.d.ts

@@ -0,0 +1,46 @@
+import type { AgentControllerEvent } from '@mastra/core/agent-controller';
+import type { RunEndCaptureSession } from '../session/run-audit.js';
+import type { FactoryRunOutcome } from './reports.js';
+type RunEndReason = Extract<AgentControllerEvent, {
+    type: 'agent_end';
+}>['reason'];
+/** What a run stopped on: a tool waiting for an answer, or one waiting for approval. */
+export interface ParkedTool {
+    toolName: string;
+    toolCallId: string;
+    approval: boolean;
+}
+export interface RunReportSession {
+    subscribe(listener: (event: AgentControllerEvent) => void): () => void;
+}
+/** Reports one run's end; `since` is when the run's window opened. Should not throw. */
+export type SessionRunEndReport = (outcome: FactoryRunOutcome, since: Date) => Promise<void>;
+/** Told when the run holds a tool call for approval; the run stays open meanwhile. */
+export type SessionApprovalReport = (request: {
+    toolName: string;
+    toolCallId: string;
+    args: unknown;
+}) => Promise<void>;
+/**
+ * Report every run end of a session, however the run started: the board, a
+ * typed message, a wake, or a run after a restart. Attached to each Factory
+ * session when it is created, so it outlives any one start. A run someone
+ * stopped or steered says nothing, and its window carries into the next run,
+ * so reports the agent made in it still count.
+ */
+export declare function observeSessionRunReports(session: RunReportSession, report: SessionRunEndReport, { onApprovalRequested }?: {
+    onApprovalRequested?: SessionApprovalReport;
+}): () => void;
+/**
+ * Renew a kicked-off run's open-run entry until the run ends, like the
+ * dispatcher's heartbeat, so no dispatcher starts the role again meanwhile.
+ * `endReason` is how that run ended, once it has; `stop` is for a kickoff that fails.
+ */
+export declare function heartbeatOpenRunUntilEnd(session: RunEndCaptureSession, kickoffId: string): {
+    endReason: () => RunEndReason;
+    stop: () => void;
+};
+/** `null` for an aborted run: someone stopped or steered it, which is not an outcome. */
+export declare function runOutcome(reason: RunEndReason, parked: Pick<ParkedTool, 'toolName' | 'approval'> | undefined, errorMessage?: string): FactoryRunOutcome | null;
+export {};
+//# sourceMappingURL=run-watch.d.ts.map

package/dist/tools/run-watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-watch.d.ts","sourceRoot":"","sources":["../../src/tools/run-watch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAG1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,KAAK,YAAY,GAAG,OAAO,CAAC,oBAAoB,EAAE;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;AAEnF,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACxE;AAED,wFAAwF;AACxF,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE7F,sFAAsF;AACtF,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAKxH;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,mBAAmB,EAC3B,EAAE,mBAAmB,EAAE,GAAE;IAAE,mBAAmB,CAAC,EAAE,qBAAqB,CAAA;CAAO,GAC5E,MAAM,IAAI,CAwCZ;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,MAAM,GAChB;IAAE,SAAS,EAAE,MAAM,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,IAAI,CAAA;CAAE,CAqBrD;AAED,yFAAyF;AACzF,wBAAgB,UAAU,CACxB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC,GAAG,SAAS,EAC7D,YAAY,CAAC,EAAE,MAAM,GACpB,iBAAiB,GAAG,IAAI,CAqB1B"}

package/dist/tools/run-watch.js

@@ -0,0 +1,102 @@
+import { FACTORY_OPEN_RUN_STALE_MS, heartbeatSessionOpenRun } from "../session/run-audit.js";
+//#region src/tools/run-watch.ts
+/** How much of a run's error message a `failed` report quotes. */
+const ERROR_MESSAGE_LENGTH = 400;
+/**
+* Report every run end of a session, however the run started: the board, a
+* typed message, a wake, or a run after a restart. Attached to each Factory
+* session when it is created, so it outlives any one start. A run someone
+* stopped or steered says nothing, and its window carries into the next run,
+* so reports the agent made in it still count.
+*/
+function observeSessionRunReports(session, report, { onApprovalRequested } = {}) {
+	let parked;
+	let lastError;
+	let since = /* @__PURE__ */ new Date();
+	const settle = (work) => void work.catch((error) => {
+		console.warn("[Factory reports] Unable to report on a session run.", error);
+	});
+	return session.subscribe((event) => {
+		if (event.type === "tool_suspended" || event.type === "tool_approval_required") {
+			parked = {
+				toolName: event.toolName,
+				toolCallId: event.toolCallId,
+				approval: event.type === "tool_approval_required"
+			};
+			if (event.type === "tool_approval_required" && onApprovalRequested) settle(onApprovalRequested({
+				toolName: event.toolName,
+				toolCallId: event.toolCallId,
+				args: event.args
+			}));
+			return;
+		}
+		if (event.type === "error") {
+			lastError = event.error?.message;
+			return;
+		}
+		if (event.type === "tool_suspension_cancelled" && parked?.toolCallId === event.toolCallId) {
+			parked = void 0;
+			return;
+		}
+		if (event.type !== "agent_end") return;
+		const outcome = runOutcome(event.reason, parked, lastError);
+		parked = void 0;
+		lastError = void 0;
+		if (!outcome) return;
+		const runSince = since;
+		since = new Date(Date.now() + 1);
+		settle(report(outcome, runSince));
+	});
+}
+/**
+* Renew a kicked-off run's open-run entry until the run ends, like the
+* dispatcher's heartbeat, so no dispatcher starts the role again meanwhile.
+* `endReason` is how that run ended, once it has; `stop` is for a kickoff that fails.
+*/
+function heartbeatOpenRunUntilEnd(session, kickoffId) {
+	let endReason;
+	let unsubscribe = () => {};
+	const timer = setInterval(() => void heartbeatSessionOpenRun(session, kickoffId), Math.floor(FACTORY_OPEN_RUN_STALE_MS / 3));
+	timer.unref?.();
+	let stopped = false;
+	const stop = () => {
+		if (stopped) return;
+		stopped = true;
+		clearInterval(timer);
+		unsubscribe();
+	};
+	unsubscribe = session.subscribe((event) => {
+		if (event.type !== "agent_end") return;
+		endReason ??= event.reason;
+		stop();
+	});
+	return {
+		endReason: () => endReason,
+		stop
+	};
+}
+/** `null` for an aborted run: someone stopped or steered it, which is not an outcome. */
+function runOutcome(reason, parked, errorMessage) {
+	switch (reason) {
+		case "error": {
+			const message = errorMessage?.trim();
+			return {
+				status: "failed",
+				reason: message ? `the run ended in error: ${message.slice(0, ERROR_MESSAGE_LENGTH)}` : "the run ended in error."
+			};
+		}
+		case "aborted": return null;
+		case "suspended": return {
+			status: "blocked",
+			...parked ? {
+				toolName: parked.toolName,
+				...parked.approval ? { approval: true } : {}
+			} : {}
+		};
+		default: return { status: "done" };
+	}
+}
+//#endregion
+export { heartbeatOpenRunUntilEnd, observeSessionRunReports, runOutcome };
+
+//# sourceMappingURL=run-watch.js.map

package/dist/tools/run-watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-watch.js","names":[],"sources":["../../src/tools/run-watch.ts"],"sourcesContent":["import type { AgentControllerEvent } from '@mastra/core/agent-controller';\n\nimport { FACTORY_OPEN_RUN_STALE_MS, heartbeatSessionOpenRun } from '../session/run-audit.js';\nimport type { RunEndCaptureSession } from '../session/run-audit.js';\nimport type { FactoryRunOutcome } from './reports.js';\n\ntype RunEndReason = Extract<AgentControllerEvent, { type: 'agent_end' }>['reason'];\n\n/** What a run stopped on: a tool waiting for an answer, or one waiting for approval. */\nexport interface ParkedTool {\n  toolName: string;\n  toolCallId: string;\n  approval: boolean;\n}\n\nexport interface RunReportSession {\n  subscribe(listener: (event: AgentControllerEvent) => void): () => void;\n}\n\n/** Reports one run's end; `since` is when the run's window opened. Should not throw. */\nexport type SessionRunEndReport = (outcome: FactoryRunOutcome, since: Date) => Promise<void>;\n\n/** Told when the run holds a tool call for approval; the run stays open meanwhile. */\nexport type SessionApprovalReport = (request: { toolName: string; toolCallId: string; args: unknown }) => Promise<void>;\n\n/** How much of a run's error message a `failed` report quotes. */\nconst ERROR_MESSAGE_LENGTH = 400;\n\n/**\n * Report every run end of a session, however the run started: the board, a\n * typed message, a wake, or a run after a restart. Attached to each Factory\n * session when it is created, so it outlives any one start. A run someone\n * stopped or steered says nothing, and its window carries into the next run,\n * so reports the agent made in it still count.\n */\nexport function observeSessionRunReports(\n  session: RunReportSession,\n  report: SessionRunEndReport,\n  { onApprovalRequested }: { onApprovalRequested?: SessionApprovalReport } = {},\n): () => void {\n  let parked: ParkedTool | undefined;\n  let lastError: string | undefined;\n  let since = new Date();\n  const settle = (work: Promise<void>) =>\n    void work.catch(error => {\n      console.warn('[Factory reports] Unable to report on a session run.', error);\n    });\n  return session.subscribe(event => {\n    if (event.type === 'tool_suspended' || event.type === 'tool_approval_required') {\n      parked = {\n        toolName: event.toolName,\n        toolCallId: event.toolCallId,\n        approval: event.type === 'tool_approval_required',\n      };\n      // An approval gate holds the run open, so it is announced now, not at the run's end.\n      if (event.type === 'tool_approval_required' && onApprovalRequested) {\n        settle(onApprovalRequested({ toolName: event.toolName, toolCallId: event.toolCallId, args: event.args }));\n      }\n      return;\n    }\n    if (event.type === 'error') {\n      lastError = event.error?.message;\n      return;\n    }\n    if (event.type === 'tool_suspension_cancelled' && parked?.toolCallId === event.toolCallId) {\n      parked = undefined;\n      return;\n    }\n    if (event.type !== 'agent_end') return;\n    const outcome = runOutcome(event.reason, parked, lastError);\n    parked = undefined;\n    lastError = undefined;\n    if (!outcome) return;\n    // Move the window now, so a run that starts before this report settles is judged on its own;\n    // reports made up to the end, including its last millisecond, belong to the run that ended.\n    const runSince = since;\n    since = new Date(Date.now() + 1);\n    settle(report(outcome, runSince));\n  });\n}\n\n/**\n * Renew a kicked-off run's open-run entry until the run ends, like the\n * dispatcher's heartbeat, so no dispatcher starts the role again meanwhile.\n * `endReason` is how that run ended, once it has; `stop` is for a kickoff that fails.\n */\nexport function heartbeatOpenRunUntilEnd(\n  session: RunEndCaptureSession,\n  kickoffId: string,\n): { endReason: () => RunEndReason; stop: () => void } {\n  let endReason: RunEndReason;\n  let unsubscribe = () => {};\n  const timer = setInterval(\n    () => void heartbeatSessionOpenRun(session, kickoffId),\n    Math.floor(FACTORY_OPEN_RUN_STALE_MS / 3),\n  );\n  timer.unref?.();\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    clearInterval(timer);\n    unsubscribe();\n  };\n  unsubscribe = session.subscribe(event => {\n    if (event.type !== 'agent_end') return;\n    endReason ??= event.reason;\n    stop();\n  });\n  return { endReason: () => endReason, stop };\n}\n\n/** `null` for an aborted run: someone stopped or steered it, which is not an outcome. */\nexport function runOutcome(\n  reason: RunEndReason,\n  parked: Pick<ParkedTool, 'toolName' | 'approval'> | undefined,\n  errorMessage?: string,\n): FactoryRunOutcome | null {\n  switch (reason) {\n    case 'error': {\n      const message = errorMessage?.trim();\n      return {\n        status: 'failed',\n        reason: message\n          ? `the run ended in error: ${message.slice(0, ERROR_MESSAGE_LENGTH)}`\n          : 'the run ended in error.',\n      };\n    }\n    case 'aborted':\n      return null;\n    case 'suspended':\n      return {\n        status: 'blocked',\n        ...(parked ? { toolName: parked.toolName, ...(parked.approval ? { approval: true } : {}) } : {}),\n      };\n    default:\n      return { status: 'done' };\n  }\n}\n"],"mappings":";;;AA0BA,MAAM,uBAAuB;;;;;;;;AAS7B,SAAgB,yBACd,SACA,QACA,EAAE,wBAAyE,CAAC,GAChE;CACZ,IAAI;CACJ,IAAI;CACJ,IAAI,wBAAQ,IAAI,KAAK;CACrB,MAAM,UAAU,SACd,KAAK,KAAK,OAAM,UAAS;EACvB,QAAQ,KAAK,wDAAwD,KAAK;CAC5E,CAAC;CACH,OAAO,QAAQ,WAAU,UAAS;EAChC,IAAI,MAAM,SAAS,oBAAoB,MAAM,SAAS,0BAA0B;GAC9E,SAAS;IACP,UAAU,MAAM;IAChB,YAAY,MAAM;IAClB,UAAU,MAAM,SAAS;GAC3B;GAEA,IAAI,MAAM,SAAS,4BAA4B,qBAC7C,OAAO,oBAAoB;IAAE,UAAU,MAAM;IAAU,YAAY,MAAM;IAAY,MAAM,MAAM;GAAK,CAAC,CAAC;GAE1G;EACF;EACA,IAAI,MAAM,SAAS,SAAS;GAC1B,YAAY,MAAM,OAAO;GACzB;EACF;EACA,IAAI,MAAM,SAAS,+BAA+B,QAAQ,eAAe,MAAM,YAAY;GACzF,SAAS,KAAA;GACT;EACF;EACA,IAAI,MAAM,SAAS,aAAa;EAChC,MAAM,UAAU,WAAW,MAAM,QAAQ,QAAQ,SAAS;EAC1D,SAAS,KAAA;EACT,YAAY,KAAA;EACZ,IAAI,CAAC,SAAS;EAGd,MAAM,WAAW;EACjB,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC;EAC/B,OAAO,OAAO,SAAS,QAAQ,CAAC;CAClC,CAAC;AACH;;;;;;AAOA,SAAgB,yBACd,SACA,WACqD;CACrD,IAAI;CACJ,IAAI,oBAAoB,CAAC;CACzB,MAAM,QAAQ,kBACN,KAAK,wBAAwB,SAAS,SAAS,GACrD,KAAK,MAAM,4BAA4B,CAAC,CAC1C;CACA,MAAM,QAAQ;CACd,IAAI,UAAU;CACd,MAAM,aAAa;EACjB,IAAI,SAAS;EACb,UAAU;EACV,cAAc,KAAK;EACnB,YAAY;CACd;CACA,cAAc,QAAQ,WAAU,UAAS;EACvC,IAAI,MAAM,SAAS,aAAa;EAChC,cAAc,MAAM;EACpB,KAAK;CACP,CAAC;CACD,OAAO;EAAE,iBAAiB;EAAW;CAAK;AAC5C;;AAGA,SAAgB,WACd,QACA,QACA,cAC0B;CAC1B,QAAQ,QAAR;EACE,KAAK,SAAS;GACZ,MAAM,UAAU,cAAc,KAAK;GACnC,OAAO;IACL,QAAQ;IACR,QAAQ,UACJ,2BAA2B,QAAQ,MAAM,GAAG,oBAAoB,MAChE;GACN;EACF;EACA,KAAK,WACH,OAAO;EACT,KAAK,aACH,OAAO;GACL,QAAQ;GACR,GAAI,SAAS;IAAE,UAAU,OAAO;IAAU,GAAI,OAAO,WAAW,EAAE,UAAU,KAAK,IAAI,CAAC;GAAG,IAAI,CAAC;EAChG;EACF,SACE,OAAO,EAAE,QAAQ,OAAO;CAC5B;AACF"}