create-agent-rig 0.8.0 → 0.9.0

package/packages/cli/dist/lib/subsystems.js

@@ -0,0 +1,269 @@
+// The machine-scoped subsystem manifest (ADR-RP-002 R6, RP-147): installation
+// metadata, not a service registry. One writer (`setup`; `upgrade` re-runs the
+// same derivation), one scope (the user's configuration root), one entry per
+// subsystem carrying the resolved executable invocation and the contract major
+// it must answer. No search path, no fallback chain, no PATH scan: the
+// executable is derived from the one root the owner declared, and every
+// substantive call performs the `--version --json` handshake first.
+//
+// Handshake results carry no path — a status is machine JSON a consumer may
+// print, and the manifest itself is the only place a location is written.
+import { statSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+export const SUBSYSTEMS_SCHEMA_VERSION = 1;
+export const MEMORY_CONTRACT_MAJOR = 1;
+const MEMORY_EXECUTABLE_REL = ['shared-memory', 'memory.mjs'];
+const HANDSHAKE_TIMEOUT_MS = 15_000;
+export class SubsystemsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SubsystemsError';
+        this.code = code;
+    }
+}
+/**
+ * Exactly one location per platform. An unset root is refused, not guessed:
+ * a manifest written under a guessed home is a manifest nothing else reads.
+ */
+export function subsystemsManifestPath(env, platform) {
+    if (platform === 'win32') {
+        const root = env.APPDATA;
+        if (!root)
+            throw new SubsystemsError('config-root-unavailable', 'APPDATA is not set');
+        return path.join(root, 'create-agent-rig', 'subsystems.json');
+    }
+    const home = env.HOME;
+    if (!home)
+        throw new SubsystemsError('config-root-unavailable', 'HOME is not set');
+    return path.join(home, '.config', 'create-agent-rig', 'subsystems.json');
+}
+/** The path module of the DECLARED platform, so an entry's encoding is pinned by the platform argument, not by the host. */
+const pathFor = (platform) => (platform === 'win32' ? path.win32 : path.posix);
+export function memoryExecutablePath(memoryRoot, platform) {
+    return pathFor(platform).join(memoryRoot, ...MEMORY_EXECUTABLE_REL);
+}
+/**
+ * The pure half of the derivation: root → invocation, in the declared
+ * platform's encoding. The root is the single declared input
+ * (`setup --memory-root`), so it must be absolute under that platform — a
+ * relative root would make the entry mean a different executable from every
+ * working directory. No filesystem here, so both encodings are pinned by tests
+ * on any host.
+ */
+export function memoryInvocation(input, platform) {
+    if (!pathFor(platform).isAbsolute(input.memoryRoot))
+        throw new SubsystemsError('memory-root-relative', 'the Memory root must be an absolute path');
+    return [input.nodeExecutable, memoryExecutablePath(input.memoryRoot, platform)];
+}
+function isFile(file) {
+    try {
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The whole derivation: the invocation above, plus the check that the
+ * executable is already there on this host — the manifest records what
+ * exists, it does not promise what an install will bring. So `platform` is
+ * the host's here; the pure half is what a foreign platform's encoding is
+ * tested through.
+ */
+export function deriveMemoryEntry(input, platform) {
+    const invocation = memoryInvocation(input, platform);
+    if (!isFile(invocation[1]))
+        throw new SubsystemsError('memory-executable-absent', `no ${MEMORY_EXECUTABLE_REL.join('/')} under the declared Memory root`);
+    return {
+        memoryRoot: input.memoryRoot,
+        invocation,
+        contractMajor: MEMORY_CONTRACT_MAJOR,
+        memoryRef: input.memoryRef,
+        installedVersion: input.installedVersion,
+    };
+}
+const majorOf = (contractVersion) => {
+    const match = /^(\d+)\.\d+$/.exec(contractVersion);
+    return match ? Number(match[1]) : null;
+};
+/**
+ * `--version --json` and its classification. The consumer compares the
+ * contract major alone; a foreign major is the consumer's refusal (exit 4 in
+ * `setup`), never something Memory emits. A failure payload is
+ * INTEGRATION-FAILED, never absence: the executable answered.
+ */
+export async function handshake(entry, run, options = {}) {
+    const [file, script] = entry.invocation;
+    // Absence is the runner's answer (ENOENT), not a pre-check: the executable
+    // the manifest names is exactly what this call must exercise.
+    const result = await run(file, [script, '--version', '--json'], {
+        timeoutMs: options.timeoutMs ?? HANDSHAKE_TIMEOUT_MS,
+    });
+    if (result.spawnError) {
+        if (result.spawnError.code === 'ENOENT')
+            return { status: 'unsupported', reason: 'absent' };
+        return { status: 'integration-failed', reason: 'invalid-payload' };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(result.stdout);
+    }
+    catch {
+        return { status: 'integration-failed', reason: 'invalid-payload' };
+    }
+    if (typeof payload !== 'object' || payload === null)
+        return { status: 'integration-failed', reason: 'invalid-payload' };
+    const record = payload;
+    // The executable answered, and answered a failure — a broken VERSION file is
+    // the Memory-side shape (RP-19). The manifest's promise about what is
+    // installed no longer holds, so this is `manifest-stale`, never absence.
+    if (result.code !== 0 || record.result === 'integration-failed')
+        return { status: 'integration-failed', reason: 'manifest-stale' };
+    const { name, version, contractVersion } = record;
+    if (typeof version !== 'string' || typeof contractVersion !== 'string')
+        return { status: 'integration-failed', reason: 'invalid-payload' };
+    if (name !== 'memory')
+        return { status: 'integration-failed', reason: 'manifest-stale' };
+    const major = majorOf(contractVersion);
+    if (major === null)
+        return { status: 'integration-failed', reason: 'manifest-stale' };
+    if (major !== MEMORY_CONTRACT_MAJOR)
+        return { status: 'foreign-major', contractVersion, requiredMajor: MEMORY_CONTRACT_MAJOR };
+    return { status: 'ok', version, contractVersion };
+}
+/** Stable bytes: fixed key order, two-space indent, trailing newline. */
+export function serializeSubsystemsManifest(manifest) {
+    const memory = manifest.entries.memory;
+    const ordered = {
+        schemaVersion: SUBSYSTEMS_SCHEMA_VERSION,
+        entries: {
+            memory: {
+                memoryRoot: memory.memoryRoot,
+                invocation: [memory.invocation[0], memory.invocation[1]],
+                contractMajor: MEMORY_CONTRACT_MAJOR,
+                memoryRef: memory.memoryRef,
+                installedVersion: memory.installedVersion,
+            },
+        },
+    };
+    return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+const isString = (value) => typeof value === 'string';
+export function parseSubsystemsManifest(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const root = parsed;
+    if (root.schemaVersion !== SUBSYSTEMS_SCHEMA_VERSION)
+        return null;
+    const entries = root.entries;
+    if (typeof entries !== 'object' || entries === null)
+        return null;
+    const memory = entries.memory;
+    if (typeof memory !== 'object' || memory === null)
+        return null;
+    const m = memory;
+    const invocation = m.invocation;
+    if (!isString(m.memoryRoot) ||
+        !Array.isArray(invocation) ||
+        invocation.length !== 2 ||
+        !invocation.every(isString) ||
+        m.contractMajor !== MEMORY_CONTRACT_MAJOR ||
+        !(m.memoryRef === null || isString(m.memoryRef)) ||
+        !isString(m.installedVersion))
+        return null;
+    return {
+        schemaVersion: SUBSYSTEMS_SCHEMA_VERSION,
+        entries: {
+            memory: {
+                memoryRoot: m.memoryRoot,
+                // `every(isString)` above proved both elements are strings, but
+                // Array.prototype.every does not narrow a tuple's element type.
+                invocation: [invocation[0], invocation[1]],
+                contractMajor: MEMORY_CONTRACT_MAJOR,
+                // Checked above as `null` or a string; the `||` chain does not narrow `m.memoryRef`.
+                memoryRef: m.memoryRef,
+                installedVersion: m.installedVersion,
+            },
+        },
+    };
+}
+/** `null` when absent — no evidence; a present file that does not parse is an error, not silence. */
+export async function readSubsystemsManifest(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new SubsystemsError('manifest-unreadable', `cannot read ${path.basename(file)}`);
+    }
+    const manifest = parseSubsystemsManifest(text);
+    if (manifest === null)
+        throw new SubsystemsError('manifest-unreadable', `${path.basename(file)} is not a schemaVersion ${SUBSYSTEMS_SCHEMA_VERSION} subsystem manifest`);
+    return manifest;
+}
+/**
+ * Atomic and idempotent: the bytes land in a sibling temp file and are renamed
+ * over the target, so a reader never sees a torn manifest and a re-run of the
+ * same derivation produces no diff of its own.
+ */
+export async function writeSubsystemsManifest(file, manifest) {
+    const dir = path.dirname(file);
+    await mkdir(dir, { recursive: true });
+    const temp = path.join(dir, `.${path.basename(file)}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`);
+    try {
+        await writeFile(temp, serializeSubsystemsManifest(manifest));
+        await rename(temp, file);
+    }
+    catch (error) {
+        // See packages/cli/test/subsystems.test.ts › "removes its temp file and
+        // rethrows when the rename is refused".
+        await rm(temp, { force: true });
+        throw error;
+    }
+}
+/**
+ * What `upgrade` re-runs: the same derivation from the recorded root, the same
+ * handshake, and a rewrite only when the handshake is ok. A manifest that is
+ * absent is left absent (`setup` is the one writer that creates it); one whose
+ * executable no longer answers is left untouched and the result says why.
+ */
+export async function refreshSubsystems(options) {
+    const manifest = await readSubsystemsManifest(options.file);
+    if (manifest === null)
+        return 'absent';
+    const previous = manifest.entries.memory;
+    let entry;
+    try {
+        entry = deriveMemoryEntry({
+            memoryRoot: previous.memoryRoot,
+            nodeExecutable: options.nodeExecutable,
+            memoryRef: previous.memoryRef,
+            installedVersion: previous.installedVersion,
+        }, options.platform);
+    }
+    catch (error) {
+        if (error instanceof SubsystemsError && error.code === 'memory-executable-absent')
+            return { status: 'unsupported', reason: 'absent' };
+        throw error;
+    }
+    const result = await handshake(entry, options.run);
+    if (result.status !== 'ok')
+        return result;
+    await writeSubsystemsManifest(options.file, {
+        schemaVersion: SUBSYSTEMS_SCHEMA_VERSION,
+        entries: { memory: { ...entry, installedVersion: result.version } },
+    });
+    return 'refreshed';
+}

package/packages/cli/dist/lib/version.js

@@ -13,3 +13,18 @@ export async function packageVersion() {
     const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
     return pkg.version;
 }
+/**
+ * The version of the command contract (`docs/command-contract.md`) this rig
+ * implements. Independent of the package version: many releases ship against
+ * one contract, and a consumer compares this field's major alone.
+ */
+export const RIG_CONTRACT_VERSION = '1.0';
+/** What `--version --json` answers — the handshake object of the contract. */
+export async function rigHandshake() {
+    return {
+        schemaVersion: 1,
+        name: 'create-agent-rig',
+        version: await packageVersion(),
+        contractVersion: RIG_CONTRACT_VERSION,
+    };
+}

package/packages/cli/dist/policy/benchmark/corpus.js

@@ -0,0 +1,165 @@
+import { CAPABILITY_STATES } from '../core/vocabulary.js';
+export const BENCHMARK_CLASSIFICATIONS = Object.freeze([
+    'equivalent',
+    'intentional-degradation',
+    'unsupported',
+]);
+const MEASUREMENT_KINDS = Object.freeze([
+    'capability-probe',
+    'guard-enforcement',
+    'compatibility-rejection',
+]);
+const REQUIRED_SCENARIO_IDS = [
+    'real-wiring',
+    'unwired-enforcement',
+    'disabled-enforcement',
+    'narrowed-enforcement',
+    'bypassed-enforcement',
+    'unreadable-input',
+    'hook-input',
+    'protected-rulebook',
+    'widening',
+    'foreign-major',
+];
+const requiredScenarioIds = new Set(REQUIRED_SCENARIO_IDS);
+const scenario = (id, fixture, mutation, action, measurementKind, expectedStates) => Object.freeze({
+    id,
+    fixture,
+    mutation,
+    action,
+    measurementKind,
+    expectedStates: Object.freeze([...expectedStates]),
+});
+export const BENCHMARK_CORPUS = Object.freeze({
+    contractMajor: 1,
+    scenarios: Object.freeze([
+        scenario('real-wiring', 'universal-rig', 'none', 'exercise protected write', 'capability-probe', ['SUPPORTED']),
+        scenario('unwired-enforcement', 'universal-rig', 'remove hook registration', 'exercise protected write', 'capability-probe', ['UNSUPPORTED']),
+        scenario('disabled-enforcement', 'universal-rig', 'disable all hooks', 'exercise protected write', 'capability-probe', ['UNSUPPORTED']),
+        scenario('narrowed-enforcement', 'universal-rig', 'narrow matcher', 'exercise omitted protected write', 'capability-probe', ['DEGRADED']),
+        scenario('bypassed-enforcement', 'universal-rig', 'bypass guard command', 'exercise protected write', 'capability-probe', ['INTEGRATION-FAILED']),
+        scenario('unreadable-input', 'universal-rig', 'make snapshot unreadable', 'exercise protected write', 'capability-probe', ['INTEGRATION-FAILED']),
+        scenario('hook-input', 'universal-rig', 'make tool_input unreadable', 'exercise protected write', 'guard-enforcement', ['SUPPORTED']),
+        scenario('protected-rulebook', 'universal-rig', 'none', 'edit protected rulebook', 'guard-enforcement', ['SUPPORTED']),
+        scenario('widening', 'universal-rig', 'widen authorization allow-list', 'attempt unauthorized widening', 'guard-enforcement', ['SUPPORTED']),
+        scenario('foreign-major', 'contracts/session-messaging/v1/fixtures/negative/envelope-foreign-major.json', 'foreign schema major', 'check policy compatibility', 'compatibility-rejection', ['UNSUPPORTED']),
+    ]),
+});
+const canonicalScenarios = new Map(BENCHMARK_CORPUS.scenarios.map((entry) => [entry.id, entry]));
+export const classifyCapability = (state) => {
+    switch (state) {
+        case 'SUPPORTED':
+            return { classification: 'equivalent', integrationFailed: false };
+        case 'DEGRADED':
+            return { classification: 'intentional-degradation', integrationFailed: false };
+        case 'UNSUPPORTED':
+            return { classification: 'unsupported', integrationFailed: false };
+        case 'INTEGRATION-FAILED':
+            return { classification: 'unsupported', integrationFailed: true };
+        default:
+            throw new Error(`Unknown capability state: ${String(state)}`);
+    }
+};
+const isOwnDataRecord = (value) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return false;
+    return Object.values(Object.getOwnPropertyDescriptors(value)).every((descriptor) => descriptor.enumerable === true && 'value' in descriptor);
+};
+const isDataArray = (value) => {
+    if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype)
+        return false;
+    for (let index = 0; index < value.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor === undefined || descriptor.enumerable !== true || !('value' in descriptor))
+            return false;
+    }
+    return true;
+};
+const hasOnlyKeys = (value, keys) => {
+    const actual = Object.keys(value);
+    return actual.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+};
+const nonBlank = (value) => typeof value === 'string' && value.trim() !== '';
+const invalidCorpus = (reason) => {
+    throw new Error(`Invalid benchmark corpus: ${reason}`);
+};
+export const parseBenchmarkCorpus = (input) => {
+    if (!isOwnDataRecord(input) || !hasOnlyKeys(input, ['contractMajor', 'scenarios'])) {
+        return invalidCorpus('must be a plain corpus with contractMajor and scenarios');
+    }
+    if (input.contractMajor !== 1)
+        return invalidCorpus('unsupported contract major; expected 1');
+    if (!isDataArray(input.scenarios))
+        return invalidCorpus('scenarios must be a data array');
+    if (input.scenarios.length !== REQUIRED_SCENARIO_IDS.length) {
+        return invalidCorpus('must include every required scenario exactly once');
+    }
+    const ids = new Set();
+    const scenarios = [];
+    for (const value of input.scenarios) {
+        if (!isOwnDataRecord(value) ||
+            !hasOnlyKeys(value, [
+                'id',
+                'fixture',
+                'mutation',
+                'action',
+                'measurementKind',
+                'expectedStates',
+            ])) {
+            return invalidCorpus('each scenario must have only id, fixture, mutation, action, measurementKind, and expectedStates');
+        }
+        const { id, fixture, mutation, action, measurementKind, expectedStates } = value;
+        if (!nonBlank(id) || !requiredScenarioIds.has(id))
+            return invalidCorpus(`unknown scenario ${String(id)}`);
+        if (ids.has(id))
+            return invalidCorpus(`scenario ${id} is duplicated`);
+        if (!nonBlank(fixture) || !nonBlank(mutation) || !nonBlank(action)) {
+            return invalidCorpus(`scenario ${id} has empty metadata`);
+        }
+        if (typeof measurementKind !== 'string' ||
+            !MEASUREMENT_KINDS.includes(measurementKind)) {
+            return invalidCorpus(`scenario ${id} has an unknown measurement kind`);
+        }
+        if (!isDataArray(expectedStates) || expectedStates.length === 0) {
+            return invalidCorpus(`scenario ${id} must name expected capability states`);
+        }
+        const states = new Set();
+        for (const expectedState of expectedStates) {
+            if (typeof expectedState !== 'string' ||
+                !CAPABILITY_STATES.includes(expectedState)) {
+                return invalidCorpus(`scenario ${id} has an unknown capability state`);
+            }
+            if (states.has(expectedState))
+                return invalidCorpus(`scenario ${id} repeats a capability state`);
+            states.add(expectedState);
+        }
+        const canonical = canonicalScenarios.get(id);
+        if (fixture !== canonical.fixture ||
+            mutation !== canonical.mutation ||
+            action !== canonical.action ||
+            measurementKind !== canonical.measurementKind) {
+            return invalidCorpus(`scenario ${id} changes its canonical metadata`);
+        }
+        if (expectedStates.length !== canonical.expectedStates.length ||
+            expectedStates.some((state, index) => state !== canonical.expectedStates[index])) {
+            return invalidCorpus(`scenario ${id} changes its expected capability states`);
+        }
+        ids.add(id);
+        scenarios.push(Object.freeze({
+            id,
+            fixture,
+            mutation,
+            action,
+            measurementKind: measurementKind,
+            expectedStates: Object.freeze([...states]),
+        }));
+    }
+    for (const id of REQUIRED_SCENARIO_IDS) {
+        if (!ids.has(id))
+            return invalidCorpus(`required scenario ${id} is missing`);
+    }
+    return Object.freeze({ contractMajor: 1, scenarios: Object.freeze(scenarios) });
+};