@mastra/factory 0.17.3-alpha.5 → 0.18.0-alpha.10

package/dist/rules/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../src/rules/types.ts"],"sourcesContent":["import type { ExternalWorkItemSource } from '../storage/domains/work-items/base.js';\n\nexport type WorkItemSource =\n  | 'github-issue'\n  | 'github-pr'\n  | 'gitlab-issue'\n  | 'gitlab-pr'\n  | 'linear-issue'\n  | 'jira-issue'\n  | 'incidentio-follow-up'\n  | 'manual';\n\nexport function externalSourceForWorkItem(\n  source: WorkItemSource,\n  sourceKey: string,\n  url?: string,\n): ExternalWorkItemSource {\n  const [integrationId, type] =\n    source === 'github-pr'\n      ? ['github', 'pull-request']\n      : source === 'github-issue'\n        ? ['github', 'issue']\n        : source === 'gitlab-pr'\n          ? ['gitlab', 'pull-request']\n          : source === 'gitlab-issue'\n            ? ['gitlab', 'issue']\n            : source === 'linear-issue'\n              ? ['linear', 'issue']\n              : source === 'jira-issue'\n                ? ['jira', 'issue']\n                : source === 'incidentio-follow-up'\n                  ? ['incidentio', 'issue']\n                  : ['factory', 'manual'];\n  return { integrationId, type, externalId: sourceKey, ...(url ? { url } : {}) };\n}\n\n/** The source label that holds an issue at rest until a maintainer decides; compared lowercased. */\nexport const NEEDS_APPROVAL_LABEL = 'status: needs approval';\nexport const AUTO_TRIAGED_LABEL = 'status: auto-triaged';\n\n// The label only holds a card at rest: once a person accepted it, or it sits in a working\n// lane only a person could have moved it into, the label is stale until the source catches up.\nexport function needsApproval(item: {\n  metadata: Record<string, unknown> | null;\n  stages?: readonly string[];\n  acceptedAt?: Date | string | null;\n}): boolean {\n  const labels = item.metadata?.labels;\n  if (!Array.isArray(labels)) return false;\n  return (\n    labels.some(label => typeof label === 'string' && label.toLowerCase() === NEEDS_APPROVAL_LABEL) &&\n    !item.acceptedAt &&\n    (item.stages ?? ['intake']).every(stage => stage === 'intake' || stage === 'triage')\n  );\n}\n\nexport function workItemSource(source: ExternalWorkItemSource | null): WorkItemSource {\n  if (!source) return 'manual';\n  if (source.integrationId === 'linear') return 'linear-issue';\n  if (source.integrationId === 'gitlab') return source.type === 'pull-request' ? 'gitlab-pr' : 'gitlab-issue';\n  if (source.integrationId === 'jira') return 'jira-issue';\n  if (source.integrationId === 'incidentio') return 'incidentio-follow-up';\n  // Only GitHub, GitLab, Linear, Jira, and incident.io have provider-specific\n  // rules; anything else (a Slack thread, say) is a plain work item, not a\n  // mislabeled GitHub issue.\n  if (source.integrationId !== 'github') return 'manual';\n  return source.type === 'pull-request' ? 'github-pr' : 'github-issue';\n}\n\n// Authored outside the write-access circle: a missing trust stamp fails closed until\n// the reconcile sweep backfills it, and Factory's own PRs pass through `factoryAuthored`.\nexport function externallyAuthored(item: { source: string; metadata: Record<string, unknown> | null }): boolean {\n  if (!['github-pr', 'github-issue', 'gitlab-pr', 'gitlab-issue'].includes(item.source)) return false;\n  if (item.metadata?.factoryAuthored === true) return false;\n  return item.metadata?.authorTrusted !== true;\n}\n\n// The board mark claims only what GitHub answered: a missing stamp is silence, not an outside contribution.\nexport function knownExternalAuthor(item: { source: string; metadata: Record<string, unknown> | null }): boolean {\n  return externallyAuthored(item) && item.metadata?.authorTrusted === false;\n}\n\nexport function externallyAuthoredWorkItem(item: {\n  externalSource: ExternalWorkItemSource | null;\n  metadata: Record<string, unknown> | null;\n}): boolean {\n  return externallyAuthored({ source: workItemSource(item.externalSource), metadata: item.metadata });\n}\n\nexport const FACTORY_RULE_STAGES = ['intake', 'triage', 'planning', 'execute', 'review', 'done', 'canceled'] as const;\nexport type FactoryRuleStage = (typeof FACTORY_RULE_STAGES)[number] | (string & {});\n\n// Each role and the working stage its run holds the card in. Key order is the\n// seat pipeline order — Resume depth derives from it.\nexport const FACTORY_ROLE_STAGES = {\n  triage: 'triage',\n  plan: 'planning',\n  work: 'execute',\n  review: 'review',\n} as const satisfies Record<string, FactoryRuleStage>;\nexport type FactoryRole = keyof typeof FACTORY_ROLE_STAGES;\n\nexport function isFactoryRole(value: string): value is FactoryRole {\n  return value in FACTORY_ROLE_STAGES;\n}\n\nexport const FACTORY_TRIAGE_TYPES = [\n  'bug',\n  'feature request',\n  'docs',\n  'question/support',\n  'maintenance',\n  'duplicate',\n  'resolved',\n  'invalid',\n  'spam',\n  'out-of-scope',\n  'other',\n] as const;\nexport type FactoryTriageType = (typeof FACTORY_TRIAGE_TYPES)[number];\n\nexport function isFactoryTriageType(value: unknown): value is FactoryTriageType {\n  return typeof value === 'string' && FACTORY_TRIAGE_TYPES.some(type => type === value);\n}\n\nexport function isFactoryRuleStage(value: unknown): value is FactoryRuleStage {\n  return typeof value === 'string' && FACTORY_RULE_STAGES.some(stage => stage === value);\n}\n\nexport function factoryRuleStage(stages: readonly string[]): FactoryRuleStage | undefined {\n  const stage = stages.length === 1 ? stages[0] : undefined;\n  return typeof stage === 'string' && stage.length > 0 ? stage : undefined;\n}\n\nexport function isTerminalFactoryRuleStage(stages: readonly string[]): boolean {\n  const stage = factoryRuleStage(stages);\n  return stage === 'done' || stage === 'canceled';\n}\n\n/** Working lanes hold cards with a seat engaged; Intake, Done and Canceled rest them. */\nexport function isWorkingFactoryRuleStage(stage: FactoryRuleStage): boolean {\n  return stage !== 'intake' && !isTerminalFactoryRuleStage([stage]);\n}\n\n// Consulted only for the Intake exit: roles don't own lanes, so a card already\n// in a working or terminal lane stays put when a run starts.\nexport function factoryLaneForRole(role: string): FactoryRuleStage | undefined {\n  return isFactoryRole(role) ? FACTORY_ROLE_STAGES[role] : undefined;\n}\n\nexport const FACTORY_RULE_BOARDS = ['work', 'review'] as const;\nexport type FactoryRuleBoard = (typeof FACTORY_RULE_BOARDS)[number] | (string & {});\n\nexport const FACTORY_RULE_SOURCES = [\n  'issue',\n  'pullRequest',\n  'gitlabIssue',\n  'gitlabPullRequest',\n  'linearIssue',\n  'jiraIssue',\n  'incidentioFollowUp',\n  'manual',\n] as const;\nexport type FactoryRuleSource = (typeof FACTORY_RULE_SOURCES)[number];\n\nexport const FACTORY_GITHUB_EVENTS = [\n  'issueOpened',\n  'issueEdited',\n  'issueClosed',\n  'issueCommentCreated',\n  'issueCommentEdited',\n  'issueCommentDeleted',\n  'pullRequestOpened',\n  'pullRequestUpdated',\n  'pullRequestCommentCreated',\n  'pullRequestReviewRequested',\n  'pullRequestReviewSubmitted',\n  'pullRequestMerged',\n  'pullRequestClosed',\n] as const;\nexport type FactoryGithubEventName = (typeof FACTORY_GITHUB_EVENTS)[number];\n\nexport const FACTORY_GITLAB_EVENTS = [\n  'issueOpened',\n  'issueUpdated',\n  'issueClosed',\n  'issueCommented',\n  'mergeRequestOpened',\n  'mergeRequestUpdated',\n  'mergeRequestCommented',\n  'mergeRequestMerged',\n  'mergeRequestClosed',\n] as const;\nexport type FactoryGitLabEventName = (typeof FACTORY_GITLAB_EVENTS)[number];\n\nexport const FACTORY_LINEAR_EVENTS = ['issueObserved', 'issueClosed'] as const;\nexport type FactoryLinearEventName = (typeof FACTORY_LINEAR_EVENTS)[number];\n\nexport const FACTORY_JIRA_EVENTS = ['issueObserved', 'issueClosed'] as const;\nexport type FactoryJiraEventName = (typeof FACTORY_JIRA_EVENTS)[number];\n\nexport const FACTORY_INCIDENTIO_EVENTS = ['followUpObserved', 'followUpClosed'] as const;\nexport type FactoryIncidentioEventName = (typeof FACTORY_INCIDENTIO_EVENTS)[number];\n\nexport type FactoryRuleJsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | FactoryRuleJsonValue[]\n  | { [key: string]: FactoryRuleJsonValue };\n\nexport interface FactoryRuleItemContext {\n  id: string;\n  source: WorkItemSource;\n  sourceKey: string | null;\n  parentWorkItemId: string | null;\n  title: string;\n  url: string | null;\n  stages: readonly string[];\n  acceptedAt: Date | null;\n  /** Intake-stamped facts about the source — repository id, reporter login, labels. */\n  metadata: Record<string, unknown> | null;\n}\n\nexport type FactoryRuleActor =\n  | { type: 'human'; id: string }\n  | { type: 'agent'; bindingId: string; role: string }\n  | { type: 'github'; login: string; trusted: boolean; factoryAuthored: boolean }\n  | { type: 'gitlab'; username: string; trusted: boolean; factoryAuthored: boolean }\n  | { type: 'system'; id: string };\n\nexport interface FactoryRuleIngressIdentity {\n  type: 'human' | 'agent' | 'toolResult' | 'github' | 'gitlab' | 'linear' | 'jira' | 'incidentio' | 'rule';\n  id: string;\n}\n\nexport interface FactoryRuleCausalEntry {\n  ingressId: string;\n  decisionType: FactoryCommitDecision['type'];\n}\n\nexport interface FactoryRuleContextBase {\n  tenant: { orgId: string; projectId: string };\n  actor: FactoryRuleActor;\n  ingress: FactoryRuleIngressIdentity;\n  cause: string;\n  causalChain: readonly FactoryRuleCausalEntry[];\n  configVersion: string;\n}\n\nexport interface FactoryBoundRuleContext extends FactoryRuleContextBase {\n  item: FactoryRuleItemContext;\n  board: FactoryRuleBoard;\n  itemRevision: number;\n}\n\nexport interface FactoryStageRuleContext extends FactoryBoundRuleContext {\n  source: FactoryRuleSource;\n  stage: FactoryRuleStage;\n  fromStage: FactoryRuleStage;\n  toStage: FactoryRuleStage;\n}\n\nexport interface FactoryToolResultRuleContext extends FactoryBoundRuleContext {\n  toolName: string;\n  threadId: string;\n  assistantMessageId: string;\n  toolCallId: string;\n  result: {\n    status: 'success' | 'error';\n    value: FactoryRuleJsonValue;\n  };\n}\n\nexport interface FactoryGithubRuleContext extends FactoryRuleContextBase {\n  item?: FactoryRuleItemContext;\n  board?: FactoryRuleBoard;\n  itemRevision?: number;\n  /**\n   * Board an issue's labels route it to, when the project has a matching label route and that board\n   * is installed. Absent for pull requests and for issues whose labels select nothing.\n   */\n  intake?: FactoryRuleIntakeTarget;\n  /**\n   * Set on the one evaluation per pull request delivery that files the pull\n   * request's own Review card. Opening a pull request concerns two cards — that\n   * Review card and the Work item that authored the pull request — so the rule\n   * answers for the two separately: the arrival carries this flag and is\n   * committed against the authoring item when resolution found one, which is\n   * what links the new card to it, while the authoring item's own evaluation\n   * leaves the flag unset.\n   */\n  pullRequestIntake?: boolean;\n  event: FactoryGithubEventName;\n  deliveryId: string;\n  factory: { createdAt: string };\n  repository: { id: number; fullName: string };\n  issue?: {\n    number: number;\n    title: string;\n    url: string;\n    createdAt?: string;\n    updatedAt?: string;\n    assignees?: string[];\n    labels?: string[];\n    state?: 'open' | 'closed';\n    /** GitHub close reason: `completed`, `not_planned`, or `duplicate`. */\n    stateReason?: string;\n  };\n  issueChange?: { title: boolean; body: boolean };\n  issueComment?: {\n    id: number;\n    body?: string;\n    url?: string;\n    author?: string;\n    authorType?: string;\n    createdAt?: string;\n    updatedAt?: string;\n  };\n  pullRequest?: {\n    number: number;\n    title: string;\n    url: string;\n    createdAt?: string;\n    state: 'open' | 'closed';\n    draft: boolean;\n    merged: boolean;\n    assignees?: string[];\n    requestedReviewers?: string[];\n    labels?: string[];\n    author?: string;\n    factoryAuthored: boolean;\n    headBranch: string;\n    baseBranch: string;\n  };\n  /** Present on `pullRequestReviewRequested`: who review was (re-)requested from. */\n  reviewRequest?: { reviewer: string; factoryReviewer: boolean };\n  /** Present when a PR comment uses Factory's exact review command. */\n  reviewCommand?: { command: 'review' | 're-review'; target: string };\n  /** Present on `pullRequestReviewSubmitted`: the review that was just posted. */\n  review?: { id: number; state: string; url: string };\n}\n\n/**\n * Where an intake source binding says new items from this source should land.\n * Absent when the source is unbound or bound without a board (built-in routing).\n */\nexport interface FactoryRuleIntakeTarget {\n  board: string;\n  initialPhase: string;\n}\n\nexport interface FactoryGitLabRuleContext extends FactoryRuleContextBase {\n  item?: FactoryRuleItemContext;\n  board?: FactoryRuleBoard;\n  itemRevision?: number;\n  intake?: FactoryRuleIntakeTarget;\n  event: FactoryGitLabEventName;\n  deliveryId: string;\n  factory: { createdAt: string };\n  repository: { id: number; fullName: string; host: string };\n  issue?: {\n    number: number;\n    sourceKey: string;\n    title: string;\n    url: string;\n    createdAt?: string;\n    updatedAt?: string;\n    assignees?: string[];\n    labels?: string[];\n    labelColors?: Record<string, string>;\n    state?: 'open' | 'closed';\n    author?: string;\n    authorTrusted: boolean;\n  };\n  note?: {\n    id: number;\n    body?: string;\n    url?: string;\n    author?: string;\n    createdAt?: string;\n    updatedAt?: string;\n  };\n  mergeRequest?: {\n    number: number;\n    sourceKey: string;\n    title: string;\n    url: string;\n    createdAt?: string;\n    state: 'open' | 'closed';\n    draft: boolean;\n    merged: boolean;\n    assignees?: string[];\n    reviewers?: string[];\n    labels?: string[];\n    labelColors?: Record<string, string>;\n    author?: string;\n    authorTrusted: boolean;\n    factoryAuthored: boolean;\n    headBranch: string;\n    baseBranch: string;\n  };\n}\n\nexport interface FactoryLinearRuleContext extends FactoryRuleContextBase {\n  item?: FactoryRuleItemContext;\n  board?: FactoryRuleBoard;\n  itemRevision?: number;\n  /** Bound board for the source this issue came from, when one is configured and installed. */\n  intake?: FactoryRuleIntakeTarget;\n  event: FactoryLinearEventName;\n  issue: {\n    id: string;\n    identifier: string;\n    title: string;\n    url: string;\n    state: string;\n    stateType: string;\n    priorityLabel: string;\n    assignee: string | null;\n    creator: string | null;\n    team: string | null;\n    labels: readonly string[];\n    createdAt: string;\n    updatedAt: string;\n  };\n}\n\nexport interface FactoryJiraRuleContext extends FactoryRuleContextBase {\n  item?: FactoryRuleItemContext;\n  board?: FactoryRuleBoard;\n  itemRevision?: number;\n  /** Bound board for the source this issue came from, when one is configured and installed. */\n  intake?: FactoryRuleIntakeTarget;\n  event: FactoryJiraEventName;\n  issue: {\n    /** Stable issue reference — the direct integration's Jira id or the Platform-encoded issue reference. */\n    id: string;\n    identifier: string;\n    title: string;\n    url: string;\n    state: string;\n    stateType: string;\n    priorityLabel: string;\n    assignee: string | null;\n    author: string | null;\n    project: string | null;\n    site: string | null;\n    labels: readonly string[];\n    createdAt: string;\n    updatedAt: string;\n  };\n}\n\nexport interface FactoryIncidentioRuleContext extends FactoryRuleContextBase {\n  item?: FactoryRuleItemContext;\n  board?: FactoryRuleBoard;\n  itemRevision?: number;\n  /** Bound board for the source this follow-up came from, when one is configured and installed. */\n  intake?: FactoryRuleIntakeTarget;\n  event: FactoryIncidentioEventName;\n  issue: {\n    /** Stable item reference — the prefixed incident.io follow-up id the intake feed serves as `id`. */\n    id: string;\n    identifier: string;\n    title: string;\n    url: string;\n    state: string;\n    stateType: string;\n    priorityLabel: string;\n    assignee: string | null;\n    author: string | null;\n    /** Reference of the incident this follow-up belongs to, when available. */\n    incident: string | null;\n    labels: readonly string[];\n    createdAt: string;\n    updatedAt: string;\n  };\n}\n\nexport type FactoryRuleHandler<TContext> = (\n  context: Readonly<TContext>,\n) => FactoryRuleDecision | void | Promise<FactoryRuleDecision | void>;\n\nexport interface FactoryBoardRuleLeaf {\n  onEnter?: FactoryRuleHandler<FactoryStageRuleContext>;\n  onExit?: FactoryRuleHandler<FactoryStageRuleContext>;\n}\n\nexport type FactoryRuleRejectionCode =\n  | 'forbidden'\n  | 'invalid_transition'\n  | 'missing_binding'\n  | 'stale'\n  | 'timeout'\n  | 'rule_error'\n  | 'causal_depth_exceeded'\n  | 'repeated_transition'\n  | 'approval_required';\n\nexport interface FactoryRuleRejectDecision {\n  type: 'reject';\n  code: FactoryRuleRejectionCode;\n  reason: string;\n}\n\ninterface FactoryCommitDecisionBase {\n  idempotencyKey: string;\n}\n\nexport interface FactoryTransitionDecision extends FactoryCommitDecisionBase {\n  type: 'transition';\n  board: FactoryRuleBoard;\n  stage: FactoryRuleStage;\n  /**\n   * Delivered to the item's active session (waking it if idle) after the\n   * transition commits. Skipped when the item has no active run binding, so\n   * informational messages never fail the transition.\n   */\n  message?: { text: string; role?: string };\n  /**\n   * Runs the stage's entry rules even when the item is already in that stage.\n   * A transition to the current stage is normally inert, because most callers\n   * are correcting a board into a state it already holds. Re-entry is for the\n   * opposite case: the stage's work is in flight and has been invalidated, so\n   * it has to start over.\n   */\n  reenter?: boolean;\n}\n\nexport interface FactoryUpsertLinkedWorkItemDecision extends FactoryCommitDecisionBase {\n  type: 'upsertLinkedWorkItem';\n  board: FactoryRuleBoard;\n  source: WorkItemSource;\n  sourceKey: string;\n  /**\n   * Org-wide ownership key for the external record, when one Factory at a time\n   * may hold a live card for it (a stable Linear issue id, for instance). The\n   * store enforces it with a unique index, so a second project's materialization\n   * is refused rather than duplicated.\n   */\n  claimKey?: string;\n  title: string;\n  url: string | null;\n  stage: FactoryRuleStage;\n  /**\n   * File the card at `stage` as its first entry and run none of the board's\n   * phase rules for it — no arrival, no destination entry. The card is filed\n   * (or, if it already exists, moved) and left parked for a person; nothing is\n   * started for it. For external records that arrive already past the board's\n   * first step: a GitHub issue whose triage is already recorded, for instance.\n   *\n   * Placement is the whole decision. An existing card it reaches is moved to\n   * that stage through the same relocation the label routes use, and its\n   * metadata is left alone.\n   */\n  skipRules?: boolean;\n  metadata?: Record<string, FactoryRuleJsonValue>;\n}\n\ninterface FactoryInvokeSkillDecisionBase extends FactoryCommitDecisionBase {\n  type: 'invokeSkill';\n  role: string;\n  arguments?: string;\n  precedingMessage?: string;\n  cancelInFlight?: boolean;\n}\n\n/**\n * Starting an agent run. Most runs activate a skill, because the skill carries\n * the handoff contract later rules match on. A run whose completion is already\n * signalled some other way — Building finishes by opening a pull request, which\n * arrives as its own event — needs no contract, so it can carry a plain prompt\n * instead of an otherwise empty skill.\n */\nexport type FactoryInvokeSkillDecision = FactoryInvokeSkillDecisionBase &\n  (\n    | {\n        skillName: string;\n        prompt?: never;\n        /**\n         * Same-stage re-entry: the skill is already active in the card's live session,\n         * so deliver a compact continuation that references it by name and carries only\n         * the fresh arguments, instead of re-pasting the whole skill document. Only valid\n         * for named-skill decisions — a plain prompt run has no active skill to resume.\n         */\n        resume?: boolean;\n      }\n    | { prompt: string; skillName?: never; resume?: never }\n  );\n\nexport interface FactorySendMessageDecision extends FactoryCommitDecisionBase {\n  type: 'sendMessage';\n  /** Omitted: the card's live session, whichever seat holds it. Required with `prepareBinding`. */\n  role?: string;\n  message: string;\n  priority?: 'medium' | 'high' | 'urgent';\n  idleBehavior?: 'persist' | 'wake';\n  prepareBinding?: boolean;\n}\n\nexport interface FactoryNotifyDecision extends FactoryCommitDecisionBase {\n  type: 'notify';\n  title: string;\n  body?: string;\n  level?: 'info' | 'warning' | 'error';\n}\n\nexport type FactoryCommitDecision =\n  | FactoryTransitionDecision\n  | FactoryUpsertLinkedWorkItemDecision\n  | FactoryInvokeSkillDecision\n  | FactorySendMessageDecision\n  | FactoryNotifyDecision;\n\nexport type FactoryRuleDecision = FactoryRuleRejectDecision | FactoryCommitDecision;\n\nexport interface FactoryTransitionResultAccepted {\n  status: 'accepted';\n  transitionId: string;\n  itemId: string;\n  revision: number;\n  stage: FactoryRuleStage;\n  decisions: FactoryCommitDecision[];\n}\n\nexport interface FactoryTransitionResultRejected {\n  status: 'rejected';\n  transitionId: string;\n  itemId: string;\n  code: FactoryRuleRejectionCode;\n  reason: string;\n}\n\nexport type FactoryTransitionResult = FactoryTransitionResultAccepted | FactoryTransitionResultRejected;\n\nexport function factoryRuleSourceForWorkItem(source: WorkItemSource): FactoryRuleSource {\n  switch (source) {\n    case 'github-issue':\n      return 'issue';\n    case 'github-pr':\n      return 'pullRequest';\n    case 'gitlab-issue':\n      return 'gitlabIssue';\n    case 'gitlab-pr':\n      return 'gitlabPullRequest';\n    case 'linear-issue':\n      return 'linearIssue';\n    case 'jira-issue':\n      return 'jiraIssue';\n    case 'incidentio-follow-up':\n      return 'incidentioFollowUp';\n    case 'manual':\n      return 'manual';\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/rules/types.ts"],"sourcesContent":["import type { ExternalWorkItemSource } from '../storage/domains/work-items/base.js';\n\nexport type WorkItemSource =\n  | 'github-issue'\n  | 'github-pr'\n  | 'gitlab-issue'\n  | 'gitlab-pr'\n  | 'linear-issue'\n  | 'jira-issue'\n  | 'incidentio-follow-up'\n  | 'manual';\n\nexport function externalSourceForWorkItem(\n  source: WorkItemSource,\n  sourceKey: string,\n  url?: string,\n): ExternalWorkItemSource {\n  const [integrationId, type] =\n    source === 'github-pr'\n      ? ['github', 'pull-request']\n      : source === 'github-issue'\n        ? ['github', 'issue']\n        : source === 'gitlab-pr'\n          ? ['gitlab', 'pull-request']\n          : source === 'gitlab-issue'\n            ? ['gitlab', 'issue']\n            : source === 'linear-issue'\n              ? ['linear', 'issue']\n              : source === 'jira-issue'\n                ? ['jira', 'issue']\n                : source === 'incidentio-follow-up'\n                  ? ['incidentio', 'issue']\n                  : ['factory', 'manual'];\n  return { integrationId, type, externalId: sourceKey, ...(url ? { url } : {}) };\n}\n\n/** The source label that holds an issue at rest until a maintainer decides; compared lowercased. */\nexport const NEEDS_APPROVAL_LABEL = 'status: needs approval';\nexport const AUTO_TRIAGED_LABEL = 'status: auto-triaged';\n\n// The label only holds a card at rest: once a person accepted it, or it sits in a working\n// lane only a person could have moved it into, the label is stale until the source catches up.\nexport function needsApproval(item: {\n  metadata: Record<string, unknown> | null;\n  stages?: readonly string[];\n  acceptedAt?: Date | string | null;\n}): boolean {\n  const labels = item.metadata?.labels;\n  if (!Array.isArray(labels)) return false;\n  return (\n    labels.some(label => typeof label === 'string' && label.toLowerCase() === NEEDS_APPROVAL_LABEL) &&\n    !item.acceptedAt &&\n    (item.stages ?? ['intake']).every(stage => stage === 'intake' || stage === 'triage')\n  );\n}\n\nexport function workItemSource(source: ExternalWorkItemSource | null): WorkItemSource {\n  if (!source) return 'manual';\n  if (source.integrationId === 'linear') return 'linear-issue';\n  if (source.integrationId === 'gitlab') return source.type === 'pull-request' ? 'gitlab-pr' : 'gitlab-issue';\n  if (source.integrationId === 'jira') return 'jira-issue';\n  if (source.integrationId === 'incidentio') return 'incidentio-follow-up';\n  // Only GitHub, GitLab, Linear, Jira, and incident.io have provider-specific\n  // rules; anything else (a Slack thread, say) is a plain work item, not a\n  // mislabeled GitHub issue.\n  if (source.integrationId !== 'github') return 'manual';\n  return source.type === 'pull-request' ? 'github-pr' : 'github-issue';\n}\n\n// Authored outside the write-access circle: a missing trust stamp fails closed until\n// the reconcile sweep backfills it, and Factory's own PRs pass through `factoryAuthored`.\nexport function externallyAuthored(item: { source: string; metadata: Record<string, unknown> | null }): boolean {\n  if (!['github-pr', 'github-issue', 'gitlab-pr', 'gitlab-issue'].includes(item.source)) return false;\n  if (item.metadata?.factoryAuthored === true) return false;\n  return item.metadata?.authorTrusted !== true;\n}\n\n// The board mark claims only what GitHub answered: a missing stamp is silence, not an outside contribution.\nexport function knownExternalAuthor(item: { source: string; metadata: Record<string, unknown> | null }): boolean {\n  return externallyAuthored(item) && item.metadata?.authorTrusted === false;\n}\n\nexport function externallyAuthoredWorkItem(item: {\n  externalSource: ExternalWorkItemSource | null;\n  metadata: Record<string, unknown> | null;\n}): boolean {\n  return externallyAuthored({ source: workItemSource(item.externalSource), metadata: item.metadata });\n}\n\nexport const FACTORY_RULE_STAGES = ['intake', 'triage', 'planning', 'execute', 'review', 'done', 'canceled'] as const;\nexport type FactoryRuleStage = (typeof FACTORY_RULE_STAGES)[number] | (string & {});\n\n// Each role and the working stage its run holds the card in. Key order is the\n// seat pipeline order — Resume depth derives from it.\nexport const FACTORY_ROLE_STAGES = {\n  triage: 'triage',\n  plan: 'planning',\n  work: 'execute',\n  review: 'review',\n} as const satisfies Record<string, FactoryRuleStage>;\nexport type FactoryRole = keyof typeof FACTORY_ROLE_STAGES;\n\nexport function isFactoryRole(value: string): value is FactoryRole {\n  return value in FACTORY_ROLE_STAGES;\n}\n\nexport const FACTORY_TRIAGE_TYPES = [\n  'bug',\n  'feature request',\n  'docs',\n  'question/support',\n  'maintenance',\n  'duplicate',\n  'resolved',\n  'invalid',\n  'spam',\n  'out-of-scope',\n  'other',\n] as const;\nexport type FactoryTriageType = (typeof FACTORY_TRIAGE_TYPES)[number];\n\nexport function isFactoryTriageType(value: unknown): value is FactoryTriageType {\n  return typeof value === 'string' && FACTORY_TRIAGE_TYPES.some(type => type === value);\n}\n\nexport function isFactoryRuleStage(value: unknown): value is FactoryRuleStage {\n  return typeof value === 'string' && FACTORY_RULE_STAGES.some(stage => stage === value);\n}\n\nexport function factoryRuleStage(stages: readonly string[]): FactoryRuleStage | undefined {\n  const stage = stages.length === 1 ? stages[0] : undefined;\n  return typeof stage === 'string' && stage.length > 0 ? stage : undefined;\n}\n\nexport function isTerminalFactoryRuleStage(stages: readonly string[]): boolean {\n  const stage = factoryRuleStage(stages);\n  return stage === 'done' || stage === 'canceled';\n}\n\n/** Working lanes hold cards with a seat engaged; Intake, Done and Canceled rest them. */\nexport function isWorkingFactoryRuleStage(stage: FactoryRuleStage): boolean {\n  return stage !== 'intake' && !isTerminalFactoryRuleStage([stage]);\n}\n\n// Consulted only for the Intake exit: roles don't own lanes, so a card already\n// in a working or terminal lane stays put when a run starts.\nexport function factoryLaneForRole(role: string): FactoryRuleStage | undefined {\n  return isFactoryRole(role) ? FACTORY_ROLE_STAGES[role] : undefined;\n}\n\nexport const FACTORY_RULE_BOARDS = ['work', 'review'] as const;\nexport type FactoryRuleBoard = (typeof FACTORY_RULE_BOARDS)[number] | (string & {});\n\nexport const FACTORY_RULE_SOURCES = [\n  'issue',\n  'pullRequest',\n  'gitlabIssue',\n  'gitlabPullRequest',\n  'linearIssue',\n  'jiraIssue',\n  'incidentioFollowUp',\n  'manual',\n] as const;\nexport type FactoryRuleSource = (typeof FACTORY_RULE_SOURCES)[number];\n\nexport const FACTORY_GITHUB_EVENTS = [\n  'issueOpened',\n  'issueEdited',\n  'issueClosed',\n  'issueCommentCreated',\n  'issueCommentEdited',\n  'issueCommentDeleted',\n  'pullRequestOpened',\n  'pullRequestUpdated',\n  'pullRequestCommentCreated',\n  'pullRequestReviewRequested',\n  'pullRequestReviewSubmitted',\n  'pullRequestMerged',\n  'pullRequestClosed',\n] as const;\nexport type FactoryGithubEventName = (typeof FACTORY_GITHUB_EVENTS)[number];\n\nexport const FACTORY_GITLAB_EVENTS = [\n  'issueOpened',\n  'issueUpdated',\n  'issueClosed',\n  'issueCommented',\n  'mergeRequestOpened',\n  'mergeRequestUpdated',\n  'mergeRequestCommented',\n  'mergeRequestMerged',\n  'mergeRequestClosed',\n] as const;\nexport type FactoryGitLabEventName = (typeof FACTORY_GITLAB_EVENTS)[number];\n\nexport const FACTORY_LINEAR_EVENTS = ['issueObserved', 'issueClosed'] as const;\nexport type FactoryLinearEventName = (typeof FACTORY_LINEAR_EVENTS)[number];\n\nexport const FACTORY_JIRA_EVENTS = ['issueObserved', 'issueClosed'] as const;\nexport type FactoryJiraEventName = (typeof FACTORY_JIRA_EVENTS)[number];\n\nexport const FACTORY_INCIDENTIO_EVENTS = ['followUpObserved', 'followUpClosed'] as const;\nexport type FactoryIncidentioEventName = (typeof FACTORY_INCIDENTIO_EVENTS)[number];\n\nexport type FactoryRuleJsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | FactoryRuleJsonValue[]\n  | { [key: string]: FactoryRuleJsonValue };\n\nexport interface FactoryRuleItemContext {\n  id: string;\n  source: WorkItemSource;\n  sourceKey: string | null;\n  parentWorkItemId: string | null;\n  title: string;\n  url: string | null;\n  stages: readonly string[];\n  acceptedAt: Date | null;\n  /** Intake-stamped facts about the source — repository id, reporter login, labels. */\n  metadata: Record<string, unknown> | null;\n}\n\nexport type FactoryRuleActor =\n  | { type: 'human'; id: string }\n  | { type: 'agent'; bindingId: string; role: string }\n  | { type: 'github'; login: string; trusted: boolean; factoryAuthored: boolean }\n  | { type: 'gitlab'; username: string; trusted: boolean; factoryAuthored: boolean }\n  | { type: 'system'; id: string };\n\nexport interface FactoryRuleIngressIdentity {\n  type: 'human' | 'agent' | 'toolResult' | 'github' | 'gitlab' | 'linear' | 'jira' | 'incidentio' | 'rule';\n  id: string;\n}\n\nexport interface FactoryRuleCausalEntry {\n  ingressId: string;\n  decisionType: FactoryCommitDecision['type'];\n}\n\nexport interface FactoryRuleContextBase {\n  tenant: { orgId: string; projectId: string };\n  actor: FactoryRuleActor;\n  ingress: FactoryRuleIngressIdentity;\n  cause: string;\n  causalChain: readonly FactoryRuleCausalEntry[];\n  configVersion: string;\n}\n\nexport interface FactoryBoundRuleContext extends FactoryRuleContextBase {\n  item: FactoryRuleItemContext;\n  board: FactoryRuleBoard;\n  itemRevision: number;\n}\n\nexport interface FactoryStageRuleContext extends FactoryBoundRuleContext {\n  source: FactoryRuleSource;\n  stage: FactoryRuleStage;\n  fromStage: FactoryRuleStage;\n  toStage: FactoryRuleStage;\n}\n\nexport interface FactoryToolResultRuleContext extends FactoryBoundRuleContext {\n  toolName: string;\n  threadId: string;\n  assistantMessageId: string;\n  toolCallId: string;\n  result: {\n    status: 'success' | 'error';\n    value: FactoryRuleJsonValue;\n  };\n}\n\nexport interface FactoryGithubRuleContext extends FactoryRuleContextBase {\n  item?: FactoryRuleItemContext;\n  board?: FactoryRuleBoard;\n  itemRevision?: number;\n  /**\n   * Board an issue's labels route it to, when the project has a matching label route and that board\n   * is installed. Absent for pull requests and for issues whose labels select nothing.\n   */\n  intake?: FactoryRuleIntakeTarget;\n  /**\n   * Set on the one evaluation per pull request delivery that files the pull\n   * request's own Review card. Opening a pull request concerns two cards — that\n   * Review card and the Work item that authored the pull request — so the rule\n   * answers for the two separately: the arrival carries this flag and is\n   * committed against the authoring item when resolution found one, which is\n   * what links the new card to it, while the authoring item's own evaluation\n   * leaves the flag unset.\n   */\n  pullRequestIntake?: boolean;\n  event: FactoryGithubEventName;\n  deliveryId: string;\n  factory: { createdAt: string };\n  repository: { id: number; fullName: string };\n  issue?: {\n    number: number;\n    title: string;\n    url: string;\n    createdAt?: string;\n    updatedAt?: string;\n    assignees?: string[];\n    labels?: string[];\n    state?: 'open' | 'closed';\n    /** GitHub close reason: `completed`, `not_planned`, or `duplicate`. */\n    stateReason?: string;\n  };\n  issueChange?: { title: boolean; body: boolean };\n  issueComment?: {\n    id: number;\n    body?: string;\n    url?: string;\n    author?: string;\n    authorType?: string;\n    createdAt?: string;\n    updatedAt?: string;\n  };\n  pullRequest?: {\n    number: number;\n    title: string;\n    url: string;\n    createdAt?: string;\n    state: 'open' | 'closed';\n    draft: boolean;\n    merged: boolean;\n    assignees?: string[];\n    requestedReviewers?: string[];\n    labels?: string[];\n    author?: string;\n    factoryAuthored: boolean;\n    headBranch: string;\n    baseBranch: string;\n  };\n  /** Present on `pullRequestReviewRequested`: who review was (re-)requested from. */\n  reviewRequest?: { reviewer: string; factoryReviewer: boolean };\n  /** Present when a PR comment uses Factory's exact review command. */\n  reviewCommand?: { command: 'review' | 're-review'; target: string };\n  /** Present on `pullRequestReviewSubmitted`: the review that was just posted. */\n  review?: { id: number; state: string; url: string };\n}\n\n/**\n * Where an intake source binding says new items from this source should land.\n * Absent when the source is unbound or bound without a board (built-in routing).\n */\nexport interface FactoryRuleIntakeTarget {\n  board: string;\n  initialPhase: string;\n}\n\nexport interface FactoryGitLabRuleContext extends FactoryRuleContextBase {\n  item?: FactoryRuleItemContext;\n  board?: FactoryRuleBoard;\n  itemRevision?: number;\n  intake?: FactoryRuleIntakeTarget;\n  event: FactoryGitLabEventName;\n  deliveryId: string;\n  factory: { createdAt: string };\n  repository: { id: number; fullName: string; host: string };\n  issue?: {\n    number: number;\n    sourceKey: string;\n    title: string;\n    url: string;\n    createdAt?: string;\n    updatedAt?: string;\n    assignees?: string[];\n    labels?: string[];\n    labelColors?: Record<string, string>;\n    state?: 'open' | 'closed';\n    author?: string;\n    authorTrusted: boolean;\n  };\n  note?: {\n    id: number;\n    body?: string;\n    url?: string;\n    author?: string;\n    createdAt?: string;\n    updatedAt?: string;\n  };\n  mergeRequest?: {\n    number: number;\n    sourceKey: string;\n    title: string;\n    url: string;\n    createdAt?: string;\n    state: 'open' | 'closed';\n    draft: boolean;\n    merged: boolean;\n    assignees?: string[];\n    reviewers?: string[];\n    labels?: string[];\n    labelColors?: Record<string, string>;\n    author?: string;\n    authorTrusted: boolean;\n    factoryAuthored: boolean;\n    headBranch: string;\n    baseBranch: string;\n  };\n}\n\nexport interface FactoryLinearRuleContext extends FactoryRuleContextBase {\n  item?: FactoryRuleItemContext;\n  board?: FactoryRuleBoard;\n  itemRevision?: number;\n  /** Bound board for the source this issue came from, when one is configured and installed. */\n  intake?: FactoryRuleIntakeTarget;\n  event: FactoryLinearEventName;\n  issue: {\n    id: string;\n    identifier: string;\n    title: string;\n    url: string;\n    state: string;\n    stateType: string;\n    priorityLabel: string;\n    assignee: string | null;\n    creator: string | null;\n    team: string | null;\n    labels: readonly string[];\n    createdAt: string;\n    updatedAt: string;\n    sourceId?: string | null;\n    projectId?: string | null;\n  };\n}\n\nexport interface FactoryJiraRuleContext extends FactoryRuleContextBase {\n  item?: FactoryRuleItemContext;\n  board?: FactoryRuleBoard;\n  itemRevision?: number;\n  /** Bound board for the source this issue came from, when one is configured and installed. */\n  intake?: FactoryRuleIntakeTarget;\n  event: FactoryJiraEventName;\n  issue: {\n    /** Stable issue reference — the direct integration's Jira id or the Platform-encoded issue reference. */\n    id: string;\n    identifier: string;\n    title: string;\n    url: string;\n    state: string;\n    stateType: string;\n    priorityLabel: string;\n    assignee: string | null;\n    author: string | null;\n    project: string | null;\n    site: string | null;\n    labels: readonly string[];\n    createdAt: string;\n    updatedAt: string;\n  };\n}\n\nexport interface FactoryIncidentioRuleContext extends FactoryRuleContextBase {\n  item?: FactoryRuleItemContext;\n  board?: FactoryRuleBoard;\n  itemRevision?: number;\n  /** Bound board for the source this follow-up came from, when one is configured and installed. */\n  intake?: FactoryRuleIntakeTarget;\n  event: FactoryIncidentioEventName;\n  issue: {\n    /** Stable item reference — the prefixed incident.io follow-up id the intake feed serves as `id`. */\n    id: string;\n    identifier: string;\n    title: string;\n    url: string;\n    state: string;\n    stateType: string;\n    priorityLabel: string;\n    assignee: string | null;\n    author: string | null;\n    /** Reference of the incident this follow-up belongs to, when available. */\n    incident: string | null;\n    labels: readonly string[];\n    createdAt: string;\n    updatedAt: string;\n  };\n}\n\nexport type FactoryRuleHandler<TContext> = (\n  context: Readonly<TContext>,\n) => FactoryRuleDecision | void | Promise<FactoryRuleDecision | void>;\n\nexport interface FactoryBoardRuleLeaf {\n  onEnter?: FactoryRuleHandler<FactoryStageRuleContext>;\n  onExit?: FactoryRuleHandler<FactoryStageRuleContext>;\n}\n\nexport type FactoryRuleRejectionCode =\n  | 'forbidden'\n  | 'invalid_transition'\n  | 'missing_binding'\n  | 'stale'\n  | 'timeout'\n  | 'rule_error'\n  | 'causal_depth_exceeded'\n  | 'repeated_transition'\n  | 'approval_required';\n\nexport interface FactoryRuleRejectDecision {\n  type: 'reject';\n  code: FactoryRuleRejectionCode;\n  reason: string;\n}\n\ninterface FactoryCommitDecisionBase {\n  idempotencyKey: string;\n}\n\nexport interface FactoryTransitionDecision extends FactoryCommitDecisionBase {\n  type: 'transition';\n  board: FactoryRuleBoard;\n  stage: FactoryRuleStage;\n  /**\n   * Delivered to the item's active session (waking it if idle) after the\n   * transition commits. Skipped when the item has no active run binding, so\n   * informational messages never fail the transition.\n   */\n  message?: { text: string; role?: string };\n  /**\n   * Runs the stage's entry rules even when the item is already in that stage.\n   * A transition to the current stage is normally inert, because most callers\n   * are correcting a board into a state it already holds. Re-entry is for the\n   * opposite case: the stage's work is in flight and has been invalidated, so\n   * it has to start over.\n   */\n  reenter?: boolean;\n}\n\nexport interface FactoryUpsertLinkedWorkItemDecision extends FactoryCommitDecisionBase {\n  type: 'upsertLinkedWorkItem';\n  board: FactoryRuleBoard;\n  source: WorkItemSource;\n  sourceKey: string;\n  /**\n   * Org-wide ownership key for the external record, when one Factory at a time\n   * may hold a live card for it (a stable Linear issue id, for instance). The\n   * store enforces it with a unique index, so a second project's materialization\n   * is refused rather than duplicated.\n   */\n  claimKey?: string;\n  title: string;\n  url: string | null;\n  stage: FactoryRuleStage;\n  /**\n   * File the card at `stage` as its first entry and run none of the board's\n   * phase rules for it — no arrival, no destination entry. The card is filed\n   * (or, if it already exists, moved) and left parked for a person; nothing is\n   * started for it. For external records that arrive already past the board's\n   * first step: a GitHub issue whose triage is already recorded, for instance.\n   *\n   * Placement is the whole decision. An existing card it reaches is moved to\n   * that stage through the same relocation the label routes use, and its\n   * metadata is left alone.\n   */\n  skipRules?: boolean;\n  metadata?: Record<string, FactoryRuleJsonValue>;\n}\n\ninterface FactoryInvokeSkillDecisionBase extends FactoryCommitDecisionBase {\n  type: 'invokeSkill';\n  role: string;\n  arguments?: string;\n  precedingMessage?: string;\n  cancelInFlight?: boolean;\n}\n\n/**\n * Starting an agent run. Most runs activate a skill, because the skill carries\n * the handoff contract later rules match on. A run whose completion is already\n * signalled some other way — Building finishes by opening a pull request, which\n * arrives as its own event — needs no contract, so it can carry a plain prompt\n * instead of an otherwise empty skill.\n */\nexport type FactoryInvokeSkillDecision = FactoryInvokeSkillDecisionBase &\n  (\n    | {\n        skillName: string;\n        prompt?: never;\n        /**\n         * Same-stage re-entry: the skill is already active in the card's live session,\n         * so deliver a compact continuation that references it by name and carries only\n         * the fresh arguments, instead of re-pasting the whole skill document. Only valid\n         * for named-skill decisions — a plain prompt run has no active skill to resume.\n         */\n        resume?: boolean;\n      }\n    | { prompt: string; skillName?: never; resume?: never }\n  );\n\nexport interface FactorySendMessageDecision extends FactoryCommitDecisionBase {\n  type: 'sendMessage';\n  /** Omitted: the card's live session, whichever seat holds it. Required with `prepareBinding`. */\n  role?: string;\n  message: string;\n  priority?: 'medium' | 'high' | 'urgent';\n  idleBehavior?: 'persist' | 'wake';\n  prepareBinding?: boolean;\n}\n\nexport interface FactoryNotifyDecision extends FactoryCommitDecisionBase {\n  type: 'notify';\n  title: string;\n  body?: string;\n  level?: 'info' | 'warning' | 'error';\n}\n\nexport type FactoryCommitDecision =\n  | FactoryTransitionDecision\n  | FactoryUpsertLinkedWorkItemDecision\n  | FactoryInvokeSkillDecision\n  | FactorySendMessageDecision\n  | FactoryNotifyDecision;\n\nexport type FactoryRuleDecision = FactoryRuleRejectDecision | FactoryCommitDecision;\n\nexport interface FactoryTransitionResultAccepted {\n  status: 'accepted';\n  transitionId: string;\n  itemId: string;\n  revision: number;\n  stage: FactoryRuleStage;\n  decisions: FactoryCommitDecision[];\n}\n\nexport interface FactoryTransitionResultRejected {\n  status: 'rejected';\n  transitionId: string;\n  itemId: string;\n  code: FactoryRuleRejectionCode;\n  reason: string;\n}\n\nexport type FactoryTransitionResult = FactoryTransitionResultAccepted | FactoryTransitionResultRejected;\n\nexport function factoryRuleSourceForWorkItem(source: WorkItemSource): FactoryRuleSource {\n  switch (source) {\n    case 'github-issue':\n      return 'issue';\n    case 'github-pr':\n      return 'pullRequest';\n    case 'gitlab-issue':\n      return 'gitlabIssue';\n    case 'gitlab-pr':\n      return 'gitlabPullRequest';\n    case 'linear-issue':\n      return 'linearIssue';\n    case 'jira-issue':\n      return 'jiraIssue';\n    case 'incidentio-follow-up':\n      return 'incidentioFollowUp';\n    case 'manual':\n      return 'manual';\n  }\n}\n"],"mappings":"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"}

package/dist/sandbox/materialization.d.ts

@@ -13,8 +13,12 @@ export interface SandboxCommandResult {
  * so this type promotes it to required. `id` is taken from core; the command
  * signature is spelled out because core's `CommandResult` is wider than what
  * these helpers read (see below).
+ *
+ * `sandboxId` is the provider's physical, reattachable VM id (undefined until
+ * started, or for providers with no separate physical id); it is carried here
+ * so callers can persist it for deterministic reattach on resume.
  */
-export type ExecutableSandbox = Pick<WorkspaceSandbox, 'id'> & {
+export type ExecutableSandbox = Pick<WorkspaceSandbox, 'id' | 'sandboxId'> & {
     /**
      * Runs a command. The options are core's, but the result is only the part
      * these helpers read: core's `CommandResult` also carries `success` and

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

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

package/dist/sandbox/materialization.js.map

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

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

@@ -8,6 +8,15 @@ import type { RepositoryAccess } from '../capabilities/version-control.js';
 export interface FactorySandboxContext {
     /** Stable session id — the sandbox identity. */
     sessionId: string;
+    /**
+     * The provider's physical sandbox id persisted from a prior start, when the
+     * session has been started before. Providers that reattach by physical id
+     * (e.g. Railway) MUST forward it to the sandbox constructor so resume
+     * reattaches the original VM instead of provisioning a replacement. E2B and
+     * Platform accept it as a deterministic-reattach optimization. Undefined on
+     * a session's first ever start.
+     */
+    sandboxId?: string;
     /** owner/name of the repository, when the session is repo-backed. */
     repoFullName?: string;
     /**
@@ -38,6 +47,9 @@ export interface FactorySandboxContext {
  * `workingDirectory` at a per-session directory (e.g.
  * `join(root, ctx.sessionId)`); the repo checks out as a subdirectory of it.
  *
+ * Forward `ctx.sandboxId` to providers that reattach by physical id so resume
+ * reattaches the original VM instead of provisioning a replacement.
+ *
  * Returns a `MastraSandbox`, not the bare `WorkspaceSandbox` interface:
  * factory relies on the base class for the start lifecycle and the runtime
  * env, so providers extend it rather than reimplementing the contract.
@@ -48,7 +60,7 @@ export interface FactorySandboxContext {
  *
  * @example
  * ```typescript
- * sandbox: ({ sessionId }) => new E2BSandbox({ id: sessionId })
+ * sandbox: ({ sessionId, sandboxId }) => new E2BSandbox({ id: sessionId, sandboxId })
  * ```
  */
 export type MastraFactorySandboxConfig = (ctx: FactorySandboxContext) => MastraSandbox;

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

@@ -1 +1 @@
-{"version":3,"file":"session-sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/session-sandbox.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAChG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAI3E;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,mBAAmB,EAAE,CAAC,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC,GAAG,SAAS,CAAC;CACpE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,GAAG,EAAE,qBAAqB,KAAK,aAAa,CAAC;AAEvF;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpH;;;;;;;;;GASG;AACH,UAAU,mBAAmB;IAC3B,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,gBAAgB,GAChC,mBAAmB,CAQrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,gBAAgB,EACzB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CASjB;AAmBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAErF;AAED,uFAAuF;AACvF,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAG3D;AAED,4DAA4D;AAC5D,wBAAgB,+BAA+B,IAAI,IAAI,CAGtD;AAcD,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEjF;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEjF;AAqCD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,gBAAgB,CAyBlB"}
+{"version":3,"file":"session-sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/session-sandbox.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAChG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAI3E;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,mBAAmB,EAAE,CAAC,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC,GAAG,SAAS,CAAC;CACpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,GAAG,EAAE,qBAAqB,KAAK,aAAa,CAAC;AAEvF;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpH;;;;;;;;;GASG;AACH,UAAU,mBAAmB;IAC3B,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,gBAAgB,GAChC,mBAAmB,CAQrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,gBAAgB,EACzB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CASjB;AAmBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAErF;AAED,uFAAuF;AACvF,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAG3D;AAED,4DAA4D;AAC5D,wBAAgB,+BAA+B,IAAI,IAAI,CAGtD;AAcD,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEjF;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEjF;AAqCD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,gBAAgB,CAyBlB"}

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  /** 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 * 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 }) => new E2BSandbox({ id: sessionId })\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 { 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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"}

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

@@ -53,8 +53,8 @@ export interface EnsureFactorySourceSessionArgs {
     orgId: string;
     factoryProjectId: string;
     branch: string;
-    /** Pick a specific linked repository by slug. Defaults to the first linked repository. */
-    repositorySlug?: string;
+    /** Pick the linked repository that the work item targets. */
+    repositorySlug: 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.
@@ -102,8 +102,12 @@ export declare function resolveFactorySourceRepository(args: {
     sourceControl: SourceControlStorageHandle;
     orgId: string;
     factoryProjectId: string;
-    /** Pick a specific linked repository by slug. Defaults to the first linked repository. */
-    repositorySlug?: string;
+    repositorySlug: string;
+} | {
+    sourceControl: SourceControlStorageHandle;
+    orgId: string;
+    factoryProjectId: string;
+    firstLinkedRepository: true;
 }): Promise<FactorySourceRepositoryResult>;
 /**
  * Walk a Factory user-session id back to the project it belongs to.
@@ -148,6 +152,12 @@ export interface HydrateFactorySessionArgs {
     factoryProjectId?: string;
     /** The factory project's default model. Without it the session keeps the SDK's built-in mode default. */
     defaultModelId?: string;
+    /**
+     * Model whose provider supplies the observational-memory fallback. Defaults
+     * to the factory model, but channel sessions can use the sender's model so OM
+     * resolves against that sender's credentials.
+     */
+    observationalMemoryModelId?: string;
     /**
      * When provided, the factory project's stored memory-settings row is
      * applied. When omitted (or no row exists) the session is reset to the

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

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

package/dist/session/factory-session.js

@@ -92,7 +92,9 @@ var FactorySourceSessionResolutionError = class extends Error {
 * handle's own `integrationId` — nothing here is provider-specific.
 */
 async function resolveFactorySourceRepository(args) {
-	const { sourceControl, orgId, factoryProjectId, repositorySlug } = args;
+	const { sourceControl, orgId, factoryProjectId } = args;
+	const repositorySlug = "repositorySlug" in args ? args.repositorySlug : void 0;
+	const firstLinkedRepository = "firstLinkedRepository" in args;
 	const candidates = (await sourceControl.connections.list({
 		orgId,
 		factoryProjectId
@@ -114,7 +116,7 @@ async function resolveFactorySourceRepository(args) {
 					orgId,
 					id: projectRepository.repositoryId
 				})
-			})))).find((candidate) => candidate.repository && (!repositorySlug || candidate.repository.slug === repositorySlug));
+			})))).find((candidate) => candidate.repository && (firstLinkedRepository || candidate.repository.slug === repositorySlug));
 		} catch (error) {
 			if (!(error instanceof SourceControlConnectionNotFoundError)) throw error;
 			continue;
@@ -218,18 +220,37 @@ async function hydrateFactorySession(session, args) {
 			orgId: args.orgId,
 			userId: factoryMemorySettingsUserId(args.factoryProjectId)
 		}) : null;
-		const provider = args.defaultModelId?.split("/")[0];
-		await applyStoredMemorySettings(session, record, provider ? resolveProviderOMDefault(provider, args.defaultModelId).modelId : void 0);
+		const observationalMemoryModelId = args.observationalMemoryModelId ?? args.defaultModelId;
+		const provider = observationalMemoryModelId?.split("/")[0];
+		await applyStoredMemorySettings(session, record, provider ? resolveProviderOMDefault(provider, observationalMemoryModelId).modelId : void 0);
 	} catch (error) {
 		console.warn("[Factory Start] Failed to apply observational-memory settings", { error: error instanceof Error ? error.message : String(error) });
 	}
-	if (args.defaultModelId) try {
-		await session.model.switch({ modelId: args.defaultModelId });
-	} catch (error) {
-		console.warn("[Factory Start] Failed to apply factory default model", {
-			modelId: args.defaultModelId,
-			error: error instanceof Error ? error.message : String(error)
-		});
+	if (args.defaultModelId) {
+		try {
+			await session.model.switch({ modelId: args.defaultModelId });
+		} catch (error) {
+			console.warn("[Factory Start] Failed to apply factory default model", {
+				modelId: args.defaultModelId,
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+		for (const agentType of [
+			"explore",
+			"plan",
+			"execute"
+		]) try {
+			await session.subagents.model.set({
+				modelId: args.defaultModelId,
+				agentType
+			});
+		} catch (error) {
+			console.warn("[Factory Start] Failed to apply factory default subagent model", {
+				agentType,
+				modelId: args.defaultModelId,
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
 	}
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"factory-session.js","names":[],"sources":["../../src/session/factory-session.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\n\nimport { resolveProviderOMDefault } from '@mastra/code-sdk/onboarding/packs';\nimport type { MastraCodeState } from '@mastra/code-sdk/schema';\nimport type { AgentController } from '@mastra/core/agent-controller';\n\nimport { factoryMemorySettingsUserId } from '../storage/domains/memory-settings/base.js';\nimport type { MemorySettingsStorage } from '../storage/domains/memory-settings/base.js';\nimport type { FactoryProjectsStorage } from '../storage/domains/projects/base.js';\nimport {\n  SourceControlConnectionNotFoundError,\n  type SourceControlSession,\n  type SourceControlStorageHandle,\n} from '../storage/domains/source-control/base.js';\nimport { applyStoredMemorySettings, type OMConfigurableSession } from './memory-settings-hydration.js';\nimport { seedSessionOrg } from './org-seed.js';\n\ntype FactorySession = Awaited<ReturnType<AgentController<MastraCodeState>['createSession']>>;\n\nexport class FactorySourceControlConflictError extends Error {}\n\n/**\n * Read the factory project's default model. Best-effort: a missing project or an\n * uninitialized storage domain means \"no default\", never a failed run.\n */\nexport async function resolveFactoryDefaultModelId(\n  projects: FactoryProjectsStorage | undefined,\n  factoryProjectId: string | undefined,\n): Promise<string | undefined> {\n  if (!projects || !factoryProjectId) return undefined;\n  try {\n    const project = await projects.getById({ id: factoryProjectId });\n    return project?.defaultModelId ?? undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nexport interface SourceControlSessionLookup {\n  getBySessionId(sessionId: string): Promise<SourceControlSession | null>;\n  getSourceControlBySessionId(sessionId: string): Promise<SourceControlStorageHandle | null>;\n  rename(args: { sessionId: string; title: string }): Promise<void>;\n  markFirstMessage(args: { sessionId: string }): Promise<void>;\n  markFirstMeaningfulExec(args: { sessionId: string }): Promise<void>;\n}\n\n/**\n * Read or update a session across every registered source-control partition.\n * Session ids are globally generated, so more than one match is invalid and\n * fails closed instead of mutating an arbitrary provider.\n */\nexport function createSourceControlSessionLookup(\n  sourceControls: readonly SourceControlStorageHandle[],\n): SourceControlSessionLookup {\n  const resolve = async (\n    sessionId: string,\n  ): Promise<{ sourceControl: SourceControlStorageHandle; session: SourceControlSession } | null> => {\n    const matches = (\n      await Promise.all(\n        sourceControls.map(async sourceControl => ({\n          sourceControl,\n          session: await sourceControl.sessions.getBySessionId(sessionId),\n        })),\n      )\n    ).filter(\n      (match): match is { sourceControl: SourceControlStorageHandle; session: SourceControlSession } =>\n        match.session !== null,\n    );\n    if (matches.length > 1) throw new Error('Factory session exists in multiple source-control providers.');\n    return matches[0] ?? null;\n  };\n\n  return {\n    getBySessionId: async sessionId => (await resolve(sessionId))?.session ?? null,\n    getSourceControlBySessionId: async sessionId => (await resolve(sessionId))?.sourceControl ?? null,\n    rename: async args => (await resolve(args.sessionId))?.sourceControl.sessions.rename(args),\n    markFirstMessage: async args => (await resolve(args.sessionId))?.sourceControl.sessions.markFirstMessage(args),\n    markFirstMeaningfulExec: async args =>\n      (await resolve(args.sessionId))?.sourceControl.sessions.markFirstMeaningfulExec(args),\n  };\n}\n\n/**\n * Resolve the source-control provider from durable Factory repository links,\n * never from the issue tracker that happened to create the work item.\n */\nexport async function resolveFactorySourceControl(args: {\n  sourceControls: readonly SourceControlStorageHandle[];\n  orgId: string;\n  factoryProjectId: string;\n  sessionId?: string;\n}): Promise<SourceControlStorageHandle | undefined> {\n  if (args.sessionId) {\n    const sessionMatches = (\n      await Promise.all(\n        args.sourceControls.map(async sourceControl => ({\n          sourceControl,\n          session: await sourceControl.sessions.getBySessionId(args.sessionId!),\n        })),\n      )\n    ).filter(match => match.session !== null);\n    if (sessionMatches.length > 1) throw new Error('Factory session exists in multiple source-control providers.');\n    if (sessionMatches[0]) return sessionMatches[0].sourceControl;\n  }\n\n  const linked = [];\n  for (const sourceControl of args.sourceControls) {\n    const connections = await sourceControl.connections.list({\n      orgId: args.orgId,\n      factoryProjectId: args.factoryProjectId,\n    });\n    let hasLinkedRepository = false;\n    for (const connection of connections) {\n      try {\n        if (\n          (await sourceControl.projectRepositories.list({ orgId: args.orgId, connectionId: connection.id })).length > 0\n        ) {\n          hasLinkedRepository = true;\n          break;\n        }\n      } catch (error) {\n        if (!(error instanceof SourceControlConnectionNotFoundError)) throw error;\n      }\n    }\n    if (hasLinkedRepository) linked.push(sourceControl);\n  }\n  if (linked.length > 1)\n    throw new FactorySourceControlConflictError(\n      'Factory project has repositories linked through multiple source-control providers.',\n    );\n  return linked[0];\n}\n\nexport interface EnsureFactorySourceSessionArgs {\n  /**\n   * Storage handle of the integration that owns source control. Nothing here is\n   * provider-specific: the connection is matched by the handle's own\n   * `integrationId`, so GitHub, Slack-on-behalf-of-GitHub, or any future owner\n   * all resolve through the same traversal.\n   */\n  sourceControl: SourceControlStorageHandle;\n  orgId: string;\n  factoryProjectId: string;\n  branch: string;\n  /** Pick a specific linked repository by slug. Defaults to the first linked repository. */\n  repositorySlug?: string;\n  /**\n   * Attribute the run to this user instead of the repo connector. Set when the\n   * run has an interactive user — e.g. the person who approved a proposed run.\n   */\n  attributeToUserId?: string;\n}\n\nexport interface EnsuredFactorySourceSession {\n  sessionId: string;\n  userId: string;\n  projectRepositoryId: string;\n  branch: string;\n  baseBranch: string;\n}\n\nexport class FactorySourceSessionResolutionError extends Error {\n  constructor(readonly reason: 'connection' | 'repository') {\n    super(\n      reason === 'connection'\n        ? 'Factory source-control connection not found.'\n        : 'Factory source-control repository not found.',\n    );\n    this.name = 'FactorySourceSessionResolutionError';\n  }\n}\n\nexport interface ResolvedFactorySourceRepository {\n  projectRepositoryId: string;\n  /** The repository's pinned branch, else its default branch. */\n  baseBranch: string;\n  /** Who connected the repository. The attribution for runs with no interactive user. */\n  connectedByUserId: string;\n}\n\n/**\n * Outcome of {@link resolveFactorySourceRepository}. A miss carries which step\n * failed: callers differ on whether that is an error (an autonomous run cannot\n * proceed) or a routine fallback (a chat integration drops to a chat-only\n * session), and the two steps fail for different reasons worth reporting apart.\n */\nexport type FactorySourceRepositoryResult =\n  | ({ found: true } & ResolvedFactorySourceRepository)\n  | { found: false; reason: 'connection' | 'repository' };\n\n/**\n * Resolve which repository a factory project's source-control runs act on: the\n * owner's connection on the project, then one of its linked repositories.\n *\n * The owner is whichever integration owns source control, matched by the\n * handle's own `integrationId` — nothing here is provider-specific.\n */\nexport async function resolveFactorySourceRepository(args: {\n  sourceControl: SourceControlStorageHandle;\n  orgId: string;\n  factoryProjectId: string;\n  /** Pick a specific linked repository by slug. Defaults to the first linked repository. */\n  repositorySlug?: string;\n}): Promise<FactorySourceRepositoryResult> {\n  const { sourceControl, orgId, factoryProjectId, repositorySlug } = args;\n\n  const connections = await sourceControl.connections.list({ orgId, factoryProjectId });\n  const candidates = connections.filter(candidate => candidate.integrationId === sourceControl.integrationId);\n  if (candidates.length === 0) return { found: false, reason: 'connection' };\n\n  // A project can carry stale connections: a provider-app reinstall leaves the\n  // old connection pointing at an installation that no longer exists, and that\n  // row can sit ahead of the healthy one. Try every candidate and skip the ones\n  // that no longer resolve rather than failing on the first.\n  for (const connection of candidates) {\n    let resolved;\n    try {\n      const projectRepositories = await sourceControl.projectRepositories.list({ orgId, connectionId: connection.id });\n      const resolvedRepositories = await Promise.all(\n        projectRepositories.map(async projectRepository => ({\n          projectRepository,\n          repository: await sourceControl.repositories.get({ orgId, id: projectRepository.repositoryId }),\n        })),\n      );\n      resolved = resolvedRepositories.find(\n        candidate => candidate.repository && (!repositorySlug || candidate.repository.slug === repositorySlug),\n      );\n    } catch (error) {\n      // A deleted installation invalidates a stale connection; storage failures must propagate.\n      if (!(error instanceof SourceControlConnectionNotFoundError)) throw error;\n      continue;\n    }\n    if (!resolved?.repository) continue;\n\n    return {\n      found: true,\n      projectRepositoryId: resolved.projectRepository.id,\n      baseBranch: resolved.projectRepository.branch ?? resolved.repository.defaultBranch,\n      connectedByUserId: connection.createdByUserId,\n    };\n  }\n\n  return { found: false, reason: 'repository' };\n}\n\n/**\n * Walk a Factory user-session id back to the project it belongs to.\n *\n * Repo-backed channel threads are keyed by their Factory session id, which is\n * the only handle a session-start hook gets. This turns that id back into the\n * project whose configuration the session should adopt. Durable by\n * construction — it reads the same rows the session was created from, so it\n * survives restarts without any in-memory mapping.\n */\nexport async function resolveFactoryProjectForSession(args: {\n  sourceControl: SourceControlStorageHandle;\n  sessionId: string;\n}): Promise<{ factoryProjectId: string; orgId: string; userId: string } | null> {\n  const { sourceControl, sessionId } = args;\n\n  const session = await sourceControl.sessions.getBySessionId(sessionId);\n  if (!session) return null;\n  const projectRepository = await sourceControl.projectRepositories.get({\n    orgId: session.orgId,\n    id: session.projectRepositoryId,\n  });\n  if (!projectRepository) return null;\n  const connection = await sourceControl.connections.get({ orgId: session.orgId, id: projectRepository.connectionId });\n  if (!connection) return null;\n\n  return { factoryProjectId: connection.factoryProjectId, orgId: session.orgId, userId: session.userId };\n}\n\n/**\n * Create the source-control session a repo-backed factory run needs.\n *\n * `FactoryStartCoordinator.prepare` requires this record to already exist —\n * `resolveSourceSession` throws `Factory session not found` otherwise — so every\n * autonomous entry point has to produce one before it can start a run. This is\n * that step, in one place: the owner's connection on the factory project, one of\n * its linked repositories, and a session on the requested branch with the\n * repository's pinned or default branch as the base.\n *\n * The run is attributed to `attributeToUserId` when the caller has an\n * interactive user (e.g. the approver of a proposed run), and otherwise falls\n * back to whoever connected the repository (`connection.createdByUserId`),\n * because a genuinely autonomous run has no interactive user of its own.\n */\nexport async function ensureFactorySourceSession(\n  args: EnsureFactorySourceSessionArgs,\n): Promise<EnsuredFactorySourceSession> {\n  const { sourceControl, orgId, factoryProjectId, branch, repositorySlug } = args;\n\n  const resolved = await resolveFactorySourceRepository({ sourceControl, orgId, factoryProjectId, repositorySlug });\n  if (!resolved.found) throw new FactorySourceSessionResolutionError(resolved.reason);\n\n  const userId = args.attributeToUserId ?? resolved.connectedByUserId;\n  const session = await sourceControl.sessions.create({\n    sessionId: randomUUID(),\n    projectRepositoryId: resolved.projectRepositoryId,\n    orgId,\n    userId,\n    branch,\n    baseBranch: resolved.baseBranch,\n    visibility: 'org',\n  });\n  return {\n    sessionId: session.sessionId,\n    userId,\n    projectRepositoryId: resolved.projectRepositoryId,\n    branch: session.branch,\n    baseBranch: resolved.baseBranch,\n  };\n}\n\nexport interface HydrateFactorySessionArgs {\n  orgId: string;\n  /**\n   * The factory project whose shared memory settings apply. Factory sessions\n   * never read an individual user's personal memory settings — the project's\n   * own row (or the built-in defaults) is what they run with.\n   */\n  factoryProjectId?: string;\n  /** The factory project's default model. Without it the session keeps the SDK's built-in mode default. */\n  defaultModelId?: string;\n  /**\n   * When provided, the factory project's stored memory-settings row is\n   * applied. When omitted (or no row exists) the session is reset to the\n   * built-in memory defaults.\n   */\n  memorySettings?: MemorySettingsStorage;\n}\n\n/**\n * Apply a factory project's configuration to a freshly created session:\n * observational-memory settings, then the project's default model.\n *\n * Both steps are best-effort. A retired model id or an unreachable settings row\n * must not sink a run that is otherwise ready — the session simply keeps the\n * default it was created with, and the reason is logged.\n */\nexport async function hydrateFactorySession(session: FactorySession, args: HydrateFactorySessionArgs): Promise<void> {\n  // The org rung knowledge curation scopes on. Seeded first so it lands even if\n  // a later best-effort step fails; an empty org marks the session unresolved.\n  await seedSessionOrg(session, args.orgId);\n  try {\n    const record =\n      args.memorySettings && args.factoryProjectId\n        ? await args.memorySettings.get({\n            orgId: args.orgId,\n            userId: factoryMemorySettingsUserId(args.factoryProjectId),\n          })\n        : null;\n    // Without a stored row, fall back to the low-cost OM model of the factory\n    // default model's provider — a factory connected only to Anthropic should\n    // not observe with the (uncredentialed) built-in Google default.\n    const provider = args.defaultModelId?.split('/')[0];\n    const fallbackOmModelId = provider ? resolveProviderOMDefault(provider, args.defaultModelId).modelId : undefined;\n    await applyStoredMemorySettings(session, record, fallbackOmModelId);\n  } catch (error) {\n    console.warn('[Factory Start] Failed to apply observational-memory settings', {\n      error: error instanceof Error ? error.message : String(error),\n    });\n  }\n  if (args.defaultModelId) {\n    try {\n      await session.model.switch({ modelId: args.defaultModelId });\n    } catch (error) {\n      console.warn('[Factory Start] Failed to apply factory default model', {\n        modelId: args.defaultModelId,\n        error: error instanceof Error ? error.message : String(error),\n      });\n    }\n  }\n}\n\nexport interface RefreshFactorySessionMemorySettingsArgs {\n  orgId: string;\n  factoryProjectId: string;\n  projects: Pick<FactoryProjectsStorage, 'get'>;\n  memorySettings: Pick<MemorySettingsStorage, 'get'>;\n}\n\n/**\n * Re-apply a factory project's stored observational-memory settings to an\n * already-running session that automation is about to reuse. Session creation\n * hydrates these settings once (`hydrateFactorySession`), but a reused binding\n * keeps whatever observer/reflector models it was created with — so a project\n * whose OM models changed since would keep observing with the stale (and\n * possibly since-rejected) models. This reads the project's current row with the\n * same provider-aware fallback as initial hydration and applies it, mirroring\n * the `GET /web/config/om` refresh. Best-effort: a settings lookup failure must\n * never sink an otherwise-ready run, so it is logged and swallowed.\n */\nexport async function refreshFactorySessionMemorySettings(\n  session: OMConfigurableSession,\n  args: RefreshFactorySessionMemorySettingsArgs,\n): Promise<void> {\n  try {\n    const record = await args.memorySettings.get({\n      orgId: args.orgId,\n      userId: factoryMemorySettingsUserId(args.factoryProjectId),\n    });\n    const project = await args.projects.get({ orgId: args.orgId, id: args.factoryProjectId });\n    const provider = project?.defaultModelId?.split('/')[0];\n    const fallbackOmModelId = provider\n      ? resolveProviderOMDefault(provider, project?.defaultModelId ?? undefined).modelId\n      : undefined;\n    await applyStoredMemorySettings(session, record, fallbackOmModelId);\n  } catch (error) {\n    console.warn('[Factory dispatch] Failed to reapply observational-memory settings on session reuse', {\n      error: error instanceof Error ? error.message : String(error),\n    });\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"factory-session.js","names":[],"sources":["../../src/session/factory-session.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\n\nimport { resolveProviderOMDefault } from '@mastra/code-sdk/onboarding/packs';\nimport type { MastraCodeState } from '@mastra/code-sdk/schema';\nimport type { AgentController } from '@mastra/core/agent-controller';\n\nimport { factoryMemorySettingsUserId } from '../storage/domains/memory-settings/base.js';\nimport type { MemorySettingsStorage } from '../storage/domains/memory-settings/base.js';\nimport type { FactoryProjectsStorage } from '../storage/domains/projects/base.js';\nimport {\n  SourceControlConnectionNotFoundError,\n  type SourceControlSession,\n  type SourceControlStorageHandle,\n} from '../storage/domains/source-control/base.js';\nimport { applyStoredMemorySettings, type OMConfigurableSession } from './memory-settings-hydration.js';\nimport { seedSessionOrg } from './org-seed.js';\n\ntype FactorySession = Awaited<ReturnType<AgentController<MastraCodeState>['createSession']>>;\n\nexport class FactorySourceControlConflictError extends Error {}\n\n/**\n * Read the factory project's default model. Best-effort: a missing project or an\n * uninitialized storage domain means \"no default\", never a failed run.\n */\nexport async function resolveFactoryDefaultModelId(\n  projects: FactoryProjectsStorage | undefined,\n  factoryProjectId: string | undefined,\n): Promise<string | undefined> {\n  if (!projects || !factoryProjectId) return undefined;\n  try {\n    const project = await projects.getById({ id: factoryProjectId });\n    return project?.defaultModelId ?? undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nexport interface SourceControlSessionLookup {\n  getBySessionId(sessionId: string): Promise<SourceControlSession | null>;\n  getSourceControlBySessionId(sessionId: string): Promise<SourceControlStorageHandle | null>;\n  rename(args: { sessionId: string; title: string }): Promise<void>;\n  markFirstMessage(args: { sessionId: string }): Promise<void>;\n  markFirstMeaningfulExec(args: { sessionId: string }): Promise<void>;\n}\n\n/**\n * Read or update a session across every registered source-control partition.\n * Session ids are globally generated, so more than one match is invalid and\n * fails closed instead of mutating an arbitrary provider.\n */\nexport function createSourceControlSessionLookup(\n  sourceControls: readonly SourceControlStorageHandle[],\n): SourceControlSessionLookup {\n  const resolve = async (\n    sessionId: string,\n  ): Promise<{ sourceControl: SourceControlStorageHandle; session: SourceControlSession } | null> => {\n    const matches = (\n      await Promise.all(\n        sourceControls.map(async sourceControl => ({\n          sourceControl,\n          session: await sourceControl.sessions.getBySessionId(sessionId),\n        })),\n      )\n    ).filter(\n      (match): match is { sourceControl: SourceControlStorageHandle; session: SourceControlSession } =>\n        match.session !== null,\n    );\n    if (matches.length > 1) throw new Error('Factory session exists in multiple source-control providers.');\n    return matches[0] ?? null;\n  };\n\n  return {\n    getBySessionId: async sessionId => (await resolve(sessionId))?.session ?? null,\n    getSourceControlBySessionId: async sessionId => (await resolve(sessionId))?.sourceControl ?? null,\n    rename: async args => (await resolve(args.sessionId))?.sourceControl.sessions.rename(args),\n    markFirstMessage: async args => (await resolve(args.sessionId))?.sourceControl.sessions.markFirstMessage(args),\n    markFirstMeaningfulExec: async args =>\n      (await resolve(args.sessionId))?.sourceControl.sessions.markFirstMeaningfulExec(args),\n  };\n}\n\n/**\n * Resolve the source-control provider from durable Factory repository links,\n * never from the issue tracker that happened to create the work item.\n */\nexport async function resolveFactorySourceControl(args: {\n  sourceControls: readonly SourceControlStorageHandle[];\n  orgId: string;\n  factoryProjectId: string;\n  sessionId?: string;\n}): Promise<SourceControlStorageHandle | undefined> {\n  if (args.sessionId) {\n    const sessionMatches = (\n      await Promise.all(\n        args.sourceControls.map(async sourceControl => ({\n          sourceControl,\n          session: await sourceControl.sessions.getBySessionId(args.sessionId!),\n        })),\n      )\n    ).filter(match => match.session !== null);\n    if (sessionMatches.length > 1) throw new Error('Factory session exists in multiple source-control providers.');\n    if (sessionMatches[0]) return sessionMatches[0].sourceControl;\n  }\n\n  const linked = [];\n  for (const sourceControl of args.sourceControls) {\n    const connections = await sourceControl.connections.list({\n      orgId: args.orgId,\n      factoryProjectId: args.factoryProjectId,\n    });\n    let hasLinkedRepository = false;\n    for (const connection of connections) {\n      try {\n        if (\n          (await sourceControl.projectRepositories.list({ orgId: args.orgId, connectionId: connection.id })).length > 0\n        ) {\n          hasLinkedRepository = true;\n          break;\n        }\n      } catch (error) {\n        if (!(error instanceof SourceControlConnectionNotFoundError)) throw error;\n      }\n    }\n    if (hasLinkedRepository) linked.push(sourceControl);\n  }\n  if (linked.length > 1)\n    throw new FactorySourceControlConflictError(\n      'Factory project has repositories linked through multiple source-control providers.',\n    );\n  return linked[0];\n}\n\nexport interface EnsureFactorySourceSessionArgs {\n  /**\n   * Storage handle of the integration that owns source control. Nothing here is\n   * provider-specific: the connection is matched by the handle's own\n   * `integrationId`, so GitHub, Slack-on-behalf-of-GitHub, or any future owner\n   * all resolve through the same traversal.\n   */\n  sourceControl: SourceControlStorageHandle;\n  orgId: string;\n  factoryProjectId: string;\n  branch: string;\n  /** Pick the linked repository that the work item targets. */\n  repositorySlug: string;\n  /**\n   * Attribute the run to this user instead of the repo connector. Set when the\n   * run has an interactive user — e.g. the person who approved a proposed run.\n   */\n  attributeToUserId?: string;\n}\n\nexport interface EnsuredFactorySourceSession {\n  sessionId: string;\n  userId: string;\n  projectRepositoryId: string;\n  branch: string;\n  baseBranch: string;\n}\n\nexport class FactorySourceSessionResolutionError extends Error {\n  constructor(readonly reason: 'connection' | 'repository') {\n    super(\n      reason === 'connection'\n        ? 'Factory source-control connection not found.'\n        : 'Factory source-control repository not found.',\n    );\n    this.name = 'FactorySourceSessionResolutionError';\n  }\n}\n\nexport interface ResolvedFactorySourceRepository {\n  projectRepositoryId: string;\n  /** The repository's pinned branch, else its default branch. */\n  baseBranch: string;\n  /** Who connected the repository. The attribution for runs with no interactive user. */\n  connectedByUserId: string;\n}\n\n/**\n * Outcome of {@link resolveFactorySourceRepository}. A miss carries which step\n * failed: callers differ on whether that is an error (an autonomous run cannot\n * proceed) or a routine fallback (a chat integration drops to a chat-only\n * session), and the two steps fail for different reasons worth reporting apart.\n */\nexport type FactorySourceRepositoryResult =\n  | ({ found: true } & ResolvedFactorySourceRepository)\n  | { found: false; reason: 'connection' | 'repository' };\n\n/**\n * Resolve which repository a factory project's source-control runs act on: the\n * owner's connection on the project, then one of its linked repositories.\n *\n * The owner is whichever integration owns source control, matched by the\n * handle's own `integrationId` — nothing here is provider-specific.\n */\nexport async function resolveFactorySourceRepository(\n  args:\n    | {\n        sourceControl: SourceControlStorageHandle;\n        orgId: string;\n        factoryProjectId: string;\n        repositorySlug: string;\n      }\n    | {\n        sourceControl: SourceControlStorageHandle;\n        orgId: string;\n        factoryProjectId: string;\n        firstLinkedRepository: true;\n      },\n): Promise<FactorySourceRepositoryResult> {\n  const { sourceControl, orgId, factoryProjectId } = args;\n  const repositorySlug = 'repositorySlug' in args ? args.repositorySlug : undefined;\n  const firstLinkedRepository = 'firstLinkedRepository' in args;\n\n  const connections = await sourceControl.connections.list({ orgId, factoryProjectId });\n  const candidates = connections.filter(candidate => candidate.integrationId === sourceControl.integrationId);\n  if (candidates.length === 0) return { found: false, reason: 'connection' };\n\n  // A project can carry stale connections: a provider-app reinstall leaves the\n  // old connection pointing at an installation that no longer exists, and that\n  // row can sit ahead of the healthy one. Try every candidate and skip the ones\n  // that no longer resolve rather than failing on the first.\n  for (const connection of candidates) {\n    let resolved;\n    try {\n      const projectRepositories = await sourceControl.projectRepositories.list({ orgId, connectionId: connection.id });\n      const resolvedRepositories = await Promise.all(\n        projectRepositories.map(async projectRepository => ({\n          projectRepository,\n          repository: await sourceControl.repositories.get({ orgId, id: projectRepository.repositoryId }),\n        })),\n      );\n      resolved = resolvedRepositories.find(\n        candidate => candidate.repository && (firstLinkedRepository || candidate.repository.slug === repositorySlug),\n      );\n    } catch (error) {\n      // A deleted installation invalidates a stale connection; storage failures must propagate.\n      if (!(error instanceof SourceControlConnectionNotFoundError)) throw error;\n      continue;\n    }\n    if (!resolved?.repository) continue;\n\n    return {\n      found: true,\n      projectRepositoryId: resolved.projectRepository.id,\n      baseBranch: resolved.projectRepository.branch ?? resolved.repository.defaultBranch,\n      connectedByUserId: connection.createdByUserId,\n    };\n  }\n\n  return { found: false, reason: 'repository' };\n}\n\n/**\n * Walk a Factory user-session id back to the project it belongs to.\n *\n * Repo-backed channel threads are keyed by their Factory session id, which is\n * the only handle a session-start hook gets. This turns that id back into the\n * project whose configuration the session should adopt. Durable by\n * construction — it reads the same rows the session was created from, so it\n * survives restarts without any in-memory mapping.\n */\nexport async function resolveFactoryProjectForSession(args: {\n  sourceControl: SourceControlStorageHandle;\n  sessionId: string;\n}): Promise<{ factoryProjectId: string; orgId: string; userId: string } | null> {\n  const { sourceControl, sessionId } = args;\n\n  const session = await sourceControl.sessions.getBySessionId(sessionId);\n  if (!session) return null;\n  const projectRepository = await sourceControl.projectRepositories.get({\n    orgId: session.orgId,\n    id: session.projectRepositoryId,\n  });\n  if (!projectRepository) return null;\n  const connection = await sourceControl.connections.get({ orgId: session.orgId, id: projectRepository.connectionId });\n  if (!connection) return null;\n\n  return { factoryProjectId: connection.factoryProjectId, orgId: session.orgId, userId: session.userId };\n}\n\n/**\n * Create the source-control session a repo-backed factory run needs.\n *\n * `FactoryStartCoordinator.prepare` requires this record to already exist —\n * `resolveSourceSession` throws `Factory session not found` otherwise — so every\n * autonomous entry point has to produce one before it can start a run. This is\n * that step, in one place: the owner's connection on the factory project, one of\n * its linked repositories, and a session on the requested branch with the\n * repository's pinned or default branch as the base.\n *\n * The run is attributed to `attributeToUserId` when the caller has an\n * interactive user (e.g. the approver of a proposed run), and otherwise falls\n * back to whoever connected the repository (`connection.createdByUserId`),\n * because a genuinely autonomous run has no interactive user of its own.\n */\nexport async function ensureFactorySourceSession(\n  args: EnsureFactorySourceSessionArgs,\n): Promise<EnsuredFactorySourceSession> {\n  const { sourceControl, orgId, factoryProjectId, branch, repositorySlug } = args;\n\n  const resolved = await resolveFactorySourceRepository({ sourceControl, orgId, factoryProjectId, repositorySlug });\n  if (!resolved.found) throw new FactorySourceSessionResolutionError(resolved.reason);\n\n  const userId = args.attributeToUserId ?? resolved.connectedByUserId;\n  const session = await sourceControl.sessions.create({\n    sessionId: randomUUID(),\n    projectRepositoryId: resolved.projectRepositoryId,\n    orgId,\n    userId,\n    branch,\n    baseBranch: resolved.baseBranch,\n    visibility: 'org',\n  });\n  return {\n    sessionId: session.sessionId,\n    userId,\n    projectRepositoryId: resolved.projectRepositoryId,\n    branch: session.branch,\n    baseBranch: resolved.baseBranch,\n  };\n}\n\nexport interface HydrateFactorySessionArgs {\n  orgId: string;\n  /**\n   * The factory project whose shared memory settings apply. Factory sessions\n   * never read an individual user's personal memory settings — the project's\n   * own row (or the built-in defaults) is what they run with.\n   */\n  factoryProjectId?: string;\n  /** The factory project's default model. Without it the session keeps the SDK's built-in mode default. */\n  defaultModelId?: string;\n  /**\n   * Model whose provider supplies the observational-memory fallback. Defaults\n   * to the factory model, but channel sessions can use the sender's model so OM\n   * resolves against that sender's credentials.\n   */\n  observationalMemoryModelId?: string;\n  /**\n   * When provided, the factory project's stored memory-settings row is\n   * applied. When omitted (or no row exists) the session is reset to the\n   * built-in memory defaults.\n   */\n  memorySettings?: MemorySettingsStorage;\n}\n\n/**\n * Apply a factory project's configuration to a freshly created session:\n * observational-memory settings, then the project's default model.\n *\n * Both steps are best-effort. A retired model id or an unreachable settings row\n * must not sink a run that is otherwise ready — the session simply keeps the\n * default it was created with, and the reason is logged.\n */\nexport async function hydrateFactorySession(session: FactorySession, args: HydrateFactorySessionArgs): Promise<void> {\n  // The org rung knowledge curation scopes on. Seeded first so it lands even if\n  // a later best-effort step fails; an empty org marks the session unresolved.\n  await seedSessionOrg(session, args.orgId);\n  try {\n    const record =\n      args.memorySettings && args.factoryProjectId\n        ? await args.memorySettings.get({\n            orgId: args.orgId,\n            userId: factoryMemorySettingsUserId(args.factoryProjectId),\n          })\n        : null;\n    // Without a stored row, fall back to the low-cost OM model of the factory\n    // default model's provider — a factory connected only to Anthropic should\n    // not observe with the (uncredentialed) built-in Google default.\n    const observationalMemoryModelId = args.observationalMemoryModelId ?? args.defaultModelId;\n    const provider = observationalMemoryModelId?.split('/')[0];\n    const fallbackOmModelId = provider\n      ? resolveProviderOMDefault(provider, observationalMemoryModelId).modelId\n      : undefined;\n    await applyStoredMemorySettings(session, record, fallbackOmModelId);\n  } catch (error) {\n    console.warn('[Factory Start] Failed to apply observational-memory settings', {\n      error: error instanceof Error ? error.message : String(error),\n    });\n  }\n  if (args.defaultModelId) {\n    try {\n      await session.model.switch({ modelId: args.defaultModelId });\n    } catch (error) {\n      console.warn('[Factory Start] Failed to apply factory default model', {\n        modelId: args.defaultModelId,\n        error: error instanceof Error ? error.message : String(error),\n      });\n    }\n    // Subagents otherwise keep the server-wide settings (or the SDK's built-in\n    // default), which may name a provider this factory has no credentials for.\n    // Each role is independent, so one failure doesn't strand the others.\n    for (const agentType of ['explore', 'plan', 'execute']) {\n      try {\n        await session.subagents.model.set({ modelId: args.defaultModelId, agentType });\n      } catch (error) {\n        console.warn('[Factory Start] Failed to apply factory default subagent model', {\n          agentType,\n          modelId: args.defaultModelId,\n          error: error instanceof Error ? error.message : String(error),\n        });\n      }\n    }\n  }\n}\n\nexport interface RefreshFactorySessionMemorySettingsArgs {\n  orgId: string;\n  factoryProjectId: string;\n  projects: Pick<FactoryProjectsStorage, 'get'>;\n  memorySettings: Pick<MemorySettingsStorage, 'get'>;\n}\n\n/**\n * Re-apply a factory project's stored observational-memory settings to an\n * already-running session that automation is about to reuse. Session creation\n * hydrates these settings once (`hydrateFactorySession`), but a reused binding\n * keeps whatever observer/reflector models it was created with — so a project\n * whose OM models changed since would keep observing with the stale (and\n * possibly since-rejected) models. This reads the project's current row with the\n * same provider-aware fallback as initial hydration and applies it, mirroring\n * the `GET /web/config/om` refresh. Best-effort: a settings lookup failure must\n * never sink an otherwise-ready run, so it is logged and swallowed.\n */\nexport async function refreshFactorySessionMemorySettings(\n  session: OMConfigurableSession,\n  args: RefreshFactorySessionMemorySettingsArgs,\n): Promise<void> {\n  try {\n    const record = await args.memorySettings.get({\n      orgId: args.orgId,\n      userId: factoryMemorySettingsUserId(args.factoryProjectId),\n    });\n    const project = await args.projects.get({ orgId: args.orgId, id: args.factoryProjectId });\n    const provider = project?.defaultModelId?.split('/')[0];\n    const fallbackOmModelId = provider\n      ? resolveProviderOMDefault(provider, project?.defaultModelId ?? undefined).modelId\n      : undefined;\n    await applyStoredMemorySettings(session, record, fallbackOmModelId);\n  } catch (error) {\n    console.warn('[Factory dispatch] Failed to reapply observational-memory settings on session reuse', {\n      error: error instanceof Error ? error.message : String(error),\n    });\n  }\n}\n"],"mappings":"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"}

package/dist/session/work-item-repository.d.ts

@@ -0,0 +1,21 @@
+import { type SourceControlStorageHandle } from '../storage/domains/source-control/base.js';
+import type { WorkItemRow } from '../storage/domains/work-items/base.js';
+export type WorkItemRepositoryResolution = {
+    status: 'resolved';
+    projectRepositoryId: string;
+    slug: string;
+} | {
+    status: 'unlinked';
+    hint: string;
+} | {
+    status: 'ambiguous';
+    candidates: string[];
+};
+export declare function resolveWorkItemRepository(args: {
+    sourceControl: SourceControlStorageHandle;
+    orgId: string;
+    factoryProjectId: string;
+    item: Pick<WorkItemRow, 'metadata'>;
+    linearRepositoryMap?: Record<string, string>;
+}): Promise<WorkItemRepositoryResolution>;
+//# sourceMappingURL=work-item-repository.d.ts.map

package/dist/session/work-item-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-item-repository.d.ts","sourceRoot":"","sources":["../../src/session/work-item-repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,2CAA2C,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAEzE,MAAM,MAAM,4BAA4B,GACpC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAQlD,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,aAAa,EAAE,0BAA0B,CAAC;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;IACpC,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAsExC"}