@kylecheng3146/agent-ops 0.8.0 → 0.8.3

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

@@ -9,7 +9,7 @@ export function criterionContractHash(criterion) {
 export function taskContractHash(task) {
     return sha256(canonicalJson({ goalHash: goalHash(task), title: task.title,
         intent: task.intent ?? null, revision: task.contractRevision ?? 0,
-        criteria: task.criteria.map(criterionContractHash) }));
+        criteria: task.criteria.map(criterionContractHash), ...(task.debug === undefined ? {} : { debug: task.debug }) }));
 }
 export function treeContractHash(tasks) {
     return sha256(canonicalJson(tasks.map(task => ({ id: task.id, hash: taskContractHash(task) }))

package/dist/runtime/src/task/debug-intake.js

@@ -0,0 +1,12 @@
+/** Conservative intake only; the existing native Agent reasons about the issue. */
+export function isDebugIssue(prompt) {
+    if (prompt.length === 0 || prompt.length > 64 * 1024 || prompt.includes("\0"))
+        return false;
+    const value = prompt.normalize("NFKC").toLowerCase();
+    if (/\b(?:explain|describe|what is|how does|refactor|feature|implement|design)\b|說明|解释|解釋|重構|新增功能|設計|實作功能/u.test(value))
+        return false;
+    return /\b(?:bug|error|fail(?:s|ed|ure)?|exception|crash|regression|500)\b|錯誤|错误|失敗|失败|異常|异常|問題|问题|回傳\s*500/u.test(value) &&
+        /\b(?:fix|debug|investigate|reproduce|diagnose|resolve|repair)\b|修復|修复|調查|调查|重現|重现|診斷|诊断|查明|找出原因|解決|解决/u.test(value);
+}
+/** One issue or cause in different spacing or case is still the same one. */
+export const sameDebugText = (left, right) => left.normalize("NFKC").trim().replace(/\s+/gu, " ").toLowerCase() === right.normalize("NFKC").trim().replace(/\s+/gu, " ").toLowerCase();

package/dist/runtime/src/task/debug-state.js

@@ -0,0 +1,130 @@
+import { canonicalJson } from "../config/hash.js";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+export const DEBUG_DEFAULTS = { enabled: true, budgetMs: 60 * 60_000, maxRounds: 5 };
+export const DEBUG_EXTENSION_MS = 20 * 60_000;
+const object = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const text = (v) => typeof v === "string" && v.length > 0 && v.length <= 4096 && !v.includes("\0");
+const hash = (v) => typeof v === "string" && /^[a-f0-9]{64}$/u.test(v);
+const integer = (v) => Number.isSafeInteger(v) && v >= 0;
+const strings = (v) => Array.isArray(v) && v.length <= 128 && v.every(text) && new Set(v).size === v.length;
+const exact = (v, names) => object(v) && Object.keys(v).length === names.length && names.every(k => Object.hasOwn(v, k));
+const statuses = ["proposed", "investigating", "confirmed", "rejected", "inconclusive"];
+export const debugCauses = ["budget", "iterations", "strategy-required", "stagnation", "environment", "permission", "user-pause", "diagnosed"];
+export function validDebugSettings(v) {
+    return exact(v, ["enabled", "budgetMs", "maxRounds"]) && typeof v.enabled === "boolean" &&
+        integer(v.budgetMs) && v.budgetMs > 0 && v.budgetMs <= 86_400_000 &&
+        integer(v.maxRounds) && v.maxRounds > 0 && v.maxRounds <= 100;
+}
+export function validDebugIntake(v) {
+    return exact(v, ["rootTaskId", "facts", "unknowns"]) && text(v.rootTaskId) && strings(v.facts) && strings(v.unknowns);
+}
+export function validDebugState(v) {
+    const baseKeys = ["schemaVersion", "rootTaskId", "ownerRoot", "baselineCommit", "budgetMs", "maxRounds", "consumedMs", "regressionChecks", "hypotheses", "receipts", "strategy", "grants", "operation", "checkpoint"];
+    if (!object(v) || Object.keys(v).some(k => !baseKeys.includes(k) && k !== "foreground" && k !== "control") || !baseKeys.every(k => Object.hasOwn(v, k)) ||
+        v.schemaVersion !== 1 || !text(v.rootTaskId) || !text(v.ownerRoot) || typeof v.baselineCommit !== "string" || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u.test(v.baselineCommit) ||
+        !validDebugSettings({ enabled: true, budgetMs: v.budgetMs, maxRounds: v.maxRounds }) || !integer(v.consumedMs) || !strings(v.regressionChecks) ||
+        !Array.isArray(v.hypotheses) || v.hypotheses.length > 32 || !Array.isArray(v.receipts) || v.receipts.length > 256 ||
+        !Array.isArray(v.grants) || v.grants.length > 128)
+        return false;
+    if (Object.hasOwn(v, "control") && (!exact(v.control, ["mode", "paused", "sessionId", "eventId", "sourceDigest", "timestamp"]) ||
+        !["full", "diagnose"].includes(String(v.control.mode)) || typeof v.control.paused !== "boolean" || !text(v.control.sessionId) ||
+        v.control.sessionId.length > 256 || !hash(v.control.eventId) || !hash(v.control.sourceDigest) || !integer(v.control.timestamp)))
+        return false;
+    for (const h of v.hypotheses) {
+        if (!exact(h, ["id", "statement", "method", "expected", "checkId", "expectedStatus", "status", "supporting", "opposing", "actual", "history"]) ||
+            ![h.id, h.statement, h.method, h.expected, h.checkId].every(text) || !["PASS", "FAIL"].includes(String(h.expectedStatus)) || !statuses.includes(String(h.status)) ||
+            !strings(h.supporting) || !strings(h.opposing) || typeof h.actual !== "string" || h.actual.length > 4096 ||
+            !Array.isArray(h.history) || h.history.length > 128 || h.history.some(entry => !exact(entry, ["status", "actual", "references", "reason"]) ||
+            !statuses.includes(String(entry.status)) || typeof entry.actual !== "string" || entry.actual.length > 4096 || !strings(entry.references) || !text(entry.reason)))
+            return false;
+    }
+    if (new Set(v.hypotheses.map(h => h.id)).size !== v.hypotheses.length)
+        return false;
+    for (const r of v.receipts)
+        if (!exact(r, ["id", "taskId", "kind", "contractHash", "configHash", "sourceFingerprint", "productDigest", "durationMs", "finishedAt", "round", "progress", "references", "outcome", "cause"]) ||
+            !text(r.id) || !text(r.taskId) || !["investigate", "verify", "review"].includes(String(r.kind)) ||
+            ![r.contractHash, r.configHash, r.sourceFingerprint, r.productDigest].every(hash) || !integer(r.durationMs) || !integer(r.finishedAt) || typeof r.round !== "boolean" ||
+            !strings(r.progress) || !strings(r.references) || !["PASS", "FAIL", "UNKNOWN"].includes(String(r.outcome)) || ![null, "environment", "permission"].includes(r.cause))
+            return false;
+    if (new Set(v.receipts.map(r => r.id)).size !== v.receipts.length || v.receipts.filter(r => r.round).length > v.maxRounds)
+        return false;
+    for (const g of v.grants)
+        if (!exact(g, ["eventId", "sessionId", "sourceDigest", "grantedMs"]) || !text(g.eventId) || !text(g.sessionId) || !hash(g.sourceDigest) || g.grantedMs !== DEBUG_EXTENSION_MS)
+            return false;
+    if (new Set(v.grants.map(g => g.eventId)).size !== v.grants.length)
+        return false;
+    if (v.strategy !== null && (!exact(v.strategy, ["from", "to", "reason", "references", "afterRound"]) ||
+        ![v.strategy.from, v.strategy.to, v.strategy.reason].every(text) || v.strategy.from === v.strategy.to ||
+        !strings(v.strategy.references) || !integer(v.strategy.afterRound) || v.strategy.afterRound < 2))
+        return false;
+    if (v.foreground !== undefined && v.foreground !== null && (!exact(v.foreground, ["sessionId", "startedAt"]) || !text(v.foreground.sessionId) || v.foreground.sessionId.length > 256 || !integer(v.foreground.startedAt)))
+        return false;
+    if (v.operation !== null && (!((exact(v.operation, ["id", "startedAt", "taskId", "contractHash", "configHash", "sourceFingerprint", "productDigest", "kind"])) ||
+        exact(v.operation, ["id", "startedAt", "taskId", "contractHash", "configHash", "sourceFingerprint", "productDigest", "kind", "processId", "processIdentity"])) ||
+        !text(v.operation.id) || !integer(v.operation.startedAt) || !text(v.operation.taskId) ||
+        ![v.operation.contractHash, v.operation.configHash, v.operation.sourceFingerprint, v.operation.productDigest].every(hash) ||
+        !["investigate", "verify", "review"].includes(String(v.operation.kind)) ||
+        (Object.hasOwn(v.operation, "processId") && (!integer(v.operation.processId) || v.operation.processId < 1)) ||
+        (Object.hasOwn(v.operation, "processIdentity") && (!text(v.operation.processIdentity) || v.operation.processIdentity.length > 256))))
+        return false;
+    if (v.checkpoint !== null && (!exact(v.checkpoint, ["taskId", "sessionId", "root", "sourceFingerprint", "contractHash", "configHash", "cause", "receiptId"]) ||
+        ![v.checkpoint.taskId, v.checkpoint.sessionId, v.checkpoint.root, v.checkpoint.receiptId].every(text) ||
+        ![v.checkpoint.sourceFingerprint, v.checkpoint.contractHash, v.checkpoint.configHash].every(hash) || (v.checkpoint.cause !== null && !debugCauses.includes(v.checkpoint.cause))))
+        return false;
+    return true;
+}
+export function createDebugState(rootTaskId, baselineCommit, settings = DEBUG_DEFAULTS, ownerRoot = ".") {
+    return { schemaVersion: 1, rootTaskId, ownerRoot, baselineCommit, budgetMs: settings.budgetMs, maxRounds: settings.maxRounds, consumedMs: 0, regressionChecks: [],
+        hypotheses: [], receipts: [], strategy: null, grants: [], foreground: null, operation: null, checkpoint: null };
+}
+export function debugRounds(state) { return state.receipts.filter(r => r.round).length; }
+export function debugRemainingMs(state, now = Date.now()) {
+    const starts = [state.foreground?.startedAt, state.operation?.startedAt].filter((startedAt) => startedAt !== undefined);
+    const active = starts.length === 0 ? 0 : Math.max(0, now - Math.min(...starts));
+    return Math.max(0, state.budgetMs + state.grants.reduce((n, g) => n + g.grantedMs, 0) - state.consumedMs - active);
+}
+export function debugStopCause(state, now = Date.now()) {
+    if (state.control?.paused === true)
+        return "user-pause";
+    const latest = state.receipts.at(-1);
+    if (latest?.cause !== null && latest?.cause !== undefined)
+        return latest.cause;
+    if (debugRemainingMs(state, now) === 0)
+        return "budget";
+    if (debugRounds(state) >= state.maxRounds)
+        return "iterations";
+    const rounds = state.receipts.filter(r => r.round);
+    const since = rounds.slice(state.strategy?.afterRound ?? 0);
+    let stagnant = 0;
+    for (const round of [...since].reverse()) {
+        if (round.progress.length > 0)
+            break;
+        stagnant++;
+    }
+    return stagnant >= 2 ? state.strategy === null ? "strategy-required" : "stagnation" : null;
+}
+/** Only reviewed reasoning/proof belongs in the digest; operations and clocks do not. */
+export function debugProofDigest(state) {
+    return sha256(canonicalJson({ rootTaskId: state.rootTaskId, baselineCommit: state.baselineCommit, regressionChecks: state.regressionChecks, hypotheses: state.hypotheses,
+        strategy: state.strategy, proof: state.receipts.filter(r => r.kind === "verify").map(r => ({ taskId: r.taskId, contractHash: r.contractHash,
+            configHash: r.configHash, sourceFingerprint: r.sourceFingerprint, productDigest: r.productDigest, references: r.references, outcome: r.outcome })) }));
+}
+export function assertDebugState(value) {
+    if (!validDebugState(value))
+        throw new AgentOpsError("TASK_DEBUG_STATE_INVALID", "Debug state must be strict, bounded and root-bound.");
+}
+export async function loadDebugProof(root, rootTaskId) {
+    const { FileTaskStore } = await import("./store.js");
+    const { join } = await import("node:path");
+    const record = (await new FileTaskStore(join(root, ".agent-ops/tasks/state.json"), root).read()).tasks.find(r => r.task.id === rootTaskId);
+    if (record?.debug === undefined || record.task.debug?.rootTaskId !== rootTaskId)
+        throw new AgentOpsError("TASK_DEBUG_ROOT_MISMATCH", "Original issue proof is unavailable; do not reset its limits.");
+    if (record.debug.ownerRoot !== root) {
+        const owned = (await new FileTaskStore(join(record.debug.ownerRoot, ".agent-ops/tasks/state.json"), record.debug.ownerRoot).read()).tasks.find(r => r.task.id === rootTaskId);
+        if (owned?.debug === undefined || owned.debug.ownerRoot !== record.debug.ownerRoot || owned.task.goal !== record.task.goal)
+            throw new AgentOpsError("TASK_DEBUG_ROOT_MISMATCH", "Original owned issue state is unavailable; do not recreate its budget.");
+        return owned.debug;
+    }
+    return record.debug;
+}

package/dist/runtime/src/task/debug-user-event.js

@@ -0,0 +1,93 @@
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+export function debugUserControl(text) {
+    const value = text.trim();
+    if (/^(?:暫停|暂停|先暫停|先暂停|停止|stop|pause)[。.!！]?$/iu.test(value))
+        return "pause";
+    if (/^(?:先)?只診斷(?:，等我補失敗時證據)?[。.!！]?$/u.test(value) || /^(?:先)?只诊断[。.!！]?$/u.test(value) || /^diagnos(?:e|is)[ -]only[.!]?$/iu.test(value))
+        return "diagnose";
+    if (/^(?:繼續|继续|continue|resume)[。.!！]?$/iu.test(value))
+        return "resume";
+    if (/^(?:繼續修復|继续修复|開始修復|开始修复|resume repair)[。.!！]?$/iu.test(value))
+        return "repair";
+    return null;
+}
+function codexUserText(row) {
+    if (row?.type === "event_msg" && row.payload?.type === "user_message")
+        return row.payload.message;
+    const message = row?.payload;
+    if (row?.type !== "response_item" || message?.type !== "message" || message.role !== "user")
+        return undefined;
+    const kinds = message.internal_chat_message_metadata_passthrough?.content_item_kinds;
+    if (!Array.isArray(kinds) || kinds.length === 0 || !kinds.every(k => k === "user.text") || !Array.isArray(message.content) ||
+        message.content.length !== kinds.length || !message.content.every((c) => c?.type === "input_text" && typeof c.text === "string"))
+        return undefined;
+    const text = message.content.map((c) => c.text).join("\n");
+    const reply = /^<send_user_message_question_reply>\s*([\s\S]*)\s*<\/send_user_message_question_reply>$/u.exec(text.trim());
+    if (reply === null)
+        return text;
+    try {
+        const answers = JSON.parse(reply[1]);
+        if (Array.isArray(answers) && answers.length === 1 && typeof answers[0]?.answer === "string")
+            return answers[0].answer;
+    }
+    catch { /* An ambiguous reply cannot authorize a control change. */ }
+    return undefined;
+}
+/** Host transcripts are the user-event authority; CLI actor/text fields are never accepted. */
+export async function readDebugUserEvent(root, sessionId, home = homedir(), kind = "latest") {
+    if (!/^[a-f0-9-]{36}$/u.test(sessionId))
+        throw new AgentOpsError("TASK_DEBUG_GRANT_UNSUPPORTED", "This host has no identifiable native user-event source.");
+    const canonicalHome = await realpath(home).catch(() => home);
+    const paths = [join(home, ".claude/projects", root.replace(/[^a-zA-Z0-9]/gu, "-"), sessionId + ".jsonl")];
+    const codex = join(home, ".codex/sessions");
+    async function visit(path, depth) {
+        if (paths.length > 4096)
+            return;
+        try {
+            for (const entry of await readdir(path, { withFileTypes: true })) {
+                if (entry.isDirectory() && depth > 0)
+                    await visit(join(path, entry.name), depth - 1);
+                else if (entry.isFile() && entry.name.endsWith(sessionId + ".jsonl"))
+                    paths.push(join(path, entry.name));
+            }
+        }
+        catch { /* The host need not be installed. */ }
+    }
+    await visit(codex, 3);
+    for (const path of paths) {
+        try {
+            const stat = await lstat(path), canonical = await realpath(path);
+            const fromHome = relative(canonicalHome, canonical);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16 * 1024 * 1024 || fromHome.startsWith("..") || isAbsolute(fromHome))
+                continue;
+            const lines = (await readFile(path, "utf8")).split("\n");
+            const rows = lines.map(line => { try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            } });
+            const codexSource = path.startsWith(codex + sep);
+            if (codexSource && !rows.some(row => row?.type === "session_meta" && row.payload?.id === sessionId && row.payload?.cwd === root))
+                continue;
+            for (let index = rows.length - 1; index >= 0; index--) {
+                const row = rows[index];
+                const text = codexSource ? codexUserText(row) :
+                    row?.type === "user" && row.sessionId === sessionId && row.cwd === root && row.message?.role === "user" ? row.message.content : undefined;
+                if (typeof text !== "string" || text.length > 64 * 1024 || (kind === "control" && debugUserControl(text) === null))
+                    continue;
+                const timestamp = Date.parse(row.timestamp);
+                if (!Number.isFinite(timestamp))
+                    break;
+                const sourceDigest = sha256(lines[index]);
+                return { id: sha256(relative(home, path) + ":" + index + ":" + sourceDigest), sourceDigest, text, timestamp };
+            }
+        }
+        catch { /* An unavailable native source cannot grant time. */ }
+    }
+    throw new AgentOpsError("TASK_DEBUG_GRANT_UNSUPPORTED", "No current native human event can authorize this extension. Request explicit host approval; this CLI cannot self-grant it.");
+}