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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (313) hide show
  1. package/CHANGELOG.md +695 -0
  2. package/LICENSE.md +30 -0
  3. package/README.md +27 -0
  4. package/dist/auth.d.ts +181 -0
  5. package/dist/auth.d.ts.map +1 -0
  6. package/dist/auth.js +505 -0
  7. package/dist/auth.js.map +1 -0
  8. package/dist/capabilities/connection.d.ts +9 -0
  9. package/dist/capabilities/connection.d.ts.map +1 -0
  10. package/dist/capabilities/connection.js +1 -0
  11. package/dist/capabilities/intake.d.ts +140 -0
  12. package/dist/capabilities/intake.d.ts.map +1 -0
  13. package/dist/capabilities/intake.js +1 -0
  14. package/dist/capabilities/version-control.d.ts +245 -0
  15. package/dist/capabilities/version-control.d.ts.map +1 -0
  16. package/dist/capabilities/version-control.js +1 -0
  17. package/dist/factory.d.ts +156 -0
  18. package/dist/factory.d.ts.map +1 -0
  19. package/dist/factory.js +483 -0
  20. package/dist/factory.js.map +1 -0
  21. package/dist/index.d.ts +14 -0
  22. package/dist/index.d.ts.map +1 -0
  23. package/dist/index.js +7 -0
  24. package/dist/integrations/base.d.ts +210 -0
  25. package/dist/integrations/base.d.ts.map +1 -0
  26. package/dist/integrations/base.js +1 -0
  27. package/dist/integrations/github/config.d.ts +60 -0
  28. package/dist/integrations/github/config.d.ts.map +1 -0
  29. package/dist/integrations/github/config.js +42 -0
  30. package/dist/integrations/github/config.js.map +1 -0
  31. package/dist/integrations/github/factory-session.d.ts +12 -0
  32. package/dist/integrations/github/factory-session.d.ts.map +1 -0
  33. package/dist/integrations/github/factory-session.js +37 -0
  34. package/dist/integrations/github/factory-session.js.map +1 -0
  35. package/dist/integrations/github/integration.d.ts +191 -0
  36. package/dist/integrations/github/integration.d.ts.map +1 -0
  37. package/dist/integrations/github/integration.js +1077 -0
  38. package/dist/integrations/github/integration.js.map +1 -0
  39. package/dist/integrations/github/issue-triage.d.ts +27 -0
  40. package/dist/integrations/github/issue-triage.d.ts.map +1 -0
  41. package/dist/integrations/github/issue-triage.js +82 -0
  42. package/dist/integrations/github/issue-triage.js.map +1 -0
  43. package/dist/integrations/github/pat.d.ts +38 -0
  44. package/dist/integrations/github/pat.d.ts.map +1 -0
  45. package/dist/integrations/github/pat.js +59 -0
  46. package/dist/integrations/github/pat.js.map +1 -0
  47. package/dist/integrations/github/provenance.d.ts +27 -0
  48. package/dist/integrations/github/provenance.d.ts.map +1 -0
  49. package/dist/integrations/github/provenance.js +75 -0
  50. package/dist/integrations/github/provenance.js.map +1 -0
  51. package/dist/integrations/github/routes.d.ts +69 -0
  52. package/dist/integrations/github/routes.d.ts.map +1 -0
  53. package/dist/integrations/github/routes.js +1324 -0
  54. package/dist/integrations/github/routes.js.map +1 -0
  55. package/dist/integrations/github/rules.d.ts +78 -0
  56. package/dist/integrations/github/rules.d.ts.map +1 -0
  57. package/dist/integrations/github/rules.js +362 -0
  58. package/dist/integrations/github/rules.js.map +1 -0
  59. package/dist/integrations/github/sandbox-release.d.ts +38 -0
  60. package/dist/integrations/github/sandbox-release.d.ts.map +1 -0
  61. package/dist/integrations/github/sandbox-release.js +74 -0
  62. package/dist/integrations/github/sandbox-release.js.map +1 -0
  63. package/dist/integrations/github/sandbox.d.ts +281 -0
  64. package/dist/integrations/github/sandbox.d.ts.map +1 -0
  65. package/dist/integrations/github/sandbox.js +547 -0
  66. package/dist/integrations/github/sandbox.js.map +1 -0
  67. package/dist/integrations/github/session-subscriptions.d.ts +26 -0
  68. package/dist/integrations/github/session-subscriptions.d.ts.map +1 -0
  69. package/dist/integrations/github/session-subscriptions.js +192 -0
  70. package/dist/integrations/github/session-subscriptions.js.map +1 -0
  71. package/dist/integrations/github/subscriptions.d.ts +54 -0
  72. package/dist/integrations/github/subscriptions.d.ts.map +1 -0
  73. package/dist/integrations/github/subscriptions.js +62 -0
  74. package/dist/integrations/github/subscriptions.js.map +1 -0
  75. package/dist/integrations/github/token-refresh.d.ts +12 -0
  76. package/dist/integrations/github/token-refresh.d.ts.map +1 -0
  77. package/dist/integrations/github/token-refresh.js +24 -0
  78. package/dist/integrations/github/token-refresh.js.map +1 -0
  79. package/dist/integrations/github/webhook.d.ts +87 -0
  80. package/dist/integrations/github/webhook.d.ts.map +1 -0
  81. package/dist/integrations/github/webhook.js +397 -0
  82. package/dist/integrations/github/webhook.js.map +1 -0
  83. package/dist/integrations/linear/agent-tools.d.ts +34 -0
  84. package/dist/integrations/linear/agent-tools.d.ts.map +1 -0
  85. package/dist/integrations/linear/agent-tools.js +85 -0
  86. package/dist/integrations/linear/agent-tools.js.map +1 -0
  87. package/dist/integrations/linear/integration.d.ts +233 -0
  88. package/dist/integrations/linear/integration.d.ts.map +1 -0
  89. package/dist/integrations/linear/integration.js +672 -0
  90. package/dist/integrations/linear/integration.js.map +1 -0
  91. package/dist/integrations/linear/routes.d.ts +61 -0
  92. package/dist/integrations/linear/routes.d.ts.map +1 -0
  93. package/dist/integrations/linear/routes.js +239 -0
  94. package/dist/integrations/linear/routes.js.map +1 -0
  95. package/dist/integrations/linear/rules.d.ts +42 -0
  96. package/dist/integrations/linear/rules.d.ts.map +1 -0
  97. package/dist/integrations/linear/rules.js +133 -0
  98. package/dist/integrations/linear/rules.js.map +1 -0
  99. package/dist/integrations/linear/storage.d.ts +65 -0
  100. package/dist/integrations/linear/storage.d.ts.map +1 -0
  101. package/dist/integrations/linear/storage.js +1 -0
  102. package/dist/integrations/platform/api-client.d.ts +26 -0
  103. package/dist/integrations/platform/api-client.d.ts.map +1 -0
  104. package/dist/integrations/platform/api-client.js +156 -0
  105. package/dist/integrations/platform/api-client.js.map +1 -0
  106. package/dist/integrations/platform/github/event-worker.d.ts +49 -0
  107. package/dist/integrations/platform/github/event-worker.d.ts.map +1 -0
  108. package/dist/integrations/platform/github/event-worker.js +348 -0
  109. package/dist/integrations/platform/github/event-worker.js.map +1 -0
  110. package/dist/integrations/platform/github/integration.d.ts +50 -0
  111. package/dist/integrations/platform/github/integration.d.ts.map +1 -0
  112. package/dist/integrations/platform/github/integration.js +961 -0
  113. package/dist/integrations/platform/github/integration.js.map +1 -0
  114. package/dist/integrations/platform/linear/integration.d.ts +46 -0
  115. package/dist/integrations/platform/linear/integration.d.ts.map +1 -0
  116. package/dist/integrations/platform/linear/integration.js +483 -0
  117. package/dist/integrations/platform/linear/integration.js.map +1 -0
  118. package/dist/integrations/workos/integration.d.ts +39 -0
  119. package/dist/integrations/workos/integration.d.ts.map +1 -0
  120. package/dist/integrations/workos/integration.js +91 -0
  121. package/dist/integrations/workos/integration.js.map +1 -0
  122. package/dist/routes/config.d.ts +235 -0
  123. package/dist/routes/config.d.ts.map +1 -0
  124. package/dist/routes/config.js +972 -0
  125. package/dist/routes/config.js.map +1 -0
  126. package/dist/routes/custom-provider-source.d.ts +52 -0
  127. package/dist/routes/custom-provider-source.d.ts.map +1 -0
  128. package/dist/routes/custom-provider-source.js +124 -0
  129. package/dist/routes/custom-provider-source.js.map +1 -0
  130. package/dist/routes/fs.d.ts +151 -0
  131. package/dist/routes/fs.d.ts.map +1 -0
  132. package/dist/routes/fs.js +708 -0
  133. package/dist/routes/fs.js.map +1 -0
  134. package/dist/routes/intake.d.ts +23 -0
  135. package/dist/routes/intake.d.ts.map +1 -0
  136. package/dist/routes/intake.js +179 -0
  137. package/dist/routes/intake.js.map +1 -0
  138. package/dist/routes/oauth.d.ts +43 -0
  139. package/dist/routes/oauth.d.ts.map +1 -0
  140. package/dist/routes/oauth.js +463 -0
  141. package/dist/routes/oauth.js.map +1 -0
  142. package/dist/routes/projects.d.ts +19 -0
  143. package/dist/routes/projects.d.ts.map +1 -0
  144. package/dist/routes/projects.js +461 -0
  145. package/dist/routes/projects.js.map +1 -0
  146. package/dist/routes/provider-credentials.d.ts +81 -0
  147. package/dist/routes/provider-credentials.d.ts.map +1 -0
  148. package/dist/routes/provider-credentials.js +86 -0
  149. package/dist/routes/provider-credentials.js.map +1 -0
  150. package/dist/routes/route.d.ts +48 -0
  151. package/dist/routes/route.d.ts.map +1 -0
  152. package/dist/routes/route.js +15 -0
  153. package/dist/routes/route.js.map +1 -0
  154. package/dist/routes/skills.d.ts +30 -0
  155. package/dist/routes/skills.d.ts.map +1 -0
  156. package/dist/routes/skills.js +168 -0
  157. package/dist/routes/skills.js.map +1 -0
  158. package/dist/routes/surface.d.ts +91 -0
  159. package/dist/routes/surface.d.ts.map +1 -0
  160. package/dist/routes/surface.js +260 -0
  161. package/dist/routes/surface.js.map +1 -0
  162. package/dist/routes/tenant-credentials.d.ts +74 -0
  163. package/dist/routes/tenant-credentials.d.ts.map +1 -0
  164. package/dist/routes/tenant-credentials.js +156 -0
  165. package/dist/routes/tenant-credentials.js.map +1 -0
  166. package/dist/routes/work-items.d.ts +40 -0
  167. package/dist/routes/work-items.d.ts.map +1 -0
  168. package/dist/routes/work-items.js +695 -0
  169. package/dist/routes/work-items.js.map +1 -0
  170. package/dist/rules/binding-context.d.ts +5 -0
  171. package/dist/rules/binding-context.d.ts.map +1 -0
  172. package/dist/rules/binding-context.js +28 -0
  173. package/dist/rules/binding-context.js.map +1 -0
  174. package/dist/rules/defaults.d.ts +9 -0
  175. package/dist/rules/defaults.d.ts.map +1 -0
  176. package/dist/rules/defaults.js +260 -0
  177. package/dist/rules/defaults.js.map +1 -0
  178. package/dist/rules/dispatcher.d.ts +42 -0
  179. package/dist/rules/dispatcher.d.ts.map +1 -0
  180. package/dist/rules/dispatcher.js +518 -0
  181. package/dist/rules/dispatcher.js.map +1 -0
  182. package/dist/rules/index.d.ts +7 -0
  183. package/dist/rules/index.d.ts.map +1 -0
  184. package/dist/rules/index.js +5 -0
  185. package/dist/rules/processor.d.ts +54 -0
  186. package/dist/rules/processor.d.ts.map +1 -0
  187. package/dist/rules/processor.js +378 -0
  188. package/dist/rules/processor.js.map +1 -0
  189. package/dist/rules/resolve.d.ts +17 -0
  190. package/dist/rules/resolve.d.ts.map +1 -0
  191. package/dist/rules/resolve.js +30 -0
  192. package/dist/rules/resolve.js.map +1 -0
  193. package/dist/rules/start-coordinator.d.ts +60 -0
  194. package/dist/rules/start-coordinator.d.ts.map +1 -0
  195. package/dist/rules/start-coordinator.js +194 -0
  196. package/dist/rules/start-coordinator.js.map +1 -0
  197. package/dist/rules/tools.d.ts +10 -0
  198. package/dist/rules/tools.d.ts.map +1 -0
  199. package/dist/rules/tools.js +58 -0
  200. package/dist/rules/tools.js.map +1 -0
  201. package/dist/rules/transition-service.d.ts +49 -0
  202. package/dist/rules/transition-service.d.ts.map +1 -0
  203. package/dist/rules/transition-service.js +232 -0
  204. package/dist/rules/transition-service.js.map +1 -0
  205. package/dist/rules/types.d.ts +234 -0
  206. package/dist/rules/types.d.ts.map +1 -0
  207. package/dist/rules/types.js +38 -0
  208. package/dist/rules/types.js.map +1 -0
  209. package/dist/rules/validation.d.ts +11 -0
  210. package/dist/rules/validation.d.ts.map +1 -0
  211. package/dist/rules/validation.js +308 -0
  212. package/dist/rules/validation.js.map +1 -0
  213. package/dist/sandbox/fleet.d.ts +222 -0
  214. package/dist/sandbox/fleet.d.ts.map +1 -0
  215. package/dist/sandbox/fleet.js +322 -0
  216. package/dist/sandbox/fleet.js.map +1 -0
  217. package/dist/sandbox/reattach.d.ts +3 -0
  218. package/dist/sandbox/reattach.d.ts.map +1 -0
  219. package/dist/sandbox/reattach.js +16 -0
  220. package/dist/sandbox/reattach.js.map +1 -0
  221. package/dist/server-error.d.ts +12 -0
  222. package/dist/server-error.d.ts.map +1 -0
  223. package/dist/server-error.js +16 -0
  224. package/dist/server-error.js.map +1 -0
  225. package/dist/skills/service.d.ts +48 -0
  226. package/dist/skills/service.d.ts.map +1 -0
  227. package/dist/skills/service.js +40 -0
  228. package/dist/skills/service.js.map +1 -0
  229. package/dist/spa-static.d.ts +33 -0
  230. package/dist/spa-static.d.ts.map +1 -0
  231. package/dist/spa-static.js +104 -0
  232. package/dist/spa-static.js.map +1 -0
  233. package/dist/state-signing.d.ts +59 -0
  234. package/dist/state-signing.d.ts.map +1 -0
  235. package/dist/state-signing.js +83 -0
  236. package/dist/state-signing.js.map +1 -0
  237. package/dist/storage/domains/audit/agent-audit.d.ts +27 -0
  238. package/dist/storage/domains/audit/agent-audit.d.ts.map +1 -0
  239. package/dist/storage/domains/audit/agent-audit.js +66 -0
  240. package/dist/storage/domains/audit/agent-audit.js.map +1 -0
  241. package/dist/storage/domains/audit/base.d.ts +140 -0
  242. package/dist/storage/domains/audit/base.d.ts.map +1 -0
  243. package/dist/storage/domains/audit/base.js +184 -0
  244. package/dist/storage/domains/audit/base.js.map +1 -0
  245. package/dist/storage/domains/audit/domain.d.ts +69 -0
  246. package/dist/storage/domains/audit/domain.d.ts.map +1 -0
  247. package/dist/storage/domains/audit/domain.js +167 -0
  248. package/dist/storage/domains/audit/domain.js.map +1 -0
  249. package/dist/storage/domains/channel-identity/base.d.ts +96 -0
  250. package/dist/storage/domains/channel-identity/base.d.ts.map +1 -0
  251. package/dist/storage/domains/channel-identity/base.js +149 -0
  252. package/dist/storage/domains/channel-identity/base.js.map +1 -0
  253. package/dist/storage/domains/credentials/base.d.ts +134 -0
  254. package/dist/storage/domains/credentials/base.d.ts.map +1 -0
  255. package/dist/storage/domains/credentials/base.js +273 -0
  256. package/dist/storage/domains/credentials/base.js.map +1 -0
  257. package/dist/storage/domains/custom-providers/base.d.ts +57 -0
  258. package/dist/storage/domains/custom-providers/base.d.ts.map +1 -0
  259. package/dist/storage/domains/custom-providers/base.js +145 -0
  260. package/dist/storage/domains/custom-providers/base.js.map +1 -0
  261. package/dist/storage/domains/intake/base.d.ts +38 -0
  262. package/dist/storage/domains/intake/base.d.ts.map +1 -0
  263. package/dist/storage/domains/intake/base.js +80 -0
  264. package/dist/storage/domains/intake/base.js.map +1 -0
  265. package/dist/storage/domains/integrations/base.d.ts +126 -0
  266. package/dist/storage/domains/integrations/base.d.ts.map +1 -0
  267. package/dist/storage/domains/integrations/base.js +317 -0
  268. package/dist/storage/domains/integrations/base.js.map +1 -0
  269. package/dist/storage/domains/memory-settings/base.d.ts +62 -0
  270. package/dist/storage/domains/memory-settings/base.d.ts.map +1 -0
  271. package/dist/storage/domains/memory-settings/base.js +126 -0
  272. package/dist/storage/domains/memory-settings/base.js.map +1 -0
  273. package/dist/storage/domains/model-packs/base.d.ts +49 -0
  274. package/dist/storage/domains/model-packs/base.d.ts.map +1 -0
  275. package/dist/storage/domains/model-packs/base.js +96 -0
  276. package/dist/storage/domains/model-packs/base.js.map +1 -0
  277. package/dist/storage/domains/projects/base.d.ts +58 -0
  278. package/dist/storage/domains/projects/base.d.ts.map +1 -0
  279. package/dist/storage/domains/projects/base.js +111 -0
  280. package/dist/storage/domains/projects/base.js.map +1 -0
  281. package/dist/storage/domains/queue-health/base.d.ts +52 -0
  282. package/dist/storage/domains/queue-health/base.d.ts.map +1 -0
  283. package/dist/storage/domains/queue-health/base.js +122 -0
  284. package/dist/storage/domains/queue-health/base.js.map +1 -0
  285. package/dist/storage/domains/source-control/base.d.ts +358 -0
  286. package/dist/storage/domains/source-control/base.d.ts.map +1 -0
  287. package/dist/storage/domains/source-control/base.js +908 -0
  288. package/dist/storage/domains/source-control/base.js.map +1 -0
  289. package/dist/storage/domains/source-control/inmemory.d.ts +175 -0
  290. package/dist/storage/domains/source-control/inmemory.d.ts.map +1 -0
  291. package/dist/storage/domains/source-control/inmemory.js +377 -0
  292. package/dist/storage/domains/source-control/inmemory.js.map +1 -0
  293. package/dist/storage/domains/work-items/base.d.ts +412 -0
  294. package/dist/storage/domains/work-items/base.d.ts.map +1 -0
  295. package/dist/storage/domains/work-items/base.js +1309 -0
  296. package/dist/storage/domains/work-items/base.js.map +1 -0
  297. package/dist/storage/domains/work-items/metrics.d.ts +101 -0
  298. package/dist/storage/domains/work-items/metrics.d.ts.map +1 -0
  299. package/dist/storage/domains/work-items/metrics.js +221 -0
  300. package/dist/storage/domains/work-items/metrics.js.map +1 -0
  301. package/dist/timing.d.ts +15 -0
  302. package/dist/timing.d.ts.map +1 -0
  303. package/dist/timing.js +34 -0
  304. package/dist/timing.js.map +1 -0
  305. package/dist/workspace.d.ts +24 -0
  306. package/dist/workspace.d.ts.map +1 -0
  307. package/dist/workspace.js +286 -0
  308. package/dist/workspace.js.map +1 -0
  309. package/factory-skills/configure-factory-rules/SKILL.md +67 -0
  310. package/factory-skills/factory-plan/SKILL.md +61 -0
  311. package/factory-skills/factory-review/SKILL.md +155 -0
  312. package/factory-skills/factory-triage/SKILL.md +77 -0
  313. package/package.json +81 -0
@@ -0,0 +1,281 @@
1
+ /**
2
+ * Repo materialization for GitHub-backed repositories.
3
+ *
4
+ * A GitHub repo is never cloned onto the server host. Instead each project gets
5
+ * its own isolated sandbox (provisioned by the fleet in `../sandbox/fleet`) and
6
+ * the repo is cloned *inside* that sandbox. The agent's file tools and command
7
+ * tools then operate entirely against the remote checkout.
8
+ *
9
+ * - `ensureProjectSandbox(row)` / `teardownProjectSandbox(row)` bind the fleet's
10
+ * provision/reattach/teardown lifecycle to the per-(project,user) sandbox row.
11
+ * - `materializeRepo(row, token)` runs `git clone` (first open) or `git pull`
12
+ * (re-open) inside the sandbox, using a short-lived installation token that is
13
+ * scrubbed from the git remote afterwards so it never persists in the VM.
14
+ *
15
+ * This module owns everything git/GitHub: clone/pull, commit/push, worktrees,
16
+ * and `gh pr create`. Sandbox provisioning, budgets, and workdir layout live in
17
+ * the fleet module.
18
+ */
19
+ import type { MaterializationSandbox, ProgressFn, SandboxFleet } from '../../sandbox/fleet.js';
20
+ import type { ProjectRepositorySandbox, SourceControlStorageHandle } from '../../storage/domains/source-control/base.js';
21
+ type SourceControlSandboxStorage = SourceControlStorageHandle['sandboxes'];
22
+ type MaterializationStore = Pick<SourceControlSandboxStorage, 'markMaterialized'>;
23
+ interface RepoMaterializationBinding {
24
+ id: string;
25
+ sandboxWorkdir: string;
26
+ materializedAt: Date | null;
27
+ }
28
+ /**
29
+ * Provision a new sandbox (persisting its provider id on first open) or
30
+ * reattach to the stored one. Returns a started, live sandbox.
31
+ */
32
+ export declare function ensureProjectSandbox(options: {
33
+ fleet: SandboxFleet;
34
+ row: ProjectRepositorySandbox;
35
+ storage: SourceControlSandboxStorage;
36
+ token: string;
37
+ onProgress?: ProgressFn;
38
+ }): Promise<MaterializationSandbox>;
39
+ /**
40
+ * Tear down a user's sandbox for a project: stop the live VM (best-effort) and
41
+ * clear the persisted `sandboxId`/`materializedAt` on the per-(project,user)
42
+ * binding row so the next open re-provisions cleanly.
43
+ *
44
+ * @param row the per-(project,user) sandbox binding to tear down
45
+ * @param sandbox an already-reattached live sandbox to stop, when available
46
+ */
47
+ export declare function teardownProjectSandbox(options: {
48
+ fleet: SandboxFleet;
49
+ row: ProjectRepositorySandbox;
50
+ storage: SourceControlSandboxStorage;
51
+ sandbox?: MaterializationSandbox;
52
+ }): Promise<void>;
53
+ /**
54
+ * Single-quote a string for safe POSIX shell interpolation. Wraps the value in
55
+ * single quotes and escapes any embedded single quote using the canonical
56
+ * close-quote / escaped-quote / reopen-quote sequence (`'\''`). This is the
57
+ * standard POSIX-safe construction and prevents the quoted string from being
58
+ * terminated early.
59
+ */
60
+ export declare function shellQuote(value: string): string;
61
+ /** Branch checkout only fetches one ref — a much tighter budget applies. */
62
+ export declare const CHECKOUT_COMMAND_TIMEOUT_MS: number;
63
+ /** Error raised when the sandbox cannot materialize the repo (actionable). */
64
+ export declare class MaterializeError extends Error {
65
+ readonly code: 'git-missing' | 'egress-blocked' | 'clone-failed' | 'pull-failed' | 'push-failed' | 'commit-failed' | 'gh-missing' | 'pr-failed';
66
+ constructor(message: string, code: 'git-missing' | 'egress-blocked' | 'clone-failed' | 'pull-failed' | 'push-failed' | 'commit-failed' | 'gh-missing' | 'pr-failed');
67
+ }
68
+ /** Repo metadata needed to materialize, read from the org-owned project row. */
69
+ export interface RepoMaterializeInfo {
70
+ repoFullName: string;
71
+ defaultBranch: string;
72
+ }
73
+ /**
74
+ * Materialize the repo inside the user's sandbox. Clones on first open, pulls on
75
+ * re-open. Always scrubs the install token from the remote afterwards and sets
76
+ * `materialized_at` on the per-user sandbox binding row.
77
+ *
78
+ */
79
+ export declare function materializeRepo(options: {
80
+ /** The per-(project,user) sandbox binding (provisioned via `ensureProjectSandbox`). */
81
+ row: RepoMaterializationBinding;
82
+ /** Repo metadata from the org-owned project row. */
83
+ repoInfo: RepoMaterializeInfo;
84
+ /** The live sandbox to run git inside. */
85
+ sandbox: MaterializationSandbox;
86
+ /** A freshly minted, short-lived installation access token. */
87
+ token: string;
88
+ storage: MaterializationStore;
89
+ onProgress?: ProgressFn;
90
+ }): Promise<void>;
91
+ /**
92
+ * Reset a pooled workdir that a new session just claimed: the previous
93
+ * session's branch and dirty state must not leak into the new session, so
94
+ * force-checkout the default branch and drop all local modifications. When
95
+ * the claimed VM was reaped and re-provisioned there is no checkout yet and
96
+ * this is a no-op (the clone path handles it). A wedged checkout falls back
97
+ * to wiping the workdir so `materializeRepo` re-clones inside the same VM
98
+ * instead of permanently failing the session.
99
+ */
100
+ export declare function recycleClaimedWorkdir(sandbox: MaterializationSandbox, workdir: string, defaultBranch: string): Promise<void>;
101
+ /** Check out a session's branch inside its isolated repository clone. */
102
+ export declare function checkoutSessionBranch(sandbox: MaterializationSandbox, workdir: string, { branch, baseBranch, token, repoFullName, }: {
103
+ branch: string;
104
+ baseBranch: string;
105
+ token: string;
106
+ repoFullName: string;
107
+ }): Promise<void>;
108
+ /**
109
+ * Validate a git ref (branch) name. Server-side defense-in-depth: only allow a
110
+ * conservative character set so a branch can never be built into a shell
111
+ * command in a way that escapes quoting. Mirrors the route-layer check.
112
+ */
113
+ export declare function isValidGitRef(value: unknown): value is string;
114
+ /** Identity used to author commits inside the sandbox. */
115
+ export interface GitIdentity {
116
+ name?: string | null;
117
+ email?: string | null;
118
+ /** GitHub login, used to derive a stable noreply identity when name/email are absent. */
119
+ login?: string | null;
120
+ }
121
+ /**
122
+ * Resolve a concrete `{ name, email }` for git authorship from a possibly-sparse
123
+ * identity. Falls back to a GitHub-style noreply identity so commits are never
124
+ * authored with an empty or host-derived identity.
125
+ */
126
+ export declare function resolveGitIdentity(identity: GitIdentity): {
127
+ name: string;
128
+ email: string;
129
+ };
130
+ /**
131
+ * Configure `user.name` / `user.email` for the given repo working tree inside
132
+ * the sandbox so commits are authored correctly. Values are shell-quoted.
133
+ */
134
+ export declare function configureGitIdentity(sandbox: MaterializationSandbox, workdir: string, identity: GitIdentity): Promise<void>;
135
+ /**
136
+ * Temporarily rewrite `origin` to a tokenized URL, run `fn` (e.g. a push), and
137
+ * **always** scrub the remote back to the tokenless URL in a `finally`. The
138
+ * token therefore only ever lives in the remote URL for the duration of the
139
+ * operation and is never left in the VM's git config.
140
+ *
141
+ * On the success path the scrub must succeed (a leaked token is a hard error);
142
+ * if it fails we surface it. On the failure path the scrub is best-effort but
143
+ * still attempted, and the original operation error is rethrown.
144
+ */
145
+ export declare function withInstallToken<T>(sandbox: MaterializationSandbox, workdir: string, repoFullName: string, token: string, fn: () => Promise<T>): Promise<T>;
146
+ /**
147
+ * Push a branch back to GitHub from inside the sandbox using a short-lived
148
+ * installation token. The branch is ref-validated, the token is injected only
149
+ * into the remote URL via `withInstallToken`, and egress failures are
150
+ * classified into actionable errors.
151
+ */
152
+ export declare function pushBranch(sandbox: MaterializationSandbox, workdir: string, branch: string, token: string, repoFullName: string): Promise<void>;
153
+ export interface CommitResult {
154
+ /** True when a commit was created; false when there was nothing to commit. */
155
+ committed: boolean;
156
+ }
157
+ /**
158
+ * Stage every change in the working tree and create a commit inside the
159
+ * sandbox. The git identity is configured first so authorship is correct. When
160
+ * there is nothing to commit this is a no-op (`committed: false`) rather than an
161
+ * error, so callers can safely commit-then-push without first diffing.
162
+ *
163
+ * @param sandbox the live sandbox containing the checkout
164
+ * @param workdir the worktree (or repo) path to commit in
165
+ * @param message the commit message (quoted; arbitrary text is safe)
166
+ * @param identity authorship identity for the commit
167
+ */
168
+ export declare function commitAll(sandbox: MaterializationSandbox, workdir: string, message: string, identity: GitIdentity): Promise<CommitResult>;
169
+ /** Error raised when a worktree cannot be created/reused inside the sandbox. */
170
+ export declare class WorktreeError extends Error {
171
+ readonly code: 'invalid-branch' | 'worktree-failed' | 'setup-failed';
172
+ constructor(message: string, code: 'invalid-branch' | 'worktree-failed' | 'setup-failed');
173
+ }
174
+ /**
175
+ * Reduce a (already ref-validated) branch name to a filesystem-safe directory
176
+ * segment for the worktree path: slashes/dots/unsafe chars collapsed to `-`.
177
+ * This only affects the *directory name*, never the git branch itself.
178
+ *
179
+ * Sanitization is lossy (e.g. `feat/a` and `feat-a` both reduce to `feat-a`),
180
+ * so an 8-char hash of the original branch is appended whenever the sanitized
181
+ * form differs from the input. That keeps clean names (`main`) readable while
182
+ * guaranteeing distinct branches never share a worktree directory.
183
+ */
184
+ export declare function safeBranchDir(branch: string): string;
185
+ /**
186
+ * Compute the absolute worktree path for a branch, server-side only. Worktrees
187
+ * live alongside the repo checkout under a sibling `worktrees/` directory so the
188
+ * repo's `.git` is shared. Never derived from client-supplied paths.
189
+ */
190
+ export declare function computeWorktreePath(repoWorkdir: string, branch: string): string;
191
+ export interface EnsureWorktreeResult {
192
+ worktreePath: string;
193
+ branch: string;
194
+ baseBranch: string;
195
+ /** True when an existing worktree was reused rather than freshly created. */
196
+ reused: boolean;
197
+ }
198
+ /**
199
+ * Create (or reuse) a git worktree + branch inside the sandbox for a unit of
200
+ * work. Idempotent: if a worktree already exists at the computed path it is
201
+ * reused. The branch is created from the freshly fetched `origin/<baseBranch>`
202
+ * — never the sandbox's possibly stale local ref — so new worktrees always
203
+ * start from the latest remote state.
204
+ *
205
+ * @param sandbox live sandbox containing the base checkout
206
+ * @param repoWorkdir the base repo checkout path inside the sandbox
207
+ * @param branch the feature branch (ref-validated server-side)
208
+ * @param baseBranch the branch to fork from (ref-validated; defaults to the repo's default branch)
209
+ * @param token short-lived installation token used only for the base-branch fetch
210
+ * @param repoFullName `owner/repo` used to build the tokenized remote URL
211
+ */
212
+ export declare function ensureWorktree(sandbox: MaterializationSandbox, repoWorkdir: string, { branch, baseBranch, token, repoFullName, }: {
213
+ branch: string;
214
+ baseBranch: string;
215
+ token: string;
216
+ repoFullName: string;
217
+ }): Promise<EnsureWorktreeResult>;
218
+ /**
219
+ * Run the project's setup command (e.g. `pnpm i && pnpm build`) inside a
220
+ * freshly created worktree. Called before the worktree is handed to any agent
221
+ * run so the checkout is ready to build/test. A non-zero exit is a hard error —
222
+ * starting agent work in a half-set-up tree is worse than failing the request.
223
+ *
224
+ * Security model: the command is intentionally arbitrary shell — that is the
225
+ * feature (install deps, build, seed fixtures). It is only configurable by
226
+ * authenticated org members (the settings route is gated by
227
+ * `resolveOrgTenant` + org-scoped project lookup, with length and
228
+ * control-character validation), and it executes exclusively inside the
229
+ * project's isolated sandbox — the same environment where org members already
230
+ * run arbitrary shell via the agent's command tool. It never runs on the web
231
+ * server host, so it grants no privilege beyond what sandbox access already
232
+ * provides.
233
+ *
234
+ * @param sandbox live sandbox containing the worktree
235
+ * @param worktreePath the server-computed worktree path the command runs in
236
+ * @param command the org-configured setup shell command
237
+ */
238
+ export declare function runWorktreeSetup(sandbox: MaterializationSandbox, worktreePath: string, command: string): Promise<void>;
239
+ /**
240
+ * Remove a worktree (and its local feature branch) from the sandbox. The
241
+ * checkout is removed with `--force` — the caller owns confirming that any
242
+ * uncommitted work in it can be discarded. Idempotent: a worktree whose
243
+ * directory is already gone only has its metadata pruned.
244
+ *
245
+ * @param sandbox live sandbox containing the base checkout
246
+ * @param repoWorkdir the base repo checkout path inside the sandbox
247
+ * @param branch the worktree's feature branch (ref-validated)
248
+ * @param worktreePath the persisted, server-computed worktree path
249
+ */
250
+ export declare function removeWorktree(sandbox: MaterializationSandbox, repoWorkdir: string, { branch, worktreePath }: {
251
+ branch: string;
252
+ worktreePath: string;
253
+ }): Promise<void>;
254
+ export interface CreatePullRequestArgs {
255
+ /** Short-lived installation token, injected only into the `gh` process env. */
256
+ token: string;
257
+ /** Base branch the PR merges into. Ref-validated. */
258
+ base: string;
259
+ /** Head branch the PR is opened from. Ref-validated. */
260
+ head: string;
261
+ /** PR title. */
262
+ title: string;
263
+ /** PR body (optional). */
264
+ body?: string;
265
+ }
266
+ export interface CreatePullRequestResult {
267
+ /** The PR URL parsed from `gh pr create` stdout. */
268
+ url: string;
269
+ }
270
+ /**
271
+ * Open a pull request from inside the sandbox via `gh pr create`. The token is
272
+ * passed only through a per-invocation `GH_TOKEN` env scoped to the single `gh`
273
+ * process (never persisted), all arguments are shell-quoted, and the resulting
274
+ * PR URL is parsed from stdout.
275
+ *
276
+ * @param sandbox live sandbox containing the checkout
277
+ * @param workdir the worktree (or repo) path the PR head branch is checked out in
278
+ */
279
+ export declare function createPullRequest(sandbox: MaterializationSandbox, workdir: string, { token, base, head, title, body }: CreatePullRequestArgs): Promise<CreatePullRequestResult>;
280
+ export {};
281
+ //# sourceMappingURL=sandbox.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/integrations/github/sandbox.ts"],"names":[],"mappings":"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"}