@opentag/lark 0.3.0 → 0.3.1

package/dist/index.js

@@ -133,6 +133,8 @@ function normalizeLarkMessage(input) {
       chatId: input.chatId,
       messageId: input.messageId,
       chatType: input.chatType,
+      sourceDeliveryId: input.eventId,
+      larkEventId: input.eventId,
       ...input.rootId ? { rootId: input.rootId } : {},
       ...input.botOpenId ? { larkBotOpenId: input.botOpenId } : {},
       ...commandMetadata(command),
@@ -144,9 +146,406 @@ function normalizeLarkMessage(input) {
 }
 
 // src/inbound.ts
-import { parseProjectTargetRef } from "@opentag/core";
+import {
+  createDoctorSummaryPresentation,
+  createSourceThreadStatusPresentation,
+  parseProjectTargetRef,
+  renderOpenTagPresentationPlainText
+} from "@opentag/core";
+
+// src/render.ts
+import {
+  createFinalSummaryPresentation
+} from "@opentag/core";
+function larkPlain(value) {
+  return value.replace(/`/g, "");
+}
+function auditCommand(runId) {
+  return `opentag status --run ${runId}`;
+}
+function renderLarkAcknowledgement(runId) {
+  return ["Received. OpenTag is working.", `Run: ${runId}`, `Use /status here for queue state; audit locally with ${auditCommand(runId)}.`].join("\n");
+}
+function renderLarkRunStatusPresentation(presentation) {
+  if (presentation.state === "received") {
+    return renderLarkAcknowledgement(presentation.runId);
+  }
+  if (presentation.state === "queued") {
+    return ["Queued behind an active run.", `Run: ${presentation.runId}`, "Use /status here for queue details."].join("\n");
+  }
+  if (presentation.state === "waiting_for_approval") {
+    return ["Waiting for your review.", `Run: ${presentation.runId}`, "Review the action receipt in this thread, or use /status here for details."].join("\n");
+  }
+  if (presentation.state === "running") {
+    return ["OpenTag is working.", `Run: ${presentation.runId}`, "Use /status here for details."].join("\n");
+  }
+  return [
+    `OpenTag run ${presentation.state}.`,
+    `Run: ${presentation.runId}`,
+    ...presentation.nextAction ? [presentation.nextAction] : [`Audit locally with ${auditCommand(presentation.runId)}.`]
+  ].join("\n");
+}
+function larkRunStatusHeaderTemplate(state) {
+  if (state === "received" || state === "queued" || state === "running") return "blue";
+  if (state === "waiting_for_approval") return "yellow";
+  if (state === "completed") return "green";
+  if (state === "failed" || state === "timed_out") return "red";
+  if (state === "cancelled" || state === "interrupted") return "grey";
+  return "blue";
+}
+function larkRunStatusTitle(state) {
+  if (state === "received") return "OpenTag received this";
+  if (state === "queued") return "OpenTag queued this";
+  if (state === "running") return "OpenTag is working";
+  if (state === "waiting_for_approval") return "OpenTag is waiting for review";
+  return `OpenTag ${state}`;
+}
+function createLarkRunStatusCard(presentation) {
+  const statusText = renderLarkRunStatusPresentation(presentation);
+  return {
+    config: {
+      wide_screen_mode: true,
+      update_multi: true
+    },
+    header: {
+      template: larkRunStatusHeaderTemplate(presentation.state),
+      title: {
+        tag: "plain_text",
+        content: larkRunStatusTitle(presentation.state)
+      }
+    },
+    elements: [
+      {
+        tag: "div",
+        text: {
+          tag: "lark_md",
+          content: statusText
+        }
+      }
+    ]
+  };
+}
+function renderLarkFinalResult(result, options = {}) {
+  return renderLarkFinalSummaryPresentation(
+    createFinalSummaryPresentation({
+      result,
+      ...options.auditRunId ? { auditRunId: options.auditRunId } : {}
+    })
+  );
+}
+function renderLarkFinalSummaryPresentation(presentation) {
+  const lines = [`Finished with ${presentation.outcome}.`, "", presentation.summary];
+  if (presentation.verification?.length) {
+    lines.push("", "Verification");
+    for (const check of presentation.verification) {
+      lines.push(`- ${check.command}: ${check.outcome}`);
+    }
+  }
+  if (presentation.nextActions?.length) {
+    lines.push("", `Next action: ${presentation.nextActions[0]}`);
+  }
+  if (presentation.auditRunId) {
+    lines.push("", `Audit: opentag status --run ${presentation.auditRunId}`);
+  }
+  return lines.join("\n");
+}
+function larkHeaderTemplate(outcome) {
+  if (outcome === "success") return "green";
+  if (outcome === "failure") return "red";
+  if (outcome === "cancelled") return "grey";
+  if (outcome === "needs_human") return "blue";
+  return "yellow";
+}
+function compactCardText(text, maxLength) {
+  const compact = text.replace(/\s+/g, " ").trim();
+  if (compact.length <= maxLength) return compact;
+  return `${compact.slice(0, Math.max(0, maxLength - 1)).trimEnd()}...`;
+}
+function larkMarkdownList(items) {
+  return items.map((item) => `- ${item}`).join("\n");
+}
+function larkActionDecisionLabel(decision, index) {
+  if (decision === "apply") return `Apply now: apply ${index}`;
+  if (decision === "approve") return `Approve only: approve ${index}`;
+  if (decision === "continue") return `Continue: continue ${index}`;
+  return `Reject: reject ${index}`;
+}
+function larkActionDetails(action) {
+  const rowDetails = action.detailRows?.map((row) => `${row.label}: ${larkPlain(row.value)}`) ?? [];
+  if (rowDetails.length > 0) return rowDetails.map((detail) => compactCardText(detail, 180));
+  const details = [`Target: ${action.targetLabel}`];
+  if (action.setupReason) details.push(`Status: ${action.setupReason}`);
+  if (action.details?.length) details.push(...action.details.slice(0, 3));
+  return details.map((detail) => compactCardText(larkPlain(detail), 180));
+}
+function larkActionReceiptMarkdown(input, options = {}) {
+  if (input.actions.length === 0) return void 0;
+  const visibleActions = input.actions.slice(0, 5);
+  const lines = [
+    ...options.includeTitle === false ? [] : [`**${input.title}**`],
+    "Choose a command in this source thread. Details stay in OpenTag audit/status."
+  ];
+  for (const action of visibleActions) {
+    lines.push("", `**${action.index}. ${compactCardText(action.title, 180)}**`);
+    lines.push(...larkMarkdownList(larkActionDetails(action)).split("\n"));
+    lines.push(...larkMarkdownList(action.visibleDecisions.map((decision) => larkActionDecisionLabel(decision, action.index))).split("\n"));
+  }
+  const remaining = input.actions.length - visibleActions.length;
+  if (remaining > 0) {
+    lines.push("", `Showing first ${visibleActions.length} of ${input.actions.length} actions. Use opentag status locally for full detail.`);
+  }
+  return lines.join("\n");
+}
+function larkFinalSummaryActionReceiptMarkdown(presentation) {
+  const actions = presentation.actions ?? [];
+  if (!presentation.actionReceiptTitle || actions.length === 0) return void 0;
+  return larkActionReceiptMarkdown({ title: presentation.actionReceiptTitle, actions });
+}
+function larkActionReceiptHeaderTemplate(actions) {
+  if (actions.some((action) => action.state === "needs_setup" || action.state === "unsupported")) return "yellow";
+  if (actions.some((action) => action.state === "ready_to_apply" || action.state === "needs_approval")) return "blue";
+  return "grey";
+}
+function createLarkFinalSummaryCard(presentation) {
+  const elements = [
+    {
+      tag: "div",
+      text: {
+        tag: "lark_md",
+        content: compactCardText(presentation.summary, 900)
+      }
+    }
+  ];
+  if (presentation.verification?.length) {
+    elements.push({ tag: "hr" });
+    elements.push({
+      tag: "div",
+      text: {
+        tag: "lark_md",
+        content: ["**Verification**", larkMarkdownList(presentation.verification.slice(0, 5).map((check) => `${larkPlain(check.command)}: ${check.outcome}`))].join(
+          "\n"
+        )
+      }
+    });
+  }
+  if (presentation.changedFiles?.length) {
+    elements.push({
+      tag: "div",
+      text: {
+        tag: "lark_md",
+        content: ["**Changed files**", larkMarkdownList(presentation.changedFiles.slice(0, 8).map(larkPlain))].join("\n")
+      }
+    });
+  }
+  if (presentation.nextActions?.length) {
+    elements.push({
+      tag: "div",
+      text: {
+        tag: "lark_md",
+        content: ["**Next action**", larkMarkdownList(presentation.nextActions.map((action) => compactCardText(action, 240)))].join("\n")
+      }
+    });
+  }
+  const actionReceipt = larkFinalSummaryActionReceiptMarkdown(presentation);
+  if (actionReceipt) {
+    elements.push({ tag: "hr" });
+    elements.push({
+      tag: "div",
+      text: {
+        tag: "lark_md",
+        content: actionReceipt
+      }
+    });
+  }
+  if (presentation.auditRunId) {
+    elements.push({
+      tag: "note",
+      elements: [
+        {
+          tag: "plain_text",
+          content: `Audit: opentag status --run ${presentation.auditRunId}`
+        }
+      ]
+    });
+  }
+  return {
+    config: {
+      wide_screen_mode: true,
+      update_multi: true
+    },
+    header: {
+      template: larkHeaderTemplate(presentation.outcome),
+      title: {
+        tag: "plain_text",
+        content: `Finished: ${presentation.outcome}`
+      }
+    },
+    elements
+  };
+}
+function renderLarkActionReceiptPresentation(presentation) {
+  return [
+    presentation.title,
+    "",
+    larkActionReceiptMarkdown({ title: presentation.title, actions: presentation.actions }, { includeTitle: false }) ?? "No source-thread actions.",
+    ...presentation.auditRunId ? ["", `Audit: opentag status --run ${presentation.auditRunId}`] : []
+  ].join("\n");
+}
+function createLarkActionReceiptCard(presentation) {
+  const elements = [
+    {
+      tag: "div",
+      text: {
+        tag: "lark_md",
+        content: larkActionReceiptMarkdown({ title: presentation.title, actions: presentation.actions }, { includeTitle: false }) ?? "No source-thread actions."
+      }
+    }
+  ];
+  if (presentation.auditRunId) {
+    elements.push({
+      tag: "note",
+      elements: [
+        {
+          tag: "plain_text",
+          content: `Audit: opentag status --run ${presentation.auditRunId}`
+        }
+      ]
+    });
+  }
+  return {
+    config: {
+      wide_screen_mode: true
+    },
+    header: {
+      template: larkActionReceiptHeaderTemplate(presentation.actions),
+      title: {
+        tag: "plain_text",
+        content: presentation.title.replace(/:$/, "")
+      }
+    },
+    elements
+  };
+}
+function larkDoctorHeaderTemplate(checks) {
+  if (checks.some((check) => check.status === "fail")) return "red";
+  if (checks.some((check) => check.status === "warn" || check.status === "unknown")) return "yellow";
+  return "green";
+}
+function larkStatusHeaderTemplate(presentation) {
+  if (presentation.bindingState === "unbound") return "yellow";
+  if (presentation.activeRun) return "blue";
+  return "green";
+}
+function checkStatusLabel(status) {
+  return status.toUpperCase();
+}
+function createLarkDoctorSummaryCard(presentation) {
+  return {
+    config: {
+      wide_screen_mode: true
+    },
+    header: {
+      template: larkDoctorHeaderTemplate(presentation.checks),
+      title: {
+        tag: "plain_text",
+        content: presentation.title.replace(/:$/, "")
+      }
+    },
+    elements: presentation.checks.map((check) => ({
+      tag: "div",
+      text: {
+        tag: "lark_md",
+        content: `**${checkStatusLabel(check.status)} ${check.name}**${check.message ? `
+${compactCardText(check.message, 500)}` : ""}`
+      }
+    }))
+  };
+}
+function createLarkSourceThreadStatusCard(presentation) {
+  const elements = [
+    {
+      tag: "div",
+      text: {
+        tag: "lark_md",
+        content: [
+          presentation.sourceContainer ? `**Source container**
+${presentation.sourceContainer}` : void 0,
+          `**Project Target**
+${presentation.projectTarget ?? "not bound"}`,
+          `**Active run**
+${presentation.activeRun ? `${presentation.activeRun.id} (${presentation.activeRun.status})${presentation.activeRun.updatedAt ? `, updated ${presentation.activeRun.updatedAt}` : ""}` : "none"}`,
+          presentation.currentCommand ? `**Command**
+${compactCardText(presentation.currentCommand, 240)}` : void 0
+        ].filter((line) => Boolean(line)).join("\n\n")
+      }
+    }
+  ];
+  const queuedTotal = presentation.queuedFollowUpsTotal ?? presentation.queuedFollowUps.length;
+  const queuedIds = presentation.queuedFollowUps.map((followUp) => {
+    const status = followUp.status ? ` (${followUp.status})` : "";
+    const command = followUp.command ? `: ${compactCardText(followUp.command, 120)}` : "";
+    return `${followUp.id}${status}${command}`;
+  });
+  const queuedOverflow = Math.max(queuedTotal - queuedIds.length, 0);
+  const queuedSummary = queuedTotal === 0 ? "none" : `${queuedTotal}${queuedIds.length ? ` (${queuedIds.join(", ")}${queuedOverflow > 0 ? `, +${queuedOverflow} more` : ""})` : ""}`;
+  elements.push({
+    tag: "div",
+    text: {
+      tag: "lark_md",
+      content: ["**Queued follow-ups**", queuedSummary, "", "**Next action**", compactCardText(presentation.nextAction, 360)].join("\n")
+    }
+  });
+  if (presentation.stopHint || presentation.detailHint) {
+    elements.push({
+      tag: "note",
+      elements: [
+        {
+          tag: "plain_text",
+          content: [presentation.stopHint ? `Stop/timeout: ${presentation.stopHint}` : void 0, presentation.detailHint ? `Details: ${presentation.detailHint}` : void 0].filter((line) => Boolean(line)).join(" ")
+        }
+      ]
+    });
+  }
+  return {
+    config: {
+      wide_screen_mode: true
+    },
+    header: {
+      template: larkStatusHeaderTemplate(presentation),
+      title: {
+        tag: "plain_text",
+        content: presentation.title.replace(/:$/, "")
+      }
+    },
+    elements
+  };
+}
+function createLarkTextMessageContent(text) {
+  return JSON.stringify({ text });
+}
+function createLarkInteractiveMessageContent(card) {
+  return JSON.stringify(card);
+}
+
+// src/inbound.ts
 var BIND_USAGE = "Usage: /bind <owner>/<repo> \u2014 e.g. /bind amplifthq/opentag (or /bind github:amplifthq/opentag).";
+var UNBIND_USAGE = "Usage: /unbind confirm \u2014 disconnects this chat from its current Project Target. This does not remove local checkout allowlists or repository bindings.";
 var UNBOUND_HINT = "This chat isn't connected to a Project Target yet. @-mention me with `/bind <owner>/<repo>` to connect it \u2014 e.g. /bind amplifthq/opentag.";
+var HELP_TEXT = [
+  "OpenTag commands:",
+  "- /bind <owner>/<repo> or /bind <provider>:<owner>/<repo> connects this chat to a Project Target.",
+  "- /unbind confirm disconnects this chat from its current Project Target; it never deletes local checkout config.",
+  "- /status shows the current Project Target, active-run guidance, queued follow-ups, and the next safe action.",
+  "- /doctor shows a redacted readiness summary for this source container.",
+  "- /stop [run_id] requests cancellation for the active chat run or the specified run; this connector will not treat stop as a successful completion.",
+  "Project Targets never use absolute local paths. Keep local checkout paths in runner config and allowlists.",
+  "Group chats must @-mention the bot before commands or runs."
+].join("\n");
+var STOP_UNAVAILABLE_TEXT = [
+  "Run cancellation from this Lark ingress is not configured.",
+  "OpenTag will not treat a stop request as a successful completion. Use `opentag status --run <run_id>` for audit detail, or `opentag service stop` if you need to stop the local background service."
+].join("\n");
+var BINDING_AUTH_DENIED_TEXT = "Only an authorized Lark binding manager can change this chat's Project Target. Ask an admin to run the command or update local OpenTag channel bindings.";
 function bindingFromDefault(input) {
   return {
     tenantKey: input.tenantKey,
@@ -171,6 +570,108 @@ function extractText(content) {
 function mentionsBot(mentions, botOpenId) {
   return (mentions ?? []).some((mention) => mention.id?.open_id === botOpenId);
 }
+function formatProjectTarget(binding) {
+  return `${binding.repoProvider}:${binding.owner}/${binding.repo}`;
+}
+function normalizeSelfServiceReply(reply) {
+  return typeof reply === "string" ? { text: reply } : reply;
+}
+function parseSelfServiceCommand(command) {
+  const trimmed = command.trim();
+  if (/^\/help(\s|$)/.test(trimmed)) return "help";
+  if (/^\/status(\s|$)/.test(trimmed)) return "status";
+  if (/^\/doctor(\s|$)/.test(trimmed)) return "doctor";
+  return null;
+}
+function statusPresentation(input) {
+  if (!input.binding) {
+    return createSourceThreadStatusPresentation({
+      title: "OpenTag status:",
+      sourceContainer: `lark:${input.tenantKey}/${input.chatId}`,
+      bindingState: "unbound",
+      nextAction: UNBOUND_HINT,
+      detailHint: "active run and queued follow-up status are unavailable until this chat is bound."
+    });
+  }
+  return createSourceThreadStatusPresentation({
+    title: "OpenTag status:",
+    sourceContainer: `lark:${input.tenantKey}/${input.chatId}`,
+    projectTarget: formatProjectTarget(input.binding),
+    bindingState: "bound",
+    nextAction: "send a follow-up in this thread, or check `opentag status --run <run_id>` locally for audit detail.",
+    stopHint: "cancellation is explicit and is not reported as successful completion; timeout policy is surfaced in status/audit.",
+    detailHint: "at most one run is active per Project Target + source thread; new same-thread requests queue behind it."
+  });
+}
+function statusReply(input) {
+  const presentation = statusPresentation(input);
+  return {
+    text: renderOpenTagPresentationPlainText(presentation),
+    card: createLarkSourceThreadStatusCard(presentation)
+  };
+}
+function doctorPresentation(input) {
+  return createDoctorSummaryPresentation({
+    title: "OpenTag doctor (redacted):",
+    checks: [
+      { status: "ok", name: "Source container", message: `lark:${input.tenantKey}/${input.chatId}` },
+      {
+        status: input.binding ? "ok" : "warn",
+        name: "Project Target",
+        message: input.binding ? formatProjectTarget(input.binding) : "not bound"
+      },
+      { status: "ok", name: "Secrets", message: "redacted. Use env/file/keychain SecretRef entries in local config instead of sharing secrets in chat." },
+      {
+        status: "warn",
+        name: "Runtime readiness",
+        message: "check `opentag service status` locally; launchd running is not the same as connector ready."
+      },
+      { status: "ok", name: "Source-thread output", message: "concise final replies by default; detailed process stays in audit/status." }
+    ]
+  });
+}
+function doctorReply(input) {
+  const presentation = doctorPresentation(input);
+  return {
+    text: renderOpenTagPresentationPlainText(presentation),
+    card: createLarkDoctorSummaryCard(presentation)
+  };
+}
+function formatFollowUpQueuedText(input) {
+  return [
+    "Queued as a follow-up.",
+    input.activeRunId ? `- Active run: ${input.activeRunId}` : "- Active run: currently in this source thread.",
+    `- Follow-up request: ${input.followUpRequestId}`,
+    input.reason ? `- Reason: ${input.reason}` : "- Reason: another run is already active for this thread.",
+    "- Next action: wait for the active run final reply, or inspect locally with `opentag status --run <run_id>`.",
+    "- Stop/timeout: cancellation is explicit and will not be treated as successful completion; timeout details are recorded in audit/status."
+  ].join("\n");
+}
+function formatRunReceivedText(runId) {
+  return [
+    `Received. Run: ${runId}.`,
+    "- Use `/status` in this chat for active-run and queue state.",
+    `- Use \`opentag status --run ${runId}\` locally for audit detail.`
+  ].join("\n");
+}
+function parseStopCommand(command) {
+  const match = command.trim().match(/^\/stop(?:\s+(\S+))?\s*$/);
+  if (!match) return null;
+  return match[1] ? { runId: match[1] } : {};
+}
+function formatStopResultText(result) {
+  if (result.outcome === "cancelled") {
+    return [
+      `Cancellation requested for run ${result.runId}.`,
+      "- OpenTag will not treat this stop request as a successful completion.",
+      "- The local executor may need a moment to observe the cancellation; further nonessential completion writes are suppressed."
+    ].join("\n");
+  }
+  if (result.outcome === "already_terminal") {
+    return `Run ${result.runId} is already finished. OpenTag will not change its final result.`;
+  }
+  return result.runId ? `Run ${result.runId} was not found or is no longer cancelable.` : "No active run was found for this chat and Project Target.";
+}
 function parseBindCommand(command) {
   if (!/^\/bind(\s|$)/.test(command)) return null;
   const match = command.match(/^\/bind\s+(\S+)\s*$/);
@@ -182,6 +683,14 @@ function parseBindCommand(command) {
     return { ok: false };
   }
 }
+function parseUnbindCommand(command) {
+  if (!/^\/unbind(\s|$)/.test(command)) return null;
+  return /^\/unbind\s+confirm\s*$/.test(command) ? { ok: true } : { ok: false };
+}
+async function canManageLarkBinding(config, context) {
+  if (config.canManageBinding) return config.canManageBinding(context);
+  return context.chatType === "p2p";
+}
 function createLarkMessageHandler(config) {
   return async function handleLarkMessage(data) {
     const message = data.message;
@@ -196,7 +705,8 @@ function createLarkMessageHandler(config) {
     if (!tenantKey || !chatId || !messageId || !eventId || !senderOpenId) {
       return { status: "ignored_invalid_payload" };
     }
-    const isDirect = message.chat_type === "p2p";
+    const chatType = message.chat_type ?? "group";
+    const isDirect = chatType === "p2p";
     if (!isDirect) {
       if (!config.botOpenId) {
         return { status: "ignored_group_requires_bot_open_id", tenantKey, chatId };
@@ -215,6 +725,21 @@ function createLarkMessageHandler(config) {
         await config.reply?.({ messageId, text: BIND_USAGE });
         return { status: "ignored_bind_usage", tenantKey, chatId };
       }
+      const authorized = await canManageLarkBinding(config, {
+        action: "bind",
+        tenantKey,
+        chatId,
+        chatType,
+        senderOpenId,
+        ...data.sender?.sender_id?.user_id ? { senderUserId: data.sender.sender_id.user_id } : {},
+        ...data.sender?.sender_id?.union_id ? { senderUnionId: data.sender.sender_id.union_id } : {},
+        messageId,
+        eventId
+      });
+      if (!authorized) {
+        await config.reply?.({ messageId, text: BINDING_AUTH_DENIED_TEXT });
+        return { status: "ignored_bind_unauthorized", tenantKey, chatId };
+      }
       await config.bindChannel({
         tenantKey,
         chatId,
@@ -228,9 +753,72 @@ function createLarkMessageHandler(config) {
       });
       return { status: "bound", tenantKey, chatId };
     }
+    const unbindRequest = parseUnbindCommand(command);
+    if (unbindRequest && !config.unbindChannel) {
+      return { status: "ignored_unbind_unavailable", tenantKey, chatId };
+    }
+    if (unbindRequest && config.unbindChannel) {
+      if (!unbindRequest.ok) {
+        await config.reply?.({ messageId, text: UNBIND_USAGE });
+        return { status: "ignored_unbind_usage", tenantKey, chatId };
+      }
+      const authorized = await canManageLarkBinding(config, {
+        action: "unbind",
+        tenantKey,
+        chatId,
+        chatType,
+        senderOpenId,
+        ...data.sender?.sender_id?.user_id ? { senderUserId: data.sender.sender_id.user_id } : {},
+        ...data.sender?.sender_id?.union_id ? { senderUnionId: data.sender.sender_id.union_id } : {},
+        messageId,
+        eventId
+      });
+      if (!authorized) {
+        await config.reply?.({ messageId, text: BINDING_AUTH_DENIED_TEXT });
+        return { status: "ignored_unbind_unauthorized", tenantKey, chatId };
+      }
+      const binding2 = await config.resolveChannelBinding({ tenantKey, chatId });
+      if (!binding2) {
+        await config.reply?.({ messageId, text: UNBOUND_HINT });
+        return { status: "ignored_unbound_chat", tenantKey, chatId };
+      }
+      await config.unbindChannel({ tenantKey, chatId });
+      await config.reply?.({
+        messageId,
+        text: `Disconnected this chat from Project Target ${formatProjectTarget(binding2)}. @-mention me with \`/bind <owner>/<repo>\` to connect a new target.`
+      });
+      return { status: "unbound", tenantKey, chatId };
+    }
     if (command.trim().length === 0) {
       return { status: "ignored_empty_command", tenantKey, chatId };
     }
+    const stopRequest = parseStopCommand(command);
+    if (stopRequest) {
+      if (!config.stopRun) {
+        await config.reply?.({ messageId, text: STOP_UNAVAILABLE_TEXT });
+        return { status: "self_service_stop_unavailable", tenantKey, chatId };
+      }
+      const result2 = await config.stopRun({
+        tenantKey,
+        chatId,
+        ...stopRequest.runId ? { runId: stopRequest.runId } : {},
+        requestedBy: `lark:${senderOpenId}`
+      });
+      await config.reply?.({ messageId, text: formatStopResultText(result2) });
+      return { status: "self_service_stop", ...result2.runId ? { runId: result2.runId } : {}, tenantKey, chatId };
+    }
+    const selfServiceCommand = parseSelfServiceCommand(command);
+    if (selfServiceCommand === "help") {
+      await config.reply?.({ messageId, text: HELP_TEXT });
+      return { status: "self_service_help", tenantKey, chatId };
+    }
+    if (selfServiceCommand === "status" || selfServiceCommand === "doctor") {
+      const binding2 = await config.resolveChannelBinding({ tenantKey, chatId });
+      const context = { tenantKey, chatId, messageId, binding: binding2 };
+      const reply = selfServiceCommand === "status" ? normalizeSelfServiceReply(await (config.status?.(context) ?? Promise.resolve(statusReply({ tenantKey, chatId, binding: binding2 })))) : normalizeSelfServiceReply(await (config.doctor?.(context) ?? Promise.resolve(doctorReply({ tenantKey, chatId, binding: binding2 }))));
+      await config.reply?.({ messageId, text: reply.text, ...reply.card ? { card: reply.card } : {} });
+      return { status: selfServiceCommand === "status" ? "self_service_status" : "self_service_doctor", tenantKey, chatId };
+    }
     let binding = await config.resolveChannelBinding({ tenantKey, chatId });
     if (binding && config.defaultRepoBinding && config.bindChannel) {
       if (shouldMigrateLegacyLocalBinding({ existing: binding, defaultBinding: config.defaultRepoBinding })) {
@@ -281,9 +869,20 @@ function createLarkMessageHandler(config) {
     }
     const result = await config.createRun(event);
     if (result.outcome === "run_created") {
+      if (!result.idempotentReplay) {
+        await config.reply?.({ messageId, text: formatRunReceivedText(result.run.id) });
+      }
       return { status: "created", runId: result.run.id, tenantKey, chatId };
     }
     if (result.outcome === "follow_up_queued") {
+      await config.reply?.({
+        messageId,
+        text: formatFollowUpQueuedText({
+          followUpRequestId: result.followUpRequest.id,
+          ...result.decision.activeRunId ? { activeRunId: result.decision.activeRunId } : {},
+          reason: result.decision.reason
+        })
+      });
       return {
         status: "follow_up_queued",
         followUpRequestId: result.followUpRequest.id,
@@ -306,39 +905,15 @@ function createLarkMessageHandler(config) {
 import { randomUUID } from "crypto";
 import * as lark2 from "@larksuiteoapi/node-sdk";
 import { createOpenTagClient } from "@opentag/client";
-import { parseProjectTargetRef as parseProjectTargetRef2 } from "@opentag/core";
+import {
+  createDoctorSummaryPresentation as createDoctorSummaryPresentation2,
+  createSourceThreadStatusPresentation as createSourceThreadStatusPresentation2,
+  parseProjectTargetRef as parseProjectTargetRef2,
+  renderOpenTagPresentationPlainText as renderOpenTagPresentationPlainText2
+} from "@opentag/core";
 
 // src/outbound.ts
 import * as lark from "@larksuiteoapi/node-sdk";
-
-// src/render.ts
-function nextActionSummary(result) {
-  if (!result.nextAction) return void 0;
-  if (typeof result.nextAction === "string") return result.nextAction;
-  return result.nextAction.summary;
-}
-function renderLarkAcknowledgement(runId) {
-  return `I picked this up: ${runId}`;
-}
-function renderLarkFinalResult(result) {
-  const lines = [`Finished with ${result.conclusion}.`, "", result.summary];
-  if (result.verification?.length) {
-    lines.push("", "Verification");
-    for (const check of result.verification) {
-      lines.push(`- ${check.command}: ${check.outcome}`);
-    }
-  }
-  const nextAction = nextActionSummary(result);
-  if (nextAction) {
-    lines.push("", `Next action: ${nextAction}`);
-  }
-  return lines.join("\n");
-}
-function createLarkTextMessageContent(text) {
-  return JSON.stringify({ text });
-}
-
-// src/outbound.ts
 function createLarkReplyClient(input) {
   return new lark.Client({
     appId: input.appId,
@@ -346,10 +921,55 @@ function createLarkReplyClient(input) {
     domain: input.domain === "feishu" ? lark.Domain.Feishu : lark.Domain.Lark
   });
 }
+function larkMessageApi(client, method) {
+  const legacyApi = client.im.message;
+  if (legacyApi?.[method]) return legacyApi;
+  const v1Api = client.im.v1?.message;
+  if (v1Api?.[method]) return v1Api;
+  throw new Error(`Lark client does not support message.${method}.`);
+}
+function larkReplyMessageId(response) {
+  if (!response || typeof response !== "object") return void 0;
+  const data = "data" in response ? response.data : void 0;
+  if (data && typeof data === "object" && "message_id" in data) {
+    const value = data.message_id;
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  if ("message_id" in response) {
+    const value = response.message_id;
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return void 0;
+}
 async function replyLarkMessage(client, input) {
-  await client.im.message.reply({
+  const reply = larkMessageApi(client, "reply").reply;
+  if (!reply) throw new Error("Lark client does not support message.reply.");
+  const response = await reply({
+    path: { message_id: input.messageId },
+    data: input.card ? { content: createLarkInteractiveMessageContent(input.card), msg_type: "interactive", reply_in_thread: true } : { content: createLarkTextMessageContent(input.text), msg_type: "text", reply_in_thread: true }
+  });
+  const messageId = larkReplyMessageId(response);
+  return messageId ? { messageId } : {};
+}
+async function patchLarkMessageCard(client, input) {
+  const patch = larkMessageApi(client, "patch").patch;
+  if (!patch) throw new Error("Lark client does not support message.patch.");
+  await patch({
     path: { message_id: input.messageId },
-    data: { content: createLarkTextMessageContent(input.text), msg_type: "text", reply_in_thread: true }
+    data: {
+      content: createLarkInteractiveMessageContent(input.card)
+    }
+  });
+}
+async function updateLarkTextMessage(client, input) {
+  const update = larkMessageApi(client, "update").update;
+  if (!update) throw new Error("Lark client does not support message.update.");
+  await update({
+    path: { message_id: input.messageId },
+    data: {
+      msg_type: "text",
+      content: createLarkTextMessageContent(input.text)
+    }
   });
 }
 
@@ -375,6 +995,18 @@ function domainFromEnv(value) {
   }
   return domain;
 }
+function positiveIntegerFromEnv(name, value) {
+  if (!value) return void 0;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  return parsed;
+}
+function csvList(value) {
+  const items = value?.split(",").map((item) => item.trim()).filter(Boolean);
+  return items?.length ? items : void 0;
+}
 function larkIngressConfigFromEnv(env) {
   const appId = env.LARK_APP_ID;
   const appSecret = env.LARK_APP_SECRET;
@@ -386,6 +1018,10 @@ function larkIngressConfigFromEnv(env) {
     throw new Error("OPENTAG_DISPATCHER_URL is required");
   }
   const defaultRepoBinding = defaultRepoBindingFromEnv(env.OPENTAG_LARK_DEFAULT_REPO);
+  const runTimeoutMs = positiveIntegerFromEnv("OPENTAG_RUN_TIMEOUT_MS", env.OPENTAG_RUN_TIMEOUT_MS);
+  const bindingAdminOpenIds = csvList(env.OPENTAG_LARK_BINDING_ADMIN_OPEN_IDS);
+  const bindingAdminUserIds = csvList(env.OPENTAG_LARK_BINDING_ADMIN_USER_IDS);
+  const bindingAdminUnionIds = csvList(env.OPENTAG_LARK_BINDING_ADMIN_UNION_IDS);
   return {
     appId,
     appSecret,
@@ -394,6 +1030,10 @@ function larkIngressConfigFromEnv(env) {
     agentId: env.OPENTAG_LARK_AGENT_ID ?? DEFAULT_AGENT_ID,
     ...env.OPENTAG_DISPATCHER_TOKEN ? { dispatcherToken: env.OPENTAG_DISPATCHER_TOKEN } : {},
     ...env.LARK_BOT_OPEN_ID ? { botOpenId: env.LARK_BOT_OPEN_ID } : {},
+    ...bindingAdminOpenIds ? { bindingAdminOpenIds } : {},
+    ...bindingAdminUserIds ? { bindingAdminUserIds } : {},
+    ...bindingAdminUnionIds ? { bindingAdminUnionIds } : {},
+    ...runTimeoutMs ? { runTimeoutMs } : {},
     ...defaultRepoBinding ? { defaultRepoBinding } : {}
   };
 }
@@ -410,7 +1050,9 @@ function createDefaultEventDispatcher(handler) {
   });
 }
 function logIgnored(outcome) {
-  if (outcome.status === "created" || outcome.status === "bound") return;
+  if (outcome.status === "created" || outcome.status === "bound" || outcome.status === "unbound" || outcome.status === "self_service_help" || outcome.status === "self_service_status" || outcome.status === "self_service_doctor" || outcome.status === "self_service_stop" || outcome.status === "self_service_stop_unavailable") {
+    return;
+  }
   if (outcome.status === "follow_up_queued") {
     console.log(
       `[lark] queued follow-up${outcome.followUpRequestId ? ` follow_up_request_id=${outcome.followUpRequestId}` : ""}${outcome.runId ? ` active_run_id=${outcome.runId}` : ""}`
@@ -429,6 +1071,109 @@ function logIgnored(outcome) {
   }
   console.log(`[lark] ignored event: ${outcome.status}${outcome.chatId ? ` chat_id=${outcome.chatId}` : ""}`);
 }
+function formatProjectTarget2(input) {
+  return `${input.repoProvider}:${input.owner}/${input.repo}`;
+}
+function queuedFollowUpsSummary(status) {
+  if (status.queuedFollowUps.length === 0) return "none.";
+  const visible = status.queuedFollowUps.slice(0, 3).map((followUp) => followUp.id);
+  const suffix = status.queuedFollowUps.length > visible.length ? `, +${status.queuedFollowUps.length - visible.length} more` : "";
+  return `${status.queuedFollowUps.length} (${visible.join(", ")}${suffix}).`;
+}
+function formatDurationMs(ms) {
+  if (ms % 6e4 === 0) return `${ms / 6e4} minute(s)`;
+  if (ms % 1e3 === 0) return `${ms / 1e3} second(s)`;
+  return `${ms}ms`;
+}
+function runTimeoutPolicy(input) {
+  const hardTimeoutMs = input.status?.runTimeoutPolicy?.hardTimeoutMs ?? input.runTimeoutMs;
+  return hardTimeoutMs ? `hard timeout after ${formatDurationMs(hardTimeoutMs)}` : "disabled";
+}
+function larkRuntimeStatusPresentation(status, input = {}) {
+  return createSourceThreadStatusPresentation2({
+    title: "OpenTag status:",
+    sourceContainer: `${status.binding.provider}:${status.binding.accountId}/${status.binding.conversationId}`,
+    projectTarget: formatProjectTarget2(status.binding),
+    bindingState: "bound",
+    ...status.activeRun ? {
+      activeRun: {
+        id: status.activeRun.id,
+        status: status.activeRun.status,
+        updatedAt: status.activeRun.updatedAt
+      }
+    } : {},
+    ...status.activeEvent?.command.rawText ? { currentCommand: status.activeEvent.command.rawText } : {},
+    queuedFollowUps: status.queuedFollowUps.slice(0, 3).map((followUp) => ({
+      id: followUp.id,
+      status: followUp.status,
+      command: followUp.event.command.rawText
+    })),
+    queuedFollowUpsTotal: status.queuedFollowUps.length,
+    nextAction: status.activeRun ? "wait for the final reply, send a follow-up to queue more context, or use `/stop` to request cancellation." : "@-mention me with a task to start a run.",
+    stopHint: `cancellation is explicit and is not reported as successful completion; timeout policy: ${runTimeoutPolicy({ ...input, status })}.`,
+    detailHint: "use `opentag status --run <run_id>` locally for audit events and executor detail."
+  });
+}
+function larkRuntimeStatusReply(status, input = {}) {
+  const presentation = larkRuntimeStatusPresentation(status, input);
+  return {
+    text: renderOpenTagPresentationPlainText2(presentation),
+    card: createLarkSourceThreadStatusCard(presentation)
+  };
+}
+function larkRuntimeDoctorPresentation(input) {
+  return createDoctorSummaryPresentation2({
+    title: "OpenTag doctor (redacted):",
+    checks: [
+      { status: "ok", name: "Source container", message: `lark:${input.tenantKey}/${input.chatId}` },
+      { status: "ok", name: "Project Target", message: formatProjectTarget2(input.status.binding) },
+      { status: "ok", name: "Dispatcher", message: "reachable for this source container." },
+      {
+        status: "ok",
+        name: "Active run",
+        message: input.status.activeRun ? `${input.status.activeRun.id} (${input.status.activeRun.status}), updated ${input.status.activeRun.updatedAt}.` : "none."
+      },
+      { status: "ok", name: "Queued follow-ups", message: queuedFollowUpsSummary(input.status) },
+      { status: "ok", name: "Timeout policy", message: runTimeoutPolicy({ ...input, status: input.status }) },
+      {
+        status: "ok",
+        name: "Runtime readiness",
+        message: "source-container status is reachable; run `opentag service status` locally to confirm launchd, connector, executor, and heartbeat health."
+      },
+      { status: "ok", name: "Secrets", message: "redacted. Use env/file/keychain SecretRef config and never paste app secrets into this chat." },
+      { status: "ok", name: "Source-thread output", message: "concise final replies by default; detailed process belongs in audit/status." }
+    ]
+  });
+}
+function larkRuntimeDoctorReply(input) {
+  const presentation = larkRuntimeDoctorPresentation(input);
+  return {
+    text: renderOpenTagPresentationPlainText2(presentation),
+    card: createLarkDoctorSummaryCard(presentation)
+  };
+}
+function formatStatusUnavailable(input) {
+  const message = input.error instanceof Error ? input.error.message : String(input.error);
+  return [
+    "OpenTag status:",
+    input.binding ? `- Project Target: ${formatProjectTarget2({ repoProvider: input.binding.repoProvider ?? "github", owner: input.binding.owner, repo: input.binding.repo })}` : "- Project Target: not bound.",
+    "- Runtime status: unavailable from dispatcher.",
+    `- Reason: ${message}`,
+    "- Next action: check `opentag service status` and `opentag status` locally."
+  ].join("\n");
+}
+function formatDoctorUnavailable(input) {
+  const message = input.error instanceof Error ? input.error.message : String(input.error);
+  return [
+    "OpenTag doctor (redacted):",
+    `- Source container: lark:${input.tenantKey}/${input.chatId}`,
+    input.binding ? `- Project Target: ${formatProjectTarget2({ repoProvider: input.binding.repoProvider ?? "github", owner: input.binding.owner, repo: input.binding.repo })}` : "- Project Target: not bound.",
+    "- Dispatcher: source-container status unavailable.",
+    `- Reason: ${message}`,
+    "- Runtime readiness: run `opentag service status` and `opentag status --channel lark:<tenant>/<chat>` locally.",
+    "- Secrets: redacted; do not share local config or app secrets in this chat."
+  ].join("\n");
+}
 function startLarkIngress(config, dependencies = {}) {
   const dispatcherClient = createOpenTagClient({
     dispatcherUrl: config.dispatcherUrl,
@@ -474,6 +1219,103 @@ function startLarkIngress(config, dependencies = {}) {
         repo: input.repo
       });
     },
+    async unbindChannel(input) {
+      await dispatcherClient.unbindChannel({
+        provider: "lark",
+        accountId: input.tenantKey,
+        conversationId: input.chatId
+      });
+    },
+    canManageBinding(input) {
+      if (input.chatType === "p2p") return true;
+      return Boolean(
+        config.bindingAdminOpenIds?.includes(input.senderOpenId) || input.senderUserId && config.bindingAdminUserIds?.includes(input.senderUserId) || input.senderUnionId && config.bindingAdminUnionIds?.includes(input.senderUnionId)
+      );
+    },
+    async stopRun(input) {
+      try {
+        const result = input.runId ? await dispatcherClient.cancelRun({
+          runId: input.runId,
+          reason: "Stop requested from Lark.",
+          requestedBy: input.requestedBy
+        }) : await dispatcherClient.cancelActiveChannelRun({
+          provider: "lark",
+          accountId: input.tenantKey,
+          conversationId: input.chatId,
+          reason: "Stop requested from Lark.",
+          requestedBy: input.requestedBy
+        });
+        return { outcome: "cancelled", runId: result.run.id };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("run_already_terminal")) {
+          return { outcome: "already_terminal", runId: input.runId ?? "active run" };
+        }
+        if (message.includes("run_not_found") || message.includes("active_run_not_found") || message.includes("channel_binding_not_found")) {
+          return input.runId ? { outcome: "not_found", runId: input.runId } : { outcome: "not_found" };
+        }
+        throw error;
+      }
+    },
+    async status(input) {
+      if (!input.binding) {
+        const presentation = createSourceThreadStatusPresentation2({
+          title: "OpenTag status:",
+          sourceContainer: `lark:${input.tenantKey}/${input.chatId}`,
+          bindingState: "unbound",
+          nextAction: "@-mention me with `/bind <owner>/<repo>` to connect a Project Target.",
+          detailHint: "active run and queued follow-up status are unavailable until this chat is bound."
+        });
+        return {
+          text: renderOpenTagPresentationPlainText2(presentation),
+          card: createLarkSourceThreadStatusCard(presentation)
+        };
+      }
+      try {
+        return larkRuntimeStatusReply(
+          await dispatcherClient.getChannelRuntimeStatus({
+            provider: "lark",
+            accountId: input.tenantKey,
+            conversationId: input.chatId
+          }),
+          { ...config.runTimeoutMs ? { runTimeoutMs: config.runTimeoutMs } : {} }
+        );
+      } catch (error) {
+        return formatStatusUnavailable({ binding: input.binding, error });
+      }
+    },
+    async doctor(input) {
+      if (!input.binding) {
+        const presentation = createDoctorSummaryPresentation2({
+          title: "OpenTag doctor (redacted):",
+          checks: [
+            { status: "ok", name: "Source container", message: `lark:${input.tenantKey}/${input.chatId}` },
+            { status: "warn", name: "Project Target", message: "not bound." },
+            { status: "warn", name: "Dispatcher", message: "binding not found for this source container." },
+            { status: "ok", name: "Next action", message: "@-mention me with `/bind <owner>/<repo>` to connect a Project Target." },
+            { status: "ok", name: "Secrets", message: "redacted; do not share local config or app secrets in this chat." }
+          ]
+        });
+        return {
+          text: renderOpenTagPresentationPlainText2(presentation),
+          card: createLarkDoctorSummaryCard(presentation)
+        };
+      }
+      try {
+        return larkRuntimeDoctorReply({
+          tenantKey: input.tenantKey,
+          chatId: input.chatId,
+          status: await dispatcherClient.getChannelRuntimeStatus({
+            provider: "lark",
+            accountId: input.tenantKey,
+            conversationId: input.chatId
+          }),
+          ...config.runTimeoutMs ? { runTimeoutMs: config.runTimeoutMs } : {}
+        });
+      } catch (error) {
+        return formatDoctorUnavailable({ tenantKey: input.tenantKey, chatId: input.chatId, binding: input.binding, error });
+      }
+    },
     async reply(input) {
       await reply(input);
     },
@@ -512,10 +1354,10 @@ function accountDomainFor(domain) {
 function sdkDomainFor(domain) {
   return domain === "feishu" ? lark3.Domain.Feishu : lark3.Domain.Lark;
 }
-function registrationDomainFromUserInfo(requestedDomain, userInfo) {
+function registrationDomainFromUserInfo(userInfo) {
   if (userInfo?.tenant_brand === "lark") return "lark";
   if (userInfo?.tenant_brand === "feishu") return "feishu";
-  return requestedDomain;
+  return "feishu";
 }
 function createDefaultBotInfoClient(input) {
   return new lark3.Client({
@@ -535,6 +1377,24 @@ function botInfoFromResponse(response) {
     botName: bot.app_name || bot.name || "OpenTag"
   };
 }
+async function validateLarkCredentials(input, dependencies = {}) {
+  const client = (dependencies.createBotInfoClient ?? createDefaultBotInfoClient)(input);
+  let response;
+  try {
+    response = await client.request({
+      url: "/open-apis/bot/v3/info",
+      method: "GET"
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Lark credentials could not be verified: ${reason}`);
+  }
+  const botIdentity = botInfoFromResponse(response);
+  if (!botIdentity) {
+    throw new Error("Lark credentials could not be verified: bot/v3/info response did not include bot.open_id.");
+  }
+  return botIdentity;
+}
 async function fetchBotIdentity(input, options) {
   const client = options.createBotInfoClient(input);
   let lastError;
@@ -564,11 +1424,12 @@ async function fetchBotIdentity(input, options) {
   return {};
 }
 async function registerLarkPersonalAgent(input, dependencies = {}) {
-  const requestedDomain = input.domain ?? "lark";
   let detectedDomain;
   const registerApp2 = dependencies.registerApp ?? lark3.registerApp;
   const registrationOptions = {
-    // The Personal Agent registration flow starts on Feishu and switches to Lark after scan when needed.
+    // QR registration does not preselect a tenant. The SDK starts on the Feishu
+    // bootstrap host and can switch polling to Lark when it detects an
+    // international tenant; the created app's actual tenant is persisted below.
     domain: accountDomainFor("feishu"),
     larkDomain: accountDomainFor("lark"),
     source: REGISTRATION_SOURCE,
@@ -599,7 +1460,7 @@ async function registerLarkPersonalAgent(input, dependencies = {}) {
     ...registrationOptions,
     ...input.signal ? { signal: input.signal } : {}
   });
-  const domain = detectedDomain ?? registrationDomainFromUserInfo(requestedDomain, registration.user_info);
+  const domain = detectedDomain ?? registrationDomainFromUserInfo(registration.user_info);
   const botIdentity = await fetchBotIdentity(
     {
       appId: registration.client_id,
@@ -623,18 +1484,30 @@ async function registerLarkPersonalAgent(input, dependencies = {}) {
 }
 export {
   DEFAULT_AGENT_ID,
+  createLarkActionReceiptCard,
+  createLarkDoctorSummaryCard,
+  createLarkFinalSummaryCard,
+  createLarkInteractiveMessageContent,
   createLarkMessageHandler,
   createLarkReplyClient,
+  createLarkRunStatusCard,
+  createLarkSourceThreadStatusCard,
   createLarkTextMessageContent,
   encodeLarkThreadKey,
   larkIngressConfigFromEnv,
   normalizeLarkMessage,
   parseLarkThreadKey,
+  patchLarkMessageCard,
   registerLarkPersonalAgent,
   renderLarkAcknowledgement,
+  renderLarkActionReceiptPresentation,
   renderLarkFinalResult,
+  renderLarkFinalSummaryPresentation,
+  renderLarkRunStatusPresentation,
   replyLarkMessage,
   startLarkIngress,
-  stripLarkMention
+  stripLarkMention,
+  updateLarkTextMessage,
+  validateLarkCredentials
 };
 //# sourceMappingURL=index.js.map