@mastra/factory 0.21.1-alpha.3 → 0.22.0-alpha.4

package/dist/environment/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","names":[],"sources":["../../src/environment/build.ts"],"sourcesContent":["/**\n * One proactive environment build: decide whether a trigger should build,\n * hand the sandbox's `builds` capability a context identical to a session's,\n * and record the started build on the project row. Polling the build to its\n * end and pinning the active template is the workflow's second step\n * (`build-workflow.ts`), so a request that only needs the start answer never\n * waits on the provider.\n */\n\nimport { createHash, randomUUID } from 'node:crypto';\n\nimport type { FactorySandbox, FactorySandboxContext } from '@mastra/core/workspace';\nimport type { VersionControl } from '../capabilities/version-control.js';\nimport type { FactoryProject, FactoryProjectsStorage } from '../storage/domains/projects/base.js';\nimport type { SourceControlStorageHandle } from '../storage/domains/source-control/base.js';\nimport { environmentSandboxContext, resolveProjectEnvironment } from '../workspace.js';\nimport type { SessionEnvironment } from '../workspace.js';\nimport { headsChanged, recordedHeadResolver, resolveCurrentHeads } from './heads.js';\nimport type { EnvironmentHeads } from './heads.js';\n\nexport const ENVIRONMENT_BUILD_TRIGGERS = ['manual', 'schedule', 'push'] as const;\nexport type EnvironmentBuildTrigger = (typeof ENVIRONMENT_BUILD_TRIGGERS)[number];\n\nexport interface EnvironmentBuildSourceControl {\n  storage: Pick<SourceControlStorageHandle, 'projectRepositories' | 'repositories'>;\n  versionControl: Pick<VersionControl, 'getRepositoryAccess'>;\n}\n\nexport interface EnvironmentBuildDeps {\n  /** The factory's normalized sandbox; builds are unavailable without its `builds`. */\n  sandbox: FactorySandbox | undefined;\n  projects: Pick<\n    FactoryProjectsStorage,\n    'getById' | 'claimBuildAttempt' | 'claimBuildStart' | 'renewBuildStart' | 'releaseBuildStart' | 'pinActiveTemplate'\n  >;\n  /** Absent when the factory has no source-control integration to resolve heads with. */\n  sourceControl: EnvironmentBuildSourceControl | undefined;\n  logger?: { info: (msg: string, meta?: Record<string, unknown>) => void };\n  now?: () => Date;\n  /** How often a run renews its build-start lease; a third of `BUILD_START_LEASE_MS` by default. */\n  leaseRenewMs?: number;\n  /** Waits between tries at recording a started build. */\n  sleep?: (ms: number) => Promise<void>;\n}\n\nexport interface EnvironmentBuildOutcome {\n  outcome: 'started' | 'skipped' | 'unavailable' | 'failed';\n  buildId?: string;\n  templateId?: string;\n  /** Why nothing started: `debounced`, `starting` (another run is starting a build), `in_progress`, `unchanged`, `unresolved` (a lapsed run may have started a build the provider cannot list), `no_environment`, `no_builds`, `no_source_control`; why a run failed: `not_recorded`, `superseded`, or an error. */\n  reason?: string;\n  /** The heads the started build pins; the workflow stores them once the build is ready. */\n  heads?: EnvironmentHeads;\n}\n\n/** The synthetic session id a project's build runs under; never a session. */\nexport function environmentBuildSessionId(projectId: string): string {\n  return `environment-build:${projectId}`;\n}\n\n/**\n * A build or setup error may echo a clone URL or a token; strip URL userinfo\n * and GitHub token shapes before the message is stored, logged or shown.\n */\nexport function redactCredentials(message: string): string {\n  return message.replace(/\\/\\/[^/\\s@]+@/g, '//***@').replace(/\\b(?:gh[pousr]|github_pat)_[A-Za-z0-9_]+/g, '***');\n}\n\n/** An error's message with credentials redacted, safe to log, store or return. */\nexport function errorReason(error: unknown): string {\n  return redactCredentials(error instanceof Error ? error.message : String(error));\n}\n\n/**\n * The context an environment build (or a read of its status) hands the\n * provider: the same list form a session boots with, under the build's own\n * session id, with heads served from `heads` so the provider never resolves\n * them itself.\n */\nexport function environmentBuildContext(\n  project: Pick<FactoryProject, 'id' | 'orgId'>,\n  environment: SessionEnvironment,\n  heads: EnvironmentHeads,\n  versionControl: Pick<VersionControl, 'getRepositoryAccess'>,\n): FactorySandboxContext {\n  return {\n    sessionId: environmentBuildSessionId(project.id),\n    ...environmentSandboxContext(environment, {\n      orgId: project.orgId,\n      getRepositoryAccess: args => versionControl.getRepositoryAccess(args),\n      resolveHead: recordedHeadResolver(heads),\n    }),\n  };\n}\n\n/**\n * Fingerprint of everything a build bakes into the template besides the\n * repository heads: provider settings, the repositories and their order,\n * their setup commands, the workspace setup command and the working\n * directory. A schedule or push skips a ready build only while this matches.\n */\nexport function environmentBuildInputs(environment: SessionEnvironment): string {\n  const inputs = {\n    settings: environment.settings,\n    workspaceSetupCommand: environment.workspaceSetupCommand ?? null,\n    workingDirectory: environment.workingDirectory ?? null,\n    repos: environment.repos.map(repo => ({\n      repositoryId: repo.repositoryId,\n      templateBranch: repo.templateBranch,\n      setupCommand: repo.setupCommand ?? null,\n    })),\n  };\n  return createHash('sha256').update(JSON.stringify(inputs)).digest('hex');\n}\n\n/**\n * The current head of every environment repository's template branch, keyed\n * by slug. The template clones the repository default branch (a link's own\n * branch is the session's base, checked out after boot), so that is the\n * branch a build pins; sessions let the provider resolve the same head.\n */\nexport async function resolveEnvironmentHeads(\n  sourceControl: EnvironmentBuildSourceControl,\n  project: Pick<FactoryProject, 'orgId'>,\n  environment: SessionEnvironment,\n): Promise<EnvironmentHeads> {\n  return resolveCurrentHeads(sourceControl, {\n    orgId: project.orgId,\n    repositories: environment.repos.map(repo => ({\n      id: repo.repositoryId,\n      slug: repo.slug,\n      branch: repo.templateBranch,\n    })),\n  });\n}\n\n/**\n * How long a build-start lease lasts without renewal. The run holding it\n * renews it every third of that while it works, so a lease lapses only when\n * its run died or stalled.\n */\nexport const BUILD_START_LEASE_MS = 10 * 60_000;\n\n/** Tries at recording a started build before the run leaves its lease to lapse. */\nconst RECORD_ATTEMPTS = 5;\n\n/**\n * Start a build for `projectId` when `trigger` calls for one. Every trigger\n * takes the project's build-start lease before reading build state and renews\n * it until the started build is recorded, so overlapping manual, scheduled and\n * push runs never both start a build, however long the provider takes; a run\n * that finds the lease held skips as `starting`. Every trigger skips while the\n * last build is still running; `schedule` and `push` also skip when the last\n * build is ready and neither a head nor any other template input changed;\n * `manual` otherwise always builds. A `push` that would build then takes the\n * leading-edge debounce claim, so only a push that starts a build opens the\n * window. Saving settings never builds.\n *\n * Taking over a lapsed lease leaves the start uncertain: the lapsed run may\n * have started a build it never recorded. The mark persists until resolved.\n * While it stands, a provider that lists builds is asked for a running one\n * (and every trigger skips as `in_progress` on it); with a provider that\n * cannot list, every trigger skips as `unresolved`.\n *\n * The result is written as the lease is released, and only while this run\n * still holds it. A failed `builds.start` clears the last build id, so a later\n * `schedule` or `push` cannot mistake the previous ready build for the current\n * template; any other error keeps a running build's id. A started build whose\n * recording keeps failing yields `failed` (`not_recorded`) with the lease left\n * to lapse rather than released, and a run that lost its lease while the\n * provider started yields `failed` (`superseded`); neither is polled or pinned.\n */\nexport async function runEnvironmentBuild(\n  deps: EnvironmentBuildDeps,\n  input: { projectId: string; trigger: EnvironmentBuildTrigger },\n): Promise<EnvironmentBuildOutcome> {\n  const builds = deps.sandbox?.builds;\n  if (!builds) return { outcome: 'unavailable', reason: 'no_builds' };\n  if (!deps.sourceControl) return { outcome: 'unavailable', reason: 'no_source_control' };\n  const sourceControl = deps.sourceControl;\n  const initial = await deps.projects.getById({ id: input.projectId });\n  if (!initial) return { outcome: 'skipped', reason: 'no_environment' };\n  const now = deps.now ?? (() => new Date());\n  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));\n\n  const pushDebounced = (project: FactoryProject, at: Date) =>\n    project.lastPushBuildAt !== null &&\n    at.getTime() - project.lastPushBuildAt.getTime() < project.buildPushDebounceMinutes * 60_000;\n  if (input.trigger === 'push' && pushDebounced(initial, now())) return { outcome: 'skipped', reason: 'debounced' };\n\n  const token = randomUUID();\n  const lease = { id: initial.id, token, leaseMs: BUILD_START_LEASE_MS };\n  const claim = await deps.projects.claimBuildStart({ ...lease, now: now() });\n  if (!claim.claimed) return { outcome: 'skipped', reason: 'starting' };\n  let held = true;\n  const renewal = setInterval(\n    () => {\n      deps.projects.renewBuildStart({ ...lease, now: now() }).then(\n        renewed => {\n          if (!renewed) held = false;\n        },\n        // A failed renewal is retried on the next tick; the lease outlasts two misses.\n        () => {},\n      );\n    },\n    deps.leaseRenewMs ?? BUILD_START_LEASE_MS / 3,\n  );\n  renewal.unref?.();\n\n  const attempted = { lastBuildAttemptedAt: now() };\n  // Set once this run has reconciled an uncertain start, or builds past it.\n  let resolved = false;\n  const release = (changes: Parameters<EnvironmentBuildDeps['projects']['releaseBuildStart']>[0]['changes'] = {}) =>\n    deps.projects.releaseBuildStart({ id: initial.id, token, changes, resolved, now: now() });\n  const failed = async (error: unknown, changes: Parameters<typeof release>[0]) => {\n    const reason = errorReason(error);\n    await release(changes);\n    deps.logger?.info('environment build failed', { factoryProjectId: initial.id, trigger: input.trigger, reason });\n    return { outcome: 'failed', reason } satisfies EnvironmentBuildOutcome;\n  };\n\n  try {\n    let project: FactoryProject;\n    let environment: SessionEnvironment;\n    let heads: EnvironmentHeads;\n    let ctx: FactorySandboxContext;\n    let buildInputs: string;\n    try {\n      // Read build state only once this run holds the lease, so a run that\n      // finished while this one waited has already recorded its build.\n      project = (await deps.projects.getById({ id: initial.id })) ?? initial;\n      environment = await resolveProjectEnvironment(sourceControl.storage, project);\n      if (environment.repos.length === 0) {\n        await release();\n        return { outcome: 'skipped', reason: 'no_environment' };\n      }\n      heads = await resolveEnvironmentHeads(sourceControl, project, environment);\n      ctx = environmentBuildContext(project, environment, heads, sourceControl.versionControl);\n      buildInputs = environmentBuildInputs(environment);\n\n      if (claim.uncertain) {\n        // A run whose lease lapsed may have reached the provider before it\n        // died; a build it left running is never raced by a second one. The\n        // mark stays until that build is gone, since its inputs are unknown.\n        if (builds.list) {\n          const listed = await builds.list(ctx, environment.settings);\n          const running = listed.find(build => build.status === 'pending' || build.status === 'building');\n          if (running) {\n            await release();\n            return { outcome: 'skipped', reason: 'in_progress', buildId: running.buildId };\n          }\n          resolved = true;\n        } else {\n          // Without history the earlier start can never be reconciled, so no\n          // trigger starts another build beside it.\n          await release();\n          return { outcome: 'skipped', reason: 'unresolved' };\n        }\n      }\n\n      if (project.lastBuildId) {\n        const last = await builds.get(ctx, environment.settings, project.lastBuildId);\n        // Two runs polling one template fight over it (each poll resubmits its\n        // own definition and the provider cancels the other), so a running\n        // build is never joined by a second one, whatever asked.\n        if (last.status === 'pending' || last.status === 'building') {\n          await release();\n          return { outcome: 'skipped', reason: 'in_progress', buildId: project.lastBuildId };\n        }\n        // A ready build whose poll ran out or died with its host was never\n        // pinned; pin it now so the skip below compares against what it built.\n        let pinnedHeads = project.activeTemplateHeads;\n        const lastTemplateId = last.templateId ?? project.lastBuildId;\n        if (last.status === 'ready' && project.lastBuildHeads && project.activeTemplateId !== lastTemplateId) {\n          const pinned = await deps.projects.pinActiveTemplate({\n            id: project.id,\n            buildId: project.lastBuildId,\n            templateId: lastTemplateId,\n            heads: project.lastBuildHeads,\n          });\n          if (pinned) pinnedHeads = project.lastBuildHeads;\n        }\n        if (\n          (input.trigger === 'schedule' || input.trigger === 'push') &&\n          last.status === 'ready' &&\n          !headsChanged(pinnedHeads, heads) &&\n          project.lastBuildInputs === buildInputs\n        ) {\n          await release();\n          return { outcome: 'skipped', reason: 'unchanged' };\n        }\n      }\n    } catch (error) {\n      return await failed(error, attempted);\n    }\n\n    // A run that lost its lease while reading must not start beside its successor.\n    if (!held) return { outcome: 'skipped', reason: 'starting' };\n\n    if (input.trigger === 'push') {\n      // Claimed only now, so a push that skipped above never closes the window.\n      let claimed: boolean;\n      try {\n        claimed = await deps.projects.claimBuildAttempt({\n          id: project.id,\n          debounceMinutes: project.buildPushDebounceMinutes,\n          now: now(),\n        });\n      } catch (error) {\n        return await failed(error, {});\n      }\n      if (!claimed) {\n        await release();\n        return { outcome: 'skipped', reason: 'debounced' };\n      }\n    }\n\n    let started: Awaited<ReturnType<typeof builds.start>>;\n    try {\n      started = await builds.start(ctx, environment.settings);\n    } catch (error) {\n      // Only a failed start clears the last build: the previous one no longer\n      // describes the template this project wants.\n      return await failed(error, { lastBuildId: null, lastBuildHeads: null, lastBuildInputs: null, ...attempted });\n    }\n\n    // The provider has started the build: from here on, no error clears it.\n    const log = { factoryProjectId: project.id, trigger: input.trigger, buildId: started.buildId };\n    const changes = { lastBuildId: started.buildId, lastBuildHeads: heads, lastBuildInputs: buildInputs, ...attempted };\n    let recorded: boolean | undefined;\n    for (let attempt = 1; recorded === undefined; attempt++) {\n      try {\n        recorded = await release(changes);\n      } catch (error) {\n        if (attempt >= RECORD_ATTEMPTS) {\n          // Keep the lease: it lapses once renewal stops, and the run that\n          // takes it over looks for this build at the provider first.\n          deps.logger?.info('environment build started but not recorded', { ...log, reason: errorReason(error) });\n          return { outcome: 'failed', reason: 'not_recorded', buildId: started.buildId };\n        }\n        await sleep(1000 * 2 ** (attempt - 1));\n      }\n    }\n    if (!recorded) {\n      // A newer run took the lease while the provider started this build; the\n      // project tracks that run's build, so this one is never polled or pinned.\n      deps.logger?.info('environment build superseded', log);\n      return { outcome: 'failed', reason: 'superseded', buildId: started.buildId };\n    }\n    try {\n      deps.logger?.info('environment build started', { ...log, templateId: started.templateId });\n    } catch {\n      // Logging never turns a recorded build into a failure.\n    }\n    return {\n      outcome: 'started',\n      buildId: started.buildId,\n      ...(started.templateId ? { templateId: started.templateId } : {}),\n      heads,\n    };\n  } finally {\n    clearInterval(renewal);\n  }\n}\n"],"mappings":"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"}

package/dist/environment/heads.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Which commit each environment repository pins to.
+ *
+ * The repo templates key `resolveHead` by clone URL; the factory records heads
+ * by repository slug. These helpers translate between the two and decide
+ * whether a set of current heads differs from the recorded one.
+ */
+import type { VersionControl } from '../capabilities/version-control.js';
+export type EnvironmentHeads = Record<string, string>;
+/** `owner/repo` from a clone URL in any common spelling, lower-cased, `.git` stripped; undefined when unparseable. */
+export declare function cloneUrlSlug(cloneUrl: string): string | undefined;
+/** The environment slug a clone URL names, in the environment's own spelling; undefined when none matches. */
+export declare function matchEnvironmentSlug(cloneUrl: string, slugs: Iterable<string>): string | undefined;
+/**
+ * A `resolveHead` that answers from recorded heads only: the template pins to
+ * what the last build used, so its identity moves when a build does. A URL
+ * outside the recorded set resolves undefined and the template falls back to
+ * its own lookup for that repository.
+ */
+export declare function recordedHeadResolver(heads: EnvironmentHeads): (cloneUrl: string) => Promise<string | undefined>;
+/** True when any repository's current head differs from the recorded one, or either side names a repository the other lacks. */
+export declare function headsChanged(recorded: EnvironmentHeads | null, current: EnvironmentHeads): boolean;
+export interface HeadRepository {
+    id: string;
+    slug: string;
+    /** The ref the environment pins: the link's branch, else the repository default. */
+    branch: string;
+}
+/** Current head of every repository's pinned ref, keyed by slug. Throws when any lookup fails. */
+export declare function resolveCurrentHeads(github: {
+    versionControl: Pick<VersionControl, 'getRepositoryAccess'>;
+}, input: {
+    orgId: string;
+    repositories: HeadRepository[];
+}): Promise<EnvironmentHeads>;
+//# sourceMappingURL=heads.d.ts.map

package/dist/environment/heads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heads.d.ts","sourceRoot":"","sources":["../../src/environment/heads.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGzE,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEtD,sHAAsH;AACtH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAkBjE;AAED,8GAA8G;AAC9G,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAOlG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM/G;AAED,gIAAgI;AAChI,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAMlG;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kGAAkG;AAClG,wBAAsB,mBAAmB,CACvC,MAAM,EAAE;IAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,qBAAqB,CAAC,CAAA;CAAE,EACvE,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,cAAc,EAAE,CAAA;CAAE,GACvD,OAAO,CAAC,gBAAgB,CAAC,CAU3B"}

package/dist/environment/heads.js

@@ -0,0 +1,60 @@
+import { getBranchHead } from "../integrations/github/commits.js";
+//#region src/environment/heads.ts
+/** `owner/repo` from a clone URL in any common spelling, lower-cased, `.git` stripped; undefined when unparseable. */
+function cloneUrlSlug(cloneUrl) {
+	let path;
+	const scp = /^[^@/]+@[^:/]+:(.+)$/.exec(cloneUrl.trim());
+	if (scp) path = scp[1];
+	else try {
+		path = new URL(cloneUrl.trim()).pathname;
+	} catch {
+		return;
+	}
+	const parts = path.replace(/\.git$/i, "").split("/").filter(Boolean);
+	if (parts.length < 2) return void 0;
+	return `${parts[parts.length - 2]}/${parts[parts.length - 1]}`.toLowerCase();
+}
+/** The environment slug a clone URL names, in the environment's own spelling; undefined when none matches. */
+function matchEnvironmentSlug(cloneUrl, slugs) {
+	const wanted = cloneUrlSlug(cloneUrl);
+	if (!wanted) return void 0;
+	for (const slug of slugs) if (slug.toLowerCase() === wanted) return slug;
+}
+/**
+* A `resolveHead` that answers from recorded heads only: the template pins to
+* what the last build used, so its identity moves when a build does. A URL
+* outside the recorded set resolves undefined and the template falls back to
+* its own lookup for that repository.
+*/
+function recordedHeadResolver(heads) {
+	const slugs = Object.keys(heads);
+	return async (cloneUrl) => {
+		const slug = matchEnvironmentSlug(cloneUrl, slugs);
+		return slug ? heads[slug] : void 0;
+	};
+}
+/** True when any repository's current head differs from the recorded one, or either side names a repository the other lacks. */
+function headsChanged(recorded, current) {
+	if (!recorded) return true;
+	const recordedKeys = Object.keys(recorded);
+	const currentKeys = Object.keys(current);
+	if (recordedKeys.length !== currentKeys.length) return true;
+	return currentKeys.some((slug) => recorded[slug] !== current[slug]);
+}
+/** Current head of every repository's pinned ref, keyed by slug. Throws when any lookup fails. */
+async function resolveCurrentHeads(github, input) {
+	const heads = {};
+	for (const repository of input.repositories) heads[repository.slug] = await getBranchHead(github, {
+		orgId: input.orgId,
+		repository: {
+			id: repository.id,
+			slug: repository.slug
+		},
+		branch: repository.branch
+	});
+	return heads;
+}
+//#endregion
+export { cloneUrlSlug, headsChanged, matchEnvironmentSlug, recordedHeadResolver, resolveCurrentHeads };
+
+//# sourceMappingURL=heads.js.map

package/dist/environment/heads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heads.js","names":[],"sources":["../../src/environment/heads.ts"],"sourcesContent":["/**\n * Which commit each environment repository pins to.\n *\n * The repo templates key `resolveHead` by clone URL; the factory records heads\n * by repository slug. These helpers translate between the two and decide\n * whether a set of current heads differs from the recorded one.\n */\n\nimport type { VersionControl } from '../capabilities/version-control.js';\nimport { getBranchHead } from '../integrations/github/commits.js';\n\nexport type EnvironmentHeads = Record<string, string>;\n\n/** `owner/repo` from a clone URL in any common spelling, lower-cased, `.git` stripped; undefined when unparseable. */\nexport function cloneUrlSlug(cloneUrl: string): string | undefined {\n  let path: string;\n  const scp = /^[^@/]+@[^:/]+:(.+)$/.exec(cloneUrl.trim());\n  if (scp) {\n    path = scp[1]!;\n  } else {\n    try {\n      path = new URL(cloneUrl.trim()).pathname;\n    } catch {\n      return undefined;\n    }\n  }\n  const parts = path\n    .replace(/\\.git$/i, '')\n    .split('/')\n    .filter(Boolean);\n  if (parts.length < 2) return undefined;\n  return `${parts[parts.length - 2]}/${parts[parts.length - 1]}`.toLowerCase();\n}\n\n/** The environment slug a clone URL names, in the environment's own spelling; undefined when none matches. */\nexport function matchEnvironmentSlug(cloneUrl: string, slugs: Iterable<string>): string | undefined {\n  const wanted = cloneUrlSlug(cloneUrl);\n  if (!wanted) return undefined;\n  for (const slug of slugs) {\n    if (slug.toLowerCase() === wanted) return slug;\n  }\n  return undefined;\n}\n\n/**\n * A `resolveHead` that answers from recorded heads only: the template pins to\n * what the last build used, so its identity moves when a build does. A URL\n * outside the recorded set resolves undefined and the template falls back to\n * its own lookup for that repository.\n */\nexport function recordedHeadResolver(heads: EnvironmentHeads): (cloneUrl: string) => Promise<string | undefined> {\n  const slugs = Object.keys(heads);\n  return async cloneUrl => {\n    const slug = matchEnvironmentSlug(cloneUrl, slugs);\n    return slug ? heads[slug] : undefined;\n  };\n}\n\n/** True when any repository's current head differs from the recorded one, or either side names a repository the other lacks. */\nexport function headsChanged(recorded: EnvironmentHeads | null, current: EnvironmentHeads): boolean {\n  if (!recorded) return true;\n  const recordedKeys = Object.keys(recorded);\n  const currentKeys = Object.keys(current);\n  if (recordedKeys.length !== currentKeys.length) return true;\n  return currentKeys.some(slug => recorded[slug] !== current[slug]);\n}\n\nexport interface HeadRepository {\n  id: string;\n  slug: string;\n  /** The ref the environment pins: the link's branch, else the repository default. */\n  branch: string;\n}\n\n/** Current head of every repository's pinned ref, keyed by slug. Throws when any lookup fails. */\nexport async function resolveCurrentHeads(\n  github: { versionControl: Pick<VersionControl, 'getRepositoryAccess'> },\n  input: { orgId: string; repositories: HeadRepository[] },\n): Promise<EnvironmentHeads> {\n  const heads: EnvironmentHeads = {};\n  for (const repository of input.repositories) {\n    heads[repository.slug] = await getBranchHead(github, {\n      orgId: input.orgId,\n      repository: { id: repository.id, slug: repository.slug },\n      branch: repository.branch,\n    });\n  }\n  return heads;\n}\n"],"mappings":";;;AAcA,SAAgB,aAAa,UAAsC;CACjE,IAAI;CACJ,MAAM,MAAM,uBAAuB,KAAK,SAAS,KAAK,CAAC;CACvD,IAAI,KACF,OAAO,IAAI;MAEX,IAAI;EACF,OAAO,IAAI,IAAI,SAAS,KAAK,CAAC,CAAC,CAAC;CAClC,QAAQ;EACN;CACF;CAEF,MAAM,QAAQ,KACX,QAAQ,WAAW,EAAE,CAAC,CACtB,MAAM,GAAG,CAAC,CACV,OAAO,OAAO;CACjB,IAAI,MAAM,SAAS,GAAG,OAAO,KAAA;CAC7B,OAAO,GAAG,MAAM,MAAM,SAAS,GAAG,GAAG,MAAM,MAAM,SAAS,KAAK,YAAY;AAC7E;;AAGA,SAAgB,qBAAqB,UAAkB,OAA6C;CAClG,MAAM,SAAS,aAAa,QAAQ;CACpC,IAAI,CAAC,QAAQ,OAAO,KAAA;CACpB,KAAK,MAAM,QAAQ,OACjB,IAAI,KAAK,YAAY,MAAM,QAAQ,OAAO;AAG9C;;;;;;;AAQA,SAAgB,qBAAqB,OAA4E;CAC/G,MAAM,QAAQ,OAAO,KAAK,KAAK;CAC/B,OAAO,OAAM,aAAY;EACvB,MAAM,OAAO,qBAAqB,UAAU,KAAK;EACjD,OAAO,OAAO,MAAM,QAAQ,KAAA;CAC9B;AACF;;AAGA,SAAgB,aAAa,UAAmC,SAAoC;CAClG,IAAI,CAAC,UAAU,OAAO;CACtB,MAAM,eAAe,OAAO,KAAK,QAAQ;CACzC,MAAM,cAAc,OAAO,KAAK,OAAO;CACvC,IAAI,aAAa,WAAW,YAAY,QAAQ,OAAO;CACvD,OAAO,YAAY,MAAK,SAAQ,SAAS,UAAU,QAAQ,KAAK;AAClE;;AAUA,eAAsB,oBACpB,QACA,OAC2B;CAC3B,MAAM,QAA0B,CAAC;CACjC,KAAK,MAAM,cAAc,MAAM,cAC7B,MAAM,WAAW,QAAQ,MAAM,cAAc,QAAQ;EACnD,OAAO,MAAM;EACb,YAAY;GAAE,IAAI,WAAW;GAAI,MAAM,WAAW;EAAK;EACvD,QAAQ,WAAW;CACrB,CAAC;CAEH,OAAO;AACT"}

package/dist/factory.d.ts

@@ -24,10 +24,11 @@ import type { Mastra } from '@mastra/core/mastra';
 import type { IMastraAuthProvider } from '@mastra/core/server';
 import type { FactoryStorage } from '@mastra/core/storage';
 import type { MastraVector } from '@mastra/core/vector';
+import type { FactorySandboxDescription } from '@mastra/core/workspace';
 import type { InstalledBoard } from './boards/index.js';
 import type { FactoryIntegration } from './integrations/base.js';
 import type { GithubRuleOverrides } from './integrations/github/default-rules.js';
-import type { MastraFactorySandboxConfig } from './sandbox/session-sandbox.js';
+import type { MastraFactorySandboxOption } from './sandbox/session-sandbox.js';
 import type { FactorySecretEncryption } from './secret-encryption.js';
 import type { FactorySandboxStart } from './workspace.js';
 /** Constructor args for the `new Mastra(...)` literal in the deploy entry. */
@@ -92,8 +93,15 @@ export interface MastraFactoryConfig {
      * static host, so credentialed requests must be explicitly allowed.
      */
     allowedOrigins?: string[];
-    /** Sandbox configuration. Omitted → repository sandboxes are disabled. */
-    sandbox?: MastraFactorySandboxConfig;
+    /**
+     * The host's sandbox: a FactorySandbox instance such as
+     * `new PlatformFactorySandbox({ ... })`, which owns the session sandbox
+     * constructor, the repo template and the schema of environment settings.
+     * A bare callback is also accepted and wrapped as a `provider: 'custom'`
+     * sandbox with no settings. Omitted → repository sandboxes are
+     * disabled.
+     */
+    sandbox?: MastraFactorySandboxOption;
     /**
      * When a session's sandbox boots: on the agent's first command (`'lazy'`,
      * the default) or as soon as the session's workspace is first resolved
@@ -172,7 +180,7 @@ export interface MastraFactoryConfig {
         };
     };
 }
-export type { MastraFactorySandboxConfig } from './sandbox/session-sandbox.js';
+export type { MastraFactorySandboxConfig, MastraFactorySandboxOption } from './sandbox/session-sandbox.js';
 export type { FactorySandboxStart } from './workspace.js';
 /**
  * Per-process cap on concurrent background Factory dispatches. Omitted means
@@ -185,6 +193,12 @@ export interface MastraFactoryDispatcherConfig {
 export declare class MastraFactory {
     #private;
     constructor(config: MastraFactoryConfig);
+    /**
+     * The host sandbox's provider, settings schema (JSON Schema) and
+     * capabilities, as the environment route reports them. Undefined before
+     * `prepare()` and when sandboxes are disabled.
+     */
+    get sandboxDescription(): FactorySandboxDescription | undefined;
     /**
      * Resolve feature readiness, wire every dependency explicitly, and assemble
      * everything needed to construct the server-owned Mastra. Returns the args

package/dist/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAGlD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAkB,yBAAyB,EAAoB,MAAM,wBAAwB,CAAC;AAY1G,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIvE,OAAO,KAAK,EAAE,kBAAkB,EAAgD,MAAM,wBAAwB,CAAC;AAE/G,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wCAAwC,CAAC;AAwClF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAE/E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAgDtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAI1D,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,qBAAqB,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAClC;;;;;;;OAOG;IACH,OAAO,EAAE,cAAc,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,SAAS,CAAA;KAAE,CAAC;IACjD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,0BAA0B,CAAC;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,mDAAmD;IACnD,UAAU,CAAC,EAAE,6BAA6B,CAAC;IAC3C;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C;;;;;;;;OAQG;IACH,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACpC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,gFAAgF;IAChF,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,EAAE;QACT,sGAAsG;QACtG,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB;;;;;;WAMG;QACH,MAAM,CAAC,EAAE;YACP,uFAAuF;YACvF,KAAK,CAAC,EAAE,mBAAmB,CAAC;YAC5B;;;eAGG;YACH,IAAI,CAAC,EAAE,MAAM,CAAC;SACf,CAAC;KACH,CAAC;CACH;AAED,YAAY,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC3G,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAgHD,qBAAa,aAAa;;gBAcZ,MAAM,EAAE,mBAAmB;IAsBvC;;;;OAIG;IACH,IAAI,kBAAkB,IAAI,yBAAyB,GAAG,SAAS,CAI9D;IAED;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;IAmtCpC;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAa/B,iFAAiF;IAC3E,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC"}

package/dist/factory.js

@@ -4,6 +4,16 @@ import { assertFactoryConfigVersion } from "./rules/validation.js";
 import { isTerminalWorkItem } from "./boards/semantics.js";
 import { createBoardRegistry } from "./boards/registry.js";
 import "./boards/index.js";
+import { isValidGitRef } from "./sandbox/git-ref.js";
+import { FactoryEnvironmentStateProcessor } from "./session/environment-state-processor.js";
+import { FactoryProjectsStorage } from "./storage/domains/projects/base.js";
+import { SourceControlStorage } from "./storage/domains/source-control/base.js";
+import { environmentSlugs, resolveSessionRepositories } from "./session/environment-repositories.js";
+import { createSourceControlSessionLookup } from "./session/factory-session.js";
+import { hydrateSupervisorSession, parseSupervisorResourceId, resolveSupervisorScope } from "./supervisor/session.js";
+import { FactoryWorkspaceRegistry, createWorkspaceFactory } from "./workspace.js";
+import { ENVIRONMENT_BUILD_WORKFLOW_ID } from "./environment/build-workflow.js";
+import { EnvironmentBuildRunner } from "./environment/build-runner.js";
 import { touchFeed } from "./feed-events.js";
 import { reconcileGithubAcceptanceLabels } from "./integrations/github/acceptance-labels.js";
 import { WorkItemsStorage } from "./storage/domains/work-items/base.js";
@@ -15,7 +25,6 @@ import { PlatformApiClient, platformApiClientConfigFromEnv } from "./integration
 import { buildPlatformConnectRoutes } from "./integrations/platform/connect/routes.js";
 import { observeSessionFirstExec } from "./session/first-exec-capture.js";
 import { observeSessionFilesystem } from "./session/filesystem-capture.js";
-import { isValidGitRef } from "./sandbox/git-ref.js";
 import { createPlaintextFactorySecretEncryption } from "./secret-encryption.js";
 import { ModelCredentialsStorage } from "./storage/domains/credentials/base.js";
 import { createTenantCredentialPrimer, primeTenantCredentials, registerTenantCredentialResolver } from "./routes/tenant-credentials.js";
@@ -29,15 +38,10 @@ import { hydrateSessionMemorySettings, layerPersonalMemorySettings } from "./ses
 import { MemorySettingsStorage, factoryMemorySettingsUserId } from "./storage/domains/memory-settings/base.js";
 import { resolveDeploymentModelProviders } from "./routes/config.js";
 import { createCustomProvidersPrimer, registerCustomProvidersSource } from "./routes/custom-provider-source.js";
-import { FactoryProjectsStorage } from "./storage/domains/projects/base.js";
 import { ProjectRoutes } from "./routes/projects.js";
-import { SourceControlStorage } from "./storage/domains/source-control/base.js";
-import { createSourceControlSessionLookup } from "./session/factory-session.js";
 import { FactoryTransitionService } from "./rules/transition-service.js";
 import { AuditStorage } from "./storage/domains/audit/base.js";
 import { AuditDomain } from "./storage/domains/audit/domain.js";
-import { hydrateSupervisorSession, parseSupervisorResourceId, resolveSupervisorScope } from "./supervisor/session.js";
-import { FactoryWorkspaceRegistry, createWorkspaceFactory } from "./workspace.js";
 import { QueueHealthStorage } from "./storage/domains/queue-health/base.js";
 import { assembleFactoryApiRoutes, buildIntegrationContext } from "./routes/surface.js";
 import { TelemetryRoutes } from "./routes/telemetry.js";
@@ -49,6 +53,7 @@ import { FactoryPhaseStateProcessor, reportMemorySettingsUnavailable } from "./r
 import { createReviewSourceTool, resolveReviewSourceUiOrigin } from "./rules/review-source-tool.js";
 import { createTerminalStageCleanup } from "./rules/terminal-cleanup.js";
 import { createFactoryTransitionTools } from "./rules/tools.js";
+import { CallbackFactorySandbox } from "./sandbox/callback-factory-sandbox.js";
 import { SessionRetirementCoordinator } from "./sandbox/session-retirement.js";
 import { handleServerError } from "./server-error.js";
 import { hydrateSessionDefaultModel } from "./session/default-model-hydration.js";
@@ -76,6 +81,7 @@ import { MastraAuthStudio } from "@mastra/auth-studio";
 import { prepareAgentControllerMount } from "@mastra/code-sdk";
 import { AgentControllerChannels } from "@mastra/core/channels";
 import { EventEmitterPubSub } from "@mastra/core/events";
+import { describeFactorySandbox, isFactorySandbox } from "@mastra/core/workspace";
 //#region src/factory.ts
 /**
 * `MastraFactory` — the single entry point to the whole Mastra Software Factory.
@@ -163,13 +169,43 @@ function liveSessionsTouchingTheFeed(controller, eventBus) {
 	});
 	return liveSessions;
 }
+/**
+* The fleet-era `sandbox` options and what replaced each one. Only the keys
+* the host actually passed are explained, so a host that never used the fleet
+* gets the short message.
+*/
+const RETIRED_SANDBOX_OPTIONS = {
+	machine: "'machine' becomes the provider instance: one sandbox per session, constructed by the FactorySandbox, instead of one template machine cloned per repository",
+	workdir: "'workdir' becomes the workingDirectory of the FactorySandboxContext, which every provider passes to its sandbox; when it is absent the provider uses its own default",
+	maxSandboxes: "'maxSandboxes' is gone with the sandbox fleet: there is one sandbox per session and no pool to cap"
+};
+function invalidSandboxOptionMessage(option) {
+	const lines = [
+		`MastraFactory: 'sandbox' must be a FactorySandbox instance or a callback constructing a MastraSandbox from a FactorySandboxContext:`,
+		`  sandbox: new PlatformFactorySandbox()`,
+		`  sandbox: ctx => new PlatformSandbox({ id: ctx.sessionId, sandboxId: ctx.sandboxId })`
+	];
+	if (typeof option === "object" && option !== null) {
+		const retired = Object.keys(RETIRED_SANDBOX_OPTIONS).filter((key) => key in option);
+		if (retired.length > 0) {
+			lines.push(`The object you passed is the retired alpha sandbox config. Its options map as follows:`);
+			for (const key of retired) lines.push(`  ${RETIRED_SANDBOX_OPTIONS[key]}.`);
+		}
+	}
+	return lines.join("\n");
+}
 var MastraFactory = class {
 	#config;
+	/** The normalized sandbox, set by `prepare()`. Undefined until then and when sandboxes are disabled. */
+	#sandbox;
+	#sandboxDescription;
 	#boards;
 	#configVersion;
 	#prepared;
 	#dispatcher;
 	#factoryProcessor;
+	/** Environment builds through the sandbox's `builds`; undefined when the sandbox has none. */
+	#environmentBuilds;
 	#preparing = false;
 	constructor(config) {
 		if (!config?.storage) throw new Error("MastraFactory: 'storage' is required. Pass a FactoryStorage backend — e.g. new PgFactoryStorage({ connectionString }) from '@mastra/pg' for deployments, or new LibSQLFactoryStorage({ url }) from '@mastra/libsql' for local dev.");
@@ -182,6 +218,16 @@ var MastraFactory = class {
 		this.#config = config;
 	}
 	/**
+	* The host sandbox's provider, settings schema (JSON Schema) and
+	* capabilities, as the environment route reports them. Undefined before
+	* `prepare()` and when sandboxes are disabled.
+	*/
+	get sandboxDescription() {
+		if (!this.#sandbox) return void 0;
+		this.#sandboxDescription ??= describeFactorySandbox(this.#sandbox);
+		return this.#sandboxDescription;
+	}
+	/**
 	* Resolve feature readiness, wire every dependency explicitly, and assemble
 	* everything needed to construct the server-owned Mastra. Returns the args
 	* for the `new Mastra(...)` literal that must live in the entry file.
@@ -278,11 +324,12 @@ var MastraFactory = class {
 			publishers: feedPublishers,
 			pubsub: eventBus
 		});
-		const sandboxConfig = this.#config.sandbox;
-		if (sandboxConfig !== void 0 && typeof sandboxConfig !== "function") {
-			if (typeof sandboxConfig === "object" && sandboxConfig !== null) throw new Error("MastraFactory: 'sandbox' is now a callback, not an options object. It receives a FactorySandboxContext and returns a MastraSandbox, so the host chooses the provider per session:\n  sandbox: ctx => new E2BSandbox({ id: ctx.sessionId, sandboxId: ctx.sandboxId })\nThe old options map three ways: 'machine' becomes the provider instance you construct inside the callback (one per session instead of one cloned template); 'workdir' is gone — remote providers clone into the VM's home directory and local providers check out under their own workingDirectory; 'maxSandboxes' is gone with the sandbox fleet — there is one sandbox per session and no pool to cap. Omit 'sandbox' entirely to disable sandboxes.");
-			throw new Error(`MastraFactory: 'sandbox' must be a function constructing a MastraSandbox from a FactorySandboxContext.`);
-		}
+		const sandboxOption = this.#config.sandbox;
+		let sandboxConfig;
+		if (sandboxOption === void 0 || isFactorySandbox(sandboxOption)) sandboxConfig = sandboxOption;
+		else if (typeof sandboxOption === "function") sandboxConfig = new CallbackFactorySandbox(sandboxOption);
+		else throw new Error(invalidSandboxOptionMessage(sandboxOption));
+		this.#sandbox = sandboxConfig;
 		const workspaceRegistry = new FactoryWorkspaceRegistry();
 		const stateSigner = createStateSigner(this.#config.stateSecret);
 		if (auth && hasAuthInit(auth)) await timedPhase("prepare.auth.init", () => auth.init({
@@ -383,8 +430,20 @@ var MastraFactory = class {
 			...onTerminalStage ? { onTerminalStage } : {},
 			...githubIntegration ? { onAccepted: (args) => reconcileGithubAcceptanceLabels(githubIntegration, sourceControlStorage.forIntegration(githubIntegration.id), args) } : {}
 		}) : void 0;
+		this.#environmentBuilds = this.#sandbox?.builds ? new EnvironmentBuildRunner({
+			sandbox: this.#sandbox,
+			projects: factoryProjectsStorage,
+			sourceControl: githubIntegration?.versionControl ? {
+				storage: sourceControlStorage.forIntegration(githubIntegration.id),
+				versionControl: githubIntegration.versionControl
+			} : void 0,
+			logger: { info: (msg, meta) => console.info(`[Mastra Factory] ${msg}`, meta ?? {}) }
+		}, { getMastra: () => this.#prepared?.base.controller.getMastra() }) : void 0;
+		const environmentBuilds = this.#environmentBuilds;
 		const projectRoutes = new ProjectRoutes({
 			auth: routeAuth,
+			sandbox: this.#sandbox,
+			...environmentBuilds ? { environmentBuilds } : {},
 			projects: factoryProjectsStorage,
 			sourceControl: sourceControlStorage,
 			versionControlIntegrationIds: integrations.filter((integration) => integration.versionControl).map((integration) => integration.id),
@@ -557,9 +616,10 @@ var MastraFactory = class {
 			...mastraStorageBackend ? { storageBackend: mastraStorageBackend } : {},
 			...this.#config.knowledge ? { knowledge: this.#config.knowledge } : {},
 			inputProcessors: async ({ requestContext }) => {
+				const environmentProcessor = new FactoryEnvironmentStateProcessor();
 				if (factoryProcessor) {
 					await factoryProcessor.prepareMemorySettings(requestContext);
-					return [factoryProcessor];
+					return [environmentProcessor, factoryProcessor];
 				}
 				try {
 					await loadMemorySettings({
@@ -569,7 +629,7 @@ var MastraFactory = class {
 				} catch (error) {
 					reportMemorySettingsUnavailable(requestContext, error instanceof Error ? error.message : String(error));
 				}
-				return [];
+				return [environmentProcessor];
 			},
 			...vector ? { vector } : {},
 			...toolIntegrations.length > 0 || sourceControlToolProviders.length > 0 || workItemsStorage && transitionService ? { extraTools: async ({ requestContext }) => {
@@ -583,7 +643,7 @@ var MastraFactory = class {
 						tools[name] = tool;
 					}
 				};
-				if (storage.isDomainReady("source-control")) mergeTools("source-control", createSourceControlTools({
+				if (storage.isDomainReady("source-control")) mergeTools("source-control", await createSourceControlTools({
 					requestContext,
 					providers: sourceControlToolProviders,
 					audit: auditDomain
@@ -659,6 +719,17 @@ var MastraFactory = class {
 					toolContext: {
 						...toolContext,
 						context: requestContext
+					},
+					resolveRepositorySlugs: async (sessionId) => {
+						for (const provider of sourceControlToolProviders) {
+							const session = await provider.storage.sessions.getBySessionId(sessionId);
+							if (!session) continue;
+							return environmentSlugs(await resolveSessionRepositories({
+								sourceControl: provider.storage,
+								session
+							}));
+						}
+						return [];
 					}
 				});
 				await Promise.all(integrations.map(async (integration) => {
@@ -696,6 +767,7 @@ var MastraFactory = class {
 					publicOrigin,
 					stateSigner,
 					sandbox: sandboxConfig,
+					...environmentBuilds ? { onRepositoryPush: environmentBuilds.onRepositoryPush } : {},
 					sessionRetirement,
 					factoryStorage: storage,
 					integrationStorage,
@@ -896,7 +968,8 @@ var MastraFactory = class {
 		return {
 			...prepared.mastraArgs,
 			...auth ? { studio: { auth } } : {},
-			...integrationWorkers.length > 0 ? { workers: integrationWorkers } : {}
+			...integrationWorkers.length > 0 ? { workers: integrationWorkers } : {},
+			...environmentBuilds ? { workflows: { [ENVIRONMENT_BUILD_WORKFLOW_ID]: environmentBuilds.workflow } } : {}
 		};
 	}
 	/**
@@ -907,6 +980,7 @@ var MastraFactory = class {
 	async finalize() {
 		if (!this.#prepared) throw new Error("MastraFactory.finalize() called before prepare()");
 		await timedPhase("finalize.controller", () => this.#prepared.finalize());
+		await this.#environmentBuilds?.probeSchedules();
 		await timedPhase("finalize.reconcileBoundThreads", () => this.#factoryProcessor?.reconcileAllBoundThreads() ?? Promise.resolve());
 		this.#dispatcher?.start();
 	}