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 +21 -0
- package/README.md +147 -0
- package/index.ts +196 -0
- package/lib/config.mjs +91 -0
- package/lib/exchange.mjs +173 -0
- package/lib/journal.mjs +86 -0
- package/lib/summary.mjs +206 -0
- package/package.json +39 -0
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
|
+
}
|
package/lib/exchange.mjs
ADDED
|
@@ -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
|
+
}
|
package/lib/journal.mjs
ADDED
|
@@ -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
|
+
}
|
package/lib/summary.mjs
ADDED
|
@@ -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
|
+
}
|