castle-web-cli 0.4.228 → 0.4.230

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 (236) hide show
  1. package/dist/agent-prompts.d.ts +11 -3
  2. package/dist/agent-prompts.js +153 -53
  3. package/dist/agent.d.ts +2 -0
  4. package/dist/agent.js +43 -33
  5. package/dist/api.d.ts +47 -2
  6. package/dist/api.js +85 -16
  7. package/dist/castle-host/host.d.ts +91 -0
  8. package/dist/castle-host/host.js +779 -3
  9. package/dist/castleJson.d.ts +59 -0
  10. package/dist/castleJson.js +267 -3
  11. package/dist/check.js +27 -1
  12. package/dist/cloudGit.d.ts +20 -1
  13. package/dist/cloudGit.js +267 -10
  14. package/dist/contentPack.d.ts +49 -0
  15. package/dist/contentPack.js +273 -0
  16. package/dist/devExperiments.d.ts +21 -0
  17. package/dist/devExperiments.js +139 -0
  18. package/dist/devHub.d.ts +55 -0
  19. package/dist/devHub.js +187 -0
  20. package/dist/devSessionChild.js +3 -1
  21. package/dist/devSessionServer.d.ts +14 -1
  22. package/dist/devSessionServer.js +229 -44
  23. package/dist/experimentAssignment.d.ts +15 -0
  24. package/dist/experimentAssignment.js +41 -0
  25. package/dist/importCheckHook.d.ts +40 -0
  26. package/dist/importCheckHook.js +171 -0
  27. package/dist/importRegression.d.ts +15 -0
  28. package/dist/importRegression.js +100 -0
  29. package/dist/importTrust.d.ts +2 -0
  30. package/dist/importTrust.js +27 -0
  31. package/dist/importUpdateHook.d.ts +18 -0
  32. package/dist/importUpdateHook.js +31 -8
  33. package/dist/importUpdateHookRunner.js +19 -7
  34. package/dist/imports.d.ts +16 -0
  35. package/dist/imports.js +145 -33
  36. package/dist/index.js +8 -1
  37. package/dist/init.d.ts +3 -0
  38. package/dist/init.js +125 -8
  39. package/dist/install.js +4 -1
  40. package/dist/localPaths.js +4 -0
  41. package/dist/login.js +2 -2
  42. package/dist/platformDoc.js +3 -8
  43. package/dist/playPagePolicy.js +3 -1
  44. package/dist/remix.js +5 -0
  45. package/dist/routerTaskReport.d.ts +28 -0
  46. package/dist/routerTaskReport.js +56 -0
  47. package/dist/save-deck.d.ts +18 -0
  48. package/dist/save-deck.js +145 -6
  49. package/dist/serve.d.ts +8 -0
  50. package/dist/serve.js +94 -13
  51. package/dist/serverBundle.d.ts +1 -1
  52. package/dist/serverBundle.js +5 -1
  53. package/dist/sourceLineage.d.ts +42 -0
  54. package/dist/sourceLineage.js +380 -0
  55. package/dist/webSourceSync.d.ts +11 -0
  56. package/dist/webSourceSync.js +26 -9
  57. package/kits/base/CLAUDE.md +2 -3
  58. package/kits/base/castle.json +1 -1
  59. package/kits/base/sdk/README.md +301 -52
  60. package/kits/base/sdk/agent.js +4 -4
  61. package/kits/base/sdk/avatar.d.ts +12 -0
  62. package/kits/base/sdk/avatar.js +23 -0
  63. package/kits/base/sdk/castle.d.ts +6 -1
  64. package/kits/base/sdk/castle.js +3 -0
  65. package/kits/base/sdk/commands.d.ts +208 -0
  66. package/kits/base/sdk/commands.js +16 -0
  67. package/kits/base/sdk/context.d.ts +6 -0
  68. package/kits/base/sdk/experiments.d.ts +15 -0
  69. package/kits/base/sdk/experiments.js +83 -0
  70. package/kits/base/sdk/hub.d.ts +85 -0
  71. package/kits/base/sdk/hub.js +107 -0
  72. package/kits/base/sdk/multiplayer.d.ts +86 -6
  73. package/kits/base/sdk/multiplayer.js +157 -4
  74. package/kits/base/sdk/server/hub.d.ts +169 -0
  75. package/kits/base/sdk/server/hub.js +125 -0
  76. package/kits/base/sdk/server/platformHandle.d.ts +49 -2
  77. package/kits/base/sdk/server/storage.d.ts +55 -2
  78. package/kits/base/sdk/server/wrapper.d.ts +85 -6
  79. package/kits/base/sdk/server/wrapper.js +393 -30
  80. package/kits/base/sdk/transport.d.ts +2 -1
  81. package/kits/base/sdk/transport.js +13 -1
  82. package/kits/hub-game/.prettierrc +5 -0
  83. package/kits/hub-game/CLAUDE.md +146 -0
  84. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  85. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  86. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  87. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  88. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  89. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  90. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  91. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  92. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  93. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  94. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  95. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  96. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  97. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  98. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  99. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  100. package/kits/hub-game/castle.json +96 -0
  101. package/kits/hub-game/code/client/attention.js +133 -0
  102. package/kits/hub-game/code/client/avatar.js +288 -0
  103. package/kits/hub-game/code/client/cabinets.js +90 -0
  104. package/kits/hub-game/code/client/chat.js +135 -0
  105. package/kits/hub-game/code/client/chrome.js +1001 -0
  106. package/kits/hub-game/code/client/doorFrame.js +15 -0
  107. package/kits/hub-game/code/client/firstJoin.js +14 -0
  108. package/kits/hub-game/code/client/grab.js +241 -0
  109. package/kits/hub-game/code/client/hookLayer.js +230 -0
  110. package/kits/hub-game/code/client/idle.js +326 -0
  111. package/kits/hub-game/code/client/keys.js +48 -0
  112. package/kits/hub-game/code/client/pack.js +232 -0
  113. package/kits/hub-game/code/client/packFormat.js +397 -0
  114. package/kits/hub-game/code/client/say.js +127 -0
  115. package/kits/hub-game/code/client/sha256.js +80 -0
  116. package/kits/hub-game/code/client/sound.js +147 -0
  117. package/kits/hub-game/code/client/state.js +131 -0
  118. package/kits/hub-game/code/client/talk.js +259 -0
  119. package/kits/hub-game/code/client/together.js +365 -0
  120. package/kits/hub-game/code/client/wear.js +149 -0
  121. package/kits/hub-game/code/server/actors.js +627 -0
  122. package/kits/hub-game/code/server/blocks.js +103 -0
  123. package/kits/hub-game/code/server/cabinets.js +309 -0
  124. package/kits/hub-game/code/server/game.js +137 -0
  125. package/kits/hub-game/code/server/grab.js +247 -0
  126. package/kits/hub-game/code/server/history.js +96 -0
  127. package/kits/hub-game/code/server/hub.js +1904 -0
  128. package/kits/hub-game/code/server/idle.js +412 -0
  129. package/kits/hub-game/code/server/index.js +64 -0
  130. package/kits/hub-game/code/server/labels.js +59 -0
  131. package/kits/hub-game/code/server/manifest.js +527 -0
  132. package/kits/hub-game/code/server/npcs.js +745 -0
  133. package/kits/hub-game/code/server/party.js +381 -0
  134. package/kits/hub-game/code/server/place.js +43 -0
  135. package/kits/hub-game/code/server/say.js +83 -0
  136. package/kits/hub-game/code/server/wear.js +142 -0
  137. package/kits/hub-game/code/systems/hub.js +2230 -0
  138. package/kits/hub-game/docs/content-pack.md +151 -0
  139. package/kits/hub-game/docs/contract.md +1139 -0
  140. package/kits/hub-game/docs/style.md +137 -0
  141. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  142. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  143. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  144. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  145. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  146. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  147. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  148. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  149. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  150. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  151. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  152. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  153. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  154. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  155. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  156. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  157. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  158. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  159. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  160. package/kits/hub-game/eslint.config.js +20 -0
  161. package/kits/hub-game/fonts.generated.js +9 -0
  162. package/kits/hub-game/index.html +22 -0
  163. package/kits/hub-game/main.jsx +6 -0
  164. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  165. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  166. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  167. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  168. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  169. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  170. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  171. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  172. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  173. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  174. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  175. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  176. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  177. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  178. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  179. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  180. package/kits/hub-game/package-lock.json +365 -0
  181. package/kits/hub-game/package.json +32 -0
  182. package/kits/hub-game/scenes/main.scene +318 -0
  183. package/kits/hub-game/scripts/check.mjs +339 -0
  184. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  185. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  186. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  187. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  188. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  189. package/kits/hub-game/scripts/pack.mjs +192 -0
  190. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  191. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  192. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  193. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  194. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  195. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  196. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  197. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  198. package/kits/hub-game/scripts/test-door.mjs +56 -0
  199. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  200. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  201. package/kits/hub-game/scripts/test-hub-trip.mjs +1310 -0
  202. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  203. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  204. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  205. package/kits/hub-game/scripts/test-manifest.mjs +224 -0
  206. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  207. package/kits/hub-game/scripts/test-npcs.mjs +714 -0
  208. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  209. package/kits/hub-game/scripts/test-party.mjs +286 -0
  210. package/kits/hub-game/scripts/test-say.mjs +149 -0
  211. package/kits/hub-game/scripts/test-together.mjs +183 -0
  212. package/kits/hub-game/theme.style +3 -0
  213. package/kits/multiplayer-3d/castle.json +5 -5
  214. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  215. package/kits/multiplayer-3d/code/server/players.js +4 -1
  216. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  217. package/kits/multiplayer-3d/code/server/world.js +20 -7
  218. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  219. package/kits/physics-2d/castle.json +2 -2
  220. package/kits/physics-2d/engine/art.js +13 -0
  221. package/kits/physics-2d/engine/assets.js +4 -2
  222. package/kits/physics-2d/engine/scene.js +25 -5
  223. package/kits/physics-3d/CLAUDE.md +6 -1
  224. package/kits/physics-3d/castle.json +3 -3
  225. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +32 -4
  226. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  227. package/kits/physics-3d/engine3d/materials.js +29 -1
  228. package/kits/physics-3d/engine3d/world3d.js +65 -1
  229. package/kits/physics-3d/systems/physics3d.js +5 -2
  230. package/kits/real-time/castle.json +2 -2
  231. package/kits/real-time/code/client/connection.js +77 -7
  232. package/kits/real-time/code/client/gameHooks.js +63 -3
  233. package/kits/real-time/code/client/messages.js +7 -0
  234. package/kits/real-time/code/server/gameHooks.js +24 -0
  235. package/kits/real-time/code/server/session.js +390 -22
  236. package/package.json +2 -2
package/dist/cloudGit.js CHANGED
@@ -38,6 +38,11 @@ export const EXIT_CONFLICT = 3;
38
38
  * the snapshot bundle could bring them back. Nothing was changed; the next command retries.
39
39
  */
40
40
  export const EXIT_HISTORY_UNAVAILABLE = 4;
41
+ /**
42
+ * A first attach outran the caller's deadline and carries on in the background (see
43
+ * attachThroughChild). Not attached yet; the deck works without git until it is.
44
+ */
45
+ export const EXIT_ATTACH_CONTINUING = 5;
41
46
  export const HISTORY_UNAVAILABLE_CODE = 'GIT_HISTORY_UNAVAILABLE';
42
47
  export class CloudGitError extends Error {
43
48
  exitCode;
@@ -964,6 +969,16 @@ export const REHYDRATE_STATE_FILE = path.join('.git', 'castle-rehydrate-state.js
964
969
  export const REHYDRATE_LOG_FILE = path.join('.castle', 'agent', 'git-rehydrate.log');
965
970
  /** `off` stops commands from starting a background rehydrate (tests). */
966
971
  export const BACKGROUND_REHYDRATE_ENV = 'CASTLE_GIT_BACKGROUND_REHYDRATE';
972
+ /** A file each rehydrate appends one JSON outcome line to. The sandbox image points it at the
973
+ * container's own stdout (/proc/1/fd/1), which the host ships to Loki; the log file above does
974
+ * not leave the container. Unset: no event. */
975
+ export const CONTAINER_EVENT_LOG_ENV = 'CASTLE_CONTAINER_EVENT_LOG';
976
+ /** Held by the child a first attach runs in, for its whole run (see attachThroughChild). */
977
+ export const ATTACH_LOCK_FILE = path.join('.git', 'castle-attach-lock');
978
+ /** Where that child writes its output. */
979
+ export const ATTACH_LOG_FILE = path.join('.castle', 'agent', 'git-attach.log');
980
+ /** `1` in that child: it attaches in its own process, bound by no caller's deadline. */
981
+ export const BACKGROUND_ATTACH_ENV = 'CASTLE_GIT_BACKGROUND_ATTACH';
967
982
  // The host's capture refuses any file over 32 MiB and fails the whole checkpoint with it. The
968
983
  // snapshot and one set-aside lost snapshot stay under 48 MiB together.
969
984
  export const SNAPSHOT_CAP_BYTES = 24 * 1024 * 1024;
@@ -1955,6 +1970,7 @@ function dropBrokenRefs(ctx) {
1955
1970
  // Under the deck lock, after rehydrateObjects: give up lost local commits only when every
1956
1971
  // source answered cleanly, settle castle/main and the other refs, check the history is whole,
1957
1972
  // and re-hash staged blobs. Throws GIT_HISTORY_UNAVAILABLE (nothing changed) otherwise.
1973
+ // True when it gave up local commits nobody had (recoverLostHistory).
1958
1974
  async function finishRehydrate(ctx, result) {
1959
1975
  const tried = () => `Tried: ${result.notes.join('; ') || 'nothing could be tried'}.`;
1960
1976
  const branches = historyMissing(ctx).filter((tip) => isBranchTip(tip.name));
@@ -1977,6 +1993,7 @@ async function finishRehydrate(ctx, result) {
1977
1993
  }
1978
1994
  await recoverLostHistory(ctx, branches, result);
1979
1995
  }
1996
+ const lost = branches.length > 0;
1980
1997
  // castle/main is where the remote was last seen: kept while its commit is here (the next
1981
1998
  // sync fetches), else what was just fetched, else the mirror's main.
1982
1999
  const remote = refValue(ctx, REMOTE_MAIN);
@@ -2001,6 +2018,7 @@ async function finishRehydrate(ctx, result) {
2001
2018
  refreshSnapshot(ctx, false);
2002
2019
  ctx.deps.log(`Rebuilt this deck's git history from ${result.used.join(', ') || 'what was already here'}` +
2003
2020
  (reindexed.length ? `; re-hashed ${reindexed.length} staged file(s) from disk.` : '.'));
2021
+ return lost;
2004
2022
  }
2005
2023
  // The whole rehydrate, under REHYDRATE_LOCK_FILE: objects first, without the deck lock, then
2006
2024
  // the deck's refs under it. Any failure is recorded for the backoff and surfaces as
@@ -2020,13 +2038,13 @@ async function runRehydrate(ctx) {
2020
2038
  }
2021
2039
  if (historyMissing(ctx).length === 0) {
2022
2040
  fs.rmSync(path.join(ctx.dir, REHYDRATE_STATE_FILE), { force: true });
2023
- return 'complete';
2041
+ return { outcome: 'complete', historyLost: false, used: [] };
2024
2042
  }
2025
2043
  const budgetEnd = ctx.deadline ?? ctx.deps.now() + REHYDRATE_BUDGET_MS;
2026
2044
  const result = await rehydrateObjects(ctx, budgetEnd);
2027
- await withDeckLock(ctx, () => finishRehydrate(ctx, result));
2045
+ const historyLost = await withDeckLock(ctx, () => finishRehydrate(ctx, result));
2028
2046
  fs.rmSync(path.join(ctx.dir, REHYDRATE_STATE_FILE), { force: true });
2029
- return 'rebuilt';
2047
+ return { outcome: 'rebuilt', historyLost, used: result.used };
2030
2048
  }
2031
2049
  catch (e) {
2032
2050
  const error = e instanceof CloudGitError && e.exitCode === EXIT_HISTORY_UNAVAILABLE
@@ -2066,7 +2084,57 @@ export async function cloudRehydrate(dir, deps) {
2066
2084
  catch {
2067
2085
  throw new CloudGitError(`${ctx.dir} has no git repo to rehydrate.`, EXIT_NOT_ENABLED);
2068
2086
  }
2069
- return runRehydrate(ctx);
2087
+ const startedAt = ctx.deps.now();
2088
+ const emit = (fields) => emitContainerEvent(ctx.deps.env, {
2089
+ event: 'sandbox_git_rehydrate',
2090
+ // castle.json is the user's to edit: only a real deck id goes in.
2091
+ deck_id: /^[A-Za-z0-9_-]{1,64}$/.test(readDeckId(ctx.dir) ?? '') ? readDeckId(ctx.dir) : null,
2092
+ ...fields,
2093
+ duration_ms: ctx.deps.now() - startedAt,
2094
+ });
2095
+ let run;
2096
+ try {
2097
+ run = await runRehydrate(ctx);
2098
+ }
2099
+ catch (e) {
2100
+ emit({ outcome: 'failed', error: errorText(e).slice(0, 500) });
2101
+ throw e;
2102
+ }
2103
+ emit({ outcome: run.historyLost ? 'history_lost' : run.outcome, used: run.used });
2104
+ return run.outcome;
2105
+ }
2106
+ // One JSON line to CONTAINER_EVENT_LOG_ENV's file, at most PIPE_BUF bytes so a pipe takes it
2107
+ // whole (an event that would not fit loses its error and sources). Opened non-blocking: a full
2108
+ // pipe drops the line (EAGAIN) rather than stalling the rehydrate. Best effort throughout.
2109
+ const CONTAINER_EVENT_MAX_BYTES = 4096;
2110
+ function emitContainerEvent(env, event) {
2111
+ const target = env[CONTAINER_EVENT_LOG_ENV];
2112
+ if (!target)
2113
+ return;
2114
+ let line = Buffer.from(`${JSON.stringify(event)}\n`);
2115
+ if (line.length > CONTAINER_EVENT_MAX_BYTES) {
2116
+ line = Buffer.from(`${JSON.stringify({ ...event, error: undefined, used: undefined, truncated: true })}\n`);
2117
+ if (line.length > CONTAINER_EVENT_MAX_BYTES)
2118
+ return;
2119
+ }
2120
+ let fd;
2121
+ try {
2122
+ fd = fs.openSync(target, fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_NONBLOCK, 0o600);
2123
+ fs.writeSync(fd, line);
2124
+ }
2125
+ catch {
2126
+ /* best effort */
2127
+ }
2128
+ finally {
2129
+ if (fd !== undefined) {
2130
+ try {
2131
+ fs.closeSync(fd);
2132
+ }
2133
+ catch {
2134
+ /* best effort */
2135
+ }
2136
+ }
2137
+ }
2070
2138
  }
2071
2139
  // Concludes the merge in progress as one whole commit -- only when no conflicted file still
2072
2140
  // has markers. Git refuses a partial commit mid-merge, so named paths are not used.
@@ -2158,13 +2226,13 @@ async function commitLocked(ctx, opts) {
2158
2226
  const specs = commitPathspecs(ctx, opts.paths);
2159
2227
  if (specs.length === 0)
2160
2228
  return { sha: null };
2161
- must(ctx, ['add', '-A', '--', ...specs]);
2229
+ must(ctx, [...BIG_FILE_ARGS, 'add', '-A', '--', ...specs]);
2162
2230
  if (ok(ctx, ['diff', '--cached', '--quiet', '--', ...specs]))
2163
2231
  return { sha: null };
2164
2232
  await commit([...commitMessageArgs(opts, reason), '--', ...specs]);
2165
2233
  }
2166
2234
  else {
2167
- must(ctx, ['add', '-A']);
2235
+ must(ctx, [...BIG_FILE_ARGS, 'add', '-A']);
2168
2236
  if (ok(ctx, ['diff', '--cached', '--quiet']))
2169
2237
  return { sha: null };
2170
2238
  await commit(commitMessageArgs(opts, reason));
@@ -2308,10 +2376,17 @@ function isRejectedPush(result) {
2308
2376
  return /\[rejected\]|non-fast-forward|fetch first|failed to update ref|incorrect old value|cannot lock ref|stale info/i.test(result.stderr);
2309
2377
  }
2310
2378
  const PUSH_ARGS = ['push', '--quiet', GIT_REMOTE_NAME, `${MAIN}:refs/heads/${MAIN}`];
2379
+ // For a commit's add and a push only: blobs over a megabyte go straight into a pack as they are,
2380
+ // and a push sends them without a delta search against the deck's other files. A deck's big
2381
+ // files are images and audio that never delta, and that search was most of a first push (a
2382
+ // 144 MB deck took 35 s in a sandbox; locally its push went from 9 s to 1.4 s). Not repo config:
2383
+ // snapshot bundles and repacks still delta, so a big file's many revisions stay small in the
2384
+ // capped snapshot, and the agent's own git diff still reads such a file as text.
2385
+ const BIG_FILE_ARGS = ['-c', 'core.bigFileThreshold=1m'];
2311
2386
  // Main only, never forced. On success castle/main is moved without another fetch, so the next
2312
2387
  // sync's comparisons hold.
2313
2388
  function pushMain(ctx, local) {
2314
- const push = run(ctx, PUSH_ARGS, { timeoutMs: NETWORK_TIMEOUT_MS });
2389
+ const push = run(ctx, [...BIG_FILE_ARGS, ...PUSH_ARGS], { timeoutMs: NETWORK_TIMEOUT_MS });
2315
2390
  if (push.status === 0) {
2316
2391
  run(ctx, ['update-ref', REMOTE_MAIN, local]);
2317
2392
  markIntegrated(ctx, local);
@@ -2340,6 +2415,21 @@ function pushOnly(ctx) {
2340
2415
  ctx.deps.warn('The Castle remote has changes this sandbox does not have yet; they are merged once the deck is idle.');
2341
2416
  return { merge: 'deferred', pushed: false };
2342
2417
  }
2418
+ // The child's seed push: never a merge, so a remote that moved meanwhile fails it (and the seed
2419
+ // is undone) rather than have the working tree written under the user.
2420
+ async function seedPushOnly(ctx) {
2421
+ requireMainBranch(ctx);
2422
+ if (mergeWaiting(ctx.dir))
2423
+ throw mergeWaitingError(ctx);
2424
+ await commitLocked(ctx, { reason: 'sync' });
2425
+ const local = revParse(ctx, 'HEAD');
2426
+ if (!local)
2427
+ return { merge: 'none', pushed: false };
2428
+ const push = pushMain(ctx, local);
2429
+ if (push.status !== 0)
2430
+ throw new CloudGitError(describeFailure(PUSH_ARGS, push));
2431
+ return { merge: 'seeded', pushed: true };
2432
+ }
2343
2433
  async function syncLocked(ctx, opts) {
2344
2434
  requireMainBranch(ctx);
2345
2435
  if (mergeWaiting(ctx.dir))
@@ -2828,6 +2918,11 @@ function forgetOtherDecksRemote(ctx, deckId) {
2828
2918
  const other = CASTLE_REMOTE_RE.exec(current)?.[2];
2829
2919
  if (!other || other === deckId)
2830
2920
  return null;
2921
+ // The other deck's snapshot key would let a checkpoint leave out objects this deck's remote
2922
+ // does not have yet (its first push can run in the background). Gone first, before the other
2923
+ // remote is: from here on a checkpoint keeps the objects until this deck has a snapshot of its own.
2924
+ for (const rel of [SNAPSHOT_KEY_FILE, SNAPSHOT_BUNDLE_FILE])
2925
+ fs.rmSync(path.join(ctx.dir, rel), { force: true });
2831
2926
  must(ctx, ['remote', 'remove', GIT_REMOTE_NAME]);
2832
2927
  for (const key of ['castle.cloud', 'castle.seed', 'user.name', 'user.email']) {
2833
2928
  run(ctx, ['config', '--local', '--unset-all', key]);
@@ -2962,13 +3057,33 @@ export async function cloudAttach(dir, remoteUrl, deps) {
2962
3057
  must(ctx, ['config', '--local', 'core.createObject', 'rename']);
2963
3058
  // The base in conflict markers is what lets the agent see what each side changed.
2964
3059
  must(ctx, ['config', '--local', 'merge.conflictStyle', 'diff3']);
3060
+ if (deps.env[BACKGROUND_ATTACH_ENV] === '1')
3061
+ return attachInChild(ctx, repo);
3062
+ if (ctx.deadline === undefined || localConfig(ctx, 'castle.cloud') === 'true')
3063
+ return attachLocked(ctx, repo, 'inline');
3064
+ // An earlier open's child is still pushing: wait on it rather than queue on the deck lock.
3065
+ if ((await waitForAttachChild(ctx)) && localConfig(ctx, 'castle.cloud') === 'true') {
3066
+ return attachLocked(ctx, repo, 'inline');
3067
+ }
3068
+ try {
3069
+ return await attachLocked(ctx, repo, 'seed-elsewhere');
3070
+ }
3071
+ catch (e) {
3072
+ if (!(e instanceof SeedInChild))
3073
+ throw e;
3074
+ }
3075
+ return attachThroughChild(ctx, remoteUrl);
3076
+ }
3077
+ class SeedInChild extends Error {
3078
+ }
3079
+ async function attachLocked(ctx, repo, seedMode) {
2965
3080
  return withDeckLock(ctx, async () => {
2966
3081
  // A cold resume's repo has refs but no objects: the rehydrate runs in the background, and
2967
3082
  // this attach stops at once (castle-www runs it in the background on open).
2968
3083
  requireHistory(ctx, { leave: false });
2969
3084
  try {
2970
3085
  ensureMainBranch(ctx);
2971
- const outcome = await firstSync(ctx, repo);
3086
+ const outcome = await firstSync(ctx, repo, seedMode);
2972
3087
  // Marked attached only once the repo shares history with the remote: a deck whose
2973
3088
  // first fetch failed must not start a local history of its own, which the next attach
2974
3089
  // could not merge. The next open retries the whole attach.
@@ -2982,6 +3097,143 @@ export async function cloudAttach(dir, remoteUrl, deps) {
2982
3097
  }
2983
3098
  });
2984
3099
  }
3100
+ // --- attach: a first seed, in a child of its own ----------------------------------------------
3101
+ //
3102
+ // A first attach onto an empty remote pushes the whole deck, and castle-www's open waits on it:
3103
+ // it is the one attach on an open's critical path. A big deck's push can outlast the open's
3104
+ // budget every time -- the seed is undone each time it is cut short -- so the deck would never
3105
+ // get git, and every open would wait out the budget first. So under a deadline that seed and
3106
+ // push run in a detached child bound by no deadline, and the command waits for it only until its
3107
+ // own deadline: a small deck attaches within the wait exactly as before, a big one finishes in
3108
+ // the background (EXIT_ATTACH_CONTINUING) and the next open finds it attached. Only the seed: a
3109
+ // first attach that takes or merges the remote's version writes the working tree, which must
3110
+ // finish before the deck is served.
3111
+ // Short of the caller's deadline: relaying the child's outcome takes a moment.
3112
+ const ATTACH_WAIT_MARGIN_MS = 1_000;
3113
+ const ATTACH_POLL_MS = 200;
3114
+ const ATTACH_LOG_MAX_BYTES = 256 * 1024;
3115
+ const ATTACH_OUTPUT_MAX_BYTES = 64 * 1024;
3116
+ function attachContinuing(why) {
3117
+ return new CloudGitError(`${why} It carries on in the background (log: ${ATTACH_LOG_FILE}); the deck has git once it finishes.`, EXIT_ATTACH_CONTINUING);
3118
+ }
3119
+ function attachChildRunning(ctx) {
3120
+ try {
3121
+ const seen = inspectLock(path.join(ctx.dir, ATTACH_LOCK_FILE));
3122
+ return seen !== null && !holderIsGone(ctx.deps, seen);
3123
+ }
3124
+ catch {
3125
+ return false;
3126
+ }
3127
+ }
3128
+ function attachWaitUntil(ctx) {
3129
+ return ctx.deadline - ATTACH_WAIT_MARGIN_MS;
3130
+ }
3131
+ function delay(ms) {
3132
+ return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
3133
+ }
3134
+ // False when no child was running; true when one was and has finished. Still running at the
3135
+ // deadline: EXIT_ATTACH_CONTINUING.
3136
+ async function waitForAttachChild(ctx) {
3137
+ if (!attachChildRunning(ctx))
3138
+ return false;
3139
+ while (attachChildRunning(ctx)) {
3140
+ if (ctx.deps.now() >= attachWaitUntil(ctx))
3141
+ throw attachContinuing('An earlier first attach of this deck is still running.');
3142
+ await delay(Math.min(ATTACH_POLL_MS, attachWaitUntil(ctx) - ctx.deps.now()));
3143
+ }
3144
+ return true;
3145
+ }
3146
+ // What a file gained past `offset`, at most the last ATTACH_OUTPUT_MAX_BYTES of it.
3147
+ function readFrom(file, offset) {
3148
+ try {
3149
+ const size = fileSize(file);
3150
+ const start = Math.max(offset, size - ATTACH_OUTPUT_MAX_BYTES);
3151
+ if (size <= start)
3152
+ return '';
3153
+ const fd = fs.openSync(file, 'r');
3154
+ try {
3155
+ const buffer = Buffer.alloc(size - start);
3156
+ const read = fs.readSync(fd, buffer, 0, buffer.length, start);
3157
+ return buffer.subarray(0, read).toString('utf-8');
3158
+ }
3159
+ finally {
3160
+ fs.closeSync(fd);
3161
+ }
3162
+ }
3163
+ catch {
3164
+ return '';
3165
+ }
3166
+ }
3167
+ /** Starts the child for a seed firstSync found to be needed, and waits for it until the deadline. */
3168
+ async function attachThroughChild(ctx, remoteUrl) {
3169
+ const log = path.join(ctx.dir, ATTACH_LOG_FILE);
3170
+ fs.mkdirSync(path.dirname(log), { recursive: true });
3171
+ if (fileSize(log) > ATTACH_LOG_MAX_BYTES)
3172
+ fs.rmSync(log, { force: true });
3173
+ const offset = fileSize(log);
3174
+ const childEnv = { ...ctx.deps.env, [BACKGROUND_ATTACH_ENV]: '1' };
3175
+ delete childEnv[DEADLINE_ENV];
3176
+ const fd = fs.openSync(log, 'a');
3177
+ let child;
3178
+ try {
3179
+ child = spawn(process.execPath, [CLI_ENTRY, 'git', 'attach', ctx.dir, '--remote', remoteUrl], {
3180
+ cwd: ctx.dir,
3181
+ env: childEnv,
3182
+ detached: true,
3183
+ stdio: ['ignore', fd, fd],
3184
+ });
3185
+ }
3186
+ finally {
3187
+ fs.closeSync(fd);
3188
+ }
3189
+ const exited = new Promise((resolve) => {
3190
+ child.on('error', () => resolve('error'));
3191
+ child.on('exit', (code) => resolve(code ?? EXIT_ERROR));
3192
+ });
3193
+ const code = await Promise.race([exited, delay(attachWaitUntil(ctx) - ctx.deps.now()).then(() => 'running')]);
3194
+ if (code === 'running') {
3195
+ child.unref();
3196
+ throw attachContinuing("This deck's first push is taking longer than the open waits.");
3197
+ }
3198
+ if (code === 'error')
3199
+ throw new CloudGitError('Could not start the attach.');
3200
+ const output = readFrom(log, offset);
3201
+ if (code === EXIT_OK)
3202
+ return { output };
3203
+ throw new CloudGitError(output.trim() || `The attach exited ${code}.`, code);
3204
+ }
3205
+ /** The child's side: one at a time, and its outcome to the container's event log. */
3206
+ async function attachInChild(ctx, repo) {
3207
+ const startedAt = ctx.deps.now();
3208
+ const deckId = remoteDeckId(ctx);
3209
+ const emit = (fields) => emitContainerEvent(ctx.deps.env, {
3210
+ event: 'sandbox_git_attach',
3211
+ deck_id: deckId && /^[A-Za-z0-9_-]{1,64}$/.test(deckId) ? deckId : null,
3212
+ ...fields,
3213
+ duration_ms: ctx.deps.now() - startedAt,
3214
+ });
3215
+ let release;
3216
+ try {
3217
+ release = acquireLockFile(path.join(ctx.dir, ATTACH_LOCK_FILE), ctx.deps);
3218
+ }
3219
+ catch (e) {
3220
+ emit({ outcome: 'failed', error: errorText(e).slice(0, 500) });
3221
+ throw e;
3222
+ }
3223
+ try {
3224
+ const outcome = await attachLocked(ctx, repo, 'seed-only');
3225
+ emit({ outcome: 'attached', attach: outcome.outcome });
3226
+ return outcome;
3227
+ }
3228
+ catch (e) {
3229
+ const code = e instanceof CloudGitError ? e.exitCode : EXIT_ERROR;
3230
+ emit({ outcome: code === EXIT_HISTORY_UNAVAILABLE ? 'history_loading' : 'failed', error: errorText(e).slice(0, 500) });
3231
+ throw e;
3232
+ }
3233
+ finally {
3234
+ release();
3235
+ }
3236
+ }
2985
3237
  // The seed commit an attach made for an empty remote, until it is pushed. Should the push
2986
3238
  // fail (or the process die first), the commit is undone so the next attach starts from an
2987
3239
  // unborn main again: it then takes whatever the remote has by then, where keeping the seed
@@ -2999,12 +3251,17 @@ function undoUnpushedSeed(ctx) {
2999
3251
  }
3000
3252
  run(ctx, ['config', '--local', '--unset-all', SEED_KEY]);
3001
3253
  }
3002
- async function firstSync(ctx, repo) {
3254
+ async function firstSync(ctx, repo, seedMode) {
3003
3255
  undoUnpushedSeed(ctx);
3004
3256
  await commitRecoveredRoot(ctx);
3005
3257
  const remote = fetchRemote(ctx);
3006
3258
  const head = revParse(ctx, 'HEAD');
3259
+ if (remote && seedMode === 'seed-only') {
3260
+ throw new CloudGitError('The Castle remote has history now; the next open of the deck takes it.');
3261
+ }
3007
3262
  if (!remote) {
3263
+ if (seedMode === 'seed-elsewhere')
3264
+ throw new SeedInChild();
3008
3265
  if (!head) {
3009
3266
  const seed = await commitLocked(ctx, { reason: 'sync', message: 'Start of history' });
3010
3267
  if (seed.sha)
@@ -3012,7 +3269,7 @@ async function firstSync(ctx, repo) {
3012
3269
  }
3013
3270
  let sync;
3014
3271
  try {
3015
- sync = await syncLocked(ctx, { commitFirst: true, mode: 'full' });
3272
+ sync = seedMode === 'seed-only' ? await seedPushOnly(ctx) : await syncLocked(ctx, { commitFirst: true, mode: 'full' });
3016
3273
  }
3017
3274
  catch (e) {
3018
3275
  undoUnpushedSeed(ctx);
@@ -0,0 +1,49 @@
1
+ /** The most a pack may be, whatever its exporter allows. */
2
+ export declare const CONTENT_PACK_MAX_BYTES: number;
3
+ export interface ContentPack {
4
+ sha256: string;
5
+ bytes: Buffer;
6
+ /** Where it is stored, absolute. */
7
+ file: string;
8
+ /** The import that exported it. */
9
+ alias: string;
10
+ /** The exporter's one-line description, if it gave one. */
11
+ summary: string | null;
12
+ }
13
+ /**
14
+ * Build the deck's content pack, or null when no import exports one. Throws
15
+ * with the exporter's own errors when it refuses: a deck that cannot pack is a
16
+ * deck that does not build.
17
+ */
18
+ export declare function buildContentPack(deckDir: string, log?: (message: string) => void): Promise<ContentPack | null>;
19
+ /** A pack this deck built before, by hash, or null. */
20
+ export declare function readStoredContentPack(deckDir: string, sha256: string): Buffer | null;
21
+ /** JSON with every object's keys sorted and no whitespace. */
22
+ export declare function canonicalJson(value: unknown): string;
23
+ /** The directory of a deck this deck lists in `devDecks`, or null. */
24
+ export declare function devDeckDir(projectDir: string, name: string): string | null;
25
+ /**
26
+ * The castle.json of every deck this deck lists in `devDecks`, by name: what a
27
+ * dev session's server is told about the decks its doors lead to, so a door
28
+ * can read the destination's own settings rather than repeat them. Decks that
29
+ * are missing or unreadable are left out.
30
+ */
31
+ export declare function devDeckCastleJsons(projectDir: string): Record<string, unknown>;
32
+ /** `deck:<name>/<key>` -> the listed deck's directory and its own key, or null. */
33
+ export declare function devDeckSessionKey(projectDir: string, key: string | null): {
34
+ name: string;
35
+ dir: string;
36
+ key: string;
37
+ } | null;
38
+ /**
39
+ * The content-origin endpoints under `/__castle/content-pack/`. GET only; true
40
+ * when the request was one of them (answered), false to fall through.
41
+ */
42
+ export declare function handleContentPackRequest(projectDir: string, req: {
43
+ method?: string;
44
+ url?: string;
45
+ }, res: {
46
+ writeHead(status: number, headers?: Record<string, string>): {
47
+ end(body?: string | Buffer): void;
48
+ };
49
+ }, reqPath: string): Promise<boolean>;