@mastra/factory 0.0.0-aggregate-trace-20261015182851

package/dist/rules/review-source-tool.d.ts

@@ -0,0 +1,105 @@
+import type { RequestContext } from '@mastra/core/request-context';
+import type { IntegrationTools } from '../integrations/base.js';
+import type { WorkItemsStorage } from '../storage/domains/work-items/base.js';
+import type { FactorySessionSourceLookup } from './binding-context.js';
+export interface ReviewSourceOutput {
+    /**
+     * Browser-facing deep-link back to the Factory session that produced this
+     * review — the only field a review body publishes. Everything else on this
+     * shape is an input to in-run cross-checks and the session handoff, never a
+     * published field, so the GitHub/GitLab audience never sees the upstream
+     * Linear/Jira slug through the review comment.
+     */
+    sessionUrl: string;
+    /**
+     * PR/MR author recorded on the review card at intake — for GitHub this is
+     * `pullRequest.user.login`, for GitLab it is the GitLab username. The skill
+     * cross-checks it against the same REST field of the reviewed PR
+     * (`gh api repos/<owner>/<repo>/pulls/<number> --jq .user.login`; `gh pr view`
+     * formats App authors as `app/<slug>` instead of `<slug>[bot]`) or the
+     * equivalent MR fetch; a mismatch means the session is bound to a different
+     * PR/MR than the one being reviewed.
+     */
+    triggeredBy: string | null;
+    /**
+     * The externalSource recorded on the review card itself — the PR/MR the
+     * session was intake-bound to. The skill cross-checks the reviewed PR/MR
+     * against this shape so a review can never quietly land on the wrong target.
+     */
+    reviewTarget: {
+        integrationId: string;
+        type: string;
+        externalId: string;
+        url: string | null;
+    } | null;
+    /**
+     * Repository identity stamped on the review card at intake — the
+     * binding-side value for the null-`url` cross-check fallback. The skill must
+     * compare this against an identity resolved independently of the card (e.g.
+     * `gh api repos/<owner>/<repo> --jq .id` — the numeric REST id — for the
+     * session checkout's repository);
+     * comparing two values derived from the same checkout proves nothing.
+     * `null` when intake recorded no repository identity — in that case there
+     * is no verifiable bound repository and the fallback must not publish.
+     */
+    boundRepository: {
+        provider: 'github';
+        repositoryId: number;
+    } | {
+        provider: 'gitlab';
+        host: string | null;
+        projectId: number;
+    } | null;
+}
+/**
+ * Normalize the operator-provided browser-facing UI origin (the
+ * `MASTRACODE_PUBLIC_URL` env var) into the `uiOrigin` the tool accepts.
+ *
+ * Blank counts as unset: `mastracode/web/.env.schema` ships
+ * `MASTRACODE_PUBLIC_URL=` as the operator-facing line, so an empty or
+ * whitespace-only value is the expected "not configured" state — it must map
+ * to `null` (tool omitted) rather than register the tool and publish a
+ * hostless `sessionUrl` into a public review body.
+ */
+export declare function resolveReviewSourceUiOrigin(raw: string | undefined): string | null;
+/**
+ * `factory_review_source` — read the routing facts behind the current review
+ * session (session deep-link, PR/MR author, the review target) so the review
+ * agent can attribute its verdict to a concrete originating run and detect a
+ * mis-targeted review before it publishes.
+ *
+ * The tool exists to make cross-PR misattribution detectable both in-run and
+ * after the fact: a review lands on GitHub/GitLab with the Factory session URL
+ * that produced it, and the human who investigates a suspicious review can
+ * jump straight to the run.
+ *
+ * All fields are derived server-side from the bound work item — nothing enters
+ * from the agent's tool arguments — so the session URL always points at the
+ * caller's own session, never one it was asked to name.
+ *
+ * The tool is intentionally omitted (returns `{}`) whenever it cannot produce
+ * a complete, correct provenance shape: no resolvable session address, no
+ * active binding, a non-review-role binding, no bound work item, or no
+ * configured browser-facing UI origin. Skills treat tool-absent identically to
+ * tool-failed: stop-don't-publish.
+ */
+export declare function createReviewSourceTool(options: {
+    requestContext: RequestContext;
+    storage: Pick<WorkItemsStorage, 'findActiveRunBindingByThread' | 'findActiveRunBinding' | 'get'>;
+    sessions?: FactorySessionSourceLookup;
+    /**
+     * Browser-facing UI origin, no trailing slash. In a separate-SPA deployment
+     * (API host distinct from UI host) this is the UI host — the origin the
+     * emitted session link opens in. `MastraFactoryConfig.publicUrl` is the API
+     * origin and must not be used here; the caller resolves the UI origin (see
+     * `factory.ts`) via the `MASTRACODE_PUBLIC_URL` env var.
+     *
+     * `null` means no browser-facing origin is configured. Match the Slack
+     * session-link surface (`integrations/slack/slack.ts:168-171`, `:809-812`),
+     * which omits the deep-link entirely rather than publishing an API/localhost
+     * URL into a public body: the tool is dropped from the toolset, and the
+     * skill's tool-not-available branch stops publication.
+     */
+    uiOrigin: string | null;
+}): Promise<IntegrationTools>;
+//# sourceMappingURL=review-source-tool.d.ts.map

package/dist/rules/review-source-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-source-tool.d.ts","sourceRoot":"","sources":["../../src/rules/review-source-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAInE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAe,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC3F,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAGvE,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,YAAY,EAAE;QACZ,aAAa,EAAE,MAAM,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;KACpB,GAAG,IAAI,CAAC;IACT;;;;;;;;;OASG;IACH,eAAe,EACX;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAC5C;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAC9D,IAAI,CAAC;CACV;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAElF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,cAAc,EAAE,cAAc,CAAC;IAC/B,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,8BAA8B,GAAG,sBAAsB,GAAG,KAAK,CAAC,CAAC;IACjG,QAAQ,CAAC,EAAE,0BAA0B,CAAC;IACtC;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAyC5B"}

package/dist/rules/review-source-tool.js

@@ -0,0 +1,109 @@
+import { resolveFactorySessionAddress } from "./binding-context.js";
+import { z } from "zod";
+import { createTool } from "@mastra/core/tools";
+//#region src/rules/review-source-tool.ts
+/**
+* Normalize the operator-provided browser-facing UI origin (the
+* `MASTRACODE_PUBLIC_URL` env var) into the `uiOrigin` the tool accepts.
+*
+* Blank counts as unset: `mastracode/web/.env.schema` ships
+* `MASTRACODE_PUBLIC_URL=` as the operator-facing line, so an empty or
+* whitespace-only value is the expected "not configured" state — it must map
+* to `null` (tool omitted) rather than register the tool and publish a
+* hostless `sessionUrl` into a public review body.
+*/
+function resolveReviewSourceUiOrigin(raw) {
+	return raw?.trim().replace(/\/+$/, "") || null;
+}
+/**
+* `factory_review_source` — read the routing facts behind the current review
+* session (session deep-link, PR/MR author, the review target) so the review
+* agent can attribute its verdict to a concrete originating run and detect a
+* mis-targeted review before it publishes.
+*
+* The tool exists to make cross-PR misattribution detectable both in-run and
+* after the fact: a review lands on GitHub/GitLab with the Factory session URL
+* that produced it, and the human who investigates a suspicious review can
+* jump straight to the run.
+*
+* All fields are derived server-side from the bound work item — nothing enters
+* from the agent's tool arguments — so the session URL always points at the
+* caller's own session, never one it was asked to name.
+*
+* The tool is intentionally omitted (returns `{}`) whenever it cannot produce
+* a complete, correct provenance shape: no resolvable session address, no
+* active binding, a non-review-role binding, no bound work item, or no
+* configured browser-facing UI origin. Skills treat tool-absent identically to
+* tool-failed: stop-don't-publish.
+*/
+async function createReviewSourceTool(options) {
+	if (options.uiOrigin === null) return {};
+	const resolution = await resolveFactorySessionAddress({
+		requestContext: options.requestContext,
+		storage: options.storage,
+		sessions: options.sessions
+	});
+	if (!resolution) return {};
+	const binding = resolution.binding ?? await options.storage.findActiveRunBinding(resolution.address);
+	if (!binding || binding.role !== "review") return {};
+	const item = await options.storage.get({
+		orgId: binding.orgId,
+		id: binding.workItemId
+	});
+	if (!item) return {};
+	const output = {
+		sessionUrl: buildSessionUrl({
+			uiOrigin: options.uiOrigin,
+			factoryProjectId: binding.factoryProjectId,
+			sessionId: binding.sessionId,
+			threadId: binding.threadId
+		}),
+		triggeredBy: readPullRequestAuthor(item),
+		reviewTarget: readReviewTarget(item),
+		boundRepository: readBoundRepository(item)
+	};
+	return { factory_review_source: createTool({
+		id: "factory_review_source",
+		description: "Read the routing facts behind this review session: a deep-link back to the Factory session that produced the review, the PR/MR author recorded on the review card, and the review target (the PR/MR the session was intake-bound to). Publish the session URL in the required `Factory Session` block of every review body so a misattributed review can always be traced back to the run that produced it. Cross-check `triggeredBy` and `reviewTarget` against the PR/MR you fetched in Phase 1, using `boundRepository` as the intake-stamped repository identity when `reviewTarget.url` is null; do not publish the `triggeredBy`, `reviewTarget`, or `boundRepository` fields.",
+		inputSchema: z.object({}),
+		execute: async () => output
+	}) };
+}
+function buildSessionUrl(input) {
+	return `${input.uiOrigin.replace(/\/+$/, "")}/factories/${encodeURIComponent(input.factoryProjectId)}/workspaces/${encodeURIComponent(input.sessionId)}/threads/${encodeURIComponent(input.threadId)}`;
+}
+function readReviewTarget(item) {
+	const source = item.externalSource;
+	if (!source) return null;
+	return {
+		integrationId: source.integrationId,
+		type: source.type,
+		externalId: source.externalId,
+		url: typeof source.url === "string" && source.url ? source.url : null
+	};
+}
+function readBoundRepository(item) {
+	const metadata = item.metadata;
+	if (!metadata) return null;
+	if (typeof metadata.githubRepositoryId === "number") return {
+		provider: "github",
+		repositoryId: metadata.githubRepositoryId
+	};
+	if (typeof metadata.gitlabProjectId === "number") return {
+		provider: "gitlab",
+		host: typeof metadata.gitlabHost === "string" && metadata.gitlabHost ? metadata.gitlabHost : null,
+		projectId: metadata.gitlabProjectId
+	};
+	return null;
+}
+function readPullRequestAuthor(item) {
+	const metadata = item.metadata;
+	if (!metadata) return null;
+	const author = metadata.author;
+	if (typeof author === "string" && author.trim()) return author.trim();
+	return null;
+}
+//#endregion
+export { createReviewSourceTool, resolveReviewSourceUiOrigin };
+
+//# sourceMappingURL=review-source-tool.js.map

package/dist/rules/review-source-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-source-tool.js","names":[],"sources":["../../src/rules/review-source-tool.ts"],"sourcesContent":["import type { RequestContext } from '@mastra/core/request-context';\nimport { createTool } from '@mastra/core/tools';\nimport { z } from 'zod';\n\nimport type { IntegrationTools } from '../integrations/base.js';\nimport type { WorkItemRow, WorkItemsStorage } from '../storage/domains/work-items/base.js';\nimport type { FactorySessionSourceLookup } from './binding-context.js';\nimport { resolveFactorySessionAddress } from './binding-context.js';\n\nexport interface ReviewSourceOutput {\n  /**\n   * Browser-facing deep-link back to the Factory session that produced this\n   * review — the only field a review body publishes. Everything else on this\n   * shape is an input to in-run cross-checks and the session handoff, never a\n   * published field, so the GitHub/GitLab audience never sees the upstream\n   * Linear/Jira slug through the review comment.\n   */\n  sessionUrl: string;\n  /**\n   * PR/MR author recorded on the review card at intake — for GitHub this is\n   * `pullRequest.user.login`, for GitLab it is the GitLab username. The skill\n   * cross-checks it against the same REST field of the reviewed PR\n   * (`gh api repos/<owner>/<repo>/pulls/<number> --jq .user.login`; `gh pr view`\n   * formats App authors as `app/<slug>` instead of `<slug>[bot]`) or the\n   * equivalent MR fetch; a mismatch means the session is bound to a different\n   * PR/MR than the one being reviewed.\n   */\n  triggeredBy: string | null;\n  /**\n   * The externalSource recorded on the review card itself — the PR/MR the\n   * session was intake-bound to. The skill cross-checks the reviewed PR/MR\n   * against this shape so a review can never quietly land on the wrong target.\n   */\n  reviewTarget: {\n    integrationId: string;\n    type: string;\n    externalId: string;\n    url: string | null;\n  } | null;\n  /**\n   * Repository identity stamped on the review card at intake — the\n   * binding-side value for the null-`url` cross-check fallback. The skill must\n   * compare this against an identity resolved independently of the card (e.g.\n   * `gh api repos/<owner>/<repo> --jq .id` — the numeric REST id — for the\n   * session checkout's repository);\n   * comparing two values derived from the same checkout proves nothing.\n   * `null` when intake recorded no repository identity — in that case there\n   * is no verifiable bound repository and the fallback must not publish.\n   */\n  boundRepository:\n    | { provider: 'github'; repositoryId: number }\n    | { provider: 'gitlab'; host: string | null; projectId: number }\n    | null;\n}\n\n/**\n * Normalize the operator-provided browser-facing UI origin (the\n * `MASTRACODE_PUBLIC_URL` env var) into the `uiOrigin` the tool accepts.\n *\n * Blank counts as unset: `mastracode/web/.env.schema` ships\n * `MASTRACODE_PUBLIC_URL=` as the operator-facing line, so an empty or\n * whitespace-only value is the expected \"not configured\" state — it must map\n * to `null` (tool omitted) rather than register the tool and publish a\n * hostless `sessionUrl` into a public review body.\n */\nexport function resolveReviewSourceUiOrigin(raw: string | undefined): string | null {\n  return raw?.trim().replace(/\\/+$/, '') || null;\n}\n\n/**\n * `factory_review_source` — read the routing facts behind the current review\n * session (session deep-link, PR/MR author, the review target) so the review\n * agent can attribute its verdict to a concrete originating run and detect a\n * mis-targeted review before it publishes.\n *\n * The tool exists to make cross-PR misattribution detectable both in-run and\n * after the fact: a review lands on GitHub/GitLab with the Factory session URL\n * that produced it, and the human who investigates a suspicious review can\n * jump straight to the run.\n *\n * All fields are derived server-side from the bound work item — nothing enters\n * from the agent's tool arguments — so the session URL always points at the\n * caller's own session, never one it was asked to name.\n *\n * The tool is intentionally omitted (returns `{}`) whenever it cannot produce\n * a complete, correct provenance shape: no resolvable session address, no\n * active binding, a non-review-role binding, no bound work item, or no\n * configured browser-facing UI origin. Skills treat tool-absent identically to\n * tool-failed: stop-don't-publish.\n */\nexport async function createReviewSourceTool(options: {\n  requestContext: RequestContext;\n  storage: Pick<WorkItemsStorage, 'findActiveRunBindingByThread' | 'findActiveRunBinding' | 'get'>;\n  sessions?: FactorySessionSourceLookup;\n  /**\n   * Browser-facing UI origin, no trailing slash. In a separate-SPA deployment\n   * (API host distinct from UI host) this is the UI host — the origin the\n   * emitted session link opens in. `MastraFactoryConfig.publicUrl` is the API\n   * origin and must not be used here; the caller resolves the UI origin (see\n   * `factory.ts`) via the `MASTRACODE_PUBLIC_URL` env var.\n   *\n   * `null` means no browser-facing origin is configured. Match the Slack\n   * session-link surface (`integrations/slack/slack.ts:168-171`, `:809-812`),\n   * which omits the deep-link entirely rather than publishing an API/localhost\n   * URL into a public body: the tool is dropped from the toolset, and the\n   * skill's tool-not-available branch stops publication.\n   */\n  uiOrigin: string | null;\n}): Promise<IntegrationTools> {\n  if (options.uiOrigin === null) return {};\n  const resolution = await resolveFactorySessionAddress({\n    requestContext: options.requestContext,\n    storage: options.storage,\n    sessions: options.sessions,\n  });\n  if (!resolution) return {};\n  const binding = resolution.binding ?? (await options.storage.findActiveRunBinding(resolution.address));\n  // The tool exists only for review-role sessions. Work/plan/triage runs never\n  // publish reviews on GitHub, so exposing them the tool would just clutter\n  // their prompt.\n  if (!binding || binding.role !== 'review') return {};\n\n  const item = await options.storage.get({ orgId: binding.orgId, id: binding.workItemId });\n  if (!item) return {};\n\n  const sessionUrl = buildSessionUrl({\n    uiOrigin: options.uiOrigin,\n    factoryProjectId: binding.factoryProjectId,\n    sessionId: binding.sessionId,\n    threadId: binding.threadId,\n  });\n  const triggeredBy = readPullRequestAuthor(item);\n  const reviewTarget = readReviewTarget(item);\n  const boundRepository = readBoundRepository(item);\n  // Every field is pre-resolved server-side and returned as a plain object.\n  // The tool takes no arguments and does no further I/O, so a review-role\n  // session either sees a complete provenance shape or the tool is absent —\n  // the skill treats those branches identically (stop-don't-publish).\n  const output: ReviewSourceOutput = { sessionUrl, triggeredBy, reviewTarget, boundRepository };\n\n  return {\n    factory_review_source: createTool({\n      id: 'factory_review_source',\n      description:\n        'Read the routing facts behind this review session: a deep-link back to the Factory session that produced the review, the PR/MR author recorded on the review card, and the review target (the PR/MR the session was intake-bound to). Publish the session URL in the required `Factory Session` block of every review body so a misattributed review can always be traced back to the run that produced it. Cross-check `triggeredBy` and `reviewTarget` against the PR/MR you fetched in Phase 1, using `boundRepository` as the intake-stamped repository identity when `reviewTarget.url` is null; do not publish the `triggeredBy`, `reviewTarget`, or `boundRepository` fields.',\n      inputSchema: z.object({}),\n      execute: async (): Promise<ReviewSourceOutput> => output,\n    }),\n  };\n}\n\nfunction buildSessionUrl(input: {\n  uiOrigin: string;\n  factoryProjectId: string;\n  sessionId: string;\n  threadId: string;\n}): string {\n  const origin = input.uiOrigin.replace(/\\/+$/, '');\n  return `${origin}/factories/${encodeURIComponent(input.factoryProjectId)}/workspaces/${encodeURIComponent(input.sessionId)}/threads/${encodeURIComponent(input.threadId)}`;\n}\n\nfunction readReviewTarget(item: WorkItemRow): ReviewSourceOutput['reviewTarget'] {\n  const source = item.externalSource;\n  if (!source) return null;\n  return {\n    integrationId: source.integrationId,\n    type: source.type,\n    externalId: source.externalId,\n    url: typeof source.url === 'string' && source.url ? source.url : null,\n  };\n}\n\nfunction readBoundRepository(item: WorkItemRow): ReviewSourceOutput['boundRepository'] {\n  const metadata = item.metadata;\n  if (!metadata) return null;\n  // Intake stamps repository identity on every PR/MR card:\n  // `github/default-rules.ts` writes `githubRepositoryId`, and\n  // `gitlab/default-rules.ts` writes `gitlabHost` + `gitlabProjectId`.\n  if (typeof metadata.githubRepositoryId === 'number') {\n    return { provider: 'github', repositoryId: metadata.githubRepositoryId };\n  }\n  if (typeof metadata.gitlabProjectId === 'number') {\n    return {\n      provider: 'gitlab',\n      host: typeof metadata.gitlabHost === 'string' && metadata.gitlabHost ? metadata.gitlabHost : null,\n      projectId: metadata.gitlabProjectId,\n    };\n  }\n  return null;\n}\n\nfunction readPullRequestAuthor(item: WorkItemRow): string | null {\n  const metadata = item.metadata;\n  if (!metadata) return null;\n  const author = metadata.author;\n  if (typeof author === 'string' && author.trim()) return author.trim();\n  return null;\n}\n"],"mappings":";;;;;;;;;;;;;;AAiEA,SAAgB,4BAA4B,KAAwC;CAClF,OAAO,KAAK,KAAK,CAAC,CAAC,QAAQ,QAAQ,EAAE,KAAK;AAC5C;;;;;;;;;;;;;;;;;;;;;;AAuBA,eAAsB,uBAAuB,SAkBf;CAC5B,IAAI,QAAQ,aAAa,MAAM,OAAO,CAAC;CACvC,MAAM,aAAa,MAAM,6BAA6B;EACpD,gBAAgB,QAAQ;EACxB,SAAS,QAAQ;EACjB,UAAU,QAAQ;CACpB,CAAC;CACD,IAAI,CAAC,YAAY,OAAO,CAAC;CACzB,MAAM,UAAU,WAAW,WAAY,MAAM,QAAQ,QAAQ,qBAAqB,WAAW,OAAO;CAIpG,IAAI,CAAC,WAAW,QAAQ,SAAS,UAAU,OAAO,CAAC;CAEnD,MAAM,OAAO,MAAM,QAAQ,QAAQ,IAAI;EAAE,OAAO,QAAQ;EAAO,IAAI,QAAQ;CAAW,CAAC;CACvF,IAAI,CAAC,MAAM,OAAO,CAAC;CAenB,MAAM,SAA6B;EAAE,YAblB,gBAAgB;GACjC,UAAU,QAAQ;GAClB,kBAAkB,QAAQ;GAC1B,WAAW,QAAQ;GACnB,UAAU,QAAQ;EACpB,CAQ8C;EAAG,aAP7B,sBAAsB,IAOiB;EAAG,cANzC,iBAAiB,IAMmC;EAAG,iBALpD,oBAAoB,IAK8C;CAAE;CAE5F,OAAO,EACL,uBAAuB,WAAW;EAChC,IAAI;EACJ,aACE;EACF,aAAa,EAAE,OAAO,CAAC,CAAC;EACxB,SAAS,YAAyC;CACpD,CAAC,EACH;AACF;AAEA,SAAS,gBAAgB,OAKd;CAET,OAAO,GADQ,MAAM,SAAS,QAAQ,QAAQ,EAC/B,EAAE,aAAa,mBAAmB,MAAM,gBAAgB,EAAE,cAAc,mBAAmB,MAAM,SAAS,EAAE,WAAW,mBAAmB,MAAM,QAAQ;AACzK;AAEA,SAAS,iBAAiB,MAAuD;CAC/E,MAAM,SAAS,KAAK;CACpB,IAAI,CAAC,QAAQ,OAAO;CACpB,OAAO;EACL,eAAe,OAAO;EACtB,MAAM,OAAO;EACb,YAAY,OAAO;EACnB,KAAK,OAAO,OAAO,QAAQ,YAAY,OAAO,MAAM,OAAO,MAAM;CACnE;AACF;AAEA,SAAS,oBAAoB,MAA0D;CACrF,MAAM,WAAW,KAAK;CACtB,IAAI,CAAC,UAAU,OAAO;CAItB,IAAI,OAAO,SAAS,uBAAuB,UACzC,OAAO;EAAE,UAAU;EAAU,cAAc,SAAS;CAAmB;CAEzE,IAAI,OAAO,SAAS,oBAAoB,UACtC,OAAO;EACL,UAAU;EACV,MAAM,OAAO,SAAS,eAAe,YAAY,SAAS,aAAa,SAAS,aAAa;EAC7F,WAAW,SAAS;CACtB;CAEF,OAAO;AACT;AAEA,SAAS,sBAAsB,MAAkC;CAC/D,MAAM,WAAW,KAAK;CACtB,IAAI,CAAC,UAAU,OAAO;CACtB,MAAM,SAAS,SAAS;CACxB,IAAI,OAAO,WAAW,YAAY,OAAO,KAAK,GAAG,OAAO,OAAO,KAAK;CACpE,OAAO;AACT"}

package/dist/rules/start-coordinator.d.ts

@@ -0,0 +1,64 @@
+import type { MastraCodeState } from '@mastra/code-sdk/schema';
+import type { AgentController } from '@mastra/core/agent-controller';
+import { RequestContext } from '@mastra/core/request-context';
+import type { IntakeStorage } from '../storage/domains/intake/base.js';
+import type { ModelDefaultsStorage } from '../storage/domains/model-defaults/base.js';
+import type { EffectiveModelScope, FactoryProjectsStorage } from '../storage/domains/projects/base.js';
+import type { SourceControlStorageHandle } from '../storage/domains/source-control/base.js';
+import type { CreateWorkItemInput, WorkItemsStorage } from '../storage/domains/work-items/base.js';
+import type { FactoryTransitionService } from './transition-service.js';
+import type { FactoryRuleStage, FactoryTransitionResult } from './types.js';
+export interface FactoryStartRequest {
+    orgId: string;
+    userId: string;
+    factoryProjectId: string;
+    sessionId: string;
+    threadTitle: string;
+    kickoffKey: string;
+    /** Where the arrival path lands the card; a session opened on an existing card names none. */
+    destinationStage?: FactoryRuleStage;
+    /** The run's effective scope; a hybrid Factory's runs use the Factory's model and credentials. */
+    modelScope: EffectiveModelScope;
+    defaultModelId?: string;
+    workItem: {
+        id?: string;
+        role: string;
+        input: CreateWorkItemInput;
+    };
+    requestContext?: RequestContext;
+}
+export declare class WorkItemRepositoryError extends Error {
+    readonly code: 'repository_mismatch' | 'repository_ambiguous' | 'repository_unlinked';
+    readonly candidates: string[];
+    constructor(code: 'repository_mismatch' | 'repository_ambiguous' | 'repository_unlinked', message: string, candidates?: string[]);
+}
+export declare class FactoryStartTransitionError extends Error {
+    readonly result: Extract<FactoryTransitionResult, {
+        status: 'rejected';
+    }>;
+    constructor(result: Extract<FactoryTransitionResult, {
+        status: 'rejected';
+    }>);
+}
+export interface FactoryStartPreparedResult {
+    workItemId: string;
+    bindingId: string;
+    threadId: string;
+    resourceId: string;
+    sessionId: string;
+    branch: string;
+    revision: number;
+    kickoffStatus: 'pending' | 'leased' | 'retry' | 'sent' | 'failed';
+    replayed: boolean;
+}
+type FactoryController = AgentController<MastraCodeState>;
+export declare class FactoryStartCoordinator {
+    #private;
+    constructor(controller: FactoryController, storage: WorkItemsStorage, transitionService?: Pick<FactoryTransitionService, 'transition'>, sourceControl?: SourceControlStorageHandle | ((request: FactoryStartRequest) => SourceControlStorageHandle | undefined | Promise<SourceControlStorageHandle | undefined>), intake?: IntakeStorage, sessionModel?: {
+        projects: FactoryProjectsStorage;
+        modelDefaults: ModelDefaultsStorage;
+    });
+    prepare(request: FactoryStartRequest): Promise<FactoryStartPreparedResult>;
+}
+export {};
+//# sourceMappingURL=start-coordinator.d.ts.map

package/dist/rules/start-coordinator.d.ts.map

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

package/dist/rules/start-coordinator.js

@@ -0,0 +1,246 @@
+import { boardForWorkItem } from "../boards/semantics.js";
+import "../boards/index.js";
+import { primeTenantCredentialsForTenant } from "../routes/tenant-credentials.js";
+import { hydrateFactorySession, resolveFactorySessionModel } from "../session/factory-session.js";
+import { resolveWorkItemRepository } from "../session/work-item-repository.js";
+import { RequestContext } from "@mastra/core/request-context";
+//#region src/rules/start-coordinator.ts
+var WorkItemRepositoryError = class extends Error {
+	code;
+	candidates;
+	constructor(code, message, candidates = []) {
+		super(message);
+		this.code = code;
+		this.candidates = candidates;
+		this.name = "WorkItemRepositoryError";
+	}
+};
+var FactoryStartTransitionError = class extends Error {
+	result;
+	constructor(result) {
+		super(result.reason);
+		this.name = "FactoryStartTransitionError";
+		this.result = result;
+	}
+};
+async function resolveSourceSession(storage, request) {
+	const session = await storage.sessions.getBySessionId(request.sessionId);
+	if (!session || session.orgId !== request.orgId || session.userId !== request.userId) throw new Error("Factory session not found");
+	const projectRepositoryId = session.projectRepositoryId;
+	if (!projectRepositoryId) throw new Error("Factory session repository not found");
+	const projectRepository = await storage.projectRepositories.get({
+		orgId: request.orgId,
+		id: projectRepositoryId
+	});
+	if (!projectRepository) throw new Error("Factory session repository not found");
+	const connection = await storage.connections.get({
+		orgId: request.orgId,
+		id: projectRepository.connectionId
+	});
+	if (!connection || connection.factoryProjectId !== request.factoryProjectId) throw new Error("Factory session does not belong to this project");
+	return {
+		...session,
+		projectRepositoryId
+	};
+}
+async function configureThread(session, request) {
+	const threadId = session.thread.requireId();
+	await session.thread.rename({
+		title: request.threadTitle,
+		pin: false
+	});
+	await session.thread.setSetting({
+		key: "factorySessionId",
+		value: request.sessionId
+	});
+	return threadId;
+}
+var FactoryStartCoordinator = class {
+	#controller;
+	#storage;
+	#transitionService;
+	#sourceControl;
+	#intake;
+	#projects;
+	#modelDefaults;
+	constructor(controller, storage, transitionService, sourceControl, intake, sessionModel) {
+		this.#controller = controller;
+		this.#storage = storage;
+		this.#transitionService = transitionService;
+		this.#sourceControl = sourceControl;
+		this.#intake = intake;
+		this.#projects = sessionModel?.projects;
+		this.#modelDefaults = sessionModel?.modelDefaults;
+	}
+	async prepare(request) {
+		const storage = this.#storage;
+		const sourceControl = typeof this.#sourceControl === "function" ? await this.#sourceControl(request) : this.#sourceControl;
+		if (!sourceControl) throw new Error("Factory source control storage is unavailable");
+		const sourceSession = await resolveSourceSession(sourceControl, request);
+		const sessionModel = this.#projects && this.#modelDefaults ? await resolveFactorySessionModel({
+			projects: this.#projects,
+			modelDefaults: this.#modelDefaults,
+			factoryProjectId: request.factoryProjectId,
+			orgId: request.orgId,
+			ownerUserId: sourceSession.userId,
+			context: "run"
+		}) : {
+			modelScope: request.modelScope,
+			modelId: request.defaultModelId
+		};
+		const storedItem = request.workItem.id ? await storage.get({
+			orgId: request.orgId,
+			id: request.workItem.id
+		}) : null;
+		const intakeConfig = await this.#intake?.getConfig({
+			orgId: request.orgId,
+			integrationIds: ["linear"]
+		});
+		let repository = await resolveWorkItemRepository({
+			sourceControl,
+			orgId: request.orgId,
+			factoryProjectId: request.factoryProjectId,
+			item: storedItem ?? { metadata: request.workItem.input.metadata ?? null },
+			linearRepositoryMap: intakeConfig?.linear?.repositoryByLinearProject
+		});
+		if (repository.status === "ambiguous") {
+			if (storedItem?.sessions[request.workItem.role]?.sessionId !== sourceSession.sessionId) throw new WorkItemRepositoryError("repository_ambiguous", `Choose a repository for this work item: ${repository.candidates.join(", ")}.`, repository.candidates);
+			const link = await sourceControl.projectRepositories.get({
+				orgId: request.orgId,
+				id: sourceSession.projectRepositoryId
+			});
+			const linked = link && await sourceControl.repositories.get({
+				orgId: request.orgId,
+				id: link.repositoryId
+			});
+			const currentLinks = link ? await sourceControl.projectRepositories.list({
+				orgId: request.orgId,
+				connectionId: link.connectionId
+			}) : [];
+			if (!linked || !repository.candidates.includes(linked.slug) || !currentLinks.some((candidate) => candidate.id === sourceSession.projectRepositoryId)) throw new WorkItemRepositoryError("repository_unlinked", "The existing session repository is not linked to this Factory.");
+			repository = {
+				status: "resolved",
+				slug: linked.slug,
+				projectRepositoryId: sourceSession.projectRepositoryId
+			};
+		}
+		if (repository.status === "unlinked") throw new WorkItemRepositoryError("repository_unlinked", repository.hint);
+		if (repository.projectRepositoryId !== sourceSession.projectRepositoryId) throw new WorkItemRepositoryError("repository_mismatch", `This run session is bound to a different repository than ${repository.slug}.`);
+		const requestContext = request.requestContext ?? new RequestContext();
+		const existingUser = requestContext.get("user");
+		if (!existingUser || typeof existingUser !== "object") requestContext.set("user", {
+			workosId: request.userId,
+			organizationId: request.orgId
+		});
+		const untrustedCheckout = request.workItem.input.externalSource?.type === "pull-request";
+		const metadataBaseBranch = request.workItem.input.metadata?.baseBranch;
+		const baseRef = (sourceSession.baseBranch || void 0) ?? (typeof metadataBaseBranch === "string" && metadataBaseBranch ? metadataBaseBranch : void 0);
+		const sessionTags = {
+			factoryProjectId: request.factoryProjectId,
+			projectRepositoryId: sourceSession.projectRepositoryId
+		};
+		const session = await this.#controller.createSession({
+			id: sourceSession.sessionId,
+			ownerId: request.userId,
+			resourceId: sourceSession.sessionId,
+			threadId: sourceSession.sessionId,
+			requestContext,
+			tags: sessionTags
+		});
+		const targetRepositoryInstruction = `Target repository: ${repository.slug}. Before editing files or creating a pull request, verify this session's checkout matches the target repository.`;
+		const existingPluginInstructions = session.state.get()?.pluginInstructions ?? [];
+		await session.state.set({
+			...sessionTags,
+			factoryOrgId: request.orgId,
+			factoryModelScope: sessionModel.modelScope,
+			factoryOwnerUserId: sourceSession.userId,
+			pluginInstructions: [...existingPluginInstructions.filter((instruction) => instruction !== targetRepositoryInstruction), targetRepositoryInstruction],
+			...untrustedCheckout ? {
+				untrustedCheckout: true,
+				...baseRef ? { baseRef } : {}
+			} : {}
+		});
+		await primeTenantCredentialsForTenant({
+			orgId: request.orgId,
+			userId: sourceSession.userId,
+			credentialScope: sessionModel.modelScope
+		});
+		await hydrateFactorySession(session, {
+			orgId: request.orgId,
+			modelScope: sessionModel.modelScope,
+			ownerUserId: sourceSession.userId,
+			defaultModelId: sessionModel.modelId
+		});
+		await session.permissions.setForTool({
+			toolName: "factory_transition_work_item",
+			policy: "allow"
+		});
+		const threadId = await configureThread(session, request);
+		const prepared = await storage.prepareRunStart({
+			orgId: request.orgId,
+			userId: request.userId,
+			factoryProjectId: request.factoryProjectId,
+			workItem: {
+				id: request.workItem.id,
+				input: request.workItem.input
+			},
+			role: request.workItem.role,
+			session: {
+				sessionId: sourceSession.sessionId,
+				branch: sourceSession.branch,
+				threadId
+			},
+			resourceId: sourceSession.sessionId,
+			kickoffKey: request.kickoffKey,
+			kickoffMessage: null
+		});
+		await session.thread.setSetting({
+			key: "factoryWorkItemId",
+			value: prepared.item.id
+		});
+		let revision = prepared.item.revision;
+		const destinationStage = request.destinationStage;
+		if (destinationStage && (prepared.item.stages.length !== 1 || prepared.item.stages[0] !== destinationStage)) {
+			if (!this.#transitionService) throw new Error("Factory transition service is unavailable.");
+			const transition = await this.#transitionService.transition({
+				orgId: request.orgId,
+				factoryProjectId: request.factoryProjectId,
+				workItemId: prepared.item.id,
+				board: boardForWorkItem(prepared.item),
+				stage: destinationStage,
+				expectedRevision: prepared.item.revision,
+				actor: {
+					type: "human",
+					id: request.userId
+				},
+				ingress: {
+					type: "human",
+					identity: `start:${request.kickoffKey}:transition`
+				},
+				cause: "run_start"
+			});
+			if (transition.status === "rejected") {
+				await storage.markPendingStart(prepared.binding.id, "failed", transition.reason);
+				throw new FactoryStartTransitionError(transition);
+			}
+			revision = transition.revision;
+		}
+		await storage.markPendingStart(prepared.binding.id, "sent");
+		prepared.pendingStart.status = "sent";
+		return {
+			workItemId: prepared.item.id,
+			bindingId: prepared.binding.id,
+			threadId,
+			resourceId: sourceSession.sessionId,
+			sessionId: sourceSession.sessionId,
+			branch: sourceSession.branch,
+			revision,
+			kickoffStatus: prepared.pendingStart.status,
+			replayed: prepared.replayed
+		};
+	}
+};
+//#endregion
+export { FactoryStartCoordinator, FactoryStartTransitionError, WorkItemRepositoryError };
+
+//# sourceMappingURL=start-coordinator.js.map

package/dist/rules/start-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-coordinator.js","names":["#controller","#storage","#transitionService","#sourceControl","#intake","#projects","#modelDefaults"],"sources":["../../src/rules/start-coordinator.ts"],"sourcesContent":["import type { MastraCodeState } from '@mastra/code-sdk/schema';\nimport type { AgentController } from '@mastra/core/agent-controller';\nimport { RequestContext } from '@mastra/core/request-context';\n\nimport { boardForWorkItem } from '../boards/index.js';\nimport { primeTenantCredentialsForTenant } from '../routes/tenant-credentials.js';\nimport { hydrateFactorySession, resolveFactorySessionModel } from '../session/factory-session.js';\nimport { resolveWorkItemRepository } from '../session/work-item-repository.js';\nimport type { IntakeStorage } from '../storage/domains/intake/base.js';\nimport type { ModelDefaultsStorage } from '../storage/domains/model-defaults/base.js';\nimport type { EffectiveModelScope, FactoryProjectsStorage } from '../storage/domains/projects/base.js';\nimport type { SourceControlSession, SourceControlStorageHandle } from '../storage/domains/source-control/base.js';\nimport type { CreateWorkItemInput, WorkItemsStorage } from '../storage/domains/work-items/base.js';\nimport type { FactoryTransitionService } from './transition-service.js';\nimport type { FactoryRuleStage, FactoryTransitionResult } from './types.js';\n\nexport interface FactoryStartRequest {\n  orgId: string;\n  userId: string;\n  factoryProjectId: string;\n  sessionId: string;\n  threadTitle: string;\n  kickoffKey: string;\n  /** Where the arrival path lands the card; a session opened on an existing card names none. */\n  destinationStage?: FactoryRuleStage;\n  /** The run's effective scope; a hybrid Factory's runs use the Factory's model and credentials. */\n  modelScope: EffectiveModelScope;\n  defaultModelId?: string;\n  workItem: {\n    id?: string;\n    role: string;\n    input: CreateWorkItemInput;\n  };\n  requestContext?: RequestContext;\n}\n\nexport class WorkItemRepositoryError extends Error {\n  constructor(\n    readonly code: 'repository_mismatch' | 'repository_ambiguous' | 'repository_unlinked',\n    message: string,\n    readonly candidates: string[] = [],\n  ) {\n    super(message);\n    this.name = 'WorkItemRepositoryError';\n  }\n}\n\nexport class FactoryStartTransitionError extends Error {\n  readonly result: Extract<FactoryTransitionResult, { status: 'rejected' }>;\n\n  constructor(result: Extract<FactoryTransitionResult, { status: 'rejected' }>) {\n    super(result.reason);\n    this.name = 'FactoryStartTransitionError';\n    this.result = result;\n  }\n}\n\nexport interface FactoryStartPreparedResult {\n  workItemId: string;\n  bindingId: string;\n  threadId: string;\n  resourceId: string;\n  sessionId: string;\n  branch: string;\n  revision: number;\n  kickoffStatus: 'pending' | 'leased' | 'retry' | 'sent' | 'failed';\n  replayed: boolean;\n}\n\ntype FactoryController = AgentController<MastraCodeState>;\ntype FactorySession = Awaited<ReturnType<FactoryController['createSession']>>;\n\nasync function resolveSourceSession(\n  storage: SourceControlStorageHandle,\n  request: FactoryStartRequest,\n): Promise<SourceControlSession & { projectRepositoryId: string }> {\n  const session = await storage.sessions.getBySessionId(request.sessionId);\n  if (!session || session.orgId !== request.orgId || session.userId !== request.userId) {\n    throw new Error('Factory session not found');\n  }\n  const projectRepositoryId = session.projectRepositoryId;\n  if (!projectRepositoryId) throw new Error('Factory session repository not found');\n  const projectRepository = await storage.projectRepositories.get({ orgId: request.orgId, id: projectRepositoryId });\n  if (!projectRepository) throw new Error('Factory session repository not found');\n  const connection = await storage.connections.get({ orgId: request.orgId, id: projectRepository.connectionId });\n  if (!connection || connection.factoryProjectId !== request.factoryProjectId) {\n    throw new Error('Factory session does not belong to this project');\n  }\n  return { ...session, projectRepositoryId };\n}\n\nasync function configureThread(session: FactorySession, request: FactoryStartRequest): Promise<string> {\n  const threadId = session.thread.requireId();\n  // Derived from the work item, not a user rename, so leave the title\n  // unpinned and let auto-naming keep refining it.\n  await session.thread.rename({ title: request.threadTitle, pin: false });\n  await session.thread.setSetting({ key: 'factorySessionId', value: request.sessionId });\n  return threadId;\n}\n\nexport class FactoryStartCoordinator {\n  readonly #controller: FactoryController;\n  readonly #storage: WorkItemsStorage;\n  readonly #transitionService?: Pick<FactoryTransitionService, 'transition'>;\n  readonly #sourceControl?:\n    | SourceControlStorageHandle\n    | ((\n        request: FactoryStartRequest,\n      ) => SourceControlStorageHandle | undefined | Promise<SourceControlStorageHandle | undefined>);\n  readonly #intake?: IntakeStorage;\n  readonly #projects?: FactoryProjectsStorage;\n  readonly #modelDefaults?: ModelDefaultsStorage;\n\n  constructor(\n    controller: FactoryController,\n    storage: WorkItemsStorage,\n    transitionService?: Pick<FactoryTransitionService, 'transition'>,\n    sourceControl?:\n      | SourceControlStorageHandle\n      | ((\n          request: FactoryStartRequest,\n        ) => SourceControlStorageHandle | undefined | Promise<SourceControlStorageHandle | undefined>),\n    intake?: IntakeStorage,\n    sessionModel?: { projects: FactoryProjectsStorage; modelDefaults: ModelDefaultsStorage },\n  ) {\n    this.#controller = controller;\n    this.#storage = storage;\n    this.#transitionService = transitionService;\n    this.#sourceControl = sourceControl;\n    this.#intake = intake;\n    this.#projects = sessionModel?.projects;\n    this.#modelDefaults = sessionModel?.modelDefaults;\n  }\n\n  async prepare(request: FactoryStartRequest): Promise<FactoryStartPreparedResult> {\n    const storage = this.#storage;\n    const sourceControl =\n      typeof this.#sourceControl === 'function' ? await this.#sourceControl(request) : this.#sourceControl;\n    if (!sourceControl) throw new Error('Factory source control storage is unavailable');\n    const sourceSession = await resolveSourceSession(sourceControl, request);\n    const sessionModel =\n      this.#projects && this.#modelDefaults\n        ? await resolveFactorySessionModel({\n            projects: this.#projects,\n            modelDefaults: this.#modelDefaults,\n            factoryProjectId: request.factoryProjectId,\n            orgId: request.orgId,\n            ownerUserId: sourceSession.userId,\n            context: 'run',\n          })\n        : { modelScope: request.modelScope, modelId: request.defaultModelId };\n    const storedItem = request.workItem.id\n      ? await storage.get({ orgId: request.orgId, id: request.workItem.id })\n      : null;\n    const intakeConfig = await this.#intake?.getConfig({ orgId: request.orgId, integrationIds: ['linear'] });\n    let repository = await resolveWorkItemRepository({\n      sourceControl,\n      orgId: request.orgId,\n      factoryProjectId: request.factoryProjectId,\n      item: storedItem ?? { metadata: request.workItem.input.metadata ?? null },\n      linearRepositoryMap: intakeConfig?.linear?.repositoryByLinearProject,\n    });\n    if (repository.status === 'ambiguous') {\n      // A retry of this role's existing session keeps its already-chosen\n      // repository; a newly minted session must not choose for the card.\n      if (storedItem?.sessions[request.workItem.role]?.sessionId !== sourceSession.sessionId) {\n        throw new WorkItemRepositoryError(\n          'repository_ambiguous',\n          `Choose a repository for this work item: ${repository.candidates.join(', ')}.`,\n          repository.candidates,\n        );\n      }\n      const link = await sourceControl.projectRepositories.get({\n        orgId: request.orgId,\n        id: sourceSession.projectRepositoryId,\n      });\n      const linked = link && (await sourceControl.repositories.get({ orgId: request.orgId, id: link.repositoryId }));\n      const currentLinks = link\n        ? await sourceControl.projectRepositories.list({ orgId: request.orgId, connectionId: link.connectionId })\n        : [];\n      if (\n        !linked ||\n        !repository.candidates.includes(linked.slug) ||\n        !currentLinks.some(candidate => candidate.id === sourceSession.projectRepositoryId)\n      ) {\n        throw new WorkItemRepositoryError(\n          'repository_unlinked',\n          'The existing session repository is not linked to this Factory.',\n        );\n      }\n      repository = { status: 'resolved', slug: linked.slug, projectRepositoryId: sourceSession.projectRepositoryId };\n    }\n    if (repository.status === 'unlinked') {\n      throw new WorkItemRepositoryError('repository_unlinked', repository.hint);\n    }\n    if (repository.projectRepositoryId !== sourceSession.projectRepositoryId) {\n      throw new WorkItemRepositoryError(\n        'repository_mismatch',\n        `This run session is bound to a different repository than ${repository.slug}.`,\n      );\n    }\n    const requestContext = request.requestContext ?? new RequestContext();\n    // Preserve an authenticated caller when present. Autonomous starts still\n    // need a principal so deployed credential resolution can authenticate the\n    // request before selecting the stamped session owner's exclusive scope.\n    const existingUser = requestContext.get('user');\n    if (!existingUser || typeof existingUser !== 'object') {\n      requestContext.set('user', {\n        workosId: request.userId,\n        organizationId: request.orgId,\n      });\n    }\n    // Sessions kicked off against third-party content (a PR under review, or\n    // any pull-request-sourced work item) get `untrustedCheckout` so the SDK\n    // never ingests the checkout's AGENTS.md/CLAUDE.md into the system prompt\n    // or reminders — those files are attacker-writable in a PR branch.\n    const untrustedCheckout = request.workItem.input.externalSource?.type === 'pull-request';\n    // The trusted ref the SDK may serve project instruction files from on an\n    // untrusted checkout (the PR's base branch). Prefer the session record's\n    // base branch; fall back to the intake metadata captured from the PR.\n    const metadataBaseBranch = request.workItem.input.metadata?.baseBranch;\n    const baseRef =\n      (sourceSession.baseBranch || undefined) ??\n      (typeof metadataBaseBranch === 'string' && metadataBaseBranch ? metadataBaseBranch : undefined);\n    const sessionTags = {\n      factoryProjectId: request.factoryProjectId,\n      projectRepositoryId: sourceSession.projectRepositoryId,\n    };\n    const session = await this.#controller.createSession({\n      id: sourceSession.sessionId,\n      ownerId: request.userId,\n      resourceId: sourceSession.sessionId,\n      threadId: sourceSession.sessionId,\n      requestContext,\n      tags: sessionTags,\n    });\n    // Bound-agent authority gates (the transition tool, the factory-phase\n    // processor, workspace token selection) resolve the session address from\n    // controller state. Seed it server-side — `tags` covers fresh creation,\n    // the explicit setState covers get-or-create returning a session another\n    // caller created without them — so autonomous runs never depend on a\n    // browser connecting to populate the state. `untrustedCheckout` is a\n    // boolean so it rides only on state (tags are string-valued).\n    const targetRepositoryInstruction = `Target repository: ${repository.slug}. Before editing files or creating a pull request, verify this session's checkout matches the target repository.`;\n    const existingPluginInstructions = session.state.get()?.pluginInstructions ?? [];\n    await session.state.set({\n      ...sessionTags,\n      // The authoritative org id for every downstream identity read (the\n      // memory seam's organizationId): the session owner is a USER id, not an\n      // org, so it must never be improvised from ownerId.\n      factoryOrgId: request.orgId,\n      factoryModelScope: sessionModel.modelScope,\n      factoryOwnerUserId: sourceSession.userId,\n      pluginInstructions: [\n        ...existingPluginInstructions.filter(instruction => instruction !== targetRepositoryInstruction),\n        targetRepositoryInstruction,\n      ],\n      ...(untrustedCheckout ? { untrustedCheckout: true, ...(baseRef ? { baseRef } : {}) } : {}),\n    });\n    await primeTenantCredentialsForTenant({\n      orgId: request.orgId,\n      userId: sourceSession.userId,\n      credentialScope: sessionModel.modelScope,\n    });\n    // Apply the factory's main model before any model-dependent run work.\n    // Observational-memory settings are loaded per invocation by the input processor.\n    await hydrateFactorySession(session, {\n      orgId: request.orgId,\n      modelScope: sessionModel.modelScope,\n      ownerUserId: sourceSession.userId,\n      defaultModelId: sessionModel.modelId,\n    });\n    // The tool is `requireApproval`, and that prompt parks the run whether or not\n    // someone pressed Start — a person is reading the plan, not an approval queue.\n    // Starting the run was already the say-so; the rules engine still governs.\n    await session.permissions.setForTool({ toolName: 'factory_transition_work_item', policy: 'allow' });\n    const threadId = await configureThread(session, request);\n    const prepared = await storage.prepareRunStart({\n      orgId: request.orgId,\n      userId: request.userId,\n      factoryProjectId: request.factoryProjectId,\n      workItem: { id: request.workItem.id, input: request.workItem.input },\n      role: request.workItem.role,\n      session: { sessionId: sourceSession.sessionId, branch: sourceSession.branch, threadId },\n      resourceId: sourceSession.sessionId,\n      kickoffKey: request.kickoffKey,\n      kickoffMessage: null,\n    });\n    await session.thread.setSetting({ key: 'factoryWorkItemId', value: prepared.item.id });\n\n    let revision = prepared.item.revision;\n    const destinationStage = request.destinationStage;\n    if (destinationStage && (prepared.item.stages.length !== 1 || prepared.item.stages[0] !== destinationStage)) {\n      if (!this.#transitionService) throw new Error('Factory transition service is unavailable.');\n      const transition = await this.#transitionService.transition({\n        orgId: request.orgId,\n        factoryProjectId: request.factoryProjectId,\n        workItemId: prepared.item.id,\n        board: boardForWorkItem(prepared.item),\n        stage: destinationStage,\n        expectedRevision: prepared.item.revision,\n        actor: { type: 'human', id: request.userId },\n        ingress: { type: 'human', identity: `start:${request.kickoffKey}:transition` },\n        cause: 'run_start',\n      });\n      if (transition.status === 'rejected') {\n        await storage.markPendingStart(prepared.binding.id, 'failed', transition.reason);\n        throw new FactoryStartTransitionError(transition);\n      }\n      revision = transition.revision;\n    }\n\n    await storage.markPendingStart(prepared.binding.id, 'sent');\n    prepared.pendingStart.status = 'sent';\n\n    return {\n      workItemId: prepared.item.id,\n      bindingId: prepared.binding.id,\n      threadId,\n      resourceId: sourceSession.sessionId,\n      sessionId: sourceSession.sessionId,\n      branch: sourceSession.branch,\n      revision,\n      kickoffStatus: prepared.pendingStart.status,\n      replayed: prepared.replayed,\n    };\n  }\n}\n"],"mappings":"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"}

package/dist/rules/terminal-cleanup.d.ts

@@ -0,0 +1,38 @@
+import type { FactoryRunBindingRecord, WorkItemsStorage } from '../storage/domains/work-items/base.js';
+export interface TerminalStageCleanupOptions {
+    workItems: Pick<WorkItemsStorage, 'get' | 'listRunBindings' | 'revokeRunBindingsForWorkItem' | 'supersedeTerminalDecisionsForWorkItem' | 'findRunBindingBySession'>;
+    /** Final ingest of trailing tool results before the binding is revoked. */
+    reconcileBinding?: (binding: FactoryRunBindingRecord) => Promise<void>;
+    /**
+     * Abort the live controller run bound to a retired seat. Without this the
+     * model keeps executing unbound after its binding is revoked (its transition
+     * tool vanishes or throws), and the parked run can later be resumed and
+     * rationalize a false blocked state.
+     */
+    abortSession?: (binding: FactoryRunBindingRecord) => Promise<void>;
+    /** Release the item's session sandboxes back to the reuse pool. */
+    releaseSandboxes?: (args: TerminalStageCleanupArgs) => Promise<unknown>;
+}
+export interface TerminalStageCleanupArgs {
+    orgId: string;
+    factoryProjectId: string;
+    workItemId: string;
+    /** Revision produced by the terminal transition that scheduled this cleanup. */
+    revision?: number;
+    /**
+     * The bound agent seat whose own tool call drove this terminal transition, if
+     * any. Its run is already returning from the tool call; aborting it would
+     * interrupt its own completion, so it is left alone.
+     */
+    initiatingBindingId?: string;
+}
+/**
+ * Terminal-stage cleanup for a work item: ingest any trailing tool results
+ * from the item's bound threads, revoke its active run bindings so completed
+ * items leave the reconcile walk (the active set otherwise grows forever),
+ * dismiss the runs still parked on it, then release its sandboxes. Every step
+ * is best-effort — a committed transition never fails on cleanup; leaked
+ * bindings are drained by the staleness sweep.
+ */
+export declare function createTerminalStageCleanup(options: TerminalStageCleanupOptions): (args: TerminalStageCleanupArgs) => Promise<void>;
+//# sourceMappingURL=terminal-cleanup.d.ts.map