yt-briefing

1import type { EngineInterface, Register } from 'claude-code'
2
3import type { Pending } from '../types'
4import { engine } from './engine.ts'
5
6// The /yt rating loop, in the chat on every surface. Each briefing is the model's whole answer to a
7// prompt this plugin submits, so the summary shows in full in the terminal, the desktop app and on
8// a phone; the rating dialog opens once that turn has ended. Ratings and comments are written by
9// the engine, never by this module.
10
11/** A sweep can expand channels, fetch transcripts and summarize; give it the engine's full budget. */
12const SWEEP_MS = 10 * 60_000
13/** A rating is a file write; a raw comment adds one `claude -p` call to distill it. */
14const RATE_MS = 3 * 60_000
15
16type SweepOut = {
17  status: string
18  summary?: string
19  pending?: Pending
20  lang?: string
21}
22
23/** The engine prints one JSON line on stdout; take the last non-empty line to be safe. */
24function parseOut(stdout: string): SweepOut {
25  const line = stdout.trim().split('\n').filter(Boolean).pop() ?? ''
26  return JSON.parse(line) as SweepOut
27}
28
29/** One engine sweep: the next ratable video, or the end state. Throws when the engine does not answer. */
30async function runSweep($: EngineInterface): Promise<SweepOut> {
31  const run = await $.process.run(engine('yt-sweep'), { timeoutMs: SWEEP_MS })
32  return parseOut(run.stdout)
33}
34
35/** Run the rating engine; on failure toast why and resolve null. */
36async function record($: EngineInterface, args: string[]): Promise<{ rule?: string } | null> {
37  const run = await $.process.run([...engine('yt-rating'), ...args], { timeoutMs: RATE_MS }).catch(err => ({
38    exitCode: 1, stdout: '', stderr: String(err),
39  }))
40  if (run.exitCode !== 0) {
41    $.ui.toast(`Rating not saved: ${run.stderr.trim().slice(0, 200) || 'engine error'}`)
42    return null
43  }
44  let result: { rule?: string } = {}
45  try { result = JSON.parse(run.stdout.trim().split('\n').pop() ?? '{}') } catch { /* rating is on disk */ }
46  return result
47}
48
49/** Give the video to the session as the person's prompt, to research it together. */
50async function handOff($: EngineInterface, p: Pending, summary: string, lang: string | undefined, question?: string) {
51  const transcript = [...engine('yt-transcript'), p.videoId, '--lang', 'auto'].join(' ')
52  const ask = question
53    ? `My question: ${question}`
54    : 'Ask me first what I want to dig into.'
55  await $.prompt.submit({
56    asUser: true,
57    text: [
58      `Let's research this video together: ${p.channel} — "${p.title}" (${p.videoId}, ${p.type}).`,
59      '',
60      'Its briefing:',
61      summary,
62      '',
63      `For anything beyond the briefing, pull the full transcript with \`${transcript}\` and work from the tool result; never paste the transcript into the chat, quote only short passages. Keep what the video claims separate from what you verify yourself, and use whatever the question needs (my project, the web). Answer in ${lang ?? 'English'}.`,
64      ask,
65      '',
66      'If it turns out to be hype, record it with `' + [...engine('yt-rating'), '--rating', '0'].join(' ') + '`; a lasting preference about this channel goes in with `' + [...engine('yt-rating'), '--raw-comment', '"<what to remember>"'].join(' ') + '`.',
67    ].join('\n'),
68  }).catch(err => $.ui.toast(`Could not hand the video to the session: ${String(err)}`))
69}
70
71// A phone or web client draws a plugin's command output and its dialogs, but not its log lines,
72// and it folds text written mid-turn into a one-line digest; only a turn's last message shows whole.
73
74/** True while the chat loop runs; a prompt the person types ends it. */
75let looping = false
76
77/** An answer this soon after its dialog opened is a tap meant for the dialog before it. */
78const STRAY_TAP_MS = 1500
79
80const CHOICES = ['OK', 'Weak', 'Research', 'Stop'] as const
81
82/** What a briefing turn must do, read from the system prompt while the loop runs. */
83function loopSection(reset: boolean): string {
84  const sweep = [...engine('yt-sweep'), ...(reset ? ['--reset'] : [])].join(' ')
85  return [
86    `The yt-briefing plugin is running the person's YouTube briefing. A user message reading exactly "${NEXT_TEXT}" is its request for the next video:`,
87    `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).`,
88    'Otherwise answer with one short line saying why there is nothing to rate. Write in the language of the summaries.',
89  ].join('\n')
90}
91
92/** What the chat shows of each briefing prompt; the instructions ride along as unseen context. */
93const NEXT_TEXT = 'yt: next video'
94
95/** Whether the next briefing prompt starts a fresh sweep. */
96let resetNext = false
97
98/** Ask for a briefing once the hook that wants it has answered: one submitted from inside would wait on it. */
99function submitLater($: EngineInterface, reset: boolean) {
100  resetNext = reset
101  $.clock.after(0, () => void $.prompt.submit({ text: NEXT_TEXT, asUser: true }).catch(err => {
102    looping = false
103    $.ui.toast(`Could not continue the briefing: ${String(err)}`)
104  }))
105}
106
107/** After a briefing turn: ask for the rating, record it and fetch the next one. */
108async function rateAfterTurn($: EngineInterface) {
109  let out: SweepOut
110  try {
111    out = await runSweep($)
112  } catch {
113    looping = false
114    return
115  }
116  if (out.status !== 'rating_needed' || !out.pending || !out.summary) {
117    looping = false
118    return
119  }
120  const title = out.pending.title.length > 80 ? `${out.pending.title.slice(0, 79)}…` : out.pending.title
121  let answer: string
122  for (;;) {
123    const opened = Date.now()
124    try {
125      answer = (await $.ui.ask(`«${title}» — rating?`, { header: 'yt-briefing', options: CHOICES })).trim()
126    } catch {
127      looping = false
128      return
129    }
130    if (!looping) return
131    if (Date.now() - opened >= STRAY_TAP_MS) break
132  }
133
134  if (answer === 'Stop' || answer.toLowerCase() === 'stop' || !answer) {
135    looping = false
136    return
137  }
138  if (answer === 'Research' || answer.startsWith('?')) {
139    looping = false
140    if (!(await record($, ['--rating', '1']))) return
141    const q = answer.startsWith('?') ? answer.slice(1).trim() || undefined : undefined
142    return handOff($, out.pending, out.summary, out.lang, q)
143  }
144  const args = answer === 'OK' ? ['--rating', '1'] : answer === 'Weak' ? ['--rating', '0'] : ['--raw-comment', answer]
145  if (!(await record($, args))) {
146    looping = false
147    return
148  }
149  submitLater($, false)
150}
151
152export const register: Register = on => {
153  on('session.start', async ($, e, next) => {
154    await $.command.register({
155      name: 'yt',
156      description: 'Rate the next videos from the YouTube channels you follow',
157    })
158
159    return next(e)
160  })
161
162  on('command.run', { command: 'yt' }, async ($) => {
163    looping = true
164    submitLater($, true)
165
166    return { text: 'The briefing runs in the chat.' }
167  })
168
169  // The engine shows a plugin none of its own prompts, so a prompt seen here is the person's.
170  on('prompt.submit', async ($, e, next) => {
171    if (looping && e.origin?.kind !== 'plugin') looping = false
172    return next(e)
173  })
174
175  // The loop's instructions ride in the system prompt, so the chat shows only NEXT_TEXT.
176  on('prompt.compose', async ($, e, next) => {
177    const composed = await next(e)
178    if (!looping) return composed
179    return { sections: [...composed.sections, { id: 'yt-briefing:loop', text: loopSection(resetNext), scope: 'session' as const }] }
180  })
181
182  on('turn.complete', async ($, e, next) => {
183    if (looping && !e.agentId && e.reason === 'answer') void rateAfterTurn($)
184    return next(e)
185  })
186}
187

1// How the mod runs the engine, relative to the project root (the session's working directory).
2// This is the dev-clone form; `yt-briefing install-skill` / `init` rewrites it for the project it
3// installs into (the compiled dist/ under node_modules, with the runtime that ran the installer).
4export const engine = (name: string): string[] => ['bun', `src/${name}.ts`]
5

1export type Pending = {
2  channel: string
3  videoId: string
4  title: string
5  type: string
6  publishedAt: string
7}
8