@mastra/factory 0.0.0-aggregate-trace-20261015182851

package/dist/environment/build-schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-schedule.js","names":[],"sources":["../../src/environment/build-schedule.ts"],"sourcesContent":["/**\n * The per-project cron that fires the `factory-environment-build` workflow,\n * kept in core `Schedules` (one row per project) rather than a factory\n * column: the scheduler owns firing, claims and the run trigger log, factory\n * only creates, pauses, resumes and reads the row.\n */\n\nimport type { AnySchedule, Schedules, WorkflowSchedule } from '@mastra/core/schedules';\nimport { validateCron } from '@mastra/core/workflows';\nimport { ENVIRONMENT_BUILD_WORKFLOW_ID } from './build-workflow.js';\n\nexport const SCHEDULES_UNAVAILABLE_ERROR_ID = 'SCHEDULES_NO_SCHEDULES_STORAGE';\n\n/**\n * The project's schedule id in its stored form. Core normalizes a created\n * id to `schedule_<slug>` and resolves a bare id to `agent_<slug>` on reads,\n * so factory always addresses the row by the normalized id (a project id is\n * a lower-case uuid, which slugifies to itself).\n */\nexport function scheduleIdFor(projectId: string): string {\n  return `schedule_factory-environment-build-${projectId}`;\n}\n\nexport interface EnvironmentBuildSchedule {\n  enabled: boolean;\n  cron: string | null;\n  timezone: string | null;\n}\n\nexport type ScheduleService = Pick<Schedules, 'create' | 'get' | 'list' | 'update' | 'pause' | 'resume' | 'delete'>;\n\nfunction isSchedulesUnavailable(error: unknown): boolean {\n  return (\n    typeof error === 'object' && error !== null && (error as { id?: unknown }).id === SCHEDULES_UNAVAILABLE_ERROR_ID\n  );\n}\n\n/**\n * Whether the host's storage implements the schedules domain. `mastra.schedules`\n * never throws on access; the missing store surfaces on the first call.\n */\nexport async function probeSchedulesAvailable(schedules: ScheduleService): Promise<boolean> {\n  try {\n    await schedules.list({ workflowId: ENVIRONMENT_BUILD_WORKFLOW_ID });\n    return true;\n  } catch (error) {\n    if (isSchedulesUnavailable(error)) return false;\n    throw error;\n  }\n}\n\n/** `undefined` when the cron parses; otherwise the validator's message. */\nexport function invalidCronMessage(cron: string, timezone?: string): string | undefined {\n  try {\n    validateCron(cron, timezone);\n    return undefined;\n  } catch (error) {\n    return error instanceof Error ? error.message : String(error);\n  }\n}\n\nfunction isWorkflowSchedule(schedule: AnySchedule | null): schedule is WorkflowSchedule {\n  return schedule !== null && schedule.agentId === undefined;\n}\n\nfunction toView(schedule: WorkflowSchedule | null): EnvironmentBuildSchedule {\n  if (!schedule) return { enabled: false, cron: null, timezone: null };\n  return { enabled: schedule.status === 'active', cron: schedule.cron, timezone: schedule.timezone ?? null };\n}\n\n/** The project's build schedule as the environment reports it. */\nexport async function readSchedule(schedules: ScheduleService, projectId: string): Promise<EnvironmentBuildSchedule> {\n  const schedule = await schedules.get(scheduleIdFor(projectId));\n  return toView(isWorkflowSchedule(schedule) ? schedule : null);\n}\n\n/**\n * Create, update, pause or resume the project's schedule so it matches\n * `input`. Disabling a project that never had a schedule creates nothing.\n */\nexport async function ensureSchedule(\n  schedules: ScheduleService,\n  projectId: string,\n  input: { enabled: boolean; cron: string; timezone?: string },\n): Promise<EnvironmentBuildSchedule> {\n  const id = scheduleIdFor(projectId);\n  const existing = await schedules.get(id);\n  const current = isWorkflowSchedule(existing) ? existing : null;\n  if (!current) {\n    if (!input.enabled) return toView(null);\n    const created = await schedules.create({\n      id,\n      workflowId: ENVIRONMENT_BUILD_WORKFLOW_ID,\n      cron: input.cron,\n      ...(input.timezone ? { timezone: input.timezone } : {}),\n      inputData: { projectId, trigger: 'schedule' },\n      resourceId: projectId,\n    });\n    return toView(created);\n  }\n  const timingChanged = current.cron !== input.cron || (current.timezone ?? undefined) !== input.timezone;\n  let next: AnySchedule = current;\n  if (timingChanged) {\n    next = await schedules.update(current.id, {\n      cron: input.cron,\n      ...(input.timezone ? { timezone: input.timezone } : {}),\n    });\n  }\n  if (input.enabled && next.status === 'paused') next = await schedules.resume(current.id);\n  if (!input.enabled && next.status === 'active') next = await schedules.pause(current.id);\n  return toView(isWorkflowSchedule(next) ? next : null);\n}\n"],"mappings":";;;AAWA,MAAa,iCAAiC;;;;;;;AAQ9C,SAAgB,cAAc,WAA2B;CACvD,OAAO,sCAAsC;AAC/C;AAUA,SAAS,uBAAuB,OAAyB;CACvD,OACE,OAAO,UAAU,YAAY,UAAU,QAAS,MAA2B,OAAA;AAE/E;;;;;AAMA,eAAsB,wBAAwB,WAA8C;CAC1F,IAAI;EACF,MAAM,UAAU,KAAK,EAAE,YAAY,8BAA8B,CAAC;EAClE,OAAO;CACT,SAAS,OAAO;EACd,IAAI,uBAAuB,KAAK,GAAG,OAAO;EAC1C,MAAM;CACR;AACF;;AAGA,SAAgB,mBAAmB,MAAc,UAAuC;CACtF,IAAI;EACF,aAAa,MAAM,QAAQ;EAC3B;CACF,SAAS,OAAO;EACd,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;CAC9D;AACF;AAEA,SAAS,mBAAmB,UAA4D;CACtF,OAAO,aAAa,QAAQ,SAAS,YAAY,KAAA;AACnD;AAEA,SAAS,OAAO,UAA6D;CAC3E,IAAI,CAAC,UAAU,OAAO;EAAE,SAAS;EAAO,MAAM;EAAM,UAAU;CAAK;CACnE,OAAO;EAAE,SAAS,SAAS,WAAW;EAAU,MAAM,SAAS;EAAM,UAAU,SAAS,YAAY;CAAK;AAC3G;;AAGA,eAAsB,aAAa,WAA4B,WAAsD;CACnH,MAAM,WAAW,MAAM,UAAU,IAAI,cAAc,SAAS,CAAC;CAC7D,OAAO,OAAO,mBAAmB,QAAQ,IAAI,WAAW,IAAI;AAC9D;;;;;AAMA,eAAsB,eACpB,WACA,WACA,OACmC;CACnC,MAAM,KAAK,cAAc,SAAS;CAClC,MAAM,WAAW,MAAM,UAAU,IAAI,EAAE;CACvC,MAAM,UAAU,mBAAmB,QAAQ,IAAI,WAAW;CAC1D,IAAI,CAAC,SAAS;EACZ,IAAI,CAAC,MAAM,SAAS,OAAO,OAAO,IAAI;EAStC,OAAO,OAAO,MARQ,UAAU,OAAO;GACrC;GACA,YAAY;GACZ,MAAM,MAAM;GACZ,GAAI,MAAM,WAAW,EAAE,UAAU,MAAM,SAAS,IAAI,CAAC;GACrD,WAAW;IAAE;IAAW,SAAS;GAAW;GAC5C,YAAY;EACd,CAAC,CACoB;CACvB;CACA,MAAM,gBAAgB,QAAQ,SAAS,MAAM,SAAS,QAAQ,YAAY,KAAA,OAAe,MAAM;CAC/F,IAAI,OAAoB;CACxB,IAAI,eACF,OAAO,MAAM,UAAU,OAAO,QAAQ,IAAI;EACxC,MAAM,MAAM;EACZ,GAAI,MAAM,WAAW,EAAE,UAAU,MAAM,SAAS,IAAI,CAAC;CACvD,CAAC;CAEH,IAAI,MAAM,WAAW,KAAK,WAAW,UAAU,OAAO,MAAM,UAAU,OAAO,QAAQ,EAAE;CACvF,IAAI,CAAC,MAAM,WAAW,KAAK,WAAW,UAAU,OAAO,MAAM,UAAU,MAAM,QAAQ,EAAE;CACvF,OAAO,OAAO,mBAAmB,IAAI,IAAI,OAAO,IAAI;AACtD"}

package/dist/environment/build-workflow.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The `factory-environment-build` workflow: step one decides and starts a
+ * build (`runEnvironmentBuild`), step two polls the provider until the build
+ * settles and pins the active template on the project row. Registered by
+ * `MastraFactory.prepare()` only when the sandbox has `builds`, and driven by
+ * the Build now route, the per-project cron schedule and the GitHub push
+ * hand-off. Saving settings never starts it.
+ */
+import { z } from 'zod';
+import type { EnvironmentBuildDeps, EnvironmentBuildOutcome } from './build.js';
+export declare const ENVIRONMENT_BUILD_WORKFLOW_ID = "factory-environment-build";
+export declare const DEFAULT_BUILD_POLL_MS = 15000;
+export declare const MAX_BUILD_WAIT_MS: number;
+export declare const environmentBuildInputSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    trigger: z.ZodEnum<{
+        manual: "manual";
+        push: "push";
+        schedule: "schedule";
+    }>;
+}, z.core.$strip>;
+export declare const environmentBuildOutputSchema: z.ZodObject<{
+    outcome: z.ZodEnum<{
+        started: "started";
+        failed: "failed";
+        skipped: "skipped";
+        unavailable: "unavailable";
+    }>;
+    buildId: z.ZodOptional<z.ZodString>;
+    templateId: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        failed: "failed";
+        ready: "ready";
+    }>>;
+}, z.core.$strip>;
+export type EnvironmentBuildWorkflowResult = z.infer<typeof environmentBuildOutputSchema>;
+export interface EnvironmentBuildWorkflowOptions {
+    sleep?: (ms: number) => Promise<void>;
+    pollMs?: number;
+    maxWaitMs?: number;
+    /** Called with the first step's answer so a caller can return it without waiting for the poll. */
+    onStart?: (runId: string, outcome: EnvironmentBuildOutcome) => void;
+}
+export declare function createEnvironmentBuildWorkflow(deps: EnvironmentBuildDeps, options?: EnvironmentBuildWorkflowOptions): import("@mastra/core/workflows").Workflow<import("@mastra/core/workflows").DefaultEngineType, import("@mastra/core/workflows").Step<string, unknown, unknown, unknown, unknown, unknown, any, unknown>[], "factory-environment-build", unknown, {
+    projectId: string;
+    trigger: "manual" | "push" | "schedule";
+}, {
+    outcome: "started" | "failed" | "skipped" | "unavailable";
+    buildId?: string | undefined;
+    templateId?: string | undefined;
+    reason?: string | undefined;
+    status?: "unknown" | "failed" | "ready" | undefined;
+}, {
+    outcome: "started" | "failed" | "skipped" | "unavailable";
+    buildId?: string | undefined;
+    templateId?: string | undefined;
+    reason?: string | undefined;
+    status?: "unknown" | "failed" | "ready" | undefined;
+}, unknown>;
+//# sourceMappingURL=build-workflow.d.ts.map

package/dist/environment/build-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-workflow.d.ts","sourceRoot":"","sources":["../../src/environment/build-workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEhF,eAAO,MAAM,6BAA6B,8BAA8B,CAAC;AACzE,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAC5C,eAAO,MAAM,iBAAiB,QAAc,CAAC;AAE7C,eAAO,MAAM,2BAA2B;;;;;;;iBAGtC,CAAC;AAWH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;iBAOvC,CAAC;AAEH,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAE1F,MAAM,WAAW,+BAA+B;IAC9C,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kGAAkG;IAClG,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAC;CACrE;AAED,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,+BAAoC;;;;;;;;;;;;;;;YAoF9C"}

package/dist/environment/build-workflow.js

@@ -0,0 +1,149 @@
+import { ENVIRONMENT_BUILD_TRIGGERS, environmentBuildContext, errorReason, redactCredentials, runEnvironmentBuild } from "./build.js";
+import { resolveProjectEnvironment } from "../workspace.js";
+import { createStep, createWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
+//#region src/environment/build-workflow.ts
+/**
+* The `factory-environment-build` workflow: step one decides and starts a
+* build (`runEnvironmentBuild`), step two polls the provider until the build
+* settles and pins the active template on the project row. Registered by
+* `MastraFactory.prepare()` only when the sandbox has `builds`, and driven by
+* the Build now route, the per-project cron schedule and the GitHub push
+* hand-off. Saving settings never starts it.
+*/
+const ENVIRONMENT_BUILD_WORKFLOW_ID = "factory-environment-build";
+const DEFAULT_BUILD_POLL_MS = 15e3;
+const MAX_BUILD_WAIT_MS = 30 * 6e4;
+const environmentBuildInputSchema = z.object({
+	projectId: z.string().min(1),
+	trigger: z.enum(ENVIRONMENT_BUILD_TRIGGERS)
+});
+const startOutputSchema = z.object({
+	projectId: z.string(),
+	outcome: z.enum([
+		"started",
+		"skipped",
+		"unavailable",
+		"failed"
+	]),
+	buildId: z.string().optional(),
+	templateId: z.string().optional(),
+	reason: z.string().optional(),
+	heads: z.record(z.string(), z.string()).optional()
+});
+const environmentBuildOutputSchema = z.object({
+	outcome: z.enum([
+		"started",
+		"skipped",
+		"unavailable",
+		"failed"
+	]),
+	buildId: z.string().optional(),
+	templateId: z.string().optional(),
+	reason: z.string().optional(),
+	/** Where the started build ended: `ready`, `failed`, or `unknown` when the provider lost it or the wait ran out. */
+	status: z.enum([
+		"ready",
+		"failed",
+		"unknown"
+	]).optional()
+});
+function createEnvironmentBuildWorkflow(deps, options = {}) {
+	const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	const pollMs = options.pollMs ?? 15e3;
+	const maxWaitMs = options.maxWaitMs ?? 18e5;
+	const now = deps.now ?? (() => /* @__PURE__ */ new Date());
+	const start = createStep({
+		id: "start",
+		inputSchema: environmentBuildInputSchema,
+		outputSchema: startOutputSchema,
+		execute: async ({ inputData, runId }) => {
+			const outcome = await runEnvironmentBuild(deps, inputData);
+			options.onStart?.(runId, outcome);
+			return {
+				projectId: inputData.projectId,
+				...outcome
+			};
+		}
+	});
+	const awaitBuild = createStep({
+		id: "await-build",
+		inputSchema: startOutputSchema,
+		outputSchema: environmentBuildOutputSchema,
+		execute: async ({ inputData }) => {
+			const { projectId, heads, ...result } = inputData;
+			if (result.outcome !== "started" || !result.buildId || !heads) return result;
+			const builds = deps.sandbox?.builds;
+			const project = await deps.projects.getById({ id: projectId });
+			if (!builds || !deps.sourceControl || !project) return {
+				...result,
+				status: "unknown"
+			};
+			const environment = await resolveProjectEnvironment(deps.sourceControl.storage, project);
+			const ctx = environmentBuildContext(project, environment, heads, deps.sourceControl.versionControl);
+			const startedAt = now().getTime();
+			try {
+				for (;;) {
+					const build = await builds.get(ctx, environment.settings, result.buildId);
+					if (build.status === "ready") {
+						const templateId = build.templateId ?? result.templateId ?? result.buildId;
+						const pinned = await deps.projects.pinActiveTemplate({
+							id: project.id,
+							buildId: result.buildId,
+							templateId,
+							heads
+						});
+						deps.logger?.info(pinned ? "environment build ready" : "environment build ready but superseded", {
+							factoryProjectId: project.id,
+							templateId
+						});
+						return {
+							...result,
+							templateId,
+							status: "ready"
+						};
+					}
+					if (build.status === "failed" || build.status === "unknown") {
+						deps.logger?.info("environment build did not complete", {
+							factoryProjectId: project.id,
+							buildId: result.buildId,
+							status: build.status,
+							...build.error ? { reason: redactCredentials(build.error) } : {}
+						});
+						return {
+							...result,
+							status: build.status,
+							...build.error ? { reason: redactCredentials(build.error) } : {}
+						};
+					}
+					if (now().getTime() - startedAt >= maxWaitMs) return {
+						...result,
+						status: "unknown",
+						reason: "Build wait timed out."
+					};
+					await sleep(pollMs);
+				}
+			} catch (error) {
+				const reason = errorReason(error);
+				deps.logger?.info("environment build status read failed", {
+					factoryProjectId: project.id,
+					reason
+				});
+				return {
+					...result,
+					status: "unknown",
+					reason
+				};
+			}
+		}
+	});
+	return createWorkflow({
+		id: ENVIRONMENT_BUILD_WORKFLOW_ID,
+		inputSchema: environmentBuildInputSchema,
+		outputSchema: environmentBuildOutputSchema
+	}).then(start).then(awaitBuild).commit();
+}
+//#endregion
+export { DEFAULT_BUILD_POLL_MS, ENVIRONMENT_BUILD_WORKFLOW_ID, MAX_BUILD_WAIT_MS, createEnvironmentBuildWorkflow, environmentBuildInputSchema, environmentBuildOutputSchema };
+
+//# sourceMappingURL=build-workflow.js.map

package/dist/environment/build-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-workflow.js","names":[],"sources":["../../src/environment/build-workflow.ts"],"sourcesContent":["/**\n * The `factory-environment-build` workflow: step one decides and starts a\n * build (`runEnvironmentBuild`), step two polls the provider until the build\n * settles and pins the active template on the project row. Registered by\n * `MastraFactory.prepare()` only when the sandbox has `builds`, and driven by\n * the Build now route, the per-project cron schedule and the GitHub push\n * hand-off. Saving settings never starts it.\n */\n\nimport { createStep, createWorkflow } from '@mastra/core/workflows';\nimport { z } from 'zod';\nimport { resolveProjectEnvironment } from '../workspace.js';\nimport {\n  ENVIRONMENT_BUILD_TRIGGERS,\n  environmentBuildContext,\n  errorReason,\n  redactCredentials,\n  runEnvironmentBuild,\n} from './build.js';\nimport type { EnvironmentBuildDeps, EnvironmentBuildOutcome } from './build.js';\n\nexport const ENVIRONMENT_BUILD_WORKFLOW_ID = 'factory-environment-build';\nexport const DEFAULT_BUILD_POLL_MS = 15_000;\nexport const MAX_BUILD_WAIT_MS = 30 * 60_000;\n\nexport const environmentBuildInputSchema = z.object({\n  projectId: z.string().min(1),\n  trigger: z.enum(ENVIRONMENT_BUILD_TRIGGERS),\n});\n\nconst startOutputSchema = z.object({\n  projectId: z.string(),\n  outcome: z.enum(['started', 'skipped', 'unavailable', 'failed']),\n  buildId: z.string().optional(),\n  templateId: z.string().optional(),\n  reason: z.string().optional(),\n  heads: z.record(z.string(), z.string()).optional(),\n});\n\nexport const environmentBuildOutputSchema = z.object({\n  outcome: z.enum(['started', 'skipped', 'unavailable', 'failed']),\n  buildId: z.string().optional(),\n  templateId: z.string().optional(),\n  reason: z.string().optional(),\n  /** Where the started build ended: `ready`, `failed`, or `unknown` when the provider lost it or the wait ran out. */\n  status: z.enum(['ready', 'failed', 'unknown']).optional(),\n});\n\nexport type EnvironmentBuildWorkflowResult = z.infer<typeof environmentBuildOutputSchema>;\n\nexport interface EnvironmentBuildWorkflowOptions {\n  sleep?: (ms: number) => Promise<void>;\n  pollMs?: number;\n  maxWaitMs?: number;\n  /** Called with the first step's answer so a caller can return it without waiting for the poll. */\n  onStart?: (runId: string, outcome: EnvironmentBuildOutcome) => void;\n}\n\nexport function createEnvironmentBuildWorkflow(\n  deps: EnvironmentBuildDeps,\n  options: EnvironmentBuildWorkflowOptions = {},\n) {\n  const sleep = options.sleep ?? (ms => new Promise<void>(resolve => setTimeout(resolve, ms)));\n  const pollMs = options.pollMs ?? DEFAULT_BUILD_POLL_MS;\n  const maxWaitMs = options.maxWaitMs ?? MAX_BUILD_WAIT_MS;\n  const now = deps.now ?? (() => new Date());\n\n  const start = createStep({\n    id: 'start',\n    inputSchema: environmentBuildInputSchema,\n    outputSchema: startOutputSchema,\n    execute: async ({ inputData, runId }) => {\n      const outcome = await runEnvironmentBuild(deps, inputData);\n      options.onStart?.(runId, outcome);\n      return { projectId: inputData.projectId, ...outcome };\n    },\n  });\n\n  const awaitBuild = createStep({\n    id: 'await-build',\n    inputSchema: startOutputSchema,\n    outputSchema: environmentBuildOutputSchema,\n    execute: async ({ inputData }): Promise<EnvironmentBuildWorkflowResult> => {\n      const { projectId, heads, ...result } = inputData;\n      if (result.outcome !== 'started' || !result.buildId || !heads) return result;\n      const builds = deps.sandbox?.builds;\n      const project = await deps.projects.getById({ id: projectId });\n      if (!builds || !deps.sourceControl || !project) return { ...result, status: 'unknown' };\n      const environment = await resolveProjectEnvironment(deps.sourceControl.storage, project);\n      const ctx = environmentBuildContext(project, environment, heads, deps.sourceControl.versionControl);\n      const startedAt = now().getTime();\n      try {\n        for (;;) {\n          const build = await builds.get(ctx, environment.settings, result.buildId);\n          if (build.status === 'ready') {\n            const templateId = build.templateId ?? result.templateId ?? result.buildId;\n            // A newer run may have replaced `last_build_id` while this one\n            // polled; the pin is skipped then so the stale image never wins.\n            const pinned = await deps.projects.pinActiveTemplate({\n              id: project.id,\n              buildId: result.buildId,\n              templateId,\n              heads,\n            });\n            deps.logger?.info(pinned ? 'environment build ready' : 'environment build ready but superseded', {\n              factoryProjectId: project.id,\n              templateId,\n            });\n            return { ...result, templateId, status: 'ready' };\n          }\n          if (build.status === 'failed' || build.status === 'unknown') {\n            deps.logger?.info('environment build did not complete', {\n              factoryProjectId: project.id,\n              buildId: result.buildId,\n              status: build.status,\n              ...(build.error ? { reason: redactCredentials(build.error) } : {}),\n            });\n            return {\n              ...result,\n              status: build.status,\n              ...(build.error ? { reason: redactCredentials(build.error) } : {}),\n            };\n          }\n          if (now().getTime() - startedAt >= maxWaitMs) {\n            return { ...result, status: 'unknown', reason: 'Build wait timed out.' };\n          }\n          await sleep(pollMs);\n        }\n      } catch (error) {\n        const reason = errorReason(error);\n        deps.logger?.info('environment build status read failed', { factoryProjectId: project.id, reason });\n        return { ...result, status: 'unknown', reason };\n      }\n    },\n  });\n\n  return createWorkflow({\n    id: ENVIRONMENT_BUILD_WORKFLOW_ID,\n    inputSchema: environmentBuildInputSchema,\n    outputSchema: environmentBuildOutputSchema,\n  })\n    .then(start)\n    .then(awaitBuild)\n    .commit();\n}\n"],"mappings":"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"}

package/dist/environment/build.d.ts

@@ -0,0 +1,111 @@
+/**
+ * One proactive environment build: decide whether a trigger should build,
+ * hand the sandbox's `builds` capability a context identical to a session's,
+ * and record the started build on the project row. Polling the build to its
+ * end and pinning the active template is the workflow's second step
+ * (`build-workflow.ts`), so a request that only needs the start answer never
+ * waits on the provider.
+ */
+import type { FactorySandbox, FactorySandboxContext } from '@mastra/core/workspace';
+import type { VersionControl } from '../capabilities/version-control.js';
+import type { FactoryProject, FactoryProjectsStorage } from '../storage/domains/projects/base.js';
+import type { SourceControlStorageHandle } from '../storage/domains/source-control/base.js';
+import type { SessionEnvironment } from '../workspace.js';
+import type { EnvironmentHeads } from './heads.js';
+export declare const ENVIRONMENT_BUILD_TRIGGERS: readonly ["manual", "schedule", "push"];
+export type EnvironmentBuildTrigger = (typeof ENVIRONMENT_BUILD_TRIGGERS)[number];
+export interface EnvironmentBuildSourceControl {
+    storage: Pick<SourceControlStorageHandle, 'projectRepositories' | 'repositories'>;
+    versionControl: Pick<VersionControl, 'getRepositoryAccess'>;
+}
+export interface EnvironmentBuildDeps {
+    /** The factory's normalized sandbox; builds are unavailable without its `builds`. */
+    sandbox: FactorySandbox | undefined;
+    projects: Pick<FactoryProjectsStorage, 'getById' | 'claimBuildAttempt' | 'claimBuildStart' | 'renewBuildStart' | 'releaseBuildStart' | 'pinActiveTemplate'>;
+    /** Absent when the factory has no source-control integration to resolve heads with. */
+    sourceControl: EnvironmentBuildSourceControl | undefined;
+    logger?: {
+        info: (msg: string, meta?: Record<string, unknown>) => void;
+    };
+    now?: () => Date;
+    /** How often a run renews its build-start lease; a third of `BUILD_START_LEASE_MS` by default. */
+    leaseRenewMs?: number;
+    /** Waits between tries at recording a started build. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface EnvironmentBuildOutcome {
+    outcome: 'started' | 'skipped' | 'unavailable' | 'failed';
+    buildId?: string;
+    templateId?: string;
+    /** 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. */
+    reason?: string;
+    /** The heads the started build pins; the workflow stores them once the build is ready. */
+    heads?: EnvironmentHeads;
+}
+/** The synthetic session id a project's build runs under; never a session. */
+export declare function environmentBuildSessionId(projectId: string): string;
+/**
+ * A build or setup error may echo a clone URL or a token; strip URL userinfo
+ * and GitHub token shapes before the message is stored, logged or shown.
+ */
+export declare function redactCredentials(message: string): string;
+/** An error's message with credentials redacted, safe to log, store or return. */
+export declare function errorReason(error: unknown): string;
+/**
+ * The context an environment build (or a read of its status) hands the
+ * provider: the same list form a session boots with, under the build's own
+ * session id, with heads served from `heads` so the provider never resolves
+ * them itself.
+ */
+export declare function environmentBuildContext(project: Pick<FactoryProject, 'id' | 'orgId'>, environment: SessionEnvironment, heads: EnvironmentHeads, versionControl: Pick<VersionControl, 'getRepositoryAccess'>): FactorySandboxContext;
+/**
+ * Fingerprint of everything a build bakes into the template besides the
+ * repository heads: provider settings, the repositories and their order,
+ * their setup commands, the workspace setup command and the working
+ * directory. A schedule or push skips a ready build only while this matches.
+ */
+export declare function environmentBuildInputs(environment: SessionEnvironment): string;
+/**
+ * The current head of every environment repository's template branch, keyed
+ * by slug. The template clones the repository default branch (a link's own
+ * branch is the session's base, checked out after boot), so that is the
+ * branch a build pins; sessions let the provider resolve the same head.
+ */
+export declare function resolveEnvironmentHeads(sourceControl: EnvironmentBuildSourceControl, project: Pick<FactoryProject, 'orgId'>, environment: SessionEnvironment): Promise<EnvironmentHeads>;
+/**
+ * How long a build-start lease lasts without renewal. The run holding it
+ * renews it every third of that while it works, so a lease lapses only when
+ * its run died or stalled.
+ */
+export declare const BUILD_START_LEASE_MS: number;
+/**
+ * Start a build for `projectId` when `trigger` calls for one. Every trigger
+ * takes the project's build-start lease before reading build state and renews
+ * it until the started build is recorded, so overlapping manual, scheduled and
+ * push runs never both start a build, however long the provider takes; a run
+ * that finds the lease held skips as `starting`. Every trigger skips while the
+ * last build is still running; `schedule` and `push` also skip when the last
+ * build is ready and neither a head nor any other template input changed;
+ * `manual` otherwise always builds. A `push` that would build then takes the
+ * leading-edge debounce claim, so only a push that starts a build opens the
+ * window. Saving settings never builds.
+ *
+ * Taking over a lapsed lease leaves the start uncertain: the lapsed run may
+ * have started a build it never recorded. The mark persists until resolved.
+ * While it stands, a provider that lists builds is asked for a running one
+ * (and every trigger skips as `in_progress` on it); with a provider that
+ * cannot list, every trigger skips as `unresolved`.
+ *
+ * The result is written as the lease is released, and only while this run
+ * still holds it. A failed `builds.start` clears the last build id, so a later
+ * `schedule` or `push` cannot mistake the previous ready build for the current
+ * template; any other error keeps a running build's id. A started build whose
+ * recording keeps failing yields `failed` (`not_recorded`) with the lease left
+ * to lapse rather than released, and a run that lost its lease while the
+ * provider started yields `failed` (`superseded`); neither is polled or pinned.
+ */
+export declare function runEnvironmentBuild(deps: EnvironmentBuildDeps, input: {
+    projectId: string;
+    trigger: EnvironmentBuildTrigger;
+}): Promise<EnvironmentBuildOutcome>;
+//# sourceMappingURL=build.d.ts.map

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

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