The best way to control Claude Code, Codex and more from any computer or phone
feat(server): voice models reuse copies already on disk (#34096)
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
Julius Marminge committed
Nov 10, 2026 at 16:05 UTC
79bca436b24a6eabb05d3d1a95348ae40d31e713
13 files changed
+366
-10
apps/server/src/speech/SpeechModelStore.test.ts
+52
@@ -12,6 +12,8 @@ import * as Path from "effect/Path";
12
import * as Stream from "effect/Stream";
13
import { HttpClient, HttpClientError, HttpClientRequest, HttpClientResponse } from "effect/http";
14
15
+import * as HostProcess from "@t3tools/shared/HostProcess";
16
+
17
import * as ServerConfig from "../config.ts";
18
import * as SpeechModelStore from "./SpeechModelStore.ts";
19
@@ -168,3 +170,53 @@ it.effect("cleans only download partials on cancellation or restart", () =>
170
]);
171
}).pipe(Effect.provide(dependencies)),
172
);
173
+
174
+it.effect("links a verified model file from another folder and never deletes it", () =>
175
+ Effect.gen(function* () {
176
+ const h = yield* harness;
177
+ const path = yield* Path.Path;
178
+ const elsewhere = yield* h.fs.makeTempDirectoryScoped({ prefix: "speech-other-app-" });
179
+ const nested = path.join(elsewhere, "hub", "snapshots");
180
+ yield* h.fs.makeDirectory(nested, { recursive: true });
181
+ const impostor = path.join(elsewhere, "same-size.gguf");
182
+ const existing = path.join(nested, "renamed-by-the-other-app.gguf");
183
+ yield* h.fs.writeFile(impostor, new Uint8Array(bytes.length));
184
+ yield* h.fs.writeFile(existing, bytes);
185
+
186
+ expect(yield* h.store.link([h.model], impostor)).toEqual([]);
187
+ expect(yield* h.store.linkedFrom(h.model)).toBeUndefined();
188
+
189
+ expect(yield* h.store.link([h.model], elsewhere)).toEqual([h.model.id]);
190
+ expect(yield* h.store.linkedFrom(h.model)).toBe(existing);
191
+ expect(yield* h.store.installedPath(h.model)).toBe(h.stale);
192
+ expect(h.requests).toHaveLength(0);
193
+ // Pointing at T3 Code's own folder must not turn the link into a link to itself.
194
+ expect(yield* h.store.link([h.model], h.directory)).toEqual([]);
195
+ expect(yield* h.store.installedPath(h.model)).toBe(h.stale);
196
+
197
+ yield* h.store.remove(h.model);
198
+ expect(yield* h.store.isReady(h.model)).toBe(false);
199
+ expect([...(yield* h.fs.readFile(existing))]).toEqual([...bytes]);
200
+ }).pipe(Effect.scoped, Effect.provide(dependencies)),
201
+);
202
+
203
+it.effect("installs from a Hugging Face cache copy instead of downloading", () =>
204
+ Effect.gen(function* () {
205
+ const h = yield* harness;
206
+ const path = yield* Path.Path;
207
+ const home = yield* h.fs.makeTempDirectoryScoped({ prefix: "speech-home-" });
208
+ const snapshot = path.join(
209
+ home,
210
+ ".cache/huggingface/hub/models--fixture--speech-model/snapshots",
211
+ h.model.revision,
212
+ );
213
+ yield* h.fs.makeDirectory(snapshot, { recursive: true });
214
+ const cached = path.join(snapshot, h.model.filename);
215
+ yield* h.fs.writeFile(cached, bytes);
216
+ const store = yield* h.openStore.pipe(Effect.provideService(HostProcess.HomeDirectory, home));
217
+
218
+ expect(yield* store.download(h.model)).toBe(h.stale);
219
+ expect(yield* store.linkedFrom(h.model)).toBe(cached);
220
+ expect(h.requests).toHaveLength(0);
221
+ }).pipe(Effect.scoped, Effect.provide(dependencies)),
222
+);
apps/server/src/speech/SpeechModelStore.ts
+120
@@ -14,7 +14,10 @@ import type { PlatformError } from "effect/PlatformError";
14
import * as Schema from "effect/Schema";
15
import * as Stream from "effect/Stream";
16
17
+import * as HostProcess from "@t3tools/shared/HostProcess";
18
+
19
import * as ServerConfig from "../config.ts";
20
+import { expandHomePath } from "../os-jank.ts";
21
import type { SpeechModel } from "./model.ts";
22
23
type ModelFile = Pick<SpeechModel, "id" | "filename" | "revision" | "size" | "sha256">;
@@ -44,6 +47,7 @@ export class SpeechModelStore extends Context.Service<
47
readonly isReady: (model: ModelFile) => Effect.Effect<boolean>;
48
/** The installed file once its SHA-256 has been verified, hashing it on first use. */
49
readonly installedPath: (model: ModelFile) => Effect.Effect<string | undefined>;
50
+ /** Links a copy the Hugging Face cache or Handy already holds; fetches only without one. */
51
readonly download: (
52
model: ModelFile,
53
progress?: SpeechModelDownloadProgress,
@@ -51,6 +55,17 @@ export class SpeechModelStore extends Context.Service<
55
string,
56
SpeechModelDownloadError | PlatformError | HttpClientError.HttpClientError
57
>;
58
+ /**
59
+ * Installs catalog files already on this machine as symlinks, never copies.
60
+ * `source` is a file or a folder to search; returns the ids it installed.
61
+ */
62
+ readonly link: (
63
+ models: ReadonlyArray<ModelFile>,
64
+ source: string,
65
+ ) => Effect.Effect<ReadonlyArray<string>, PlatformError>;
66
+ /** The outside file a linked model points at. */
67
+ readonly linkedFrom: (model: ModelFile) => Effect.Effect<string | undefined>;
68
+ /** Removes T3 Code's file or link; a linked file itself is left in place. */
69
readonly remove: (model: ModelFile) => Effect.Effect<void, PlatformError>;
70
}
71
>()("t3/speech/SpeechModelStore") {}
@@ -59,9 +74,14 @@ const DOWNLOAD_ATTEMPTS = 3;
74
const PARTIAL_FILENAME =
75
/\.gguf\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.part$/i;
76
77
+const LINK_SEARCH_DEPTH = 5;
78
+const LINK_SEARCH_ENTRIES = 5_000;
79
+
80
const make = Effect.gen(function* () {
81
const fs = yield* FileSystem.FileSystem;
82
const path = yield* Path.Path;
83
+ const home = yield* HostProcess.HomeDirectory;
84
+ const platform = yield* HostProcess.Platform;
85
const http = yield* HttpClient.HttpClient;
86
const random = yield* SecureRandom.SecureRandom;
87
const config = yield* ServerConfig.ServerConfig;
@@ -73,6 +93,28 @@ const make = Effect.gen(function* () {
93
}
94
}
95
const modelPath = (model: ModelFile) => path.join(directory, model.filename);
96
+ const appDataDirectories =
97
+ platform === "darwin"
98
+ ? [path.join(home, "Library", "Application Support")]
99
+ : platform === "win32"
100
+ ? [path.join(home, "AppData", "Roaming")]
101
+ : [path.join(home, ".local", "share"), path.join(home, ".config")];
102
+ // Where the Hugging Face cache and Handy keep these same pinned files.
103
+ const knownCopies = (model: ModelFile) => [
104
+ path.join(
105
+ home,
106
+ ".cache",
107
+ "huggingface",
108
+ "hub",
109
+ `models--${model.id.replace("/", "--")}`,
110
+ "snapshots",
111
+ model.revision,
112
+ model.filename,
113
+ ),
114
+ ...appDataDirectories.map((appData) =>
115
+ path.join(appData, "com.pais.handy", "models", model.filename),
116
+ ),
117
+ ];
118
// Files whose digest failed, by identity, so status polls stop calling them ready.
119
const corrupt = new Map<string, string>();
120
@@ -179,12 +221,81 @@ const make = Effect.gen(function* () {
221
return downloaded;
222
});
223
224
+ const filesUnder = Effect.fn("SpeechModelStore.filesUnder")(function* (source: string) {
225
+ const files: Array<{ readonly file: string; readonly size: number }> = [];
226
+ const pending = [{ entry: source, depth: LINK_SEARCH_DEPTH }];
227
+ for (let visited = 0; pending.length > 0 && visited < LINK_SEARCH_ENTRIES; visited += 1) {
228
+ const { entry, depth } = pending.pop()!;
229
+ const info = yield* statFile(entry);
230
+ if (info?.type === "File") files.push({ file: entry, size: Number(info.size) });
231
+ if (info?.type !== "Directory" || depth === 0) continue;
232
+ for (const name of yield* fs.readDirectory(entry).pipe(Effect.orElseSucceed(() => [])))
233
+ pending.push({ entry: path.join(entry, name), depth: depth - 1 });
234
+ }
235
+ return files;
236
+ });
237
+
238
+ const realPath = (file: string) => fs.realPath(file).pipe(Effect.orElseSucceed(() => undefined));
239
+
240
+ const link: SpeechModelStore["Service"]["link"] = Effect.fn("SpeechModelStore.link")(
241
+ function* (models, source) {
242
+ const root = path.resolve(
243
+ yield* expandHomePath(source.trim()).pipe(
244
+ Effect.provideService(Path.Path, path),
245
+ Effect.provideService(HostProcess.HomeDirectory, home),
246
+ ),
247
+ );
248
+ yield* fs.makeDirectory(directory, { recursive: true });
249
+ const linked: string[] = [];
250
+ for (const { file, size } of yield* filesUnder(root)) {
251
+ for (const model of models) {
252
+ if (model.size !== size || linked.includes(model.id)) continue;
253
+ const finalPath = modelPath(model);
254
+ // Pointing at T3 Code's own model folder must not replace a file with a link to itself.
255
+ if ((yield* realPath(file)) === (yield* realPath(finalPath))) continue;
256
+ if (yield* verifiedPath(model, finalPath)) continue;
257
+ const hashed = yield* expectedFile(model, file);
258
+ if (!hashed || !(yield* digestMatches(model, file))) continue;
259
+ // Staged then renamed, so a failed link never removes the file already installed.
260
+ const staged = `${finalPath}.${yield* random.uuidV4()}.part`;
261
+ // Windows grants symlinks only to privileged accounts; a hard link also shares the bytes.
262
+ const hardLinked = yield* fs.symlink(file, staged).pipe(
263
+ Effect.as(false),
264
+ Effect.catch(() => fs.link(file, staged).pipe(Effect.as(true))),
265
+ );
266
+ const current = yield* expectedFile(model, staged);
267
+ const marker = identity(model, hashed);
268
+ if (!current || identity(model, current) !== marker) {
269
+ yield* fs.remove(staged, { force: true });
270
+ continue;
271
+ }
272
+ yield* fs.rename(staged, finalPath);
273
+ // A hard link cannot be read back, so its origin is recorded beside it.
274
+ yield* (
275
+ hardLinked
276
+ ? fs.writeFileString(`${finalPath}.source`, file, { mode: 0o600 })
277
+ : fs.remove(`${finalPath}.source`, { force: true })
278
+ ).pipe(Effect.ignore);
279
+ yield* fs
280
+ .writeFileString(`${finalPath}.verified`, marker, { mode: 0o600 })
281
+ .pipe(Effect.ignore);
282
+ linked.push(model.id);
283
+ }
284
+ }
285
+ return linked;
286
+ },
287
+ );
288
+
289
const download: SpeechModelStore["Service"]["download"] = Effect.fn("SpeechModelStore.download")(
290
function* (model, progress = {}) {
291
yield* Effect.annotateCurrentSpan({ modelId: model.id });
292
const finalPath = modelPath(model);
293
yield* fs.makeDirectory(directory, { recursive: true });
294
if (yield* verifiedPath(model, finalPath, progress.onVerificationStart)) return finalPath;
295
+ for (const copy of knownCopies(model)) {
296
+ const linked = yield* link([model], copy).pipe(Effect.orElseSucceed(() => []));
297
+ if (linked.length > 0) return finalPath;
298
+ }
299
const partialPath = `${finalPath}.${yield* random.uuidV4()}.part`;
300
const url = `https://huggingface.co/${model.id}/resolve/${model.revision}/${model.filename}`;
301
return yield* Effect.gen(function* () {
@@ -211,6 +322,7 @@ const make = Effect.gen(function* () {
322
if (!complete || !(yield* digestMatches(model, partialPath)))
323
return yield* new SpeechModelDownloadError({ modelId: model.id, reason: "verification" });
324
yield* fs.rename(partialPath, finalPath);
325
+ yield* fs.remove(`${finalPath}.source`, { force: true }).pipe(Effect.ignore);
326
// Rename changes file metadata, so record the verified file's final identity.
327
const info = yield* fs.stat(finalPath);
328
yield* fs
@@ -228,6 +340,13 @@ const make = Effect.gen(function* () {
340
);
341
342
return SpeechModelStore.of({
343
+ link,
344
+ linkedFrom: Effect.fn("SpeechModelStore.linkedFrom")((model) =>
345
+ fs.readLink(modelPath(model)).pipe(
346
+ Effect.catch(() => fs.readFileString(`${modelPath(model)}.source`)),
347
+ Effect.orElseSucceed(() => undefined),
348
+ ),
349
+ ),
350
isReady: Effect.fn("SpeechModelStore.isReady")((model) =>
351
expectedFile(model, modelPath(model)).pipe(
352
Effect.map(
@@ -243,6 +362,7 @@ const make = Effect.gen(function* () {
362
const file = modelPath(model);
363
yield* fs.remove(file, { force: true });
364
yield* fs.remove(`${file}.verified`, { force: true });
365
+ yield* fs.remove(`${file}.source`, { force: true });
366
}),
367
});
368
});
apps/server/src/speech/SpeechService.test.ts
+2
@@ -103,6 +103,8 @@ const store = Layer.succeed(
103
installedPath: (model) =>
104
Effect.sync(() => (readyModels.has(model.id) ? "test.gguf" : undefined)),
105
download,
106
+ link: () => Effect.succeed([]),
107
+ linkedFrom: () => Effect.undefined,
108
remove: (model) =>
109
Effect.sync(() => {
110
readyModels.delete(model.id);
apps/server/src/speech/SpeechService.ts
+21
-2
@@ -138,6 +138,8 @@ export class SpeechService extends Context.Service<
138
readonly selectModel: (modelId: string) => Effect.Effect<SpeechModels, SpeechError>;
139
readonly cancelDownload: (modelId: string) => Effect.Effect<SpeechModels, SpeechError>;
140
readonly removeModel: (modelId: string) => Effect.Effect<SpeechModels, SpeechError>;
141
+ /** Uses catalog model files already on this machine, from a file or folder path. */
142
+ readonly linkModels: (source: string) => Effect.Effect<SpeechModels, SpeechError>;
143
readonly prepareModel: Effect.Effect<void, SpeechError>;
144
readonly transcribe: (
145
pcmBytes: Uint8Array,
@@ -467,6 +469,7 @@ const make = Effect.gen(function* () {
469
size: definition.size,
470
supportsStreaming: definition.supportsStreaming,
471
supportsBufferedStreaming: true,
472
+ supportsModelLinking: true,
473
supportsTranslation: definition.supportsTranslation,
474
languages: definition.languages,
475
supportsLanguageDetection: definition.supportsLanguageDetection,
@@ -489,8 +492,8 @@ const make = Effect.gen(function* () {
492
const models = yield* Effect.forEach(
493
SPEECH_MODELS,
494
(definition) =>
492
- store.isReady(definition).pipe(
493
- Effect.map((ready): EnvironmentSpeechModel => {
495
+ Effect.all([store.isReady(definition), store.linkedFrom(definition)]).pipe(
496
+ Effect.map(([ready, linkedFrom]): EnvironmentSpeechModel => {
497
const operation = downloading?.modelId === definition.id ? downloading : undefined;
498
return {
499
id: definition.id,
@@ -514,6 +517,7 @@ const make = Effect.gen(function* () {
517
? "installed"
518
: "downloadable",
519
...(operation ? { downloaded: operation.downloaded } : {}),
520
+ ...(ready && linkedFrom ? { linkedFrom } : {}),
521
};
522
}),
523
),
@@ -951,6 +955,21 @@ const make = Effect.gen(function* () {
955
),
956
),
957
),
958
+ linkModels: Effect.fn("SpeechService.linkModels")(function* (source) {
959
+ yield* requireSupported;
960
+ const settings = yield* readSettings("model linking");
961
+ const linked = yield* exclusive(
962
+ "model linking",
963
+ store
964
+ .link(SPEECH_MODELS, source)
965
+ .pipe(Effect.mapError((cause) => speechError("model linking", cause))),
966
+ );
967
+ const first = linked[0];
968
+ if (first === undefined) return yield* new SpeechModelNotFoundError({ modelId: source });
969
+ if (!(yield* store.isReady(selectedModel(settings))))
970
+ yield* writeSettings("model linking", { speechModelId: first });
971
+ return yield* modelsEffect;
972
+ }),
973
updateAcceleration: Effect.fn("SpeechService.updateAcceleration")((acceleration) =>
974
writeSettings("acceleration update", { speechAcceleration: acceleration }).pipe(
975
Effect.andThen(freshStatus("acceleration update")),
apps/server/src/speech/http.test.ts
+43
-1
@@ -80,6 +80,7 @@ effectIt.live("rejects oversized chunked audio without invoking transcription",
80
prepareModel: Effect.void,
81
models: () => Effect.succeed({ models: [] }),
82
downloadModel: () => Effect.succeed({ models: [] }),
83
+ linkModels: () => Effect.succeed({ models: [] }),
84
selectModel: () => Effect.succeed({ models: [] }),
85
cancelDownload: () => Effect.succeed({ models: [] }),
86
updateAcceleration: () => Effect.succeed({ supported: false as const, reason: "test" }),
@@ -164,7 +165,31 @@ effectIt.effect(
165
HttpApiBuilder.layer(HttpApi.make("environment").add(EnvironmentVoiceHttpApi)).pipe(
166
Layer.provide(speechHttpApiLayer),
167
Layer.provide(principal(AuthOrchestrationOperateScope, AuthSettingsWriteScope)),
167
- Layer.provide(Layer.mock(SpeechService.SpeechService)({})),
168
+ Layer.provide(
169
+ Layer.mock(SpeechService.SpeechService)({
170
+ models: () =>
171
+ Effect.succeed({
172
+ models: [
173
+ {
174
+ id: "fixture/model",
175
+ name: "Fixture",
176
+ description: "",
177
+ size: 1,
178
+ languages: ["en"],
179
+ accuracy: 0,
180
+ speed: 0,
181
+ recommended: false,
182
+ supportsStreaming: false,
183
+ supportsLanguageDetection: false,
184
+ supportsTranslation: false,
185
+ active: true,
186
+ state: "installed",
187
+ linkedFrom: "/home/someone/models/fixture.gguf",
188
+ },
189
+ ],
190
+ }),
191
+ }),
192
+ ),
193
Layer.provide(cloud),
194
Layer.provide(dependencies),
195
Layer.provide(HttpServer.layerServices),
@@ -228,6 +253,22 @@ effectIt.effect(
253
422,
254
);
255
expect(transcribe).toHaveBeenLastCalledWith("openrouter", "acme/transcribe-1");
256
+ // Naming a path on the environment needs filesystem access, not only settings access.
257
+ const link = yield* Effect.promise(() =>
258
+ handler(
259
+ new Request("http://localhost/api/voice/models/link", {
260
+ method: "POST",
261
+ headers: { "content-type": "application/json" },
262
+ body: JSON.stringify({ path: "/models" }),
263
+ }),
264
+ context,
265
+ ),
266
+ );
267
+ expect(link.status).toBe(403);
268
+ const listed = yield* Effect.promise(() =>
269
+ handler(new Request("http://localhost/api/voice/models"), context),
270
+ );
271
+ expect(yield* Effect.promise(() => listed.text())).not.toContain("/home/someone");
272
}).pipe(Effect.scoped),
273
);
274
@@ -268,6 +309,7 @@ effectIt.effect.each([
309
prepareModel: Effect.void,
310
models: () => Effect.succeed({ models: [] }),
311
downloadModel: () => Effect.fail(error),
312
+ linkModels: () => Effect.fail(error),
313
selectModel: () => Effect.fail(error),
314
cancelDownload: () => Effect.fail(error),
315
updateAcceleration: () => Effect.fail(error),
apps/server/src/speech/http.ts
+35
-5
@@ -1,9 +1,12 @@
1
import { decodeSpeechPcmRequest } from "@t3tools/shared/speech";
2
import {
3
+ AuthFilesystemReadScope,
4
AuthOrchestrationOperateScope,
5
AuthSettingsWriteScope,
6
type AuthEnvironmentScope,
7
+ EnvironmentAuthenticatedPrincipal,
8
EnvironmentHttpApi,
9
+ type EnvironmentSpeechModels,
10
EnvironmentVoiceBodyLimit,
11
SPEECH_MAX_OPTIONS_BYTES,
12
} from "@t3tools/contracts";
@@ -53,6 +56,14 @@ const mapSpeechError = <A, R>(effect: Effect.Effect<A, SpeechService.SpeechError
56
}),
57
);
58
59
+// A linked model's origin is a path on this machine; only filesystem readers may see it.
60
+// Untraced: it runs inside each handler's own span.
61
+const withoutHostPaths = Effect.fnUntraced(function* (result: EnvironmentSpeechModels) {
62
+ const session = yield* EnvironmentAuthenticatedPrincipal;
63
+ if (session.scopes.has(AuthFilesystemReadScope)) return result;
64
+ return { models: result.models.map(({ linkedFrom: _, ...model }) => model) };
65
+});
66
+
67
export const speechHttpApiLayer = HttpApiBuilder.group(
68
EnvironmentHttpApi,
69
"voice",
@@ -133,35 +144,54 @@ export const speechHttpApiLayer = HttpApiBuilder.group(
144
"models",
145
Effect.fn("environment.voice.models")(function* (args) {
146
yield* guard(args.endpoint.name);
136
- return yield* speech.models(args.query.benchmarks === "1").pipe(mapSpeechError);
147
+ return yield* speech
148
+ .models(args.query.benchmarks === "1")
149
+ .pipe(mapSpeechError, Effect.flatMap(withoutHostPaths));
150
}),
151
)
152
.handle(
153
"downloadModel",
154
Effect.fn("environment.voice.downloadModel")(function* (args) {
155
yield* guard(args.endpoint.name, AuthSettingsWriteScope);
143
- return yield* speech.downloadModel(args.payload.modelId).pipe(mapSpeechError);
156
+ return yield* speech
157
+ .downloadModel(args.payload.modelId)
158
+ .pipe(mapSpeechError, Effect.flatMap(withoutHostPaths));
159
}),
160
)
161
.handle(
162
"selectModel",
163
Effect.fn("environment.voice.selectModel")(function* (args) {
164
yield* guard(args.endpoint.name, AuthSettingsWriteScope);
150
- return yield* speech.selectModel(args.payload.modelId).pipe(mapSpeechError);
165
+ return yield* speech
166
+ .selectModel(args.payload.modelId)
167
+ .pipe(mapSpeechError, Effect.flatMap(withoutHostPaths));
168
}),
169
)
170
.handle(
171
"cancelModelDownload",
172
Effect.fn("environment.voice.cancelModelDownload")(function* (args) {
173
yield* guard(args.endpoint.name, AuthSettingsWriteScope);
157
- return yield* speech.cancelDownload(args.payload.modelId).pipe(mapSpeechError);
174
+ return yield* speech
175
+ .cancelDownload(args.payload.modelId)
176
+ .pipe(mapSpeechError, Effect.flatMap(withoutHostPaths));
177
}),
178
)
179
.handle(
180
"removeModel",
181
Effect.fn("environment.voice.removeModel")(function* (args) {
182
yield* guard(args.endpoint.name, AuthSettingsWriteScope);
164
- return yield* speech.removeModel(args.payload.modelId).pipe(mapSpeechError);
183
+ return yield* speech
184
+ .removeModel(args.payload.modelId)
185
+ .pipe(mapSpeechError, Effect.flatMap(withoutHostPaths));
186
+ }),
187
+ )
188
+ .handle(
189
+ "linkModels",
190
+ Effect.fn("environment.voice.linkModels")(function* (args) {
191
+ yield* guard(args.endpoint.name, AuthSettingsWriteScope);
192
+ // The request names a path on this machine and the result reveals what is there.
193
+ yield* requireEnvironmentScope(AuthFilesystemReadScope);
194
+ return yield* speech.linkModels(args.payload.path).pipe(mapSpeechError);
195
}),
196
)
197
.handle(
apps/web/src/components/settings/VoiceSettingsPanel.tsx
+52
-2
@@ -3,6 +3,7 @@ import {
3
downloadEnvironmentSpeechModel,
4
getEnvironmentSpeechModels,
5
getEnvironmentSpeechStatus,
6
+ linkEnvironmentSpeechModels,
7
removeEnvironmentSpeechModel,
8
selectEnvironmentSpeechModel,
9
updateEnvironmentSpeechAcceleration,
@@ -11,6 +12,7 @@ import {
12
import type { PreparedConnection } from "@t3tools/client-runtime/connection";
13
import { openRouterIcon } from "@t3tools/client-runtime/provider-clients";
14
import {
15
+ AuthFilesystemReadScope,
16
AuthSettingsWriteScope,
17
CLOUD_SPEECH_LABELS,
18
CloudSpeechProvider,
@@ -42,6 +44,7 @@ import {
44
StarIcon,
45
SlidersHorizontalIcon,
46
Trash2Icon,
47
+ UnlinkIcon,
48
XIcon,
49
} from "lucide-react";
50
import { useEffect, useRef, useState, type ReactNode } from "react";
@@ -215,6 +218,11 @@ function ModelCard(props: ModelCardProps) {
218
) : null}
219
</div>
220
<p className="mt-0.5 text-xs leading-relaxed text-muted-foreground">{model.description}</p>
221
+ {model.linkedFrom ? (
222
+ <p className="mt-0.5 break-all text-2xs text-muted-foreground">
223
+ Using your file at {model.linkedFrom}
224
+ </p>
225
+ ) : null}
226
<ModelBenchmarks
227
model={model}
228
languages={props.comparisonLanguages}
@@ -283,10 +291,18 @@ function ModelCard(props: ModelCardProps) {
291
size="icon-sm"
292
variant="ghost"
293
disabled={props.busy}
286
- aria-label={`Delete ${model.name}`}
294
+ aria-label={
295
+ model.linkedFrom
296
+ ? `Stop using your ${model.name} file; the file stays on disk`
297
+ : `Delete ${model.name}`
298
+ }
299
onClick={props.onDelete}
300
>
289
- <Trash2Icon className="size-3.5" />
301
+ {model.linkedFrom ? (
302
+ <UnlinkIcon className="size-3.5" />
303
+ ) : (
304
+ <Trash2Icon className="size-3.5" />
305
+ )}
306
</Button>
307
) : null}
308
</div>
@@ -779,6 +795,8 @@ function SpeechModelBrowser(props: {
795
const [search, setSearch] = useState("");
796
const [sort, setSort] = useState<SpeechModelSort>("recommended");
797
const [downloadedOnly, setDownloadedOnly] = useState(false);
798
+ const [existingPath, setExistingPath] = useState("");
799
+ const canReadFiles = useEnvironmentScope(prepared.environmentId, AuthFilesystemReadScope);
800
const [languageSearch, setLanguageSearch] = useState("");
801
const [selection, setSelection] = useState<string[] | null>(null);
802
const [preferred] = useState(preferredSpeechLanguages);
@@ -981,6 +999,38 @@ function SpeechModelBrowser(props: {
999
);
1000
})}
1001
</div>
1002
+ {status.supportsModelLinking && canReadFiles ? (
1003
+ <form
1004
+ className="flex items-center gap-2 border-t border-border/60 p-3"
1005
+ onSubmit={(event) => {
1006
+ event.preventDefault();
1007
+ void run("Could not use a model from that path", async () => {
1008
+ await runEnvironmentSpeech(
1009
+ linkEnvironmentSpeechModels(prepared, existingPath),
1010
+ );
1011
+ setExistingPath("");
1012
+ });
1013
+ }}
1014
+ >
1015
+ <div className="min-w-0 flex-1">
1016
+ <Input
1017
+ size="compact"
1018
+ aria-label="Path to a model file or folder already on this environment"
1019
+ placeholder="Already downloaded elsewhere? Paste the model file or folder path"
1020
+ value={existingPath}
1021
+ onChange={(e) => setExistingPath(e.target.value)}
1022
+ />
1023
+ </div>
1024
+ <Button
1025
+ type="submit"
1026
+ size="sm"
1027
+ variant="outline"
1028
+ disabled={controlsDisabled || !existingPath.trim()}
1029
+ >
1030
+ Use existing
1031
+ </Button>
1032
+ </form>
1033
+ ) : null}
1034
</div>
1035
</div>
1036
</>
docs/internals/voice-input.md
+3
@@ -63,6 +63,9 @@ at a time. Batch uploads carry their options in the body framing defined in
63
[shared/speech.ts](../../packages/shared/src/speech.ts); streaming sends them in
64
the socket's first command. Model files and the selected model, hardware
65
placement, and unload timeout are environment state in server settings.
66
+A model file from another app is installed as a symlink only after its SHA-256
67
+matches a catalog entry, so the store never loads a file the catalog does not pin
68
+and removing a model never deletes a file T3 Code did not download.
69
70
The Silero silence detector is optional. If its download fails, recordings use
71
raw audio during the retry cooldown so a detector outage cannot block dictation.
docs/user/voice-input.md
+10
@@ -54,6 +54,16 @@ isn’t already selected. **Test model** lets you try it without sending a messa
54
If you use the composer microphone before a model is installed, it offers to download one.
55
The recommendation uses your Voice language, or your system’s preferred languages with **Auto-detect**.
56
57
+If another app already downloaded one of these models, you don’t need a second copy.
58
+**Download** first looks in Handy’s model folder and the Hugging Face cache on that
59
+environment and uses a copy it finds there instead of downloading. For a copy anywhere
60
+else, on web or desktop, paste the path of the model file or its folder under the model
61
+list and choose **Use existing**. The path is on the environment
62
+that transcribes, not on the device you are using. T3 Code checks that the file is exactly a
63
+model from its list and then uses it in place. Removing the model in T3 Code leaves your file
64
+alone; if the other app deletes it, download or link the model again. Files in another
65
+format, such as Core ML, ONNX, or MLX builds of the same model, can’t be used.
66
+
67
Select the languages you dictate in to compare models that support all of them.
68
Accuracy shows how often the model got words or characters wrong in each
69
language; speed is the time to transcribe 30 seconds on a reference GPU. Choose
packages/client-runtime/src/voice-input/environment.ts
+11
@@ -292,6 +292,17 @@ export const updateEnvironmentSpeechModelUnloadTimeout = (
292
client.updateModelUnloadTimeout({ headers, payload: { timeout } }),
293
});
294
295
+export const linkEnvironmentSpeechModels = (prepared: PreparedConnection, path: string) =>
296
+ request({
297
+ group: "voice",
298
+ prepared,
299
+ method: "POST",
300
+ path: (urls) => urls.linkModels(),
301
+ // Hashing several multi-gigabyte files takes longer than an ordinary request.
302
+ timeoutMs: INFERENCE_OR_DOWNLOAD_TIMEOUT_MS,
303
+ run: ({ client, headers }) => client.linkModels({ headers, payload: { path } }),
304
+ });
305
+
306
export const removeEnvironmentSpeechModel = (prepared: PreparedConnection, modelId: string) =>
307
request({
308
group: "voice",
packages/client-runtime/src/voice-input/index.ts
+1
@@ -21,6 +21,7 @@ export {
21
transcribeCloudPcm,
22
getEnvironmentSpeechStatus,
23
getEnvironmentSpeechStreamUrl,
24
+ linkEnvironmentSpeechModels,
25
postProcessEnvironmentTranscript,
26
removeEnvironmentSpeechModel,
27
selectEnvironmentSpeechModel,
packages/contracts/src/environmentHttp.ts
+9
@@ -56,6 +56,7 @@ import {
56
CloudSpeechModels,
57
CloudSpeechProvider,
58
EnvironmentSpeechAccelerationRequest,
59
+ EnvironmentSpeechModelLinkRequest,
60
EnvironmentSpeechModelRequest,
61
EnvironmentSpeechModels,
62
EnvironmentSpeechModelUnloadTimeoutRequest,
@@ -888,6 +889,14 @@ export class EnvironmentVoiceHttpApi extends HttpApiGroup.make("voice")
889
error: [...EnvironmentScopedOperationErrors, EnvironmentRequestInvalidError],
890
}).middleware(EnvironmentAuthenticatedAuth),
891
)
892
+ .add(
893
+ HttpApiEndpoint.post("linkModels", "/api/voice/models/link", {
894
+ headers: OptionalBearerHeaders,
895
+ payload: EnvironmentSpeechModelLinkRequest,
896
+ success: EnvironmentSpeechModels,
897
+ error: [...EnvironmentScopedOperationErrors, EnvironmentRequestInvalidError],
898
+ }).middleware(EnvironmentAuthenticatedAuth),
899
+ )
900
.add(
901
HttpApiEndpoint.post("updateAcceleration", "/api/voice/acceleration", {
902
headers: OptionalBearerHeaders,
packages/contracts/src/speech.ts
+7
@@ -194,6 +194,8 @@ export const EnvironmentSpeechModel = Schema.Struct({
194
active: Schema.Boolean,
195
state: EnvironmentSpeechModelState,
196
downloaded: Schema.optionalKey(Schema.Finite),
197
+ /** The file outside T3 Code's model folder this model is used from. */
198
+ linkedFrom: Schema.optionalKey(Schema.String),
199
});
200
export type EnvironmentSpeechModel = typeof EnvironmentSpeechModel.Type;
201
@@ -203,6 +205,10 @@ export const EnvironmentSpeechModels = Schema.Struct({
205
export type EnvironmentSpeechModels = typeof EnvironmentSpeechModels.Type;
206
207
export const EnvironmentSpeechModelRequest = Schema.Struct({ modelId: SpeechModelId });
208
+/** A model file, or a folder to search for them, on the environment's own disk. */
209
+export const EnvironmentSpeechModelLinkRequest = Schema.Struct({
210
+ path: TrimmedNonEmptyString.check(Schema.isMaxLength(4096)),
211
+});
212
213
export const EnvironmentSpeechState = Schema.Literals(["missing-model", "ready", "transcribing"]);
214
export type EnvironmentSpeechState = typeof EnvironmentSpeechState.Type;
@@ -215,6 +221,7 @@ const SupportedSpeechStatus = Schema.Struct({
221
size: Schema.Finite,
222
supportsStreaming: Schema.Boolean,
223
supportsBufferedStreaming: Schema.optionalKey(Schema.Boolean),
224
+ supportsModelLinking: Schema.optionalKey(Schema.Boolean),
225
supportsTranslation: Schema.Boolean,
226
languages: Schema.optionalKey(Schema.Array(Schema.String)),
227
supportsLanguageDetection: Schema.optionalKey(Schema.Boolean),