@kylecheng3146/agent-ops 0.0.1

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

@@ -0,0 +1,196 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { sha256 } from "../fs/hash.js";
+import { parseInstallManifest, PROJECT_MANIFEST_PATH } from "../fs/manifest.js";
+import { resolveContainedPath } from "../fs/paths.js";
+import { validateConfig } from "../schema/validate.js";
+import { assertExpectedManagedBlock, assertSupportedManifestOwnership } from "./ownership.js";
+const CONFIG_PATH = ".agent-ops/config.json";
+const MINIMUM_NODE_VERSION = [22, 14, 0];
+const MAX_DOCTOR_FILE_BYTES = 1024 * 1024;
+function check(id, status, message) {
+    return { id, status, message };
+}
+function parseNodeVersion(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version);
+    if (match === null) {
+        return null;
+    }
+    const parsed = [Number(match[1]), Number(match[2]), Number(match[3])];
+    return parsed.every(Number.isSafeInteger) ? parsed : null;
+}
+function meetsMinimumNodeVersion(version) {
+    for (let index = 0; index < MINIMUM_NODE_VERSION.length; index += 1) {
+        const actual = version[index];
+        const minimum = MINIMUM_NODE_VERSION[index];
+        if (actual !== minimum) {
+            return actual > minimum;
+        }
+    }
+    return true;
+}
+function checkNodeVersion(version) {
+    const parsed = parseNodeVersion(version);
+    if (parsed === null || !meetsMinimumNodeVersion(parsed)) {
+        return check("node-version", "FAIL", `Node ${version} does not meet the minimum version 22.14.0.`);
+    }
+    return check("node-version", "PASS", `Node ${version} meets the minimum version 22.14.0.`);
+}
+async function readContained(root, path) {
+    const resolvedPath = await resolveContainedPath(root, path);
+    const before = await lstat(resolvedPath, { bigint: true });
+    if (!before.isFile() ||
+        before.size > BigInt(MAX_DOCTOR_FILE_BYTES)) {
+        throw new Error("Doctor targets must be bounded regular files.");
+    }
+    const handle = await open(resolvedPath, constants.O_RDONLY |
+        constants.O_NOFOLLOW |
+        constants.O_NONBLOCK);
+    try {
+        const opened = await handle.stat({ bigint: true });
+        const resolvedAgain = await resolveContainedPath(root, path);
+        const after = await lstat(resolvedAgain, { bigint: true });
+        if (!opened.isFile() ||
+            opened.size > BigInt(MAX_DOCTOR_FILE_BYTES) ||
+            after.dev !== before.dev ||
+            after.ino !== before.ino) {
+            throw new Error("Doctor target identity changed during inspection.");
+        }
+        const chunks = [];
+        let totalBytes = 0;
+        while (totalBytes <= MAX_DOCTOR_FILE_BYTES) {
+            const remaining = MAX_DOCTOR_FILE_BYTES + 1 - totalBytes;
+            const chunk = Buffer.alloc(Math.min(64 * 1024, remaining));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+            if (bytesRead === 0) {
+                return Buffer.concat(chunks, totalBytes);
+            }
+            chunks.push(chunk.subarray(0, bytesRead));
+            totalBytes += bytesRead;
+        }
+        throw new Error("Doctor target exceeded its inspection limit.");
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readContainedText(root, path) {
+    return (await readContained(root, path)).toString("utf8");
+}
+async function checkManifest(root) {
+    try {
+        const manifest = parseInstallManifest(await readContainedText(root, PROJECT_MANIFEST_PATH));
+        assertSupportedManifestOwnership(manifest);
+        return {
+            check: check("manifest", "PASS", "Installation manifest is valid."),
+            manifest
+        };
+    }
+    catch {
+        return {
+            check: check("manifest", "FAIL", "Installation manifest is missing, unsafe, or invalid.")
+        };
+    }
+}
+async function checkConfig(root) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readContainedText(root, CONFIG_PATH));
+    }
+    catch {
+        return {
+            check: check("config", "FAIL", "Configuration is missing, unsafe, or invalid JSON.")
+        };
+    }
+    const result = validateConfig(parsed);
+    if (!result.ok) {
+        const error = result.errors[0];
+        return {
+            check: check("config", "FAIL", error === undefined
+                ? "Configuration failed validation."
+                : `Configuration failed validation: ${error.code} at ${error.path}.`)
+        };
+    }
+    return {
+        check: check("config", "PASS", "Configuration is valid."),
+        config: result.value
+    };
+}
+async function checkArtifacts(root, manifest) {
+    if (manifest === undefined) {
+        return check("artifacts", "FAIL", "Artifacts cannot be verified without a valid manifest.");
+    }
+    const failures = [];
+    for (const artifact of manifest.artifacts) {
+        try {
+            const content = await readContained(root, artifact.path);
+            if (sha256(content) !== artifact.hash) {
+                failures.push(artifact.path);
+            }
+        }
+        catch {
+            failures.push(artifact.path);
+        }
+    }
+    return failures.length === 0
+        ? check("artifacts", "PASS", "All managed artifacts match their hashes.")
+        : check("artifacts", "FAIL", `Managed artifacts failed verification: ${failures.join(", ")}.`);
+}
+async function checkMarkers(root, manifest) {
+    if (manifest === undefined) {
+        return check("markers", "FAIL", "Managed blocks cannot be verified without a valid manifest.");
+    }
+    const failures = [];
+    const expectedMarkers = assertSupportedManifestOwnership(manifest);
+    for (const marker of manifest.markers) {
+        try {
+            const source = await readContainedText(root, marker.path);
+            const expected = expectedMarkers.get(marker.id);
+            if (expected === undefined) {
+                failures.push(marker.path);
+                continue;
+            }
+            assertExpectedManagedBlock(source, marker, expected);
+        }
+        catch {
+            failures.push(marker.path);
+        }
+    }
+    return failures.length === 0
+        ? check("markers", "PASS", "All managed block markers are intact.")
+        : check("markers", "FAIL", `Managed block markers failed verification: ${failures.join(", ")}.`);
+}
+async function checkProbe(id, probe) {
+    if (probe === undefined) {
+        return check(id, "UNKNOWN", "No probe was provided.");
+    }
+    try {
+        return (await probe())
+            ? check(id, "PASS", "Probe passed.")
+            : check(id, "FAIL", "Probe failed.");
+    }
+    catch {
+        return check(id, "FAIL", "Probe failed.");
+    }
+}
+export async function doctorInstallation(options) {
+    const manifest = await checkManifest(options.root);
+    const config = await checkConfig(options.root);
+    const checks = [
+        checkNodeVersion(options.nodeVersion ?? process.versions.node),
+        manifest.check,
+        config.check,
+        await checkArtifacts(options.root, manifest.manifest),
+        await checkMarkers(options.root, manifest.manifest),
+        await checkProbe("hook-registration", options.probes?.hookRegistration),
+        await checkProbe("repository-trust", options.probes?.repositoryTrust),
+        await checkProbe("smoke-availability", options.probes?.smokeAvailability)
+    ];
+    return {
+        checks,
+        ...(manifest.manifest === undefined
+            ? {}
+            : { manifest: manifest.manifest }),
+        ...(config.config === undefined ? {} : { config: config.config })
+    };
+}

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

@@ -0,0 +1,87 @@
+import { AgentOpsError } from "../fs/paths.js";
+export const COMMON_AGENTS_BLOCK = "## Loop Engineering\n\nUse `.agent-ops/AGENTS.md` as the canonical Loop Engineering specification for this project.\n";
+export const COMMON_CLAUDE_BLOCK = "## Loop Engineering\n\nUse `.agent-ops/CLAUDE.md` as the canonical Loop Engineering specification for this project.\n";
+function managedRules(id, context) {
+    const instructionFile = id === "codex" ? "AGENTS.md" : "CLAUDE.md";
+    const lines = [
+        "# Loop Engineering",
+        "",
+        "This routing specification is managed by `agent-ops`.",
+        "",
+        `Active profiles: ${context.profiles.join(", ")}`,
+        `Active capabilities: ${context.capabilities.join(", ")}`,
+        ...(context.toolkitVersion === undefined
+            ? []
+            : [`Toolkit version: ${context.toolkitVersion}`]),
+        ""
+    ];
+    if (context.capabilities.includes("rules")) {
+        lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope and preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain independent review before claiming completion.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "explicit matching trust record; installation approval never grants trust.", "");
+    }
+    if (context.capabilities.includes("lifecycle-summary")) {
+        lines.push("Advisory lifecycle summaries and local logs are informational. Advisory", "failures must remain fail-open and cannot become verification evidence.", "");
+    }
+    if (context.capabilities.includes("command-policy")) {
+        lines.push("Command policy guards high-confidence unsafe actions. Optional Stop", "verification never marks a task complete by itself.", "");
+    }
+    lines.push(`This file is routed from the active ${instructionFile}.`, "");
+    return lines.join("\n");
+}
+export function commonHarnessAdapters() {
+    return ["codex", "claude"].map((id) => {
+        const instructionFile = id === "codex" ? "AGENTS.md" : "CLAUDE.md";
+        const blockContent = id === "codex" ? COMMON_AGENTS_BLOCK : COMMON_CLAUDE_BLOCK;
+        return {
+            id,
+            async plan(context) {
+                return {
+                    artifacts: [
+                        {
+                            id: `${id}-rules`,
+                            path: `.agent-ops/${instructionFile}`,
+                            content: managedRules(id, context)
+                        }
+                    ],
+                    blocks: [
+                        {
+                            id: `${id}-routing`,
+                            path: context.scope === "project"
+                                ? instructionFile
+                                : `.${id}/${instructionFile}`,
+                            version: 1,
+                            content: blockContent
+                        }
+                    ]
+                };
+            }
+        };
+    });
+}
+function requestedHarnessIds(harness) {
+    return harness === "both" ? ["codex", "claude"] : [harness];
+}
+function selectAdapter(id, adapters) {
+    const matches = adapters.filter((adapter) => adapter.id === id);
+    if (matches.length === 0) {
+        throw new AgentOpsError("HARNESS_ADAPTER_MISSING", `Missing harness adapter: ${id}`);
+    }
+    if (matches.length > 1) {
+        throw new AgentOpsError("HARNESS_ADAPTER_DUPLICATE", `Duplicate harness adapter: ${id}`);
+    }
+    const adapter = matches[0];
+    if (adapter === undefined) {
+        throw new AgentOpsError("HARNESS_ADAPTER_MISSING", `Missing harness adapter: ${id}`);
+    }
+    return adapter;
+}
+export async function planHarnessContributions(harness, context, adapters) {
+    const selectedAdapters = requestedHarnessIds(harness).map((id) => selectAdapter(id, adapters));
+    const artifacts = [];
+    const blocks = [];
+    for (const adapter of selectedAdapters) {
+        const contribution = await adapter.plan(context);
+        artifacts.push(...contribution.artifacts);
+        blocks.push(...contribution.blocks);
+    }
+    return { artifacts, blocks };
+}

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

@@ -0,0 +1,84 @@
+import { applyManagedBlock, managedBlockMarkers } from "../fs/managed-block.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { COMMON_AGENTS_BLOCK, COMMON_CLAUDE_BLOCK } from "./harness.js";
+function selectedHarnesses(manifest) {
+    return manifest.harness === "both"
+        ? ["codex", "claude"]
+        : [manifest.harness];
+}
+function expectedMarker(manifest, id) {
+    const isCodex = id === "codex";
+    const markerId = `${id}-routing`;
+    const markers = managedBlockMarkers(markerId, 1);
+    const instructionFile = isCodex ? "AGENTS.md" : "CLAUDE.md";
+    return {
+        id: markerId,
+        path: manifest.scope === "project"
+            ? instructionFile
+            : `.${id}/${instructionFile}`,
+        startMarker: markers.start,
+        endMarker: markers.end,
+        content: isCodex ? COMMON_AGENTS_BLOCK : COMMON_CLAUDE_BLOCK
+    };
+}
+function manifestOwnershipError() {
+    return new AgentOpsError("MANIFEST_OWNERSHIP_INVALID", "The manifest does not match a supported managed installation shape.");
+}
+export function assertSupportedManifestOwnership(manifest) {
+    const harnesses = selectedHarnesses(manifest);
+    const expectedArtifacts = new Map([
+        ["config", ".agent-ops/config.json"]
+    ]);
+    const expectedMarkers = new Map();
+    for (const id of harnesses) {
+        expectedArtifacts.set(`${id}-rules`, `.agent-ops/${id === "codex" ? "AGENTS.md" : "CLAUDE.md"}`);
+        const marker = expectedMarker(manifest, id);
+        expectedMarkers.set(marker.id, marker);
+    }
+    if (manifest.artifacts.length !== expectedArtifacts.size ||
+        manifest.markers.length !== expectedMarkers.size) {
+        throw manifestOwnershipError();
+    }
+    for (const artifact of manifest.artifacts) {
+        if (expectedArtifacts.get(artifact.id) !== artifact.path) {
+            throw manifestOwnershipError();
+        }
+    }
+    for (const marker of manifest.markers) {
+        const expected = expectedMarkers.get(marker.id);
+        if (expected === undefined ||
+            marker.path !== expected.path ||
+            marker.startMarker !== expected.startMarker ||
+            marker.endMarker !== expected.endMarker) {
+            throw manifestOwnershipError();
+        }
+    }
+    return expectedMarkers;
+}
+function exactMarkerCount(source, marker) {
+    let count = 0;
+    let offset = 0;
+    while ((offset = source.indexOf(marker, offset)) !== -1) {
+        count += 1;
+        offset += marker.length;
+    }
+    return count;
+}
+export function assertExpectedManagedBlock(source, marker, expected) {
+    const startIndex = source.indexOf(marker.startMarker);
+    const endIndex = source.indexOf(marker.endMarker);
+    if (exactMarkerCount(source, marker.startMarker) !== 1 ||
+        exactMarkerCount(source, marker.endMarker) !== 1 ||
+        startIndex >= endIndex) {
+        throw new AgentOpsError("MANAGED_BLOCK_CHANGED", `Managed block boundaries changed after installation: ${marker.path}`);
+    }
+    const expectedBlock = applyManagedBlock("", {
+        id: expected.id,
+        version: 1,
+        content: expected.content
+    }).replace(/\n$/u, "");
+    const currentBlock = source.slice(startIndex, endIndex + marker.endMarker.length);
+    if (currentBlock !== expectedBlock) {
+        throw new AgentOpsError("MANAGED_BLOCK_CHANGED", `Managed block content changed after installation: ${marker.path}`);
+    }
+}

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

@@ -0,0 +1,257 @@
+import { lstat, readFile } from "node:fs/promises";
+import { SCHEMA_VERSION } from "../contracts.js";
+import { sha256 } from "../fs/hash.js";
+import { applyManagedBlock, managedBlockMarkers } 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 } from "./harness.js";
+import { 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;
+function isMissing(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+async function readCurrentFile(root, path) {
+    const resolvedPath = await resolveContainedPath(root, path);
+    try {
+        const status = await lstat(resolvedPath);
+        if (!status.isFile()) {
+            throw new AgentOpsError("INSTALL_TARGET_INVALID", `Install target must be a regular file: ${path}`);
+        }
+        if (status.size > MAX_PLANNED_FILE_BYTES) {
+            throw new AgentOpsError("INSTALL_TARGET_TOO_LARGE", `Install target exceeds the planning limit: ${path}`);
+        }
+        const content = await readFile(resolvedPath, "utf8");
+        return { content, hash: sha256(content) };
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+function formatConfig(profiles, existing) {
+    return `${JSON.stringify({
+        schemaVersion: SCHEMA_VERSION,
+        profiles,
+        verification: existing?.verification ?? { commands: [] },
+        pathMappings: existing?.pathMappings ?? [],
+        securityExceptions: existing?.securityExceptions ?? []
+    }, null, 2)}\n`;
+}
+async function planConfig(root, profiles, existingManifest, suppliedConfig) {
+    const current = await readCurrentFile(root, CONFIG_PATH);
+    const owned = findOwnedArtifact(existingManifest, CONFIG_PATH);
+    if (current !== null && owned === undefined) {
+        throw new AgentOpsError("UNMANAGED_INSTALL_PATH", `Refusing to replace an unmanaged install artifact: ${CONFIG_PATH}`);
+    }
+    let existingConfig;
+    if (suppliedConfig !== undefined) {
+        if (current === null ||
+            current.hash !== suppliedConfig.sourceHash) {
+            throw new AgentOpsError("PRECONDITION_CHANGED", "Managed configuration changed during plan creation.");
+        }
+        const result = validateConfig(suppliedConfig.value);
+        if (!result.ok) {
+            throw new AgentOpsError("CONFIG_INVALID", `${result.errors[0]?.path ?? "$"}: ${result.errors[0]?.message ?? "Invalid managed configuration."}`);
+        }
+        existingConfig = result.value;
+    }
+    else if (current !== null) {
+        let parsed;
+        try {
+            parsed = JSON.parse(current.content);
+        }
+        catch (error) {
+            throw new AgentOpsError("CONFIG_INVALID_JSON", "Managed configuration is not valid JSON.", { cause: error });
+        }
+        const result = validateConfig(parsed);
+        if (!result.ok) {
+            throw new AgentOpsError("CONFIG_INVALID", `${result.errors[0]?.path ?? "$"}: ${result.errors[0]?.message ?? "Invalid managed configuration."}`);
+        }
+        existingConfig = result.value;
+    }
+    const content = formatConfig(profiles, existingConfig);
+    return {
+        operation: {
+            kind: "write",
+            path: CONFIG_PATH,
+            content,
+            expectedHash: current?.hash ?? null
+        },
+        record: {
+            id: "config",
+            path: CONFIG_PATH,
+            hash: sha256(content),
+            owner: "agent-ops"
+        }
+    };
+}
+function pathKey(path) {
+    return path.toLowerCase();
+}
+function assertUniqueContributions(artifacts, blocks) {
+    const ids = new Set(["config"]);
+    const artifactPaths = new Set([pathKey(CONFIG_PATH)]);
+    for (const artifact of artifacts) {
+        if (ids.has(artifact.id) || artifactPaths.has(pathKey(artifact.path))) {
+            throw new AgentOpsError("INSTALL_PATH_CONFLICT", `Harness artifact conflicts with another managed entry: ${artifact.path}`);
+        }
+        ids.add(artifact.id);
+        artifactPaths.add(pathKey(artifact.path));
+    }
+    const markerBoundaries = new Set();
+    for (const block of blocks) {
+        const markers = managedBlockMarkers(block.id, block.version);
+        const key = pathKey(block.path);
+        if (ids.has(block.id) ||
+            artifactPaths.has(key) ||
+            markerBoundaries.has(`${key}\0${markers.start}`) ||
+            markerBoundaries.has(`${key}\0${markers.end}`)) {
+            throw new AgentOpsError("INSTALL_PATH_CONFLICT", `Harness block conflicts with another managed entry: ${block.path}`);
+        }
+        ids.add(block.id);
+        markerBoundaries.add(`${key}\0${markers.start}`);
+        markerBoundaries.add(`${key}\0${markers.end}`);
+    }
+}
+async function readExistingManifest(root) {
+    const current = await readCurrentFile(root, MANIFEST_PATH);
+    return current === null
+        ? null
+        : {
+            manifest: parseInstallManifest(current.content),
+            hash: current.hash
+        };
+}
+function assertCompatibleManifest(existing, scope, harness) {
+    if (existing !== null &&
+        (existing.scope !== scope || existing.harness !== harness)) {
+        throw new AgentOpsError("INSTALL_ALREADY_CONFIGURED", "Use update to change the scope or harness of an existing installation.");
+    }
+}
+function findOwnedArtifact(manifest, path) {
+    const key = pathKey(path);
+    return manifest?.artifacts.find((artifact) => pathKey(artifact.path) === key);
+}
+async function planArtifact(root, artifact, existingManifest) {
+    const current = await readCurrentFile(root, artifact.path);
+    const owned = findOwnedArtifact(existingManifest, artifact.path);
+    if (current !== null && owned === undefined) {
+        throw new AgentOpsError("UNMANAGED_INSTALL_PATH", `Refusing to replace an unmanaged install artifact: ${artifact.path}`);
+    }
+    if (current !== null &&
+        owned !== undefined &&
+        owned.hash !== current.hash) {
+        throw new AgentOpsError("MANAGED_ARTIFACT_CHANGED", `Managed artifact changed after installation: ${artifact.path}`);
+    }
+    const hash = sha256(artifact.content);
+    return {
+        operation: {
+            kind: "write",
+            path: artifact.path,
+            content: artifact.content,
+            expectedHash: current?.hash ?? null
+        },
+        record: {
+            id: artifact.id,
+            path: artifact.path,
+            hash,
+            owner: "agent-ops"
+        }
+    };
+}
+async function planBlocks(root, blocks) {
+    const grouped = new Map();
+    for (const block of blocks) {
+        const existing = grouped.get(block.path) ?? [];
+        existing.push(block);
+        grouped.set(block.path, existing);
+    }
+    const operations = [];
+    const records = [];
+    for (const [path, pathBlocks] of grouped) {
+        const current = await readCurrentFile(root, path);
+        let content = current?.content ?? "";
+        for (const block of pathBlocks) {
+            content = applyManagedBlock(content, block);
+        }
+        const hash = sha256(content);
+        operations.push({
+            kind: "write",
+            path,
+            content,
+            expectedHash: current?.hash ?? null
+        });
+        for (const block of pathBlocks) {
+            const markers = managedBlockMarkers(block.id, block.version);
+            records.push({
+                id: block.id,
+                path,
+                hash,
+                owner: "agent-ops",
+                startMarker: markers.start,
+                endMarker: markers.end
+            });
+        }
+    }
+    return { operations, records };
+}
+export async function createInstallPlan(options) {
+    if (options.toolkitVersion !== undefined &&
+        !/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u
+            .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, {
+        scope: options.scope,
+        profiles: resolved.profiles,
+        capabilities: resolved.capabilities,
+        ...(options.toolkitVersion === undefined
+            ? {}
+            : { toolkitVersion: options.toolkitVersion })
+    }, options.adapters);
+    assertUniqueContributions(contribution.artifacts, contribution.blocks);
+    const existing = await readExistingManifest(options.root);
+    assertCompatibleManifest(existing?.manifest ?? null, options.scope, options.harness);
+    const operations = [];
+    const artifacts = [];
+    const config = await planConfig(options.root, resolved.profiles, existing?.manifest ?? null, options.existingConfig);
+    operations.push(config.operation);
+    artifacts.push(config.record);
+    for (const artifact of contribution.artifacts) {
+        const planned = await planArtifact(options.root, artifact, existing?.manifest ?? null);
+        operations.push(planned.operation);
+        artifacts.push(planned.record);
+    }
+    const plannedBlocks = await planBlocks(options.root, contribution.blocks);
+    operations.push(...plannedBlocks.operations);
+    const manifest = {
+        schemaVersion: SCHEMA_VERSION,
+        scope: options.scope,
+        harness: options.harness,
+        artifacts,
+        markers: plannedBlocks.records
+    };
+    operations.push({
+        kind: "write",
+        path: MANIFEST_PATH,
+        content: formatInstallManifest(manifest),
+        expectedHash: existing?.hash ?? null
+    });
+    return {
+        scope: options.scope,
+        harness: options.harness,
+        profiles: resolved.profiles,
+        capabilities: resolved.capabilities,
+        manifest,
+        operations
+    };
+}

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

@@ -0,0 +1,28 @@
+import { AgentOpsError } from "../fs/paths.js";
+const PROFILE_ORDER = ["core", "advisory", "guardrails"];
+export const PROFILE_CAPABILITIES = {
+    core: ["rules", "task", "verify", "review"],
+    advisory: ["lifecycle-summary", "local-log"],
+    guardrails: ["command-policy", "optional-stop-verify"]
+};
+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")) {
+        selectedProfiles.add("core");
+    }
+    const profiles = PROFILE_ORDER.filter((profile) => selectedProfiles.has(profile));
+    const capabilities = [];
+    const seenCapabilities = new Set();
+    for (const profile of profiles) {
+        for (const capability of PROFILE_CAPABILITIES[profile]) {
+            if (!seenCapabilities.has(capability)) {
+                seenCapabilities.add(capability);
+                capabilities.push(capability);
+            }
+        }
+    }
+    return { profiles: [...profiles], capabilities };
+}

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

@@ -0,0 +1 @@
+export {};