pi-forge 1.2.5 → 1.3.0

package/dist/server/webhooks/dispatcher.js

@@ -0,0 +1,254 @@
+/**
+ * Webhook delivery: takes a candidate event, finds every webhook
+ * that subscribes to it (matching events + scope + enabled), and
+ * fires an HTTP POST per match with retry + delivery recording.
+ *
+ * Per-webhook fire-and-forget — the function returns as soon as
+ * the deliveries are kicked off. Retries run in the background.
+ * The event source (event-bridge.ts) doesn't block on webhook
+ * outcomes.
+ *
+ * Retry policy:
+ *   - 2xx                 → "delivered", no retry.
+ *   - 4xx                 → "failed", no retry (consumer's
+ *                           problem; retrying won't help).
+ *   - 5xx / network error → "error", retry with exponential
+ *                           backoff (1s, 5s, 30s — 3 attempts
+ *                           total counting the initial fire).
+ *
+ * HMAC: when `webhook.secret` is set, every request includes
+ *   `X-Pi-Forge-Signature: sha256=<hex of HMAC-SHA256(secret, body)>`.
+ * The hex digest is the same convention GitHub webhooks use.
+ *
+ * `insecureTls: true` swaps the `https.Agent` for one with
+ * `rejectUnauthorized: false`. Logged to stderr on every fire
+ * so the relaxed security is visible in `docker logs`.
+ */
+import { createHmac, randomUUID } from "node:crypto";
+import { Agent as HttpsAgent } from "node:https";
+import { recordDelivery, readWebhooks, SECRET_PLACEHOLDER } from "./store.js";
+/**
+ * Reusable agents. The insecure one is allocated lazily — most
+ * deployments never set `insecureTls` on any webhook, and we'd
+ * rather not have a permissive agent sitting around unless asked.
+ */
+const SECURE_AGENT = new HttpsAgent({ keepAlive: true });
+let insecureAgent;
+function getInsecureAgent() {
+    if (insecureAgent === undefined) {
+        insecureAgent = new HttpsAgent({ keepAlive: true, rejectUnauthorized: false });
+    }
+    return insecureAgent;
+}
+const BACKOFF_MS = [1_000, 5_000, 30_000];
+const MAX_ATTEMPTS = BACKOFF_MS.length;
+const REQUEST_TIMEOUT_MS = 30_000;
+const ERROR_PREVIEW_LIMIT = 200;
+/**
+ * Reserved headers we always set ourselves. User-supplied custom
+ * headers for these names are silently overridden — letting a
+ * webhook config rewrite `X-Pi-Forge-Signature` would defeat the
+ * point of HMAC.
+ */
+const RESERVED_HEADERS = new Set([
+    "content-type",
+    "x-pi-forge-event",
+    "x-pi-forge-delivery",
+    "x-pi-forge-signature",
+    "user-agent",
+]);
+/**
+ * Public entry point. Resolves once all matching webhooks have
+ * been queued (kicks off the first attempt synchronously per
+ * webhook so the operator can observe failures immediately, then
+ * retries continue in the background).
+ *
+ * Returns the number of webhooks targeted — useful for the test
+ * route to surface "0 webhooks matched" feedback.
+ */
+export async function dispatch(opts, targeting) {
+    const webhooks = await readWebhooks();
+    const matches = webhooks.filter((w) => isMatch(w, opts, targeting));
+    if (matches.length === 0)
+        return 0;
+    // Build the payload ONCE — same body across all matching
+    // webhooks. Each webhook gets its own deliveryId since each is
+    // independently retryable.
+    const timestamp = new Date().toISOString();
+    for (const webhook of matches) {
+        const payload = {
+            deliveryId: randomUUID(),
+            event: opts.event,
+            timestamp,
+            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+            ...(opts.projectId !== undefined ? { projectId: opts.projectId } : {}),
+            data: opts.data,
+        };
+        // Fire-and-forget. Retries handled inside; we don't await the
+        // full chain.
+        void deliverWithRetries(webhook, payload);
+    }
+    return matches.length;
+}
+function isMatch(webhook, opts, targeting) {
+    if (targeting?.onlyWebhookId !== undefined) {
+        return webhook.id === targeting.onlyWebhookId;
+    }
+    if (!webhook.enabled)
+        return false;
+    // Event subscription. `webhook.test` always matches if the test
+    // route invoked us (handled by targeting above); the real-event
+    // dispatch path goes through here and filters strictly.
+    if (opts.event === "webhook.test")
+        return false;
+    if (!webhook.events.includes(opts.event))
+        return false;
+    // Scope. Global webhooks match every event with a projectId or
+    // none. Per-project webhooks only fire when the event carries a
+    // matching projectId.
+    if (webhook.scope.kind === "project") {
+        return opts.projectId !== undefined && opts.projectId === webhook.scope.projectId;
+    }
+    return true;
+}
+async function deliverWithRetries(webhook, payload) {
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        const outcome = await deliverOnce(webhook, payload, attempt);
+        const record = {
+            id: randomUUID(),
+            webhookId: webhook.id,
+            deliveryId: payload.deliveryId,
+            event: payload.event,
+            attempt,
+            status: outcome.status,
+            durationMs: outcome.durationMs,
+            requestedAt: outcome.requestedAt,
+            ...(payload.sessionId !== undefined ? { sessionId: payload.sessionId } : {}),
+            ...(payload.projectId !== undefined ? { projectId: payload.projectId } : {}),
+            ...(outcome.statusCode !== undefined ? { statusCode: outcome.statusCode } : {}),
+            ...(outcome.errorPreview !== undefined ? { errorPreview: outcome.errorPreview } : {}),
+        };
+        await recordDelivery(record).catch(() => undefined);
+        // Stop on success or terminal-4xx; retry on error.
+        if (outcome.status === "delivered" || outcome.status === "failed")
+            return;
+        if (attempt < MAX_ATTEMPTS) {
+            const backoff = BACKOFF_MS[attempt - 1] ?? BACKOFF_MS[BACKOFF_MS.length - 1] ?? 1000;
+            await new Promise((resolve) => setTimeout(resolve, backoff));
+        }
+    }
+}
+async function deliverOnce(webhook, payload, attempt) {
+    const body = JSON.stringify(payload);
+    const headers = {
+        "Content-Type": "application/json; charset=utf-8",
+        "User-Agent": "pi-forge-webhook/1.0",
+        "X-Pi-Forge-Event": payload.event,
+        "X-Pi-Forge-Delivery": payload.deliveryId,
+    };
+    if (webhook.secret !== undefined && webhook.secret.length > 0) {
+        const sig = createHmac("sha256", webhook.secret).update(body).digest("hex");
+        headers["X-Pi-Forge-Signature"] = `sha256=${sig}`;
+    }
+    if (webhook.headers !== undefined) {
+        for (const [name, value] of Object.entries(webhook.headers)) {
+            if (RESERVED_HEADERS.has(name.toLowerCase()))
+                continue;
+            // Defense in depth: the CRUD path round-trips header values
+            // through the SECRET_PLACEHOLDER sentinel so the wire never
+            // exposes them. A hand-edited webhooks.json (or a future
+            // bug) could leak the sentinel into stored config — skip
+            // here so we never POST literally `Authorization: ***REDACTED***`
+            // to the consumer.
+            if (value === SECRET_PLACEHOLDER)
+                continue;
+            headers[name] = value;
+        }
+    }
+    const requestedAt = new Date().toISOString();
+    const t0 = Date.now();
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    timeout.unref();
+    if (webhook.insecureTls === true) {
+        process.stderr.write(JSON.stringify({
+            level: "warn",
+            time: requestedAt,
+            msg: "webhook-insecure-tls",
+            webhookId: webhook.id,
+            url: webhook.url,
+            event: payload.event,
+            attempt,
+        }) + "\n");
+    }
+    try {
+        // Node's global fetch routes through undici. We pass the
+        // agent via the `dispatcher` undici-extension field — TS's
+        // standard RequestInit doesn't know about it, hence the cast.
+        // Falls back gracefully on runtimes that ignore the field.
+        const agent = webhook.insecureTls === true ? getInsecureAgent() : SECURE_AGENT;
+        const init = {
+            method: "POST",
+            headers,
+            body,
+            signal: controller.signal,
+            agent,
+        };
+        const res = await fetch(webhook.url, init);
+        const durationMs = Date.now() - t0;
+        const statusCode = res.status;
+        if (statusCode >= 200 && statusCode < 300) {
+            return { status: "delivered", statusCode, durationMs, requestedAt };
+        }
+        if (statusCode >= 400 && statusCode < 500) {
+            const text = await safeReadErrorBody(res);
+            return {
+                status: "failed",
+                statusCode,
+                durationMs,
+                requestedAt,
+                ...(text !== undefined ? { errorPreview: text } : {}),
+            };
+        }
+        // 5xx or other non-2xx — retryable.
+        const text = await safeReadErrorBody(res);
+        return {
+            status: "error",
+            statusCode,
+            durationMs,
+            requestedAt,
+            ...(text !== undefined ? { errorPreview: text } : {}),
+        };
+    }
+    catch (err) {
+        const durationMs = Date.now() - t0;
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            status: "error",
+            durationMs,
+            requestedAt,
+            errorPreview: message.slice(0, ERROR_PREVIEW_LIMIT),
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Read a small slice of the response body for diagnostics.
+ * Bounded so a runaway server returning megabytes doesn't blow
+ * memory. Body bytes themselves are not persisted in
+ * DeliveryRecord — only this preview makes it through.
+ */
+async function safeReadErrorBody(res) {
+    try {
+        const text = await res.text();
+        if (text.length === 0)
+            return undefined;
+        return text.slice(0, ERROR_PREVIEW_LIMIT);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/server/webhooks/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../src/webhooks/dispatcher.ts"],"names":[],"mappings":"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"}

package/dist/server/webhooks/event-bridge.js

@@ -0,0 +1,185 @@
+import { dispatch } from "./dispatcher.js";
+/**
+ * Called from `session-registry.makeSubscribeHandler` for every
+ * AgentSessionEvent that fires on a live session. We filter inside
+ * for the 3 SDK events we care about — the rest are ignored.
+ */
+export function bridgeAgentSessionEvent(meta, event) {
+    // `event` is the SDK's union; some fields are typed loose enough
+    // that we cast through unknown to read them. That matches the
+    // pattern session-registry.ts itself uses for the same union.
+    const e = event;
+    if (e.type === "agent_end") {
+        // session.messages is post-turn; pull the final assistant
+        // message for the payload's primary content. The SDK guarantees
+        // session.errorMessage is the authoritative error field on
+        // agent_end.
+        const messages = meta.session.messages;
+        const lastAssistant = findLastAssistant(messages);
+        const errorMessage = meta.session.errorMessage ??
+            lastAssistant?.errorMessage;
+        void dispatch({
+            event: "agent_end",
+            sessionId: meta.sessionId,
+            projectId: meta.projectId,
+            data: {
+                stopReason: lastAssistant?.stopReason ?? null,
+                errorMessage: errorMessage ?? null,
+                assistantText: lastAssistant?.text ?? null,
+                usage: lastAssistant?.usage ?? null,
+                provider: lastAssistant?.provider ?? null,
+                model: lastAssistant?.model ?? null,
+            },
+        });
+        return;
+    }
+    if (e.type === "auto_retry_end" && e.success === false) {
+        void dispatch({
+            event: "auto_retry_end",
+            sessionId: meta.sessionId,
+            projectId: meta.projectId,
+            data: {
+                attempt: e.attempt ?? null,
+                maxAttempts: e.maxAttempts ?? null,
+                finalError: e.finalError ?? null,
+            },
+        });
+        return;
+    }
+    if (e.type === "compaction_end") {
+        // Only fire on completed compactions (aborted ones aren't
+        // useful for "your context just shrank" integrations).
+        if (e.aborted === true)
+            return;
+        void dispatch({
+            event: "compaction_end",
+            sessionId: meta.sessionId,
+            projectId: meta.projectId,
+            data: {
+                reason: e.reason ?? null,
+                tokensBefore: e.tokensBefore ?? null,
+            },
+        });
+        return;
+    }
+}
+function findLastAssistant(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m?.role !== "assistant")
+            continue;
+        const a = m;
+        const text = extractAssistantText(a.content);
+        const result = {};
+        if (a.stopReason !== undefined)
+            result.stopReason = a.stopReason;
+        if (a.errorMessage !== undefined)
+            result.errorMessage = a.errorMessage;
+        if (text !== undefined)
+            result.text = text;
+        if (a.usage !== undefined)
+            result.usage = a.usage;
+        if (a.provider !== undefined)
+            result.provider = a.provider;
+        if (a.model !== undefined)
+            result.model = a.model;
+        return result;
+    }
+    return undefined;
+}
+function extractAssistantText(content) {
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = [];
+    for (const c of content) {
+        const o = c;
+        if (o.type === "text" && typeof o.text === "string")
+            parts.push(o.text);
+    }
+    if (parts.length === 0)
+        return undefined;
+    return parts.join("\n");
+}
+/**
+ * Called from a subscriber on the ask-user-question registry.
+ * Fires the `ask_user_question` webhook when a NEW request lands;
+ * cancellations aren't a webhook event (no obvious consumer use
+ * case yet).
+ */
+export function bridgeAskUserQuestion(meta, questions, requestId) {
+    void dispatch({
+        event: "ask_user_question",
+        sessionId: meta.sessionId,
+        projectId: meta.projectId,
+        data: {
+            requestId,
+            questions: questions.map((q) => ({
+                header: q.header,
+                question: q.question,
+                multiSelect: q.multiSelect,
+                options: q.options.map((o) => ({
+                    label: o.label,
+                    description: o.description,
+                })),
+            })),
+        },
+    });
+}
+// ---- processes ----
+/**
+ * Called from a subscriber on processManager. Fires the
+ * `process_alert` webhook with the same trigger conditions the
+ * agent-side alert uses (manager filters alertOn* flags before
+ * emitting the manager event).
+ */
+export function bridgeProcessAlert(meta, info, reason) {
+    void dispatch({
+        event: "process_alert",
+        sessionId: meta.sessionId,
+        projectId: meta.projectId,
+        data: {
+            reason,
+            processId: info.id,
+            name: info.name,
+            pid: info.pid,
+            command: info.command,
+            cwd: info.cwd,
+            startTime: info.startTime,
+            endTime: info.endTime,
+            exitCode: info.exitCode,
+            success: info.success,
+        },
+    });
+}
+// ---- session lifecycle ----
+/**
+ * Called from session-registry on session creation. Fires
+ * `session_created` with enough metadata for an audit-log
+ * consumer to record "session X was created in project Y at T."
+ */
+export function bridgeSessionCreated(meta) {
+    void dispatch({
+        event: "session_created",
+        sessionId: meta.sessionId,
+        projectId: meta.projectId,
+        data: {
+            workspacePath: meta.workspacePath,
+        },
+    });
+}
+/**
+ * Called from session-registry on session deletion (cold delete
+ * via the DELETE route). The wasLive flag distinguishes "we
+ * disposed an active session" from "we removed a cold JSONL."
+ */
+export function bridgeSessionDeleted(meta) {
+    void dispatch({
+        event: "session_deleted",
+        sessionId: meta.sessionId,
+        ...(meta.projectId !== undefined ? { projectId: meta.projectId } : {}),
+        data: {
+            wasLive: meta.wasLive,
+        },
+    });
+}
+//# sourceMappingURL=event-bridge.js.map

package/dist/server/webhooks/event-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bridge.js","sourceRoot":"","sources":["../../src/webhooks/event-bridge.ts"],"names":[],"mappings":"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"}

package/dist/server/webhooks/init.js

@@ -0,0 +1,55 @@
+/**
+ * Boot-time hookup of the webhook event-bridge to the forge-native
+ * event sources (ask-user-question registry, processManager). The
+ * AgentSession-side bridge is wired directly inside
+ * `session-registry.makeSubscribeHandler` because that's where the
+ * per-session subscription is created and torn down; this module
+ * handles the singleton-channel sources.
+ *
+ * Mirrors the `initAskUserQuestionFanout` / `initProcessesFanout`
+ * pattern in `sse-bridge.ts`. Called once from `index.ts` at
+ * server boot; the returned unsubscribe is exposed for tests.
+ */
+import { subscribe as subscribeAskQuestions } from "../ask-user-question/registry.js";
+import { processManager } from "../processes/manager.js";
+import { getSession } from "../session-registry.js";
+import { bridgeAskUserQuestion, bridgeProcessAlert } from "./event-bridge.js";
+/**
+ * Wire `ask_user_question` registry events to the webhook dispatcher.
+ * We only fire for fresh requests (not cancellations) since "agent
+ * needs you" is the actionable signal; cancellations are bookkeeping.
+ *
+ * The projectId comes from looking up the live session — the
+ * registry event doesn't carry it directly. If the session is
+ * tombstoned/disposed in the brief window between event emission
+ * and webhook dispatch, we skip rather than fire with a missing
+ * project (per-project webhooks would never match anyway).
+ */
+export function initAskUserQuestionWebhookBridge() {
+    return subscribeAskQuestions((event) => {
+        if (event.type !== "ask_user_question")
+            return;
+        const live = getSession(event.sessionId);
+        if (live === undefined)
+            return;
+        bridgeAskUserQuestion({ sessionId: event.sessionId, projectId: live.projectId }, event.questions, event.requestId);
+    });
+}
+/**
+ * Wire `processManager` events to the webhook dispatcher. Only
+ * the `process_alert` variant gets forwarded — that's the curated
+ * "completion with intent to notify" signal the manager already
+ * filters on the alertOn* flags. The chatty per-line output and
+ * watch-match events stay in the SSE fanout where they belong.
+ */
+export function initProcessesWebhookBridge() {
+    return processManager.subscribe((event) => {
+        if (event.type !== "process_alert")
+            return;
+        const live = getSession(event.sessionId);
+        if (live === undefined)
+            return;
+        bridgeProcessAlert({ sessionId: event.sessionId, projectId: live.projectId }, event.info, event.reason);
+    });
+}
+//# sourceMappingURL=init.js.map

package/dist/server/webhooks/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/webhooks/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,SAAS,IAAI,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gCAAgC;IAC9C,OAAO,qBAAqB,CAAC,CAAC,KAAK,EAAE,EAAE;QACrC,IAAI,KAAK,CAAC,IAAI,KAAK,mBAAmB;YAAE,OAAO;QAC/C,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO;QAC/B,qBAAqB,CACnB,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,EACzD,KAAK,CAAC,SAAS,EACf,KAAK,CAAC,SAAS,CAChB,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO,cAAc,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QACxC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe;YAAE,OAAO;QAC3C,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO;QAC/B,kBAAkB,CAChB,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,EACzD,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,MAAM,CACb,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}