@mastra/factory 0.0.0-aggregate-trace-20261015182851

package/dist/sandbox/callback-factory-sandbox.d.ts

@@ -0,0 +1,15 @@
+import { FactorySandbox } from '@mastra/core/workspace';
+import type { FactorySandboxContext, MastraSandbox } from '@mastra/core/workspace';
+import type { MastraFactorySandboxConfig } from './session-sandbox.js';
+/**
+ * Wraps the `sandbox: ctx => new SomeSandbox(...)` host callback
+ * as a FactorySandbox. The host owns everything inside the callback, so the
+ * factory knows nothing about it: no settings, no template, no builds.
+ */
+export declare class CallbackFactorySandbox extends FactorySandbox<Record<string, never>> {
+    #private;
+    readonly provider = "custom";
+    constructor(callback: MastraFactorySandboxConfig);
+    create(ctx: FactorySandboxContext): MastraSandbox;
+}
+//# sourceMappingURL=callback-factory-sandbox.d.ts.map

package/dist/sandbox/callback-factory-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-factory-sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/callback-factory-sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEnF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAEvE;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;;IAC/E,QAAQ,CAAC,QAAQ,YAAY;gBAIjB,QAAQ,EAAE,0BAA0B;IAKhD,MAAM,CAAC,GAAG,EAAE,qBAAqB,GAAG,aAAa;CAGlD"}

package/dist/sandbox/callback-factory-sandbox.js

@@ -0,0 +1,22 @@
+import { FactorySandbox } from "@mastra/core/workspace";
+//#region src/sandbox/callback-factory-sandbox.ts
+/**
+* Wraps the `sandbox: ctx => new SomeSandbox(...)` host callback
+* as a FactorySandbox. The host owns everything inside the callback, so the
+* factory knows nothing about it: no settings, no template, no builds.
+*/
+var CallbackFactorySandbox = class extends FactorySandbox {
+	provider = "custom";
+	#callback;
+	constructor(callback) {
+		super();
+		this.#callback = callback;
+	}
+	create(ctx) {
+		return this.#callback(ctx);
+	}
+};
+//#endregion
+export { CallbackFactorySandbox };
+
+//# sourceMappingURL=callback-factory-sandbox.js.map

package/dist/sandbox/callback-factory-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-factory-sandbox.js","names":["#callback"],"sources":["../../src/sandbox/callback-factory-sandbox.ts"],"sourcesContent":["import { FactorySandbox } from '@mastra/core/workspace';\nimport type { FactorySandboxContext, MastraSandbox } from '@mastra/core/workspace';\n\nimport type { MastraFactorySandboxConfig } from './session-sandbox.js';\n\n/**\n * Wraps the `sandbox: ctx => new SomeSandbox(...)` host callback\n * as a FactorySandbox. The host owns everything inside the callback, so the\n * factory knows nothing about it: no settings, no template, no builds.\n */\nexport class CallbackFactorySandbox extends FactorySandbox<Record<string, never>> {\n  readonly provider = 'custom';\n\n  readonly #callback: MastraFactorySandboxConfig;\n\n  constructor(callback: MastraFactorySandboxConfig) {\n    super();\n    this.#callback = callback;\n  }\n\n  create(ctx: FactorySandboxContext): MastraSandbox {\n    return this.#callback(ctx);\n  }\n}\n"],"mappings":";;;;;;;AAUA,IAAa,yBAAb,cAA4C,eAAsC;CAChF,WAAoB;CAEpB;CAEA,YAAY,UAAsC;EAChD,MAAM;EACN,KAAKA,YAAY;CACnB;CAEA,OAAO,KAA2C;EAChD,OAAO,KAAKA,UAAU,GAAG;CAC3B;AACF"}

package/dist/sandbox/git-ref.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validate a branch/ref name before persistence or use in a Git command.
+ * The conservative character allowlist is paired with Git's structural rules
+ * so accepted values remain valid when a workspace is materialized later.
+ */
+export declare function isValidGitRef(value: unknown): value is string;
+//# sourceMappingURL=git-ref.d.ts.map

package/dist/sandbox/git-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-ref.d.ts","sourceRoot":"","sources":["../../src/sandbox/git-ref.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAe7D"}

package/dist/sandbox/git-ref.js

@@ -0,0 +1,15 @@
+//#region src/sandbox/git-ref.ts
+/**
+* Validate a branch/ref name before persistence or use in a Git command.
+* The conservative character allowlist is paired with Git's structural rules
+* so accepted values remain valid when a workspace is materialized later.
+*/
+function isValidGitRef(value) {
+	if (typeof value !== "string" || value.length === 0 || value.length > 255 || !/^[A-Za-z0-9_./-]+$/.test(value)) return false;
+	if (value.startsWith("-") || value.startsWith("/") || value.endsWith("/") || value.endsWith(".") || value.includes("..") || value.includes("//")) return false;
+	return value.split("/").every((component) => !component.startsWith(".") && !component.toLowerCase().endsWith(".lock"));
+}
+//#endregion
+export { isValidGitRef };
+
+//# sourceMappingURL=git-ref.js.map

package/dist/sandbox/git-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-ref.js","names":[],"sources":["../../src/sandbox/git-ref.ts"],"sourcesContent":["/**\n * Validate a branch/ref name before persistence or use in a Git command.\n * The conservative character allowlist is paired with Git's structural rules\n * so accepted values remain valid when a workspace is materialized later.\n */\nexport function isValidGitRef(value: unknown): value is string {\n  if (typeof value !== 'string' || value.length === 0 || value.length > 255 || !/^[A-Za-z0-9_./-]+$/.test(value)) {\n    return false;\n  }\n  if (\n    value.startsWith('-') ||\n    value.startsWith('/') ||\n    value.endsWith('/') ||\n    value.endsWith('.') ||\n    value.includes('..') ||\n    value.includes('//')\n  ) {\n    return false;\n  }\n  return value.split('/').every(component => !component.startsWith('.') && !component.toLowerCase().endsWith('.lock'));\n}\n"],"mappings":";;;;;;AAKA,SAAgB,cAAc,OAAiC;CAC7D,IAAI,OAAO,UAAU,YAAY,MAAM,WAAW,KAAK,MAAM,SAAS,OAAO,CAAC,qBAAqB,KAAK,KAAK,GAC3G,OAAO;CAET,IACE,MAAM,WAAW,GAAG,KACpB,MAAM,WAAW,GAAG,KACpB,MAAM,SAAS,GAAG,KAClB,MAAM,SAAS,GAAG,KAClB,MAAM,SAAS,IAAI,KACnB,MAAM,SAAS,IAAI,GAEnB,OAAO;CAET,OAAO,MAAM,MAAM,GAAG,CAAC,CAAC,OAAM,cAAa,CAAC,UAAU,WAAW,GAAG,KAAK,CAAC,UAAU,YAAY,CAAC,CAAC,SAAS,OAAO,CAAC;AACrH"}

package/dist/sandbox/local-factory-sandbox.d.ts

@@ -0,0 +1,20 @@
+import { FactorySandbox, LocalSandbox } from '@mastra/core/workspace';
+import type { FactorySandboxContext } from '@mastra/core/workspace';
+export interface LocalFactorySandboxOptions {
+    /** Directory under which every session gets its own working directory. */
+    root: string;
+    /** Environment for commands run in the sandbox. */
+    env?: Record<string, string>;
+}
+/**
+ * Sessions run on the host machine: each session's sandbox is a LocalSandbox
+ * rooted at `join(root, sessionId)`, where the repository checks out as a
+ * subdirectory. No template and no user-tunable settings.
+ */
+export declare class LocalFactorySandbox extends FactorySandbox<Record<string, never>> {
+    #private;
+    readonly provider = "local";
+    constructor(options: LocalFactorySandboxOptions);
+    create(ctx: FactorySandboxContext): LocalSandbox;
+}
+//# sourceMappingURL=local-factory-sandbox.d.ts.map

package/dist/sandbox/local-factory-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-factory-sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/local-factory-sandbox.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,MAAM,WAAW,0BAA0B;IACzC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;;IAC5E,QAAQ,CAAC,QAAQ,WAAW;gBAIhB,OAAO,EAAE,0BAA0B;IAK/C,MAAM,CAAC,GAAG,EAAE,qBAAqB,GAAG,YAAY;CAOjD"}

package/dist/sandbox/local-factory-sandbox.js

@@ -0,0 +1,27 @@
+import { FactorySandbox, LocalSandbox } from "@mastra/core/workspace";
+import { join } from "path";
+//#region src/sandbox/local-factory-sandbox.ts
+/**
+* Sessions run on the host machine: each session's sandbox is a LocalSandbox
+* rooted at `join(root, sessionId)`, where the repository checks out as a
+* subdirectory. No template and no user-tunable settings.
+*/
+var LocalFactorySandbox = class extends FactorySandbox {
+	provider = "local";
+	#options;
+	constructor(options) {
+		super();
+		this.#options = options;
+	}
+	create(ctx) {
+		return new LocalSandbox({
+			id: ctx.sessionId,
+			workingDirectory: join(this.#options.root, ctx.sessionId),
+			...this.#options.env ? { env: this.#options.env } : {}
+		});
+	}
+};
+//#endregion
+export { LocalFactorySandbox };
+
+//# sourceMappingURL=local-factory-sandbox.js.map

package/dist/sandbox/local-factory-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-factory-sandbox.js","names":["#options"],"sources":["../../src/sandbox/local-factory-sandbox.ts"],"sourcesContent":["import { join } from 'node:path';\nimport { FactorySandbox, LocalSandbox } from '@mastra/core/workspace';\nimport type { FactorySandboxContext } from '@mastra/core/workspace';\n\nexport interface LocalFactorySandboxOptions {\n  /** Directory under which every session gets its own working directory. */\n  root: string;\n  /** Environment for commands run in the sandbox. */\n  env?: Record<string, string>;\n}\n\n/**\n * Sessions run on the host machine: each session's sandbox is a LocalSandbox\n * rooted at `join(root, sessionId)`, where the repository checks out as a\n * subdirectory. No template and no user-tunable settings.\n */\nexport class LocalFactorySandbox extends FactorySandbox<Record<string, never>> {\n  readonly provider = 'local';\n\n  readonly #options: LocalFactorySandboxOptions;\n\n  constructor(options: LocalFactorySandboxOptions) {\n    super();\n    this.#options = options;\n  }\n\n  create(ctx: FactorySandboxContext): LocalSandbox {\n    return new LocalSandbox({\n      id: ctx.sessionId,\n      workingDirectory: join(this.#options.root, ctx.sessionId),\n      ...(this.#options.env ? { env: this.#options.env } : {}),\n    });\n  }\n}\n"],"mappings":";;;;;;;;AAgBA,IAAa,sBAAb,cAAyC,eAAsC;CAC7E,WAAoB;CAEpB;CAEA,YAAY,SAAqC;EAC/C,MAAM;EACN,KAAKA,WAAW;CAClB;CAEA,OAAO,KAA0C;EAC/C,OAAO,IAAI,aAAa;GACtB,IAAI,IAAI;GACR,kBAAkB,KAAK,KAAKA,SAAS,MAAM,IAAI,SAAS;GACxD,GAAI,KAAKA,SAAS,MAAM,EAAE,KAAK,KAAKA,SAAS,IAAI,IAAI,CAAC;EACxD,CAAC;CACH;AACF"}

package/dist/sandbox/materialization.d.ts

@@ -0,0 +1,41 @@
+import type { ExecuteCommandOptions, WorkspaceSandbox } from '@mastra/core/workspace';
+/** Result of one command executed inside a sandbox. */
+export interface SandboxCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * A sandbox that can run commands.
+ *
+ * `executeCommand` is optional on `WorkspaceSandbox` because some providers
+ * only offer a filesystem. Every git and materialization helper here needs it,
+ * so this type promotes it to required. `id` is taken from core; the command
+ * signature is spelled out because core's `CommandResult` is wider than what
+ * these helpers read (see below).
+ *
+ * `sandboxId` is the provider's physical, reattachable VM id (undefined until
+ * started, or for providers with no separate physical id); it is carried here
+ * so callers can persist it for deterministic reattach on resume.
+ */
+export type ExecutableSandbox = Pick<WorkspaceSandbox, 'id'> & {
+    sandboxId?: string;
+    /**
+     * Runs a command. The options are core's, but the result is only the part
+     * these helpers read: core's `CommandResult` also carries `success` and
+     * `executionTimeMs`, and asking for them would reject test doubles that
+     * report exactly what the helpers consume.
+     */
+    executeCommand(command: string, args?: string[], options?: ExecuteCommandOptions): Promise<SandboxCommandResult>;
+};
+/**
+ * Narrow a sandbox to one that can run commands, or fail saying which
+ * capability is missing.
+ *
+ * Callers hold a `WorkspaceSandbox`, whose `executeCommand` is optional.
+ * Optional-chaining past it would hand every caller `undefined` where it
+ * expects an exit code, turning a misconfigured provider into a git command
+ * that silently did nothing.
+ */
+export declare function requireExec(sandbox: WorkspaceSandbox): ExecutableSandbox;
+//# sourceMappingURL=materialization.d.ts.map

package/dist/sandbox/materialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialization.d.ts","sourceRoot":"","sources":["../../src/sandbox/materialization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEtF,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,GAAG;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAClH,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,iBAAiB,CAOxE"}

package/dist/sandbox/materialization.js

@@ -0,0 +1,18 @@
+//#region src/sandbox/materialization.ts
+/**
+* Narrow a sandbox to one that can run commands, or fail saying which
+* capability is missing.
+*
+* Callers hold a `WorkspaceSandbox`, whose `executeCommand` is optional.
+* Optional-chaining past it would hand every caller `undefined` where it
+* expects an exit code, turning a misconfigured provider into a git command
+* that silently did nothing.
+*/
+function requireExec(sandbox) {
+	if (typeof sandbox.executeCommand !== "function") throw new Error(`Sandbox provider '${sandbox.provider}' does not support executeCommand, which is required to run git and filesystem operations in a session.`);
+	return sandbox;
+}
+//#endregion
+export { requireExec };
+
+//# sourceMappingURL=materialization.js.map

package/dist/sandbox/materialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialization.js","names":[],"sources":["../../src/sandbox/materialization.ts"],"sourcesContent":["import type { ExecuteCommandOptions, WorkspaceSandbox } from '@mastra/core/workspace';\n\n/** Result of one command executed inside a sandbox. */\nexport interface SandboxCommandResult {\n  exitCode: number;\n  stdout: string;\n  stderr: string;\n}\n\n/**\n * A sandbox that can run commands.\n *\n * `executeCommand` is optional on `WorkspaceSandbox` because some providers\n * only offer a filesystem. Every git and materialization helper here needs it,\n * so this type promotes it to required. `id` is taken from core; the command\n * signature is spelled out because core's `CommandResult` is wider than what\n * these helpers read (see below).\n *\n * `sandboxId` is the provider's physical, reattachable VM id (undefined until\n * started, or for providers with no separate physical id); it is carried here\n * so callers can persist it for deterministic reattach on resume.\n */\nexport type ExecutableSandbox = Pick<WorkspaceSandbox, 'id'> & {\n  sandboxId?: string;\n  /**\n   * Runs a command. The options are core's, but the result is only the part\n   * these helpers read: core's `CommandResult` also carries `success` and\n   * `executionTimeMs`, and asking for them would reject test doubles that\n   * report exactly what the helpers consume.\n   */\n  executeCommand(command: string, args?: string[], options?: ExecuteCommandOptions): Promise<SandboxCommandResult>;\n};\n\n/**\n * Narrow a sandbox to one that can run commands, or fail saying which\n * capability is missing.\n *\n * Callers hold a `WorkspaceSandbox`, whose `executeCommand` is optional.\n * Optional-chaining past it would hand every caller `undefined` where it\n * expects an exit code, turning a misconfigured provider into a git command\n * that silently did nothing.\n */\nexport function requireExec(sandbox: WorkspaceSandbox): ExecutableSandbox {\n  if (typeof sandbox.executeCommand !== 'function') {\n    throw new Error(\n      `Sandbox provider '${sandbox.provider}' does not support executeCommand, which is required to run git and filesystem operations in a session.`,\n    );\n  }\n  return sandbox as ExecutableSandbox;\n}\n"],"mappings":";;;;;;;;;;AA0CA,SAAgB,YAAY,SAA8C;CACxE,IAAI,OAAO,QAAQ,mBAAmB,YACpC,MAAM,IAAI,MACR,qBAAqB,QAAQ,SAAS,wGACxC;CAEF,OAAO;AACT"}

package/dist/sandbox/session-retirement.d.ts

@@ -0,0 +1,45 @@
+import type { SourceControlStorageHandle } from '../storage/domains/source-control/base.js';
+import type { WorkItemsStorage } from '../storage/domains/work-items/base.js';
+type WarningLogger = (message: string, details: Record<string, unknown>) => void;
+export interface SessionRetirementCoordinatorOptions {
+    invalidateSession?: (sessionId: string) => Promise<void> | void;
+    warn?: WarningLogger;
+}
+export interface RetireSessionInput {
+    sourceControl: SourceControlStorageHandle;
+    /** When provided, deleting the session row also strips its work-item refs. */
+    workItems?: Pick<WorkItemsStorage, 'clearSessionReferences'>;
+    orgId: string;
+    sessionId: string;
+    deleteSession: boolean;
+}
+/**
+ * Owns terminal and destructive session cleanup. Each session is serialized so
+ * duplicate role bindings and competing deletion/transition requests cannot
+ * run teardown concurrently.
+ *
+ * Sandbox identity is the session id: retirement stops (or, for deleted
+ * sessions, destroys) the sandbox this process holds in the session memo.
+ * Sessions opened on another replica have no memo entry here — their VMs are
+ * left to the provider's idle lifecycle (pause / idle GC), which is the
+ * provider-owned half of the contract.
+ */
+export declare class SessionRetirementCoordinator {
+    #private;
+    constructor(options?: SessionRetirementCoordinatorOptions);
+    retireSession(input: RetireSessionInput): Promise<void>;
+    retireWorkItemSessions(options: {
+        workItems: Pick<WorkItemsStorage, 'get'>;
+        sourceControl: SourceControlStorageHandle;
+        orgId: string;
+        workItemId: string;
+    }): Promise<void>;
+    retireProjectRepositorySessions(options: {
+        sourceControl: SourceControlStorageHandle;
+        workItems?: Pick<WorkItemsStorage, 'clearSessionReferences'>;
+        orgId: string;
+        projectRepositoryId: string;
+    }): Promise<void>;
+}
+export {};
+//# sourceMappingURL=session-retirement.d.ts.map

package/dist/sandbox/session-retirement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-retirement.d.ts","sourceRoot":"","sources":["../../src/sandbox/session-retirement.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,0BAA0B,EAC3B,MAAM,2CAA2C,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAI9E,KAAK,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAEjF,MAAM,WAAW,mCAAmC;IAClD,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAChE,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,0BAA0B,CAAC;IAC1C,8EAA8E;IAC9E,SAAS,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,wBAAwB,CAAC,CAAC;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;CACxB;AAQD;;;;;;;;;;GAUG;AACH,qBAAa,4BAA4B;;gBAK3B,OAAO,GAAE,mCAAwC;IAKvD,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvD,sBAAsB,CAAC,OAAO,EAAE;QACpC,SAAS,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;QACzC,aAAa,EAAE,0BAA0B,CAAC;QAC1C,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBX,+BAA+B,CAAC,OAAO,EAAE;QAC7C,aAAa,EAAE,0BAA0B,CAAC;QAC1C,SAAS,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,wBAAwB,CAAC,CAAC;QAC7D,KAAK,EAAE,MAAM,CAAC;QACd,mBAAmB,EAAE,MAAM,CAAC;KAC7B,GAAG,OAAO,CAAC,IAAI,CAAC;CAqHlB"}

package/dist/sandbox/session-retirement.js

@@ -0,0 +1,153 @@
+import { DEFAULT_COMMAND_TIMEOUT_MS, runTeardownCommand } from "../integrations/github/sandbox.js";
+import { requireExec } from "./materialization.js";
+import { peekSessionSandbox } from "./session-sandbox.js";
+import { peekSessionEnvironmentTeardown } from "../session/environment-state-processor.js";
+import { releaseSessionSandbox } from "../integrations/github/sandbox-release.js";
+//#region src/sandbox/session-retirement.ts
+function boundedError(error) {
+	const detail = error instanceof Error ? error.message : String(error);
+	if (detail.length <= 2e3) return detail;
+	return `${detail.slice(0, 200)}...${detail.slice(-1797)}`;
+}
+/**
+* Owns terminal and destructive session cleanup. Each session is serialized so
+* duplicate role bindings and competing deletion/transition requests cannot
+* run teardown concurrently.
+*
+* Sandbox identity is the session id: retirement stops (or, for deleted
+* sessions, destroys) the sandbox this process holds in the session memo.
+* Sessions opened on another replica have no memo entry here — their VMs are
+* left to the provider's idle lifecycle (pause / idle GC), which is the
+* provider-owned half of the contract.
+*/
+var SessionRetirementCoordinator = class {
+	#invalidateSession;
+	#warn;
+	#locks = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.#invalidateSession = options.invalidateSession ?? (() => {});
+		this.#warn = options.warn ?? ((message, details) => console.warn(`[Mastra Factory] ${message}`, details));
+	}
+	async retireSession(input) {
+		const current = (this.#locks.get(input.sessionId) ?? Promise.resolve()).catch(() => {}).then(() => this.#retireSession(input));
+		this.#locks.set(input.sessionId, current);
+		try {
+			await current;
+		} finally {
+			if (this.#locks.get(input.sessionId) === current) this.#locks.delete(input.sessionId);
+		}
+	}
+	async retireWorkItemSessions(options) {
+		const item = await options.workItems.get({
+			orgId: options.orgId,
+			id: options.workItemId
+		});
+		if (!item) return;
+		const sessionIds = [...new Set(Object.values(item.sessions).map((session) => session.sessionId))];
+		await Promise.all(sessionIds.map((sessionId) => this.retireSession({
+			sourceControl: options.sourceControl,
+			orgId: options.orgId,
+			sessionId,
+			deleteSession: false
+		})));
+	}
+	async retireProjectRepositorySessions(options) {
+		const sessions = await options.sourceControl.sessions.listByProjectRepository({ projectRepositoryId: options.projectRepositoryId });
+		await Promise.all(sessions.map((session) => this.retireSession({
+			sourceControl: options.sourceControl,
+			...options.workItems ? { workItems: options.workItems } : {},
+			orgId: options.orgId,
+			sessionId: session.sessionId,
+			deleteSession: true
+		})));
+	}
+	async #retireSession(input) {
+		const session = await input.sourceControl.sessions.getBySessionId(input.sessionId);
+		if (!session || session.orgId !== input.orgId) return;
+		try {
+			await this.#teardownSessionSandbox(input, session);
+		} finally {
+			try {
+				await this.#invalidateSession(session.sessionId);
+			} catch (error) {
+				this.#warn("Factory session workspace cache invalidation failed", {
+					orgId: session.orgId,
+					sessionId: session.sessionId,
+					projectRepositoryId: session.projectRepositoryId,
+					error: boundedError(error)
+				});
+			}
+			if (input.deleteSession) {
+				await input.workItems?.clearSessionReferences({
+					orgId: input.orgId,
+					sessionId: input.sessionId
+				});
+				await input.sourceControl.sessions.delete(session.id);
+			}
+		}
+	}
+	async #teardownSessionSandbox(input, session) {
+		const entry = peekSessionSandbox(session.id);
+		if (!entry) return;
+		const environmentTeardown = peekSessionEnvironmentTeardown(session.sessionId);
+		if (environmentTeardown.length > 0) {
+			for (const repo of environmentTeardown) try {
+				await runTeardownCommand(requireExec(entry.sandbox), repo.dir, repo.command, { timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS });
+			} catch (error) {
+				this.#warn("Factory teardown command failed", {
+					orgId: session.orgId,
+					sessionId: session.sessionId,
+					projectRepositoryId: session.projectRepositoryId,
+					repository: repo.slug,
+					error: boundedError(error)
+				});
+			}
+			await this.#releaseSandbox(input, session);
+			return;
+		}
+		let projectRepository;
+		try {
+			projectRepository = session.projectRepositoryId ? await input.sourceControl.projectRepositories.get({
+				orgId: input.orgId,
+				id: session.projectRepositoryId
+			}) : null;
+		} catch (error) {
+			this.#warn("Factory repository settings could not be loaded for session retirement", {
+				orgId: session.orgId,
+				sessionId: session.sessionId,
+				projectRepositoryId: session.projectRepositoryId,
+				error: boundedError(error)
+			});
+		}
+		if (projectRepository?.teardownCommand && entry.workdir) try {
+			await runTeardownCommand(requireExec(entry.sandbox), entry.workdir, projectRepository.teardownCommand, { timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS });
+		} catch (error) {
+			this.#warn("Factory teardown command failed", {
+				orgId: session.orgId,
+				sessionId: session.sessionId,
+				projectRepositoryId: session.projectRepositoryId,
+				error: boundedError(error)
+			});
+		}
+		await this.#releaseSandbox(input, session);
+	}
+	async #releaseSandbox(input, session) {
+		try {
+			await releaseSessionSandbox({
+				sessionId: session.id,
+				destroy: input.deleteSession
+			});
+		} catch (error) {
+			this.#warn("Factory session sandbox release failed", {
+				orgId: session.orgId,
+				sessionId: session.sessionId,
+				projectRepositoryId: session.projectRepositoryId,
+				error: boundedError(error)
+			});
+		}
+	}
+};
+//#endregion
+export { SessionRetirementCoordinator };
+
+//# sourceMappingURL=session-retirement.js.map

package/dist/sandbox/session-retirement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-retirement.js","names":["#invalidateSession","#warn","#locks","#retireSession","#teardownSessionSandbox","#releaseSandbox"],"sources":["../../src/sandbox/session-retirement.ts"],"sourcesContent":["import { releaseSessionSandbox } from '../integrations/github/sandbox-release.js';\nimport { DEFAULT_COMMAND_TIMEOUT_MS, runTeardownCommand } from '../integrations/github/sandbox.js';\nimport { peekSessionEnvironmentTeardown } from '../session/environment-state-processor.js';\nimport type {\n  ProjectRepository,\n  SourceControlSession,\n  SourceControlStorageHandle,\n} from '../storage/domains/source-control/base.js';\nimport type { WorkItemsStorage } from '../storage/domains/work-items/base.js';\nimport { requireExec } from './materialization.js';\nimport { peekSessionSandbox } from './session-sandbox.js';\n\ntype WarningLogger = (message: string, details: Record<string, unknown>) => void;\n\nexport interface SessionRetirementCoordinatorOptions {\n  invalidateSession?: (sessionId: string) => Promise<void> | void;\n  warn?: WarningLogger;\n}\n\nexport interface RetireSessionInput {\n  sourceControl: SourceControlStorageHandle;\n  /** When provided, deleting the session row also strips its work-item refs. */\n  workItems?: Pick<WorkItemsStorage, 'clearSessionReferences'>;\n  orgId: string;\n  sessionId: string;\n  deleteSession: boolean;\n}\n\nfunction boundedError(error: unknown): string {\n  const detail = error instanceof Error ? error.message : String(error);\n  if (detail.length <= 2000) return detail;\n  return `${detail.slice(0, 200)}...${detail.slice(-1797)}`;\n}\n\n/**\n * Owns terminal and destructive session cleanup. Each session is serialized so\n * duplicate role bindings and competing deletion/transition requests cannot\n * run teardown concurrently.\n *\n * Sandbox identity is the session id: retirement stops (or, for deleted\n * sessions, destroys) the sandbox this process holds in the session memo.\n * Sessions opened on another replica have no memo entry here — their VMs are\n * left to the provider's idle lifecycle (pause / idle GC), which is the\n * provider-owned half of the contract.\n */\nexport class SessionRetirementCoordinator {\n  readonly #invalidateSession: NonNullable<SessionRetirementCoordinatorOptions['invalidateSession']>;\n  readonly #warn: WarningLogger;\n  readonly #locks = new Map<string, Promise<void>>();\n\n  constructor(options: SessionRetirementCoordinatorOptions = {}) {\n    this.#invalidateSession = options.invalidateSession ?? (() => {});\n    this.#warn = options.warn ?? ((message, details) => console.warn(`[Mastra Factory] ${message}`, details));\n  }\n\n  async retireSession(input: RetireSessionInput): Promise<void> {\n    const previous = this.#locks.get(input.sessionId) ?? Promise.resolve();\n    const current = previous.catch(() => {}).then(() => this.#retireSession(input));\n    this.#locks.set(input.sessionId, current);\n    try {\n      await current;\n    } finally {\n      if (this.#locks.get(input.sessionId) === current) this.#locks.delete(input.sessionId);\n    }\n  }\n\n  async retireWorkItemSessions(options: {\n    workItems: Pick<WorkItemsStorage, 'get'>;\n    sourceControl: SourceControlStorageHandle;\n    orgId: string;\n    workItemId: string;\n  }): Promise<void> {\n    const item = await options.workItems.get({ orgId: options.orgId, id: options.workItemId });\n    if (!item) return;\n    const sessionIds = [...new Set(Object.values(item.sessions).map(session => session.sessionId))];\n    await Promise.all(\n      sessionIds.map(sessionId =>\n        this.retireSession({\n          sourceControl: options.sourceControl,\n          orgId: options.orgId,\n          sessionId,\n          deleteSession: false,\n        }),\n      ),\n    );\n  }\n\n  async retireProjectRepositorySessions(options: {\n    sourceControl: SourceControlStorageHandle;\n    workItems?: Pick<WorkItemsStorage, 'clearSessionReferences'>;\n    orgId: string;\n    projectRepositoryId: string;\n  }): Promise<void> {\n    const sessions = await options.sourceControl.sessions.listByProjectRepository({\n      projectRepositoryId: options.projectRepositoryId,\n    });\n    await Promise.all(\n      sessions.map(session =>\n        this.retireSession({\n          sourceControl: options.sourceControl,\n          ...(options.workItems ? { workItems: options.workItems } : {}),\n          orgId: options.orgId,\n          sessionId: session.sessionId,\n          deleteSession: true,\n        }),\n      ),\n    );\n  }\n\n  async #retireSession(input: RetireSessionInput): Promise<void> {\n    const session = await input.sourceControl.sessions.getBySessionId(input.sessionId);\n    if (!session || session.orgId !== input.orgId) return;\n\n    try {\n      await this.#teardownSessionSandbox(input, session);\n    } finally {\n      try {\n        await this.#invalidateSession(session.sessionId);\n      } catch (error) {\n        this.#warn('Factory session workspace cache invalidation failed', {\n          orgId: session.orgId,\n          sessionId: session.sessionId,\n          projectRepositoryId: session.projectRepositoryId,\n          error: boundedError(error),\n        });\n      }\n\n      if (input.deleteSession) {\n        // Refs first: clearing again is a no-op, but refs on a deleted row would dangle forever.\n        await input.workItems?.clearSessionReferences({ orgId: input.orgId, sessionId: input.sessionId });\n        await input.sourceControl.sessions.delete(session.id);\n      }\n    }\n  }\n\n  async #teardownSessionSandbox(input: RetireSessionInput, session: SourceControlSession): Promise<void> {\n    const entry = peekSessionSandbox(session.id);\n    if (!entry) return;\n\n    // A session booted from its factory environment tears every repository\n    // down in position order, each in its own directory; a failure is logged\n    // and the next repository still runs.\n    const environmentTeardown = peekSessionEnvironmentTeardown(session.sessionId);\n    if (environmentTeardown.length > 0) {\n      for (const repo of environmentTeardown) {\n        try {\n          await runTeardownCommand(requireExec(entry.sandbox), repo.dir, repo.command, {\n            timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,\n          });\n        } catch (error) {\n          this.#warn('Factory teardown command failed', {\n            orgId: session.orgId,\n            sessionId: session.sessionId,\n            projectRepositoryId: session.projectRepositoryId,\n            repository: repo.slug,\n            error: boundedError(error),\n          });\n        }\n      }\n      await this.#releaseSandbox(input, session);\n      return;\n    }\n\n    let projectRepository: ProjectRepository | null | undefined;\n    try {\n      projectRepository = session.projectRepositoryId\n        ? await input.sourceControl.projectRepositories.get({ orgId: input.orgId, id: session.projectRepositoryId })\n        : null;\n    } catch (error) {\n      this.#warn('Factory repository settings could not be loaded for session retirement', {\n        orgId: session.orgId,\n        sessionId: session.sessionId,\n        projectRepositoryId: session.projectRepositoryId,\n        error: boundedError(error),\n      });\n    }\n\n    // An unresolved workdir means the sandbox never started in this process:\n    // nothing was set up, so there is nothing for a teardown command to undo.\n    if (projectRepository?.teardownCommand && entry.workdir) {\n      try {\n        await runTeardownCommand(requireExec(entry.sandbox), entry.workdir, projectRepository.teardownCommand, {\n          timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,\n        });\n      } catch (error) {\n        this.#warn('Factory teardown command failed', {\n          orgId: session.orgId,\n          sessionId: session.sessionId,\n          projectRepositoryId: session.projectRepositoryId,\n          error: boundedError(error),\n        });\n      }\n    }\n\n    await this.#releaseSandbox(input, session);\n  }\n\n  async #releaseSandbox(input: RetireSessionInput, session: SourceControlSession): Promise<void> {\n    try {\n      await releaseSessionSandbox({ sessionId: session.id, destroy: input.deleteSession });\n    } catch (error) {\n      this.#warn('Factory session sandbox release failed', {\n        orgId: session.orgId,\n        sessionId: session.sessionId,\n        projectRepositoryId: session.projectRepositoryId,\n        error: boundedError(error),\n      });\n    }\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,185 @@
+import type { FactorySandbox, FactorySandboxContext as CoreFactorySandboxContext, MastraSandbox, SandboxStartHook, WorkspaceSandbox } from '@mastra/core/workspace';
+/**
+ * Everything factory knows about a session's sandbox needs: the whole contract
+ * between factory and the host's FactorySandbox. Factory owns intent; the
+ * provider owns resolving `sessionId` to a runnable VM. Defined in
+ * `@mastra/core/workspace` so provider packages can implement it without
+ * depending on factory.
+ */
+export type FactorySandboxContext = CoreFactorySandboxContext;
+/**
+ * The deploy's sandbox configuration: construct a session's sandbox from
+ * intent. The sandbox identity is the session id; the provider must honor
+ * id-keyed getOrCreate on `start()` (reconnect/resume an existing VM for the
+ * id, create otherwise). Construction must be cheap and side-effect-free —
+ * VMs are provisioned on `start()` only. Local sandboxes should root their
+ * `workingDirectory` at a per-session directory (e.g.
+ * `join(root, ctx.sessionId)`); the repo checks out as a subdirectory of it.
+ *
+ * Forward `ctx.sandboxId` to providers that reattach by physical id so resume
+ * reattaches the original VM instead of provisioning a replacement.
+ *
+ * Returns a `MastraSandbox`, not the bare `WorkspaceSandbox` interface:
+ * factory relies on the base class for the start lifecycle and the runtime
+ * env, so providers extend it rather than reimplementing the contract.
+ *
+ * Factory attaches its own session setup to the returned sandbox, so the
+ * callback never has to wire it up. A callback may still pass its own
+ * `onStart`; it runs after factory's setup, against a prepared workspace.
+ *
+ * @example
+ * ```typescript
+ * sandbox: ({ sessionId, sandboxId }) => new E2BSandbox({ id: sessionId, sandboxId })
+ * ```
+ *
+ * A FactorySandbox instance (for example `new E2BFactorySandbox({ apiKey })`)
+ * additionally exposes settings and template builds to the environment.
+ */
+export type MastraFactorySandboxConfig = (ctx: FactorySandboxContext) => MastraSandbox;
+/**
+ * The `sandbox` option of `MastraFactoryConfig`: a FactorySandbox instance
+ * (it owns the session sandbox constructor, the repo template and the
+ * environment settings schema) or a bare callback, which the factory wraps as a `provider: 'custom'` sandbox with no settings.
+ */
+export type MastraFactorySandboxOption = FactorySandbox | MastraFactorySandboxConfig;
+/**
+ * What the start hook learned about the setup command before running the
+ * session setup, and how to record its completion afterwards.
+ */
+export interface SessionSetupGate {
+    /** True when the sandbox already carries a marker for the current setup command. */
+    setupDone: boolean;
+    /** Write the marker once the setup command succeeded. Best-effort. */
+    markSetupDone: () => Promise<void>;
+}
+/**
+ * The session's setup work, run against a started sandbox on EVERY start.
+ * Materialize and checkout are idempotent and must always run (a warm boot
+ * still needs its pull); only the setup command consults `gate`.
+ */
+export type SessionSetupRun = (sandbox: WorkspaceSandbox, workdir: string, gate: SessionSetupGate) => Promise<void>;
+/** One environment repository as the boot hook needs it: its slug and setup command. */
+export interface SessionEnvironmentRepository {
+    slug: string;
+    setupCommand?: string;
+}
+/** What the environment hook learned about one repository before the boot runs. */
+export interface SessionEnvironmentRepositoryGate extends SessionEnvironmentRepository {
+    /** `<root>/<repoDir>`, the directory the template cloned this repository into. */
+    dir: string;
+    gate: SessionSetupGate;
+}
+/** The environment hook's view of the workspace: the root, every repository in position order, the workspace gate. */
+export interface SessionEnvironmentGate {
+    /** The workspace root, parent of every repository directory. */
+    root: string;
+    repos: SessionEnvironmentRepositoryGate[];
+    /** Gate for `workspaceSetupCommand`; `setupDone` when there is no command or its marker matches. */
+    workspace: SessionSetupGate;
+}
+/** The list-form session boot: run on every start, like `SessionSetupRun`. */
+export type SessionEnvironmentSetupRun = (sandbox: WorkspaceSandbox, environment: SessionEnvironmentGate) => Promise<void>;
+/**
+ * Per-process session-id → sandbox instance memo.
+ *
+ * The provider contract is id-keyed getOrCreate, but provider find-then-create
+ * has a real double-create race across independent instances. Memoizing the
+ * instance per session makes the base class's per-instance start coalescing
+ * apply process-wide per session — the same single-flight scope the fleet's
+ * per-binding coalescing provided. Cross-replica races are accepted (the
+ * fleet was also per-replica).
+ */
+interface SessionSandboxEntry {
+    sandbox: WorkspaceSandbox;
+    /**
+     * The session's repo checkout root, recorded for passive readers (fs
+     * routes, capture, authz). Local sandboxes derive it at construction;
+     * remote sandboxes clone into the VM's own home, so it is undefined until
+     * `resolveSessionWorkdir` probes the first started VM — passive readers
+     * treat an unresolved workdir as "nothing materialized".
+     */
+    workdir?: string;
+    /** The session's own repository, the only one `workdir` is ever recorded for. */
+    ownRepo: string;
+    /** Environment repositories in position order; the session's own repository is among them. */
+    repos?: string[];
+}
+/** One environment repository as the file readers see it. */
+export interface SessionLayoutRepository {
+    slug: string;
+    /** Absolute checkout directory. */
+    dir: string;
+    /** Path prefix of this checkout under the layout root: empty for a single-repository session, `<dir>/` otherwise. */
+    prefix: string;
+}
+/**
+ * Where a session's files are read from. A session with one repository is
+ * rooted at that checkout, as before environments existed; a session with
+ * several is rooted at the workspace root with each checkout as a directory
+ * beneath it.
+ */
+export interface SessionLayout {
+    root: string;
+    repos: SessionLayoutRepository[];
+}
+/** The layout of a memoized session, `undefined` until its workdir resolved. */
+export declare function sessionLayout(entry: SessionSandboxEntry | undefined): SessionLayout | undefined;
+/**
+ * Get the session's memoized sandbox entry, constructing (and memoizing) it on
+ * first access. Construction is cheap and side-effect-free by contract; VMs
+ * are provisioned on `start()` only. Local sandboxes get their workdir here;
+ * remote workdirs are a runtime fact of the VM, resolved on first start.
+ */
+export declare function getSessionSandbox(sessionId: string, repoFullName: string, construct: () => WorkspaceSandbox, repos?: string[]): SessionSandboxEntry;
+/**
+ * Resolve (and memoize on the session entry) the session's repo checkout
+ * root. Local sandboxes answer synchronously from their configured
+ * `workingDirectory`; remote sandboxes clone into the VM's own default cwd,
+ * so the first resolution probes it with one `pwd` — the VM tells us where
+ * home is, we never invent a path. Calling this against a stopped sandbox
+ * lazily starts it (the probe is a command), so passive readers must peek
+ * `entry.workdir` instead. The memo is the session's own checkout; another
+ * environment repository lives beside it under the same root, so it is
+ * answered from the memo's parent without a second probe.
+ */
+export declare function resolveSessionWorkdir(sessionId: string, sandbox: WorkspaceSandbox, repoFullName: string): Promise<string>;
+/**
+ * The session's memoized sandbox (and its workdir) when one was already
+ * constructed in this process, else undefined. Never constructs — passive
+ * read paths use this so browsing files cannot provision a VM.
+ */
+export declare function peekSessionSandbox(sessionId: string): SessionSandboxEntry | undefined;
+/** Drop the memoized instance (on stop/destroy/retirement or construction failure). */
+export declare function evictSessionSandbox(sessionId: string): void;
+/** Test-only: reset the process-wide memo between tests. */
+export declare function __clearSessionSandboxesForTests(): void;
+export declare function recordFailedSetupCommand(sessionId: string, command: string): void;
+export declare function hasFailedSetupCommand(sessionId: string, command: string): boolean;
+/**
+ * Build the session setup hook, which factory attaches to the constructed
+ * sandbox with `setOnStart`. Runs inside the sandbox start lifecycle on
+ * every start, fresh VM or reconnect: materialize and checkout always run,
+ * and the setup command runs unless the sandbox already carries the marker
+ * for it (a warm template image, or an earlier successful start). Throwing
+ * fails `start()` loudly; core treats onStart errors as fatal.
+ */
+export declare function createSessionSetupHook(run: SessionSetupRun, sessionId: string, repoFullName: string, setupCommand: string | undefined): SandboxStartHook;
+/**
+ * The list-form start hook for a session whose factory has an environment:
+ * the same lifecycle as `createSessionSetupHook`, with one gate per
+ * repository plus one for the workspace setup command. The markers are the
+ * ones the multi-repo templates write (`.mastra-sandbox/repos/<repoDir>`,
+ * `.mastra-sandbox/workspace-setup`, `.mastra-sandbox/setup-failed`), all
+ * under the workspace root, which is the parent of the primary repository's
+ * directory: `resolveSessionWorkdir` keeps answering that directory so the
+ * PR tools and passive readers see the primary checkout, and the root is
+ * derived from it rather than probed twice.
+ *
+ * `repos` is in position order and must include the primary (`repoFullName`).
+ */
+export declare function createEnvironmentSetupHook(run: SessionEnvironmentSetupRun, sessionId: string, repoFullName: string, environment: {
+    repos: SessionEnvironmentRepository[];
+    workspaceSetupCommand?: string;
+}): SandboxStartHook;
+export {};
+//# sourceMappingURL=session-sandbox.d.ts.map

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

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