@kylecheng3146/agent-ops 0.5.3 → 0.6.0

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

@@ -0,0 +1,189 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { createHash } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { AgentOpsError } from "../fs/paths.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+const execFile = promisify(execFileCallback);
+function xml(value) {
+    return value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;")
+        .replace(/"/gu, "&quot;").replace(/'/gu, "&apos;");
+}
+function shellSafe(value) {
+    return value.replace(/[^A-Za-z0-9._-]/gu, "-").slice(0, 60) || "worker";
+}
+function assertPathInside(root, candidate) {
+    const canonicalRoot = resolve(root);
+    const canonicalCandidate = resolve(candidate);
+    const fromRoot = relative(canonicalRoot, canonicalCandidate);
+    if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
+        throw new AgentOpsError("LAUNCHD_PATH_INVALID", "launchd transient state escaped its private directory.");
+    }
+}
+function defaultUid() {
+    if (typeof process.getuid !== "function") {
+        throw new AgentOpsError("LAUNCHD_UID_UNAVAILABLE", "launchd requires a macOS user id.");
+    }
+    return process.getuid();
+}
+function defaultExecFile(file, args, options) {
+    return execFile(file, [...args], options).then((result) => ({
+        stdout: result.stdout,
+        stderr: result.stderr
+    }));
+}
+export function createLaunchdDescriptor(input) {
+    if (input.runId.length === 0 || input.workerId.length === 0 || input.command.length === 0 || input.cwd.length === 0) {
+        throw new AgentOpsError("LAUNCHD_DESCRIPTOR_INVALID", "launchd descriptor fields cannot be empty.");
+    }
+    const privateDirectory = resolve(input.privateDirectory);
+    const label = `com.agent-ops.run.${shellSafe(input.runId)}.${shellSafe(input.workerId)}.${createHash("sha256").update(input.runId).digest("hex").slice(0, 8)}`;
+    const path = join(privateDirectory, `${label}.plist`);
+    const disabledPath = join(privateDirectory, `${label}.disabled.json`);
+    assertPathInside(privateDirectory, path);
+    assertPathInside(privateDirectory, disabledPath);
+    const uid = input.uid ?? (process.platform === "darwin" ? defaultUid() : 0);
+    if (!Number.isSafeInteger(uid) || uid < 0) {
+        throw new AgentOpsError("LAUNCHD_UID_INVALID", "launchd user id is invalid.");
+    }
+    const stdoutPath = input.stdoutPath ?? join(privateDirectory, `${label}.stdout.log`);
+    const stderrPath = input.stderrPath ?? join(privateDirectory, `${label}.stderr.log`);
+    assertPathInside(privateDirectory, stdoutPath);
+    assertPathInside(privateDirectory, stderrPath);
+    const argumentsXml = [input.command, ...input.args]
+        .map((arg) => `    <string>${xml(arg)}</string>`)
+        .join("\n");
+    const xmlDocument = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${xml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argumentsXml}
+  </array>
+  <key>WorkingDirectory</key><string>${xml(input.cwd)}</string>
+${input.pathEnvironment === undefined ? "" : "  <key>EnvironmentVariables</key><dict><key>PATH</key><string>" + xml(input.pathEnvironment) + "</string></dict>"}
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key>
+  <dict><key>SuccessfulExit</key><false/></dict>
+  <key>StandardOutPath</key><string>${xml(stdoutPath)}</string>
+  <key>StandardErrorPath</key><string>${xml(stderrPath)}</string>
+</dict>
+</plist>
+`;
+    return {
+        label,
+        domain: `gui/${uid}`,
+        path,
+        privateDirectory,
+        disabledPath,
+        xml: xmlDocument
+    };
+}
+export function compareBootLogin(saved, current) {
+    if (saved.boot !== current.boot) {
+        return { resume: false, reason: "boot-change" };
+    }
+    if (saved.login !== current.login) {
+        return { resume: false, reason: "login-change" };
+    }
+    return { resume: true, reason: "same-login" };
+}
+export async function readBootIdentity(platform = process.platform, run = defaultExecFile) {
+    if (platform !== "darwin") {
+        return `platform:${platform}`;
+    }
+    const result = await run("sysctl", ["-n", "kern.boottime"], {});
+    const value = result.stdout?.trim();
+    if (value === undefined || value.length === 0) {
+        throw new AgentOpsError("LAUNCHD_BOOT_IDENTITY_UNAVAILABLE", "macOS boot identity was empty.");
+    }
+    return value;
+}
+export function readLoginIdentity(uid = defaultUid()) {
+    if (!Number.isSafeInteger(uid) || uid < 0) {
+        throw new AgentOpsError("LAUNCHD_UID_INVALID", "macOS login user id is invalid.");
+    }
+    return `uid:${uid}:${process.env.LOGNAME ?? process.env.USER ?? "unknown"}`;
+}
+/** A uid alone survives logout/login; the GUI audit session identifies this login. */
+export async function readGuiLoginIdentity(uid = defaultUid(), run = defaultExecFile) {
+    if (!Number.isSafeInteger(uid) || uid < 0)
+        throw new AgentOpsError("LAUNCHD_UID_INVALID", "Invalid macOS login user id.");
+    const result = await run("launchctl", ["print", `gui/${uid}`], {});
+    const security = result.stdout?.match(/^\tsecurity context = \{[\s\S]*?^\t\}/mu)?.[0];
+    const auditSession = security?.match(/^\s*asid = ([0-9]+)$/mu)?.[1];
+    if (auditSession === undefined)
+        throw new AgentOpsError("LAUNCHD_LOGIN_IDENTITY_UNAVAILABLE", "Cannot identify the current GUI audit session.");
+    return `gui:${uid}:asid:${auditSession}`;
+}
+export class LaunchdController {
+    platform;
+    uid;
+    run;
+    constructor(options = {}) {
+        this.platform = options.platform ?? process.platform;
+        this.uid = options.uid ?? (this.platform === "darwin" ? defaultUid() : 0);
+        this.run = options.execFile ?? defaultExecFile;
+    }
+    get supported() {
+        return this.platform === "darwin";
+    }
+    async writeDescriptor(descriptor) {
+        this.assertSupported();
+        await writePrivateFile(descriptor.path, descriptor.xml, descriptor.privateDirectory);
+    }
+    async bootstrap(descriptor) {
+        this.assertSupported();
+        await this.run("launchctl", ["bootstrap", descriptor.domain, descriptor.path], {
+            cwd: descriptor.privateDirectory
+        });
+    }
+    async wake(descriptor) {
+        this.assertSupported();
+        try {
+            await this.bootstrap(descriptor);
+        }
+        catch {
+            await this.run("launchctl", ["kickstart", `${descriptor.domain}/${descriptor.label}`], { cwd: descriptor.privateDirectory });
+        }
+    }
+    async bootout(descriptor) {
+        this.assertSupported();
+        try {
+            await this.run("launchctl", ["bootout", `${descriptor.domain}/${descriptor.label}`], { cwd: descriptor.privateDirectory });
+        }
+        catch (cause) {
+            const failure = cause;
+            if (failure.code !== 3 || typeof failure.stderr !== "string" || !failure.stderr.includes("No such process"))
+                throw cause;
+        }
+    }
+    async disableRestart(descriptor, reason) {
+        this.assertSupported();
+        if (reason.length === 0 || reason.length > 512 || reason.includes("\0")) {
+            throw new AgentOpsError("LAUNCHD_DISABLE_REASON_INVALID", "launchd disable reason is invalid.");
+        }
+        await writePrivateFile(descriptor.disabledPath, `${JSON.stringify({ disabled: true, reason, at: new Date().toISOString() })}\n`, descriptor.privateDirectory);
+        await this.run("launchctl", ["disable", `${descriptor.domain}/${descriptor.label}`], {
+            cwd: descriptor.privateDirectory
+        });
+    }
+    async isRestartDisabled(descriptor) {
+        return (await readPrivateFile(descriptor.disabledPath, descriptor.privateDirectory)) !== null;
+    }
+    async enableRestart(descriptor) {
+        this.assertSupported();
+        await this.run("launchctl", ["enable", `${descriptor.domain}/${descriptor.label}`], {
+            cwd: descriptor.privateDirectory
+        });
+        await rm(descriptor.disabledPath, { force: true });
+    }
+    assertSupported() {
+        if (!this.supported) {
+            throw new AgentOpsError("LAUNCHD_UNSUPPORTED", "Transient launchd primitives require macOS.");
+        }
+    }
+}

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

@@ -0,0 +1,22 @@
+import { join } from "node:path";
+import { FileRunRepository } from "./service.js";
+/** The common run ledger, rather than worker-local metadata, grants writer ownership. */
+export async function registeredRunWriter(record, sessionId, agentId) {
+    if (record.runId === undefined || record.workerId === undefined || record.workerGeneration === undefined)
+        return false;
+    try {
+        const common = join(record.mainRoot, ".git");
+        const state = await new FileRunRepository(join(common, "agent-ops", "runs"), common).read(record.runId);
+        const worker = state?.workers.find(w => w.workerId === record.workerId);
+        return state !== null && state !== undefined && state.status === "active" && !state.disableRestart &&
+            worker !== undefined && worker.worktree === record.path && worker.generation === record.workerGeneration &&
+            worker.ownerSessionId === record.ownerSessionId && state.coordinatorId === record.coordinatorId &&
+            ["running", "idle"].includes(worker.status) && worker.stopIntent === null &&
+            (worker.nativeSessionId === sessionId || worker.ownerSessionId === sessionId) &&
+            worker.leaseExpiresAt !== null && Date.parse(worker.leaseExpiresAt) > Date.now() &&
+            (agentId === undefined || agentId === record.agentId);
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,25 @@
+import { AgentOpsError } from "../fs/paths.js";
+import { validateCriterion } from "../schema/validate.js";
+const plain = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const text = (v) => typeof v === "string" && v.trim().length > 0 && v.length <= 4096 && !v.includes("\0");
+/** Validate a deferred worker plan without freezing criteria before dependencies are delivered. */
+export function workerPlan(value, taskId, state) {
+    if (!plain(value) || Object.keys(value).some(k => !["title", "intent", "criteria", "dependencies"].includes(k)) ||
+        !text(value.title) || !text(value.intent) || !Array.isArray(value.criteria) || value.criteria.length < 2 || value.criteria.length > 5 ||
+        !Array.isArray(value.dependencies) || value.dependencies.length > 512 || new Set(value.dependencies).size !== value.dependencies.length ||
+        value.dependencies.some(id => typeof id !== "string" || id === state.rootTaskId || !state.tasks.some(task => task.taskId === id)))
+        throw new AgentOpsError("RUN_WORKER_PLAN_INVALID", "Worker plans require 2–5 criteria and known non-coordinator dependencies.");
+    const ids = new Set();
+    const criteria = value.criteria.map((criterion, index) => {
+        if (!plain(criterion) || criterion.finding !== undefined || (plain(criterion.acceptance) && criterion.acceptance.baselineCommit !== undefined))
+            throw new AgentOpsError("RUN_WORKER_BASELINE_DEFERRED", "New worker baselines are captured only after dependencies enter its checkout; finding pins belong to an existing task.");
+        const normalized = { ...criterion, ...(plain(criterion.acceptance) ? { acceptance: { ...criterion.acceptance, baselineCommit: "0".repeat(40) } } : {}) };
+        const checked = validateCriterion(normalized, `$.criteria[${index}]`);
+        if (!checked.ok || ids.has(checked.value.id))
+            throw new AgentOpsError("RUN_WORKER_PLAN_INVALID", "Worker criteria must be unique valid contracts.");
+        ids.add(checked.value.id);
+        // TaskService.create resolves the real checkout SHA when this worker starts.
+        return structuredClone(criterion);
+    });
+    return { taskId, title: value.title, intent: value.intent, criteria, dependencies: [...value.dependencies] };
+}