@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.
Files changed (110) hide show
  1. package/README.md +86 -0
  2. package/dist/agent-loop/index.js +239 -65
  3. package/dist/agent-loop/stream.js +212 -29
  4. package/dist/agent-loop/types.js +15 -2
  5. package/dist/checkpoint.js +103 -22
  6. package/dist/commands/info.js +30 -15
  7. package/dist/commands/model.js +6 -2
  8. package/dist/commands/review.js +183 -0
  9. package/dist/commands/session.js +70 -7
  10. package/dist/commands.js +168 -12
  11. package/dist/config.js +87 -10
  12. package/dist/context/compactor.js +239 -0
  13. package/dist/context/pruner.js +39 -13
  14. package/dist/context/token-counter.js +33 -1
  15. package/dist/custom-commands.js +69 -0
  16. package/dist/guards/repeat-tool-reminder.js +75 -0
  17. package/dist/headless.js +115 -0
  18. package/dist/herdr-hooks.js +71 -0
  19. package/dist/index.js +351 -48
  20. package/dist/mcp-client.js +434 -73
  21. package/dist/mcp-oauth.js +121 -0
  22. package/dist/memory/anti-patterns.js +7 -3
  23. package/dist/memory/auto-capture.js +7 -3
  24. package/dist/memory/context.js +92 -73
  25. package/dist/memory/project-context.js +24 -5
  26. package/dist/memory/provenance.js +15 -0
  27. package/dist/memory/review-triage.js +166 -0
  28. package/dist/memory/session.js +36 -1
  29. package/dist/models.js +152 -19
  30. package/dist/multi/child-entry.js +65 -10
  31. package/dist/multi/diff-renderer.js +3 -3
  32. package/dist/multi/markdown.js +125 -27
  33. package/dist/multi/provider-manager.js +8 -0
  34. package/dist/multi/publish.js +72 -0
  35. package/dist/multi/spawner.js +45 -4
  36. package/dist/multi/syntax-highlight.js +25 -4
  37. package/dist/multi/types.js +1 -1
  38. package/dist/permissions/allowlist.js +86 -13
  39. package/dist/permissions/checker.js +42 -7
  40. package/dist/permissions/kernel-sandbox.js +197 -0
  41. package/dist/permissions/prompt.js +10 -1
  42. package/dist/permissions/sandbox.js +40 -17
  43. package/dist/providers/anthropic.js +154 -7
  44. package/dist/providers/codex-auth.js +28 -0
  45. package/dist/providers/codex.js +134 -23
  46. package/dist/providers/history.js +35 -0
  47. package/dist/providers/ollama.js +37 -6
  48. package/dist/providers/openai-compat.js +171 -74
  49. package/dist/providers/openrouter.js +47 -17
  50. package/dist/providers/replay.js +62 -0
  51. package/dist/providers/resolve.js +41 -7
  52. package/dist/providers/retry.js +38 -5
  53. package/dist/providers/types.js +9 -1
  54. package/dist/repl.js +47 -5
  55. package/dist/session/log.js +217 -0
  56. package/dist/session/persist.js +190 -0
  57. package/dist/settings.js +42 -26
  58. package/dist/system-prompt.js +18 -2
  59. package/dist/tools/apply-patch.js +355 -0
  60. package/dist/tools/edit-engine.js +287 -0
  61. package/dist/tools/edit-file.js +86 -27
  62. package/dist/tools/grep.js +25 -10
  63. package/dist/tools/lint-test.js +0 -22
  64. package/dist/tools/mcp-resources.js +51 -6
  65. package/dist/tools/phren-finding.js +12 -4
  66. package/dist/tools/phren-search.js +7 -2
  67. package/dist/tools/read-file.js +37 -9
  68. package/dist/tools/read-image.js +76 -0
  69. package/dist/tools/registry.js +27 -5
  70. package/dist/tools/shell.js +134 -71
  71. package/dist/tools/skill.js +20 -20
  72. package/dist/tools/spawn-agent.js +77 -13
  73. package/dist/tools/update-plan.js +48 -0
  74. package/dist/tools/web-fetch.js +110 -12
  75. package/dist/tools/web-search.js +4 -4
  76. package/dist/tui/components/App.js +98 -26
  77. package/dist/tui/components/ApprovalPanel.js +8 -0
  78. package/dist/tui/components/InputArea.js +5 -5
  79. package/dist/tui/components/ModelPicker.js +43 -0
  80. package/dist/tui/components/PhrenInput.js +10 -5
  81. package/dist/tui/components/PlanReview.js +7 -0
  82. package/dist/tui/components/ShortcutHelp.js +5 -0
  83. package/dist/tui/components/StatusBar.js +46 -20
  84. package/dist/tui/components/SteerQueue.js +1 -1
  85. package/dist/tui/components/ThinkingIndicator.js +6 -4
  86. package/dist/tui/components/ToolCall.js +10 -4
  87. package/dist/tui/components/ToolDetail.js +21 -0
  88. package/dist/tui/help.js +6 -0
  89. package/dist/tui/hooks/useKeyboardShortcuts.js +15 -1
  90. package/dist/tui/index.js +0 -1
  91. package/dist/tui/ink-entry.js +317 -33
  92. package/dist/tui/tool-render.js +1 -1
  93. package/dist/user-hooks.js +171 -0
  94. package/package.json +14 -8
  95. package/dist/multi/multi-commands.js +0 -170
  96. package/dist/multi/multi-events.js +0 -98
  97. package/dist/multi/multi-render.js +0 -147
  98. package/dist/multi/pane.js +0 -28
  99. package/dist/multi/tui-multi.js +0 -200
  100. package/dist/permissions/privacy.js +0 -248
  101. package/dist/tui/components/AgentMessage.js +0 -5
  102. package/dist/tui/components/ChatMessage.js +0 -23
  103. package/dist/tui/components/CodeBlock.js +0 -8
  104. package/dist/tui/components/Separator.js +0 -7
  105. package/dist/tui/components/StreamingText.js +0 -5
  106. package/dist/tui/components/UserMessage.js +0 -5
  107. package/dist/tui/menu-mode.js +0 -86
  108. package/dist/tui/mouse.js +0 -71
  109. package/dist/tui/terminal-control.js +0 -62
  110. 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: openrouter, anthropic, openai, openai-codex, ollama
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 Resume last session's conversation
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
+ }
@@ -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
- const fp = block.input?.file_path;
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.content.split("\n")[0].trim();
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
- // ── Pruner ──────────────────────────────────────────────────────────────────
109
- /** Prune messages, keeping the first (original task) and last N turn pairs. */
110
- export function pruneMessages(messages, config) {
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 messages;
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
- const summaryMessage = {
147
- role: "user",
148
- content: formatFactSummary(middle, toolsUsed),
161
+ return {
162
+ startIndex: 1,
163
+ endIndex: splitIdx - 1,
164
+ summaryMessage: { role: "user", content: formatFactSummary(middle, toolsUsed) },
149
165
  };
150
- return [first, summaryMessage, ...tail];
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.content);
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
+ }