@kylecheng3146/agent-ops 0.1.1 → 0.1.3

package/dist/packages/cli/src/context.js

@@ -0,0 +1,102 @@
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadConfigFile } from "../../../runtime/src/config/load.js";
+import { mergeConfigLayers } from "../../../runtime/src/config/merge.js";
+import { sha256 } from "../../../runtime/src/fs/hash.js";
+import { AgentOpsError } from "../../../runtime/src/fs/paths.js";
+import { localStatePaths } from "../../../runtime/src/security/permissions.js";
+import { calculateTrustBinding, FileTrustStore } from "../../../runtime/src/security/trust.js";
+export const DEFAULT_CONFIG = {
+    schemaVersion: 1,
+    profiles: [],
+    verification: { commands: [] },
+    pathMappings: [],
+    securityExceptions: []
+};
+function defaultConfigLayer() {
+    return {
+        source: "default",
+        sourcePath: "built-in defaults",
+        config: DEFAULT_CONFIG
+    };
+}
+async function loadOptionalConfig(path) {
+    try {
+        return await loadConfigFile(path);
+    }
+    catch (error) {
+        if (error instanceof AgentOpsError &&
+            error.code === "CONFIG_READ_FAILED" &&
+            typeof error.cause === "object" &&
+            error.cause !== null &&
+            "code" in error.cause &&
+            error.cause.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function loadEffectiveConfig(root, scope) {
+    const home = process.env.AGENT_OPS_HOME ?? homedir();
+    const userPath = join(home, ".agent-ops", "config.json");
+    const projectPath = join(root, ".agent-ops", "config.json");
+    const layers = [defaultConfigLayer()];
+    if (scope === "user") {
+        const user = await loadOptionalConfig(userPath);
+        if (user !== null) {
+            layers.push({
+                source: "user",
+                sourcePath: user.sourcePath,
+                config: user.config
+            });
+        }
+        return mergeConfigLayers(layers);
+    }
+    if (projectPath !== userPath) {
+        const user = await loadOptionalConfig(userPath);
+        if (user !== null) {
+            layers.push({
+                source: "user",
+                sourcePath: user.sourcePath,
+                config: user.config
+            });
+        }
+    }
+    const project = await loadOptionalConfig(projectPath);
+    if (project !== null) {
+        layers.push({
+            source: "project",
+            sourcePath: project.sourcePath,
+            config: project.config
+        });
+    }
+    return mergeConfigLayers(layers);
+}
+export function repositoryRemoteUrl(root) {
+    try {
+        return execFileSync("git", ["config", "--get", "remote.origin.url"], {
+            cwd: root,
+            encoding: "utf8"
+        }).trim();
+    }
+    catch {
+        return `local:${root}`;
+    }
+}
+export async function repositoryTrust(root, config, cliVersion) {
+    const home = process.env.AGENT_OPS_HOME ?? homedir();
+    const state = localStatePaths(home);
+    try {
+        const binding = await calculateTrustBinding({
+            repositoryPath: root,
+            remoteUrl: repositoryRemoteUrl(root),
+            configHash: sha256(JSON.stringify(config)),
+            runtimeHash: sha256(cliVersion)
+        });
+        return (await new FileTrustStore(state.trustStore, state.anchorDirectory).status(binding)).status;
+    }
+    catch {
+        return "UNTRUSTED";
+    }
+}

package/dist/packages/cli/src/hook-entry.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Entry point registered in Claude settings as:
+//   node <this file> <harness> <event> --managed-by=agent-ops
+import { CLI_VERSION } from "./version.js";
+import { runHookProcess } from "./hook-process.js";
+process.exitCode = await runHookProcess(process.argv.slice(2), {
+    stdin: process.stdin,
+    writeStdout: (value) => process.stdout.write(value),
+    writeStderr: (value) => process.stderr.write(value)
+}, CLI_VERSION);

package/dist/packages/cli/src/hook-process.js

@@ -0,0 +1,54 @@
+import { runHookCommand, HOOK_EVENTS } from "./commands/hook.js";
+import { loadEffectiveConfig, repositoryTrust } from "./context.js";
+const HARNESSES = new Set(["codex", "claude"]);
+const MAX_HOOK_INPUT_BYTES = 1024 * 1024;
+async function readStdin(stream) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk)
+            ? chunk
+            : Buffer.from(String(chunk), "utf8");
+        total += buffer.byteLength;
+        if (total > MAX_HOOK_INPUT_BYTES) {
+            return "";
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks, total).toString("utf8");
+}
+/**
+ * Runs one hook invocation. Always resolves to exit code 0: a hook that
+ * cannot answer must never block the harness it advises.
+ */
+export async function runHookProcess(argv, io, cliVersion) {
+    const [harness, event] = argv;
+    if (harness === undefined ||
+        !HARNESSES.has(harness) ||
+        event === undefined ||
+        !HOOK_EVENTS.includes(event)) {
+        io.writeStderr("Usage: agent-ops hook <codex|claude> <SessionStart|PreToolUse|Stop>\n");
+        return 0;
+    }
+    try {
+        const root = process.cwd();
+        const config = (await loadEffectiveConfig(root, "project")).config;
+        const output = await runHookCommand({
+            harness: harness,
+            event: event,
+            stdin: await readStdin(io.stdin),
+            config,
+            trusted: (await repositoryTrust(root, config, cliVersion)) === "TRUSTED"
+        });
+        if (output.stdout.length > 0) {
+            io.writeStdout(output.stdout);
+        }
+        if (output.stderr.length > 0) {
+            io.writeStderr(output.stderr);
+        }
+    }
+    catch {
+        // ponytail: fail-open by design; hook failures stay invisible to the harness.
+    }
+    return 0;
+}

package/dist/packages/cli/src/ui.js

@@ -0,0 +1,132 @@
+// figlet "agent-ops" -f Standard, trimmed of trailing blank lines/columns.
+const BANNER = [
+    "                         _",
+    "   __ _  __ _  ___ _ __ | |_       ___  _ __  ___ ",
+    "  / _\` |/ _\` |/ _ \\ '_ \\| __|____ / _ \\| '_ \\/ __|",
+    " | (_| | (_| |  __/ | | | ||_____| (_) | |_) \\__ \\",
+    "  \\__,_|\\__, |\\___|_| |_|\\__|     \\___/| .__/|___/",
+    "        |___/                          |_|"
+].join("\n");
+const TAGLINE = "loop engineering toolkit";
+const MIN_BANNER_COLUMNS = 54;
+const RAIL = "\u2502";
+const DIAMOND = "\u25c6";
+const DOT_ON = "\u25cf";
+const DOT_OFF = "\u25cb";
+function envColorPreference() {
+    if (process.env.NO_COLOR !== undefined) {
+        return "off";
+    }
+    if (process.env.FORCE_COLOR !== undefined) {
+        return "on";
+    }
+    return undefined;
+}
+function useColor(output) {
+    const preference = envColorPreference();
+    return preference === undefined ? output.isTTY : preference === "on";
+}
+function paint(output, code, text) {
+    return useColor(output) ? `\u001b[${code}m${text}\u001b[0m` : text;
+}
+const dim = (output, text) => paint(output, "2", text);
+const bold = (output, text) => paint(output, "1", text);
+const green = (output, text) => paint(output, "32", text);
+const cyan = (output, text) => paint(output, "36", text);
+/**
+ * Decorative only: skipped for --json output, non-interactive runs, and
+ * terminals too narrow to render the wordmark without wrapping.
+ */
+export function writeBanner(output) {
+    if (!output.isTTY || (output.columns ?? 0) < MIN_BANNER_COLUMNS) {
+        return;
+    }
+    output.write(`${cyan(output, BANNER)}\n${dim(output, TAGLINE)}\n\n`);
+}
+function eraseLines(write, count) {
+    for (let index = 0; index < count; index += 1) {
+        write("\u001b[1A\u001b[2K");
+    }
+}
+function renderChoice(outputLike, question, value) {
+    const yes = value
+        ? bold(outputLike, green(outputLike, `${DOT_ON} Yes`))
+        : dim(outputLike, `${DOT_OFF} Yes`);
+    const no = !value
+        ? bold(outputLike, green(outputLike, `${DOT_ON} No`))
+        : dim(outputLike, `${DOT_OFF} No`);
+    return [
+        `${bold(outputLike, DIAMOND)}  ${question}`,
+        `${dim(outputLike, RAIL)}  ${yes} / ${no}`
+    ].join("\n");
+}
+async function typedFallback(question, io, defaultValue) {
+    const { createInterface } = await import("node:readline/promises");
+    const readline = createInterface({ input: io.input, output: io.output });
+    try {
+        const suffix = defaultValue ? "Y/n" : "y/N";
+        const answer = (await readline.question(`${question} [${suffix}]: `)).trim().toLowerCase();
+        if (answer === "") {
+            return defaultValue;
+        }
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        readline.close();
+    }
+}
+/**
+ * Arrow-key Yes/No selector. Falls back to a typed y/N prompt when stdin
+ * cannot enter raw mode (piped input, or a stub stream in tests), so the
+ * same call works under both a real terminal and test harnesses.
+ */
+export async function selectYesNo(question, io, defaultValue = false) {
+    if (typeof io.input.setRawMode !== "function" ||
+        io.input.isTTY !== true) {
+        return await typedFallback(question, io, defaultValue);
+    }
+    const outputLike = {
+        isTTY: true,
+        columns: io.output.columns,
+        write: (value) => io.output.write(value)
+    };
+    const { emitKeypressEvents } = await import("node:readline");
+    emitKeypressEvents(io.input);
+    io.input.setRawMode(true);
+    io.input.resume();
+    let value = defaultValue;
+    let rendered = renderChoice(outputLike, question, value);
+    io.output.write(`${rendered}\n`);
+    return await new Promise((resolve) => {
+        const cleanup = () => {
+            io.input.setRawMode?.(false);
+            io.input.pause();
+            io.input.removeListener("keypress", onKeypress);
+        };
+        const redraw = () => {
+            eraseLines((value_) => io.output.write(value_), rendered.split("\n").length);
+            rendered = renderChoice(outputLike, question, value);
+            io.output.write(`${rendered}\n`);
+        };
+        const onKeypress = (_chunk, key) => {
+            if (key?.ctrl === true && key.name === "c") {
+                cleanup();
+                process.exit(130);
+            }
+            if (key?.name === "left" ||
+                key?.name === "right" ||
+                key?.name === "tab" ||
+                key?.name === "h" ||
+                key?.name === "l") {
+                value = !value;
+                redraw();
+                return;
+            }
+            if (key?.name === "return" || key?.name === "space") {
+                cleanup();
+                resolve(value);
+            }
+        };
+        io.input.on("keypress", onKeypress);
+    });
+}

package/dist/packages/cli/src/version.js

@@ -0,0 +1,3 @@
+// Single source of the published CLI version. Release preparation updates
+// this constant; bin.ts and the hook entry both read it from here.
+export const CLI_VERSION = "0.1.3";

package/dist/runtime/src/adapters/claude/config.js

@@ -83,6 +83,25 @@ function hookRecord(settings) {
     }
     return settings.hooks;
 }
+/**
+ * Removes every agent-ops owned handler and leaves foreign hooks untouched.
+ */
+export function stripClaudeManagedHooks(existing) {
+    if (!isRecord(existing)) {
+        throw new AgentOpsError("CLAUDE_SETTINGS_INVALID", "Claude settings must be a JSON object.");
+    }
+    const existingHooks = hookRecord(existing);
+    const hooks = {};
+    for (const [eventName, groups] of Object.entries(existingHooks)) {
+        const preserved = groups
+            .map(withoutOwnedHandlers)
+            .filter((group) => group !== null);
+        if (preserved.length > 0) {
+            hooks[eventName] = preserved;
+        }
+    }
+    return { ...existing, hooks };
+}
 export function mergeClaudeSettings(existing, managed) {
     if (!isRecord(existing)) {
         throw new AgentOpsError("CLAUDE_SETTINGS_INVALID", "Claude settings must be a JSON object.");

package/dist/runtime/src/adapters/codex/config.js

@@ -67,6 +67,22 @@ function hookRecord(value) {
     }
     return value.hooks;
 }
+/**
+ * Removes every agent-ops owned handler and leaves foreign hooks untouched.
+ */
+export function stripCodexManagedHooks(existing) {
+    const existingHooks = hookRecord(existing);
+    const hooks = {};
+    for (const [eventName, groups] of Object.entries(existingHooks)) {
+        const preserved = groups
+            .map(withoutOwnedHandlers)
+            .filter((group) => group !== null);
+        if (preserved.length > 0) {
+            hooks[eventName] = preserved;
+        }
+    }
+    return { ...existing, hooks };
+}
 export function mergeCodexHookConfig(existing, managed) {
     if (!isRecord(existing)) {
         throw new AgentOpsError("CODEX_HOOK_CONFIG_INVALID", "Codex hook configuration must be a JSON object.");

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

@@ -6,6 +6,17 @@ import { fileURLToPath } from "node:url";
 import { sha256 } from "./hash.js";
 import { AgentOpsError, resolveContainedPath } from "./paths.js";
 export { AgentOpsError } from "./paths.js";
+/**
+ * Identity must come from bigint stats. Windows file indexes pack a sequence
+ * number above the 2^53 boundary, so a numeric `ino` silently rounds and an
+ * untouched file looks like it changed.
+ */
+export function fileIdentity(status) {
+    return {
+        device: status.dev.toString(),
+        inode: status.ino.toString()
+    };
+}
 const MUTATION_WORKER_PATH = fileURLToPath(new URL("./mutation-worker.js", import.meta.url));
 function isMissing(error) {
     return (typeof error === "object" &&
@@ -25,10 +36,11 @@ async function captureParentGuard(parent) {
         normalizedPath(canonicalPath) !== normalizedPath(parent)) {
         throw new AgentOpsError("PRECONDITION_CHANGED", `Destination directory changed before mutation: ${parent}`);
     }
+    const identity = fileIdentity(status);
     return {
         expectedParentPath: canonicalPath,
-        parentDevice: status.dev.toString(),
-        parentInode: status.ino.toString()
+        parentDevice: identity.device,
+        parentInode: identity.inode
     };
 }
 async function runAnchoredMutation(targetPath, action, expectedHash, content, mode) {
@@ -162,20 +174,21 @@ async function createBackup(snapshot, recoveryDirectory) {
 async function snapshotOperation(root, operation) {
     const targetPath = await resolveContainedPath(root, operation.path);
     try {
-        const status = await lstat(targetPath);
+        const status = await lstat(targetPath, { bigint: true });
         if (!status.isFile()) {
             throw new AgentOpsError("UNSUPPORTED_FILE_TYPE", `Managed target must be a regular file: ${operation.path}`);
         }
         const content = await readFile(targetPath);
+        const identity = fileIdentity(status);
         return {
             operation,
             targetPath,
             existed: true,
             content,
-            mode: status.mode & 0o777,
+            mode: Number(status.mode) & 0o777,
             actualHash: sha256(content),
-            device: status.dev.toString(),
-            inode: status.ino.toString(),
+            device: identity.device,
+            inode: identity.inode,
             backupPath: null,
             createdDirectories: []
         };
@@ -219,10 +232,7 @@ async function currentIdentity(path) {
         if (!status.isFile() || status.isSymbolicLink()) {
             throw new AgentOpsError("PRECONDITION_CHANGED", `A managed path is no longer a regular file: ${path}`);
         }
-        return {
-            device: status.dev.toString(),
-            inode: status.ino.toString()
-        };
+        return fileIdentity(status);
     }
     catch (error) {
         if (isMissing(error)) {

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

@@ -165,9 +165,13 @@ async function checkProbe(id, probe) {
         return check(id, "UNKNOWN", "No probe was provided.");
     }
     try {
-        return (await probe())
-            ? check(id, "PASS", "Probe passed.")
-            : check(id, "FAIL", "Probe failed.");
+        const result = await probe();
+        const status = typeof result === "boolean" ? (result ? "PASS" : "FAIL") : result;
+        return check(id, status, status === "PASS"
+            ? "Probe passed."
+            : status === "FAIL"
+                ? "Probe failed."
+                : "Probe has nothing to verify yet.");
     }
     catch {
         return check(id, "FAIL", "Probe failed.");

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

@@ -57,7 +57,7 @@ export function commonHarnessAdapters() {
         };
     });
 }
-function requestedHarnessIds(harness) {
+export function requestedHarnessIds(harness) {
     return harness === "both" ? ["codex", "claude"] : [harness];
 }
 function selectAdapter(id, adapters) {

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

@@ -0,0 +1,77 @@
+import { buildClaudeHookSettings, mergeClaudeSettings, stripClaudeManagedHooks } from "../adapters/claude/config.js";
+import { buildCodexHookConfig, mergeCodexHookConfig, stripCodexManagedHooks } from "../adapters/codex/config.js";
+import { AgentOpsError } from "../fs/paths.js";
+export const CLAUDE_HOOK_PATH = ".claude/settings.json";
+export const CODEX_HOOK_PATH = ".codex/hooks.json";
+function format(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function parseSettings(path, source) {
+    if (source === null || source.trim().length === 0) {
+        return {};
+    }
+    try {
+        return JSON.parse(source);
+    }
+    catch (error) {
+        throw new AgentOpsError("HOOK_SETTINGS_INVALID_JSON", `Hook settings are not valid JSON: ${path}`, { cause: error });
+    }
+}
+export function hookRegistrationPath(harness, scope) {
+    // ponytail: user scope resolves against AGENT_OPS_HOME, so the same
+    // relative path serves both scopes.
+    void scope;
+    return harness === "claude" ? CLAUDE_HOOK_PATH : CODEX_HOOK_PATH;
+}
+/**
+ * Builds the merged settings file for one harness, preserving foreign hooks.
+ * Returns null when the selected capabilities register no events at all.
+ */
+export function planHookRegistration(options) {
+    const path = hookRegistrationPath(options.harness, options.scope);
+    const managed = options.harness === "claude"
+        ? buildClaudeHookSettings(options.capabilities, options.runtimePath)
+        : buildCodexHookConfig(options.capabilities);
+    const events = Object.keys(managed.hooks);
+    if (events.length === 0) {
+        return null;
+    }
+    const existing = parseSettings(path, options.currentSource);
+    const merged = options.harness === "claude"
+        ? mergeClaudeSettings(existing, managed)
+        : mergeCodexHookConfig(existing, managed);
+    return {
+        content: format(merged),
+        record: {
+            id: `${options.harness}-hooks`,
+            path,
+            harness: options.harness,
+            events,
+            owner: "agent-ops"
+        }
+    };
+}
+function onlyManagedRemains(harness, value) {
+    const ownKeys = new Set(harness === "codex" ? ["hooks", "description"] : ["hooks"]);
+    const hooks = value.hooks;
+    return (Object.keys(value).every((key) => ownKeys.has(key)) &&
+        typeof hooks === "object" &&
+        hooks !== null &&
+        Object.keys(hooks).length === 0);
+}
+/**
+ * Strips owned handlers from a hook settings file. The file is removed only
+ * when nothing but agent-ops content is left, so foreign settings survive.
+ */
+export function planHookRemoval(record, currentSource) {
+    const existing = parseSettings(record.path, currentSource);
+    const stripped = record.harness === "claude"
+        ? stripClaudeManagedHooks(existing)
+        : stripCodexManagedHooks(existing);
+    return {
+        path: record.path,
+        content: onlyManagedRemains(record.harness, stripped)
+            ? null
+            : format(stripped)
+    };
+}

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

@@ -1,6 +1,7 @@
 import { applyManagedBlock, managedBlockMarkers } from "../fs/managed-block.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { COMMON_AGENTS_BLOCK, COMMON_CLAUDE_BLOCK } from "./harness.js";
+import { hookRegistrationPath } from "./hooks.js";
 function selectedHarnesses(manifest) {
     return manifest.harness === "both"
         ? ["codex", "claude"]
@@ -24,6 +25,24 @@ function expectedMarker(manifest, id) {
 function manifestOwnershipError() {
     return new AgentOpsError("MANIFEST_OWNERSHIP_INVALID", "The manifest does not match a supported managed installation shape.");
 }
+/**
+ * Hook records are optional: installations without hook capabilities, and
+ * manifests written before hook registration existed, carry none.
+ */
+function assertSupportedHookRecords(manifest, harnesses) {
+    const selected = new Set(harnesses);
+    const seen = new Set();
+    for (const hook of manifest.hooks ?? []) {
+        if (!selected.has(hook.harness) ||
+            seen.has(hook.harness) ||
+            hook.id !== `${hook.harness}-hooks` ||
+            hook.path !== hookRegistrationPath(hook.harness, manifest.scope) ||
+            hook.events.length === 0) {
+            throw manifestOwnershipError();
+        }
+        seen.add(hook.harness);
+    }
+}
 export function assertSupportedManifestOwnership(manifest) {
     const harnesses = selectedHarnesses(manifest);
     const expectedArtifacts = new Map([
@@ -53,6 +72,7 @@ export function assertSupportedManifestOwnership(manifest) {
             throw manifestOwnershipError();
         }
     }
+    assertSupportedHookRecords(manifest, harnesses);
     return expectedMarkers;
 }
 function exactMarkerCount(source, marker) {

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

@@ -5,7 +5,8 @@ import { applyManagedBlock, managedBlockMarkers } from "../fs/managed-block.js";
 import { formatInstallManifest, parseInstallManifest } from "../fs/manifest.js";
 import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
 import { validateConfig } from "../schema/validate.js";
-import { planHarnessContributions } from "./harness.js";
+import { planHarnessContributions, requestedHarnessIds } from "./harness.js";
+import { hookRegistrationPath, planHookRegistration } from "./hooks.js";
 import { resolveProfiles } from "./profiles.js";
 const CONFIG_PATH = ".agent-ops/config.json";
 const MANIFEST_PATH = ".agent-ops/manifest.json";
@@ -233,12 +234,36 @@ export async function createInstallPlan(options) {
     }
     const plannedBlocks = await planBlocks(options.root, contribution.blocks);
     operations.push(...plannedBlocks.operations);
+    const hooks = [];
+    if (options.hookRuntimePath !== undefined) {
+        for (const harness of requestedHarnessIds(options.harness)) {
+            const current = await readCurrentFile(options.root, hookRegistrationPath(harness, options.scope));
+            const planned = planHookRegistration({
+                harness,
+                scope: options.scope,
+                capabilities: resolved.capabilities,
+                runtimePath: options.hookRuntimePath,
+                currentSource: current?.content ?? null
+            });
+            if (planned === null) {
+                continue;
+            }
+            operations.push({
+                kind: "write",
+                path: planned.record.path,
+                content: planned.content,
+                expectedHash: current?.hash ?? null
+            });
+            hooks.push(planned.record);
+        }
+    }
     const manifest = {
         schemaVersion: SCHEMA_VERSION,
         scope: options.scope,
         harness: options.harness,
         artifacts,
-        markers: plannedBlocks.records
+        markers: plannedBlocks.records,
+        ...(hooks.length === 0 ? {} : { hooks })
     };
     operations.push({
         kind: "write",