patchrelay 0.1.0

package/dist/webhook-agent-session-handler.js

@@ -0,0 +1,157 @@
+import { createHash } from "node:crypto";
+import { triggerEventAllowed } from "./project-resolution.js";
+import { listRunnableStates, resolveWorkflowStage } from "./workflow-policy.js";
+function trimPrompt(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+export class AgentSessionWebhookHandler {
+    stores;
+    turnInputDispatcher;
+    agentActivity;
+    constructor(stores, turnInputDispatcher, agentActivity) {
+        this.stores = stores;
+        this.turnInputDispatcher = turnInputDispatcher;
+        this.agentActivity = agentActivity;
+    }
+    async handle(params) {
+        const { normalized, project, issue, desiredStage, delegatedToPatchRelay } = params;
+        if (!normalized.agentSession?.id) {
+            return;
+        }
+        const promptBody = trimPrompt(normalized.agentSession.promptBody);
+        const promptContext = trimPrompt(normalized.agentSession.promptContext);
+        const issueControl = normalized.issue ? this.stores.issueControl.getIssueControl(project.id, normalized.issue.id) : undefined;
+        const activeRunLease = issueControl?.activeRunLeaseId !== undefined ? this.stores.runLeases.getRunLease(issueControl.activeRunLeaseId) : undefined;
+        const activeStage = activeRunLease?.stage;
+        const runnableWorkflow = normalized.issue?.stateName ? resolveWorkflowStage(project, normalized.issue.stateName) : undefined;
+        if (normalized.triggerEvent === "agentSessionCreated") {
+            if (!delegatedToPatchRelay) {
+                if (activeStage) {
+                    await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
+                        type: "thought",
+                        body: `PatchRelay is already running the ${activeStage} workflow for this issue. Delegate it to PatchRelay if you want automation to own the workflow, or keep replying here to steer the active run.`,
+                    });
+                    return;
+                }
+                const body = runnableWorkflow
+                    ? `PatchRelay received your mention. Delegate the issue to PatchRelay to start the ${runnableWorkflow} workflow from the current \`${normalized.issue?.stateName}\` state.`
+                    : `PatchRelay received your mention, but the issue is not in a runnable workflow state yet. Move it to one of: ${listRunnableStates(project).join(", ")}, then delegate it to PatchRelay.`;
+                await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
+                    type: "elicitation",
+                    body,
+                });
+                return;
+            }
+            if (!desiredStage && !activeStage) {
+                const runnableStates = listRunnableStates(project).join(", ");
+                await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
+                    type: "elicitation",
+                    body: `PatchRelay is delegated, but the issue is not in a runnable workflow state. Move it to one of: ${runnableStates}.`,
+                });
+                return;
+            }
+            if (desiredStage) {
+                await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
+                    type: "thought",
+                    body: `PatchRelay received the delegation and is preparing the ${desiredStage} workflow.`,
+                });
+                return;
+            }
+            if (activeStage) {
+                await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
+                    type: "thought",
+                    body: `PatchRelay is already running the ${activeStage} workflow for this issue.`,
+                });
+            }
+            return;
+        }
+        if (normalized.triggerEvent !== "agentPrompted") {
+            return;
+        }
+        if (!triggerEventAllowed(project, normalized.triggerEvent)) {
+            return;
+        }
+        if (activeRunLease && promptBody) {
+            const dedupeKey = buildPromptDedupeKey(normalized.agentSession.id, promptBody);
+            if (issueControl?.activeRunLeaseId !== undefined &&
+                this.stores.obligations.getObligationByDedupeKey({
+                    runLeaseId: issueControl.activeRunLeaseId,
+                    kind: "deliver_turn_input",
+                    dedupeKey,
+                })) {
+                return;
+            }
+            const promptInput = ["New Linear agent prompt received while you are working.", "", promptBody].join("\n");
+            const source = `linear-agent-prompt:${normalized.agentSession.id}:${normalized.webhookId}`;
+            const obligationId = this.enqueueObligation(project.id, normalized.issue.id, activeRunLease.threadId, activeRunLease.turnId, source, promptInput, dedupeKey);
+            const flushResult = await this.turnInputDispatcher.flush({
+                id: issueControl?.activeRunLeaseId ?? 0,
+                projectId: project.id,
+                linearIssueId: normalized.issue.id,
+                ...(activeRunLease.threadId ? { threadId: activeRunLease.threadId } : {}),
+                ...(activeRunLease.turnId ? { turnId: activeRunLease.turnId } : {}),
+            }, {
+                ...(issue?.issueKey ? { issueKey: issue.issueKey } : {}),
+                failureMessage: "Failed to deliver queued Linear agent prompt to active Codex turn",
+            });
+            await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
+                type: "thought",
+                body: obligationId !== undefined && flushResult.deliveredObligationIds.includes(obligationId)
+                    ? `PatchRelay routed your follow-up instructions into the active ${activeRunLease.stage} workflow.`
+                    : `PatchRelay queued your follow-up instructions for delivery into the active ${activeRunLease.stage} workflow.`,
+            });
+            return;
+        }
+        if (!delegatedToPatchRelay && (promptBody || promptContext)) {
+            const body = runnableWorkflow
+                ? `PatchRelay received your prompt. Delegate the issue to PatchRelay to start the ${runnableWorkflow} workflow from the current \`${normalized.issue?.stateName}\` state.`
+                : `PatchRelay received your prompt, but the issue is not in a runnable workflow state yet. Move it to one of: ${listRunnableStates(project).join(", ")}, then delegate it to PatchRelay.`;
+            await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
+                type: "elicitation",
+                body,
+            });
+            return;
+        }
+        if (!activeRunLease && desiredStage) {
+            await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
+                type: "thought",
+                body: `PatchRelay received your prompt and is preparing the ${desiredStage} workflow.`,
+            });
+            return;
+        }
+        if (!activeRunLease && !desiredStage && (promptBody || promptContext)) {
+            const runnableStates = listRunnableStates(project).join(", ");
+            await this.agentActivity.publishForSession(project.id, normalized.agentSession.id, {
+                type: "elicitation",
+                body: `PatchRelay received your prompt, but the issue is not in a runnable workflow state yet. Move it to one of: ${runnableStates}.`,
+            });
+        }
+    }
+    enqueueObligation(projectId, linearIssueId, threadId, turnId, source, promptBody, dedupeKey) {
+        const activeRunLeaseId = this.stores.issueControl.getIssueControl(projectId, linearIssueId)?.activeRunLeaseId;
+        if (activeRunLeaseId === undefined) {
+            return undefined;
+        }
+        const obligation = this.stores.obligations.enqueueObligation({
+            projectId,
+            linearIssueId,
+            kind: "deliver_turn_input",
+            source,
+            payloadJson: JSON.stringify({
+                body: promptBody,
+            }),
+            runLeaseId: activeRunLeaseId,
+            ...(threadId ? { threadId } : {}),
+            ...(turnId ? { turnId } : {}),
+            dedupeKey,
+        });
+        return obligation.id;
+    }
+}
+function buildPromptDedupeKey(agentSessionId, promptBody) {
+    return `linear-agent-prompt:${agentSessionId}:${hashBody(promptBody)}`;
+}
+function hashBody(value) {
+    return createHash("sha256").update(value).digest("hex");
+}

package/dist/webhook-archive.js

@@ -0,0 +1,24 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+const REDACTED_HEADERS = new Set(["authorization", "cookie", "set-cookie", "linear-signature"]);
+function sanitizePathSegment(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+export async function archiveWebhook(params) {
+    const datePrefix = params.receivedAt.slice(0, 10);
+    const directory = path.join(params.archiveDir, datePrefix);
+    const fileName = `${params.receivedAt.replace(/[:.]/g, "-")}-${sanitizePathSegment(params.webhookId)}.json`;
+    const filePath = path.join(directory, fileName);
+    await mkdir(directory, { recursive: true });
+    await writeFile(filePath, JSON.stringify({
+        webhookId: params.webhookId,
+        receivedAt: params.receivedAt,
+        headers: redactHeaders(params.headers),
+        rawBodyUtf8: params.rawBody.toString("utf8"),
+        payload: params.payload,
+    }, null, 2), "utf8");
+    return filePath;
+}
+function redactHeaders(headers) {
+    return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, REDACTED_HEADERS.has(key.toLowerCase()) ? "[redacted]" : value]));
+}

package/dist/webhook-comment-handler.js

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { isPatchRelayStatusComment } from "./linear-workflow.js";
+import { triggerEventAllowed } from "./project-resolution.js";
+export class CommentWebhookHandler {
+    stores;
+    turnInputDispatcher;
+    constructor(stores, turnInputDispatcher) {
+        this.stores = stores;
+        this.turnInputDispatcher = turnInputDispatcher;
+    }
+    async handle(normalized, project) {
+        if ((normalized.triggerEvent !== "commentCreated" && normalized.triggerEvent !== "commentUpdated") || !normalized.comment?.body) {
+            return;
+        }
+        if (!triggerEventAllowed(project, normalized.triggerEvent)) {
+            return;
+        }
+        const normalizedIssue = normalized.issue;
+        if (!normalizedIssue) {
+            return;
+        }
+        const issue = this.stores.issueWorkflows.getTrackedIssue(project.id, normalizedIssue.id);
+        const issueControl = this.stores.issueControl.getIssueControl(project.id, normalizedIssue.id);
+        if (!issueControl?.activeRunLeaseId) {
+            return;
+        }
+        if (isPatchRelayStatusComment(normalized.comment.id, normalized.comment.body, issueControl.serviceOwnedCommentId ?? issue?.statusCommentId)) {
+            return;
+        }
+        const runLease = this.stores.runLeases.getRunLease(issueControl.activeRunLeaseId);
+        if (!runLease) {
+            return;
+        }
+        const body = [
+            "New Linear comment received while you are working.",
+            normalized.comment.userName ? `Author: ${normalized.comment.userName}` : undefined,
+            "",
+            normalized.comment.body.trim(),
+        ]
+            .filter(Boolean)
+            .join("\n");
+        const dedupeKey = buildCommentDedupeKey(normalized.comment.id, body);
+        if (issueControl.activeRunLeaseId !== undefined &&
+            this.stores.obligations.getObligationByDedupeKey({
+                runLeaseId: issueControl.activeRunLeaseId,
+                kind: "deliver_turn_input",
+                dedupeKey,
+            })) {
+            return;
+        }
+        this.enqueueObligation(project.id, normalizedIssue.id, runLease.threadId, runLease.turnId, normalized.comment.id, body, dedupeKey);
+        await this.turnInputDispatcher.flush({
+            id: issueControl.activeRunLeaseId,
+            projectId: project.id,
+            linearIssueId: normalizedIssue.id,
+            ...(runLease.threadId ? { threadId: runLease.threadId } : {}),
+            ...(runLease.turnId ? { turnId: runLease.turnId } : {}),
+        }, {
+            ...(issue?.issueKey ? { issueKey: issue.issueKey } : {}),
+            failureMessage: "Failed to deliver queued Linear comment to active Codex turn",
+        });
+    }
+    enqueueObligation(projectId, linearIssueId, threadId, turnId, commentId, body, dedupeKey) {
+        const activeRunLeaseId = this.stores.issueControl.getIssueControl(projectId, linearIssueId)?.activeRunLeaseId;
+        if (activeRunLeaseId === undefined) {
+            return undefined;
+        }
+        const obligation = this.stores.obligations.enqueueObligation({
+            projectId,
+            linearIssueId,
+            kind: "deliver_turn_input",
+            source: `linear-comment:${commentId}`,
+            payloadJson: JSON.stringify({
+                body,
+            }),
+            runLeaseId: activeRunLeaseId,
+            ...(threadId ? { threadId } : {}),
+            ...(turnId ? { turnId } : {}),
+            dedupeKey,
+        });
+        return obligation.id;
+    }
+}
+function buildCommentDedupeKey(commentId, body) {
+    return `linear-comment:${commentId}:${hashBody(body)}`;
+}
+function hashBody(value) {
+    return createHash("sha256").update(value).digest("hex");
+}

package/dist/webhook-desired-stage-recorder.js

@@ -0,0 +1,150 @@
+import { triggerEventAllowed } from "./project-resolution.js";
+import { resolveWorkflowStage } from "./workflow-policy.js";
+function trimPrompt(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+export class WebhookDesiredStageRecorder {
+    stores;
+    constructor(stores) {
+        this.stores = stores;
+    }
+    record(project, normalized, options) {
+        const normalizedIssue = normalized.issue;
+        if (!normalizedIssue) {
+            return {
+                issue: undefined,
+                activeStageRun: undefined,
+                desiredStage: undefined,
+                delegatedToPatchRelay: false,
+                launchInput: undefined,
+            };
+        }
+        const issue = this.stores.issueWorkflows.getTrackedIssue(project.id, normalizedIssue.id);
+        const issueControl = this.stores.issueControl.getIssueControl(project.id, normalizedIssue.id);
+        const activeStageRun = issueControl?.activeRunLeaseId !== undefined ? this.stores.issueWorkflows.getStageRun(issueControl.activeRunLeaseId) : undefined;
+        const delegatedToPatchRelay = this.isDelegatedToPatchRelay(project, normalized);
+        const stageAllowed = triggerEventAllowed(project, normalized.triggerEvent);
+        const desiredStage = this.resolveDesiredStage(project, normalized, issue, activeStageRun, delegatedToPatchRelay);
+        const launchInput = this.resolveLaunchInput(normalized.agentSession);
+        this.persistIssueControlFirst(project.id, normalizedIssue.id, issue, activeStageRun, desiredStage, normalized.agentSession?.id, options?.eventReceiptId);
+        this.stores.issueWorkflows.recordDesiredStage({
+            projectId: project.id,
+            linearIssueId: normalizedIssue.id,
+            ...(normalizedIssue.identifier ? { issueKey: normalizedIssue.identifier } : {}),
+            ...(normalizedIssue.title ? { title: normalizedIssue.title } : {}),
+            ...(normalizedIssue.url ? { issueUrl: normalizedIssue.url } : {}),
+            ...(normalizedIssue.stateName ? { currentLinearState: normalizedIssue.stateName } : {}),
+            lastWebhookAt: new Date().toISOString(),
+        });
+        if (normalized.agentSession?.id) {
+            this.stores.issueWorkflows.setIssueActiveAgentSession(project.id, normalizedIssue.id, normalized.agentSession.id);
+        }
+        if (launchInput && !activeStageRun && delegatedToPatchRelay && stageAllowed) {
+            this.stores.obligations.enqueueObligation({
+                projectId: project.id,
+                linearIssueId: normalizedIssue.id,
+                kind: "deliver_turn_input",
+                source: `linear-agent-launch:${normalized.agentSession?.id ?? normalized.webhookId}`,
+                payloadJson: JSON.stringify({
+                    body: launchInput,
+                }),
+            });
+        }
+        const refreshedIssue = this.stores.issueWorkflows.getTrackedIssue(project.id, normalizedIssue.id);
+        this.syncIssueControl(project.id, normalizedIssue.id, refreshedIssue, desiredStage, normalized.agentSession?.id, options?.eventReceiptId);
+        return {
+            issue: refreshedIssue ?? issue,
+            activeStageRun,
+            desiredStage,
+            delegatedToPatchRelay,
+            launchInput,
+        };
+    }
+    isDelegatedToPatchRelay(project, normalized) {
+        const normalizedIssue = normalized.issue;
+        if (!normalizedIssue) {
+            return false;
+        }
+        const installation = this.stores.linearInstallations.getLinearInstallationForProject(project.id);
+        if (!installation?.actorId) {
+            return false;
+        }
+        return normalizedIssue.delegateId === installation.actorId;
+    }
+    resolveDesiredStage(project, normalized, issue, activeStageRun, delegatedToPatchRelay) {
+        const normalizedIssue = normalized.issue;
+        if (!normalizedIssue) {
+            return undefined;
+        }
+        const stageAllowed = triggerEventAllowed(project, normalized.triggerEvent);
+        let desiredStage;
+        if (normalized.triggerEvent === "delegateChanged") {
+            desiredStage = delegatedToPatchRelay ? resolveWorkflowStage(project, normalizedIssue.stateName) : undefined;
+            if (!desiredStage) {
+                return undefined;
+            }
+            if (!stageAllowed && !project.triggerEvents.includes("statusChanged")) {
+                return undefined;
+            }
+        }
+        else if (normalized.triggerEvent === "agentSessionCreated" || normalized.triggerEvent === "agentPrompted") {
+            if (!delegatedToPatchRelay || !stageAllowed) {
+                return undefined;
+            }
+            desiredStage = resolveWorkflowStage(project, normalizedIssue.stateName);
+        }
+        else if (stageAllowed) {
+            desiredStage = resolveWorkflowStage(project, normalizedIssue.stateName);
+        }
+        else {
+            return undefined;
+        }
+        if (activeStageRun && desiredStage === activeStageRun.stage) {
+            return undefined;
+        }
+        if (issue?.desiredStage && desiredStage === issue.desiredStage) {
+            return undefined;
+        }
+        return desiredStage;
+    }
+    resolveLaunchInput(agentSession) {
+        const promptBody = trimPrompt(agentSession?.promptBody);
+        if (promptBody) {
+            return ["New Linear agent input received.", "", promptBody].join("\n");
+        }
+        const promptContext = trimPrompt(agentSession?.promptContext);
+        if (promptContext) {
+            return ["Linear provided this initial agent context.", "", promptContext].join("\n");
+        }
+        return undefined;
+    }
+    persistIssueControlFirst(projectId, linearIssueId, issue, activeStageRun, desiredStage, activeAgentSessionId, eventReceiptId) {
+        if (!desiredStage) {
+            return;
+        }
+        const lifecycleStatus = issue?.lifecycleStatus ?? "queued";
+        this.stores.issueControl.upsertIssueControl({
+            projectId,
+            linearIssueId,
+            desiredStage,
+            ...(eventReceiptId !== undefined ? { desiredReceiptId: eventReceiptId } : {}),
+            ...(issue?.statusCommentId ? { serviceOwnedCommentId: issue.statusCommentId } : {}),
+            ...(activeAgentSessionId ? { activeAgentSessionId } : {}),
+            lifecycleStatus,
+        });
+    }
+    syncIssueControl(projectId, linearIssueId, issue, desiredStage, activeAgentSessionId, eventReceiptId) {
+        if (!issue) {
+            return;
+        }
+        this.stores.issueControl.upsertIssueControl({
+            projectId,
+            linearIssueId,
+            ...(desiredStage ? { desiredStage } : {}),
+            ...(eventReceiptId !== undefined && desiredStage ? { desiredReceiptId: eventReceiptId } : {}),
+            ...(activeAgentSessionId ? { activeAgentSessionId } : {}),
+            lifecycleStatus: issue.lifecycleStatus,
+        });
+    }
+}

package/dist/webhook-event-ports.js

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

package/dist/webhook-installation-handler.js

@@ -0,0 +1,57 @@
+export class InstallationWebhookHandler {
+    config;
+    stores;
+    logger;
+    constructor(config, stores, logger) {
+        this.config = config;
+        this.stores = stores;
+        this.logger = logger;
+    }
+    handle(normalized) {
+        if (!normalized.installation) {
+            return;
+        }
+        if (normalized.triggerEvent === "installationPermissionsChanged") {
+            const matchingInstallations = normalized.installation.appUserId
+                ? this.stores.linearInstallations
+                    .listLinearInstallations()
+                    .filter((installation) => installation.actorId === normalized.installation?.appUserId)
+                : [];
+            const links = this.stores.linearInstallations.listProjectInstallations();
+            const impactedProjects = matchingInstallations.flatMap((installation) => links
+                .filter((link) => link.installationId === installation.id)
+                .map((link) => {
+                const project = this.config.projects.find((entry) => entry.id === link.projectId);
+                const removedMatches = normalized.installation?.removedTeamIds.some((teamId) => project?.linearTeamIds.includes(teamId)) ?? false;
+                const addedMatches = normalized.installation?.addedTeamIds.some((teamId) => project?.linearTeamIds.includes(teamId)) ?? false;
+                return {
+                    projectId: link.projectId,
+                    removedMatches,
+                    addedMatches,
+                };
+            }));
+            this.logger.warn({
+                appUserId: normalized.installation.appUserId,
+                addedTeamIds: normalized.installation.addedTeamIds,
+                removedTeamIds: normalized.installation.removedTeamIds,
+                canAccessAllPublicTeams: normalized.installation.canAccessAllPublicTeams,
+                impactedProjects,
+            }, "Linear app-team permissions changed; reconnect or adjust project routing if PatchRelay lost required team access");
+            return;
+        }
+        if (normalized.triggerEvent === "installationRevoked") {
+            this.logger.warn({
+                organizationId: normalized.installation.organizationId,
+                oauthClientId: normalized.installation.oauthClientId,
+            }, "Linear OAuth app installation was revoked; reconnect affected projects with `patchrelay project apply <id> <repo-path>` or `patchrelay connect --project <id>`");
+            return;
+        }
+        if (normalized.triggerEvent === "appUserNotification") {
+            this.logger.info({
+                appUserId: normalized.installation.appUserId,
+                notificationType: normalized.installation.notificationType,
+                organizationId: normalized.installation.organizationId,
+            }, "Received Linear app-user notification webhook");
+        }
+    }
+}