amalgm 0.1.88 → 0.1.89

package/runtime/scripts/amalgm-mcp/fs/rest.js

@@ -6,7 +6,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const activeMemory = require('../../chat-core/tooling/active-memory');
+const { notifyProjectContextPathChanged } = require('../project-context/store');
 const { AMALGM_DIR } = require('../config');
 const { appendStateEvent } = require('../state/events');
 
@@ -538,7 +538,7 @@ async function handleWrite(body, sendJson) {
 
     await fs.promises.mkdir(path.dirname(targetPath), { recursive: true });
     await fs.promises.writeFile(targetPath, data);
-    activeMemory.notifyMemoryPathChanged(targetPath, 'fs:write');
+    notifyProjectContextPathChanged(targetPath, 'fs:write');
     await publishFilesystemChange([targetPath], 'fs:write');
 
     sendJson(200, { success: true, path: targetPath });
@@ -553,7 +553,7 @@ async function handleDelete(body, sendJson) {
     const targetPath = await resolveSafePath(body.path);
     const stats = await fs.promises.lstat(targetPath).catch(() => null);
     await fs.promises.rm(targetPath, { recursive: true, force: true });
-    activeMemory.notifyMemoryPathChanged(targetPath, 'fs:delete');
+    notifyProjectContextPathChanged(targetPath, 'fs:delete');
     await publishFilesystemChange([targetPath], 'fs:delete');
     if (stats?.isDirectory()) {
       appendStateEvent({
@@ -575,7 +575,6 @@ async function handleMkdir(body, sendJson) {
   try {
     const targetPath = await resolveSafePath(body.path, { forCreate: true });
     await fs.promises.mkdir(targetPath, { recursive: true, mode: 0o755 });
-    activeMemory.notifyMemoryPathChanged(targetPath, 'fs:mkdir');
     await publishFilesystemChange([targetPath], 'fs:mkdir');
     await publishFilesResourceForPath(targetPath, 'fs:mkdir');
     sendJson(200, { success: true, path: targetPath });
@@ -592,8 +591,8 @@ async function handleRename(body, sendJson) {
     const stats = await fs.promises.lstat(oldPath).catch(() => null);
     await fs.promises.mkdir(path.dirname(newPath), { recursive: true });
     await fs.promises.rename(oldPath, newPath);
-    activeMemory.notifyMemoryPathChanged(oldPath, 'fs:rename');
-    activeMemory.notifyMemoryPathChanged(newPath, 'fs:rename');
+    notifyProjectContextPathChanged(oldPath, 'fs:rename');
+    notifyProjectContextPathChanged(newPath, 'fs:rename');
     await publishFilesystemChange([oldPath, newPath], 'fs:rename');
     if (stats?.isDirectory()) {
       appendStateEvent({

package/runtime/scripts/amalgm-mcp/index.js

@@ -82,12 +82,14 @@ async function boot() {
   const { ensureAppsDirs } = require('./apps/store');
   const { startAppRouteSyncLoop } = require('./apps/advertise');
   const { startRegisteredApps } = require('./apps/supervisor');
+  const { startProjectContextService } = require('./project-context/store');
   const { listen } = require('./server/http');
 
   // Make sure every storage dir/file exists before we accept traffic.
   ensureAutomationsStore();
   ensureAgentsDirs();
   ensureAppsDirs();
+  startProjectContextService();
 
   await listen();
   await startRegisteredApps();

package/runtime/scripts/amalgm-mcp/lib/tool-result.js

@@ -53,86 +53,52 @@ function buildActionDescriptor(toolName, args = {}) {
     case 'talk_to_agent':
       if (args.response_to_caller) return 'Deliver peer response';
       return `Talk to agent${quoteIfPresent(args.agent || args.agent_id)}`;
-    case 'browser_navigate':
-      return args.url ? `Navigate browser to ${clipText(args.url, 90)}` : 'Navigate browser';
-    case 'browser_tabs_list':
-      return 'List browser tabs';
-    case 'browser_tabs_selected':
-      return 'Get selected browser tab';
-    case 'browser_tabs_new':
-      return args.url ? `Open browser tab ${clipText(args.url, 90)}` : 'Open browser tab';
-    case 'browser_tabs_get':
-      return 'Get browser tab';
-    case 'browser_tabs_select':
-      return 'Select browser tab';
-    case 'browser_tabs_close':
-      return 'Close browser tab';
-    case 'browser_state':
-      return 'Get browser state';
-    case 'browser_back':
-      return 'Go back in browser';
-    case 'browser_forward':
-      return 'Go forward in browser';
-    case 'browser_reload':
-      return 'Reload browser';
-    case 'browser_screenshot':
-      return args.full_page ? 'Take full-page browser screenshot' : 'Take browser screenshot';
+    case 'browser_open':
+      return args.url ? `Open ${clipText(args.url, 90)} in browser` : 'Open browser page';
     case 'browser_snapshot':
       return 'Capture browser snapshot';
+    case 'browser_screenshot':
+      return args.fullPage ? 'Take full-page browser screenshot' : 'Take browser screenshot';
     case 'browser_click':
-      if (args.text) return `Click browser text${quoteIfPresent(args.text)}`;
-      if (args.selector) return `Click browser selector${quoteIfPresent(args.selector)}`;
-      return 'Click in browser';
-    case 'browser_type':
-      if (args.selector && args.text) {
-        return `Type ${clipText(args.text, 40)} into ${clipText(args.selector, 40)}`;
-      }
-      if (args.selector) return `Type into ${clipText(args.selector, 60)}`;
-      return args.text ? `Type ${clipText(args.text, 40)} in browser` : 'Type in browser';
+      return `Click${quoteIfPresent(args.target)} in browser`;
+    case 'browser_fill':
+      return args.target
+        ? `Fill ${clipText(args.target, 40)} with ${clipText(args.text, 40)}`
+        : 'Fill browser field';
     case 'browser_press':
       return args.key ? `Press ${clipText(args.key, 30)} in browser` : 'Press key in browser';
-    case 'browser_get_text':
-      return args.selector
-        ? `Get browser text from ${clipText(args.selector, 60)}`
-        : 'Get browser page text';
-    case 'browser_locator_count':
-      return 'Count browser locator';
-    case 'browser_locator_text':
-      return 'Read browser locator text';
-    case 'browser_evaluate':
+    case 'browser_eval':
       return 'Evaluate browser script';
-    case 'browser_wait_for_load_state':
-      return 'Wait for browser load state';
-    case 'browser_wait_for_url':
-      return args.url ? `Wait for browser URL ${clipText(args.url, 80)}` : 'Wait for browser URL';
-    case 'browser_wait_for_selector':
-      return args.selector ? `Wait for browser selector ${clipText(args.selector, 60)}` : 'Wait for browser selector';
-    case 'browser_cua_click':
+    case 'browser_wait':
+      if (args.selector) return `Wait for browser selector ${clipText(args.selector, 60)}`;
+      if (args.url) return `Wait for browser URL ${clipText(args.url, 80)}`;
+      return args.ms ? `Wait ${args.ms}ms in browser` : 'Wait in browser';
+    case 'browser_cli':
+      return `Browser CLI${quoteIfPresent(Array.isArray(args.args) ? args.args.join(' ') : '')}`;
+    case 'browser_close':
+      return 'Close browser';
+    case 'cua_click':
       return 'Click browser coordinates';
-    case 'browser_cua_double_click':
+    case 'cua_double_click':
       return 'Double-click browser coordinates';
-    case 'browser_cua_move':
+    case 'cua_move':
       return 'Move browser mouse';
-    case 'browser_cua_scroll':
+    case 'cua_scroll':
       return 'Scroll browser';
-    case 'browser_cua_type':
+    case 'cua_type':
       return args.text ? `Type ${clipText(args.text, 40)} in browser` : 'Type in browser';
-    case 'browser_cua_keypress':
+    case 'cua_keypress':
       return 'Press browser key';
-    case 'browser_cua_drag':
+    case 'cua_drag':
       return 'Drag in browser';
-    case 'browser_cua_screenshot':
+    case 'cua_screenshot':
       return 'Take visible browser screenshot';
-    case 'browser_clipboard_read_text':
-      return 'Read browser clipboard';
-    case 'browser_clipboard_write_text':
-      return 'Write browser clipboard';
-    case 'browser_start_video':
-      return 'Start browser video recording';
-    case 'browser_stop_video':
-      return 'Stop browser video recording';
-    case 'browser_close':
-      return 'Close browser';
+    case 'record_start':
+      return `Start browser recording${quoteIfPresent(args.name)}`;
+    case 'record_stop':
+      return 'Stop browser recording';
+    case 'record_list':
+      return 'List browser recordings';
     default: {
       const humanized = humanizeToolName(toolName);
       return humanized ? humanized.charAt(0).toUpperCase() + humanized.slice(1) : 'Tool call';

package/runtime/scripts/amalgm-mcp/project-context/paths.js

@@ -0,0 +1,266 @@
+'use strict';
+
+/**
+ * Project context paths + pure text helpers.
+ *
+ * Every registered workspace carries `<project>/.amalgm/context/` with three
+ * markdown docs:
+ *   instructions.md   user-authored durable instructions
+ *   change-log.md     append-only operational history, newest entry on top
+ *   project-state.md  consolidated "where the project stands" snapshot
+ *
+ * This module is dependency-free (no db/event imports) so chat-core and tests
+ * can use the path/text helpers without pulling in the store.
+ */
+
+const path = require('path');
+
+const CONTEXT_DIR_SEGMENTS = ['.amalgm', 'context'];
+const INSTRUCTIONS_FILENAME = 'instructions.md';
+const CHANGE_LOG_FILENAME = 'change-log.md';
+const PROJECT_STATE_FILENAME = 'project-state.md';
+
+const CHANGE_LOG_TITLE = '# Change Log';
+const PROJECT_STATE_TITLE = '# Project State';
+const INSTRUCTIONS_TITLE = '# Instructions';
+
+// "Roughly the last 2,000 words" of history, kept deterministic in chars.
+const CHANGE_LOG_CONTEXT_MAX_CHARS = 12_000;
+const CONTEXT_FILE_MAX_CHARS = 12_000;
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function contextRoot(projectPath) {
+  return path.join(path.resolve(projectPath), ...CONTEXT_DIR_SEGMENTS);
+}
+
+function contextPaths(projectPath) {
+  const root = contextRoot(projectPath);
+  return {
+    root,
+    instructions: path.join(root, INSTRUCTIONS_FILENAME),
+    changeLog: path.join(root, CHANGE_LOG_FILENAME),
+    projectState: path.join(root, PROJECT_STATE_FILENAME),
+  };
+}
+
+const CONTEXT_DOC_FILENAMES = new Set([
+  INSTRUCTIONS_FILENAME,
+  CHANGE_LOG_FILENAME,
+  PROJECT_STATE_FILENAME,
+]);
+
+/** True when filePath points at one of the context docs (any project). */
+function isProjectContextDocPath(filePath) {
+  const resolved = cleanString(filePath) ? path.resolve(filePath) : '';
+  if (!resolved) return false;
+  if (!CONTEXT_DOC_FILENAMES.has(path.basename(resolved))) return false;
+  const dir = path.dirname(resolved);
+  return path.basename(dir) === CONTEXT_DIR_SEGMENTS[1]
+    && path.basename(path.dirname(dir)) === CONTEXT_DIR_SEGMENTS[0];
+}
+
+/** Project root implied by a context doc/dir path, or '' when not one. */
+function projectPathForContextPath(filePath) {
+  const resolved = cleanString(filePath) ? path.resolve(filePath) : '';
+  if (!resolved) return '';
+  const dir = isProjectContextDocPath(resolved) ? path.dirname(resolved) : resolved;
+  if (path.basename(dir) !== CONTEXT_DIR_SEGMENTS[1]) return '';
+  const amalgmDir = path.dirname(dir);
+  if (path.basename(amalgmDir) !== CONTEXT_DIR_SEGMENTS[0]) return '';
+  return path.dirname(amalgmDir);
+}
+
+/**
+ * Timestamp for change-log entries: ISO-like local time with offset plus the
+ * IANA timezone name. The runtime owns this — models never write timestamps.
+ */
+function localTimestamp(date = new Date()) {
+  const pad = (value) => String(value).padStart(2, '0');
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes < 0 ? '-' : '+';
+  const absMinutes = Math.abs(offsetMinutes);
+  const offset = `${sign}${pad(Math.floor(absMinutes / 60))}:${pad(absMinutes % 60)}`;
+  const iso = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
+    + `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}${offset}`;
+  let timeZone = 'UTC';
+  try {
+    timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+  } catch {
+    // Keep UTC.
+  }
+  return { iso, timeZone, ms: date.getTime() };
+}
+
+function changeLogEntryHeading(stamp = localTimestamp()) {
+  return `## ${stamp.iso} [${stamp.timeZone}]`;
+}
+
+/**
+ * The model supplies only the entry body. Strip a timestamp-style heading if
+ * one slipped in anyway so runtime timestamps stay canonical.
+ */
+function sanitizeChangeLogBody(body) {
+  let text = String(body || '').replace(/\r\n/g, '\n').trim();
+  text = text.replace(/^##\s+\d{4}-\d{2}-\d{2}T[^\n]*\n+/, '').trim();
+  return text;
+}
+
+/**
+ * Prepend an entry directly under the `# Change Log` title. Self-heals a
+ * missing or mangled title instead of failing the append.
+ */
+function insertChangeLogEntry(current, entry) {
+  const normalizedEntry = String(entry || '').trim();
+  const content = String(current || '').replace(/^\uFEFF/, '');
+  if (!content.trim()) {
+    return `${CHANGE_LOG_TITLE}\n\n${normalizedEntry}\n`;
+  }
+  const lines = content.split('\n');
+  const titleIndex = lines.findIndex((line) => line.trim() === CHANGE_LOG_TITLE);
+  if (titleIndex === -1) {
+    return `${CHANGE_LOG_TITLE}\n\n${normalizedEntry}\n\n${content.trim()}\n`;
+  }
+  const before = lines.slice(0, titleIndex + 1).join('\n');
+  const rest = lines.slice(titleIndex + 1).join('\n').trim();
+  return rest
+    ? `${before}\n\n${normalizedEntry}\n\n${rest}\n`
+    : `${before}\n\n${normalizedEntry}\n`;
+}
+
+function changeLogEntryOffsets(content) {
+  const offsets = [];
+  const re = /^##\s/gm;
+  let match;
+  while ((match = re.exec(content)) !== null) offsets.push(match.index);
+  return offsets;
+}
+
+/**
+ * Newest entries up to maxChars, always cut on an entry boundary — a
+ * truncated half-entry with no timestamp is worse than a smaller window.
+ */
+function changeLogRecentWindow(content, maxChars = CHANGE_LOG_CONTEXT_MAX_CHARS) {
+  const body = String(content || '');
+  const offsets = changeLogEntryOffsets(body);
+  if (offsets.length === 0) {
+    const trimmed = body.trim();
+    if (!trimmed || trimmed === CHANGE_LOG_TITLE) return '';
+    return trimmed.length <= maxChars
+      ? trimmed
+      : `${trimmed.slice(0, maxChars).trimEnd()}\n[truncated]`;
+  }
+  const start = offsets[0];
+  let end = body.length;
+  if (end - start > maxChars) {
+    end = start;
+    for (let i = 1; i <= offsets.length; i += 1) {
+      const boundary = i < offsets.length ? offsets[i] : body.length;
+      if (boundary - start <= maxChars) {
+        end = boundary;
+      } else {
+        break;
+      }
+    }
+    if (end === start) {
+      return `${body.slice(start, start + maxChars).trimEnd()}\n[truncated]`;
+    }
+  }
+  const window = body.slice(start, end).trim();
+  return end < body.length ? `${window}\n\n[older entries truncated]` : window;
+}
+
+function parseEntryTimestamp(headingLine) {
+  const text = String(headingLine || '').replace(/^##\s+/, '');
+  const iso = text.split(' [')[0].trim();
+  const ms = Date.parse(iso);
+  return { iso, ms: Number.isFinite(ms) ? ms : null };
+}
+
+/** Timestamp of the newest entry (first heading), or nulls when none parse. */
+function latestChangeLogEntry(content) {
+  const body = String(content || '');
+  const match = body.match(/^##\s+[^\n]*/m);
+  if (!match) return { iso: null, ms: null };
+  const parsed = parseEntryTimestamp(match[0]);
+  return { iso: parsed.ms === null ? null : parsed.iso, ms: parsed.ms };
+}
+
+/**
+ * Entries newer than sinceMs (newest first), capped at maxChars on entry
+ * boundaries. Entries without a parsable timestamp are skipped — the
+ * append-only convention keeps tool-written entries parsable.
+ */
+function changeLogEntriesSince(content, sinceMs, maxChars = CHANGE_LOG_CONTEXT_MAX_CHARS) {
+  const body = String(content || '');
+  const offsets = changeLogEntryOffsets(body);
+  if (offsets.length === 0) return '';
+  const floor = Number.isFinite(sinceMs) ? sinceMs : null;
+  const kept = [];
+  let total = 0;
+  let omitted = false;
+  for (let i = 0; i < offsets.length; i += 1) {
+    const sliceEnd = i + 1 < offsets.length ? offsets[i + 1] : body.length;
+    const entry = body.slice(offsets[i], sliceEnd).trim();
+    const heading = entry.split('\n', 1)[0];
+    const { ms } = parseEntryTimestamp(heading);
+    if (ms === null) continue;
+    if (floor !== null && ms <= floor) continue;
+    if (total + entry.length > maxChars && kept.length > 0) {
+      omitted = true;
+      break;
+    }
+    kept.push(entry);
+    total += entry.length;
+  }
+  if (kept.length === 0) return '';
+  const joined = kept.join('\n\n');
+  return omitted ? `${joined}\n\n[older new entries truncated]` : joined;
+}
+
+/**
+ * Body emptiness: nothing left after dropping the title heading. The legacy
+ * placeholder line ("No instructions for X yet.") counts as empty so files
+ * created by the old context system don't inject noise.
+ */
+function isEmptyContextDoc(content) {
+  const body = String(content || '')
+    .replace(/^\uFEFF/, '')
+    .replace(/^#[^\n]*\n?/, '')
+    .trim();
+  if (!body) return true;
+  return /^No instructions for .{1,200} yet\.$/.test(body);
+}
+
+function cappedDocContent(content, maxChars = CONTEXT_FILE_MAX_CHARS) {
+  const text = String(content || '').trim();
+  if (!text) return '';
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars).trimEnd()}\n[truncated]`;
+}
+
+module.exports = {
+  CHANGE_LOG_CONTEXT_MAX_CHARS,
+  CHANGE_LOG_FILENAME,
+  CHANGE_LOG_TITLE,
+  CONTEXT_FILE_MAX_CHARS,
+  INSTRUCTIONS_FILENAME,
+  INSTRUCTIONS_TITLE,
+  PROJECT_STATE_FILENAME,
+  PROJECT_STATE_TITLE,
+  cappedDocContent,
+  changeLogEntriesSince,
+  changeLogEntryHeading,
+  changeLogRecentWindow,
+  contextPaths,
+  contextRoot,
+  insertChangeLogEntry,
+  isEmptyContextDoc,
+  isProjectContextDocPath,
+  latestChangeLogEntry,
+  localTimestamp,
+  projectPathForContextPath,
+  sanitizeChangeLogBody,
+};

package/runtime/scripts/amalgm-mcp/project-context/prompt.js

@@ -0,0 +1,232 @@
+'use strict';
+
+/**
+ * Project context prompt blocks.
+ *
+ * Fresh provider threads get the full block in the system prompt. Resumed
+ * threads can't change their system prompt without busting the provider's
+ * prompt cache, so freshness is per-turn instead: the runtime tracks the
+ * contextRevision each session last saw (local_meta), and when the canonical
+ * row moved, the next turn gets a compact <project_context_update> prepended.
+ * Because the change log is append-only, the delta is cheap: entries newer
+ * than the last-seen entry timestamp, plus full project-state/instructions
+ * only when their revisions changed.
+ *
+ * Invariant: the prompt for turn N reflects every context write committed
+ * before turn N was sent. Mid-turn writes show up next turn.
+ *
+ * This module runs in the chat-server process — reads rows, writes only
+ * seen-state to local_meta, never emits Local Live events.
+ */
+
+const fs = require('fs');
+
+const SEEN_META_PREFIX = 'project_context_seen:';
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function contractProjectPath(contract) {
+  const origin = contract?.origin && typeof contract.origin === 'object' ? contract.origin : {};
+  return cleanString(origin.projectPath || contract?.projectPath || contract?.cwd);
+}
+
+function peekForContract(contract) {
+  const projectPath = contractProjectPath(contract);
+  if (!projectPath) return null;
+  try {
+    return require('./store').peekProjectContext(projectPath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message.split('\n')[0] : String(error);
+    console.warn('[ProjectContext] Prompt peek failed:', message);
+    return null;
+  }
+}
+
+function readSeen(sessionId) {
+  if (!cleanString(sessionId)) return null;
+  try {
+    const { openLocalDb } = require('../state/db');
+    const row = openLocalDb()
+      .prepare('SELECT value FROM local_meta WHERE key = ?')
+      .get(`${SEEN_META_PREFIX}${sessionId}`);
+    return row?.value ? JSON.parse(row.value) : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeSeen(sessionId, record) {
+  if (!cleanString(sessionId) || !record) return;
+  try {
+    const { openLocalDb } = require('../state/db');
+    openLocalDb()
+      .prepare(`
+        INSERT INTO local_meta (key, value, updated_at)
+        VALUES (?, ?, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+        ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+      `)
+      .run(`${SEEN_META_PREFIX}${sessionId}`, JSON.stringify({
+        projectId: record.projectId,
+        contextRevision: record.contextRevision,
+        instructionsRevision: record.files?.instructions?.revision || null,
+        projectStateRevision: record.files?.projectState?.revision || null,
+        changeLogRevision: record.files?.changeLog?.revision || null,
+        latestEntryAtMs: record.files?.changeLog?.latestEntryAtMs ?? null,
+        updatedAt: new Date().toISOString(),
+      }));
+  } catch (error) {
+    const message = error instanceof Error ? error.message.split('\n')[0] : String(error);
+    console.warn('[ProjectContext] Seen-state write failed:', message);
+  }
+}
+
+function escapeAttribute(value) {
+  return String(value || '')
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function memoryProtocolBlock() {
+  return [
+    '<project_memory_protocol>',
+    'Project memory is maintained through the memories tool — never by editing these files directly.',
+    '- When you complete durable, user-visible work in this project, or make decisions future agents need, call toolbox__memories_append_change_log with a concise markdown body: 3-6 factual bullets such as "- Completed: ...", "- Decisions: ...", "- Notes: ...". No transcripts, no essays; mark uncertain items as open questions.',
+    '- The runtime owns timestamps and entry placement. Never write timestamps, never rewrite change-log.md — it is append-only.',
+    '- Call toolbox__memories_write_project_state only when the consolidated "where this project stands" snapshot must be rewritten (e.g. after a milestone or when consolidating the change log).',
+    '- instructions.md is user-authored. Do not modify it unless the user explicitly asks.',
+    '</project_memory_protocol>',
+  ].join('\n');
+}
+
+function contentBlocks(record) {
+  const blocks = [];
+  if (record.prompt?.instructions) {
+    blocks.push([
+      `<project_instructions path="${escapeAttribute(record.paths?.instructions)}">`,
+      record.prompt.instructions,
+      '</project_instructions>',
+    ].join('\n'));
+  }
+  if (record.prompt?.projectState) {
+    blocks.push([
+      `<project_state path="${escapeAttribute(record.paths?.projectState)}">`,
+      record.prompt.projectState,
+      '</project_state>',
+    ].join('\n'));
+  }
+  if (record.prompt?.changeLogRecent) {
+    blocks.push([
+      `<recent_change_log path="${escapeAttribute(record.paths?.changeLog)}">`,
+      record.prompt.changeLogRecent,
+      '</recent_change_log>',
+    ].join('\n'));
+  }
+  return blocks;
+}
+
+/**
+ * Full block for the system prompt. Only fresh provider threads get it —
+ * resumed threads stay on the per-turn update path.
+ */
+function projectContextPromptBlock(contract) {
+  if (contract?.providerSessionId) return '';
+  const record = peekForContract(contract);
+  if (!record) return '';
+
+  const lines = [
+    '<project_context>',
+    `Project: ${record.name} (${record.projectPath})`,
+    'This is the project\'s durable memory. The change log is operational history (newest first); project state is the consolidated snapshot of where things stand; instructions are user-authored guidance for this project.',
+    '',
+    ...contentBlocks(record).flatMap((block) => [block, '']),
+    memoryProtocolBlock(),
+    '</project_context>',
+  ];
+
+  writeSeen(contract?.sessionId, record);
+  return lines.join('\n');
+}
+
+function readFileSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Per-turn freshness for resumed threads. Empty in the common case (revision
+ * unchanged). A session that predates the feature (or switched projects) gets
+ * the full context once, then deltas.
+ */
+function projectContextTurnUpdateBlock(contract) {
+  if (!contract?.providerSessionId) return '';
+  const record = peekForContract(contract);
+  if (!record) return '';
+
+  const seen = readSeen(contract?.sessionId);
+  if (seen && seen.projectId === record.projectId && seen.contextRevision === record.contextRevision) {
+    return '';
+  }
+
+  const blocks = [];
+  if (!seen || seen.projectId !== record.projectId) {
+    blocks.push(...contentBlocks(record));
+    blocks.push(memoryProtocolBlock());
+  } else {
+    const { changeLogEntriesSince } = require('./paths');
+    if (seen.instructionsRevision !== record.files?.instructions?.revision && record.prompt?.instructions) {
+      blocks.push([
+        `<project_instructions path="${escapeAttribute(record.paths?.instructions)}">`,
+        record.prompt.instructions,
+        '</project_instructions>',
+      ].join('\n'));
+    }
+    if (seen.projectStateRevision !== record.files?.projectState?.revision && record.prompt?.projectState) {
+      blocks.push([
+        `<project_state path="${escapeAttribute(record.paths?.projectState)}">`,
+        record.prompt.projectState,
+        '</project_state>',
+      ].join('\n'));
+    }
+    if (seen.changeLogRevision !== record.files?.changeLog?.revision) {
+      const content = readFileSafe(record.paths?.changeLog);
+      const floor = Number.isFinite(seen.latestEntryAtMs) ? seen.latestEntryAtMs : null;
+      let newEntries = changeLogEntriesSince(content, floor);
+      if (!newEntries && floor !== null) {
+        // Entry timestamps have second resolution, so an append within the
+        // same second as the previously-newest entry hides behind a strict
+        // ">" filter. Re-sending that second is cheaper than a context gap.
+        newEntries = changeLogEntriesSince(content, floor - 1);
+      }
+      if (newEntries) {
+        blocks.push([
+          `<new_change_log_entries path="${escapeAttribute(record.paths?.changeLog)}">`,
+          newEntries,
+          '</new_change_log_entries>',
+        ].join('\n'));
+      }
+    }
+  }
+
+  writeSeen(contract?.sessionId, record);
+  if (blocks.length === 0) return '';
+
+  return [
+    '<project_context_update>',
+    `Project context for ${record.name} (${record.projectPath}) changed since the last turn. Current state:`,
+    '',
+    ...blocks.flatMap((block) => [block, '']),
+    '</project_context_update>',
+  ].join('\n').trimEnd();
+}
+
+module.exports = {
+  projectContextPromptBlock,
+  projectContextTurnUpdateBlock,
+};