@phren/agent 0.3.19 → 0.3.21

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 (67) hide show
  1. package/dist/agent-loop/index.js +185 -47
  2. package/dist/agent-loop/stream.js +74 -66
  3. package/dist/agent-loop/types.js +2 -3
  4. package/dist/attach-images.js +57 -0
  5. package/dist/bin.js +7 -2
  6. package/dist/commands/info.js +7 -3
  7. package/dist/commands/model.js +55 -13
  8. package/dist/commands/session.js +79 -18
  9. package/dist/commands.js +24 -3
  10. package/dist/config.js +89 -10
  11. package/dist/context/clear-tool-results.js +43 -0
  12. package/dist/context/compactor.js +13 -3
  13. package/dist/context/pruner.js +29 -11
  14. package/dist/context/usage.js +26 -0
  15. package/dist/cost.js +68 -10
  16. package/dist/headless.js +47 -1
  17. package/dist/index.js +335 -127
  18. package/dist/mcp-client.js +38 -1
  19. package/dist/mcp-prompts.js +94 -0
  20. package/dist/memory/chat.js +70 -0
  21. package/dist/memory/context.js +1 -1
  22. package/dist/model-overrides.js +17 -0
  23. package/dist/models-list.js +73 -0
  24. package/dist/models.js +42 -15
  25. package/dist/multi/child-entry.js +18 -28
  26. package/dist/multi/ipc-hooks.js +34 -0
  27. package/dist/multi/spawner.js +49 -3
  28. package/dist/permissions/allowlist.js +19 -4
  29. package/dist/permissions/checker.js +37 -20
  30. package/dist/permissions/kernel-sandbox.js +32 -10
  31. package/dist/permissions/rules.js +173 -0
  32. package/dist/permissions/shell-classify.js +173 -0
  33. package/dist/plan.js +6 -2
  34. package/dist/providers/anthropic.js +119 -75
  35. package/dist/providers/codex.js +10 -9
  36. package/dist/providers/ollama.js +5 -2
  37. package/dist/providers/openai-compat.js +219 -92
  38. package/dist/providers/openrouter.js +12 -7
  39. package/dist/providers/resolve.js +47 -1
  40. package/dist/providers/retry.js +20 -7
  41. package/dist/providers/types.js +31 -0
  42. package/dist/repl.js +17 -1
  43. package/dist/session/persist.js +9 -4
  44. package/dist/session/preview.js +99 -0
  45. package/dist/settings.js +14 -0
  46. package/dist/structured-output.js +85 -0
  47. package/dist/system-prompt.js +117 -14
  48. package/dist/tools/apply-patch.js +15 -1
  49. package/dist/tools/edit-file.js +8 -1
  50. package/dist/tools/file-state.js +88 -0
  51. package/dist/tools/glob.js +53 -35
  52. package/dist/tools/grep.js +139 -53
  53. package/dist/tools/lint-test.js +24 -0
  54. package/dist/tools/read-file.js +2 -0
  55. package/dist/tools/registry.js +8 -1
  56. package/dist/tools/search-support.js +141 -0
  57. package/dist/tools/shell.js +266 -41
  58. package/dist/tools/spawn-agent.js +15 -3
  59. package/dist/tools/syntax-check.js +116 -0
  60. package/dist/tools/write-file.js +11 -3
  61. package/dist/tui/components/App.js +5 -4
  62. package/dist/tui/components/Banner.js +1 -1
  63. package/dist/tui/components/ListPicker.js +32 -0
  64. package/dist/tui/ink-entry.js +79 -15
  65. package/dist/user-hooks.js +26 -4
  66. package/package.json +3 -2
  67. package/dist/memory/context-flush.js +0 -24
@@ -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";
@@ -31,6 +32,12 @@ The original task; work completed so far; files created or modified; the current
31
32
  ## Knowledge
32
33
  A fenced json block: {"items":[{"text":"...","confidence":0.9,"kind":"finding|gotcha|decision"}]}
33
34
  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.`;
35
+ function checkpointInstruction(focus) {
36
+ const trimmed = focus?.trim();
37
+ if (!trimmed)
38
+ return CHECKPOINT_INSTRUCTION;
39
+ return `${CHECKPOINT_INSTRUCTION}\n\nThe user asked the summary to focus on: ${trimmed}. Keep everything about it; shorten the rest.`;
40
+ }
34
41
  // ── Response parsing ─────────────────────────────────────────────────────────
35
42
  const KNOWLEDGE_HEADING_RE = /^##\s*Knowledge\b.*$/im;
36
43
  const SUMMARY_HEADING_RE = /^##\s*Checkpoint Summary\b.*$/im;
@@ -183,11 +190,14 @@ export async function compactWithLlm(provider, systemPrompt, messages, opts = {}
183
190
  // covers the prefix, so this costs roughly one summary generation.
184
191
  const prefixMessages = [
185
192
  ...messages.slice(0, plan.endIndex + 1),
186
- { role: "user", content: CHECKPOINT_INSTRUCTION },
193
+ { role: "user", content: checkpointInstruction(opts.focus) },
187
194
  ];
188
- const response = await withTimeout(provider.chat(systemPrompt, prefixMessages, []), config.timeoutMs, opts.signal);
195
+ // A timeout or turn abort settles the wait; finally() then cancels the
196
+ // request itself so it doesn't keep generating (and billing) detached.
197
+ const cancel = new AbortController();
198
+ const response = await withTimeout(provider.chat(systemPrompt, prefixMessages, opts.tools ?? [], cancel.signal), config.timeoutMs, opts.signal).finally(() => cancel.abort());
189
199
  if (response.usage && opts.costTracker) {
190
- opts.costTracker.recordUsage(response.usage.input_tokens, response.usage.output_tokens);
200
+ recordTokenUsage(opts.costTracker, response.usage);
191
201
  }
192
202
  responseText = response.content
193
203
  .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;
@@ -0,0 +1,26 @@
1
+ import { estimateMessageTokens, estimateTokens } from "./token-counter.js";
2
+ /** Record the size the provider reported, after its reply is in the log. */
3
+ export function reportedContext(usage, log) {
4
+ if (!usage)
5
+ return undefined;
6
+ const prompt = usage.input_tokens + (usage.cache_read_input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0);
7
+ // A provider that reports nothing useful (0 prompt tokens) leaves the estimate in charge.
8
+ if (prompt <= 0)
9
+ return undefined;
10
+ return { tokens: prompt + usage.output_tokens, messageCount: log.getMessages().length, logLength: log.length };
11
+ }
12
+ /** Tokens the next request will carry: reported plus estimated growth, or the estimate alone. */
13
+ export function contextTokens(systemPrompt, messages, log, reported) {
14
+ if (reported && messages.length >= reported.messageCount && log.length >= reported.logLength && !replacedSince(log, reported.logLength)) {
15
+ return reported.tokens + estimateMessageTokens(messages.slice(reported.messageCount));
16
+ }
17
+ return estimateTokens(systemPrompt) + estimateMessageTokens(messages);
18
+ }
19
+ function replacedSince(log, from) {
20
+ const events = log.all;
21
+ for (let i = from; i < events.length; i++) {
22
+ if (events[i].type === "log/replace")
23
+ return true;
24
+ }
25
+ return false;
26
+ }
package/dist/cost.js CHANGED
@@ -1,25 +1,80 @@
1
1
  /** Cost tracking for LLM API usage. */
2
2
  import { lookupPricing } from "./models.js";
3
- export function createCostTracker(model, budget = null, provider) {
4
- const { pricing, metered } = lookupPricing(model, provider);
3
+ import { overridesFor } from "./model-overrides.js";
4
+ /**
5
+ * Price a model and endpoint. The --price-* flags (when this is the model
6
+ * they were given for), then PHREN_AGENT_PRICE_IN/OUT/CACHE (USD per 1M),
7
+ * take precedence over the catalog.
8
+ */
9
+ export function resolvePricing(model, provider, baseUrl) {
10
+ const looked = lookupPricing(model, provider, baseUrl);
11
+ const env = (key) => {
12
+ const raw = process.env[key];
13
+ if (raw === undefined || raw === "")
14
+ return undefined;
15
+ const value = Number(raw);
16
+ return Number.isFinite(value) && value >= 0 ? value : undefined;
17
+ };
18
+ const flags = overridesFor(model);
19
+ const input = flags.priceIn ?? env("PHREN_AGENT_PRICE_IN");
20
+ const output = flags.priceOut ?? env("PHREN_AGENT_PRICE_OUT");
21
+ const cacheRead = flags.priceCache ?? env("PHREN_AGENT_PRICE_CACHE");
22
+ if (input === undefined && output === undefined && cacheRead === undefined)
23
+ return looked;
24
+ // An explicit price means the user is paying per token, even on a route
25
+ // the catalog calls included.
26
+ const cache = cacheRead ?? looked.pricing.cacheReadPer1M;
27
+ return {
28
+ pricing: {
29
+ inputPer1M: input ?? looked.pricing.inputPer1M,
30
+ outputPer1M: output ?? looked.pricing.outputPer1M,
31
+ ...(cache !== undefined ? { cacheReadPer1M: cache } : {}),
32
+ },
33
+ metered: true,
34
+ };
35
+ }
36
+ /** Prompt-cache writes cost this much more than ordinary input. */
37
+ export const CACHE_WRITE_MULTIPLIER = 1.25;
38
+ export function createCostTracker(model, budget = null, provider, baseUrl) {
39
+ let { pricing, metered } = resolvePricing(model, provider, baseUrl);
40
+ // Without a cache price, hits bill as ordinary input (no discount assumed).
41
+ let cacheReadPer1M = pricing.cacheReadPer1M ?? pricing.inputPer1M;
42
+ // Cache writes bill at 1.25x input (Anthropic's 5-minute cache, the one
43
+ // the agent asks for); providers that cache implicitly report none.
44
+ let cacheWritePer1M = pricing.inputPer1M * CACHE_WRITE_MULTIPLIER;
45
+ const price = (input, output, cacheRead, cacheWrite) => (input / 1_000_000) * pricing.inputPer1M +
46
+ (output / 1_000_000) * pricing.outputPer1M +
47
+ (cacheRead / 1_000_000) * cacheReadPer1M +
48
+ (cacheWrite / 1_000_000) * cacheWritePer1M;
5
49
  const tracker = {
6
50
  totalInputTokens: 0,
7
51
  totalOutputTokens: 0,
52
+ totalCacheReadTokens: 0,
53
+ totalCacheWriteTokens: 0,
8
54
  totalCost: 0,
9
55
  budget,
10
56
  metered,
11
- recordUsage(inputTokens, outputTokens) {
57
+ recordUsage(inputTokens, outputTokens, cacheReadTokens = 0, cacheWriteTokens = 0) {
12
58
  tracker.totalInputTokens += inputTokens;
13
59
  tracker.totalOutputTokens += outputTokens;
14
- tracker.totalCost +=
15
- (inputTokens / 1_000_000) * pricing.inputPer1M +
16
- (outputTokens / 1_000_000) * pricing.outputPer1M;
60
+ tracker.totalCacheReadTokens += cacheReadTokens;
61
+ tracker.totalCacheWriteTokens += cacheWriteTokens;
62
+ tracker.totalCost += price(inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens);
63
+ },
64
+ reprice(nextModel, nextProvider, nextBaseUrl) {
65
+ ({ pricing, metered } = resolvePricing(nextModel, nextProvider, nextBaseUrl));
66
+ cacheReadPer1M = pricing.cacheReadPer1M ?? pricing.inputPer1M;
67
+ cacheWritePer1M = pricing.inputPer1M * CACHE_WRITE_MULTIPLIER;
68
+ // Money already spent on a metered model still counts against --budget.
69
+ tracker.metered = metered || tracker.totalCost > 0;
17
70
  },
18
71
  isOverBudget() {
19
72
  return tracker.metered && budget !== null && tracker.totalCost >= budget;
20
73
  },
21
74
  formatCost() {
22
- const tokens = `${tracker.totalInputTokens + tracker.totalOutputTokens} tokens`;
75
+ const total = tracker.totalInputTokens + tracker.totalOutputTokens + tracker.totalCacheReadTokens + tracker.totalCacheWriteTokens;
76
+ const cached = tracker.totalCacheReadTokens > 0 ? `, ${tracker.totalCacheReadTokens} cached` : "";
77
+ const tokens = `${total} tokens${cached}`;
23
78
  if (!tracker.metered) {
24
79
  return `included (${tokens})`;
25
80
  }
@@ -29,11 +84,10 @@ export function createCostTracker(model, budget = null, provider) {
29
84
  const budgetStr = budget !== null ? ` / $${budget.toFixed(2)} budget` : "";
30
85
  return `${cost} (${tokens}${budgetStr})`;
31
86
  },
32
- formatTurnCost(inputTokens, outputTokens) {
87
+ formatTurnCost(inputTokens, outputTokens, cacheReadTokens = 0, cacheWriteTokens = 0) {
33
88
  if (!tracker.metered)
34
89
  return "included";
35
- const turnCost = (inputTokens / 1_000_000) * pricing.inputPer1M +
36
- (outputTokens / 1_000_000) * pricing.outputPer1M;
90
+ const turnCost = price(inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens);
37
91
  return turnCost < 0.01
38
92
  ? `$${turnCost.toFixed(4)}`
39
93
  : `$${turnCost.toFixed(2)}`;
@@ -41,3 +95,7 @@ export function createCostTracker(model, budget = null, provider) {
41
95
  };
42
96
  return tracker;
43
97
  }
98
+ /** Record one response's usage, every bucket included. */
99
+ export function recordTokenUsage(tracker, usage) {
100
+ tracker.recordUsage(usage.input_tokens, usage.output_tokens, usage.cache_read_input_tokens, usage.cache_creation_input_tokens);
101
+ }
package/dist/headless.js CHANGED
@@ -4,6 +4,7 @@ const SUBTYPE = {
4
4
  budget: "error_budget",
5
5
  plan_rejected: "error_plan_rejected",
6
6
  aborted: "cancelled",
7
+ hook_blocked: "error_hook_blocked",
7
8
  };
8
9
  export function buildHeadlessResult(opts) {
9
10
  const subtype = opts.stopReason === "error" ? "error_during_execution" : SUBTYPE[opts.stopReason];
@@ -19,7 +20,12 @@ export function buildHeadlessResult(opts) {
19
20
  session_id: opts.sessionId,
20
21
  provider: opts.provider,
21
22
  model: opts.model,
22
- usage: { input_tokens: tracker?.totalInputTokens ?? 0, output_tokens: tracker?.totalOutputTokens ?? 0 },
23
+ usage: {
24
+ input_tokens: tracker?.totalInputTokens ?? 0,
25
+ output_tokens: tracker?.totalOutputTokens ?? 0,
26
+ cache_read_input_tokens: tracker?.totalCacheReadTokens ?? 0,
27
+ cache_creation_input_tokens: tracker?.totalCacheWriteTokens ?? 0,
28
+ },
23
29
  total_cost_usd: tracker?.metered ? Number(tracker.totalCost.toFixed(6)) : null,
24
30
  permission_denials: opts.permissionDenials,
25
31
  ...(opts.error ? { error: opts.error } : {}),
@@ -106,6 +112,46 @@ export function parseOutputFormat(raw) {
106
112
  return raw;
107
113
  return null;
108
114
  }
115
+ /**
116
+ * One `--input-format stream-json` line: Claude Code's shape,
117
+ * {"type":"user","message":{"role":"user","content":"…" | [{"type":"text","text":"…"}]}}.
118
+ * Returns the prompt text, or an error naming what was wrong.
119
+ */
120
+ export function parseStreamJsonInput(line) {
121
+ let event;
122
+ try {
123
+ event = JSON.parse(line);
124
+ }
125
+ catch {
126
+ return { error: "not JSON" };
127
+ }
128
+ const e = event;
129
+ if (e?.type !== "user" || !e.message || e.message.role !== "user")
130
+ return { error: "expected {\"type\":\"user\",\"message\":{\"role\":\"user\",…}}" };
131
+ const content = e.message.content;
132
+ const prompt = typeof content === "string"
133
+ ? content
134
+ : Array.isArray(content)
135
+ ? content.filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n")
136
+ : "";
137
+ return prompt.trim() ? { prompt } : { error: "the message has no text" };
138
+ }
139
+ /** Non-empty lines from a stream, as they arrive. */
140
+ export async function* readLines(stream = process.stdin) {
141
+ let buffer = "";
142
+ for await (const chunk of stream) {
143
+ buffer += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
144
+ let nl;
145
+ while ((nl = buffer.indexOf("\n")) >= 0) {
146
+ const line = buffer.slice(0, nl).trim();
147
+ buffer = buffer.slice(nl + 1);
148
+ if (line)
149
+ yield line;
150
+ }
151
+ }
152
+ if (buffer.trim())
153
+ yield buffer.trim();
154
+ }
109
155
  /** Read the whole of stdin (for `echo task | phren-agent -p`). */
110
156
  export async function readStdin(stream = process.stdin) {
111
157
  const chunks = [];