@mastra/factory 0.24.0-alpha.1 → 0.24.0-alpha.2

package/dist/tools/messaging-tools.js

@@ -0,0 +1,312 @@
+import { FACTORY_SESSION_NOTIFICATION_SOURCE, deliverFactorySessionNotification, resolveSessionThread } from "./deliver.js";
+import { workItemNumber } from "./read-tools.js";
+import { reportNotification, workItemReportAttributes, workItemReportRecipients } from "./reports.js";
+import { z } from "zod";
+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;
+/** 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.";
+const message = z.string().trim().min(1).max(4e3);
+function senderAttributes(scope) {
+	return {
+		"from-session": scope.sessionId,
+		"from-thread": scope.threadId,
+		"from-user": scope.userId
+	};
+}
+function unavailable(result) {
+	return /* @__PURE__ */ new Error(`The session is not available (${result.reason}).`);
+}
+function createFactoryMessagingTools(scope, deps) {
+	const requireMessaging = async () => {
+		const messaging = await deps.messaging();
+		if (!messaging) throw new Error("Session messaging is not available on this server.");
+		return messaging;
+	};
+	const human = scope.kind === "user" && scope.interactive;
+	const audit = (input) => deps.auditRecorder.record({
+		orgId: scope.orgId,
+		actorId: human ? scope.userId : `agent:${scope.threadId}`,
+		actorType: human ? "human" : "agent",
+		action: "factory.agent.signaled",
+		factoryProjectId: scope.factoryProjectId,
+		targets: [{
+			type: "session",
+			id: input.targetSessionId
+		}],
+		metadata: {
+			targetSessionId: input.targetSessionId,
+			priority: input.priority,
+			kind: input.kind,
+			delivery: input.delivery
+		}
+	});
+	/** Why this session can't reach `row`, or null when it can: the rule for message targets and reply targets alike. */
+	const unreachable = (row) => {
+		if (!row || row.orgId !== scope.orgId || row.factoryProjectId !== scope.factoryProjectId) return "not-found";
+		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 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;
+	};
+	const recent = (notifications, threadId) => notifications.listNotifications({
+		threadId,
+		source: FACTORY_SESSION_NOTIFICATION_SOURCE,
+		limit: RECENT_SCAN
+	});
+	/** On turns nobody signed in started, only sessions working on items this session follows. */
+	const followedWorkers = async () => {
+		const project = {
+			orgId: scope.orgId,
+			factoryProjectId: scope.factoryProjectId
+		};
+		const follows = await deps.workItems.listSessionSubscriptions({
+			...project,
+			sessionId: scope.sessionId
+		});
+		const bindings = await Promise.all(follows.map((follow) => deps.workItems.listRunBindings(scope.orgId, scope.factoryProjectId, follow.workItemId)));
+		const sideSessions = await deps.sessions.listByOrigin({
+			orgId: scope.orgId,
+			originSessionId: scope.sessionId
+		});
+		return /* @__PURE__ */ new Set([...bindings.flat().filter((binding) => binding.status === "active").map((binding) => binding.sessionId), ...sideSessions.map((session) => session.sessionId)]);
+	};
+	const workItemAttribute = async (sessionId, orgId, factoryProjectId) => {
+		const binding = await deps.workItems.findActiveRunBindingForSession({
+			orgId,
+			factoryProjectId,
+			sessionId
+		});
+		if (!binding) return {};
+		const item = await deps.workItems.getForProject(orgId, factoryProjectId, binding.workItemId);
+		if (!item) return {};
+		const number = workItemNumber(item);
+		return { "work-item": number === null ? item.id : `#${number}` };
+	};
+	const signal = createTool({
+		id: "factory_signal_session",
+		description: [
+			"Send a message to another session in this Factory: a work item role session, or a teammate session you can see.",
+			"Replies come back to this session as `factory-session` notifications with kind `reply` and an `in-reply-to` attribute naming your message.",
+			"Priority `medium` (default) wakes an idle session and waits for a busy one to finish its step; use `urgent` only to make it stop and change course.",
+			...scope.interactive ? [] : ["On this turn you can only message your side sessions and sessions working on items this session follows."]
+		].join(" "),
+		inputSchema: z.object({
+			sessionId: z.string().trim().min(1).max(200).describe("The session to message."),
+			message: message.describe("What to say. It arrives as-is, so make it self-contained."),
+			priority: z.enum([
+				"low",
+				"medium",
+				"high",
+				"urgent"
+			]).default("medium")
+		}).strict(),
+		execute: async ({ sessionId, message: text, priority }) => {
+			if (sessionId === scope.sessionId) throw new Error("You can't message your own session.");
+			const row = await deps.sessions.getBySessionId(sessionId);
+			const blocked = unreachable(row);
+			if (blocked === "not-found" || !row) throw new Error(`No session ${sessionId} was found in this Factory.`);
+			if (blocked === "private") throw new Error(`Session ${sessionId} is private to its owner.`);
+			if (!scope.interactive && !(await followedWorkers()).has(sessionId)) throw new Error(`On this turn you can only message this session's side sessions and sessions working on items it follows; ${sessionId} isn't one.`);
+			const messaging = await requireMessaging();
+			const threadId = await resolveSessionThread({
+				controller: messaging.controller,
+				sessions: deps.sessions,
+				workItems: deps.workItems,
+				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,
+				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,
+				kind: "message",
+				delivery: result.delivered
+			});
+			return {
+				notificationId: result.notificationId,
+				delivered: result.delivered
+			};
+		}
+	});
+	const reply = createTool({
+		id: "factory_message_origin",
+		description: [
+			"Answer a message another Factory session sent you, or report on your work.",
+			"With `inReplyTo` (the id of a `factory-session` notification of kind `message`) the answer goes back to the session and thread that sent it; each message can be answered once.",
+			"Without it, the report goes to whoever follows your work: the session that started you, or everyone following your work item.",
+			"Set `status`: `progress` for an update, `blocked` when you need an answer to go on, `done` when finished, `failed` when you can't finish. Send one `done` or `failed` when you finish."
+		].join(" "),
+		inputSchema: z.object({
+			message: message.describe("Your answer."),
+			inReplyTo: z.string().trim().min(1).max(200).optional().describe("Id of the message notification you are answering."),
+			status: z.enum([
+				"progress",
+				"blocked",
+				"done",
+				"failed"
+			]).optional()
+		}).strict(),
+		execute: async ({ message: text, inReplyTo, status }) => {
+			if (!inReplyTo) return report(text, status);
+			const messaging = await requireMessaging();
+			const original = await messaging.notifications.getNotification({
+				threadId: scope.threadId,
+				id: inReplyTo
+			});
+			if (!original || original.source !== "factory-session") throw new Error(`No message ${inReplyTo} was sent to this session.`);
+			if (original.kind !== "message") throw new Error(`Only messages can be answered; ${inReplyTo} is a ${original.kind}.`);
+			const fromSession = original.attributes?.["from-session"];
+			const fromThread = original.attributes?.["from-thread"];
+			if (typeof fromSession !== "string" || typeof fromThread !== "string" || original.sourceId !== fromSession) throw new Error(`Message ${inReplyTo} doesn't say which session sent it.`);
+			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,
+				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",
+				kind: "reply",
+				delivery: result.delivered
+			});
+			return {
+				notificationId: result.notificationId,
+				delivered: result.delivered
+			};
+		}
+	});
+	/** A report with no message to answer: to the origin, else to the item's followers. */
+	async function report(text, status) {
+		const sender = {
+			sessionId: scope.sessionId,
+			threadId: scope.threadId,
+			userId: scope.userId
+		};
+		let recipients;
+		let attributes = {};
+		if (scope.origin) recipients = [scope.origin];
+		else {
+			const binding = await deps.workItems.findActiveRunBindingForSession({
+				orgId: scope.orgId,
+				factoryProjectId: scope.factoryProjectId,
+				sessionId: scope.sessionId
+			});
+			if (!binding) throw new Error("Nothing started this session; pass inReplyTo to answer a message.");
+			recipients = await workItemReportRecipients(deps.workItems, {
+				orgId: scope.orgId,
+				workItemId: binding.workItemId,
+				senderSessionId: scope.sessionId
+			});
+			({attributes} = await workItemReportAttributes(deps.workItems, {
+				orgId: scope.orgId,
+				factoryProjectId: scope.factoryProjectId,
+				workItemId: binding.workItemId,
+				role: binding.role
+			}));
+		}
+		if (recipients.length === 0) return {
+			delivered: 0,
+			recipients: []
+		};
+		const messaging = await requireMessaging();
+		const notification = reportNotification({
+			sender,
+			status,
+			message: text,
+			attributes
+		});
+		const results = [];
+		for (const recipient of recipients) {
+			if (status !== "progress" && overRateLimit(await recent(messaging.notifications, recipient.threadId))) {
+				results.push({
+					sessionId: recipient.sessionId,
+					delivered: "skipped",
+					reason: "rate-limited"
+				});
+				continue;
+			}
+			const result = await deliverFactorySessionNotification({
+				controller: messaging.controller,
+				sessions: deps.sessions,
+				target: recipient,
+				notification
+			});
+			results.push({
+				sessionId: recipient.sessionId,
+				delivered: result.delivered
+			});
+			if (result.delivered === "skipped") continue;
+			await audit({
+				targetSessionId: recipient.sessionId,
+				priority: notification.priority ?? "high",
+				kind: notification.kind,
+				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);
+		return {
+			delivered,
+			recipients: results
+		};
+	}
+	if (scope.kind === "worker") return { factory_message_origin: reply };
+	return {
+		factory_signal_session: signal,
+		factory_message_origin: reply
+	};
+}
+//#endregion
+export { SIGNAL_RATE_LIMIT, SIGNAL_RATE_WINDOW_MS, createFactoryMessagingTools };
+
+//# sourceMappingURL=messaging-tools.js.map

package/dist/tools/messaging-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging-tools.js","names":[],"sources":["../../src/tools/messaging-tools.ts"],"sourcesContent":["/**\n * Messages between Factory sessions. A user session can message any session in\n * its Factory it can see; the receiver answers that exact message. Both\n * directions are `factory-session` notifications on the receiver's stored thread.\n */\n\nimport type { NotificationPriority, NotificationRecord, NotificationsStorage } from '@mastra/core/notifications';\nimport { createTool } from '@mastra/core/tools';\nimport { z } from 'zod';\n\nimport type { IntegrationTools } from '../integrations/base.js';\nimport type { SourceControlSessionLookup } from '../session/factory-session.js';\nimport type { AuditRecorder } from '../storage/domains/audit/domain.js';\nimport type { SourceControlSession } from '../storage/domains/source-control/base.js';\nimport type { WorkItemsStorage } from '../storage/domains/work-items/base.js';\nimport {\n  FACTORY_SESSION_NOTIFICATION_SOURCE,\n  deliverFactorySessionNotification,\n  resolveSessionThread,\n} from './deliver.js';\nimport type { FactoryDeliveryController, FactoryDeliveryResult } from './deliver.js';\nimport { workItemNumber } from './read-tools.js';\nimport { reportNotification, workItemReportAttributes, workItemReportRecipients } from './reports.js';\nimport type { FactoryToolScope } from './scope.js';\n\n/** Messages plus replies, per sender session, per target thread, per window. */\nexport const SIGNAL_RATE_LIMIT = 10;\nexport const SIGNAL_RATE_WINDOW_MS = 10 * 60 * 1000;\n/** How many recent `factory-session` notifications on a thread the rate and duplicate checks read. */\nconst RECENT_SCAN = 100;\nconst RATE_LIMITED = 'Too many messages to that session in the last 10 minutes; wait before sending more.';\n\nexport interface FactoryMessaging {\n  controller: FactoryDeliveryController;\n  notifications: Pick<NotificationsStorage, 'listNotifications' | 'getNotification'>;\n}\n\nexport interface FactoryMessagingToolDependencies {\n  sessions: Pick<SourceControlSessionLookup, 'getBySessionId' | 'listByOrigin'>;\n  workItems: Pick<\n    WorkItemsStorage,\n    | 'findActiveRunBindingForSession'\n    | 'getForProject'\n    | 'listSessionSubscriptions'\n    | 'listRunBindings'\n    | 'listWorkItemSubscribers'\n  >;\n  auditRecorder: AuditRecorder;\n  /** The live controller and notifications store; resolved per call because they exist only once the mount is up. */\n  messaging: () => Promise<FactoryMessaging | null>;\n}\n\nconst message = z.string().trim().min(1).max(4000);\n\nfunction senderAttributes(scope: FactoryToolScope) {\n  return {\n    'from-session': scope.sessionId,\n    'from-thread': scope.threadId,\n    'from-user': scope.userId,\n  };\n}\n\nfunction unavailable(result: Extract<FactoryDeliveryResult, { delivered: 'skipped' }>) {\n  return new Error(`The session is not available (${result.reason}).`);\n}\n\nexport function createFactoryMessagingTools(\n  scope: FactoryToolScope,\n  deps: FactoryMessagingToolDependencies,\n): IntegrationTools {\n  const requireMessaging = async () => {\n    const messaging = await deps.messaging();\n    if (!messaging) throw new Error('Session messaging is not available on this server.');\n    return messaging;\n  };\n  // Only a user-session turn the person started is the person's act. Workers\n  // (even when someone types into one) and turns nobody signed in started\n  // (wakes, webhooks) act as the thread's agent.\n  const human = scope.kind === 'user' && scope.interactive;\n  const audit = (input: { targetSessionId: string; priority: NotificationPriority; kind: string; delivery: string }) =>\n    deps.auditRecorder.record({\n      orgId: scope.orgId,\n      actorId: human ? scope.userId : `agent:${scope.threadId}`,\n      actorType: human ? 'human' : 'agent',\n      action: 'factory.agent.signaled',\n      factoryProjectId: scope.factoryProjectId,\n      targets: [{ type: 'session', id: input.targetSessionId }],\n      metadata: {\n        targetSessionId: input.targetSessionId,\n        priority: input.priority,\n        kind: input.kind,\n        delivery: input.delivery,\n      },\n    });\n  /** Why this session can't reach `row`, or null when it can: the rule for message targets and reply targets alike. */\n  const unreachable = (row: SourceControlSession | null): 'not-found' | 'private' | null => {\n    if (!row || row.orgId !== scope.orgId || row.factoryProjectId !== scope.factoryProjectId) return 'not-found';\n    if (row.visibility === 'private' && row.userId !== scope.userId) return 'private';\n    return null;\n  };\n  /** Messages, replies and reports (not progress) this session put on a thread inside the rate window. */\n  const overRateLimit = (records: NotificationRecord[]) => {\n    const since = Date.now() - SIGNAL_RATE_WINDOW_MS;\n    return (\n      records.filter(\n        record =>\n          // Everything this session sends counts except coalescing progress updates.\n          record.kind !== 'progress' &&\n          record.kind !== 'stage' &&\n          record.attributes?.['from-session'] === scope.sessionId &&\n          record.createdAt.getTime() >= since,\n      ).length >= SIGNAL_RATE_LIMIT\n    );\n  };\n  const recent = (notifications: FactoryMessaging['notifications'], threadId: string) =>\n    notifications.listNotifications({ threadId, source: FACTORY_SESSION_NOTIFICATION_SOURCE, limit: RECENT_SCAN });\n\n  /** On turns nobody signed in started, only sessions working on items this session follows. */\n  const followedWorkers = async () => {\n    const project = { orgId: scope.orgId, factoryProjectId: scope.factoryProjectId };\n    const follows = await deps.workItems.listSessionSubscriptions({ ...project, sessionId: scope.sessionId });\n    const bindings = await Promise.all(\n      follows.map(follow => deps.workItems.listRunBindings(scope.orgId, scope.factoryProjectId, follow.workItemId)),\n    );\n    const sideSessions = await deps.sessions.listByOrigin({ orgId: scope.orgId, originSessionId: scope.sessionId });\n    return new Set([\n      ...bindings\n        .flat()\n        .filter(binding => binding.status === 'active')\n        .map(binding => binding.sessionId),\n      ...sideSessions.map(session => session.sessionId),\n    ]);\n  };\n\n  const workItemAttribute = async (sessionId: string, orgId: string, factoryProjectId: string) => {\n    const binding = await deps.workItems.findActiveRunBindingForSession({ orgId, factoryProjectId, sessionId });\n    if (!binding) return {};\n    const item = await deps.workItems.getForProject(orgId, factoryProjectId, binding.workItemId);\n    if (!item) return {};\n    const number = workItemNumber(item);\n    return { 'work-item': number === null ? item.id : `#${number}` };\n  };\n\n  const signal = createTool({\n    id: 'factory_signal_session',\n    description: [\n      'Send a message to another session in this Factory: a work item role session, or a teammate session you can see.',\n      'Replies come back to this session as `factory-session` notifications with kind `reply` and an `in-reply-to` attribute naming your message.',\n      'Priority `medium` (default) wakes an idle session and waits for a busy one to finish its step; use `urgent` only to make it stop and change course.',\n      ...(scope.interactive\n        ? []\n        : ['On this turn you can only message your side sessions and sessions working on items this session follows.']),\n    ].join(' '),\n    inputSchema: z\n      .object({\n        sessionId: z.string().trim().min(1).max(200).describe('The session to message.'),\n        message: message.describe('What to say. It arrives as-is, so make it self-contained.'),\n        priority: z.enum(['low', 'medium', 'high', 'urgent']).default('medium'),\n      })\n      .strict(),\n    execute: async ({ sessionId, message: text, priority }) => {\n      if (sessionId === scope.sessionId) throw new Error(\"You can't message your own session.\");\n      const row = await deps.sessions.getBySessionId(sessionId);\n      const blocked = unreachable(row);\n      if (blocked === 'not-found' || !row) throw new Error(`No session ${sessionId} was found in this Factory.`);\n      if (blocked === 'private') throw new Error(`Session ${sessionId} is private to its owner.`);\n      if (!scope.interactive && !(await followedWorkers()).has(sessionId)) {\n        throw new Error(\n          `On this turn you can only message this session's side sessions and sessions working on items it follows; ${sessionId} isn't one.`,\n        );\n      }\n\n      const messaging = await requireMessaging();\n      const threadId = await resolveSessionThread({\n        controller: messaging.controller,\n        sessions: deps.sessions,\n        workItems: deps.workItems,\n        sessionId,\n      });\n      if (!threadId) throw new Error('The session is not available (thread-not-found).');\n\n      if (overRateLimit(await recent(messaging.notifications, threadId))) {\n        throw new Error(RATE_LIMITED);\n      }\n\n      const result = await deliverFactorySessionNotification({\n        controller: messaging.controller,\n        sessions: deps.sessions,\n        target: { sessionId, threadId },\n        notification: {\n          kind: 'message',\n          priority,\n          summary: text,\n          payload: { message: text },\n          sourceId: scope.sessionId,\n          attributes: {\n            ...(await workItemAttribute(sessionId, row.orgId, scope.factoryProjectId)),\n            ...senderAttributes(scope),\n          },\n        },\n      });\n      if (result.delivered === 'skipped') throw unavailable(result);\n      await audit({ targetSessionId: sessionId, priority, kind: 'message', delivery: result.delivered });\n      return { notificationId: result.notificationId, delivered: result.delivered };\n    },\n  });\n\n  const reply = createTool({\n    id: 'factory_message_origin',\n    description: [\n      'Answer a message another Factory session sent you, or report on your work.',\n      'With `inReplyTo` (the id of a `factory-session` notification of kind `message`) the answer goes back to the session and thread that sent it; each message can be answered once.',\n      'Without it, the report goes to whoever follows your work: the session that started you, or everyone following your work item.',\n      \"Set `status`: `progress` for an update, `blocked` when you need an answer to go on, `done` when finished, `failed` when you can't finish. Send one `done` or `failed` when you finish.\",\n    ].join(' '),\n    inputSchema: z\n      .object({\n        message: message.describe('Your answer.'),\n        inReplyTo: z\n          .string()\n          .trim()\n          .min(1)\n          .max(200)\n          .optional()\n          .describe('Id of the message notification you are answering.'),\n        status: z.enum(['progress', 'blocked', 'done', 'failed']).optional(),\n      })\n      .strict(),\n    execute: async ({ message: text, inReplyTo, status }) => {\n      if (!inReplyTo) return report(text, status);\n      const messaging = await requireMessaging();\n      // Only a message that reached this session's own thread can be answered,\n      // and the answer goes where that message came from: never to an address\n      // the model supplies.\n      const original: NotificationRecord | null = await messaging.notifications.getNotification({\n        threadId: scope.threadId,\n        id: inReplyTo,\n      });\n      if (!original || original.source !== FACTORY_SESSION_NOTIFICATION_SOURCE) {\n        throw new Error(`No message ${inReplyTo} was sent to this session.`);\n      }\n      if (original.kind !== 'message') {\n        throw new Error(`Only messages can be answered; ${inReplyTo} is a ${original.kind}.`);\n      }\n      const fromSession = original.attributes?.['from-session'];\n      const fromThread = original.attributes?.['from-thread'];\n      if (typeof fromSession !== 'string' || typeof fromThread !== 'string' || original.sourceId !== fromSession) {\n        throw new Error(`Message ${inReplyTo} doesn't say which session sent it.`);\n      }\n      // Notification records can be written outside these tools, so the\n      // sender they name gets the same checks a message to it would.\n      const blocked = unreachable(await deps.sessions.getBySessionId(fromSession));\n      if (blocked === 'not-found') throw new Error(`Message ${inReplyTo} didn't come from a session in this Factory.`);\n      if (blocked === 'private') {\n        throw new Error(`Message ${inReplyTo} came from a private session this session can't answer.`);\n      }\n      const onSenderThread = await recent(messaging.notifications, fromThread);\n      // Replies count toward the same cap as messages, so records written to\n      // this session can't turn it into an unlimited high-priority sender.\n      const answered = onSenderThread.some(\n        record =>\n          record.kind === 'reply' &&\n          record.attributes?.['in-reply-to'] === inReplyTo &&\n          record.attributes?.['from-session'] === scope.sessionId,\n      );\n      if (answered) throw new Error(`You already answered ${inReplyTo}.`);\n      if (overRateLimit(onSenderThread)) throw new Error(RATE_LIMITED);\n\n      const result = await deliverFactorySessionNotification({\n        controller: messaging.controller,\n        sessions: deps.sessions,\n        target: { sessionId: fromSession, threadId: fromThread },\n        notification: {\n          kind: 'reply',\n          priority: 'high',\n          summary: text,\n          payload: { message: text },\n          sourceId: scope.sessionId,\n          attributes: {\n            ...senderAttributes(scope),\n            'in-reply-to': inReplyTo,\n            ...(status ? { status } : {}),\n          },\n        },\n      });\n      if (result.delivered === 'skipped') throw unavailable(result);\n      await audit({ targetSessionId: fromSession, priority: 'high', kind: 'reply', delivery: result.delivered });\n      return { notificationId: result.notificationId, delivered: result.delivered };\n    },\n  });\n\n  /** A report with no message to answer: to the origin, else to the item's followers. */\n  async function report(text: string, status: 'progress' | 'blocked' | 'done' | 'failed' | undefined) {\n    const sender = { sessionId: scope.sessionId, threadId: scope.threadId, userId: scope.userId };\n    let recipients: Array<{ sessionId: string; threadId: string }>;\n    let attributes: Record<string, string> = {};\n    if (scope.origin) {\n      recipients = [scope.origin];\n    } else {\n      const binding = await deps.workItems.findActiveRunBindingForSession({\n        orgId: scope.orgId,\n        factoryProjectId: scope.factoryProjectId,\n        sessionId: scope.sessionId,\n      });\n      if (!binding) throw new Error('Nothing started this session; pass inReplyTo to answer a message.');\n      recipients = await workItemReportRecipients(deps.workItems, {\n        orgId: scope.orgId,\n        workItemId: binding.workItemId,\n        senderSessionId: scope.sessionId,\n      });\n      ({ attributes } = await workItemReportAttributes(deps.workItems, {\n        orgId: scope.orgId,\n        factoryProjectId: scope.factoryProjectId,\n        workItemId: binding.workItemId,\n        role: binding.role,\n      }));\n    }\n    if (recipients.length === 0) return { delivered: 0, recipients: [] };\n\n    const messaging = await requireMessaging();\n    const notification = reportNotification({ sender, status, message: text, attributes });\n    const results: Array<{ sessionId: string; delivered: FactoryDeliveryResult['delivered']; reason?: string }> = [];\n    for (const recipient of recipients) {\n      // Progress replaces itself while unread; anything else can wake a follower, so it counts.\n      if (status !== 'progress' && overRateLimit(await recent(messaging.notifications, recipient.threadId))) {\n        results.push({ sessionId: recipient.sessionId, delivered: 'skipped', reason: 'rate-limited' });\n        continue;\n      }\n      const result = await deliverFactorySessionNotification({\n        controller: messaging.controller,\n        sessions: deps.sessions,\n        target: recipient,\n        notification,\n      });\n      results.push({ sessionId: recipient.sessionId, delivered: result.delivered });\n      if (result.delivered === 'skipped') continue;\n      await audit({\n        targetSessionId: recipient.sessionId,\n        priority: notification.priority ?? 'high',\n        kind: notification.kind,\n        delivery: result.delivered,\n      });\n    }\n    const delivered = results.filter(result => result.delivered !== 'skipped').length;\n    if (delivered === 0 && results.every(result => result.reason === 'rate-limited')) throw new Error(RATE_LIMITED);\n    return { delivered, recipients: results };\n  }\n\n  if (scope.kind === 'worker') return { factory_message_origin: reply };\n  return { factory_signal_session: signal, factory_message_origin: reply };\n}\n"],"mappings":"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"}

package/dist/tools/permissions.d.ts

@@ -0,0 +1,31 @@
+import type { PermissionPolicy, PermissionRules } from '@mastra/core/agent-controller';
+import type { SourceControlSessionLookup } from '../session/factory-session.js';
+/**
+ * Factory tools that run without asking. Factory tools fall into the SDK's
+ * `mcp` category, whose default policy is `ask`, so each of these needs an
+ * explicit per-session `allow`.
+ */
+export declare const FACTORY_TOOLS_WITHOUT_APPROVAL: readonly string[];
+export interface FactoryToolPermissionsSession {
+    readonly identity: {
+        getResourceId(): string;
+    };
+    readonly permissions: {
+        getRules(): PermissionRules;
+        setForTool(args: {
+            toolName: string;
+            policy: PermissionPolicy;
+        }): Promise<void>;
+    };
+}
+export interface FactoryToolPermissionsDependencies {
+    sessions: Pick<SourceControlSessionLookup, 'getBySessionId'>;
+}
+/**
+ * Allow the no-approval Factory tools on a newly created Factory session.
+ * This only sets policy; which tools a turn actually gets is decided by the
+ * tool scope. A person's own choices win: a per-tool policy is never
+ * overwritten, and an explicit `mcp` category policy leaves everything alone.
+ */
+export declare function applyFactoryToolPermissions(session: FactoryToolPermissionsSession, { sessions }: FactoryToolPermissionsDependencies, toolNames?: readonly string[]): Promise<void>;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/tools/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/tools/permissions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAEvF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAgB3D,CAAC;AAEF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE;QAAE,aAAa,IAAI,MAAM,CAAA;KAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,IAAI,eAAe,CAAC;QAC5B,UAAU,CAAC,IAAI,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,gBAAgB,CAAA;SAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACjF,CAAC;CACH;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,EAAE,IAAI,CAAC,0BAA0B,EAAE,gBAAgB,CAAC,CAAC;CAC9D;AAED;;;;;GAKG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,6BAA6B,EACtC,EAAE,QAAQ,EAAE,EAAE,kCAAkC,EAChD,SAAS,GAAE,SAAS,MAAM,EAAmC,GAC5D,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/tools/permissions.js

@@ -0,0 +1,44 @@
+//#region src/tools/permissions.ts
+/**
+* Factory tools that run without asking. Factory tools fall into the SDK's
+* `mcp` category, whose default policy is `ask`, so each of these needs an
+* explicit per-session `allow`.
+*/
+const FACTORY_TOOLS_WITHOUT_APPROVAL = [
+	"factory_list_work_items",
+	"factory_inspect_work_item",
+	"factory_list_attention",
+	"factory_create_work_item",
+	"factory_update_work_item",
+	"factory_transition_work_item",
+	"factory_retry_decision",
+	"factory_dismiss_decision",
+	"factory_resolve_proposal",
+	"factory_subscribe_work_item",
+	"factory_unsubscribe_work_item",
+	"factory_signal_session",
+	"factory_message_origin",
+	"factory_start_session",
+	"factory_answer_approval"
+];
+/**
+* Allow the no-approval Factory tools on a newly created Factory session.
+* This only sets policy; which tools a turn actually gets is decided by the
+* tool scope. A person's own choices win: a per-tool policy is never
+* overwritten, and an explicit `mcp` category policy leaves everything alone.
+*/
+async function applyFactoryToolPermissions(session, { sessions }, toolNames = FACTORY_TOOLS_WITHOUT_APPROVAL) {
+	if (!(await sessions.getBySessionId(session.identity.getResourceId()))?.factoryProjectId) return;
+	if (session.permissions.getRules().categories.mcp !== void 0) return;
+	for (const toolName of toolNames) {
+		if (session.permissions.getRules().tools[toolName] !== void 0) continue;
+		await session.permissions.setForTool({
+			toolName,
+			policy: "allow"
+		});
+	}
+}
+//#endregion
+export { FACTORY_TOOLS_WITHOUT_APPROVAL, applyFactoryToolPermissions };
+
+//# sourceMappingURL=permissions.js.map

package/dist/tools/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","names":[],"sources":["../../src/tools/permissions.ts"],"sourcesContent":["import type { PermissionPolicy, PermissionRules } from '@mastra/core/agent-controller';\n\nimport type { SourceControlSessionLookup } from '../session/factory-session.js';\n\n/**\n * Factory tools that run without asking. Factory tools fall into the SDK's\n * `mcp` category, whose default policy is `ask`, so each of these needs an\n * explicit per-session `allow`.\n */\nexport const FACTORY_TOOLS_WITHOUT_APPROVAL: readonly string[] = [\n  'factory_list_work_items',\n  'factory_inspect_work_item',\n  'factory_list_attention',\n  'factory_create_work_item',\n  'factory_update_work_item',\n  'factory_transition_work_item',\n  'factory_retry_decision',\n  'factory_dismiss_decision',\n  'factory_resolve_proposal',\n  'factory_subscribe_work_item',\n  'factory_unsubscribe_work_item',\n  'factory_signal_session',\n  'factory_message_origin',\n  'factory_start_session',\n  'factory_answer_approval',\n];\n\nexport interface FactoryToolPermissionsSession {\n  readonly identity: { getResourceId(): string };\n  readonly permissions: {\n    getRules(): PermissionRules;\n    setForTool(args: { toolName: string; policy: PermissionPolicy }): Promise<void>;\n  };\n}\n\nexport interface FactoryToolPermissionsDependencies {\n  sessions: Pick<SourceControlSessionLookup, 'getBySessionId'>;\n}\n\n/**\n * Allow the no-approval Factory tools on a newly created Factory session.\n * This only sets policy; which tools a turn actually gets is decided by the\n * tool scope. A person's own choices win: a per-tool policy is never\n * overwritten, and an explicit `mcp` category policy leaves everything alone.\n */\nexport async function applyFactoryToolPermissions(\n  session: FactoryToolPermissionsSession,\n  { sessions }: FactoryToolPermissionsDependencies,\n  toolNames: readonly string[] = FACTORY_TOOLS_WITHOUT_APPROVAL,\n): Promise<void> {\n  const row = await sessions.getBySessionId(session.identity.getResourceId());\n  if (!row?.factoryProjectId) return;\n  const rules = session.permissions.getRules();\n  if (rules.categories.mcp !== undefined) return;\n  for (const toolName of toolNames) {\n    if (session.permissions.getRules().tools[toolName] !== undefined) continue;\n    await session.permissions.setForTool({ toolName, policy: 'allow' });\n  }\n}\n"],"mappings":";;;;;;AASA,MAAa,iCAAoD;CAC/D;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;;AAoBA,eAAsB,4BACpB,SACA,EAAE,YACF,YAA+B,gCAChB;CAEf,IAAI,EAAC,MADa,SAAS,eAAe,QAAQ,SAAS,cAAc,CAAC,EAAA,EAChE,kBAAkB;CAE5B,IADc,QAAQ,YAAY,SAC1B,CAAC,CAAC,WAAW,QAAQ,KAAA,GAAW;CACxC,KAAK,MAAM,YAAY,WAAW;EAChC,IAAI,QAAQ,YAAY,SAAS,CAAC,CAAC,MAAM,cAAc,KAAA,GAAW;EAClE,MAAM,QAAQ,YAAY,WAAW;GAAE;GAAU,QAAQ;EAAQ,CAAC;CACpE;AACF"}

package/dist/tools/read-tools.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import type { BoardRegistry } from '../boards/index.js';
+import type { IntegrationTools } from '../integrations/base.js';
+import type { AuditStorage } from '../storage/domains/audit/base.js';
+import type { WorkItemCommentsStorage } from '../storage/domains/comments/base.js';
+import type { WorkItemRow, WorkItemsStorage } from '../storage/domains/work-items/base.js';
+import type { FactoryToolScope } from './scope.js';
+export declare const MAX_TEXT = 600;
+export declare const MAX_ERROR = 400;
+export declare const MAX_LIST = 50;
+export interface FactoryReadToolDependencies {
+    workItems: Pick<WorkItemsStorage, 'list' | 'getForProject' | 'listRunBindings' | 'listDeferredDecisions' | 'listByIds' | 'listDecisionsForEvaluations' | 'listWorkItemSubscribers' | 'listSessionSubscriptions'>;
+    comments: Pick<WorkItemCommentsStorage, 'listRecent'>;
+    audit: Pick<AuditStorage, 'list'>;
+    boards: BoardRegistry;
+}
+export declare function truncate(text: string, max: number): string;
+/** The number a person sees on the card: the issue or PR number the item was filed from. */
+export declare function workItemNumber(item: Pick<WorkItemRow, 'metadata'>): number | null;
+export declare function workItemStage(item: Pick<WorkItemRow, 'stages'>): string;
+/** A work item id or its card number; anything else can't name an item. */
+export declare const workItemRefSchema: z.ZodString;
+/** Resolve `<uuid>` or `#123` to an item in this Factory only. Pass a ref validated by `workItemRefSchema`. */
+export declare function findWorkItem(workItems: Pick<WorkItemsStorage, 'list' | 'getForProject'>, scope: Pick<FactoryToolScope, 'orgId' | 'factoryProjectId'>, ref: string): Promise<WorkItemRow | null>;
+export declare function workItemNotFound(ref: string): Error;
+export declare function createFactoryReadTools(scope: FactoryToolScope, deps: FactoryReadToolDependencies): IntegrationTools;
+//# sourceMappingURL=read-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"read-tools.d.ts","sourceRoot":"","sources":["../../src/tools/read-tools.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,KAAK,EAGV,WAAW,EACX,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,eAAO,MAAM,QAAQ,MAAM,CAAC;AAC5B,eAAO,MAAM,SAAS,MAAM,CAAC;AAC7B,eAAO,MAAM,QAAQ,KAAK,CAAC;AAG3B,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,IAAI,CACb,gBAAgB,EACd,MAAM,GACN,eAAe,GACf,iBAAiB,GACjB,uBAAuB,GACvB,WAAW,GACX,6BAA6B,GAC7B,yBAAyB,GACzB,0BAA0B,CAC7B,CAAC;IACF,QAAQ,EAAE,IAAI,CAAC,uBAAuB,EAAE,YAAY,CAAC,CAAC;IACtD,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAClC,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1D;AAQD,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,GAAG,MAAM,GAAG,IAAI,CAGjF;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,GAAG,MAAM,CAEvE;AAED,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,aAOyB,CAAC;AAExD,+GAA+G;AAC/G,wBAAsB,YAAY,CAChC,SAAS,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,eAAe,CAAC,EAC3D,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,kBAAkB,CAAC,EAC3D,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAQ7B;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAEnD;AAkED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,2BAA2B,GAAG,gBAAgB,CA8MnH"}