loopengine 0.1.66 → 0.1.68

package/dist/core/http-notify-triggers/webhook.js

@@ -39,56 +39,109 @@
 // pending-approval/pending-question one hitting the same URL (see
 // examples/notifier-handler/webhook.ts's own `verifyWebhookNotifier` for
 // the receiving side of all three).
+// Delivery is retried (RETRY_DELAYS_MS, a non-2xx answer counts as a
+// failure), every attempt is recorded for the console's delivery log
+// (core/notifier-deliveries.ts), and each payload carries where to send
+// the decision back (`resolvePath`/`answerPath`, plus a full
+// `resolveUrl`/`answerUrl` when LOOPENGINE_PUBLIC_URL says where this
+// server is reachable) — all additive fields, so existing receivers keep
+// working unchanged.
 import { createHmac, randomUUID } from 'node:crypto';
+import { recordDelivery } from '../notifier-deliveries.js';
+import { decidePath } from '../approval-links.js';
+/** Waits before each retry after the first attempt — four tries in all,
+ * spread over about 40 seconds. */
+const RETRY_DELAYS_MS = [2_000, 10_000, 30_000];
+function sign(body, secret) {
+    return `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`;
+}
+/** Where this server is reachable: LOOPENGINE_PUBLIC_URL (e.g.
+ * https://acme.loopengine.app) when set, read per call so a change takes
+ * effect without a restart, else `fallback` (a notifier.yml's own
+ * publicUrl, remembered from the console). undefined when neither is
+ * known, in which case payloads carry only relative paths. */
+export function publicBaseUrl(fallback) {
+    const base = process.env.LOOPENGINE_PUBLIC_URL || fallback;
+    return base ? base.replace(/\/+$/, '') : undefined;
+}
+function absolute(base, path) {
+    return base ? base + path : undefined;
+}
+async function attemptOnce(url, body, headers) {
+    try {
+        const res = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body });
+        return res.ok ? { ok: true, status: res.status } : { ok: false, status: res.status, error: `HTTP ${res.status}` };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Sends one signed POST, retrying on a network error or non-2xx answer,
+ * and records every attempt. Resolves with the last attempt's result —
+ * callers that must return right away (a pending decision is already
+ * recorded either way) don't await it. */
+async function deliver(url, body, headers, meta, retryDelaysMs) {
+    let result = { ok: false };
+    for (let attempt = 1; attempt <= retryDelaysMs.length + 1; attempt++) {
+        if (attempt > 1)
+            await new Promise((resolve) => setTimeout(resolve, retryDelaysMs[attempt - 2]));
+        result = await attemptOnce(url, body, headers);
+        recordDelivery({ at: new Date().toISOString(), url, attempt, ...meta, ...result });
+        if (result.ok)
+            return result;
+    }
+    console.error(`[loopengine] webhook delivery to ${url} failed after ${retryDelaysMs.length + 1} attempts (${meta.kind}${meta.pendingId ? ` ${meta.pendingId}` : ''}): ${result.error}`);
+    return result;
+}
 export class WebhookNotifier {
     webhookUrl;
     signingSecret;
+    retryDelaysMs;
+    publicUrl;
     constructor(options) {
         this.webhookUrl = options.webhookUrl;
         this.signingSecret = options.signingSecret;
+        this.retryDelaysMs = options.retryDelaysMs ?? RETRY_DELAYS_MS;
+        this.publicUrl = options.publicUrl;
     }
     requestDurableApproval(tool, args, scope, reason) {
         const pendingId = randomUUID();
         const requestedAt = new Date().toISOString();
-        const body = JSON.stringify({ pendingId, tool, args, scope, reason, requestedAt });
-        this.post(body, 'X-Actauth-Signature', pendingId);
+        const resolvePath = `/pending-approvals/${pendingId}/resolve`;
+        const decide = decidePath(pendingId, 'approval');
+        const base = publicBaseUrl(this.publicUrl);
+        const body = JSON.stringify({
+            pendingId, tool, args, scope, reason, requestedAt,
+            kind: 'approval', agent: scope.agent, resolvePath, resolveUrl: absolute(base, resolvePath),
+            // A signed link a person can open to decide, no login needed.
+            decidePath: decide, decideUrl: absolute(base, decide),
+        });
+        void deliver(this.webhookUrl, body, { 'X-Actauth-Signature': sign(body, this.signingSecret) }, { agent: scope.agent, kind: 'approval', pendingId }, this.retryDelaysMs);
         return { pendingId };
     }
     notifyPendingQuestion(question, options, agent, sessionId) {
         const pendingId = randomUUID();
         const requestedAt = new Date().toISOString();
-        const body = JSON.stringify({ pendingId, question, options, agent, sessionId, requestedAt });
-        this.post(body, 'X-Askuser-Signature', pendingId);
-        return { pendingId };
-    }
-    /** Shared by both methods above — the one place either used to
-     * independently build the same signed fetch() call. Not awaited by its
-     * own callers, same fire-and-forget contract each had on its own: both
-     * requestDurableApproval/notifyPendingQuestion return immediately, by
-     * contract (see DurableApprover/DurableQuestionHandler's own doc
-     * comments), so a delivery failure here has no synchronous way to
-     * surface to the caller — logged instead of thrown, since throwing
-     * would blow up a decision that has already, correctly, been recorded
-     * as pending. */
-    post(body, signatureHeader, pendingId) {
-        const signature = `sha256=${createHmac('sha256', this.signingSecret).update(body).digest('hex')}`;
-        fetch(this.webhookUrl, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json', [signatureHeader]: signature },
-            body,
-        }).catch((err) => {
-            console.error(`[loopengine] WebhookNotifier: webhook delivery failed for pendingId '${pendingId}':`, err);
+        const answerPath = `/pending-questions/${pendingId}/answer`;
+        const decide = decidePath(pendingId, 'question');
+        const base = publicBaseUrl(this.publicUrl);
+        const body = JSON.stringify({
+            pendingId, question, options, agent, sessionId, requestedAt,
+            kind: 'question', answerPath, answerUrl: absolute(base, answerPath),
+            decidePath: decide, decideUrl: absolute(base, decide),
         });
+        void deliver(this.webhookUrl, body, { 'X-Askuser-Signature': sign(body, this.signingSecret) }, { agent, kind: 'question', pendingId }, this.retryDelaysMs);
+        return { pendingId };
     }
 }
 export function postLifecycleWebhook(webhookUrl, webhookSecret, event, context) {
     const payload = JSON.stringify({ event, ...context, occurredAt: new Date().toISOString() });
-    const signature = `sha256=${createHmac('sha256', webhookSecret).update(payload).digest('hex')}`;
-    fetch(webhookUrl, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', 'X-Lifecycle-Signature': signature },
-        body: payload,
-    }).catch((err) => {
-        console.error(`[loopengine] httpNotifier ${event} webhook delivery failed:`, err);
-    });
+    void deliver(webhookUrl, payload, { 'X-Lifecycle-Signature': sign(payload, webhookSecret) }, { agent: String(context.agent ?? ''), kind: event }, RETRY_DELAYS_MS);
+}
+/** One signed `{event: "test"}` POST (lifecycle signature header), no
+ * retries, awaited — backs the console's "Send test" button so an
+ * operator sees right away whether the receiver accepts it. */
+export function sendTestWebhook(webhookUrl, webhookSecret, agent) {
+    const payload = JSON.stringify({ event: 'test', agent, occurredAt: new Date().toISOString() });
+    return deliver(webhookUrl, payload, { 'X-Lifecycle-Signature': sign(payload, webhookSecret) }, { agent, kind: 'test' }, []);
 }

package/dist/core/notifier-deliveries.d.ts

@@ -0,0 +1,18 @@
+export type NotifierDeliveryKind = 'approval' | 'question' | 'run_start' | 'run_finish' | 'test';
+export interface NotifierDelivery {
+    at: string;
+    agent: string;
+    kind: NotifierDeliveryKind;
+    url: string;
+    pendingId?: string;
+    /** 1 for the first try, 2+ for retries. */
+    attempt: number;
+    ok: boolean;
+    /** The receiver's HTTP status, when it answered at all. */
+    status?: number;
+    error?: string;
+}
+export declare function recordDelivery(delivery: NotifierDelivery): void;
+/** Newest first. */
+export declare function listDeliveries(agent: string): NotifierDelivery[];
+export declare function clearDeliveries(): void;

package/dist/core/notifier-deliveries.js

@@ -0,0 +1,22 @@
+// A short, in-memory record of recent webhook deliveries per agent — what
+// the console's Approvals section shows so an operator can see whether a
+// notification actually reached the app on the other end (and why not).
+// Deliberately not persisted: it's a debugging aid that resets with the
+// process, not an audit log; the pending decision itself is what's
+// durable (core/durable-approvals.ts).
+const MAX_PER_AGENT = 50;
+const byAgent = new Map();
+export function recordDelivery(delivery) {
+    const list = byAgent.get(delivery.agent) ?? [];
+    list.unshift(delivery);
+    if (list.length > MAX_PER_AGENT)
+        list.length = MAX_PER_AGENT;
+    byAgent.set(delivery.agent, list);
+}
+/** Newest first. */
+export function listDeliveries(agent) {
+    return [...(byAgent.get(agent) ?? [])];
+}
+export function clearDeliveries() {
+    byAgent.clear();
+}

package/dist/core/notifier-file.d.ts

@@ -0,0 +1,35 @@
+import type { AgentEnv, HttpNotifierConfig, HttpNotifierEvent } from '#core/agent-config.js';
+export type NotifierFileChannel = 'webhook' | 'slack' | 'lark';
+export interface NotifierFile {
+    channel: NotifierFileChannel;
+    events: HttpNotifierEvent[];
+    /** webhook: where to POST. */
+    url?: string;
+    /** slack: channel to post into. */
+    channelId?: string;
+    /** lark: app id and chat to post into. */
+    appId?: string;
+    chatId?: string;
+    /** Where this server is reachable, for the links in each message —
+     * remembered from the console's own address when saving.
+     * LOOPENGINE_PUBLIC_URL, when set, wins over it. */
+    publicUrl?: string;
+}
+/** The env var each channel's secret is read from, per agent. */
+export declare const NOTIFIER_SECRET_VARS: Record<NotifierFileChannel, string>;
+export declare class NotifierFileError extends Error {
+}
+export declare function notifierFilePath(dir: string): string;
+/** Throws NotifierFileError naming the first problem. */
+export declare function validateNotifierFile(input: unknown): NotifierFile;
+/** undefined when the agent has no notifier.yml. */
+export declare function readNotifierFile(dir: string): NotifierFile | undefined;
+export declare function writeNotifierFile(dir: string, input: unknown): NotifierFile;
+export declare function removeNotifierFile(dir: string): void;
+/** The HttpNotifierConfig a notifier.yml describes, with its secret read
+ * from `env` — or which secret is missing, so nothing is sent unsigned
+ * or unauthenticated. */
+export declare function notifierConfigFromFile(file: NotifierFile, env: AgentEnv): {
+    config?: HttpNotifierConfig;
+    missingSecret?: string;
+};

package/dist/core/notifier-file.js

@@ -0,0 +1,104 @@
+// agents/<name>/notifier.yml — where an agent's "ask" approvals and
+// questions go when nobody is watching a live chat, set from the console
+// (Permissions → "Where approval requests and questions are sent") instead of in code. Only consulted when the
+// agent's own AgentConfig.httpNotifier is unset; code always wins.
+//
+// The file holds only non-secret settings. The one secret each channel
+// needs (a webhook signing secret, a Slack bot token, a Lark app secret)
+// lives in the agent's own env (agents/<name>/.env by default, through
+// core/secret-store.ts) under a fixed name, so it's never written into a
+// file that might get committed.
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+/** The env var each channel's secret is read from, per agent. */
+export const NOTIFIER_SECRET_VARS = {
+    webhook: 'LOOPENGINE_NOTIFIER_WEBHOOK_SECRET',
+    slack: 'LOOPENGINE_NOTIFIER_SLACK_BOT_TOKEN',
+    lark: 'LOOPENGINE_NOTIFIER_LARK_APP_SECRET',
+};
+const CHANNELS = ['webhook', 'slack', 'lark'];
+const EVENTS = ['approval', 'question', 'run_start', 'run_finish'];
+export class NotifierFileError extends Error {
+}
+export function notifierFilePath(dir) {
+    return join(dir, 'notifier.yml');
+}
+/** Throws NotifierFileError naming the first problem. */
+export function validateNotifierFile(input) {
+    if (!input || typeof input !== 'object')
+        throw new NotifierFileError('notifier settings must be an object');
+    const raw = input;
+    const channel = raw.channel;
+    if (!CHANNELS.includes(channel))
+        throw new NotifierFileError(`channel must be one of: ${CHANNELS.join(', ')}`);
+    const events = Array.isArray(raw.events) ? raw.events : [];
+    if (!events.length || events.some((e) => !EVENTS.includes(e))) {
+        throw new NotifierFileError(`events must be a non-empty list of: ${EVENTS.join(', ')}`);
+    }
+    const str = (key) => (typeof raw[key] === 'string' && raw[key].trim() ? raw[key].trim() : undefined);
+    const file = { channel, events: events };
+    const publicUrl = str('publicUrl');
+    if (publicUrl) {
+        if (!/^https?:\/\/[^/]+/.test(publicUrl))
+            throw new NotifierFileError('publicUrl must be an http(s) URL');
+        file.publicUrl = publicUrl.replace(/\/+$/, '');
+    }
+    if (channel === 'webhook') {
+        const url = str('url');
+        if (!url || !/^https?:\/\//.test(url))
+            throw new NotifierFileError('url must be an http(s) URL');
+        file.url = url;
+    }
+    else if (channel === 'slack') {
+        const channelId = str('channelId');
+        if (!channelId)
+            throw new NotifierFileError('channelId is required for slack');
+        file.channelId = channelId;
+    }
+    else {
+        const appId = str('appId');
+        const chatId = str('chatId');
+        if (!appId || !chatId)
+            throw new NotifierFileError('appId and chatId are required for lark');
+        file.appId = appId;
+        file.chatId = chatId;
+    }
+    return file;
+}
+/** undefined when the agent has no notifier.yml. */
+export function readNotifierFile(dir) {
+    const path = notifierFilePath(dir);
+    if (!existsSync(path))
+        return undefined;
+    return validateNotifierFile(parseYaml(readFileSync(path, 'utf8')));
+}
+export function writeNotifierFile(dir, input) {
+    const file = validateNotifierFile(input);
+    const header = '# Where this agent sends approval requests and questions when it is called over HTTP.\n' +
+        `# Edited from the console (Permissions tab). The secret lives in this agent's env as ${NOTIFIER_SECRET_VARS[file.channel]}.\n`;
+    writeFileSync(notifierFilePath(dir), header + stringifyYaml(file));
+    return file;
+}
+export function removeNotifierFile(dir) {
+    rmSync(notifierFilePath(dir), { force: true });
+}
+/** The HttpNotifierConfig a notifier.yml describes, with its secret read
+ * from `env` — or which secret is missing, so nothing is sent unsigned
+ * or unauthenticated. */
+export function notifierConfigFromFile(file, env) {
+    const secretVar = NOTIFIER_SECRET_VARS[file.channel];
+    const secret = env.get(secretVar);
+    if (!secret)
+        return { missingSecret: secretVar };
+    switch (file.channel) {
+        case 'webhook':
+            return { config: { channel: 'webhook', config: { webhookUrl: file.url, webhookSecret: secret, publicUrl: file.publicUrl }, events: file.events } };
+        case 'slack':
+            // No interactive buttons: a console-configured Slack notifier has
+            // no interactivity endpoint behind it; the decision link replaces them.
+            return { config: { channel: 'slack', config: { botToken: secret, channelId: file.channelId, publicUrl: file.publicUrl, buttons: false }, events: file.events } };
+        case 'lark':
+            return { config: { channel: 'lark', config: { appId: file.appId, appSecret: secret, chatId: file.chatId }, events: file.events } };
+    }
+}

package/dist/index.d.ts

@@ -7,6 +7,13 @@ export { createAgentEnv, agentDirFor, envScopeOf, type EnvScope } from '#core/ag
 export { FileSecretStore, setSecretStore, getSecretStore, type SecretStore } from '#core/secret-store.js';
 export { signProxyIdentity, verifyProxyIdentity, TRUSTED_PROXY_IDENTITY_HEADER, type ProxyIdentity } from '#core/trusted-proxy.js';
 export { setUsageSink, recordUsage, type UsageEvent, type UsageSink } from '#core/usage.js';
+export { readNotifierFile, writeNotifierFile, removeNotifierFile, validateNotifierFile, notifierConfigFromFile, NotifierFileError, NOTIFIER_SECRET_VARS, type NotifierFile } from '#core/notifier-file.js';
+export { listDeliveries, recordDelivery, type NotifierDelivery } from '#core/notifier-deliveries.js';
+export { describeNotifier } from '#core/http-notifier.js';
+export { createDecisionToken, verifyDecisionToken, decidePath, decideLinkMaker, decisionLinkTtlMs, type DecisionKind } from '#core/approval-links.js';
+export { renderDecidePage, renderDecideGonePage, renderDecideInvalidPage, type DecidePageItem } from './web/decide-page.js';
+export { sendTestWebhook } from '#core/http-notify-triggers/webhook.js';
+export { describeAgentNotifier, saveAgentNotifier, removeAgentNotifier, testAgentNotifier, listAgentPending, type DefaultWebhook } from './web/notifier-admin.js';
 export type * from './core/loop-events.js';
 export { streamMessage, streamMessageWithCallbacks, sendMessage, approveCall, denyCall, answerQuestion, getSessionHistory, } from './core/client.js';
 export type { RequestOptions, SendMessageResult, PendingApprovalResult, PendingQuestionResult, PendingResult, MessageResult, StreamMessageCallbacks, } from './core/client.js';

package/dist/index.js

@@ -9,6 +9,13 @@ export { createAgentEnv, agentDirFor, envScopeOf } from '#core/agent-env.js';
 export { FileSecretStore, setSecretStore, getSecretStore } from '#core/secret-store.js';
 export { signProxyIdentity, verifyProxyIdentity, TRUSTED_PROXY_IDENTITY_HEADER } from '#core/trusted-proxy.js';
 export { setUsageSink, recordUsage } from '#core/usage.js';
+export { readNotifierFile, writeNotifierFile, removeNotifierFile, validateNotifierFile, notifierConfigFromFile, NotifierFileError, NOTIFIER_SECRET_VARS } from '#core/notifier-file.js';
+export { listDeliveries, recordDelivery } from '#core/notifier-deliveries.js';
+export { describeNotifier } from '#core/http-notifier.js';
+export { createDecisionToken, verifyDecisionToken, decidePath, decideLinkMaker, decisionLinkTtlMs } from '#core/approval-links.js';
+export { renderDecidePage, renderDecideGonePage, renderDecideInvalidPage } from './web/decide-page.js';
+export { sendTestWebhook } from '#core/http-notify-triggers/webhook.js';
+export { describeAgentNotifier, saveAgentNotifier, removeAgentNotifier, testAgentNotifier, listAgentPending } from './web/notifier-admin.js';
 // The framework-agnostic browser client for adapters/http.ts's own wire
 // protocol (see client.ts's own header comment) — this, not a deep
 // subpath import, is how a consumer's React/Vue/etc. chat UI is meant to