@kylecheng3146/agent-ops 0.0.1

package/dist/runtime/src/security/trust.js

@@ -0,0 +1,209 @@
+import { lstat, realpath } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { AgentOpsError } from "../fs/paths.js";
+import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "./permissions.js";
+const HASH_PATTERN = /^[a-f0-9]{64}$/;
+const BINDING_FIELDS = [
+    "canonicalPath",
+    "remoteIdentity",
+    "configHash",
+    "runtimeHash"
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOnlyKeys(value, allowed) {
+    const allowedKeys = new Set(allowed);
+    return Object.keys(value).every((key) => allowedKeys.has(key));
+}
+function normalizedRepositoryPath(path, caseInsensitive) {
+    const normalized = path
+        .replace(/^\/+/, "")
+        .replace(/\/+$/, "")
+        .replace(/\.git$/i, "");
+    return caseInsensitive ? normalized.toLowerCase() : normalized;
+}
+function isCaseInsensitiveHost(host) {
+    return host === "github.com";
+}
+export function normalizeRemoteIdentity(remoteUrl) {
+    const value = remoteUrl.trim();
+    if (value.length === 0 || value.includes("\0")) {
+        throw new AgentOpsError("TRUST_REMOTE_INVALID", "Git remote identity must be a non-empty value.");
+    }
+    const scpLike = /^(?:[^@\s/:]+@)?([^:\s/]+):(.+)$/.exec(value);
+    if (!value.includes("://") &&
+        !/^[A-Za-z]:[\\/]/.test(value) &&
+        scpLike !== null) {
+        const host = scpLike[1];
+        const repository = scpLike[2];
+        if (host !== undefined && repository !== undefined) {
+            const normalizedHost = host.toLowerCase();
+            return `${normalizedHost}/${normalizedRepositoryPath(repository, isCaseInsensitiveHost(normalizedHost))}`;
+        }
+    }
+    try {
+        const url = new URL(value);
+        if (url.hostname.length > 0) {
+            const normalizedHost = url.hostname.toLowerCase();
+            const repository = normalizedRepositoryPath(url.pathname, isCaseInsensitiveHost(normalizedHost));
+            if (repository.length === 0) {
+                throw new AgentOpsError("TRUST_REMOTE_INVALID", "Git remote must include a repository path.");
+            }
+            const port = url.port.length === 0 ? "" : `:${url.port}`;
+            return `${normalizedHost}${port}/${repository}`;
+        }
+    }
+    catch (error) {
+        if (error instanceof AgentOpsError) {
+            throw error;
+        }
+    }
+    const local = value.replace(/\\/g, "/").replace(/\.git$/i, "");
+    if (local.length === 0) {
+        throw new AgentOpsError("TRUST_REMOTE_INVALID", "Git remote identity could not be normalized.");
+    }
+    return `local:${process.platform === "win32" ? local.toLowerCase() : local}`;
+}
+function assertBinding(binding) {
+    if (!isAbsolute(binding.canonicalPath) ||
+        binding.canonicalPath.includes("\0") ||
+        binding.remoteIdentity.trim().length === 0 ||
+        binding.remoteIdentity.includes("\0") ||
+        !HASH_PATTERN.test(binding.configHash) ||
+        !HASH_PATTERN.test(binding.runtimeHash)) {
+        throw new AgentOpsError("TRUST_BINDING_INVALID", "Trust binding fields are invalid.");
+    }
+}
+export async function calculateTrustBinding(input) {
+    const canonicalPath = await realpath(resolve(input.repositoryPath));
+    const status = await lstat(canonicalPath);
+    if (!status.isDirectory()) {
+        throw new AgentOpsError("TRUST_REPOSITORY_INVALID", "Trust can be granted only to a repository directory.");
+    }
+    const binding = {
+        canonicalPath,
+        remoteIdentity: normalizeRemoteIdentity(input.remoteUrl),
+        configHash: input.configHash,
+        runtimeHash: input.runtimeHash
+    };
+    assertBinding(binding);
+    return binding;
+}
+function sameBinding(left, right) {
+    return BINDING_FIELDS.every((field) => left[field] === right[field]);
+}
+function parseBinding(value) {
+    if (!isRecord(value) ||
+        !hasOnlyKeys(value, BINDING_FIELDS) ||
+        typeof value.canonicalPath !== "string" ||
+        typeof value.remoteIdentity !== "string" ||
+        typeof value.configHash !== "string" ||
+        typeof value.runtimeHash !== "string") {
+        throw new AgentOpsError("TRUST_STORE_INVALID", "Trust store contains an invalid binding.");
+    }
+    const binding = {
+        canonicalPath: value.canonicalPath,
+        remoteIdentity: value.remoteIdentity,
+        configHash: value.configHash,
+        runtimeHash: value.runtimeHash
+    };
+    assertBinding(binding);
+    return binding;
+}
+function parseTrustStore(source) {
+    if (source === null) {
+        return { schemaVersion: 1, records: [] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch (error) {
+        throw new AgentOpsError("TRUST_STORE_INVALID", "Trust store is not valid JSON.", { cause: error });
+    }
+    if (!isRecord(parsed) ||
+        !hasOnlyKeys(parsed, ["records", "schemaVersion"]) ||
+        parsed.schemaVersion !== 1 ||
+        !Array.isArray(parsed.records)) {
+        throw new AgentOpsError("TRUST_STORE_INVALID", "Trust store has an unsupported structure.");
+    }
+    const records = parsed.records.map((value) => {
+        if (!isRecord(value) ||
+            !hasOnlyKeys(value, ["binding", "grantedAt"]) ||
+            typeof value.grantedAt !== "string" ||
+            !Number.isFinite(Date.parse(value.grantedAt))) {
+            throw new AgentOpsError("TRUST_STORE_INVALID", "Trust store contains an invalid record.");
+        }
+        return {
+            binding: parseBinding(value.binding),
+            grantedAt: value.grantedAt
+        };
+    });
+    return { schemaVersion: 1, records };
+}
+function mismatchFields(stored, current) {
+    return BINDING_FIELDS.filter((field) => stored[field] !== current[field]);
+}
+function matchScore(left, right) {
+    return BINDING_FIELDS.reduce((score, field) => score + (left[field] === right[field] ? 1 : 0), 0);
+}
+export class FileTrustStore {
+    #anchorDirectory;
+    #path;
+    constructor(path, anchorDirectory) {
+        this.#path = path;
+        this.#anchorDirectory = anchorDirectory;
+    }
+    async #read() {
+        return parseTrustStore(await readPrivateFile(this.#path, this.#anchorDirectory));
+    }
+    async #write(store) {
+        await writePrivateFile(this.#path, `${JSON.stringify(store, null, 2)}\n`, this.#anchorDirectory);
+    }
+    async status(binding) {
+        assertBinding(binding);
+        const store = await this.#read();
+        const exact = store.records.find((record) => sameBinding(record.binding, binding));
+        if (exact !== undefined) {
+            return { status: "TRUSTED", mismatchedFields: [] };
+        }
+        const related = store.records
+            .filter((record) => record.binding.canonicalPath === binding.canonicalPath ||
+            record.binding.remoteIdentity === binding.remoteIdentity)
+            .sort((left, right) => matchScore(right.binding, binding) -
+            matchScore(left.binding, binding))[0];
+        if (related === undefined) {
+            return { status: "UNTRUSTED", mismatchedFields: [] };
+        }
+        return {
+            status: "STALE",
+            mismatchedFields: mismatchFields(related.binding, binding)
+        };
+    }
+    async grant(binding, grantedAt = new Date().toISOString()) {
+        assertBinding(binding);
+        if (!Number.isFinite(Date.parse(grantedAt))) {
+            throw new AgentOpsError("TRUST_TIMESTAMP_INVALID", "Trust grant timestamp must be an ISO-compatible timestamp.");
+        }
+        await withPrivateFileLock(this.#path, this.#anchorDirectory, async () => {
+            const store = await this.#read();
+            const records = store.records.filter((record) => record.binding.canonicalPath !== binding.canonicalPath &&
+                record.binding.remoteIdentity !== binding.remoteIdentity);
+            records.push({ binding: structuredClone(binding), grantedAt });
+            await this.#write({ schemaVersion: 1, records });
+        });
+    }
+    async revoke(binding) {
+        assertBinding(binding);
+        return await withPrivateFileLock(this.#path, this.#anchorDirectory, async () => {
+            const store = await this.#read();
+            const records = store.records.filter((record) => !sameBinding(record.binding, binding));
+            if (records.length === store.records.length) {
+                return false;
+            }
+            await this.#write({ schemaVersion: 1, records });
+            return true;
+        });
+    }
+}

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

@@ -0,0 +1,43 @@
+export function safeTaskText(value) {
+    return value.replace(/[\u0000-\u001F\u007F-\u009F\u202A-\u202E\u2066-\u2069]/gu, (character) => {
+        if (character === "\n") {
+            return " ";
+        }
+        const codePoint = character.codePointAt(0);
+        return codePoint === undefined
+            ? "\\u{fffd}"
+            : `\\u{${codePoint.toString(16)}}`;
+    });
+}
+export function renderTaskMarkdown(record) {
+    const lines = [
+        `# ${safeTaskText(record.task.title)}`,
+        "",
+        `Task ID: ${record.task.id}`,
+        `Status: ${record.status}`,
+        `Created: ${record.createdAt}`,
+        `Updated: ${record.updatedAt}`,
+        ...(record.completedAt === null
+            ? []
+            : [`Completed: ${record.completedAt}`]),
+        ...(record.archivedAt === null
+            ? []
+            : [`Archived: ${record.archivedAt}`]),
+        "",
+        "## Acceptance criteria",
+        ""
+    ];
+    for (const criterion of record.task.criteria) {
+        const references = record.evidence[criterion.id] ?? [];
+        lines.push(`- ${references.length > 0 ? "[x]" : "[ ]"} ${safeTaskText(criterion.description)} (\`${criterion.id}\`)`, `  - Verifiers: ${criterion.verifierIds
+            .map((id) => `\`${id}\``)
+            .join(", ")}`);
+        if (references.length === 0) {
+            lines.push("  - Evidence: none");
+        }
+        else {
+            lines.push("  - Evidence:", ...references.map((reference) => `    - ${safeTaskText(reference)}`));
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}

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

@@ -0,0 +1,235 @@
+import { randomUUID } from "node:crypto";
+import { SCHEMA_VERSION } from "../contracts.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { validateTask } from "../schema/validate.js";
+import { renderTaskMarkdown } from "./render.js";
+import { advanceFailureFingerprint } from "../verify/fingerprint.js";
+const SESSION_ID_PATTERN = /^[^\0\r\n]{1,256}$/u;
+function defaultTaskId() {
+    return `task-${randomUUID()}`;
+}
+function cloneRecord(record) {
+    return structuredClone(record);
+}
+function taskError(code, message) {
+    return new AgentOpsError(code, message);
+}
+function findTask(state, taskId) {
+    const record = state.tasks.find((candidate) => candidate.task.id === taskId);
+    if (record === undefined) {
+        throw taskError("TASK_NOT_FOUND", `Task not found: ${taskId}`);
+    }
+    return record;
+}
+function replaceTask(state, record) {
+    const index = state.tasks.findIndex((candidate) => candidate.task.id === record.task.id);
+    if (index === -1) {
+        throw taskError("TASK_NOT_FOUND", `Task not found: ${record.task.id}`);
+    }
+    state.tasks[index] = record;
+}
+function assertTimestamp(value) {
+    if (value.length === 0 ||
+        value.length > 64 ||
+        !Number.isFinite(Date.parse(value))) {
+        throw taskError("TASK_TIMESTAMP_INVALID", "Task timestamps must be ISO-compatible.");
+    }
+    return value;
+}
+function assertSessionId(sessionId) {
+    if (!SESSION_ID_PATTERN.test(sessionId)) {
+        throw taskError("TASK_SESSION_INVALID", "Session identity must be a bounded non-empty string.");
+    }
+}
+function normalizeEvidence(task, input) {
+    const criterionIds = new Set(task.criteria.map((criterion) => criterion.id));
+    if (Object.keys(input).length !== criterionIds.size ||
+        Object.keys(input).some((criterionId) => !criterionIds.has(criterionId))) {
+        throw taskError("TASK_EVIDENCE_INCOMPLETE", "Completion requires evidence for every acceptance criterion.");
+    }
+    const evidence = {};
+    for (const criterion of task.criteria) {
+        const references = input[criterion.id];
+        if (references === undefined ||
+            references.length === 0 ||
+            references.some((reference) => typeof reference !== "string" ||
+                reference.length === 0 ||
+                reference.length > 4096 ||
+                reference.includes("\0")) ||
+            new Set(references).size !== references.length) {
+            throw taskError("TASK_EVIDENCE_INCOMPLETE", `Criterion ${criterion.id} requires valid evidence references.`);
+        }
+        evidence[criterion.id] = [...references];
+    }
+    return evidence;
+}
+export class TaskService {
+    #store;
+    #generateId;
+    #now;
+    constructor(store, options = {}) {
+        this.#store = store;
+        this.#generateId = options.generateId ?? defaultTaskId;
+        this.#now = options.now ?? (() => new Date().toISOString());
+    }
+    async create(input) {
+        const task = {
+            schemaVersion: SCHEMA_VERSION,
+            id: this.#generateId(),
+            title: input.title,
+            criteria: [...input.criteria]
+        };
+        const validation = validateTask(task);
+        if (!validation.ok) {
+            throw taskError("TASK_INVALID", validation.errors[0]?.message ?? "Task input is invalid.");
+        }
+        const now = assertTimestamp(this.#now());
+        return await this.#store.mutate((state) => {
+            if (state.tasks.some((record) => record.task.id === validation.value.id)) {
+                throw taskError("TASK_ID_CONFLICT", `Task ID already exists: ${validation.value.id}`);
+            }
+            const record = {
+                task: validation.value,
+                status: "active",
+                evidence: {},
+                createdAt: now,
+                updatedAt: now,
+                completedAt: null,
+                archivedAt: null,
+                failureFingerprint: null
+            };
+            state.tasks.push(record);
+            return cloneRecord(record);
+        });
+    }
+    async list() {
+        const state = await this.#store.read();
+        return state.tasks
+            .map(cloneRecord)
+            .sort((left, right) => left.createdAt.localeCompare(right.createdAt) ||
+            left.task.id.localeCompare(right.task.id));
+    }
+    async status(query) {
+        if ((query.taskId === undefined) ===
+            (query.sessionId === undefined)) {
+            throw taskError("TASK_STATUS_TARGET_REQUIRED", "Task status requires exactly one task or session identity.");
+        }
+        const state = await this.#store.read();
+        if (query.taskId !== undefined) {
+            return cloneRecord(findTask({
+                schemaVersion: 1,
+                tasks: [...state.tasks],
+                sessions: [...state.sessions]
+            }, query.taskId));
+        }
+        const sessionId = query.sessionId;
+        if (sessionId === undefined) {
+            throw taskError("TASK_STATUS_TARGET_REQUIRED", "Task status requires a session identity.");
+        }
+        assertSessionId(sessionId);
+        const attachment = state.sessions.find((candidate) => candidate.sessionId === sessionId);
+        if (attachment === undefined) {
+            throw taskError("TASK_SESSION_UNATTACHED", "The session is not attached to a task.");
+        }
+        const record = state.tasks.find((candidate) => candidate.task.id === attachment.taskId);
+        if (record === undefined) {
+            throw taskError("TASK_STATE_INVALID", "The session references an unknown task.");
+        }
+        return cloneRecord(record);
+    }
+    async attach(sessionId, taskId) {
+        assertSessionId(sessionId);
+        const now = assertTimestamp(this.#now());
+        return await this.#store.mutate((state) => {
+            const record = findTask(state, taskId);
+            if (record.status !== "active") {
+                throw taskError("TASK_NOT_ACTIVE", "Only an active task can be attached to a session.");
+            }
+            const currentIndex = state.sessions.findIndex((attachment) => attachment.sessionId === sessionId);
+            const attachment = { sessionId, taskId, attachedAt: now };
+            if (currentIndex === -1) {
+                state.sessions.push(attachment);
+            }
+            else {
+                state.sessions[currentIndex] = attachment;
+            }
+            return cloneRecord(record);
+        });
+    }
+    async complete(taskId, evidenceInput) {
+        const now = assertTimestamp(this.#now());
+        return await this.#store.mutate((state) => {
+            const current = findTask(state, taskId);
+            if (current.status === "archived") {
+                throw taskError("TASK_NOT_ACTIVE", "An archived task cannot be completed.");
+            }
+            const evidence = normalizeEvidence(current.task, evidenceInput);
+            if (current.status === "complete") {
+                if (JSON.stringify(current.evidence) !== JSON.stringify(evidence)) {
+                    throw taskError("TASK_ALREADY_COMPLETE", "Completed task evidence cannot be replaced.");
+                }
+                return cloneRecord(current);
+            }
+            const completed = {
+                ...current,
+                status: "complete",
+                evidence,
+                updatedAt: now,
+                completedAt: now
+            };
+            replaceTask(state, completed);
+            return cloneRecord(completed);
+        });
+    }
+    async archive(taskId) {
+        const now = assertTimestamp(this.#now());
+        return await this.#store.mutate((state) => {
+            const current = findTask(state, taskId);
+            if (current.status === "archived") {
+                return cloneRecord(current);
+            }
+            const archived = {
+                ...current,
+                status: "archived",
+                updatedAt: now,
+                archivedAt: now
+            };
+            replaceTask(state, archived);
+            state.sessions = state.sessions.filter((attachment) => attachment.taskId !== taskId);
+            return cloneRecord(archived);
+        });
+    }
+    async export(taskId) {
+        return renderTaskMarkdown(await this.status({ taskId }));
+    }
+    async recordFailure(taskId, fingerprint) {
+        const now = assertTimestamp(this.#now());
+        return await this.#store.mutate((state) => {
+            const current = findTask(state, taskId);
+            if (current.status === "archived") {
+                throw taskError("TASK_NOT_ACTIVE", "An archived task cannot record verification failures.");
+            }
+            const advanced = advanceFailureFingerprint(current.failureFingerprint, fingerprint, now);
+            replaceTask(state, {
+                ...current,
+                updatedAt: now,
+                failureFingerprint: advanced.state
+            });
+            return structuredClone(advanced);
+        });
+    }
+    async clearFailure(taskId) {
+        const now = assertTimestamp(this.#now());
+        await this.#store.mutate((state) => {
+            const current = findTask(state, taskId);
+            if (current.failureFingerprint === null) {
+                return;
+            }
+            replaceTask(state, {
+                ...current,
+                updatedAt: now,
+                failureFingerprint: null
+            });
+        });
+    }
+}