@kylecheng3146/agent-ops 0.0.1

package/dist/packages/cli/src/commands/task.js

@@ -0,0 +1,141 @@
+import { AgentOpsError } from "../../../../runtime/src/fs/paths.js";
+import { renderTaskMarkdown, safeTaskText } from "../../../../runtime/src/task/render.js";
+import { errorEnvelope, okEnvelope } from "../output.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseCriterion(source) {
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        throw new AgentOpsError("TASK_CRITERION_INVALID", "Each --criterion value must be a JSON criterion object.");
+    }
+    if (!isRecord(value) ||
+        Object.keys(value).sort().join(",") !==
+            "description,id,verifierIds" ||
+        typeof value.id !== "string" ||
+        typeof value.description !== "string" ||
+        !Array.isArray(value.verifierIds) ||
+        value.verifierIds.some((id) => typeof id !== "string")) {
+        throw new AgentOpsError("TASK_CRITERION_INVALID", "Each criterion requires only id, description, and verifierIds.");
+    }
+    return {
+        id: value.id,
+        description: value.description,
+        verifierIds: [...value.verifierIds]
+    };
+}
+function parseEvidence(values) {
+    const evidence = {};
+    for (const value of values) {
+        const separator = value.indexOf("=");
+        if (separator <= 0 || separator === value.length - 1) {
+            throw new AgentOpsError("TASK_EVIDENCE_INVALID", "Each --evidence value must use criterion-id=reference.");
+        }
+        const criterionId = value.slice(0, separator);
+        const reference = value.slice(separator + 1);
+        const references = evidence[criterionId] ?? [];
+        references.push(reference);
+        evidence[criterionId] = references;
+    }
+    return evidence;
+}
+function requireTaskId(args) {
+    if (args.taskId === undefined) {
+        throw new AgentOpsError("TASK_ID_REQUIRED", "This task action requires --task <id>.");
+    }
+    return args.taskId;
+}
+function taskAction(args) {
+    if (args.command !== "task" ||
+        args.action === undefined ||
+        ![
+            "archive",
+            "attach",
+            "complete",
+            "create",
+            "export",
+            "status"
+        ].includes(args.action)) {
+        throw new AgentOpsError("TASK_ACTION_INVALID", "A supported task action is required.");
+    }
+    return args.action;
+}
+function taskEnvelope(action, code, message, record) {
+    return okEnvelope(code, {
+        action,
+        message,
+        record,
+        text: renderTaskMarkdown(record)
+    });
+}
+function renderTaskList(records) {
+    if (records.length === 0) {
+        return "No tasks.\n";
+    }
+    return `${records
+        .map((record) => `- ${record.task.id} [${record.status}] ${safeTaskText(record.task.title)}`)
+        .join("\n")}\n`;
+}
+export async function runTaskCommand(options) {
+    try {
+        const action = taskAction(options.args);
+        const sessionId = options.args.sessionId ?? options.sessionId;
+        if (action === "create") {
+            if (options.args.title === undefined) {
+                throw new AgentOpsError("TASK_TITLE_REQUIRED", "Task creation requires --title.");
+            }
+            const record = await options.service.create({
+                title: options.args.title,
+                criteria: (options.args.criteria ?? []).map(parseCriterion)
+            });
+            return taskEnvelope(action, "TASK_CREATED", `Created task ${record.task.id}.`, record);
+        }
+        if (action === "status") {
+            if (options.args.taskId === undefined && sessionId === undefined) {
+                const records = await options.service.list();
+                return okEnvelope("TASK_LISTED", {
+                    action,
+                    message: `Listed ${records.length} task(s).`,
+                    records,
+                    text: renderTaskList(records)
+                });
+            }
+            const record = await options.service.status(options.args.taskId === undefined
+                ? { sessionId }
+                : { taskId: options.args.taskId });
+            return taskEnvelope(action, "TASK_STATUS", `Read task ${record.task.id}.`, record);
+        }
+        if (action === "attach") {
+            if (sessionId === undefined) {
+                throw new AgentOpsError("TASK_SESSION_REQUIRED", "Task attachment requires an injected session identity or --session.");
+            }
+            const record = await options.service.attach(sessionId, requireTaskId(options.args));
+            return taskEnvelope(action, "TASK_ATTACHED", `Attached session to ${record.task.id}.`, record);
+        }
+        if (action === "complete") {
+            const record = await options.service.complete(requireTaskId(options.args), parseEvidence(options.args.evidence ?? []));
+            return taskEnvelope(action, "TASK_COMPLETED", `Completed task ${record.task.id}.`, record);
+        }
+        if (action === "archive") {
+            const record = await options.service.archive(requireTaskId(options.args));
+            return taskEnvelope(action, "TASK_ARCHIVED", `Archived task ${record.task.id}.`, record);
+        }
+        const taskId = requireTaskId(options.args);
+        const record = await options.service.status({ taskId });
+        return okEnvelope("TASK_EXPORTED", {
+            action,
+            message: `Exported task ${record.task.id}.`,
+            record,
+            text: await options.service.export(taskId)
+        });
+    }
+    catch (error) {
+        if (error instanceof AgentOpsError) {
+            return errorEnvelope(error.code, error.message);
+        }
+        throw error;
+    }
+}

package/dist/packages/cli/src/commands/trust.js

@@ -0,0 +1,48 @@
+import { okEnvelope } from "../output.js";
+function trustError(code, message, binding) {
+    return {
+        code,
+        status: "error",
+        data: { binding },
+        errors: [{ code, message }]
+    };
+}
+export async function runTrustCommand(options) {
+    const binding = await options.calculateBinding();
+    switch (options.action) {
+        case "status": {
+            const trust = await options.store.status(binding);
+            return okEnvelope("TRUST_STATUS", {
+                binding,
+                trust,
+                message: `Repository trust status: ${trust.status}`
+            });
+        }
+        case "revoke": {
+            const revoked = await options.store.revoke(binding);
+            return okEnvelope("TRUST_REVOKED", {
+                binding,
+                revoked,
+                message: revoked
+                    ? "Repository trust was revoked."
+                    : "No exact repository trust record existed."
+            });
+        }
+        case "grant": {
+            await options.presentBinding(binding);
+            if (!options.isTTY && !options.yes) {
+                return trustError("TRUST_CONFIRMATION_REQUIRED", "Non-interactive trust grant requires: agent-ops trust grant --yes", binding);
+            }
+            if (options.isTTY &&
+                !options.yes &&
+                !(await options.confirmGrant(binding))) {
+                return trustError("TRUST_GRANT_CANCELLED", "Repository trust was not granted.", binding);
+            }
+            await options.store.grant(binding);
+            return okEnvelope("TRUST_GRANTED", {
+                binding,
+                message: "Repository trust was granted for the displayed binding."
+            });
+        }
+    }
+}

package/dist/packages/cli/src/commands/uninstall.js

@@ -0,0 +1,58 @@
+import { applyUninstallPlan, createUninstallPlan } from "../../../../runtime/src/install/uninstall.js";
+import { okEnvelope } from "../output.js";
+import { formatOperationPlan } from "../plan-output.js";
+function formatUninstallPlan(plan) {
+    return formatOperationPlan({
+        title: "Uninstall plan",
+        metadata: [
+            `Installed: ${plan.installed ? "yes" : "no"}`,
+            ...(plan.manifest === null
+                ? []
+                : [
+                    `Scope: ${plan.manifest.scope}`,
+                    `Harness: ${plan.manifest.harness}`
+                ])
+        ],
+        operations: plan.operations
+    });
+}
+function uninstallError(code, message, plan) {
+    return {
+        code,
+        status: "error",
+        data: { applied: false, plan, message },
+        errors: [{ code, message }]
+    };
+}
+export async function runUninstallCommand(options) {
+    const plan = await createUninstallPlan(options.root);
+    if (!plan.installed) {
+        return okEnvelope("UNINSTALL_NOT_INSTALLED", {
+            applied: false,
+            plan,
+            message: "No managed installation exists."
+        });
+    }
+    if (options.args.dryRun) {
+        return okEnvelope("UNINSTALL_PLAN_READY", {
+            applied: false,
+            plan,
+            message: "Uninstall plan calculated; no files were changed.",
+            text: formatUninstallPlan(plan)
+        });
+    }
+    if (!options.args.yes && !options.isTTY) {
+        return uninstallError("UNINSTALL_CONFIRMATION_REQUIRED", "Non-interactive uninstall requires --yes.", plan);
+    }
+    if (!options.args.yes &&
+        !(await options.confirm(plan))) {
+        return uninstallError("UNINSTALL_CANCELLED", "Uninstall was cancelled; no files were changed.", plan);
+    }
+    await applyUninstallPlan(options.root, plan);
+    return okEnvelope("UNINSTALL_APPLIED", {
+        applied: true,
+        plan,
+        message: "Managed installation content was removed."
+    });
+}
+export { formatUninstallPlan };

package/dist/packages/cli/src/commands/update.js

@@ -0,0 +1,58 @@
+import { applyUpdatePlan, createUpdatePlan } from "../../../../runtime/src/install/update.js";
+import { okEnvelope } from "../output.js";
+import { formatOperationPlan } from "../plan-output.js";
+export function formatUpdatePlan(plan) {
+    return formatOperationPlan({
+        title: "Update plan",
+        metadata: [
+            `Target version: ${plan.targetVersion}`,
+            `Schema migrations: ${plan.migrationSteps.length === 0
+                ? "none"
+                : plan.migrationSteps
+                    .map(({ fromVersion, toVersion }) => `${fromVersion} -> ${toVersion}`)
+                    .join(", ")}`
+        ],
+        operations: plan.installation.operations
+    });
+}
+function updateError(code, message, plan) {
+    return {
+        code,
+        status: "error",
+        data: { applied: false, plan, message },
+        errors: [{ code, message }]
+    };
+}
+export async function runUpdateCommand(options) {
+    const plan = await createUpdatePlan({
+        root: options.root,
+        adapters: options.adapters,
+        ...(options.registry === undefined
+            ? {}
+            : { registry: options.registry }),
+        ...(options.targetVersion === undefined
+            ? {}
+            : { targetVersion: options.targetVersion })
+    });
+    if (options.args.dryRun) {
+        return okEnvelope("UPDATE_PLAN_READY", {
+            applied: false,
+            plan,
+            message: "Update plan calculated; no files were changed.",
+            text: formatUpdatePlan(plan)
+        });
+    }
+    if (!options.args.yes && !options.isTTY) {
+        return updateError("UPDATE_CONFIRMATION_REQUIRED", "Non-interactive update requires --yes.", plan);
+    }
+    if (!options.args.yes &&
+        !(await options.confirm(plan))) {
+        return updateError("UPDATE_CANCELLED", "Update was cancelled; no files were changed.", plan);
+    }
+    await applyUpdatePlan(options.root, plan);
+    return okEnvelope("UPDATE_APPLIED", {
+        applied: true,
+        plan,
+        message: `Managed installation updated to ${plan.targetVersion}.`
+    });
+}

package/dist/packages/cli/src/commands/verify.js

@@ -0,0 +1,108 @@
+import { AgentOpsError } from "../../../../runtime/src/fs/paths.js";
+import { redactSecrets } from "../../../../runtime/src/security/redact.js";
+import { safeTaskText } from "../../../../runtime/src/task/render.js";
+import { errorEnvelope, okEnvelope } from "../output.js";
+function safe(value) {
+    return safeTaskText(redactSecrets(value));
+}
+function publicReport(report) {
+    return {
+        taskId: report.taskId,
+        status: report.status,
+        surface: {
+            staged: report.surface.staged.map(redactSecrets),
+            unstaged: report.surface.unstaged.map(redactSecrets),
+            untracked: report.surface.untracked.map(redactSecrets),
+            paths: report.surface.paths.map(redactSecrets)
+        },
+        selection: {
+            verifierIds: [...report.selection.verifierIds],
+            fallback: report.selection.fallback,
+            reason: report.selection.reason,
+            evidence: {
+                changedPaths: report.selection.evidence.changedPaths.map(redactSecrets),
+                mappings: report.selection.evidence.mappings.map((mapping) => ({
+                    changedPath: redactSecrets(mapping.changedPath),
+                    mappingPaths: mapping.mappingPaths.map(redactSecrets),
+                    verifierIds: [...mapping.verifierIds]
+                })),
+                requiredVerifierIds: [
+                    ...report.selection.evidence.requiredVerifierIds
+                ]
+            }
+        },
+        results: report.results.map((result) => ({
+            commandId: result.commandId,
+            required: result.required,
+            status: result.status,
+            failureClass: result.failureClass,
+            exitCode: result.exitCode,
+            timedOut: result.timedOut,
+            testCount: result.testCount,
+            evidenceReferences: result.evidenceReferences.map(redactSecrets)
+        })),
+        signal: report.signal
+    };
+}
+function formatResult(result) {
+    const testCount = result.testCount === null ? "" : ` (tests: ${result.testCount})`;
+    const lines = [
+        `- ${result.status} ${safe(result.commandId)}${testCount}`
+    ];
+    if (result.evidenceReferences.length > 0) {
+        lines.push(...result.evidenceReferences.map((reference) => `  Evidence: ${safe(reference)}`));
+    }
+    return lines;
+}
+function formatReport(report) {
+    const lines = [
+        `Verification task ${safe(report.taskId)}: ${report.status}`,
+        `Scope: ${report.selection.reason} (${report.selection.fallback ? "fallback" : "bounded"})`,
+        ...report.results.flatMap(formatResult)
+    ];
+    if (report.signal !== null) {
+        lines.push(`Signal: ${report.signal}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+async function resolveTaskId(options) {
+    if (options.args.taskId !== undefined) {
+        return options.args.taskId;
+    }
+    const sessionId = options.args.sessionId ?? options.sessionId;
+    if (sessionId === undefined) {
+        throw new AgentOpsError("VERIFY_TASK_REQUIRED", "Verification requires --task, --session, or an injected session identity.");
+    }
+    return (await options.taskService.status({ sessionId })).task.id;
+}
+export async function runVerifyCommand(options) {
+    try {
+        const report = publicReport(await options.service.verify(await resolveTaskId(options)));
+        const text = formatReport(report);
+        if (report.status === "PASS") {
+            return okEnvelope("VERIFICATION_PASSED", {
+                message: "Required verification passed.",
+                report,
+                text
+            });
+        }
+        const code = report.status === "FAIL"
+            ? "VERIFICATION_FAILED"
+            : "VERIFICATION_UNKNOWN";
+        const message = report.status === "FAIL"
+            ? "Required verification failed."
+            : "Required verification could not be established.";
+        return {
+            code,
+            status: "error",
+            data: { message, report, text },
+            errors: [{ code, message }]
+        };
+    }
+    catch (error) {
+        if (error instanceof AgentOpsError) {
+            return errorEnvelope(error.code, safe(error.message));
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +1,53 @@
+export function okEnvelope(code, data) {
+    return {
+        code,
+        status: "ok",
+        data: data === undefined ? null : data,
+        errors: []
+    };
+}
+export function errorEnvelope(code, message) {
+    return {
+        code,
+        status: "error",
+        data: null,
+        errors: [{ code, message }]
+    };
+}
+function humanSuccess(envelope) {
+    if (typeof envelope.data === "object" && envelope.data !== null) {
+        const data = envelope.data;
+        if (typeof data.text === "string") {
+            return data.text.endsWith("\n") ? data.text : `${data.text}\n`;
+        }
+        if (typeof data.version === "string") {
+            return `${data.version}\n`;
+        }
+        if (typeof data.message === "string") {
+            return `${data.message}\n`;
+        }
+    }
+    return `${envelope.code}\n`;
+}
+function humanError(envelope) {
+    if (typeof envelope.data === "object" && envelope.data !== null) {
+        const data = envelope.data;
+        if (typeof data.text === "string") {
+            return data.text.endsWith("\n") ? data.text : `${data.text}\n`;
+        }
+    }
+    const message = envelope.errors[0]?.message ?? envelope.code;
+    return `${message}\n`;
+}
+export function writeEnvelope(sink, envelope, json) {
+    if (json) {
+        const normalized = envelope.data === undefined ? { ...envelope, data: null } : envelope;
+        sink.writeStdout(`${JSON.stringify(normalized)}\n`);
+        return;
+    }
+    if (envelope.status === "ok") {
+        sink.writeStdout(humanSuccess(envelope));
+        return;
+    }
+    sink.writeStderr(humanError(envelope));
+}

package/dist/packages/cli/src/plan-output.js

@@ -0,0 +1,28 @@
+function escapeTerminalText(value) {
+    return value.replace(/[\u0000-\u0009\u000B-\u001F\u007F-\u009F\u202A-\u202E\u2066-\u2069]/gu, (character) => {
+        const codePoint = character.codePointAt(0);
+        if (codePoint === undefined) {
+            return "\\u{fffd}";
+        }
+        return codePoint <= 0xff
+            ? `\\x${codePoint.toString(16).padStart(2, "0")}`
+            : `\\u{${codePoint.toString(16)}}`;
+    });
+}
+export function formatOperationPlan(options) {
+    const lines = [
+        options.title,
+        ...options.metadata.map(escapeTerminalText),
+        "Operations:"
+    ];
+    for (const operation of options.operations) {
+        lines.push(`- ${operation.kind} ${escapeTerminalText(operation.path)}`, `  expected: ${operation.expectedHash ?? "<absent>"}`);
+        if (operation.kind === "write") {
+            lines.push("  content:", ...operation.content
+                .replace(/\n$/u, "")
+                .split("\n")
+                .map((line) => `    ${escapeTerminalText(line)}`));
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}

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

@@ -0,0 +1,75 @@
+import { CliArgumentError } from "./args.js";
+const SCOPES = new Set(["project", "user"]);
+const HARNESSES = new Set(["both", "claude", "codex"]);
+const PROFILES = new Set(["advisory", "core", "guardrails"]);
+async function createPromptSession(io) {
+    if (!io.isTTY) {
+        throw new CliArgumentError("CLI_INTERACTIVE_REQUIRED", "Missing init choices require an interactive terminal.");
+    }
+    if (io.prompt !== undefined) {
+        return {
+            question: io.prompt,
+            close: () => undefined
+        };
+    }
+    if (io.input === undefined || io.output === undefined) {
+        throw new CliArgumentError("CLI_INTERACTIVE_IO_REQUIRED", "Interactive input and output streams are unavailable.");
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const readline = createInterface({
+        input: io.input,
+        output: io.output
+    });
+    return {
+        question: (prompt) => readline.question(prompt),
+        close: () => readline.close()
+    };
+}
+function selectValue(raw, fallback, allowed, label) {
+    const value = raw.trim() === "" ? fallback : raw.trim();
+    if (!allowed.has(value)) {
+        throw new CliArgumentError("CLI_INVALID_VALUE", `Invalid ${label}: ${value}`);
+    }
+    return value;
+}
+function selectProfiles(raw) {
+    const values = raw.trim() === ""
+        ? ["core"]
+        : raw.split(",").map((value) => value.trim());
+    if (values.length === 0 ||
+        values.some((value) => !PROFILES.has(value)) ||
+        new Set(values).size !== values.length) {
+        throw new CliArgumentError("CLI_INVALID_VALUE", "Profiles must be a unique comma-separated list of core, advisory, or guardrails.");
+    }
+    return values;
+}
+export async function completeInitChoices(args, io) {
+    if (args.command !== "init" ||
+        (args.scope !== undefined &&
+            args.harness !== undefined &&
+            args.profiles.length > 0)) {
+        return args;
+    }
+    if (!io.isTTY) {
+        throw new CliArgumentError("CLI_INTERACTIVE_REQUIRED", "Non-interactive init requires --scope, --harness, and at least one --profile.");
+    }
+    const session = await createPromptSession(io);
+    try {
+        const scope = args.scope ??
+            selectValue(await session.question("Scope (project/user) [project]: "), "project", SCOPES, "scope");
+        const harness = args.harness ??
+            selectValue(await session.question("Harness (both/claude/codex) [both]: "), "both", HARNESSES, "harness");
+        const profiles = args.profiles.length > 0
+            ? args.profiles
+            : selectProfiles(await session.question("Profiles (core,advisory,guardrails) [core]: "));
+        return {
+            ...args,
+            scope,
+            harness,
+            profiles
+        };
+    }
+    finally {
+        session.close();
+    }
+}

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

@@ -0,0 +1,109 @@
+import { AgentOpsError } from "../../fs/paths.js";
+export function claudeSettingsTarget(scope) {
+    return scope === "project"
+        ? {
+            path: ".claude/settings.json",
+            requiresWorkspaceTrust: true
+        }
+        : {
+            path: "~/.claude/settings.json",
+            requiresWorkspaceTrust: false
+        };
+}
+export function claudeRoutingBlock() {
+    return [
+        "## Loop Engineering",
+        "",
+        "Load `.agent-ops/CLAUDE.md` as concise project context.",
+        ""
+    ].join("\n");
+}
+function commandHook(event, runtimePath) {
+    return {
+        type: "command",
+        command: "node",
+        args: [
+            runtimePath,
+            "claude",
+            event,
+            "--managed-by=agent-ops"
+        ],
+        timeout: 30
+    };
+}
+function matcherGroup(event, runtimePath) {
+    return {
+        ...(event === "PreToolUse" ? { matcher: "Bash" } : {}),
+        hooks: [commandHook(event, runtimePath)]
+    };
+}
+export function buildClaudeHookSettings(capabilities, runtimePath) {
+    if (runtimePath.length === 0 ||
+        runtimePath.length > 4096 ||
+        runtimePath.includes("\0")) {
+        throw new AgentOpsError("CLAUDE_HOOK_PATH_INVALID", "Claude hook runtime path is invalid.");
+    }
+    const hooks = {};
+    if (capabilities.includes("lifecycle-summary")) {
+        hooks.SessionStart = [matcherGroup("SessionStart", runtimePath)];
+    }
+    if (capabilities.includes("command-policy")) {
+        hooks.PreToolUse = [matcherGroup("PreToolUse", runtimePath)];
+    }
+    if (capabilities.includes("optional-stop-verify")) {
+        hooks.Stop = [matcherGroup("Stop", runtimePath)];
+    }
+    return { hooks };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOwnedHandler(handler) {
+    if (!isRecord(handler) ||
+        handler.command !== "node" ||
+        !Array.isArray(handler.args)) {
+        return false;
+    }
+    return handler.args[3] === "--managed-by=agent-ops";
+}
+function withoutOwnedHandlers(value) {
+    if (!isRecord(value) || !Array.isArray(value.hooks)) {
+        return value;
+    }
+    const hooks = value.hooks.filter((handler) => !isOwnedHandler(handler));
+    return hooks.length === 0 ? null : { ...value, hooks };
+}
+function hookRecord(settings) {
+    if (settings.hooks === undefined) {
+        return {};
+    }
+    if (!isRecord(settings.hooks) ||
+        Object.values(settings.hooks).some((groups) => !Array.isArray(groups))) {
+        throw new AgentOpsError("CLAUDE_SETTINGS_INVALID", "Claude hook groups must be arrays.");
+    }
+    return settings.hooks;
+}
+export function mergeClaudeSettings(existing, managed) {
+    if (!isRecord(existing)) {
+        throw new AgentOpsError("CLAUDE_SETTINGS_INVALID", "Claude settings must be a JSON object.");
+    }
+    const existingHooks = hookRecord(existing);
+    const hooks = {};
+    const eventNames = new Set([
+        ...Object.keys(existingHooks),
+        ...Object.keys(managed.hooks)
+    ]);
+    for (const eventName of eventNames) {
+        const preserved = (existingHooks[eventName] ?? [])
+            .map(withoutOwnedHandlers)
+            .filter((group) => group !== null);
+        const additions = managed.hooks[eventName] ?? [];
+        if (preserved.length > 0 || additions.length > 0) {
+            hooks[eventName] = [...preserved, ...additions];
+        }
+    }
+    return {
+        ...existing,
+        hooks
+    };
+}