@fastagent-sh/voicenote 0.18.5 → 0.18.7

package/README.md

@@ -113,7 +113,7 @@ Optional settings:
   "VOICENOTE_RECORD_DIR": "/Volumes/VTR6500/RECORD",
   "VOICENOTE_MAX_AGE_HOURS": "48",
   "VOICENOTE_PI_BIN": "pi",
-  "VOICENOTE_PI_PROVIDER": "openai-codex,openai",
+  "VOICENOTE_PI_PROVIDER": "openai-codex",
   "VOICENOTE_PI_MODEL": "gpt-5.5",
   "VOICENOTE_PI_THINKING": "high",
   "VOICENOTE_PI_SUMMARY_TOOLS": "read,grep",
@@ -121,12 +121,16 @@ Optional settings:
 }
 ```
 
-`VOICENOTE_PI_PROVIDER` is a fallback chain, tried left to right. Credentials are
+`VOICENOTE_PI_PROVIDER` is a fallback chain, tried left to right; it defaults to
+`openai-codex` alone. Add the paid API path explicitly (`openai-codex,openai`) if
+you keep an OpenAI key around. Credentials are
 resolved by `pi auth check` (covering OAuth, keys stored by `pi` → `/login`, and
 each provider's own API-key env var). A provider that deterministically cannot
 work — no credentials, or not a provider pi knows — is dropped from the chain,
 because its inevitable "No API key found" would replace the real error from the
-provider that actually failed. If that empties the chain, `vn run --mode notes`
+provider that actually failed. When a chain still fails everywhere, the reported
+error lists every provider's failure, so a fallback's missing key never hides why
+the first provider broke. If pruning empties the chain, `vn run --mode notes`
 skips instead of paying for a transcript whose summary cannot happen.
 `vn doctor` prints the effective chain and the status of anything not ready.
 
@@ -158,6 +162,7 @@ vn run --latest                 # process only the latest valid recording
 vn run --latest --force         # re-run the latest one
 vn run --pdf                    # additionally render a PDF after notes
 vn run --dry-run                # print the plan only
+vn run /path/to/audio.m4a       # process one file by path (skips the scan, ignores age/size/duration filters)
 vn list                         # list this month's notes
 vn list --month 2026-05         # specific month
 vn last                         # print the latest processing summary

package/README.zh-CN.md

@@ -113,7 +113,7 @@ brew install ffmpeg
   "VOICENOTE_RECORD_DIR": "/Volumes/VTR6500/RECORD",
   "VOICENOTE_MAX_AGE_HOURS": "48",
   "VOICENOTE_PI_BIN": "pi",
-  "VOICENOTE_PI_PROVIDER": "openai-codex,openai",
+  "VOICENOTE_PI_PROVIDER": "openai-codex",
   "VOICENOTE_PI_MODEL": "gpt-5.5",
   "VOICENOTE_PI_THINKING": "high",
   "VOICENOTE_PI_SUMMARY_TOOLS": "read,grep",
@@ -121,11 +121,13 @@ brew install ffmpeg
 }
 ```
 
-`VOICENOTE_PI_PROVIDER` 是从左到右尝试的回退链。凭证由 `pi auth check` 判定(覆盖
+`VOICENOTE_PI_PROVIDER` 是从左到右尝试的回退链, 默认只有 `openai-codex`。如果你确实配了
+ OpenAI API key, 可以显式写成 `openai-codex,openai`。凭证由 `pi auth check` 判定(覆盖
 OAuth、`pi` → `/login` 存下的 key、以及各 provider 自己的 API key 环境变量)。
 确定不可能工作的 provider(没凭证, 或 pi 根本不认识这个名字)会被剔除 —— 否则
-它必然抛出的 "No API key found" 会覆盖掉真正失败的那个 provider 的错误。若链因此
-变空, `vn run --mode notes` 会直接跳过, 而不是花钱转写一个注定无法生成纪要的录音。
+它必然抛出的 "No API key found" 会覆盖掉真正失败的那个 provider 的错误。整条链都失败时,
+报错会列出每个 provider 的失败原因, 回退项缺 key 不会再掩盖第一个 provider 的真正错误。
+若剪枝后链变空, `vn run --mode notes` 会直接跳过, 而不是花钱转写一个注定无法生成纪要的录音。
 实际生效的链和非 ready 项的状态由 `vn doctor` 打印。
 
 ## 用法
@@ -138,6 +140,7 @@ vn run --latest                 # 只处理最新有效录音
 vn run --latest --force         # 重跑最新条
 vn run --pdf                    # 生成纪要后额外渲染 PDF
 vn run --dry-run                # 仅列出计划
+vn run /path/to/audio.m4a       # 直接处理单个文件(不扫描目录, 不套用时长/大小/时效过滤)
 vn list                         # 列出本月笔记
 vn list --month 2026-05         # 指定月份
 vn last                         # 打印最新处理摘要

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/voicenote",
-  "version": "0.18.5",
+  "version": "0.18.7",
   "description": "Voice recordings → diarized transcripts → integrated semantic Markdown notes. Currently optimized for the PHILIPS VTR6500 recorder, but the workflow is generic.",
   "type": "module",
   "license": "MIT",

package/src/cli.ts

@@ -8,12 +8,12 @@ import { createHash, createHmac, randomUUID } from 'node:crypto'
 import { appendFile, chmod, mkdir, readFile, writeFile, copyFile, rename, unlink, stat, readdir, rm } from 'node:fs/promises'
 import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, openSync, closeSync, statSync, readSync, unlinkSync, renameSync } from 'node:fs'
 import { dlopen, FFIType, suffix } from 'bun:ffi'
-import { basename, dirname, extname, join } from 'node:path'
+import { basename, dirname, extname, join, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { spawn, spawnSync } from 'node:child_process'
 import os from 'node:os'
 
-const VERSION = '0.18.5'
+const VERSION = '0.18.7'
 const LAUNCH_AGENT_LABEL = 'sh.fastagent.voicenote'
 const LAUNCH_AGENT_LABEL_LEGACY = 'com.kid7st.voicenote' // pre-fastagent installs; cleaned up on install
 const TASK_NAME = 'VoiceNote'   // Windows Task Scheduler name (mac uses LAUNCH_AGENT_LABEL)
@@ -800,6 +800,18 @@ function isCandidateFile(path: string): boolean {
  * treating a half-read device as authoritative would delete live queue entries
  * along with their retry counters.
  */
+async function toRecording(file: string): Promise<Recording> {
+  const st = await stat(file)
+  return {
+    sourcePath: file,
+    sizeBytes: st.size,
+    modifiedAt: st.mtime.toISOString(),
+    durationSeconds: await ffprobeDuration(file),
+    sourceId: await sourceIdFor(file),
+    recordedAt: parseRecordedAt(file),
+  }
+}
+
 async function scanRecordings(config: Config): Promise<{ recordings: Recording[]; complete: boolean }> {
   if (!existsSync(config.recordDir)) return { recordings: [], complete: false }
   const recordings: Recording[] = []
@@ -813,14 +825,7 @@ async function scanRecordings(config: Config): Promise<{ recordings: Recording[]
       if (!st) { complete = false; continue }
       if (!st.isFile()) continue
       try {
-        recordings.push({
-          sourcePath: file,
-          sizeBytes: st.size,
-          modifiedAt: st.mtime.toISOString(),
-          durationSeconds: await ffprobeDuration(file),
-          sourceId: await sourceIdFor(file),
-          recordedAt: parseRecordedAt(file),
-        })
+        recordings.push(await toRecording(file))
       } catch (e) { complete = false; warnSideEffect(`read ${basename(file)} during scan`, e) }
     }
   } catch (e) {
@@ -1620,6 +1625,7 @@ async function chatCompleteViaPiCodex(opts: Omit<Parameters<typeof chatCompleteV
   if (!providers.length) throw new Error(noUsableProviderMessage())
   const maxAttempts = Math.max(1, Number(process.env.VOICENOTE_PI_RETRIES || 3))
   let lastError: any = null
+  const failures: string[] = []
   for (const [idx, provider] of providers.entries()) {
     if (idx > 0) console.error(`pi provider fallback: trying ${provider} after ${providers[idx - 1]} failed: ${lastError?.message || lastError}`)
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -1636,7 +1642,14 @@ async function chatCompleteViaPiCodex(opts: Omit<Parameters<typeof chatCompleteV
         break // non-transient, or retries exhausted → fall back to next provider
       }
     }
-  }
+    failures.push(`${provider}: ${String(lastError?.message || lastError).slice(0, 400)}`)
+  }
+  // Report EVERY provider's error, not just the chain's last one. The last link is
+  // usually the fallback nobody signed into, so its "No API key found for openai"
+  // buried the actual reason openai-codex failed (usage limit, expired token, 5xx)
+  // in the notes stub and in the GUI — which then disagreed with a dashboard that
+  // correctly showed ChatGPT as connected.
+  if (failures.length > 1) throw new Error(`pi summary failed on every provider — ${failures.join(' | ')}`)
   throw lastError || new Error('pi provider fallback exhausted')
 }
 
@@ -2061,9 +2074,10 @@ function pidAlive(pid: number): boolean {
   try { process.kill(pid, 0); return true } catch (e: any) { return e?.code === 'EPERM' }
 }
 
-async function runPipeline(opts: any): Promise<void> {
+async function runPipeline(file: string | undefined, opts: any): Promise<void> {
   wireDailyLog()
   const config = getConfig()
+  opts = { ...opts, file }
   const lock = await acquireRunLock()
   if (!lock) {
     console.log('voicenote pipeline already running; skip')
@@ -2089,21 +2103,30 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
   const interrupted = reconcileInterrupted(store.jobs, nowIso())
   if (interrupted.length) console.log(`Reclaimed ${interrupted.length} job(s) left running by an interrupted run: ${interrupted.slice(0, 3).map(j => j.name).join(', ')}`)
 
-  if (!existsSync(config.recordDir)) {
+  // Explicit file: process exactly that path, wherever it lives. Nothing is
+  // scanned, so the listing is never "complete" (no pruning), and the recorder
+  // filters (age/size/duration) don't apply — the user named the file.
+  const single = opts.file ? resolve(String(opts.file)) : null
+  if (single && !statSync(single, { throwIfNoEntry: false })?.isFile()) throw new Error(`Not a file: ${single}`)
+  if (!single && !existsSync(config.recordDir)) {
     if (shouldLogIdleStatus(`missing:${config.recordDir}`)) {
       console.log(`Idle: recorder not mounted or record dir missing: ${config.recordDir} (repeated idle logs suppressed for 30m)`)
     }
     return
   }
-  const { recordings, complete: scanComplete } = await scanRecordings(config)
+  const { recordings, complete: scanComplete } = single
+    ? { recordings: [await toRecording(single)], complete: false }
+    : await scanRecordings(config)
   const mode = normalizeRunMode(opts)
   const force = Boolean(opts.force)
   const eligible: Recording[] = []
   const skipCounts: Record<string, number> = {}
   const skipSamples: Record<string, string[]> = {}
-  const verboseSkips = Boolean(opts.verbose || opts.dryRun)
+  // An explicitly named file that gets skipped must say why, not fall into the
+  // idle-suppressed silence meant for the 60s scheduler tick.
+  const verboseSkips = Boolean(opts.verbose || opts.dryRun || single)
   const seen = new Set<string>()
-  const limits = limitsOf(config)
+  const limits = single ? { maxAgeHours: 0, minBytes: 0, minDurationSeconds: 0 } : limitsOf(config)
   for (const rec of recordings) {
     seen.add(rec.sourceId)
     const entry = recordFor(store, rec)
@@ -2117,7 +2140,7 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
   // Only prune against a listing we believe to be complete: if the recorder went
   // away mid-glob the scan is partial, and pruning would wipe live queue entries
   // (they'd return on the next scan, but their retry counters would not).
-  const dropped = pruneUnseen(store.jobs, seen, scanComplete && existsSync(config.recordDir))
+  const dropped = pruneUnseen(store.jobs, seen, !single && scanComplete && existsSync(config.recordDir))
   // The only routine path that deletes state — never do it silently.
   if (dropped.length) console.log(`Forgot ${dropped.length} record(s) whose source is no longer on the recorder: ${dropped.slice(0, 3).map(j => j.name).join(', ')}${dropped.length > 3 ? `…(+${dropped.length - 3})` : ''}`)
   const skipSummary = Object.entries(skipCounts).map(([reason, count]) => `${reason}=${count}`).join(', ') || 'none'
@@ -2202,7 +2225,7 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
     }
     // Whole recorder went away — every remaining target would fail the same way
     // and churn ASR-free but noisy retries. Stop and let the next run rescan.
-    if (!existsSync(config.recordDir)) {
+    if (!single && !existsSync(config.recordDir)) {
       console.error(`Recorder disappeared mid-run (${config.recordDir}); stopping. Remaining recordings stay queued.`)
       break
     }
@@ -2902,7 +2925,7 @@ async function dispatchServe(req: any, send: (o: unknown) => void): Promise<void
         // request timeout can't misread it as a wedged engine. Progress shows
         // via the jobs poll; acquireRunLock inside runPipeline dedupes against
         // the scheduler tick and a double-click.
-        void runPipeline({}).catch(e => console.error('manual run failed:', e?.message || e))
+        void runPipeline(undefined, {}).catch(e => console.error('manual run failed:', e?.message || e))
         result = { started: true }
         break
       }
@@ -2986,7 +3009,7 @@ async function serve(): Promise<void> {
 
 const cli = cac('vn')
 
-cli.command('run', 'Scan recorder and process recordings (Volcano ASR + pi notes)')
+cli.command('run [file]', 'Scan recorder and process recordings, or process one audio file by path (Volcano ASR + pi notes)')
   .option('--mode <mode>', 'Output mode: notes (default) | transcript', { default: 'notes' })
   .option('--latest', 'Only process newest eligible recording')
   .option('--force', 'Reprocess already processed recordings')

package/src/piProvider.ts

@@ -1,7 +1,12 @@
 // Which pi providers the summary chain tries. Credential *detection* lives in
 // cli.ts (it shells out to `pi auth check`); only the pure logic is here.
 
-export const DEFAULT_PI_PROVIDERS = ['openai-codex', 'openai']
+// Only the free ChatGPT OAuth path by default. The paid OpenAI API fallback is
+// opt-in (VOICENOTE_PI_PROVIDER='openai-codex,openai', or the GUI dropdown):
+// shipping it in the default chain meant every codex failure was retried against
+// a provider almost nobody has a key for, and that second failure was the one the
+// user saw.
+export const DEFAULT_PI_PROVIDERS = ['openai-codex']
 
 export function defaultPiModel(provider: string): string {
   return provider === 'deepseek' ? 'deepseek-v4-flash' : 'gpt-5.5'