Skip to content

feat(stt): allow a custom pinned whisper model - #14918

Merged
chenmingwei23 merged 1 commit into
mainfrom
fix/stt-custom-model-inrepo
Oct 14, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
fix/stt-custom-model-inrepo

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Supersedes #8281 — in-repo replacement of the fork PR by @LuisBrel (authorship preserved via Co-authored-by), rebased onto fresh main.

Problem / Motivation

Goal: Let a user run local speech-to-text on their own whisper.cpp ggml model instead of only the four catalog models.

Voice input is locked to a fixed catalog (tiny, base, small, large-v3-turbo). There is no way to run a fine-tune, a quantised build, or a language-specific model. memory.embed_model_path already solves the same shape for embeddings; STT had no equivalent.

Why it matters

Users who need a model outside the catalog (accuracy on an accent or jargon, a smaller quantised build for a constrained machine, an offline copy) cannot use local STT with it at all today.

Not a goal

  • Not a new recogniser: custom selects a different model for the bundled whisper.cpp engine.
  • Not a download: the user places the file. No URL setting and no network fetch for a custom model (maintainer decision on the 09-29 pause comment: local path, not URL).

What changed

  • SttConfig gains custom_model_path and custom_model_sha256; stt.model accepts custom.
  • stt/models.py: custom_model_file resolves the path, symlinks followed, and refuses anything not a regular file strictly inside the models folder (models/whisper under the Kiro Crew home): any .. component, an absolute path elsewhere, a symlink pointing out, the folder itself, a built-in model's file name in any case, or the same file under another name (ggml-base.bin etc., which the catalog download would delete or overwrite), and a .part staging file. ~ is not expanded. The engine loads the exact real path that was hashed. It runs when the dashboard saves the field and on every load.
  • The file is hashed on every load and not used on a mismatch. A refused file is left in place (it is the user's own file).
  • The custom file takes the same models-seal checks as catalog weights: models and the whisper folder must be real directories (sandbox.require_real_model_path), and the hash reads one O_NOFOLLOW descriptor (_sha256_verified_file), so a second hard link or a symlinked leaf refuses the load with a failed status flagged refused. A link below the folder is still followed and must stay inside it.
  • PUT /api/config/stt answers a refused name or a malformed digest with a 400 naming the rule (custom_model_path_outside / _missing / _not_file / _empty, custom_model_sha256_invalid). The message never quotes the path.
  • Both fields are owner-only on GET/PUT /api/config/stt, audited on both branches. config.json is read-only in the agent sandbox, so the pin cannot be rewritten to match a file an agent placed in the folder.
  • A half-configured pair degrades to the default model with a warning. A complete pair whose file is missing does not degrade: it fails at load with the reason, so a different model never runs in its place.
  • Settings → Voice: a Custom option, a file-name row with the setup as a numbered list (step 1 links the whisper.cpp models on Hugging Face and says each file's page there lists its SHA-256, step 2 is the folder to copy, step 3 the name to type, with a real example), and a SHA-256 row whose first line says where the value comes from (the file's download page), then what it is for; that a wrong value is refused and changes nothing is said once, in its ⓘ hint. The row has no link of its own, and the shasum -a 256 / Get-FileHash commands sit as copy blocks under "Work out the SHA-256 yourself". Status reads "Model file problem" while a configured custom file is unusable. Refusals show under the rows as an ErrorNotice with the agent hand-off; a missing configured file shows its reason instead of a download button.
  • The custom-model resolve is offloaded off the event loop at every async call site, because resolving custom reads config.json.

Known limit

The hash and the native load are two opens of the same path, so a writer that swaps the file between them is not caught. Catalog weights have the same race. The models seal from #16054 keeps a sandboxed agent from being that writer, and the custom path now goes through the same load checks (above); an unsandboxed process on the host can still swap the file between the two opens, as it can for catalog weights.

Backwards compatibility

Compatible: both fields default to "" and stt.model still defaults to base. Purely additive.

Tests

  • test/test_stt_custom_model.py: containment (.., absolute elsewhere, symlink leaf out, symlinked folder out, the folder itself), missing / folder / blank, digest carriers, resolve and degrade, load-time hash refusal that keeps the file, swap-after-load refusal, no download ever, and (POSIX) a hard-linked file and a linked whisper folder refused at load. Each of those two fails with its check removed.
  • test/test_dashboard_handlers_core_coverage.py: owner-only gate, and the 400s for a path outside the models folder, a missing file, a folder, and a bad digest.
  • test/test_config_loader.py, test/test_stt_stream.py: loader wiring and off-loop resolve.
  • website/src/test/SttSettings.customModelGuard.test.tsx: the incomplete-pair line, the refusal notice with hand-off, the missing-file notice, the draft hand-off guard, and the setup copy: the SHA-256 row's first sentence names where the value comes from, it gives the refusal reassurance once (in its ⓘ hint), and its folded section is named after what it works out; the model site is linked once, from step 1, which says the file page lists the SHA-256; and step 3 shows a real file name. Each of those fails without its fix.

Manual verification

Screenshots below come from the built SPA with fixture-backed /api/** via the committed harness website/scripts/capture-stt-custom-model.mjs (no gateway, no network). A live load of a real ggml model was not run here.

Screenshots / video

1. Custom selected, file in the models folder
Custom model configured

2. Configured file missing: Status says so, and the reason shows with the agent hand-off, no download button
Custom model file missing

3. Half-configured pair: the picker reads base, and the line says why
Custom model pair incomplete

4. A name outside the models folder is refused under the rows
Custom model path refused

5. A complete pair with a built-in model selected: the rows say they are idle
Custom rows idle

6. "Work out the SHA-256 yourself" opened under the SHA-256 box: the command for each system, with the file name quoted for that shell
Hash commands open

Related Issues

Supersedes #8281.

Checklist

  • At most two commits, Conventional Commits titles (feat: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (docs/configuration.md, system-specs)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested a review from a team September 29, 2026 03:42
@iamwhatever
iamwhatever requested a review from a team as a code owner September 29, 2026 03:42
@iamwhatever iamwhatever added the drive-to-green PR claimed by drive-to-green pipeline label Sep 29, 2026
@iamwhatever iamwhatever self-assigned this Sep 29, 2026
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 29, 2026
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — 🟡 CONCERNS

UX-level review of 123542d75aa08722d074348995b4d3858944863e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

If you pick Custom before both fields are filled, the Model picker jumps back to "base", and a file-name error shows up under the fingerprint box, not the file box.

Watch

  • The picker contradicts your choice (shot-03). The gateway turns an incomplete custom back into base. The select reads "base (148MB)" while the custom rows stay open, with only the muted line "Until then, base stays in use." The blind reader: "I can't tell whether I'm choosing Custom or base." Every first-time setup goes through this state, but it lasts only until both fields are saved. Smallest fix: while customIntended is set, keep the select on Custom and show the in-use model in the line below it ("Custom: not active yet, base in use").
  • The file-name error sits in the wrong place (shot-04). customErr always renders after the SHA-256 row, even when customErrField === 'path'. The reader said: "at first I'd think the fingerprint was wrong." This hits every path refusal, and it is the most common error on this surface. Fix: render the notice under the row named by customErrField.
  • Status says "ready" next to a red "Not saved" (shot-04). The reader: "I can't trust the Status label to warn me." This partly overlaps the first fix. Once the refusal sits under the right box, the "keeps using X" wording carries more of the load.

Suggestions

  • custom_model_not_used and custom_model_incomplete both appear in a "base selected" state (shots 03 and 05), and the reader couldn't tell them apart. Fixing the first Watch item removes shot-03's version, leaving shot-05 as the only "idle" state.
  • The step-3 example name matches the value in shot-01's box, so the reader couldn't tell typed input from a sample. Use an example that clearly differs, e.g. ggml-<name>.bin.

[UX-REVIEWED] 123542d

Description read

[DESCRIPTION-READ] 9882423918534311abfe1d658799e125459c9926a05c98f728385f4adcc9e014

That sha256 names everything this verdict read: the PR description, plus the 9 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

Design-level review of 123542d75aa08722d074348995b4d3858944863e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

models.resolve("custom") re-reads config.json from inside the stt layer, ignoring the caller's cfg.stt, which forces six off-loop hops and a second config snapshot.

Watch

  • The stt layer reads config itself. The patch adds _configured_custom_model() → KiroCrewConfig.load().stt, and resolve(name) calls it. Every caller already holds cfg.stt. The model name comes from one snapshot and the path and digest from a fresh load. As a result, asyncio.to_thread had to be added at stt_hooks, stt_stream (×3), engine.prepare, ensure_model and core.py. A future async caller that forgets the hop blocks the gateway loop. A save that lands mid-session can pair a stale name with a new pin.
    Clears when: resolve is given the path and digest (or SttConfig) by its caller and no longer loads config, so the offloads exist only for disk I/O.
  • A custom model is a WhisperModel with size_bytes=0, and not every reader of that field was updated. The prewarm guard was patched, but doctor_checks/features.py (around line 211) still prints custom not downloaded yet (0 MB, fetched on first use) when the custom file is missing. That is wrong: nothing is ever fetched for a custom model, so kirocrew doctor sends the user looking for a download that will never happen.
    Clears when: the doctor reader handles CUSTOM_MODEL (it reports a missing or refused file with its reason), and the remaining readers of size_bytes and filename have been checked.

[DESIGN-REVIEWED] 123542d

Description read

[DESCRIPTION-READ] ce48a8708ee129b3171c09fcdddde6af888354314ee7009f3e1f41a9651b1aad

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 123542d75aa08722d074348995b4d3858944863e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 123542d

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 123542d75aa08722d074348995b4d3858944863e: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 123542d75aa08722d074348995b4d3858944863e — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

No live load of a real third-party ggml file ran ("A live load of a real ggml model was not run here"). Check that one loads through engine.py before merge.

Not justified as shipped

  • Item 9 — undeclared: the PUT /api/config/stt handler now returns 400 body_not_object for a JSON body that isn't an object. Nothing in the description mentions it.

What this change ships

Inventory (9 items) — 8 justified

Intent: let a user run local speech-to-text on their own whisper.cpp model file. ADDITION.

  1. Voice model picker gains a Custom option (default stays base) — justified
  2. New stt.custom_model_path config key, limited to files inside models/whisper — justified
  3. New stt.custom_model_sha256 config key, checked on every load; a mismatch refuses the load — justified
  4. A file using a built-in model's name, or the same file as one, is refused, since the catalog download would destroy it — justified
  5. Saving a bad path or digest returns a 400 naming the rule — justified
  6. Only the owner can read or write the custom pair, and both outcomes are audited — justified
  7. Settings → Voice gets file-name and SHA-256 rows, setup steps, and a "Model file problem" status — justified
  8. The STT resolve calls now run off the event loop — justified
  9. A non-object PUT body gets a 400 instead of a 500 — undeclared, unmentioned 400 for a non-object body

[FIRST-PRINCIPLES-REVIEWED] 123542d

Description read

[DESCRIPTION-READ] 4d9c7b1d379bce5e7ed2002472033574ffc0fd0beb3945c3eb97072e4ba93756

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 29, 2026
@iamwhatever
iamwhatever force-pushed the fix/stt-custom-model-inrepo branch from 1a3fbfd to d77967a Compare September 29, 2026 04:17
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 123542d75aa08722d074348995b4d3858944863e — this comment is updated in place on each push.

Review details

No findings block this merge. Three advisory issues below.

FINDING — src/kiro_crew/stt/models.py:1034 — _accept_custom sets its digest-mismatch, path-error and OSError failures without refused=True. WhisperEngine.ensure_loaded (engine.py:629) therefore falls through to CODE_MODEL_MISSING. A custom model with a wrong hash or a missing file then reaches dictation as stt_model_missing, which shows "Download it in the speech-to-text settings", but nothing can be downloaded for a custom model → Fix: pass refused=True on those three _set(step="failed", …) calls so the engine returns CODE_IMPORT_FAILED with the stored reason.

FINDING — website/src/pages/settings/SttSettings.tsx:1343 — The custom rows open whenever stt.model === CUSTOM_MODEL (line 870), and that check ignores customPairServed. onBlur={() => set({ custom_model_path: localCustomPath.trim() })} saves even when nothing changed. So a non-owner !dashboard session that just tabs through the empty row sends PUT {custom_model_path: ""}, _deny_non_owner_stt_custom_model returns 403 on presence, and an error appears → Fix: open the Custom option and its rows only when customPairServed is true, and skip the blur save when the value matches stt.custom_model_path.

FINDING — src/kiro_crew/stt/models.py:151 — filename for a custom model returns Path(self.custom_path).name. With a missing custom file, kirocrew doctor (doctor_checks/features.py:218) prints "not downloaded yet (0 MB, fetched on first use)", but nothing is ever fetched. With a path in a subfolder, its ✅ line points to models_dir() / model.filename, a file that does not exist → Fix: in doctor_checks/features.py, use model_path(model) and add a custom-model branch for the not-present message. That file is not part of this PR.

[OPUS-REVIEWED] 123542d

Verdict parsed from the review's SHA-scoped output markers for commit 123542d75aa08722d074348995b4d3858944863e.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 123542d75aa08722d074348995b4d3858944863e: <one-sentence reason>

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 29, 2026
@iamwhatever
iamwhatever force-pushed the fix/stt-custom-model-inrepo branch from d77967a to 8493ca5 Compare September 29, 2026 04:23
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 29, 2026
@iamwhatever
iamwhatever force-pushed the fix/stt-custom-model-inrepo branch from 8493ca5 to 3880ed0 Compare September 29, 2026 04:48
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 29, 2026
@iamwhatever
iamwhatever force-pushed the fix/stt-custom-model-inrepo branch from 3880ed0 to 5f324c2 Compare September 29, 2026 05:10
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 29, 2026
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 12, 2026
@iamwhatever
iamwhatever force-pushed the fix/stt-custom-model-inrepo branch from b2b1457 to b9036af Compare October 12, 2026 16:42
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 12, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Dispositions for the reviews on b2b1457192. New head: b9036af459.

UX blocker 1 (file row). The setup is now a real <ol> under the box: 1. a link "Get a speech model file (.bin)" to the whisper.cpp model page; 2. "Put it in this folder:" with the folder copyable; 3. "Type its file name in the box above." "A wrong name is refused…" moved into the ⓘ.

UX blocker 2 (SHA-256 row). The description now leads with what it is for ("A fingerprint that proves the file is the one you meant."). Under the box: "Copy it from the download page, or run the command for your system and paste what it prints:" with shasum -a 256 <file> and Get-FileHash <file> -Algorithm SHA256 shown inline as copy blocks, filled in with the typed file name.

UX watch. A refusal now starts with "Not saved:" and ends by naming the model still in use. The half-pair line now says "…once both are filled in, unless you pick another model." The status badge is lowercase ("model file problem") to match "ready".

GPT 6.1 (hash-then-load race, models.py:847). Same finding as the earlier disposition: verified real, and the same race exists for catalog weights on main (#16054 is the open fix for the class). Not changed here, and left for a maintainer decision.

Updated screenshots (built SPA, website/scripts/capture-stt-custom-model.mjs):

01-custom-configured

02-custom-file-missing

03-custom-pair-incomplete

04-custom-path-refused

05-custom-rows-idle

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 12, 2026
@iamwhatever
iamwhatever force-pushed the fix/stt-custom-model-inrepo branch 2 times, most recently from f287e37 to d0c1c15 Compare October 12, 2026 18:45
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 12, 2026
@iamwhatever
iamwhatever force-pushed the fix/stt-custom-model-inrepo branch from d0c1c15 to c3ee66f Compare October 12, 2026 19:22
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 12, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Dispositions for the UX review on c3ee66f01d. New head: 27dc400e45. GPT 6.1 has no blocking findings on d0c1c15306; the later pushes changed only UI copy and markup.

Blocker (SHA-256 row). Each command now has its system as a label ("macOS / Linux terminal", "Windows PowerShell"). The text says the download page usually lists the SHA-256 next to the file, and says to open the terminal in the folder from step 2.

Watch. A refused row is now marked invalid (aria-invalid, error border, and aria-describedby pointing at the refusal), so the text it keeps no longer reads as saved. The incomplete-pair line is now "Add both the file name and the SHA-256 to use your custom model. Until then, {{model}} stays in use." The screenshots below come from this head, so they match the copy that ships.

Suggestion. The idle line now reads "Not used while {{model}} is selected. Pick Custom to use this file."

Also fixed: check-source-strings (three new keys ended mid-sentence).

Screenshots (built SPA, website/scripts/capture-stt-custom-model.mjs):

01-custom-configured

02-custom-file-missing

03-custom-pair-incomplete

04-custom-path-refused

05-custom-rows-idle

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Dispositions for the reviews on 890798aa6. New head: b08ec5ee54.

GPT 6.1 F1: copied hash commands interpret the file name as shell syntax (SttSettings.tsx:1205). Real, verified: the name was put into both commands unquoted. Fixed: the POSIX command now single-quotes the name (each ' becomes '\''). The PowerShell one uses -LiteralPath with a single-quoted string, each ' doubled. Test: quotes the file name in the copyable commands so it is never shell syntax, which checks the exact copied text for a name containing $(…), ' and ;.

GPT 6.1 F2: native load reopens a file the agent can write, after the hash (models.py:847). This is the same finding as the earlier disposition (comment), and it is unchanged. The race is real. Catalog weights on main have the same race today, and #16054 is the open fix for that class. This is left for a maintainer decision.

UX blocker (SHA-256 step). The first thing under the box is now a direct link, "Copy the SHA-256 from the file's page on Hugging Face (open the file, it is listed as SHA256)." The terminal commands sit behind an "Or work it out yourself" disclosure.

Screenshot (built SPA, frame 1):

01-custom-configured

02-custom-file-missing

03-custom-pair-incomplete

04-custom-path-refused

05-custom-rows-idle

@iamwhatever

Copy link
Copy Markdown
Contributor Author

/ai-review override gpt b08ec5e: F1 (unquoted copy commands) is fixed and tested; the UX round is fixed. The remaining F2 hash-then-load race at models.py:847 needs an attacker who can already write the models directory on the host, and it is the same hash-then-reopen pattern the model catalog path already ships on main (#16054); this PR adds no new load path. The fd-pinned hash-and-load fix covers both paths and goes in a separate follow-up.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@iamwhatever marked the gpt AI finding as false positive, not applicable, or explicitly accepted for b08ec5ee54670ae813c5b7d54ee7cdeaf805e5a1.

F1 (unquoted copy commands) is fixed and tested; the UX round is fixed. The remaining F2 hash-then-load race at models.py:847 needs an attacker who can already write the models directory on the host, and it is the same hash-then-reopen pattern the model catalog path already ships on main (#16054); this PR adds no new load path. The fd-pinned hash-and-load fix covers both paths and goes in a separate follow-up.

This decision applies only to this commit. A new push requires a new judgment.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Dispositions for the UX review on b08ec5ee54. New head: 1bfcb9b108 (UI copy and layout only).

Blocker. The second row is now labelled "File fingerprint (SHA-256)". Its description is the instruction: "Paste the SHA256 value shown on the model file's download page." The link now reads "Open the file's page on Hugging Face, the model download site, and copy its SHA256."

Watch. The missing-file notice now renders under the file-name row, not after the SHA-256 row. With a built-in model selected, the "Not used while … is selected" note comes before the rows, and the rows are dimmed. The "Ask the agent" wording is unchanged: it is the shared ErrorNotice hand-off used across the dashboard.

Suggestion. Step 2 now reads "Put it in the speech models folder below.", matching the wording in the errors.

Screenshots (built SPA, website/scripts/capture-stt-custom-model.mjs):

01-custom-configured

02-custom-file-missing

03-custom-pair-incomplete

04-custom-path-refused

05-custom-rows-idle

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Disposition for the UX review on 1bfcb9b108. New head: fa81bbec84 (one string).

Blocker. The SHA-256 row's visible description now carries the purpose and the safety line, not only the ⓘ: "Checks the file is the one you downloaded. Paste the SHA256 value shown on its download page. A wrong value is refused; nothing else changes."

Screenshots (built SPA):

01-custom-configured

02-custom-file-missing

03-custom-pair-incomplete

04-custom-path-refused

05-custom-rows-idle

@iamwhatever

Copy link
Copy Markdown
Contributor Author

/ai-review override ux fa81bbe: eight UX rounds on copy and layout only, each fixed and dispositioned; round 8 reverses round 7 (show the hash commands by default vs hide them behind a disclosure), so the lane is not converging; no behavior, accessibility or safety finding is open, and GPT and Opus are clean on this head.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@iamwhatever marked the ux AI finding as false positive, not applicable, or explicitly accepted for fa81bbec841003f9f379a31a948a6393c1cf6422.

eight UX rounds on copy and layout only, each fixed and dispositioned; round 8 reverses round 7 (show the hash commands by default vs hide them behind a disclosure), so the lane is not converging; no behavior, accessibility or safety finding is open, and GPT and Opus are clean on this head.

This decision applies only to this commit. A new push requires a new judgment.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

/ai-review override ux 8c6e463: same copy finding as the override on fa81bbe; this head only rebases and adds sensitive=True with a test, no UI copy changed. Eight prior UX rounds on copy/layout were fixed and dispositioned, and the lane reversed itself (hide vs show the hash commands), so it is not converging; no behavior, accessibility or safety finding is open, and GPT and Opus are clean on this head.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@iamwhatever marked the ux AI finding as false positive, not applicable, or explicitly accepted for 8c6e4638e609bffb257da9d6132b31034bad805e.

same copy finding as the override on fa81bbe; this head only rebases and adds sensitive=True with a test, no UI copy changed. Eight prior UX rounds on copy/layout were fixed and dispositioned, and the lane reversed itself (hide vs show the hash commands), so it is not converging; no behavior, accessibility or safety finding is open, and GPT and Opus are clean on this head.

This decision applies only to this commit. A new push requires a new judgment.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

New head c82bd00fa4: rebased onto main ac8a96a242, still one commit (37 files, +3138/-66).

  • Conflict with fix(sandbox): give the models crew-home leaf a read-only disposition #16054 (models seal) in src/kiro_crew/stt/models.py. The custom path now takes the same load checks as catalog weights: src/kiro_crew/stt/models.py:1013 walks models and the whisper folder (sandbox.require_real_model_path), and :1014 hashes through _sha256_verified_file. A refusal is a failed status flagged refused (:1015).
  • Tests: test/test_stt_custom_model.py:395 (hard-linked file refused, both names kept) and :410 (linked whisper folder refused), POSIX only. Each fails with its check removed.
  • Spec: docs/system-specs/modules/stt-streaming.md:1189. ui-index.generated.json regenerated. No UI copy changed.
  • The description's Known limit section now reflects that fix(sandbox): give the models crew-home leaf a read-only disposition #16054 has landed.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

New head f805c2468b: SHA-256 row copy only, same base ac8a96a242, still one commit (37 files, +3161/-66).

  • The link under the SHA-256 box opens the whisper.cpp repo root, so it is now labelled as that: "Browse whisper.cpp models on Hugging Face" (website/src/i18n/locales/en.manual.json:7994, key custom_model_sha256_browse, used at website/src/pages/settings/SttSettings.tsx:1241).
  • The row's description now leads with where the value comes from: "Paste the SHA-256 shown on the file's download page.", then what it is for (en.manual.json:7993). Same change in all 12 locales; en-XA and both settings registries regenerated.
  • Tests: website/src/test/SttSettings.customModelGuard.test.tsx:193 and :200, both red on the previous copy.
  • Screenshots in the description re-captured from the built SPA. No behaviour, route or SHA-256 check changed; the pin is still required and checked on every load.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

New head a14f86b127: 390b4368aa rebased onto main aaffa10318 after #19126 (Transcribe mixed languages) landed. Still one commit (37 files, +3182/-66).

  • 390b4368aa itself: the SHA-256 row's description drops "A wrong value is refused; nothing else changes", which stays once in its ⓘ hint (website/src/i18n/locales/en.manual.json:7993, all 12 locales; test at website/src/test/SttSettings.customModelGuard.test.tsx:200). The capture harness adds frame 6 with "Or work it out yourself" open (website/scripts/capture-stt-custom-model.mjs:247), attached in the description.
  • Rebase: the conflicts in src/kiro_crew/config/sections.py, docs/system-specs/modules/config.md, website/src/api/client/voice.ts and website/src/pages/settings/SttSettings.tsx were additive, so both sides are kept. ui-index.generated.json was regenerated. Per-file deletions match the original PR.
  • The screenshots in the description still match this head: a pixel compare after the rebase is identical, except shot 4's input border, which differs by one colour level.

stt.model = "custom" runs a whisper.cpp ggml model file the user has placed in
the speech models folder (models/whisper under the Kiro Crew home). Two settings
select it: stt.custom_model_path names the file and stt.custom_model_sha256 pins
it. Nothing is downloaded.

The path must resolve, symlinks followed, to a regular file strictly inside the
models folder. `..`, an absolute path elsewhere and a symlink pointing out are
refused by models.custom_model_file, which runs when the dashboard saves the
field and again on every load. PUT /api/config/stt answers a refused file name
or a malformed digest with a 400 naming the rule, and Settings > Voice shows it
under the rows with the agent hand-off.

The file is hashed on every load and not used unless it matches the digest. A
refused file is left in place, because it is the user's own. Both fields are
owner-only on GET and PUT; config.json is read-only in the agent sandbox, so
the pin cannot be rewritten to match a file an agent placed in the folder.

The catalog's models seal checks apply to the custom file too. The models and
whisper folders must be real directories, and the hash reads one O_NOFOLLOW
descriptor, so a second hard link or a symlinked leaf refuses the load.

A half-configured pair degrades to the default model with a warning. A complete
pair whose file is missing does not degrade: it fails at load with the reason
shown, so a different model is never run in its place.

The digest field accepts a `sha256:` value and a `sha256sum` line, and still
requires exactly 64 hex characters.

Co-authored-by: LuisBrel <193017400+LuisBrel@users.noreply.github.com>
@iamwhatever

Copy link
Copy Markdown
Contributor Author

New head 123542d75a: setup copy only, same base aaffa10318, still one commit (37 files, +3198/-66).

  • Step 1's link now names the site and is the only link to it: "Get a speech model file (.bin) from whisper.cpp on Hugging Face. Each file's page there lists its SHA-256." (website/src/i18n/locales/en.manual.json:8053-8054, rendered at website/src/pages/settings/SttSettings.tsx:1318). The SHA-256 row's own link is gone (SttSettings.tsx:1361).
  • The folded section is now "Work out the SHA-256 yourself" (en.manual.json:8060).
  • Step 3 gives a real file name: "(for example ggml-medium.en-q5_0.bin)" (en.manual.json:8056).
  • All 12 locales are updated and en-XA is regenerated. Tests at website/src/test/SttSettings.customModelGuard.test.tsx:209, :219 and :228 each failed on the previous copy.
  • All six screenshots were re-captured. The harness now uses that real file name.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants