compact-methods

1import type { EngineInterface, Register, SessionCompactResult, SessionMessage } from "claude-code";
2import { messageTokens, shake } from "./shake";
3
4// compact-methods: oh-my-pi's shake and handoff as Claude Code compaction methods.
5// `/compact shake` and `/compact handoff [focus]` pick one by name (the built-in /compact passes its
6// text through as `instructions`); `autoMethod` picks what runs when the context fills. There are
7// no /shake or /handoff commands: a command hook may not start a compaction.
8
9// oh-my-pi's prompts (agent/src/compaction/prompts/handoff-document.md, handoff-summary-context.md).
10const HANDOFF_PROMPT = `<critical>
11Write a handoff document for another instance of yourself.
12The handoff MUST be sufficient for seamless continuation without access to this conversation.
13Output ONLY the handoff document. No preamble, no commentary, no wrapper text.
14</critical>
15
16<instruction>
17Capture exact technical state, not abstractions.
18- File paths, symbol names, commands run
19- Test results, observed failures
20- Decisions made
21- Partial work affecting the next step
22Register: address the successor directly in the imperative ("Fix X", "Run Y") — never first person ("I need to…", "my attempt…").
23The handoff mechanism is invisible to the document: NEVER list writing, generating, or delivering a handoff/summary/context document as progress or a next step. Progress and Next Steps cover the user's task only.
24</instruction>
25
26<output>
27Use exactly this structure:
28
29## Goal
30## Constraints & Preferences
31## Progress
32### Done
33### In Progress
34### Pending
35## Key Decisions
36## Critical Context
37## Next Steps
38</output>`;
39
40const handoffContext = (doc: string) => `Context replaced. The <handoff> below is a handoff document a prior instance of you wrote from the full conversation. It is your own working memory, not user input.
41- First person inside it refers to you (the prior instance).
42- "Next Steps" is your own resumed plan; re-check it against the latest user message before acting.
43- The handoff already exists and is complete: NEVER write another handoff document unless the user explicitly asks.
44MUST build on prior work; NEVER duplicate prior work.
45
46<handoff>
47${doc}
48</handoff>`;
49
50const total = (ms: readonly SessionMessage[]) => ms.reduce((n, m) => n + messageTokens(m), 0);
51
52async function stateDir($: EngineInterface): Promise<string> {
53  return `${(await $.env.get("HOME")) ?? "/tmp"}/.claude/compact-methods/${await $.session.id()}`;
54}
55
56async function runShake($: EngineInterface, messages: readonly SessionMessage[], protectTokens: number): Promise<{ result: SessionCompactResult; saved: number }> {
57  const r = shake(messages, protectTokens, await stateDir($));
58  for (const o of r.offloads) await $.fs.write(o.path, o.text);
59  return { result: { messages: r.messages, tokensBefore: total(messages), tokensAfter: total(r.messages) }, saved: r.saved };
60}
61
62/** The conversation as plain text, for a handoff written without the prompt cache. */
63function transcript(messages: readonly SessionMessage[]): string {
64  const cap = (t: string, n: number) => (t.length > n ? `${t.slice(0, n)} …[${t.length - n} more]` : t);
65  return messages
66    .map(m => [
67      m.text && `${m.role}: ${m.text}`,
68      ...m.toolUses.map(u => `${m.role} called ${u.tool}(${cap(JSON.stringify(u.input), 300)})${u.text ? ` -> ${cap(u.text, 1500)}` : ""}`),
69    ].filter(Boolean).join("\n"))
70    .filter(Boolean)
71    .join("\n\n")
72    .slice(-200_000);
73}
74
75async function runHandoff($: EngineInterface, messages: readonly SessionMessage[], focus: string): Promise<SessionCompactResult | undefined> {
76  const ask = focus ? `${HANDOFF_PROMPT}\n\n<instruction>\nAdditional focus: ${focus}\n</instruction>` : HANDOFF_PROMPT;
77  // Fork first: it asks over the main thread's last request, so the prompt cache serves the
78  // prefix. With no request to fork (a session just resumed), write it from the messages.
79  let r = await $.model.fork({ prompt: ask });
80  if (!r.isAnswered) r = await $.model.complete({ model: await $.session.model(), system: ask, prompt: `<conversation>\n${transcript(messages)}\n</conversation>\n\nWrite the handoff document now.`, maxTokens: 8000 });
81  if (!r.isAnswered || !r.text.trim()) return undefined;
82  await $.fs.write(`${await stateDir($)}/handoff-${await $.clock.now()}.md`, r.text);
83  return { messages: [{ role: "user", text: handoffContext(r.text.trim()), toolUses: [] }], usage: r.usage };
84}
85
86export const register: Register = (on, options) => {
87  const autoMethod = String(options.autoMethod ?? "native");
88  const protectTokens = Number(options.protectTokens ?? 16000);
89  const minSavings = Number(options.minSavings ?? 4000);
90
91  on("session.compact", async ($, e, next) => {
92    if (e.trigger === "precompute" || e.agentId) return next(e);
93    const named = /^\s*(shake|handoff)\b\s*([\s\S]*)$/.exec(e.instructions ?? "");
94    const method = named ? named[1]! : e.trigger === "auto" ? autoMethod : "native";
95    if (method === "shake") {
96      // A shake the person asked for keeps only a small tail, as oh-my-pi's manual /shake does.
97      const { result, saved } = await runShake($, e.messages, named ? Math.min(protectTokens, 4000) : protectTokens);
98      if (!named && saved < minSavings) return next(e);
99      $.ui.toast(`compact-methods: shake saved ~${saved} tokens`);
100      return saved > 0 ? result : { skip: "nothing large enough to shake" };
101    }
102    if (method === "handoff") {
103      const result = await runHandoff($, e.messages, named?.[2]?.trim() ?? "");
104      if (result) return result;
105      $.ui.toast("compact-methods: handoff failed; using native compaction");
106      return next({ ...e, instructions: named?.[2]?.trim() || undefined });
107    }
108    return next(e);
109  });
110};
111

1// Shake, after oh-my-pi's compaction/shake.ts: drop heavy, recoverable content out of the live
2// context with no model call. Tool output older than the protected tail is moved to a file and
3// replaced by a one-line pointer the model can Read back.
4//
5// ponytail: tool output only, sized by chars/4. oh-my-pi also elides large fenced/XML blocks in
6// message text and uses a tokenizer. Upgrade path: same pass over `text` for ``` and <tag> blocks.
7
8import type { SessionMessage } from "claude-code";
9
10export type Offload = { id: string; path: string; text: string };
11
12const tokens = (s: string) => Math.ceil(s.length / 4);
13const MIN_TOKENS = 400;
14
15export function messageTokens(m: SessionMessage): number {
16  let n = tokens(m.text);
17  for (const u of m.toolUses) n += tokens(JSON.stringify(u.input ?? {})) + tokens(u.text ?? "");
18  for (const r of m.toolResults ?? []) n += tokens(r.text);
19  return n;
20}
21
22/**
23 * Shake `messages`, keeping the newest `protectTokens` intact. `dir` is where offloaded text will
24 * be written (by the caller); the pointers name files under it.
25 */
26export function shake(messages: readonly SessionMessage[], protectTokens: number, dir: string): { messages: SessionMessage[]; offloads: Offload[]; saved: number } {
27  let tail = 0;
28  let cut = messages.length;
29  while (cut > 0 && tail + messageTokens(messages[cut - 1]!) <= protectTokens) tail += messageTokens(messages[--cut]!);
30
31  const offloads: Offload[] = [];
32  let saved = 0;
33  const pointer = (id: string, text: string) => {
34    const path = `${dir}/${id}.txt`;
35    if (!offloads.some(o => o.id === id)) offloads.push({ id, path, text });
36    const note = `[shaken: ${text.length} characters of tool output moved to ${path}; Read it if you need it]`;
37    saved += tokens(text) - tokens(note);
38    return note;
39  };
40
41  const out = messages.map((m, i) => {
42    if (i >= cut) return m;
43    let changed = false;
44    const toolUses = m.toolUses.map(u => {
45      if (!u.text || tokens(u.text) < MIN_TOKENS) return u;
46      changed = true;
47      const { result: _drop, ...rest } = u;
48      return { ...rest, text: pointer(u.tool_use_id, u.text) };
49    });
50    const toolResults = m.toolResults?.map(r => {
51      if (tokens(r.text) < MIN_TOKENS) return r;
52      changed = true;
53      const { result: _drop, ...rest } = r;
54      return { ...rest, text: pointer(r.tool_use_id, r.text) };
55    });
56    if (!changed) return m;
57    // Without its handle the engine rebuilds the message from role, text and the tool blocks.
58    const { handle: _handle, ...plain } = m;
59    return { ...plain, toolUses, ...(toolResults ? { toolResults } : {}) };
60  });
61  return { messages: out, offloads, saved };
62}
63