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

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

@@ -1 +1 @@
-{"version":3,"file":"session-sandbox.js","names":[],"sources":["../../src/sandbox/session-sandbox.ts"],"sourcesContent":["import path from 'node:path';\nimport { SETUP_MARKER_PATH, setupMarkerContent } from '@internal/workspace';\n\nimport type { MastraSandbox, SandboxStartHook, WorkspaceSandbox } from '@mastra/core/workspace';\nimport type { RepositoryAccess } from '../capabilities/version-control.js';\nimport { timedPhase } from '../timing.js';\nimport { deriveLocalWorkdir, deriveRemoteRepoDir, repoDirUnder } from './workdir.js';\n\n/**\n * Everything factory knows about a session's sandbox needs — the whole\n * contract between factory and the deployer's sandbox callback. Factory owns\n * intent; the provider owns resolving `sessionId` to a runnable VM.\n */\nexport interface FactorySandboxContext {\n  /** Stable session id — the sandbox identity. */\n  sessionId: string;\n  /**\n   * The provider's physical sandbox id persisted from a prior start, when the\n   * session has been started before. Providers that reattach by physical id\n   * (e.g. Railway) MUST forward it to the sandbox constructor so resume\n   * reattaches the original VM instead of provisioning a replacement. E2B and\n   * Platform accept it as a deterministic-reattach optimization. Undefined on\n   * a session's first ever start.\n   */\n  sandboxId?: string;\n  /** owner/name of the repository, when the session is repo-backed. */\n  repoFullName?: string;\n  /**\n   * Configured repo setup command, when present. Part of a repo template's\n   * identity: a different setup command produces a different template.\n   */\n  setupCommand?: string;\n  /**\n   * Resolves the session repository's clone URL and a fresh short-lived\n   * credential for it. Providers use it for authenticated work that runs\n   * outside the VM — resolving a private repo's head, or cloning it during\n   * a template build. The credential is minted per call (installation\n   * tokens expire in ~1h); never an org PAT.\n   *\n   * `undefined` when the session has no repository, which is how a provider\n   * knows to build no repo template. The key is always present so that\n   * passing the whole context to a provider helper keeps working when this\n   * field changes, instead of silently resolving to \"no repository\".\n   */\n  getRepositoryAccess: (() => Promise<RepositoryAccess>) | undefined;\n}\n\n/**\n * The deploy's sandbox configuration: construct a session's sandbox from\n * intent. The sandbox identity is the session id; the provider must honor\n * id-keyed getOrCreate on `start()` (reconnect/resume an existing VM for the\n * id, create otherwise). Construction must be cheap and side-effect-free —\n * VMs are provisioned on `start()` only. Local sandboxes should root their\n * `workingDirectory` at a per-session directory (e.g.\n * `join(root, ctx.sessionId)`); the repo checks out as a subdirectory of it.\n *\n * Forward `ctx.sandboxId` to providers that reattach by physical id so resume\n * reattaches the original VM instead of provisioning a replacement.\n *\n * Returns a `MastraSandbox`, not the bare `WorkspaceSandbox` interface:\n * factory relies on the base class for the start lifecycle and the runtime\n * env, so providers extend it rather than reimplementing the contract.\n *\n * Factory attaches its own session setup to the returned sandbox, so the\n * callback never has to wire it up. A callback may still pass its own\n * `onStart`; it runs after factory's setup, against a prepared workspace.\n *\n * @example\n * ```typescript\n * sandbox: ({ sessionId, sandboxId }) => new E2BSandbox({ id: sessionId, sandboxId })\n * ```\n */\nexport type MastraFactorySandboxConfig = (ctx: FactorySandboxContext) => MastraSandbox;\n\n/**\n * What the start hook learned about the setup command before running the\n * session setup, and how to record its completion afterwards.\n */\nexport interface SessionSetupGate {\n  /** True when the sandbox already carries a marker for the current setup command. */\n  setupDone: boolean;\n  /** Write the marker once the setup command succeeded. Best-effort. */\n  markSetupDone: () => Promise<void>;\n}\n\n/**\n * The session's setup work, run against a started sandbox on EVERY start.\n * Materialize and checkout are idempotent and must always run (a warm boot\n * still needs its pull); only the setup command consults `gate`.\n */\nexport type SessionSetupRun = (sandbox: WorkspaceSandbox, workdir: string, gate: SessionSetupGate) => Promise<void>;\n\n/**\n * Per-process session-id → sandbox instance memo.\n *\n * The provider contract is id-keyed getOrCreate, but provider find-then-create\n * has a real double-create race across independent instances. Memoizing the\n * instance per session makes the base class's per-instance start coalescing\n * apply process-wide per session — the same single-flight scope the fleet's\n * per-binding coalescing provided. Cross-replica races are accepted (the\n * fleet was also per-replica).\n */\ninterface SessionSandboxEntry {\n  sandbox: WorkspaceSandbox;\n  /**\n   * The session's repo checkout root, recorded for passive readers (fs\n   * routes, capture, authz). Local sandboxes derive it at construction;\n   * remote sandboxes clone into the VM's own home, so it is undefined until\n   * `resolveSessionWorkdir` probes the first started VM — passive readers\n   * treat an unresolved workdir as \"nothing materialized\".\n   */\n  workdir?: string;\n}\n\nconst sessionSandboxes = new Map<string, SessionSandboxEntry>();\n\n/**\n * Get the session's memoized sandbox entry, constructing (and memoizing) it on\n * first access. Construction is cheap and side-effect-free by contract; VMs\n * are provisioned on `start()` only. Local sandboxes get their workdir here;\n * remote workdirs are a runtime fact of the VM, resolved on first start.\n */\nexport function getSessionSandbox(\n  sessionId: string,\n  repoFullName: string,\n  construct: () => WorkspaceSandbox,\n): SessionSandboxEntry {\n  const existing = sessionSandboxes.get(sessionId);\n  if (existing) return existing;\n  const sandbox = construct();\n  const local = deriveLocalWorkdir(sandbox, repoFullName);\n  const entry: SessionSandboxEntry = { sandbox, ...(local ? { workdir: local } : {}) };\n  sessionSandboxes.set(sessionId, entry);\n  return entry;\n}\n\n/**\n * Resolve (and memoize on the session entry) the session's repo checkout\n * root. Local sandboxes answer synchronously from their configured\n * `workingDirectory`; remote sandboxes clone into the VM's own default cwd,\n * so the first resolution probes it with one `pwd` — the VM tells us where\n * home is, we never invent a path. Calling this against a stopped sandbox\n * lazily starts it (the probe is a command), so passive readers must peek\n * `entry.workdir` instead.\n */\nexport async function resolveSessionWorkdir(\n  sessionId: string,\n  sandbox: WorkspaceSandbox,\n  repoFullName: string,\n): Promise<string> {\n  const entry = sessionSandboxes.get(sessionId);\n  if (entry?.workdir && entry.sandbox === sandbox) return entry.workdir;\n  const workdir =\n    deriveLocalWorkdir(sandbox, repoFullName) ??\n    deriveRemoteRepoDir(sandbox, repoFullName) ??\n    repoDirUnder(await probeHome(sandbox), repoFullName);\n  if (entry && entry.sandbox === sandbox) entry.workdir = workdir;\n  return workdir;\n}\n\n/** One `pwd` in the VM's default shell cwd — its home dir, by provider convention. */\nasync function probeHome(sandbox: WorkspaceSandbox): Promise<string> {\n  if (!sandbox.executeCommand) {\n    throw new Error(`Sandbox '${sandbox.id}' cannot resolve its workdir: no executeCommand implementation`);\n  }\n  const probe = await sandbox.executeCommand('pwd');\n  const home = probe.stdout.trim().split('\\n').pop()?.trim() ?? '';\n  if (probe.exitCode !== 0 || !home.startsWith('/')) {\n    throw new Error(\n      `Sandbox '${sandbox.id}' default cwd probe failed (exit ${probe.exitCode}): ${\n        probe.stderr.trim() || probe.stdout.trim() || 'empty output'\n      }`,\n    );\n  }\n  return home;\n}\n\n/**\n * The session's memoized sandbox (and its workdir) when one was already\n * constructed in this process, else undefined. Never constructs — passive\n * read paths use this so browsing files cannot provision a VM.\n */\nexport function peekSessionSandbox(sessionId: string): SessionSandboxEntry | undefined {\n  return sessionSandboxes.get(sessionId);\n}\n\n/** Drop the memoized instance (on stop/destroy/retirement or construction failure). */\nexport function evictSessionSandbox(sessionId: string): void {\n  sessionSandboxes.delete(sessionId);\n  failedSetupCommands.delete(sessionId);\n}\n\n/** Test-only: reset the process-wide memo between tests. */\nexport function __clearSessionSandboxesForTests(): void {\n  sessionSandboxes.clear();\n  failedSetupCommands.clear();\n}\n\n/**\n * Setup commands that already failed once for a session. The first failure\n * fails the start loudly — the agent sees the real error in the tool result\n * that triggered it. Recording it lets the next start skip the known-bad\n * command instead of wedging the session behind a permanently failing\n * onStart: clone and checkout still run, and the agent can fix or re-run\n * the setup itself. Keyed by the exact command so an edited setup command\n * runs fresh. In-memory only — a server restart re-runs the (idempotent)\n * setup.\n */\nconst failedSetupCommands = new Map<string, string>();\n\nexport function recordFailedSetupCommand(sessionId: string, command: string): void {\n  failedSetupCommands.set(sessionId, command);\n}\n\nexport function hasFailedSetupCommand(sessionId: string, command: string): boolean {\n  return failedSetupCommands.get(sessionId) === command;\n}\n\n/**\n * The setup completion marker is a convention shared with the repo templates\n * (`@internal/workspace`): `.mastra-sandbox/setup` beside the checkout,\n * containing a digest of the setup commands. Templates write it as their last\n * build step, so a sandbox booted from a warm image already carries it; the\n * start hook writes it after a successful runtime setup. It is a skip cache,\n * not a correctness mechanism: the setup command is assumed idempotent, and a\n * missing or mismatched marker only re-runs it.\n *\n * The working directory is the parent of the repo dir, which is also the\n * template's build cwd, so this is the file the template's marker step wrote.\n */\nfunction markerShellPath(workdir: string): string {\n  return `${path.posix.dirname(workdir)}/${SETUP_MARKER_PATH}`;\n}\n\nasync function markerMatches(sandbox: WorkspaceSandbox, workdir: string, content: string): Promise<boolean> {\n  // The marker sits beside the checkout, not inside it, so it can outlive a\n  // removed checkout (a wiped local session dir, a recovered VM). Trust it\n  // only when the checkout it describes exists and it names this command.\n  const marker = markerShellPath(workdir);\n  const probe = await sandbox.executeCommand!(\n    `test -d \"${workdir}/.git\" && test -f \"${marker}\" && [ \"$(cat \"${marker}\")\" = \"${content}\" ]`,\n  );\n  return probe.exitCode === 0;\n}\n\nasync function writeMarker(sandbox: WorkspaceSandbox, workdir: string, content: string): Promise<void> {\n  // Best-effort: a missing marker only re-runs the idempotent setup later.\n  const marker = markerShellPath(workdir);\n  await sandbox.executeCommand!(`mkdir -p \"$(dirname \"${marker}\")\" && printf '%s' '${content}' > \"${marker}\"`).catch(\n    () => {},\n  );\n}\n\n/**\n * Build the session setup hook, which factory attaches to the constructed\n * sandbox with `setOnStart`. Runs inside the sandbox start lifecycle on\n * every start, fresh VM or reconnect: materialize and checkout always run,\n * and the setup command runs unless the sandbox already carries the marker\n * for it (a warm template image, or an earlier successful start). Throwing\n * fails `start()` loudly; core treats onStart errors as fatal.\n */\nexport function createSessionSetupHook(\n  run: SessionSetupRun,\n  sessionId: string,\n  repoFullName: string,\n  setupCommand: string | undefined,\n): SandboxStartHook {\n  // No command, no marker: nothing to gate.\n  const marker = setupCommand?.trim() ? setupMarkerContent(setupCommand) : undefined;\n  return async ({ sandbox }) => {\n    if (!sandbox.executeCommand) {\n      throw new Error(`Sandbox '${sandbox.id}' cannot run the session setup: no executeCommand implementation`);\n    }\n    // Resolved from the live instance (the hook runs inside `start()`, so the\n    // VM is up) and memoized on the session entry for passive readers.\n    const workdir = await resolveSessionWorkdir(sessionId, sandbox, repoFullName);\n    // Probed before materialize so a wiped checkout reads as \"not done\" even\n    // though materialize is about to restore it.\n    const setupDone = marker\n      ? await timedPhase('workspace.setup-marker', () => markerMatches(sandbox, workdir, marker))\n      : true;\n    if (marker) {\n      process.stderr.write(\n        `[factory:setup] ${setupDone ? 'marker matches, skipping setup command' : 'no matching marker, setup command will run'} (${markerShellPath(workdir)})\\n`,\n      );\n    }\n    await run(sandbox, workdir, {\n      setupDone,\n      markSetupDone: () => (marker ? writeMarker(sandbox, workdir, marker) : Promise.resolve()),\n    });\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"session-sandbox.js","names":[],"sources":["../../src/sandbox/session-sandbox.ts"],"sourcesContent":["import path from 'node:path';\nimport {\n  SETUP_FAILED_MARKER_PATH,\n  SETUP_MARKER_PATH,\n  WORKSPACE_SETUP_MARKER_PATH,\n  repoSetupMarkerPath,\n  setupMarkerContent,\n} from '@internal/workspace';\n\nimport type {\n  FactorySandbox,\n  FactorySandboxContext as CoreFactorySandboxContext,\n  MastraSandbox,\n  SandboxStartHook,\n  WorkspaceSandbox,\n} from '@mastra/core/workspace';\nimport { timedPhase } from '../timing.js';\nimport { deriveLocalWorkdir, deriveRemoteRepoDir, repoDirUnder, repositoryDirectoryName } from './workdir.js';\n\n/**\n * Everything factory knows about a session's sandbox needs: the whole contract\n * between factory and the host's FactorySandbox. Factory owns intent; the\n * provider owns resolving `sessionId` to a runnable VM. Defined in\n * `@mastra/core/workspace` so provider packages can implement it without\n * depending on factory.\n */\nexport type FactorySandboxContext = CoreFactorySandboxContext;\n\n/**\n * The deploy's sandbox configuration: construct a session's sandbox from\n * intent. The sandbox identity is the session id; the provider must honor\n * id-keyed getOrCreate on `start()` (reconnect/resume an existing VM for the\n * id, create otherwise). Construction must be cheap and side-effect-free —\n * VMs are provisioned on `start()` only. Local sandboxes should root their\n * `workingDirectory` at a per-session directory (e.g.\n * `join(root, ctx.sessionId)`); the repo checks out as a subdirectory of it.\n *\n * Forward `ctx.sandboxId` to providers that reattach by physical id so resume\n * reattaches the original VM instead of provisioning a replacement.\n *\n * Returns a `MastraSandbox`, not the bare `WorkspaceSandbox` interface:\n * factory relies on the base class for the start lifecycle and the runtime\n * env, so providers extend it rather than reimplementing the contract.\n *\n * Factory attaches its own session setup to the returned sandbox, so the\n * callback never has to wire it up. A callback may still pass its own\n * `onStart`; it runs after factory's setup, against a prepared workspace.\n *\n * @example\n * ```typescript\n * sandbox: ({ sessionId, sandboxId }) => new E2BSandbox({ id: sessionId, sandboxId })\n * ```\n *\n * A FactorySandbox instance (for example `new E2BFactorySandbox({ apiKey })`)\n * additionally exposes settings and template builds to the environment.\n */\nexport type MastraFactorySandboxConfig = (ctx: FactorySandboxContext) => MastraSandbox;\n\n/**\n * The `sandbox` option of `MastraFactoryConfig`: a FactorySandbox instance\n * (it owns the session sandbox constructor, the repo template and the\n * environment settings schema) or a bare callback, which the factory wraps as a `provider: 'custom'` sandbox with no settings.\n */\nexport type MastraFactorySandboxOption = FactorySandbox | MastraFactorySandboxConfig;\n\n/**\n * What the start hook learned about the setup command before running the\n * session setup, and how to record its completion afterwards.\n */\nexport interface SessionSetupGate {\n  /** True when the sandbox already carries a marker for the current setup command. */\n  setupDone: boolean;\n  /** Write the marker once the setup command succeeded. Best-effort. */\n  markSetupDone: () => Promise<void>;\n}\n\n/**\n * The session's setup work, run against a started sandbox on EVERY start.\n * Materialize and checkout are idempotent and must always run (a warm boot\n * still needs its pull); only the setup command consults `gate`.\n */\nexport type SessionSetupRun = (sandbox: WorkspaceSandbox, workdir: string, gate: SessionSetupGate) => Promise<void>;\n\n/** One environment repository as the boot hook needs it: its slug and setup command. */\nexport interface SessionEnvironmentRepository {\n  slug: string;\n  setupCommand?: string;\n}\n\n/** What the environment hook learned about one repository before the boot runs. */\nexport interface SessionEnvironmentRepositoryGate extends SessionEnvironmentRepository {\n  /** `<root>/<repoDir>`, the directory the template cloned this repository into. */\n  dir: string;\n  gate: SessionSetupGate;\n}\n\n/** The environment hook's view of the workspace: the root, every repository in position order, the workspace gate. */\nexport interface SessionEnvironmentGate {\n  /** The workspace root, parent of every repository directory. */\n  root: string;\n  repos: SessionEnvironmentRepositoryGate[];\n  /** Gate for `workspaceSetupCommand`; `setupDone` when there is no command or its marker matches. */\n  workspace: SessionSetupGate;\n}\n\n/** The list-form session boot: run on every start, like `SessionSetupRun`. */\nexport type SessionEnvironmentSetupRun = (\n  sandbox: WorkspaceSandbox,\n  environment: SessionEnvironmentGate,\n) => Promise<void>;\n\n/**\n * Per-process session-id → sandbox instance memo.\n *\n * The provider contract is id-keyed getOrCreate, but provider find-then-create\n * has a real double-create race across independent instances. Memoizing the\n * instance per session makes the base class's per-instance start coalescing\n * apply process-wide per session — the same single-flight scope the fleet's\n * per-binding coalescing provided. Cross-replica races are accepted (the\n * fleet was also per-replica).\n */\ninterface SessionSandboxEntry {\n  sandbox: WorkspaceSandbox;\n  /**\n   * The session's repo checkout root, recorded for passive readers (fs\n   * routes, capture, authz). Local sandboxes derive it at construction;\n   * remote sandboxes clone into the VM's own home, so it is undefined until\n   * `resolveSessionWorkdir` probes the first started VM — passive readers\n   * treat an unresolved workdir as \"nothing materialized\".\n   */\n  workdir?: string;\n  /** The session's own repository, the only one `workdir` is ever recorded for. */\n  ownRepo: string;\n  /** Environment repositories in position order; the session's own repository is among them. */\n  repos?: string[];\n}\n\nconst sessionSandboxes = new Map<string, SessionSandboxEntry>();\n\n/** One environment repository as the file readers see it. */\nexport interface SessionLayoutRepository {\n  slug: string;\n  /** Absolute checkout directory. */\n  dir: string;\n  /** Path prefix of this checkout under the layout root: empty for a single-repository session, `<dir>/` otherwise. */\n  prefix: string;\n}\n\n/**\n * Where a session's files are read from. A session with one repository is\n * rooted at that checkout, as before environments existed; a session with\n * several is rooted at the workspace root with each checkout as a directory\n * beneath it.\n */\nexport interface SessionLayout {\n  root: string;\n  repos: SessionLayoutRepository[];\n}\n\n/** The layout of a memoized session, `undefined` until its workdir resolved. */\nexport function sessionLayout(entry: SessionSandboxEntry | undefined): SessionLayout | undefined {\n  if (!entry?.workdir) return undefined;\n  const slugs = entry.repos?.length ? entry.repos : [entry.ownRepo];\n  if (slugs.length === 1) {\n    return { root: entry.workdir, repos: [{ slug: slugs[0]!, dir: entry.workdir, prefix: '' }] };\n  }\n  const root = path.posix.dirname(entry.workdir);\n  return {\n    root,\n    repos: slugs.map(slug => {\n      const dir = slug.toLowerCase() === entry.ownRepo.toLowerCase() ? entry.workdir! : repoDirUnder(root, slug);\n      return { slug, dir, prefix: `${path.posix.basename(dir)}/` };\n    }),\n  };\n}\n\n/**\n * Get the session's memoized sandbox entry, constructing (and memoizing) it on\n * first access. Construction is cheap and side-effect-free by contract; VMs\n * are provisioned on `start()` only. Local sandboxes get their workdir here;\n * remote workdirs are a runtime fact of the VM, resolved on first start.\n */\nexport function getSessionSandbox(\n  sessionId: string,\n  repoFullName: string,\n  construct: () => WorkspaceSandbox,\n  repos?: string[],\n): SessionSandboxEntry {\n  const existing = sessionSandboxes.get(sessionId);\n  if (existing) {\n    // The environment can change between boots; the layout follows the latest.\n    if (repos) existing.repos = repos;\n    return existing;\n  }\n  const sandbox = construct();\n  const local = deriveLocalWorkdir(sandbox, repoFullName);\n  const entry: SessionSandboxEntry = {\n    sandbox,\n    ownRepo: repoFullName,\n    ...(local ? { workdir: local } : {}),\n    ...(repos ? { repos } : {}),\n  };\n  sessionSandboxes.set(sessionId, entry);\n  return entry;\n}\n\n/**\n * Resolve (and memoize on the session entry) the session's repo checkout\n * root. Local sandboxes answer synchronously from their configured\n * `workingDirectory`; remote sandboxes clone into the VM's own default cwd,\n * so the first resolution probes it with one `pwd` — the VM tells us where\n * home is, we never invent a path. Calling this against a stopped sandbox\n * lazily starts it (the probe is a command), so passive readers must peek\n * `entry.workdir` instead. The memo is the session's own checkout; another\n * environment repository lives beside it under the same root, so it is\n * answered from the memo's parent without a second probe.\n */\nexport async function resolveSessionWorkdir(\n  sessionId: string,\n  sandbox: WorkspaceSandbox,\n  repoFullName: string,\n): Promise<string> {\n  const entry = sessionSandboxes.get(sessionId);\n  const memo = entry && entry.sandbox === sandbox ? entry : undefined;\n  if (memo && memo.ownRepo !== repoFullName) {\n    // Passive readers take `workdir` as the session's own checkout, so a\n    // sibling never lands in the memo: resolve the own checkout (cold memo\n    // included) and answer the sibling beside it.\n    const own = await resolveSessionWorkdir(sessionId, sandbox, memo.ownRepo);\n    return repoDirUnder(path.posix.dirname(own), repoFullName);\n  }\n  if (memo?.workdir) return memo.workdir;\n  const workdir =\n    deriveLocalWorkdir(sandbox, repoFullName) ??\n    deriveRemoteRepoDir(sandbox, repoFullName) ??\n    repoDirUnder(await probeHome(sandbox), repoFullName);\n  if (memo) memo.workdir = workdir;\n  return workdir;\n}\n\n/** One `pwd` in the VM's default shell cwd — its home dir, by provider convention. */\nasync function probeHome(sandbox: WorkspaceSandbox): Promise<string> {\n  if (!sandbox.executeCommand) {\n    throw new Error(`Sandbox '${sandbox.id}' cannot resolve its workdir: no executeCommand implementation`);\n  }\n  const probe = await sandbox.executeCommand('pwd');\n  const home = probe.stdout.trim().split('\\n').pop()?.trim() ?? '';\n  if (probe.exitCode !== 0 || !home.startsWith('/')) {\n    throw new Error(\n      `Sandbox '${sandbox.id}' default cwd probe failed (exit ${probe.exitCode}): ${\n        probe.stderr.trim() || probe.stdout.trim() || 'empty output'\n      }`,\n    );\n  }\n  return home;\n}\n\n/**\n * The session's memoized sandbox (and its workdir) when one was already\n * constructed in this process, else undefined. Never constructs — passive\n * read paths use this so browsing files cannot provision a VM.\n */\nexport function peekSessionSandbox(sessionId: string): SessionSandboxEntry | undefined {\n  return sessionSandboxes.get(sessionId);\n}\n\n/** Drop the memoized instance (on stop/destroy/retirement or construction failure). */\nexport function evictSessionSandbox(sessionId: string): void {\n  sessionSandboxes.delete(sessionId);\n  failedSetupCommands.delete(sessionId);\n}\n\n/** Test-only: reset the process-wide memo between tests. */\nexport function __clearSessionSandboxesForTests(): void {\n  sessionSandboxes.clear();\n  failedSetupCommands.clear();\n}\n\n/**\n * Setup commands that already failed once for a session. The first failure\n * fails the start loudly — the agent sees the real error in the tool result\n * that triggered it. Recording it lets the next start skip the known-bad\n * command instead of wedging the session behind a permanently failing\n * onStart: clone and checkout still run, and the agent can fix or re-run\n * the setup itself. Keyed by the exact command, one entry per failed command, so an\n * edited setup command runs fresh. In-memory only — a server restart re-runs the (idempotent)\n * setup.\n */\nconst failedSetupCommands = new Map<string, Set<string>>();\n\nexport function recordFailedSetupCommand(sessionId: string, command: string): void {\n  const failed = failedSetupCommands.get(sessionId) ?? new Set<string>();\n  failed.add(command);\n  failedSetupCommands.set(sessionId, failed);\n}\n\nexport function hasFailedSetupCommand(sessionId: string, command: string): boolean {\n  return failedSetupCommands.get(sessionId)?.has(command) ?? false;\n}\n\n/**\n * The setup completion marker is a convention shared with the repo templates\n * (`@internal/workspace`): `.mastra-sandbox/setup` beside the checkout,\n * containing a digest of the setup commands. Templates write it as their last\n * build step, so a sandbox booted from a warm image already carries it; the\n * start hook writes it after a successful runtime setup. It is a skip cache,\n * not a correctness mechanism: the setup command is assumed idempotent, and a\n * missing or mismatched marker only re-runs it.\n *\n * The working directory is the parent of the repo dir, which is also the\n * template's build cwd, so this is the file the template's marker step wrote.\n */\nfunction markerShellPath(workdir: string): string {\n  return `${path.posix.dirname(workdir)}/${SETUP_MARKER_PATH}`;\n}\n\nasync function markerMatches(sandbox: WorkspaceSandbox, workdir: string, content: string): Promise<boolean> {\n  // The marker sits beside the checkout, not inside it, so it can outlive a\n  // removed checkout (a wiped local session dir, a recovered VM). Trust it\n  // only when the checkout it describes exists and it names this command.\n  const marker = markerShellPath(workdir);\n  const probe = await sandbox.executeCommand!(\n    `test -d \"${workdir}/.git\" && test -f \"${marker}\" && [ \"$(cat \"${marker}\")\" = \"${content}\" ]`,\n  );\n  return probe.exitCode === 0;\n}\n\nasync function writeMarker(sandbox: WorkspaceSandbox, workdir: string, content: string): Promise<void> {\n  // Best-effort: a missing marker only re-runs the idempotent setup later.\n  const marker = markerShellPath(workdir);\n  await sandbox.executeCommand!(`mkdir -p \"$(dirname \"${marker}\")\" && printf '%s' '${content}' > \"${marker}\"`).catch(\n    () => {},\n  );\n}\n\n/**\n * Build the session setup hook, which factory attaches to the constructed\n * sandbox with `setOnStart`. Runs inside the sandbox start lifecycle on\n * every start, fresh VM or reconnect: materialize and checkout always run,\n * and the setup command runs unless the sandbox already carries the marker\n * for it (a warm template image, or an earlier successful start). Throwing\n * fails `start()` loudly; core treats onStart errors as fatal.\n */\nexport function createSessionSetupHook(\n  run: SessionSetupRun,\n  sessionId: string,\n  repoFullName: string,\n  setupCommand: string | undefined,\n): SandboxStartHook {\n  // No command, no marker: nothing to gate.\n  const marker = setupCommand?.trim() ? setupMarkerContent(setupCommand) : undefined;\n  return async ({ sandbox }) => {\n    if (!sandbox.executeCommand) {\n      throw new Error(`Sandbox '${sandbox.id}' cannot run the session setup: no executeCommand implementation`);\n    }\n    // Resolved from the live instance (the hook runs inside `start()`, so the\n    // VM is up) and memoized on the session entry for passive readers.\n    const workdir = await resolveSessionWorkdir(sessionId, sandbox, repoFullName);\n    // Probed before materialize so a wiped checkout reads as \"not done\" even\n    // though materialize is about to restore it.\n    const setupDone = marker\n      ? await timedPhase('workspace.setup-marker', () => markerMatches(sandbox, workdir, marker))\n      : true;\n    if (marker) {\n      process.stderr.write(\n        `[factory:setup] ${setupDone ? 'marker matches, skipping setup command' : 'no matching marker, setup command will run'} (${markerShellPath(workdir)})\\n`,\n      );\n    }\n    await run(sandbox, workdir, {\n      setupDone,\n      markSetupDone: () => (marker ? writeMarker(sandbox, workdir, marker) : Promise.resolve()),\n    });\n  };\n}\n\n/**\n * Shell-quote one marker file's content. Marker contents are digests, but\n * the quoting keeps an edited command's digest from ever reaching the shell\n * unquoted.\n */\nfunction shellQuote(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`;\n}\n\n/**\n * The list-form marker probe: trust a repository's marker only when its\n * checkout exists, the marker names this command, and the template did not\n * record the repository in `setup-failed` (a failed per-repo setup still\n * writes the marker because every step ran; the failure list says it failed).\n */\nasync function repoMarkerMatches(\n  sandbox: WorkspaceSandbox,\n  root: string,\n  repoDir: string,\n  content: string,\n): Promise<boolean> {\n  const marker = `${root}/${repoSetupMarkerPath(repoDir)}`;\n  const failed = `${root}/${SETUP_FAILED_MARKER_PATH}`;\n  const probe = await sandbox.executeCommand!(\n    `test -d \"${root}/${repoDir}/.git\" && test -f \"${marker}\" && [ \"$(cat \"${marker}\")\" = ${shellQuote(content)} ] && ! grep -qxF -- ${shellQuote(repoDir)} \"${failed}\" 2>/dev/null`,\n  );\n  return probe.exitCode === 0;\n}\n\n/** Write a repository's marker and drop it from `setup-failed`. Best-effort, like `writeMarker`. */\nasync function writeRepoMarker(\n  sandbox: WorkspaceSandbox,\n  root: string,\n  repoDir: string,\n  content: string,\n): Promise<void> {\n  const marker = `${root}/${repoSetupMarkerPath(repoDir)}`;\n  const failed = `${root}/${SETUP_FAILED_MARKER_PATH}`;\n  await sandbox.executeCommand!(\n    `mkdir -p \"$(dirname \"${marker}\")\" && printf '%s' ${shellQuote(content)} > \"${marker}\" && { test -f \"${failed}\" && { grep -vxF -- ${shellQuote(repoDir)} \"${failed}\" > \"${failed}.tmp\" || true; } && mv \"${failed}.tmp\" \"${failed}\" || true; }`,\n  ).catch(() => {});\n}\n\nasync function workspaceMarkerMatches(sandbox: WorkspaceSandbox, root: string, content: string): Promise<boolean> {\n  const marker = `${root}/${WORKSPACE_SETUP_MARKER_PATH}`;\n  const probe = await sandbox.executeCommand!(\n    `test -f \"${marker}\" && [ \"$(cat \"${marker}\")\" = ${shellQuote(content)} ]`,\n  );\n  return probe.exitCode === 0;\n}\n\nasync function writeWorkspaceMarker(sandbox: WorkspaceSandbox, root: string, content: string): Promise<void> {\n  const marker = `${root}/${WORKSPACE_SETUP_MARKER_PATH}`;\n  await sandbox.executeCommand!(\n    `mkdir -p \"$(dirname \"${marker}\")\" && printf '%s' ${shellQuote(content)} > \"${marker}\"`,\n  ).catch(() => {});\n}\n\n/**\n * The list-form start hook for a session whose factory has an environment:\n * the same lifecycle as `createSessionSetupHook`, with one gate per\n * repository plus one for the workspace setup command. The markers are the\n * ones the multi-repo templates write (`.mastra-sandbox/repos/<repoDir>`,\n * `.mastra-sandbox/workspace-setup`, `.mastra-sandbox/setup-failed`), all\n * under the workspace root, which is the parent of the primary repository's\n * directory: `resolveSessionWorkdir` keeps answering that directory so the\n * PR tools and passive readers see the primary checkout, and the root is\n * derived from it rather than probed twice.\n *\n * `repos` is in position order and must include the primary (`repoFullName`).\n */\nexport function createEnvironmentSetupHook(\n  run: SessionEnvironmentSetupRun,\n  sessionId: string,\n  repoFullName: string,\n  environment: { repos: SessionEnvironmentRepository[]; workspaceSetupCommand?: string },\n): SandboxStartHook {\n  const workspaceCommand = environment.workspaceSetupCommand?.trim() ? environment.workspaceSetupCommand : undefined;\n  const workspaceMarker = workspaceCommand ? setupMarkerContent(workspaceCommand) : undefined;\n  return async ({ sandbox }) => {\n    if (!sandbox.executeCommand) {\n      throw new Error(`Sandbox '${sandbox.id}' cannot run the session setup: no executeCommand implementation`);\n    }\n    const workdir = await resolveSessionWorkdir(sessionId, sandbox, repoFullName);\n    const root = path.posix.dirname(workdir);\n    const repos: SessionEnvironmentRepositoryGate[] = [];\n    for (const repo of environment.repos) {\n      const repoDir = repositoryDirectoryName(repo.slug);\n      const marker = repo.setupCommand?.trim() ? setupMarkerContent(repo.setupCommand) : undefined;\n      const setupDone = marker\n        ? await timedPhase(`workspace.setup-marker(${repoDir})`, () =>\n            repoMarkerMatches(sandbox, root, repoDir, marker),\n          )\n        : true;\n      if (marker) {\n        process.stderr.write(\n          `[factory:setup] ${repo.slug}: ${setupDone ? 'marker matches, skipping setup command' : 'no matching marker, setup command will run'} (${root}/${repoSetupMarkerPath(repoDir)})\\n`,\n        );\n      }\n      repos.push({\n        ...repo,\n        dir: `${root}/${repoDir}`,\n        gate: {\n          setupDone,\n          markSetupDone: () => (marker ? writeRepoMarker(sandbox, root, repoDir, marker) : Promise.resolve()),\n        },\n      });\n    }\n    const workspaceDone = workspaceMarker\n      ? await timedPhase('workspace.setup-marker(workspace)', () =>\n          workspaceMarkerMatches(sandbox, root, workspaceMarker),\n        )\n      : true;\n    await run(sandbox, {\n      root,\n      repos,\n      workspace: {\n        setupDone: workspaceDone,\n        markSetupDone: () =>\n          workspaceMarker ? writeWorkspaceMarker(sandbox, root, workspaceMarker) : Promise.resolve(),\n      },\n    });\n  };\n}\n"],"mappings":"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"}

package/dist/sandbox/workdir.d.ts

@@ -30,6 +30,16 @@ export declare function deriveRemoteRepoDir(sandbox: {
 }, repoFullName: string): string | undefined;
 /** Join a parent directory and sanitized repository name. */
 export declare function repoDirUnder(parent: string, repoFullName: string): string;
+/**
+ * The directory a repository checks out into, under the workspace root. Must
+ * agree with the repo templates' private `repoDirName`
+ * (`workspaces/platform-workspace/src/repo-template.ts`): the last segment
+ * of the clone URL, `[^A-Za-z0-9._-]` replaced by `-`, leading dots dropped,
+ * `repo` when nothing is left. A repository slug never ends in `.git`, so
+ * both derive the same name for every slug; `workdir.test.ts` pins the
+ * template's own fixtures.
+ */
+export declare function repositoryDirectoryName(repoFullName: string): string;
 /** Resolve a workdir under `root`, refusing any path that escapes the configured root. */
 export declare function resolveContainedLocalWorkdir(root: string, ...segments: string[]): string;
 //# sourceMappingURL=workdir.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"workdir.d.ts","sourceRoot":"","sources":["../../src/sandbox/workdir.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,EACzD,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAMpB;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CACjC,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,EACzD,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAMpB;AAED,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAIzE;AAOD,0FAA0F;AAC1F,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAKxF"}
+{"version":3,"file":"workdir.d.ts","sourceRoot":"","sources":["../../src/sandbox/workdir.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,EACzD,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAMpB;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CACjC,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,EACzD,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAMpB;AAED,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAIzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED,0FAA0F;AAC1F,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAKxF"}

package/dist/sandbox/workdir.js

@@ -38,6 +38,15 @@ function repoDirUnder(parent, repoFullName) {
 	while (end > 0 && parent[end - 1] === "/") end--;
 	return `${parent.slice(0, end)}/${repositoryDirectoryName(repoFullName)}`;
 }
+/**
+* The directory a repository checks out into, under the workspace root. Must
+* agree with the repo templates' private `repoDirName`
+* (`workspaces/platform-workspace/src/repo-template.ts`): the last segment
+* of the clone URL, `[^A-Za-z0-9._-]` replaced by `-`, leading dots dropped,
+* `repo` when nothing is left. A repository slug never ends in `.git`, so
+* both derive the same name for every slug; `workdir.test.ts` pins the
+* template's own fixtures.
+*/
 function repositoryDirectoryName(repoFullName) {
 	const segments = repoFullName.split("/");
 	return sanitizeSegment(segments.length > 1 ? segments.at(-1) || "repo" : "repo");
@@ -50,6 +59,6 @@ function resolveContainedLocalWorkdir(root, ...segments) {
 	throw new Error(`Refusing to use local sandbox path outside configured root: ${resolved}`);
 }
 //#endregion
-export { deriveLocalWorkdir, deriveRemoteRepoDir, repoDirUnder, resolveContainedLocalWorkdir, sanitizeSegment };
+export { deriveLocalWorkdir, deriveRemoteRepoDir, repoDirUnder, repositoryDirectoryName, resolveContainedLocalWorkdir, sanitizeSegment };
 
 //# sourceMappingURL=workdir.js.map

package/dist/sandbox/workdir.js.map

@@ -1 +1 @@
-{"version":3,"file":"workdir.js","names":["path"],"sources":["../../src/sandbox/workdir.ts"],"sourcesContent":["import * as path from 'node:path';\n\n/**\n * Session workdir derivation. Workdirs are never persisted or trusted from\n * storage or client input — the stale-workdir class of production bugs came\n * from reading `session.sandboxWorkdir` written under a different provider.\n *\n * Local sandboxes derive their workdir synchronously from the sandbox's own\n * `workingDirectory` (the per-session directory the deploy's callback chose).\n * Remote sandboxes have no invented path: the repo clones into the VM's own\n * default cwd (its home dir), so the workdir is only knowable once a VM is\n * running — resolved lazily by `resolveSessionWorkdir` via a one-time `pwd`\n * probe and memoized on the session entry.\n */\n\n/** Keep each path piece a single safe segment (no separators or traversal). */\nexport function sanitizeSegment(segment: string): string {\n  const cleaned = segment.replace(/[^A-Za-z0-9._-]/g, '-').replace(/^\\.+/, '');\n  return cleaned || 'repo';\n}\n\n/**\n * Synchronously derivable workdir: local sandboxes expose their host\n * `workingDirectory`; the repo checks out as a contained subdirectory so the\n * setup marker sits beside the clone instead of polluting `git status`\n * inside it. Returns undefined for remote providers, whose workdir is a\n * runtime fact of the VM (`<home>/<repo>`).\n */\nexport function deriveLocalWorkdir(\n  sandbox: { provider: string; workingDirectory?: unknown },\n  repoFullName: string,\n): string | undefined {\n  const wd = sandbox.workingDirectory;\n  if (sandbox.provider === 'local' && typeof wd === 'string' && wd.length > 0) {\n    return resolveContainedLocalWorkdir(wd, repositoryDirectoryName(repoFullName));\n  }\n  return undefined;\n}\n\n/** Derive `<workingDirectory>/<repo>` when a remote sandbox declares an absolute root. */\nexport function deriveRemoteRepoDir(\n  sandbox: { provider: string; workingDirectory?: unknown },\n  repoFullName: string,\n): string | undefined {\n  const wd = sandbox.workingDirectory;\n  if (sandbox.provider !== 'local' && typeof wd === 'string' && wd.startsWith('/')) {\n    return repoDirUnder(wd, repoFullName);\n  }\n  return undefined;\n}\n\n/** Join a parent directory and sanitized repository name. */\nexport function repoDirUnder(parent: string, repoFullName: string): string {\n  let end = parent.length;\n  while (end > 0 && parent[end - 1] === '/') end--;\n  return `${parent.slice(0, end)}/${repositoryDirectoryName(repoFullName)}`;\n}\n\nfunction repositoryDirectoryName(repoFullName: string): string {\n  const segments = repoFullName.split('/');\n  return sanitizeSegment(segments.length > 1 ? segments.at(-1) || 'repo' : 'repo');\n}\n\n/** Resolve a workdir under `root`, refusing any path that escapes the configured root. */\nexport function resolveContainedLocalWorkdir(root: string, ...segments: string[]): string {\n  const resolvedRoot = path.resolve(root);\n  const resolved = path.resolve(resolvedRoot, ...segments);\n  if (resolved !== resolvedRoot && resolved.startsWith(`${resolvedRoot}${path.sep}`)) return resolved;\n  throw new Error(`Refusing to use local sandbox path outside configured root: ${resolved}`);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgBA,SAAgB,gBAAgB,SAAyB;CAEvD,OADgB,QAAQ,QAAQ,oBAAoB,GAAG,CAAC,CAAC,QAAQ,QAAQ,EAC5D,KAAK;AACpB;;;;;;;;AASA,SAAgB,mBACd,SACA,cACoB;CACpB,MAAM,KAAK,QAAQ;CACnB,IAAI,QAAQ,aAAa,WAAW,OAAO,OAAO,YAAY,GAAG,SAAS,GACxE,OAAO,6BAA6B,IAAI,wBAAwB,YAAY,CAAC;AAGjF;;AAGA,SAAgB,oBACd,SACA,cACoB;CACpB,MAAM,KAAK,QAAQ;CACnB,IAAI,QAAQ,aAAa,WAAW,OAAO,OAAO,YAAY,GAAG,WAAW,GAAG,GAC7E,OAAO,aAAa,IAAI,YAAY;AAGxC;;AAGA,SAAgB,aAAa,QAAgB,cAA8B;CACzE,IAAI,MAAM,OAAO;CACjB,OAAO,MAAM,KAAK,OAAO,MAAM,OAAO,KAAK;CAC3C,OAAO,GAAG,OAAO,MAAM,GAAG,GAAG,EAAE,GAAG,wBAAwB,YAAY;AACxE;AAEA,SAAS,wBAAwB,cAA8B;CAC7D,MAAM,WAAW,aAAa,MAAM,GAAG;CACvC,OAAO,gBAAgB,SAAS,SAAS,IAAI,SAAS,GAAG,EAAE,KAAK,SAAS,MAAM;AACjF;;AAGA,SAAgB,6BAA6B,MAAc,GAAG,UAA4B;CACxF,MAAM,eAAeA,OAAK,QAAQ,IAAI;CACtC,MAAM,WAAWA,OAAK,QAAQ,cAAc,GAAG,QAAQ;CACvD,IAAI,aAAa,gBAAgB,SAAS,WAAW,GAAG,eAAeA,OAAK,KAAK,GAAG,OAAO;CAC3F,MAAM,IAAI,MAAM,+DAA+D,UAAU;AAC3F"}
+{"version":3,"file":"workdir.js","names":["path"],"sources":["../../src/sandbox/workdir.ts"],"sourcesContent":["import * as path from 'node:path';\n\n/**\n * Session workdir derivation. Workdirs are never persisted or trusted from\n * storage or client input — the stale-workdir class of production bugs came\n * from reading `session.sandboxWorkdir` written under a different provider.\n *\n * Local sandboxes derive their workdir synchronously from the sandbox's own\n * `workingDirectory` (the per-session directory the deploy's callback chose).\n * Remote sandboxes have no invented path: the repo clones into the VM's own\n * default cwd (its home dir), so the workdir is only knowable once a VM is\n * running — resolved lazily by `resolveSessionWorkdir` via a one-time `pwd`\n * probe and memoized on the session entry.\n */\n\n/** Keep each path piece a single safe segment (no separators or traversal). */\nexport function sanitizeSegment(segment: string): string {\n  const cleaned = segment.replace(/[^A-Za-z0-9._-]/g, '-').replace(/^\\.+/, '');\n  return cleaned || 'repo';\n}\n\n/**\n * Synchronously derivable workdir: local sandboxes expose their host\n * `workingDirectory`; the repo checks out as a contained subdirectory so the\n * setup marker sits beside the clone instead of polluting `git status`\n * inside it. Returns undefined for remote providers, whose workdir is a\n * runtime fact of the VM (`<home>/<repo>`).\n */\nexport function deriveLocalWorkdir(\n  sandbox: { provider: string; workingDirectory?: unknown },\n  repoFullName: string,\n): string | undefined {\n  const wd = sandbox.workingDirectory;\n  if (sandbox.provider === 'local' && typeof wd === 'string' && wd.length > 0) {\n    return resolveContainedLocalWorkdir(wd, repositoryDirectoryName(repoFullName));\n  }\n  return undefined;\n}\n\n/** Derive `<workingDirectory>/<repo>` when a remote sandbox declares an absolute root. */\nexport function deriveRemoteRepoDir(\n  sandbox: { provider: string; workingDirectory?: unknown },\n  repoFullName: string,\n): string | undefined {\n  const wd = sandbox.workingDirectory;\n  if (sandbox.provider !== 'local' && typeof wd === 'string' && wd.startsWith('/')) {\n    return repoDirUnder(wd, repoFullName);\n  }\n  return undefined;\n}\n\n/** Join a parent directory and sanitized repository name. */\nexport function repoDirUnder(parent: string, repoFullName: string): string {\n  let end = parent.length;\n  while (end > 0 && parent[end - 1] === '/') end--;\n  return `${parent.slice(0, end)}/${repositoryDirectoryName(repoFullName)}`;\n}\n\n/**\n * The directory a repository checks out into, under the workspace root. Must\n * agree with the repo templates' private `repoDirName`\n * (`workspaces/platform-workspace/src/repo-template.ts`): the last segment\n * of the clone URL, `[^A-Za-z0-9._-]` replaced by `-`, leading dots dropped,\n * `repo` when nothing is left. A repository slug never ends in `.git`, so\n * both derive the same name for every slug; `workdir.test.ts` pins the\n * template's own fixtures.\n */\nexport function repositoryDirectoryName(repoFullName: string): string {\n  const segments = repoFullName.split('/');\n  return sanitizeSegment(segments.length > 1 ? segments.at(-1) || 'repo' : 'repo');\n}\n\n/** Resolve a workdir under `root`, refusing any path that escapes the configured root. */\nexport function resolveContainedLocalWorkdir(root: string, ...segments: string[]): string {\n  const resolvedRoot = path.resolve(root);\n  const resolved = path.resolve(resolvedRoot, ...segments);\n  if (resolved !== resolvedRoot && resolved.startsWith(`${resolvedRoot}${path.sep}`)) return resolved;\n  throw new Error(`Refusing to use local sandbox path outside configured root: ${resolved}`);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgBA,SAAgB,gBAAgB,SAAyB;CAEvD,OADgB,QAAQ,QAAQ,oBAAoB,GAAG,CAAC,CAAC,QAAQ,QAAQ,EAC5D,KAAK;AACpB;;;;;;;;AASA,SAAgB,mBACd,SACA,cACoB;CACpB,MAAM,KAAK,QAAQ;CACnB,IAAI,QAAQ,aAAa,WAAW,OAAO,OAAO,YAAY,GAAG,SAAS,GACxE,OAAO,6BAA6B,IAAI,wBAAwB,YAAY,CAAC;AAGjF;;AAGA,SAAgB,oBACd,SACA,cACoB;CACpB,MAAM,KAAK,QAAQ;CACnB,IAAI,QAAQ,aAAa,WAAW,OAAO,OAAO,YAAY,GAAG,WAAW,GAAG,GAC7E,OAAO,aAAa,IAAI,YAAY;AAGxC;;AAGA,SAAgB,aAAa,QAAgB,cAA8B;CACzE,IAAI,MAAM,OAAO;CACjB,OAAO,MAAM,KAAK,OAAO,MAAM,OAAO,KAAK;CAC3C,OAAO,GAAG,OAAO,MAAM,GAAG,GAAG,EAAE,GAAG,wBAAwB,YAAY;AACxE;;;;;;;;;;AAWA,SAAgB,wBAAwB,cAA8B;CACpE,MAAM,WAAW,aAAa,MAAM,GAAG;CACvC,OAAO,gBAAgB,SAAS,SAAS,IAAI,SAAS,GAAG,EAAE,KAAK,SAAS,MAAM;AACjF;;AAGA,SAAgB,6BAA6B,MAAc,GAAG,UAA4B;CACxF,MAAM,eAAeA,OAAK,QAAQ,IAAI;CACtC,MAAM,WAAWA,OAAK,QAAQ,cAAc,GAAG,QAAQ;CACvD,IAAI,aAAa,gBAAgB,SAAS,WAAW,GAAG,eAAeA,OAAK,KAAK,GAAG,OAAO;CAC3F,MAAM,IAAI,MAAM,+DAA+D,UAAU;AAC3F"}

package/dist/session/environment-repositories.d.ts

@@ -0,0 +1,31 @@
+import type { ProjectRepository, ProjectSourceControlConnection, SourceControlRepository, SourceControlSession, SourceControlStorageHandle } from '../storage/domains/source-control/base.js';
+/** One repository of a factory environment, fully resolved: the link, its repository row and its connection. */
+export interface EnvironmentRepository {
+    link: ProjectRepository;
+    repository: SourceControlRepository;
+    connection: ProjectSourceControlConnection;
+}
+/**
+ * The `inEnvironment` links of a factory in position order, resolved to their
+ * repository and connection rows, for the integration the handle belongs to.
+ * A link whose connection or repository row is missing (an uninstalled app,
+ * a link left behind by a reinstall) is skipped with one warning, ids only.
+ */
+export declare function resolveEnvironmentRepositories(args: {
+    sourceControl: SourceControlStorageHandle;
+    orgId: string;
+    factoryProjectId: string;
+}): Promise<EnvironmentRepository[]>;
+/**
+ * The repositories a session may target: the environment list plus, when the
+ * session is filed under a link that is no longer in the environment (a work
+ * item's repository toggled out after dispatch), that own link appended last.
+ * A session can always target the repository it was filed under.
+ */
+export declare function resolveSessionRepositories(args: {
+    sourceControl: SourceControlStorageHandle;
+    session: Pick<SourceControlSession, 'orgId' | 'factoryProjectId' | 'projectRepositoryId'>;
+}): Promise<EnvironmentRepository[]>;
+export declare function findEnvironmentRepository(repositories: EnvironmentRepository[], slug: string): EnvironmentRepository | undefined;
+export declare function environmentSlugs(repositories: EnvironmentRepository[]): string[];
+//# sourceMappingURL=environment-repositories.d.ts.map

package/dist/session/environment-repositories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-repositories.d.ts","sourceRoot":"","sources":["../../src/session/environment-repositories.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,8BAA8B,EAC9B,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC3B,MAAM,2CAA2C,CAAC;AAEnD,gHAAgH;AAChH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,iBAAiB,CAAC;IACxB,UAAU,EAAE,uBAAuB,CAAC;IACpC,UAAU,EAAE,8BAA8B,CAAC;CAC5C;AAED;;;;;GAKG;AACH,wBAAsB,8BAA8B,CAAC,IAAI,EAAE;IACzD,aAAa,EAAE,0BAA0B,CAAC;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC,CA2BnC;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,EAAE;IACrD,aAAa,EAAE,0BAA0B,CAAC;IAC1C,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,OAAO,GAAG,kBAAkB,GAAG,qBAAqB,CAAC,CAAC;CAC3F,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAcnC;AAED,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,qBAAqB,EAAE,EACrC,IAAI,EAAE,MAAM,GACX,qBAAqB,GAAG,SAAS,CAGnC;AAED,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,qBAAqB,EAAE,GAAG,MAAM,EAAE,CAEhF"}

package/dist/session/environment-repositories.js

@@ -0,0 +1,89 @@
+//#region src/session/environment-repositories.ts
+/**
+* The `inEnvironment` links of a factory in position order, resolved to their
+* repository and connection rows, for the integration the handle belongs to.
+* A link whose connection or repository row is missing (an uninstalled app,
+* a link left behind by a reinstall) is skipped with one warning, ids only.
+*/
+async function resolveEnvironmentRepositories(args) {
+	const { sourceControl, orgId, factoryProjectId } = args;
+	const connections = await sourceControl.connections.list({
+		orgId,
+		factoryProjectId
+	});
+	const connectionById = new Map(connections.filter((connection) => connection.integrationId === sourceControl.integrationId).map((connection) => [connection.id, connection]));
+	const links = (await sourceControl.projectRepositories.listByProject({
+		orgId,
+		factoryProjectId
+	})).filter((link) => link.inEnvironment).sort((a, b) => a.position - b.position || a.createdAt.getTime() - b.createdAt.getTime());
+	const resolved = [];
+	for (const link of links) {
+		const connection = connectionById.get(link.connectionId);
+		const repository = connection ? await sourceControl.repositories.get({
+			orgId,
+			id: link.repositoryId
+		}) : null;
+		if (!connection || !repository) {
+			console.warn("[Mastra Factory] Environment repository link cannot be resolved; skipping it", {
+				orgId,
+				factoryProjectId,
+				projectRepositoryId: link.id,
+				reason: connection ? "repository" : "connection"
+			});
+			continue;
+		}
+		resolved.push({
+			link,
+			repository,
+			connection
+		});
+	}
+	return resolved;
+}
+/**
+* The repositories a session may target: the environment list plus, when the
+* session is filed under a link that is no longer in the environment (a work
+* item's repository toggled out after dispatch), that own link appended last.
+* A session can always target the repository it was filed under.
+*/
+async function resolveSessionRepositories(args) {
+	const { sourceControl, session } = args;
+	const orgId = session.orgId;
+	const repositories = session.factoryProjectId ? await resolveEnvironmentRepositories({
+		sourceControl,
+		orgId,
+		factoryProjectId: session.factoryProjectId
+	}) : [];
+	const ownId = session.projectRepositoryId;
+	if (!ownId || repositories.some((candidate) => candidate.link.id === ownId)) return repositories;
+	const link = await sourceControl.projectRepositories.get({
+		orgId,
+		id: ownId
+	});
+	if (!link) return repositories;
+	const connection = await sourceControl.connections.get({
+		orgId,
+		id: link.connectionId
+	});
+	const repository = connection ? await sourceControl.repositories.get({
+		orgId,
+		id: link.repositoryId
+	}) : null;
+	if (!connection || !repository) return repositories;
+	return [...repositories, {
+		link,
+		repository,
+		connection
+	}];
+}
+function findEnvironmentRepository(repositories, slug) {
+	const wanted = slug.trim().toLowerCase();
+	return repositories.find((candidate) => candidate.repository.slug.toLowerCase() === wanted);
+}
+function environmentSlugs(repositories) {
+	return repositories.map((candidate) => candidate.repository.slug);
+}
+//#endregion
+export { environmentSlugs, findEnvironmentRepository, resolveEnvironmentRepositories, resolveSessionRepositories };
+
+//# sourceMappingURL=environment-repositories.js.map

package/dist/session/environment-repositories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-repositories.js","names":[],"sources":["../../src/session/environment-repositories.ts"],"sourcesContent":["import type {\n  ProjectRepository,\n  ProjectSourceControlConnection,\n  SourceControlRepository,\n  SourceControlSession,\n  SourceControlStorageHandle,\n} from '../storage/domains/source-control/base.js';\n\n/** One repository of a factory environment, fully resolved: the link, its repository row and its connection. */\nexport interface EnvironmentRepository {\n  link: ProjectRepository;\n  repository: SourceControlRepository;\n  connection: ProjectSourceControlConnection;\n}\n\n/**\n * The `inEnvironment` links of a factory in position order, resolved to their\n * repository and connection rows, for the integration the handle belongs to.\n * A link whose connection or repository row is missing (an uninstalled app,\n * a link left behind by a reinstall) is skipped with one warning, ids only.\n */\nexport async function resolveEnvironmentRepositories(args: {\n  sourceControl: SourceControlStorageHandle;\n  orgId: string;\n  factoryProjectId: string;\n}): Promise<EnvironmentRepository[]> {\n  const { sourceControl, orgId, factoryProjectId } = args;\n  const connections = await sourceControl.connections.list({ orgId, factoryProjectId });\n  const connectionById = new Map(\n    connections\n      .filter(connection => connection.integrationId === sourceControl.integrationId)\n      .map(connection => [connection.id, connection] as const),\n  );\n  const links = (await sourceControl.projectRepositories.listByProject({ orgId, factoryProjectId }))\n    .filter(link => link.inEnvironment)\n    .sort((a, b) => a.position - b.position || a.createdAt.getTime() - b.createdAt.getTime());\n  const resolved: EnvironmentRepository[] = [];\n  for (const link of links) {\n    const connection = connectionById.get(link.connectionId);\n    const repository = connection ? await sourceControl.repositories.get({ orgId, id: link.repositoryId }) : null;\n    if (!connection || !repository) {\n      console.warn('[Mastra Factory] Environment repository link cannot be resolved; skipping it', {\n        orgId,\n        factoryProjectId,\n        projectRepositoryId: link.id,\n        reason: connection ? 'repository' : 'connection',\n      });\n      continue;\n    }\n    resolved.push({ link, repository, connection });\n  }\n  return resolved;\n}\n\n/**\n * The repositories a session may target: the environment list plus, when the\n * session is filed under a link that is no longer in the environment (a work\n * item's repository toggled out after dispatch), that own link appended last.\n * A session can always target the repository it was filed under.\n */\nexport async function resolveSessionRepositories(args: {\n  sourceControl: SourceControlStorageHandle;\n  session: Pick<SourceControlSession, 'orgId' | 'factoryProjectId' | 'projectRepositoryId'>;\n}): Promise<EnvironmentRepository[]> {\n  const { sourceControl, session } = args;\n  const orgId = session.orgId;\n  const repositories = session.factoryProjectId\n    ? await resolveEnvironmentRepositories({ sourceControl, orgId, factoryProjectId: session.factoryProjectId })\n    : [];\n  const ownId = session.projectRepositoryId;\n  if (!ownId || repositories.some(candidate => candidate.link.id === ownId)) return repositories;\n  const link = await sourceControl.projectRepositories.get({ orgId, id: ownId });\n  if (!link) return repositories;\n  const connection = await sourceControl.connections.get({ orgId, id: link.connectionId });\n  const repository = connection ? await sourceControl.repositories.get({ orgId, id: link.repositoryId }) : null;\n  if (!connection || !repository) return repositories;\n  return [...repositories, { link, repository, connection }];\n}\n\nexport function findEnvironmentRepository(\n  repositories: EnvironmentRepository[],\n  slug: string,\n): EnvironmentRepository | undefined {\n  const wanted = slug.trim().toLowerCase();\n  return repositories.find(candidate => candidate.repository.slug.toLowerCase() === wanted);\n}\n\nexport function environmentSlugs(repositories: EnvironmentRepository[]): string[] {\n  return repositories.map(candidate => candidate.repository.slug);\n}\n"],"mappings":";;;;;;;AAqBA,eAAsB,+BAA+B,MAIhB;CACnC,MAAM,EAAE,eAAe,OAAO,qBAAqB;CACnD,MAAM,cAAc,MAAM,cAAc,YAAY,KAAK;EAAE;EAAO;CAAiB,CAAC;CACpF,MAAM,iBAAiB,IAAI,IACzB,YACG,QAAO,eAAc,WAAW,kBAAkB,cAAc,aAAa,CAAC,CAC9E,KAAI,eAAc,CAAC,WAAW,IAAI,UAAU,CAAU,CAC3D;CACA,MAAM,SAAS,MAAM,cAAc,oBAAoB,cAAc;EAAE;EAAO;CAAiB,CAAC,EAAA,CAC7F,QAAO,SAAQ,KAAK,aAAa,CAAC,CAClC,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,QAAQ,IAAI,EAAE,UAAU,QAAQ,CAAC;CAC1F,MAAM,WAAoC,CAAC;CAC3C,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,aAAa,eAAe,IAAI,KAAK,YAAY;EACvD,MAAM,aAAa,aAAa,MAAM,cAAc,aAAa,IAAI;GAAE;GAAO,IAAI,KAAK;EAAa,CAAC,IAAI;EACzG,IAAI,CAAC,cAAc,CAAC,YAAY;GAC9B,QAAQ,KAAK,gFAAgF;IAC3F;IACA;IACA,qBAAqB,KAAK;IAC1B,QAAQ,aAAa,eAAe;GACtC,CAAC;GACD;EACF;EACA,SAAS,KAAK;GAAE;GAAM;GAAY;EAAW,CAAC;CAChD;CACA,OAAO;AACT;;;;;;;AAQA,eAAsB,2BAA2B,MAGZ;CACnC,MAAM,EAAE,eAAe,YAAY;CACnC,MAAM,QAAQ,QAAQ;CACtB,MAAM,eAAe,QAAQ,mBACzB,MAAM,+BAA+B;EAAE;EAAe;EAAO,kBAAkB,QAAQ;CAAiB,CAAC,IACzG,CAAC;CACL,MAAM,QAAQ,QAAQ;CACtB,IAAI,CAAC,SAAS,aAAa,MAAK,cAAa,UAAU,KAAK,OAAO,KAAK,GAAG,OAAO;CAClF,MAAM,OAAO,MAAM,cAAc,oBAAoB,IAAI;EAAE;EAAO,IAAI;CAAM,CAAC;CAC7E,IAAI,CAAC,MAAM,OAAO;CAClB,MAAM,aAAa,MAAM,cAAc,YAAY,IAAI;EAAE;EAAO,IAAI,KAAK;CAAa,CAAC;CACvF,MAAM,aAAa,aAAa,MAAM,cAAc,aAAa,IAAI;EAAE;EAAO,IAAI,KAAK;CAAa,CAAC,IAAI;CACzG,IAAI,CAAC,cAAc,CAAC,YAAY,OAAO;CACvC,OAAO,CAAC,GAAG,cAAc;EAAE;EAAM;EAAY;CAAW,CAAC;AAC3D;AAEA,SAAgB,0BACd,cACA,MACmC;CACnC,MAAM,SAAS,KAAK,KAAK,CAAC,CAAC,YAAY;CACvC,OAAO,aAAa,MAAK,cAAa,UAAU,WAAW,KAAK,YAAY,MAAM,MAAM;AAC1F;AAEA,SAAgB,iBAAiB,cAAiD;CAChF,OAAO,aAAa,KAAI,cAAa,UAAU,WAAW,IAAI;AAChE"}

package/dist/session/environment-state-processor.d.ts

@@ -0,0 +1,59 @@
+import type { ComputeStateSignalArgs, ComputeStateSignalResult, Processor } from '@mastra/core/processors';
+export type EnvironmentRepositorySetupStatus = 'ok' | 'failed' | 'skipped';
+/** One repository of the booted environment as the agent is told about it: never a token or a clone URL. */
+export interface SessionEnvironmentRepositoryState {
+    slug: string;
+    /** Absolute directory of the checkout under the workspace root. */
+    dir: string;
+    /** The branch the checkout ended on after boot; `null` when it stays detached. */
+    branch: string | null;
+    defaultBranch: string;
+    position: number;
+    /** `ok` ran or was already set up, `failed` exited non-zero, `skipped` has no setup command. */
+    setupStatus: EnvironmentRepositorySetupStatus;
+    /** The change request this session opened in the repository, once it has. */
+    changeRequestUrl?: string;
+}
+export interface SessionEnvironmentState {
+    /** The workspace root, the session's working directory; repositories sit beneath it. */
+    workingDirectory: string;
+    repositories: SessionEnvironmentRepositoryState[];
+    /** One free-form line the boot wants the agent to know (never a credential), rendered last. */
+    note?: string;
+}
+/** A repository's teardown command and the directory it runs in; kept beside the state, never rendered. */
+export interface SessionEnvironmentTeardown {
+    slug: string;
+    dir: string;
+    command: string;
+}
+export declare function recordSessionEnvironment(sessionId: string, state: SessionEnvironmentState, teardown?: SessionEnvironmentTeardown[]): void;
+/**
+ * Record what a source-control tool did in one environment repository (the
+ * branch it pushed, the change request it opened) so the next signal snapshot
+ * tells the agent. A no-op when the session's environment is not recorded in
+ * this process or the slug is not part of it.
+ */
+export declare function updateSessionEnvironmentRepository(sessionId: string, slug: string, patch: {
+    branch?: string;
+    changeRequestUrl?: string;
+}): void;
+/** Set or clear the environment's note; a no-op when the session's environment is not recorded here. */
+export declare function setSessionEnvironmentNote(sessionId: string, note: string | null): void;
+export declare function clearSessionEnvironment(sessionId: string): void;
+export declare function peekSessionEnvironment(sessionId: string): SessionEnvironmentState | undefined;
+/** Teardown commands of the booted environment, in position order. */
+export declare function peekSessionEnvironmentTeardown(sessionId: string): SessionEnvironmentTeardown[];
+export declare function __clearSessionEnvironmentsForTests(): void;
+/**
+ * Tells the agent which repositories its sandbox holds and where: the
+ * workspace root is the session's working directory and every environment
+ * repository is a directory beneath it. Snapshot mode only; a new snapshot
+ * is emitted when the booted set changes (a start after an environment edit).
+ */
+export declare class FactoryEnvironmentStateProcessor implements Processor<'factory-environment'> {
+    readonly id = "factory-environment";
+    readonly stateId = "factory-environment";
+    computeStateSignal(args: ComputeStateSignalArgs): Promise<ComputeStateSignalResult>;
+}
+//# sourceMappingURL=environment-state-processor.d.ts.map

package/dist/session/environment-state-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-state-processor.d.ts","sourceRoot":"","sources":["../../src/session/environment-state-processor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAK3G,MAAM,MAAM,gCAAgC,GAAG,IAAI,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE3E,4GAA4G;AAC5G,MAAM,WAAW,iCAAiC;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,gGAAgG;IAChG,WAAW,EAAE,gCAAgC,CAAC;IAC9C,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,wFAAwF;IACxF,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,iCAAiC,EAAE,CAAC;IAClD,+FAA+F;IAC/F,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAQD,2GAA2G;AAC3G,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,uBAAuB,EAC9B,QAAQ,GAAE,0BAA0B,EAAO,GAC1C,IAAI,CAEN;AAED;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAChD,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD,IAAI,CAaN;AAED,wGAAwG;AACxG,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAKtF;AAED,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAE7F;AAED,sEAAsE;AACtE,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,GAAG,0BAA0B,EAAE,CAE9F;AAED,wBAAgB,kCAAkC,IAAI,IAAI,CAEzD;AAmBD;;;;;GAKG;AACH,qBAAa,gCAAiC,YAAW,SAAS,CAAC,qBAAqB,CAAC;IACvF,QAAQ,CAAC,EAAE,yBAAY;IACvB,QAAQ,CAAC,OAAO,yBAAY;IAEtB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,wBAAwB,CAAC;CAiC1F"}

package/dist/session/environment-state-processor.js

@@ -0,0 +1,105 @@
+import { createHash } from "crypto";
+//#region src/session/environment-state-processor.ts
+const STATE_ID = "factory-environment";
+const environments = /* @__PURE__ */ new Map();
+function recordSessionEnvironment(sessionId, state, teardown = []) {
+	environments.set(sessionId, {
+		state,
+		teardown
+	});
+}
+/**
+* Record what a source-control tool did in one environment repository (the
+* branch it pushed, the change request it opened) so the next signal snapshot
+* tells the agent. A no-op when the session's environment is not recorded in
+* this process or the slug is not part of it.
+*/
+function updateSessionEnvironmentRepository(sessionId, slug, patch) {
+	const entry = environments.get(sessionId);
+	if (!entry) return;
+	const wanted = slug.toLowerCase();
+	const repositories = entry.state.repositories.map((repo) => {
+		if (repo.slug.toLowerCase() !== wanted) return repo;
+		return {
+			...repo,
+			...patch.branch !== void 0 ? { branch: patch.branch } : {},
+			...patch.changeRequestUrl !== void 0 ? { changeRequestUrl: patch.changeRequestUrl } : {}
+		};
+	});
+	entry.state = {
+		...entry.state,
+		repositories
+	};
+}
+/** Set or clear the environment's note; a no-op when the session's environment is not recorded here. */
+function setSessionEnvironmentNote(sessionId, note) {
+	const entry = environments.get(sessionId);
+	if (!entry) return;
+	const { note: _previous, ...rest } = entry.state;
+	entry.state = note ? {
+		...rest,
+		note
+	} : rest;
+}
+function clearSessionEnvironment(sessionId) {
+	environments.delete(sessionId);
+}
+function peekSessionEnvironment(sessionId) {
+	return environments.get(sessionId)?.state;
+}
+/** Teardown commands of the booted environment, in position order. */
+function peekSessionEnvironmentTeardown(sessionId) {
+	return environments.get(sessionId)?.teardown ?? [];
+}
+function __clearSessionEnvironmentsForTests() {
+	environments.clear();
+}
+function escapeText(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function sessionIdFromContext(requestContext) {
+	if (!requestContext || typeof requestContext.get !== "function") return null;
+	const controller = requestContext.get("controller");
+	return typeof controller?.resourceId === "string" && controller.resourceId ? controller.resourceId : null;
+}
+function environmentCacheKey(state) {
+	return `environment:${createHash("sha256").update(JSON.stringify(state)).digest("hex").slice(0, 16)}`;
+}
+/**
+* Tells the agent which repositories its sandbox holds and where: the
+* workspace root is the session's working directory and every environment
+* repository is a directory beneath it. Snapshot mode only; a new snapshot
+* is emitted when the booted set changes (a start after an environment edit).
+*/
+var FactoryEnvironmentStateProcessor = class {
+	id = STATE_ID;
+	stateId = STATE_ID;
+	async computeStateSignal(args) {
+		const sessionId = sessionIdFromContext(args.requestContext);
+		if (!sessionId) return;
+		const state = environments.get(sessionId)?.state;
+		if (!state) return;
+		const cacheKey = environmentCacheKey(state);
+		if (Boolean(args.lastSnapshot) && args.contextWindow.hasSnapshot && (args.tracking?.currentCacheKey ?? args.lastSnapshot?.metadata?.state?.cacheKey) === cacheKey) return;
+		const lines = state.repositories.map((repo) => `${repo.position}. ${escapeText(repo.slug)} at ${escapeText(repo.dir)} on ${escapeText(repo.branch ?? "(detached)")} (default ${escapeText(repo.defaultBranch)}, setup ${repo.setupStatus})` + (repo.changeRequestUrl ? `, change request ${escapeText(repo.changeRequestUrl)}` : ""));
+		const only = state.repositories.length === 1 ? state.repositories[0] : void 0;
+		const contents = (only ? `Factory environment: 1 repository, ${escapeText(only.slug)} at ${escapeText(only.dir)}, your working directory.\n` : `Factory environment: ${state.repositories.length} repositories under ${escapeText(state.workingDirectory)}, your working directory.\n`) + lines.join("\n") + (only ? "" : "\nRun git and project commands inside the repository directory they belong to.") + (state.note ? `\n${escapeText(state.note)}` : "");
+		return {
+			id: STATE_ID,
+			cacheKey,
+			mode: "snapshot",
+			tagName: "factory-environment",
+			contents,
+			value: { environment: state },
+			attributes: {
+				workingDirectory: only?.dir ?? state.workingDirectory,
+				repositories: state.repositories.length
+			},
+			metadata: { value: { environment: state } }
+		};
+	}
+};
+//#endregion
+export { FactoryEnvironmentStateProcessor, __clearSessionEnvironmentsForTests, clearSessionEnvironment, peekSessionEnvironment, peekSessionEnvironmentTeardown, recordSessionEnvironment, setSessionEnvironmentNote, updateSessionEnvironmentRepository };
+
+//# sourceMappingURL=environment-state-processor.js.map

package/dist/session/environment-state-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-state-processor.js","names":[],"sources":["../../src/session/environment-state-processor.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\nimport type { ComputeStateSignalArgs, ComputeStateSignalResult, Processor } from '@mastra/core/processors';\nimport type { RequestContext } from '@mastra/core/request-context';\n\nconst STATE_ID = 'factory-environment';\n\nexport type EnvironmentRepositorySetupStatus = 'ok' | 'failed' | 'skipped';\n\n/** One repository of the booted environment as the agent is told about it: never a token or a clone URL. */\nexport interface SessionEnvironmentRepositoryState {\n  slug: string;\n  /** Absolute directory of the checkout under the workspace root. */\n  dir: string;\n  /** The branch the checkout ended on after boot; `null` when it stays detached. */\n  branch: string | null;\n  defaultBranch: string;\n  position: number;\n  /** `ok` ran or was already set up, `failed` exited non-zero, `skipped` has no setup command. */\n  setupStatus: EnvironmentRepositorySetupStatus;\n  /** The change request this session opened in the repository, once it has. */\n  changeRequestUrl?: string;\n}\n\nexport interface SessionEnvironmentState {\n  /** The workspace root, the session's working directory; repositories sit beneath it. */\n  workingDirectory: string;\n  repositories: SessionEnvironmentRepositoryState[];\n  /** One free-form line the boot wants the agent to know (never a credential), rendered last. */\n  note?: string;\n}\n\n// The boot records what it materialized, keyed by the factory session id (the\n// agent's resource id); the processor reads it on the next model step. Boot\n// runs on every sandbox start, so a replacement process re-learns the state\n// the first time the session's sandbox starts again.\nconst environments = new Map<string, { state: SessionEnvironmentState; teardown: SessionEnvironmentTeardown[] }>();\n\n/** A repository's teardown command and the directory it runs in; kept beside the state, never rendered. */\nexport interface SessionEnvironmentTeardown {\n  slug: string;\n  dir: string;\n  command: string;\n}\n\nexport function recordSessionEnvironment(\n  sessionId: string,\n  state: SessionEnvironmentState,\n  teardown: SessionEnvironmentTeardown[] = [],\n): void {\n  environments.set(sessionId, { state, teardown });\n}\n\n/**\n * Record what a source-control tool did in one environment repository (the\n * branch it pushed, the change request it opened) so the next signal snapshot\n * tells the agent. A no-op when the session's environment is not recorded in\n * this process or the slug is not part of it.\n */\nexport function updateSessionEnvironmentRepository(\n  sessionId: string,\n  slug: string,\n  patch: { branch?: string; changeRequestUrl?: string },\n): void {\n  const entry = environments.get(sessionId);\n  if (!entry) return;\n  const wanted = slug.toLowerCase();\n  const repositories = entry.state.repositories.map(repo => {\n    if (repo.slug.toLowerCase() !== wanted) return repo;\n    return {\n      ...repo,\n      ...(patch.branch !== undefined ? { branch: patch.branch } : {}),\n      ...(patch.changeRequestUrl !== undefined ? { changeRequestUrl: patch.changeRequestUrl } : {}),\n    };\n  });\n  entry.state = { ...entry.state, repositories };\n}\n\n/** Set or clear the environment's note; a no-op when the session's environment is not recorded here. */\nexport function setSessionEnvironmentNote(sessionId: string, note: string | null): void {\n  const entry = environments.get(sessionId);\n  if (!entry) return;\n  const { note: _previous, ...rest } = entry.state;\n  entry.state = note ? { ...rest, note } : rest;\n}\n\nexport function clearSessionEnvironment(sessionId: string): void {\n  environments.delete(sessionId);\n}\n\nexport function peekSessionEnvironment(sessionId: string): SessionEnvironmentState | undefined {\n  return environments.get(sessionId)?.state;\n}\n\n/** Teardown commands of the booted environment, in position order. */\nexport function peekSessionEnvironmentTeardown(sessionId: string): SessionEnvironmentTeardown[] {\n  return environments.get(sessionId)?.teardown ?? [];\n}\n\nexport function __clearSessionEnvironmentsForTests(): void {\n  environments.clear();\n}\n\nfunction escapeText(value: string): string {\n  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');\n}\n\n// The session id is the controller's resource id. Unlike factory runs, a user\n// session carries no `factoryProjectId` in its controller state, and the\n// environment is recorded for both, so only the resource id is required.\nfunction sessionIdFromContext(requestContext: RequestContext | undefined): string | null {\n  if (!requestContext || typeof requestContext.get !== 'function') return null;\n  const controller = requestContext.get('controller') as { resourceId?: unknown } | undefined;\n  return typeof controller?.resourceId === 'string' && controller.resourceId ? controller.resourceId : null;\n}\n\nfunction environmentCacheKey(state: SessionEnvironmentState): string {\n  return `environment:${createHash('sha256').update(JSON.stringify(state)).digest('hex').slice(0, 16)}`;\n}\n\n/**\n * Tells the agent which repositories its sandbox holds and where: the\n * workspace root is the session's working directory and every environment\n * repository is a directory beneath it. Snapshot mode only; a new snapshot\n * is emitted when the booted set changes (a start after an environment edit).\n */\nexport class FactoryEnvironmentStateProcessor implements Processor<'factory-environment'> {\n  readonly id = STATE_ID;\n  readonly stateId = STATE_ID;\n\n  async computeStateSignal(args: ComputeStateSignalArgs): Promise<ComputeStateSignalResult> {\n    const sessionId = sessionIdFromContext(args.requestContext);\n    if (!sessionId) return;\n    const state = environments.get(sessionId)?.state;\n    if (!state) return;\n    const cacheKey = environmentCacheKey(state);\n    const hasBase = Boolean(args.lastSnapshot) && args.contextWindow.hasSnapshot;\n    if (hasBase && (args.tracking?.currentCacheKey ?? args.lastSnapshot?.metadata?.state?.cacheKey) === cacheKey)\n      return;\n    const lines = state.repositories.map(\n      repo =>\n        `${repo.position}. ${escapeText(repo.slug)} at ${escapeText(repo.dir)} on ${escapeText(repo.branch ?? '(detached)')} (default ${escapeText(repo.defaultBranch)}, setup ${repo.setupStatus})` +\n        (repo.changeRequestUrl ? `, change request ${escapeText(repo.changeRequestUrl)}` : ''),\n    );\n    const only = state.repositories.length === 1 ? state.repositories[0] : undefined;\n    const contents =\n      (only\n        ? `Factory environment: 1 repository, ${escapeText(only.slug)} at ${escapeText(only.dir)}, your working directory.\\n`\n        : `Factory environment: ${state.repositories.length} repositories under ${escapeText(state.workingDirectory)}, your working directory.\\n`) +\n      lines.join('\\n') +\n      (only ? '' : '\\nRun git and project commands inside the repository directory they belong to.') +\n      (state.note ? `\\n${escapeText(state.note)}` : '');\n    return {\n      id: STATE_ID,\n      cacheKey,\n      mode: 'snapshot',\n      tagName: 'factory-environment',\n      contents,\n      value: { environment: state },\n      attributes: { workingDirectory: only?.dir ?? state.workingDirectory, repositories: state.repositories.length },\n      metadata: { value: { environment: state } },\n    };\n  }\n}\n"],"mappings":"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"}

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

@@ -51,8 +51,12 @@ export interface EnsureFactorySourceSessionArgs {
     orgId: string;
     factoryProjectId: string;
     branch: string;
-    /** Pick the linked repository that the work item targets. */
-    repositorySlug: string;
+    /**
+     * The repository link the session is filed under: the one a work item
+     * targets. Defaults to the factory's position-1 environment link (D1), for
+     * callers where nothing names a repository (chat threads, user sessions).
+     */
+    projectRepositoryId?: string;
     /**
      * Attribute the run to this user instead of the repo connector. Set when the
      * run has an interactive user — e.g. the person who approved a proposed run.
@@ -78,10 +82,11 @@ export interface ResolvedFactorySourceRepository {
     connectedByUserId: string;
 }
 /**
- * Outcome of {@link resolveFactorySourceRepository}. A miss carries which step
- * failed: callers differ on whether that is an error (an autonomous run cannot
- * proceed) or a routine fallback (a chat integration drops to a chat-only
- * session), and the two steps fail for different reasons worth reporting apart.
+ * Outcome of {@link resolvePrimaryEnvironmentRepository}. A miss carries which
+ * step failed: callers differ on whether that is an error (an autonomous run
+ * cannot proceed) or a routine fallback (a chat integration drops to a
+ * chat-only session), and the two steps fail for different reasons worth
+ * reporting apart.
  */
 export type FactorySourceRepositoryResult = ({
     found: true;
@@ -90,49 +95,35 @@ export type FactorySourceRepositoryResult = ({
     reason: 'connection' | 'repository';
 };
 /**
- * Resolve which repository a factory project's source-control runs act on: the
- * owner's connection on the project, then one of its linked repositories.
+ * The repository link a new session is filed under. By default the position-1
+ * `inEnvironment` link of the factory (decision D1); a work item that targets
+ * a repository names its link through `projectRepositoryId`, which must be an
+ * environment link of the same factory. Session start no longer picks a
+ * repository to work in, the sandbox holds every environment repository. The
+ * PR tools default to this link, and subscriptions, audit and the work item's
+ * repository check still read it; moving them to the per-repository
+ * `sessionRepositories` rows is a follow-up.
  *
  * The owner is whichever integration owns source control, matched by the
  * handle's own `integrationId` — nothing here is provider-specific.
  */
-export declare function resolveFactorySourceRepository(args: {
+export declare function resolvePrimaryEnvironmentRepository(args: {
     sourceControl: SourceControlStorageHandle;
     orgId: string;
     factoryProjectId: string;
-    repositorySlug: string;
-} | {
-    sourceControl: SourceControlStorageHandle;
-    orgId: string;
-    factoryProjectId: string;
-    firstLinkedRepository: true;
+    projectRepositoryId?: string;
 }): Promise<FactorySourceRepositoryResult>;
-/**
- * Walk a Factory user-session id back to the project it belongs to.
- *
- * Repo-backed channel threads are keyed by their Factory session id, which is
- * the only handle a session-start hook gets. This turns that id back into the
- * project whose configuration the session should adopt. Durable by
- * construction — it reads the same rows the session was created from, so it
- * survives restarts without any in-memory mapping.
- */
-export declare function resolveFactoryProjectForSession(args: {
-    sourceControl: SourceControlStorageHandle;
-    sessionId: string;
-}): Promise<{
-    factoryProjectId: string;
-    orgId: string;
-    userId: string;
-} | null>;
 /**
  * Create the source-control session a repo-backed factory run needs.
  *
  * `FactoryStartCoordinator.prepare` requires this record to already exist —
  * `resolveSourceSession` throws `Factory session not found` otherwise — so every
  * autonomous entry point has to produce one before it can start a run. This is
- * that step, in one place: the owner's connection on the factory project, one of
- * its linked repositories, and a session on the requested branch with the
- * repository's pinned or default branch as the base.
+ * that step, in one place: the owner's connection on the factory project, the
+ * work item's repository link (else the position-1 environment link, D1) as
+ * the session's link, and a session on the requested branch with that
+ * repository's pinned or default branch as the base. The sandbox itself boots
+ * every environment repository.
  *
  * The run is attributed to `attributeToUserId` when the caller has an
  * interactive user (e.g. the approver of a proposed run), and otherwise falls