@mastra/factory 0.0.0-fix-thread-subscription-multi-instance-redis-streams-20260730204150

package/dist/rules/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","names":[],"sources":["../../src/rules/validation.ts"],"sourcesContent":["import {\n  FACTORY_GITHUB_EVENTS,\n  FACTORY_LINEAR_EVENTS,\n  FACTORY_RULE_BOARDS,\n  FACTORY_RULE_SOURCES,\n  FACTORY_RULE_STAGES,\n} from './types.js';\nimport type {\n  FactoryBoardRules,\n  FactoryCommitDecision,\n  FactoryRuleDecision,\n  FactoryRuleJsonValue,\n  FactoryRules,\n  FactoryRuleRejectionCode,\n  WorkItemSource,\n} from './types.js';\n\nexport const MAX_FACTORY_RULE_CAUSAL_DEPTH = 8;\n\nconst MAX_VERSION_LENGTH = 128;\nconst MAX_IDEMPOTENCY_KEY_LENGTH = 256;\nconst MAX_REASON_LENGTH = 512;\nconst MAX_TITLE_LENGTH = 512;\nconst MAX_MESSAGE_LENGTH = 8_192;\nconst MAX_ARGUMENTS_LENGTH = 4_096;\nconst MAX_ROLE_LENGTH = 32;\nconst MAX_SKILL_NAME_LENGTH = 128;\nconst MAX_SOURCE_KEY_LENGTH = 256;\nconst MAX_URL_LENGTH = 2_048;\nconst MAX_METADATA_JSON_LENGTH = 16_384;\nconst MAX_JSON_DEPTH = 8;\nconst MAX_JSON_COLLECTION_SIZE = 100;\n\nconst IDENTIFIER_RE = /^[a-z0-9][a-z0-9_-]*$/i;\nconst SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;\nconst SENSITIVE_KEY_RE = /(?:authorization|cookie|credential|password|secret|token)/i;\nconst WORK_ITEM_SOURCES: readonly WorkItemSource[] = ['github-issue', 'github-pr', 'linear-issue', 'manual'];\nconst REJECTION_CODES: readonly FactoryRuleRejectionCode[] = [\n  'forbidden',\n  'invalid_transition',\n  'missing_binding',\n  'stale',\n  'timeout',\n  'rule_error',\n  'causal_depth_exceeded',\n  'repeated_transition',\n];\n\nexport class FactoryRuleValidationError extends Error {\n  readonly code = 'invalid_factory_rule';\n\n  constructor(message: string) {\n    super(message);\n    this.name = 'FactoryRuleValidationError';\n  }\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;\n  const prototype = Object.getPrototypeOf(value);\n  return prototype === Object.prototype || prototype === null;\n}\n\nfunction assertExactKeys(value: Record<string, unknown>, keys: readonly string[], label: string): void {\n  const allowed = new Set(keys);\n  if (Object.keys(value).some(key => !allowed.has(key))) {\n    throw new FactoryRuleValidationError(`${label} contains an unsupported field.`);\n  }\n}\n\nfunction boundedString(value: unknown, label: string, max: number, pattern?: RegExp): string {\n  if (typeof value !== 'string') throw new FactoryRuleValidationError(`${label} must be a string.`);\n  const normalized = value.trim();\n  if (normalized.length === 0 || normalized.length > max || (pattern && !pattern.test(normalized))) {\n    throw new FactoryRuleValidationError(`${label} is invalid.`);\n  }\n  return normalized;\n}\n\nfunction optionalBoundedString(value: unknown, label: string, max: number): string | undefined {\n  if (value === undefined) return undefined;\n  return boundedString(value, label, max);\n}\n\nfunction enumValue<T extends string>(value: unknown, allowed: readonly T[], label: string): T {\n  if (typeof value !== 'string' || !allowed.includes(value as T)) {\n    throw new FactoryRuleValidationError(`${label} is invalid.`);\n  }\n  return value as T;\n}\n\nexport function normalizeFactoryRuleJsonValue(\n  value: unknown,\n  depth = 0,\n  seen = new Set<object>(),\n): FactoryRuleJsonValue {\n  if (value === null || typeof value === 'boolean' || typeof value === 'string') return value;\n  if (typeof value === 'number') {\n    if (!Number.isFinite(value)) throw new FactoryRuleValidationError('Rule metadata must contain finite numbers.');\n    return value;\n  }\n  if (depth >= MAX_JSON_DEPTH || (typeof value !== 'object' && !Array.isArray(value))) {\n    throw new FactoryRuleValidationError('Rule metadata is not bounded JSON.');\n  }\n  if (seen.has(value as object)) throw new FactoryRuleValidationError('Rule metadata must not contain cycles.');\n  seen.add(value as object);\n  try {\n    if (Array.isArray(value)) {\n      if (value.length > MAX_JSON_COLLECTION_SIZE) {\n        throw new FactoryRuleValidationError('Rule metadata contains too many entries.');\n      }\n      return value.map(entry => normalizeFactoryRuleJsonValue(entry, depth + 1, seen));\n    }\n    if (!isPlainObject(value)) throw new FactoryRuleValidationError('Rule metadata must use plain objects.');\n    const entries = Object.entries(value);\n    if (entries.length > MAX_JSON_COLLECTION_SIZE) {\n      throw new FactoryRuleValidationError('Rule metadata contains too many fields.');\n    }\n    const sanitized: Record<string, FactoryRuleJsonValue> = {};\n    for (const [key, entry] of entries) {\n      const normalizedKey = boundedString(key, 'Rule metadata key', 128, IDENTIFIER_RE);\n      sanitized[normalizedKey] = SENSITIVE_KEY_RE.test(normalizedKey)\n        ? '[REDACTED]'\n        : normalizeFactoryRuleJsonValue(entry, depth + 1, seen);\n    }\n    return sanitized;\n  } finally {\n    seen.delete(value as object);\n  }\n}\n\nfunction sanitizeMetadata(value: unknown): Record<string, FactoryRuleJsonValue> | undefined {\n  if (value === undefined) return undefined;\n  const sanitized = normalizeFactoryRuleJsonValue(value);\n  if (!isPlainObject(sanitized)) throw new FactoryRuleValidationError('Rule metadata must be an object.');\n  if (JSON.stringify(sanitized).length > MAX_METADATA_JSON_LENGTH) {\n    throw new FactoryRuleValidationError('Rule metadata is too large.');\n  }\n  return sanitized;\n}\n\nfunction validateBoardRules(rules: unknown, label: string): asserts rules is FactoryBoardRules {\n  if (!isPlainObject(rules)) throw new FactoryRuleValidationError(`${label} must be an object.`);\n  for (const [stage, sources] of Object.entries(rules)) {\n    enumValue(stage, FACTORY_RULE_STAGES, `${label} stage`);\n    if (!isPlainObject(sources)) throw new FactoryRuleValidationError(`${label}.${stage} must be an object.`);\n    for (const [source, leaf] of Object.entries(sources)) {\n      enumValue(source, FACTORY_RULE_SOURCES, `${label}.${stage} source`);\n      if (!isPlainObject(leaf)) throw new FactoryRuleValidationError(`${label}.${stage}.${source} must be an object.`);\n      assertExactKeys(leaf, ['onEnter', 'onExit'], `${label}.${stage}.${source}`);\n      for (const handler of Object.values(leaf)) {\n        if (handler !== undefined && typeof handler !== 'function') {\n          throw new FactoryRuleValidationError(`${label}.${stage}.${source} handlers must be functions.`);\n        }\n      }\n    }\n  }\n}\n\nexport function assertFactoryRules(rules: unknown): asserts rules is FactoryRules {\n  if (!isPlainObject(rules)) throw new FactoryRuleValidationError('Factory rules must be an object.');\n  assertExactKeys(rules, ['version', 'work', 'review', 'tools', 'github', 'linear'], 'Factory rules');\n  boundedString(rules.version, 'Factory rule version', MAX_VERSION_LENGTH);\n  validateBoardRules(rules.work, 'Factory rules.work');\n  validateBoardRules(rules.review, 'Factory rules.review');\n\n  if (!isPlainObject(rules.tools)) throw new FactoryRuleValidationError('Factory rules.tools must be an object.');\n  for (const [toolName, leaf] of Object.entries(rules.tools)) {\n    boundedString(toolName, 'Factory tool name', 128, IDENTIFIER_RE);\n    if (!isPlainObject(leaf))\n      throw new FactoryRuleValidationError(`Factory rules.tools.${toolName} must be an object.`);\n    assertExactKeys(leaf, ['onResult'], `Factory rules.tools.${toolName}`);\n    if (leaf.onResult !== undefined && typeof leaf.onResult !== 'function') {\n      throw new FactoryRuleValidationError(`Factory rules.tools.${toolName}.onResult must be a function.`);\n    }\n  }\n\n  if (!isPlainObject(rules.github)) throw new FactoryRuleValidationError('Factory rules.github must be an object.');\n  for (const [event, leaf] of Object.entries(rules.github)) {\n    enumValue(event, FACTORY_GITHUB_EVENTS, 'Factory GitHub event');\n    if (!isPlainObject(leaf)) throw new FactoryRuleValidationError(`Factory rules.github.${event} must be an object.`);\n    assertExactKeys(leaf, ['onEvent'], `Factory rules.github.${event}`);\n    if (leaf.onEvent !== undefined && typeof leaf.onEvent !== 'function') {\n      throw new FactoryRuleValidationError(`Factory rules.github.${event}.onEvent must be a function.`);\n    }\n  }\n\n  if (!isPlainObject(rules.linear)) throw new FactoryRuleValidationError('Factory rules.linear must be an object.');\n  for (const [event, leaf] of Object.entries(rules.linear)) {\n    enumValue(event, FACTORY_LINEAR_EVENTS, 'Factory Linear event');\n    if (!isPlainObject(leaf)) throw new FactoryRuleValidationError(`Factory rules.linear.${event} must be an object.`);\n    assertExactKeys(leaf, ['onEvent'], `Factory rules.linear.${event}`);\n    if (leaf.onEvent !== undefined && typeof leaf.onEvent !== 'function') {\n      throw new FactoryRuleValidationError(`Factory rules.linear.${event}.onEvent must be a function.`);\n    }\n  }\n}\n\nfunction commonCommitFields(value: Record<string, unknown>): { idempotencyKey: string } {\n  return {\n    idempotencyKey: boundedString(value.idempotencyKey, 'Factory decision idempotencyKey', MAX_IDEMPOTENCY_KEY_LENGTH),\n  };\n}\n\nexport function validateFactoryRuleDecision(value: unknown, causalDepth = 0): FactoryRuleDecision {\n  if (causalDepth > MAX_FACTORY_RULE_CAUSAL_DEPTH) {\n    throw new FactoryRuleValidationError('Factory rule causal depth exceeded.');\n  }\n  if (!isPlainObject(value)) throw new FactoryRuleValidationError('Factory rule decision must be an object.');\n  const type = value.type;\n  if (typeof type !== 'string') throw new FactoryRuleValidationError('Factory rule decision type is required.');\n\n  switch (type) {\n    case 'reject': {\n      assertExactKeys(value, ['type', 'code', 'reason'], 'Factory reject decision');\n      return {\n        type,\n        code: enumValue(value.code, REJECTION_CODES, 'Factory rejection code'),\n        reason: boundedString(value.reason, 'Factory rejection reason', MAX_REASON_LENGTH),\n      };\n    }\n    case 'transition': {\n      assertExactKeys(value, ['type', 'idempotencyKey', 'board', 'stage', 'message'], 'Factory transition decision');\n      let message: { text: string; role?: string } | undefined;\n      if (value.message !== undefined) {\n        if (!isPlainObject(value.message)) {\n          throw new FactoryRuleValidationError('Factory transition message must be an object.');\n        }\n        assertExactKeys(value.message, ['text', 'role'], 'Factory transition message');\n        const role =\n          value.message.role === undefined\n            ? undefined\n            : boundedString(value.message.role, 'Factory transition message role', MAX_ROLE_LENGTH, IDENTIFIER_RE);\n        message = {\n          text: boundedString(value.message.text, 'Factory transition message text', MAX_MESSAGE_LENGTH),\n          ...(role ? { role } : {}),\n        };\n      }\n      return {\n        type,\n        ...commonCommitFields(value),\n        board: enumValue(value.board, FACTORY_RULE_BOARDS, 'Factory transition board'),\n        stage: enumValue(value.stage, FACTORY_RULE_STAGES, 'Factory transition stage'),\n        ...(message ? { message } : {}),\n      };\n    }\n    case 'upsertLinkedWorkItem': {\n      assertExactKeys(\n        value,\n        ['type', 'idempotencyKey', 'board', 'source', 'sourceKey', 'title', 'url', 'stage', 'metadata'],\n        'Factory linked work item decision',\n      );\n      const url = value.url;\n      if (url !== null && (typeof url !== 'string' || url.length > MAX_URL_LENGTH || !/^https?:\\/\\//.test(url))) {\n        throw new FactoryRuleValidationError('Factory linked work item URL is invalid.');\n      }\n      const metadata = sanitizeMetadata(value.metadata);\n      return {\n        type,\n        ...commonCommitFields(value),\n        board: enumValue(value.board, FACTORY_RULE_BOARDS, 'Factory linked work item board'),\n        source: enumValue(value.source, WORK_ITEM_SOURCES, 'Factory linked work item source'),\n        sourceKey: boundedString(value.sourceKey, 'Factory linked work item sourceKey', MAX_SOURCE_KEY_LENGTH),\n        title: boundedString(value.title, 'Factory linked work item title', MAX_TITLE_LENGTH),\n        url,\n        stage: enumValue(value.stage, FACTORY_RULE_STAGES, 'Factory linked work item stage'),\n        ...(metadata ? { metadata } : {}),\n      };\n    }\n    case 'invokeSkill': {\n      assertExactKeys(\n        value,\n        ['type', 'idempotencyKey', 'role', 'skillName', 'arguments', 'precedingMessage'],\n        'Factory invoke skill decision',\n      );\n      const args = optionalBoundedString(value.arguments, 'Factory skill arguments', MAX_ARGUMENTS_LENGTH);\n      const precedingMessage = optionalBoundedString(\n        value.precedingMessage,\n        'Factory skill preceding message',\n        MAX_MESSAGE_LENGTH,\n      );\n      return {\n        type,\n        ...commonCommitFields(value),\n        role: boundedString(value.role, 'Factory skill role', MAX_ROLE_LENGTH, IDENTIFIER_RE),\n        skillName: boundedString(value.skillName, 'Factory skill name', MAX_SKILL_NAME_LENGTH, SKILL_NAME_RE),\n        ...(args ? { arguments: args } : {}),\n        ...(precedingMessage ? { precedingMessage } : {}),\n      };\n    }\n    case 'sendMessage': {\n      assertExactKeys(\n        value,\n        ['type', 'idempotencyKey', 'role', 'message', 'priority', 'idleBehavior', 'prepareBinding'],\n        'Factory send message decision',\n      );\n      const priority =\n        value.priority === undefined\n          ? undefined\n          : enumValue(value.priority, ['medium', 'high', 'urgent'] as const, 'Factory message priority');\n      const idleBehavior =\n        value.idleBehavior === undefined\n          ? undefined\n          : enumValue(value.idleBehavior, ['persist', 'wake'] as const, 'Factory message idle behavior');\n      if (value.prepareBinding !== undefined && typeof value.prepareBinding !== 'boolean') {\n        throw new FactoryRuleValidationError('Factory message prepareBinding must be a boolean.');\n      }\n      return {\n        type,\n        ...commonCommitFields(value),\n        role: boundedString(value.role, 'Factory message role', MAX_ROLE_LENGTH, IDENTIFIER_RE),\n        message: boundedString(value.message, 'Factory message', MAX_MESSAGE_LENGTH),\n        ...(priority ? { priority } : {}),\n        ...(idleBehavior ? { idleBehavior } : {}),\n        ...(value.prepareBinding === true ? { prepareBinding: true } : {}),\n      };\n    }\n    case 'notify': {\n      assertExactKeys(value, ['type', 'idempotencyKey', 'title', 'body', 'level'], 'Factory notify decision');\n      const body = optionalBoundedString(value.body, 'Factory notification body', MAX_MESSAGE_LENGTH);\n      const level =\n        value.level === undefined\n          ? undefined\n          : enumValue(value.level, ['info', 'warning', 'error'] as const, 'Factory notification level');\n      return {\n        type,\n        ...commonCommitFields(value),\n        title: boundedString(value.title, 'Factory notification title', MAX_TITLE_LENGTH),\n        ...(body ? { body } : {}),\n        ...(level ? { level } : {}),\n      };\n    }\n    default:\n      throw new FactoryRuleValidationError('Factory rule decision type is unsupported.');\n  }\n}\n\nexport function validateFactoryRuleDecisions(values: readonly unknown[], causalDepth = 0): FactoryCommitDecision[] {\n  if (values.length > MAX_JSON_COLLECTION_SIZE) {\n    throw new FactoryRuleValidationError('Factory rule produced too many decisions.');\n  }\n  const decisions: FactoryCommitDecision[] = [];\n  for (const value of values) {\n    const decision = validateFactoryRuleDecision(value, causalDepth);\n    if (decision.type === 'reject') {\n      throw new FactoryRuleValidationError('A rejection cannot be persisted with commit decisions.');\n    }\n    decisions.push(decision);\n  }\n  const keys = decisions.map(decision => decision.idempotencyKey);\n  if (new Set(keys).size !== keys.length) {\n    throw new FactoryRuleValidationError('Factory decisions require unique idempotency keys.');\n  }\n  return decisions;\n}\n"],"mappings":"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"}

package/dist/sandbox/fleet.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Project sandbox fleet: provisioning, reattach, teardown, and budgeting.
+ *
+ * Server-hosted projects never run on the web host itself. Each project gets
+ * its own isolated sandbox (a `WorkspaceSandbox`, e.g. a Railway VM) `clone()`d
+ * from the machine the factory was configured with. This module owns everything
+ * about that fleet — which provider is active, where checkouts live inside a
+ * sandbox, the idle window, the per-replica budget, and the
+ * provision/reattach/teardown lifecycle — but knows nothing about what runs
+ * inside a sandbox (git materialization lives with its feature, e.g. the
+ * GitHub integration's `sandbox.ts`).
+ *
+ * The fleet is constructed once at boot with the machine config (or none, when
+ * sandboxes are disabled) and handed to consumers — no global registry.
+ * Persistence of the provider's reattach id is delegated to the caller via
+ * {@link SandboxBindingStore}, so the fleet stays storage-agnostic. Tests can
+ * swap the low-level construction via {@link SandboxFleet.setFactory}.
+ */
+import type { WorkspaceSandbox } from '@mastra/core/workspace';
+/** Minimal command result shape sandbox consumers depend on. */
+export interface SandboxCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Minimal live-sandbox surface fleet consumers need: an id, a way to start it,
+ * a way to learn the provider's reattach id, and command execution.
+ */
+export interface MaterializationSandbox {
+    readonly id: string;
+    start(): Promise<void>;
+    getInfo(): Promise<{
+        metadata?: Record<string, unknown>;
+    }>;
+    executeCommand(command: string, args?: string[], options?: {
+        timeout?: number;
+        env?: Record<string, string | undefined>;
+    }): Promise<SandboxCommandResult>;
+    /** Update an environment variable for future commands in this sandbox. */
+    setEnvironmentVariable?(name: string, value: string): void;
+    /** Tear down the underlying VM. Optional: providers without it are no-ops. */
+    stop?(): Promise<void>;
+}
+/** Options for building (or reattaching) one sandbox. */
+export interface SandboxCreateOptions {
+    /** Reattach to this existing provider VM instead of provisioning a new one. */
+    providerSandboxId?: string;
+    /**
+     * Environment variables for commands run in the sandbox. Adapter-level
+     * only: merged into every `executeCommand`, never baked into the provider
+     * VM (see `SandboxFleet.#build`).
+     */
+    env?: Record<string, string>;
+    /** Provider working directory for this sandbox. */
+    workingDirectory?: string;
+    /** Idle teardown window (minutes). The provider stops the VM after this idle period. */
+    idleTimeoutMinutes?: number;
+    /** Provider checkpoint used to seed and preserve this sandbox's filesystem. */
+    checkpointName?: string;
+}
+/**
+ * A coarse-grained step of the sandbox-preparation flow, reported as it happens
+ * so the UI can show the user what the server is doing instead of a static
+ * "Preparing…" toast. `phase` is a stable machine token; `message` is
+ * user-facing copy.
+ */
+export interface PrepareProgress {
+    phase: 'reattaching' | 'provisioning' | 'preparing-workspace' | 'cloning' | 'pulling' | 'finalizing' | 'done';
+    message: string;
+}
+/** Callback invoked with each preparation step. Best-effort; never throws. */
+export type ProgressFn = (event: PrepareProgress) => void;
+/** Invoke a progress callback without letting it break the actual work. */
+export declare function reportProgress(onProgress: ProgressFn | undefined, event: PrepareProgress): void;
+/**
+ * Factory that builds a (not-yet-started) sandbox. When `providerSandboxId` is
+ * provided the sandbox should reattach to that existing VM instead of
+ * provisioning a new one.
+ */
+export type SandboxFactory = (opts: SandboxCreateOptions) => MaterializationSandbox;
+/** Raised when provisioning would exceed the per-replica sandbox budget. */
+export declare class SandboxBudgetError extends Error {
+    readonly max: number;
+    readonly code: "sandbox-budget-exceeded";
+    constructor(max: number);
+}
+/** Optional knobs for provisioning/reattaching one sandbox. */
+export interface EnsureSandboxOptions {
+    /** Provider working directory for this sandbox. */
+    workingDirectory?: string;
+}
+/**
+ * Where a feature persists its sandbox binding. The fleet reads the stored
+ * reattach id and writes updates through this seam so it stays agnostic of
+ * the owning table (GitHub projects today, anything else tomorrow).
+ */
+export interface SandboxBindingStore {
+    /** Stored provider reattach id from a previous provisioning, if any. */
+    readonly sandboxId: string | null;
+    /** Provider checkpoint used to seed and preserve this sandbox's filesystem. */
+    readonly checkpointName?: string;
+    /** Persist a freshly provisioned provider id, or clear a stale one with `null`. */
+    setSandboxId(id: string | null): Promise<void>;
+    /** Clear all stored sandbox state (reattach id + materialization mark) on teardown. */
+    clear(): Promise<void>;
+}
+/** Resolve a workdir under `root`, refusing any path that escapes the configured root. */
+export declare function resolveContainedLocalWorkdir(root: string, ...segments: string[]): string;
+/**
+ * Factory-resolved sandbox runtime the fleet is constructed with: the machine
+ * projects clone their per-project sandboxes from, plus the knobs the factory
+ * resolved around it.
+ */
+export interface SandboxFleetConfig {
+    /**
+     * Template machine (validated by the factory to implement `clone()`).
+     * Never started — acts purely as the credential/default holder that
+     * per-project sandboxes are cloned from.
+     */
+    machine: WorkspaceSandbox;
+    /** In-sandbox base directory repos check out under (no trailing slash). */
+    workdirBase: string;
+    /** Per-replica cap on concurrently provisioned sandboxes. 0 = unlimited. */
+    maxSandboxes?: number;
+}
+/**
+ * The sandbox fleet for one deployment. Constructed once at boot — with a
+ * config when a sandbox machine was configured, or without one when sandboxes
+ * are disabled (every provisioning entry point then throws and
+ * {@link enabled} reports `false` so features stay off).
+ */
+export declare class SandboxFleet {
+    #private;
+    constructor(config?: SandboxFleetConfig);
+    /**
+     * True when a sandbox machine was configured. The factory validates the
+     * machine implements `clone()` at boot, so a configured fleet is usable —
+     * sandbox-backed projects stay off only when the slot was omitted.
+     */
+    get enabled(): boolean;
+    /**
+     * Name of the active sandbox provider — the configured machine's `provider`
+     * discriminator (`'railway'`, `'local'`, …), or `'none'` when the fleet was
+     * constructed without a config. Diagnostic only; feature gating goes
+     * through {@link enabled}.
+     */
+    get provider(): string;
+    /**
+     * Idle teardown window for provisioned sandboxes, in minutes; defaults to 30.
+     * Read back from the machine's own config when it exposes one
+     * (Railway's `idleTimeoutMinutes`) — the knob lives on the sandbox, the
+     * fleet only needs it to schedule GC and stamp sandbox clones. Advisory:
+     * providers without idle GC ignore it, and a re-open detects a torn-down VM
+     * and re-provisions cleanly.
+     */
+    get idleMinutes(): number;
+    /**
+     * Per-replica cap on concurrently *provisioned* sandboxes. 0 means unlimited.
+     * This is a lightweight per-process budget to keep a single replica from
+     * exhausting provider quota — it is not a global, cross-replica scheduler
+     * (that is a deferred follow-up).
+     */
+    get maxSandboxes(): number;
+    /**
+     * Count of sandboxes this fleet has freshly provisioned and not yet torn
+     * down. Reattaches to existing VMs do not count (they reuse an already-billed
+     * sandbox). Used to enforce {@link maxSandboxes}.
+     */
+    get liveCount(): number;
+    /** For tests: reset the live-sandbox counter to a known state. */
+    __resetLiveCount(value?: number): void;
+    /** Override the sandbox factory (tests). */
+    setFactory(factory: SandboxFactory): void;
+    /** Reset to the default machine-cloning factory. */
+    resetFactory(): void;
+    /**
+     * Compute the in-sandbox working directory for a repo: a nested
+     * `<base>/<owner>/<name>` layout under the factory-resolved checkout base.
+     * Nesting keeps same-name repos apart (`acme/api` vs `other/api`) — cloud
+     * sandboxes are one-per-project so it's merely tidy there, but local
+     * checkouts share one host root where it prevents collisions. Server-side
+     * only; never derived from client input.
+     */
+    computeWorkdir(repoFullName: string): string;
+    /**
+     * Compute the host working directory for a local GitHub session checkout.
+     * This is server-derived only: repo pieces are sanitized and the trusted
+     * session id is kept as a single path segment under the configured local root.
+     */
+    computeLocalSessionWorkdir(repoFullName: string, sessionId: string): string;
+    /**
+     * Provision a new sandbox (persisting its provider id on first open) or
+     * reattach to the stored one. Returns a started, live sandbox.
+     *
+     * Concurrent calls for the same binding coalesce onto one in-flight
+     * provision/reattach and share its sandbox handle — N simultaneous requests
+     * for one cold session (e.g. several browser tabs polling right after boot)
+     * must not each fire their own `POST /sandbox` against the provider.
+     * Failures are not cached: once the shared attempt settles, the next call
+     * starts fresh.
+     */
+    ensureSandbox(store: SandboxBindingStore, onProgress?: ProgressFn): Promise<MaterializationSandbox>;
+    ensureSandbox(store: SandboxBindingStore, env?: Record<string, string>, onProgress?: ProgressFn, options?: EnsureSandboxOptions): Promise<MaterializationSandbox>;
+    /**
+     * Tear down a sandbox binding: stop the live VM (best-effort) and clear the
+     * persisted state through the binding store so the next open re-provisions
+     * cleanly. Decrements the per-replica live-sandbox counter.
+     *
+     * @param store   the binding to tear down
+     * @param sandbox an already-reattached live sandbox to stop, when available
+     */
+    teardownSandbox(store: SandboxBindingStore, sandbox?: MaterializationSandbox): Promise<void>;
+    /**
+     * Reattach to an already-provisioned sandbox by its provider id and start it.
+     * Used by the workspace seam when opening a project that was already
+     * materialized (sandbox id + workdir carried on controller state), so no DB
+     * round-trip is needed.
+     */
+    reattachSandbox(providerSandboxId: string, options?: EnsureSandboxOptions): Promise<MaterializationSandbox>;
+}
+//# sourceMappingURL=fleet.d.ts.map

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

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

package/dist/sandbox/fleet.js

@@ -0,0 +1,322 @@
+import path from "path";
+//#region src/sandbox/fleet.ts
+/**
+* Project sandbox fleet: provisioning, reattach, teardown, and budgeting.
+*
+* Server-hosted projects never run on the web host itself. Each project gets
+* its own isolated sandbox (a `WorkspaceSandbox`, e.g. a Railway VM) `clone()`d
+* from the machine the factory was configured with. This module owns everything
+* about that fleet — which provider is active, where checkouts live inside a
+* sandbox, the idle window, the per-replica budget, and the
+* provision/reattach/teardown lifecycle — but knows nothing about what runs
+* inside a sandbox (git materialization lives with its feature, e.g. the
+* GitHub integration's `sandbox.ts`).
+*
+* The fleet is constructed once at boot with the machine config (or none, when
+* sandboxes are disabled) and handed to consumers — no global registry.
+* Persistence of the provider's reattach id is delegated to the caller via
+* {@link SandboxBindingStore}, so the fleet stays storage-agnostic. Tests can
+* swap the low-level construction via {@link SandboxFleet.setFactory}.
+*/
+/** Invoke a progress callback without letting it break the actual work. */
+function reportProgress(onProgress, event) {
+	if (!onProgress) return;
+	try {
+		onProgress(event);
+	} catch {}
+}
+/** Raised when provisioning would exceed the per-replica sandbox budget. */
+var SandboxBudgetError = class extends Error {
+	max;
+	code = "sandbox-budget-exceeded";
+	constructor(max) {
+		super(`Sandbox budget exceeded: this server already has ${max} active sandbox(es), the configured per-replica maximum. Close an existing repository's sandbox and try again.`);
+		this.max = max;
+		this.name = "SandboxBudgetError";
+	}
+};
+/**
+* Stable identity for one binding's in-flight provision work, used to coalesce
+* concurrent `ensureSandbox` calls. Prefer `checkpointName` — it is a pure
+* function of the owning session and is set before the first provision, which
+* is exactly when the herd forms (the stored `sandboxId` is still null then).
+* Fall back to the stored provider id, and skip coalescing entirely for
+* bindings with neither: keying those on a shared constant would wrongly
+* funnel *different* bindings onto one sandbox.
+*/
+function coalesceKey(store) {
+	if (store.checkpointName) return `checkpoint:${store.checkpointName}`;
+	if (store.sandboxId) return `sandbox:${store.sandboxId}`;
+}
+/**
+* Adapt a cloned `WorkspaceSandbox` to the minimal surface this module needs.
+* Lifecycle goes through the `_`-prefixed wrappers when present (they add
+* status tracking and concurrency safety on `MastraSandbox` subclasses),
+* falling back to the plain methods for interface-only implementations.
+*/
+function toMaterializationSandbox(sandbox, initialEnvironment = {}) {
+	if (typeof sandbox.executeCommand !== "function") throw new Error(`Sandbox provider '${sandbox.provider}' does not implement executeCommand() — cannot materialize repos.`);
+	const lifecycle = sandbox;
+	const environment = { ...initialEnvironment };
+	return {
+		id: sandbox.id,
+		start: async () => {
+			await (lifecycle._start ?? sandbox.start)?.call(sandbox);
+		},
+		getInfo: async () => await sandbox.getInfo?.() ?? {},
+		executeCommand: (command, args, options) => sandbox.executeCommand(command, args, {
+			...options,
+			env: {
+				...environment,
+				...options?.env
+			}
+		}),
+		setEnvironmentVariable: (name, value) => {
+			environment[name] = value;
+		},
+		stop: async () => {
+			await (lifecycle._stop ?? sandbox.stop)?.call(sandbox);
+		}
+	};
+}
+/**
+* The provider's reattach id for a started sandbox. For Railway this is the
+* underlying `railwaySandboxId` in `getInfo().metadata`. Providers without a
+* provider-native id (e.g. local) reattach by construction id, so fall back
+* to the sandbox's own logical id.
+*/
+async function readProviderSandboxId(sandbox) {
+	const info = await sandbox.getInfo();
+	const id = info.metadata?.railwaySandboxId ?? info.metadata?.sandboxId;
+	return typeof id === "string" ? id : sandbox.id;
+}
+/** Keep each path piece a single safe segment (no separators or traversal). */
+function sanitizeSegment(segment) {
+	return segment.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^\.+/, "") || "repo";
+}
+/** Resolve a workdir under `root`, refusing any path that escapes the configured root. */
+function resolveContainedLocalWorkdir(root, ...segments) {
+	const resolvedRoot = path.resolve(root);
+	const resolved = path.resolve(resolvedRoot, ...segments);
+	if (resolved !== resolvedRoot && resolved.startsWith(`${resolvedRoot}${path.sep}`)) return resolved;
+	throw new Error(`Refusing to use local sandbox path outside configured root: ${resolved}`);
+}
+/**
+* The sandbox fleet for one deployment. Constructed once at boot — with a
+* config when a sandbox machine was configured, or without one when sandboxes
+* are disabled (every provisioning entry point then throws and
+* {@link enabled} reports `false` so features stay off).
+*/
+var SandboxFleet = class {
+	#config;
+	#factory;
+	#liveCount = 0;
+	/** In-flight `ensureSandbox` work, keyed per binding so concurrent callers coalesce. */
+	#inflight = /* @__PURE__ */ new Map();
+	constructor(config) {
+		this.#config = config;
+	}
+	/**
+	* True when a sandbox machine was configured. The factory validates the
+	* machine implements `clone()` at boot, so a configured fleet is usable —
+	* sandbox-backed projects stay off only when the slot was omitted.
+	*/
+	get enabled() {
+		return this.#config !== void 0;
+	}
+	/**
+	* Name of the active sandbox provider — the configured machine's `provider`
+	* discriminator (`'railway'`, `'local'`, …), or `'none'` when the fleet was
+	* constructed without a config. Diagnostic only; feature gating goes
+	* through {@link enabled}.
+	*/
+	get provider() {
+		return this.#config?.machine.provider ?? "none";
+	}
+	/**
+	* Idle teardown window for provisioned sandboxes, in minutes; defaults to 30.
+	* Read back from the machine's own config when it exposes one
+	* (Railway's `idleTimeoutMinutes`) — the knob lives on the sandbox, the
+	* fleet only needs it to schedule GC and stamp sandbox clones. Advisory:
+	* providers without idle GC ignore it, and a re-open detects a torn-down VM
+	* and re-provisions cleanly.
+	*/
+	get idleMinutes() {
+		const minutes = (this.#config?.machine)?.idleTimeoutMinutes;
+		return typeof minutes === "number" && Number.isFinite(minutes) && minutes > 0 ? minutes : 30;
+	}
+	/**
+	* Per-replica cap on concurrently *provisioned* sandboxes. 0 means unlimited.
+	* This is a lightweight per-process budget to keep a single replica from
+	* exhausting provider quota — it is not a global, cross-replica scheduler
+	* (that is a deferred follow-up).
+	*/
+	get maxSandboxes() {
+		return this.#config?.maxSandboxes ?? 0;
+	}
+	/**
+	* Count of sandboxes this fleet has freshly provisioned and not yet torn
+	* down. Reattaches to existing VMs do not count (they reuse an already-billed
+	* sandbox). Used to enforce {@link maxSandboxes}.
+	*/
+	get liveCount() {
+		return this.#liveCount;
+	}
+	/** For tests: reset the live-sandbox counter to a known state. */
+	__resetLiveCount(value = 0) {
+		this.#liveCount = value;
+	}
+	/** Override the sandbox factory (tests). */
+	setFactory(factory) {
+		this.#factory = factory;
+	}
+	/** Reset to the default machine-cloning factory. */
+	resetFactory() {
+		this.#factory = void 0;
+	}
+	/**
+	* Compute the in-sandbox working directory for a repo: a nested
+	* `<base>/<owner>/<name>` layout under the factory-resolved checkout base.
+	* Nesting keeps same-name repos apart (`acme/api` vs `other/api`) — cloud
+	* sandboxes are one-per-project so it's merely tidy there, but local
+	* checkouts share one host root where it prevents collisions. Server-side
+	* only; never derived from client input.
+	*/
+	computeWorkdir(repoFullName) {
+		if (!this.#config) throw new Error("No sandbox configured");
+		const [owner, name] = repoFullName.split("/", 2);
+		return `${this.#config.workdirBase}/${sanitizeSegment(owner || "unknown")}/${sanitizeSegment(name || "repo")}`;
+	}
+	/**
+	* Compute the host working directory for a local GitHub session checkout.
+	* This is server-derived only: repo pieces are sanitized and the trusted
+	* session id is kept as a single path segment under the configured local root.
+	*/
+	computeLocalSessionWorkdir(repoFullName, sessionId) {
+		if (!this.#config) throw new Error("No sandbox configured");
+		if (this.#config.machine.provider !== "local") throw new Error("Local session workdirs require the local sandbox provider");
+		const localRoot = this.#config.machine.workingDirectory;
+		if (typeof localRoot !== "string" || localRoot.length === 0) throw new Error("Local sandbox working directory is not configured");
+		const [owner, name] = repoFullName.split("/", 2);
+		return resolveContainedLocalWorkdir(localRoot, "github-sessions", sanitizeSegment(owner || "unknown"), sanitizeSegment(name || "repo"), sanitizeSegment(sessionId));
+	}
+	/**
+	* Build a (not-yet-started) sandbox: the test-provided factory when set,
+	* otherwise a per-project clone of the configured machine. The stored id is
+	* passed both as the logical `id` (providers that reattach by construction
+	* id, e.g. local) and as the provider-native `sandboxId` hint (Railway) so
+	* reattach works across the provider matrix.
+	*
+	* `env` is deliberately NOT forwarded to the provider clone: remote
+	* providers bake creation-time env into the VM for its whole lifetime
+	* (`POST /sandbox`), which would persist credentials like `GH_TOKEN` inside
+	* a VM that can outlive the session and be reused by another user via the
+	* sandbox pool. Instead the env lives only on the adapter, which merges it
+	* into every `executeCommand` — commands see the (refreshable) token, but
+	* the VM itself never stores it.
+	*/
+	#build(opts) {
+		if (this.#factory) return this.#factory(opts);
+		if (!this.#config) throw new Error("No sandbox configured");
+		return toMaterializationSandbox(this.#config.machine.clone({
+			...opts.providerSandboxId ? {
+				id: opts.providerSandboxId,
+				sandboxId: opts.providerSandboxId
+			} : {},
+			...opts.workingDirectory ? { workingDirectory: opts.workingDirectory } : {},
+			...opts.idleTimeoutMinutes !== void 0 ? { idleTimeoutMinutes: opts.idleTimeoutMinutes } : {},
+			...opts.checkpointName ? { checkpointName: opts.checkpointName } : {}
+		}), opts.env);
+	}
+	async ensureSandbox(store, envOrProgress, progressOrOptions, maybeOptions = {}) {
+		const env = typeof envOrProgress === "function" ? void 0 : envOrProgress;
+		const onProgress = typeof envOrProgress === "function" ? envOrProgress : progressOrOptions;
+		const options = typeof envOrProgress === "function" ? progressOrOptions ?? {} : maybeOptions;
+		const key = coalesceKey(store);
+		if (!key) return this.#ensureSandboxUncoalesced(store, env, onProgress, options);
+		const existing = this.#inflight.get(key);
+		if (existing) return existing;
+		const promise = this.#ensureSandboxUncoalesced(store, env, onProgress, options).finally(() => {
+			if (this.#inflight.get(key) === promise) this.#inflight.delete(key);
+		});
+		this.#inflight.set(key, promise);
+		return promise;
+	}
+	/** The single provision/reattach attempt behind {@link ensureSandbox}. */
+	async #ensureSandboxUncoalesced(store, env, onProgress, options) {
+		const idleTimeoutMinutes = this.idleMinutes;
+		const checkpointName = store.checkpointName;
+		if (store.sandboxId) {
+			reportProgress(onProgress, {
+				phase: "reattaching",
+				message: "Reconnecting to your sandbox…"
+			});
+			const reattached = this.#build({
+				providerSandboxId: store.sandboxId,
+				idleTimeoutMinutes,
+				...checkpointName ? { checkpointName } : {},
+				...env ? { env } : {},
+				...options.workingDirectory ? { workingDirectory: options.workingDirectory } : {}
+			});
+			try {
+				await reattached.start();
+				return reattached;
+			} catch {
+				await store.setSandboxId(null);
+			}
+		}
+		const max = this.maxSandboxes;
+		if (max > 0 && this.#liveCount >= max) throw new SandboxBudgetError(max);
+		reportProgress(onProgress, {
+			phase: "provisioning",
+			message: "Provisioning a new sandbox…"
+		});
+		const sandbox = this.#build({
+			idleTimeoutMinutes,
+			...checkpointName ? { checkpointName } : {},
+			...env ? { env } : {},
+			...options.workingDirectory ? { workingDirectory: options.workingDirectory } : {}
+		});
+		await sandbox.start();
+		this.#liveCount += 1;
+		const providerSandboxId = await readProviderSandboxId(sandbox);
+		if (providerSandboxId) await store.setSandboxId(providerSandboxId);
+		return sandbox;
+	}
+	/**
+	* Tear down a sandbox binding: stop the live VM (best-effort) and clear the
+	* persisted state through the binding store so the next open re-provisions
+	* cleanly. Decrements the per-replica live-sandbox counter.
+	*
+	* @param store   the binding to tear down
+	* @param sandbox an already-reattached live sandbox to stop, when available
+	*/
+	async teardownSandbox(store, sandbox) {
+		if (sandbox?.stop) try {
+			await sandbox.stop();
+		} catch {}
+		if (store.sandboxId) {
+			if (this.#liveCount > 0) this.#liveCount -= 1;
+			await store.clear();
+		}
+	}
+	/**
+	* Reattach to an already-provisioned sandbox by its provider id and start it.
+	* Used by the workspace seam when opening a project that was already
+	* materialized (sandbox id + workdir carried on controller state), so no DB
+	* round-trip is needed.
+	*/
+	async reattachSandbox(providerSandboxId, options = {}) {
+		const sandbox = this.#build({
+			providerSandboxId,
+			idleTimeoutMinutes: this.idleMinutes,
+			...options.workingDirectory ? { workingDirectory: options.workingDirectory } : {}
+		});
+		await sandbox.start();
+		return sandbox;
+	}
+};
+//#endregion
+export { SandboxBudgetError, SandboxFleet, reportProgress, resolveContainedLocalWorkdir };
+
+//# sourceMappingURL=fleet.js.map