@kylecheng3146/agent-ops 0.1.4 → 0.1.6

package/dist/runtime/src/install/plan.js

@@ -1,13 +1,16 @@
 import { lstat, readFile } from "node:fs/promises";
-import { SCHEMA_VERSION } from "../contracts.js";
+import { CONFIG_SCHEMA_VERSION, MANIFEST_SCHEMA_VERSION } from "../contracts.js";
 import { sha256 } from "../fs/hash.js";
-import { applyManagedBlock, managedBlockMarkers } from "../fs/managed-block.js";
+import { applyManagedBlock, managedBlockMarkers, removeManagedBlock } from "../fs/managed-block.js";
 import { formatInstallManifest, parseInstallManifest } from "../fs/manifest.js";
 import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
 import { validateConfig } from "../schema/validate.js";
-import { planHarnessContributions, requestedHarnessIds } from "./harness.js";
-import { hookRegistrationPath, planHookRegistration } from "./hooks.js";
-import { resolveProfiles } from "./profiles.js";
+import { planHarnessContributions, harnessDescriptor, selectHarnessHookSurface } from "./harness.js";
+import { assertExpectedManagedBlock, assertSupportedManifestOwnership } from "./ownership.js";
+import { codexHooksExplicitlyDisabled, loopLauncherArtifactId, loopSeeds, planLoopContribution, selectedLoopHarnesses } from "./codex-loop.js";
+import { isOpencodeManagedPlugin } from "../adapters/opencode/config.js";
+import { planHookRegistration, planHookRemoval } from "./hooks.js";
+import { resolveCapabilities, resolveProfiles } from "./profiles.js";
 const CONFIG_PATH = ".agent-ops/config.json";
 const MANIFEST_PATH = ".agent-ops/manifest.json";
 const MAX_PLANNED_FILE_BYTES = 1024 * 1024;
@@ -39,9 +42,14 @@ async function readCurrentFile(root, path) {
 }
 function formatConfig(profiles, existing) {
     return `${JSON.stringify({
-        schemaVersion: SCHEMA_VERSION,
+        schemaVersion: CONFIG_SCHEMA_VERSION,
         profiles,
         verification: existing?.verification ?? { commands: [] },
+        features: existing?.features ?? {
+            stopVerification: {
+                enabled: false
+            }
+        },
         pathMappings: existing?.pathMappings ?? [],
         securityExceptions: existing?.securityExceptions ?? []
     }, null, 2)}\n`;
@@ -109,7 +117,7 @@ function assertUniqueContributions(artifacts, blocks) {
     }
     const markerBoundaries = new Set();
     for (const block of blocks) {
-        const markers = managedBlockMarkers(block.id, block.version);
+        const markers = managedBlockMarkers(block.id, block.version, block.markerStyle);
         const key = pathKey(block.path);
         if (ids.has(block.id) ||
             artifactPaths.has(key) ||
@@ -131,9 +139,12 @@ async function readExistingManifest(root) {
             hash: current.hash
         };
 }
-function assertCompatibleManifest(existing, scope, harness) {
+function assertCompatibleManifest(existing, scope, harness, allowHarnessChange) {
+    const harnessChanged = existing !== null &&
+        (existing.harness.length !== harness.length ||
+            !existing.harness.every((id) => harness.includes(id)));
     if (existing !== null &&
-        (existing.scope !== scope || existing.harness !== harness)) {
+        (existing.scope !== scope || (harnessChanged && !allowHarnessChange))) {
         throw new AgentOpsError("INSTALL_ALREADY_CONFIGURED", "Use update to change the scope or harness of an existing installation.");
     }
 }
@@ -144,6 +155,11 @@ function findOwnedArtifact(manifest, path) {
 async function planArtifact(root, artifact, existingManifest) {
     const current = await readCurrentFile(root, artifact.path);
     const owned = findOwnedArtifact(existingManifest, artifact.path);
+    if (artifact.id === "opencode-plugin" &&
+        current !== null &&
+        !isOpencodeManagedPlugin(current.content)) {
+        throw new AgentOpsError("MANIFEST_OWNERSHIP_INVALID", `The recorded opencode plugin is not an agent-ops managed plugin: ${artifact.path}`);
+    }
     if (current !== null && owned === undefined) {
         throw new AgentOpsError("UNMANAGED_INSTALL_PATH", `Refusing to replace an unmanaged install artifact: ${artifact.path}`);
     }
@@ -168,30 +184,128 @@ async function planArtifact(root, artifact, existingManifest) {
         }
     };
 }
-async function planBlocks(root, blocks) {
+async function planArtifactRemoval(root, artifact) {
+    const current = await readCurrentFile(root, artifact.path);
+    if (current === null || current.hash !== artifact.hash) {
+        throw new AgentOpsError("MANAGED_ARTIFACT_CHANGED", `Managed artifact changed after installation: ${artifact.path}`);
+    }
+    if (artifact.id === "opencode-plugin" &&
+        !isOpencodeManagedPlugin(current.content)) {
+        throw new AgentOpsError("MANIFEST_OWNERSHIP_INVALID", `The recorded opencode plugin is not an agent-ops managed plugin: ${artifact.path}`);
+    }
+    return {
+        kind: "remove",
+        path: artifact.path,
+        expectedHash: current.hash
+    };
+}
+async function planCreateOnceSeeds(root, seeds) {
+    const operations = [];
+    for (const seed of seeds) {
+        const current = await readCurrentFile(root, seed.path);
+        if (current === null) {
+            operations.push({
+                kind: "write",
+                path: seed.path,
+                content: seed.content,
+                expectedHash: null
+            });
+        }
+    }
+    return operations;
+}
+/**
+ * User-owned seed files belong to the first loop install for each harness.
+ * An existing loop launcher is the durable installation record: it prevents an
+ * update from recreating a file a user intentionally removed, while still
+ * allowing loop to be enabled later or for a newly added harness.
+ */
+function loopHarnessesNeedingSeeds(harnesses, existingManifest) {
+    const existingArtifactIds = new Set(existingManifest?.artifacts.map(({ id }) => id) ?? []);
+    return selectedLoopHarnesses(harnesses).filter((harness) => !existingArtifactIds.has(loopLauncherArtifactId(harness)));
+}
+function markerKey(path, id) {
+    return `${pathKey(path)}\0${id}`;
+}
+function assertLoopProfileSupport(scope, harness, capabilities) {
+    if (!capabilities.includes("project-loop")) {
+        return;
+    }
+    if (scope !== "project" ||
+        !harness.some((id) => id === "codex" || id === "claude")) {
+        throw new AgentOpsError("LOOP_PROFILE_UNSUPPORTED", "The loop profile requires project scope and the Codex or Claude harness.");
+    }
+}
+async function assertCodexLoopConfiguration(root, harness, capabilities) {
+    if (!capabilities.includes("project-loop") ||
+        !harness.includes("codex")) {
+        return;
+    }
+    const config = await readCurrentFile(root, ".codex/config.toml");
+    if (config !== null && codexHooksExplicitlyDisabled(config.content)) {
+        throw new AgentOpsError("CODEX_LOOP_HOOKS_DISABLED", "Codex loop installation requires [features] hooks = true; the existing .codex/config.toml explicitly disables hooks.");
+    }
+}
+async function planBlocks(root, blocks, removals = [], expectedMarkers = new Map()) {
     const grouped = new Map();
     for (const block of blocks) {
-        const existing = grouped.get(block.path) ?? [];
-        existing.push(block);
-        grouped.set(block.path, existing);
+        const key = pathKey(block.path);
+        const existing = grouped.get(key) ?? {
+            path: block.path,
+            blocks: [],
+            removals: []
+        };
+        existing.blocks.push(block);
+        existing.path = block.path;
+        grouped.set(key, existing);
+    }
+    for (const marker of removals) {
+        const key = pathKey(marker.path);
+        const existing = grouped.get(key) ?? {
+            path: marker.path,
+            blocks: [],
+            removals: []
+        };
+        existing.removals.push(marker);
+        grouped.set(key, existing);
     }
     const operations = [];
     const records = [];
-    for (const [path, pathBlocks] of grouped) {
+    for (const { path, blocks: pathBlocks, removals: pathRemovals } of grouped.values()) {
         const current = await readCurrentFile(root, path);
+        if (pathRemovals.length > 0 && current === null) {
+            throw new AgentOpsError("MANAGED_BLOCK_CHANGED", `Managed block file is missing: ${path}`);
+        }
         let content = current?.content ?? "";
+        for (const marker of pathRemovals) {
+            const expected = expectedMarkers.get(marker.id);
+            if (expected === undefined) {
+                throw new AgentOpsError("MANIFEST_OWNERSHIP_INVALID", "The manifest contains an unsupported managed block.");
+            }
+            assertExpectedManagedBlock(content, marker, expected);
+            content = removeManagedBlock(content, marker.id, expected.markerStyle);
+        }
         for (const block of pathBlocks) {
             content = applyManagedBlock(content, block);
         }
         const hash = sha256(content);
-        operations.push({
-            kind: "write",
-            path,
-            content,
-            expectedHash: current?.hash ?? null
-        });
+        if (content.length === 0 && current !== null) {
+            operations.push({
+                kind: "remove",
+                path,
+                expectedHash: current.hash
+            });
+        }
+        else {
+            operations.push({
+                kind: "write",
+                path,
+                content,
+                expectedHash: current?.hash ?? null
+            });
+        }
         for (const block of pathBlocks) {
-            const markers = managedBlockMarkers(block.id, block.version);
+            const markers = managedBlockMarkers(block.id, block.version, block.markerStyle);
             records.push({
                 id: block.id,
                 path,
@@ -210,18 +324,93 @@ export async function createInstallPlan(options) {
             .test(options.toolkitVersion)) {
         throw new AgentOpsError("INVALID_TOOLKIT_VERSION", "Toolkit version must be a valid semantic version.");
     }
-    const resolved = resolveProfiles(options.profiles);
-    const contribution = await planHarnessContributions(options.harness, {
+    const resolved = options.existingConfig === undefined
+        ? resolveProfiles(options.profiles)
+        : resolveCapabilities(options.existingConfig.value);
+    assertLoopProfileSupport(options.scope, options.harness, resolved.capabilities);
+    await assertCodexLoopConfiguration(options.root, options.harness, resolved.capabilities);
+    const existing = await readExistingManifest(options.root);
+    assertCompatibleManifest(existing?.manifest ?? null, options.scope, options.harness, options.allowHarnessChange === true);
+    const existingOpencodePluginPath = existing?.manifest.artifacts.find(({ id }) => id === "opencode-plugin")?.path;
+    const explicitHookTargets = new Map();
+    for (const target of options.hookTargets ?? []) {
+        if (explicitHookTargets.has(target.harness) ||
+            !options.harness.includes(target.harness)) {
+            throw new AgentOpsError("HOOK_TARGET_INVALID", `Hook target must name one selected harness exactly once: ${target.harness}.`);
+        }
+        if (harnessDescriptor(target.harness).control.buildHooks === undefined) {
+            throw new AgentOpsError("HOOK_TARGET_UNSUPPORTED", `Harness hook targets are not supported for ${target.harness}.`);
+        }
+        explicitHookTargets.set(target.harness, target.surfaceId);
+    }
+    if (options.hookRuntimePath === undefined &&
+        explicitHookTargets.size > 0) {
+        throw new AgentOpsError("HOOK_TARGET_REQUIRES_RUNTIME", "An explicit hook target requires a hook runtime path.");
+    }
+    const baseContribution = await planHarnessContributions(options.harness, {
+        root: options.root,
         scope: options.scope,
         profiles: resolved.profiles,
         capabilities: resolved.capabilities,
+        ...(options.hookRuntimePath === undefined
+            ? {}
+            : { runtimePath: options.hookRuntimePath }),
         ...(options.toolkitVersion === undefined
             ? {}
-            : { toolkitVersion: options.toolkitVersion })
+            : { toolkitVersion: options.toolkitVersion }),
+        ...(existingOpencodePluginPath === undefined
+            ? {}
+            : { opencodePluginPath: existingOpencodePluginPath })
     }, options.adapters);
+    const loopContribution = planLoopContribution({
+        scope: options.scope,
+        harnesses: options.harness,
+        capabilities: resolved.capabilities,
+        ...(options.hookRuntimePath === undefined
+            ? {}
+            : { hookRuntimePath: options.hookRuntimePath })
+    });
+    const contribution = {
+        artifacts: [
+            ...baseContribution.artifacts,
+            ...loopContribution.artifacts
+        ],
+        blocks: [...baseContribution.blocks, ...loopContribution.blocks]
+    };
     assertUniqueContributions(contribution.artifacts, contribution.blocks);
-    const existing = await readExistingManifest(options.root);
-    assertCompatibleManifest(existing?.manifest ?? null, options.scope, options.harness);
+    const reconcileExisting = existing !== null;
+    const expectedExistingMarkers = reconcileExisting
+        ? assertSupportedManifestOwnership(existing.manifest, options.root)
+        : new Map();
+    const desiredArtifactPaths = new Set([
+        pathKey(CONFIG_PATH),
+        ...contribution.artifacts.map(({ path }) => pathKey(path))
+    ]);
+    const preservedArtifacts = options.hookRuntimePath === undefined &&
+        options.allowHarnessChange === true &&
+        options.harness.includes("opencode")
+        ? (existing?.manifest.artifacts.filter(({ id }) => id === "opencode-plugin") ?? [])
+        : [];
+    for (const artifact of preservedArtifacts) {
+        const current = await readCurrentFile(options.root, artifact.path);
+        if (current === null || current.hash !== artifact.hash) {
+            throw new AgentOpsError("MANAGED_ARTIFACT_CHANGED", `Managed artifact changed after installation: ${artifact.path}`);
+        }
+        if (artifact.id === "opencode-plugin" &&
+            !isOpencodeManagedPlugin(current.content)) {
+            throw new AgentOpsError("MANIFEST_OWNERSHIP_INVALID", `The recorded opencode plugin is not an agent-ops managed plugin: ${artifact.path}`);
+        }
+    }
+    for (const artifact of preservedArtifacts) {
+        desiredArtifactPaths.add(pathKey(artifact.path));
+    }
+    const artifactsToRemove = reconcileExisting
+        ? existing.manifest.artifacts.filter(({ path }) => !desiredArtifactPaths.has(pathKey(path)))
+        : [];
+    const desiredMarkerKeys = new Set(contribution.blocks.map(({ path, id }) => markerKey(path, id)));
+    const markersToRemove = reconcileExisting
+        ? existing.manifest.markers.filter(({ path, id }) => !desiredMarkerKeys.has(markerKey(path, id)))
+        : [];
     const operations = [];
     const artifacts = [];
     const config = await planConfig(options.root, resolved.profiles, existing?.manifest ?? null, options.existingConfig);
@@ -232,15 +421,39 @@ export async function createInstallPlan(options) {
         operations.push(planned.operation);
         artifacts.push(planned.record);
     }
-    const plannedBlocks = await planBlocks(options.root, contribution.blocks);
+    if (resolved.capabilities.includes("project-loop")) {
+        const seedHarnesses = loopHarnessesNeedingSeeds(options.harness, existing?.manifest ?? null);
+        operations.push(...await planCreateOnceSeeds(options.root, loopSeeds(seedHarnesses)));
+    }
+    artifacts.push(...preservedArtifacts);
+    for (const artifact of artifactsToRemove) {
+        operations.push(await planArtifactRemoval(options.root, artifact));
+    }
+    const plannedBlocks = await planBlocks(options.root, contribution.blocks, markersToRemove, expectedExistingMarkers);
     operations.push(...plannedBlocks.operations);
     const hooks = [];
     if (options.hookRuntimePath !== undefined) {
-        for (const harness of requestedHarnessIds(options.harness)) {
-            const current = await readCurrentFile(options.root, hookRegistrationPath(harness, options.scope));
+        for (const harness of options.harness) {
+            if (harnessDescriptor(harness).control.buildHooks === undefined) {
+                continue;
+            }
+            const existingHook = existing?.manifest.hooks?.find(({ harness: recordHarness }) => recordHarness === harness);
+            const selectedSurface = selectHarnessHookSurface({
+                harness,
+                scope: options.scope,
+                root: options.root,
+                ...(explicitHookTargets.has(harness)
+                    ? { surfaceId: explicitHookTargets.get(harness) }
+                    : existingHook === undefined
+                        ? {}
+                        : { persistedPath: existingHook.path })
+            });
+            const hookPath = selectedSurface.path;
+            const current = await readCurrentFile(options.root, hookPath);
             const planned = planHookRegistration({
                 harness,
                 scope: options.scope,
+                path: hookPath,
                 capabilities: resolved.capabilities,
                 runtimePath: options.hookRuntimePath,
                 currentSource: current?.content ?? null
@@ -252,13 +465,45 @@ export async function createInstallPlan(options) {
                 kind: "write",
                 path: planned.record.path,
                 content: planned.content,
-                expectedHash: current?.hash ?? null
+                expectedHash: current?.hash ?? null,
+                disclosure: planned.disclosure
             });
             hooks.push(planned.record);
         }
     }
+    else if (existing !== null) {
+        const selectedHarnesses = new Set(options.harness);
+        hooks.push(...(existing.manifest.hooks ?? []).filter(({ harness }) => selectedHarnesses.has(harness)));
+    }
+    if (reconcileExisting) {
+        const desiredHookPaths = new Set(hooks.map(({ path }) => pathKey(path)));
+        for (const hook of existing.manifest.hooks ?? []) {
+            if (desiredHookPaths.has(pathKey(hook.path))) {
+                continue;
+            }
+            const current = await readCurrentFile(options.root, hook.path);
+            if (current === null) {
+                continue;
+            }
+            const removal = planHookRemoval(hook, current.content);
+            operations.push(removal.content === null
+                ? {
+                    kind: "remove",
+                    path: hook.path,
+                    expectedHash: current.hash,
+                    disclosure: removal.disclosure
+                }
+                : {
+                    kind: "write",
+                    path: hook.path,
+                    content: removal.content,
+                    expectedHash: current.hash,
+                    disclosure: removal.disclosure
+                });
+        }
+    }
     const manifest = {
-        schemaVersion: SCHEMA_VERSION,
+        schemaVersion: MANIFEST_SCHEMA_VERSION,
         scope: options.scope,
         harness: options.harness,
         artifacts,

package/dist/runtime/src/install/probes.js

@@ -1,52 +1,18 @@
-import { buildClaudeHookSettings } from "../adapters/claude/config.js";
-import { buildCodexHookConfig } from "../adapters/codex/config.js";
-import { resolveProfiles } from "./profiles.js";
-const CLAUDE_HOOK_MARKER = "--managed-by=agent-ops";
-const CODEX_COMMAND_PREFIX = "agent-ops hook codex ";
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function hasManagedHandler(source, events, isManaged) {
-    if (!isRecord(source) || !isRecord(source.hooks)) {
-        return false;
-    }
-    const registered = source.hooks;
-    return events.every((event) => {
-        const groups = registered[event];
-        return (Array.isArray(groups) &&
-            groups.some((group) => isRecord(group) &&
-                Array.isArray(group.hooks) &&
-                group.hooks.some(isManaged)));
-    });
-}
-function isManagedClaudeHandler(handler) {
-    return (isRecord(handler) &&
-        Array.isArray(handler.args) &&
-        handler.args.includes(CLAUDE_HOOK_MARKER));
-}
-function isManagedCodexHandler(handler) {
-    return (isRecord(handler) &&
-        typeof handler.command === "string" &&
-        handler.command.startsWith(CODEX_COMMAND_PREFIX));
-}
+import { harnessDescriptor } from "./harness.js";
+import { resolveCapabilities } from "./profiles.js";
 /**
  * Hook registration is satisfied when every hook event implied by the
  * installed profiles carries an agent-ops owned handler for every installed
  * harness. Installations without hook capabilities have nothing to register.
  */
 export function hookRegistrationSatisfied(input) {
-    const { capabilities } = resolveProfiles(input.profiles);
-    const claudeEvents = Object.keys(buildClaudeHookSettings(capabilities, "probe").hooks);
-    const codexEvents = Object.keys(buildCodexHookConfig(capabilities).hooks);
-    if (claudeEvents.length === 0 && codexEvents.length === 0) {
-        return true;
-    }
-    if (input.harness !== "codex" &&
-        !hasManagedHandler(input.claudeSettings, claudeEvents, isManagedClaudeHandler)) {
-        return false;
-    }
-    return (input.harness === "claude" ||
-        hasManagedHandler(input.codexHooks, codexEvents, isManagedCodexHandler));
+    const capabilities = input.config.profiles.length === 0
+        ? []
+        : resolveCapabilities(input.config).capabilities;
+    return input.harness.every((id) => {
+        const descriptor = harnessDescriptor(id);
+        return descriptor.control.hookRegistered(input.sources[id], capabilities);
+    });
 }
 /**
  * Smoke availability stays UNKNOWN until the repository declares a

package/dist/runtime/src/install/profiles.js

@@ -1,16 +1,18 @@
 import { AgentOpsError } from "../fs/paths.js";
-const PROFILE_ORDER = ["core", "advisory", "guardrails"];
+const PROFILE_ORDER = ["core", "advisory", "guardrails", "loop"];
 export const PROFILE_CAPABILITIES = {
     core: ["rules", "task", "verify", "review"],
     advisory: ["lifecycle-summary", "local-log"],
-    guardrails: ["command-policy", "optional-stop-verify"]
+    guardrails: ["command-policy"],
+    loop: ["project-loop"]
 };
 export function resolveProfiles(inputProfiles) {
     if (inputProfiles.length === 0) {
         throw new AgentOpsError("PROFILE_REQUIRED", "At least one installation profile is required.");
     }
     const selectedProfiles = new Set(inputProfiles);
-    if (selectedProfiles.has("guardrails")) {
+    if (selectedProfiles.has("guardrails") ||
+        selectedProfiles.has("loop")) {
         selectedProfiles.add("core");
     }
     const profiles = PROFILE_ORDER.filter((profile) => selectedProfiles.has(profile));
@@ -26,3 +28,10 @@ export function resolveProfiles(inputProfiles) {
     }
     return { profiles: [...profiles], capabilities };
 }
+export function resolveCapabilities(config) {
+    const resolved = resolveProfiles(config.profiles);
+    if (config.features.stopVerification.enabled) {
+        resolved.capabilities.push("optional-stop-verify");
+    }
+    return resolved;
+}