@amalgm/chat 0.1.1 → 0.2.0

package/host/tooling/native-config.js

@@ -0,0 +1,460 @@
+/**
+ * Native harness config and provider-auth synchronization.
+ *
+ * The provider-auth import rules are preserved exactly: `provider_auth`
+ * syncs auth material only (auth.json links, .credentials.json, oauth JSON
+ * subsets, keychain alias) — never native prefs — and non-provider auth
+ * methods never import native config at all.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const EXCLUDED_DIR_NAMES = new Set([
+  '.cache',
+  '.npm',
+  '.tmp',
+  'cache',
+  'debug',
+  'generated_images',
+  'log',
+  'logs',
+  'memories',
+  'node_modules',
+  'plugins',
+  'projects',
+  'sessions',
+  'shell_snapshots',
+  'skills',
+  'tmp',
+  'worktrees',
+]);
+
+const EXCLUDED_FILE_PATTERNS = [
+  /^logs?_\d+\.sqlite(?:-.+)?$/i,
+  /^state_\d+\.sqlite(?:-.+)?$/i,
+  /^.*\.db-(?:shm|wal)$/i,
+  /^.*\.sqlite-(?:shm|wal)$/i,
+];
+
+function exists(p) {
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function shouldCopyConfigPath(root, source) {
+  const relative = path.relative(root, source);
+  if (!relative || relative === '.') return true;
+  const parts = relative.split(path.sep);
+  if (parts.some((part) => EXCLUDED_DIR_NAMES.has(part))) return false;
+  try {
+    if (fs.lstatSync(source).isSymbolicLink()) return false;
+  } catch {
+    return false;
+  }
+  const basename = path.basename(source);
+  return !EXCLUDED_FILE_PATTERNS.some((pattern) => pattern.test(basename));
+}
+
+function sameFile(a, b) {
+  try {
+    const left = fs.statSync(a);
+    const right = fs.statSync(b);
+    return left.dev === right.dev && left.ino === right.ino;
+  } catch {
+    return false;
+  }
+}
+
+function copyConfigTree(sourceDir, targetDir) {
+  if (!sourceDir || !targetDir || !exists(sourceDir)) return false;
+  if (path.resolve(sourceDir) === path.resolve(targetDir)) return true;
+  return copyDirBounded(sourceDir, targetDir, { maxFiles: 500, maxBytes: 25 * 1024 * 1024 }).copied;
+}
+
+function copyFileIfPresent(source, target) {
+  if (!exists(source)) return false;
+  if (!ensureDirectory(path.dirname(target)) || !canWriteFileTarget(target)) return false;
+  unlinkSymlinkIfPresent(target);
+  fs.copyFileSync(source, target);
+  try {
+    fs.chmodSync(target, fs.statSync(source).mode & 0o777);
+  } catch {}
+  return true;
+}
+
+function unlinkSymlinkIfPresent(target) {
+  try {
+    if (fs.lstatSync(target).isSymbolicLink()) fs.unlinkSync(target);
+  } catch {}
+}
+
+function linkFileIfPresent(source, target) {
+  if (!exists(source)) return false;
+  if (!ensureDirectory(path.dirname(target))) return false;
+  if (sameFile(source, target)) return true;
+  try {
+    const stat = fs.lstatSync(target);
+    if (stat.isDirectory()) return false;
+    fs.unlinkSync(target);
+  } catch {}
+  try {
+    fs.symlinkSync(source, target, 'file');
+    return true;
+  } catch {}
+  try {
+    fs.linkSync(source, target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ensureHomeAlias(runtimeHome, dotDirName) {
+  if (!runtimeHome || !dotDirName) return;
+  const alias = path.join(runtimeHome, dotDirName);
+  try {
+    const stat = fs.lstatSync(alias);
+    if (stat.isSymbolicLink()) {
+      const target = fs.readlinkSync(alias);
+      if (target === '.' || path.resolve(runtimeHome, target) === path.resolve(runtimeHome)) return;
+    }
+    return;
+  } catch {}
+  try {
+    fs.symlinkSync('.', alias, 'dir');
+  } catch {
+    fs.mkdirSync(alias, { recursive: true });
+  }
+}
+
+function ensureNativeKeychainAlias(runtimeHome) {
+  if (process.platform !== 'darwin' || !runtimeHome) return false;
+  const source = path.join(nativeHome(), 'Library', 'Keychains');
+  if (!exists(source)) return false;
+  const target = path.join(runtimeHome, 'Library', 'Keychains');
+  try {
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink()) {
+      const linkTarget = fs.readlinkSync(target);
+      if (path.resolve(path.dirname(target), linkTarget) === path.resolve(source)) return true;
+    }
+    return false;
+  } catch {}
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  try {
+    fs.symlinkSync(source, target, 'dir');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function nativeHome() {
+  return process.env.AMALGM_NATIVE_HOME || os.homedir();
+}
+
+function ensureDirectory(dir) {
+  try {
+    const stat = fs.lstatSync(dir);
+    return stat.isDirectory();
+  } catch {
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+function canWriteFileTarget(target) {
+  try {
+    const stat = fs.lstatSync(target);
+    return stat.isFile();
+  } catch {
+    return true;
+  }
+}
+
+function copyDirBounded(sourceDir, targetDir, options = {}) {
+  if (!sourceDir || !targetDir || !exists(sourceDir)) return { copied: false, files: 0, bytes: 0, truncated: false };
+  const maxFiles = Number(options.maxFiles || 200);
+  const maxBytes = Number(options.maxBytes || 10 * 1024 * 1024);
+  const skipRelatives = new Set(Array.isArray(options.skipRelatives) ? options.skipRelatives : []);
+  const state = { copied: false, files: 0, bytes: 0, truncated: false };
+  const root = path.resolve(sourceDir);
+
+  function walk(source, target) {
+    const relative = path.relative(root, source);
+    if (relative && skipRelatives.has(relative)) return;
+    if (state.truncated || !shouldCopyConfigPath(root, source)) return;
+    let stat;
+    try {
+      stat = fs.lstatSync(source);
+    } catch {
+      return;
+    }
+    if (stat.isSymbolicLink()) return;
+    if (stat.isDirectory()) {
+      if (!ensureDirectory(target)) return;
+      for (const entry of fs.readdirSync(source)) {
+        walk(path.join(source, entry), path.join(target, entry));
+        if (state.truncated) break;
+      }
+      return;
+    }
+    if (!stat.isFile()) return;
+    if (state.files + 1 > maxFiles || state.bytes + stat.size > maxBytes) {
+      state.truncated = true;
+      return;
+    }
+    if (!ensureDirectory(path.dirname(target)) || !canWriteFileTarget(target)) return;
+    fs.copyFileSync(source, target);
+    state.files += 1;
+    state.bytes += stat.size;
+    state.copied = true;
+  }
+
+  walk(sourceDir, targetDir);
+  return state;
+}
+
+export function syncCodexNativeConfig(runtimeHome) {
+  if (!runtimeHome) return null;
+  const sourceDir = path.join(nativeHome(), '.codex');
+  const sourceAuth = path.join(sourceDir, 'auth.json');
+  fs.mkdirSync(runtimeHome, { recursive: true });
+  if (!exists(sourceDir)) return null;
+
+  const nativeConfig = copyDirBounded(sourceDir, runtimeHome, { skipRelatives: ['auth.json'] });
+  const copiedFiles = [
+    copyFileIfPresent(path.join(sourceDir, 'config.toml'), path.join(runtimeHome, 'config.toml')),
+    copyFileIfPresent(path.join(sourceDir, 'hooks.json'), path.join(runtimeHome, 'hooks.json')),
+    copyFileIfPresent(path.join(sourceDir, 'supermemory.json'), path.join(runtimeHome, 'supermemory.json')),
+  ].filter(Boolean).length;
+  const supermemory = copyDirBounded(path.join(sourceDir, 'supermemory'), path.join(runtimeHome, 'supermemory'));
+  copyDirBounded(path.join(nativeHome(), '.codex-supermemory'), path.join(runtimeHome, '.codex-supermemory'));
+  ensureHomeAlias(runtimeHome, '.codex');
+  const linkedAuth = linkFileIfPresent(sourceAuth, path.join(runtimeHome, 'auth.json'));
+  linkFileIfPresent(sourceAuth, path.join(runtimeHome, '.codex', 'auth.json'));
+
+  return {
+    sourceDir,
+    runtimeHome,
+    sourceConfigPath: path.join(sourceDir, 'config.toml'),
+    copied: nativeConfig.copied || copiedFiles + (supermemory.copied ? 1 : 0) > 0 || linkedAuth,
+    truncated: nativeConfig.truncated || supermemory.truncated,
+    linkedAuth,
+  };
+}
+
+export function syncClaudeNativeConfig(runtimeHome) {
+  if (!runtimeHome) return null;
+  const home = nativeHome();
+  if (path.resolve(runtimeHome) === path.resolve(home)) return null;
+  const sourceDir = path.join(home, '.claude');
+  fs.mkdirSync(runtimeHome, { recursive: true });
+  const copied = copyConfigTree(sourceDir, runtimeHome);
+  ensureHomeAlias(runtimeHome, '.claude');
+  ensureNativeKeychainAlias(runtimeHome);
+  copyFileIfPresent(path.join(home, '.claude.json'), path.join(runtimeHome, '.claude.json'));
+  copyConfigTree(path.join(home, '.config', 'claude'), path.join(runtimeHome, '.config', 'claude'));
+  return copied ? { sourceDir, runtimeHome } : null;
+}
+
+export function syncOpenCodeNativeConfig(runtimeHome) {
+  if (!runtimeHome) return null;
+  const home = nativeHome();
+  fs.mkdirSync(runtimeHome, { recursive: true });
+  const config = copyConfigTree(
+    path.join(home, '.config', 'opencode'),
+    path.join(runtimeHome, '.config', 'opencode'),
+  );
+  const data = copyConfigTree(
+    path.join(home, '.local', 'share', 'opencode'),
+    path.join(runtimeHome, '.local', 'share', 'opencode'),
+  );
+  const dot = copyConfigTree(path.join(home, '.opencode'), path.join(runtimeHome, '.opencode'));
+  if (!config && !data && !dot) return null;
+  return {
+    sourceDir: path.join(home, '.config', 'opencode'),
+    runtimeHome,
+    copied: config || data || dot,
+  };
+}
+
+function copyJsonSubsetIfPresent(source, target, keys) {
+  const data = readJsonFile(source);
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return false;
+  const out = {};
+  for (const key of keys) {
+    if (data[key] !== undefined) out[key] = data[key];
+  }
+  if (Object.keys(out).length === 0) return false;
+  if (!ensureDirectory(path.dirname(target)) || !canWriteFileTarget(target)) return false;
+  fs.writeFileSync(target, JSON.stringify(out, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(target, 0o600); } catch {}
+  return true;
+}
+
+export function syncCodexProviderAuth(runtimeHome) {
+  if (!runtimeHome) return null;
+  const sourceDir = path.join(nativeHome(), '.codex');
+  const sourceAuth = path.join(sourceDir, 'auth.json');
+  fs.mkdirSync(runtimeHome, { recursive: true });
+  ensureHomeAlias(runtimeHome, '.codex');
+  const linked = linkFileIfPresent(sourceAuth, path.join(runtimeHome, 'auth.json'));
+  if (linked) linkFileIfPresent(sourceAuth, path.join(runtimeHome, '.codex', 'auth.json'));
+  return linked ? { sourceDir, runtimeHome, copied: false, linkedAuth: true, authOnly: true } : null;
+}
+
+export function syncClaudeProviderAuth(runtimeHome) {
+  if (!runtimeHome) return null;
+  const home = nativeHome();
+  const sourceDir = path.join(home, '.claude');
+  fs.mkdirSync(runtimeHome, { recursive: true });
+  ensureHomeAlias(runtimeHome, '.claude');
+  const copiedCredentials = copyFileIfPresent(
+    path.join(sourceDir, '.credentials.json'),
+    path.join(runtimeHome, '.credentials.json'),
+  );
+  const copiedOauth = copyJsonSubsetIfPresent(
+    path.join(home, '.claude.json'),
+    path.join(runtimeHome, '.claude.json'),
+    ['claudeAiOauth', 'oauthAccount'],
+  ) || copyJsonSubsetIfPresent(
+    path.join(sourceDir, '.claude.json'),
+    path.join(runtimeHome, '.claude.json'),
+    ['claudeAiOauth', 'oauthAccount'],
+  );
+  const keychain = ensureNativeKeychainAlias(runtimeHome);
+  return copiedCredentials || copiedOauth || keychain
+    ? { sourceDir, runtimeHome, copied: copiedCredentials || copiedOauth, keychain, authOnly: true }
+    : null;
+}
+
+// Cursor stores its login token in the macOS Keychain (service "cursor-access-token"),
+// not in a file, so warm auth in a managed home rides on the Keychains alias.
+// cli-config.json is copied once so the CLI starts from the user's preferences.
+export function syncCursorProviderAuth(runtimeHome) {
+  if (!runtimeHome) return null;
+  const home = nativeHome();
+  const sourceDir = path.join(home, '.cursor');
+  fs.mkdirSync(runtimeHome, { recursive: true });
+  const keychain = ensureNativeKeychainAlias(runtimeHome);
+  const copiedAuth = copyFileIfPresent(
+    path.join(sourceDir, 'auth.json'),
+    path.join(runtimeHome, '.cursor', 'auth.json'),
+  );
+  const targetConfig = path.join(runtimeHome, '.cursor', 'cli-config.json');
+  const copiedConfig = !exists(targetConfig) && copyFileIfPresent(path.join(sourceDir, 'cli-config.json'), targetConfig);
+  return keychain || copiedAuth || copiedConfig
+    ? { sourceDir, runtimeHome, copied: copiedAuth || copiedConfig, keychain, authOnly: true }
+    : null;
+}
+
+// Pi keeps provider keys and custom-provider config under ~/.pi; auth.json is
+// the auth material, models.json/settings.json carry provider definitions the
+// managed home needs to resolve the same models.
+export function syncPiProviderAuth(runtimeHome) {
+  if (!runtimeHome) return null;
+  const home = nativeHome();
+  const sourceDir = path.join(home, '.pi');
+  fs.mkdirSync(runtimeHome, { recursive: true });
+  const copied = ['agent/auth.json', 'agent/models.json', 'agent/settings.json']
+    .map((file) => copyFileIfPresent(path.join(sourceDir, file), path.join(runtimeHome, '.pi', file)))
+    .some(Boolean);
+  return copied ? { sourceDir, runtimeHome, copied: true, authOnly: true } : null;
+}
+
+export function syncOpenCodeProviderAuth(runtimeHome) {
+  if (!runtimeHome) return null;
+  const home = nativeHome();
+  const source = path.join(home, '.local', 'share', 'opencode', 'auth.json');
+  const target = path.join(runtimeHome, '.local', 'share', 'opencode', 'auth.json');
+  fs.mkdirSync(runtimeHome, { recursive: true });
+  const copied = copyFileIfPresent(source, target);
+  return copied ? { sourceDir: path.dirname(source), runtimeHome, copied: true, authOnly: true } : null;
+}
+
+function readJsonFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function cloneJson(value) {
+  if (value == null) return value;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return null;
+  }
+}
+
+function mergeHookMaps(target, hooks) {
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) return;
+  for (const [event, matchers] of Object.entries(hooks)) {
+    if (!Array.isArray(matchers)) continue;
+    const cloned = cloneJson(matchers);
+    if (!Array.isArray(cloned)) continue;
+    target[event] = [...(Array.isArray(target[event]) ? target[event] : []), ...cloned];
+  }
+}
+
+export function claudeNativeHookSettings(options = {}) {
+  const sources = [
+    path.join(nativeHome(), '.claude', 'settings.json'),
+    options.cwd ? path.join(options.cwd, '.claude', 'settings.json') : null,
+    options.cwd ? path.join(options.cwd, '.claude', 'settings.local.json') : null,
+  ].filter(Boolean);
+  const hooks = {};
+  for (const source of sources) {
+    const data = readJsonFile(source);
+    mergeHookMaps(hooks, data?.hooks);
+  }
+  return Object.keys(hooks).length > 0 ? { hooks } : null;
+}
+
+export function syncNativeHarnessConfig(contract) {
+  const runtimeHome = contract?.auth?.runtimeHome;
+  if (!runtimeHome) return null;
+  if (contract.authMethod !== 'provider_auth') return null;
+  if (contract.harness === 'codex') return syncCodexNativeConfig(runtimeHome);
+  if (contract.harness === 'claude_code') return syncClaudeNativeConfig(runtimeHome);
+  if (contract.harness === 'opencode') return syncOpenCodeNativeConfig(runtimeHome);
+  return null;
+}
+
+export function syncNativeProviderAuth(contract) {
+  const runtimeHome = contract?.auth?.runtimeHome;
+  if (!runtimeHome) return null;
+  if (contract.authMethod !== 'provider_auth') return null;
+  if (contract.harness === 'codex') return syncCodexProviderAuth(runtimeHome);
+  if (contract.harness === 'claude_code') return syncClaudeProviderAuth(runtimeHome);
+  if (contract.harness === 'opencode') return syncOpenCodeProviderAuth(runtimeHome);
+  if (contract.harness === 'cursor') return syncCursorProviderAuth(runtimeHome);
+  if (contract.harness === 'pi') return syncPiProviderAuth(runtimeHome);
+  return null;
+}
+
+export const __private = {
+  claudeNativeHookSettings,
+  copyConfigTree,
+  copyDirBounded,
+  copyFileIfPresent,
+  ensureDirectory,
+  ensureNativeKeychainAlias,
+  ensureHomeAlias,
+  linkFileIfPresent,
+  shouldCopyConfigPath,
+  unlinkSymlinkIfPresent,
+};

package/host/tooling/package-import.js

@@ -0,0 +1,111 @@
+/**
+ * Optional-package importer. Bare `import()` is followed by explicit
+ * node_modules fallbacks for NODE_PATH, ancestors, and Electron resources.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function packageParts(specifier) {
+  const parts = String(specifier || '').split('/').filter(Boolean);
+  if (parts.length === 0) throw new Error('Package specifier is required');
+  if (parts[0].startsWith('@')) {
+    if (parts.length < 2) throw new Error(`Invalid scoped package specifier: ${specifier}`);
+    return {
+      packageName: `${parts[0]}/${parts[1]}`,
+      subpath: parts.slice(2).join('/'),
+    };
+  }
+  return {
+    packageName: parts[0],
+    subpath: parts.slice(1).join('/'),
+  };
+}
+
+function nodePathEntries() {
+  return String(process.env.NODE_PATH || '')
+    .split(path.delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function ancestorNodeModules() {
+  const entries = [];
+  let current = __dirname;
+  for (;;) {
+    entries.push(path.join(current, 'node_modules'));
+    const next = path.dirname(current);
+    if (next === current) break;
+    current = next;
+  }
+  return entries;
+}
+
+function candidateNodeModules() {
+  const resourcesPath = process.resourcesPath || '';
+  const entries = [
+    ...nodePathEntries(),
+    ...ancestorNodeModules(),
+    resourcesPath ? path.join(resourcesPath, 'app.asar', 'node_modules') : '',
+    resourcesPath ? path.join(resourcesPath, 'app.asar.unpacked', 'node_modules') : '',
+    resourcesPath ? path.join(resourcesPath, 'cli', 'node_modules') : '',
+    resourcesPath ? path.join(resourcesPath, 'runtime', 'node_modules') : '',
+  ].filter(Boolean);
+  return Array.from(new Set(entries));
+}
+
+function readPackageJson(packageRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function exportedPath(exportsField, subpath) {
+  if (!exportsField) return '';
+  const key = subpath ? `./${subpath}` : '.';
+  const value = typeof exportsField === 'object' && !Array.isArray(exportsField)
+    ? exportsField[key]
+    : (key === '.' ? exportsField : null);
+  if (!value) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'object' || Array.isArray(value)) return '';
+  for (const condition of ['import', 'module', 'default', 'node', 'require']) {
+    if (typeof value[condition] === 'string') return value[condition];
+  }
+  return '';
+}
+
+export function resolvePackageEntry(specifier) {
+  const { packageName, subpath } = packageParts(specifier);
+  for (const nodeModules of candidateNodeModules()) {
+    const packageRoot = path.join(nodeModules, packageName);
+    const pkg = readPackageJson(packageRoot);
+    if (!pkg) continue;
+
+    const target = (
+      exportedPath(pkg.exports, subpath)
+      || (subpath ? subpath : '')
+      || pkg.module
+      || pkg.main
+      || 'index.js'
+    );
+    const resolved = path.join(packageRoot, target);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+  return '';
+}
+
+export async function importPackage(specifier) {
+  try {
+    return await import(specifier);
+  } catch (originalError) {
+    const resolved = resolvePackageEntry(specifier);
+    if (!resolved) throw originalError;
+    return import(pathToFileURL(resolved).href);
+  }
+}

package/host/tooling/runtime-home.js

@@ -0,0 +1,26 @@
+/** Prepare the one managed CLI home owned by an agent installation. */
+
+import fs from 'node:fs';
+import { runtimeEnv } from '../auth.js';
+import { syncNativeProviderAuth } from './native-config.js';
+
+export function managedRuntimeHome(contract) {
+  const runtimeHome = contract?.auth?.runtimeHome;
+  if (typeof runtimeHome !== 'string' || !runtimeHome.trim()) {
+    throw new Error(`${contract?.harness || 'Agent'} is missing a managed CLI home`);
+  }
+  return runtimeHome;
+}
+
+export function prepareHarnessRuntime(contract, baseEnv = process.env) {
+  const runtimeHome = managedRuntimeHome(contract);
+  fs.mkdirSync(runtimeHome, { recursive: true });
+  const syncInfo = contract?.authMethod === 'provider_auth'
+    ? syncNativeProviderAuth(contract)
+    : null;
+  return {
+    runtimeHome,
+    syncInfo,
+    env: runtimeEnv(contract, baseEnv),
+  };
+}

package/host/tooling/system-instructions.js

@@ -0,0 +1,69 @@
+/**
+ * System-level instructions — the one machine-wide context document.
+ *
+ * `<AMALGM_DIR>/context/system-instructions.md` is user-authored and applies
+ * to every session on this computer. Project context is handled separately.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { amalgmDir } from '../lib/runtime-paths.js';
+
+const CONTEXT_FILE_MAX_CHARS = 12_000;
+const SYSTEM_INSTRUCTIONS_FILENAME = 'system-instructions.md';
+
+function systemContextPaths(dir) {
+  const root = path.join(path.resolve(dir), 'context');
+  return {
+    root,
+    instructions: path.join(root, SYSTEM_INSTRUCTIONS_FILENAME),
+  };
+}
+
+/**
+ * A title-only document has no operative instructions.
+ */
+function isEmptyContextDoc(content) {
+  const body = String(content || '')
+    .replace(/^\uFEFF/, '')
+    .replace(/^#[^\n]*\n?/, '')
+    .trim();
+  return !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]`;
+}
+
+export function systemInstructionsPath() {
+  return systemContextPaths(amalgmDir()).instructions;
+}
+
+function escapeAttribute(value) {
+  return String(value || '')
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+export function systemInstructionsBlock() {
+  const filePath = systemInstructionsPath();
+  let content = '';
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+  if (isEmptyContextDoc(content)) return '';
+  return [
+    `<system_instructions path="${escapeAttribute(filePath)}">`,
+    'These are user-authored instructions that apply to every session on this computer. Current user requests and higher-priority system/developer instructions win on conflict.',
+    '',
+    cappedDocContent(content),
+    '</system_instructions>',
+  ].join('\n');
+}

package/host/tooling/system-prompt.js

@@ -0,0 +1,35 @@
+import { systemInstructionsBlock } from './system-instructions.js';
+
+function trimBlock(value) {
+  return String(value || '').trim();
+}
+
+function safeBlock(label, render) {
+  if (typeof render !== 'function') return '';
+  try {
+    return trimBlock(render());
+  } catch (error) {
+    const message = error instanceof Error ? error.message.split('\n')[0] : String(error);
+    console.warn(`[chat] ${label} failed:`, message);
+    return '';
+  }
+}
+
+/** Compose machine, project, and exact agent-revision instructions once. */
+export function composeSystemPrompt(contract, options = {}) {
+  const parts = [];
+  const systemInstructions = contract?.providerSessionId
+    ? ''
+    : safeBlock('system instructions', systemInstructionsBlock);
+  const projectContext = safeBlock(
+    'project context',
+    typeof options.projectContextPromptBlock === 'function'
+      ? () => options.projectContextPromptBlock(contract)
+      : null,
+  );
+  const agentInstructions = trimBlock(contract?.compiledAgentInstructions);
+  if (systemInstructions) parts.push(systemInstructions);
+  if (projectContext) parts.push(projectContext);
+  if (agentInstructions) parts.push(agentInstructions);
+  return parts.join('\n\n');
+}