@kylecheng3146/agent-ops 0.5.3 → 0.6.0

package/dist/runtime/src/run/convergence.js

@@ -0,0 +1,177 @@
+import { canonicalJson } from "../config/hash.js";
+import { sha256 } from "../fs/hash.js";
+const MAX_ID = 4_096;
+function bounded(value, label) {
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_ID || value.includes("\0") || /[\r\n]/u.test(value)) {
+        throw new TypeError(`${label} must be a bounded single-line string.`);
+    }
+    return value;
+}
+function status(value) {
+    return value === "PASS" || value === "FAIL" ? value : "UNKNOWN";
+}
+function failureClass(value, current) {
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_ID || value.includes("\0") || /[\r\n]/u.test(value)) {
+        return current === "PASS" ? "none" : "unknown";
+    }
+    return value;
+}
+function stablePins(values) {
+    return [...new Set((values ?? []).map((value) => bounded(value, "pinId")))].sort();
+}
+function stableIds(values, label) {
+    return [...new Set((values ?? []).map((value) => bounded(value, label)))].sort();
+}
+function itemKey(check) {
+    return {
+        criterionId: check.criterionId,
+        runnerId: check.runnerId,
+        checkId: check.checkId,
+        phase: check.phase,
+        pinId: check.pinId
+    };
+}
+function identity(check) {
+    return {
+        ...itemKey(check),
+        status: check.status,
+        failureClass: check.failureClass
+    };
+}
+function sortedChecks(checks) {
+    return [...checks].sort((left, right) => canonicalJson(identity(left)).localeCompare(canonicalJson(identity(right))));
+}
+function commandObservation(result) {
+    const current = status(result.status);
+    return {
+        criterionId: null,
+        runnerId: null,
+        checkId: bounded(result.commandId, "commandId"),
+        phase: "verification",
+        status: current,
+        failureClass: failureClass(result.failureClass, current),
+        pinId: null
+    };
+}
+function acceptanceObservations(result) {
+    const current = status(result.status);
+    const criterionId = bounded(result.criterionId, "criterionId");
+    const runnerId = bounded(result.runnerId, "runnerId");
+    const phase = result.phase === "baseline" || result.phase === "candidate" ? result.phase : "candidate";
+    const actual = new Map((result.checks ?? []).map((check) => [bounded(check.checkId, "checkId"), {
+            status: status(check.status),
+            failureClass: failureClass(check.failureClass, status(check.status))
+        }]));
+    const required = stableIds(result.requiredCheckIds, "checkId");
+    const red = stableIds(result.redCheckIds, "redCheckId");
+    const checkIds = [...new Set([...required, ...red, ...actual.keys()])].sort();
+    if (checkIds.length === 0) {
+        return [{
+                criterionId,
+                runnerId,
+                checkId: criterionId,
+                phase,
+                status: current,
+                failureClass: failureClass(result.failureClass, current),
+                pinId: null
+            }];
+    }
+    return checkIds.map((checkId) => {
+        const observed = actual.get(checkId);
+        // A PASS criterion is a successful contract result. Baseline assertion
+        // failures are the intended red proof and must not become repair work.
+        if (current === "PASS") {
+            return { criterionId, runnerId, checkId, phase, status: "PASS", failureClass: "none", pinId: null };
+        }
+        if (phase === "baseline" && red.length > 0) {
+            if (red.includes(checkId) && observed?.status === "FAIL" && observed.failureClass === "assertion") {
+                return { criterionId, runnerId, checkId, phase, status: "PASS", failureClass: "none", pinId: null };
+            }
+            if (red.includes(checkId)) {
+                return {
+                    criterionId,
+                    runnerId,
+                    checkId,
+                    phase,
+                    status: "FAIL",
+                    failureClass: observed === undefined ? "missing-red-check" : observed.status === "PASS" ? "non-discriminating" : observed.failureClass,
+                    pinId: null
+                };
+            }
+        }
+        return {
+            criterionId,
+            runnerId,
+            checkId,
+            phase,
+            status: observed?.status ?? current,
+            failureClass: observed?.failureClass ?? (observed === undefined ? "missing-check" : failureClass(result.failureClass, current)),
+            pinId: null
+        };
+    });
+}
+function pinObservation(pinId) {
+    return {
+        criterionId: null,
+        runnerId: null,
+        checkId: pinId,
+        phase: "review",
+        status: "FAIL",
+        failureClass: "pinned-finding",
+        pinId
+    };
+}
+/**
+ * Turn a verifier report and the saved finding ratchet into a stable semantic
+ * observation. Raw diagnostics, source commits, timestamps, and task failure
+ * fingerprints are deliberately not read by this function.
+ */
+export function deriveFailureObservation(report, options = {}) {
+    const checks = [
+        ...report.results.filter((result) => result.required).map(commandObservation),
+        ...(report.acceptance ?? []).flatMap(acceptanceObservations),
+        ...stablePins(options.pendingPinIds).map(pinObservation)
+    ];
+    if (checks.length === 0 && report.status !== undefined && report.status !== "PASS") {
+        checks.push({
+            criterionId: null,
+            runnerId: null,
+            checkId: "verification",
+            phase: "verification",
+            status: status(report.status),
+            failureClass: "verification-failed",
+            pinId: null
+        });
+    }
+    const ordered = sortedChecks(checks);
+    const pendingPinIds = stablePins(options.pendingPinIds);
+    const failing = ordered.filter((check) => check.status !== "PASS").map(identity);
+    return {
+        taskId: bounded(report.taskId, "taskId"),
+        checks: ordered,
+        pendingPinIds,
+        failureKey: failing.length === 0 ? null : sha256(canonicalJson({ taskId: report.taskId, failing })),
+        progressDigest: sha256(canonicalJson({
+            taskId: report.taskId,
+            checks: ordered.map((check) => identity(check)),
+            pendingPinIds
+        }))
+    };
+}
+/** Compare only stable check identities; diagnostic text never participates. */
+export function compareFailureObservations(previous, current) {
+    const currentByItem = new Map(current.checks.map((check) => [canonicalJson(itemKey(check)), check]));
+    const passed = previous.checks.some((check) => {
+        if (check.status === "PASS")
+            return false;
+        return currentByItem.get(canonicalJson(itemKey(check)))?.status === "PASS";
+    });
+    const currentPins = new Set(current.pendingPinIds);
+    const dischargedPin = previous.pendingPinIds.some((pinId) => !currentPins.has(pinId));
+    return {
+        sameFailure: previous.failureKey !== null && previous.failureKey === current.failureKey,
+        usefulProgress: passed || dischargedPin,
+        failureKey: current.failureKey,
+        progressDigest: current.progressDigest
+    };
+}

package/dist/runtime/src/run/hosts/claude.js

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+import { AgentOpsError } from "../../fs/paths.js";
+import { JsonLineStream } from "./protocol.js";
+import { actionResult, assertContext, assertProcessRunning, event, spawnNative, stopNativeProcess } from "./util.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringField(value, key) {
+    return isRecord(value) && typeof value[key] === "string" ? value[key] : null;
+}
+function goalStatus(value) {
+    if (isRecord(value)) {
+        const subtype = stringField(value, "subtype");
+        if (subtype === "success")
+            return "complete";
+        if (subtype === "error_max_budget_usd" || subtype === "error_max_turns")
+            return "budgetLimited";
+        const status = stringField(value, "status");
+        if (status === "active" || status === "paused" || status === "blocked" ||
+            status === "usageLimited" || status === "budgetLimited" || status === "complete") {
+            return status;
+        }
+    }
+    return "unknown";
+}
+function writeMessage(handle, text) {
+    handle.process.stdin.write(`${JSON.stringify({
+        type: "user",
+        message: {
+            role: "user",
+            content: [{ type: "text", text }]
+        }
+    })}\n`);
+}
+export class ClaudeGoalHost {
+    options;
+    kind = "claude";
+    streams = new WeakMap();
+    now;
+    constructor(options = {}) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date());
+    }
+    async start(input) {
+        return this.open(input, false, null);
+    }
+    async resume(input, sessionId, objective) {
+        if (sessionId.length === 0) {
+            throw new AgentOpsError("NATIVE_SESSION_INVALID", "Claude session id is required to resume.");
+        }
+        const handle = await this.open(input, true, sessionId);
+        if (objective !== undefined) {
+            await this.activate(handle, objective, input, input.tokenBudget);
+        }
+        return handle;
+    }
+    async activate(handle, objective, context, tokenBudget = null) {
+        assertContext(handle, context);
+        assertProcessRunning(handle.process);
+        if (objective.length === 0 || objective.length > 4000) {
+            throw new AgentOpsError("NATIVE_GOAL_INVALID", "Claude goal objective must be 1–4000 characters.");
+        }
+        const condition = tokenBudget === null
+            ? `/goal ${objective}`
+            : `/goal ${objective} or stop after ${tokenBudget} tokens`;
+        writeMessage(handle, condition);
+        return actionResult(true, "active", { objective, tokenBudget });
+    }
+    async update(handle, update) {
+        assertContext(handle, update);
+        assertProcessRunning(handle.process);
+        return this.activate(handle, update.objective, update, update.tokenBudget ?? null);
+    }
+    async *observe(handle, options = {}) {
+        const stream = this.stream(handle);
+        while (true) {
+            const message = await stream.next(options.signal);
+            if (message === null) {
+                return;
+            }
+            const mapped = this.mapEvent(handle, message);
+            yield mapped;
+            if (mapped.type === "completed" || mapped.type === "error" || mapped.type === "closed") {
+                return;
+            }
+        }
+    }
+    async interrupt(handle, context) {
+        assertContext(handle, context);
+        if (handle.process.exitCode === null && handle.process.signalCode === null) {
+            handle.process.kill("SIGINT");
+        }
+        return actionResult(true, "paused", { signal: "SIGINT" });
+    }
+    async stop(handle, context, signal = "SIGTERM") {
+        assertContext(handle, context);
+        await stopNativeProcess(handle.process, signal);
+        return actionResult(true, "paused", { signal });
+    }
+    async open(input, resume, sessionId) {
+        const requestedSessionId = sessionId ?? input.sessionId ?? randomUUID();
+        const defaultArgs = resume
+            ? [
+                "-p",
+                "--resume", requestedSessionId,
+                "--input-format", "stream-json",
+                "--output-format", "stream-json",
+                "--verbose", "--include-partial-messages",
+                "--permission-mode", "auto",
+                "--permission-prompts", "none"
+            ]
+            : [
+                "-p",
+                "--session-id", requestedSessionId,
+                "--input-format", "stream-json",
+                "--output-format", "stream-json",
+                "--verbose", "--include-partial-messages",
+                "--permission-mode", "auto",
+                "--permission-prompts", "none"
+            ];
+        const command = this.options.command ?? "claude";
+        const args = this.options.args ?? defaultArgs;
+        const process = spawnNative(command, args, input.cwd, input.env, this.options);
+        const stream = new JsonLineStream(process);
+        try {
+            if (process.pid !== undefined)
+                await input.registerProcess?.(process.pid);
+        }
+        catch (cause) {
+            stream.close(cause);
+            if (process.pid !== undefined)
+                await stopNativeProcess(process, "SIGKILL");
+            throw cause;
+        }
+        const handle = {
+            runId: input.runId,
+            workerId: input.workerId,
+            generation: input.generation,
+            contractHash: input.contractHash,
+            kind: this.kind,
+            // --session-id and --resume make this identity durable before the first
+            // user message. Claude can emit startup hook events before system/init,
+            // so start intentionally does not wait for that event.
+            sessionId: requestedSessionId,
+            threadId: null,
+            nativeVersion: input.nativeVersion ?? this.options.nativeVersion ?? null,
+            cwd: input.cwd,
+            processId: process.pid ?? null,
+            startedAt: this.now().toISOString(),
+            process,
+            goalStatus: "unknown"
+        };
+        this.streams.set(handle, stream);
+        return handle;
+    }
+    stream(handle) {
+        const stream = this.streams.get(handle);
+        if (stream === undefined) {
+            throw new AgentOpsError("NATIVE_SESSION_INVALID", "Unknown Claude native handle.");
+        }
+        return stream;
+    }
+    mapEvent(handle, payload) {
+        const type = stringField(payload, "type");
+        if (type === "result") {
+            const subtype = stringField(payload, "subtype");
+            return event(handle, subtype === "success" ? "completed" : "error", goalStatus(payload), payload, this.now);
+        }
+        if (type === "error" || (type === "system" && stringField(payload, "subtype") === "error")) {
+            return event(handle, "error", goalStatus(payload), payload, this.now);
+        }
+        if (isRecord(payload.usage) || typeof payload.total_cost_usd === "number") {
+            return event(handle, "usage", goalStatus(payload), payload, this.now);
+        }
+        if (type === "system" && stringField(payload, "subtype") === "goal") {
+            return event(handle, "goal-updated", goalStatus(payload), payload, this.now);
+        }
+        return event(handle, "message", goalStatus(payload), payload, this.now);
+    }
+}

package/dist/runtime/src/run/hosts/codex.js

@@ -0,0 +1,279 @@
+import { randomUUID } from "node:crypto";
+import { AgentOpsError } from "../../fs/paths.js";
+import { JsonRpcSession } from "./protocol.js";
+import { actionResult, assertContext, commandParts, event, assertProcessRunning, spawnNative, stopNativeProcess } from "./util.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nestedRecord(value, key) {
+    if (!isRecord(value) || !isRecord(value[key])) {
+        return null;
+    }
+    return value[key];
+}
+function stringField(value, key) {
+    return isRecord(value) && typeof value[key] === "string" ? value[key] : null;
+}
+function statusField(value) {
+    const status = stringField(value, "status");
+    return status === "active" || status === "paused" || status === "blocked" ||
+        status === "usageLimited" || status === "budgetLimited" || status === "complete"
+        ? status
+        : "unknown";
+}
+function resultThreadId(result, fallback = null) {
+    const thread = nestedRecord(result, "thread");
+    const id = stringField(thread, "id");
+    if (id === null) {
+        if (fallback !== null) {
+            return fallback;
+        }
+        throw new AgentOpsError("NATIVE_PROTOCOL_INVALID", "Codex app server did not return a thread id.");
+    }
+    return id;
+}
+function resultTurnId(result) {
+    const turn = nestedRecord(result, "turn");
+    return stringField(turn, "id");
+}
+export class CodexGoalHost {
+    options;
+    kind = "codex";
+    sessions = new WeakMap();
+    turns = new WeakMap();
+    now;
+    constructor(options = {}) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date());
+    }
+    async start(input) {
+        const handle = await this.open(input, false, null);
+        return handle;
+    }
+    async resume(input, sessionId, objective) {
+        if (sessionId.length === 0) {
+            throw new AgentOpsError("NATIVE_SESSION_INVALID", "Codex thread id is required to resume.");
+        }
+        const handle = await this.open(input, true, sessionId);
+        if (objective !== undefined) {
+            await this.activate(handle, objective, input, input.tokenBudget);
+        }
+        return handle;
+    }
+    async activate(handle, objective, context, tokenBudget = null) {
+        assertContext(handle, context);
+        assertProcessRunning(handle.process);
+        if (objective.length === 0 || objective.length > 4000) {
+            throw new AgentOpsError("NATIVE_GOAL_INVALID", "Codex goal objective must be 1–4000 characters.");
+        }
+        const session = this.session(handle);
+        const goal = await session.request("thread/goal/set", {
+            threadId: handle.threadId,
+            objective,
+            status: "active",
+            tokenBudget
+        });
+        const turn = await session.request("turn/start", {
+            threadId: handle.threadId,
+            input: [{ type: "text", text: objective }],
+            approvalPolicy: "on-request",
+            approvalsReviewer: "auto_review"
+        });
+        const turnId = resultTurnId(turn);
+        if (turnId !== null) {
+            this.turns.set(handle, turnId);
+        }
+        return actionResult(true, statusField(nestedRecord(goal, "goal") ?? goal), goal);
+    }
+    async update(handle, update) {
+        assertContext(handle, update);
+        assertProcessRunning(handle.process);
+        const session = this.session(handle);
+        const goal = await session.request("thread/goal/set", {
+            threadId: handle.threadId,
+            objective: update.objective,
+            status: "active",
+            tokenBudget: update.tokenBudget ?? null
+        });
+        const turnId = this.turns.get(handle);
+        let turn;
+        if (turnId === undefined) {
+            turn = await session.request("turn/start", {
+                threadId: handle.threadId,
+                input: [{ type: "text", text: update.objective }],
+                approvalPolicy: "on-request",
+                approvalsReviewer: "auto_review"
+            });
+        }
+        else {
+            try {
+                turn = await session.request("turn/steer", {
+                    threadId: handle.threadId,
+                    expectedTurnId: turnId,
+                    input: [{ type: "text", text: update.objective }]
+                });
+            }
+            catch (error) {
+                if (!(error instanceof AgentOpsError) || error.code !== "NATIVE_REQUEST_FAILED") {
+                    throw error;
+                }
+                turn = await session.request("turn/start", {
+                    threadId: handle.threadId,
+                    input: [{ type: "text", text: update.objective }],
+                    approvalPolicy: "on-request",
+                    approvalsReviewer: "auto_review"
+                });
+            }
+        }
+        const nextTurnId = resultTurnId(turn);
+        if (nextTurnId !== null) {
+            this.turns.set(handle, nextTurnId);
+        }
+        return actionResult(true, statusField(nestedRecord(goal, "goal") ?? goal), goal);
+    }
+    async *observe(handle, options = {}) {
+        const session = this.session(handle);
+        while (true) {
+            const message = await session.nextEvent(options.signal);
+            if (message === null) {
+                return;
+            }
+            const mapped = this.mapEvent(handle, message);
+            yield { ...mapped, ...(typeof message.method === "string" ? { transportMethod: message.method } : {}) };
+            if (mapped.type === "completed" || mapped.type === "error" || mapped.type === "closed") {
+                return;
+            }
+        }
+    }
+    async interrupt(handle, context) {
+        assertContext(handle, context);
+        const session = this.session(handle);
+        const turnId = this.turns.get(handle);
+        if (turnId !== undefined) {
+            await session.request("turn/interrupt", { threadId: handle.threadId, turnId });
+        }
+        const result = await session.request("thread/goal/set", {
+            threadId: handle.threadId,
+            objective: null,
+            status: "paused",
+            tokenBudget: null
+        });
+        return actionResult(true, statusField(nestedRecord(result, "goal") ?? result), result);
+    }
+    async stop(handle, context, signal = "SIGTERM") {
+        assertContext(handle, context);
+        let payload = null;
+        try {
+            const result = await this.interrupt(handle, context);
+            payload = result.payload;
+        }
+        catch {
+            // A crashed or already closed native process is already stopped.
+        }
+        await stopNativeProcess(handle.process, signal);
+        return actionResult(true, "paused", payload);
+    }
+    async open(input, resume, threadId) {
+        const parts = commandParts(this.options, "codex", ["app-server", "--listen", "stdio://"]);
+        const process = spawnNative(parts.command, parts.args, input.cwd, input.env, this.options);
+        const channel = new JsonRpcSession(process, input.timeoutMs ?? this.options.requestTimeoutMs ?? 30_000);
+        try {
+            if (process.pid !== undefined)
+                await input.registerProcess?.(process.pid);
+            await this.sendInitialize(channel);
+            let nativeThreadId;
+            if (resume) {
+                const result = await channel.request("thread/resume", {
+                    threadId,
+                    cwd: input.cwd,
+                    approvalPolicy: "on-request",
+                    approvalsReviewer: "auto_review",
+                    sandbox: "workspace-write",
+                    excludeTurns: true
+                });
+                nativeThreadId = resultThreadId(result, threadId);
+            }
+            else {
+                const result = await channel.request("thread/start", {
+                    cwd: input.cwd,
+                    approvalPolicy: "on-request",
+                    approvalsReviewer: "auto_review",
+                    sandbox: "workspace-write",
+                    ephemeral: false
+                });
+                nativeThreadId = resultThreadId(result);
+            }
+            const handle = {
+                runId: input.runId,
+                workerId: input.workerId,
+                generation: input.generation,
+                contractHash: input.contractHash,
+                kind: this.kind,
+                sessionId: input.sessionId ?? randomUUID(),
+                threadId: nativeThreadId,
+                nativeVersion: input.nativeVersion ?? this.options.nativeVersion ?? null,
+                cwd: input.cwd,
+                processId: process.pid ?? null,
+                startedAt: this.now().toISOString(),
+                process,
+                goalStatus: "unknown"
+            };
+            this.sessions.set(handle, channel);
+            return handle;
+        }
+        catch (cause) {
+            channel.close(cause);
+            if (process.pid !== undefined)
+                await stopNativeProcess(process, "SIGKILL");
+            throw cause;
+        }
+    }
+    async sendInitialize(session) {
+        // Keep the notification sequence in one helper so callers cannot send a
+        // goal before the app-server handshake is complete.
+        await session.request("initialize", {
+            capabilities: { experimentalApi: true },
+            clientInfo: {
+                name: "agent-ops",
+                title: "agent-ops native goal host",
+                version: "0.6.0"
+            }
+        });
+        session.notify("initialized", {});
+    }
+    session(handle) {
+        const session = this.sessions.get(handle);
+        if (session === undefined) {
+            throw new AgentOpsError("NATIVE_SESSION_INVALID", "Unknown Codex native handle.");
+        }
+        return session;
+    }
+    mapEvent(handle, message) {
+        const method = typeof message.method === "string" ? message.method : "message";
+        const payload = isRecord(message.params) ? message.params : message;
+        if (method === "thread/goal/updated") {
+            const goal = isRecord(payload.goal) ? payload.goal : payload;
+            const status = statusField(goal);
+            return event(handle, status === "complete" ? "completed" : "goal-updated", status, payload, this.now);
+        }
+        if (method === "thread/goal/cleared") {
+            return event(handle, "goal-updated", "complete", payload, this.now);
+        }
+        if (method === "turn/completed") {
+            this.turns.delete(handle);
+            // A completed turn is not necessarily a completed native goal. Native
+            // goals can continue automatically after a turn boundary.
+            return event(handle, "message", "unknown", payload, this.now);
+        }
+        if (method === "turn/started") {
+            const turn = nestedRecord(payload, "turn");
+            const id = stringField(turn, "id");
+            if (id !== null)
+                this.turns.set(handle, id);
+        }
+        if (method.includes("usage") || method.includes("token")) {
+            return event(handle, "usage", "unknown", payload, this.now);
+        }
+        return event(handle, "message", "unknown", payload, this.now);
+    }
+}

package/dist/runtime/src/run/hosts/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./protocol.js";
+export * from "./codex.js";
+export * from "./claude.js";