@kylecheng3146/agent-ops 0.1.3 → 0.1.5

package/dist/runtime/src/adapters/opencode/surfaces.js

@@ -0,0 +1,23 @@
+import { opencodePluginTarget } from "./config.js";
+export const OPENCODE_SURFACE_IDS = {
+    plugin: "opencode-plugin",
+    config: "opencode-config"
+};
+export function opencodeSurfaces(scope, root) {
+    return [
+        {
+            id: OPENCODE_SURFACE_IDS.plugin,
+            path: opencodePluginTarget(scope, root).path,
+            scope,
+            access: "managed-default",
+            representation: "javascript"
+        },
+        {
+            id: OPENCODE_SURFACE_IDS.config,
+            path: "opencode.json",
+            scope,
+            access: "inspect-only",
+            representation: "json"
+        }
+    ];
+}

package/dist/runtime/src/config/explain.js

@@ -1,6 +1,13 @@
 export function explainConfig(merged) {
     return {
         schemaVersion: merged.config.schemaVersion,
+        features: {
+            stopVerification: {
+                enabled: merged.config.features.stopVerification.enabled,
+                source: merged.provenance.features.source,
+                sourcePath: merged.provenance.features.sourcePath
+            }
+        },
         profiles: merged.provenance.profiles.map((entry) => ({
             id: entry.value,
             source: entry.source,

package/dist/runtime/src/config/hash.js

@@ -0,0 +1,24 @@
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+function canonicalJson(value) {
+    if (value === null ||
+        typeof value === "boolean" ||
+        typeof value === "number" ||
+        typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    if (typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+            .join(",")}}`;
+    }
+    throw new AgentOpsError("CONFIG_HASH_INVALID", "Configuration contains an unsupported value.");
+}
+export function calculateConfigHash(config) {
+    return sha256(canonicalJson(config));
+}

package/dist/runtime/src/config/merge.js

@@ -108,8 +108,10 @@ export function mergeConfigLayers(inputLayers) {
     const mappings = new Map();
     const exceptions = new Map();
     let schemaVersion;
+    let features;
     for (const layer of layers) {
         schemaVersion = effective(layer.config.schemaVersion, layer);
+        features = effective(layer.config.features, layer);
         for (const profile of layer.config.profiles) {
             profiles.set(profile, effective(profile, layer));
         }
@@ -139,22 +141,24 @@ export function mergeConfigLayers(inputLayers) {
             exceptions.set(key, effective(securityException, layer));
         }
     }
-    if (schemaVersion === undefined) {
+    if (schemaVersion === undefined || features === undefined) {
         throw new AgentOpsError("CONFIG_LAYER_REQUIRED", "At least one configuration layer is required.");
     }
     const provenance = {
         schemaVersion,
+        features,
         profiles: [...profiles.values()],
         verificationCommands: [...commands.values()],
         pathMappings: [...mappings.values()],
         securityExceptions: [...exceptions.values()]
     };
     const config = {
-        schemaVersion: 1,
+        schemaVersion: schemaVersion.value,
         profiles: provenance.profiles.map(({ value }) => value),
         verification: {
             commands: provenance.verificationCommands.map(({ value }) => value)
         },
+        features: provenance.features.value,
         pathMappings: provenance.pathMappings.map(({ value }) => value),
         securityExceptions: provenance.securityExceptions.map(({ value }) => value)
     };

package/dist/runtime/src/config/migrate.js

@@ -1,4 +1,4 @@
-import { SCHEMA_VERSION } from "../contracts.js";
+import { CONFIG_SCHEMA_VERSION } from "../contracts.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { validateConfig } from "../schema/validate.js";
 function isRecord(value) {
@@ -18,6 +18,21 @@ const MIGRATIONS = new Map([
                 verification: { commands: clone(commands) }
             };
         }
+    ],
+    [
+        1,
+        (input) => {
+            const { schemaVersion: _schemaVersion, ...rest } = input;
+            return {
+                ...rest,
+                schemaVersion: CONFIG_SCHEMA_VERSION,
+                features: {
+                    stopVerification: {
+                        enabled: false
+                    }
+                }
+            };
+        }
     ]
 ]);
 function schemaVersionOf(value) {
@@ -30,13 +45,13 @@ function schemaVersionOf(value) {
 }
 export function previewConfigMigration(input) {
     const sourceVersion = schemaVersionOf(input);
-    if (sourceVersion > SCHEMA_VERSION) {
-        throw new AgentOpsError("CONFIG_SCHEMA_FUTURE", `Config schemaVersion ${sourceVersion} is newer than supported version ${SCHEMA_VERSION}.`);
+    if (sourceVersion > CONFIG_SCHEMA_VERSION) {
+        throw new AgentOpsError("CONFIG_SCHEMA_FUTURE", `Config schemaVersion ${sourceVersion} is newer than supported version ${CONFIG_SCHEMA_VERSION}.`);
     }
     let migrated = clone(input);
     let version = sourceVersion;
     const steps = [];
-    while (version < SCHEMA_VERSION) {
+    while (version < CONFIG_SCHEMA_VERSION) {
         const migration = MIGRATIONS.get(version);
         if (migration === undefined || !isRecord(migrated)) {
             throw new AgentOpsError("CONFIG_MIGRATION_MISSING", `No migration is registered from config schemaVersion ${version}.`);

package/dist/runtime/src/contracts.js

@@ -1 +1,10 @@
-export const SCHEMA_VERSION = 1;
+export const CONFIG_SCHEMA_VERSION = 2;
+export const TASK_SCHEMA_VERSION = 1;
+export const EVIDENCE_SCHEMA_VERSION = 1;
+/** @deprecated Use the document-specific schema version constants. */
+export const SCHEMA_VERSION = CONFIG_SCHEMA_VERSION;
+/**
+ * The manifest versions independently of config, tasks, and evidence: only its
+ * own shape changed when the harness selection became a list.
+ */
+export const MANIFEST_SCHEMA_VERSION = 2;

package/dist/runtime/src/fs/manifest.js

@@ -1,6 +1,37 @@
+import { MANIFEST_SCHEMA_VERSION } from "../contracts.js";
 import { validateManifest } from "../schema/validate.js";
 import { AgentOpsError } from "./paths.js";
 export const PROJECT_MANIFEST_PATH = ".agent-ops/manifest.json";
+const LEGACY_HARNESS_SELECTIONS = {
+    both: ["codex", "claude"],
+    claude: ["claude"],
+    codex: ["codex"]
+};
+/**
+ * Manifests written up to 0.1.4 stored a single harness string, with `"both"`
+ * standing in for two harnesses. Reading one upgrades it in memory; the file is
+ * rewritten the next time `update` runs.
+ */
+function migrateLegacyManifest(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value)) {
+        return value;
+    }
+    const record = value;
+    if (record.schemaVersion !== 1 || typeof record.harness !== "string") {
+        return value;
+    }
+    const harness = LEGACY_HARNESS_SELECTIONS[record.harness];
+    if (harness === undefined) {
+        return value;
+    }
+    return {
+        ...record,
+        schemaVersion: MANIFEST_SCHEMA_VERSION,
+        harness
+    };
+}
 export function parseInstallManifest(source) {
     let value;
     try {
@@ -9,7 +40,7 @@ export function parseInstallManifest(source) {
     catch (error) {
         throw new AgentOpsError("MANIFEST_INVALID_JSON", "The installation manifest is not valid JSON.", { cause: error });
     }
-    const result = validateManifest(value);
+    const result = validateManifest(migrateLegacyManifest(value));
     if (!result.ok) {
         throw new AgentOpsError("MANIFEST_INVALID", `${result.errors[0]?.path ?? "$"}: ${result.errors[0]?.message ?? "Invalid installation manifest."}`);
     }

package/dist/runtime/src/fs/transaction.js

@@ -147,13 +147,25 @@ function assertTransactionPlan(plan) {
         }
         if (operation.kind === "write") {
             if (typeof operation.content !== "string" ||
-                !hasOnlyKeys(operation, ["kind", "path", "content", "expectedHash"])) {
+                (operation.disclosure !== undefined &&
+                    operation.disclosure !== "full" &&
+                    operation.disclosure !== "opaque") ||
+                !hasOnlyKeys(operation, [
+                    "kind",
+                    "path",
+                    "content",
+                    "expectedHash",
+                    "disclosure"
+                ])) {
                 throw new AgentOpsError("INVALID_TRANSACTION_PLAN", `Invalid write operation at index ${index}.`);
             }
             continue;
         }
         if (operation.kind !== "remove" ||
-            !hasOnlyKeys(operation, ["kind", "path", "expectedHash"])) {
+            (operation.disclosure !== undefined &&
+                operation.disclosure !== "full" &&
+                operation.disclosure !== "opaque") ||
+            !hasOnlyKeys(operation, ["kind", "path", "expectedHash", "disclosure"])) {
             throw new AgentOpsError("INVALID_TRANSACTION_PLAN", `Invalid remove operation at index ${index}.`);
         }
     }

package/dist/runtime/src/hooks/advisory.js

@@ -0,0 +1,16 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { appendLocalLog } from "../logging/local-log.js";
+import { localStatePaths } from "../security/permissions.js";
+/**
+ * Records the bounded lifecycle summary signal locally. It deliberately does
+ * not include project paths, prompts, commands, or verification evidence.
+ */
+export async function runLifecycleAdvisory(_event, options = {}) {
+    const home = options.homeDirectory ?? process.env.AGENT_OPS_HOME ?? homedir();
+    const state = localStatePaths(home);
+    await appendLocalLog(join(state.logDirectory, "events.ndjson"), { type: "diagnostic", code: "LIFECYCLE_SUMMARY" }, {
+        anchorDirectory: state.anchorDirectory,
+        ...(options.now === undefined ? {} : { now: options.now })
+    });
+}

package/dist/runtime/src/hooks/stop-service.js

@@ -0,0 +1,70 @@
+import { calculateConfigHash } from "../config/hash.js";
+import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
+import { aggregateVerificationStatus, executeConfiguredCommand } from "../verify/command-executor.js";
+import { collectChangeSurface } from "../verify/change-surface.js";
+import { selectVerificationScope } from "../verify/scope.js";
+export const STOP_VERIFICATION_ENV = "AGENT_OPS_STOP_VERIFY_ACTIVE";
+const HASH_PATTERN = /^[a-f0-9]{64}$/;
+function stopError(code, message) {
+    return new AgentOpsError(code, message);
+}
+function commandById(config, commandId) {
+    const command = config.verification.commands.find((candidate) => candidate.id === commandId);
+    if (command === undefined) {
+        throw stopError("STOP_VERIFICATION_COMMAND_NOT_FOUND", `Stop verification command not found: ${commandId}`);
+    }
+    return command;
+}
+export class StopVerificationService {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    #assertReady() {
+        if (!this.#options.config.features.stopVerification.enabled) {
+            throw stopError("STOP_VERIFICATION_DISABLED", "Stop verification is not enabled in configuration.");
+        }
+        if (this.#options.config.verification.commands.length === 0) {
+            throw stopError("STOP_VERIFICATION_COMMANDS_REQUIRED", "Stop verification requires at least one configured command.");
+        }
+        if (!this.#options.trusted) {
+            throw stopError("STOP_VERIFICATION_UNTRUSTED", "Stop verification requires a trusted repository.");
+        }
+        if (this.#options.recursionActive ||
+            process.env[STOP_VERIFICATION_ENV] === "1") {
+            throw stopError("STOP_VERIFICATION_RECURSION", "Stop verification recursion is active.");
+        }
+        if (!HASH_PATTERN.test(this.#options.configHash) ||
+            calculateConfigHash(this.#options.config) !== this.#options.configHash) {
+            throw stopError("STOP_VERIFICATION_UNCONFIRMED", "Stop verification configuration is stale or unconfirmed.");
+        }
+    }
+    async verify() {
+        this.#assertReady();
+        const surface = await collectChangeSurface(this.#options.gitRunner);
+        const selection = selectVerificationScope(surface.paths, this.#options.config);
+        const executions = [];
+        for (const commandId of selection.verifierIds) {
+            const command = commandById(this.#options.config, commandId);
+            const cwd = command.cwd === "."
+                ? this.#options.root
+                : await resolveContainedPath(this.#options.root, command.cwd);
+            const result = await executeConfiguredCommand(command, {
+                cwd,
+                runner: this.#options.processRunner,
+                trusted: true,
+                env: { [STOP_VERIFICATION_ENV]: "1" }
+            });
+            executions.push(result);
+        }
+        const results = executions.map(({ commandId, exitCode, testCount }) => ({
+            commandId,
+            exitCode,
+            testCount
+        }));
+        return {
+            status: aggregateVerificationStatus(executions),
+            results
+        };
+    }
+}

package/dist/runtime/src/hooks/stop-verify.js

@@ -16,11 +16,14 @@ function boundedEvidence(results) {
                 (!Number.isSafeInteger(result.testCount) || result.testCount < 0)))) {
         return null;
     }
-    return results.map(({ commandId, exitCode, testCount }) => ({
+    const bounded = results.map(({ commandId, exitCode, testCount }) => ({
         commandId,
         exitCode,
         testCount
     }));
+    return Buffer.byteLength(JSON.stringify(bounded), "utf8") <= 4096
+        ? bounded
+        : null;
 }
 function evidenceSupportsStatus(status, results) {
     if (status !== "PASS") {

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

@@ -5,11 +5,17 @@ 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";
+import { isOpencodeManagedPlugin } from "../adapters/opencode/config.js";
+import { harnessDescriptor } from "./harness.js";
+import { resolveProfiles } from "./profiles.js";
+import { inspectHarnessSurfaces, inspectHarnessRegistrations } from "./surface-inspection.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 check(id, status, message, code) {
+    return code === undefined
+        ? { id, status, message }
+        : { id, status, message, code };
 }
 function parseNodeVersion(version) {
     const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version);
@@ -80,7 +86,7 @@ async function readContainedText(root, path) {
 async function checkManifest(root) {
     try {
         const manifest = parseInstallManifest(await readContainedText(root, PROJECT_MANIFEST_PATH));
-        assertSupportedManifestOwnership(manifest);
+        assertSupportedManifestOwnership(manifest, root);
         return {
             check: check("manifest", "PASS", "Installation manifest is valid."),
             manifest
@@ -124,7 +130,9 @@ async function checkArtifacts(root, manifest) {
     for (const artifact of manifest.artifacts) {
         try {
             const content = await readContained(root, artifact.path);
-            if (sha256(content) !== artifact.hash) {
+            if (sha256(content) !== artifact.hash ||
+                (artifact.id === "opencode-plugin" &&
+                    !isOpencodeManagedPlugin(content.toString("utf8")))) {
                 failures.push(artifact.path);
             }
         }
@@ -141,7 +149,8 @@ async function checkMarkers(root, manifest) {
         return check("markers", "FAIL", "Managed blocks cannot be verified without a valid manifest.");
     }
     const failures = [];
-    const expectedMarkers = assertSupportedManifestOwnership(manifest);
+    const legacyPaths = [];
+    const expectedMarkers = assertSupportedManifestOwnership(manifest, root);
     for (const marker of manifest.markers) {
         try {
             const source = await readContainedText(root, marker.path);
@@ -150,15 +159,22 @@ async function checkMarkers(root, manifest) {
                 failures.push(marker.path);
                 continue;
             }
-            assertExpectedManagedBlock(source, marker, expected);
+            const match = assertExpectedManagedBlock(source, marker, expected);
+            if (match === "legacy") {
+                legacyPaths.push(marker.path);
+            }
         }
         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(", ")}.`);
+    if (failures.length > 0) {
+        return check("markers", "FAIL", `Managed block markers failed verification: ${failures.join(", ")}.`);
+    }
+    if (legacyPaths.length > 0) {
+        return check("markers", "DEGRADED", `Legacy managed routing blocks need migration: ${legacyPaths.join(", ")}.`);
+    }
+    return check("markers", "PASS", "All managed block markers are intact.");
 }
 async function checkProbe(id, probe) {
     if (probe === undefined) {
@@ -177,21 +193,115 @@ async function checkProbe(id, probe) {
         return check(id, "FAIL", "Probe failed.");
     }
 }
+function checkLifecycleSummary(manifest, config) {
+    if (manifest === undefined || config === undefined) {
+        return check("lifecycle-summary", "UNKNOWN", "Lifecycle summary cannot be assessed without a valid manifest and configuration.");
+    }
+    const hasLifecycleSummary = config.profiles.length > 0 &&
+        resolveProfiles(config.profiles).capabilities.includes("lifecycle-summary");
+    if (!hasLifecycleSummary) {
+        return check("lifecycle-summary", "PASS", "Lifecycle summary has no harness-specific degradation.");
+    }
+    const registrations = manifest.harness.map((id) => ({
+        id,
+        registration: harnessDescriptor(id).control.registrations.find((candidate) => candidate.capability === "lifecycle-summary")
+    }));
+    const missing = registrations
+        .filter(({ registration }) => registration === undefined)
+        .map(({ id }) => id);
+    if (missing.length > 0) {
+        return check("lifecycle-summary", "UNKNOWN", `Lifecycle summary registration is missing for ${missing.join(", ")}.`);
+    }
+    const unsupported = registrations
+        .filter(({ registration }) => registration?.support === "unsupported")
+        .map(({ id }) => id);
+    if (unsupported.length > 0) {
+        return check("lifecycle-summary", "UNSUPPORTED", `Lifecycle summary is not dispatched for ${unsupported.join(", ")}; advisory runtime wiring is unavailable.`);
+    }
+    const degraded = registrations
+        .filter(({ registration }) => registration?.support === "degraded")
+        .map(({ id }) => id);
+    if (degraded.length > 0) {
+        return check("lifecycle-summary", "DEGRADED", `Lifecycle summary is degraded for ${degraded.join(", ")}.`);
+    }
+    const unknown = registrations
+        .filter(({ registration }) => registration?.support === "unknown")
+        .map(({ id }) => id);
+    if (unknown.length > 0) {
+        return check("lifecycle-summary", "UNKNOWN", `Lifecycle summary support is unknown for ${unknown.join(", ")}.`);
+    }
+    return check("lifecycle-summary", "PASS", "Lifecycle summary is reachable for every selected harness.");
+}
+async function checkSurfaceInventory(root, manifest, config) {
+    if (manifest === undefined || config === undefined) {
+        return {
+            check: check("surface-inventory", "UNKNOWN", "Harness surfaces cannot be inventoried without a valid manifest and configuration."),
+            surfaces: []
+        };
+    }
+    try {
+        const surfaces = await inspectHarnessSurfaces({
+            root,
+            scope: manifest.scope,
+            harness: manifest.harness,
+            profiles: config.profiles
+        });
+        const unknown = surfaces.filter(({ status }) => status === "unknown");
+        return {
+            check: check("surface-inventory", unknown.length > 0 ? "UNKNOWN" : "PASS", unknown.length > 0
+                ? `${unknown.length} harness surface(s) could not be inspected.`
+                : "Harness surfaces were inventoried without exposing settings values."),
+            surfaces
+        };
+    }
+    catch {
+        return {
+            check: check("surface-inventory", "UNKNOWN", "Harness surfaces could not be inspected safely."),
+            surfaces: []
+        };
+    }
+}
+async function checkRegistrationDrift(root, manifest, config) {
+    if (manifest === undefined || config === undefined) {
+        return check("registration-drift", "UNKNOWN", "Hook registration drift cannot be assessed without a valid manifest and configuration.");
+    }
+    try {
+        const statuses = await inspectHarnessRegistrations({
+            root,
+            manifest,
+            config
+        });
+        const drifted = statuses
+            .filter(({ registered }) => !registered)
+            .map(({ harness }) => harness);
+        return drifted.length === 0
+            ? check("registration-drift", "PASS", "Managed hook registrations match the desired capabilities.")
+            : check("registration-drift", "FAIL", `Hook registration drift detected for ${drifted.join(", ")}; run agent-ops update.`, "UPDATE_REQUIRED");
+    }
+    catch {
+        return check("registration-drift", "UNKNOWN", "Hook registration drift could not be assessed safely.");
+    }
+}
 export async function doctorInstallation(options) {
     const manifest = await checkManifest(options.root);
     const config = await checkConfig(options.root);
+    const surfaceInventory = await checkSurfaceInventory(options.root, manifest.manifest, config.config);
     const checks = [
         checkNodeVersion(options.nodeVersion ?? process.versions.node),
         manifest.check,
         config.check,
         await checkArtifacts(options.root, manifest.manifest),
         await checkMarkers(options.root, manifest.manifest),
+        surfaceInventory.check,
+        await checkRegistrationDrift(options.root, manifest.manifest, config.config),
         await checkProbe("hook-registration", options.probes?.hookRegistration),
+        checkLifecycleSummary(manifest.manifest, config.config),
         await checkProbe("repository-trust", options.probes?.repositoryTrust),
         await checkProbe("smoke-availability", options.probes?.smokeAvailability)
     ];
     return {
         checks,
+        surfaces: surfaceInventory.surfaces,
         ...(manifest.manifest === undefined
             ? {}
             : { manifest: manifest.manifest }),