@phren/agent 0.3.20 → 0.3.22

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 (48) hide show
  1. package/dist/agent-loop/index.js +113 -19
  2. package/dist/agent-loop/stream.js +3 -1
  3. package/dist/attach-images.js +57 -0
  4. package/dist/commands/info.js +6 -2
  5. package/dist/commands/model.js +55 -13
  6. package/dist/commands/session.js +79 -18
  7. package/dist/commands.js +9 -2
  8. package/dist/config.js +45 -0
  9. package/dist/context/clear-tool-results.js +43 -0
  10. package/dist/context/compactor.js +8 -2
  11. package/dist/context/usage.js +26 -0
  12. package/dist/cost.js +10 -3
  13. package/dist/headless.js +41 -0
  14. package/dist/index.js +180 -56
  15. package/dist/mcp-client.js +38 -1
  16. package/dist/mcp-prompts.js +94 -0
  17. package/dist/multi/child-entry.js +3 -1
  18. package/dist/multi/spawner.js +27 -15
  19. package/dist/permissions/allowlist.js +19 -4
  20. package/dist/permissions/checker.js +37 -20
  21. package/dist/permissions/kernel-sandbox.js +32 -10
  22. package/dist/permissions/rules.js +173 -0
  23. package/dist/permissions/shell-classify.js +173 -0
  24. package/dist/plan.js +6 -2
  25. package/dist/repl.js +16 -1
  26. package/dist/session/persist.js +9 -4
  27. package/dist/settings.js +14 -0
  28. package/dist/structured-output.js +85 -0
  29. package/dist/system-prompt.js +117 -14
  30. package/dist/tools/apply-patch.js +15 -1
  31. package/dist/tools/edit-file.js +8 -1
  32. package/dist/tools/file-state.js +88 -0
  33. package/dist/tools/glob.js +53 -35
  34. package/dist/tools/grep.js +139 -53
  35. package/dist/tools/lint-test.js +24 -0
  36. package/dist/tools/read-file.js +2 -0
  37. package/dist/tools/registry.js +8 -1
  38. package/dist/tools/search-support.js +141 -0
  39. package/dist/tools/shell.js +3 -1
  40. package/dist/tools/spawn-agent.js +15 -3
  41. package/dist/tools/syntax-check.js +116 -0
  42. package/dist/tools/write-file.js +11 -3
  43. package/dist/tui/components/App.js +5 -4
  44. package/dist/tui/components/Banner.js +1 -1
  45. package/dist/tui/components/ListPicker.js +32 -0
  46. package/dist/tui/ink-entry.js +57 -16
  47. package/dist/user-hooks.js +26 -4
  48. package/package.json +3 -2
@@ -0,0 +1,173 @@
1
+ /**
2
+ * What a shell command line does, coarsely: enough to tell a read-only or
3
+ * build-and-test command, which auto-confirm may run unprompted, from
4
+ * anything else, which it must ask about. The blocklist in shell-safety.ts
5
+ * only names the catastrophic cases; everything it misses (`rm -rf src`,
6
+ * `git push`, `npm publish`) used to count as safe.
7
+ *
8
+ * This is a conservative reader, not a shell parser: anything it doesn't
9
+ * understand (redirection into a file, substitution, a leading variable
10
+ * assignment, background `&`) is not auto-approvable.
11
+ */
12
+ /** Commands that only read. */
13
+ const READ_ONLY = new Set([
14
+ "ls", "cat", "head", "tail", "wc", "grep", "egrep", "fgrep", "rg", "pwd", "echo", "printf", "which", "type",
15
+ "file", "stat", "du", "df", "tree", "diff", "cmp", "sort", "uniq", "cut", "tr", "basename", "dirname", "realpath",
16
+ "readlink", "date", "true", "false", "test", "[", "jq", "nl", "column", "sha256sum", "shasum", "md5sum", "whoami",
17
+ "uname", "hostname", "cd", "find", "sed",
18
+ ]);
19
+ /** Build, test and type-check tools, and the subcommands of multi-command tools that read, build or test. */
20
+ const RUNNERS = new Set(["tsc", "vitest", "jest", "mocha", "pytest", "mypy", "pyright"]);
21
+ const SUBCOMMANDS = {
22
+ git: new Set(["status", "diff", "log", "show", "rev-parse", "ls-files", "blame", "grep", "describe", "shortlog"]),
23
+ npm: new Set(["test", "t", "run", "ls", "view", "outdated"]),
24
+ pnpm: new Set(["test", "t", "run", "lint", "build", "typecheck", "ls", "list", "why", "outdated"]),
25
+ yarn: new Set(["test", "run", "lint", "build", "typecheck", "list", "why"]),
26
+ bun: new Set(["test", "run"]),
27
+ npx: new Set(["tsc", "vitest", "jest", "mocha", "eslint", "biome"]),
28
+ cargo: new Set(["build", "check", "test", "clippy", "doc", "tree", "metadata"]),
29
+ go: new Set(["build", "test", "vet", "list", "version", "doc"]),
30
+ ruff: new Set(["check"]),
31
+ eslint: new Set(),
32
+ biome: new Set(["check", "lint", "ci"]),
33
+ };
34
+ /** Arguments that turn a read-only command into one that writes or runs things. */
35
+ const WRITING_ARGS = {
36
+ find: /^-(exec|execdir|ok|okdir|delete|fprint|fprint0|fprintf|fls)$/,
37
+ // -i edits in place; a script's w command writes a file and e runs one.
38
+ sed: /^(-i|--in-place)|(^|[;{}\n]|\/[gpIiMm0-9]*)\s*[we](\s|$)/,
39
+ eslint: /^--fix/,
40
+ git: /^(-o|--output)/,
41
+ };
42
+ /** Package scripts that `npm run` and friends may run unprompted. */
43
+ const SAFE_SCRIPT = /^(test|build|lint|check|typecheck|type-check|tsc|compile)(:[\w:-]+)?$/;
44
+ const SCRIPT_RUNNERS = new Set(["npm", "pnpm", "yarn", "bun"]);
45
+ /** Multi-command tools whose allowlist entries are scoped to the subcommand. */
46
+ export const MULTI_COMMAND_TOOLS = new Set([
47
+ "git", "npm", "pnpm", "yarn", "bun", "npx", "cargo", "go", "docker", "kubectl", "gh", "pip", "pip3", "uv", "poetry",
48
+ "brew", "dotnet", "mvn", "gradle", "terraform", "helm", "systemctl", "apt", "apt-get", "ruff", "biome",
49
+ ]);
50
+ /** A command line split into its simple commands, or null when it has constructs this reader won't vouch for. */
51
+ export function splitCommandLine(command) {
52
+ const segments = [];
53
+ let tokens = [];
54
+ let current = "";
55
+ let inToken = false;
56
+ let quote = null;
57
+ const endToken = () => {
58
+ if (inToken)
59
+ tokens.push(current);
60
+ current = "";
61
+ inToken = false;
62
+ };
63
+ const endSegment = () => {
64
+ endToken();
65
+ if (tokens.length > 0)
66
+ segments.push(tokens);
67
+ tokens = [];
68
+ };
69
+ for (let i = 0; i < command.length; i++) {
70
+ const c = command[i];
71
+ if (quote) {
72
+ if (c === quote)
73
+ quote = null;
74
+ else if (quote === '"' && (c === "`" || (c === "$" && command[i + 1] === "(")))
75
+ return null;
76
+ else
77
+ current += c;
78
+ continue;
79
+ }
80
+ if (c === "'" || c === '"') {
81
+ quote = c;
82
+ inToken = true;
83
+ continue;
84
+ }
85
+ if (c === "\\") {
86
+ current += command[i + 1] ?? "";
87
+ inToken = true;
88
+ i++;
89
+ continue;
90
+ }
91
+ if (c === "`" || (c === "$" && command[i + 1] === "(") || c === "<" && command[i + 1] === "(")
92
+ return null;
93
+ if (c === "&" && command[i + 1] === "&") {
94
+ endSegment();
95
+ i++;
96
+ continue;
97
+ }
98
+ if (c === "|") {
99
+ endSegment();
100
+ if (command[i + 1] === "|")
101
+ i++;
102
+ continue;
103
+ }
104
+ if (c === ";" || c === "\n") {
105
+ endSegment();
106
+ continue;
107
+ }
108
+ if (c === "&" || c === ">" || c === "<") {
109
+ // Only the harmless redirections: stderr into stdout, output thrown away.
110
+ const rest = command.slice(i);
111
+ const harmless = /^(?:>&[12]|>\s*\/dev\/null|&>\s*\/dev\/null)/.exec(rest);
112
+ const fd = current === "1" || current === "2" ? current : null;
113
+ if (!harmless || (inToken && !fd))
114
+ return null;
115
+ current = "";
116
+ inToken = false;
117
+ i += harmless[0].length - 1;
118
+ continue;
119
+ }
120
+ if (c === " " || c === "\t") {
121
+ endToken();
122
+ continue;
123
+ }
124
+ current += c;
125
+ inToken = true;
126
+ }
127
+ if (quote)
128
+ return null;
129
+ endSegment();
130
+ return segments;
131
+ }
132
+ function segmentIsSafe(tokens) {
133
+ const [binary, ...args] = tokens;
134
+ // A leading assignment (PATH=… cmd) can change what runs.
135
+ if (!binary || /^[A-Za-z_][A-Za-z0-9_]*=/.test(binary))
136
+ return false;
137
+ const name = binary.includes("/") ? "" : binary;
138
+ const writing = WRITING_ARGS[name];
139
+ if (writing && args.some((a) => writing.test(a)))
140
+ return false;
141
+ if (READ_ONLY.has(name) || RUNNERS.has(name))
142
+ return true;
143
+ const subs = SUBCOMMANDS[name];
144
+ if (!subs)
145
+ return false;
146
+ if (subs.size === 0)
147
+ return true;
148
+ const positional = args.filter((a) => !a.startsWith("-"));
149
+ const sub = positional[0];
150
+ if (sub === undefined || !subs.has(sub))
151
+ return false;
152
+ // `npm run deploy` runs whatever the package says; only the usual check scripts pass.
153
+ if (sub === "run" && SCRIPT_RUNNERS.has(name))
154
+ return positional[1] !== undefined && SAFE_SCRIPT.test(positional[1]);
155
+ return true;
156
+ }
157
+ /** True when every part of the command line only reads, builds or tests. */
158
+ export function isAutoApprovableCommand(command) {
159
+ const segments = splitCommandLine(command);
160
+ return segments !== null && segments.length > 0 && segments.every(segmentIsSafe);
161
+ }
162
+ /** The allowlist pattern for one simple command: the binary, plus the subcommand for multi-command tools. */
163
+ export function commandPattern(tokens) {
164
+ const [binary, ...args] = tokens;
165
+ if (!binary)
166
+ return "*";
167
+ if (MULTI_COMMAND_TOOLS.has(binary)) {
168
+ const sub = args.find((a) => !a.startsWith("-"));
169
+ if (sub)
170
+ return `${binary} ${sub}`;
171
+ }
172
+ return binary;
173
+ }
package/dist/plan.js CHANGED
@@ -4,13 +4,17 @@ const PLAN_SUFFIX = `
4
4
 
5
5
  ## Plan mode
6
6
 
7
- Before executing any tools, first describe your plan:
7
+ Before changing anything, propose a plan for the user to approve. You can
8
+ use the read-only tools (read_file, glob, grep, git_status, git_diff and the
9
+ like) to explore the code first; edits, writes and shell commands are refused
10
+ until the plan is approved. Then describe:
8
11
  1. What you understand about the task
9
12
  2. What files you'll need to read or modify
10
13
  3. What approach you'll take
11
14
  4. Any risks or uncertainties
12
15
 
13
- Do NOT call any tools yet. Just describe your plan.`;
16
+ End your reply with the plan, without a tool call; the user approves it or
17
+ asks for changes.`;
14
18
  /** Append plan instruction to the system prompt. */
15
19
  export function injectPlanPrompt(systemPrompt) {
16
20
  return systemPrompt + PLAN_SUFFIX;
package/dist/repl.js CHANGED
@@ -8,6 +8,7 @@ import { randomUUID } from "node:crypto";
8
8
  import { persistFork } from "./session/persist.js";
9
9
  import { createSession, runTurn } from "./agent-loop.js";
10
10
  import { handleCommand, resolveSkillGesture, resolveCustomCommand } from "./commands.js";
11
+ import { isMcpPromptCommand, resolveMcpPromptCommand } from "./mcp-prompts.js";
11
12
  import { resolveProvider } from "./providers/resolve.js";
12
13
  import { loadInputMode } from "./settings.js";
13
14
  const HISTORY_DIR = path.join(os.homedir(), ".phren-agent");
@@ -87,7 +88,9 @@ export async function startRepl(config) {
87
88
  registry: config.registry,
88
89
  promote: config.promote,
89
90
  onModelChange: (result) => {
90
- config.provider = resolveProvider(config.provider.name, result.model, undefined, result.reasoning ?? undefined);
91
+ config.provider = resolveProvider(result.provider ?? config.provider.name, result.model || undefined, undefined, result.reasoning ?? undefined);
92
+ config.costTracker?.reprice(config.provider.model ?? config.provider.name, config.provider.name, config.provider.baseUrl);
93
+ return config.provider;
91
94
  },
92
95
  });
93
96
  for await (const line of rl) {
@@ -97,6 +100,18 @@ export async function startRepl(config) {
97
100
  continue;
98
101
  }
99
102
  allHistory.push(trimmed);
103
+ // An MCP prompt: fetch it from its server and send what it says.
104
+ if (isMcpPromptCommand(trimmed)) {
105
+ try {
106
+ process.stderr.write(`${DIM}↳ fetching MCP prompt ${trimmed.split(/\s+/)[0]}${RESET}\n`);
107
+ trimmed = await resolveMcpPromptCommand(trimmed);
108
+ }
109
+ catch (err) {
110
+ process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
111
+ rl.prompt();
112
+ continue;
113
+ }
114
+ }
100
115
  // /skill-name gesture: rewrite into a run_skill task before command dispatch
101
116
  const customTask = resolveCustomCommand(trimmed);
102
117
  const skillTask = customTask ? null : resolveSkillGesture(trimmed, config.phrenCtx);
@@ -113,6 +113,8 @@ export function listEventLogs(phrenPath, opts = {}) {
113
113
  const { header, events } = loadEventLog(file);
114
114
  if (opts.project && header.project !== opts.project)
115
115
  continue;
116
+ if (opts.cwd && header.cwd !== opts.cwd)
117
+ continue;
116
118
  const log = SessionLog.restore(header, events, () => { });
117
119
  const msgs = log.getMessages();
118
120
  if (msgs.length === 0)
@@ -158,10 +160,11 @@ export function findEventLogById(phrenPath, idPrefix) {
158
160
  return path.join(dir, entries[0]);
159
161
  }
160
162
  /**
161
- * Newest event log for resume, optionally filtered by project.
163
+ * Newest event log for resume, optionally filtered by project or by the
164
+ * directory it ran in (sessions kept without a store have no project).
162
165
  * @returns the file path, or null when none exist.
163
166
  */
164
- export function findLatestEventLog(phrenPath, project) {
167
+ export function findLatestEventLog(phrenPath, project, cwd) {
165
168
  const dir = sessionsDir(phrenPath);
166
169
  let entries;
167
170
  try {
@@ -174,9 +177,11 @@ export function findLatestEventLog(phrenPath, project) {
174
177
  for (const entry of entries) {
175
178
  const file = path.join(dir, entry);
176
179
  try {
177
- if (project) {
180
+ if (project || cwd) {
178
181
  const { header } = loadEventLog(file);
179
- if (header.project !== project)
182
+ if (project && header.project !== project)
183
+ continue;
184
+ if (cwd && header.cwd !== cwd)
180
185
  continue;
181
186
  }
182
187
  candidates.push({ file, mtimeMs: fs.statSync(file).mtimeMs });
package/dist/settings.js CHANGED
@@ -40,6 +40,20 @@ export function loadPermissionMode() {
40
40
  }
41
41
  return undefined;
42
42
  }
43
+ /** Projects whose own MCP config (`.mcp.json`) the user chose to load. */
44
+ export function isMcpProjectTrusted(projectRoot) {
45
+ const list = readSettings().trustedMcpProjects;
46
+ return Array.isArray(list) && list.includes(path.resolve(projectRoot));
47
+ }
48
+ export function trustMcpProject(projectRoot) {
49
+ const data = readSettings();
50
+ const list = Array.isArray(data.trustedMcpProjects) ? data.trustedMcpProjects.filter((p) => typeof p === "string") : [];
51
+ const root = path.resolve(projectRoot);
52
+ if (!list.includes(root))
53
+ list.push(root);
54
+ data.trustedMcpProjects = list;
55
+ writeSettings(data);
56
+ }
43
57
  export function loadTheme() {
44
58
  const name = readSettings().theme;
45
59
  return typeof name === "string" && name ? name : undefined;
@@ -0,0 +1,85 @@
1
+ /**
2
+ * `--json-schema`: a headless run that ends with a JSON value matching the
3
+ * caller's schema, in the result's `structured_output`, as Claude Code's
4
+ * option does.
5
+ *
6
+ * Provider-agnostic: once the task is done, one more request (the session's
7
+ * history, the same tools so Anthropic accepts the tool history, no new tool
8
+ * calls asked for) tells the model to answer with JSON only. The answer is
9
+ * parsed and validated; on a mismatch the model gets the validation errors
10
+ * and tries again, twice at most. The exchange stays out of the session log.
11
+ */
12
+ import * as fs from "fs";
13
+ import { Ajv } from "ajv";
14
+ import { recordTokenUsage } from "./cost.js";
15
+ const MAX_ATTEMPTS = 3;
16
+ /** Read `--json-schema`: inline JSON, or a path to a JSON file. Throws a user-facing error. */
17
+ export function loadJsonSchema(raw) {
18
+ const text = raw.trim().startsWith("{") ? raw : (() => {
19
+ try {
20
+ return fs.readFileSync(raw, "utf-8");
21
+ }
22
+ catch {
23
+ throw new Error(`--json-schema: "${raw}" is neither a JSON object nor a readable file.`);
24
+ }
25
+ })();
26
+ let schema;
27
+ try {
28
+ schema = JSON.parse(text);
29
+ }
30
+ catch (err) {
31
+ throw new Error(`--json-schema is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
32
+ }
33
+ if (!schema || typeof schema !== "object" || Array.isArray(schema))
34
+ throw new Error("--json-schema must be a JSON Schema object.");
35
+ try {
36
+ const validate = new Ajv({ allErrors: true, strict: false }).compile(schema);
37
+ return { schema: schema, validate };
38
+ }
39
+ catch (err) {
40
+ throw new Error(`--json-schema is not a usable JSON Schema: ${err instanceof Error ? err.message : String(err)}`);
41
+ }
42
+ }
43
+ /** The JSON in a model's reply: the whole reply, or the first fenced block. */
44
+ export function extractJson(text) {
45
+ const fenced = /```(?:json)?\s*\n([\s\S]*?)```/.exec(text);
46
+ return JSON.parse((fenced ? fenced[1] : text).trim());
47
+ }
48
+ function instruction(schema) {
49
+ return [
50
+ "The task is done. Now reply with ONLY a JSON value that matches this JSON Schema: no prose, no code fence, no tool calls.",
51
+ "",
52
+ JSON.stringify(schema, null, 2),
53
+ ].join("\n");
54
+ }
55
+ export async function produceStructuredOutput(provider, systemPrompt, messages, tools, json, opts = {}) {
56
+ const exchange = [...messages, { role: "user", content: instruction(json.schema) }];
57
+ let problem = "";
58
+ for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
59
+ if (opts.signal?.aborted)
60
+ return { error: "cancelled" };
61
+ const response = await provider.chat(systemPrompt, exchange, tools, opts.signal);
62
+ if (response.usage && opts.costTracker)
63
+ recordTokenUsage(opts.costTracker, response.usage);
64
+ const text = response.content
65
+ .filter((b) => b.type === "text")
66
+ .map((b) => b.text)
67
+ .join("\n");
68
+ let value;
69
+ try {
70
+ value = extractJson(text);
71
+ }
72
+ catch (err) {
73
+ problem = `not JSON (${err instanceof Error ? err.message : String(err)})`;
74
+ }
75
+ if (!problem) {
76
+ if (json.validate(value))
77
+ return { value };
78
+ problem = (json.validate.errors ?? []).map((e) => `${e.instancePath || "(root)"} ${e.message}`).join("; ");
79
+ }
80
+ exchange.push({ role: "assistant", content: text || "(no text)" }, { role: "user", content: `That doesn't match the schema: ${problem}. Reply again with only the JSON value.` });
81
+ if (attempt < MAX_ATTEMPTS - 1)
82
+ problem = "";
83
+ }
84
+ return { error: `no valid structured output after ${MAX_ATTEMPTS} attempts: ${problem}` };
85
+ }
@@ -1,4 +1,117 @@
1
- export function buildSystemPrompt(phrenContext, priorSummary, providerInfo, customCommands) {
1
+ import { execFileSync } from "node:child_process";
2
+ import * as os from "node:os";
3
+ import * as path from "node:path";
4
+ function git(cwd, args) {
5
+ try {
6
+ return execFileSync("git", args, { cwd, timeout: 2000, stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" }).trim();
7
+ }
8
+ catch {
9
+ return null;
10
+ }
11
+ }
12
+ /**
13
+ * The environment block: cwd, platform, shell, date, git state. Nothing in it
14
+ * changes per turn (the date, not the time), so the prompt caches.
15
+ */
16
+ export function buildEnvironmentBlock(cwd = process.cwd(), permissionMode) {
17
+ const now = new Date();
18
+ const pad = (n) => String(n).padStart(2, "0");
19
+ const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
20
+ const shell = process.env.SHELL ? path.basename(process.env.SHELL) : process.env.COMSPEC ? path.basename(process.env.COMSPEC) : "unknown";
21
+ const lines = [
22
+ `- Working directory: ${cwd}`,
23
+ `- Platform: ${os.type()} ${os.release()} (${process.platform}, ${os.arch()})`,
24
+ `- Shell: ${shell}`,
25
+ `- Today's date: ${date}`,
26
+ ];
27
+ if (git(cwd, ["rev-parse", "--is-inside-work-tree"]) === "true") {
28
+ const branch = git(cwd, ["symbolic-ref", "--short", "-q", "HEAD"]);
29
+ const detached = branch ? null : git(cwd, ["rev-parse", "--short", "HEAD"]);
30
+ lines.push(`- Git repository: yes, ${branch ? `branch ${branch}` : detached ? `detached HEAD at ${detached}` : "no commits yet"}`);
31
+ }
32
+ else {
33
+ lines.push("- Git repository: no");
34
+ }
35
+ if (permissionMode)
36
+ lines.push(`- Permission mode: ${permissionMode}`);
37
+ return `## Environment\n${lines.join("\n")}`;
38
+ }
39
+ const TOOL_GROUPS = [
40
+ ["Files and editing", ["read_file", "write_file", "edit_file", "multi_edit", "apply_patch", "read_image"]],
41
+ ["Search", ["glob", "grep"]],
42
+ ["Shell", ["shell", "task_output", "task_stop"]],
43
+ ["Git", ["git_status", "git_diff", "git_commit"]],
44
+ ["Web", ["web_search", "web_fetch"]],
45
+ ["Memory", ["phren_search", "phren_add_finding", "phren_get_tasks", "phren_complete_task", "phren_add_task", "run_skill"]],
46
+ ["Planning and agents", ["update_plan", "spawn_agent", "send_message_to_agent", "list_agents", "list_mcp_resources", "read_mcp_resource"]],
47
+ ];
48
+ const EDIT_HINTS = [
49
+ ["edit_file", "`edit_file` for a small change"],
50
+ ["multi_edit", "`multi_edit` for several changes in one file"],
51
+ ["apply_patch", "`apply_patch` for changes across files"],
52
+ ["write_file", "`write_file` for new files"],
53
+ ];
54
+ /** The tools section, from the names actually registered. MCP tools are counted per server, not listed. */
55
+ export function buildToolSection(toolNames, mcpServers = []) {
56
+ const registered = new Set(toolNames);
57
+ const lines = [];
58
+ const known = new Set();
59
+ for (const [label, names] of TOOL_GROUPS) {
60
+ for (const n of names)
61
+ known.add(n);
62
+ const present = names.filter((n) => registered.has(n));
63
+ if (present.length > 0)
64
+ lines.push(`- ${label}: ${present.map((n) => `\`${n}\``).join(", ")}`);
65
+ }
66
+ const servers = [...mcpServers].sort((a, b) => b.length - a.length);
67
+ const counts = new Map();
68
+ const other = [];
69
+ for (const n of toolNames) {
70
+ if (known.has(n))
71
+ continue;
72
+ if (!n.startsWith("mcp_")) {
73
+ other.push(n);
74
+ continue;
75
+ }
76
+ const rest = n.slice(4);
77
+ const server = servers.find((s) => rest.startsWith(`${s}_`)) ?? rest.split("_")[0];
78
+ counts.set(server, (counts.get(server) ?? 0) + 1);
79
+ }
80
+ if (other.length > 0)
81
+ lines.push(`- Other: ${other.map((n) => `\`${n}\``).join(", ")}`);
82
+ if (counts.size > 0) {
83
+ const summary = [...counts].map(([s, c]) => `${s} (${c})`).join(", ");
84
+ lines.push(`- MCP: ${summary}. Tools are named \`mcp_<server>_<tool>\`.`);
85
+ }
86
+ const hints = EDIT_HINTS.filter(([n]) => registered.has(n)).map(([, text]) => text);
87
+ if (hints.length > 1)
88
+ lines.push("", `Edit tools: ${hints.join(", ")}.`);
89
+ return `## Tools You Have\n${lines.join("\n")}`;
90
+ }
91
+ function workflowSteps(has) {
92
+ const steps = [];
93
+ if (has("phren_search"))
94
+ steps.push("**Search memory first** — `phren_search` for relevant past findings before starting work.");
95
+ const reads = ["glob", "grep", "read_file"].filter(has);
96
+ if (reads.length > 0)
97
+ steps.push(`**Read before writing** — ${reads.map((n) => `\`${n}\``).join(", ")} to find and understand code.`);
98
+ if (has("edit_file") && has("write_file"))
99
+ steps.push("**Make changes** — `edit_file` for surgical edits, `write_file` for new files only.");
100
+ else if (has("edit_file"))
101
+ steps.push("**Make changes** — `edit_file` for surgical edits.");
102
+ else if (has("write_file"))
103
+ steps.push("**Make changes** — `write_file`.");
104
+ const verify = [has("shell") && "`shell` to run tests/linters", has("git_diff") && "`git_diff` to review changes"].filter(Boolean);
105
+ if (verify.length > 0)
106
+ steps.push(`**Verify** — ${verify.join(", ")}.`);
107
+ if (has("phren_add_finding"))
108
+ steps.push("**Save learnings** — `phren_add_finding` for non-obvious discoveries (bugs, architecture decisions, gotchas). Skip obvious stuff.");
109
+ steps.push("**Report concisely** — what changed and why. No fluff.");
110
+ return steps.map((s, i) => `${i + 1}. ${s}`);
111
+ }
112
+ export function buildSystemPrompt(phrenContext, priorSummary, providerInfo, customCommands, options = {}) {
113
+ const registered = options.toolNames ? new Set(options.toolNames) : null;
114
+ const has = (name) => !registered || registered.has(name);
2
115
  const modelNote = providerInfo ? ` You are running on ${providerInfo.name}${providerInfo.model ? ` (model: ${providerInfo.model})` : ""}.` : "";
3
116
  const parts = [
4
117
  `You are phren-agent, an autonomous coding agent with persistent memory.${modelNote}`,
@@ -9,21 +122,11 @@ export function buildSystemPrompt(phrenContext, priorSummary, providerInfo, cust
9
122
  "You have persistent memory via phren. Past decisions, discovered patterns, and project context are searchable across sessions. Use this to avoid repeating mistakes.",
10
123
  "",
11
124
  "## Workflow",
12
- "1. **Search memory first** — `phren_search` for relevant past findings before starting work.",
13
- "2. **Read before writing** — `glob` to find files, `grep` to locate symbols, `read_file` to understand code.",
14
- "3. **Make changes** — `edit_file` for surgical edits, `write_file` for new files only.",
15
- "4. **Verify** — `shell` to run tests/linters, `git_diff` to review changes.",
16
- "5. **Save learnings** — `phren_add_finding` for non-obvious discoveries (bugs, architecture decisions, gotchas). Skip obvious stuff.",
17
- "6. **Report concisely** — what changed and why. No fluff.",
125
+ ...workflowSteps(has),
18
126
  "",
19
- "## Tools You Have",
20
- "- File I/O: `read_file`, `write_file`, `edit_file`",
21
- "- Search: `glob`, `grep`, `web_search`, `web_fetch`",
22
- "- System: `shell` (run commands, cd, build, test)",
23
- "- Git: `git_status`, `git_diff`, `git_commit`",
24
- "- Memory: `phren_search`, `phren_add_finding`, `phren_get_tasks`, `phren_complete_task`, `phren_add_task`",
25
- "- Planning: `update_plan` — keep a short visible todo list for multi-step work",
127
+ options.environment ?? buildEnvironmentBlock(process.cwd(), options.permissionMode),
26
128
  "",
129
+ ...(options.toolNames ? [buildToolSection(options.toolNames, options.mcpServers), ""] : []),
27
130
  "## Important",
28
131
  "- Be direct and concise. Lead with the answer, not the reasoning.",
29
132
  "- Call multiple tools in parallel when they're independent.",
@@ -24,6 +24,8 @@ import * as fs from "fs";
24
24
  import * as path from "path";
25
25
  import { checkSensitivePath, validatePath } from "../permissions/sandbox.js";
26
26
  import { describeNotFound } from "./edit-engine.js";
27
+ import { forgetFileState, recordFileState, staleFileError } from "./file-state.js";
28
+ import { syntaxCheckNote } from "./syntax-check.js";
27
29
  const BEGIN = "*** Begin Patch";
28
30
  const END = "*** End Patch";
29
31
  const ADD = "*** Add File: ";
@@ -332,6 +334,12 @@ export const applyPatchTool = {
332
334
  if (!sandbox.ok)
333
335
  return { output: `Path outside sandbox: ${sandbox.error}`, is_error: true };
334
336
  }
337
+ for (const op of ops) {
338
+ // Add File over an existing file is a whole-file overwrite.
339
+ const stale = staleFileError(path.resolve(cwd, op.path), { requireRead: op.kind === "add" });
340
+ if (stale)
341
+ throw new PatchError(stale);
342
+ }
335
343
  writes = planPatch(ops, cwd);
336
344
  }
337
345
  catch (err) {
@@ -343,13 +351,19 @@ export const applyPatchTool = {
343
351
  if (w.content === null) {
344
352
  if (fs.existsSync(abs))
345
353
  fs.rmSync(abs);
354
+ forgetFileState(abs);
346
355
  }
347
356
  else {
348
357
  fs.mkdirSync(path.dirname(abs), { recursive: true });
349
358
  fs.writeFileSync(abs, w.content);
359
+ recordFileState(abs);
350
360
  }
351
361
  }
352
362
  const summary = writes.map((w) => `${w.status} ${w.path}`).join("\n");
353
- return { output: `Success. Updated the following files:\n${summary}` };
363
+ const notes = writes.flatMap((w) => {
364
+ const note = w.content === null ? null : syntaxCheckNote(w.path, w.before, w.content);
365
+ return note ? [note] : [];
366
+ });
367
+ return { output: `Success. Updated the following files:\n${summary}${notes.length > 0 ? `\n\n${notes.join("\n\n")}` : ""}` };
354
368
  },
355
369
  };
@@ -3,6 +3,8 @@ import * as path from "path";
3
3
  import { encodeDiffPayload } from "../multi/diff-renderer.js";
4
4
  import { checkSensitivePath, validatePath } from "../permissions/sandbox.js";
5
5
  import { applyEdits, snippetAround } from "./edit-engine.js";
6
+ import { recordFileState, staleFileError } from "./file-state.js";
7
+ import { syntaxCheckNote } from "./syntax-check.js";
6
8
  /** Shared path checks and read for the edit tools. */
7
9
  function openForEdit(filePath) {
8
10
  if (typeof filePath !== "string" || filePath === "") {
@@ -20,6 +22,9 @@ function openForEdit(filePath) {
20
22
  if (fs.statSync(filePath).isDirectory()) {
21
23
  return { ok: false, result: { output: `${filePath} is a directory, not a file.`, is_error: true } };
22
24
  }
25
+ const stale = staleFileError(filePath);
26
+ if (stale)
27
+ return { ok: false, result: { output: stale, is_error: true } };
23
28
  return { ok: true, filePath, content: fs.readFileSync(filePath, "utf-8") };
24
29
  }
25
30
  function runEdits(filePath, edits) {
@@ -30,13 +35,15 @@ function runEdits(filePath, edits) {
30
35
  if (!outcome.ok)
31
36
  return { output: `${opened.filePath}: ${outcome.error}`, is_error: true };
32
37
  fs.writeFileSync(opened.filePath, outcome.content);
38
+ recordFileState(opened.filePath);
33
39
  const count = outcome.replacements === 1 ? "1 replacement" : `${outcome.replacements} replacements`;
34
40
  const note = outcome.note ? ` (${outcome.note})` : "";
35
41
  // The model sees a short numbered excerpt of the result; the diff payload
36
42
  // after DIFF_MARKER is for the TUI and is stripped before the model sees it.
37
43
  const snippet = snippetAround(outcome.content.replace(/\r\n/g, "\n"), outcome.firstLine, outcome.lastLine);
44
+ const syntax = syntaxCheckNote(opened.filePath, opened.content, outcome.content);
38
45
  return {
39
- output: `Edited ${opened.filePath}: ${count}${note}.\n${snippet}${encodeDiffPayload(opened.filePath, opened.content, outcome.content)}`,
46
+ output: `Edited ${opened.filePath}: ${count}${note}.\n${snippet}${syntax ? `\n\n${syntax}` : ""}${encodeDiffPayload(opened.filePath, opened.content, outcome.content)}`,
40
47
  };
41
48
  }
42
49
  export const editFileTool = {