@botcord/daemon 0.2.75 → 0.2.77

package/src/gateway/__tests__/deepseek-tui-adapter.test.ts

@@ -150,6 +150,25 @@ describe("DeepseekTuiAdapter", () => {
     }
   });
 
+  it("treats DeepSeek embedded terminal events as turn completion", async () => {
+    const server = await startMockDeepseekServer({
+      events: [
+        { event: "status", data: { event: "turn.started", thread_id: "thr_test", turn_id: "turn_test" } },
+        { event: "message.delta", data: { thread_id: "thr_test", turn_id: "turn_test", content: "done" } },
+        { event: "status", data: { event: "turn.finished", thread_id: "thr_test", turn_id: "turn_test" } },
+      ],
+    });
+    try {
+      const { result, blocks, status } = runAdapter(server.baseUrl, server.token);
+      const res = await result;
+      expect(res).toEqual({ text: "done", newSessionId: server.threadId });
+      expect(blocks).toContain("assistant_text");
+      expect(status.at(-1)).toEqual({ phase: "stopped", label: undefined });
+    } finally {
+      await server.close();
+    }
+  });
+
   it("reuses an existing DeepSeek thread id and patches per-turn system context", async () => {
     const server = await startMockDeepseekServer({ threadId: "thr_existing" });
     try {

package/src/gateway/__tests__/dispatcher.test.ts

@@ -188,6 +188,23 @@ function makeEnvelope(
   return { message: makeMessage(partial), ack };
 }
 
+function cloudRunRaw(
+  budget: { max_wall_time_seconds?: number; max_tool_calls?: number },
+): Record<string, unknown> {
+  return {
+    envelope: {
+      type: "cloud_run",
+      payload: {
+        text: "run this",
+        cloud_run: {
+          run_id: "crun_test",
+          budget,
+        },
+      },
+    },
+  };
+}
+
 function baseConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
   return {
     channels: [{ id: "botcord", type: "botcord", accountId: "ag_me" }],
@@ -225,6 +242,8 @@ describe("Dispatcher", () => {
     channel?: FakeChannel;
     runtimeFactory?: RuntimeFactory;
     turnTimeoutMs?: number;
+    runtimeAuthFailureThreshold?: number;
+    runtimeAuthFailureCooldownMs?: number;
   }) {
     const { store, dir } = await makeStore();
     tempDirs.push(dir);
@@ -237,6 +256,8 @@ describe("Dispatcher", () => {
       sessionStore: store,
       log: silentLogger(),
       turnTimeoutMs: args.turnTimeoutMs,
+      runtimeAuthFailureThreshold: args.runtimeAuthFailureThreshold,
+      runtimeAuthFailureCooldownMs: args.runtimeAuthFailureCooldownMs,
     });
     return { dispatcher, channel, store };
   }
@@ -293,6 +314,51 @@ describe("Dispatcher", () => {
     expect(store.all()[0].threadId).toBe("t_1");
   });
 
+  it("cloud_run: forwards budget caps to the runtime", async () => {
+    const runtime = new FakeRuntime({ reply: "ok", newSessionId: "sid-cloud" });
+    const { dispatcher } = await scaffold({
+      runtimeFactory: () => runtime,
+    });
+
+    await dispatcher.handle(
+      makeEnvelope({
+        id: "msg_cloud_budget",
+        raw: cloudRunRaw({ max_wall_time_seconds: 12, max_tool_calls: 7 }),
+      }),
+    );
+
+    expect(runtime.calls.length).toBe(1);
+    expect(runtime.calls[0].budget).toEqual({
+      maxWallTimeMs: 12000,
+      maxToolCalls: 7,
+    });
+  });
+
+  it("cloud_run: aborts the turn when tool-call budget is exceeded", async () => {
+    const runtime = new FakeRuntime({
+      reply: "should not deliver",
+      newSessionId: "sid-budget",
+      blocks: [
+        { raw: { type: "tool", name: "one" }, kind: "tool_use", seq: 1 },
+        { raw: { type: "tool", name: "two" }, kind: "tool_use", seq: 2 },
+      ],
+    });
+    const { dispatcher, channel, store } = await scaffold({
+      runtimeFactory: () => runtime,
+    });
+
+    await dispatcher.handle(
+      makeEnvelope({
+        id: "msg_cloud_tool_budget",
+        raw: cloudRunRaw({ max_tool_calls: 1 }),
+      }),
+    );
+
+    expect(channel.sends.length).toBe(1);
+    expect(channel.sends[0].message.text).toContain("Cloud run budget exceeded");
+    expect(store.all().length).toBe(0);
+  });
+
   it("sends replies to the provider reply id when it differs from the internal message id", async () => {
     const runtime = new FakeRuntime({ reply: "ok" });
     const feishuChannel = new FakeChannel({ id: "gw_feishu_1", type: "feishu" });
@@ -394,6 +460,60 @@ describe("Dispatcher", () => {
     expect(channel.sends[0].message.type).toBe("error");
   });
 
+  it("treats auth failure text as an error and does not persist the failed session", async () => {
+    let callNo = 0;
+    const runtimeFactory: RuntimeFactory = () => {
+      callNo += 1;
+      if (callNo === 1) return new FakeRuntime({ reply: "ok", newSessionId: "sid-1" });
+      return new FakeRuntime({
+        reply: "Failed to authenticate. API Error: 403 Request not allowed",
+        newSessionId: "sid-bad",
+      });
+    };
+    const { dispatcher, store, channel } = await scaffold({ runtimeFactory });
+
+    await dispatcher.handle(
+      makeEnvelope({ id: "msg_1", conversation: { id: "rm_oc_auth", kind: "direct" } }),
+    );
+    expect(store.all()[0].runtimeSessionId).toBe("sid-1");
+
+    await dispatcher.handle(
+      makeEnvelope({ id: "msg_2", conversation: { id: "rm_oc_auth", kind: "direct" } }),
+    );
+
+    expect(store.all().length).toBe(0);
+    expect(channel.sends).toHaveLength(2);
+    expect(channel.sends[1].message.type).toBe("error");
+    expect(channel.sends[1].message.text).toContain("Runtime error");
+    expect(channel.sends[1].message.text).toContain("Failed to authenticate");
+  });
+
+  it("opens an auth circuit breaker after repeated failures and skips runtime spawn", async () => {
+    const runtime = new FakeRuntime({
+      reply: "Failed to authenticate. API Error: 403 Request not allowed",
+      newSessionId: "sid-bad",
+    });
+    const { dispatcher, channel, store } = await scaffold({
+      runtimeFactory: () => runtime,
+      runtimeAuthFailureThreshold: 2,
+      runtimeAuthFailureCooldownMs: 60_000,
+    });
+    const conversation = { id: "rm_oc_auth_breaker", kind: "direct" as const };
+
+    await dispatcher.handle(makeEnvelope({ id: "msg_1", conversation }));
+    await dispatcher.handle(makeEnvelope({ id: "msg_2", conversation }));
+    expect(runtime.calls).toHaveLength(2);
+    expect(Object.values(dispatcher.runtimeCircuitBreakers())).toHaveLength(1);
+
+    await dispatcher.handle(makeEnvelope({ id: "msg_3", conversation }));
+
+    expect(runtime.calls).toHaveLength(2);
+    expect(store.all()).toHaveLength(0);
+    expect(channel.sends).toHaveLength(3);
+    expect(channel.sends[2].message.type).toBe("error");
+    expect(channel.sends[2].message.text).toContain("dispatch paused");
+  });
+
   it("applies composeUserTurn before handing text to the runtime", async () => {
     const runtime = new FakeRuntime({ reply: "ok", newSessionId: "sid-1" });
     const { store, dir } = await makeStore();

package/src/gateway/channels/botcord.ts

@@ -43,7 +43,8 @@ type InboxDrainTrigger =
   | "ws_auth_ok"
   | "ws_inbox_update"
   | "coalesced_inbox_update"
-  | "has_more_continue";
+  | "has_more_continue"
+  | "poll_interval";
 
 /** Minimal surface the adapter needs from `BotCordClient`. Matches the subset used at runtime. */
 export interface BotCordChannelClient {
@@ -90,7 +91,7 @@ export interface BotCordChannelOptions {
   credentialsPath?: string;
   /** Override the Hub base URL. Defaults to the `hubUrl` stored in credentials. */
   hubBaseUrl?: string;
-  /** Not used by the WS-only loop today; kept for future polling fallback. */
+  /** Periodic inbox polling fallback. Set to 0 to disable. Defaults to 30s. */
   pollIntervalMs?: number;
   /** Test hook: supply a pre-built client instead of loading credentials from disk. */
   client?: BotCordChannelClient;
@@ -152,7 +153,11 @@ function defaultClientFactory(input: {
  */
 function isOwnerTrust(msg: InboxMessage): boolean {
   if (msg.room_id?.startsWith(OWNER_CHAT_PREFIX)) return true;
-  if (msg.source_type === "dashboard_user_chat") return true;
+  const sourceType = msg.source_type as string | undefined;
+  if (sourceType === "dashboard_user_chat") return true;
+  // Cloud Agent run tasks are Hub-issued on the user's behalf, same
+  // trust posture as owner chat.
+  if (sourceType === "cloud_agent_run") return true;
   return false;
 }
 
@@ -186,11 +191,20 @@ function normalizeInbox(
   if (!env) return null;
   // `message` is the normal conversational envelope; `contact_request` is
   // a lightweight inbound asking the agent to notify its owner (the
-  // composer appends the notify-owner hint). All other envelope types
-  // (notification, system, contact_added/removed, …) are still filtered
-  // out here — they belong in a separate push-notification path that
-  // daemon does not yet implement.
-  if (env.type !== "message" && env.type !== "contact_request") return null;
+  // composer appends the notify-owner hint); `cloud_run` carries a
+  // Cloud Agent run task with embedded run_id + budget (the cloud
+  // daemon's runtime adapter reads them from `raw.envelope.payload.cloud_run`
+  // and reports usage back via /internal/cloud-agents/.../settle when the
+  // run completes). All other envelope types (notification, system,
+  // contact_added/removed, …) are still filtered out — they belong in
+  // a separate push-notification path that daemon does not yet implement.
+  const envType = env.type as string;
+  if (
+    envType !== "message" &&
+    envType !== "contact_request" &&
+    envType !== "cloud_run"
+  )
+    return null;
   if (!msg.room_id) return null;
 
   const rawText =
@@ -202,8 +216,9 @@ function normalizeInbox(
 
   const isDm = msg.room_id.startsWith(DM_ROOM_PREFIX);
   const isOwnerChat = msg.room_id.startsWith(OWNER_CHAT_PREFIX);
+  const sourceType = msg.source_type as string | undefined;
   const senderKind: "user" | "agent" =
-    ownerTrust || msg.source_type === "dashboard_human_room" ? "user" : "agent";
+    ownerTrust || sourceType === "dashboard_human_room" ? "user" : "agent";
 
   const senderName = msg.source_user_name ?? undefined;
   const threadId = msg.topic_id ?? msg.topic ?? null;
@@ -482,6 +497,7 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
     let ws: WebSocket | null = null;
     let reconnectTimer: NodeJS.Timeout | null = null;
     let keepaliveTimer: NodeJS.Timeout | null = null;
+    let pollTimer: NodeJS.Timeout | null = null;
     let reconnectAttempt = 0;
     let connectionSeq = 0;
     let consecutiveAuthFailures = 0;
@@ -507,6 +523,10 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
         clearInterval(keepaliveTimer);
         keepaliveTimer = null;
       }
+      if (pollTimer) {
+        clearInterval(pollTimer);
+        pollTimer = null;
+      }
     }
 
     function markStatus(patch: Partial<ChannelStatusSnapshot>) {
@@ -709,6 +729,16 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
           });
           log.info("botcord ws authenticated", { agentId: msg.agent_id });
           void fireInbox("ws_auth_ok");
+          const pollIntervalMs = options.pollIntervalMs ?? 30_000;
+          if (pollTimer) clearInterval(pollTimer);
+          if (pollIntervalMs > 0) {
+            pollTimer = setInterval(() => {
+              if (ws === socket && socket.readyState === WebSocket.OPEN) {
+                void fireInbox("poll_interval");
+              }
+            }, pollIntervalMs);
+            pollTimer.unref?.();
+          }
           if (keepaliveTimer) clearInterval(keepaliveTimer);
           keepaliveTimer = setInterval(() => {
             if (ws === socket && socket.readyState === WebSocket.OPEN) {
@@ -978,45 +1008,25 @@ function normalizeBlockForHub(
   }
 
   if (kind === "tool_use") {
-    // Claude Code: assistant message w/ content[].type === "tool_use" → {id,name,input}
-    // Codex:       item.started for command_execution, file_change, mcp_tool_call, web_search
-    const contents = Array.isArray(raw?.message?.content) ? raw.message.content : [];
-    const tu = contents.find((c: any) => c?.type === "tool_use");
-    if (tu) {
-      payload.name = typeof tu.name === "string" ? tu.name : "tool";
-      if (tu.input && typeof tu.input === "object") payload.params = tu.input;
-      if (typeof tu.id === "string") payload.id = tu.id;
-    } else if (raw?.item && typeof raw.item === "object") {
-      payload.name = typeof raw.item.type === "string" ? raw.item.type : "tool";
-      const params = codexToolParams(raw.item);
-      if (Object.keys(params).length > 0) payload.params = params;
-      if (typeof raw.item.id === "string") payload.id = raw.item.id;
-      if (typeof raw.item.status === "string") payload.status = raw.item.status;
+    // Claude Code, Codex, DeepSeek TUI, Kimi, and ACP all expose tool calls
+    // with slightly different field names. Preserve the real invocation input
+    // so the dashboard can show more than a bare "tool" label.
+    const call = extractToolCall(raw);
+    if (call) {
+      payload.name = call.name;
+      if (call.params !== undefined && !isEmptyRecord(call.params)) payload.params = call.params;
+      if (call.id) payload.id = call.id;
+      if (call.status) payload.status = call.status;
     }
     return { kind: "tool_call", seq, payload };
   }
 
   if (kind === "tool_result") {
-    // Claude Code: {type:"user", message:{content:[{type:"tool_result",tool_use_id,content}]}}
-    // Codex:       item.completed for command_execution, file_change, mcp_tool_call, web_search
-    const contents = Array.isArray(raw?.message?.content) ? raw.message.content : [];
-    const tr = contents.find((c: any) => c?.type === "tool_result");
-    if (tr) {
-      let resultStr = "";
-      if (typeof tr.content === "string") {
-        resultStr = tr.content;
-      } else if (Array.isArray(tr.content)) {
-        resultStr = tr.content
-          .map((c: any) => (typeof c?.text === "string" ? c.text : JSON.stringify(c)))
-          .join("\n");
-      }
-      payload.result = resultStr;
-      if (typeof tr.tool_use_id === "string") payload.tool_use_id = tr.tool_use_id;
-    } else if (raw?.item && typeof raw.item === "object") {
-      payload.name = typeof raw.item.type === "string" ? raw.item.type : "tool";
-      if (typeof raw.item.id === "string") payload.tool_use_id = raw.item.id;
-      const result = codexToolResult(raw.item);
-      if (result) payload.result = result;
+    const result = extractToolResult(raw);
+    if (result) {
+      if (result.name) payload.name = result.name;
+      payload.result = result.result;
+      if (result.id) payload.tool_use_id = result.id;
     }
     return { kind: "tool_result", seq, payload };
   }
@@ -1042,6 +1052,14 @@ function normalizeBlockForHub(
   }
 
   // "other" — e.g. Claude Code `type:"result"` end-of-turn summary.
+  if (isTerminalRuntimeBlock(raw)) {
+    payload.terminal = true;
+    payload.details = formatBlockDetails(raw);
+    const event = typeof raw?.event === "string" ? raw.event : undefined;
+    const embedded = typeof raw?.payload?.event === "string" ? raw.payload.event : undefined;
+    if (event || embedded) payload.event = event ?? embedded;
+    return { kind: "other", seq, payload };
+  }
   if (raw?.type === "result") {
     if (typeof raw.result === "string") payload.text = raw.result;
     if (typeof raw.subtype === "string") payload.subtype = raw.subtype;
@@ -1050,6 +1068,203 @@ function normalizeBlockForHub(
   return { kind: "other", seq, payload };
 }
 
+function isTerminalRuntimeBlock(raw: any): boolean {
+  const event = typeof raw?.event === "string" ? raw.event : undefined;
+  const embedded = typeof raw?.payload?.event === "string" ? raw.payload.event : undefined;
+  const terminal = event ?? embedded;
+  return (
+    terminal === "turn.completed" ||
+    terminal === "turn.finished" ||
+    terminal === "turn.done" ||
+    terminal === "done"
+  );
+}
+
+function extractToolCall(raw: any): { name: string; params?: unknown; id?: string; status?: string } | null {
+  const contents = Array.isArray(raw?.message?.content) ? raw.message.content : [];
+  const tu = contents.find((c: any) => c?.type === "tool_use");
+  if (tu) {
+    return {
+      name: stringField(tu, "name") ?? "tool",
+      params: parseMaybeJson(tu.input ?? tu.arguments),
+      id: stringField(tu, "id"),
+    };
+  }
+
+  const deepseek = extractDeepseekToolCall(raw);
+  if (deepseek) return deepseek;
+
+  const item = raw?.item;
+  if (item && typeof item === "object") {
+    const params = codexToolParams(item);
+    return {
+      name: stringField(item, "type") ?? stringField(item, "name") ?? "tool",
+      params,
+      id: stringField(item, "id"),
+      status: stringField(item, "status"),
+    };
+  }
+
+  const toolCalls = Array.isArray(raw?.tool_calls) ? raw.tool_calls : [];
+  const toolCall = toolCalls.find((t: any) => t && typeof t === "object");
+  if (toolCall) {
+    const fn = toolCall.function && typeof toolCall.function === "object" ? toolCall.function : undefined;
+    return {
+      name: stringField(fn, "name") ?? stringField(toolCall, "name") ?? "tool",
+      params: parseMaybeJson(fn?.arguments ?? toolCall.arguments ?? toolCall.input ?? toolCall.rawInput),
+      id: stringField(toolCall, "id"),
+    };
+  }
+
+  const update = raw?.params?.update ?? raw?.update;
+  const acpTool = update?.toolCall ?? update?.tool_call ?? update?.tool;
+  if (acpTool && typeof acpTool === "object") {
+    return {
+      name: stringField(acpTool, "name") ?? stringField(update, "name") ?? "tool",
+      params: parseMaybeJson(
+        acpTool.rawInput ??
+          acpTool.raw_input ??
+          acpTool.input ??
+          acpTool.arguments ??
+          acpTool.args ??
+          acpTool.params,
+      ) ?? acpTool,
+      id: stringField(acpTool, "id") ?? stringField(update, "toolCallId"),
+    };
+  }
+
+  return null;
+}
+
+function extractToolResult(raw: any): { name?: string; result: string; id?: string } | null {
+  const contents = Array.isArray(raw?.message?.content) ? raw.message.content : [];
+  const tr = contents.find((c: any) => c?.type === "tool_result");
+  if (tr) {
+    return {
+      result: stringifyToolResult(tr.content),
+      id: stringField(tr, "tool_use_id"),
+    };
+  }
+
+  const deepseek = extractDeepseekToolResult(raw);
+  if (deepseek) return deepseek;
+
+  const item = raw?.item;
+  if (item && typeof item === "object") {
+    const result = codexToolResult(item);
+    return {
+      name: stringField(item, "type") ?? stringField(item, "name"),
+      result: result || stringifyToolResult(item),
+      id: stringField(item, "id"),
+    };
+  }
+
+  if (raw?.role === "tool") {
+    return {
+      result: stringifyToolResult(raw.content),
+      id: stringField(raw, "tool_call_id"),
+    };
+  }
+
+  const update = raw?.params?.update ?? raw?.update;
+  const acpTool = update?.toolCall ?? update?.tool_call ?? update?.tool;
+  if (acpTool && typeof acpTool === "object") {
+    const result =
+      acpTool.output ??
+      acpTool.result ??
+      acpTool.content ??
+      acpTool.error ??
+      update.content ??
+      update;
+    return {
+      name: stringField(acpTool, "name") ?? stringField(update, "name"),
+      result: stringifyToolResult(result),
+      id: stringField(acpTool, "id") ?? stringField(update, "toolCallId"),
+    };
+  }
+
+  return null;
+}
+
+function extractDeepseekToolCall(raw: any): { name: string; params?: unknown; id?: string; status?: string } | null {
+  const payload = raw?.payload;
+  if (!payload || typeof payload !== "object") return null;
+
+  if (raw?.event === "tool.started") {
+    const tool = payload.tool && typeof payload.tool === "object" ? payload.tool : undefined;
+    return {
+      name: stringField(payload, "name") ?? stringField(tool, "name") ?? "tool",
+      params: parseMaybeJson(payload.input ?? payload.arguments ?? payload.params ?? tool?.input ?? tool?.rawInput),
+      id: stringField(payload, "id") ?? stringField(tool, "id"),
+      status: stringField(payload, "status") ?? stringField(tool, "status"),
+    };
+  }
+
+  if (payload.event === "item.started") {
+    const inner = payload.payload && typeof payload.payload === "object" ? payload.payload : {};
+    const item = inner.item && typeof inner.item === "object" ? inner.item : undefined;
+    const tool = inner.tool && typeof inner.tool === "object" ? inner.tool : item?.tool;
+    return {
+      name:
+        stringField(tool, "name") ??
+        stringField(inner, "name") ??
+        stringField(item, "name") ??
+        stringField(item, "type") ??
+        "tool",
+      params: parseMaybeJson(
+        tool?.input ??
+          tool?.rawInput ??
+          tool?.arguments ??
+          inner.input ??
+          item?.input ??
+          item?.arguments,
+      ) ?? tool ?? item,
+      id: stringField(tool, "id") ?? stringField(inner, "id") ?? stringField(item, "id"),
+      status: stringField(tool, "status") ?? stringField(inner, "status") ?? stringField(item, "status"),
+    };
+  }
+
+  return null;
+}
+
+function extractDeepseekToolResult(raw: any): { name?: string; result: string; id?: string } | null {
+  const payload = raw?.payload;
+  if (!payload || typeof payload !== "object") return null;
+
+  if (raw?.event === "tool.completed") {
+    const result = payload.output ?? payload.result ?? payload.content ?? payload.error ?? payload;
+    return {
+      name: stringField(payload, "name"),
+      result: stringifyToolResult(result),
+      id: stringField(payload, "id"),
+    };
+  }
+
+  if (payload.event === "item.completed" || payload.event === "item.failed") {
+    const inner = payload.payload && typeof payload.payload === "object" ? payload.payload : {};
+    const item = inner.item && typeof inner.item === "object" ? inner.item : undefined;
+    const result =
+      item?.output ??
+      item?.result ??
+      item?.content ??
+      item?.detail ??
+      item?.summary ??
+      item?.error ??
+      inner.output ??
+      inner.result ??
+      inner.error ??
+      item ??
+      inner;
+    return {
+      name: stringField(item, "name") ?? stringField(item, "type") ?? stringField(inner, "name"),
+      result: stringifyToolResult(result),
+      id: stringField(item, "id") ?? stringField(inner, "id"),
+    };
+  }
+
+  return null;
+}
+
 function formatBlockDetails(raw: unknown): string {
   if (!raw || typeof raw !== "object") return "";
   const r = raw as any;
@@ -1121,6 +1336,47 @@ function codexToolResult(item: Record<string, unknown>): string {
   return parts.join("\n");
 }
 
+function stringifyToolResult(value: unknown): string {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    return value
+      .map((c: any) => {
+        if (typeof c === "string") return c;
+        if (typeof c?.text === "string") return c.text;
+        return stringifyToolResult(c);
+      })
+      .filter(Boolean)
+      .join("\n");
+  }
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+function parseMaybeJson(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  const trimmed = value.trim();
+  if (!trimmed) return value;
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return value;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return value;
+  }
+}
+
+function isEmptyRecord(value: unknown): boolean {
+  return !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0;
+}
+
+function stringField(obj: any, key: string): string | undefined {
+  const value = obj?.[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
 function extractContentText(content: unknown): string {
   if (!content) return "";
   if (typeof content === "string") return content;