agentic-workflow-manager 3.1.0 → 3.2.1

package/dist/src/core/install-transaction.js

@@ -0,0 +1,405 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyInstallPlan = applyInstallPlan;
+exports.defaultTransactionDeps = defaultTransactionDeps;
+exports.beginBackupSession = beginBackupSession;
+exports.restoreBackup = restoreBackup;
+exports.listBackups = listBackups;
+// src/core/install-transaction.ts
+//
+// Transactional filesystem apply for InstallPlan (install-planner.ts):
+// validates every target, backs up every existing target BEFORE any
+// replacement happens (R24.1), replaces targets, verifies, and — on any
+// failure — rolls back every target already replaced, in reverse order
+// (R25). Never removes a live target before its staged replacement exists
+// (R17, enforced by executor.ts's stageArtifact/replaceArtifact split).
+//
+// Also exports a general-purpose `beginBackupSession`, for callers outside
+// the planner (e.g. preferences/provider-config mutations during `init`)
+// that want the same backup/restore guarantees without going through a full
+// InstallPlan. `applyInstallPlan` and `beginBackupSession` write independent
+// backup directories under ~/.awm/backups/<transactionId>/, each with a
+// manifest.json (mode 0600) inside a 0700 directory — paths and existence
+// flags only, never file contents or environment variables.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const artifact_state_1 = require("./artifact-state");
+const paths_1 = require("./paths");
+const atomic_file_1 = require("./atomic-file");
+const codex_agent_1 = require("./renderers/codex-agent");
+const executor_1 = require("./executor");
+/**
+ * The single timestamp-sanitization rule for transaction IDs, shared by
+ * `applyInstallPlan` and `beginBackupSession` so both always produce IDs
+ * `restoreBackup`'s validation regex (`^\d{4}-\d{2}-\d{2}T[0-9A-Za-z.-]+$`)
+ * accepts. Strips both `:` and `.` (an ISO timestamp has both) so the result
+ * is filesystem- and regex-safe either way.
+ */
+function sanitizeTransactionTimestamp() {
+    return new Date().toISOString().replace(/[:.]/g, '-');
+}
+function ensureBackupDir(backupDir) {
+    fs_1.default.mkdirSync(backupDir, { recursive: true });
+    fs_1.default.chmodSync(backupDir, 0o700);
+}
+function writeBackupManifest(backupDir, manifest) {
+    ensureBackupDir(backupDir);
+    (0, atomic_file_1.writeFileAtomic)(path_1.default.join(backupDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 0o600);
+}
+function readBackupManifest(manifestPath) {
+    if (!fs_1.default.existsSync(manifestPath)) {
+        throw new Error(`backup manifest not found: ${manifestPath}`);
+    }
+    let value;
+    try {
+        value = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf8'));
+    }
+    catch {
+        throw new Error(`${manifestPath} is not valid JSON`);
+    }
+    const manifest = value;
+    if (!manifest || typeof manifest.id !== 'string' || !Array.isArray(manifest.entries)) {
+        throw new Error(`${manifestPath} is not a valid backup manifest`);
+    }
+    return manifest;
+}
+function targetExists(targetPath) {
+    try {
+        fs_1.default.lstatSync(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * sha256 of the target's content, for the manifest's integrity record.
+ * Files hash their bytes directly; directories and symlinks hash a stable
+ * summary (entry name + kind + size + mtime, or the symlink's own target)
+ * rather than walking and hashing every file individually — enough to detect
+ * "the backup no longer matches what's on disk" without the cost of a full
+ * recursive content hash.
+ */
+function computeContentHash(targetPath) {
+    const hash = crypto_1.default.createHash('sha256');
+    const stat = fs_1.default.lstatSync(targetPath);
+    if (stat.isSymbolicLink()) {
+        hash.update('symlink:').update(fs_1.default.readlinkSync(targetPath));
+    }
+    else if (stat.isDirectory()) {
+        hash.update('dir:');
+        for (const name of fs_1.default.readdirSync(targetPath).sort()) {
+            const entryStat = fs_1.default.lstatSync(path_1.default.join(targetPath, name));
+            const kind = entryStat.isDirectory() ? 'd' : entryStat.isSymbolicLink() ? 'l' : 'f';
+            hash.update(`${name}:${kind}:${entryStat.size}:${entryStat.mtimeMs}\n`);
+        }
+    }
+    else {
+        hash.update(fs_1.default.readFileSync(targetPath));
+    }
+    return hash.digest('hex');
+}
+/** Copies `targetPath` (if it exists) into `backupDir/relName` and returns the manifest entry. */
+function backupEntryFor(targetPath, backupDir, relName) {
+    if (!targetExists(targetPath)) {
+        return { targetPath, existed: false, backupRelPath: null };
+    }
+    ensureBackupDir(backupDir);
+    // dereference:false (fs.cpSync default) — a symlinked target is backed up
+    // as a symlink, not by copying whatever it points at.
+    fs_1.default.cpSync(targetPath, path_1.default.join(backupDir, relName), { recursive: true });
+    return { targetPath, existed: true, backupRelPath: relName, contentHash: computeContentHash(targetPath) };
+}
+/** Restores `targetPath` from its backup, or removes it if it didn't exist before. */
+function restoreTargetFrom(targetPath, backupPath) {
+    fs_1.default.rmSync(targetPath, { recursive: true, force: true });
+    if (backupPath !== null) {
+        fs_1.default.mkdirSync(path_1.default.dirname(targetPath), { recursive: true });
+        fs_1.default.cpSync(backupPath, targetPath, { recursive: true });
+    }
+}
+function restoreManifestEntry(backupDir, entry) {
+    // Only ever operates on targetPath/backupRelPath literally enumerated in
+    // the validated manifest — never on a path derived from user input.
+    const backupPath = entry.existed && entry.backupRelPath ? path_1.default.join(backupDir, entry.backupRelPath) : null;
+    restoreTargetFrom(entry.targetPath, backupPath);
+}
+// ---------------------------------------------------------------------------
+// applyInstallPlan
+// ---------------------------------------------------------------------------
+/**
+ * Real transactional apply for an InstallPlan. Order (per target, across the
+ * whole plan):
+ *   1. validate every op                         (no writes)
+ *   2. backup every op's existing target          (before ANY replace — R24.1)
+ *   3. stage every op's replacement                (source untouched, target untouched — R17)
+ *   4. replace every op's target with its staged replacement
+ *   5. verify every op
+ *   6. persist artifact-state records — merged into the existing ledger
+ *      (upsert by targetPath, see mergeArtifactRecords), not a wholesale
+ *      overwrite, so earlier applyInstallPlan calls' records survive
+ * Any failure from step 4 onward rolls back every already-replaced target, in
+ * reverse order, using the backups captured in step 2 (R25). Rollback is
+ * best-effort: a rollback failure for one target does not stop the others
+ * from being attempted, and never masks the original failure.
+ */
+function applyInstallPlan(plan, deps = defaultTransactionDeps()) {
+    for (const op of plan.operations)
+        deps.validate(op);
+    const backupDir = path_1.default.join((0, paths_1.awmHome)(), 'backups', sanitizeTransactionTimestamp());
+    const transactionId = path_1.default.basename(backupDir);
+    const backups = new Map();
+    for (const op of plan.operations)
+        backups.set(op, deps.backup(op, backupDir));
+    const staged = new Map();
+    try {
+        for (const op of plan.operations)
+            staged.set(op, deps.stage(op));
+    }
+    catch (error) {
+        // Best-effort: clean up any temp files earlier iterations already
+        // staged before this one threw — none of them have been swapped in
+        // yet (replace() hasn't run), so there's nothing to roll back, just
+        // orphaned staging artifacts to remove.
+        for (const stagedPath of staged.values()) {
+            try {
+                fs_1.default.rmSync(stagedPath, { recursive: true, force: true });
+            }
+            catch {
+                // best-effort: retain the original failure
+            }
+        }
+        throw error;
+    }
+    const replaced = [];
+    try {
+        for (const op of plan.operations) {
+            deps.replace(op, staged.get(op));
+            replaced.push(op);
+        }
+        for (const op of plan.operations)
+            deps.verify(op);
+        // Upsert this plan's records into the EXISTING persisted ledger,
+        // keyed by targetPath — a real `awm init` run makes several separate
+        // applyInstallPlan calls (one per bundle), and each one only knows
+        // about the artifacts IT touched. Writing plan.records wholesale
+        // would silently discard every earlier call's ownership records
+        // (BLOCKER found in post-implementation QA); merging preserves them.
+        (0, artifact_state_1.writeArtifactState)((0, artifact_state_1.mergeArtifactRecords)((0, artifact_state_1.readArtifactState)(), plan.records));
+    }
+    catch (error) {
+        for (const op of [...replaced].reverse()) {
+            try {
+                deps.rollback(op, backups.get(op) ?? null);
+            }
+            catch {
+                // best-effort: retain the original failure; the backup path remains available for manual recovery
+            }
+        }
+        throw error;
+    }
+    return {
+        // Every owner in plan.reports — 'install' (the owner whose selection
+        // caused the physical write) AND 'retain' (co-owners of the same
+        // shared target, e.g. OpenCode+Codex sharing one skill directory) —
+        // gained ownership of this target as a result of THIS run. The
+        // user-facing summary must list all of them, not just the first
+        // (R15/R15.1): a single physical write can still mean N providers now
+        // own the artifact.
+        installed: plan.reports
+            .map((report) => `${path_1.default.basename(report.targetPath)} → ${report.owner}`),
+        skipped: [],
+        transactionId,
+        modifiedFiles: plan.operations.map((op) => op.targetPath),
+    };
+}
+function stageRenderedFile(content, targetPath) {
+    const parent = path_1.default.dirname(targetPath);
+    fs_1.default.mkdirSync(parent, { recursive: true });
+    const staged = path_1.default.join(parent, `.${path_1.default.basename(targetPath)}.${process.pid}.staged`);
+    fs_1.default.rmSync(staged, { recursive: true, force: true });
+    fs_1.default.writeFileSync(staged, content, 'utf8');
+    return staged;
+}
+/**
+ * The real, filesystem-touching TransactionDeps used by applyInstallPlan by
+ * default. Renders `codex-agent-toml` targets from the canonical agent
+ * Markdown source at stage time; every other renderer uses the plain
+ * symlink/copy staging from executor.ts. Never logs target contents or
+ * environment variables.
+ */
+function defaultTransactionDeps() {
+    let index = 0;
+    let createdAt = null;
+    const manifestEntries = [];
+    return {
+        validate(op) {
+            if (!fs_1.default.existsSync(op.sourcePath)) {
+                throw new Error(`Source path does not exist: ${op.sourcePath}`);
+            }
+            if (op.renderer === 'codex-agent-toml') {
+                // Renders without writing anything, purely to surface parse errors
+                // before any backup/replace happens.
+                (0, codex_agent_1.renderCodexAgent)(fs_1.default.readFileSync(op.sourcePath, 'utf8'));
+            }
+        },
+        backup(op, backupDir) {
+            if (createdAt === null)
+                createdAt = new Date().toISOString();
+            const entry = backupEntryFor(op.targetPath, backupDir, String(index));
+            index += 1;
+            manifestEntries.push(entry);
+            writeBackupManifest(backupDir, {
+                id: path_1.default.basename(backupDir),
+                createdAt,
+                committed: false,
+                entries: manifestEntries,
+            });
+            return entry.existed ? path_1.default.join(backupDir, entry.backupRelPath) : null;
+        },
+        stage(op) {
+            if (op.renderer === 'codex-agent-toml') {
+                const rendered = (0, codex_agent_1.renderCodexAgent)(fs_1.default.readFileSync(op.sourcePath, 'utf8'));
+                return stageRenderedFile(rendered, op.targetPath);
+            }
+            return (0, executor_1.stageArtifact)(op.sourcePath, op.targetPath, op.method);
+        },
+        replace(op, staged) {
+            (0, executor_1.replaceArtifact)(staged, op.targetPath);
+        },
+        verify(op) {
+            let stat;
+            try {
+                stat = fs_1.default.lstatSync(op.targetPath);
+            }
+            catch {
+                throw new Error(`verification failed: ${op.targetPath} is missing after install`);
+            }
+            if (op.renderer === 'codex-agent-toml') {
+                if (!stat.isFile()) {
+                    throw new Error(`verification failed: ${op.targetPath} is not a regular file`);
+                }
+                const content = fs_1.default.readFileSync(op.targetPath, 'utf8');
+                if (!content.startsWith('name = ')) {
+                    throw new Error(`verification failed: ${op.targetPath} does not look like rendered TOML`);
+                }
+                return;
+            }
+            if (op.method === 'symlink' && !stat.isSymbolicLink()) {
+                throw new Error(`verification failed: ${op.targetPath} is not a symlink`);
+            }
+            if (op.method === 'copy' && stat.isSymbolicLink()) {
+                throw new Error(`verification failed: ${op.targetPath} is unexpectedly a symlink`);
+            }
+        },
+        rollback(op, backup) {
+            restoreTargetFrom(op.targetPath, backup);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// beginBackupSession — general-purpose backup wrapper for mutations outside
+// the planner (preferences, provider configs, etc.)
+// ---------------------------------------------------------------------------
+function createBackupManifest(targets, backupDir) {
+    const entries = targets.map((target, i) => backupEntryFor(target, backupDir, String(i)));
+    return {
+        id: path_1.default.basename(backupDir),
+        createdAt: new Date().toISOString(),
+        committed: false,
+        entries,
+    };
+}
+function markBackupCommitted(backupDir) {
+    const manifest = readBackupManifest(path_1.default.join(backupDir, 'manifest.json'));
+    writeBackupManifest(backupDir, { ...manifest, committed: true });
+}
+/**
+ * Backs up every (currently existing) path in `targetPaths` before the
+ * caller mutates them. `commit()` marks the backup as no-longer-needed
+ * (kept for manual recovery, never auto-deleted); `rollback()` restores
+ * every target to its pre-session state (or removes it, if it did not exist
+ * before the session began).
+ */
+function beginBackupSession(targetPaths) {
+    const unique = Array.from(new Set(targetPaths.map((target) => path_1.default.resolve(target))));
+    if (unique.some((target) => target === path_1.default.parse(target).root)) {
+        throw new Error('refusing to back up a filesystem root');
+    }
+    const transactionId = sanitizeTransactionTimestamp();
+    const backupDir = path_1.default.join((0, paths_1.awmHome)(), 'backups', transactionId);
+    const manifest = createBackupManifest(unique, backupDir);
+    writeBackupManifest(backupDir, manifest);
+    return {
+        transactionId,
+        targetPaths: unique,
+        commit: () => markBackupCommitted(backupDir),
+        rollback: () => {
+            restoreBackup(transactionId);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// restoreBackup — explicit, ID-scoped restore (also used by `awm backup restore`)
+// ---------------------------------------------------------------------------
+/**
+ * Restores every target recorded in the given transaction's manifest.
+ * `transactionId` is untrusted input (it reaches here from CLI args) — it is
+ * validated against a strict format AND the resolved backup directory is
+ * checked to stay inside ~/.awm/backups before any read, to rule out path
+ * traversal. Only targets literally enumerated in the manifest are touched.
+ */
+function restoreBackup(transactionId) {
+    if (!/^\d{4}-\d{2}-\d{2}T[0-9A-Za-z.-]+$/.test(transactionId)) {
+        throw new Error('invalid backup transaction id');
+    }
+    const root = path_1.default.join((0, paths_1.awmHome)(), 'backups');
+    const dir = path_1.default.join(root, transactionId);
+    if (!dir.startsWith(`${root}${path_1.default.sep}`)) {
+        throw new Error('backup path escapes AWM backup root');
+    }
+    const manifest = readBackupManifest(path_1.default.join(dir, 'manifest.json'));
+    const restored = [];
+    for (const entry of manifest.entries) {
+        restoreManifestEntry(dir, entry);
+        restored.push(entry.targetPath);
+    }
+    return { restored };
+}
+/** Lists every recorded backup transaction under ~/.awm/backups, newest first. Corrupt manifests are skipped. */
+function listBackups() {
+    const root = path_1.default.join((0, paths_1.awmHome)(), 'backups');
+    if (!fs_1.default.existsSync(root))
+        return [];
+    const ids = fs_1.default.readdirSync(root).filter((name) => {
+        try {
+            return fs_1.default.statSync(path_1.default.join(root, name)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+    const summaries = [];
+    for (const id of ids) {
+        const manifestPath = path_1.default.join(root, id, 'manifest.json');
+        if (!fs_1.default.existsSync(manifestPath))
+            continue;
+        try {
+            const manifest = readBackupManifest(manifestPath);
+            summaries.push({
+                id: manifest.id,
+                createdAt: manifest.createdAt,
+                committed: manifest.committed,
+                targets: manifest.entries.map((entry) => entry.targetPath),
+            });
+        }
+        catch {
+            // corrupt manifest — skip rather than fail the whole listing
+        }
+    }
+    return summaries.sort((a, b) => b.id.localeCompare(a.id));
+}

package/dist/src/core/profile.js

@@ -120,7 +120,7 @@ function ensureSkillsGitignored(root, agents) {
     const existingLines = existing.split(/\r?\n/).map((l) => l.trim());
     const toIgnore = [];
     for (const agent of agents) {
-        const provider = providers_1.PROVIDERS[agent];
+        const provider = (0, providers_1.providerFor)(agent);
         for (const type of ['skill', 'workflow', 'agent']) {
             const config = provider[type];
             if (!config)

package/dist/src/core/provider-artifacts.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preflightLinkArtifactPairs = preflightLinkArtifactPairs;
+exports.scanLegacyArtifacts = scanLegacyArtifacts;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const providers_1 = require("../providers");
+const ARTIFACT_TYPES = ['skill', 'workflow', 'agent'];
+function preflightLinkArtifactPairs(pairs) {
+    for (const { agent, artifact } of pairs) {
+        (0, providers_1.assertLinkRenderer)(artifact.type, agent);
+    }
+}
+function scanLegacyArtifacts(agents, scope) {
+    const artifacts = new Map();
+    for (const agent of agents) {
+        for (const type of ARTIFACT_TYPES) {
+            let config;
+            try {
+                config = (0, providers_1.assertLinkRenderer)(type, agent);
+            }
+            catch (error) {
+                if (error instanceof providers_1.UnsupportedRendererError)
+                    continue;
+                throw error;
+            }
+            if (!config)
+                continue;
+            const dir = config[scope];
+            if (!fs_1.default.existsSync(dir))
+                continue;
+            for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+                const fullPath = path_1.default.join(dir, entry.name);
+                const existing = artifacts.get(entry.name);
+                if (existing) {
+                    existing.installedIn.push(agent);
+                    existing.fullPaths.push(fullPath);
+                }
+                else {
+                    artifacts.set(entry.name, {
+                        name: entry.name,
+                        type,
+                        installedIn: [agent],
+                        fullPaths: [fullPath],
+                    });
+                }
+            }
+        }
+    }
+    return Array.from(artifacts.values());
+}

package/dist/src/core/provider-version.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertProviderSupported = assertProviderSupported;
+const child_process_1 = require("child_process");
+const providers_1 = require("../providers");
+const versioning_1 = require("./versioning");
+function assertProviderSupported(agent, exec = child_process_1.execFileSync) {
+    const provider = (0, providers_1.providerFor)(agent);
+    if (!provider.versionCommand || !provider.minimumVersion) {
+        return { provider: agent, version: null };
+    }
+    let output;
+    try {
+        output = exec(provider.versionCommand.command, provider.versionCommand.args, {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 5000,
+        }).toString();
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT') {
+            throw new Error('Codex is not installed or not available on PATH. ' +
+                'Install the current stable @openai/codex release, then re-run.');
+        }
+        throw new Error(`Codex version probe failed: ${error.message}`);
+    }
+    const match = output.trim().match(/^codex-cli (\d+\.\d+\.\d+)$/);
+    if (!match) {
+        throw new Error(`could not parse Codex version from: ${output.trim()}`);
+    }
+    if ((0, versioning_1.compareSemver)(match[1], provider.minimumVersion) < 0) {
+        throw new Error(`requires Codex >= ${provider.minimumVersion}; found ${match[1]}`);
+    }
+    return { provider: agent, version: match[1] };
+}

package/dist/src/core/reconciliation.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planReconciliation = planReconciliation;
+const bundles_1 = require("./bundles");
+const install_planner_1 = require("./install-planner");
+const bundle_install_1 = require("./bundle-install");
+const config_1 = require("../utils/config");
+function intentKey(intent) {
+    return `${intent.type}\0${intent.installName}\0${intent.sourcePath}`;
+}
+/**
+ * Computes the InstallPlan that reconciles every machine-scope (baseline +
+ * ambient) artifact for `targets` against the currently synced registries at
+ * `roots`. Pure — no filesystem writes; callers apply the result with
+ * `applyInstallPlan` (install-transaction.ts).
+ */
+function planReconciliation(params) {
+    const { targets, roots } = params;
+    const bundles = params.bundles ?? (0, bundles_1.discoverAllBundles)(roots);
+    const contentDir = roots[0] ?? '';
+    const machineBundles = bundles.filter((b) => b.scope === 'baseline' || b.scope === 'ambient');
+    const seen = new Set();
+    const artifacts = [];
+    for (const b of machineBundles) {
+        let intents;
+        try {
+            intents = (0, bundle_install_1.expandBundleArtifacts)({
+                bundleName: b.name,
+                bundles,
+                agents: targets,
+                method: 'symlink',
+                projectRoot: '',
+                contentDir,
+            });
+        }
+        catch {
+            // A plain dangling `dependsOn` name doesn't reach here — resolveBundleClosure
+            // (bundles.ts) silently drops it before this point. This only fires on a
+            // genuinely malformed bundle definition (e.g. `dependsOn` not an array), which
+            // throws while walking the closure. Skip that one bundle rather than aborting
+            // reconciliation for every other bundle (see tests/core/reconciliation.test.ts).
+            continue;
+        }
+        for (const intent of intents) {
+            const key = intentKey(intent);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            artifacts.push(intent);
+        }
+    }
+    const enabledAgents = params.enabledAgents ?? (0, config_1.getPreferences)().enabledAgents;
+    return (0, install_planner_1.planInstall)({
+        artifacts,
+        selectedAgents: targets,
+        enabledAgents,
+        scope: 'global',
+        projectRoot: '',
+        method: 'symlink',
+    });
+}

package/dist/src/core/registries.js

@@ -16,6 +16,7 @@ exports.syncRegistries = syncRegistries;
 exports.readRegistryManifest = readRegistryManifest;
 exports.registryNameForPath = registryNameForPath;
 exports.verifyMinCliVersions = verifyMinCliVersions;
+exports.assertRegistryGates = assertRegistryGates;
 // src/core/registries.ts
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -203,3 +204,12 @@ function verifyMinCliVersions(current = (0, cli_version_1.cliVersion)()) {
     }
     return failures;
 }
+/** Throwing form of `verifyMinCliVersions`'s failure list — lets callers treat the
+ *  min-CLI-version gate uniformly with other gates (version-gate, backup session, …)
+ *  in a single try/catch rather than a bespoke console.warn loop. */
+function assertRegistryGates(failures) {
+    if (failures.length === 0)
+        return;
+    const detail = failures.map((f) => `${f.name} requires CLI >= ${f.min}`).join('; ');
+    throw new Error(`Registry version gate failed: ${detail}. Run: npm i -g agentic-workflow-manager`);
+}

package/dist/src/core/renderers/canonical-agent.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCanonicalAgent = parseCanonicalAgent;
+function parseCanonicalAgent(source) {
+    const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+    if (!match)
+        throw new Error('canonical agent requires YAML frontmatter');
+    const fields = new Map();
+    for (const line of match[1].split(/\r?\n/)) {
+        const field = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+        if (!field)
+            throw new Error(`invalid canonical agent frontmatter line: ${line}`);
+        if (fields.has(field[1]))
+            throw new Error(`duplicate canonical agent frontmatter key: ${field[1]}`);
+        fields.set(field[1], field[2].replace(/^(['"])(.*)\1$/, '$2').trim());
+    }
+    const name = fields.get('name') ?? '';
+    const description = fields.get('description') ?? '';
+    const instructions = match[2].trim();
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
+        throw new Error('invalid agent name');
+    if (!description)
+        throw new Error('canonical agent requires a non-empty description');
+    if (!instructions)
+        throw new Error('canonical agent requires a non-empty instruction body');
+    return { name, description, instructions };
+}

package/dist/src/core/renderers/codex-agent.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderCodexAgent = renderCodexAgent;
+const canonical_agent_1 = require("./canonical-agent");
+// TOML requires control characters other than tab (U+0009) and newline
+// (U+000A) to be escaped in both basic and multi-line basic strings,
+// including U+007F (DEL) and the rest of the C0 range (U+0000-U+0008,
+// U+000B-U+001F). JSON.stringify (used for single-line strings) already
+// escapes U+0000-U+001F, but not U+007F. A plain backslash/quote replace
+// (used for multi-line strings) escapes neither. escapeControlChars covers
+// both: for tomlString it only ever finds a literal U+007F left over from
+// JSON.stringify (the rest were already turned into escape sequences by
+// JSON.stringify, so they are no longer literal control characters); for
+// tomlMultiline it finds every raw control character in the value.
+//
+// The character class below is built from numeric code points rather than
+// written as literal escape sequences in source, to avoid ambiguity between
+// "the two characters backslash and u" and "the control character itself".
+const CONTROL_CHAR_RANGES = [
+    [0x00, 0x08],
+    [0x0b, 0x1f],
+    [0x7f, 0x7f],
+];
+function buildControlCharsRegex() {
+    const classBody = CONTROL_CHAR_RANGES.map(([start, end]) => {
+        const from = String.fromCharCode(start);
+        const to = String.fromCharCode(end);
+        return start === end ? from : `${from}-${to}`;
+    }).join('');
+    return new RegExp(`[${classBody}]`, 'g');
+}
+const CONTROL_CHARS = buildControlCharsRegex();
+function escapeControlChars(value) {
+    return value.replace(CONTROL_CHARS, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+function tomlString(value) {
+    // JSON.stringify escapes backslashes, double quotes, and control characters
+    // U+0000-U+001F, but TOML also requires U+007F (DEL) to be escaped.
+    return escapeControlChars(JSON.stringify(value));
+}
+function tomlMultiline(value) {
+    // Escape every backslash and every double quote individually (not just
+    // triple-quote runs) so no run of 3+ unescaped quotes can ever appear in
+    // the output, regardless of how many consecutive quotes are embedded.
+    // Order matters: backslashes first (so escaping a control character does
+    // not introduce a backslash that gets doubled), then control characters,
+    // then quotes. Tab and newline are left raw; they're legitimately
+    // allowed unescaped in a TOML multi-line basic string.
+    const escaped = escapeControlChars(value.replace(/\\/g, '\\\\')).replace(/"/g, '\\"');
+    return `"""\n${escaped}\n"""`;
+}
+function renderCodexAgent(source) {
+    const agent = (0, canonical_agent_1.parseCanonicalAgent)(source);
+    return [
+        `name = ${tomlString(agent.name)}`,
+        `description = ${tomlString(agent.description)}`,
+        `developer_instructions = ${tomlMultiline(agent.instructions)}`,
+        '',
+    ].join('\n');
+}