@kylecheng3146/agent-ops 0.1.5 → 0.1.6

package/dist/runtime/src/hooks/codex-loop.js

@@ -0,0 +1,439 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { lstat, realpath } from "node:fs/promises";
+import { promisify } from "node:util";
+import { applyManagedBlock } from "../fs/managed-block.js";
+import { evaluateGuardrail } from "../guardrails/evaluate.js";
+import { appendLocalLog } from "../logging/local-log.js";
+import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
+import { redactSecrets } from "../security/redact.js";
+import { normalizeShellHookEvent } from "./shell.js";
+const execFile = promisify(execFileCallback);
+const MAX_CONTEXT_CHARS = 1_200;
+const MAX_GIT_STATUS_CHARS = 4_096;
+const DEFAULT_TELEMETRY_MAX_BYTES = 64 * 1024;
+const LOOP_SNAPSHOT_ID = "loop-snapshot";
+export const PROJECT_LOOP_EVENTS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PermissionRequest",
+    "PostToolUse",
+    "PreCompact",
+    "PostCompact",
+    "SubagentStart",
+    "SubagentStop"
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringField(value, maximum = 64 * 1024) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= maximum &&
+        !value.includes("\0"))
+        ? value
+        : null;
+}
+function inputCwd(input) {
+    return isRecord(input) ? stringField(input.cwd, 4_096) : null;
+}
+function prompt(input) {
+    return isRecord(input) ? stringField(input.prompt) : null;
+}
+function bashCommand(input) {
+    if (!isRecord(input) ||
+        input.tool_name !== "Bash" ||
+        !isRecord(input.tool_input)) {
+        return null;
+    }
+    return stringField(input.tool_input.command, 16 * 1024);
+}
+function requestedSandboxPermission(input) {
+    return isRecord(input)
+        ? stringField(input.sandbox_permissions, 128)
+        : null;
+}
+function noOutput() {
+    return { exitCode: 0, stdout: "", stderr: "" };
+}
+function secretDenial(harness, event) {
+    const reason = "agent-ops blocked a suspected secret.";
+    if (harness === "claude" && event === "UserPromptSubmit") {
+        return {
+            exitCode: 0,
+            stdout: JSON.stringify({ decision: "block", reason }),
+            stderr: ""
+        };
+    }
+    if (harness === "claude" && event === "PreToolUse") {
+        return {
+            exitCode: 0,
+            stdout: JSON.stringify({
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "deny",
+                    permissionDecisionReason: reason
+                }
+            }),
+            stderr: ""
+        };
+    }
+    return { exitCode: 2, stdout: "", stderr: reason };
+}
+function commandDenial(harness, event, code) {
+    const reason = "agent-ops blocked a dangerous command.";
+    if (harness === "claude" && event === "PreToolUse") {
+        return {
+            exitCode: 0,
+            stdout: JSON.stringify({
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "deny",
+                    permissionDecisionReason: reason
+                }
+            }),
+            stderr: ""
+        };
+    }
+    return {
+        exitCode: 2,
+        stdout: "",
+        stderr: `${reason} (${code})`
+    };
+}
+function evaluatePrompt(input, scope) {
+    const value = prompt(input);
+    if (value === null) {
+        return {
+            blocked: false,
+            outcome: "observed",
+            code: "prompt-unavailable",
+            denial: "none"
+        };
+    }
+    const decision = evaluateGuardrail({ kind: "content", content: value, scope });
+    return decision.action === "block"
+        ? {
+            blocked: true,
+            outcome: "blocked",
+            code: decision.ruleId,
+            denial: "secret"
+        }
+        : {
+            blocked: false,
+            outcome: "allowed",
+            code: "prompt-allowed",
+            denial: "none"
+        };
+}
+function evaluateBash(input, scope) {
+    const rawCommand = bashCommand(input);
+    if (rawCommand === null) {
+        return {
+            blocked: false,
+            outcome: "observed",
+            code: "command-unavailable",
+            denial: "none"
+        };
+    }
+    const secretDecision = evaluateGuardrail({
+        kind: "content",
+        content: rawCommand,
+        scope
+    });
+    if (secretDecision.action === "block") {
+        return {
+            blocked: true,
+            outcome: "blocked",
+            code: secretDecision.ruleId,
+            denial: "secret"
+        };
+    }
+    const event = normalizeShellHookEvent(rawCommand, scope);
+    const commands = event.event === "command"
+        ? [{ command: event.command, args: event.args }]
+        : event.event === "command-batch"
+            ? event.commands
+            : [];
+    for (const command of commands) {
+        const decision = evaluateGuardrail({
+            kind: "command",
+            command: command.command,
+            args: command.args,
+            scope
+        });
+        if (decision.action === "block") {
+            return {
+                blocked: true,
+                outcome: "blocked",
+                code: decision.ruleId,
+                denial: "command"
+            };
+        }
+    }
+    return {
+        blocked: false,
+        outcome: commands.length === 0 ? "observed" : "allowed",
+        code: commands.length === 0 ? "command-unavailable" : "command-allowed",
+        denial: "none"
+    };
+}
+function eventLogName(event) {
+    const names = {
+        SessionStart: "session-start",
+        UserPromptSubmit: "user-prompt-submit",
+        PreToolUse: "pre-tool-use",
+        PermissionRequest: "permission-request",
+        PostToolUse: "post-tool-use",
+        PreCompact: "pre-compact",
+        PostCompact: "post-compact",
+        SubagentStart: "subagent-start",
+        SubagentStop: "subagent-stop"
+    };
+    return names[event];
+}
+function boundedContext(value) {
+    const normalized = value.replace(/\r\n/g, "\n").trim();
+    return normalized.length <= MAX_CONTEXT_CHARS
+        ? normalized
+        : `${normalized.slice(0, MAX_CONTEXT_CHARS - 14)}\n[truncated]`;
+}
+function safeGoalContext(source) {
+    if (source === null || source.trim().length === 0) {
+        return "No project loop goal is recorded.";
+    }
+    const decision = evaluateGuardrail({
+        kind: "content",
+        content: source,
+        scope: "loop-goal.md"
+    });
+    if (decision.action === "block") {
+        return "The project loop goal contains sensitive-looking text and was omitted.";
+    }
+    return boundedContext(redactSecrets(source));
+}
+function isMissing(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+async function findLoopRoot(start, harness) {
+    let current;
+    try {
+        current = await realpath(resolve(start));
+        const status = await lstat(current);
+        if (!status.isDirectory() || status.isSymbolicLink()) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    while (true) {
+        try {
+            const harnessDirectory = await lstat(join(current, `.${harness}`));
+            if (harnessDirectory.isDirectory() && !harnessDirectory.isSymbolicLink()) {
+                return current;
+            }
+        }
+        catch (error) {
+            if (!isMissing(error)) {
+                return null;
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+async function resolveLoopRoot(input, fallback, harness) {
+    const candidates = [inputCwd(input), fallback].filter((value) => value !== null && value !== undefined);
+    for (const candidate of new Set(candidates)) {
+        const root = await findLoopRoot(candidate, harness);
+        if (root !== null) {
+            return root;
+        }
+    }
+    return null;
+}
+function loopPath(root, harness, name) {
+    return join(root, `.${harness}`, name);
+}
+async function appendTelemetry(options) {
+    const telemetry = loopPath(options.root, options.harness, "loop-telemetry.jsonl");
+    await appendLocalLog(telemetry, {
+        type: "loop-event",
+        event: eventLogName(options.event),
+        outcome: options.decision.outcome,
+        code: options.decision.code
+    }, {
+        anchorDirectory: options.root,
+        maxBytes: options.maxBytes ?? DEFAULT_TELEMETRY_MAX_BYTES,
+        ...(options.now === undefined ? {} : { now: options.now() })
+    });
+}
+async function telemetryCount(root, harness) {
+    const source = await readPrivateFile(loopPath(root, harness, "loop-telemetry.jsonl"), root);
+    if (source === null || Buffer.byteLength(source) > DEFAULT_TELEMETRY_MAX_BYTES) {
+        return 0;
+    }
+    let count = 0;
+    for (const line of source.split("\n")) {
+        if (line.length === 0) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(line);
+            if (isRecord(parsed) && parsed.type === "loop-event") {
+                count += 1;
+            }
+        }
+        catch {
+            return 0;
+        }
+    }
+    return count;
+}
+async function defaultGitStatus(root) {
+    const result = await execFile("git", ["status", "--short", "--branch"], {
+        cwd: root,
+        encoding: "utf8",
+        maxBuffer: MAX_GIT_STATUS_CHARS + 1,
+        timeout: 2_000,
+        windowsHide: true
+    });
+    return result.stdout;
+}
+function boundedSnapshot(status) {
+    const decision = evaluateGuardrail({
+        kind: "content",
+        content: status,
+        scope: "git-status"
+    });
+    if (decision.action === "block") {
+        return "Sensitive-looking Git status text was omitted.";
+    }
+    const redacted = redactSecrets(status).replace(/\r\n/g, "\n").trim();
+    return redacted.length <= MAX_GIT_STATUS_CHARS
+        ? redacted || "Working tree is clean."
+        : `${redacted.slice(0, MAX_GIT_STATUS_CHARS - 14)}\n[truncated]`;
+}
+async function writeCompactSnapshot(options) {
+    const path = loopPath(options.root, options.harness, "loop-state.md");
+    const status = boundedSnapshot(await options.gitStatus(options.root));
+    await withPrivateFileLock(path, options.root, async () => {
+        const source = await readPrivateFile(path, options.root);
+        const baseline = source ?? "# Loop state\n";
+        const content = [
+            "Last compaction snapshot (bounded and redacted).",
+            `Captured: ${options.now}`,
+            "",
+            "## Git status",
+            status
+        ].join("\n");
+        await writePrivateFile(path, applyManagedBlock(baseline, {
+            id: LOOP_SNAPSHOT_ID,
+            version: 1,
+            content
+        }), options.root);
+    });
+}
+function sessionContext(goal, telemetryEntries) {
+    return boundedContext([
+        "agent-ops project loop is active.",
+        "",
+        "Current goal:",
+        goal,
+        "",
+        `Telemetry: ${telemetryEntries} recent redacted event(s).`
+    ].join("\n"));
+}
+function sessionOutput(harness, context) {
+    return {
+        exitCode: 0,
+        stdout: JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "SessionStart",
+                additionalContext: context
+            }
+        }),
+        stderr: ""
+    };
+}
+/**
+ * Generic project-local loop policy. It deliberately reads only documented
+ * hook fields and records outcome identifiers, never prompts or command text.
+ */
+export async function runProjectLoop(options) {
+    let decision = {
+        blocked: false,
+        outcome: "observed",
+        code: "loop-observed",
+        denial: "none"
+    };
+    const scope = inputCwd(options.input) ?? options.root ?? ".";
+    try {
+        if (options.event === "UserPromptSubmit") {
+            decision = evaluatePrompt(options.input, scope);
+        }
+        else if (options.event === "PreToolUse") {
+            decision = evaluateBash(options.input, scope);
+        }
+        else if (options.event === "PermissionRequest") {
+            decision = {
+                blocked: false,
+                outcome: "observed",
+                code: requestedSandboxPermission(options.input) === "require_escalated"
+                    ? "permission-escalated"
+                    : "permission-pending",
+                denial: "none"
+            };
+        }
+    }
+    catch {
+        return noOutput();
+    }
+    const root = await resolveLoopRoot(options.input, options.root, options.harness).catch(() => null);
+    if (root !== null) {
+        await appendTelemetry({
+            root,
+            harness: options.harness,
+            event: options.event,
+            decision,
+            ...(options.now === undefined ? {} : { now: options.now }),
+            ...(options.telemetryMaxBytes === undefined
+                ? {}
+                : { maxBytes: options.telemetryMaxBytes })
+        }).catch(() => undefined);
+    }
+    if (decision.blocked) {
+        return decision.denial === "secret"
+            ? secretDenial(options.harness, options.event)
+            : commandDenial(options.harness, options.event, decision.code);
+    }
+    if (options.event === "PreCompact" && root !== null) {
+        await writeCompactSnapshot({
+            root,
+            harness: options.harness,
+            now: options.now?.() ?? new Date().toISOString(),
+            gitStatus: options.gitStatus ?? defaultGitStatus
+        }).catch(() => undefined);
+    }
+    if (options.event === "SessionStart" && root !== null) {
+        try {
+            const [goal, telemetryEntries] = await Promise.all([
+                readPrivateFile(loopPath(root, options.harness, "loop-goal.md"), root),
+                telemetryCount(root, options.harness)
+            ]);
+            return sessionOutput(options.harness, sessionContext(safeGoalContext(goal), telemetryEntries));
+        }
+        catch {
+            return noOutput();
+        }
+    }
+    return noOutput();
+}

package/dist/runtime/src/install/codex-loop.js

@@ -0,0 +1,139 @@
+import { AgentOpsError } from "../fs/paths.js";
+export const LOOP_MARKER_ID = "loop-state";
+export const LOOP_MARKER_VERSION = 1;
+const LOOP_HARNESSES = new Set(["claude", "codex"]);
+const CODEX_CONFIG_SEED = [
+    "# Created by agent-ops for the project-local loop.",
+    "# This file remains user-owned after installation.",
+    "[features]",
+    "hooks = true",
+    ""
+].join("\n");
+const GOAL_SEED = [
+    "# Current goal",
+    "",
+    "Describe the current objective, acceptance criteria, and important constraints.",
+    ""
+].join("\n");
+const STATE_SEED = [
+    "# Loop state",
+    "",
+    "Status: idle",
+    ""
+].join("\n");
+function isLoopHarness(value) {
+    return LOOP_HARNESSES.has(value);
+}
+export function selectedLoopHarnesses(harnesses) {
+    return harnesses.filter(isLoopHarness);
+}
+function loopRoot(harness) {
+    return `.${harness}`;
+}
+export function loopLauncherPath(harness) {
+    return `${loopRoot(harness)}/hooks/agent-ops-loop.sh`;
+}
+export function loopLauncherArtifactId(harness) {
+    return `${harness}-loop-launcher`;
+}
+function assertRuntimePath(runtimePath) {
+    if (runtimePath.length === 0 ||
+        runtimePath.length > 4096 ||
+        /[\0\r\n]/u.test(runtimePath) ||
+        !runtimePath.endsWith("hook-entry.js")) {
+        throw new AgentOpsError("LOOP_RUNTIME_PATH_INVALID", "The loop runtime path must name a safe hook-entry.js file.");
+    }
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+function loopEntryPath(hookRuntimePath) {
+    assertRuntimePath(hookRuntimePath);
+    return `${hookRuntimePath.slice(0, -"hook-entry.js".length)}loop-entry.js`;
+}
+export function buildLoopLauncher(harness, hookRuntimePath) {
+    const runtimePath = loopEntryPath(hookRuntimePath);
+    return [
+        "#!/usr/bin/env bash",
+        `# agent-ops: generated ${harness} loop v1`,
+        "set -uo pipefail",
+        `exec node ${shellQuote(runtimePath)} ${harness} "$@"`,
+        ""
+    ].join("\n");
+}
+function statePaths(harness) {
+    const root = loopRoot(harness);
+    return [
+        `${root}/loop-goal.md`,
+        `${root}/loop-state.md`,
+        `${root}/loop-telemetry.jsonl`
+    ];
+}
+export function loopSeeds(harnesses) {
+    const seeds = [];
+    for (const harness of selectedLoopHarnesses(harnesses)) {
+        const root = loopRoot(harness);
+        if (harness === "codex") {
+            seeds.push({ path: `${root}/config.toml`, content: CODEX_CONFIG_SEED });
+        }
+        seeds.push({ path: `${root}/loop-goal.md`, content: GOAL_SEED }, { path: `${root}/loop-state.md`, content: STATE_SEED }, { path: `${root}/loop-telemetry.jsonl`, content: "" });
+    }
+    return seeds;
+}
+export function loopIgnoreContent(harnesses) {
+    return selectedLoopHarnesses(harnesses)
+        .flatMap((harness) => statePaths(harness))
+        .join("\n");
+}
+/**
+ * This is intentionally narrower than a TOML parser: only an unambiguous
+ * boolean assignment inside the exact [features] table is a conflict. Other
+ * configuration remains user-owned and is never normalized or rewritten.
+ */
+export function codexHooksExplicitlyDisabled(source) {
+    let inFeatures = false;
+    for (const rawLine of source.split(/\r?\n/u)) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith("#")) {
+            continue;
+        }
+        const section = /^\[([^\]]+)\]\s*(?:#.*)?$/u.exec(line);
+        if (section !== null) {
+            inFeatures = section[1] === "features";
+            continue;
+        }
+        if (inFeatures &&
+            /^hooks\s*=\s*false\s*(?:#.*)?$/u.test(line)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function planLoopContribution(options) {
+    if (!options.capabilities.includes("project-loop")) {
+        return { artifacts: [], blocks: [] };
+    }
+    const harnesses = selectedLoopHarnesses(options.harnesses);
+    if (options.scope !== "project" || harnesses.length === 0) {
+        throw new AgentOpsError("LOOP_PROFILE_UNSUPPORTED", "The loop profile requires project scope and the Codex or Claude harness.");
+    }
+    if (options.hookRuntimePath === undefined) {
+        throw new AgentOpsError("LOOP_RUNTIME_REQUIRED", "The loop profile requires the installed hook runtime path.");
+    }
+    return {
+        artifacts: harnesses.map((harness) => ({
+            id: loopLauncherArtifactId(harness),
+            path: loopLauncherPath(harness),
+            content: buildLoopLauncher(harness, options.hookRuntimePath ?? "")
+        })),
+        blocks: [
+            {
+                id: LOOP_MARKER_ID,
+                path: ".gitignore",
+                version: LOOP_MARKER_VERSION,
+                markerStyle: "hash",
+                content: loopIgnoreContent(harnesses)
+            }
+        ]
+    };
+}

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

@@ -6,8 +6,8 @@ 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 { harnessDescriptor, managedRules } from "./harness.js";
+import { resolveCapabilities, 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];
@@ -124,25 +124,81 @@ async function checkConfig(root) {
 }
 async function checkArtifacts(root, manifest) {
     if (manifest === undefined) {
-        return check("artifacts", "FAIL", "Artifacts cannot be verified without a valid manifest.");
+        return {
+            check: check("artifacts", "FAIL", "Artifacts cannot be verified without a valid manifest."),
+            hashesByPath: new Map()
+        };
     }
     const failures = [];
+    const hashesByPath = new Map();
     for (const artifact of manifest.artifacts) {
         try {
             const content = await readContained(root, artifact.path);
-            if (sha256(content) !== artifact.hash ||
+            const hash = sha256(content);
+            if (hash !== artifact.hash ||
                 (artifact.id === "opencode-plugin" &&
                     !isOpencodeManagedPlugin(content.toString("utf8")))) {
                 failures.push(artifact.path);
             }
+            else {
+                hashesByPath.set(artifact.path, hash);
+            }
         }
         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(", ")}.`);
+    return {
+        check: failures.length === 0
+            ? check("artifacts", "PASS", "All managed artifacts match their hashes.")
+            : check("artifacts", "FAIL", `Managed artifacts failed verification: ${failures.join(", ")}.`),
+        hashesByPath
+    };
+}
+function checkArtifactStaleness(manifest, config, artifacts, toolkitVersion) {
+    if (manifest === undefined || config === undefined) {
+        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness cannot be assessed without a valid manifest and configuration.");
+    }
+    if (artifacts.check.status !== "PASS") {
+        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness cannot be assessed until artifact integrity passes.");
+    }
+    if (toolkitVersion === undefined) {
+        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness cannot be assessed without the running toolkit version.");
+    }
+    const expectedHashesByPath = new Map();
+    try {
+        const resolved = config.profiles.length === 0
+            ? { profiles: [], capabilities: [] }
+            : resolveCapabilities(config);
+        for (const id of manifest.harness) {
+            const descriptor = harnessDescriptor(id);
+            const path = `.agent-ops/${descriptor.control.instructionFile}`;
+            if (!expectedHashesByPath.has(path)) {
+                expectedHashesByPath.set(path, sha256(managedRules(descriptor, {
+                    scope: manifest.scope,
+                    profiles: resolved.profiles,
+                    capabilities: resolved.capabilities,
+                    toolkitVersion
+                })));
+            }
+        }
+    }
+    catch {
+        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness could not be assessed safely.");
+    }
+    const stalePaths = [];
+    for (const [path, expectedHash] of expectedHashesByPath) {
+        const actualHash = artifacts.hashesByPath.get(path);
+        if (actualHash === undefined) {
+            return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness could not be assessed safely.");
+        }
+        if (actualHash !== expectedHash) {
+            stalePaths.push(path);
+        }
+    }
+    return stalePaths.length === 0
+        ? check("artifact-staleness", "PASS", "Managed artifacts match the current toolkit and configuration.")
+        : check("artifact-staleness", "DEGRADED", `Managed artifacts need update: ${stalePaths.join(", ")}; run agent-ops update.`, "UPDATE_REQUIRED");
 }
 async function checkMarkers(root, manifest) {
     if (manifest === undefined) {
@@ -285,12 +341,14 @@ async function checkRegistrationDrift(root, manifest, config) {
 export async function doctorInstallation(options) {
     const manifest = await checkManifest(options.root);
     const config = await checkConfig(options.root);
+    const artifacts = await checkArtifacts(options.root, manifest.manifest);
     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),
+        artifacts.check,
+        checkArtifactStaleness(manifest.manifest, config.config, artifacts, options.toolkitVersion),
         await checkMarkers(options.root, manifest.manifest),
         surfaceInventory.check,
         await checkRegistrationDrift(options.root, manifest.manifest, config.config),