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

package/dist/tools/scope.d.ts

@@ -0,0 +1,54 @@
+import type { RequestContext } from '@mastra/core/request-context';
+import { FACTORY_INTERACTIVE_KEY } from '../auth.js';
+import type { SourceControlSessionLookup } from '../session/factory-session.js';
+import type { AuditActorProfileInput } from '../storage/domains/audit/base.js';
+import type { FactoryProjectsStorage } from '../storage/domains/projects/base.js';
+import type { WorkItemsStorage } from '../storage/domains/work-items/base.js';
+export { FACTORY_INTERACTIVE_KEY };
+/** Linked Slack sender, separate from the session owner's model-credential identity. */
+export declare const FACTORY_SLACK_SENDER_KEY = "mastra__factorySlackSender";
+/** Who is calling Factory tools, and from which session. Everything a tool needs to stay in scope. */
+export interface FactoryToolScope {
+    orgId: string;
+    factoryProjectId: string;
+    /** The signed-in caller for a user session; the session row's owner for a worker. */
+    userId: string;
+    /** The source-control session id. */
+    sessionId: string;
+    /** The memory resource the session runs under. */
+    resourceId: string;
+    threadId: string;
+    /** `worker` sessions are bound to a work item run; only `user` sessions manage the Factory. */
+    kind: 'user' | 'worker';
+    /** True only for turns a signed-in person started over HTTP (see {@link FACTORY_INTERACTIVE_KEY}). */
+    interactive: boolean;
+    /** The caller's name and avatar, stamped on audit events so the board can show who acted. */
+    actorProfile?: AuditActorProfileInput;
+    /** Set for a side session: the user session and thread that started it. */
+    origin?: {
+        sessionId: string;
+        threadId: string;
+    };
+}
+export interface ResolveFactoryToolScopeOptions {
+    requestContext: RequestContext;
+    /** `routeAuth.enabled()`; when false every caller is the shared `local` tenant. */
+    authEnabled: boolean;
+    sessions: Pick<SourceControlSessionLookup, 'getBySessionId'>;
+    projects: Pick<FactoryProjectsStorage, 'get'>;
+    workItems: Pick<WorkItemsStorage, 'hasRunBindingForSession'>;
+}
+/**
+ * Resolve the Factory a session's agent may act in. The scope comes from the
+ * stored source-control session row and the authenticated caller, never from
+ * the `factoryProjectId` thread tag alone: the browser sets that tag and
+ * nothing clears it.
+ */
+export declare function resolveFactoryToolScope({ requestContext, authEnabled, sessions, projects, workItems, }: ResolveFactoryToolScopeOptions): Promise<FactoryToolScope | null>;
+/**
+ * Refuses an action only a signed-in person may take. Turns nobody signed in
+ * started (notification wakes, webhooks, dispatcher notices) carry text other
+ * people wrote, so they can't approve, resolve proposals, or waive plan approval.
+ */
+export declare function requirePerson(scope: FactoryToolScope, action: string): void;
+//# sourceMappingURL=scope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/tools/scope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,OAAO,EACL,uBAAuB,EAIxB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAEhF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC/E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAE9E,OAAO,EAAE,uBAAuB,EAAE,CAAC;AAEnC,wFAAwF;AACxF,eAAO,MAAM,wBAAwB,+BAA+B,CAAC;AAErE,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,sGAAsG;IACtG,WAAW,EAAE,OAAO,CAAC;IACrB,6FAA6F;IAC7F,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC,2EAA2E;IAC3E,MAAM,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAED,MAAM,WAAW,8BAA8B;IAC7C,cAAc,EAAE,cAAc,CAAC;IAC/B,mFAAmF;IACnF,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,IAAI,CAAC,0BAA0B,EAAE,gBAAgB,CAAC,CAAC;IAC7D,QAAQ,EAAE,IAAI,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAC;IAC9C,SAAS,EAAE,IAAI,CAAC,gBAAgB,EAAE,yBAAyB,CAAC,CAAC;CAC9D;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,EAC5C,cAAc,EACd,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,SAAS,GACV,EAAE,8BAA8B,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAkEnE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAK3E"}

package/dist/tools/scope.js

@@ -0,0 +1,87 @@
+import { FACTORY_INTERACTIVE_KEY, factoryUserOrgId, getFactoryAuthUserFromContext, getFactoryAuthUserId } from "../auth.js";
+import { auditActorProfile } from "../storage/domains/audit/base.js";
+//#region src/tools/scope.ts
+/** Linked Slack sender, separate from the session owner's model-credential identity. */
+const FACTORY_SLACK_SENDER_KEY = "mastra__factorySlackSender";
+/**
+* Resolve the Factory a session's agent may act in. The scope comes from the
+* stored source-control session row and the authenticated caller, never from
+* the `factoryProjectId` thread tag alone: the browser sets that tag and
+* nothing clears it.
+*/
+async function resolveFactoryToolScope({ requestContext, authEnabled, sessions, projects, workItems }) {
+	if (typeof requestContext?.get !== "function") return null;
+	const controller = requestContext.get("controller");
+	const sessionId = controller?.sessionId;
+	const resourceId = controller?.resourceId;
+	const threadId = controller?.threadId;
+	if (!sessionId || !resourceId || !threadId) return null;
+	let caller = null;
+	if (authEnabled) {
+		const slackSender = requestContext.get(FACTORY_SLACK_SENDER_KEY);
+		const user = getFactoryAuthUserFromContext(requestContext);
+		if (slackSender && factoryUserOrgId(user) !== slackSender.orgId) return null;
+		const userId = slackSender?.userId ?? getFactoryAuthUserId(user);
+		const orgId = slackSender?.orgId ?? factoryUserOrgId(user);
+		const actorProfile = slackSender ? void 0 : auditActorProfile(user);
+		if (userId && orgId) caller = {
+			orgId,
+			userId,
+			...actorProfile ? { actorProfile } : {}
+		};
+	} else caller = {
+		orgId: "local",
+		userId: "local"
+	};
+	const row = await sessions.getBySessionId(sessionId);
+	if (!row?.factoryProjectId) return null;
+	if (caller && row.orgId !== caller.orgId) return null;
+	const origin = row.originSessionId && row.originThreadId ? {
+		sessionId: row.originSessionId,
+		threadId: row.originThreadId
+	} : void 0;
+	const worker = origin !== void 0 || await workItems.hasRunBindingForSession({
+		orgId: row.orgId,
+		factoryProjectId: row.factoryProjectId,
+		sessionId: row.sessionId
+	});
+	let identity;
+	if (worker) identity = {
+		orgId: row.orgId,
+		userId: row.userId
+	};
+	else {
+		if (!caller) return null;
+		if (row.visibility === "private" && row.userId !== caller.userId) return null;
+		identity = caller;
+	}
+	if (!await projects.get({
+		orgId: identity.orgId,
+		id: row.factoryProjectId
+	})) return null;
+	return {
+		orgId: identity.orgId,
+		factoryProjectId: row.factoryProjectId,
+		userId: identity.userId,
+		sessionId: row.sessionId,
+		resourceId,
+		threadId,
+		kind: worker ? "worker" : "user",
+		interactive: requestContext.get(FACTORY_INTERACTIVE_KEY) === true,
+		...identity.actorProfile ? { actorProfile: identity.actorProfile } : {},
+		...origin ? { origin } : {}
+	};
+}
+/**
+* Refuses an action only a signed-in person may take. Turns nobody signed in
+* started (notification wakes, webhooks, dispatcher notices) carry text other
+* people wrote, so they can't approve, resolve proposals, or waive plan approval.
+*/
+function requirePerson(scope, action) {
+	if (scope.interactive) return;
+	throw new Error(`Only a person can ${action}. Nobody signed in started this turn (it came from a notification, webhook or rule); ask the person to do it from the board or by messaging this session.`);
+}
+//#endregion
+export { FACTORY_INTERACTIVE_KEY, FACTORY_SLACK_SENDER_KEY, requirePerson, resolveFactoryToolScope };
+
+//# sourceMappingURL=scope.js.map

package/dist/tools/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","names":[],"sources":["../../src/tools/scope.ts"],"sourcesContent":["import type { AgentControllerRequestContext } from '@mastra/core/agent-controller';\nimport type { RequestContext } from '@mastra/core/request-context';\n\nimport {\n  FACTORY_INTERACTIVE_KEY,\n  factoryUserOrgId,\n  getFactoryAuthUserFromContext,\n  getFactoryAuthUserId,\n} from '../auth.js';\nimport type { SourceControlSessionLookup } from '../session/factory-session.js';\nimport { auditActorProfile } from '../storage/domains/audit/base.js';\nimport type { AuditActorProfileInput } from '../storage/domains/audit/base.js';\nimport type { FactoryProjectsStorage } from '../storage/domains/projects/base.js';\nimport type { WorkItemsStorage } from '../storage/domains/work-items/base.js';\n\nexport { FACTORY_INTERACTIVE_KEY };\n\n/** Linked Slack sender, separate from the session owner's model-credential identity. */\nexport const FACTORY_SLACK_SENDER_KEY = 'mastra__factorySlackSender';\n\n/** Who is calling Factory tools, and from which session. Everything a tool needs to stay in scope. */\nexport interface FactoryToolScope {\n  orgId: string;\n  factoryProjectId: string;\n  /** The signed-in caller for a user session; the session row's owner for a worker. */\n  userId: string;\n  /** The source-control session id. */\n  sessionId: string;\n  /** The memory resource the session runs under. */\n  resourceId: string;\n  threadId: string;\n  /** `worker` sessions are bound to a work item run; only `user` sessions manage the Factory. */\n  kind: 'user' | 'worker';\n  /** True only for turns a signed-in person started over HTTP (see {@link FACTORY_INTERACTIVE_KEY}). */\n  interactive: boolean;\n  /** The caller's name and avatar, stamped on audit events so the board can show who acted. */\n  actorProfile?: AuditActorProfileInput;\n  /** Set for a side session: the user session and thread that started it. */\n  origin?: { sessionId: string; threadId: string };\n}\n\nexport interface ResolveFactoryToolScopeOptions {\n  requestContext: RequestContext;\n  /** `routeAuth.enabled()`; when false every caller is the shared `local` tenant. */\n  authEnabled: boolean;\n  sessions: Pick<SourceControlSessionLookup, 'getBySessionId'>;\n  projects: Pick<FactoryProjectsStorage, 'get'>;\n  workItems: Pick<WorkItemsStorage, 'hasRunBindingForSession'>;\n}\n\n/**\n * Resolve the Factory a session's agent may act in. The scope comes from the\n * stored source-control session row and the authenticated caller, never from\n * the `factoryProjectId` thread tag alone: the browser sets that tag and\n * nothing clears it.\n */\nexport async function resolveFactoryToolScope({\n  requestContext,\n  authEnabled,\n  sessions,\n  projects,\n  workItems,\n}: ResolveFactoryToolScopeOptions): Promise<FactoryToolScope | null> {\n  if (typeof requestContext?.get !== 'function') return null;\n  const controller = requestContext.get('controller') as AgentControllerRequestContext<unknown> | undefined;\n  const sessionId = controller?.sessionId;\n  const resourceId = controller?.resourceId;\n  const threadId = controller?.threadId;\n  if (!sessionId || !resourceId || !threadId) return null;\n\n  let caller: { orgId: string; userId: string; actorProfile?: AuditActorProfileInput } | null = null;\n  if (authEnabled) {\n    const slackSender = requestContext.get(FACTORY_SLACK_SENDER_KEY) as { userId: string; orgId: string } | undefined;\n    const user = getFactoryAuthUserFromContext(requestContext);\n    if (slackSender && factoryUserOrgId(user) !== slackSender.orgId) return null;\n    const userId = slackSender?.userId ?? getFactoryAuthUserId(user);\n    const orgId = slackSender?.orgId ?? factoryUserOrgId(user);\n    const actorProfile = slackSender ? undefined : auditActorProfile(user);\n    if (userId && orgId) caller = { orgId, userId, ...(actorProfile ? { actorProfile } : {}) };\n  } else {\n    caller = { orgId: 'local', userId: 'local' };\n  }\n\n  const row = await sessions.getBySessionId(sessionId);\n  if (!row?.factoryProjectId) return null;\n  // A caller from another org never acts here, worker or not.\n  if (caller && row.orgId !== caller.orgId) return null;\n\n  // A side session works for the session that started it. Otherwise any\n  // binding, active or revoked, on any thread: a session that ever ran a role stays a worker.\n  const origin =\n    row.originSessionId && row.originThreadId\n      ? { sessionId: row.originSessionId, threadId: row.originThreadId }\n      : undefined;\n  const worker =\n    origin !== undefined ||\n    (await workItems.hasRunBindingForSession({\n      orgId: row.orgId,\n      factoryProjectId: row.factoryProjectId,\n      sessionId: row.sessionId,\n    }));\n\n  // A worker acts as its session row: dispatcher-driven runs carry no signed-in user.\n  // A user session acts as the signed-in caller, who must be able to see it.\n  let identity: { orgId: string; userId: string; actorProfile?: AuditActorProfileInput };\n  if (worker) {\n    identity = { orgId: row.orgId, userId: row.userId };\n  } else {\n    if (!caller) return null;\n    if (row.visibility === 'private' && row.userId !== caller.userId) return null;\n    identity = caller;\n  }\n\n  const project = await projects.get({ orgId: identity.orgId, id: row.factoryProjectId });\n  if (!project) return null;\n\n  return {\n    orgId: identity.orgId,\n    factoryProjectId: row.factoryProjectId,\n    userId: identity.userId,\n    sessionId: row.sessionId,\n    resourceId,\n    threadId,\n    kind: worker ? 'worker' : 'user',\n    interactive: requestContext.get(FACTORY_INTERACTIVE_KEY) === true,\n    ...(identity.actorProfile ? { actorProfile: identity.actorProfile } : {}),\n    ...(origin ? { origin } : {}),\n  };\n}\n\n/**\n * Refuses an action only a signed-in person may take. Turns nobody signed in\n * started (notification wakes, webhooks, dispatcher notices) carry text other\n * people wrote, so they can't approve, resolve proposals, or waive plan approval.\n */\nexport function requirePerson(scope: FactoryToolScope, action: string): void {\n  if (scope.interactive) return;\n  throw new Error(\n    `Only a person can ${action}. Nobody signed in started this turn (it came from a notification, webhook or rule); ask the person to do it from the board or by messaging this session.`,\n  );\n}\n"],"mappings":";;;;AAkBA,MAAa,2BAA2B;;;;;;;AAsCxC,eAAsB,wBAAwB,EAC5C,gBACA,aACA,UACA,UACA,aACmE;CACnE,IAAI,OAAO,gBAAgB,QAAQ,YAAY,OAAO;CACtD,MAAM,aAAa,eAAe,IAAI,YAAY;CAClD,MAAM,YAAY,YAAY;CAC9B,MAAM,aAAa,YAAY;CAC/B,MAAM,WAAW,YAAY;CAC7B,IAAI,CAAC,aAAa,CAAC,cAAc,CAAC,UAAU,OAAO;CAEnD,IAAI,SAA0F;CAC9F,IAAI,aAAa;EACf,MAAM,cAAc,eAAe,IAAI,wBAAwB;EAC/D,MAAM,OAAO,8BAA8B,cAAc;EACzD,IAAI,eAAe,iBAAiB,IAAI,MAAM,YAAY,OAAO,OAAO;EACxE,MAAM,SAAS,aAAa,UAAU,qBAAqB,IAAI;EAC/D,MAAM,QAAQ,aAAa,SAAS,iBAAiB,IAAI;EACzD,MAAM,eAAe,cAAc,KAAA,IAAY,kBAAkB,IAAI;EACrE,IAAI,UAAU,OAAO,SAAS;GAAE;GAAO;GAAQ,GAAI,eAAe,EAAE,aAAa,IAAI,CAAC;EAAG;CAC3F,OACE,SAAS;EAAE,OAAO;EAAS,QAAQ;CAAQ;CAG7C,MAAM,MAAM,MAAM,SAAS,eAAe,SAAS;CACnD,IAAI,CAAC,KAAK,kBAAkB,OAAO;CAEnC,IAAI,UAAU,IAAI,UAAU,OAAO,OAAO,OAAO;CAIjD,MAAM,SACJ,IAAI,mBAAmB,IAAI,iBACvB;EAAE,WAAW,IAAI;EAAiB,UAAU,IAAI;CAAe,IAC/D,KAAA;CACN,MAAM,SACJ,WAAW,KAAA,KACV,MAAM,UAAU,wBAAwB;EACvC,OAAO,IAAI;EACX,kBAAkB,IAAI;EACtB,WAAW,IAAI;CACjB,CAAC;CAIH,IAAI;CACJ,IAAI,QACF,WAAW;EAAE,OAAO,IAAI;EAAO,QAAQ,IAAI;CAAO;MAC7C;EACL,IAAI,CAAC,QAAQ,OAAO;EACpB,IAAI,IAAI,eAAe,aAAa,IAAI,WAAW,OAAO,QAAQ,OAAO;EACzE,WAAW;CACb;CAGA,IAAI,CAAC,MADiB,SAAS,IAAI;EAAE,OAAO,SAAS;EAAO,IAAI,IAAI;CAAiB,CAAC,GACxE,OAAO;CAErB,OAAO;EACL,OAAO,SAAS;EAChB,kBAAkB,IAAI;EACtB,QAAQ,SAAS;EACjB,WAAW,IAAI;EACf;EACA;EACA,MAAM,SAAS,WAAW;EAC1B,aAAa,eAAe,IAAI,uBAAuB,MAAM;EAC7D,GAAI,SAAS,eAAe,EAAE,cAAc,SAAS,aAAa,IAAI,CAAC;EACvE,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;CAC7B;AACF;;;;;;AAOA,SAAgB,cAAc,OAAyB,QAAsB;CAC3E,IAAI,MAAM,aAAa;CACvB,MAAM,IAAI,MACR,qBAAqB,OAAO,0JAC9B;AACF"}

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

@@ -0,0 +1,43 @@
+import type { BoardRegistry } from '../boards/registry.js';
+import type { IntegrationTools } from '../integrations/base.js';
+import type { FactoryStartCoordinator } from '../rules/start-coordinator.js';
+import type { SourceControlSessionLookup } from '../session/factory-session.js';
+import type { AuditRecorder } from '../storage/domains/audit/domain.js';
+import type { ModelCredentialsStorage } from '../storage/domains/credentials/base.js';
+import type { CustomProvidersStorage } from '../storage/domains/custom-providers/base.js';
+import type { IntakeStorage } from '../storage/domains/intake/base.js';
+import type { ModelDefaultsStorage } from '../storage/domains/model-defaults/base.js';
+import type { FactoryProjectsStorage } from '../storage/domains/projects/base.js';
+import type { WorkItemsStorage } from '../storage/domains/work-items/base.js';
+import type { FactoryMessaging } from './messaging-tools.js';
+import type { FactoryToolScope } from './scope.js';
+/** Who renews the open-run entries this process writes; one id per process, like the dispatcher's. */
+export declare const FACTORY_TOOLS_OWNER_ID: string;
+export interface FactorySessionToolDependencies {
+    sessions: Pick<SourceControlSessionLookup, 'getBySessionId' | 'getSourceControlBySessionId'>;
+    sessionModel: {
+        projects: FactoryProjectsStorage;
+        modelDefaults: ModelDefaultsStorage;
+        /**
+         * Tenant credential stores, present when auth is on. Model switches then
+         * check the target session's credential scope, like the Settings picker;
+         * without them the server's own keys decide.
+         */
+        tenantCatalog?: {
+            credentials: Pick<ModelCredentialsStorage, 'listCredentials'>;
+            customProviders?: Pick<CustomProvidersStorage, 'ensureReady' | 'list'>;
+            deploymentProviders?: ReadonlySet<string>;
+        };
+    };
+    /** Resolved lazily: the controller only exists once the mount is up. */
+    messaging: () => Promise<FactoryMessaging | null>;
+    workItems: Pick<WorkItemsStorage, 'list' | 'getForProject' | 'listRunBindings' | 'findActiveRunBindingForSession' | 'findRunBindingByThread' | 'hasRunBindingForSession' | 'subscribeToWorkItem' | 'unsubscribeFromWorkItem' | 'listSessionSubscriptions' | 'listWorkItemSubscribers'>;
+    boards: BoardRegistry;
+    auditRecorder: AuditRecorder;
+    intake?: Pick<IntakeStorage, 'getConfig'>;
+    /** The browser Start's coordinator; absent until the Factory runtime is ready. */
+    startCoordinator: () => Pick<FactoryStartCoordinator, 'prepare'> | undefined;
+}
+/** Tools that start sessions on the caller's behalf, or switch their models. User sessions only. */
+export declare function createFactorySessionTools(scope: FactoryToolScope, deps: FactorySessionToolDependencies): IntegrationTools;
+//# sourceMappingURL=session-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-tools.d.ts","sourceRoot":"","sources":["../../src/tools/session-tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAKhE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAE7E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAQhF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACtF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AAC1F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEtF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAElF,OAAO,KAAK,EAAe,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAE3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,sGAAsG;AACtG,eAAO,MAAM,sBAAsB,QAAoD,CAAC;AAExF,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,IAAI,CAAC,0BAA0B,EAAE,gBAAgB,GAAG,6BAA6B,CAAC,CAAC;IAC7F,YAAY,EAAE;QACZ,QAAQ,EAAE,sBAAsB,CAAC;QACjC,aAAa,EAAE,oBAAoB,CAAC;QACpC;;;;WAIG;QACH,aAAa,CAAC,EAAE;YACd,WAAW,EAAE,IAAI,CAAC,uBAAuB,EAAE,iBAAiB,CAAC,CAAC;YAC9D,eAAe,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,aAAa,GAAG,MAAM,CAAC,CAAC;YACvE,mBAAmB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;SAC3C,CAAC;KACH,CAAC;IACF,wEAAwE;IACxE,SAAS,EAAE,MAAM,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAClD,SAAS,EAAE,IAAI,CACb,gBAAgB,EACd,MAAM,GACN,eAAe,GACf,iBAAiB,GACjB,gCAAgC,GAChC,wBAAwB,GACxB,yBAAyB,GACzB,qBAAqB,GACrB,yBAAyB,GACzB,0BAA0B,GAC1B,yBAAyB,CAC5B,CAAC;IACF,MAAM,EAAE,aAAa,CAAC;IACtB,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IAC1C,kFAAkF;IAClF,gBAAgB,EAAE,MAAM,IAAI,CAAC,uBAAuB,EAAE,SAAS,CAAC,GAAG,SAAS,CAAC;CAC9E;AA0BD,oGAAoG;AACpG,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,8BAA8B,GACnC,gBAAgB,CAsYlB"}

package/dist/tools/session-tools.js

@@ -0,0 +1,410 @@
+import { boardForWorkItem } from "../boards/semantics.js";
+import "../boards/index.js";
+import { primeTenantCredentialsForTenant } from "../routes/tenant-credentials.js";
+import { effectiveModelScope } from "../storage/domains/projects/base.js";
+import { ensureFactorySourceSession, hydrateFactorySession, resolveFactorySessionModel } from "../session/factory-session.js";
+import { resolveSessionThread } from "./deliver.js";
+import { findWorkItem, workItemNotFound, workItemNumber, workItemRefSchema } from "./read-tools.js";
+import { resolveFactoryModelPolicy } from "../session/credential-policy.js";
+import { buildModelCatalog, listSessionScopedCredentials } from "../routes/config.js";
+import { USER_SESSION_BRANCH_PREFIX } from "../routes/source-control-sessions.js";
+import { resolveWorkItemRepository } from "../session/work-item-repository.js";
+import { FactoryStartTransitionError, WorkItemRepositoryError } from "../rules/start-coordinator.js";
+import { recordSessionRunStart } from "../session/run-audit.js";
+import { heartbeatOpenRunUntilEnd } from "./run-watch.js";
+import { RequestContext } from "@mastra/core/request-context";
+import { z } from "zod";
+import { createTool } from "@mastra/core/tools";
+//#region src/tools/session-tools.ts
+const TITLE_LENGTH = 120;
+/** Who renews the open-run entries this process writes; one id per process, like the dispatcher's. */
+const FACTORY_TOOLS_OWNER_ID = `factory-tools:${globalThis.crypto.randomUUID()}`;
+const LISTED_MODELS = 8;
+function ambiguousRepository(candidates) {
+	return `This item has several repositories (${candidates.join(", ")}); v1 can't choose one.`;
+}
+function startErrorMessage(error) {
+	if (error instanceof WorkItemRepositoryError) return error.code === "repository_ambiguous" ? ambiguousRepository(error.candidates) : error.message;
+	if (error instanceof FactoryStartTransitionError) return `The start was refused: ${error.result.reason}`;
+	return null;
+}
+function workItemLabel(item) {
+	const number = workItemNumber(item);
+	return number === null ? `"${item.title}"` : `#${number}`;
+}
+function titleFrom(prompt) {
+	return (prompt.split("\n").find((line) => line.trim()) ?? prompt).trim().slice(0, TITLE_LENGTH);
+}
+/** Tools that start sessions on the caller's behalf, or switch their models. User sessions only. */
+function createFactorySessionTools(scope, deps) {
+	/** The models a session can switch to, resolved from the target session's owner and project policy. */
+	async function sessionModelCatalog(controller, sessionId, threadId, resourceId) {
+		const models = await controller.listAvailableModels();
+		const known = new Set(models.flatMap((model) => typeof model.id === "string" ? [model.id] : []));
+		const tenantCatalog = deps.sessionModel.tenantCatalog;
+		if (!tenantCatalog) return {
+			usable: (await buildModelCatalog({ controller })).map((model) => model.id),
+			known,
+			scopeLabel: "server"
+		};
+		const requestContext = new RequestContext();
+		requestContext.set("user", {
+			id: scope.userId,
+			organizationId: scope.orgId
+		});
+		requestContext.set("controller", {
+			sessionId,
+			resourceId,
+			threadId
+		});
+		const policy = await resolveFactoryModelPolicy(requestContext, {
+			projects: deps.sessionModel.projects,
+			sourceControl: deps.sessions,
+			workItems: deps.workItems
+		});
+		if (!policy) throw new Error("Session model policy is unavailable.");
+		const modelScope = policy.tenant.credentialScope ?? "user";
+		const orgId = policy.tenant.orgId ?? scope.orgId;
+		const customProviders = tenantCatalog.customProviders;
+		const usable = (await buildModelCatalog({
+			controller,
+			tenantCredentials: await listSessionScopedCredentials({
+				credentials: tenantCatalog.credentials,
+				orgId,
+				userId: policy.tenant.userId,
+				modelScope
+			}),
+			deploymentProviders: tenantCatalog.deploymentProviders,
+			listCustomProviders: customProviders ? async () => {
+				await customProviders.ensureReady();
+				return customProviders.list({ orgId });
+			} : void 0
+		})).map((model) => model.id);
+		for (const id of usable) known.add(id);
+		return {
+			usable,
+			known,
+			scopeLabel: modelScope === "factory" ? "Factory" : "session owner"
+		};
+	}
+	const switchModel = createTool({
+		id: "factory_switch_session_model",
+		description: "Switch the model of a session you own in this Factory (side, work item, or review session) without recreating it. A running session switches immediately; a stopped one uses the model on its next run. The model must be one the session credentials can run: the owner credentials for a user-scoped session, the Factory credentials for a Factory-scoped one. Use a session ID from the Factory session or work item tools.",
+		inputSchema: z.object({
+			sessionId: z.string().trim().min(1).max(200),
+			modelId: z.string().trim().min(1).max(200)
+		}).strict(),
+		execute: async ({ sessionId, modelId }) => {
+			const row = await deps.sessions.getBySessionId(sessionId);
+			if (!row || row.orgId !== scope.orgId || row.factoryProjectId !== scope.factoryProjectId || row.userId !== scope.userId) throw new Error("Session not found or not owned by you in this Factory.");
+			if (!scope.interactive && sessionId !== scope.sessionId && row.originSessionId !== scope.sessionId) throw new Error("Without a person in this turn, only this session and the side sessions it started can switch models.");
+			const messaging = await deps.messaging();
+			if (!messaging) throw new Error("Session model switching is not available on this server.");
+			const threadId = await resolveSessionThread({
+				controller: messaging.controller,
+				sessions: deps.sessions,
+				workItems: deps.workItems,
+				sessionId
+			});
+			if (!threadId) throw new Error("Session has no conversation thread yet.");
+			const resourceId = (await messaging.controller.queryThreadById({ threadId }))?.resourceId ?? sessionId;
+			const catalog = await sessionModelCatalog(messaging.controller, sessionId, threadId, resourceId);
+			if (!catalog.usable.includes(modelId)) {
+				const options = catalog.usable.length ? ` Models available to it: ${catalog.usable.slice(0, LISTED_MODELS).join(", ")}${catalog.usable.length > LISTED_MODELS ? ", …" : ""}.` : " No models are available to it; connect a provider credential first.";
+				throw new Error(catalog.known.has(modelId) ? `Model ${modelId} exists, but this session's credential scope (${catalog.scopeLabel}) has no credential for its provider.${options}` : `Unknown model ${modelId}.${options}`);
+			}
+			const { live } = await messaging.controller.setThreadModel({
+				resourceId,
+				threadId,
+				modelId
+			});
+			return {
+				sessionId,
+				threadId,
+				modelId,
+				live
+			};
+		}
+	});
+	const start = createTool({
+		id: "factory_start_session",
+		description: [
+			"Start a side session in this Factory with a prompt. It runs on its own sandbox and branch as you, and reports back to this session with `factory-session` notifications.",
+			"Use it for self-contained investigations; when the result should land as a pull request, file a work item instead.",
+			"With `workItem` and `role` it starts that role on the work item instead, without moving the card, and this session follows the item.",
+			"A role that already has a session on the item (current or past) can't be started again from here: message that session with factory_signal_session, or ask the person to use the board."
+		].join(" "),
+		inputSchema: z.object({
+			prompt: z.string().trim().min(1).max(8e3).describe("The first message the new session receives."),
+			title: z.string().trim().min(1).max(TITLE_LENGTH).optional(),
+			workItem: workItemRefSchema.optional(),
+			role: z.string().trim().min(1).max(64).optional()
+		}).strict().refine((input) => input.role === void 0 || input.workItem !== void 0, {
+			message: "Pass workItem together with role.",
+			path: ["role"]
+		}),
+		execute: async ({ prompt, title, workItem, role }) => {
+			if (workItem !== void 0) {
+				if (!scope.interactive) throw new Error("Starting a role on a work item needs a person in this turn; start a side session, or ask the person to use the board.");
+				return startWorkItemRole({
+					prompt,
+					title,
+					workItem,
+					role
+				});
+			}
+			const parent = await deps.sessions.getBySessionId(scope.sessionId);
+			const sourceControl = await deps.sessions.getSourceControlBySessionId(scope.sessionId);
+			if (!parent || !sourceControl) throw new Error("This session has no Factory session row to start from.");
+			const messaging = await deps.messaging();
+			if (!messaging) throw new Error("Starting sessions is not available on this server.");
+			const sessionId = globalThis.crypto.randomUUID();
+			const ensured = await ensureFactorySourceSession({
+				sourceControl,
+				orgId: scope.orgId,
+				factoryProjectId: scope.factoryProjectId,
+				sessionId,
+				branch: `${USER_SESSION_BRANCH_PREFIX}${sessionId}`,
+				attributeToUserId: scope.userId,
+				...parent.projectRepositoryId ? { projectRepositoryId: parent.projectRepositoryId } : {},
+				visibility: parent.visibility,
+				origin: {
+					sessionId: scope.sessionId,
+					threadId: scope.threadId
+				}
+			});
+			const sessionModel = await resolveFactorySessionModel({
+				...deps.sessionModel,
+				factoryProjectId: scope.factoryProjectId,
+				orgId: scope.orgId,
+				ownerUserId: scope.userId,
+				context: "session"
+			});
+			const kickoffContext = new RequestContext();
+			kickoffContext.set("user", {
+				workosId: scope.userId,
+				organizationId: scope.orgId
+			});
+			const tags = {
+				factoryProjectId: scope.factoryProjectId,
+				projectRepositoryId: ensured.projectRepositoryId
+			};
+			const session = await messaging.controller.createSession({
+				id: ensured.sessionId,
+				ownerId: scope.userId,
+				resourceId: parent.visibility === "private" ? scope.userId : scope.factoryProjectId,
+				threadId: ensured.sessionId,
+				requestContext: kickoffContext,
+				tags
+			});
+			await session.state.set(tags);
+			await hydrateFactorySession(session, {
+				orgId: scope.orgId,
+				modelScope: sessionModel.modelScope,
+				ownerUserId: scope.userId,
+				defaultModelId: sessionModel.modelId
+			});
+			const threadId = session.thread.requireId();
+			const threadTitle = title ?? titleFrom(prompt);
+			await session.thread.rename({
+				title: threadTitle,
+				pin: false
+			});
+			await sourceControl.sessions.rename({
+				sessionId: ensured.sessionId,
+				title: threadTitle
+			});
+			await session.thread.setSetting({
+				key: "factorySessionId",
+				value: ensured.sessionId
+			});
+			await primeTenantCredentialsForTenant({
+				orgId: scope.orgId,
+				userId: scope.userId,
+				credentialScope: sessionModel.modelScope
+			});
+			await session.sendSignal({
+				id: globalThis.crypto.randomUUID(),
+				type: "user",
+				tagName: "user",
+				contents: prompt
+			}, {
+				requestContext: kickoffContext,
+				requireDelivery: true
+			}).accepted;
+			return {
+				mode: "side",
+				sessionId: ensured.sessionId,
+				threadId,
+				title: threadTitle
+			};
+		}
+	});
+	async function startWorkItemRole({ prompt, title, workItem, role }) {
+		if (!role) throw new Error("Pass the role to start on the work item.");
+		const coordinator = deps.startCoordinator();
+		if (!coordinator) throw new Error("Factory sessions can't be started yet; try again shortly.");
+		const item = await findWorkItem(deps.workItems, scope, workItem);
+		if (!item) throw workItemNotFound(workItem);
+		const label = workItemLabel(item);
+		if (!deps.boards.get(boardForWorkItem(item))?.phaseForRole(role)) throw new Error(`${label}'s board has no ${role} role.`);
+		const seated = item.sessions[role];
+		if (seated) throw new Error(`${label} already has a ${role} session ${seated.sessionId}; message it with factory_signal_session.`);
+		const parent = await deps.sessions.getBySessionId(scope.sessionId);
+		const sourceControl = await deps.sessions.getSourceControlBySessionId(scope.sessionId);
+		if (!parent || !sourceControl) throw new Error("This session has no Factory session row to start from.");
+		const messaging = await deps.messaging();
+		if (!messaging) throw new Error("Starting sessions is not available on this server.");
+		const project = await deps.sessionModel.projects.get({
+			orgId: scope.orgId,
+			id: scope.factoryProjectId
+		});
+		if (!project) throw new Error("This Factory no longer exists.");
+		const modelScope = effectiveModelScope(project.modelScope, "run");
+		const projectRepositoryId = await resolveRepository(sourceControl, item);
+		const sessionId = globalThis.crypto.randomUUID();
+		const ensured = await ensureFactorySourceSession({
+			sourceControl,
+			orgId: scope.orgId,
+			factoryProjectId: scope.factoryProjectId,
+			sessionId,
+			branch: `${USER_SESSION_BRANCH_PREFIX}${sessionId}`,
+			projectRepositoryId,
+			attributeToUserId: scope.userId,
+			visibility: parent.visibility
+		});
+		const followScope = {
+			orgId: scope.orgId,
+			factoryProjectId: scope.factoryProjectId
+		};
+		const alreadyFollowing = (await deps.workItems.listSessionSubscriptions({
+			...followScope,
+			sessionId: scope.sessionId
+		})).some((subscription) => subscription.workItemId === item.id);
+		await deps.workItems.subscribeToWorkItem({
+			...followScope,
+			workItemId: item.id,
+			sessionId: scope.sessionId,
+			threadId: scope.threadId,
+			resourceId: scope.resourceId,
+			userId: scope.userId,
+			reason: "started"
+		});
+		const startedAt = /* @__PURE__ */ new Date();
+		let prepared;
+		try {
+			prepared = await coordinator.prepare({
+				orgId: scope.orgId,
+				userId: scope.userId,
+				factoryProjectId: scope.factoryProjectId,
+				sessionId: ensured.sessionId,
+				threadTitle: title ?? `${label} ${role}`,
+				kickoffKey: globalThis.crypto.randomUUID(),
+				modelScope,
+				defaultModelId: modelScope === "factory" ? project.defaultModelId ?? void 0 : void 0,
+				workItem: {
+					id: item.id,
+					role,
+					input: {
+						externalSource: item.externalSource,
+						parentWorkItemId: item.parentWorkItemId,
+						title: item.title,
+						stages: item.stages,
+						sessions: item.sessions,
+						metadata: item.metadata
+					}
+				}
+			});
+		} catch (error) {
+			if (!alreadyFollowing) await deps.workItems.unsubscribeFromWorkItem({
+				orgId: scope.orgId,
+				workItemId: item.id,
+				sessionId: scope.sessionId
+			});
+			const message = startErrorMessage(error);
+			if (message) throw new Error(message);
+			throw error;
+		}
+		const replaced = (await deps.workItems.listRunBindings(scope.orgId, scope.factoryProjectId, item.id)).find((binding) => binding.role === role && binding.id !== prepared.bindingId && binding.revokedAt !== null && binding.revokedAt >= startedAt);
+		const session = await messaging.controller.getSession(prepared.sessionId);
+		if (!session) throw new Error(`The ${role} session was bound but is not running; open it from the board.`);
+		const kickoffId = globalThis.crypto.randomUUID();
+		const heartbeat = heartbeatOpenRunUntilEnd(session, kickoffId);
+		const kickoffContext = new RequestContext();
+		kickoffContext.set("user", {
+			workosId: scope.userId,
+			organizationId: scope.orgId
+		});
+		try {
+			await session.sendSignal({
+				id: kickoffId,
+				type: "user",
+				tagName: "user",
+				contents: prompt
+			}, {
+				requestContext: kickoffContext,
+				requireDelivery: true
+			}).accepted;
+		} catch (error) {
+			heartbeat.stop();
+			throw error;
+		}
+		await recordSessionRunStart(session, {
+			audit: deps.auditRecorder,
+			actorType: "human",
+			observedEnd: heartbeat.endReason,
+			run: {
+				kickoffId,
+				ownerId: FACTORY_TOOLS_OWNER_ID,
+				heartbeatAt: Date.now(),
+				bindingId: prepared.bindingId,
+				role,
+				startedBy: scope.userId,
+				orgId: scope.orgId,
+				factoryProjectId: scope.factoryProjectId,
+				workItemId: item.id,
+				workItemName: item.title,
+				sessionId: prepared.sessionId,
+				threadId: prepared.threadId,
+				branch: prepared.branch
+			}
+		});
+		const number = workItemNumber(item);
+		return {
+			mode: "work-item",
+			workItem: {
+				id: item.id,
+				...number === null ? {} : { number }
+			},
+			role,
+			sessionId: prepared.sessionId,
+			threadId: prepared.threadId,
+			bindingId: prepared.bindingId,
+			...replaced ? { replacedSessionId: replaced.sessionId } : {}
+		};
+	}
+	async function resolveRepository(sourceControl, item) {
+		const intakeConfig = await deps.intake?.getConfig({
+			orgId: scope.orgId,
+			integrationIds: ["linear"]
+		});
+		const repository = await resolveWorkItemRepository({
+			sourceControl,
+			orgId: scope.orgId,
+			factoryProjectId: scope.factoryProjectId,
+			item,
+			linearRepositoryMap: intakeConfig?.linear?.repositoryByLinearProject
+		});
+		if (repository.status === "ambiguous") throw new Error(ambiguousRepository(repository.candidates));
+		if (repository.status === "unlinked") throw new Error(repository.hint);
+		return repository.projectRepositoryId;
+	}
+	return {
+		factory_start_session: start,
+		factory_switch_session_model: switchModel
+	};
+}
+//#endregion
+export { FACTORY_TOOLS_OWNER_ID, createFactorySessionTools };
+
+//# sourceMappingURL=session-tools.js.map