aegis-desktop 0.8.12 → 0.8.13

package/vendor/attest.js

@@ -0,0 +1,439 @@
+'use strict';
+
+/**
+ * attest.js — turn a session into a φ(α) record.
+ *
+ * `client/fingerprint.js` knows how to seal a record from *inputs*; it knows
+ * nothing about where those inputs live, and that is deliberate — the vendored
+ * module must stay byte-identical to the engine's, so nothing host-specific can
+ * be added to it. This file is that missing half, shared by the CLI and the
+ * desktop so both hosts attest a session the same way: the same log is read the
+ * same way, thumbed into the same observations, and sealed under the same key.
+ *
+ * ## What the fields may be
+ *
+ * The engine's rule (see `src/fingerprint.js`) is that a record may carry only
+ * what was actually observed: a fabricated field is not evidence. Carried over
+ * literally here, that means this module never invents a value to fill a shape:
+ *
+ *  - a session log entry that carries no recognisable working directory
+ *    contributes `dir: null`, not `process.cwd()`;
+ *  - a turn with no recorded outcome contributes `outcome: null`, not `'ok'`;
+ *  - `--turns N` that selects more turns than exist attests the turns there
+ *    are, and the record's `behaviourSamples` then says how many that was.
+ *
+ * A null field is a true statement about the log ("the log did not say"); a
+ * guessed one is a false statement about the session. The engine's `verify`
+ * compares the attestation over these fields, so the difference is not
+ * cosmetic — it is the difference between a record that reproduces and one
+ * that does not.
+ *
+ * ## Schema tolerance, and why it stops where it does
+ *
+ * The session log has carried more than one entry shape across versions, so
+ * each turn is read through a small ordered list of aliases (`cwd`/`dir`,
+ * `demand`/`prompt`/…). Unknown keys are ignored rather than merged in, because
+ * an unknown key is a key nobody has agreed on the meaning of, and including it
+ * would make the behavioural axis change silently the first time a log gained a
+ * field. Adding an alias here is a deliberate act with a test behind it.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const fp = require('./fingerprint.js');
+const authorship = require('./authorship-key.js');
+
+const DEFAULT_HISTORY = () => path.join(authorship.dataDir(), 'history.jsonl');
+
+/** Ordered aliases. First present key wins; a later alias never overrides one. */
+const DIR_KEYS = ['cwd', 'dir', 'workspace', 'root'];
+const DEMAND_KEYS = ['demand', 'prompt', 'task', 'text', 'content'];
+const OUTCOME_KEYS = ['outcome', 'status', 'result'];
+const SESSION_KEYS = ['session', 'sessionId', 'session_id'];
+const TIME_KEYS = ['at', 'ts', 'time', 'createdAt'];
+
+/**
+ * The AI half's aliases. Separate lists from the human half's on purpose: `text`
+ * is a demand in `DEMAND_KEYS` and a reply would be one here, and a shared list
+ * would let one axis read the other's field — which is exactly the conflation the
+ * two signatures exist to prevent.
+ */
+const REPLY_KEYS = ['reply', 'answer', 'response'];
+const MODEL_KEYS = ['model', 'aiModel', 'modelId'];
+
+/** `sha256(text)[0:8]` — a content address, never the content. */
+const sha256hex = (text) => crypto.createHash('sha256').update(String(text || ''), 'utf8').digest('hex');
+
+/** Where the AI credential comes from: `--ai-secret FILE`, then `AEGIS_AI_SECRET`. */
+const AI_SECRET_ENV = 'AEGIS_AI_SECRET';
+
+function firstKey(entry, keys) {
+  for (const k of keys) {
+    const v = entry[k];
+    if (v === undefined || v === null) continue;
+    const s = typeof v === 'string' ? v : String(v);
+    if (s.trim() !== '') return s;
+  }
+  return null;
+}
+
+/**
+ * Read a session log.
+ *
+ * A malformed line is skipped, not fatal: a half-written last line is the
+ * normal state of an append-only log that was interrupted, and refusing the
+ * whole file over it would mean the sessions with the most history — the ones
+ * worth attesting — are the ones that cannot be.
+ */
+function readHistory(file) {
+  if (!fs.existsSync(file)) throw new Error(`attest: no session log at ${file}`);
+  const entries = [];
+  let skipped = 0;
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    const text = line.trim();
+    if (!text) continue;
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed && typeof parsed === 'object') entries.push(parsed);
+      else skipped += 1;
+    } catch {
+      skipped += 1;
+    }
+  }
+  return { entries, skipped };
+}
+
+/** The last session id the log mentions, which is what "current" means. */
+function lastSessionId(entries) {
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const id = firstKey(entries[i], SESSION_KEYS);
+    if (id) return id;
+  }
+  return null;
+}
+
+/**
+ * Select the turns to attest.
+ *
+ * With no `session`, the last session in the log is used — attributed rather
+ * than assumed: turns whose session id is missing are included only when no
+ * session was requested, since "which session is this?" is exactly the question
+ * they cannot answer.
+ */
+function selectTurns(entries, { session = null, turns = null } = {}) {
+  let chosen = entries;
+  if (session) {
+    const wanted = String(session);
+    chosen = entries.filter((e) => firstKey(e, SESSION_KEYS) === wanted);
+  }
+  if (turns && Number.isFinite(Number(turns)) && Number(turns) > 0) {
+    chosen = chosen.slice(-Math.floor(Number(turns)));
+  }
+  return chosen;
+}
+
+/**
+ * Fold turns into observations.
+ *
+ * The keys are the ENGINE's (`fp.observationKey` reads `tool`, `target`,
+ * `outcome`, `model`) and nothing else, because an observation is hashed by
+ * reading those four fields and a field with another name is silently dropped —
+ * it never reaches the signature it was handed over to feed. An earlier version of
+ * this function emitted `{dir, demand, outcome}` and read as if the demand were
+ * attested; it was not, so the behavioural axis of every record minted from a
+ * session log described the turn outcomes alone.
+ *
+ * So the two true things this log says about a turn are carried as the engine's
+ * fields: where it ran and what was asked for. `target` is a content address of
+ * the demand rather than the demand itself — the signature exists to compare
+ * agents, not to archive what they were told — and it is addressed exactly as
+ * `aegiscodex`'s own tool addresses it, so the two hosts read one session log into
+ * one digest.
+ *
+ * `outcome` stays `null` when the log did not record one, and a null field
+ * contributes no signal: `behaviouralSignature` drops an observation that carries
+ * nothing, and `behaviourSamples` counts what was actually attested.
+ */
+function observationsFromTurns(turns) {
+  const out = [];
+  for (const t of Array.isArray(turns) ? turns : []) {
+    if (!t || typeof t !== 'object') continue;
+    const dir = firstKey(t, DIR_KEYS);
+    const demand = firstKey(t, DEMAND_KEYS);
+    out.push({
+      tool: demand || dir ? 'turn' : null,
+      target: `${dir ? path.basename(dir) : '?'}#${sha256hex(demand || '').slice(0, 8)}`,
+      outcome: firstKey(t, OUTCOME_KEYS),
+    });
+  }
+  return out;
+}
+
+/**
+ * Fold the same turns from the *reply* side: the AI axis's observations.
+ *
+ * One observation per turn, carrying only what the entry records about the
+ * answer — the tool it named (usually none), the working directory it ran in, the
+ * outcome, and the model that produced it. Every one of those is `null` when the
+ * log did not say, and `null` contributes no signal: `fp.aiSignature` hashes only
+ * the observations that carry something, and `aiSamples` counts those. A log that
+ * records nothing about the answers therefore yields `ai: null, aiSamples: 0` —
+ * "the log did not say" — rather than a signature over a row of empty fields.
+ *
+ * The reply text is deliberately NOT hashed. It would be a transcript hash wearing
+ * a behavioural signature's name: two agents answering the same demand in
+ * different words would stop matching, and the axis is meant to compare habits,
+ * not prose. `--ai-observations` (the engine CLI) is where a caller who has real
+ * tool-level AI observations passes them.
+ */
+function aiObservationsFromTurns(turns) {
+  const out = [];
+  for (const t of Array.isArray(turns) ? turns : []) {
+    if (!t || typeof t !== 'object') continue;
+    const reply = firstKey(t, REPLY_KEYS);
+    const status = firstKey(t, OUTCOME_KEYS);
+    const model = firstKey(t, MODEL_KEYS);
+    // "Answered" is evidence about the ANSWER. A turn the log recorded with no
+    // reply, no status and no model contributes an all-null observation, which
+    // `fp.aiSignature` drops: "the log never said" must stay distinct from a
+    // signature over a pretend answer, and the working directory the human side
+    // already carries must not be re-read as if it were the AI's evidence.
+    const answered = Boolean(reply || status || model);
+    out.push({
+      tool: answered ? 'reply' : null,
+      // The reply is addressed, not archived — the same discipline the engine tool
+      // uses for a demand, and it is why both hosts read one log into one digest.
+      target: answered ? `reply#${sha256hex(reply || '').slice(0, 8)}` : null,
+      outcome: status || null,
+      model,
+    });
+  }
+  return out;
+}
+
+/**
+ * Resolve the AI credential: `--ai-secret FILE`, then `$AEGIS_AI_SECRET`, else no
+ * key.
+ *
+ * `--ai-secret` is an alias for the engine's `--ai-secret-file` spelling, and both
+ * are checked because the two hosts' users read different docs. The authorship
+ * ladder is NOT consulted: `keyFingerprint` of the sealing key would make every
+ * record claim it ran on its author's key, and "which mind answered" would stop
+ * being a question with an answer. No key nominated ⇒ `null`, which the record
+ * states plainly.
+ */
+function resolveAiSecret(o = {}) {
+  const argv = o.argv || [];
+  const env = o.env || {};
+  const file = firstFlag(argv, ['--ai-secret', '--ai-secret-file']);
+  if (file) {
+    const secret = fs.readFileSync(file, 'utf8').trim();
+    if (!secret) throw new Error(`attest: ${file} is empty — an empty AI credential is not one`);
+    return { secret, source: file };
+  }
+  const envSecret = env[AI_SECRET_ENV] && String(env[AI_SECRET_ENV]).trim();
+  if (envSecret) return { secret: envSecret, source: AI_SECRET_ENV };
+  return { secret: null, source: 'none' };
+}
+
+/** `--flag V`, first spelling that matches. Local so this file keeps no argv helper. */
+function firstFlag(argv, names) {
+  for (const name of names) {
+    const i = argv.indexOf(name);
+    if (i !== -1 && argv[i + 1] !== undefined && !String(argv[i + 1]).startsWith('--')) {
+      return argv[i + 1];
+    }
+  }
+  return null;
+}
+
+/**
+ * Walk a directory and return `{path, content}` records for the code axis.
+ *
+ * The key names are the engine's (`codeDigest` reads `f.path`), not this
+ * module's choice: a mismatch here yields `codeFiles: 0` and a null axis —
+ * silently, since the engine treats an unusable path as "not a file" rather
+ * than as an error. `test/fingerprint.test.mjs` pins the count for that reason.
+ *
+ * Symlinks are not followed and the noisy trees are skipped, matching the
+ * engine tool: the axis is meant to say *which revision of which files*, and a
+ * walk that followed a symlink out of the declared root, or dragged in
+ * `node_modules`, would attest something other than the user's code. An
+ * oversized file throws rather than attesting a hole in the digest.
+ */
+const SKIP_DIRS = new Set([
+  '.git',
+  'node_modules',
+  'dist',
+  'build',
+  'out',
+  'vendor',
+  '.venv',
+  'venv',
+  '__pycache__',
+  '.next',
+  '.cache',
+  'release',
+  'coverage',
+]);
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_FILES = 4096;
+
+function collectCode({ roots = [], files = [], skip = [] } = {}) {
+  const extraSkip = new Set(skip);
+  const out = [];
+  const add = (relpath, abs) => {
+    const st = fs.statSync(abs);
+    if (!st.isFile()) return;
+    if (st.size > MAX_FILE_BYTES) {
+      throw new Error(`attest: ${abs} is ${st.size} bytes — too large to attest (max ${MAX_FILE_BYTES})`);
+    }
+    if (out.length >= MAX_FILES) {
+      throw new Error(`attest: more than ${MAX_FILES} files — refusing to attest a partial walk`);
+    }
+    const rel = fp.normaliseCodePath(relpath);
+    if (!rel) return; // a path the engine cannot use is not a code file
+    out.push({ path: rel, content: fs.readFileSync(abs, 'utf8') });
+  };
+
+  for (const root of roots) {
+    const abs = path.resolve(root);
+    const walk = (dir, prefix) => {
+      for (const name of fs.readdirSync(dir).sort()) {
+        const full = path.join(dir, name);
+        const rel = prefix ? `${prefix}/${name}` : name;
+        const st = fs.lstatSync(full);
+        if (st.isSymbolicLink()) continue; // never leave the declared root
+        if (st.isDirectory()) {
+          if (SKIP_DIRS.has(name) || extraSkip.has(name)) continue;
+          walk(full, rel);
+          continue;
+        }
+        add(rel, full);
+      }
+    };
+    walk(abs, '');
+  }
+
+  for (const file of files) {
+    const abs = path.resolve(file);
+    add(path.basename(abs), abs);
+  }
+
+  return out;
+}
+
+/**
+ * Mint a record for a session.
+ *
+ * @param {object} o
+ * @param {string[]} [o.argv]        flags; `--secret`/`--secret-file` are read here
+ * @param {object}   [o.env]
+ * @param {string}   [o.history]     session log (default `$AEGIS_HOME/history.jsonl`)
+ * @param {string}   [o.session]     session id (default: the last one in the log)
+ * @param {number}   [o.turns]       only the last N turns
+ * @param {string}   [o.label]
+ * @param {string}   [o.account]
+ * @param {string}   [o.model]
+ * @param {string[]} [o.tools]
+ * @param {object[]} [o.code]        output of `collectCode`
+ * @param {boolean?} [o.codeDirty]
+ * @param {string}   [o.createdAt]   pin the record's timestamp
+
+ * `createdAt` is a pass-through to the engine's `mint`, which otherwise stamps
+ * the record with the current time. That default is right for a session being
+ * sealed now and wrong for the one thing this module is used for besides that:
+ * two hosts attesting the *same* session must produce the *same* record, and
+ * they cannot if each stampes its own millisecond. It is also what lets a
+ * record be re-sealed at the time it originally described. It is deliberately
+ * not exposed as a CLI flag — a hand-set timestamp on an ordinary mint would
+ * let a caller backdate evidence, which is exactly what the record exists to
+ * prevent.
+ * @param {string|null} [o.aiSecret]     the credential the session ran on. Passed
+ *                                       in, resolved from `--ai-secret`/
+ *                                       `$AEGIS_AI_SECRET`, or explicitly null.
+ * @param {string}   [o.aiModel]          the model that answered.
+ * @param {object[]} [o.aiObservations]   the replies' observations; derived from
+ *                                       the turns when omitted.
+ * @returns {{record: object, keySource: string, public: boolean, samples: number,
+ *            observations: number, aiKeySource: string, aiSamples: number,
+ *            skippedLines: number}}
+ */
+function mintSession(o = {}) {
+  const key = o.key || authorship.resolveKey(o);
+  if (!key.secret) {
+    throw new Error(
+      'attest: no authorship key — run `aegiscode fingerprint keygen`, set ' +
+        `${authorship.SECRET_ENV}, or pass --secret <file>`,
+    );
+  }
+
+  const history = o.history || DEFAULT_HISTORY();
+  const { entries, skipped } = readHistory(history);
+  const session = o.session || lastSessionId(entries);
+  const turns = selectTurns(entries, { session, turns: o.turns });
+  const observations = observationsFromTurns(turns);
+
+  const code = o.code || [];
+
+  // The AI axis. `aiSecret` may be passed in (a host that already resolved it),
+  // left undefined (then the two rungs above are walked), or explicitly null (a
+  // host saying "no credential — mint the axis as unobserved").
+  const aiKey = o.aiSecret === undefined ? resolveAiSecret(o) : { secret: o.aiSecret, source: o.aiSecret ? 'caller' : 'none' };
+  const aiObservations = o.aiObservations || aiObservationsFromTurns(turns);
+  const aiModel = o.aiModel !== undefined && o.aiModel !== null
+    ? o.aiModel
+    : aiObservations.map((a) => a.model).filter(Boolean).pop() || '';
+
+  const record = fp.mint({
+    secret: key.secret,
+    label: o.label,
+    account: o.account,
+    model: o.model,
+    tools: o.tools,
+    observations,
+    code,
+    codeDirty: o.codeDirty === undefined ? null : o.codeDirty,
+    aiSecret: aiKey.secret,
+    aiModel,
+    aiObservations,
+    createdAt: o.createdAt || undefined,
+  });
+
+  return {
+    record,
+    keySource: key.source,
+    public: key.public,
+    samples: record.behaviourSamples,
+    observations: observations.length,
+    aiKeySource: aiKey.source,
+    aiSamples: record.aiSamples,
+    skippedLines: skipped,
+  };
+}
+
+module.exports = {
+  DEFAULT_HISTORY,
+  DIR_KEYS,
+  DEMAND_KEYS,
+  OUTCOME_KEYS,
+  SESSION_KEYS,
+  REPLY_KEYS,
+  MODEL_KEYS,
+  AI_SECRET_ENV,
+  TIME_KEYS,
+  SKIP_DIRS,
+  MAX_FILE_BYTES,
+  MAX_FILES,
+  firstKey,
+  readHistory,
+  lastSessionId,
+  selectTurns,
+  observationsFromTurns,
+  aiObservationsFromTurns,
+  resolveAiSecret,
+  collectCode,
+  mintSession,
+};