@botcord/daemon 0.2.83 → 0.2.84

package/dist/cloud-daemon.js

@@ -9,7 +9,7 @@
  *
  * See ``docs/cloud-agent-technical-design.md`` §4 + §6.
  */
-import { shouldWake } from "@botcord/protocol-core";
+import { CONTROL_FRAME_TYPES, shouldWake } from "@botcord/protocol-core";
 import { Gateway, resolveTranscriptEnabled, } from "./gateway/index.js";
 import { ActivityTracker } from "./activity-tracker.js";
 import { SESSIONS_PATH, SNAPSHOT_PATH } from "./config.js";
@@ -201,10 +201,34 @@ export async function startCloudDaemon(opts) {
     if (!opts.disableControlChannel) {
         const auth = asUserAuthManager(new CloudAuthManager(cloudCfg));
         const provisionerFactory = opts.provisionerFactory ?? createProvisioner;
+        // Forward-declare controlChannel-bound emitter: the provisioner is
+        // built before the channel exists, so the closure captures the slot
+        // and reads it back lazily once cloud-daemon assigns the instance.
+        const cloudGatewayTypingEmitter = (event) => {
+            const ch = controlChannel;
+            if (!ch)
+                return;
+            ch.send({
+                id: `cgrs_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+                type: CONTROL_FRAME_TYPES.CLOUD_GATEWAY_RUNTIME_STATUS,
+                params: {
+                    eventId: event.eventId,
+                    turnId: event.turnId,
+                    gatewayId: event.gatewayId,
+                    agentId: event.agentId,
+                    conversationId: event.conversationId,
+                    kind: "typing",
+                    phase: event.phase,
+                    traceId: event.traceId ?? null,
+                },
+                ts: Date.now(),
+            });
+        };
         const provisioner = provisionerFactory({
             gateway,
             policyResolver,
             onAgentInstalled,
+            cloudGatewayTypingEmitter,
         });
         const ControlChannelCtor = opts.controlChannelFactory ?? ControlChannel;
         controlChannel = new ControlChannelCtor({

package/dist/cloud-gateway-runtime.d.ts

@@ -1,5 +1,22 @@
 import { type GatewayInboundFrame } from "@botcord/protocol-core";
 import type { Gateway, GatewayLogger } from "./gateway/index.js";
+/**
+ * Fire-and-forget hook invoked when the dispatcher signals "typing" while
+ * a cloud-gateway runtime turn is in flight. The cloud daemon wires this
+ * to a control-plane `cloud_gateway_runtime_status` push so the Hub can
+ * relay it to the ingress runtime WS and the third-party provider can
+ * render a typing indicator.
+ */
+export interface CloudGatewayTypingEvent {
+    eventId: string;
+    turnId: string;
+    gatewayId: string;
+    agentId: string;
+    conversationId: string;
+    phase: "started" | "stopped";
+    traceId?: string | null;
+}
+export type CloudGatewayTypingEmitter = (event: CloudGatewayTypingEvent) => void;
 export interface CloudGatewayRuntimeResult {
     accepted: boolean;
     eventId: string;
@@ -26,4 +43,4 @@ export interface CloudGatewayRuntimeResult {
  * gateway_outbound_complete for gateway-ingress, which then calls the real
  * provider API.
  */
-export declare function handleCloudGatewayRuntimeInbound(gateway: Gateway, frame: GatewayInboundFrame, log?: GatewayLogger): Promise<CloudGatewayRuntimeResult>;
+export declare function handleCloudGatewayRuntimeInbound(gateway: Gateway, frame: GatewayInboundFrame, log?: GatewayLogger, onTyping?: CloudGatewayTypingEmitter): Promise<CloudGatewayRuntimeResult>;

package/dist/cloud-gateway-runtime.js

@@ -9,7 +9,7 @@ import { RUNTIME_FRAME_TYPES, } from "@botcord/protocol-core";
  * gateway_outbound_complete for gateway-ingress, which then calls the real
  * provider API.
  */
-export async function handleCloudGatewayRuntimeInbound(gateway, frame, log) {
+export async function handleCloudGatewayRuntimeInbound(gateway, frame, log, onTyping) {
     if (frame.type !== RUNTIME_FRAME_TYPES.GATEWAY_INBOUND) {
         return rejected(frame, "bad_frame_type", `unsupported frame type "${frame.type}"`);
     }
@@ -25,6 +25,7 @@ export async function handleCloudGatewayRuntimeInbound(gateway, frame, log) {
     let accepted = false;
     let outboundText = null;
     let providerMessageId;
+    const turnId = `turn_${frame.event_id}`;
     const channel = createRuntimeRelayChannel({
         id: frame.gateway_id,
         provider: frame.provider,
@@ -34,6 +35,29 @@ export async function handleCloudGatewayRuntimeInbound(gateway, frame, log) {
             providerMessageId = ctx.message.traceId ?? null;
             return { providerMessageId };
         },
+        onTyping: onTyping
+            ? (ctx) => {
+                try {
+                    onTyping({
+                        eventId: frame.event_id,
+                        turnId,
+                        gatewayId: frame.gateway_id,
+                        agentId: frame.agent_id,
+                        conversationId: frame.message.conversation.id,
+                        phase: "started",
+                        traceId: ctx.traceId ?? null,
+                    });
+                }
+                catch (err) {
+                    log?.warn?.("cloud gateway typing emit failed", {
+                        eventId: frame.event_id,
+                        gatewayId: frame.gateway_id,
+                        agentId: frame.agent_id,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            : undefined,
     });
     const message = {
         ...frame.message,
@@ -67,7 +91,7 @@ export async function handleCloudGatewayRuntimeInbound(gateway, frame, log) {
         gatewayId: frame.gateway_id,
         agentId: frame.agent_id,
         conversationId: frame.message.conversation.id,
-        turnId: `turn_${frame.event_id}`,
+        turnId,
         ...(outboundText !== null
             ? {
                 outbound: {
@@ -83,7 +107,7 @@ export async function handleCloudGatewayRuntimeInbound(gateway, frame, log) {
 }
 function createRuntimeRelayChannel(opts) {
     let lastSendAt;
-    return {
+    const adapter = {
         id: opts.id,
         type: opts.provider,
         async start() {
@@ -108,6 +132,12 @@ function createRuntimeRelayChannel(opts) {
             };
         },
     };
+    if (opts.onTyping) {
+        adapter.typing = async (ctx) => {
+            opts.onTyping(ctx);
+        };
+    }
+    return adapter;
 }
 function rejected(frame, code, message) {
     return {

package/dist/provision.d.ts

@@ -4,6 +4,7 @@ import type { PolicyResolverLike } from "./gateway/policy-resolver.js";
 import type { GatewayRuntimeSnapshot } from "./gateway/index.js";
 import { type DaemonConfig } from "./config.js";
 import type { LoginSessionStore } from "./gateway/channels/login-session.js";
+import { type CloudGatewayTypingEmitter } from "./cloud-gateway-runtime.js";
 /**
  * Information passed to {@link OnAgentInstalledHook} after a successful
  * provision. Mirrors the credential fields the daemon's per-agent caches
@@ -58,6 +59,13 @@ export interface ProvisionerOptions {
      * spin up a default in-memory store.
      */
     loginSessions?: LoginSessionStore;
+    /**
+     * Optional callback invoked when an in-flight `cloud_gateway_runtime_inbound`
+     * fires a typing event. The cloud daemon wires this to its control-plane
+     * connection so the Hub can relay the hint to the live ingress runtime WS.
+     * Absent for local daemons (no ingress path).
+     */
+    cloudGatewayTypingEmitter?: CloudGatewayTypingEmitter;
 }
 /** The value a frame handler returns (minus the `id` which the channel fills in). */
 type AckBody = Omit<ControlAck, "id">;

package/dist/provision.js

@@ -20,7 +20,7 @@ import { discoverAgentCredentials } from "./agent-discovery.js";
 import { resolveMemoryDir } from "./working-memory.js";
 import { discoverRuntimeModelCatalog } from "./runtime-models.js";
 import { buildRuntimeSelectionExtraArgs, mergeRuntimeExtraArgs, } from "./runtime-route-options.js";
-import { handleCloudGatewayRuntimeInbound } from "./cloud-gateway-runtime.js";
+import { handleCloudGatewayRuntimeInbound, } from "./cloud-gateway-runtime.js";
 /**
  * Build a dispatcher function that routes a `ControlFrame` to the right
  * handler. Returned function signature matches
@@ -31,6 +31,7 @@ export function createProvisioner(opts) {
     const register = opts.register ?? BotCordClient.register;
     const policyResolver = opts.policyResolver;
     const onAgentInstalled = opts.onAgentInstalled;
+    const cloudGatewayTypingEmitter = opts.cloudGatewayTypingEmitter;
     const gatewayControl = createGatewayControl({
         gateway,
         ...(opts.loginSessions ? { loginSessions: opts.loginSessions } : {}),
@@ -286,7 +287,7 @@ export function createProvisioner(opts) {
                         },
                     };
                 }
-                const result = await handleCloudGatewayRuntimeInbound(gateway, runtimeFrame);
+                const result = await handleCloudGatewayRuntimeInbound(gateway, runtimeFrame, undefined, cloudGatewayTypingEmitter);
                 return result.accepted
                     ? { ok: true, result }
                     : {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/daemon",
-  "version": "0.2.83",
+  "version": "0.2.84",
   "description": "BotCord local daemon — bridges Hub inbox push to local Claude Code / Codex / Gemini CLIs",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@botcord/cli": "^0.1.7",
-    "@botcord/protocol-core": "^0.2.11",
+    "@botcord/protocol-core": "^0.2.12",
     "@larksuiteoapi/node-sdk": "^1.63.1",
     "ws": "^8.20.1"
   },

package/src/__tests__/cloud-gateway-runtime.test.ts

@@ -4,7 +4,10 @@ import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { RUNTIME_FRAME_TYPES, type GatewayInboundFrame } from "@botcord/protocol-core";
 
-import { handleCloudGatewayRuntimeInbound } from "../cloud-gateway-runtime.js";
+import {
+  handleCloudGatewayRuntimeInbound,
+  type CloudGatewayTypingEvent,
+} from "../cloud-gateway-runtime.js";
 import { Gateway, type ChannelAdapter } from "../gateway/index.js";
 
 describe("cloud gateway runtime inbound", () => {
@@ -66,6 +69,64 @@ describe("cloud gateway runtime inbound", () => {
     expect(result.outbound?.finalText).toBe("hello from runtime");
   });
 
+  it("invokes the typing emitter when the dispatcher fires typing.started", async () => {
+    const typingEvents: CloudGatewayTypingEvent[] = [];
+    const gateway = new Gateway({
+      config: {
+        channels: [],
+        defaultRoute: { runtime: "fake", cwd: tmpDir },
+      },
+      sessionStorePath: path.join(tmpDir, "sessions.json"),
+      createChannel: (cfg) => stubChannel(cfg.id, cfg.type, cfg.accountId),
+      createRuntime: () => ({
+        id: "fake",
+        async run() {
+          return { text: "ok", newSessionId: "sess_typing" };
+        },
+      }),
+      transcriptEnabled: false,
+    });
+    await gateway.start();
+
+    const frame: GatewayInboundFrame = {
+      type: RUNTIME_FRAME_TYPES.GATEWAY_INBOUND,
+      event_id: "evt_typing",
+      gateway_id: "gw_wc_1",
+      agent_id: "ag_typing",
+      provider: "wechat",
+      message: {
+        id: "wechat:alice:t1",
+        channel: "gw_wc_1",
+        accountId: "ag_typing",
+        conversation: { id: "wechat:user:alice", kind: "direct" },
+        sender: { id: "wechat:user:alice", kind: "user" },
+        text: "ping",
+        replyTo: null,
+        mentioned: true,
+        receivedAt: Date.now(),
+        trace: { id: "wechat:alice:t1", streamable: false },
+      },
+    };
+
+    const result = await handleCloudGatewayRuntimeInbound(
+      gateway,
+      frame,
+      undefined,
+      (event) => typingEvents.push(event),
+    );
+    await gateway.stop("test");
+
+    expect(result.accepted).toBe(true);
+    expect(typingEvents.length).toBeGreaterThanOrEqual(1);
+    const first = typingEvents[0]!;
+    expect(first.eventId).toBe("evt_typing");
+    expect(first.gatewayId).toBe("gw_wc_1");
+    expect(first.agentId).toBe("ag_typing");
+    expect(first.conversationId).toBe("wechat:user:alice");
+    expect(first.phase).toBe("started");
+    expect(first.traceId).toBe("wechat:alice:t1");
+  });
+
   it("rejects frames outside the token scope", async () => {
     const gateway = new Gateway({
       config: {

package/src/cloud-daemon.ts

@@ -9,7 +9,8 @@
  *
  * See ``docs/cloud-agent-technical-design.md`` §4 + §6.
  */
-import { shouldWake, type AttentionPolicy } from "@botcord/protocol-core";
+import { CONTROL_FRAME_TYPES, shouldWake, type AttentionPolicy } from "@botcord/protocol-core";
+import type { CloudGatewayTypingEmitter } from "./cloud-gateway-runtime.js";
 import {
   Gateway,
   resolveTranscriptEnabled,
@@ -284,10 +285,33 @@ export async function startCloudDaemon(
   if (!opts.disableControlChannel) {
     const auth = asUserAuthManager(new CloudAuthManager(cloudCfg));
     const provisionerFactory = opts.provisionerFactory ?? createProvisioner;
+    // Forward-declare controlChannel-bound emitter: the provisioner is
+    // built before the channel exists, so the closure captures the slot
+    // and reads it back lazily once cloud-daemon assigns the instance.
+    const cloudGatewayTypingEmitter: CloudGatewayTypingEmitter = (event) => {
+      const ch = controlChannel;
+      if (!ch) return;
+      ch.send({
+        id: `cgrs_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+        type: CONTROL_FRAME_TYPES.CLOUD_GATEWAY_RUNTIME_STATUS,
+        params: {
+          eventId: event.eventId,
+          turnId: event.turnId,
+          gatewayId: event.gatewayId,
+          agentId: event.agentId,
+          conversationId: event.conversationId,
+          kind: "typing",
+          phase: event.phase,
+          traceId: event.traceId ?? null,
+        },
+        ts: Date.now(),
+      });
+    };
     const provisioner = provisionerFactory({
       gateway,
       policyResolver,
       onAgentInstalled,
+      cloudGatewayTypingEmitter,
     });
     const ControlChannelCtor = opts.controlChannelFactory ?? ControlChannel;
     controlChannel = new ControlChannelCtor({

package/src/cloud-gateway-runtime.ts

@@ -8,11 +8,31 @@ import type {
   ChannelSendContext,
   ChannelSendResult,
   ChannelStatusSnapshot,
+  ChannelTypingContext,
   Gateway,
   GatewayInboundMessage,
   GatewayLogger,
 } from "./gateway/index.js";
 
+/**
+ * Fire-and-forget hook invoked when the dispatcher signals "typing" while
+ * a cloud-gateway runtime turn is in flight. The cloud daemon wires this
+ * to a control-plane `cloud_gateway_runtime_status` push so the Hub can
+ * relay it to the ingress runtime WS and the third-party provider can
+ * render a typing indicator.
+ */
+export interface CloudGatewayTypingEvent {
+  eventId: string;
+  turnId: string;
+  gatewayId: string;
+  agentId: string;
+  conversationId: string;
+  phase: "started" | "stopped";
+  traceId?: string | null;
+}
+
+export type CloudGatewayTypingEmitter = (event: CloudGatewayTypingEvent) => void;
+
 export interface CloudGatewayRuntimeResult {
   accepted: boolean;
   eventId: string;
@@ -44,6 +64,7 @@ export async function handleCloudGatewayRuntimeInbound(
   gateway: Gateway,
   frame: GatewayInboundFrame,
   log?: GatewayLogger,
+  onTyping?: CloudGatewayTypingEmitter,
 ): Promise<CloudGatewayRuntimeResult> {
   if (frame.type !== RUNTIME_FRAME_TYPES.GATEWAY_INBOUND) {
     return rejected(frame, "bad_frame_type", `unsupported frame type "${frame.type}"`);
@@ -61,6 +82,7 @@ export async function handleCloudGatewayRuntimeInbound(
   let accepted = false;
   let outboundText: string | null = null;
   let providerMessageId: string | null | undefined;
+  const turnId = `turn_${frame.event_id}`;
   const channel = createRuntimeRelayChannel({
     id: frame.gateway_id,
     provider: frame.provider,
@@ -70,6 +92,28 @@ export async function handleCloudGatewayRuntimeInbound(
       providerMessageId = ctx.message.traceId ?? null;
       return { providerMessageId };
     },
+    onTyping: onTyping
+      ? (ctx) => {
+          try {
+            onTyping({
+              eventId: frame.event_id,
+              turnId,
+              gatewayId: frame.gateway_id,
+              agentId: frame.agent_id,
+              conversationId: frame.message.conversation.id,
+              phase: "started",
+              traceId: ctx.traceId ?? null,
+            });
+          } catch (err) {
+            log?.warn?.("cloud gateway typing emit failed", {
+              eventId: frame.event_id,
+              gatewayId: frame.gateway_id,
+              agentId: frame.agent_id,
+              error: err instanceof Error ? err.message : String(err),
+            });
+          }
+        }
+      : undefined,
   });
 
   const message: GatewayInboundMessage = {
@@ -105,7 +149,7 @@ export async function handleCloudGatewayRuntimeInbound(
     gatewayId: frame.gateway_id,
     agentId: frame.agent_id,
     conversationId: frame.message.conversation.id,
-    turnId: `turn_${frame.event_id}`,
+    turnId,
     ...(outboundText !== null
       ? {
           outbound: {
@@ -125,9 +169,10 @@ function createRuntimeRelayChannel(opts: {
   provider: string;
   accountId: string;
   onSend: (ctx: ChannelSendContext) => Promise<ChannelSendResult>;
+  onTyping?: (ctx: ChannelTypingContext) => void;
 }): ChannelAdapter {
   let lastSendAt: number | undefined;
-  return {
+  const adapter: ChannelAdapter = {
     id: opts.id,
     type: opts.provider,
     async start() {
@@ -152,6 +197,12 @@ function createRuntimeRelayChannel(opts: {
       };
     },
   };
+  if (opts.onTyping) {
+    adapter.typing = async (ctx) => {
+      opts.onTyping!(ctx);
+    };
+  }
+  return adapter;
 }
 
 function rejected(

package/src/provision.ts

@@ -78,7 +78,10 @@ import {
   buildRuntimeSelectionExtraArgs,
   mergeRuntimeExtraArgs,
 } from "./runtime-route-options.js";
-import { handleCloudGatewayRuntimeInbound } from "./cloud-gateway-runtime.js";
+import {
+  handleCloudGatewayRuntimeInbound,
+  type CloudGatewayTypingEmitter,
+} from "./cloud-gateway-runtime.js";
 
 /**
  * Information passed to {@link OnAgentInstalledHook} after a successful
@@ -136,6 +139,13 @@ export interface ProvisionerOptions {
    * spin up a default in-memory store.
    */
   loginSessions?: LoginSessionStore;
+  /**
+   * Optional callback invoked when an in-flight `cloud_gateway_runtime_inbound`
+   * fires a typing event. The cloud daemon wires this to its control-plane
+   * connection so the Hub can relay the hint to the live ingress runtime WS.
+   * Absent for local daemons (no ingress path).
+   */
+  cloudGatewayTypingEmitter?: CloudGatewayTypingEmitter;
 }
 
 /** The value a frame handler returns (minus the `id` which the channel fills in). */
@@ -153,6 +163,7 @@ export function createProvisioner(opts: ProvisionerOptions): (
   const register = opts.register ?? BotCordClient.register;
   const policyResolver = opts.policyResolver;
   const onAgentInstalled = opts.onAgentInstalled;
+  const cloudGatewayTypingEmitter = opts.cloudGatewayTypingEmitter;
   const gatewayControl = createGatewayControl({
     gateway,
     ...(opts.loginSessions ? { loginSessions: opts.loginSessions } : {}),
@@ -440,7 +451,12 @@ export function createProvisioner(opts: ProvisionerOptions): (
             },
           };
         }
-        const result = await handleCloudGatewayRuntimeInbound(gateway, runtimeFrame);
+        const result = await handleCloudGatewayRuntimeInbound(
+          gateway,
+          runtimeFrame,
+          undefined,
+          cloudGatewayTypingEmitter,
+        );
         return result.accepted
           ? { ok: true, result }
           : {