@kylecheng3146/agent-ops 0.7.3 → 0.8.3

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

@@ -54,7 +54,7 @@ export function buildAgyHookSettings(capabilities, runtimePath, platform = proce
         throw new AgentOpsError("AGY_HOOK_PATH_INVALID", "agy hook runtime path is invalid.");
     }
     const hooks = {};
-    if ((capabilities.includes("lifecycle-summary") || capabilities.includes("office-presence")) || capabilities.includes("project-loop")) {
+    if ((capabilities.includes("lifecycle-summary") || capabilities.includes("office-presence") || capabilities.includes("task-debug")) || capabilities.includes("project-loop")) {
         hooks.PreInvocation = [handler(runtimePath, "SessionStart", platform)];
     }
     if ((capabilities.includes("command-policy") || capabilities.includes("office-presence")) || capabilities.includes("project-loop")) {
@@ -62,7 +62,8 @@ export function buildAgyHookSettings(capabilities, runtimePath, platform = proce
     }
     if (capabilities.includes("office-presence") ||
         capabilities.includes("optional-stop-verify") ||
-        capabilities.includes("completion-gate")) {
+        capabilities.includes("completion-gate") ||
+        capabilities.includes("task-debug")) {
         hooks.Stop = [handler(runtimePath, "Stop", platform, capabilities.includes("completion-gate"))];
     }
     return { hooks };

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

@@ -113,8 +113,12 @@ export function buildClaudeHookSettings(capabilities, runtimePath, platform = pr
         if (capabilities.includes("lifecycle-summary") || capabilities.includes("office-presence")) {
             hooks.SessionStart = [matcherGroup("SessionStart", runtimePath)];
         }
-        if (capabilities.includes("command-policy") || capabilities.includes("office-presence")) {
-            hooks.PreToolUse = [matcherGroup("PreToolUse", runtimePath)];
+        // The loop has its own prompt hook. Outside it, a prompt is both the
+        // turn's start for Office and content for command policy.
+        if (capabilities.includes("command-policy") || capabilities.includes("office-presence") || capabilities.includes("task-debug")) {
+            hooks.UserPromptSubmit = [matcherGroup("UserPromptSubmit", runtimePath)];
+            if (capabilities.includes("command-policy") || capabilities.includes("office-presence"))
+                hooks.PreToolUse = [matcherGroup("PreToolUse", runtimePath)];
         }
     }
     // The gate supersedes report-only Stop verification: one managed Stop
@@ -122,7 +126,7 @@ export function buildClaudeHookSettings(capabilities, runtimePath, platform = pr
     if (capabilities.includes("completion-gate")) {
         hooks.Stop = [matcherGroup("Stop", runtimePath, true)];
     }
-    else if (capabilities.includes("optional-stop-verify") || capabilities.includes("office-presence")) {
+    else if (capabilities.includes("task-debug") || capabilities.includes("optional-stop-verify") || capabilities.includes("office-presence")) {
         hooks.Stop = [matcherGroup("Stop", runtimePath)];
     }
     // Stop only ends a turn. SessionEnd is the one signal that the conversation

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

@@ -82,13 +82,20 @@ export function buildCodexHookConfig(capabilities, runtimePath) {
         if (capabilities.includes("lifecycle-summary") || capabilities.includes("office-presence")) {
             hooks.SessionStart = [matcherGroup("SessionStart", runtimePath)];
         }
-        if (capabilities.includes("command-policy") || capabilities.includes("office-presence")) {
-            hooks.PreToolUse = [matcherGroup("PreToolUse", runtimePath)];
+        // The loop has its own prompt hook. Outside it, a prompt is both the
+        // turn's start for Office and content for command policy.
+        if (capabilities.includes("command-policy") || capabilities.includes("office-presence") || capabilities.includes("task-debug")) {
+            hooks.UserPromptSubmit = [matcherGroup("UserPromptSubmit", runtimePath)];
+            if (capabilities.includes("command-policy") || capabilities.includes("office-presence"))
+                hooks.PreToolUse = [matcherGroup("PreToolUse", runtimePath)];
         }
     }
-    if (capabilities.includes("optional-stop-verify") || capabilities.includes("office-presence")) {
+    if (capabilities.includes("task-debug") || capabilities.includes("optional-stop-verify") || capabilities.includes("office-presence")) {
         hooks.Stop = [matcherGroup("Stop", runtimePath)];
     }
+    if (capabilities.includes("task-debug")) {
+        hooks.Interrupt = [{ hooks: [{ ...commandHook("Interrupt", runtimePath), timeout: 3 }] }];
+    }
     return {
         description: "agent-ops lifecycle hooks.",
         hooks

package/dist/runtime/src/adapters/codex/events.js

@@ -8,7 +8,8 @@ export const CODEX_SUPPORTED_EVENTS = [
     "PostCompact",
     "SubagentStart",
     "SubagentStop",
-    "Stop"
+    "Stop",
+    "Interrupt"
 ];
 export function codexMatcherSupport(event) {
     return event === "PreToolUse" ? "tool-name" : "unsupported";

package/dist/runtime/src/adapters/codex/input.js

@@ -15,17 +15,35 @@ export function normalizeCodexHookInput(input) {
         return normalizeHookEvent(input);
     }
     const projectRoot = input.cwd;
+    const sessionId = typeof input.session_id === "string" && input.session_id.length > 0
+        ? input.session_id
+        : undefined;
     if (input.hook_event_name === "SessionStart") {
-        return normalizeHookEvent({
+        const start = normalizeHookEvent({
             event: "session-start",
             projectRoot
         });
+        return {
+            event: "session-start",
+            projectRoot: start.projectRoot,
+            ...(sessionId === undefined ? {} : { sessionId })
+        };
     }
     if (input.hook_event_name === "Stop") {
-        return normalizeHookEvent({
+        const stop = normalizeHookEvent({
             event: "stop",
             projectRoot
         });
+        return {
+            event: "stop",
+            projectRoot: stop.projectRoot,
+            ...(sessionId === undefined ? {} : { sessionId }),
+            terminationReason: typeof input.termination_reason === "string"
+                ? input.termination_reason
+                : "model_stop",
+            // stop_hook_active means a prior continuation, not a non-idle Stop.
+            fullyIdle: true
+        };
     }
     if (input.hook_event_name === "PreToolUse" &&
         input.tool_name === "Bash") {

package/dist/runtime/src/adapters/codex/output.js

@@ -1,6 +1,9 @@
 export const CODEX_NON_ZERO_EXIT_BEHAVIOR = "UNKNOWN";
 export const CODEX_PRE_TOOL_BLOCKING = "UNKNOWN";
 export function codexHookOutput(event, result) {
+    if (event === "Stop" && result.action === "block") {
+        return { exitCode: 0, stdout: JSON.stringify({ decision: "block", reason: `agent-ops: ${result.code}. ${result.remedy ?? "Continue the unfinished task."}` }) };
+    }
     if (event === "Stop" && result.evidence !== undefined) {
         return {
             exitCode: 0,
@@ -28,7 +31,7 @@ export function codexHookOutput(event, result) {
             continue: result.action !== "block",
             ...(result.action === "block"
                 ? { stopReason: result.code }
-                : { systemMessage: `agent-ops: ${result.code}` })
+                : { systemMessage: `agent-ops: ${result.code}${result.remedy === undefined ? "" : ". " + result.remedy}` })
         })
     };
 }

package/dist/runtime/src/config/merge.js

@@ -114,7 +114,7 @@ export function mergeConfigLayers(inputLayers) {
     let worktree;
     for (const layer of layers) {
         schemaVersion = effective(layer.config.schemaVersion, layer);
-        features = effective(layer.config.features, layer);
+        features = effective({ ...layer.config.features, ...(layer.config.features.debug === undefined && features?.value.debug !== undefined ? { debug: features.value.debug } : {}) }, layer);
         // Whole-block override: a workflow choice, not a guardrail, so a project
         // may turn a user-level `auto` off.
         if (layer.config.worktree !== undefined) {

package/dist/runtime/src/hooks/completion-gate.js

@@ -260,6 +260,9 @@ export class CompletionGateService {
         }
     }
     async grantPermit(sessionId) {
+        const attached = await this.#options.taskService.status({ sessionId }).catch(() => null);
+        if (attached?.task.debug !== undefined && attached.status === "active")
+            throw new AgentOpsError("TASK_DEBUG_CHECKPOINT_REQUIRED", "Active debug issues require a runtime stop checkpoint; allow-stop does not grant budget or success.");
         const fingerprint = await this.#fingerprint();
         const granted = await this.#store.mutate(sessionId, (state) => {
             if (state === null) {
@@ -485,6 +488,18 @@ export class CompletionGateService {
             }
             return last;
         }
+        const debugTask = await this.#options.taskService.status({ sessionId }).catch(() => null);
+        if (debugTask?.task.debug !== undefined) {
+            if (debugTask.status === "active") {
+                await this.#options.taskService.debugService().prepareStop(debugTask.task.id, sessionId);
+                const valid = await this.#options.taskService.debugService().validCheckpoint(debugTask.task.id, sessionId, fingerprint);
+                return valid ? gateResult("continue", "UNKNOWN", "COMPLETION_GATE_TASK_DEBUG_STOPPED", "Original issue remains active with a runtime-bound non-success checkpoint.") :
+                    gateResult("block", "FAIL", "COMPLETION_GATE_TASK_DEBUG_ACTIVE", "Continue the investigation/evidence loop or record a current runtime stop checkpoint, even when Git has no net diff.");
+            }
+            const failure = await this.#validateTask(sessionId);
+            if (failure !== null)
+                return failure;
+        }
         if (changed) {
             const failure = await this.#validateTask(sessionId);
             if (failure !== null)

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

@@ -361,6 +361,8 @@ export function managedRules(descriptor, context) {
             : [`Toolkit version: ${context.toolkitVersion}`]),
         ""
     ];
+    if (context.capabilities.includes("task-debug"))
+        lines.push("Task DEBUG routing is enabled for investigation/bugfix issues. Native prompt hooks create the issue task when a session identity is available; otherwise use agent-ops task create --debug --goal <verbatim issue> with two to five issue-specific criteria. Explain/read-only, feature and refactor requests use the existing normal task flow.", "For DEBUG: understand the issue, investigate with task debug --debug-action investigate --command-id <trusted verifier>, record falsifiable hypotheses with --debug-action hypothesis --payload-file <json>, reproduce, fix, verify, then obtain two fresh independent reviews and finish automatically. A clean HEAD is the automatic baseline; do not ask permission for it or offer diagnosis-only as a fallback. Failure to reproduce alone is not a stop condition: continue discriminating checks within the budget. Replace provisional intake criteria with relevant behavioral acceptance; baseline setup/skip/timeout/UNKNOWN is never reproduction. Never report success from edits or unrelated green checks.", "DEBUG defaults are 60 cumulative active minutes and 5 material repair candidates across the original issue, revisions, sessions and children. After two stagnant candidates document one substantive strategy switch; two further stagnant candidates block. Save task debug --debug-action checkpoint before stopping. Resume preserves budgets and blockers. A human continue event may authorize --debug-action extend --event-id latest; unsupported native event sources fail closed. Never use allow-stop for DEBUG.", "DEBUG human control comes only from native human events: '只診斷' / 'diagnosis only' keeps investigating without product repairs until current sealed baseline assertion FAIL confirms a hypothesis or runtime limits/blockers permit non-success Stop. '暫停' / 'pause' saves progress and stops immediately. '繼續' / 'continue' resumes the existing scope; '繼續修復' / 'resume repair' restores the full loop. Codex Interrupt is a pause. Preserve the original task, evidence, consumed time and rounds; diagnosis or pause never marks repair complete. CLI actor/text fields and synthetic instructions cannot authorize these changes.", "DEBUG is foreground work. On Claude, agy and native Codex, Stop refuses an active DEBUG issue without a valid stop checkpoint, with or without the completion gate. Codex uses decision:block to continue the original task even on repeated Stop; stop_hook_active does not waive it. Codex's generic completion gate remains unsupported; opencode has no supported foreground lifecycle. DEBUG gate faults get one targeted task/config reload, then an explicit UNKNOWN/incomplete diagnostic and non-success Stop, preserving state. Without reliable native session identity, automatic hook intake is unsupported; the existing native Agent can use the task CLI. Only a matching owned debug worktree checkpoint permits dirty recovery; preserve all original user edits.", "");
     if (context.capabilities.includes("rules")) {
         lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope and preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Keep it a plain command line: to keep the output add `--output <file>`", "   (the JSON envelope is written there and one line is printed) instead of", "   a shell redirect, which the host can only allow by matching the whole", "   command string, task id included.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }

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

@@ -1,4 +1,5 @@
 import { lstat, readFile } from "node:fs/promises";
+import { DEBUG_DEFAULTS } from "../task/debug-state.js";
 import { CONFIG_SCHEMA_VERSION, MANIFEST_SCHEMA_VERSION } from "../contracts.js";
 import { discoverProject } from "../discovery/index.js";
 import { sha256 } from "../fs/hash.js";
@@ -97,6 +98,7 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         profiles: [...profiles],
         verification,
         features: {
+            debug: existing?.features.debug ?? { ...DEBUG_DEFAULTS },
             ...(existing?.features ?? {
                 stopVerification: { enabled: false },
                 completionGate: { enabled: completionGateEnabled }
@@ -439,9 +441,7 @@ export async function createInstallPlan(options) {
     const existing = await readExistingManifest(options.root);
     assertCompatibleManifest(existing?.manifest ?? null, options.scope, options.harness, options.allowHarnessChange === true);
     const config = await planConfig(options.root, resolved.profiles, existing?.manifest ?? null, options.existingConfig, options.reviewTargets ?? [], completionGateEnabled, options.worktree, options.officeEnabled);
-    resolved.capabilities = resolved.capabilities.filter(capability => capability !== "office-presence");
-    if (config.config.features.office?.enabled === true)
-        resolved.capabilities.push("office-presence");
+    resolved.capabilities = resolveCapabilities(config.config).capabilities;
     const existingOpencodePluginPath = existing?.manifest.artifacts.find(({ id }) => id === "opencode-plugin")?.path;
     const explicitHookTargets = new Map();
     for (const target of options.hookTargets ?? []) {

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

@@ -34,6 +34,8 @@ export function resolveProfiles(inputProfiles) {
 }
 export function resolveCapabilities(config) {
     const resolved = resolveProfiles(config.profiles);
+    if (config.features.debug?.enabled === true)
+        resolved.capabilities.push("task-debug");
     if (config.features.office?.enabled === true)
         resolved.capabilities.push("office-presence");
     if (config.features.stopVerification.enabled) {

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

@@ -106,11 +106,19 @@ export async function createUpdatePlan(options) {
         configPreview.steps.length === 0) {
         throw new AgentOpsError("UPDATE_INSTALLATION_INVALID", "Update requires a passing config doctor check.");
     }
+    const current = configPreview.migrated.profiles;
+    // `run` implies `loop`; turning run off keeps the loop it brought, since
+    // the config cannot tell an implied loop from a chosen one.
+    const profiles = options.autoRun === true
+        ? current.includes("run") ? current : [...current, "run"]
+        : options.autoRun === false && current.includes("run")
+            ? [...current.filter((profile) => profile !== "run"), ...(current.includes("loop") ? [] : ["loop"])]
+            : current;
     const installation = await createInstallPlan({
         root: options.root,
         scope: report.manifest.scope,
         harness: options.harness ?? report.manifest.harness,
-        profiles: configPreview.migrated.profiles,
+        profiles,
         adapters: options.adapters,
         toolkitVersion: options.toolkitVersion ?? targetVersion,
         allowHarnessChange: true,
@@ -122,7 +130,7 @@ export async function createUpdatePlan(options) {
             ? {}
             : { hookTargets: options.hookTargets }),
         existingConfig: {
-            value: configPreview.migrated,
+            value: profiles === current ? configPreview.migrated : { ...configPreview.migrated, profiles },
             sourceHash: configPreview.sourceHash
         },
         ...(options.codexHome === undefined ? {} : { codexHome: options.codexHome }),

package/dist/runtime/src/office/activity.js

@@ -0,0 +1,105 @@
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+const KINDS = new Set(["verify", "review", "finish"]);
+const ID = /^[A-Za-z0-9._-]{1,128}$/u;
+const TARGET = /^[a-z][a-z0-9-]{0,31}$/u;
+const FILE = /^(verify|review|finish)-(\d{1,10})-(\d{1,10})\.json$/u;
+const NOOP = { update: async () => { }, end: async () => { } };
+export function activityDirectory(commonDir) {
+    return join(commonDir, "agent-ops", "office-activity");
+}
+/** Keeps only the allowlisted, well-formed fields; null when the record cannot stand. */
+export function activityValue(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const item = value;
+    if (!KINDS.has(item.kind) || typeof item.pid !== "number" || !Number.isInteger(item.pid) || item.pid <= 0 ||
+        typeof item.root !== "string" || item.root.length === 0 || item.root.length > 4096 ||
+        typeof item.startedAt !== "string" || Number.isNaN(Date.parse(item.startedAt)))
+        return null;
+    const id = (field) => typeof field === "string" && ID.test(field) ? field : undefined;
+    const targets = Array.isArray(item.targets) ? item.targets.filter((t) => typeof t === "string" && TARGET.test(t)).slice(0, 2) : undefined;
+    const round = item.round === 1 || item.round === 2 ? item.round : undefined;
+    const target = typeof item.target === "string" && TARGET.test(item.target) ? item.target : undefined;
+    const taskId = id(item.taskId), sessionId = id(item.sessionId), worktree = id(item.worktree);
+    return { kind: item.kind, pid: item.pid, root: item.root, startedAt: item.startedAt,
+        ...(taskId === undefined ? {} : { taskId }), ...(sessionId === undefined ? {} : { sessionId }), ...(worktree === undefined ? {} : { worktree }),
+        ...(targets === undefined || targets.length === 0 ? {} : { targets }), ...(round === undefined ? {} : { round }), ...(target === undefined ? {} : { target }) };
+}
+let sequence = 0;
+/** Starts a record; returns a handle whose writes never throw. No common dir means no record. */
+export async function beginActivity(commonDir, start, options = {}) {
+    if (commonDir === undefined || commonDir.length === 0)
+        return NOOP;
+    const pid = options.pid ?? process.pid, startedAt = (options.now ?? (() => new Date()))().toISOString();
+    let current = activityValue({ ...start, pid, startedAt });
+    if (current === null)
+        return NOOP;
+    // One process may run several reviews at once (batch), so the name carries a sequence too.
+    const path = join(activityDirectory(commonDir), `${current.kind}-${pid}-${++sequence}.json`);
+    // Writes run one after another in call order, so a slow early write never lands over a later one,
+    // and none runs after end() has removed the record.
+    let queue = Promise.resolve(), ended = false;
+    const write = () => (queue = queue.then(async () => {
+        if (ended)
+            return;
+        try {
+            await writePrivateFile(path, JSON.stringify(current) + "\n", commonDir);
+        }
+        catch { /* display only */ }
+    }));
+    await write();
+    return {
+        update: async (patch) => { const next = activityValue({ ...current, ...patch }); if (next !== null) {
+            current = next;
+            await write();
+        } },
+        end: async () => { ended = true; await queue; try {
+            await rm(path, { force: true });
+        }
+        catch { /* display only */ } }
+    };
+}
+/** Runs `work` with a record present; the record goes when the work ends, however it ends. */
+export async function withActivity(commonDir, start, work) {
+    const handle = await beginActivity(commonDir, start).catch(() => NOOP);
+    try {
+        return await work(handle);
+    }
+    finally {
+        await handle.end().catch(() => undefined);
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** Live records only: malformed files, files whose name disagrees with their content and dead processes are skipped. */
+export async function readActivities(commonDir, alive = processAlive) {
+    const directory = activityDirectory(commonDir);
+    const names = (await readdir(directory).catch(() => [])).filter(name => FILE.test(name)).sort().slice(0, 200);
+    const records = [];
+    for (const name of names) {
+        const match = FILE.exec(name);
+        const source = await readPrivateFile(join(directory, name), commonDir).catch(() => null);
+        if (source === null || source.length > 16 * 1024)
+            continue;
+        let value;
+        try {
+            value = activityValue(JSON.parse(source));
+        }
+        catch {
+            continue;
+        }
+        if (value === null || value.kind !== match[1] || value.pid !== Number(match[2]) || !alive(value.pid))
+            continue;
+        records.push(value);
+    }
+    return records;
+}