@kylecheng3146/agent-ops 0.1.4 → 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/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/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)
+            }
+        ]
+    };
+}