Files
stack/packages/organization/src/agent-levels-write.mjs

304 lines
19 KiB
JavaScript

// #1873 Phase A slice A2: the root agent file's writer (design
// docs/plans/2026-11-10_agent-levels-design.md sections 6, 7 and 9 item 1).
//
// One instance-wide file, <configDir>/agents.json. Only the signed-in owner writes it: the caller
// passes the actor and the owner principal its own trusted context established (the CLI's local
// owner, the Console's owner session), and anything else refuses `human-required`. The write
// follows M2's locked store (accounts.mjs): a lock file, a re-read and revision check under it, the
// whole new document checked with A1's checkRootAgents, a 0600 temp file, a re-check, then rename
// (or link for a new file), a directory sync and one receipt line. Nothing here launches an agent.
//
// No refusal and no receipt carries a value from the file or the request: a var value can be a
// secret typed into the wrong place. Messages name the file (agents.json) and the key, never a
// host path.
import { constants } from 'node:fs';
import * as fs from 'node:fs/promises';
import { createHash, randomBytes } from 'node:crypto';
import { join } from 'node:path';
import { OrgError } from './org-registry.mjs';
import { assertTrustedConfigDir } from './config-dir-trust.mjs';
import { ROOT_FILE, checkProjectAgents, checkRootAgents, loadRootAgents, projectUnion, rootAgentsPath } from './agent-levels.mjs';
import { checkDefinition } from "./definitions.mjs";
import { canonicalJson, isPlainObject } from './util.mjs';
import { ID_PATTERN } from './vocabulary.mjs';
import { REGISTRY } from './vars.mjs';
export const ROOT_LOCK = 'agents.lock';
export const ROOT_RECEIPTS = 'agents-receipts.jsonl';
const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
// The revision of a root file that does not exist yet: the digest of no bytes.
export const ABSENT_REVISION = sha256('');
const REVISION = /^[a-f0-9]{64}$/;
const PRINCIPAL = ['provider', 'iss', 'sub'];
const fail = (code, message = code) => { throw new OrgError(code, message); };
// The only actor that writes: the owner principal the caller's trusted context names. The tester
// identity never counts as the owner, whatever a context says.
export function requireRootOwner(actor, owner) {
const ok = p => isPlainObject(p) && PRINCIPAL.every(k => typeof p[k] === 'string' && p[k] !== '');
if (!ok(actor) || !ok(owner) || PRINCIPAL.some(k => actor[k] !== owner[k]) || actor.sub === 'tester' || actor.provider === 'tester')
fail('human-required', 'only the signed-in owner writes the root agent file');
}
// The shared config directory check (config-dir-trust.mjs): every ancestor root's or this uid's and
// not writable by others without the sticky bit, configDir this uid's and not group or other writable.
const assertConfigDir = (configDir, uid) => assertTrustedConfigDir(configDir, { uid, code: 'agents-unsafe' });
// The reader's descriptor checks (loadRootAgents), plus one link: a regular file, no symbolic link,
// this uid, no group or other write. Missing is an empty root level at ABSENT_REVISION.
async function readCurrent(configDir, uid, statFile = fd => fd.stat()) {
const file = rootAgentsPath(configDir);
let fd;
try { fd = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
catch (error) {
if (error.code === 'ENOENT') return { exists: false, revision: ABSENT_REVISION, document: { agentsVersion: 1, agents: {} } };
fail('agents-unsafe', `root agent file must be a regular file, not a symbolic link (${ROOT_FILE})`);
}
let bytes;
try {
const st = await statFile(fd);
if (!st.isFile()) fail('agents-unsafe', `root agent file must be a regular file, not a symbolic link (${ROOT_FILE})`);
if (st.uid !== uid) fail('agents-unsafe', `root agent file must belong to uid ${uid} (${ROOT_FILE})`);
if (st.mode & 0o022) fail('agents-unsafe', `root agent file must not be writable by group or other (${ROOT_FILE})`);
if (st.nlink !== 1) fail('agents-unsafe', `root agent file must have exactly one link (${ROOT_FILE})`);
bytes = await fd.readFile();
} finally { await fd.close(); }
let document;
// The parser's text can quote the file's bytes: say only that it is not JSON.
try { document = JSON.parse(bytes.toString('utf8')); } catch { fail('agents-invalid', `root agent file is not valid JSON (${ROOT_FILE})`); }
return { exists: true, revision: sha256(bytes), document };
}
// The file's document and revision, for a form or a CLI list. A file that is not a root agent
// document at all refuses; one with a bad entry reads, so the owner can fix or remove that entry.
// statFile is a test seam for the descriptor stat; it grants nothing a caller's uid does not.
export async function readRootAgentsFile(configDir, { uid = process.geteuid(), statFile } = {}) {
assertConfigDir(configDir, uid);
const current = await readCurrent(configDir, uid, statFile);
shape(current.document);
return current;
}
function shape(document) {
if (!isPlainObject(document) || document.agentsVersion !== 1 || !isPlainObject(document.agents))
fail('agents-invalid', `root agent file must be {"agentsVersion": 1, "agents": {...}} (${ROOT_FILE})`);
}
// Every string a request put in an entry, as a message could quote it bare or as JSON.
// What a refusal must not show. Field names, var names, role ids and org ids may appear; every
// var value, every unknown key and any other string that isn't an id is caller text.
const FIELDS = new Set(['definition', 'vars', 'excludeOrgs', 'exclude', 'credentials', 'holder', 'tracker', 'identity', 'publish', 'hosts']);
function all(value, out) {
if (typeof value === 'string') { if (value.length >= 3) out.push(value, JSON.stringify(value)); }
else if (Array.isArray(value)) value.forEach(v => all(v, out));
else if (isPlainObject(value)) for (const [key, v] of Object.entries(value)) { all(key, out); all(v, out); }
return out;
}
const unlessId = (value, out) => (typeof value === 'string' && ID_PATTERN.test(value) ? out : all(value, out));
function strings(entry, out = []) {
if (!isPlainObject(entry)) return all(entry, out);
for (const [key, value] of Object.entries(entry)) {
if (!FIELDS.has(key)) all(key, out);
if (key === 'definition') unlessId(value, out);
else if (key === 'excludeOrgs' && Array.isArray(value)) value.forEach(v => unlessId(v, out));
else if (key === 'exclude' && typeof value === 'boolean') continue;
else if (key === 'vars' && isPlainObject(value)) for (const [name, v] of Object.entries(value)) { if (!Object.hasOwn(REGISTRY, name)) all(name, out); all(v, out); }
else all(value, out);
}
return out;
}
// A refusal's message with its key path and without any value: an id check's "(got ...)" is cut,
// and a message that still holds a string from the entry is replaced by one naming the key only.
export function withoutValues(message, entry, prefix) {
const cut = String(message).replace(/ \(got [\s\S]*\)$/, '');
if (!strings(entry).some(text => cut.includes(text))) return cut;
const at = new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\.[^\\s:]+)*`).exec(cut)?.[0] ?? prefix;
return `${at}: refused (the value is not shown)`;
}
// A1's checks on the whole new document.
function validate(document, rolesDir, entry) {
try { return checkRootAgents(document, { rolesDir }); }
catch (error) {
if (error?.name !== 'BusinessError') throw error;
fail('agents-invalid', withoutValues(error.message, entry, 'root agents'));
}
}
// What changed in one entry, by key name only.
function changedKeys(before, after) {
if (!before && !after) return [];
if (!before) return ['added'];
if (!after) return ['removed'];
const out = [];
if (before.definition !== after.definition) out.push('definition');
const bv = isPlainObject(before.vars) ? before.vars : {}, av = isPlainObject(after.vars) ? after.vars : {};
for (const key of [...new Set([...Object.keys(bv), ...Object.keys(av)])].sort()) {
if (canonicalJson(bv[key]) !== canonicalJson(av[key])) out.push(`vars.${key}`);
}
if (canonicalJson(before.excludeOrgs ?? []) !== canonicalJson(after.excludeOrgs ?? [])) out.push('excludeOrgs');
return out;
}
// One entry changed by a patch: `definition` replaces, `vars` sets each key it names (null removes
// that key), `excludeOrgs` replaces the list ([] clears it). Keys the patch leaves out are kept.
export function patchRootEntry(old, { definition, vars, excludeOrgs } = {}) {
const next = old ? structuredClone(old) : {};
if (definition !== undefined) next.definition = definition;
if (vars !== undefined) {
if (!isPlainObject(vars)) fail('agents-invalid', 'vars must be an object of keys');
const merged = isPlainObject(next.vars) ? { ...next.vars } : {};
for (const [key, value] of Object.entries(vars)) { if (value === null) delete merged[key]; else merged[key] = value; }
if (Object.keys(merged).length) next.vars = merged; else delete next.vars;
}
if (excludeOrgs !== undefined) { if (Array.isArray(excludeOrgs) && excludeOrgs.length === 0) delete next.excludeOrgs; else next.excludeOrgs = excludeOrgs; }
return next;
}
async function syncDirectory(dir) {
const fd = await fs.open(dir, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
try { await fd.sync(); } finally { await fd.close(); }
}
// Change one root agent. `entry` is the new entry, null to remove it, or a function of the old
// entry (undefined when there is none) returning either. Returns the receipt. An error after the
// rename carries committed: true, so a caller never retries a write that landed.
export async function changeRootAgent(configDir, { revision, name, entry }, { actor, owner, rolesDir, uid = process.geteuid(), beforeReplace, statFile, syncDirectory: syncDir = syncDirectory, approvedDefinition = null, decision = null, assertClean = null } = {}) {
requireRootOwner(actor, owner);
if (typeof name !== 'string' || !ID_PATTERN.test(name)) fail('agents-invalid', 'agent name must be an id: lowercase letters, digits, dot, dash or underscore, at most 64');
if (typeof revision !== 'string' || !REVISION.test(revision)) fail('revision-conflict', 'a root agent change needs the revision it was read at');
assertConfigDir(configDir, uid);
const lock = join(configDir, ROOT_LOCK);
let lockFd;
for (let n = 0; n < 200; n++) {
try { lockFd = await fs.open(lock, 'wx', 0o600); break; }
catch (error) { if (error.code !== 'EEXIST') throw error; await new Promise(r => setTimeout(r, 10)); }
}
if (!lockFd) fail('agents-locked', 'the root agent file is locked by another write; inspect agents.lock before retrying');
const file = rootAgentsPath(configDir);
let temp, receiptFd, committed = false;
try {
assertConfigDir(configDir, uid);
const before = await readCurrent(configDir, uid, statFile);
if (before.revision !== revision) fail('revision-conflict', 'the root agent file changed since it was read; read it again');
shape(before.document);
const old = Object.hasOwn(before.document.agents, name) ? before.document.agents[name] : undefined;
const value = typeof entry === 'function' ? entry(old === undefined ? undefined : structuredClone(old)) : entry;
if (value === null && old === undefined) fail('agent-not-found', `root agents.${name} does not exist`);
if (value !== null && !isPlainObject(value)) fail('agents-invalid', `root agents.${name} must be an object`);
const next = structuredClone(before.document);
if (value === null) {delete next.agents[name];if(decision)next.retired=[...(next.retired??[]),name];} else next.agents[name] = value;
if (approvedDefinition) {
const {name:def,entry}=approvedDefinition;
if(typeof assertClean!=="function")fail("definition-secret-check-required");
checkDefinition(def,entry,{assertClean});
next.definitions={...(next.definitions??{}),[def]:entry};
}
const changed = changedKeys(old, value ?? undefined);
if(approvedDefinition && canonicalJson(before.document.definitions?.[approvedDefinition.name])!==canonicalJson(approvedDefinition.entry))changed.push("definition.rev");
if (changed.length === 0) fail('no-change', `root agents.${name} is already that`);
validate(next, rolesDir, value);
const bytes = JSON.stringify(next, null, 2) + '\n';
// Check what lands on disk, not only the object built: JSON can drop or reshape a value.
validate(JSON.parse(bytes), rolesDir, value);
const after = sha256(bytes);
const line = {
at: new Date().toISOString(), uid: process.geteuid(), actor: 'owner',
verb: value === null ? 'root.agent.remove' : 'root.agent.set', agent: name, ...(decision ? {decision} : {}),
...(value === null ? {} : { definition: value.definition }),
revisionBefore: before.revision, revisionAfter: after, changed,
};
// Refuse an unsafe receipt destination before publishing the change.
receiptFd = await fs.open(join(configDir, ROOT_RECEIPTS), constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
const st = await receiptFd.stat();
if (!st.isFile() || st.uid !== uid || (st.mode & 0o022) || st.nlink !== 1) fail('agents-unsafe', `unsafe root agent receipt file (${ROOT_RECEIPTS})`);
temp = join(configDir, `.agents-${randomBytes(12).toString('hex')}`);
const fd = await fs.open(temp, 'wx', 0o600);
try { await fd.writeFile(bytes); await fd.sync(); } finally { await fd.close(); }
await beforeReplace?.();
// A writer that ignores the lock still loses: the bytes must be the ones read.
const again = await readCurrent(configDir, uid, statFile);
if (again.exists !== before.exists || again.revision !== before.revision) fail('revision-conflict', 'the root agent file changed before the write; read it again');
// A new file is published with link, which fails rather than replace a file made meanwhile.
if (before.exists) await fs.rename(temp, file);
else await fs.link(temp, file);
committed = true;
if (!before.exists) await fs.unlink(temp);
await syncDir(configDir);
await receiptFd.writeFile(JSON.stringify(line) + '\n'); await receiptFd.sync();
return line;
} catch (error) { if (committed && error instanceof Error) error.committed = true; throw error; }
finally {
if (temp) await fs.rm(temp, { force: true });
if (receiptFd) await receiptFd.close();
await lockFd.close(); await fs.unlink(lock);
}
}
// The entries as a form or a list shows them: names, definition, the model, the other var keys and
// the opted-out organizations. No var value other than the model.
export function rootAgentSummary(document) {
return Object.entries(isPlainObject(document?.agents) ? document.agents : {}).map(([name, entry]) => {
const vars = isPlainObject(entry?.vars) ? entry.vars : {};
return {
name, definition: typeof entry?.definition === 'string' ? entry.definition : null,
model: typeof vars.model === 'string' ? vars.model : null,
varKeys: Object.keys(vars).filter(k => k !== 'model').sort(),
excludeOrgs: Array.isArray(entry?.excludeOrgs) ? entry.excludeOrgs.filter(x => typeof x === 'string') : [],
};
}).sort((a, b) => a.name.localeCompare(b.name));
}
// One row per entry: its form and what it names, never a var value.
export function projectAgentSummary(agents) {
if (!isPlainObject(agents)) return [];
return Object.keys(agents).sort().map(name => {
const entry = isPlainObject(agents[name]) ? agents[name] : {};
if (entry.exclude === true) return { name, form: 'exclude' };
if (entry.definition !== undefined) return { name, form: 'define', definition: typeof entry.definition === 'string' ? entry.definition : null, varKeys: Object.keys(isPlainObject(entry.vars) ? entry.vars : {}).sort() };
return { name, form: 'narrow', varKeys: Object.keys(isPlainObject(entry.vars) ? entry.vars : {}).sort() };
});
}
// The project-agent verb's guard (design section 7, the projects fence's one exception for agents):
// `next` may differ from `old` only in projects.<project>.agents.<name>, the project must exist and
// not be a library, and the project's entries and its union must pass A1's checks. Returns
// [code, message] or null. `root` is the root level as loadRootAgents reads it.
export function projectAgentProblem(old, next, { orgId, project, name, entry, rolesDir, root, definitions = old.definitions }) {
const target = old?.projects?.[project];
if (!isPlainObject(target)) return ['project-not-found', `projects.${project} does not exist`];
if (target.kind === 'library') return ['project-agents-library', `projects.${project} is a library project; it takes no agents`];
const without = doc => {
const copy = structuredClone(doc);
const p = copy?.projects?.[project];
if (isPlainObject(p) && isPlainObject(p.agents)) {
delete p.agents[name];
if (Object.keys(p.agents).length === 0) delete p.agents;
}
return canonicalJson(copy);
};
if (without(old) !== without(next)) return ['organization-projects-protected', `only projects.${project}.agents.${name} may change`];
const after = next.projects[project].agents?.[name];
if (canonicalJson(after ?? null) !== canonicalJson(entry ?? null)) return ['organization-projects-protected', `projects.${project}.agents.${name} is not the entry asked for`];
if (canonicalJson(after ?? null) === canonicalJson(target.agents?.[name] ?? null)) return ['no-change', `projects.${project}.agents.${name} is already that`];
const where = `projects.${project}.agents`;
let entries;
try { entries = checkProjectAgents(next.projects[project].agents ?? {}, { rolesDir, where, definitions }); }
catch (error) { if (error?.name !== 'BusinessError') throw error; return ['project-agents-invalid', withoutValues(error.message, entry, where)]; }
const org = Object.fromEntries(Object.entries(old.roles ?? {}).map(([n, r]) => [n, { definition: r?.definition, vars: r?.vars ?? {} }]));
try { projectUnion({ orgId, root, org, project: entries, projectId: project }); }
catch (error) { if (error?.name !== 'BusinessError') throw error; return ['project-agents-invalid', withoutValues(error.message, entry, where)]; }
return null;
}
// The root level a project union is checked against. A root file that refuses refuses the project
// write too: an exclusion or narrowing checked against a root level that did not parse could be wrong.
export function rootForProjectCheck(configDir, rolesDir) {
try { return loadRootAgents(configDir, { rolesDir }); }
catch (error) { if (error?.name !== 'BusinessError') throw error; fail('project-agents-invalid', 'the root agent file refuses; fix it before changing project agents'); }
}
// A project entry's form, for the change log and the receipt.
export const entryForm = entry => entry === null ? 'remove' : Object.hasOwn(entry, 'exclude') ? 'exclude' : Object.hasOwn(entry, 'definition') ? 'define' : 'narrow';