@phren/agent 0.1.15 → 0.3.6
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/README.md +86 -0
- package/dist/agent-loop/index.js +239 -65
- package/dist/agent-loop/stream.js +212 -29
- package/dist/agent-loop/types.js +15 -2
- package/dist/checkpoint.js +103 -22
- package/dist/commands/info.js +30 -15
- package/dist/commands/model.js +6 -2
- package/dist/commands/review.js +183 -0
- package/dist/commands/session.js +70 -7
- package/dist/commands.js +168 -12
- package/dist/config.js +87 -10
- package/dist/context/compactor.js +239 -0
- package/dist/context/pruner.js +39 -13
- package/dist/context/token-counter.js +33 -1
- package/dist/custom-commands.js +69 -0
- package/dist/guards/repeat-tool-reminder.js +75 -0
- package/dist/headless.js +115 -0
- package/dist/herdr-hooks.js +71 -0
- package/dist/index.js +351 -48
- package/dist/mcp-client.js +434 -73
- package/dist/mcp-oauth.js +121 -0
- package/dist/memory/anti-patterns.js +7 -3
- package/dist/memory/auto-capture.js +7 -3
- package/dist/memory/context.js +92 -73
- package/dist/memory/project-context.js +24 -5
- package/dist/memory/provenance.js +15 -0
- package/dist/memory/review-triage.js +166 -0
- package/dist/memory/session.js +36 -1
- package/dist/models.js +152 -19
- package/dist/multi/child-entry.js +65 -10
- package/dist/multi/diff-renderer.js +3 -3
- package/dist/multi/markdown.js +125 -27
- package/dist/multi/provider-manager.js +8 -0
- package/dist/multi/publish.js +72 -0
- package/dist/multi/spawner.js +45 -4
- package/dist/multi/syntax-highlight.js +25 -4
- package/dist/multi/types.js +1 -1
- package/dist/permissions/allowlist.js +86 -13
- package/dist/permissions/checker.js +42 -7
- package/dist/permissions/kernel-sandbox.js +197 -0
- package/dist/permissions/prompt.js +10 -1
- package/dist/permissions/sandbox.js +40 -17
- package/dist/providers/anthropic.js +154 -7
- package/dist/providers/codex-auth.js +28 -0
- package/dist/providers/codex.js +134 -23
- package/dist/providers/history.js +35 -0
- package/dist/providers/ollama.js +37 -6
- package/dist/providers/openai-compat.js +171 -74
- package/dist/providers/openrouter.js +47 -17
- package/dist/providers/replay.js +62 -0
- package/dist/providers/resolve.js +41 -7
- package/dist/providers/retry.js +38 -5
- package/dist/providers/types.js +9 -1
- package/dist/repl.js +47 -5
- package/dist/session/log.js +217 -0
- package/dist/session/persist.js +190 -0
- package/dist/settings.js +42 -26
- package/dist/system-prompt.js +18 -2
- package/dist/tools/apply-patch.js +355 -0
- package/dist/tools/edit-engine.js +287 -0
- package/dist/tools/edit-file.js +86 -27
- package/dist/tools/grep.js +25 -10
- package/dist/tools/lint-test.js +0 -22
- package/dist/tools/mcp-resources.js +51 -6
- package/dist/tools/phren-finding.js +12 -4
- package/dist/tools/phren-search.js +7 -2
- package/dist/tools/read-file.js +37 -9
- package/dist/tools/read-image.js +76 -0
- package/dist/tools/registry.js +27 -5
- package/dist/tools/shell.js +134 -71
- package/dist/tools/skill.js +20 -20
- package/dist/tools/spawn-agent.js +77 -13
- package/dist/tools/update-plan.js +48 -0
- package/dist/tools/web-fetch.js +110 -12
- package/dist/tools/web-search.js +4 -4
- package/dist/tui/components/App.js +98 -26
- package/dist/tui/components/ApprovalPanel.js +8 -0
- package/dist/tui/components/InputArea.js +5 -5
- package/dist/tui/components/ModelPicker.js +43 -0
- package/dist/tui/components/PhrenInput.js +10 -5
- package/dist/tui/components/PlanReview.js +7 -0
- package/dist/tui/components/ShortcutHelp.js +5 -0
- package/dist/tui/components/StatusBar.js +46 -20
- package/dist/tui/components/SteerQueue.js +1 -1
- package/dist/tui/components/ThinkingIndicator.js +6 -4
- package/dist/tui/components/ToolCall.js +10 -4
- package/dist/tui/components/ToolDetail.js +21 -0
- package/dist/tui/help.js +6 -0
- package/dist/tui/hooks/useKeyboardShortcuts.js +15 -1
- package/dist/tui/index.js +0 -1
- package/dist/tui/ink-entry.js +317 -33
- package/dist/tui/tool-render.js +1 -1
- package/dist/user-hooks.js +171 -0
- package/package.json +14 -8
- package/dist/multi/multi-commands.js +0 -170
- package/dist/multi/multi-events.js +0 -98
- package/dist/multi/multi-render.js +0 -147
- package/dist/multi/pane.js +0 -28
- package/dist/multi/tui-multi.js +0 -200
- package/dist/permissions/privacy.js +0 -248
- package/dist/tui/components/AgentMessage.js +0 -5
- package/dist/tui/components/ChatMessage.js +0 -23
- package/dist/tui/components/CodeBlock.js +0 -8
- package/dist/tui/components/Separator.js +0 -7
- package/dist/tui/components/StreamingText.js +0 -5
- package/dist/tui/components/UserMessage.js +0 -5
- package/dist/tui/menu-mode.js +0 -86
- package/dist/tui/mouse.js +0 -71
- package/dist/tui/terminal-control.js +0 -62
- package/dist/tui.js +0 -781
package/dist/config.js
CHANGED
|
@@ -1,10 +1,22 @@
|
|
|
1
|
+
import * as os from "node:os";
|
|
2
|
+
import * as path from "node:path";
|
|
3
|
+
import { loadPermissionMode } from "./settings.js";
|
|
4
|
+
export const AGENT_CONFIG_DIR = ".phren-agent";
|
|
5
|
+
export function agentConfigDir(base) {
|
|
6
|
+
return path.join(base, AGENT_CONFIG_DIR);
|
|
7
|
+
}
|
|
8
|
+
export function agentUserDir(home = os.homedir()) {
|
|
9
|
+
return path.join(home, AGENT_CONFIG_DIR);
|
|
10
|
+
}
|
|
1
11
|
const HELP = `
|
|
2
|
-
phren — coding agent with persistent memory
|
|
12
|
+
phren-agent — coding agent with persistent memory
|
|
3
13
|
|
|
4
|
-
Usage: phren [options] <task>
|
|
14
|
+
Usage: phren-agent [options] <task> (also: phren agent [options] <task>)
|
|
5
15
|
|
|
6
16
|
Options:
|
|
7
|
-
--provider <name> Force provider:
|
|
17
|
+
--provider <name> Force provider: openai-codex, openai, openrouter, anthropic, deepseek,
|
|
18
|
+
openai-compat, ollama
|
|
19
|
+
--base-url <url> Endpoint for openai-compat (or to override deepseek's)
|
|
8
20
|
--model <model> Override LLM model
|
|
9
21
|
--reasoning <level> Reasoning effort: low, medium, high, xhigh
|
|
10
22
|
--project <name> Force phren project context
|
|
@@ -12,10 +24,18 @@ Options:
|
|
|
12
24
|
--max-output <n> Max output tokens per response (default: auto per model)
|
|
13
25
|
--budget <dollars> Max spend in USD (aborts when exceeded)
|
|
14
26
|
--plan Plan mode: show plan before executing tools
|
|
27
|
+
--no-subagents Disable spawn_agent/send_message/list_agents in one-shot mode
|
|
28
|
+
--no-llm-compact Use regex prune summaries instead of LLM compaction
|
|
29
|
+
--sandbox <mode> Kernel write-fence for shell (bwrap): off, auto (default), require
|
|
15
30
|
--permissions <mode> Permission mode: suggest (default), auto-confirm, full-auto
|
|
16
31
|
--yolo Full-auto permissions — no confirmations (alias for --permissions full-auto)
|
|
17
32
|
--interactive, -i Interactive REPL mode (multi-turn conversation)
|
|
18
|
-
--resume
|
|
33
|
+
--resume, -c Resume the newest session's conversation (task optional)
|
|
34
|
+
--session <id> Resume a specific session by id or unique id prefix
|
|
35
|
+
--list-sessions List recent sessions and exit
|
|
36
|
+
-p, --print Headless: no prompts (tool approvals are denied), clean stdout
|
|
37
|
+
--output-format <f> With -p: text (final message), json (one result object),
|
|
38
|
+
stream-json (NDJSON events + result). Implies -p
|
|
19
39
|
--lint-cmd <cmd> Override auto-detected lint command
|
|
20
40
|
--test-cmd <cmd> Override auto-detected test command
|
|
21
41
|
--mcp <command> Connect to an MCP server via stdio (repeatable)
|
|
@@ -30,28 +50,35 @@ Options:
|
|
|
30
50
|
Providers (auto-detected from env, or use --provider):
|
|
31
51
|
openai-codex Uses your ChatGPT/Codex subscription directly (preferred default)
|
|
32
52
|
(no API key needed, flat rate via your subscription)
|
|
33
|
-
Setup: phren auth login
|
|
53
|
+
Setup: phren-agent auth login
|
|
34
54
|
Legacy alias: codex
|
|
35
55
|
openai OPENAI_API_KEY — OpenAI direct (defaults to gpt-5.4)
|
|
36
56
|
openrouter OPENROUTER_API_KEY — routes to any model
|
|
37
57
|
anthropic ANTHROPIC_API_KEY — Claude direct
|
|
58
|
+
deepseek DEEPSEEK_API_KEY — DeepSeek's own API (api.deepseek.com)
|
|
59
|
+
openai-compat PHREN_AGENT_BASE_URL (or --base-url) + PHREN_AGENT_API_KEY —
|
|
60
|
+
any OpenAI-compatible /chat/completions endpoint
|
|
61
|
+
(OpenCode Go/Zen, Together, Fireworks, vLLM, LM Studio…)
|
|
38
62
|
ollama PHREN_OLLAMA_URL — local models (default: localhost:11434)
|
|
39
63
|
|
|
40
64
|
Environment:
|
|
41
65
|
PHREN_AGENT_PROVIDER Force provider via env
|
|
42
66
|
PHREN_AGENT_MODEL Override model via env
|
|
43
67
|
PHREN_AGENT_REASONING Override reasoning effort via env
|
|
68
|
+
PHREN_AGENT_BASE_URL Endpoint for openai-compat
|
|
69
|
+
PHREN_AGENT_API_KEY Key for openai-compat
|
|
44
70
|
|
|
45
71
|
Examples:
|
|
46
|
-
phren "fix the login bug"
|
|
47
|
-
phren --provider openai-codex "add input validation"
|
|
48
|
-
phren --model openai-codex/gpt-5.4 --reasoning high "add input validation"
|
|
49
|
-
phren --provider anthropic --verbose "refactor the database layer"
|
|
72
|
+
phren-agent "fix the login bug"
|
|
73
|
+
phren-agent --provider openai-codex "add input validation"
|
|
74
|
+
phren-agent --model openai-codex/gpt-5.4 --reasoning high "add input validation"
|
|
75
|
+
phren-agent --provider anthropic --verbose "refactor the database layer"
|
|
50
76
|
`.trim();
|
|
51
77
|
export function parseArgs(argv) {
|
|
52
78
|
const args = {
|
|
53
79
|
task: "",
|
|
54
80
|
permissions: "suggest",
|
|
81
|
+
permissionsExplicit: false,
|
|
55
82
|
maxTurns: 50,
|
|
56
83
|
budget: null,
|
|
57
84
|
plan: false,
|
|
@@ -59,6 +86,12 @@ export function parseArgs(argv) {
|
|
|
59
86
|
verbose: false,
|
|
60
87
|
interactive: false,
|
|
61
88
|
resume: false,
|
|
89
|
+
listSessions: false,
|
|
90
|
+
print: false,
|
|
91
|
+
outputFormat: "text",
|
|
92
|
+
noSubagents: false,
|
|
93
|
+
noLlmCompact: false,
|
|
94
|
+
sandbox: "auto",
|
|
62
95
|
mcp: [],
|
|
63
96
|
multi: false,
|
|
64
97
|
help: false,
|
|
@@ -83,11 +116,46 @@ export function parseArgs(argv) {
|
|
|
83
116
|
else if (arg === "--interactive" || arg === "-i") {
|
|
84
117
|
args.interactive = true;
|
|
85
118
|
}
|
|
119
|
+
else if (arg === "--no-subagents") {
|
|
120
|
+
args.noSubagents = true;
|
|
121
|
+
}
|
|
122
|
+
else if (arg === "--no-llm-compact") {
|
|
123
|
+
args.noLlmCompact = true;
|
|
124
|
+
}
|
|
125
|
+
else if (arg === "--sandbox" && argv[i + 1]) {
|
|
126
|
+
const mode = argv[++i];
|
|
127
|
+
if (mode === "off" || mode === "auto" || mode === "require") {
|
|
128
|
+
args.sandbox = mode;
|
|
129
|
+
}
|
|
130
|
+
}
|
|
86
131
|
else if (arg === "--plan") {
|
|
87
132
|
args.plan = true;
|
|
88
133
|
}
|
|
89
|
-
else if (arg === "--resume") {
|
|
134
|
+
else if (arg === "--resume" || arg === "--continue" || arg === "-c") {
|
|
135
|
+
args.resume = true;
|
|
136
|
+
}
|
|
137
|
+
else if (arg === "--session" && argv[i + 1]) {
|
|
90
138
|
args.resume = true;
|
|
139
|
+
args.resumeId = argv[++i];
|
|
140
|
+
}
|
|
141
|
+
else if (arg === "--list-sessions") {
|
|
142
|
+
args.listSessions = true;
|
|
143
|
+
}
|
|
144
|
+
else if (arg === "--print" || arg === "-p") {
|
|
145
|
+
args.print = true;
|
|
146
|
+
}
|
|
147
|
+
else if (arg === "--output-format" && argv[i + 1]) {
|
|
148
|
+
const format = argv[++i];
|
|
149
|
+
if (format === "text" || format === "json" || format === "stream-json") {
|
|
150
|
+
args.outputFormat = format;
|
|
151
|
+
args.print = true;
|
|
152
|
+
}
|
|
153
|
+
else {
|
|
154
|
+
throw new Error(`Unknown --output-format "${format}". Use text, json or stream-json.`);
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
else if (arg === "--base-url" && argv[i + 1]) {
|
|
158
|
+
args.baseUrl = argv[++i];
|
|
91
159
|
}
|
|
92
160
|
else if (arg === "--lint-cmd" && argv[i + 1]) {
|
|
93
161
|
args.lintCmd = argv[++i];
|
|
@@ -133,11 +201,13 @@ export function parseArgs(argv) {
|
|
|
133
201
|
}
|
|
134
202
|
else if (arg === "--yolo") {
|
|
135
203
|
args.permissions = "full-auto";
|
|
204
|
+
args.permissionsExplicit = true;
|
|
136
205
|
}
|
|
137
206
|
else if (arg === "--permissions" && argv[i + 1]) {
|
|
138
207
|
const mode = argv[++i];
|
|
139
208
|
if (mode === "suggest" || mode === "auto-confirm" || mode === "full-auto") {
|
|
140
209
|
args.permissions = mode;
|
|
210
|
+
args.permissionsExplicit = true;
|
|
141
211
|
}
|
|
142
212
|
}
|
|
143
213
|
else if (!arg.startsWith("-")) {
|
|
@@ -158,6 +228,13 @@ export function parseArgs(argv) {
|
|
|
158
228
|
}
|
|
159
229
|
return args;
|
|
160
230
|
}
|
|
231
|
+
export function resolveStartupPermissions(args) {
|
|
232
|
+
if (args.permissionsExplicit)
|
|
233
|
+
return;
|
|
234
|
+
const saved = loadPermissionMode();
|
|
235
|
+
if (saved)
|
|
236
|
+
args.permissions = saved;
|
|
237
|
+
}
|
|
161
238
|
export function printHelp() {
|
|
162
239
|
console.log(HELP);
|
|
163
240
|
}
|
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
import { planPrune } from "./pruner.js";
|
|
2
|
+
import { estimateMessageTokens } from "../context/token-counter.js";
|
|
3
|
+
import { agentProvenance } from "../memory/provenance.js";
|
|
4
|
+
export const DEFAULT_COMPACTION = {
|
|
5
|
+
enabled: true,
|
|
6
|
+
extractKnowledge: true,
|
|
7
|
+
promoteThreshold: 0.8,
|
|
8
|
+
queueThreshold: 0.5,
|
|
9
|
+
minPrunedTokens: 8_000,
|
|
10
|
+
timeoutMs: 60_000,
|
|
11
|
+
maxItems: 8,
|
|
12
|
+
};
|
|
13
|
+
export function resolveCompactionConfig(overrides) {
|
|
14
|
+
const cfg = { ...DEFAULT_COMPACTION, ...overrides };
|
|
15
|
+
if (process.env.PHREN_AGENT_LLM_COMPACT === "0")
|
|
16
|
+
cfg.enabled = false;
|
|
17
|
+
const envThreshold = Number.parseFloat(process.env.PHREN_AGENT_COMPACT_THRESHOLD ?? "");
|
|
18
|
+
if (Number.isFinite(envThreshold) && envThreshold > 0 && envThreshold <= 1) {
|
|
19
|
+
cfg.promoteThreshold = envThreshold;
|
|
20
|
+
}
|
|
21
|
+
const envMin = Number.parseInt(process.env.PHREN_AGENT_COMPACT_MIN_TOKENS ?? "", 10);
|
|
22
|
+
if (Number.isFinite(envMin) && envMin >= 0)
|
|
23
|
+
cfg.minPrunedTokens = envMin;
|
|
24
|
+
return cfg;
|
|
25
|
+
}
|
|
26
|
+
const CHECKPOINT_INSTRUCTION = `[Context checkpoint — this conversation is about to be compacted. Ignore any pending questions above and respond with ONLY the following two sections:]
|
|
27
|
+
|
|
28
|
+
## Checkpoint Summary
|
|
29
|
+
The original task; work completed so far; files created or modified; the current approach and why; unresolved errors or blockers; immediate next steps. Under 400 words, written for an agent resuming this work with no other history.
|
|
30
|
+
|
|
31
|
+
## Knowledge
|
|
32
|
+
A fenced json block: {"items":[{"text":"...","confidence":0.9,"kind":"finding|gotcha|decision"}]}
|
|
33
|
+
Only durable, non-obvious, project-level knowledge worth remembering across sessions (root causes, architecture decisions with rationale, gotchas, workarounds). Confidence is YOUR certainty the item is true and durable, 0 to 1. Use {"items":[]} if nothing qualifies. Never include secrets or credentials.`;
|
|
34
|
+
// ── Response parsing ─────────────────────────────────────────────────────────
|
|
35
|
+
const KNOWLEDGE_HEADING_RE = /^##\s*Knowledge\b.*$/im;
|
|
36
|
+
const SUMMARY_HEADING_RE = /^##\s*Checkpoint Summary\b.*$/im;
|
|
37
|
+
const FENCED_JSON_RE = /```(?:json)?\s*\n([\s\S]*?)```/;
|
|
38
|
+
const MIN_SUMMARY_CHARS = 50;
|
|
39
|
+
/**
|
|
40
|
+
* Extract knowledge items from any response text using the same ladder as the
|
|
41
|
+
* checkpoint parser: fenced json first, bare-object salvage second, [] on any
|
|
42
|
+
* failure. Shared with the session-end reflection.
|
|
43
|
+
*/
|
|
44
|
+
export function extractKnowledgeItems(text) {
|
|
45
|
+
const fenced = text.match(FENCED_JSON_RE);
|
|
46
|
+
if (fenced) {
|
|
47
|
+
const items = parseItems(fenced[1]);
|
|
48
|
+
if (items.length > 0)
|
|
49
|
+
return items;
|
|
50
|
+
}
|
|
51
|
+
const bare = text.match(/\{[\s\S]*"items"[\s\S]*\}/);
|
|
52
|
+
return bare ? parseItems(bare[0]) : [];
|
|
53
|
+
}
|
|
54
|
+
function parseItems(raw) {
|
|
55
|
+
let parsed;
|
|
56
|
+
try {
|
|
57
|
+
parsed = JSON.parse(raw);
|
|
58
|
+
}
|
|
59
|
+
catch {
|
|
60
|
+
return [];
|
|
61
|
+
}
|
|
62
|
+
if (typeof parsed !== "object" || parsed === null)
|
|
63
|
+
return [];
|
|
64
|
+
const items = parsed.items;
|
|
65
|
+
if (!Array.isArray(items))
|
|
66
|
+
return [];
|
|
67
|
+
const valid = [];
|
|
68
|
+
for (const item of items) {
|
|
69
|
+
if (typeof item !== "object" || item === null)
|
|
70
|
+
continue;
|
|
71
|
+
const text = item.text;
|
|
72
|
+
const confidence = item.confidence;
|
|
73
|
+
const kind = item.kind;
|
|
74
|
+
if (typeof text !== "string" || !text.trim())
|
|
75
|
+
continue;
|
|
76
|
+
const conf = typeof confidence === "number" && Number.isFinite(confidence)
|
|
77
|
+
? Math.max(0, Math.min(1, confidence))
|
|
78
|
+
: 0;
|
|
79
|
+
valid.push({ text: text.trim(), confidence: conf, kind: typeof kind === "string" ? kind : "finding" });
|
|
80
|
+
}
|
|
81
|
+
return valid;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Parse the checkpoint response: summary text + knowledge items.
|
|
85
|
+
* Botched JSON never discards the summary; a missing/short summary returns
|
|
86
|
+
* null so the caller falls back to the regex summary.
|
|
87
|
+
*/
|
|
88
|
+
export function parseCheckpointResponse(text) {
|
|
89
|
+
const headingMatch = text.match(KNOWLEDGE_HEADING_RE);
|
|
90
|
+
let summaryPart = text;
|
|
91
|
+
let knowledgePart = "";
|
|
92
|
+
if (headingMatch && headingMatch.index !== undefined) {
|
|
93
|
+
summaryPart = text.slice(0, headingMatch.index);
|
|
94
|
+
knowledgePart = text.slice(headingMatch.index + headingMatch[0].length);
|
|
95
|
+
}
|
|
96
|
+
// Strip the summary heading itself; keep the body.
|
|
97
|
+
const summary = summaryPart.replace(SUMMARY_HEADING_RE, "").trim();
|
|
98
|
+
let items = [];
|
|
99
|
+
if (knowledgePart) {
|
|
100
|
+
const fenced = knowledgePart.match(FENCED_JSON_RE);
|
|
101
|
+
if (fenced) {
|
|
102
|
+
items = parseItems(fenced[1]);
|
|
103
|
+
}
|
|
104
|
+
if (items.length === 0) {
|
|
105
|
+
// Salvage: bare JSON object containing "items" without a fence.
|
|
106
|
+
const bare = knowledgePart.match(/\{[\s\S]*"items"[\s\S]*\}/);
|
|
107
|
+
if (bare)
|
|
108
|
+
items = parseItems(bare[0]);
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
if (summary.length < MIN_SUMMARY_CHARS) {
|
|
112
|
+
return { summary: null, items };
|
|
113
|
+
}
|
|
114
|
+
return { summary, items };
|
|
115
|
+
}
|
|
116
|
+
/** Route knowledge items by confidence. Returns counts; never throws. */
|
|
117
|
+
export async function routeKnowledgeItems(items, opts) {
|
|
118
|
+
const { phrenCtx, sessionId, config } = opts;
|
|
119
|
+
let promoted = 0;
|
|
120
|
+
let queued = 0;
|
|
121
|
+
if (!phrenCtx.project || items.length === 0)
|
|
122
|
+
return { promoted, queued };
|
|
123
|
+
const capped = items.slice(0, config.maxItems);
|
|
124
|
+
const toQueue = [];
|
|
125
|
+
for (const item of capped) {
|
|
126
|
+
if (item.confidence >= config.promoteThreshold) {
|
|
127
|
+
try {
|
|
128
|
+
const { addFindingToFile } = await import("@phren/cli/shared/content");
|
|
129
|
+
const result = addFindingToFile(phrenCtx.phrenPath, phrenCtx.project, item.text, undefined, {
|
|
130
|
+
provenance: agentProvenance(sessionId),
|
|
131
|
+
...(sessionId ? { sessionId } : {}),
|
|
132
|
+
});
|
|
133
|
+
if (result.ok)
|
|
134
|
+
promoted++;
|
|
135
|
+
}
|
|
136
|
+
catch { /* best effort */ }
|
|
137
|
+
}
|
|
138
|
+
else if (item.confidence >= config.queueThreshold) {
|
|
139
|
+
toQueue.push(item);
|
|
140
|
+
}
|
|
141
|
+
// below queueThreshold: dropped
|
|
142
|
+
}
|
|
143
|
+
if (toQueue.length > 0) {
|
|
144
|
+
try {
|
|
145
|
+
const { appendReviewQueue } = await import("@phren/cli/shared/governance");
|
|
146
|
+
const { buildQueueProvenanceMeta } = await import("@phren/cli/cli/extract");
|
|
147
|
+
const meta = buildQueueProvenanceMeta({
|
|
148
|
+
source: "agent",
|
|
149
|
+
...(sessionId ? { sessionId } : {}),
|
|
150
|
+
});
|
|
151
|
+
const result = appendReviewQueue(phrenCtx.phrenPath, phrenCtx.project, "Review", toQueue.map((item) => ({ text: item.text, meta })));
|
|
152
|
+
if (result.ok)
|
|
153
|
+
queued = result.data ?? toQueue.length;
|
|
154
|
+
}
|
|
155
|
+
catch { /* best effort */ }
|
|
156
|
+
}
|
|
157
|
+
return { promoted, queued };
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* Plan a compaction: decide the prune range via planPrune, then try to upgrade
|
|
161
|
+
* the summary via an out-of-band prefix-replay call to the same provider,
|
|
162
|
+
* routing extracted knowledge into phren. Falls back to the regex summary on
|
|
163
|
+
* any failure. Returns null when there is nothing to prune. Never throws.
|
|
164
|
+
*
|
|
165
|
+
* The provider call goes through provider.chat directly (never runTurn), so it
|
|
166
|
+
* cannot recurse into pruning or touch the session log.
|
|
167
|
+
*/
|
|
168
|
+
export async function compactWithLlm(provider, systemPrompt, messages, opts = {}) {
|
|
169
|
+
const config = resolveCompactionConfig(opts.config);
|
|
170
|
+
const plan = planPrune(messages, opts.pruneConfig);
|
|
171
|
+
if (!plan)
|
|
172
|
+
return null;
|
|
173
|
+
const regexResult = { plan, usedLlm: false, promoted: 0, queued: 0 };
|
|
174
|
+
if (!config.enabled || opts.signal?.aborted)
|
|
175
|
+
return regexResult;
|
|
176
|
+
const prunedRange = messages.slice(plan.startIndex, plan.endIndex + 1);
|
|
177
|
+
if (estimateMessageTokens(prunedRange) < config.minPrunedTokens)
|
|
178
|
+
return regexResult;
|
|
179
|
+
let responseText;
|
|
180
|
+
try {
|
|
181
|
+
// Prefix replay: byte-identical system prompt + message prefix up to the
|
|
182
|
+
// end of the pruned range, then one instruction. The provider's KV cache
|
|
183
|
+
// covers the prefix, so this costs roughly one summary generation.
|
|
184
|
+
const prefixMessages = [
|
|
185
|
+
...messages.slice(0, plan.endIndex + 1),
|
|
186
|
+
{ role: "user", content: CHECKPOINT_INSTRUCTION },
|
|
187
|
+
];
|
|
188
|
+
const response = await withTimeout(provider.chat(systemPrompt, prefixMessages, []), config.timeoutMs, opts.signal);
|
|
189
|
+
if (response.usage && opts.costTracker) {
|
|
190
|
+
opts.costTracker.recordUsage(response.usage.input_tokens, response.usage.output_tokens);
|
|
191
|
+
}
|
|
192
|
+
responseText = response.content
|
|
193
|
+
.filter((block) => block.type === "text")
|
|
194
|
+
.map((block) => block.text)
|
|
195
|
+
.join("\n");
|
|
196
|
+
}
|
|
197
|
+
catch {
|
|
198
|
+
return regexResult;
|
|
199
|
+
}
|
|
200
|
+
const { summary, items } = parseCheckpointResponse(responseText);
|
|
201
|
+
let promoted = 0;
|
|
202
|
+
let queued = 0;
|
|
203
|
+
if (config.extractKnowledge && opts.phrenCtx?.project && items.length > 0) {
|
|
204
|
+
const routed = await routeKnowledgeItems(items, {
|
|
205
|
+
phrenCtx: opts.phrenCtx,
|
|
206
|
+
sessionId: opts.sessionId,
|
|
207
|
+
config,
|
|
208
|
+
verbose: opts.verbose,
|
|
209
|
+
});
|
|
210
|
+
promoted = routed.promoted;
|
|
211
|
+
queued = routed.queued;
|
|
212
|
+
}
|
|
213
|
+
if (!summary) {
|
|
214
|
+
// Knowledge may still have routed; the summary falls back to regex.
|
|
215
|
+
return { ...regexResult, promoted, queued };
|
|
216
|
+
}
|
|
217
|
+
const prunedCount = plan.endIndex - plan.startIndex + 1;
|
|
218
|
+
const summaryMessage = {
|
|
219
|
+
role: "user",
|
|
220
|
+
content: `[Context compacted: ${prunedCount} messages summarized]\n\n${summary}`,
|
|
221
|
+
};
|
|
222
|
+
return {
|
|
223
|
+
plan: { ...plan, summaryMessage },
|
|
224
|
+
usedLlm: true,
|
|
225
|
+
promoted,
|
|
226
|
+
queued,
|
|
227
|
+
};
|
|
228
|
+
}
|
|
229
|
+
function withTimeout(promise, ms, signal) {
|
|
230
|
+
return new Promise((resolve, reject) => {
|
|
231
|
+
const timer = setTimeout(() => reject(new Error(`compaction call timed out after ${ms}ms`)), ms);
|
|
232
|
+
const onAbort = () => {
|
|
233
|
+
clearTimeout(timer);
|
|
234
|
+
reject(new Error("compaction aborted"));
|
|
235
|
+
};
|
|
236
|
+
signal?.addEventListener("abort", onAbort, { once: true });
|
|
237
|
+
promise.then((value) => { clearTimeout(timer); signal?.removeEventListener("abort", onAbort); resolve(value); }, (err) => { clearTimeout(timer); signal?.removeEventListener("abort", onAbort); reject(err); });
|
|
238
|
+
});
|
|
239
|
+
}
|
package/dist/context/pruner.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { toolResultText } from "../providers/types.js";
|
|
1
2
|
import { estimateTokens, estimateMessageTokens } from "./token-counter.js";
|
|
2
3
|
const DEFAULT_CONFIG = {
|
|
3
4
|
contextLimit: 200_000,
|
|
@@ -11,7 +12,7 @@ export function shouldPrune(systemPrompt, messages, config) {
|
|
|
11
12
|
return (systemTokens + msgTokens) > limit * 0.75;
|
|
12
13
|
}
|
|
13
14
|
// ── Fact extraction (regex only, no LLM) ────────────────────────────────────
|
|
14
|
-
const FILE_TOOL_NAMES = new Set(["edit_file", "write_file"]);
|
|
15
|
+
const FILE_TOOL_NAMES = new Set(["edit_file", "multi_edit", "write_file"]);
|
|
15
16
|
const SEARCH_TOOL_NAMES = new Set(["phren_search"]);
|
|
16
17
|
const DECISION_RE = /\b(?:I'll|Let's|The fix is|Changed|because|decided to|switched to|replaced|removed|added|created|updated|refactored)\b/i;
|
|
17
18
|
/** Extract key facts from messages about to be pruned. Fast regex-only scan. */
|
|
@@ -49,7 +50,8 @@ export function extractFacts(messages) {
|
|
|
49
50
|
}
|
|
50
51
|
function extractFromToolUse(block, filesSet, searchesSet) {
|
|
51
52
|
if (FILE_TOOL_NAMES.has(block.name)) {
|
|
52
|
-
|
|
53
|
+
// The tools take `path`; `file_path` is kept for older recorded sessions.
|
|
54
|
+
const fp = block.input?.path ?? block.input?.file_path;
|
|
53
55
|
if (typeof fp === "string" && fp) {
|
|
54
56
|
filesSet.add(fp);
|
|
55
57
|
}
|
|
@@ -62,7 +64,7 @@ function extractFromToolUse(block, filesSet, searchesSet) {
|
|
|
62
64
|
}
|
|
63
65
|
}
|
|
64
66
|
function extractError(block, errorsSet) {
|
|
65
|
-
const firstLine = block.
|
|
67
|
+
const firstLine = toolResultText(block).split("\n")[0].trim();
|
|
66
68
|
if (firstLine) {
|
|
67
69
|
// Cap length to keep summary concise
|
|
68
70
|
errorsSet.add(firstLine.length > 120 ? firstLine.slice(0, 120) + "..." : firstLine);
|
|
@@ -105,16 +107,19 @@ function formatFactSummary(middle, toolsUsed) {
|
|
|
105
107
|
}
|
|
106
108
|
return lines.join("\n");
|
|
107
109
|
}
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
110
|
+
/**
|
|
111
|
+
* Plan a prune, keeping the first message (original task) and the last N turn
|
|
112
|
+
* pairs. Returns null when there is nothing worth pruning. The caller applies
|
|
113
|
+
* the plan — the session log records it as a durable replace, so the pruned
|
|
114
|
+
* range survives in the log even though the model no longer sees it.
|
|
115
|
+
*/
|
|
116
|
+
export function planPrune(messages, config) {
|
|
111
117
|
const keepRecent = config?.keepRecentTurns ?? DEFAULT_CONFIG.keepRecentTurns;
|
|
112
118
|
const keepRecentMessages = keepRecent * 2; // each turn = user + assistant
|
|
113
119
|
// Not enough messages to prune
|
|
114
120
|
if (messages.length <= keepRecentMessages + 1) {
|
|
115
|
-
return
|
|
121
|
+
return null;
|
|
116
122
|
}
|
|
117
|
-
const first = messages[0]; // original task
|
|
118
123
|
// Walk backwards from split point to ensure tail starts with a user text message,
|
|
119
124
|
// not a tool_result-only message (which would be orphaned without its tool_use).
|
|
120
125
|
let splitIdx = messages.length - keepRecentMessages;
|
|
@@ -130,8 +135,18 @@ export function pruneMessages(messages, config) {
|
|
|
130
135
|
}
|
|
131
136
|
splitIdx--;
|
|
132
137
|
}
|
|
138
|
+
if (splitIdx <= 1) {
|
|
139
|
+
// A single long tool loop (the usual one-shot run) has no later user
|
|
140
|
+
// text message at all: every user message is tool results. Split before
|
|
141
|
+
// an assistant message instead; the tail then opens with a complete
|
|
142
|
+
// tool_use/tool_result pair and never orphans a result.
|
|
143
|
+
splitIdx = messages.length - keepRecentMessages;
|
|
144
|
+
while (splitIdx > 1 && messages[splitIdx].role !== "assistant")
|
|
145
|
+
splitIdx--;
|
|
146
|
+
if (splitIdx <= 1)
|
|
147
|
+
return null;
|
|
148
|
+
}
|
|
133
149
|
const middle = messages.slice(1, splitIdx);
|
|
134
|
-
const tail = messages.slice(splitIdx);
|
|
135
150
|
// Collect tool names used in the pruned middle section
|
|
136
151
|
const toolsUsed = new Set();
|
|
137
152
|
for (const msg of middle) {
|
|
@@ -143,9 +158,20 @@ export function pruneMessages(messages, config) {
|
|
|
143
158
|
}
|
|
144
159
|
}
|
|
145
160
|
}
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
161
|
+
return {
|
|
162
|
+
startIndex: 1,
|
|
163
|
+
endIndex: splitIdx - 1,
|
|
164
|
+
summaryMessage: { role: "user", content: formatFactSummary(middle, toolsUsed) },
|
|
149
165
|
};
|
|
150
|
-
|
|
166
|
+
}
|
|
167
|
+
/** Prune messages, keeping the first (original task) and last N turn pairs. */
|
|
168
|
+
export function pruneMessages(messages, config) {
|
|
169
|
+
const plan = planPrune(messages, config);
|
|
170
|
+
if (!plan)
|
|
171
|
+
return messages;
|
|
172
|
+
return [
|
|
173
|
+
...messages.slice(0, plan.startIndex),
|
|
174
|
+
plan.summaryMessage,
|
|
175
|
+
...messages.slice(plan.endIndex + 1),
|
|
176
|
+
];
|
|
151
177
|
}
|
|
@@ -1,7 +1,18 @@
|
|
|
1
|
+
import { toolResultText } from "../providers/types.js";
|
|
1
2
|
/** Rough token estimate: ~4 chars per token. */
|
|
2
3
|
export function estimateTokens(text) {
|
|
3
4
|
return Math.ceil(text.length / 4);
|
|
4
5
|
}
|
|
6
|
+
/**
|
|
7
|
+
* Estimate image tokens from base64 length. Anthropic prices roughly
|
|
8
|
+
* width*height/750; for typical screenshots the byte count tracks pixel
|
|
9
|
+
* count closely enough that bytes/750 (base64Len * 3/4 / 750) is a usable
|
|
10
|
+
* heuristic — the point is that an image never counts as ~40 tokens of
|
|
11
|
+
* block metadata the way an uncounted block would.
|
|
12
|
+
*/
|
|
13
|
+
export function estimateImageTokens(base64Data) {
|
|
14
|
+
return Math.max(64, Math.ceil((base64Data.length * 3) / 4 / 750));
|
|
15
|
+
}
|
|
5
16
|
/** Estimate total tokens across a message array. */
|
|
6
17
|
export function estimateMessageTokens(messages) {
|
|
7
18
|
let total = 0;
|
|
@@ -16,11 +27,32 @@ export function estimateMessageTokens(messages) {
|
|
|
16
27
|
total += estimateTokens(block.text);
|
|
17
28
|
}
|
|
18
29
|
else if (block.type === "tool_result") {
|
|
19
|
-
total += estimateTokens(block
|
|
30
|
+
total += estimateTokens(toolResultText(block));
|
|
31
|
+
if (Array.isArray(block.content)) {
|
|
32
|
+
for (const part of block.content) {
|
|
33
|
+
if (part.type === "image")
|
|
34
|
+
total += estimateImageTokens(part.source.data);
|
|
35
|
+
}
|
|
36
|
+
}
|
|
20
37
|
}
|
|
21
38
|
else if (block.type === "tool_use") {
|
|
22
39
|
total += estimateTokens(JSON.stringify(block.input));
|
|
23
40
|
}
|
|
41
|
+
else if (block.type === "reasoning") {
|
|
42
|
+
// Reasoning text plus the round-trip payload (encrypted_content can
|
|
43
|
+
// dominate on Codex; it is re-sent on every request).
|
|
44
|
+
total += estimateTokens(block.text);
|
|
45
|
+
if (block.encrypted_content)
|
|
46
|
+
total += estimateTokens(block.encrypted_content);
|
|
47
|
+
}
|
|
48
|
+
else if (block.type === "image") {
|
|
49
|
+
total += estimateImageTokens(block.source.data);
|
|
50
|
+
}
|
|
51
|
+
else {
|
|
52
|
+
// Never let an unknown block count as 0 tokens: pruning decisions
|
|
53
|
+
// would silently under-count and overrun the real context window.
|
|
54
|
+
total += estimateTokens(JSON.stringify(block));
|
|
55
|
+
}
|
|
24
56
|
}
|
|
25
57
|
}
|
|
26
58
|
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import * as fs from "node:fs";
|
|
2
|
+
import * as os from "node:os";
|
|
3
|
+
import * as path from "node:path";
|
|
4
|
+
import { agentConfigDir, agentUserDir } from "./config.js";
|
|
5
|
+
export function parseCommandMarkdown(raw) {
|
|
6
|
+
const normalized = raw.replace(/^\uFEFF/, "");
|
|
7
|
+
const match = normalized.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
|
|
8
|
+
if (!match)
|
|
9
|
+
return { body: normalized.trim() };
|
|
10
|
+
const frontmatter = match[1];
|
|
11
|
+
const body = normalized.slice(match[0].length).trim();
|
|
12
|
+
let description;
|
|
13
|
+
for (const line of frontmatter.split(/\r?\n/)) {
|
|
14
|
+
const m = line.match(/^description\s*:\s*(.*)$/);
|
|
15
|
+
if (m) {
|
|
16
|
+
description = m[1].trim().replace(/^["']|["']$/g, "");
|
|
17
|
+
break;
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
return { description, body };
|
|
21
|
+
}
|
|
22
|
+
export function substituteArguments(body, args) {
|
|
23
|
+
const trimmed = args.trim();
|
|
24
|
+
const tokens = trimmed.length > 0 ? trimmed.split(/\s+/) : [];
|
|
25
|
+
let out = body.replace(/\$ARGUMENTS\b/g, trimmed);
|
|
26
|
+
out = out.replace(/\$([1-9])\b/g, (_match, index) => tokens[Number(index) - 1] ?? "");
|
|
27
|
+
return out;
|
|
28
|
+
}
|
|
29
|
+
export function expandCustomCommand(command, args) {
|
|
30
|
+
return substituteArguments(command.body, args).trim();
|
|
31
|
+
}
|
|
32
|
+
export function loadCustomCommands(cwd = process.cwd(), options = {}) {
|
|
33
|
+
const home = options.home ?? os.homedir();
|
|
34
|
+
const sources = [
|
|
35
|
+
{ dir: path.join(agentUserDir(home), "commands"), source: "user" },
|
|
36
|
+
{ dir: path.join(agentConfigDir(cwd), "commands"), source: "project" },
|
|
37
|
+
];
|
|
38
|
+
const byName = new Map();
|
|
39
|
+
for (const { dir, source } of sources) {
|
|
40
|
+
let entries;
|
|
41
|
+
try {
|
|
42
|
+
entries = fs.readdirSync(dir);
|
|
43
|
+
}
|
|
44
|
+
catch {
|
|
45
|
+
continue;
|
|
46
|
+
}
|
|
47
|
+
for (const entry of entries) {
|
|
48
|
+
if (!entry.endsWith(".md"))
|
|
49
|
+
continue;
|
|
50
|
+
const name = entry.slice(0, -3).trim();
|
|
51
|
+
if (!name)
|
|
52
|
+
continue;
|
|
53
|
+
const file = path.join(dir, entry);
|
|
54
|
+
let raw;
|
|
55
|
+
try {
|
|
56
|
+
raw = fs.readFileSync(file, "utf-8");
|
|
57
|
+
}
|
|
58
|
+
catch {
|
|
59
|
+
continue;
|
|
60
|
+
}
|
|
61
|
+
const { description, body } = parseCommandMarkdown(raw);
|
|
62
|
+
byName.set(name, { name, description, body, source, path: file });
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
|
|
66
|
+
}
|
|
67
|
+
export function customCommandInfos(commands) {
|
|
68
|
+
return commands.map((command) => ({ name: command.name, description: command.description }));
|
|
69
|
+
}
|