pi-chat-recap 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 WilberC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,147 @@
1
+ # pi-chat-recap
2
+
3
+ Producer-only chat recap data for [Pi](https://pi.dev) and
4
+ [Gentle Shell](https://github.com/Gentleman-Programming/gentle-shell).
5
+
6
+ The extension records what happened in the conversation — user text, assistant
7
+ text, cancelled exchanges, session language, and per-exchange model summaries
8
+ (optional; off by default) — and
9
+ renders nothing. Renderers (for example the herdr-sidecar recap view) consume
10
+ the data and own all presentation.
11
+
12
+ ## Install
13
+
14
+ From the npm registry:
15
+
16
+ ```bash
17
+ pi install npm:pi-chat-recap
18
+ ```
19
+
20
+ Or from the parent directory of a local clone:
21
+
22
+ ```bash
23
+ pi install ./pi-chat-recap
24
+ ```
25
+
26
+ Or for a one-shot test without persisting:
27
+
28
+ ```bash
29
+ pi -e ./pi-chat-recap/index.ts
30
+ ```
31
+
32
+ ## Design boundaries
33
+
34
+ - **Producer owns semantics**: what an exchange is, when it was cancelled
35
+ (fixed markers, no summary of things that never happened), the session
36
+ language fixed by the first exchange, what gets summarized.
37
+ - **Renderer owns presentation**: bubbles, alignment, grouping, timestamps
38
+ display, truncation. It must never re-derive conversation semantics and must
39
+ degrade explicitly when data is absent.
40
+ - The summary model summarizes; it never replies to the conversation (R2).
41
+ The hard no-reply rule is producer text appended to every request, so a
42
+ user prompt edit cannot disable it; the editable template controls tone,
43
+ format and length only.
44
+
45
+ ## Journal (for renderers)
46
+
47
+ The extension appends an append-only JSONL journal next to the Pi session
48
+ file: `pi-chat-recap.journal.jsonl`. Each line is self-sufficient so
49
+ consumers can rebuild state by tailing:
50
+
51
+ ```json
52
+ {"v":1,"producer":"pi-chat-recap","sessionId":"…","ts":"…","type":"exchange","data":{"id":1,"status":"aborted","user":{"text":"…","ts":"…","cancelled":true},"assistant":{"text":null,"ts":"…","marker":"No response (operation aborted)"}}}
53
+ ```
54
+
55
+ `status` is `pending`, `answered` or `aborted`. Consumers must tolerate
56
+ unknown fields and unknown `type` values, and must degrade explicitly when
57
+ data is absent — never reconstruct conversation semantics.
58
+
59
+ Record types:
60
+
61
+ - `exchange` — full exchange state after every transition (pending /
62
+ answered / aborted). Aborted exchanges carry fixed markers and never get
63
+ summarized. A turn that calls tools stays `pending` through its tool steps
64
+ and answers with the final reply. An answered `assistant` carries:
65
+ - `text` — the turn's final reply, verbatim.
66
+ - `ts` — when the final reply message started.
67
+ - `doneTs` — when the final reply finished. Response time is
68
+ `doneTs − user.ts`.
69
+ - `tokens` — `{input, output}` summed over the turn's assistant messages
70
+ as the provider reported them, or `null` when it reported none.
71
+ - `toolCalls` — how many tool calls the turn made.
72
+
73
+ Older lines may lack these fields; consumers show nothing for them rather
74
+ than inventing a value.
75
+ - `summary` — `{exchangeId, language, text, truncated, model, tokens}` for
76
+ each successfully summarized answered exchange. `tokens` is the
77
+ provider-reported usage, never an estimate presented as spend.
78
+ - `recap_warning` — configuration, prompt-validation or model-failure
79
+ warnings. Every problem is surfaced here (and via UI notify), never silent.
80
+
81
+ ## Model mode configuration
82
+
83
+ Two editable files under `~/.pi/agent/` control the summary mode. Both are
84
+ re-read on every summarization — edits apply on the next exchange without
85
+ reinstalling (invalid values are warned, with defaults taking over).
86
+
87
+ `pi-chat-recap.json`:
88
+
89
+ ```json
90
+ {
91
+ "mode": "off", // "off" (default) or "model" — model mode is an opt-in
92
+ "model": "provider/model", // summary model; null disables summarization (warns in model mode)
93
+ "fallbackModels": [], // tried in order when the primary fails
94
+ "maxOutputTokens": 512, // requested output cap per summary call
95
+ "maxContextChars": 4000, // material bytes sent to the model
96
+ "maxDisplayChars": 100 // summary length kept in the journal (renderer may still truncate)
97
+ }
98
+ ```
99
+
100
+ With the default `"mode": "off"` the producer journals exchanges exactly as
101
+ before (verbatim text, markers, timestamps) but makes **no model call** and
102
+ writes **no `summary` and no `recap_warning` records** — model mode is fully
103
+ silent unless you opt in. To enable it, set `"mode": "model"` (invalid or
104
+ missing `mode` values fall back to `"off"`, with a warning only when the value
105
+ is invalid).
106
+
107
+ `maxOutputTokens` is what is requested from the provider — actual usage
108
+ depends on the provider and is reported per summary in the journal's
109
+ `tokens` field. On endpoints where reasoning and the answer share that budget
110
+ (reasoning models behind OpenAI-compatible APIs), a summary whose budget is
111
+ consumed by thinking comes back empty (`stopReason: "length"`, no text block);
112
+ in that case the producer retries the same model once with a larger budget
113
+ (4× `maxOutputTokens`), and the journal records the provider-reported usage of
114
+ the call that produced the text. `maxContextChars` (model input) and `maxDisplayChars`
115
+ (journal text) are distinct limits.
116
+
117
+ `pi-chat-recap.prompt.md` — the summary prompt template. Placeholders:
118
+ `{{user}}`, `{{assistant}}`, `{{language}}`. `{{user}}` is required (a
119
+ template without it is rejected with a warning and the built-in default is
120
+ used); unknown placeholders stay as literal text with a warning. The session
121
+ language (`{{language}}`) is fixed by the first exchange, so summaries stay
122
+ in one language even if the conversation alternates (R3). When the file is
123
+ absent, this default applies:
124
+
125
+ ```
126
+ Summary task: write a brief third-person recap of the material below.
127
+ Tone: neutral and factual. Keep it short.
128
+ Material to summarize:
129
+ - User said: {{user}}
130
+ - Assistant said: {{assistant}}
131
+ Write the summary in this language: {{language}}.
132
+ ```
133
+
134
+ ## Status command
135
+
136
+ `/chat-recap` prints exchange counts, detection language, and the effective
137
+ model mode/prompt path.
138
+
139
+ ## Development
140
+
141
+ ```bash
142
+ npm test
143
+ ```
144
+
145
+ Core logic lives in `lib/` and is tested without a Pi host
146
+ (`lib/*.test.mjs`); the host adapter (`index.ts`) is smoke-tested in a live
147
+ session.
package/index.ts ADDED
@@ -0,0 +1,196 @@
1
+ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
2
+ import {
3
+ createExchangeLog,
4
+ userText,
5
+ assistantText,
6
+ EXCHANGE_STATUS,
7
+ } from './lib/exchange.mjs';
8
+ import { createJournal } from './lib/journal.mjs';
9
+ import { createSummarizer, loadPromptFile } from './lib/summary.mjs';
10
+ import { loadRecapConfig, recapPaths } from './lib/config.mjs';
11
+ import { join } from 'node:path';
12
+ import { homedir } from 'node:os';
13
+
14
+ // pi-chat-recap: producer-only conversation data. It records what happened
15
+ // (user text, assistant text, cancellations, session language) and renders
16
+ // nothing. Renderers such as herdr-sidecar consume the data; they never
17
+ // re-derive exchange semantics.
18
+ export default function chatRecap(pi: ExtensionAPI) {
19
+ const log = createExchangeLog();
20
+ const journal = createJournal({ sessionId: '', producer: 'pi-chat-recap' });
21
+
22
+ // Config and prompt live in editable files (R4/S4); they are re-read per
23
+ // summarization so edits apply on the next exchange without a reinstall.
24
+ const paths = recapPaths(join(homedir(), '.pi', 'agent'));
25
+ let configWarned = false;
26
+ let noModelWarned = false;
27
+
28
+ const runSummarizer = (exchange) => {
29
+ // R4: fresh config + prompt per call; every problem is a surfaced
30
+ // warning, never a silent fallback.
31
+ const { config, warnings: cfgWarnings } = loadRecapConfig(join(homedir(), '.pi', 'agent'));
32
+ const prompt = loadPromptFile(paths.prompt);
33
+ const summarizer = createSummarizer({
34
+ callModel: async (req) => {
35
+ const slash = req.model.indexOf('/');
36
+ const model = ctxRef?.modelRegistry?.find?.(
37
+ req.model.slice(0, slash),
38
+ req.model.slice(slash + 1),
39
+ );
40
+ if (!model) throw new Error(`model "${req.model}" not found in the registry`);
41
+ const result = await ctxRef.modelRegistry.complete(model, req.context, {
42
+ maxTokens: req.maxOutputTokens,
43
+ });
44
+ const content = result?.content;
45
+ const text = typeof content === 'string'
46
+ ? content
47
+ : Array.isArray(content)
48
+ ? content.filter((b) => (b as { type?: string })?.type === 'text').map((b) => (b as { text?: string }).text ?? '').join('\n')
49
+ : '';
50
+ return { text, tokens: result?.usage ?? null, stopReason: result?.stopReason ?? null };
51
+ },
52
+ config,
53
+ loadPrompt: () => prompt,
54
+ warn: (msg) => {
55
+ journal.append('recap_warning', { message: msg });
56
+ uiRef?.ui?.notify?.(`pi-chat-recap: ${msg}`, 'warning');
57
+ },
58
+ language: log.language(),
59
+ });
60
+ return summarizer.summarizeExchange(exchange);
61
+ };
62
+
63
+ let ctxRef = null;
64
+ let uiRef = null;
65
+
66
+ const warnOnce = (msg) => {
67
+ journal.append('recap_warning', { message: msg });
68
+ uiRef?.ui?.notify?.(`pi-chat-recap: ${msg}`, 'warning');
69
+ };
70
+
71
+ // Append the full exchange record after every transition so consumers can
72
+ // rebuild state by tailing; each line is self-sufficient.
73
+ const publish = (exchange) => {
74
+ if (exchange) journal.append('exchange', exchange);
75
+ };
76
+
77
+ pi.on('session_start', async (_event, ctx) => {
78
+ ctxRef = ctx;
79
+ uiRef = ctx;
80
+ journal.openSession(
81
+ ctx.sessionManager?.getSessionFile?.(),
82
+ ctx.sessionManager?.getSessionId?.(),
83
+ );
84
+ // Surface config/prompt problems once at startup, not per exchange.
85
+ const { warnings } = loadRecapConfig(join(homedir(), '.pi', 'agent'));
86
+ for (const w of warnings) warnOnce(w);
87
+ configWarned = warnings.length > 0;
88
+ const { warnings: promptWarnings } = loadPromptFile(paths.prompt);
89
+ for (const w of promptWarnings) warnOnce(w);
90
+ // Replay existing exchanges so a renderer joining late has full state.
91
+ for (const exchange of log.exchanges()) publish(exchange);
92
+ });
93
+ pi.on('session_shutdown', () => journal.close());
94
+
95
+ const tsOf = (message: unknown) => {
96
+ // Message events carry no event.timestamp; the timestamp lives on the
97
+ // message itself (pi-ai UserMessage/AssistantMessage.timestamp: number).
98
+ const ts = (message as { timestamp?: unknown } | undefined)?.timestamp;
99
+ return typeof ts === 'number' ? new Date(ts).toISOString() : undefined;
100
+ };
101
+
102
+ pi.on('message_start', async (event) => {
103
+ const message = (event as { message?: unknown }).message as
104
+ | { role?: string; content?: unknown }
105
+ | undefined;
106
+ if (message?.role !== 'user') return;
107
+ // Extension-authored messages (pi.sendMessage custom_message) surface as
108
+ // user-role model messages; they are not things the human typed, so they
109
+ // never begin an exchange.
110
+ if ((message as { customType?: string }).customType) return;
111
+ publish(log.beginUser(userText(message as { content: unknown }), tsOf(message)));
112
+ });
113
+
114
+ pi.on('message_end', async (event) => {
115
+ const message = (event as { message?: unknown }).message as
116
+ | { role?: string; content?: unknown }
117
+ | undefined;
118
+ if (message?.role !== 'assistant') return;
119
+ // stopReason 'aborted' (Escape mid-stream) closes the exchange with the
120
+ // R1 markers; 'toolUse' keeps it pending (S10). lib/exchange.mjs owns
121
+ // the semantics; this adapter only reads the message's own fields.
122
+ const m = message as {
123
+ stopReason?: unknown;
124
+ usage?: { input?: unknown; output?: unknown };
125
+ content?: unknown;
126
+ };
127
+ const toolCalls = Array.isArray(m.content)
128
+ ? m.content.filter((b) => (b as { type?: string })?.type === 'toolCall').length
129
+ : 0;
130
+ const exchange = log.setAssistant(assistantText(message), tsOf(message), {
131
+ stopReason: m.stopReason,
132
+ usage: m.usage,
133
+ toolCalls,
134
+ // message_end fires when the reply has finished streaming: this is
135
+ // the moment the answer was complete (S10 doneTs).
136
+ doneTs: new Date().toISOString(),
137
+ });
138
+ publish(exchange);
139
+
140
+ // R2/R4: summarization happens in agent_settled (end of turn), not here:
141
+ // message_end can fire mid tool-loop and must never stall the loop.
142
+ if (!exchange || exchange.status !== EXCHANGE_STATUS.answered) return;
143
+ });
144
+
145
+ // R1: Escape during a run cancels the exchange. agent_settled carries
146
+ // `aborted`; the core records the fixed markers and no summary runs.
147
+ // R2/R4: for settled non-aborted runs, summarize the just-answered
148
+ // exchange and await it so a summary is never cut by a session exit.
149
+ let summarizedIds = new Set();
150
+ pi.on('agent_settled', async (event) => {
151
+ if ((event as { aborted?: boolean }).aborted) {
152
+ publish(log.abort(tsOf(event)));
153
+ return;
154
+ }
155
+ const exchange = log
156
+ .exchanges()
157
+ .filter((e) => e.status === EXCHANGE_STATUS.answered)
158
+ .at(-1);
159
+ if (!exchange || summarizedIds.has(exchange.id)) return;
160
+ const { config } = loadRecapConfig(join(homedir(), '.pi', 'agent'));
161
+ if (config.mode === 'off') return;
162
+ if (!config.model && !config.fallbackModels.length) {
163
+ if (!noModelWarned) {
164
+ noModelWarned = true;
165
+ warnOnce('no summary model configured (pi-chat-recap.json "model"); skipping summarization');
166
+ }
167
+ return;
168
+ }
169
+ summarizedIds.add(exchange.id);
170
+ try {
171
+ const summary = await runSummarizer(exchange);
172
+ if (summary) {
173
+ journal.append('summary', {
174
+ exchangeId: exchange.id,
175
+ language: log.language(),
176
+ ...summary,
177
+ });
178
+ }
179
+ } catch (err) {
180
+ warnOnce(`summary flow failed: ${err?.message ?? err}`);
181
+ }
182
+ });
183
+
184
+ pi.registerCommand('chat-recap', {
185
+ description: 'Chat recap data: exchange and session-language status',
186
+ handler: async (_args, ctx) => {
187
+ const s = log.summary();
188
+ const lang = s.language ? `language=${s.language}` : 'language=undetected';
189
+ const { config, paths: p } = loadRecapConfig(join(homedir(), '.pi', 'agent'));
190
+ ctx.ui.notify(
191
+ `chat-recap: ${s.count} exchanges (answered ${s.status.answered}, aborted ${s.status.aborted}, pending ${s.status.pending}), ${lang}; mode=${config.mode}, model=${config.model ?? 'none'}, prompt=${p.prompt}`,
192
+ 'info',
193
+ );
194
+ },
195
+ });
196
+ }
package/lib/config.mjs ADDED
@@ -0,0 +1,91 @@
1
+ // Recap config (S4): a user-editable JSON file, mirrored by the prompt file
2
+ // path (R4). Unknown keys and bad values are warnings, never silent.
3
+
4
+ import { existsSync, readFileSync } from 'node:fs';
5
+ import { homedir } from 'node:os';
6
+ import { join } from 'node:path';
7
+
8
+ export const RECAP_MODES = ['model', 'off'];
9
+
10
+ export function recapPaths(piAgentDir = join(homedir(), '.pi', 'agent')) {
11
+ return {
12
+ config: join(piAgentDir, 'pi-chat-recap.json'),
13
+ prompt: join(piAgentDir, 'pi-chat-recap.prompt.md'),
14
+ };
15
+ }
16
+
17
+ export function defaultConfig() {
18
+ return {
19
+ // S6: model mode is an opt-in (L7). The default journals exchanges only:
20
+ // no model call, no summary, no recap_warning. Invalid modes also fall
21
+ // back to "off" (with a warning, below).
22
+ mode: 'off',
23
+ model: null,
24
+ fallbackModels: [],
25
+ maxOutputTokens: 512,
26
+ maxContextChars: 4000,
27
+ maxDisplayChars: 100,
28
+ };
29
+ }
30
+
31
+ const NUMERIC_KEYS = ['maxOutputTokens', 'maxContextChars', 'maxDisplayChars'];
32
+
33
+ // Validate one edited config object; every problem is a surfaced warning.
34
+ export function validateConfig(raw) {
35
+ const warnings = [];
36
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
37
+ return { config: defaultConfig(), warnings: ['recap config must be a JSON object; using defaults'] };
38
+ }
39
+ const config = defaultConfig();
40
+ for (const key of Object.keys(raw)) {
41
+ if (key === 'mode') {
42
+ if (!RECAP_MODES.includes(raw.mode)) {
43
+ warnings.push(`recap config mode "${raw.mode}" is not one of ${RECAP_MODES.join(', ')}; using "off"`);
44
+ config.mode = 'off';
45
+ } else {
46
+ config.mode = raw.mode;
47
+ }
48
+ } else if (key === 'model') {
49
+ if (raw.model !== null && typeof raw.model !== 'string') {
50
+ warnings.push('recap config model must be a string like "provider/model-id" or null; ignoring it');
51
+ } else {
52
+ config.model = raw.model;
53
+ }
54
+ } else if (key === 'fallbackModels') {
55
+ if (!Array.isArray(raw.fallbackModels) || raw.fallbackModels.some((m) => typeof m !== 'string')) {
56
+ warnings.push('recap config fallbackModels must be an array of strings; ignoring it');
57
+ } else {
58
+ config.fallbackModels = raw.fallbackModels;
59
+ }
60
+ } else if (NUMERIC_KEYS.includes(key)) {
61
+ const n = Number(raw[key]);
62
+ if (!Number.isFinite(n) || n < 1) {
63
+ warnings.push(`recap config ${key} must be a number >= 1; keeping the default`);
64
+ } else {
65
+ config[key] = Math.floor(n);
66
+ }
67
+ } else {
68
+ warnings.push(`recap config has unknown key "${key}" (ignored)`);
69
+ }
70
+ }
71
+ return { config, warnings };
72
+ }
73
+
74
+ export function loadRecapConfig(piAgentDir, { read = (p) => readFileSync(p, 'utf8'), exists = existsSync } = {}) {
75
+ const paths = recapPaths(piAgentDir);
76
+ if (!exists(paths.config)) {
77
+ return { config: defaultConfig(), warnings: [], paths };
78
+ }
79
+ let raw;
80
+ try {
81
+ raw = JSON.parse(read(paths.config));
82
+ } catch (err) {
83
+ return {
84
+ config: defaultConfig(),
85
+ warnings: [`recap config file could not be parsed (${err?.message ?? err}); using defaults`],
86
+ paths,
87
+ };
88
+ }
89
+ const { config, warnings } = validateConfig(raw);
90
+ return { config, warnings, paths };
91
+ }
@@ -0,0 +1,173 @@
1
+ // Core conversation model (producer-only). Owns the semantics of an exchange
2
+ // so renderers never have to guess: user text, assistant text or an explicit
3
+ // aborted state, with timestamps captured when events happen.
4
+ // Requirements: R1 (cancelled exchange shows what happened, no summary) and
5
+ // R3 (session language fixed by the first exchange). No model calls here.
6
+
7
+ export const EXCHANGE_STATUS = {
8
+ pending: 'pending',
9
+ answered: 'answered',
10
+ aborted: 'aborted',
11
+ };
12
+
13
+ // Fixed surface markers for an aborted exchange (R1). Renderers print them
14
+ // verbatim; they are data, not presentation decisions.
15
+ export const ABORTED_YOU_SUFFIX = '(operation cancelled)';
16
+ export const ABORTED_PI_MARKER = 'No response (operation aborted)';
17
+
18
+ // Minimal stopword heuristic for R3: the session language is decided once,
19
+ // from the first exchange whose text is detectable. Good enough to keep
20
+ // summaries stable; consumers may override with their own detector.
21
+ const ES_HINTS = ['que', 'de', 'el', 'la', 'los', 'las', 'para', 'con', 'por', 'una', 'uno', 'como', 'pero', 'esta', 'este', 'si', 'no', 'y', 'o', 'hacer', 'puede'];
22
+ const EN_HINTS = ['the', 'and', 'for', 'with', 'that', 'this', 'from', 'have', 'not', 'you', 'are', 'what', 'how', 'can', 'should', 'make', 'add'];
23
+
24
+ export function detectLanguage(text) {
25
+ if (typeof text !== 'string' || text.trim() === '') return null;
26
+ const words = text.toLowerCase().split(/[^\p{L}]+/u).filter(Boolean);
27
+ if (words.length === 0) return null;
28
+ let es = 0;
29
+ let en = 0;
30
+ for (const w of words) {
31
+ if (ES_HINTS.includes(w)) es += 1;
32
+ if (EN_HINTS.includes(w)) en += 1;
33
+ }
34
+ if (es === en) return null;
35
+ return es > en ? 'es' : 'en';
36
+ }
37
+
38
+ export function userText(message) {
39
+ if (!message) return '';
40
+ const content = message.content;
41
+ if (typeof content === 'string') return content;
42
+ if (Array.isArray(content)) {
43
+ return content
44
+ .filter((b) => b?.type === 'text' && typeof b.text === 'string')
45
+ .map((b) => b.text)
46
+ .join('\n');
47
+ }
48
+ return '';
49
+ }
50
+
51
+ export function assistantText(message) {
52
+ if (!message || message.role !== 'assistant') return '';
53
+ return userText(message);
54
+ }
55
+
56
+ // Sums provider-reported usage over a turn's assistant messages (S10). A
57
+ // message without usage adds nothing; a turn without any usage stays null so
58
+ // renderers show no tokens instead of a fake zero.
59
+ function addTokens(total, usage) {
60
+ const input = Number(usage?.input);
61
+ const output = Number(usage?.output);
62
+ if (!Number.isFinite(input) && !Number.isFinite(output)) return total;
63
+ return {
64
+ input: (total?.input ?? 0) + (Number.isFinite(input) ? input : 0),
65
+ output: (total?.output ?? 0) + (Number.isFinite(output) ? output : 0),
66
+ };
67
+ }
68
+
69
+ export function createExchangeLog({ detect = detectLanguage } = {}) {
70
+ const exchanges = [];
71
+ // Per-exchange turn accumulators (S10): tokens and tool calls of every
72
+ // assistant message of the turn, kept off the exchange until it answers.
73
+ const turns = new Map();
74
+ let language = null;
75
+ let nextId = 1;
76
+
77
+ const log = {
78
+ // A user message starts (or reopens) the pending exchange.
79
+ beginUser(text, ts) {
80
+ const exchange = {
81
+ id: nextId++,
82
+ status: EXCHANGE_STATUS.pending,
83
+ user: { text: String(text ?? ''), ts: ts ?? null, cancelled: false },
84
+ assistant: null,
85
+ };
86
+ exchanges.push(exchange);
87
+ if (!language) {
88
+ const detected = detect(exchange.user.text);
89
+ if (detected) language = detected;
90
+ }
91
+ return exchange;
92
+ },
93
+
94
+ // The assistant answered: data goes in verbatim, never summarized.
95
+ // An assistant message with stopReason 'aborted' (Escape mid-stream) is
96
+ // not an answer: record the R1 abort with the fixed markers, even when
97
+ // the delivered text is empty or a partial fragment.
98
+ // S10: a turn that calls tools emits several assistant messages; a
99
+ // 'toolUse' one is a step, not the answer, so the exchange stays pending
100
+ // while its tokens and tool calls accumulate. The final message answers
101
+ // with its own text; doneTs is when the turn's final reply ended.
102
+ setAssistant(text, ts, meta = {}) {
103
+ const current = log.pending();
104
+ if (!current) return null;
105
+ const turn = (turns.get(current.id) ?? { tokens: null, toolCalls: 0 });
106
+ turns.set(current.id, turn);
107
+ turn.tokens = addTokens(turn.tokens, meta?.usage);
108
+ turn.toolCalls += Number.isInteger(meta?.toolCalls) && meta.toolCalls > 0 ? meta.toolCalls : 0;
109
+ if (meta?.stopReason === 'aborted') {
110
+ current.user.cancelled = true;
111
+ current.assistant = { text: null, ts: ts ?? null, marker: ABORTED_PI_MARKER };
112
+ current.status = EXCHANGE_STATUS.aborted;
113
+ return current;
114
+ }
115
+ if (meta?.stopReason === 'toolUse') return current;
116
+ current.assistant = {
117
+ text: String(text ?? ''),
118
+ ts: ts ?? null,
119
+ marker: null,
120
+ doneTs: meta?.doneTs ?? null,
121
+ tokens: turn.tokens,
122
+ toolCalls: turn.toolCalls,
123
+ };
124
+ current.status = EXCHANGE_STATUS.answered;
125
+ return current;
126
+ },
127
+
128
+ // R1: the exchange was cancelled. Record exactly what happened; the
129
+ // aborted exchange carries fixed markers and triggers no summary.
130
+ // Also recovers an exchange left 'answered' with empty text by a run
131
+ // whose message_end arrived without a stopReason before the abort.
132
+ abort(ts) {
133
+ const current = log.pending()
134
+ ?? (() => {
135
+ const last = exchanges[exchanges.length - 1];
136
+ if (last
137
+ && last.status === EXCHANGE_STATUS.answered
138
+ && last.assistant
139
+ && last.assistant.text === '') {
140
+ return last;
141
+ }
142
+ return null;
143
+ })();
144
+ if (!current) return null;
145
+ current.user.cancelled = true;
146
+ current.assistant = { text: null, ts: ts ?? null, marker: ABORTED_PI_MARKER };
147
+ current.status = EXCHANGE_STATUS.aborted;
148
+ return current;
149
+ },
150
+
151
+ pending() {
152
+ for (let i = exchanges.length - 1; i >= 0; i -= 1) {
153
+ if (exchanges[i].status === EXCHANGE_STATUS.pending) return exchanges[i];
154
+ }
155
+ return null;
156
+ },
157
+
158
+ language() {
159
+ return language;
160
+ },
161
+
162
+ exchanges() {
163
+ return exchanges.map((e) => structuredClone(e));
164
+ },
165
+
166
+ summary() {
167
+ const counts = { pending: 0, answered: 0, aborted: 0 };
168
+ for (const e of exchanges) counts[e.status] += 1;
169
+ return { count: exchanges.length, status: counts, language };
170
+ },
171
+ };
172
+ return log;
173
+ }
@@ -0,0 +1,86 @@
1
+ // Append-only JSONL journal (producer-only). One file per session, written
2
+ // next to the Pi session file; consumers (herdr-sidecar or any renderer)
3
+ // tail it and own all presentation. Line contract:
4
+ // {v:1, producer, sessionId, ts, type, data}
5
+ // Consumers must tolerate unknown fields and unknown `type` values.
6
+
7
+ import { appendFileSync, mkdirSync } from 'node:fs';
8
+ import { dirname, join } from 'node:path';
9
+
10
+ export const JOURNAL_VERSION = 1;
11
+
12
+ export function journalPathFor(sessionFile, name) {
13
+ return join(dirname(sessionFile), `${name}.journal.jsonl`);
14
+ }
15
+
16
+ export function createJournal({ file, sessionId, producer, now = () => new Date().toISOString() } = {}) {
17
+ let open = false;
18
+ let sid = sessionId;
19
+
20
+ const write = (type, data) => {
21
+ if (!file || !open) return null;
22
+ const line = JSON.stringify({
23
+ v: JOURNAL_VERSION,
24
+ producer,
25
+ sessionId: sid,
26
+ ts: now(),
27
+ type,
28
+ data,
29
+ });
30
+ try {
31
+ mkdirSync(dirname(file), { recursive: true });
32
+ appendFileSync(file, `${line}\n`, 'utf8');
33
+ return line;
34
+ } catch {
35
+ // A journaling failure never breaks the host session; consumers
36
+ // degrade explicitly when data is absent.
37
+ return null;
38
+ }
39
+ };
40
+
41
+ return {
42
+ // Bind (or rebind) to a session file; call again on session switch.
43
+ // An explicit sessionId updates the recorded id (advisory: the id comes
44
+ // from the host at session_start, not at extension load).
45
+ openSession(sessionFile, sessionId) {
46
+ if (!sessionFile) {
47
+ open = false;
48
+ return null;
49
+ }
50
+ if (typeof sessionId === 'string' && sessionId !== '') sid = sessionId;
51
+ file = journalPathFor(sessionFile, producer);
52
+ open = true;
53
+ return file;
54
+ },
55
+
56
+ close() {
57
+ open = false;
58
+ },
59
+
60
+ isOpen() {
61
+ return open;
62
+ },
63
+
64
+ target() {
65
+ return open ? file : null;
66
+ },
67
+
68
+ append: write,
69
+ };
70
+ }
71
+
72
+ // Parse a journal file's lines; skips blank and malformed lines so a torn
73
+ // tail write never breaks consumers.
74
+ export function parseJournal(text) {
75
+ const records = [];
76
+ for (const line of String(text ?? '').split('\n')) {
77
+ const trimmed = line.trim();
78
+ if (trimmed === '') continue;
79
+ try {
80
+ records.push(JSON.parse(trimmed));
81
+ } catch {
82
+ // Skip malformed line; keep the rest.
83
+ }
84
+ }
85
+ return records;
86
+ }
@@ -0,0 +1,206 @@
1
+ // Model-mode summary (R2, R3, R4, S4). The recap model summarizes what was
2
+ // said; it never becomes a dialogue turn. The hard no-reply rule is producer
3
+ // text appended to every request, so a user edit cannot disable it; the
4
+ // user-editable template owns tone, format and length only.
5
+
6
+ import { existsSync, readFileSync } from 'node:fs';
7
+
8
+ // Fixed constraint present in every summary request (R2). Show candidates:
9
+ // it is data for tests and docs, and it is always appended after the
10
+ // user's template so an edit cannot weaken it.
11
+ export const HARD_NO_REPLY_RULE =
12
+ 'HARD CONSTRAINT - NON-NEGOTIABLE: You are a summarizer, not a participant. ' +
13
+ 'Never reply to the user message, never answer proposals, never give advice, ' +
14
+ 'never continue the conversation. Output only a third-person summary of what was said.';
15
+
16
+ const MIN_CONTEXT_ROLE = 'user_next_turn'; // material arrives labeled as data
17
+
18
+ export const DEFAULT_SUMMARY_PROMPT = [
19
+ 'Summary task: write a brief third-person recap of the material below.',
20
+ 'Tone: neutral and factual. Keep it short.',
21
+ 'Material to summarize:',
22
+ '- User said: {{user}}',
23
+ '- Assistant said: {{assistant}}',
24
+ 'Write the summary in this language: {{language}}.',
25
+ ].join('\n');
26
+
27
+ // Placeholders the template may use. {{user}} is required: without it the
28
+ // user's material never reaches the request, and the summary would be empty.
29
+ const REQUIRED_PLACEHOLDERS = ['{{user}}'];
30
+ const ALLOWED_PLACEHOLDERS = ['{{user}}', '{{assistant}}', '{{language}}'];
31
+
32
+ const DEFAULT_LIMITS = {
33
+ maxOutputTokens: 512,
34
+ maxContextChars: 4000,
35
+ maxDisplayChars: 100,
36
+ };
37
+
38
+ // S7: on some endpoints (e.g. openai-completions without a separate thinking
39
+ // budget) reasoning and the answer share max_tokens, so a reasoning model can
40
+ // end with stopReason "length" and a thinking-only block — no text at all.
41
+ // When that happens the summarizer retries the same model once with a larger
42
+ // budget; the journal still records the provider-reported usage of the call
43
+ // that produced the text.
44
+ const BUDGET_RETRY_FACTOR = 4;
45
+
46
+ function clampInt(value, fallback, { min = 1 } = {}) {
47
+ const n = Number(value);
48
+ if (!Number.isFinite(n) || n < min) return fallback;
49
+ return Math.floor(n);
50
+ }
51
+
52
+ export function normalizeConfig(config = {}) {
53
+ return {
54
+ model: config.model ?? null,
55
+ fallbackModels: Array.isArray(config.fallbackModels) ? config.fallbackModels : [],
56
+ maxOutputTokens: clampInt(config.maxOutputTokens, DEFAULT_LIMITS.maxOutputTokens),
57
+ maxContextChars: clampInt(config.maxContextChars, DEFAULT_LIMITS.maxContextChars),
58
+ maxDisplayChars: clampInt(config.maxDisplayChars, DEFAULT_LIMITS.maxDisplayChars),
59
+ };
60
+ }
61
+
62
+ // R4/S4: validate the edited template. Problems are warnings, never silent
63
+ // fallbacks: the caller surfaces every message (journal + UI notify).
64
+ export function validateTemplate(template) {
65
+ const warnings = [];
66
+ if (typeof template !== 'string' || template.trim() === '') {
67
+ return { warnings: ['summary prompt template is empty; using the default template'] };
68
+ }
69
+ for (const ph of REQUIRED_PLACEHOLDERS) {
70
+ if (!template.includes(ph)) {
71
+ warnings.push(`summary prompt template is missing required placeholder ${ph}; using the default template`);
72
+ }
73
+ }
74
+ const used = template.match(/\{\{\w+\}\}/g) ?? [];
75
+ for (const u of used) {
76
+ if (!ALLOWED_PLACEHOLDERS.includes(u.toLowerCase())) {
77
+ warnings.push(`summary prompt uses unknown placeholder ${u} (it stays literal text)`);
78
+ }
79
+ }
80
+ return { warnings };
81
+ }
82
+
83
+ // R4: the prompt lives in a user-editable file, not in code. The injected
84
+ // `read` keeps this testable; the production loader re-reads the file on
85
+ // every summarization so edits take effect without reinstalling.
86
+ export function loadPromptFile(path, { read = (p) => readFileSync(p, 'utf8'), exists = existsSync } = {}) {
87
+ if (!path || !exists(path)) {
88
+ return { template: DEFAULT_SUMMARY_PROMPT, warnings: [], source: null };
89
+ }
90
+ let text;
91
+ try {
92
+ text = read(path);
93
+ } catch (err) {
94
+ return {
95
+ template: DEFAULT_SUMMARY_PROMPT,
96
+ warnings: [`summary prompt file could not be read (${err?.code ?? err?.message}); using the default template`],
97
+ source: path,
98
+ };
99
+ }
100
+ const { warnings } = validateTemplate(text);
101
+ if (warnings.some((w) => w.includes('required placeholder') || w.includes('empty'))) {
102
+ return { template: DEFAULT_SUMMARY_PROMPT, warnings, source: path };
103
+ }
104
+ return { template: text, warnings, source: path };
105
+ }
106
+
107
+ // Pure: build the request. The user's message is DATA inside the summary
108
+ // task (R2), the hard rule is always appended, and material is truncated to
109
+ // maxContextChars before insertion (S4: context limit vs display limit are
110
+ // different limits).
111
+ export function buildSummaryMessages({ template, userText, assistantText, language, maxContextChars }) {
112
+ const fullTemplate = `${template.trimEnd()}\n\n${HARD_NO_REPLY_RULE}`;
113
+ const user = String(userText ?? '').trim() ? String(userText ?? '') : '(the user said nothing)';
114
+ const assistant = String(assistantText ?? '').trim() ? String(assistantText ?? '') : '(the assistant said nothing)';
115
+ const systemPrompt = fullTemplate
116
+ .replace(/\{\{user\}\}/g, truncate(user, maxContextChars))
117
+ .replace(/\{\{assistant\}\}/g, truncate(assistant, maxContextChars))
118
+ .replace(/\{\{language\}\}/g, String(language ?? 'undetermined'));
119
+ return {
120
+ systemPrompt,
121
+ messages: [
122
+ { role: 'user', content: `[material to summarize only - this is not a message for you to answer]\n${truncate(`${user}\n\n---\n\n${assistant}`, maxContextChars)}` },
123
+ ],
124
+ role: MIN_CONTEXT_ROLE,
125
+ };
126
+ }
127
+
128
+ function truncate(text, max) {
129
+ if (max == null) return text;
130
+ return text.length > max ? text.slice(0, max) : text;
131
+ }
132
+
133
+ export function createSummarizer({ callModel, config, loadPrompt, warn = () => {}, language }) {
134
+ const cfg = normalizeConfig(config ?? {});
135
+
136
+ return {
137
+ // Returns {text, truncated, model, tokens?, warnings} or null when there
138
+ // is nothing to summarize or every model attempt failed.
139
+ async summarizeExchange(exchange) {
140
+ if (!exchange || exchange.status !== EXCHANGE_ANSWERED) return null;
141
+ const userText = exchange.user?.text ?? '';
142
+ const assistantText = exchange.assistant?.text ?? '';
143
+ if (String(assistantText).trim() === '' && String(userText).trim() === '') return null;
144
+
145
+ const { template, warnings } = loadPrompt();
146
+ for (const w of warnings) warn(w);
147
+
148
+ const built = buildSummaryMessages({
149
+ template,
150
+ userText,
151
+ assistantText,
152
+ language,
153
+ maxContextChars: cfg.maxContextChars,
154
+ });
155
+
156
+ const models = [cfg.model, ...cfg.fallbackModels].filter(Boolean);
157
+ if (models.length === 0) {
158
+ warn('no summary model configured; skipping summarization');
159
+ return null;
160
+ }
161
+
162
+ const tried = [];
163
+ for (const model of models) {
164
+ try {
165
+ const context = { systemPrompt: built.systemPrompt, messages: built.messages };
166
+ let result = await callModel({
167
+ model,
168
+ context,
169
+ maxOutputTokens: cfg.maxOutputTokens,
170
+ });
171
+ let text = String(result?.text ?? '').trim();
172
+ if (text === '' && result?.stopReason === 'length') {
173
+ // S7: the reasoning phase consumed the whole budget before any
174
+ // text block. Retry the same model with a larger budget.
175
+ result = await callModel({
176
+ model,
177
+ context,
178
+ maxOutputTokens: cfg.maxOutputTokens * BUDGET_RETRY_FACTOR,
179
+ });
180
+ text = String(result?.text ?? '').trim();
181
+ }
182
+ if (text === '') {
183
+ const stop = result?.stopReason ? ` (stopReason: ${result.stopReason})` : '';
184
+ tried.push(`${model}: empty output${stop}`);
185
+ continue;
186
+ }
187
+ const truncated = text.length > cfg.maxDisplayChars;
188
+ return {
189
+ text: truncated ? text.slice(0, cfg.maxDisplayChars) : text,
190
+ truncated,
191
+ model,
192
+ tokens: result?.tokens ?? null,
193
+ warnings: [],
194
+ };
195
+ } catch (err) {
196
+ tried.push(`${model}: ${err?.message ?? String(err)}`);
197
+ }
198
+ }
199
+ warn(`summary models all failed (${tried.join('; ')}); exchange left unsummarized`);
200
+ return null;
201
+ },
202
+ };
203
+ }
204
+
205
+ import { EXCHANGE_STATUS } from './exchange.mjs';
206
+ const EXCHANGE_ANSWERED = EXCHANGE_STATUS.answered;
package/package.json ADDED
@@ -0,0 +1,39 @@
1
+ {
2
+ "name": "pi-chat-recap",
3
+ "version": "0.1.0",
4
+ "description": "Producer-only chat recap data for Pi: conversation exchanges with real timestamps, cancellation states and session-fixed language. Renders nothing; built to feed renderers like herdr-sidecar.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "author": "WilberC",
8
+ "keywords": [
9
+ "pi-package",
10
+ "pi",
11
+ "pi-coding-agent",
12
+ "recap",
13
+ "session-log"
14
+ ],
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git+https://github.com/WilberC/pi-chat-recap.git"
18
+ },
19
+ "homepage": "https://github.com/WilberC/pi-chat-recap#readme",
20
+ "bugs": {
21
+ "url": "https://github.com/WilberC/pi-chat-recap/issues"
22
+ },
23
+ "files": [
24
+ "index.ts",
25
+ "lib",
26
+ "!lib/*.test.mjs",
27
+ "!adapter.test.mjs",
28
+ "README.md",
29
+ "LICENSE"
30
+ ],
31
+ "scripts": {
32
+ "test": "node --test"
33
+ },
34
+ "pi": {
35
+ "extensions": [
36
+ "./index.ts"
37
+ ]
38
+ }
39
+ }