patchrelay 0.1.0

package/dist/reconciliation-engine.js

@@ -0,0 +1,312 @@
+export class ReconciliationEngine {
+    reconcile(input) {
+        const actions = [];
+        const issue = input.issue;
+        const policy = input.policy ?? {};
+        const liveLinear = input.live?.linear ?? { status: "unknown" };
+        const liveCodex = input.live?.codex ?? { status: "unknown" };
+        const obligations = relevantObligations(issue, input.obligations ?? []);
+        if (!issue.activeRun) {
+            if (!issue.desiredStage) {
+                return {
+                    outcome: "noop",
+                    reasons: ["issue has no active run and no desired stage"],
+                    actions,
+                };
+            }
+            return {
+                outcome: "launch",
+                reasons: [`desired stage ${issue.desiredStage} is ready to launch`],
+                actions: [
+                    {
+                        type: "launch_desired_stage",
+                        projectId: issue.projectId,
+                        linearIssueId: issue.linearIssueId,
+                        stage: issue.desiredStage,
+                        reason: "desired stage exists without an active run",
+                    },
+                ],
+            };
+        }
+        if (needsLinearState(issue, policy, liveLinear)) {
+            actions.push({
+                type: "read_linear_issue",
+                projectId: issue.projectId,
+                linearIssueId: issue.linearIssueId,
+                reason: "active reconciliation needs the live Linear state",
+            });
+        }
+        if (needsCodexState(issue.activeRun, liveCodex)) {
+            actions.push({
+                type: "read_codex_thread",
+                projectId: issue.projectId,
+                linearIssueId: issue.linearIssueId,
+                runId: issue.activeRun.id,
+                threadId: issue.activeRun.threadId,
+                reason: "active reconciliation needs the live Codex thread",
+            });
+        }
+        if (actions.length > 0) {
+            return {
+                outcome: "hydrate_live_state",
+                reasons: ["reconciliation needs fresh live state before deciding"],
+                actions,
+            };
+        }
+        return reconcileActiveRun({
+            issue,
+            liveLinear,
+            liveCodex,
+            obligations,
+            policy,
+        });
+    }
+}
+export function reconcileIssue(input) {
+    return new ReconciliationEngine().reconcile(input);
+}
+function reconcileActiveRun(params) {
+    const { issue, liveLinear, liveCodex, obligations, policy } = params;
+    const run = issue.activeRun;
+    if (run.status === "queued") {
+        return {
+            outcome: "launch",
+            reasons: ["queued run has not been materialized yet"],
+            actions: [
+                {
+                    type: "launch_desired_stage",
+                    projectId: issue.projectId,
+                    linearIssueId: issue.linearIssueId,
+                    stage: run.stage,
+                    runId: run.id,
+                    reason: "active run is queued and should be launched",
+                },
+            ],
+        };
+    }
+    if (!run.threadId) {
+        return failRun(issue, run, liveLinear, policy, "active run is missing a persisted thread id");
+    }
+    if (liveCodex.status === "error") {
+        return {
+            outcome: "continue",
+            reasons: [liveCodex.errorMessage ?? "codex thread lookup failed"],
+            actions: [
+                {
+                    type: "await_codex_retry",
+                    projectId: issue.projectId,
+                    linearIssueId: issue.linearIssueId,
+                    runId: run.id,
+                    reason: liveCodex.errorMessage ?? "codex thread lookup failed",
+                },
+            ],
+        };
+    }
+    if (liveCodex.status === "missing" || !liveCodex.thread) {
+        return failRun(issue, run, liveLinear, policy, "thread was not found during reconciliation");
+    }
+    const latestTurn = latestThreadTurn(liveCodex.thread);
+    const targetTurnId = latestTurn?.id ?? run.turnId;
+    if (!latestTurn || latestTurn.status === "inProgress") {
+        const actions = routePendingObligations(issue, run, obligations, liveCodex.thread.id, targetTurnId);
+        actions.push({
+            type: "keep_run_active",
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            runId: run.id,
+            reason: !latestTurn ? "thread has not produced a turn yet" : "latest turn is still in progress",
+        });
+        return {
+            outcome: "continue",
+            reasons: [!latestTurn ? "thread has no completed turns yet" : "latest turn is still in progress"],
+            actions,
+        };
+    }
+    if (latestTurn.status !== "completed") {
+        return failRun(issue, run, liveLinear, policy, "thread completed reconciliation in a failed state", latestTurn.id);
+    }
+    const actions = [
+        {
+            type: "mark_run_completed",
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            runId: run.id,
+            threadId: liveCodex.thread.id,
+            ...(latestTurn.id ? { turnId: latestTurn.id } : {}),
+            reason: "latest turn completed successfully during reconciliation",
+        },
+    ];
+    if (shouldAwaitHandoff(liveLinear, policy)) {
+        actions.push({
+            type: "clear_active_run",
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            runId: run.id,
+            nextLifecycleStatus: "paused",
+            reason: "stage completed while the issue still matches the service-owned active Linear state",
+        }, {
+            type: "refresh_status_comment",
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            runId: run.id,
+            ...(issue.statusCommentId ? { commentId: issue.statusCommentId } : {}),
+            mode: "awaiting_handoff",
+            reason: "stage completed and should publish an awaiting handoff status",
+        });
+        return {
+            outcome: "complete",
+            reasons: ["stage completed and should pause for human handoff"],
+            actions,
+        };
+    }
+    actions.push({
+        type: "release_issue_ownership",
+        projectId: issue.projectId,
+        linearIssueId: issue.linearIssueId,
+        runId: run.id,
+        nextLifecycleStatus: "completed",
+        reason: "stage completed after the live Linear state moved on",
+    });
+    return {
+        outcome: "release",
+        reasons: ["stage completed and the live Linear state already moved on"],
+        actions,
+    };
+}
+function failRun(issue, run, liveLinear, policy, message, turnId) {
+    const actions = [
+        {
+            type: "mark_run_failed",
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            runId: run.id,
+            ...(run.threadId ? { threadId: run.threadId } : {}),
+            ...(turnId ? { turnId } : run.turnId ? { turnId: run.turnId } : {}),
+            reason: message,
+        },
+    ];
+    if (shouldFailBack(liveLinear, policy)) {
+        actions.push({
+            type: "sync_linear_failure",
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            runId: run.id,
+            ...(policy.activeLinearStateName ? { expectedStateName: policy.activeLinearStateName } : {}),
+            ...(policy.fallbackLinearStateName ? { fallbackStateName: policy.fallbackLinearStateName } : {}),
+            message,
+        }, {
+            type: "clear_active_run",
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            runId: run.id,
+            nextLifecycleStatus: "failed",
+            reason: "run failed while PatchRelay still owned the expected active Linear state",
+        });
+        if (issue.statusCommentId) {
+            actions.push({
+                type: "refresh_status_comment",
+                projectId: issue.projectId,
+                linearIssueId: issue.linearIssueId,
+                runId: run.id,
+                commentId: issue.statusCommentId,
+                mode: "failed",
+                reason: "run failed and should refresh the service-owned status comment",
+            });
+        }
+        return {
+            outcome: "fail",
+            reasons: [message],
+            actions,
+        };
+    }
+    actions.push({
+        type: "release_issue_ownership",
+        projectId: issue.projectId,
+        linearIssueId: issue.linearIssueId,
+        runId: run.id,
+        nextLifecycleStatus: "failed",
+        reason: "run failed after the live Linear state moved on",
+    });
+    return {
+        outcome: "release",
+        reasons: [message, "live Linear state no longer matches the expected service-owned active state"],
+        actions,
+    };
+}
+function routePendingObligations(issue, run, obligations, threadId, turnId) {
+    if (!turnId) {
+        return [];
+    }
+    const actions = [];
+    for (const obligation of obligations) {
+        const needsRouting = obligation.threadId !== threadId || obligation.turnId !== turnId;
+        if (needsRouting) {
+            actions.push({
+                type: "route_obligation",
+                projectId: issue.projectId,
+                linearIssueId: issue.linearIssueId,
+                obligationId: obligation.id,
+                runId: run.id,
+                threadId,
+                turnId,
+                reason: "pending obligation should target the latest live turn",
+            });
+        }
+        actions.push({
+            type: "deliver_obligation",
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            obligationId: obligation.id,
+            runId: run.id,
+            threadId,
+            turnId,
+            reason: "pending obligation can be delivered to the active turn",
+        });
+    }
+    return actions;
+}
+function needsLinearState(issue, policy, liveLinear) {
+    if (!issue.activeRun) {
+        return false;
+    }
+    if (!policy.activeLinearStateName && !policy.fallbackLinearStateName) {
+        return false;
+    }
+    return liveLinear.status === "unknown";
+}
+function needsCodexState(run, liveCodex) {
+    if (!run.threadId) {
+        return false;
+    }
+    return liveCodex.status === "unknown";
+}
+function shouldFailBack(liveLinear, policy) {
+    return matchesActiveLinearOwnership(liveLinear, policy);
+}
+function shouldAwaitHandoff(liveLinear, policy) {
+    return matchesActiveLinearOwnership(liveLinear, policy);
+}
+function matchesActiveLinearOwnership(liveLinear, policy) {
+    if (!policy.activeLinearStateName) {
+        return true;
+    }
+    if (liveLinear.status !== "known") {
+        return false;
+    }
+    return liveLinear.issue?.stateName === policy.activeLinearStateName;
+}
+function relevantObligations(issue, obligations) {
+    const activeRunId = issue.activeRun?.id;
+    return obligations.filter((obligation) => {
+        if (obligation.status === "completed" || obligation.status === "cancelled") {
+            return false;
+        }
+        if (activeRunId === undefined) {
+            return false;
+        }
+        return obligation.runId === undefined || obligation.runId === activeRunId;
+    });
+}
+function latestThreadTurn(thread) {
+    return thread.turns.at(-1);
+}

package/dist/reconciliation-snapshot-builder.js

@@ -0,0 +1,96 @@
+import { safeJsonParse } from "./utils.js";
+export async function buildReconciliationSnapshot(params) {
+    const runLease = params.stores.runLeases.getRunLease(params.runLeaseId);
+    if (!runLease) {
+        return undefined;
+    }
+    const issueControl = params.stores.issueControl.getIssueControl(runLease.projectId, runLease.linearIssueId);
+    if (!issueControl) {
+        return undefined;
+    }
+    const workspaceOwnership = params.stores.workspaceOwnership.getWorkspaceOwnership(runLease.workspaceOwnershipId);
+    const project = params.config.projects.find((candidate) => candidate.id === runLease.projectId);
+    const workflowConfig = project?.workflows.find((workflow) => workflow.id === runLease.stage);
+    const liveLinear = project
+        ? await params.linearProvider
+            .forProject(runLease.projectId)
+            .then((linear) => linear
+            ? linear.getIssue(runLease.linearIssueId).then((issue) => issue.stateName
+                ? {
+                    status: "known",
+                    issue: {
+                        id: issue.id,
+                        stateName: issue.stateName,
+                    },
+                }
+                : ({ status: "unknown" }))
+            : ({ status: "unknown" }))
+            .catch(() => ({ status: "unknown" }))
+        : ({ status: "unknown" });
+    const liveCodex = runLease.threadId
+        ? await params.codex
+            .readThread(runLease.threadId, true)
+            .then((thread) => ({ status: "found", thread }))
+            .catch((error) => mapCodexReadFailure(error))
+        : ({ status: "unknown" });
+    const obligations = params.stores.obligations
+        .listPendingObligations({ runLeaseId: runLease.id, includeInProgress: true })
+        .map((obligation) => {
+        const payload = safeJsonParse(obligation.payloadJson);
+        return {
+            id: obligation.id,
+            kind: obligation.kind,
+            status: obligation.status,
+            ...(obligation.runLeaseId !== undefined ? { runId: obligation.runLeaseId } : {}),
+            ...(obligation.threadId ? { threadId: obligation.threadId } : {}),
+            ...(obligation.turnId ? { turnId: obligation.turnId } : {}),
+            ...(payload !== undefined ? { payload } : {}),
+        };
+    });
+    return {
+        issueControl,
+        runLease,
+        ...(workspaceOwnership ? { workspaceOwnership } : {}),
+        input: {
+            issue: {
+                projectId: runLease.projectId,
+                linearIssueId: runLease.linearIssueId,
+                ...(issueControl.desiredStage ? { desiredStage: issueControl.desiredStage } : {}),
+                lifecycleStatus: issueControl.lifecycleStatus,
+                ...(issueControl.serviceOwnedCommentId ? { statusCommentId: issueControl.serviceOwnedCommentId } : {}),
+                activeRun: {
+                    id: runLease.id,
+                    stage: runLease.stage,
+                    status: runLease.status,
+                    ...(runLease.threadId ? { threadId: runLease.threadId } : {}),
+                    ...(runLease.turnId ? { turnId: runLease.turnId } : {}),
+                    ...(runLease.parentThreadId ? { parentThreadId: runLease.parentThreadId } : {}),
+                },
+            },
+            ...(obligations.length > 0 ? { obligations } : {}),
+            ...(workflowConfig
+                ? {
+                    policy: {
+                        ...(workflowConfig.activeState ? { activeLinearStateName: workflowConfig.activeState } : {}),
+                        ...(workflowConfig.fallbackState ? { fallbackLinearStateName: workflowConfig.fallbackState } : {}),
+                    },
+                }
+                : {}),
+            live: {
+                linear: liveLinear,
+                codex: liveCodex,
+            },
+        },
+    };
+}
+function mapCodexReadFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const normalized = message.trim().toLowerCase();
+    if (normalized.includes("not found") || normalized.includes("missing")) {
+        return { status: "missing" };
+    }
+    return {
+        status: "error",
+        errorMessage: message,
+    };
+}

package/dist/reconciliation-types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime-paths.js

@@ -0,0 +1,89 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureAbsolutePath } from "./utils.js";
+export function getPatchRelayPathLayout() {
+    const homeDir = homedir();
+    const xdgConfigHome = process.env.XDG_CONFIG_HOME ?? path.join(homeDir, ".config");
+    const xdgStateHome = process.env.XDG_STATE_HOME ?? path.join(homeDir, ".local", "state");
+    const xdgDataHome = process.env.XDG_DATA_HOME ?? path.join(homeDir, ".local", "share");
+    const configPath = ensureAbsolutePath(process.env.PATCHRELAY_CONFIG ?? path.join(xdgConfigHome, "patchrelay", "patchrelay.json"));
+    const configDir = path.dirname(configPath);
+    const runtimeEnvPath = path.join(configDir, "runtime.env");
+    const serviceEnvPath = path.join(configDir, "service.env");
+    const stateDir = path.join(xdgStateHome, "patchrelay");
+    const shareDir = path.join(xdgDataHome, "patchrelay");
+    const systemdUserDir = path.join(xdgConfigHome, "systemd", "user");
+    return {
+        homeDir,
+        configDir,
+        configPath,
+        runtimeEnvPath,
+        serviceEnvPath,
+        stateDir,
+        shareDir,
+        databasePath: ensureAbsolutePath(process.env.PATCHRELAY_DB_PATH ?? path.join(stateDir, "patchrelay.sqlite")),
+        logFilePath: ensureAbsolutePath(process.env.PATCHRELAY_LOG_FILE ?? path.join(stateDir, "patchrelay.log")),
+        systemdUserDir,
+        systemdUnitPath: path.join(systemdUserDir, "patchrelay.service"),
+        systemdReloadUnitPath: path.join(systemdUserDir, "patchrelay-reload.service"),
+        systemdPathUnitPath: path.join(systemdUserDir, "patchrelay.path"),
+    };
+}
+export function getPatchRelayConfigDir() {
+    return getPatchRelayPathLayout().configDir;
+}
+export function getDefaultConfigPath() {
+    return getPatchRelayPathLayout().configPath;
+}
+export function getDefaultRuntimeEnvPath() {
+    return getPatchRelayPathLayout().runtimeEnvPath;
+}
+export function getDefaultServiceEnvPath() {
+    return getPatchRelayPathLayout().serviceEnvPath;
+}
+export function getPatchRelayStateDir() {
+    return getPatchRelayPathLayout().stateDir;
+}
+export function getPatchRelayDataDir() {
+    return getPatchRelayPathLayout().shareDir;
+}
+export function getDefaultDatabasePath() {
+    return getPatchRelayPathLayout().databasePath;
+}
+export function getDefaultLogPath() {
+    return getPatchRelayPathLayout().logFilePath;
+}
+export function getDefaultWebhookArchiveDir() {
+    return path.join(getPatchRelayStateDir(), "webhooks");
+}
+export function getSystemdUserUnitPath() {
+    return getPatchRelayPathLayout().systemdUnitPath;
+}
+export function getSystemdUserReloadUnitPath() {
+    return getPatchRelayPathLayout().systemdReloadUnitPath;
+}
+export function getSystemdUserPathUnitPath() {
+    return getPatchRelayPathLayout().systemdPathUnitPath;
+}
+export function getPackageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+export function getBundledAssetPath(relativePath) {
+    return path.join(getPackageRoot(), relativePath);
+}
+export function readBundledAsset(relativePath) {
+    const assetPath = getBundledAssetPath(relativePath);
+    if (!existsSync(assetPath)) {
+        throw new Error(`Bundled asset not found: ${assetPath}`);
+    }
+    return readFileSync(assetPath, "utf8");
+}
+export function getBuiltCliEntryPath() {
+    const entryPath = getBundledAssetPath("dist/index.js");
+    if (!existsSync(entryPath)) {
+        throw new Error(`Built PatchRelay entrypoint not found: ${entryPath}. Run npm run build before installing the service.`);
+    }
+    return entryPath;
+}

package/dist/service-queue.js

@@ -0,0 +1,49 @@
+export class SerialWorkQueue {
+    onDequeue;
+    logger;
+    getKey;
+    items = [];
+    queuedKeys = new Set();
+    pending = false;
+    constructor(onDequeue, logger, getKey) {
+        this.onDequeue = onDequeue;
+        this.logger = logger;
+        this.getKey = getKey;
+    }
+    enqueue(item) {
+        const key = this.getKey?.(item);
+        if (key && this.queuedKeys.has(key)) {
+            return;
+        }
+        this.items.push(item);
+        if (key) {
+            this.queuedKeys.add(key);
+        }
+        if (!this.pending) {
+            this.pending = true;
+            queueMicrotask(() => {
+                void this.drain();
+            });
+        }
+    }
+    async drain() {
+        while (this.items.length > 0) {
+            const next = this.items.shift();
+            if (next === undefined) {
+                continue;
+            }
+            const key = this.getKey?.(next);
+            if (key) {
+                this.queuedKeys.delete(key);
+            }
+            try {
+                await this.onDequeue(next);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.logger.error({ item: next, error: err.message, stack: err.stack }, "Queue item processing failed");
+            }
+        }
+        this.pending = false;
+    }
+}

package/dist/service-runtime.js

@@ -0,0 +1,96 @@
+import { SerialWorkQueue } from "./service-queue.js";
+const ISSUE_KEY_DELIMITER = "::";
+function toReconciler(value) {
+    if (typeof value === "function") {
+        return {
+            reconcileActiveStageRuns: value,
+        };
+    }
+    return value;
+}
+function toReadyIssueSource(value) {
+    if (typeof value === "function") {
+        return {
+            listIssuesReadyForExecution: value,
+        };
+    }
+    return value;
+}
+function toWebhookProcessor(value) {
+    if (typeof value === "function") {
+        return {
+            processWebhookEvent: value,
+        };
+    }
+    return value;
+}
+function toIssueProcessor(value) {
+    if (typeof value === "function") {
+        return {
+            processIssue: value,
+        };
+    }
+    return value;
+}
+function makeIssueQueueKey(item) {
+    return `${item.projectId}${ISSUE_KEY_DELIMITER}${item.issueId}`;
+}
+// ServiceRuntime is the coordination seam for the harness. It is responsible for
+// startup reconciliation, queue ownership, and handing eligible work to the stage runner.
+export class ServiceRuntime {
+    codex;
+    logger;
+    webhookQueue;
+    issueQueue;
+    ready = false;
+    startupError;
+    constructor(codex, logger, stageRunReconciler, readyIssueSource, webhookProcessor, issueProcessor) {
+        this.codex = codex;
+        this.logger = logger;
+        this.stageRunReconciler = toReconciler(stageRunReconciler);
+        this.readyIssueSource = toReadyIssueSource(readyIssueSource);
+        this.webhookProcessor = toWebhookProcessor(webhookProcessor);
+        this.issueProcessor = toIssueProcessor(issueProcessor);
+        this.webhookQueue = new SerialWorkQueue((eventId) => this.webhookProcessor.processWebhookEvent(eventId), logger, (eventId) => String(eventId));
+        this.issueQueue = new SerialWorkQueue((item) => this.issueProcessor.processIssue(item), logger, makeIssueQueueKey);
+    }
+    stageRunReconciler;
+    readyIssueSource;
+    webhookProcessor;
+    issueProcessor;
+    async start() {
+        try {
+            await this.codex.start();
+            // Reconciliation happens before new work is enqueued so restart recovery can
+            // resolve or release any previously claimed work deterministically.
+            await this.stageRunReconciler.reconcileActiveStageRuns();
+            for (const issue of this.readyIssueSource.listIssuesReadyForExecution()) {
+                this.enqueueIssue(issue.projectId, issue.linearIssueId);
+            }
+            this.ready = true;
+            this.startupError = undefined;
+        }
+        catch (error) {
+            this.ready = false;
+            this.startupError = error instanceof Error ? error.message : String(error);
+            throw error;
+        }
+    }
+    stop() {
+        this.ready = false;
+        void this.codex.stop();
+    }
+    enqueueWebhookEvent(eventId) {
+        this.webhookQueue.enqueue(eventId);
+    }
+    enqueueIssue(projectId, issueId) {
+        this.issueQueue.enqueue({ projectId, issueId });
+    }
+    getReadiness() {
+        return {
+            ready: this.ready && this.codex.isStarted(),
+            codexStarted: this.codex.isStarted(),
+            ...(this.startupError ? { startupError: this.startupError } : {}),
+        };
+    }
+}