@kylecheng3146/agent-ops 0.0.1

package/dist/runtime/src/guardrails/evaluate.js

@@ -0,0 +1,9 @@
+import { evaluateDestructiveCommand } from "./destructive.js";
+import { applySecurityExceptions } from "./exceptions.js";
+import { evaluateSecretContent } from "./secrets.js";
+export function evaluateGuardrail(input, options = {}) {
+    const decision = input.kind === "content"
+        ? evaluateSecretContent(input.content, input.scope)
+        : evaluateDestructiveCommand(input);
+    return applySecurityExceptions(decision, input.scope, options);
+}

package/dist/runtime/src/guardrails/exceptions.js

@@ -0,0 +1,49 @@
+const ID_PATTERN = /^[a-z][a-z0-9-]{0,127}$/;
+const WINDOWS_RESERVED_SEGMENT = /^(?:aux|com[1-9]|con|lpt[1-9]|nul|prn)(?:\..*)?$/i;
+function isBoundedProjectScope(scope) {
+    if (scope.length === 0 ||
+        scope === "." ||
+        scope.includes("\0") ||
+        scope.includes("\\") ||
+        scope.includes("*") ||
+        scope.includes("?") ||
+        scope.includes("[") ||
+        scope.startsWith("/") ||
+        /^[A-Za-z]:/.test(scope)) {
+        return false;
+    }
+    return scope.split("/").every((segment) => segment.length > 0 &&
+        segment !== "." &&
+        segment !== ".." &&
+        !segment.endsWith(".") &&
+        !WINDOWS_RESERVED_SEGMENT.test(segment) &&
+        /^[A-Za-z0-9._-]+$/.test(segment));
+}
+function scopeContains(exceptionScope, evaluatedScope) {
+    return (evaluatedScope === exceptionScope ||
+        evaluatedScope.startsWith(`${exceptionScope}/`));
+}
+export function isActiveSecurityException(exception, ruleId, scope, now) {
+    const expiresAt = Date.parse(exception.expiresAt);
+    return (ID_PATTERN.test(exception.ruleId) &&
+        exception.ruleId === ruleId &&
+        isBoundedProjectScope(exception.scope) &&
+        isBoundedProjectScope(scope) &&
+        scopeContains(exception.scope, scope) &&
+        exception.reason.trim().length > 0 &&
+        Number.isFinite(expiresAt) &&
+        Number.isFinite(now.getTime()) &&
+        expiresAt > now.getTime());
+}
+export function applySecurityExceptions(decision, scope, options) {
+    if (decision.action === "allow" || options.exceptions === undefined) {
+        return decision;
+    }
+    const now = options.now;
+    if (now === undefined) {
+        return decision;
+    }
+    return options.exceptions.some((exception) => isActiveSecurityException(exception, decision.ruleId, scope, now))
+        ? { action: "allow" }
+        : decision;
+}

package/dist/runtime/src/guardrails/secrets.js

@@ -0,0 +1,97 @@
+import { GUARDRAIL_RULE_IDS } from "./types.js";
+const PRIVATE_KEY_BLOCK = /-----BEGIN (PGP PRIVATE KEY BLOCK|(?:[A-Z0-9]+ )?PRIVATE KEY)-----([\s\S]*?)-----END \1-----/g;
+const KNOWN_TOKEN = /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9_-]{20,})\b/g;
+const SENSITIVE_ASSIGNMENT = /\b(?:[a-z0-9]+[_-])*(?:access[_-]?token|api[_-]?key|client[_-]?secret|private[_-]?key|secret[_-]?access[_-]?key|password|token)\b["']?\s*[:=]\s*(?:"([^"\r\n]*)"|'([^'\r\n]*)'|([^\s"'&;,}]+))/gi;
+const AUTHORIZATION_VALUE = /\bAuthorization\s*:\s*(?:Bearer|Basic|token)\s+([^\s,;]+)/gi;
+const PLACEHOLDER = /^(?:\[(?:REDACTED|REMOVED)(?:[_ -][A-Z0-9]+)*\]|<[^>]*(?:example|placeholder|redacted|replace|your)[^>]*>|(?:change-?me|example|placeholder|redacted|replace-?me|sample)|x{6,})$/i;
+const SYNTHETIC_DOCUMENTATION_LABEL = /^\s*(?:[#/*-]+\s*)?synthetic documentation example\s*:/i;
+function isPlaceholder(value) {
+    return PLACEHOLDER.test(value.trim());
+}
+function hasHighEntropy(value) {
+    if (value.length < 24 || value.length > 4_096 || /\s/.test(value)) {
+        return false;
+    }
+    const frequencies = new Map();
+    for (const character of value) {
+        frequencies.set(character, (frequencies.get(character) ?? 0) + 1);
+    }
+    let entropy = 0;
+    for (const count of frequencies.values()) {
+        const probability = count / value.length;
+        entropy -= probability * Math.log2(probability);
+    }
+    return frequencies.size >= 8 && entropy >= 3;
+}
+function blocksPrivateKey(content) {
+    for (const match of content.matchAll(PRIVATE_KEY_BLOCK)) {
+        const body = match[2]?.trim() ?? "";
+        if (!isPlaceholder(body)) {
+            return true;
+        }
+    }
+    return false;
+}
+function blocksKnownToken(content) {
+    for (const match of content.matchAll(KNOWN_TOKEN)) {
+        const token = match[0];
+        if (!isPlaceholder(token)) {
+            return true;
+        }
+    }
+    return false;
+}
+function blocksSensitiveValue(content) {
+    for (const match of content.matchAll(SENSITIVE_ASSIGNMENT)) {
+        const value = match[1] ?? match[2] ?? match[3] ?? "";
+        if (!isPlaceholder(value) && hasHighEntropy(value)) {
+            return true;
+        }
+    }
+    for (const match of content.matchAll(AUTHORIZATION_VALUE)) {
+        const value = match[1] ?? "";
+        if (!isPlaceholder(value) && hasHighEntropy(value)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isDocumentationScope(scope) {
+    const normalized = scope.toLowerCase();
+    const segments = normalized.split("/");
+    const filename = segments.at(-1) ?? "";
+    return (segments.includes("docs") ||
+        segments.includes("documentation") ||
+        /^readme(?:\.|$)/.test(filename) ||
+        /\.(?:adoc|md|mdx|rst)$/.test(filename));
+}
+function documentationExampleDecision(decision, content, scope) {
+    if (decision.action !== "block" ||
+        !isDocumentationScope(scope) ||
+        !SYNTHETIC_DOCUMENTATION_LABEL.test(content)) {
+        return decision;
+    }
+    return {
+        action: "warn",
+        ruleId: GUARDRAIL_RULE_IDS.documentationExample,
+        reason: "A labeled synthetic documentation example contains credential-shaped material."
+    };
+}
+export function evaluateSecretContent(content, scope = "") {
+    let decision = { action: "allow" };
+    if (blocksPrivateKey(content)) {
+        decision = {
+            action: "block",
+            ruleId: GUARDRAIL_RULE_IDS.privateKey,
+            reason: "Private-key material must not be persisted or transmitted."
+        };
+    }
+    else if (blocksKnownToken(content) || blocksSensitiveValue(content)) {
+        decision = {
+            action: "block",
+            ruleId: GUARDRAIL_RULE_IDS.credential,
+            reason: "Credential-shaped material must be replaced with a redacted value."
+        };
+    }
+    return documentationExampleDecision(decision, content, scope);
+}

package/dist/runtime/src/guardrails/types.js

@@ -0,0 +1,9 @@
+export const GUARDRAIL_RULE_IDS = {
+    ambiguousTarget: "destructive-ambiguous-target",
+    broadDelete: "destructive-broad-delete",
+    credential: "secret-credential",
+    documentationExample: "secret-documentation-example",
+    forcePush: "destructive-force-push",
+    privateKey: "secret-private-key",
+    reset: "destructive-reset"
+};

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

@@ -0,0 +1,78 @@
+import { evaluateGuardrail } from "../guardrails/evaluate.js";
+import { runStopVerification } from "./stop-verify.js";
+function continueWith(status, code) {
+    return { action: "continue", status, code };
+}
+function guardrailResult(decision) {
+    if (decision.action === "block") {
+        return {
+            action: "block",
+            status: "FAIL",
+            code: decision.ruleId
+        };
+    }
+    if (decision.action === "warn") {
+        return continueWith("UNKNOWN", decision.ruleId);
+    }
+    return continueWith("PASS", "GUARDRAIL_ALLOWED");
+}
+function evaluateCommands(commands, scope) {
+    let warning = null;
+    for (const command of commands) {
+        const result = guardrailResult(evaluateGuardrail({
+            kind: "command",
+            command: command.command,
+            args: command.args,
+            scope
+        }));
+        if (result.action === "block") {
+            return result;
+        }
+        if (result.status === "UNKNOWN") {
+            warning = result;
+        }
+    }
+    return warning ?? continueWith("PASS", "GUARDRAIL_ALLOWED");
+}
+export async function dispatchHookEvent(event, options) {
+    if (event.event === "unsupported") {
+        return continueWith("UNKNOWN", "HOOK_EVENT_UNSUPPORTED");
+    }
+    if (event.event === "session-start" &&
+        options.capabilities.includes("lifecycle-summary") &&
+        options.advisory !== undefined) {
+        try {
+            await options.advisory(event);
+            return continueWith("PASS", "ADVISORY_FINISHED");
+        }
+        catch {
+            return continueWith("UNKNOWN", "ADVISORY_FAILED");
+        }
+    }
+    if ((event.event === "command" ||
+        event.event === "command-batch" ||
+        event.event === "content") &&
+        options.capabilities.includes("command-policy")) {
+        if (event.event === "content") {
+            return guardrailResult(evaluateGuardrail({
+                kind: "content",
+                content: event.content,
+                scope: event.scope
+            }));
+        }
+        return evaluateCommands(event.event === "command"
+            ? [{ command: event.command, args: event.args }]
+            : event.commands, event.scope);
+    }
+    if (event.event === "stop" &&
+        options.capabilities.includes("optional-stop-verify")) {
+        if (options.stopVerification === undefined) {
+            return continueWith("UNKNOWN", "STOP_VERIFICATION_UNAVAILABLE");
+        }
+        return await runStopVerification({
+            ...options.stopVerification,
+            trusted: options.trusted && options.stopVerification.trusted
+        });
+    }
+    return continueWith("PASS", "HOOK_NOOP");
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/runtime/src/hooks/hook-entry.js

@@ -0,0 +1,19 @@
+import { dispatchHookEvent } from "./dispatch.js";
+import { normalizeHookEvent } from "./normalize.js";
+function invalidInput() {
+    return {
+        action: "continue",
+        status: "UNKNOWN",
+        code: "HOOK_INPUT_INVALID"
+    };
+}
+export async function runHookEntry(stdin, options) {
+    let input;
+    try {
+        input = JSON.parse(stdin);
+        return await dispatchHookEvent(normalizeHookEvent(input), options);
+    }
+    catch {
+        return invalidInput();
+    }
+}

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

@@ -0,0 +1,59 @@
+import { AgentOpsError } from "../fs/paths.js";
+const MAX_TEXT_LENGTH = 4096;
+const MAX_ARGS = 256;
+function invalidInput() {
+    throw new AgentOpsError("HOOK_INPUT_INVALID", "Hook input is invalid.");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function boundedString(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_TEXT_LENGTH ||
+        value.includes("\0")) {
+        return invalidInput();
+    }
+    return value;
+}
+function stringArgs(value) {
+    if (!Array.isArray(value) ||
+        value.length > MAX_ARGS ||
+        !value.every((item) => typeof item === "string" &&
+            item.length <= MAX_TEXT_LENGTH &&
+            !item.includes("\0"))) {
+        return invalidInput();
+    }
+    return [...value];
+}
+export function normalizeHookEvent(input) {
+    if (!isRecord(input)) {
+        return invalidInput();
+    }
+    const event = boundedString(input.event);
+    const projectRoot = boundedString(input.projectRoot);
+    if (event === "session-start" || event === "stop") {
+        return { event, projectRoot };
+    }
+    if (event === "command") {
+        return {
+            event,
+            projectRoot,
+            command: boundedString(input.command),
+            args: stringArgs(input.args),
+            scope: boundedString(input.scope)
+        };
+    }
+    if (event === "content") {
+        return {
+            event,
+            projectRoot,
+            content: boundedString(input.content),
+            scope: boundedString(input.scope)
+        };
+    }
+    return {
+        event: "unsupported",
+        projectRoot
+    };
+}

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

@@ -0,0 +1,12 @@
+import { AgentOpsError } from "../fs/paths.js";
+export const DEFAULT_HOOK_OUTPUT_BYTES = 8 * 1024;
+export function encodeHookOutput(output, maxBytes = DEFAULT_HOOK_OUTPUT_BYTES) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+        throw new AgentOpsError("HOOK_OUTPUT_LIMIT_INVALID", "Hook output limit must be a positive safe integer.");
+    }
+    const encoded = JSON.stringify(output);
+    if (Buffer.byteLength(encoded, "utf8") > maxBytes) {
+        throw new AgentOpsError("HOOK_OUTPUT_TOO_LARGE", "Hook output exceeds the configured byte limit.");
+    }
+    return encoded;
+}

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

@@ -0,0 +1,138 @@
+import { normalizeHookEvent } from "./normalize.js";
+const MAX_COMMAND_LENGTH = 16 * 1024;
+const MAX_COMMANDS = 64;
+const MAX_WORDS = 256;
+function parseShellWords(input) {
+    if (input.length === 0 || input.length > MAX_COMMAND_LENGTH) {
+        return null;
+    }
+    const commands = [];
+    let words = [];
+    let word = "";
+    let quote = null;
+    let escaped = false;
+    const finishWord = () => {
+        if (word.length > 0) {
+            words.push(word);
+            word = "";
+        }
+    };
+    const finishCommand = () => {
+        finishWord();
+        if (words.length > 0) {
+            commands.push(words);
+            words = [];
+        }
+    };
+    for (let index = 0; index < input.length; index += 1) {
+        const character = input[index];
+        if (character === undefined) {
+            return null;
+        }
+        if (escaped) {
+            word += character;
+            escaped = false;
+            continue;
+        }
+        if (character === "\\" && quote !== "'") {
+            escaped = true;
+            continue;
+        }
+        if (quote !== "'" &&
+            (character === "$" || character === "`")) {
+            return null;
+        }
+        if (quote !== null) {
+            if (character === quote) {
+                quote = null;
+            }
+            else {
+                word += character;
+            }
+            continue;
+        }
+        if (character === "'" || character === "\"") {
+            quote = character;
+            continue;
+        }
+        if (/\s/.test(character)) {
+            finishWord();
+            if (character === "\n") {
+                finishCommand();
+            }
+            continue;
+        }
+        if (character === ";" || character === "|" || character === "&") {
+            finishCommand();
+            const next = input[index + 1];
+            if (next === character) {
+                index += 1;
+            }
+            continue;
+        }
+        if (character === "(" ||
+            character === ")" ||
+            character === "\0") {
+            return null;
+        }
+        word += character;
+        if (word.length > MAX_COMMAND_LENGTH) {
+            return null;
+        }
+    }
+    if (escaped || quote !== null) {
+        return null;
+    }
+    finishCommand();
+    if (commands.length === 0 ||
+        commands.length > MAX_COMMANDS ||
+        commands.some((command) => command.length > MAX_WORDS)) {
+        return null;
+    }
+    return commands;
+}
+export function normalizeShellHookEvent(input, projectRoot) {
+    const commands = parseShellWords(input);
+    if (commands === null) {
+        return normalizeHookEvent({
+            event: "unsupported",
+            projectRoot
+        });
+    }
+    const normalized = commands.map((words) => {
+        const command = words[0];
+        if (command === undefined) {
+            throw new Error("Shell parser returned an empty command.");
+        }
+        const event = normalizeHookEvent({
+            event: "command",
+            projectRoot,
+            command,
+            args: words.slice(1),
+            scope: projectRoot
+        });
+        if (event.event !== "command") {
+            throw new Error("Shell command normalization failed.");
+        }
+        return event;
+    });
+    if (normalized.length === 1 && normalized[0] !== undefined) {
+        return normalized[0];
+    }
+    const first = normalized[0];
+    if (first === undefined) {
+        return normalizeHookEvent({
+            event: "unsupported",
+            projectRoot
+        });
+    }
+    return {
+        event: "command-batch",
+        projectRoot: first.projectRoot,
+        commands: normalized.map(({ command, args }) => ({
+            command,
+            args
+        })),
+        scope: first.scope
+    };
+}

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

@@ -0,0 +1,70 @@
+const ID_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,127}$/;
+const HASH_PATTERN = /^[a-f0-9]{64}$/;
+function unavailable(code) {
+    return {
+        action: "continue",
+        status: "UNKNOWN",
+        code
+    };
+}
+function boundedEvidence(results) {
+    if (results.length > 256 ||
+        results.some((result) => !ID_PATTERN.test(result.commandId) ||
+            (result.exitCode !== null &&
+                (!Number.isSafeInteger(result.exitCode) || result.exitCode < 0)) ||
+            (result.testCount !== null &&
+                (!Number.isSafeInteger(result.testCount) || result.testCount < 0)))) {
+        return null;
+    }
+    return results.map(({ commandId, exitCode, testCount }) => ({
+        commandId,
+        exitCode,
+        testCount
+    }));
+}
+function evidenceSupportsStatus(status, results) {
+    if (status !== "PASS") {
+        return true;
+    }
+    return (results.length > 0 &&
+        results.some((result) => result.testCount !== null && result.testCount > 0) &&
+        results.every((result) => result.exitCode === 0 &&
+            (result.testCount === null || result.testCount > 0)));
+}
+export async function runStopVerification(options) {
+    if (options.recursionMarker) {
+        return unavailable("STOP_VERIFICATION_RECURSION");
+    }
+    if (!options.confirmedConfig || !HASH_PATTERN.test(options.configHash)) {
+        return unavailable("STOP_VERIFICATION_UNCONFIRMED");
+    }
+    if (!options.trusted) {
+        return unavailable("STOP_VERIFICATION_UNTRUSTED");
+    }
+    if (!options.scopeMapped) {
+        return unavailable("STOP_VERIFICATION_SCOPE_UNMAPPED");
+    }
+    try {
+        const report = await options.verify();
+        const commandResults = boundedEvidence(report.results);
+        const timestamp = (options.now ?? (() => new Date().toISOString()))();
+        if (commandResults === null ||
+            !evidenceSupportsStatus(report.status, commandResults) ||
+            !Number.isFinite(Date.parse(timestamp))) {
+            return unavailable("STOP_VERIFICATION_EVIDENCE_INVALID");
+        }
+        return {
+            action: "continue",
+            status: report.status,
+            code: "STOP_VERIFICATION_FINISHED",
+            evidence: {
+                commandResults,
+                configHash: options.configHash,
+                timestamp
+            }
+        };
+    }
+    catch {
+        return unavailable("STOP_VERIFICATION_FAILED");
+    }
+}

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

@@ -0,0 +1,70 @@
+import { readFile } from "node:fs/promises";
+import { sha256 } from "../fs/hash.js";
+import { formatInstallManifest, parseInstallManifest } from "../fs/manifest.js";
+import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
+import { FileTransaction } from "../fs/transaction.js";
+import { validateConfig } from "../schema/validate.js";
+const CONFIG_PATH = ".agent-ops/config.json";
+const MANIFEST_PATH = ".agent-ops/manifest.json";
+async function readInstalledFile(root, path) {
+    return await readFile(await resolveContainedPath(root, path), "utf8");
+}
+function markerCount(source, marker) {
+    let count = 0;
+    let index = 0;
+    while ((index = source.indexOf(marker, index)) !== -1) {
+        count += 1;
+        index += marker.length;
+    }
+    return count;
+}
+async function validateAppliedPlan(root, plan) {
+    const installedManifestSource = await readInstalledFile(root, MANIFEST_PATH);
+    const installedManifest = parseInstallManifest(installedManifestSource);
+    if (formatInstallManifest(installedManifest) !==
+        formatInstallManifest(plan.manifest)) {
+        throw new AgentOpsError("INSTALL_VALIDATION_FAILED", "The installed manifest does not match the approved plan.");
+    }
+    for (const artifact of installedManifest.artifacts) {
+        const content = await readInstalledFile(root, artifact.path);
+        if (sha256(content) !== artifact.hash) {
+            throw new AgentOpsError("INSTALL_VALIDATION_FAILED", `Installed artifact hash mismatch: ${artifact.path}`);
+        }
+    }
+    for (const marker of installedManifest.markers) {
+        const content = await readInstalledFile(root, marker.path);
+        if (sha256(content) !== marker.hash ||
+            markerCount(content, marker.startMarker) !== 1 ||
+            markerCount(content, marker.endMarker) !== 1 ||
+            content.indexOf(marker.startMarker) >=
+                content.indexOf(marker.endMarker)) {
+            throw new AgentOpsError("INSTALL_VALIDATION_FAILED", `Installed managed block is invalid: ${marker.path}`);
+        }
+    }
+    const configSource = await readInstalledFile(root, CONFIG_PATH);
+    let config;
+    try {
+        config = JSON.parse(configSource);
+    }
+    catch (error) {
+        throw new AgentOpsError("INSTALL_VALIDATION_FAILED", "Installed configuration is not valid JSON.", { cause: error });
+    }
+    const configResult = validateConfig(config);
+    if (!configResult.ok) {
+        throw new AgentOpsError("INSTALL_VALIDATION_FAILED", `${configResult.errors[0]?.path ?? "$"}: ${configResult.errors[0]?.message ?? "Invalid installed configuration."}`);
+    }
+}
+function assertManifestOperation(plan) {
+    const manifestOperations = plan.operations.filter((operation) => operation.path === MANIFEST_PATH);
+    const manifestOperation = manifestOperations[0];
+    if (manifestOperations.length !== 1 ||
+        manifestOperation?.kind !== "write" ||
+        manifestOperation.content !== formatInstallManifest(plan.manifest)) {
+        throw new AgentOpsError("INVALID_INSTALL_PLAN", "Install plan must contain one matching manifest write.");
+    }
+}
+export async function applyInstallPlan(root, plan) {
+    assertManifestOperation(plan);
+    const transaction = new FileTransaction(root);
+    await transaction.apply({ operations: plan.operations }, async () => await validateAppliedPlan(root, plan));
+}