atris 3.82.26 → 3.83.0

package/lib/agent-home.js

@@ -0,0 +1,289 @@
+'use strict';
+
+// An Atris agent's home folder on this computer: the rules for which files
+// belong in it, the small state file that remembers what the server had at
+// the last pull, the adapter blocks that let any engine boot as the agent,
+// and the private key file a spawn returns.
+//
+// The server copy (POST/PUT /api/agents/{id}/home/...) is the durable one.
+// This module never talks to the network; commands/agent-home.js does.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { atrisHome } = require('./state-home');
+const { frontmatterOf, identityText } = require('./member-export');
+
+const STATE_REL = path.join('.atris', 'agent-home.json');
+const MAX_FILE_BYTES = 1000000;
+const MAX_FILES = 2000;
+const MAX_DEPTH = 24;
+// The adapters are generated here for the local engine and never sent up.
+const ADAPTER_FILES = ['AGENTS.md', 'CLAUDE.md'];
+const BLOCK_START = '<!-- atris agent home: start. generated by atris agent pull from MEMBER.md, SOUL.md and MISSION.md; edit those, this block gets rewritten -->';
+const BLOCK_END = '<!-- atris agent home: end -->';
+
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+function sha256(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+// A path that may live in a home, or null. Matches the server's refusals:
+// absolute, '..', hidden parts (.env*, .atris/, .git/), secrets/, *.pem, *.key.
+function homeRel(rel) {
+  if (typeof rel !== 'string' || !rel || rel.length > 400) return null;
+  if (rel.startsWith('/') || rel.includes('\\') || rel.includes('\0') || /^[A-Za-z]:/.test(rel)) return null;
+  const parts = rel.split('/');
+  if (parts.length > MAX_DEPTH) return null;
+  if (parts.some((part) => part === '' || part === '.' || part === '..' || part.startsWith('.'))) return null;
+  if (parts.slice(0, -1).includes('secrets')) return null;
+  if (/\.(pem|key)$/i.test(parts[parts.length - 1])) return null;
+  return rel;
+}
+
+function isAdapter(rel) {
+  return ADAPTER_FILES.includes(rel);
+}
+
+function statePath(dir) {
+  return path.join(dir, STATE_REL);
+}
+
+// { agent_id, handle, files: { rel: { etag, sha256 } }, pulled_at } or null.
+function loadState(dir) {
+  try {
+    const state = JSON.parse(fs.readFileSync(targetIn(dir, '.atris/agent-home.json'), 'utf8'));
+    if (!state || typeof state.agent_id !== 'string' || !state.agent_id) return null;
+    if (!state.files || typeof state.files !== 'object') state.files = {};
+    return state;
+  } catch {
+    return null;
+  }
+}
+
+function saveState(dir, state) {
+  const file = targetIn(dir, '.atris/agent-home.json');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${crypto.randomBytes(16).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { flag: 'wx' });
+  fs.renameSync(tmp, file);
+}
+
+// The nearest folder at or above `start` that holds a pulled home.
+function findHomeDir(start) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (loadState(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// Absolute path for `rel` inside `rootReal`, refusing any link on the way so
+// a server path can never write outside the folder.
+function targetIn(rootReal, rel) {
+  let current = rootReal;
+  for (const part of rel.split('/').slice(0, -1)) {
+    current = path.join(current, part);
+    let stat = null;
+    try { stat = fs.lstatSync(current); } catch {}
+    if (stat && !stat.isDirectory()) throw new Error(`${rel} would pass through a file or link`);
+  }
+  const abs = path.join(rootReal, rel);
+  let stat = null;
+  try { stat = fs.lstatSync(abs); } catch {}
+  if (stat && !stat.isFile()) throw new Error(`${rel} is not a plain file here`);
+  return abs;
+}
+
+function writeText(rootReal, rel, text) {
+  const abs = targetIn(rootReal, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, text, 'utf8');
+}
+
+// Local text, or null when the file is missing.
+function readLocal(rootReal, rel) {
+  try {
+    return fs.readFileSync(targetIn(rootReal, rel), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// Every file under the home that could go up: { files: Map(rel -> text), skipped: [{path, reason}] }.
+function scanHome(rootReal) {
+  const files = new Map();
+  const skipped = [];
+  const walk = (dir, prefix, depth) => {
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.name.startsWith('.')) continue;
+      if (!prefix && isAdapter(rel)) continue;
+      if (entry.isSymbolicLink()) { skipped.push({ path: rel, reason: 'is a link' }); continue; }
+      if (entry.isDirectory()) {
+        if (depth >= MAX_DEPTH || entry.name === 'secrets') { skipped.push({ path: rel, reason: 'is not allowed in a home' }); continue; }
+        walk(path.join(dir, entry.name), rel, depth + 1);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (!homeRel(rel)) { skipped.push({ path: rel, reason: 'is not allowed in a home' }); continue; }
+      if (files.size >= MAX_FILES) { skipped.push({ path: rel, reason: `is past the ${MAX_FILES} file limit` }); continue; }
+      const abs = path.join(dir, entry.name);
+      let data;
+      try { data = fs.readFileSync(abs); } catch { skipped.push({ path: rel, reason: 'could not be read' }); continue; }
+      if (data.length > MAX_FILE_BYTES) { skipped.push({ path: rel, reason: 'is over 1 MB' }); continue; }
+      let text;
+      try { text = utf8.decode(data); } catch { skipped.push({ path: rel, reason: 'is not text' }); continue; }
+      files.set(rel, text);
+    }
+  };
+  walk(rootReal, '', 1);
+  return { files, skipped };
+}
+
+// What changed here since the last pull or push: new or edited files to send,
+// and files the state knows that were deleted here.
+function localChanges(rootReal, state) {
+  const { files, skipped } = scanHome(rootReal);
+  const changed = [];
+  for (const [rel, text] of files) {
+    const base = state.files[rel];
+    if (!base || base.sha256 !== sha256(text)) changed.push({ path: rel, text });
+  }
+  const deleted = Object.keys(state.files).filter((rel) => homeRel(rel) && !isAdapter(rel) && !files.has(rel) && readLocal(rootReal, rel) === null).sort();
+  return { changed, deleted, skipped };
+}
+
+// A short, file-name-safe handle: "Scout Two" -> "scout-two".
+function handleOf(name) {
+  return String(name || '').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64);
+}
+
+// ---- adapters ---------------------------------------------------------------
+
+// The block both adapters carry: who the agent is, its soul, mission and
+// goals in full, and the folder rules. Engines read one of AGENTS.md (Codex,
+// Muse, Grok) or CLAUDE.md (Claude Code), so each carries the whole identity.
+function adapterBlock(rootReal) {
+  const memberText = readLocal(rootReal, 'MEMBER.md');
+  if (memberText === null) return null;
+  const { fields, body } = frontmatterOf(memberText);
+  const name = String(fields.name || '').trim() || 'this agent';
+  const role = String(fields.role || '').trim();
+  const lines = [
+    BLOCK_START,
+    '',
+    `# You are ${name}${role ? `, ${role}` : ''}`,
+    '',
+    `You are the Atris agent ${name}${fields.member_id ? ` (id ${fields.member_id})` : ''}. This folder is your home: your manifest, soul, mission, skills, memory and journal.`,
+    'Act as this agent for the whole session. Read MEMBER.md, SOUL.md and MISSION.md below as your own.',
+    '',
+    '## Folder rules',
+    '',
+    '- MEMBER.md is your manifest. Only your owner may change it; the server refuses your edits to it.',
+    '- Consolidated lessons go in memory/MEMORY.md.',
+    '- Each session adds one new note at memory/notes/<utc-timestamp>-<session>.md. Never edit another session\'s note.',
+    '- The day\'s journal is journal/YYYY/MM/DD.md.',
+    '- Secrets never go in this folder: no keys, tokens, .env files or secrets/.',
+    '- Save your work with `atris agent push`, then mark a version with `atris agent snapshot`.',
+    '- Also read when it helps: card.md, memory/MEMORY.md, skills/*/SKILL.md, tools/, context/.',
+    '',
+    '## Manifest (MEMBER.md)',
+    '',
+    body.trim() || '(empty)',
+    '',
+  ];
+  for (const [file, title] of [['SOUL.md', 'Soul'], ['MISSION.md', 'Mission'], ['goals.md', 'Goals']]) {
+    const text = identityText(rootReal, file, readLocal(rootReal, file));
+    if (text) lines.push(`## ${title} (${file})`, '', text, '');
+  }
+  lines.push(BLOCK_END);
+  return lines.join('\n');
+}
+
+// File text with the block inserted or replaced. Anything outside the block,
+// like a repo's own CLAUDE.md, is kept as it was.
+function withBlock(existing, block) {
+  if (existing === null || !existing.trim()) return `${block}\n`;
+  const start = existing.indexOf(BLOCK_START);
+  const end = existing.indexOf(BLOCK_END, start);
+  if (start >= 0 && end > start) {
+    return existing.slice(0, start) + block + existing.slice(end + BLOCK_END.length);
+  }
+  return `${existing.replace(/\s*$/, '')}\n\n${block}\n`;
+}
+
+// Write or refresh both adapters. Returns the files written, or [] when the
+// folder has no MEMBER.md yet.
+function writeAdapters(rootReal) {
+  const block = adapterBlock(rootReal);
+  if (!block) return [];
+  const written = [];
+  for (const rel of ADAPTER_FILES) {
+    const existing = readLocal(rootReal, rel);
+    const next = withBlock(existing, block);
+    if (next !== existing) {
+      writeText(rootReal, rel, next);
+      written.push(rel);
+    }
+  }
+  return written;
+}
+
+// ---- private keys -------------------------------------------------------------
+
+function keysDir(env = process.env) {
+  return path.join(atrisHome(env), 'agents');
+}
+
+function keyPath(handle, env = process.env) {
+  return path.join(keysDir(env), `${handle}.json`);
+}
+
+function readKeyFile(handle, env = process.env) {
+  if (!handle) return null;
+  try {
+    return JSON.parse(fs.readFileSync(keyPath(handle, env), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Owner-only folder and file; written through a temp file so a crash never
+// leaves half a key behind, and created 0600 so it is never readable by others.
+function writeKeyFile(handle, record, env = process.env) {
+  const dir = keysDir(env);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(dir, 0o700); } catch {}
+  const file = keyPath(handle, env);
+  const tmp = `${file}.${crypto.randomBytes(16).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+module.exports = {
+  BLOCK_START,
+  BLOCK_END,
+  MAX_FILE_BYTES,
+  findHomeDir,
+  handleOf,
+  homeRel,
+  keyPath,
+  loadState,
+  localChanges,
+  readKeyFile,
+  readLocal,
+  saveState,
+  sha256,
+  withBlock,
+  writeAdapters,
+  writeKeyFile,
+  writeText,
+};