@openparachute/vault 0.7.5-rc.6 → 0.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.5-rc.6",
+  "version": "0.7.5",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/attachment-tickets.test.ts

@@ -270,6 +270,72 @@ describe("attachment tickets — upload lifecycle", () => {
     expect((updatedNote!.metadata as any)?.transcribe_stub).toBe(true);
   });
 
+  // vault#643 — the fresh-install case. Auto-transcribe is ON by default and
+  // no provider is reachable (SCRIBE_URL unset, no scribe row), which is
+  // exactly what a new box looks like. The upload must not come back looking
+  // like an ordinary file: it carries a `failed` status and an actionable
+  // reason, so the state is visible in the API and the admin SPA.
+  test("audio + auto-transcribe on + NO provider → attachment records the failure, not silence", async () => {
+    const vaultName = freshVault("tickets-no-provider");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# Voice memo\n", { path: "memo-noprov" });
+
+    const mint = await callTool(vaultName, "request-attachment-upload", {
+      note: note.id,
+      filename: "memo.webm",
+      size_bytes: 4,
+      // NO `transcribe: true` — this is the AUTO path, the one that used to
+      // silently do nothing.
+    });
+    const res = await routeReq(
+      new Request(mint.url, {
+        method: "PUT",
+        headers: { "content-type": "audio/webm" },
+        body: new Uint8Array([1, 2, 3, 4]),
+      }),
+    );
+    expect(res.status).toBe(201);
+    const attachment = (await res.json()) as any;
+    expect(attachment.metadata.transcribe_status).toBe("failed");
+    expect(attachment.metadata.transcribe_error).toMatch(/no transcription provider configured/i);
+    // The reason has to be actionable — naming both routes out of it.
+    expect(attachment.metadata.transcribe_error).toMatch(/TRANSCRIPTION_PROVIDER/);
+    expect(attachment.metadata.transcribe_error).toMatch(/SCRIBE_URL/);
+    expect(attachment.metadata.transcribe_origin).toBe("auto");
+  });
+
+  // The counter-case: turning auto-transcribe OFF must stay silent. The
+  // operator asked for nothing to happen, so nothing happening is correct and
+  // must not be dressed up as a failure.
+  test("audio + auto-transcribe explicitly OFF → no transcribe metadata at all", async () => {
+    const vaultName = freshVault("tickets-transcribe-off");
+    const store = getVaultStore(vaultName);
+    writeVaultConfig({
+      name: vaultName,
+      api_keys: [],
+      created_at: new Date().toISOString(),
+      auto_transcribe: { enabled: false },
+    } as never);
+    const note = await store.createNote("# Voice memo\n", { path: "memo-off" });
+
+    const mint = await callTool(vaultName, "request-attachment-upload", {
+      note: note.id,
+      filename: "memo.webm",
+      size_bytes: 4,
+    });
+    const res = await routeReq(
+      new Request(mint.url, {
+        method: "PUT",
+        headers: { "content-type": "audio/webm" },
+        body: new Uint8Array([1, 2, 3, 4]),
+      }),
+    );
+    expect(res.status).toBe(201);
+    const attachment = (await res.json()) as any;
+    expect(attachment.metadata.transcribe_status).toBeUndefined();
+    expect(attachment.metadata.transcribe_error).toBeUndefined();
+  });
+
   test("segment_index (voice W2): a valid integer >= 0 rides ticket mint through to the attachment row", async () => {
     const vaultName = freshVault("tickets-segment");
     const store = getVaultStore(vaultName);

package/src/attachment-tickets.ts

@@ -22,7 +22,11 @@ import type { Store } from "../core/src/types.ts";
 import type { AttachmentTicket, AttachmentTicketProvider } from "../core/src/attachment/tickets.ts";
 import { sanitizeAttachmentExtension } from "../core/src/attachment/policy.ts";
 import { assetsDir, readVaultConfig } from "./config.ts";
-import { shouldAutoTranscribe } from "./auto-transcribe.ts";
+import {
+  NO_PROVIDER_ERROR,
+  classifyAutoTranscribe,
+  warnNoTranscriptionProvider,
+} from "./auto-transcribe.ts";
 import { invalidateUsageCache } from "./usage.ts";
 
 function json(data: unknown, status = 200): Response {
@@ -265,7 +269,13 @@ async function handleUploadSpend(
   // auto-transcribe toggle.
   const explicitOptIn = ticket.transcribe === true;
   const perVaultEnabled = readVaultConfig(vaultName)?.auto_transcribe?.enabled;
-  const autoOptIn = !explicitOptIn && shouldAutoTranscribe(ticket.mimeType, { perVaultEnabled });
+  const autoDecision = explicitOptIn
+    ? ({ kind: "transcribe" } as const)
+    : classifyAutoTranscribe(ticket.mimeType, { perVaultEnabled });
+  const autoOptIn = !explicitOptIn && autoDecision.kind === "transcribe";
+  // vault#643 — same honesty as the REST path: enabled-but-unconfigured is a
+  // misconfiguration, not a silent no-op.
+  const transcribeUnavailable = !explicitOptIn && autoDecision.kind === "unavailable";
   const attMeta: Record<string, unknown> = {
     original_name: ticket.filename,
     size: buffer.length,
@@ -280,6 +290,15 @@ async function handleUploadSpend(
     if (ticket.segmentIndex !== undefined) {
       attMeta.segment_index = ticket.segmentIndex;
     }
+  } else if (transcribeUnavailable) {
+    attMeta.transcribe_status = "failed";
+    attMeta.transcribe_error = NO_PROVIDER_ERROR;
+    attMeta.transcribe_requested_at = new Date().toISOString();
+    attMeta.transcribe_origin = "auto";
+    if (ticket.segmentIndex !== undefined) {
+      attMeta.segment_index = ticket.segmentIndex;
+    }
+    warnNoTranscriptionProvider();
   }
 
   const attachment = await store.addAttachment(ticket.noteId, relativePath, ticket.mimeType, attMeta);

package/src/auto-transcribe.test.ts

@@ -6,7 +6,12 @@
  */
 
 import { describe, test, expect } from "bun:test";
-import { shouldAutoTranscribe } from "./auto-transcribe.ts";
+import {
+  _resetNoProviderWarnForTest,
+  classifyAutoTranscribe,
+  shouldAutoTranscribe,
+  warnNoTranscriptionProvider,
+} from "./auto-transcribe.ts";
 
 function readGlobalConfig(enabled: boolean | undefined) {
   return () => ({
@@ -170,3 +175,109 @@ describe("shouldAutoTranscribe", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// vault#643 — "disabled" and "unavailable" are not the same answer.
+//
+// `shouldAutoTranscribe` collapsed both into `false`, so a box with
+// auto-transcribe ON and no reachable provider accepted audio, transcribed
+// nothing, wrote no marker, and logged nothing. The attachment was
+// indistinguishable from a plain upload.
+//
+// That is the DEFAULT state of a fresh install: the provider resolves to
+// `scribe-http`, nothing sets SCRIBE_URL, and voice memos silently never
+// transcribe. The hosted door already marks a terminal state rather than
+// skipping quietly (workers/vault/src/vault-do.ts — "voice not enabled for
+// this plan" / "monthly voice limit reached"); this is the self-host twin.
+// ---------------------------------------------------------------------------
+describe("classifyAutoTranscribe (vault#643)", () => {
+  const audio = "audio/webm";
+  const withProvider = () => "http://127.0.0.1:1943";
+  const noProvider = () => undefined;
+
+  test("non-audio → not-audio, whatever else is true", () => {
+    expect(
+      classifyAutoTranscribe("image/png", { getCachedScribeUrlImpl: withProvider }).kind,
+    ).toBe("not-audio");
+  });
+
+  test("operator turned it off → disabled (silence is CORRECT here)", () => {
+    expect(
+      classifyAutoTranscribe(audio, {
+        perVaultEnabled: false,
+        getCachedScribeUrlImpl: withProvider,
+      }).kind,
+    ).toBe("disabled");
+  });
+
+  test("enabled + no provider → unavailable, NOT disabled — the whole point", () => {
+    expect(
+      classifyAutoTranscribe(audio, {
+        perVaultEnabled: true,
+        getCachedScribeUrlImpl: noProvider,
+      }).kind,
+    ).toBe("unavailable");
+  });
+
+  test("a blank provider URL is unavailable, not a provider", () => {
+    expect(
+      classifyAutoTranscribe(audio, {
+        perVaultEnabled: true,
+        getCachedScribeUrlImpl: () => "   ",
+      }).kind,
+    ).toBe("unavailable");
+  });
+
+  test("the default (no toggle set) with no provider is unavailable — the fresh-install case", () => {
+    expect(
+      classifyAutoTranscribe(audio, {
+        readGlobalConfigImpl: (() => ({})) as never,
+        getCachedScribeUrlImpl: noProvider,
+      }).kind,
+    ).toBe("unavailable");
+  });
+
+  test("enabled + provider → transcribe", () => {
+    expect(
+      classifyAutoTranscribe(audio, {
+        perVaultEnabled: true,
+        getCachedScribeUrlImpl: withProvider,
+      }).kind,
+    ).toBe("transcribe");
+  });
+
+  test("shouldAutoTranscribe stays a faithful boolean view of the classifier", () => {
+    for (const opts of [
+      { perVaultEnabled: false, getCachedScribeUrlImpl: withProvider },
+      { perVaultEnabled: true, getCachedScribeUrlImpl: noProvider },
+      { perVaultEnabled: true, getCachedScribeUrlImpl: withProvider },
+    ]) {
+      expect(shouldAutoTranscribe(audio, opts)).toBe(
+        classifyAutoTranscribe(audio, opts).kind === "transcribe",
+      );
+    }
+  });
+});
+
+describe("warnNoTranscriptionProvider throttle (vault#643)", () => {
+  test("warns once per window — a bulk import gets one line, not a hundred", () => {
+    _resetNoProviderWarnForTest();
+    const seen: string[] = [];
+    const orig = console.warn;
+    console.warn = (...args: unknown[]) => seen.push(String(args[0]));
+    try {
+      let now = 1_000_000;
+      const clock = () => now;
+      for (let i = 0; i < 50; i++) warnNoTranscriptionProvider(clock);
+      expect(seen.length).toBe(1);
+      expect(seen[0]).toMatch(/no transcription provider configured/i);
+      // Past the window → one more.
+      now += 61_000;
+      warnNoTranscriptionProvider(clock);
+      expect(seen.length).toBe(2);
+    } finally {
+      console.warn = orig;
+      _resetNoProviderWarnForTest();
+    }
+  });
+});

package/src/auto-transcribe.ts

@@ -59,12 +59,90 @@ export function shouldAutoTranscribe(
   if (typeof mimeType !== "string" || !mimeType.toLowerCase().startsWith("audio/")) {
     return false;
   }
+  return classifyAutoTranscribe(mimeType, opts).kind === "transcribe";
+}
+
+/**
+ * Why an audio attachment is (or isn't) being transcribed. The three outcomes
+ * are NOT interchangeable, which is the whole point of this type:
+ *
+ *   - `transcribe`  — enqueue it.
+ *   - `disabled`    — the operator turned auto-transcribe off. Silence is
+ *                     correct: they asked for nothing to happen.
+ *   - `unavailable` — auto-transcribe is ON, but no provider is reachable.
+ *                     This is a MISCONFIGURATION, and silence is wrong.
+ *
+ * vault#643: `shouldAutoTranscribe` collapsed the last two into `false`, so a
+ * box with transcription enabled and no reachable provider accepted audio,
+ * transcribed nothing, wrote no marker, logged nothing, and left an attachment
+ * indistinguishable from a plain upload. Observed on a fresh install: the
+ * provider resolves to `scribe-http` by default, nothing sets `SCRIBE_URL`, and
+ * voice memos silently never transcribe.
+ *
+ * The hosted door already gets this right — `workers/vault/src/vault-do.ts`
+ * marks a terminal state ("voice not enabled for this plan", "monthly voice
+ * limit reached") rather than skipping quietly, precisely so the operator never
+ * faces an eternal spinner. This brings self-host to the same posture.
+ */
+export type AutoTranscribeDecision =
+  | { kind: "transcribe" }
+  | { kind: "not-audio" }
+  | { kind: "disabled" }
+  | { kind: "unavailable" };
+
+/** The full decision behind `shouldAutoTranscribe`. Same inputs, more answer. */
+export function classifyAutoTranscribe(
+  mimeType: string,
+  opts: {
+    readGlobalConfigImpl?: typeof readGlobalConfig;
+    getCachedScribeUrlImpl?: () => string | undefined;
+    perVaultEnabled?: boolean;
+    enabledOverride?: boolean;
+  } = {},
+): AutoTranscribeDecision {
+  if (typeof mimeType !== "string" || !mimeType.toLowerCase().startsWith("audio/")) {
+    return { kind: "not-audio" };
+  }
   const enabled = opts.enabledOverride
     ?? opts.perVaultEnabled
     ?? (opts.readGlobalConfigImpl ?? readGlobalConfig)().auto_transcribe?.enabled
     ?? true;
-  if (!enabled) return false;
+  if (!enabled) return { kind: "disabled" };
   const url = (opts.getCachedScribeUrlImpl ?? getCachedScribeUrl)();
-  if (!url || !url.trim()) return false;
-  return true;
+  if (!url || !url.trim()) return { kind: "unavailable" };
+  return { kind: "transcribe" };
+}
+
+/**
+ * The `transcribe_error` written when auto-transcribe is on but no provider is
+ * reachable. Deliberately actionable — the operator needs to know which of the
+ * two things to do, not just that something went wrong.
+ */
+export const NO_PROVIDER_ERROR =
+  "no transcription provider configured — set TRANSCRIPTION_PROVIDER to a local " +
+  "provider (see `parachute-vault transcription install`), or point SCRIBE_URL at " +
+  "a transcription service";
+
+/** Throttle for {@link warnNoTranscriptionProvider}. */
+const NO_PROVIDER_WARN_INTERVAL_MS = 60_000;
+let lastNoProviderWarnAt = 0;
+
+/**
+ * Warn (at most once a minute) that audio is arriving with nowhere to send it.
+ *
+ * Throttled because it fires per-upload: a bulk import of a hundred voice
+ * memos should produce one actionable line, not a hundred. Silence was the old
+ * behaviour and it is what made this invisible — a box can accept audio for
+ * months and never say that transcription isn't wired up.
+ */
+export function warnNoTranscriptionProvider(now: () => number = Date.now): void {
+  const t = now();
+  if (t - lastNoProviderWarnAt < NO_PROVIDER_WARN_INTERVAL_MS) return;
+  lastNoProviderWarnAt = t;
+  console.warn(`[transcribe] audio attachment accepted but ${NO_PROVIDER_ERROR}.`);
+}
+
+/** Test seam: forget the throttle window. */
+export function _resetNoProviderWarnForTest(): void {
+  lastNoProviderWarnAt = 0;
 }

package/src/mirror-routes.ts

@@ -1655,7 +1655,7 @@ export async function applyCredentialsToMirror(
 //     "credentials": null
 //       | { "kind": "pat", "token": "ghp_..." }
 //       | { "kind": "none" },
-//     "enable_sync": true   // optional, DEFAULT TRUE
+//     "enable_sync": false  // optional, DEFAULT FALSE (vault#641)
 //   }
 //
 // `credentials: null` means "use the stored mirror credentials." Passing
@@ -1663,11 +1663,18 @@ export async function applyCredentialsToMirror(
 // for the CLONE, but IS persisted when sync is enabled (it's the push
 // credential for the now-configured mirror).
 //
-// `enable_sync` (vault#416) — DEFAULT TRUE when omitted. After a successful
-// import, auto-enable mirror push-back to the SAME repo, reusing the import's
-// credentials. Makes "import a repo" and "back up to that repo going forward"
-// one fluid flow. The UI ships a checked-by-default checkbox the operator can
-// uncheck. Edge cases (handled in `enableSyncToImportedRepo`, never fail the
+// `enable_sync` — DEFAULT **FALSE** when omitted (vault#641). When explicitly
+// enabled, a successful import also configures mirror push-back to the SAME
+// repo, reusing the import's credentials — "import a repo" and "back up to that
+// repo going forward" in one flow. The UI's checkbox is **unchecked** by default
+// to match.
+//
+// This shipped default-ON in vault#416 and was inverted in vault#641: import is
+// a READ, and defaulting to ON silently made the repo you were reading from into
+// this vault's push target. The full rationale lives at the handler below; keep
+// these two in agreement.
+//
+// Edge cases (handled in `enableSyncToImportedRepo`, never fail the
 // whole import):
 //   - `auth: none` (public repo, no push creds) → skip + warn (can't push
 //     without a credential).

package/src/routes.ts

@@ -145,7 +145,12 @@ import {
 import { join, extname, normalize } from "path";
 import { existsSync, mkdirSync, statSync, unlinkSync, writeFileSync } from "fs";
 import { assetsDir, readGlobalConfig, readVaultConfig } from "./config.ts";
-import { shouldAutoTranscribe } from "./auto-transcribe.ts";
+import {
+  NO_PROVIDER_ERROR,
+  classifyAutoTranscribe,
+  shouldAutoTranscribe,
+  warnNoTranscriptionProvider,
+} from "./auto-transcribe.ts";
 // usage.ts imports `assetsDir` from config.ts (neutral ground), so this import
 // of invalidateUsageCache does NOT form a cycle — routes.ts → usage.ts only.
 import { invalidateUsageCache } from "./usage.ts";
@@ -2369,7 +2374,18 @@ async function handleNotesInner(
       const perVaultEnabled = vault
         ? readVaultConfig(vault)?.auto_transcribe?.enabled
         : undefined;
-      const autoOptIn = !explicitOptIn && shouldAutoTranscribe(body.mimeType, { perVaultEnabled });
+      // vault#643: classify rather than collapse to a boolean. "Operator
+      // turned it off" and "nothing is configured to do it" both used to read
+      // as `false`, so a misconfigured box silently accepted audio and
+      // transcribed nothing — no marker, no status, no log.
+      const autoDecision = explicitOptIn
+        ? ({ kind: "transcribe" } as const)
+        : classifyAutoTranscribe(body.mimeType, { perVaultEnabled });
+      const autoOptIn = !explicitOptIn && autoDecision.kind === "transcribe";
+      // Enabled, audio, but no reachable provider. Record it on the attachment
+      // so the state is visible in the API and the admin SPA instead of the
+      // upload looking like an ordinary file.
+      const transcribeUnavailable = !explicitOptIn && autoDecision.kind === "unavailable";
       // Per-segment slots (voice W2, cloud twin: workers/vault/src/rest/notes.ts
       // ~791-800): an optional `segment_index` (integer >= 0) lets one recording
       // split across several attachments on ONE note, each resolving into its
@@ -2385,7 +2401,16 @@ async function handleNotesInner(
             transcribe_origin: (explicitOptIn ? "legacy" : "auto") as "legacy" | "auto",
             ...(validSegment ? { segment_index: segIdx } : {}),
           }
-        : undefined;
+        : transcribeUnavailable
+          ? {
+              transcribe_status: "failed" as const,
+              transcribe_error: NO_PROVIDER_ERROR,
+              transcribe_requested_at: new Date().toISOString(),
+              transcribe_origin: "auto" as const,
+              ...(validSegment ? { segment_index: segIdx } : {}),
+            }
+          : undefined;
+      if (transcribeUnavailable) warnNoTranscriptionProvider();
 
       const attachment = await store.addAttachment(note.id, body.path, body.mimeType, attMeta);
 

package/src/routing.ts

@@ -118,6 +118,10 @@ import {
   handleMirrorRunNow,
 } from "./mirror-routes.ts";
 import { handleEmbeddingsGet, handleEmbeddingsPut } from "./embeddings-routes.ts";
+import {
+  handleTranscriptionGet,
+  handleTranscriptionPut,
+} from "./transcription-routes.ts";
 import { getMirrorManager } from "./mirror-registry.ts";
 import { buildUsageReport } from "./usage.ts";
 import { handleTicketSpend } from "./attachment-tickets.ts";
@@ -716,6 +720,38 @@ export async function route(
     return Response.json({ error: "Method not allowed" }, { status: 405 });
   }
 
+  // /.parachute/transcription — Admin-gated read+write of the transcription
+  // setup. Mirrors the embeddings toggle's shape (persist a preference, report
+  // `restart_required`) but answers a harder question: transcription can be
+  // "configured" and still not work, because it needs a binary and a model on
+  // disk that no config file can promise are there.
+  //
+  // So GET reports readiness with the missing PIECE named, the paths searched,
+  // and the exact command that fixes it. That's the gap this closes: a box
+  // could accept audio for weeks and transcribe nothing, with the only evidence
+  // a boot log line the operator scrolled past (vault#643).
+  //
+  // PUT persists provider/model only — installing downloads hundreds of MB and
+  // shells brew/tar, which belongs in the CLI with a progress bar, not in a
+  // request a browser tab can abandon. See transcription-routes.ts.
+  if (subpath === "/.parachute/transcription") {
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    if (req.method === "GET") return handleTranscriptionGet();
+    if (req.method === "PUT") return handleTranscriptionPut(req);
+    return Response.json({ error: "Method not allowed" }, { status: 405 });
+  }
+
   // The per-vault `/tokens` REST surface (pvt_* mint/list/revoke) was removed
   // at 0.5.0 (vault#282 Stage 2 — vault is a pure hub resource-server). Hub
   // JWTs are minted via hub's registry (`/api/auth/mint-token`); a `/tokens`

package/src/server.ts

@@ -279,7 +279,20 @@ if (providerName === "whisper-cpp") {
     wireTranscriptionWorker(transcriptionWorker);
     console.log(`[transcribe] worker started → ${scribeUrl}`);
   } else {
-    console.log("[transcribe] worker disabled (no scribe in services.json and SCRIBE_URL unset)");
+    // vault#643: was a console.log reading "worker disabled", which states a
+    // fact about the worker and says nothing about the CONSEQUENCE. On a fresh
+    // box the provider resolves to `scribe-http` by default and nothing sets
+    // SCRIBE_URL, so this is the DEFAULT state — and audio silently never
+    // transcribes. Name the consequence, and warn rather than log, because the
+    // box is misconfigured for a feature that is on by default.
+    console.warn(
+      "[transcribe] NO transcription provider is reachable — audio attachments " +
+        "will be accepted but never transcribed. " +
+        `Provider resolved to "${providerName}". Fix with either: ` +
+        "`parachute-vault transcription install` + TRANSCRIPTION_PROVIDER=<local provider>, " +
+        "or point SCRIBE_URL at a transcription service. " +
+        "Set `auto_transcribe.enabled: false` to silence this if you don't want transcription.",
+    );
   }
 }