eve-lark 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -64,6 +64,44 @@ interface LarkChannelOptions {
      * Defaults to `$PORT` or `2000` (matches `eve dev`).
      */
     port?: number | undefined;
+    /**
+     * Allowlist of sender open_ids for DM (p2p) messages. When set, DMs from
+     * senders not in this list are dropped before reaching the agent. Has no
+     * effect on group messages (use `groupAllowFrom` for those). Default:
+     * unset → all DMs allowed.
+     */
+    allowFrom?: readonly string[] | undefined;
+    /**
+     * Allowlist of chat_ids for group messages. When set, messages from
+     * chats not in this list are dropped. Default: unset → all groups allowed.
+     */
+    groupAllowFrom?: readonly string[] | undefined;
+    /**
+     * Per-group configuration. Matched by chat_id on inbound group messages.
+     * Currently only `systemPrompt` is read; it's injected as `context` in
+     * the `send()` call so the agent treats it as an additional user-role
+     * instruction at the start of the turn. DMs ignore this.
+     */
+    groupConfigs?: readonly LarkGroupConfig[] | undefined;
+    /**
+     * ASR provider for audio/media transcription. When set, audio/media
+     * messages are downloaded, transcribed, and the transcript is forwarded
+     * to the agent as text. When unset (default), audio/media messages are
+     * ack-and-skipped.
+     */
+    asrProvider?: LarkAsrProvider | undefined;
+}
+interface LarkGroupConfig {
+    chatId: string;
+    systemPrompt?: string | undefined;
+}
+/**
+ * Pluggable ASR (Automatic Speech Recognition) provider. When configured,
+ * inbound audio/media messages are downloaded, transcribed, and the transcript
+ * replaces the empty text — the agent receives it as a normal text message.
+ */
+interface LarkAsrProvider {
+    transcribe(audioBytes: Buffer, mediaType: string): Promise<string>;
 }
 interface ResolvedLarkOptions {
     appId: string;
@@ -86,6 +124,10 @@ interface ResolvedLarkOptions {
     ackReaction: string | readonly string[] | false;
     mode: LarkTransportMode;
     port: number;
+    allowFrom: readonly string[] | undefined;
+    groupAllowFrom: readonly string[] | undefined;
+    groupConfigs: readonly LarkGroupConfig[] | undefined;
+    asrProvider: LarkAsrProvider | undefined;
 }
 type LarkSenderType = "user" | "app";
 type LarkChatType = "p2p" | "group";
@@ -197,9 +239,34 @@ type LarkCardElement = {
     }>;
 } | {
     tag: "action";
-    actions: LarkCardButton[];
+    actions: LarkCardActionItem[];
     layout?: "bisected" | "trisection" | "flow";
 };
+/** Union of action-row item shapes: buttons (yes/no confirm style) and
+ *  select menus (dropdowns for longer option lists). */
+type LarkCardActionItem = LarkCardButton | LarkCardSelectMenu;
+interface LarkCardSelectMenu {
+    tag: "select_static";
+    placeholder?: {
+        tag: "plain_text";
+        content: string;
+    };
+    /** Initially-selected option id (string). */
+    initial_option?: string;
+    /** Selectable options. `value` carries the optionId we get back in
+     *  `action.option` when the user picks one. */
+    options: Array<{
+        text: {
+            tag: "plain_text";
+            content: string;
+        };
+        value: string;
+    }>;
+    /** Same marker payload as a button so the dispatcher can recognise our
+     *  own callbacks. `optionId` is NOT set here — it comes back via
+     *  `action.option` instead. */
+    value?: Record<string, unknown>;
+}
 interface LarkCardButton {
     tag: "button";
     text: {
@@ -207,6 +274,8 @@ interface LarkCardButton {
         content: string;
     };
     type?: "default" | "primary" | "danger";
+    /** Opens this URL when clicked (instead of triggering card.action.trigger). */
+    url?: string;
     /** Arbitrary JSON returned in the card.action.trigger callback's
      *  `action.value`. eve-lark sets `{ __eveLarkAsk, requestId, optionId }`. */
     value?: Record<string, unknown>;

package/dist/index.js

@@ -535,6 +535,57 @@ var BASE_CONFIG = {
   wide_screen_mode: true,
   update_multi: true
 };
+function buildAuthCard(opts) {
+  const elements = [
+    { tag: "div", text: { tag: "lark_md", content: `Sign in to **${escapeMarkdown(opts.displayName)}** to continue.` } },
+    {
+      tag: "action",
+      actions: [
+        {
+          tag: "button",
+          text: { tag: "plain_text", content: `Sign in with ${opts.displayName}` },
+          type: "primary",
+          url: opts.url
+        }
+      ]
+    }
+  ];
+  if (opts.userCode) {
+    elements.push({
+      tag: "div",
+      text: { tag: "lark_md", content: `Verification code: \`${escapeMarkdown(opts.userCode)}\`` }
+    });
+  }
+  return { config: { ...BASE_CONFIG }, elements };
+}
+__name(buildAuthCard, "buildAuthCard");
+function buildAuthCompletedCard(opts) {
+  const outcomeLabel = {
+    authorized: "\u2713",
+    declined: "\u2717",
+    failed: "\u26A0",
+    "timed-out": "\u23F1"
+  };
+  const glyph = outcomeLabel[opts.outcome] ?? "\u2022";
+  const outcomeText = {
+    authorized: "connected",
+    declined: "declined",
+    failed: "failed",
+    "timed-out": "timed out"
+  };
+  const label = outcomeText[opts.outcome] ?? opts.outcome;
+  const suffix = opts.reason ? ` \u2014 ${escapeMarkdown(opts.reason)}` : "";
+  return {
+    config: { ...BASE_CONFIG },
+    elements: [
+      {
+        tag: "div",
+        text: { tag: "lark_md", content: `**${escapeMarkdown(opts.displayName)}**: ${glyph} ${label}${suffix}` }
+      }
+    ]
+  };
+}
+__name(buildAuthCompletedCard, "buildAuthCompletedCard");
 function buildTextCard(text) {
   return {
     config: { ...BASE_CONFIG },
@@ -564,26 +615,56 @@ function buildErrorCard(message) {
 }
 __name(buildErrorCard, "buildErrorCard");
 var ASK_BUTTON_VALUE_MARKER = "__eveLarkAsk";
+var ASK_OPTIONS_BUTTON_MAX = 3;
 function buildAskCard(request) {
   const elements = [
     { tag: "div", text: { tag: "lark_md", content: request.prompt } }
   ];
-  if (request.options && request.options.length > 0) {
-    const buttons = request.options.map((opt) => ({
-      tag: "button",
-      text: { tag: "plain_text", content: opt.label },
-      type: opt.style ?? "default",
-      value: {
-        [ASK_BUTTON_VALUE_MARKER]: true,
-        requestId: request.requestId,
-        optionId: opt.id
-      },
-      ...opt.description ? { confirm: { title: { tag: "plain_text", content: opt.label }, text: { tag: "plain_text", content: opt.description } } } : {}
-    }));
-    elements.push({ tag: "action", actions: buttons });
+  const optionCount = request.options?.length ?? 0;
+  if (optionCount > 0) {
+    const useSelect = request.display === "select" || optionCount > ASK_OPTIONS_BUTTON_MAX;
+    if (useSelect) {
+      elements.push({
+        tag: "action",
+        actions: [
+          {
+            tag: "select_static",
+            placeholder: { tag: "plain_text", content: "Select an option\u2026" },
+            options: request.options.map((opt) => ({
+              text: { tag: "plain_text", content: opt.label },
+              value: opt.id
+            })),
+            // Marker carries requestId; optionId is returned via action.option.
+            value: {
+              [ASK_BUTTON_VALUE_MARKER]: true,
+              requestId: request.requestId,
+              __larkSelect: true
+            }
+          }
+        ]
+      });
+    } else {
+      const buttons = request.options.map((opt) => ({
+        tag: "button",
+        text: { tag: "plain_text", content: opt.label },
+        type: opt.style ?? "default",
+        value: {
+          [ASK_BUTTON_VALUE_MARKER]: true,
+          requestId: request.requestId,
+          optionId: opt.id
+        },
+        ...opt.description ? {
+          confirm: {
+            title: { tag: "plain_text", content: opt.label },
+            text: { tag: "plain_text", content: opt.description }
+          }
+        } : {}
+      }));
+      elements.push({ tag: "action", actions: buttons });
+    }
   }
   if (request.allowFreeform) {
-    const hint = request.options && request.options.length > 0 ? "_\u2026or reply to this chat with your own answer_" : "_Reply to this chat with your answer_";
+    const hint = optionCount > 0 ? "_\u2026or reply to this chat with your own answer_" : "_Reply to this chat with your answer_";
     elements.push({ tag: "div", text: { tag: "lark_md", content: hint } });
   }
   return { config: { ...BASE_CONFIG }, elements };
@@ -879,7 +960,11 @@ function resolveOptions(options, env = defaultEnv()) {
     fetch: options.fetch ?? globalThis.fetch,
     ackReaction: options.ackReaction ?? DEFAULTS.ackReaction,
     mode,
-    port: options.port ?? (process.env.PORT ? Number(process.env.PORT) : 2e3)
+    port: options.port ?? (process.env.PORT ? Number(process.env.PORT) : 2e3),
+    allowFrom: options.allowFrom,
+    groupAllowFrom: options.groupAllowFrom,
+    groupConfigs: options.groupConfigs,
+    asrProvider: options.asrProvider
   };
 }
 __name(resolveOptions, "resolveOptions");
@@ -1327,6 +1412,30 @@ function buildUserContent(text, files, options, messageId) {
   return parts;
 }
 __name(buildUserContent, "buildUserContent");
+async function runDiagnostics(client, opts, chatId) {
+  const lines = ["**eve-lark diagnostics**", ""];
+  lines.push(`appId: \`${opts.appId}\``);
+  lines.push(`baseUrl: \`${opts.baseUrl}\``);
+  lines.push(`mode: \`${opts.mode}\``);
+  lines.push(`replyMode: \`${opts.replyMode}\``);
+  lines.push(`encryptKey: ${opts.encryptKey ? "\u2713 set" : "\u2717 not set"}`);
+  lines.push(`ackReaction: \`${opts.ackReaction === false ? "disabled" : opts.ackReaction}\``);
+  lines.push("");
+  lines.push("**Token fetch:**");
+  try {
+    const token = await client.getTenantAccessToken();
+    lines.push(`\u2713 tenant_access_token: ${token.slice(0, 8)}\u2026`);
+  } catch (e) {
+    lines.push(`\u2717 failed: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  const report = lines.join("\n");
+  try {
+    await client.sendPost({ chatId, content: report });
+  } catch (e) {
+    console.error("[eve-lark] diagnostic report delivery failed:", e);
+  }
+}
+__name(runDiagnostics, "runDiagnostics");
 function formatErrorHint(data) {
   if (typeof data !== "object" || data === null) return "";
   const d = data;
@@ -1376,6 +1485,7 @@ function createLarkChannel(optionsInput) {
   const sessionMeta = /* @__PURE__ */ new Map();
   const pendingInputsByRequestId = /* @__PURE__ */ new Map();
   const pendingInputsByChatToken = /* @__PURE__ */ new Map();
+  const authCards = /* @__PURE__ */ new Map();
   function getController(sessionId, meta) {
     let ctrl = controllers.get(sessionId);
     if (!ctrl) {
@@ -1605,9 +1715,55 @@ function createLarkChannel(optionsInput) {
     if (parsed.senderType === "app") {
       return ackOk();
     }
+    if (parsed.chatType === "p2p" && options.allowFrom) {
+      if (!options.allowFrom.includes(parsed.senderOpenId)) {
+        console.log(
+          `[eve-lark] dropping DM from non-allowlisted sender ${parsed.senderOpenId}`
+        );
+        return ackOk();
+      }
+    }
+    if (parsed.chatType === "group" && options.groupAllowFrom) {
+      if (!options.groupAllowFrom.includes(parsed.chatId)) {
+        console.log(
+          `[eve-lark] dropping group message from non-allowlisted chat ${parsed.chatId}`
+        );
+        return ackOk();
+      }
+    }
+    if (options.asrProvider && parsed.text === "" && parsed.files.length === 0) {
+      const rawEvent = body.event;
+      const msgType = rawEvent.message?.message_type;
+      if (msgType === "audio" || msgType === "media") {
+        try {
+          const content = JSON.parse(rawEvent.message.content);
+          if (content.file_key) {
+            const bytes = await client.downloadResource({
+              messageId: parsed.messageId,
+              fileKey: content.file_key,
+              type: "file"
+            });
+            const mediaType = msgType === "audio" ? "audio/mpeg" : "video/mp4";
+            const transcript = await options.asrProvider.transcribe(bytes, mediaType);
+            if (transcript) {
+              parsed.text = transcript;
+            }
+          }
+        } catch (e) {
+          console.warn(
+            "[eve-lark] audio transcription failed, skipping message:",
+            e instanceof Error ? e.message : e
+          );
+        }
+      }
+    }
     if (parsed.text === "" && parsed.files.length === 0) {
       return ackOk();
     }
+    if (parsed.text.trim().toLowerCase() === "/lark-diagnose") {
+      helpers.waitUntil(runDiagnostics(client, options, parsed.chatId));
+      return ackOk();
+    }
     const tokenKey = chatTokenKey(parsed.chatId, parsed.rootId ?? void 0, parsed.parentId ?? void 0);
     const pending = pendingInputsByChatToken.get(tokenKey);
     if (pending && pending.awaitingFreeform && parsed.text.length > 0) {
@@ -1659,10 +1815,15 @@ function createLarkChannel(optionsInput) {
         chatType: parsed.chatType
       }
     };
-    const session = await helpers.send(userContent, {
+    const groupConfig = parsed.chatType === "group" ? options.groupConfigs?.find((g) => g.chatId === parsed.chatId) : void 0;
+    const sendPayload = {
       auth,
       continuationToken
-    });
+    };
+    if (groupConfig?.systemPrompt) {
+      sendPayload.context = [groupConfig.systemPrompt];
+    }
+    const session = await helpers.send(userContent, sendPayload);
     sessionMeta.set(session.id, {
       chatId: parsed.chatId,
       rootId: parsed.rootId ?? void 0,
@@ -1693,50 +1854,69 @@ function createLarkChannel(optionsInput) {
       return ackOk();
     }
     const requestId = typeof value.requestId === "string" ? value.requestId : "";
-    const optionId = typeof value.optionId === "string" ? value.optionId : "";
+    const optionId = (typeof value.optionId === "string" ? value.optionId : "") || (typeof evt.action?.option === "string" ? evt.action.option : "");
     if (!requestId) return ackOk();
     const pending = pendingInputsByRequestId.get(requestId);
     if (!pending) {
-      console.warn(`[eve-lark] card action for unknown requestId=${requestId} (already answered or expired)`);
-      return ackOk();
-    }
-    const resp = { requestId, optionId: optionId || void 0 };
-    const resumeToken = larkContinuationToken(pending.chatId, pending.parentId ?? pending.rootId ?? null);
-    const resumeAuth = {
-      authenticator: "lark",
-      principalType: "user",
-      principalId: evt.open_id,
-      attributes: {
-        chatId: pending.chatId,
-        rootMessageId: pending.rootId,
-        messageId: evt.open_message_id,
-        chatType: pending.request.display === "confirmation" ? "p2p" : "group"
-      }
-    };
-    try {
-      await helpers.send(
-        { inputResponses: [resp] },
-        { auth: resumeAuth, continuationToken: resumeToken }
-      );
-      console.log(`[eve-lark] ask answered via button click requestId=${requestId} optionId=${optionId}`);
-    } catch (e) {
-      console.error(
-        `[eve-lark] ask input-response send failed (requestId=${requestId}):`,
-        e instanceof Error ? e.message : e
+      console.warn(
+        `[eve-lark] card action for unknown requestId=${requestId} (already answered or expired)`
       );
+      return ackOk();
     }
     const selectedOpt = pending.request.options?.find((o) => o.id === optionId);
-    if (pending.cardMessageId && selectedOpt) {
-      try {
-        await client.patchCard({
-          messageId: pending.cardMessageId,
-          card: buildAskAnsweredCard(pending.request, { kind: "option", label: selectedOpt.label })
-        });
-      } catch (e) {
-        console.warn("[eve-lark] patchCard after ask-answer failed:", e instanceof Error ? e.message : e);
-      }
-    }
-    dropPendingInput(pending);
+    helpers.waitUntil(
+      (async () => {
+        if (pending.cardMessageId && selectedOpt) {
+          try {
+            await client.patchCard({
+              messageId: pending.cardMessageId,
+              card: buildAskAnsweredCard(pending.request, {
+                kind: "option",
+                label: selectedOpt.label
+              })
+            });
+          } catch (e) {
+            console.warn(
+              "[eve-lark] patchCard after ask-answer failed:",
+              e instanceof Error ? e.message : e
+            );
+          }
+        }
+        const resp = { requestId, optionId: optionId || void 0 };
+        const resumeToken = larkContinuationToken(
+          pending.chatId,
+          pending.parentId ?? pending.rootId ?? null
+        );
+        const resumeAuth = {
+          authenticator: "lark",
+          principalType: "user",
+          principalId: evt.open_id,
+          attributes: {
+            chatId: pending.chatId,
+            rootMessageId: pending.rootId,
+            messageId: evt.open_message_id,
+            chatType: pending.request.display === "confirmation" ? "p2p" : "group"
+          }
+        };
+        try {
+          await helpers.send(
+            { inputResponses: [resp] },
+            { auth: resumeAuth, continuationToken: resumeToken }
+          );
+          console.log(
+            `[eve-lark] ask answered via card action requestId=${requestId} optionId=${optionId}`
+          );
+        } catch (e) {
+          console.error(
+            `[eve-lark] ask input-response send failed (requestId=${requestId}):`,
+            e instanceof Error ? e.message : e
+          );
+        }
+        dropPendingInput(pending);
+      })().catch((e) => {
+        console.error("[eve-lark] card action background work failed:", e);
+      })
+    );
     return ackOk();
   }
   __name(handleCardAction, "handleCardAction");
@@ -1752,6 +1932,31 @@ function createLarkChannel(optionsInput) {
       const ctrl = getController(sessionId, info);
       ctrl.appendDelta(d.messageDelta);
     },
+    // Model is about to call tools. Update the streaming card status so the
+    // user sees what's happening mid-turn instead of a static typing dot.
+    // Only fires when replyMode is "streaming" (cards exist). Post/static
+    // modes have no live surface to update.
+    async "actions.requested"(data, _channel, ctx) {
+      if (options.replyMode !== "streaming") return;
+      const sessionId = ctx.session.id;
+      const ctrl = controllers.get(sessionId);
+      if (!ctrl) return;
+      const d = data;
+      const names = (d.actions ?? []).map((a) => a.toolName).filter((n) => typeof n === "string");
+      if (names.length === 0) return;
+      const label = names.length === 1 ? `\u{1F527} ${names[0]}` : `\u{1F527} ${names.join(", ")}`;
+      ctrl.setStatus(label);
+    },
+    // A tool finished. Clear the status (the next message.appended or
+    // message.completed will overwrite anyway, but clearing here gives
+    // snappier feedback for long tool chains). Best-effort.
+    async "action.result"(_data, _channel, ctx) {
+      if (options.replyMode !== "streaming") return;
+      const sessionId = ctx.session.id;
+      const ctrl = controllers.get(sessionId);
+      if (!ctrl) return;
+      ctrl.setStatus("");
+    },
     // eve's ask_question (and similar HITL tools) fire this event with a
     // list of input requests. Each request becomes a Feishu card with
     // buttons (one per option) plus optional freeform hint.
@@ -1872,6 +2077,67 @@ function createLarkChannel(optionsInput) {
       console.error(
         `[eve-lark] session.failed: ${userText}` + (errorId ? ` (errorId=${errorId})` : "")
       );
+    },
+    // Turn ended cleanly. eve fires this after the final message.completed
+    // (or instead of it when the assistant step ended in tool-calls with no
+    // visible text). Either way, free this session's controller + ack
+    // reaction so we don't leak waiting for a message.completed that's
+    // never coming.
+    async "turn.completed"(data, _channel, ctx) {
+      const sessionId = ctx?.session?.id;
+      if (!sessionId) return;
+      try {
+        await cleanupAckReaction(sessionId);
+      } catch {
+      }
+      dropController(sessionId);
+    },
+    // The agent needs the user to sign in to an external service (e.g.
+    // GitHub, Slack, Linear). Render a card with a "Sign in with <X>"
+    // URL button so the user can complete the flow in their browser.
+    // The card message id is tracked so `authorization.completed` can
+    // patch it with the outcome.
+    async "authorization.required"(data, _channel, ctx) {
+      const sessionId = ctx?.session?.id;
+      const info = sessionInfoFromCtx(ctx);
+      if (!info || !sessionId) return;
+      const d = data;
+      const name = d.name ?? "service";
+      const displayName = d.authorization?.displayName ?? name;
+      const url = d.authorization?.url;
+      if (!url) {
+        console.warn(`[eve-lark] authorization.required for ${name}: no url, skipping card`);
+        return;
+      }
+      const card = buildAuthCard({ displayName, url, userCode: d.authorization?.userCode });
+      try {
+        const res = await client.sendCard({ chatId: info.chatId, card, rootId: info.rootId, parentId: info.parentId });
+        authCards.set(`${sessionId}:${name}`, res.messageId);
+      } catch (e) {
+        console.error(`[eve-lark] auth card send failed (${name}):`, e instanceof Error ? e.message : e);
+      }
+    },
+    // The user completed (or declined) the external auth. Patch the card
+    // we rendered in `authorization.required` to show the outcome.
+    async "authorization.completed"(data, _channel, ctx) {
+      const sessionId = ctx?.session?.id;
+      if (!sessionId) return;
+      const d = data;
+      const name = d.name ?? "service";
+      const cardMessageId = authCards.get(`${sessionId}:${name}`);
+      if (!cardMessageId) return;
+      const displayName = d.authorization?.displayName ?? name;
+      const card = buildAuthCompletedCard({
+        displayName,
+        outcome: d.outcome ?? "completed",
+        reason: d.reason
+      });
+      try {
+        await client.patchCard({ messageId: cardMessageId, card });
+      } catch (e) {
+        console.warn(`[eve-lark] auth card patch failed (${name}):`, e instanceof Error ? e.message : e);
+      }
+      authCards.delete(`${sessionId}:${name}`);
     }
   };
   const channel = defineChannel({