@qvac/sdk 0.23.0 → 0.24.0

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 (239) hide show
  1. package/NOTICE +115 -58
  2. package/README.md +10 -13
  3. package/dist/examples/asr/parakeet-sortformer.js +24 -14
  4. package/dist/examples/asr/parakeet-transcribepsy-filesystem.js +40 -11
  5. package/dist/examples/asr/parakeet-unified-coreml.js +14 -9
  6. package/dist/examples/asr/whispercpp-prompt.js +9 -5
  7. package/dist/examples/assess-model-fit.d.ts +7 -9
  8. package/dist/examples/assess-model-fit.js +22 -43
  9. package/dist/examples/calc-tokens.d.ts +2 -0
  10. package/dist/examples/calc-tokens.js +21 -0
  11. package/dist/examples/classification/classify-image.js +11 -5
  12. package/dist/examples/completion-stop-reason.d.ts +3 -3
  13. package/dist/examples/completion-stop-reason.js +4 -4
  14. package/dist/examples/diffusion-flux3-klein.d.ts +2 -0
  15. package/dist/examples/diffusion-flux3-klein.js +102 -0
  16. package/dist/examples/diffusion-moss-image.d.ts +2 -0
  17. package/dist/examples/diffusion-moss-image.js +126 -0
  18. package/dist/examples/diffusion-qwen-image-21.js +15 -4
  19. package/dist/examples/embed-multimodal.d.ts +2 -0
  20. package/dist/examples/embed-multimodal.js +80 -0
  21. package/dist/examples/embed-p2p.js +2 -2
  22. package/dist/examples/image/megaloc.d.ts +2 -0
  23. package/dist/examples/image/megaloc.js +37 -0
  24. package/dist/examples/llamacpp-multimodal.js +18 -0
  25. package/dist/examples/rag/rag-hyperdb/pipeline.js +2 -2
  26. package/dist/examples/rag/rag-turbovec.js +2 -2
  27. package/dist/examples/sessions.d.ts +17 -0
  28. package/dist/examples/sessions.js +63 -0
  29. package/dist/examples/tools/llamacpp-deferred-tools.js +8 -4
  30. package/dist/scripts/check-resource-collectors-packaging.js +7 -6
  31. package/dist/scripts/contract/build-contract.d.ts +2 -1
  32. package/dist/scripts/contract/build-contract.js +13 -1
  33. package/dist/scripts/contract/constants-registry.d.ts +17 -0
  34. package/dist/scripts/contract/constants-registry.js +8 -2
  35. package/dist/scripts/contract/method-shapes.d.ts +4 -0
  36. package/dist/scripts/contract/method-shapes.js +4 -0
  37. package/dist/scripts/enforce-inference-versions.d.ts +1 -1
  38. package/dist/scripts/enforce-inference-versions.js +28 -18
  39. package/dist/scripts/generate-bare-kit-runtimes.js +101 -69
  40. package/dist/src/client/api/assess-model-fit.d.ts +17 -17
  41. package/dist/src/client/api/assess-model-fit.js +18 -31
  42. package/dist/src/client/api/audio-edit.d.ts +5 -3
  43. package/dist/src/client/api/audio-edit.js +5 -3
  44. package/dist/src/client/api/audio-gen-result.js +134 -45
  45. package/dist/src/client/api/audio-gen.d.ts +40 -3
  46. package/dist/src/client/api/audio-gen.js +40 -3
  47. package/dist/src/client/api/audio-understand.d.ts +2 -2
  48. package/dist/src/client/api/audio-understand.js +2 -2
  49. package/dist/src/client/api/batch-completion.js +2 -1
  50. package/dist/src/client/api/calc-tokens.d.ts +33 -0
  51. package/dist/src/client/api/calc-tokens.js +44 -0
  52. package/dist/src/client/api/cancel.d.ts +2 -2
  53. package/dist/src/client/api/cancel.js +2 -2
  54. package/dist/src/client/api/classify.d.ts +12 -5
  55. package/dist/src/client/api/classify.js +17 -5
  56. package/dist/src/client/api/client-request-id.d.ts +0 -15
  57. package/dist/src/client/api/client-request-id.js +15 -12
  58. package/dist/src/client/api/completion-stream.d.ts +8 -1
  59. package/dist/src/client/api/completion-stream.js +10 -1
  60. package/dist/src/client/api/delete-cache.d.ts +9 -2
  61. package/dist/src/client/api/delete-cache.js +13 -3
  62. package/dist/src/client/api/diffusion.d.ts +20 -4
  63. package/dist/src/client/api/diffusion.js +23 -5
  64. package/dist/src/client/api/embed.d.ts +82 -29
  65. package/dist/src/client/api/embed.js +64 -19
  66. package/dist/src/client/api/get-model-info.d.ts +2 -2
  67. package/dist/src/client/api/get-model-info.js +2 -2
  68. package/dist/src/client/api/get-system-resources.d.ts +2 -2
  69. package/dist/src/client/api/get-system-resources.js +2 -2
  70. package/dist/src/client/api/heartbeat.d.ts +3 -2
  71. package/dist/src/client/api/heartbeat.js +3 -2
  72. package/dist/src/client/api/index.d.ts +4 -3
  73. package/dist/src/client/api/index.js +2 -1
  74. package/dist/src/client/api/invoke-plugin.d.ts +8 -2
  75. package/dist/src/client/api/invoke-plugin.js +17 -2
  76. package/dist/src/client/api/load-model.js +5 -2
  77. package/dist/src/client/api/ocr.d.ts +5 -3
  78. package/dist/src/client/api/ocr.js +44 -21
  79. package/dist/src/client/api/rag.d.ts +1 -1
  80. package/dist/src/client/api/rag.js +1 -1
  81. package/dist/src/client/api/registry.d.ts +17 -7
  82. package/dist/src/client/api/registry.js +37 -12
  83. package/dist/src/client/api/resume.d.ts +2 -1
  84. package/dist/src/client/api/resume.js +2 -2
  85. package/dist/src/client/api/rpc-server.d.ts +4 -4
  86. package/dist/src/client/api/rpc-server.js +10 -10
  87. package/dist/src/client/api/state.d.ts +2 -2
  88. package/dist/src/client/api/state.js +2 -2
  89. package/dist/src/client/api/subscribe-logs.d.ts +2 -2
  90. package/dist/src/client/api/subscribe-logs.js +2 -2
  91. package/dist/src/client/api/suspend.d.ts +4 -2
  92. package/dist/src/client/api/suspend.js +4 -3
  93. package/dist/src/client/api/text-to-speech.d.ts +14 -5
  94. package/dist/src/client/api/text-to-speech.js +83 -29
  95. package/dist/src/client/api/transcribe.d.ts +6 -2
  96. package/dist/src/client/api/transcribe.js +7 -1
  97. package/dist/src/client/api/unload-model.d.ts +19 -7
  98. package/dist/src/client/api/unload-model.js +29 -11
  99. package/dist/src/client/api/upscale.d.ts +6 -3
  100. package/dist/src/client/api/upscale.js +9 -4
  101. package/dist/src/client/api/vector-index.d.ts +50 -16
  102. package/dist/src/client/api/vector-index.js +100 -48
  103. package/dist/src/client/api/video-request.d.ts +5 -5
  104. package/dist/src/client/api/video.d.ts +3 -2
  105. package/dist/src/client/api/video.js +3 -2
  106. package/dist/src/client/api/vla.d.ts +9 -5
  107. package/dist/src/client/api/vla.js +17 -8
  108. package/dist/src/client/api/world.d.ts +5 -5
  109. package/dist/src/client/api/world.js +4 -4
  110. package/dist/src/client/init-hooks.d.ts +6 -4
  111. package/dist/src/client/init-hooks.js +12 -15
  112. package/dist/src/client/logging-stream-registry.d.ts +6 -3
  113. package/dist/src/client/logging-stream-registry.js +31 -12
  114. package/dist/src/client/rpc/bundle-stamp.d.ts +29 -0
  115. package/dist/src/client/rpc/bundle-stamp.js +75 -0
  116. package/dist/src/client/rpc/expo-home-dir.d.ts +2 -0
  117. package/dist/src/client/rpc/expo-home-dir.js +4 -0
  118. package/dist/src/client/rpc/expo-rpc-client.js +189 -135
  119. package/dist/src/client/rpc/node-rpc-client.js +322 -413
  120. package/dist/src/client/rpc/pear-runtime.d.ts +12 -0
  121. package/dist/src/client/rpc/pear-runtime.js +12 -0
  122. package/dist/src/client/rpc/rpc-client.d.ts +5 -4
  123. package/dist/src/client/rpc/rpc-client.js +126 -23
  124. package/dist/src/client/rpc/rpc-error.js +21 -2
  125. package/dist/src/client/rpc/unbundled-harness.d.ts +16 -0
  126. package/dist/src/client/rpc/unbundled-harness.js +27 -0
  127. package/dist/src/client/rpc/worker-failure.d.ts +27 -0
  128. package/dist/src/client/rpc/worker-failure.js +61 -0
  129. package/dist/src/client/session-registry.d.ts +75 -0
  130. package/dist/src/client/session-registry.js +149 -0
  131. package/dist/src/client/session.d.ts +125 -0
  132. package/dist/src/client/session.js +148 -0
  133. package/dist/src/commands/bundle/addons.d.ts +14 -0
  134. package/dist/src/commands/bundle/addons.js +65 -0
  135. package/dist/src/commands/bundle/constants.js +1 -0
  136. package/dist/src/commands/bundle/entry-gen.d.ts +1 -5
  137. package/dist/src/commands/bundle/entry-gen.js +17 -50
  138. package/dist/src/commands/bundle/index.d.ts +59 -13
  139. package/dist/src/commands/bundle/index.js +345 -121
  140. package/dist/src/commands/bundle/link.d.ts +58 -0
  141. package/dist/src/commands/bundle/link.js +135 -0
  142. package/dist/src/commands/bundle/node-support.d.ts +13 -0
  143. package/dist/src/commands/bundle/node-support.js +23 -0
  144. package/dist/src/commands/bundle/read-bundle.d.ts +9 -0
  145. package/dist/src/commands/bundle/read-bundle.js +27 -0
  146. package/dist/src/commands/bundle/resolve-sdk-import.d.ts +6 -0
  147. package/dist/src/commands/bundle/resolve-sdk-import.js +24 -28
  148. package/dist/src/commands/bundle/scratch.d.ts +35 -0
  149. package/dist/src/commands/bundle/scratch.js +178 -0
  150. package/dist/src/commands/bundle/targets.d.ts +14 -0
  151. package/dist/src/commands/bundle/targets.js +37 -0
  152. package/dist/src/commands/host-prebuilds/index.d.ts +5 -4
  153. package/dist/src/commands/host-prebuilds/index.js +9 -7
  154. package/dist/src/commands/index.d.ts +4 -3
  155. package/dist/src/commands/verify/abi.d.ts +20 -14
  156. package/dist/src/commands/verify/abi.js +11 -79
  157. package/dist/src/commands/verify/bare-kit-runtime.d.ts +20 -22
  158. package/dist/src/commands/verify/bare-kit-runtime.js +102 -150
  159. package/dist/src/commands/verify/bare-kit-runtimes.d.ts +10 -9
  160. package/dist/src/commands/verify/bare-kit-runtimes.js +21 -21
  161. package/dist/src/commands/verify/bundle-source.js +25 -21
  162. package/dist/src/commands/verify/engines-advice.d.ts +2 -8
  163. package/dist/src/commands/verify/engines-advice.js +7 -54
  164. package/dist/src/commands/verify/index.d.ts +30 -29
  165. package/dist/src/commands/verify/index.js +92 -200
  166. package/dist/src/commands/verify/prebuilds.d.ts +3 -5
  167. package/dist/src/commands/verify/prebuilds.js +1 -2
  168. package/dist/src/commands/verify/resource-collectors.d.ts +0 -6
  169. package/dist/src/commands/verify/resource-collectors.js +1 -50
  170. package/dist/src/commands/verify/sidecar-runtime.d.ts +6 -0
  171. package/dist/src/commands/verify/sidecar-runtime.js +51 -0
  172. package/dist/src/expo/plugins/withBareKit.d.ts +59 -0
  173. package/dist/src/expo/plugins/withBareKit.js +204 -0
  174. package/dist/src/expo/plugins/withMobileBundle.d.ts +4 -11
  175. package/dist/src/expo/plugins/withMobileBundle.js +36 -57
  176. package/dist/src/expo/plugins/withQvacSDK.d.ts +1 -0
  177. package/dist/src/expo/plugins/withQvacSDK.js +3 -0
  178. package/dist/src/index.d.ts +6 -5
  179. package/dist/src/index.js +10 -14
  180. package/dist/src/logging/utils.js +10 -2
  181. package/dist/src/plugin-ids.d.ts +2 -1
  182. package/dist/src/plugin-ids.js +2 -0
  183. package/dist/src/schemas/public.d.ts +1 -1
  184. package/dist/src/schemas/public.js +1 -1
  185. package/dist/src/schemas/sdk-errors-client.d.ts +5 -6
  186. package/dist/src/schemas/sdk-errors-client.js +30 -36
  187. package/dist/src/schemas/sdk-errors-server.d.ts +11 -1
  188. package/dist/src/schemas/sdk-errors-server.js +60 -2
  189. package/dist/src/server/rpc/rpc-utils.d.ts +25 -4
  190. package/dist/src/server/rpc/rpc-utils.js +39 -5
  191. package/dist/src/utils/errors-client.d.ts +37 -29
  192. package/dist/src/utils/errors-client.js +50 -41
  193. package/dist/src/utils/errors-server.d.ts +59 -1
  194. package/dist/src/utils/errors-server.js +110 -1
  195. package/dist/src/utils/withTimeout.js +34 -17
  196. package/dist/src/worker/handle-request.js +25 -22
  197. package/dist/src/worker/handler-utils.d.ts +2 -6
  198. package/dist/src/worker/handler-utils.js +2 -20
  199. package/dist/src/worker/index.d.ts +2 -4
  200. package/dist/src/worker/index.js +23 -35
  201. package/dist/src/worker/plugins/ggml-image-embedding.d.ts +2 -0
  202. package/dist/src/worker/plugins/ggml-image-embedding.js +1 -0
  203. package/dist/src/worker/shim.d.ts +4 -0
  204. package/dist/src/worker/shim.js +7 -0
  205. package/dist/src/worker/start.d.ts +9 -0
  206. package/dist/src/worker/start.js +16 -0
  207. package/dist/src/worker/unbundled-shim.d.ts +2 -0
  208. package/dist/src/worker/unbundled-shim.js +4 -0
  209. package/docs/system-resources-support-matrix.md +27 -19
  210. package/package.json +62 -51
  211. package/src/electron-forge/index.cjs +65 -91
  212. package/dist/examples/model-fit-ui/server.d.ts +0 -24
  213. package/dist/examples/model-fit-ui/server.js +0 -221
  214. package/dist/src/client/rpc/ensure-worker-ready.d.ts +0 -9
  215. package/dist/src/client/rpc/ensure-worker-ready.js +0 -17
  216. package/dist/src/client/rpc/init-timeout.d.ts +0 -26
  217. package/dist/src/client/rpc/init-timeout.js +0 -25
  218. package/dist/src/client/rpc/ipc-socket-path.d.ts +0 -11
  219. package/dist/src/client/rpc/ipc-socket-path.js +0 -30
  220. package/dist/src/client/rpc/worker-startup-error.d.ts +0 -12
  221. package/dist/src/client/rpc/worker-startup-error.js +0 -13
  222. package/dist/src/commands/bundle/bare-pack.d.ts +0 -21
  223. package/dist/src/commands/bundle/bare-pack.js +0 -77
  224. package/dist/src/commands/bundle/manifest.d.ts +0 -25
  225. package/dist/src/commands/bundle/manifest.js +0 -192
  226. package/dist/src/expo/plugins/link-addons.d.ts +0 -18
  227. package/dist/src/expo/plugins/link-addons.js +0 -65
  228. package/dist/src/pear/pre.d.ts +0 -21
  229. package/dist/src/pear/pre.js +0 -450
  230. package/dist/src/server/env.d.ts +0 -22
  231. package/dist/src/server/env.js +0 -59
  232. package/dist/src/server/utils/qvac-paths.d.ts +0 -2
  233. package/dist/src/server/utils/qvac-paths.js +0 -5
  234. package/dist/src/server/utils/worker-lock.d.ts +0 -3
  235. package/dist/src/server/utils/worker-lock.js +0 -67
  236. package/dist/src/worker/create-server.d.ts +0 -8
  237. package/dist/src/worker/create-server.js +0 -51
  238. package/dist/src/worker/lifecycle.d.ts +0 -23
  239. package/dist/src/worker/lifecycle.js +0 -149
@@ -1,16 +1,33 @@
1
1
  import { getClientLogger } from '../logging/index.js';
2
2
  import { loggingStream } from './api/logging-stream.js';
3
+ import { bindSession, sessionOf } from './session-registry.js';
3
4
  const logger = getClientLogger();
5
+ // One stream per caller and model: a session's logger opens its stream as
6
+ // that session, so the worker ends it when the session closes, and another
7
+ // caller sharing the model keeps its own logger.
4
8
  const activeStreams = new Map();
5
- export function startLoggingStreamForModel(modelId, modelLogger) {
6
- if (activeStreams.has(modelId)) {
9
+ function streamKey(modelId, options) {
10
+ return `${options?.sessionId ?? ''}\u0000${modelId}`;
11
+ }
12
+ export function startLoggingStreamForModel(modelId, modelLogger, options, openStream = loggingStream) {
13
+ const key = streamKey(modelId, options);
14
+ if (activeStreams.has(key)) {
7
15
  logger.warn(`Logging stream already active for model ${modelId}`);
8
16
  return;
9
17
  }
10
18
  const controller = new AbortController();
11
- const streamIterator = loggingStream({ id: modelId }, { signal: controller.signal });
19
+ // Only the caller's identity carries over from the load: its timeout and
20
+ // profiling options do not apply to a stream that lives as long as the model.
21
+ const streamOptions = { signal: controller.signal };
22
+ if (options?.sessionId !== undefined) {
23
+ streamOptions.sessionId = options.sessionId;
24
+ const record = sessionOf(options);
25
+ if (record)
26
+ bindSession(streamOptions, record);
27
+ }
28
+ const streamIterator = openStream({ id: modelId }, streamOptions);
12
29
  const entry = { logger: modelLogger, controller };
13
- activeStreams.set(modelId, entry);
30
+ activeStreams.set(key, entry);
14
31
  try {
15
32
  void (async () => {
16
33
  try {
@@ -39,26 +56,28 @@ export function startLoggingStreamForModel(modelId, modelLogger) {
39
56
  }
40
57
  finally {
41
58
  // A reload may have replaced this entry.
42
- if (activeStreams.get(modelId) === entry)
43
- activeStreams.delete(modelId);
59
+ if (activeStreams.get(key) === entry)
60
+ activeStreams.delete(key);
44
61
  }
45
62
  })();
46
63
  }
47
64
  catch (error) {
48
65
  logger.error(`Failed to start logging stream for model ${modelId}:`, error);
49
- activeStreams.delete(modelId);
66
+ activeStreams.delete(key);
50
67
  throw error;
51
68
  }
52
69
  }
53
- export function stopLoggingStreamForModel(modelId) {
54
- const stream = activeStreams.get(modelId);
70
+ /** Stops the logging stream the caller behind `options` opened for the model. */
71
+ export function stopLoggingStreamForModel(modelId, options) {
72
+ const key = streamKey(modelId, options);
73
+ const stream = activeStreams.get(key);
55
74
  if (stream) {
56
- activeStreams.delete(modelId);
75
+ activeStreams.delete(key);
57
76
  // `return()` would wait for a log an unloaded model never sends.
58
77
  stream.controller.abort();
59
78
  logger.debug(`Stopped logging stream for model ${modelId}`);
60
79
  }
61
80
  }
62
- export function hasActiveStreamForModel(modelId) {
63
- return activeStreams.has(modelId);
81
+ export function hasActiveStreamForModel(modelId, options) {
82
+ return activeStreams.has(streamKey(modelId, options));
64
83
  }
@@ -0,0 +1,29 @@
1
+ /** The field `bundleSdk` sets in a bundled worker's package.json to the `@qvac/sdk` version that bundled it. */
2
+ export declare const BUNDLED_SDK_VERSION_FIELD = "qvacSdkVersion";
3
+ /** The field `bundleSdk` sets in a bundled worker's package.json to the target it bundled for. */
4
+ export declare const BUNDLED_TARGET_FIELD = "qvacTarget";
5
+ /**
6
+ * The file `bundleSdk` writes at the root of a Kotlin or Python harness, which
7
+ * has no package.json, with the same fields as a JavaScript harness stamp.
8
+ */
9
+ export declare const BUNDLE_RECORD_FILE = "qvac-bundle.json";
10
+ /**
11
+ * The version of the `@qvac/sdk` package above `from`, which for this module
12
+ * is the SDK's own. Undefined when the SDK was bundled into the app.
13
+ */
14
+ export declare function installedSdkVersion(from?: string): string | undefined;
15
+ /**
16
+ * A warning when the bundled worker in `dir` was bundled by another
17
+ * `@qvac/sdk` than `installed`, or null when the versions match or the bundle
18
+ * cannot be read.
19
+ */
20
+ export declare function bundledSdkMismatch(dir: string, installed: string): string | null;
21
+ /** The target the worker in `dir` was bundled for, or undefined when it does not say. */
22
+ export declare function bundledTarget(dir: string): string | undefined;
23
+ /**
24
+ * The target the bundle at `bundlePath` was bundled for. A Kotlin or Python
25
+ * harness keeps its bundle in a subfolder, so the nearest folder above it with
26
+ * a record or a package.json says; undefined when that folder does not record it.
27
+ */
28
+ export declare function bundleTargetOf(bundlePath: string): string | undefined;
29
+ //# sourceMappingURL=bundle-stamp.d.ts.map
@@ -0,0 +1,75 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { fileURLToPath } from 'node:url';
4
+ /** The field `bundleSdk` sets in a bundled worker's package.json to the `@qvac/sdk` version that bundled it. */
5
+ export const BUNDLED_SDK_VERSION_FIELD = 'qvacSdkVersion';
6
+ /** The field `bundleSdk` sets in a bundled worker's package.json to the target it bundled for. */
7
+ export const BUNDLED_TARGET_FIELD = 'qvacTarget';
8
+ /**
9
+ * The file `bundleSdk` writes at the root of a Kotlin or Python harness, which
10
+ * has no package.json, with the same fields as a JavaScript harness stamp.
11
+ */
12
+ export const BUNDLE_RECORD_FILE = 'qvac-bundle.json';
13
+ const SDK_NAME = '@qvac/sdk';
14
+ function readJson(file) {
15
+ try {
16
+ return JSON.parse(fs.readFileSync(file, 'utf8'));
17
+ }
18
+ catch {
19
+ return null;
20
+ }
21
+ }
22
+ function readManifest(dir) {
23
+ return readJson(path.join(dir, 'package.json'));
24
+ }
25
+ /**
26
+ * The version of the `@qvac/sdk` package above `from`, which for this module
27
+ * is the SDK's own. Undefined when the SDK was bundled into the app.
28
+ */
29
+ export function installedSdkVersion(from = path.dirname(fileURLToPath(import.meta.url))) {
30
+ for (let dir = from;; dir = path.dirname(dir)) {
31
+ const manifest = fs.existsSync(path.join(dir, 'package.json')) ? readManifest(dir) : null;
32
+ if (manifest?.['name'] === SDK_NAME) {
33
+ return typeof manifest['version'] === 'string' ? manifest['version'] : undefined;
34
+ }
35
+ if (path.dirname(dir) === dir)
36
+ return undefined;
37
+ }
38
+ }
39
+ /**
40
+ * A warning when the bundled worker in `dir` was bundled by another
41
+ * `@qvac/sdk` than `installed`, or null when the versions match or the bundle
42
+ * cannot be read.
43
+ */
44
+ export function bundledSdkMismatch(dir, installed) {
45
+ const manifest = readManifest(dir);
46
+ if (manifest === null)
47
+ return null;
48
+ const bundled = manifest[BUNDLED_SDK_VERSION_FIELD];
49
+ if (bundled === installed)
50
+ return null;
51
+ const bundledBy = typeof bundled === 'string' ? `@qvac/sdk ${bundled}` : 'an older @qvac/sdk';
52
+ return (`The worker in ${dir} was bundled by ${bundledBy}, but @qvac/sdk ${installed} is installed. ` +
53
+ 'Run `qvac bundle sdk` again so the worker matches the SDK.');
54
+ }
55
+ /** The target the worker in `dir` was bundled for, or undefined when it does not say. */
56
+ export function bundledTarget(dir) {
57
+ const target = readManifest(dir)?.[BUNDLED_TARGET_FIELD];
58
+ return typeof target === 'string' ? target : undefined;
59
+ }
60
+ /**
61
+ * The target the bundle at `bundlePath` was bundled for. A Kotlin or Python
62
+ * harness keeps its bundle in a subfolder, so the nearest folder above it with
63
+ * a record or a package.json says; undefined when that folder does not record it.
64
+ */
65
+ export function bundleTargetOf(bundlePath) {
66
+ for (let dir = path.dirname(bundlePath);; dir = path.dirname(dir)) {
67
+ const record = readJson(path.join(dir, BUNDLE_RECORD_FILE));
68
+ if (record !== null || fs.existsSync(path.join(dir, 'package.json'))) {
69
+ const target = (record ?? readManifest(dir))?.[BUNDLED_TARGET_FIELD];
70
+ return typeof target === 'string' ? target : undefined;
71
+ }
72
+ if (path.dirname(dir) === dir)
73
+ return undefined;
74
+ }
75
+ }
@@ -0,0 +1,2 @@
1
+ export declare function getHomeDir(): Promise<string>;
2
+ //# sourceMappingURL=expo-home-dir.d.ts.map
@@ -0,0 +1,4 @@
1
+ export async function getHomeDir() {
2
+ const { Paths } = await import('expo-file-system');
3
+ return Paths.document.uri.replace('file://', '');
4
+ }
@@ -1,19 +1,26 @@
1
1
  import RPC from 'bare-rpc';
2
- import { RPCConnectionFailedError } from '../../utils/errors-client.js';
2
+ import { RPCConnectionFailedError, WorkerCrashedError, WorkerShutdownError, WorkerStartupError } from '../../utils/errors-client.js';
3
3
  import { initializeConfig } from '../../client/init-hooks.js';
4
+ import { DEFAULT_WORKER_START_TIMEOUT_MS, rejectOnAbort, startDeadline, WORKER_SHUTDOWN_GRACE_MS, workerCrashed, workerStartupFailed } from '../../client/rpc/worker-failure.js';
4
5
  import { resolveConfig } from '../../client/config-loader/resolve-config.expo.js';
5
6
  import { getClientLogger } from '../../logging/index.js';
6
7
  import { getDeviceInfo } from '../../client/rpc/expo-device-info.js';
8
+ import { getHomeDir } from '../../client/rpc/expo-home-dir.js';
7
9
  const logger = getClientLogger();
8
10
  let rpcInstance = null;
9
11
  let rpcPromise = null;
10
- let workletInstance = null;
11
- let workletInitialized = false;
12
+ let workerIpc = null;
13
+ let workerLifeController = null;
14
+ let closePromise = null;
15
+ // Bumped by close(); a start that finishes under an older generation stops its
16
+ // own worker, so a caller waiting on that start never receives a closed client.
17
+ let generation = 0;
18
+ // The worklet runs in the app's process. One that ends without reporting its
19
+ // exit was killed or died before its stop() ran, so the addons still hold
20
+ // handles into its isolate, which crash the next worklet on first use.
21
+ let uncleanStop = false;
22
+ const exitReported = new WeakSet();
12
23
  let cachedRuntimeContext;
13
- // Set while close() is in flight. Concurrent callers share the same
14
- // promise instead of double-sending __shutdown__ or re-entering the
15
- // terminate block on already-null state.
16
- let closingPromise = null;
17
24
  logger.debug('EXPO RPC Client bundle');
18
25
  async function getRuntimeContext() {
19
26
  if (cachedRuntimeContext) {
@@ -28,167 +35,214 @@ async function getRuntimeContext() {
28
35
  };
29
36
  return cachedRuntimeContext;
30
37
  }
31
- // No child-process exit on Expo (Worklet lifecycle) — `#rpc` interface stub.
38
+ function loadHarness() {
39
+ try {
40
+ return require('@qvac/sdk/worker.mobile').default;
41
+ }
42
+ catch (error) {
43
+ const message = 'Failed to load the mobile worker. Make sure the QVAC Expo plugin is configured. ' +
44
+ `Add '@qvac/sdk/expo-plugin' to your app.json plugins array. ` +
45
+ `Error: ${String(error)}`;
46
+ logger.error(message);
47
+ throw new RPCConnectionFailedError(message, error);
48
+ }
49
+ }
50
+ /**
51
+ * The config file, read before the worker starts because it sets the startup
52
+ * timeout. A config that fails to load is reported by `initializeConfig`,
53
+ * which reads it again.
54
+ */
55
+ async function readConfigBeforeStart() {
56
+ try {
57
+ return { config: await resolveConfig() };
58
+ }
59
+ catch (error) {
60
+ logger.debug('Reading the config for the worker startup timeout failed; using the default', {
61
+ error
62
+ });
63
+ return null;
64
+ }
65
+ }
66
+ /** bare-stow-host codes for a worker that ended before ready without reporting its exit. */
67
+ const UNREPORTED_EXIT_CODES = new Set([
68
+ 'WORKER_TIMEOUT',
69
+ 'WORKER_CLOSED',
70
+ 'WORKER_KILLED',
71
+ 'TRANSPORT_ERROR'
72
+ ]);
73
+ async function startWorker(timeout) {
74
+ const harness = loadHarness();
75
+ try {
76
+ return (await harness.start({ timeout, grace: WORKER_SHUTDOWN_GRACE_MS })).ipc;
77
+ }
78
+ catch (error) {
79
+ // A start that fails hands back no IPC to watch, so its error code is the
80
+ // only sign of whether the worklet reported its exit.
81
+ if (UNREPORTED_EXIT_CODES.has(error?.code ?? '')) {
82
+ uncleanStop = true;
83
+ }
84
+ throw workerStartupFailed(error);
85
+ }
86
+ }
32
87
  export function getWorkerLifeSignal() {
33
- return null;
88
+ return workerLifeController?.signal ?? null;
34
89
  }
35
- // No life signal on Expo, so the RPC layer never calls this — `#rpc` interface stub.
36
- export function notifyChannelClosed() { }
37
- export async function getRPC() {
38
- if (rpcInstance) {
90
+ function dropWorker(reason) {
91
+ const ipc = workerIpc;
92
+ const controller = workerLifeController;
93
+ workerIpc = null;
94
+ workerLifeController = null;
95
+ rpcInstance = null;
96
+ controller?.abort(reason);
97
+ return ipc;
98
+ }
99
+ /** Stops `ipc` in the background; a start that follows waits for it. */
100
+ function stopInBackground(ipc) {
101
+ const stopping = ipc
102
+ .terminate()
103
+ .then(() => { }, () => { })
104
+ .finally(() => {
105
+ if (closePromise === stopping)
106
+ closePromise = null;
107
+ });
108
+ closePromise = stopping;
109
+ }
110
+ export function notifyChannelClosed() {
111
+ if (!workerLifeController || workerLifeController.signal.aborted)
112
+ return;
113
+ const closed = dropWorker(new WorkerCrashedError(null, null));
114
+ if (closed)
115
+ stopInBackground(closed);
116
+ }
117
+ async function ensureRPC() {
118
+ if (rpcInstance)
39
119
  return rpcInstance;
40
- }
41
- if (rpcPromise) {
120
+ if (rpcPromise)
42
121
  return rpcPromise;
122
+ if (closePromise) {
123
+ await closePromise;
124
+ return ensureRPC();
43
125
  }
44
- rpcPromise = (async () => {
45
- if (workletInstance) {
46
- logger.debug('🔄 Reusing existing worklet');
47
- rpcInstance = new RPC(workletInstance.IPC, () => { });
48
- // Only initialize once per worklet - server state persists
49
- if (!workletInitialized) {
50
- const runtimeContext = await getRuntimeContext();
51
- await initializeConfig(rpcInstance, resolveConfig, runtimeContext);
52
- workletInitialized = true;
53
- }
54
- return rpcInstance;
55
- }
56
- const { Paths } = await import('expo-file-system');
57
- const bareKitModule = await import('react-native-bare-kit');
58
- const worklet = new bareKitModule.Worklet();
59
- workletInstance = worklet;
60
- logger.debug('Starting new worklet');
61
- // Load the mobile bundle - generated by expo plugin during prebuild
62
- // The expo plugin handles bundle selection:
63
- // 1. Uses qvac/worker.bundle.js if exists (user pre-generated)
64
- // 2. Generates tree-shaken bundle if qvac.config.* exists
65
- // 3. Generates default bundle (all plugins) otherwise
66
- let mobileBundle;
67
- try {
68
- mobileBundle = require('@qvac/sdk/worker.mobile.bundle');
69
- }
70
- catch (error) {
71
- const message = 'Failed to load mobile worker bundle. Make sure the QVAC Expo plugin is configured. ' +
72
- `Add '@qvac/sdk/expo-plugin' to your app.json plugins array. ` +
73
- `Error: ${String(error)}`;
74
- logger.error(message);
75
- throw new RPCConnectionFailedError(message, error instanceof Error ? error : undefined);
126
+ if (uncleanStop) {
127
+ throw new WorkerStartupError('A QVAC worker in this app stopped before its cleanup finished; restart the app to start a new one', { exitCode: null, exitSignal: null, timedOut: false });
128
+ }
129
+ const startGeneration = generation;
130
+ const attempt = (async () => {
131
+ const preloaded = await readConfigBeforeStart();
132
+ if (startGeneration !== generation)
133
+ throw new WorkerShutdownError();
134
+ const timeout = preloaded?.config?.rpcInitTimeoutMs ?? DEFAULT_WORKER_START_TIMEOUT_MS;
135
+ const launchedAt = Date.now();
136
+ const ipc = await startWorker(timeout).catch((error) => {
137
+ if (startGeneration !== generation)
138
+ throw new WorkerShutdownError(error);
139
+ throw error;
140
+ });
141
+ let workerError;
142
+ let exitCode;
143
+ ipc.on('error', (error) => {
144
+ workerError = error;
145
+ });
146
+ ipc.on('exit', (code) => {
147
+ exitCode = code;
148
+ exitReported.add(ipc);
149
+ });
150
+ ipc.once('close', () => {
151
+ if (!exitReported.has(ipc))
152
+ uncleanStop = true;
153
+ });
154
+ const crashed = () => workerCrashed(workerError ?? { exitCode });
155
+ if (startGeneration !== generation) {
156
+ await ipc.terminate();
157
+ throw new WorkerShutdownError();
76
158
  }
77
- worklet.start('worker.bundle', mobileBundle, [
78
- // Normalize arg number across platforms
79
- 'react-native-bare-kit',
80
- 'worker.js',
81
- JSON.stringify({
82
- HOME_DIR: Paths.document.uri.replace('file://', '')
83
- })
84
- ]);
159
+ const controller = new AbortController();
160
+ workerIpc = ipc;
161
+ workerLifeController = controller;
85
162
  logger.info('Worklet started');
86
- rpcInstance = new RPC(worklet.IPC, () => {
87
- // Use this for async callbacks
163
+ ipc.once('close', () => {
164
+ if (workerIpc !== ipc)
165
+ return;
166
+ logger.info('🪦 Bare worklet closed unexpectedly');
167
+ dropWorker(crashed());
88
168
  });
169
+ const rpc = new RPC(ipc, () => { });
89
170
  const runtimeContext = await getRuntimeContext();
90
- await initializeConfig(rpcInstance, resolveConfig, runtimeContext);
91
- workletInitialized = true;
92
- return rpcInstance;
171
+ const homeDir = await getHomeDir();
172
+ const deadline = startDeadline(timeout - (Date.now() - launchedAt));
173
+ try {
174
+ await Promise.race([
175
+ initializeConfig(rpc, preloaded ? async () => preloaded.config : resolveConfig, runtimeContext, homeDir),
176
+ rejectOnAbort(controller.signal),
177
+ deadline.expired
178
+ ]);
179
+ }
180
+ finally {
181
+ deadline.clear();
182
+ }
183
+ if (startGeneration !== generation)
184
+ throw new WorkerShutdownError();
185
+ if (workerIpc !== ipc)
186
+ throw crashed();
187
+ rpcInstance = rpc;
188
+ return rpc;
93
189
  })();
190
+ rpcPromise = attempt;
94
191
  try {
95
- return await rpcPromise;
192
+ return await attempt;
96
193
  }
97
194
  catch (error) {
98
195
  logger.error(`Failed to initialize RPC: ${String(error)}`);
196
+ if (startGeneration === generation) {
197
+ const failed = dropWorker(error instanceof Error ? error : new WorkerCrashedError(null, null, error));
198
+ if (failed)
199
+ stopInBackground(failed);
200
+ }
99
201
  throw error;
100
202
  }
101
203
  finally {
102
- rpcPromise = null;
204
+ if (rpcPromise === attempt)
205
+ rpcPromise = null;
103
206
  }
104
207
  }
105
- const SHUTDOWN_RPC_TIMEOUT_MS = 10_000;
106
- /**
107
- * Pre-terminate cleanup roundtrip. Sends an internal `__shutdown__` message
108
- * to the worker so it can clear addon plugin registries (calls each addon's
109
- * `releaseLogger` → frees env-bound js_ref_t state) and unload all model
110
- * instances BEFORE we kill the worklet.
111
- *
112
- * Without this, the worklet's V8 isolate dies while addon static state still
113
- * holds js_ref_t handles into it; the next worklet's first `setLogger` call
114
- * trips a V8 GlobalHandle assertion (brk 0 / SIGTRAP) and the iOS app dies.
115
- *
116
- * Best-effort: never throws. Falls through to terminate even on timeout.
117
- */
118
- async function sendShutdownMessage(rpc) {
119
- let timer;
120
- try {
121
- await Promise.race([
122
- (async () => {
123
- const req = rpc.request(1);
124
- req.send(JSON.stringify({ type: '__shutdown__' }), 'utf8');
125
- const response = await req.reply('utf8');
126
- const parsed = JSON.parse(String(response));
127
- if (!parsed.success) {
128
- throw new Error(parsed.error ?? 'Worker reported cleanup failure');
129
- }
130
- })(),
131
- new Promise((_, reject) => {
132
- timer = setTimeout(() => reject(new Error(`Worker did not ack __shutdown__ within ${SHUTDOWN_RPC_TIMEOUT_MS}ms`)), SHUTDOWN_RPC_TIMEOUT_MS);
133
- })
134
- ]);
135
- }
136
- catch (error) {
137
- // Best-effort: log but don't block termination if cleanup fails.
138
- logger.warn(`⚠️ Pre-terminate worker cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
139
- }
140
- finally {
141
- if (timer)
142
- clearTimeout(timer);
143
- }
208
+ export async function getRPC() {
209
+ return ensureRPC();
144
210
  }
145
211
  export async function close() {
146
- // Concurrent callers (or a getRPC retry that overlaps with a manual
147
- // close) share the in-flight close promise instead of each sending
148
- // their own __shutdown__ and racing on the terminate block.
149
- if (closingPromise)
150
- return closingPromise;
151
- closingPromise = (async () => {
152
- logger.info('🧹 Closing RPC client (Expo)');
153
- // The inference addons self-pin (RTLD_NODELETE, qvac-lib-inference-addon-cpp
154
- // >= 1.2.2), so dlclose() during terminate() no longer unmaps addon code
155
- // with dangling pthread_key_t destructors. terminate() is therefore safe on
156
- // every platform (previously it was skipped on non-iOS to avoid a SIGSEGV in
157
- // pthread_key_clean_all), so we always run the full pre-terminate cleanup +
158
- // terminate path.
159
- if (rpcInstance) {
160
- logger.info('🧹 Requesting worker pre-terminate cleanup');
161
- await sendShutdownMessage(rpcInstance);
162
- }
163
- rpcInstance = null;
212
+ if (closePromise)
213
+ return closePromise;
214
+ generation++;
215
+ closePromise = (async () => {
216
+ const pending = rpcPromise;
164
217
  rpcPromise = null;
165
- if (workletInstance) {
166
- logger.info('🐻🔫 Terminating bare worklet');
167
- try {
168
- workletInstance.terminate();
169
- }
170
- catch (error) {
171
- logger.debug('Failed to terminate worklet', { error });
172
- }
173
- workletInstance = null;
174
- workletInitialized = false;
218
+ const ipc = dropWorker(new WorkerShutdownError());
219
+ if (!ipc) {
220
+ await pending?.catch(() => { });
221
+ return;
175
222
  }
223
+ logger.info('🧹 Closing RPC client (Expo)');
224
+ await ipc.terminate();
225
+ // terminate() resolves before the worklet's `close` event, so a start that
226
+ // follows close() would not see the unclean stop yet.
227
+ if (!exitReported.has(ipc))
228
+ uncleanStop = true;
176
229
  })();
177
230
  try {
178
- await closingPromise;
231
+ await closePromise;
179
232
  }
180
233
  finally {
181
- // Reset so a subsequent close() (e.g. after a fresh getRPC spawned
182
- // a new worklet) can run again. Body guards on rpcInstance / workletInstance
183
- // make a redundant call a no-op if state is already cleared.
184
- closingPromise = null;
234
+ closePromise = null;
185
235
  }
186
236
  }
187
237
  export async function createDuplexSession(payload, commandId) {
188
- const rpc = await getRPC();
238
+ const rpc = await ensureRPC();
189
239
  const req = rpc.request(commandId);
190
240
  const requestStream = req.createRequestStream();
191
241
  const responseStream = req.createResponseStream({ encoding: 'utf-8' });
242
+ // bare-rpc cancels the request when the response stream closes first, which
243
+ // destroys this stream with CANCELLED. Consumers read errors from the
244
+ // response stream, so pass the error there instead of throwing it uncaught.
245
+ requestStream.on('error', (error) => responseStream.destroy(error));
192
246
  // Pre-encode payload — RN/Hermes lacks a global `Buffer`, so `write(string, "utf-8")` would throw.
193
247
  requestStream.write(new TextEncoder().encode(payload));
194
248
  return { requestStream, responseStream };