yt-briefing 1.3.2 → 1.3.4

package/dist/cli.js

@@ -10,6 +10,7 @@
  *   yt-briefing add|remove <@handle|url>   add or remove channels (also list)
  *   yt-briefing list                       list the channels you follow
  *   yt-briefing sweep [--reset]            advance one step; prints a JSON status line
+ *   yt-briefing sweep --pending            read-only: the video already shown and not yet rated
  *   yt-briefing rate --rating 0|1 [...]    record a rating for the pending video
  *   yt-briefing transcribe <url|id>        print a single video's transcript
  *   yt-briefing search "<intent>" --channel <@handle|url>   search within one channel → triage → compare

package/dist/lib/paths.js

@@ -54,6 +54,7 @@ export const REST_FILE = join(CACHE_DIR, 'queue-rest.json');
 export const PENDING_FILE = join(CACHE_DIR, 'pending.json');
 export const PREFETCH_FILE = join(CACHE_DIR, 'prefetch.json');
 export const LOG_FILE = join(CACHE_DIR, 'sweep.log');
+export const VIDEO_DATES_FILE = join(CACHE_DIR, 'video-dates.json'); // videoId → publishedAt, for the monotonic pointer
 // /yt-search (ad-hoc topic search → lazy triage → compare). All throwaway, under .cache/.
 export const SEARCH_QUEUE_FILE = join(CACHE_DIR, 'search-queue.json'); // ranked candidates + cursor
 export const SEARCH_PENDING_FILE = join(CACHE_DIR, 'search-pending.json'); // current candidate awaiting keep/skip

package/dist/lib/video-dates.js

@@ -0,0 +1,45 @@
+/**
+ * Publish dates of every video the sweep has listed, so a state pointer bump can refuse to
+ * move back in time (see pointerWouldRegress). Kept across --reset: the pointer outlives the
+ * queue. Best-effort cache — a missing or corrupt file only turns the guard off.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { VIDEO_DATES_FILE } from "./paths.js";
+/** Entries older than this are dropped on write; the channel listing looks back 45 days. */
+const KEEP_DAYS = 120;
+export function loadVideoDates() {
+    if (!existsSync(VIDEO_DATES_FILE))
+        return {};
+    try {
+        const d = JSON.parse(readFileSync(VIDEO_DATES_FILE, 'utf8'));
+        return d && typeof d === 'object' ? d : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Merge newly seen videos into the cache (atomic write); no-op when nothing is new. */
+export function rememberVideoDates(videos) {
+    const dates = loadVideoDates();
+    let changed = false;
+    for (const v of videos) {
+        if (!v.publishedAt || !Number.isFinite(Date.parse(v.publishedAt)) || dates[v.videoId] === v.publishedAt)
+            continue;
+        dates[v.videoId] = v.publishedAt;
+        changed = true;
+    }
+    if (!changed)
+        return;
+    const cutoff = Date.now() - KEEP_DAYS * 24 * 60 * 60 * 1000;
+    for (const [id, at] of Object.entries(dates))
+        if (Date.parse(at) < cutoff)
+            delete dates[id];
+    try {
+        mkdirSync(dirname(VIDEO_DATES_FILE), { recursive: true });
+        const tmp = `${VIDEO_DATES_FILE}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(dates));
+        renameSync(tmp, VIDEO_DATES_FILE);
+    }
+    catch { /* best-effort: the guard is only off for dates not written */ }
+}

package/dist/lib/yt-lib.js

@@ -46,6 +46,24 @@ export function parseState(content) {
 export function bumpStateFrontmatterDate(content, date) {
     return content.replace(/^updated:\s*\d{4}-\d{2}-\d{2}/m, `updated: ${date}`);
 }
+/** The state pointer of one type for a channel row (null when unset or the row is missing). */
+export function pointerFor(row, type) {
+    if (!row)
+        return null;
+    return type === 'longform' ? row.last_longform_id : type === 'short' ? row.last_short_id : row.last_live_id;
+}
+/**
+ * Would moving the pointer from `pointerId` to `videoId` move it back in time? `dates` maps
+ * videoIds to publishedAt. Unknown dates answer false (bump as before): only a known older
+ * video is refused. A stale skip applied after the pointer moved on used to rewind it, and
+ * the next queue listed already-rated videos again.
+ */
+export function pointerWouldRegress(pointerId, videoId, publishedAt, dates) {
+    if (!pointerId || pointerId === videoId || !publishedAt)
+        return false;
+    const at = dates[pointerId];
+    return !!at && Date.parse(at) > Date.parse(publishedAt);
+}
 /**
  * Per-video pointer bump. Updates one type's last_id for one channel.
  * Session counter increments only on first touch of the day (updated != date).

package/dist/yt-channel-pending.js

@@ -19,6 +19,7 @@ import { loadEnv } from "./lib/env.js";
 import { parseState } from "./lib/yt-lib.js";
 import { STATE_MD } from "./lib/paths.js";
 import { fetchChannelVideos } from "./lib/yt-api.js";
+import { loadVideoDates, rememberVideoDates } from "./lib/video-dates.js";
 loadEnv();
 const handle = process.argv[2];
 if (!handle) {
@@ -47,6 +48,10 @@ catch (e) {
     console.error(e.message);
     process.exit(1);
 }
+// Date cache read before this listing is added, so a pointer that left the window still has its
+// old date; then every listed video (the pointer too) is remembered for the monotonic bump.
+const videoDates = loadVideoDates();
+rememberVideoDates(videos);
 const pointerByType = {
     longform: row.last_longform_id,
     short: row.last_short_id,
@@ -74,10 +79,12 @@ for (const type of ['longform', 'short', 'live']) {
     }
     // normal: find pointer's publishedAt, take everything strictly newer
     const pointerVideo = ofType.find(v => v.videoId === pointerId);
+    // Pointer not in the fetched window: older than the lookback, or deleted/unlisted. Its date
+    // from the sweep's cache keeps already-seen videos out; without one, take the whole window.
+    const cachedTs = Date.parse(videoDates[pointerId] ?? '');
     const cutoffTs = pointerVideo
         ? new Date(pointerVideo.publishedAt).getTime()
-        : // pointer not in fetched window (older than --since cutoff) — take all videos of this type from response
-            -Infinity;
+        : Number.isFinite(cachedTs) ? cachedTs : -Infinity;
     for (const v of ofType) {
         if (new Date(v.publishedAt).getTime() <= cutoffTs)
             continue;

package/dist/yt-rating.js

@@ -27,7 +27,8 @@ import { spawn } from 'node:child_process';
 import { loadEnv } from "./lib/env.js";
 import { loadConfig } from "./lib/config.js";
 import { distillComment } from "./lib/distill.js";
-import { parseChannels, appendSkipTitle, appendNote, bumpStatePointer } from "./lib/yt-lib.js";
+import { parseChannels, parseState, appendSkipTitle, appendNote, bumpStatePointer, pointerFor, pointerWouldRegress } from "./lib/yt-lib.js";
+import { loadVideoDates } from "./lib/video-dates.js";
 import { CHANNELS_MD, STATE_MD, PENDING_FILE, QUEUE_FILE, profilePath } from "./lib/paths.js";
 loadEnv();
 function getArg(args, name) {
@@ -123,7 +124,14 @@ if (profileAfter !== profileBefore) {
 let stateBumped = false;
 if (!args.noState) {
     const stateBefore = readFileSync(STATE_MD, 'utf8');
-    const stateAfter = bumpStatePointer(stateBefore, args.channel, args.type, args.id, date);
+    // An older video rated after a newer one of the same channel was title-skipped must not
+    // rewind the pointer; the date comes from the sweep's cache of listed videos.
+    const pointer = pointerFor(parseState(stateBefore).find(r => r.handle === args.channel), args.type);
+    const dates = loadVideoDates();
+    const publishedAt = dates[args.id] ?? (() => { const p = loadPending(); return p.videoId === args.id ? p.publishedAt : undefined; })();
+    // Never rewind: re-bump the current pointer instead, so the day's session still counts.
+    const regress = pointer !== null && pointerWouldRegress(pointer, args.id, publishedAt, dates);
+    const stateAfter = bumpStatePointer(stateBefore, args.channel, args.type, regress ? pointer : args.id, date);
     if (stateAfter !== stateBefore) {
         writeFileSync(STATE_MD, stateAfter, 'utf8');
         stateBumped = true;

package/dist/yt-sweep.js

@@ -8,12 +8,14 @@
  *
  * Usage:
  *   bun src/yt-sweep.ts [--reset]
+ *   bun src/yt-sweep.ts --pending              (read-only: the video already emitted, still unrated)
  *   bun src/yt-sweep.ts --prefetch <videoId>   (internal: detached next-video warmup)
  *   bun src/yt-sweep.ts --fill                 (internal: detached queue builder)
  *
  * Output (stdout, single JSON line):
  *   {"status":"rating_needed","summary":"<md>","pending":{channel,videoId,title,type,publishedAt,is_baseline}}  (+ "lang")
  *   {"status":"done"}
+ *   {"status":"no_pending"}  (--pending only: no emitted video awaits a rating)
  *   {"status":"rate_limited"}
  *
  * The engine ONLY writes files under DATA_DIR — it never runs git or any VCS. If you
@@ -51,7 +53,8 @@
 import { readFileSync, writeFileSync, existsSync, rmSync, mkdirSync, renameSync, appendFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { loadEnv, missingEnv, missingEnvMessage, REQUIRED_YOUTUBE } from "./lib/env.js";
-import { parseChannels, parseState, bumpStatePointer, isResolved } from "./lib/yt-lib.js";
+import { parseChannels, parseState, bumpStatePointer, isResolved, pointerFor, pointerWouldRegress } from "./lib/yt-lib.js";
+import { loadVideoDates, rememberVideoDates } from "./lib/video-dates.js";
 import { chat, claudeMissing } from "./lib/llm.js";
 import { outputLang } from "./lib/config.js";
 import { PKG_ROOT, CHANNELS_MD, STATE_MD, CACHE_DIR, QUEUE_FILE, REST_FILE, PENDING_FILE, PREFETCH_FILE, LOG_FILE, profilePath, script, } from "./lib/paths.js";
@@ -67,6 +70,7 @@ const CONCURRENCY = 6;
 const argv = process.argv.slice(2);
 const reset = argv.includes('--reset');
 const fillMode = argv.includes('--fill');
+const pendingMode = argv.includes('--pending');
 const pfIdx = argv.indexOf('--prefetch');
 const prefetchTarget = pfIdx !== -1 ? argv[pfIdx + 1] : null;
 const today = new Date().toISOString().slice(0, 10);
@@ -105,9 +109,14 @@ function run(cmd) {
     });
 }
 // ---------- state mutation (inline, crash-safe per write) ----------
-function bumpState(handle, type, videoId) {
+function bumpState(handle, type, videoId, publishedAt) {
     const before = readFileSync(STATE_MD, 'utf8');
-    const after = bumpStatePointer(before, handle, type, videoId, today);
+    const pointer = pointerFor(parseState(before).find(r => r.handle === handle), type);
+    // Never rewind: re-bump the current pointer instead, so the day's session still counts.
+    const regress = pointer !== null && pointerWouldRegress(pointer, videoId, publishedAt, loadVideoDates());
+    if (regress)
+        log(`pointer kept ${handle} ${type} ${pointer} (not rewound to older ${videoId})`);
+    const after = bumpStatePointer(before, handle, type, regress ? pointer : videoId, today);
     if (after !== before)
         writeFileSync(STATE_MD, after, 'utf8');
 }
@@ -117,20 +126,23 @@ function bumpState(handle, type, videoId) {
  */
 function persistSkip(item, status) {
     if (status !== 'no_transcript')
-        bumpState(item.channel, item.type, item.videoId);
+        bumpState(item.channel, item.type, item.videoId, item.publishedAt);
 }
 /**
- * Apply title-skips to state.md. Always bumps the pointer (a title-skip is final).
+ * Apply title-skips to state.md. Bumps the pointer (a title-skip is final) unless that would
+ * rewind it: a background fill's skips are listed against the pointer it saw when it started.
  * Idempotent — re-applying the same skip is a no-op. ONLY the foreground calls this.
  */
 function applyTitleSkips(skips) {
+    rememberVideoDates(skips);
     for (const s of skips) {
-        bumpState(s.channel, s.type, s.videoId);
+        bumpState(s.channel, s.type, s.videoId, s.publishedAt);
         recordSkip({ stage: 'title', channel: s.channel, videoId: s.videoId, title: s.title, reason: s.reason || 'title filter' });
     }
 }
 /** Append items, skipping any videoId already queued OR already resolved (seen). */
 function enqueue(queue, add) {
+    rememberVideoDates(add);
     const have = new Set([...queue.items.map(i => i.videoId), ...queue.seen]);
     for (const it of add)
         if (!have.has(it.videoId)) {
@@ -341,7 +353,7 @@ async function expandChannel(ref) {
     const skips = [];
     for (const it of candidates) {
         if (titleSkip.has(it.videoId))
-            skips.push({ channel: it.channel, type: it.type, videoId: it.videoId, title: it.title, reason: titleSkip.get(it.videoId) || 'title filter' });
+            skips.push({ channel: it.channel, type: it.type, videoId: it.videoId, title: it.title, reason: titleSkip.get(it.videoId) || 'title filter', publishedAt: it.publishedAt });
         else
             items.push(it);
     }
@@ -421,11 +433,7 @@ function loadQueue() {
 // ---------- advance (the lazy step) ----------
 /** state.md pointer for this item's type, or null if the channel has no row yet. */
 function statePointer(item) {
-    const row = parseState(readFileSync(STATE_MD, 'utf8')).find(r => r.handle === item.channel);
-    if (!row)
-        return null;
-    return item.type === 'longform' ? row.last_longform_id
-        : item.type === 'short' ? row.last_short_id : row.last_live_id;
+    return pointerFor(parseState(readFileSync(STATE_MD, 'utf8')).find(r => r.handle === item.channel), item.type);
 }
 /**
  * Pure-ish pipeline for one queue item: fetch transcript → substance check + summary.
@@ -453,6 +461,13 @@ async function processItem(item) {
         return { kind: 'skip', status: 'content_skip', reason: summary.slice(9).trim() };
     return { kind: 'ratable', summary };
 }
+/** The video's metadata as `rating_needed` reports it and yt-rating reads it from pending.json. */
+function pendingOf(item) {
+    return {
+        channel: item.channel, videoId: item.videoId, title: item.title,
+        type: item.type, publishedAt: item.publishedAt, is_baseline: item.is_baseline,
+    };
+}
 async function advance(queue) {
     while (true) {
         // Pull in the background fill (or expand a channel ourselves) until there's an
@@ -467,8 +482,8 @@ async function advance(queue) {
             dropHead(queue);
             continue;
         }
-        // Already emitted (the plugin re-runs the sweep after the briefing turn to open the rating
-        // dialog) or warmed by the background child? Use it and skip the live fetch + content filter.
+        // Already emitted (a repeat sweep before the rating) or warmed by the background child? Use it
+        // and skip the live fetch + content filter.
         const emitted = loadCachedSummary(PENDING_FILE, item.videoId);
         const cached = emitted ?? loadPrefetch(item.videoId);
         if (cached)
@@ -492,10 +507,7 @@ async function advance(queue) {
         }
         // Ratable — hand off to the frontend. Leave item at queue head (rating bumps state,
         // next call detects pointer === videoId and drops it).
-        const pending = {
-            channel: item.channel, videoId: item.videoId, title: item.title,
-            type: item.type, publishedAt: item.publishedAt, is_baseline: item.is_baseline,
-        };
+        const pending = pendingOf(item);
         writeAtomic(PENDING_FILE, { ...pending, summary: result.summary, built_at: today });
         writeFileSync(QUEUE_FILE, JSON.stringify(queue));
         // Warm the NEXT video in the background while the user rates this one. A repeat emit of the
@@ -511,6 +523,21 @@ async function advance(queue) {
     clearPrefetch();
     emit({ status: 'done' });
 }
+/**
+ * --pending mode: the video the sweep already emitted, if it still awaits a rating. The plugin asks
+ * this after a briefing turn to open the rating dialog. Read-only and offline on purpose: a real
+ * sweep there rebuilt the queue once `done` had removed it, and the dialog then asked about a new
+ * video the chat never showed.
+ */
+function runPending() {
+    const queue = loadQueue();
+    const head = queue?.items[0];
+    const summary = head && loadCachedSummary(PENDING_FILE, head.videoId);
+    if (!queue || !head || !summary || isResolved(statePointer(head), head.videoId, queue.seen)) {
+        emit({ status: 'no_pending' });
+    }
+    emit({ status: 'rating_needed', summary, pending: pendingOf(head), lang: LANG });
+}
 /**
  * --prefetch mode: compute the summary for one specific queued video and cache it, with
  * NO side effects on state.md / queue / pending. Runs detached while the user rates the
@@ -568,6 +595,9 @@ if (prefetchTarget) {
 if (fillMode) {
     await runFill(); // detached background queue builder — never returns
 }
+if (pendingMode) {
+    runPending(); // read-only answer for the rating dialog — never returns
+}
 if (reset) {
     if (existsSync(QUEUE_FILE))
         rmSync(QUEUE_FILE);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yt-briefing",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "A self-learning YouTube briefing for Claude Code: it sweeps the channels you follow, filters noise in two stages (title, then transcript), gives you a short briefing of the rest in your language in the chat, and adapts to your ratings — one video at a time.",
   "type": "module",
   "bin": {

package/plugin/hooks/register.tsx

@@ -8,8 +8,10 @@ import { engine } from './engine.ts'
 // a phone; the rating dialog opens once that turn has ended. Ratings and comments are written by
 // the engine, never by this module.
 
-/** A sweep can expand channels, fetch transcripts and summarize; give it the engine's full budget. */
+/** A sweep can expand channels, fetch transcripts and summarize; the model's call gets this budget. */
 const SWEEP_MS = 10 * 60_000
+/** Local files only, no network. */
+const PENDING_MS = 30_000
 /** A rating is a file write; a raw comment adds one `claude -p` call to distill it. */
 const RATE_MS = 3 * 60_000
 
@@ -26,9 +28,9 @@ function parseOut(stdout: string): SweepOut {
   return JSON.parse(line) as SweepOut
 }
 
-/** One engine sweep: the next ratable video, or the end state. Throws when the engine does not answer. */
-async function runSweep($: EngineInterface): Promise<SweepOut> {
-  const run = await $.process.run(engine('yt-sweep'), { timeoutMs: SWEEP_MS })
+/** The video this run already showed and not yet rated. Never a real sweep: that could fetch a new one. */
+async function shownVideo($: EngineInterface): Promise<SweepOut> {
+  const run = await $.process.run([...engine('yt-sweep'), '--pending'], { timeoutMs: PENDING_MS })
   return parseOut(run.stdout)
 }
 
@@ -93,7 +95,7 @@ function loopSection(): string {
   const sweep = engine('yt-sweep').join(' ')
   return [
     `The yt-briefing plugin is running the person's YouTube briefing. A user message reading exactly "${FIRST_TEXT}" or "${NEXT_TEXT}" is its request for the next video:`,
-    `for "${FIRST_TEXT}" run \`${sweep} --reset\`, for "${NEXT_TEXT}" run \`${sweep}\`; it prints one JSON line. If \`status\` is \`rating_needed\`, answer with \`summary\` verbatim as your whole message, Markdown kept: nothing before or after it, no question, no tool call after it (the plugin opens the rating dialog itself).`,
+    `for "${FIRST_TEXT}" run \`${sweep} --reset\`, for "${NEXT_TEXT}" run \`${sweep}\`, in the foreground with a ${SWEEP_MS / 60_000}-minute timeout; it prints one JSON line. If \`status\` is \`rating_needed\`, answer with \`summary\` verbatim as your whole message, Markdown kept: nothing before or after it, no question, no tool call after it (the plugin opens the rating dialog itself).`,
     'Otherwise answer with one short line saying why there is nothing to rate. Write in the language of the summaries.',
   ].join('\n')
 }
@@ -110,9 +112,10 @@ function submitLater($: EngineInterface, reset: boolean) {
 async function rateAfterTurn($: EngineInterface) {
   let out: SweepOut
   try {
-    out = await runSweep($)
-  } catch {
+    out = await shownVideo($)
+  } catch (err) {
     looping = false
+    $.ui.toast(`Could not open the rating: ${String(err).slice(0, 200)}`)
     return
   }
   if (out.status !== 'rating_needed' || !out.pending || !out.summary) {