@devries-cameron20 / t3code-1 / commits / 79bca436b2
Fork 0

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),