@phren/agent 0.3.18 → 0.3.20

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.
@@ -3,14 +3,14 @@ import { shouldPrune } from "../context/pruner.js";
3
3
  import { compactWithLlm } from "../context/compactor.js";
4
4
  import { estimateMessageTokens } from "../context/token-counter.js";
5
5
  import { isContextOverflowError, withRetry } from "../providers/retry.js";
6
- import { checkFlushNeeded } from "../memory/context-flush.js";
7
6
  import { injectPlanPrompt, requestPlanApproval } from "../plan.js";
8
7
  import { detectLintCommand, detectTestCommand } from "../tools/lint-test.js";
9
8
  import { createCheckpoint } from "../checkpoint.js";
10
9
  import { resetRepeatChain } from "../guards/repeat-tool-reminder.js";
11
10
  import { runLifecycleHooks } from "../user-hooks.js";
11
+ import { recordTokenUsage } from "../cost.js";
12
12
  import { createSession } from "./types.js";
13
- import { consumeStream, executeToolBlocks, prefetchFirst, runToolsConcurrently } from "./stream.js";
13
+ import { consumeStream, executeToolBlocks, runToolsConcurrently } from "./stream.js";
14
14
  export { createSession };
15
15
  /**
16
16
  * If the history ends with an assistant message whose tool calls have no
@@ -53,11 +53,14 @@ export async function runTurn(userInput, session, config, hooks) {
53
53
  // Direct user input resets the repeat-call chain (repetition across it is not a loop)
54
54
  resetRepeatChain(session.repeatChain);
55
55
  // Append user message to the durable log
56
- session.log.append("user/message", {
56
+ const prompted = session.log.append("user/message", {
57
57
  message: { role: "user", content: userInput },
58
58
  source: "user",
59
59
  turn: session.turns,
60
60
  });
61
+ // Phren Hook streams the text block being written from this sidecar; the
62
+ // turn is named by the time of the prompt that started it.
63
+ const preview = config.livePreview?.(session.log.header.sessionId);
61
64
  let turnToolCalls = 0;
62
65
  const turnStart = session.turns;
63
66
  // A refusal applies to automatic checks for this entire user turn.
@@ -86,20 +89,12 @@ export async function runTurn(userInput, session, config, hooks) {
86
89
  if (verbose && session.turns > turnStart) {
87
90
  status(`\n${formatTurnHeader(session.turns + 1, turnToolCalls)}\n`);
88
91
  }
89
- // Check if context flush is needed (one-time per session) — must run before pruning
90
- const contextLimit = provider.contextWindow ?? 200_000;
91
- const flushPrompt = checkFlushNeeded(systemPrompt, session.messages, session.flushConfig);
92
- if (flushPrompt) {
93
- session.log.append("user/message", {
94
- message: { role: "user", content: flushPrompt },
95
- source: "system",
96
- turn: session.turns,
97
- });
98
- if (verbose)
99
- status("[context flush injected]\n");
100
- }
101
92
  // Prune context if approaching limit — LLM checkpoint with knowledge
102
- // promotion, degrading to the regex summary on any failure.
93
+ // promotion, degrading to the regex summary on any failure. (There is no
94
+ // separate "summarize what you learned" prompt: injected mid-task, the
95
+ // model answered it and ended the turn, and compaction already promotes
96
+ // knowledge to phren out of band.)
97
+ const contextLimit = provider.contextWindow ?? 200_000;
103
98
  const compactHistory = async (keepRecentTurns, trigger) => {
104
99
  const preCount = session.messages.length;
105
100
  const preTokens = estimateMessageTokens(session.messages);
@@ -140,20 +135,46 @@ export async function runTurn(userInput, session, config, hooks) {
140
135
  }
141
136
  let assistantContent;
142
137
  let stopReason;
138
+ let invalidToolCalls = [];
143
139
  try {
144
140
  if (useStream) {
145
- // Streaming path — retry the initial connection. The async generator does
146
- // no work until first read, so the first next() runs inside withRetry.
147
- const opening = await withRetry(async () => {
148
- const iterator = provider.chatStream(systemPrompt, session.messages, turnTools, signal)[Symbol.asyncIterator]();
149
- const first = await iterator.next();
150
- return { iterator, first };
151
- }, undefined, verbose, signal);
141
+ // Streaming path — the whole request is retried, not just opening it:
142
+ // a stream that drops, stalls into an incomplete end, or reports a
143
+ // retryable failure mid-response is requested again. Nothing has run
144
+ // yet (tools execute after the stream completes), so the only cost is
145
+ // the partial text already shown, dropped before the backoff wait.
152
146
  const onReasoningDelta = hooks?.onReasoningDelta ??
153
147
  (verbose ? (text) => process.stderr.write(`\x1b[2m${text}\x1b[0m`) : undefined);
154
- const result = await consumeStream(prefetchFirst(opening.iterator, opening.first), costTracker, { onTextDelta: hooks?.onTextDelta, onReasoningDelta, providerName: provider.name }, signal);
148
+ const onTextDelta = hooks?.onTextDelta ?? process.stdout.write.bind(process.stdout);
149
+ // Text this attempt has shown, for UIs that cannot take it back.
150
+ let shown = "";
151
+ const onRetry = () => {
152
+ if (hooks?.onStreamRetry) {
153
+ hooks.onStreamRetry();
154
+ }
155
+ else if (shown && !shown.endsWith("\n")) {
156
+ // Plain stdout (the REPL, one-shot) cannot erase the abandoned
157
+ // text; end its line so the restarted reply begins on its own.
158
+ onTextDelta("\n");
159
+ }
160
+ status(shown
161
+ ? "\x1b[33m[model request failed; retrying, the reply starts again]\x1b[0m\n"
162
+ : "\x1b[33m[model request failed; retrying]\x1b[0m\n");
163
+ shown = "";
164
+ // The phone's live preview drops the abandoned attempt's text too.
165
+ preview?.clear();
166
+ };
167
+ const result = await withRetry(async () => {
168
+ preview?.start(prompted.time);
169
+ return consumeStream(provider.chatStream(systemPrompt, session.messages, turnTools, signal), costTracker, {
170
+ onTextDelta: (text) => { shown += text; onTextDelta(text); preview?.append(text); },
171
+ onReasoningDelta,
172
+ providerName: provider.name,
173
+ }, signal);
174
+ }, { onRetry }, verbose, signal);
155
175
  assistantContent = result.content;
156
176
  stopReason = result.stop_reason;
177
+ invalidToolCalls = result.invalidToolCalls;
157
178
  }
158
179
  else {
159
180
  // Batch path
@@ -162,9 +183,10 @@ export async function runTurn(userInput, session, config, hooks) {
162
183
  spinner.stop();
163
184
  assistantContent = response.content;
164
185
  stopReason = response.stop_reason;
186
+ invalidToolCalls = response.invalidToolCalls ?? [];
165
187
  // Track cost from batch response
166
188
  if (costTracker && response.usage) {
167
- costTracker.recordUsage(response.usage.input_tokens, response.usage.output_tokens);
189
+ recordTokenUsage(costTracker, response.usage);
168
190
  }
169
191
  // Print text blocks (streaming already prints inline)
170
192
  for (const block of assistantContent) {
@@ -183,6 +205,7 @@ export async function runTurn(userInput, session, config, hooks) {
183
205
  }
184
206
  catch (err) {
185
207
  spinner.stop();
208
+ preview?.clear();
186
209
  // The token estimate is approximate; when the provider itself says the
187
210
  // prompt is too long, compact harder (keep 2 turns) and retry once.
188
211
  if (!overflowRecovered && !signal?.aborted && isContextOverflowError(err)) {
@@ -212,6 +235,8 @@ export async function runTurn(userInput, session, config, hooks) {
212
235
  stop_reason: stopReason,
213
236
  turn: session.turns,
214
237
  });
238
+ // Only after the message is in the log, so a reader never sees neither.
239
+ preview?.clear();
215
240
  session.turns++;
216
241
  hooks?.onAssistantMessage?.(assistantContent, stopReason);
217
242
  // Abort check after LLM response. Tool calls the model already made must
@@ -260,9 +285,13 @@ export async function runTurn(userInput, session, config, hooks) {
260
285
  });
261
286
  continue;
262
287
  }
263
- // If max_tokens, warn user and inject continuation prompt
288
+ // If max_tokens, warn user and inject continuation prompt. Complete tool
289
+ // calls in the truncated response are not run (the response may have been
290
+ // cut mid-batch), but each still needs a result or every later request
291
+ // carries an unpaired tool_use.
264
292
  if (stopReason === "max_tokens") {
265
293
  status("\x1b[33m[response truncated: max_tokens reached, requesting continuation]\x1b[0m\n");
294
+ closeDanglingToolUses(session, "Not executed: your response was truncated at max_tokens. Issue the call again if it is still needed.");
266
295
  session.log.append("user/message", {
267
296
  message: { role: "user", content: "Your response was truncated due to length. Please continue where you left off." },
268
297
  source: "system",
@@ -275,12 +304,15 @@ export async function runTurn(userInput, session, config, hooks) {
275
304
  endReason = "end_turn";
276
305
  break;
277
306
  }
278
- // Execute tool calls with concurrency
307
+ // Execute tool calls with concurrency. Calls whose arguments were not
308
+ // valid JSON are answered with an error instead of being run.
279
309
  const toolUseBlocks = assistantContent.filter((b) => b.type === "tool_use");
310
+ const invalidById = new Map(invalidToolCalls.map((call) => [call.id, call]));
311
+ const runnableBlocks = toolUseBlocks.filter((b) => !invalidById.has(b.id));
280
312
  // Checkpoint BEFORE the mutating batch: the tool names are known now, and
281
313
  // the snapshot must be the true pre-turn tree so /rewind can restore it.
282
314
  const mutatingTools = new Set(["edit_file", "multi_edit", "apply_patch", "write_file"]);
283
- const hasMutation = toolUseBlocks.some(b => mutatingTools.has(b.name));
315
+ const hasMutation = runnableBlocks.some(b => mutatingTools.has(b.name));
284
316
  if (hasMutation) {
285
317
  createCheckpoint(process.cwd(), `turn-${session.turns}`);
286
318
  }
@@ -295,7 +327,7 @@ export async function runTurn(userInput, session, config, hooks) {
295
327
  }
296
328
  if (!hooks?.onToolStart)
297
329
  spinner.start(`Running ${toolUseBlocks.length} tool${toolUseBlocks.length > 1 ? "s" : ""}...`);
298
- const { results: toolResults, toolCallCount } = await executeToolBlocks(toolUseBlocks, {
330
+ const { results: executedResults, toolCallCount } = await executeToolBlocks(runnableBlocks, {
299
331
  registry, verbose, status, hooks, signal,
300
332
  antiPatterns: session.antiPatterns,
301
333
  captureState: session.captureState,
@@ -305,8 +337,20 @@ export async function runTurn(userInput, session, config, hooks) {
305
337
  });
306
338
  if (!hooks?.onToolStart)
307
339
  spinner.stop();
308
- session.toolCalls += toolCallCount;
309
- turnToolCalls += toolCallCount;
340
+ // Results in the model's call order, invalid calls answered in place.
341
+ const resultById = new Map(executedResults.flatMap((r) => (r.type === "tool_result" ? [[r.tool_use_id, r]] : [])));
342
+ const toolResults = toolUseBlocks.map((block) => {
343
+ const invalid = invalidById.get(block.id);
344
+ if (!invalid)
345
+ return resultById.get(block.id);
346
+ const sample = invalid.raw.length > 300 ? `${invalid.raw.slice(0, 300)}…` : invalid.raw;
347
+ const output = `Not run: the arguments for ${block.name} were not valid JSON (${invalid.error}). ` +
348
+ `Call the tool again with a JSON object of arguments. You sent: ${sample}`;
349
+ hooks?.onToolEnd?.(block.name, block.input, output, true, 0);
350
+ return { type: "tool_result", tool_use_id: block.id, content: output, is_error: true };
351
+ });
352
+ session.toolCalls += toolCallCount + invalidById.size;
353
+ turnToolCalls += toolCallCount + invalidById.size;
310
354
  // Only successful write/edit results justify checks; requested, denied,
311
355
  // failed, or cancelled mutations must never launch a follow-up command.
312
356
  const successfulMutation = toolUseBlocks.some((block) => mutatingTools.has(block.name)
@@ -1,4 +1,7 @@
1
+ import { partialUsage } from "../providers/types.js";
2
+ import { parseToolArguments } from "../providers/openai-compat.js";
1
3
  import { chainKey, recordCall } from "../guards/repeat-tool-reminder.js";
4
+ import { recordTokenUsage } from "../cost.js";
2
5
  import { searchErrorRecovery } from "../memory/error-recovery.js";
3
6
  import { analyzeAndCapture } from "../memory/auto-capture.js";
4
7
  import { DIFF_MARKER } from "../multi/diff-renderer.js";
@@ -148,74 +151,78 @@ export async function consumeStream(stream, costTracker, hooks, signal) {
148
151
  });
149
152
  currentReasoning = "";
150
153
  };
151
- for await (const delta of stream) {
152
- if (signal?.aborted)
153
- break;
154
- if (delta.type === "text_delta") {
155
- (onTextDelta ?? process.stdout.write.bind(process.stdout))(delta.text);
156
- currentText += delta.text;
157
- }
158
- else if (delta.type === "reasoning_delta") {
159
- // Preserve stream order: a reasoning segment starting after visible
160
- // text closes that text block first (providers normally emit
161
- // reasoning before text, so this is the uncommon direction).
162
- if (currentText && !currentReasoning) {
163
- content.push({ type: "text", text: currentText });
164
- currentText = "";
165
- }
166
- onReasoningDelta?.(delta.text);
167
- currentReasoning += delta.text;
168
- }
169
- else if (delta.type === "reasoning_end") {
170
- flushReasoning(delta);
171
- }
172
- else if (delta.type === "tool_use_start") {
173
- // Flush accumulated reasoning (without a reasoning_end, e.g. compat
174
- // providers that only emit deltas), then text.
175
- flushReasoning();
176
- if (currentText) {
177
- content.push({ type: "text", text: currentText });
178
- currentText = "";
154
+ try {
155
+ for await (const delta of stream) {
156
+ if (signal?.aborted)
157
+ break;
158
+ if (delta.type === "text_delta") {
159
+ (onTextDelta ?? process.stdout.write.bind(process.stdout))(delta.text);
160
+ currentText += delta.text;
179
161
  }
180
- toolsByIndex.set(delta.id, { id: delta.id, name: delta.name, jsonParts: [] });
181
- }
182
- else if (delta.type === "tool_use_delta") {
183
- const tool = toolsByIndex.get(delta.id);
184
- if (tool)
185
- tool.jsonParts.push(delta.json);
186
- }
187
- else if (delta.type === "tool_use_end") {
188
- const tool = toolsByIndex.get(delta.id);
189
- if (tool) {
190
- const jsonStr = tool.jsonParts.join("");
191
- let input = null;
192
- try {
193
- const parsed = JSON.parse(jsonStr);
194
- if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
195
- input = parsed;
196
- }
162
+ else if (delta.type === "reasoning_delta") {
163
+ // Preserve stream order: a reasoning segment starting after visible
164
+ // text closes that text block first (providers normally emit
165
+ // reasoning before text, so this is the uncommon direction).
166
+ if (currentText && !currentReasoning) {
167
+ content.push({ type: "text", text: currentText });
168
+ currentText = "";
197
169
  }
198
- catch { /* fall through to malformed handling */ }
199
- if (input) {
200
- content.push({ type: "tool_use", id: tool.id, name: tool.name, input });
170
+ onReasoningDelta?.(delta.text);
171
+ currentReasoning += delta.text;
172
+ }
173
+ else if (delta.type === "reasoning_end") {
174
+ flushReasoning(delta);
175
+ }
176
+ else if (delta.type === "tool_use_start") {
177
+ // Flush accumulated reasoning (without a reasoning_end, e.g. compat
178
+ // providers that only emit deltas), then text.
179
+ flushReasoning();
180
+ if (currentText) {
181
+ content.push({ type: "text", text: currentText });
182
+ currentText = "";
201
183
  }
202
- else {
203
- // Defer: a malformed call must not become an orphan tool_use on a
204
- // truncated (max_tokens) or text turn, where runTurn never executes
205
- // it. If the turn does end as tool_use, emit it with empty input so
206
- // the tool runs and produces the matching tool_result.
207
- malformedTools.push({ id: tool.id, name: tool.name });
208
- process.stderr.write(`\x1b[33m[warning] Malformed tool_use JSON for ${tool.name} (${tool.id}); using empty input\x1b[0m\n`);
184
+ toolsByIndex.set(delta.id, { id: delta.id, name: delta.name, jsonParts: [] });
185
+ }
186
+ else if (delta.type === "tool_use_delta") {
187
+ const tool = toolsByIndex.get(delta.id);
188
+ if (tool)
189
+ tool.jsonParts.push(delta.json);
190
+ }
191
+ else if (delta.type === "tool_use_end") {
192
+ const tool = toolsByIndex.get(delta.id);
193
+ if (tool) {
194
+ const jsonStr = tool.jsonParts.join("");
195
+ const parsed = parseToolArguments(jsonStr);
196
+ if ("input" in parsed) {
197
+ content.push({ type: "tool_use", id: tool.id, name: tool.name, input: parsed.input });
198
+ }
199
+ else {
200
+ // Defer: a malformed call must not become an orphan tool_use on a
201
+ // truncated (max_tokens) or text turn, where runTurn never answers
202
+ // it. If the turn does end as tool_use, emit it with empty input and
203
+ // report it, so runTurn answers it with an error instead of running
204
+ // the tool with arguments the model never gave.
205
+ malformedTools.push({ id: tool.id, name: tool.name, raw: jsonStr, error: parsed.error });
206
+ process.stderr.write(`\x1b[33m[warning] Malformed tool_use JSON for ${tool.name} (${tool.id}); returning an error to the model\x1b[0m\n`);
207
+ }
209
208
  }
210
209
  }
211
- }
212
- else if (delta.type === "done") {
213
- stop_reason = delta.stop_reason;
214
- if (costTracker && delta.usage) {
215
- costTracker.recordUsage(delta.usage.input_tokens, delta.usage.output_tokens);
210
+ else if (delta.type === "done") {
211
+ stop_reason = delta.stop_reason;
212
+ if (costTracker && delta.usage) {
213
+ recordTokenUsage(costTracker, delta.usage);
214
+ }
216
215
  }
217
216
  }
218
217
  }
218
+ catch (err) {
219
+ // A failed attempt is retried, but what the provider reported it billed
220
+ // still counts toward --budget.
221
+ const usage = partialUsage(err);
222
+ if (costTracker && usage)
223
+ recordTokenUsage(costTracker, usage);
224
+ throw err;
225
+ }
219
226
  // Flush remaining reasoning, then text
220
227
  flushReasoning();
221
228
  if (currentText) {
@@ -225,14 +232,13 @@ export async function consumeStream(stream, costTracker, hooks, signal) {
225
232
  content.push({ type: "text", text: currentText });
226
233
  }
227
234
  // Only a genuine tool_use turn can safely carry a synthesized tool block;
228
- // runTurn executes it and pairs the result. On any other stop reason the
235
+ // runTurn pairs it with an error result. On any other stop reason the
229
236
  // block is dropped so the durable history never holds an orphan tool_use.
230
- if (stop_reason === "tool_use") {
231
- for (const tool of malformedTools) {
232
- content.push({ type: "tool_use", id: tool.id, name: tool.name, input: {} });
233
- }
237
+ const invalidToolCalls = stop_reason === "tool_use" ? malformedTools : [];
238
+ for (const tool of invalidToolCalls) {
239
+ content.push({ type: "tool_use", id: tool.id, name: tool.name, input: {} });
234
240
  }
235
- return { content, stop_reason };
241
+ return { content, stop_reason, invalidToolCalls };
236
242
  }
237
243
  /**
238
244
  * The model-visible part of a tool output. File tools append a full
@@ -1,10 +1,10 @@
1
1
  import { createCaptureState } from "../memory/auto-capture.js";
2
2
  import { AntiPatternTracker } from "../memory/anti-patterns.js";
3
- import { createFlushConfig } from "../memory/context-flush.js";
4
3
  import { SessionLog } from "../session/log.js";
5
4
  import { createRepeatChain } from "../guards/repeat-tool-reminder.js";
6
5
  import { randomUUID } from "crypto";
7
- export function createSession(contextLimit, options) {
6
+ /** The context limit argument is unused (compaction reads the provider's window); kept for callers. */
7
+ export function createSession(_contextLimit, options) {
8
8
  const log = options?.log ??
9
9
  new SessionLog({
10
10
  sessionId: `mem-${randomUUID()}`,
@@ -20,7 +20,6 @@ export function createSession(contextLimit, options) {
20
20
  toolCalls: 0,
21
21
  captureState: createCaptureState(),
22
22
  antiPatterns: new AntiPatternTracker(),
23
- flushConfig: createFlushConfig(contextLimit ?? 200_000),
24
23
  repeatChain: createRepeatChain(),
25
24
  };
26
25
  }
package/dist/bin.js CHANGED
@@ -1,3 +1,8 @@
1
1
  #!/usr/bin/env node
2
- import { runAgentCli } from "./index.js";
3
- runAgentCli(process.argv.slice(2));
2
+ const argv = process.argv.slice(2);
3
+ // `phren-agent models [--json]` lists the model catalog without loading the agent.
4
+ if (argv[0] === "models")
5
+ (await import("./models-list.js")).printModels(argv.slice(1));
6
+ else
7
+ (await import("./index.js")).runAgentCli(argv);
8
+ export {};
@@ -94,7 +94,7 @@ export function costCommand(_parts, ctx) {
94
94
  const ct = ctx.costTracker;
95
95
  if (ct) {
96
96
  const cost = ct.metered ? `$${ct.totalCost.toFixed(4)}` : "included";
97
- process.stderr.write(`${DIM}Tokens — input: ${ct.totalInputTokens} output: ${ct.totalOutputTokens} est. cost: ${cost}${RESET}\n`);
97
+ process.stderr.write(`${DIM}Tokens — input: ${ct.totalInputTokens} cached: ${ct.totalCacheReadTokens} output: ${ct.totalOutputTokens} est. cost: ${cost}${RESET}\n`);
98
98
  }
99
99
  else {
100
100
  process.stderr.write(`${DIM}Cost tracking not available.${RESET}\n`);
package/dist/commands.js CHANGED
@@ -23,7 +23,7 @@ const BUILTIN_COMMAND_NAMES = [
23
23
  "/context", "/model", "/provider", "/preset", "/session", "/history",
24
24
  "/compact", "/diff", "/git", "/mem", "/ask", "/resume", "/review", "/config", "/spawn", "/agents",
25
25
  "/allow",
26
- "/mode", "/permissions", "/verbose", "/theme", "/agent", "/rewind", "/fork",
26
+ "/mode", "/permissions", "/verbose", "/theme", "/agent", "/rewind", "/fork", "/promote",
27
27
  "/exit", "/quit", "/q",
28
28
  ];
29
29
  /**
@@ -134,6 +134,20 @@ export function handleCommand(input, ctx) {
134
134
  case "/review": return reviewCommand(parts, ctx);
135
135
  case "/config": return configCommand(parts, ctx);
136
136
  case "/rewind": return rewindCommand(parts, ctx);
137
+ case "/promote": {
138
+ const promote = ctx.promote;
139
+ if (!promote) {
140
+ process.stderr.write(`${DIM}Already an agent session: /promote turns a quick chat (--mode chat) into one.${RESET}\n`);
141
+ return true;
142
+ }
143
+ return promote().then((message) => {
144
+ process.stderr.write(`\x1b[32m${message}${RESET}\n`);
145
+ return true;
146
+ }, (err) => {
147
+ process.stderr.write(`\x1b[31mPromote failed: ${err instanceof Error ? err.message : String(err)}${RESET}\n`);
148
+ return true;
149
+ });
150
+ }
137
151
  case "/fork": {
138
152
  const result = ctx.forkSession?.();
139
153
  if (!result) {
package/dist/config.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import * as os from "node:os";
2
2
  import * as path from "node:path";
3
+ import { normalizeReasoningEffort } from "./models.js";
3
4
  import { loadPermissionMode } from "./settings.js";
4
5
  export const AGENT_CONFIG_DIR = ".phren-agent";
5
6
  export function agentConfigDir(base) {
@@ -18,12 +19,18 @@ Options:
18
19
  openai-compat, ollama
19
20
  --base-url <url> Endpoint for openai-compat (or to override deepseek's)
20
21
  --model <model> Override LLM model
21
- --reasoning <level> Reasoning effort: low, medium, high, xhigh
22
+ --reasoning <level> Reasoning effort: none, low, medium, high, xhigh (max)
22
23
  --project <name> Force phren project context
23
24
  --max-turns <n> Max tool-use turns (default: 50)
24
25
  --max-output <n> Max output tokens per response (default: auto per model)
26
+ --context-window <n> Context window in tokens, overriding the model catalog
27
+ --price-in <usd> Input price per 1M tokens, overriding the catalog
28
+ --price-out <usd> Output price per 1M tokens
29
+ --price-cache <usd> Cache-hit input price per 1M tokens
25
30
  --budget <dollars> Max spend in USD (aborts when exceeded)
26
31
  --plan Plan mode: show plan before executing tools
32
+ --mode <mode> agent (default) or chat: quick chat with no tools and read-only
33
+ phren memory up front; /promote continues it as an agent
27
34
  --no-subagents Disable spawn_agent/send_message/list_agents in one-shot mode
28
35
  --no-llm-compact Use regex prune summaries instead of LLM compaction
29
36
  --sandbox <mode> Kernel write-fence for shell (bwrap): off, auto (default), require
@@ -65,8 +72,14 @@ Environment:
65
72
  PHREN_AGENT_PROVIDER Force provider via env
66
73
  PHREN_AGENT_MODEL Override model via env
67
74
  PHREN_AGENT_REASONING Override reasoning effort via env
68
- PHREN_AGENT_BASE_URL Endpoint for openai-compat
75
+ PHREN_AGENT_BASE_URL Endpoint for openai-compat (and for deepseek with
76
+ PHREN_AGENT_PROVIDER=deepseek)
69
77
  PHREN_AGENT_API_KEY Key for openai-compat
78
+ PHREN_AGENT_CONTEXT_WINDOW, PHREN_AGENT_PRICE_IN, PHREN_AGENT_PRICE_OUT,
79
+ PHREN_AGENT_PRICE_CACHE Same as the flags, for every model (the flags apply
80
+ only to the model they were given with, and win)
81
+ OpenCode Go (base URL https://opencode.ai/zen/go/v1) is a subscription, so
82
+ its usage shows as included rather than priced.
70
83
 
71
84
  Examples:
72
85
  phren-agent "fix the login bug"
@@ -94,6 +107,7 @@ export function parseArgs(argv) {
94
107
  sandbox: "auto",
95
108
  mcp: [],
96
109
  multi: false,
110
+ mode: "agent",
97
111
  help: false,
98
112
  version: false,
99
113
  };
@@ -131,6 +145,12 @@ export function parseArgs(argv) {
131
145
  else if (arg === "--plan") {
132
146
  args.plan = true;
133
147
  }
148
+ else if (arg === "--mode" && argv[i + 1]) {
149
+ const mode = argv[++i];
150
+ if (mode !== "agent" && mode !== "chat")
151
+ throw new Error(`Unknown --mode "${mode}". Use agent or chat.`);
152
+ args.mode = mode;
153
+ }
134
154
  else if (arg === "--resume" || arg === "--continue" || arg === "-c") {
135
155
  args.resume = true;
136
156
  }
@@ -182,10 +202,7 @@ export function parseArgs(argv) {
182
202
  args.model = argv[++i];
183
203
  }
184
204
  else if (arg === "--reasoning" && argv[i + 1]) {
185
- const value = argv[++i]?.toLowerCase();
186
- if (value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max") {
187
- args.reasoning = value === "max" ? "xhigh" : value;
188
- }
205
+ args.reasoning = normalizeReasoningEffort(argv[++i]) ?? args.reasoning;
189
206
  }
190
207
  else if (arg === "--project" && argv[i + 1]) {
191
208
  args.project = argv[++i];
@@ -196,6 +213,18 @@ export function parseArgs(argv) {
196
213
  else if (arg === "--max-output" && argv[i + 1]) {
197
214
  args.maxOutput = parseInt(argv[++i], 10) || undefined;
198
215
  }
216
+ else if (arg === "--context-window" && argv[i + 1]) {
217
+ args.contextWindow = parsePositive(argv[++i], arg, true);
218
+ }
219
+ else if (arg === "--price-in" && argv[i + 1]) {
220
+ args.priceIn = parsePositive(argv[++i], arg);
221
+ }
222
+ else if (arg === "--price-out" && argv[i + 1]) {
223
+ args.priceOut = parsePositive(argv[++i], arg);
224
+ }
225
+ else if (arg === "--price-cache" && argv[i + 1]) {
226
+ args.priceCache = parsePositive(argv[++i], arg);
227
+ }
199
228
  else if (arg === "--budget" && argv[i + 1]) {
200
229
  args.budget = parseFloat(argv[++i]) || null;
201
230
  }
@@ -221,13 +250,18 @@ export function parseArgs(argv) {
221
250
  args.model = process.env.PHREN_AGENT_MODEL;
222
251
  }
223
252
  if (!args.reasoning && process.env.PHREN_AGENT_REASONING) {
224
- const value = process.env.PHREN_AGENT_REASONING.toLowerCase();
225
- if (value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max") {
226
- args.reasoning = value === "max" ? "xhigh" : value;
227
- }
253
+ args.reasoning = normalizeReasoningEffort(process.env.PHREN_AGENT_REASONING);
228
254
  }
229
255
  return args;
230
256
  }
257
+ /** A non-negative number (prices) or positive integer (token counts); throws on junk. */
258
+ function parsePositive(raw, flag, integer = false) {
259
+ const value = Number(raw.replace(/_/g, ""));
260
+ const ok = integer ? Number.isInteger(value) && value > 0 : Number.isFinite(value) && value >= 0;
261
+ if (!ok)
262
+ throw new Error(`${flag} needs ${integer ? "a positive whole number" : "a number"}, got "${raw}".`);
263
+ return value;
264
+ }
231
265
  export function resolveStartupPermissions(args) {
232
266
  if (args.permissionsExplicit)
233
267
  return;
@@ -1,3 +1,4 @@
1
+ import { recordTokenUsage } from "../cost.js";
1
2
  import { planPrune } from "./pruner.js";
2
3
  import { estimateMessageTokens } from "../context/token-counter.js";
3
4
  import { agentProvenance } from "../memory/provenance.js";
@@ -185,9 +186,12 @@ export async function compactWithLlm(provider, systemPrompt, messages, opts = {}
185
186
  ...messages.slice(0, plan.endIndex + 1),
186
187
  { role: "user", content: CHECKPOINT_INSTRUCTION },
187
188
  ];
188
- const response = await withTimeout(provider.chat(systemPrompt, prefixMessages, []), config.timeoutMs, opts.signal);
189
+ // A timeout or turn abort settles the wait; finally() then cancels the
190
+ // request itself so it doesn't keep generating (and billing) detached.
191
+ const cancel = new AbortController();
192
+ const response = await withTimeout(provider.chat(systemPrompt, prefixMessages, [], cancel.signal), config.timeoutMs, opts.signal).finally(() => cancel.abort());
189
193
  if (response.usage && opts.costTracker) {
190
- opts.costTracker.recordUsage(response.usage.input_tokens, response.usage.output_tokens);
194
+ recordTokenUsage(opts.costTracker, response.usage);
191
195
  }
192
196
  responseText = response.content
193
197
  .filter((block) => block.type === "text")
@@ -107,6 +107,28 @@ function formatFactSummary(middle, toolsUsed) {
107
107
  }
108
108
  return lines.join("\n");
109
109
  }
110
+ /** A user message with text and no tool results: safe to start the kept tail on. */
111
+ function isUserTextBoundary(msg) {
112
+ if (typeof msg.content === "string")
113
+ return true;
114
+ return msg.content.some((b) => b.type === "text") && !msg.content.some((b) => b.type === "tool_result");
115
+ }
116
+ /** Every tool_result in messages[from..] answers a tool_use that is also kept. */
117
+ function tailIsPaired(messages, from) {
118
+ const calls = new Set();
119
+ for (let i = from; i < messages.length; i++) {
120
+ const content = messages[i].content;
121
+ if (typeof content === "string")
122
+ continue;
123
+ for (const block of content) {
124
+ if (block.type === "tool_use")
125
+ calls.add(block.id);
126
+ else if (block.type === "tool_result" && !calls.has(block.tool_use_id))
127
+ return false;
128
+ }
129
+ }
130
+ return true;
131
+ }
110
132
  /**
111
133
  * Plan a prune, keeping the first message (original task) and the last N turn
112
134
  * pairs. Returns null when there is nothing worth pruning. The caller applies
@@ -120,19 +142,15 @@ export function planPrune(messages, config) {
120
142
  if (messages.length <= keepRecentMessages + 1) {
121
143
  return null;
122
144
  }
123
- // Walk backwards from split point to ensure tail starts with a user text message,
124
- // not a tool_result-only message (which would be orphaned without its tool_use).
145
+ // Walk backwards from split point to ensure tail starts with a user text
146
+ // message. A user message that also carries tool results (lint/test
147
+ // follow-ups ride along with them) is not a boundary: its results belong to
148
+ // the assistant call just before it, which would be pruned.
125
149
  let splitIdx = messages.length - keepRecentMessages;
126
150
  while (splitIdx > 1) {
127
151
  const msg = messages[splitIdx];
128
- if (msg.role === "user") {
129
- // Check if this is a text message (not just tool_results)
130
- if (typeof msg.content === "string")
131
- break;
132
- const hasText = msg.content.some((b) => b.type === "text");
133
- if (hasText)
134
- break;
135
- }
152
+ if (msg.role === "user" && isUserTextBoundary(msg) && tailIsPaired(messages, splitIdx))
153
+ break;
136
154
  splitIdx--;
137
155
  }
138
156
  if (splitIdx <= 1) {
@@ -141,7 +159,7 @@ export function planPrune(messages, config) {
141
159
  // an assistant message instead; the tail then opens with a complete
142
160
  // tool_use/tool_result pair and never orphans a result.
143
161
  splitIdx = messages.length - keepRecentMessages;
144
- while (splitIdx > 1 && messages[splitIdx].role !== "assistant")
162
+ while (splitIdx > 1 && (messages[splitIdx].role !== "assistant" || !tailIsPaired(messages, splitIdx)))
145
163
  splitIdx--;
146
164
  if (splitIdx <= 1)
147
165
  return null;