feat(plugin-sdk): add generic SDK seam followups

Adds host runtime reads, derived tool paths, channel attachment hints, input-suppression descriptors, scheduler tag cleanup, session-entry slot projection, and channel helper exports on top of the workflow seams.

Author: Eva

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -4395,6 +4395,7 @@ public struct PluginControlUiDescriptor: Codable, Sendable {
     public let renderer: String?
     public let statenamespace: String?
     public let actionids: [String]?
+    public let suppresshostinputwhile: [String: AnyCodable]?
     public let schema: AnyCodable?
     public let requiredscopes: [String]?
 
@@ -4409,6 +4410,7 @@ public struct PluginControlUiDescriptor: Codable, Sendable {
         renderer: String?,
         statenamespace: String?,
         actionids: [String]?,
+        suppresshostinputwhile: [String: AnyCodable]?,
         schema: AnyCodable?,
         requiredscopes: [String]?)
     {
@@ -4422,6 +4424,7 @@ public struct PluginControlUiDescriptor: Codable, Sendable {
         self.renderer = renderer
         self.statenamespace = statenamespace
         self.actionids = actionids
+        self.suppresshostinputwhile = suppresshostinputwhile
         self.schema = schema
         self.requiredscopes = requiredscopes
     }
@@ -4437,6 +4440,7 @@ public struct PluginControlUiDescriptor: Codable, Sendable {
         case renderer
         case statenamespace = "stateNamespace"
         case actionids = "actionIds"
+        case suppresshostinputwhile = "suppressHostInputWhile"
         case schema
         case requiredscopes = "requiredScopes"
     }

apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift

@@ -4395,6 +4395,7 @@ public struct PluginControlUiDescriptor: Codable, Sendable {
     public let renderer: String?
     public let statenamespace: String?
     public let actionids: [String]?
+    public let suppresshostinputwhile: [String: AnyCodable]?
     public let schema: AnyCodable?
     public let requiredscopes: [String]?
 
@@ -4409,6 +4410,7 @@ public struct PluginControlUiDescriptor: Codable, Sendable {
         renderer: String?,
         statenamespace: String?,
         actionids: [String]?,
+        suppresshostinputwhile: [String: AnyCodable]?,
         schema: AnyCodable?,
         requiredscopes: [String]?)
     {
@@ -4422,6 +4424,7 @@ public struct PluginControlUiDescriptor: Codable, Sendable {
         self.renderer = renderer
         self.statenamespace = statenamespace
         self.actionids = actionids
+        self.suppresshostinputwhile = suppresshostinputwhile
         self.schema = schema
         self.requiredscopes = requiredscopes
     }
@@ -4437,6 +4440,7 @@ public struct PluginControlUiDescriptor: Codable, Sendable {
         case renderer
         case statenamespace = "stateNamespace"
         case actionids = "actionIds"
+        case suppresshostinputwhile = "suppressHostInputWhile"
         case schema
         case requiredscopes = "requiredScopes"
     }

docs/.generated/plugin-sdk-api-baseline.sha256

@@ -1,2 +1,2 @@
-4d9d95b378019e6dc0c533af87bac2251b426ccc2c63b36a941101161bb81e95  plugin-sdk-api-baseline.json
-7cb657a117e1c5c227a0b6b8ae5c4c371ca4f4f97a7b4f57a9f980573deb4c76  plugin-sdk-api-baseline.jsonl
+93a24eda968062d28c5bda33e1d6eaec8cb252d4b3bde9ead1e5fe46756b1e4a  plugin-sdk-api-baseline.json
+0ceea424a909b5c059d47384ebf36a5912c51c40e30b5cae6cd1a0c92b4e7f18  plugin-sdk-api-baseline.jsonl

extensions/qa-lab/src/runtime-api.ts

@@ -20,7 +20,7 @@ export {
   searchQaBusMessages,
   sendQaBusMessage,
   setQaChannelRuntime,
-} from "openclaw/plugin-sdk/qa-channel";
+} from "@openclaw/qa-channel/api.js";
 export type {
   QaBusAttachment,
   QaBusConversation,
@@ -39,4 +39,4 @@ export type {
   QaBusStateSnapshot,
   QaBusThread,
   QaBusWaitForInput,
-} from "./protocol.js";
+} from "@openclaw/qa-channel/api.js";

extensions/telegram/api.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { escapeTelegramHtml, markdownToTelegramHtml } from "./api.js";
+
+describe("@openclaw/telegram api re-exports", () => {
+  it("re-exports markdownToTelegramHtml as a working function", () => {
+    expect(typeof markdownToTelegramHtml).toBe("function");
+    const rendered = markdownToTelegramHtml("**bold** plain");
+    expect(rendered).toContain("<b>");
+    expect(rendered).toContain("plain");
+  });
+
+  it("re-exports escapeTelegramHtml that escapes the three Telegram-reserved characters", () => {
+    expect(typeof escapeTelegramHtml).toBe("function");
+    expect(escapeTelegramHtml("<b>x & y</b>")).toBe("&lt;b&gt;x &amp; y&lt;/b&gt;");
+  });
+});

extensions/telegram/api.ts

@@ -182,3 +182,11 @@ export {
 export type { TelegramButtonStyle, TelegramInlineButtons } from "./src/button-types.js";
 export type { StickerMetadata } from "./src/bot/types.js";
 export type { TelegramTokenResolution } from "./src/token.js";
+export {
+  escapeTelegramHtml,
+  markdownToTelegramChunks,
+  markdownToTelegramHtml,
+  markdownToTelegramHtmlChunks,
+  splitTelegramHtmlChunks,
+  type TelegramFormattedChunk,
+} from "./src/format.js";

extensions/telegram/src/channel.ts

@@ -170,6 +170,7 @@ function buildTelegramSendOptions(params: {
   threadId?: string | number | null;
   silent?: boolean | null;
   forceDocument?: boolean | null;
+  parseMode?: "HTML" | "MarkdownV2" | null;
   gatewayClientScopes?: readonly string[] | null;
 }): TelegramSendOptions {
   return {
@@ -182,6 +183,7 @@ function buildTelegramSendOptions(params: {
     accountId: params.accountId ?? undefined,
     silent: params.silent ?? undefined,
     forceDocument: params.forceDocument ?? undefined,
+    textMode: params.parseMode === "MarkdownV2" ? "markdown" : "html",
     ...(Array.isArray(params.gatewayClientScopes)
       ? { gatewayClientScopes: [...params.gatewayClientScopes] }
       : {}),
@@ -199,6 +201,7 @@ async function sendTelegramOutbound(params: {
   replyToId?: string | null;
   threadId?: string | number | null;
   silent?: boolean | null;
+  parseMode?: "HTML" | "MarkdownV2" | null;
   gatewayClientScopes?: readonly string[] | null;
 }) {
   const send = await resolveTelegramSend(params.deps);
@@ -213,6 +216,7 @@ async function sendTelegramOutbound(params: {
       replyToId: params.replyToId,
       threadId: params.threadId,
       silent: params.silent,
+      parseMode: params.parseMode,
       gatewayClientScopes: params.gatewayClientScopes,
     }),
   );
@@ -1098,6 +1102,7 @@ export const telegramPlugin = createChatChannelPlugin({
         replyToId,
         threadId,
         silent,
+        formatting,
         gatewayClientScopes,
       }) =>
         await sendTelegramOutbound({
@@ -1109,6 +1114,7 @@ export const telegramPlugin = createChatChannelPlugin({
           replyToId,
           threadId,
           silent,
+          parseMode: formatting?.parseMode,
           gatewayClientScopes,
         }),
       sendMedia: async ({
@@ -1122,6 +1128,7 @@ export const telegramPlugin = createChatChannelPlugin({
         replyToId,
         threadId,
         silent,
+        formatting,
         gatewayClientScopes,
       }) =>
         await sendTelegramOutbound({
@@ -1135,6 +1142,7 @@ export const telegramPlugin = createChatChannelPlugin({
           replyToId,
           threadId,
           silent,
+          parseMode: formatting?.parseMode,
           gatewayClientScopes,
         }),
       sendPoll: async ({

extensions/telegram/src/format.ts

@@ -15,10 +15,20 @@ export type TelegramFormattedChunk = {
   text: string;
 };
 
-function escapeHtml(text: string): string {
+/**
+ * Escape a plain string for safe insertion inside Telegram HTML messages.
+ *
+ * Public alias used by `@openclaw/telegram/api` so plugin authors can render
+ * Telegram-safe captions without re-implementing the escape rules.
+ */
+export function escapeTelegramHtml(text: string): string {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
+function escapeHtml(text: string): string {
+  return escapeTelegramHtml(text);
+}
+
 function escapeHtmlAttr(text: string): string {
   return escapeHtml(text).replace(/"/g, "&quot;");
 }

extensions/telegram/src/outbound-adapter.ts

@@ -48,7 +48,7 @@ async function resolveTelegramSendContext(params: {
   baseOpts: {
     cfg: NonNullable<TelegramSendOpts>["cfg"];
     verbose: false;
-    textMode: "html";
+    textMode: "html" | "markdown";
     messageThreadId?: number;
     replyToMessageId?: number;
     accountId?: string;
@@ -161,6 +161,7 @@ export const telegramOutbound: ChannelOutboundAdapter = {
       replyToId,
       threadId,
       gatewayClientScopes,
+      formatting,
     }) => {
       const { send, baseOpts } = await resolveTelegramSendContext({
         cfg,
@@ -172,6 +173,7 @@ export const telegramOutbound: ChannelOutboundAdapter = {
       });
       return await send(to, text, {
         ...baseOpts,
+        textMode: formatting?.parseMode === "MarkdownV2" ? "markdown" : "html",
       });
     },
     sendMedia: async ({
@@ -187,6 +189,7 @@ export const telegramOutbound: ChannelOutboundAdapter = {
       threadId,
       forceDocument,
       gatewayClientScopes,
+      formatting,
     }) => {
       const { send, baseOpts } = await resolveTelegramSendContext({
         cfg,
@@ -198,6 +201,7 @@ export const telegramOutbound: ChannelOutboundAdapter = {
       });
       return await send(to, text, {
         ...baseOpts,
+        textMode: formatting?.parseMode === "MarkdownV2" ? "markdown" : "html",
         mediaUrl,
         mediaLocalRoots,
         mediaReadFile,

src/agents/agent-command.ts

@@ -479,6 +479,7 @@ async function agentCommandInternal(
       const startedAt = Date.now();
       registerAgentRunContext(runId, {
         sessionKey,
+        ...(opts.parentRunId ? { parentRunId: opts.parentRunId } : {}),
       });
       attemptExecutionRuntime.emitAcpLifecycleStart({ runId, startedAt });
 
@@ -605,6 +606,7 @@ async function agentCommandInternal(
       registerAgentRunContext(runId, {
         sessionKey,
         verboseLevel: resolvedVerboseLevel,
+        ...(opts.parentRunId ? { parentRunId: opts.parentRunId } : {}),
       });
     }