@kylecheng3146/agent-ops 0.0.1

package/dist/runtime/src/task/store.js

@@ -0,0 +1,265 @@
+import { lstat } from "node:fs/promises";
+import { AgentOpsError } from "../fs/paths.js";
+import { validateTask } from "../schema/validate.js";
+import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+const SESSION_ID_PATTERN = /^[^\0\r\n]{1,256}$/u;
+function isMissing(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    const sortedExpected = [...expected].sort();
+    return (actual.length === sortedExpected.length &&
+        sortedExpected.every((key, index) => actual[index] === key));
+}
+function isTimestamp(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= 64 &&
+        Number.isFinite(Date.parse(value)));
+}
+function invalidState(message) {
+    throw new AgentOpsError("TASK_STATE_INVALID", message);
+}
+function parseEvidence(value, task, requireComplete) {
+    if (!isRecord(value)) {
+        return invalidState("Task evidence must be an object.");
+    }
+    const criterionIds = new Set(task.criteria.map((criterion) => criterion.id));
+    const evidence = {};
+    for (const [criterionId, references] of Object.entries(value)) {
+        if (!criterionIds.has(criterionId) ||
+            !Array.isArray(references) ||
+            references.length === 0 ||
+            references.some((reference) => typeof reference !== "string" ||
+                reference.length === 0 ||
+                reference.length > 4096 ||
+                reference.includes("\0")) ||
+            new Set(references).size !== references.length) {
+            return invalidState("Task evidence references are invalid.");
+        }
+        evidence[criterionId] = [...references];
+    }
+    if (requireComplete &&
+        task.criteria.some((criterion) => evidence[criterion.id] === undefined)) {
+        return invalidState("Completed task state requires evidence for every criterion.");
+    }
+    return evidence;
+}
+function parseTaskRecord(value) {
+    const baseKeys = [
+        "archivedAt",
+        "completedAt",
+        "createdAt",
+        "evidence",
+        "status",
+        "task",
+        "updatedAt"
+    ];
+    if (!isRecord(value) ||
+        (!hasExactKeys(value, baseKeys) &&
+            !hasExactKeys(value, [...baseKeys, "failureFingerprint"]))) {
+        return invalidState("Task state contains an invalid task record.");
+    }
+    const task = validateTask(value.task);
+    if (!task.ok) {
+        return invalidState("Task state contains an invalid task.");
+    }
+    if (!["active", "archived", "complete"].includes(String(value.status)) ||
+        !isTimestamp(value.createdAt) ||
+        !isTimestamp(value.updatedAt) ||
+        (value.completedAt !== null && !isTimestamp(value.completedAt)) ||
+        (value.archivedAt !== null && !isTimestamp(value.archivedAt))) {
+        return invalidState("Task state contains invalid lifecycle metadata.");
+    }
+    const status = value.status;
+    if ((status === "active" &&
+        (value.completedAt !== null || value.archivedAt !== null)) ||
+        (status === "complete" &&
+            (value.completedAt === null || value.archivedAt !== null)) ||
+        (status === "archived" && value.archivedAt === null)) {
+        return invalidState("Task lifecycle timestamps do not match its status.");
+    }
+    const evidence = parseEvidence(value.evidence, task.value, status === "complete" ||
+        (status === "archived" && value.completedAt !== null));
+    let failureFingerprint = null;
+    if (value.failureFingerprint !== undefined &&
+        value.failureFingerprint !== null) {
+        const fingerprint = value.failureFingerprint;
+        if (!isRecord(fingerprint) ||
+            !hasExactKeys(fingerprint, [
+                "commandId",
+                "consecutive",
+                "diagnostics",
+                "exitCategory",
+                "failureClass",
+                "recordedAt",
+                "value"
+            ]) ||
+            typeof fingerprint.value !== "string" ||
+            !/^[a-f0-9]{64}$/u.test(fingerprint.value) ||
+            typeof fingerprint.commandId !== "string" ||
+            typeof fingerprint.failureClass !== "string" ||
+            typeof fingerprint.exitCategory !== "string" ||
+            typeof fingerprint.diagnostics !== "string" ||
+            fingerprint.diagnostics.includes("\0") ||
+            Buffer.byteLength(fingerprint.diagnostics, "utf8") > 512 ||
+            !Number.isSafeInteger(fingerprint.consecutive) ||
+            fingerprint.consecutive <= 0 ||
+            !isTimestamp(fingerprint.recordedAt)) {
+            return invalidState("Task state contains an invalid failure fingerprint.");
+        }
+        failureFingerprint = {
+            value: fingerprint.value,
+            commandId: fingerprint.commandId,
+            failureClass: fingerprint.failureClass,
+            exitCategory: fingerprint.exitCategory,
+            diagnostics: fingerprint.diagnostics,
+            consecutive: fingerprint.consecutive,
+            recordedAt: fingerprint.recordedAt
+        };
+    }
+    return {
+        task: task.value,
+        status,
+        evidence,
+        createdAt: value.createdAt,
+        updatedAt: value.updatedAt,
+        completedAt: value.completedAt,
+        archivedAt: value.archivedAt,
+        failureFingerprint
+    };
+}
+function parseSession(value) {
+    if (!isRecord(value) ||
+        !hasExactKeys(value, ["attachedAt", "sessionId", "taskId"]) ||
+        typeof value.sessionId !== "string" ||
+        !SESSION_ID_PATTERN.test(value.sessionId) ||
+        typeof value.taskId !== "string" ||
+        !isTimestamp(value.attachedAt)) {
+        return invalidState("Task state contains an invalid session attachment.");
+    }
+    return {
+        sessionId: value.sessionId,
+        taskId: value.taskId,
+        attachedAt: value.attachedAt
+    };
+}
+function parseState(source) {
+    if (source === null) {
+        return { schemaVersion: 1, tasks: [], sessions: [] };
+    }
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        return invalidState("Task state is not valid JSON.");
+    }
+    if (!isRecord(value) ||
+        !hasExactKeys(value, ["schemaVersion", "sessions", "tasks"]) ||
+        value.schemaVersion !== 1 ||
+        !Array.isArray(value.tasks) ||
+        !Array.isArray(value.sessions)) {
+        return invalidState("Task state has an unsupported structure.");
+    }
+    const tasks = value.tasks.map(parseTaskRecord);
+    const sessions = value.sessions.map(parseSession);
+    if (new Set(tasks.map(({ task }) => task.id)).size !== tasks.length ||
+        new Set(sessions.map(({ sessionId }) => sessionId)).size !==
+            sessions.length) {
+        return invalidState("Task and session identifiers must be unique.");
+    }
+    const tasksById = new Map(tasks.map((record) => [record.task.id, record]));
+    if (sessions.some(({ taskId }) => {
+        const record = tasksById.get(taskId);
+        return record === undefined || record.status === "archived";
+    })) {
+        return invalidState("Session attachments must reference known tasks.");
+    }
+    return { schemaVersion: 1, tasks, sessions };
+}
+function positiveMaxBytes(value) {
+    if (value === undefined) {
+        return DEFAULT_MAX_BYTES;
+    }
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new AgentOpsError("TASK_STATE_LIMIT_INVALID", "Task state byte limit must be a positive integer.");
+    }
+    return value;
+}
+export class FileTaskStore {
+    #path;
+    #anchorDirectory;
+    #maxBytes;
+    constructor(path, anchorDirectory, options = {}) {
+        this.#path = path;
+        this.#anchorDirectory = anchorDirectory;
+        this.#maxBytes = positiveMaxBytes(options.maxBytes);
+    }
+    async #readState() {
+        let before = null;
+        try {
+            const status = await lstat(this.#path, { bigint: true });
+            if (!status.isFile() ||
+                status.isSymbolicLink() ||
+                status.size > BigInt(this.#maxBytes)) {
+                if (status.size > BigInt(this.#maxBytes)) {
+                    throw new AgentOpsError("TASK_STATE_TOO_LARGE", "Task state exceeds its configured byte limit.");
+                }
+                throw new AgentOpsError("TASK_STATE_INVALID", "Task state must be a regular private file.");
+            }
+            before = { device: status.dev, inode: status.ino };
+        }
+        catch (error) {
+            if (!isMissing(error)) {
+                throw error;
+            }
+        }
+        const source = await readPrivateFile(this.#path, this.#anchorDirectory);
+        if (before === null && source !== null) {
+            throw new AgentOpsError("TASK_STATE_INVALID", "Task state appeared during inspection.");
+        }
+        if (before !== null) {
+            if (source === null) {
+                throw new AgentOpsError("TASK_STATE_INVALID", "Task state disappeared during inspection.");
+            }
+            const after = await lstat(this.#path, { bigint: true });
+            if (!after.isFile() ||
+                after.isSymbolicLink() ||
+                after.dev !== before.device ||
+                after.ino !== before.inode ||
+                after.size > BigInt(this.#maxBytes)) {
+                throw new AgentOpsError("TASK_STATE_INVALID", "Task state changed during inspection.");
+            }
+        }
+        if (source !== null &&
+            Buffer.byteLength(source, "utf8") > this.#maxBytes) {
+            throw new AgentOpsError("TASK_STATE_TOO_LARGE", "Task state exceeds its configured byte limit.");
+        }
+        return parseState(source);
+    }
+    async read() {
+        return await withPrivateFileLock(this.#path, this.#anchorDirectory, async () => structuredClone(await this.#readState()));
+    }
+    async mutate(action) {
+        return await withPrivateFileLock(this.#path, this.#anchorDirectory, async () => {
+            const state = await this.#readState();
+            const result = await action(state);
+            const validated = parseState(JSON.stringify(state));
+            const content = `${JSON.stringify(validated, null, 2)}\n`;
+            if (Buffer.byteLength(content, "utf8") > this.#maxBytes) {
+                throw new AgentOpsError("TASK_STATE_TOO_LARGE", "Task state exceeds its configured byte limit.");
+            }
+            await writePrivateFile(this.#path, content, this.#anchorDirectory);
+            return result;
+        });
+    }
+}

package/dist/runtime/src/verify/change-surface.js

@@ -0,0 +1,86 @@
+import { TextDecoder } from "node:util";
+import { AgentOpsError } from "../fs/paths.js";
+const WINDOWS_RESERVED_SEGMENT = /^(?:aux|com[1-9]|con|lpt[1-9]|nul|prn)(?:\..*)?$/i;
+function sortedUnique(values) {
+    return [...new Set(values)].sort();
+}
+function normalizePortablePath(path) {
+    if (path.length === 0 ||
+        path.includes("\\") ||
+        path.startsWith("/") ||
+        /^[A-Za-z]:/.test(path)) {
+        throw new AgentOpsError("CHANGE_SURFACE_UNSAFE_PATH", `Git reported an unsafe path: ${path}`);
+    }
+    const normalizedSegments = [];
+    for (const segment of path.split("/")) {
+        if (segment.length === 0 || segment === ".") {
+            continue;
+        }
+        if (segment === ".." ||
+            segment.endsWith(".") ||
+            segment.endsWith(" ") ||
+            WINDOWS_RESERVED_SEGMENT.test(segment) ||
+            /[\u0000-\u001F\u007F-\u009F\u202A-\u202E\u2066-\u2069]/u
+                .test(segment)) {
+            throw new AgentOpsError("CHANGE_SURFACE_UNSAFE_PATH", `Git reported a path with an unsafe segment: ${path}`);
+        }
+        normalizedSegments.push(segment);
+    }
+    if (normalizedSegments.length === 0) {
+        throw new AgentOpsError("CHANGE_SURFACE_UNSAFE_PATH", `Git reported an empty normalized path: ${path}`);
+    }
+    return normalizedSegments.join("/");
+}
+function parseNulPaths(stdout) {
+    if (stdout.byteLength === 0) {
+        return [];
+    }
+    if (stdout[stdout.byteLength - 1] !== 0) {
+        throw new AgentOpsError("CHANGE_SURFACE_INVALID_OUTPUT", "Git path output must end with a NUL delimiter.");
+    }
+    let decoded;
+    try {
+        decoded = new TextDecoder("utf-8", { fatal: true }).decode(stdout);
+    }
+    catch (error) {
+        throw new AgentOpsError("CHANGE_SURFACE_INVALID_OUTPUT", "Git path output is not valid UTF-8.", { cause: error });
+    }
+    const entries = decoded.split("\0");
+    entries.pop();
+    if (entries.some((entry) => entry.length === 0)) {
+        throw new AgentOpsError("CHANGE_SURFACE_INVALID_OUTPUT", "Git path output contains an empty NUL-delimited entry.");
+    }
+    return sortedUnique(entries.map(normalizePortablePath));
+}
+async function collectPaths(runner, args) {
+    const result = await runner.run(args);
+    if (result.exitCode !== 0) {
+        throw new AgentOpsError("CHANGE_SURFACE_GIT_FAILED", `Git command failed with exit code ${result.exitCode}: ${args.join(" ")}`);
+    }
+    return parseNulPaths(result.stdout);
+}
+export async function collectChangeSurface(runner) {
+    const staged = await collectPaths(runner, [
+        "diff",
+        "--cached",
+        "--name-only",
+        "-z"
+    ]);
+    const unstaged = await collectPaths(runner, [
+        "diff",
+        "--name-only",
+        "-z"
+    ]);
+    const untracked = await collectPaths(runner, [
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+        "-z"
+    ]);
+    return {
+        staged,
+        unstaged,
+        untracked,
+        paths: sortedUnique([...staged, ...unstaged, ...untracked])
+    };
+}

package/dist/runtime/src/verify/evidence.js

@@ -0,0 +1,89 @@
+import { join } from "node:path";
+import { SCHEMA_VERSION } from "../contracts.js";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { validateEvidence } from "../schema/validate.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { redactSecrets } from "../security/redact.js";
+function canonicalJson(value) {
+    if (value === null ||
+        typeof value === "boolean" ||
+        typeof value === "number" ||
+        typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    if (typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+            .join(",")}}`;
+    }
+    throw new AgentOpsError("CONFIG_HASH_INVALID", "Configuration contains an unsupported value.");
+}
+export function calculateConfigHash(config) {
+    return sha256(canonicalJson(config));
+}
+function redactRecord(record) {
+    return Object.fromEntries(Object.entries(record).map(([key, value]) => [
+        redactSecrets(key),
+        redactSecrets(value)
+    ]));
+}
+function validateBuiltEvidence(value) {
+    const validation = validateEvidence(value);
+    if (!validation.ok) {
+        throw new AgentOpsError("EVIDENCE_INVALID", validation.errors[0]?.message ??
+            "Verification evidence is invalid.");
+    }
+    return validation.value;
+}
+export function buildVerificationEvidence(input) {
+    return validateBuiltEvidence({
+        schemaVersion: SCHEMA_VERSION,
+        taskId: input.taskId,
+        criterionId: input.criterionId,
+        commandId: input.command.id,
+        argv: [input.command.command, ...input.command.args].map(redactSecrets),
+        cwd: input.command.cwd,
+        scope: input.scope,
+        startedAt: input.startedAt,
+        finishedAt: input.finishedAt,
+        exitCode: input.exitCode,
+        testCount: input.testCount,
+        toolVersions: redactRecord(input.toolVersions),
+        configHash: calculateConfigHash(input.config)
+    });
+}
+export class FileEvidenceStore {
+    #root;
+    #anchorDirectory;
+    constructor(root, anchorDirectory) {
+        this.#root = root;
+        this.#anchorDirectory = anchorDirectory;
+    }
+    async save(value) {
+        const evidence = validateBuiltEvidence(value);
+        const content = `${JSON.stringify(evidence, null, 2)}\n`;
+        const contentHash = sha256(content);
+        const relativePath = [
+            ".agent-ops",
+            "tasks",
+            "evidence",
+            evidence.taskId,
+            `${evidence.commandId}-${contentHash.slice(0, 16)}.json`
+        ].join("/");
+        const absolutePath = join(this.#root, ...relativePath.split("/"));
+        const existing = await readPrivateFile(absolutePath, this.#anchorDirectory);
+        if (existing !== null && existing !== content) {
+            throw new AgentOpsError("EVIDENCE_CONFLICT", "Evidence path already contains different content.");
+        }
+        if (existing === null) {
+            await writePrivateFile(absolutePath, content, this.#anchorDirectory);
+        }
+        return relativePath;
+    }
+}

package/dist/runtime/src/verify/fingerprint.js

@@ -0,0 +1,67 @@
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { redactSecrets } from "../security/redact.js";
+const COMPONENT_PATTERN = /^[a-z][a-z0-9-]{0,127}$/u;
+const MAX_DIAGNOSTIC_BYTES = 512;
+function boundedUtf8(value, maxBytes) {
+    let output = "";
+    let bytes = 0;
+    for (const character of value) {
+        const characterBytes = Buffer.byteLength(character, "utf8");
+        if (bytes + characterBytes > maxBytes) {
+            break;
+        }
+        output += character;
+        bytes += characterBytes;
+    }
+    return output;
+}
+function normalizedDiagnostic(value) {
+    const redacted = redactSecrets(value)
+        .replace(/\r\n?/gu, "\n")
+        .split("\n")
+        .map((line) => line.trim().replace(/[ \t]+/gu, " "))
+        .filter((line) => line.length > 0)
+        .join("\n");
+    return boundedUtf8(redacted, MAX_DIAGNOSTIC_BYTES);
+}
+function assertComponent(name, value) {
+    if (!COMPONENT_PATTERN.test(value)) {
+        throw new AgentOpsError("FINGERPRINT_INVALID", `Failure fingerprint ${name} is invalid.`);
+    }
+}
+export function createFailureFingerprint(input) {
+    assertComponent("commandId", input.commandId);
+    assertComponent("failureClass", input.failureClass);
+    assertComponent("exitCategory", input.exitCategory);
+    const diagnostics = normalizedDiagnostic(input.diagnostics);
+    const components = {
+        commandId: input.commandId,
+        failureClass: input.failureClass,
+        exitCategory: input.exitCategory,
+        diagnostics
+    };
+    return {
+        value: sha256(JSON.stringify(components)),
+        ...components
+    };
+}
+export function advanceFailureFingerprint(previous, current, recordedAt) {
+    if (!Number.isFinite(Date.parse(recordedAt))) {
+        throw new AgentOpsError("FINGERPRINT_TIMESTAMP_INVALID", "Failure fingerprint timestamp must be ISO-compatible.");
+    }
+    const consecutive = previous?.value === current.value
+        ? previous.consecutive + 1
+        : 1;
+    if (!Number.isSafeInteger(consecutive) || consecutive <= 0) {
+        throw new AgentOpsError("FINGERPRINT_COUNT_INVALID", "Failure fingerprint repetition count is invalid.");
+    }
+    return {
+        state: {
+            ...current,
+            consecutive,
+            recordedAt
+        },
+        signal: consecutive >= 2 ? "CHANGE_APPROACH_REQUIRED" : null
+    };
+}

package/dist/runtime/src/verify/scope.js

@@ -0,0 +1,69 @@
+import { AgentOpsError } from "../fs/paths.js";
+function sortedUnique(values) {
+    return [...new Set(values)].sort();
+}
+function mappingMatches(path, mapping) {
+    return path === mapping.path || path.startsWith(`${mapping.path}/`);
+}
+function mappingEvidence(path, mappings) {
+    return {
+        changedPath: path,
+        mappingPaths: sortedUnique(mappings.map((mapping) => mapping.path)),
+        verifierIds: sortedUnique(mappings.flatMap((mapping) => mapping.verifierIds))
+    };
+}
+function sameVerifierIds(left, right) {
+    return (left.length === right.length &&
+        left.every((verifierId, index) => verifierId === right[index]));
+}
+function fallbackSelection(reason, evidence) {
+    if (evidence.requiredVerifierIds.length === 0) {
+        throw new AgentOpsError("VERIFICATION_SCOPE_EMPTY", `Verification scope fallback (${reason}) has no required commands.`);
+    }
+    return {
+        verifierIds: evidence.requiredVerifierIds,
+        fallback: true,
+        reason,
+        evidence
+    };
+}
+export function selectVerificationScope(paths, config) {
+    const changedPaths = sortedUnique(paths);
+    const requiredVerifierIds = sortedUnique(config.verification.commands
+        .filter((command) => command.required)
+        .map((command) => command.id));
+    const mappings = changedPaths.map((changedPath) => {
+        const matches = config.pathMappings.filter((mapping) => mappingMatches(changedPath, mapping));
+        return mappingEvidence(changedPath, matches);
+    });
+    const evidence = {
+        changedPaths,
+        mappings,
+        requiredVerifierIds
+    };
+    if (changedPaths.length === 0) {
+        return fallbackSelection("no-changes", evidence);
+    }
+    if (mappings.some((mapping) => mapping.mappingPaths.length === 0)) {
+        return fallbackSelection("unknown-path", evidence);
+    }
+    if (mappings.some((mapping) => mapping.mappingPaths.length > 1)) {
+        return fallbackSelection("ambiguous-path", evidence);
+    }
+    if (mappings.some((mapping) => mapping.verifierIds.length === 0)) {
+        return fallbackSelection("empty-mapping", evidence);
+    }
+    const selectedVerifierIds = mappings[0]?.verifierIds ?? [];
+    if (mappings.some((mapping) => !sameVerifierIds(mapping.verifierIds, selectedVerifierIds))) {
+        return fallbackSelection("conflicting-scope", evidence);
+    }
+    if (selectedVerifierIds.length === 0) {
+        return fallbackSelection("empty-mapping", evidence);
+    }
+    return {
+        verifierIds: selectedVerifierIds,
+        fallback: false,
+        reason: "mapped",
+        evidence
+    };
+}