@renseiai/agentfactory-nextjs 0.8.0

package/dist/src/webhook/processor.js

@@ -0,0 +1,98 @@
+/**
+ * Webhook Processor — Main Entry Point
+ *
+ * Receives Linear webhook events, verifies signatures, runs idempotency
+ * checks, and dispatches to sub-handlers.
+ */
+import { NextResponse } from 'next/server';
+import { isAgentSessionCreated, isAgentSessionPrompted, isAgentSessionUpdated, isIssueUpdate, } from '@renseiai/agentfactory-linear';
+import { createLogger, generateRequestId } from '@renseiai/agentfactory-server';
+import { verifyWebhookSignature } from './signature.js';
+import { handleSessionCreated } from './handlers/session-created.js';
+import { handleSessionUpdated } from './handlers/session-updated.js';
+import { handleSessionPrompted } from './handlers/session-prompted.js';
+import { handleIssueUpdated } from './handlers/issue-updated.js';
+const baseLogger = createLogger('webhook');
+/**
+ * Create webhook route handlers from config.
+ *
+ * Returns { POST, GET } for use as Next.js App Router exports.
+ */
+export function createWebhookHandler(config) {
+    async function POST(request) {
+        const startTime = Date.now();
+        const requestId = generateRequestId();
+        const log = baseLogger.child({ requestId });
+        try {
+            const body = await request.text();
+            const signature = request.headers.get('linear-signature');
+            // Verify webhook signature
+            const webhookSecret = config.webhookSecret ?? process.env.LINEAR_WEBHOOK_SECRET;
+            if (!webhookSecret) {
+                const isProduction = process.env.NODE_ENV === 'production' ||
+                    process.env.VERCEL_ENV === 'production';
+                if (isProduction) {
+                    log.error('LINEAR_WEBHOOK_SECRET not configured - rejecting webhook in production');
+                    return NextResponse.json({ error: 'Service unavailable', message: 'Webhook signature verification not configured' }, { status: 503 });
+                }
+                else {
+                    log.warn('LINEAR_WEBHOOK_SECRET not configured - skipping signature verification in development');
+                }
+            }
+            else {
+                if (!verifyWebhookSignature(body, signature, webhookSecret)) {
+                    log.warn('Invalid webhook signature');
+                    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
+                }
+            }
+            const payload = JSON.parse(body);
+            log.info('Webhook received', {
+                webhookType: payload.type,
+                webhookAction: payload.action,
+                workspaceId: payload.organizationId,
+            });
+            const rawPayload = payload;
+            // Handle agent session 'create' events
+            if (isAgentSessionCreated(payload)) {
+                const result = await handleSessionCreated(config, payload, rawPayload, log);
+                if (result)
+                    return result;
+            }
+            // Handle agent session 'update' events (stop signal)
+            if (isAgentSessionUpdated(payload)) {
+                const result = await handleSessionUpdated(config, payload, rawPayload, log);
+                if (result)
+                    return result;
+            }
+            // Handle agent session 'prompted' events (follow-up messages)
+            if (isAgentSessionPrompted(payload)) {
+                const result = await handleSessionPrompted(config, payload, rawPayload, log);
+                if (result)
+                    return result;
+            }
+            // Handle Issue update events (status transitions)
+            if (isIssueUpdate(payload)) {
+                const result = await handleIssueUpdated(config, payload, log);
+                if (result)
+                    return result;
+            }
+            const durationMs = Date.now() - startTime;
+            log.info('Webhook processed', { durationMs });
+            return NextResponse.json({ success: true, duration: durationMs, requestId });
+        }
+        catch (err) {
+            const durationMs = Date.now() - startTime;
+            log.error('Webhook error', { error: err, durationMs });
+            return NextResponse.json({ error: 'Internal server error', requestId }, { status: 500 });
+        }
+    }
+    async function GET() {
+        baseLogger.debug('Health check requested');
+        return NextResponse.json({
+            status: 'ok',
+            endpoint: '/webhook',
+            description: 'Linear webhook receiver',
+        });
+    }
+    return { POST, GET };
+}

package/dist/src/webhook/signature.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Webhook Signature Verification
+ *
+ * HMAC-SHA256 verification for Linear webhook signatures.
+ * @see https://developers.linear.app/docs/webhooks#validating-webhooks
+ */
+/**
+ * Verify a Linear webhook signature using HMAC-SHA256.
+ *
+ * @param body - Raw request body string
+ * @param signature - Value of the `linear-signature` header
+ * @param secret - The webhook signing secret
+ * @returns true if the signature is valid
+ */
+export declare function verifyWebhookSignature(body: string, signature: string | null, secret: string): boolean;
+//# sourceMappingURL=signature.d.ts.map

package/dist/src/webhook/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../../src/webhook/signature.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,MAAM,EAAE,MAAM,GACb,OAAO,CAQT"}

package/dist/src/webhook/signature.js

@@ -0,0 +1,23 @@
+/**
+ * Webhook Signature Verification
+ *
+ * HMAC-SHA256 verification for Linear webhook signatures.
+ * @see https://developers.linear.app/docs/webhooks#validating-webhooks
+ */
+import crypto from 'crypto';
+/**
+ * Verify a Linear webhook signature using HMAC-SHA256.
+ *
+ * @param body - Raw request body string
+ * @param signature - Value of the `linear-signature` header
+ * @param secret - The webhook signing secret
+ * @returns true if the signature is valid
+ */
+export function verifyWebhookSignature(body, signature, secret) {
+    if (!signature)
+        return false;
+    const hmac = crypto.createHmac('sha256', secret);
+    hmac.update(body);
+    const digest = hmac.digest('hex');
+    return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
+}

package/dist/src/webhook/utils.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Webhook Utility Functions
+ *
+ * Shared helpers used by webhook sub-handlers.
+ */
+import type { LinearAgentClient, AgentWorkType } from '@renseiai/agentfactory-linear';
+import type { ResolvedWebhookConfig } from '../types.js';
+/**
+ * Activity types for Linear Agent API
+ */
+type ActivityType = 'thought' | 'response' | 'error';
+/**
+ * Emit an activity to the agent session.
+ * Uses Linear's native Agent API.
+ */
+export declare function emitActivity(client: LinearAgentClient, sessionId: string, type: ActivityType, body: string, ephemeral?: boolean): Promise<void>;
+/**
+ * Consolidated stop signal handler.
+ *
+ * Handles stops for sessions in any non-terminal state:
+ * - running/claimed: Worker will detect the status change and stop the agent
+ * - pending: Removes from global work queue and/or issue-pending queue
+ * - Any other non-terminal state: Updates status and cleans up
+ */
+export declare function handleStopSignal(config: ResolvedWebhookConfig, sessionId: string, issueId: string, organizationId?: string): Promise<void>;
+/**
+ * Resolve a state ID to its name using the Linear API.
+ */
+export declare function resolveStateName(config: ResolvedWebhookConfig, organizationId: string | undefined, issueId: string, stateId: string): Promise<string | undefined>;
+/**
+ * Check if a project is allowed for auto-trigger.
+ */
+export declare function isProjectAllowed(projectName: string | undefined, allowedProjects: string[]): boolean;
+/**
+ * Check if an issue has any excluded labels.
+ */
+export declare function hasExcludedLabel(labels: Array<{
+    name: string;
+}> | undefined, excludedLabels: string[]): boolean;
+/**
+ * Determine work type from issue status.
+ */
+export declare function determineWorkType(status: string | undefined): AgentWorkType;
+/**
+ * Default priority for work types (lower = higher priority).
+ */
+export declare function defaultGetPriority(workType: AgentWorkType): number;
+/**
+ * Get the app URL for constructing dashboard links.
+ */
+export declare function getAppUrl(config: ResolvedWebhookConfig): string;
+/**
+ * Get the priority for a work type, using config override if available.
+ */
+export declare function getPriority(config: ResolvedWebhookConfig, workType: AgentWorkType): number;
+/**
+ * Work type messages for queuing acknowledgment.
+ */
+export declare const WORK_TYPE_MESSAGES: Record<AgentWorkType, string>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/src/webhook/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/webhook/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAarF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAIxD;;GAEG;AACH,KAAK,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAA;AAEpD;;;GAGG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,iBAAiB,EACzB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,OAAO,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,qBAAqB,EAC7B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CA4Cf;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,qBAAqB,EAC7B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAgB7B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,GAAG,OAAO,CAIpG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAI/G;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAG3E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAelE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAM/D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,aAAa,GAAG,MAAM,CAE1F;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAY5D,CAAA"}

package/dist/src/webhook/utils.js

@@ -0,0 +1,166 @@
+/**
+ * Webhook Utility Functions
+ *
+ * Shared helpers used by webhook sub-handlers.
+ */
+import { STATUS_WORK_TYPE_MAP } from '@renseiai/agentfactory-linear';
+import { getSessionState, updateSessionStatus, removeFromQueue, removeParkedWorkBySessionId, releaseClaim, getIssueLock, releaseIssueLock, promoteNextPendingWork, createLogger, } from '@renseiai/agentfactory-server';
+const baseLogger = createLogger('webhook');
+/**
+ * Emit an activity to the agent session.
+ * Uses Linear's native Agent API.
+ */
+export async function emitActivity(client, sessionId, type, body, ephemeral) {
+    const isEphemeral = ephemeral ?? type === 'thought';
+    await client.createAgentActivity({
+        agentSessionId: sessionId,
+        content: { type, body },
+        ephemeral: isEphemeral,
+    });
+}
+/**
+ * Consolidated stop signal handler.
+ *
+ * Handles stops for sessions in any non-terminal state:
+ * - running/claimed: Worker will detect the status change and stop the agent
+ * - pending: Removes from global work queue and/or issue-pending queue
+ * - Any other non-terminal state: Updates status and cleans up
+ */
+export async function handleStopSignal(config, sessionId, issueId, organizationId) {
+    const stopLog = baseLogger.child({ sessionId, issueId, handler: 'handleStopSignal' });
+    const session = await getSessionState(sessionId);
+    if (session && ['completed', 'failed', 'stopped'].includes(session.status)) {
+        stopLog.info('Session already in terminal state, skipping stop', {
+            status: session.status,
+        });
+        return;
+    }
+    if (session) {
+        stopLog.info('Stopping session', {
+            previousStatus: session.status,
+            workerId: session.workerId,
+        });
+        await updateSessionStatus(sessionId, 'stopped');
+    }
+    else {
+        stopLog.info('No session state found, cleaning up queues only');
+    }
+    await removeFromQueue(sessionId);
+    await removeParkedWorkBySessionId(issueId, sessionId);
+    await releaseClaim(sessionId);
+    const lock = await getIssueLock(issueId);
+    if (lock && lock.sessionId === sessionId) {
+        await releaseIssueLock(issueId);
+        await promoteNextPendingWork(issueId);
+        stopLog.info('Released issue lock and promoted next pending work');
+    }
+    try {
+        const linearClient = await config.linearClient.getClient(organizationId);
+        const statusMsg = session?.status === 'pending'
+            ? 'Stop signal received. Queued work has been cancelled.'
+            : 'Stop signal received. Agent will stop shortly.';
+        await emitActivity(linearClient, sessionId, 'response', statusMsg);
+    }
+    catch (err) {
+        stopLog.error('Failed to emit stop activity', { error: err });
+    }
+}
+/**
+ * Resolve a state ID to its name using the Linear API.
+ */
+export async function resolveStateName(config, organizationId, issueId, stateId) {
+    try {
+        const linearClient = await config.linearClient.getClient(organizationId);
+        const issue = await linearClient.getIssue(issueId);
+        const team = await issue.team;
+        if (team) {
+            const statuses = await linearClient.getTeamStatuses(team.id);
+            const entry = Object.entries(statuses).find(([, id]) => id === stateId);
+            return entry?.[0];
+        }
+        return undefined;
+    }
+    catch (err) {
+        baseLogger.warn('Failed to resolve state name', { issueId, stateId, error: err });
+        return undefined;
+    }
+}
+/**
+ * Check if a project is allowed for auto-trigger.
+ */
+export function isProjectAllowed(projectName, allowedProjects) {
+    if (allowedProjects.length === 0)
+        return true;
+    if (!projectName)
+        return false;
+    return allowedProjects.includes(projectName);
+}
+/**
+ * Check if an issue has any excluded labels.
+ */
+export function hasExcludedLabel(labels, excludedLabels) {
+    if (excludedLabels.length === 0)
+        return false;
+    if (!labels || labels.length === 0)
+        return false;
+    return labels.some(label => excludedLabels.includes(label.name));
+}
+/**
+ * Determine work type from issue status.
+ */
+export function determineWorkType(status) {
+    if (!status)
+        return 'development';
+    return STATUS_WORK_TYPE_MAP[status] ?? 'development';
+}
+/**
+ * Default priority for work types (lower = higher priority).
+ */
+export function defaultGetPriority(workType) {
+    switch (workType) {
+        case 'qa': return 2;
+        case 'acceptance': return 2;
+        case 'refinement': return 2;
+        case 'refinement-coordination': return 2;
+        case 'inflight': return 2;
+        case 'backlog-creation': return 3;
+        case 'development': return 3;
+        case 'research': return 4;
+        case 'coordination': return 2;
+        case 'qa-coordination': return 2;
+        case 'acceptance-coordination': return 2;
+        default: return 3;
+    }
+}
+/**
+ * Get the app URL for constructing dashboard links.
+ */
+export function getAppUrl(config) {
+    return config.appUrl
+        ?? process.env.NEXT_PUBLIC_APP_URL
+        ?? (process.env.VERCEL_PROJECT_PRODUCTION_URL && `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`)
+        ?? (process.env.VERCEL_URL && `https://${process.env.VERCEL_URL}`)
+        ?? 'https://agent.rensei.dev';
+}
+/**
+ * Get the priority for a work type, using config override if available.
+ */
+export function getPriority(config, workType) {
+    return config.getPriority?.(workType) ?? defaultGetPriority(workType);
+}
+/**
+ * Work type messages for queuing acknowledgment.
+ */
+export const WORK_TYPE_MESSAGES = {
+    research: 'Research work queued. Agent will analyze and flesh out story requirements...',
+    'backlog-creation': 'Backlog creation queued. Agent will break down the story into separate issues...',
+    development: 'Development work queued. Waiting for an available worker...',
+    inflight: 'Resuming in-flight work. Agent will continue where it left off...',
+    qa: 'QA work queued. Waiting for an available worker to validate the implementation...',
+    acceptance: 'Acceptance testing queued. Agent will verify the deployed preview...',
+    refinement: 'Refinement work queued. Agent will address rejection feedback...',
+    coordination: 'Coordination work queued. Agent will orchestrate sub-issue execution...',
+    'qa-coordination': 'QA coordination queued. Agent will validate all sub-issues in parallel...',
+    'acceptance-coordination': 'Acceptance coordination queued. Agent will verify sub-issues and merge PR...',
+    'refinement-coordination': 'Refinement coordination queued. Agent will triage QA/acceptance failures to sub-issues...',
+};

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@renseiai/agentfactory-nextjs",
+  "version": "0.8.0",
+  "type": "module",
+  "description": "Next.js API route handlers for AgentFactory — webhook processor, worker/session management, public stats",
+  "author": "Rensei AI (https://rensei.ai)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/renseiai/agentfactory",
+    "directory": "packages/nextjs"
+  },
+  "homepage": "https://github.com/renseiai/agentfactory/tree/main/packages/nextjs",
+  "bugs": {
+    "url": "https://github.com/renseiai/agentfactory/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/src/index.d.ts",
+        "import": "./dist/src/index.js",
+        "default": "./dist/src/index.js"
+      },
+      "./middleware": {
+        "types": "./dist/src/middleware/index.d.ts",
+        "import": "./dist/src/middleware/index.js",
+        "default": "./dist/src/middleware/index.js"
+      }
+    },
+    "main": "./dist/src/index.js",
+    "types": "./dist/src/index.d.ts"
+  },
+  "keywords": [
+    "nextjs",
+    "api-routes",
+    "webhook",
+    "agent-server",
+    "linear"
+  ],
+  "main": "./dist/src/index.js",
+  "module": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    },
+    "./middleware": {
+      "types": "./src/middleware/index.ts",
+      "import": "./dist/src/middleware/index.js",
+      "default": "./dist/src/middleware/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@renseiai/agentfactory": "workspace:*",
+    "@renseiai/agentfactory-linear": "workspace:*",
+    "@renseiai/agentfactory-server": "workspace:*"
+  },
+  "peerDependencies": {
+    "next": ">=14.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.4",
+    "next": "^15.3.3",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm clean && pnpm build"
+  }
+}