prompt-offload

1import type { EngineInterface, PromptOrigin, Register } from 'claude-code'
2import { DEFAULT_LIMIT, MIN_LIMIT, fileName, isLong, limitOf, logText, offloadText } from './offload.ts'
3
4const ENABLED_KEY = 'enabled'
5const LIMIT_KEY = 'limit'
6
7const USAGE = `expects nothing (the status), on, off or limit <n> (at least ${MIN_LIMIT})`
8
9type State = { enabled: boolean; limit: number; lastError?: string }
10
11/** The person's own prompts: typed at the terminal or sent from a phone. */
12function isPersons(origin: PromptOrigin): boolean {
13  return origin.kind === 'composer' || origin.kind === 'bridge'
14}
15
16function errorText(err: unknown): string {
17  return err instanceof Error ? err.message : String(err)
18}
19
20/** Logs an error once until a different one comes; the prompt itself is never dropped. */
21function report($: EngineInterface, state: State, err: unknown): void {
22  const text = errorText(err)
23  if (text !== state.lastError) $.ui.log(`the prompt was left as it is: ${text}`)
24  state.lastError = text
25}
26
27/** The directory the files go in, made when it is missing. */
28async function tempDir($: EngineInterface): Promise<string> {
29  const dir = `${((await $.env.get('TMPDIR')) ?? '/tmp').replace(/\/+$/, '')}/prompt-offload`
30  const made = await $.process.run(['mkdir', '-p', dir], { timeoutMs: 5_000 })
31  if (made.exitCode !== 0) throw new Error(`mkdir ${dir} failed: ${made.stderr.trim()}`)
32  return dir
33}
34
35/** Writes the whole prompt to a file and answers the text the model reads, or the prompt unchanged. */
36async function offload($: EngineInterface, state: State, text: string): Promise<string> {
37  try {
38    const path = `${await tempDir($)}/${fileName(text, await $.clock.now())}`
39    await $.fs.write(path, text)
40    $.ui.log(logText(text, path))
41    return offloadText(text, path)
42  } catch (err) {
43    report($, state, err)
44    return text
45  }
46}
47
48async function setLimit($: EngineInterface, state: State, arg: string): Promise<string> {
49  const limit = limitOf(arg)
50  if (limit === undefined) return `limit expects a whole number of at least ${MIN_LIMIT}`
51  await $.store.set(LIMIT_KEY, limit)
52  state.limit = limit
53  return `limit ${limit}: a prompt longer than that goes to a file`
54}
55
56async function setEnabled($: EngineInterface, state: State, on: boolean): Promise<string> {
57  await $.store.set(ENABLED_KEY, on)
58  state.enabled = on
59  return on ? `on: a prompt over ${state.limit} characters goes to a file` : 'off: every prompt reaches the model as it is'
60}
61
62/**
63 * Reads the on/off setting and the limit from the store, which every window shares, so a change made in
64 * another window applies here at the next hook that acts on it.
65 */
66async function readSettings($: EngineInterface, state: State): Promise<void> {
67  state.enabled = (await $.store.get(ENABLED_KEY)) !== false
68  state.limit = Number(await $.store.get(LIMIT_KEY)) || DEFAULT_LIMIT
69}
70
71async function runCommand($: EngineInterface, state: State, args: string): Promise<string> {
72  const [word = '', arg = ''] = args.trim().split(/\s+/)
73  await readSettings($, state)
74  if (word === 'on' || word === 'off') return setEnabled($, state, word === 'on')
75  if (word === 'limit') return setLimit($, state, arg)
76  return word === '' ? `${state.enabled ? 'on' : 'off'} · limit ${state.limit} characters` : USAGE
77}
78
79export const register: Register = on => {
80  const state: State = { enabled: true, limit: DEFAULT_LIMIT }
81
82  on('session.start', async ($, e, next) => {
83    const r = await next(e)
84    await $.command.register({ name: 'prompt-offload', description: 'Long pasted prompts to a file: status, on, off, limit <n> (prompt-offload)', argumentHint: '[on | off | limit <n>]' })
85    await readSettings($, state)
86    return r
87  })
88
89  // The engine prints the plugin name in front of command text and log lines, so the texts do not repeat it.
90  on('command.run', { command: 'prompt-offload' }, async ($, e) => ({ text: await runCommand($, state, String(e.args ?? '')) }))
91
92  on('prompt.submit', async ($, e, next) => {
93    if (!isPersons(e.origin)) return next(e)
94    await readSettings($, state)
95    if (!state.enabled || !isLong(e.text, state.limit)) return next(e)
96    return next({ ...e, text: await offload($, state, e.text) })
97  })
98}
99

1/** Which prompt is too long, where its file goes, and what the model reads in its place. */
2
3/** The prompt is offloaded above this many characters, until a /prompt-offload limit says otherwise. */
4export const DEFAULT_LIMIT = 2000
5
6/** A limit under this keeps too little of the prompt to be worth a file. */
7export const MIN_LIMIT = 500
8
9/** How many characters of the prompt stay in the message. */
10export const HEAD = 200
11
12/** A name for the file, from the prompt and the time it was sent, FNV-1a 32. */
13export function fileName(text: string, now: number): string {
14  let h = 0x811c9dc5
15  for (const ch of `${text}\0${now}`) h = Math.imul(h ^ (ch.codePointAt(0) ?? 0), 0x01000193) >>> 0
16  return `${h.toString(16).padStart(8, '0')}.txt`
17}
18
19/** The start of the prompt, cut at the last line break of the head when there is one. */
20export function head(text: string, count = HEAD): string {
21  const cut = text.slice(0, count)
22  const line = cut.lastIndexOf('\n')
23  return (line > count / 2 ? cut.slice(0, line) : cut).trimEnd()
24}
25
26/** What the model reads: the start of the prompt, then where the whole of it is. */
27export function offloadText(text: string, path: string): string {
28  const lines = text.split('\n').length
29  return `${head(text)}\n\n[prompt-offload] The message was ${text.length} characters, so it was written to ${path} (${lines} line(s)) and this prompt holds its first ${head(text).length}. Read that file before you answer.`
30}
31
32/** The line the person reads in the transcript. */
33export function logText(text: string, path: string): string {
34  return `${text.length} characters written to ${path}; the model reads the first ${head(text).length} here`
35}
36
37/** The limit a `/prompt-offload limit <n>` argument names, or undefined when it is not one. */
38export function limitOf(arg: string): number | undefined {
39  const n = Number(arg)
40  return /^\d+$/.test(arg) && n >= MIN_LIMIT ? n : undefined
41}
42
43/** Whether this prompt is long enough to be written to a file. */
44export const isLong = (text: string, limit: number): boolean => text.length > limit
45