@kylecheng3146/agent-ops 0.1.5 → 0.1.7

package/dist/runtime/src/fs/managed-block.js

@@ -7,37 +7,54 @@ function assertBlockId(id) {
         throw new AgentOpsError("INVALID_BLOCK_ID", `Invalid block ID: ${id}`);
     }
 }
-function assertExactMarkerSyntax(source) {
-    const validMarker = /^<!-- agent-ops:(?:start [a-z][a-z0-9-]{0,127} v[1-9][0-9]*|end [a-z][a-z0-9-]{0,127}) -->$/;
+function assertExactMarkerSyntax(source, markerStyle) {
+    const validMarker = markerStyle === "html"
+        ? /^<!-- agent-ops:(?:start [a-z][a-z0-9-]{0,127} v[1-9][0-9]*|end [a-z][a-z0-9-]{0,127}) -->$/
+        : /^# agent-ops:(?:start [a-z][a-z0-9-]{0,127} v[1-9][0-9]*|end [a-z][a-z0-9-]{0,127})$/;
+    const markerPrefix = markerStyle === "html"
+        ? /<!--\s*agent-ops:/
+        : /#\s*agent-ops:/;
     for (const line of source.split(/\r?\n/)) {
-        if (/<!--\s*agent-ops:/.test(line) && !validMarker.test(line)) {
+        if (markerPrefix.test(line) && !validMarker.test(line)) {
             throw new AgentOpsError("MALFORMED_MANAGED_BLOCK", "Managed block markers must use the exact agent-ops marker syntax.");
         }
     }
 }
-export function managedBlockMarkers(id, version) {
+export function managedBlockMarkers(id, version, markerStyle = "html") {
     assertBlockId(id);
     if (!Number.isSafeInteger(version) || version < 1) {
         throw new AgentOpsError("INVALID_BLOCK_VERSION", `Invalid block version: ${version}`);
     }
-    return {
-        start: `<!-- agent-ops:start ${id} v${version} -->`,
-        end: `<!-- agent-ops:end ${id} -->`
-    };
+    return markerStyle === "html"
+        ? {
+            start: `<!-- agent-ops:start ${id} v${version} -->`,
+            end: `<!-- agent-ops:end ${id} -->`
+        }
+        : {
+            start: `# agent-ops:start ${id} v${version}`,
+            end: `# agent-ops:end ${id}`
+        };
 }
-function locateMarkers(source, id, version) {
+function locateMarkers(source, id, version, markerStyle = "html") {
     assertBlockId(id);
-    assertExactMarkerSyntax(source);
+    assertExactMarkerSyntax(source, markerStyle);
     const escapedId = escapeRegExp(id);
+    const startPattern = markerStyle === "html"
+        ? `<!-- agent-ops:start ${escapedId} v[0-9]+ -->`
+        : `# agent-ops:start ${escapedId} v[0-9]+`;
+    const end = markerStyle === "html"
+        ? `<!-- agent-ops:end ${id} -->`
+        : `# agent-ops:end ${id}`;
     const startMatches = [
-        ...source.matchAll(new RegExp(`<!-- agent-ops:start ${escapedId} v[0-9]+ -->`, "g"))
+        ...source.matchAll(new RegExp(startPattern, "g"))
     ];
-    const end = `<!-- agent-ops:end ${id} -->`;
     const endMatches = [...source.matchAll(new RegExp(escapeRegExp(end), "g"))];
     if (startMatches.length === 0 && endMatches.length === 0) {
         return null;
     }
-    const expectedStart = version === undefined ? startMatches[0]?.[0] : managedBlockMarkers(id, version).start;
+    const expectedStart = version === undefined
+        ? startMatches[0]?.[0]
+        : managedBlockMarkers(id, version, markerStyle).start;
     const start = startMatches[0]?.[0];
     const startIndex = startMatches[0]?.index;
     const endIndex = endMatches[0]?.index;
@@ -54,16 +71,16 @@ function locateMarkers(source, id, version) {
     return { start, end, startIndex, endIndex };
 }
 function renderBlock(options) {
-    if (/<!--\s*agent-ops:/.test(options.content)) {
+    if (/(?:<!--|#)\s*agent-ops:/.test(options.content)) {
         throw new AgentOpsError("AMBIGUOUS_MANAGED_CONTENT", "Managed content must not contain agent-ops marker boundaries.");
     }
-    const { start, end } = managedBlockMarkers(options.id, options.version);
+    const { start, end } = managedBlockMarkers(options.id, options.version, options.markerStyle);
     const content = options.content.replace(/\r\n/g, "\n").replace(/\n+$/g, "");
     return `${start}\n${content}\n${end}`;
 }
 export function applyManagedBlock(source, options) {
     const block = renderBlock(options);
-    const located = locateMarkers(source, options.id, options.version);
+    const located = locateMarkers(source, options.id, options.version, options.markerStyle);
     if (located === null) {
         if (source.length === 0) {
             return `${block}\n`;
@@ -72,8 +89,8 @@ export function applyManagedBlock(source, options) {
     }
     return `${source.slice(0, located.startIndex)}${block}${source.slice(located.endIndex + located.end.length)}`;
 }
-export function removeManagedBlock(source, id) {
-    const located = locateMarkers(source, id);
+export function removeManagedBlock(source, id, markerStyle = "html") {
+    const located = locateMarkers(source, id, undefined, markerStyle);
     if (located === null) {
         return source;
     }

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)
+            }
+        ]
+    };
+}