@chorus-aidlc/chorus-openclaw-plugin 0.5.3 → 0.11.0

package/src/index.ts

@@ -5,9 +5,15 @@ import { resolveConfig, validateConfigWithWarnings } from "./config.js";
 import { ensureChorusMcpServer } from "./mcp-registration.js";
 import { ChorusMcpClient } from "./mcp-client.js";
 import { ChorusSseListener } from "./sse-listener.js";
-import { ChorusEventRouter } from "./event-router.js";
-import { createWake } from "./wake.js";
+import { ChorusEventRouter, type WakeAttribution } from "./event-router.js";
+import { resolveWakeRunContext } from "./wake.js";
 import { registerChorusCommands } from "./commands.js";
+import { ConnectionState } from "./connection-state.js";
+import { createControlHandler, type ControlBehaviorHooks } from "./control-handler.js";
+import { createDaemonRestClient } from "./daemon-rest-client.js";
+import { LineageResolver } from "./lineage.js";
+import { OpenClawDaemonClient, type WakeRequest } from "./daemon-client.js";
+import type { DaemonPendingTurn } from "./daemon-rest-client.js";
 
 /**
  * JSON-Schema config contract for the Chorus plugin.
@@ -70,15 +76,97 @@ export default definePluginEntry({
     //    assignments, notifications back-fill).
     const mcpClient = new ChorusMcpClient({ chorusUrl, apiKey, logger });
 
-    // 5. Event router. Wakes the agent in-process by running an embedded agent
-    //    turn via `api.runtime.agent.runEmbeddedAgent` (see wake.ts). `createWake`
-    //    resolves the main agent session + configured model on each wake and
-    //    gracefully DROPS (logs + returns) when it cannot run — it never throws,
-    //    so the SSE service stays alive even on a host that exposes no session.
+    // 4b. Connection identity + reverse control channel + daemon reporting (parity).
+    //     `connectionState` holds the DaemonConnection uuid the server reports
+    //     post-handshake (captured by the listener's onConnectionId); it is the
+    //     single source of truth for "which connection am I", read by the control
+    //     handler's double-check AND the daemon REST reporter (lazily, so order
+    //     doesn't matter — both predate the handshake).
+    const connectionState = new ConnectionState();
+
+    //     The shared pure-REST daemon client owns the `/api/daemon/*` payload shapes
+    //     (turn-advance / transcript / execution-state / report-interrupt /
+    //     pending-turns). It reads the connectionUuid lazily from connectionState.
+    const restClient = createDaemonRestClient({
+      url: chorusUrl,
+      apiKey,
+      getConnectionUuid: () => connectionState.getConnectionUuid(),
+      logger,
+    });
+
+    //     Lineage resolver: per-notification { rootIdeaUuid, directIdeaUuid } via the
+    //     root-idea REST endpoint, so the daemon client anchors the session on the
+    //     DIRECT idea (resume/deliver_turn continuity) and reports the ROOT idea in
+    //     its execution snapshot (the two-id contract).
+    const lineage = new LineageResolver({ url: chorusUrl, apiKey, logger });
+
+    //     The in-process daemon client wraps runEmbeddedAgent with full reporting,
+    //     the AbortController registry (real mid-run interrupt), the execution
+    //     snapshot source, deterministic session-key mapping, and the at-most-once
+    //     pending-turns backfill. `resolveRunContext` is the ONE place that reaches
+    //     into api.config/api.runtime (kept out of the client so it stays testable).
+    //     `redispatch` resolves lineage for a synthetic resume so it continues the
+    //     SAME session, then runs the wake; a delivered turn already carries its ids.
+    let daemonClient: OpenClawDaemonClient;
+    const redispatch = (req: WakeRequest): void => {
+      void (async () => {
+        let enriched = req;
+        // A resume only knows the entity — resolve its lineage so the wake anchors on
+        // the same business key (direct idea) the original run used. A delivered turn
+        // already carries directIdeaUuid, so we skip the round-trip when present.
+        if (req.directIdeaUuid == null && req.entityType && req.entityUuid) {
+          try {
+            const { rootIdeaUuid, directIdeaUuid } = await lineage.resolve({
+              entityType: req.entityType,
+              entityUuid: req.entityUuid,
+            });
+            enriched = { ...req, rootIdeaUuid, directIdeaUuid };
+          } catch (err) {
+            logger.warn(`[Chorus] resume lineage resolve failed: ${err}`);
+          }
+        }
+        await daemonClient.runWake(enriched);
+      })();
+    };
+    daemonClient = new OpenClawDaemonClient({
+      restClient,
+      resolveRunContext: () => resolveWakeRunContext(api, logger),
+      redispatch,
+      // Build the prompt for a delivered human_instruction turn. The free-text body
+      // lives only on the turn (promptText); fall back to a generic nudge if absent.
+      buildTurnPrompt: (turn: DaemonPendingTurn) =>
+        turn.promptText && turn.promptText.trim()
+          ? `[Chorus] A human sent you an instruction in this conversation:\n\n${turn.promptText}`
+          : `[Chorus] A human sent you a new instruction in this conversation (session ${turn.sessionId}). Review the latest comments and respond.`,
+      logger,
+    });
+
+    //     The control handler ROUTES verified control commands to the daemon client's
+    //     behavior hooks (real abort / resume re-dispatch / pending-turns sweep),
+    //     after its own double-check (own connection + held entity).
+    const controlHooks: ControlBehaviorHooks = daemonClient.controlHooks;
+    const onControl = createControlHandler({ connectionState, hooks: controlHooks, logger });
+
+    // 5. Event router. Wakes the agent in-process by running an embedded agent turn
+    //    via the daemon client (which calls api.runtime.agent.runEmbeddedAgent and
+    //    reports lifecycle/transcript). The router resolves each notification's
+    //    lineage, then the daemon client's runWake gracefully DROPS (logs + returns)
+    //    when it cannot run — it never throws, so the SSE service stays alive.
+    const wakeFn = (message: string, contextKey: string, attribution?: WakeAttribution): void => {
+      void daemonClient.runWake({
+        prompt: message,
+        contextKey,
+        entityType: attribution?.entityType,
+        entityUuid: attribution?.entityUuid,
+        directIdeaUuid: attribution?.directIdeaUuid,
+        rootIdeaUuid: attribution?.rootIdeaUuid,
+      });
+    };
     const eventRouter = new ChorusEventRouter({
       mcpClient,
       logger,
-      wake: createWake(api, logger),
+      lineage,
+      wake: wakeFn,
     });
 
     // 6. Background SSE service. The SSE socket opens only inside start(), which
@@ -92,7 +180,23 @@ export default definePluginEntry({
           apiKey,
           logger,
           onEvent: (event) => eventRouter.dispatch(event),
+          // Capture (and refresh on reconnect) the DaemonConnection identity the
+          // server reports post-handshake. NOT a wake — forked by the listener.
+          onConnectionId: (connectionUuid) => {
+            connectionState.setConnectionUuid(connectionUuid);
+            logger.info(`[Chorus] registered as daemon connection ${connectionUuid}`);
+          },
+          // Reverse control channel. The handler does the double-check and routes
+          // to the behavior hooks — NEVER the wake path.
+          onControl,
           onReconnect: async () => {
+            // (1) Notification backfill — re-pull unread notifications missed during
+            //     the gap (autonomous wakes). (2) Pending-turns backfill — re-derive
+            //     this connection's unstarted human_instruction turns from the turn
+            //     table and run each (the lost-deliver_turn-ping safety net). The two
+            //     share the daemon client's seen-set so a turn is run at most once
+            //     across live delivery + backfill. Each swallows its own errors so one
+            //     failing source never aborts the other.
             try {
               const result = (await mcpClient.callTool("chorus_get_notifications", {
                 status: "unread",
@@ -105,6 +209,7 @@ export default definePluginEntry({
             } catch (err) {
               logger.warn(`Failed to back-fill notifications: ${err}`);
             }
+            await daemonClient.onReconnect();
           },
         });
         await sseListener.connect();

package/src/lineage.ts

@@ -0,0 +1,157 @@
+// packages/openclaw-plugin/src/lineage.ts
+// Resolves any inbound Chorus notification/entity to its idea attribution, so the
+// OpenClaw daemon client can anchor ONE embedded-agent session per DIRECT idea (the
+// in-process analog of `claude --resume <directIdeaUuid>`) while reporting the ROOT
+// idea in its execution snapshot for observability.
+//
+// TS mirror of `cli/lineage.mjs` (`LineageResolver`) — same single-source-of-truth
+// REST contract, re-stated in TS because the plugin publishes standalone (it cannot
+// import a file under `cli/`; see daemon-rest-client.ts for the same rationale).
+//
+// Resolution is fully SERVER-SIDE: every entity is resolved by a single call to the
+// standalone REST endpoint
+//   GET /api/entities/{type}/{uuid}/root-idea   (Bearer <cho_ agent key>)
+// which returns BOTH `rootIdeaUuid` (topmost ancestor) and `directIdeaUuid` (the
+// first idea node on the lineage). There is intentionally NO client-side lineage
+// walk. On any failure (unreachable server, non-2xx, malformed body) it returns both
+// ids as null so the caller falls back to a per-entity session key — "no idea
+// ancestor" is a normal, non-fatal outcome. Uses global fetch (Node 18+) → no new dep.
+
+export interface LineageLogger {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+}
+
+const NOOP_LOGGER: LineageLogger = { info() {}, warn() {}, error() {} };
+
+/** The idea attribution of an entity. Both null when there's no idea ancestor. */
+export interface LineageAttribution {
+  rootIdeaUuid: string | null;
+  directIdeaUuid: string | null;
+}
+
+const NONE: LineageAttribution = { rootIdeaUuid: null, directIdeaUuid: null };
+
+export interface LineageResolverOptions {
+  /** Chorus base URL. */
+  url: string;
+  /** `cho_` agent API key. */
+  apiKey: string;
+  logger?: LineageLogger;
+  /** Injectable for tests (defaults to global fetch). */
+  fetchImpl?: typeof fetch;
+}
+
+export class LineageResolver {
+  private readonly url: string;
+  private readonly apiKey: string;
+  private readonly logger: LineageLogger;
+  private readonly fetchImpl: typeof fetch;
+  /** Per-run cache keyed by `${type}:${uuid}` so repeats single-flight. */
+  private readonly cache = new Map<string, LineageAttribution>();
+
+  constructor(opts: LineageResolverOptions) {
+    this.url = opts.url.replace(/\/$/, "");
+    this.apiKey = opts.apiKey;
+    this.logger = opts.logger ?? NOOP_LOGGER;
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  }
+
+  /**
+   * Resolve an entity to its idea attribution `{ rootIdeaUuid, directIdeaUuid }`.
+   * One REST call per entity; the cache single-flights repeats. On any failure both
+   * ids are null (caller falls back to a per-entity key). Never throws.
+   */
+  async resolve(event: {
+    entityType?: string;
+    entityUuid?: string;
+  }): Promise<LineageAttribution> {
+    const entityType = event?.entityType;
+    const entityUuid = event?.entityUuid;
+    if (!entityType || !entityUuid) {
+      this.logger.warn("[Chorus] lineage: event missing entityType/entityUuid");
+      return NONE;
+    }
+    // An ad-hoc conversation (`daemon_session`) has NO idea ancestor by definition,
+    // and the root-idea endpoint does not accept it (it would 400). Short-circuit to
+    // the null attribution the caller would fall back to anyway — avoiding a
+    // guaranteed-failing round-trip + a spurious warn on every ad-hoc resume. The
+    // caller then anchors the session on the entity uuid (= the ad-hoc sessionId).
+    if (entityType === "daemon_session") {
+      return NONE;
+    }
+    const cacheKey = `${entityType}:${entityUuid}`;
+    const cached = this.cache.get(cacheKey);
+    if (cached) return cached;
+
+    const result = await this.resolveViaServer(entityType, entityUuid);
+    this.cache.set(cacheKey, result);
+    return result;
+  }
+
+  /**
+   * Call GET /api/entities/{type}/{uuid}/root-idea and return
+   * `{ rootIdeaUuid, directIdeaUuid }` (each string | null). Returns both null on any
+   * error so the caller degrades to a per-entity session key — never throws.
+   */
+  private async resolveViaServer(
+    entityType: string,
+    entityUuid: string,
+  ): Promise<LineageAttribution> {
+    const endpoint =
+      `${this.url}/api/entities/${encodeURIComponent(entityType)}/` +
+      `${encodeURIComponent(entityUuid)}/root-idea`;
+    let response: Response;
+    try {
+      response = await this.fetchImpl(endpoint, {
+        headers: { Authorization: `Bearer ${this.apiKey}`, Accept: "application/json" },
+      });
+    } catch (err) {
+      this.logger.warn(`[Chorus] lineage: request failed for ${entityType}:${entityUuid}: ${err}`);
+      return NONE;
+    }
+    if (!response.ok) {
+      this.logger.warn(
+        `[Chorus] lineage: server returned ${response.status} for ${entityType}:${entityUuid}`,
+      );
+      return NONE;
+    }
+    let body: unknown;
+    try {
+      body = await response.json();
+    } catch (err) {
+      this.logger.warn(`[Chorus] lineage: bad JSON for ${entityType}:${entityUuid}: ${err}`);
+      return NONE;
+    }
+    // API envelope: { success: true, data: { rootIdeaUuid, directIdeaUuid, ... } }.
+    const data =
+      body && typeof body === "object" ? (body as { data?: unknown }).data : undefined;
+    if (!data || typeof data !== "object" || !("rootIdeaUuid" in data)) {
+      this.logger.warn(
+        `[Chorus] lineage: unexpected response shape for ${entityType}:${entityUuid}`,
+      );
+      return NONE;
+    }
+    const root = (data as { rootIdeaUuid: unknown }).rootIdeaUuid;
+    if (root !== null && typeof root !== "string") {
+      this.logger.warn(`[Chorus] lineage: non-string rootIdeaUuid for ${entityType}:${entityUuid}`);
+      return NONE;
+    }
+    // directIdeaUuid is the session anchor. Older servers may omit it: treat a
+    // missing/non-string value as null so the caller falls back to a per-entity key.
+    const directRaw = (data as { directIdeaUuid?: unknown }).directIdeaUuid;
+    const direct = typeof directRaw === "string" ? directRaw : null;
+    if (directRaw !== undefined && directRaw !== null && typeof directRaw !== "string") {
+      this.logger.warn(
+        `[Chorus] lineage: non-string directIdeaUuid for ${entityType}:${entityUuid}`,
+      );
+    }
+    const resolvedVia = (data as { resolvedVia?: unknown }).resolvedVia;
+    this.logger.info(
+      `[Chorus] lineage: ${entityType}:${entityUuid} → root ${root ?? "none"}, direct ${direct ?? "none"}` +
+        (typeof resolvedVia === "string" ? ` (${resolvedVia})` : ""),
+    );
+    return { rootIdeaUuid: root, directIdeaUuid: direct };
+  }
+}

package/src/mcp-registration.ts

@@ -86,25 +86,12 @@ export async function ensureChorusMcpServer(
   const desired = buildDesiredEntry(cfg.chorusUrl!, cfg.apiKey!);
 
   try {
-    // `api.runtime` is permissively typed via the SDK shim; narrow to the
-    // config surface we use (current() + mutateConfigFile). At runtime the host
-    // provides the real `PluginRuntimeCore.config` API
-    // (../openclaw/src/plugins/runtime/types-core.ts:145).
-    const runtimeConfig = (
-      api.runtime as
-        | {
-            config?: {
-              current?: () => { mcp?: { servers?: Record<string, unknown> } } | undefined;
-              mutateConfigFile?: (params: {
-                afterWrite: { mode: "auto" };
-                mutate: (draft: {
-                  mcp?: { servers?: Record<string, unknown> };
-                }) => void;
-              }) => Promise<unknown>;
-            };
-          }
-        | undefined
-    )?.config;
+    // `api.runtime` is now typed (`OpenClawPluginRuntime`) via the SDK shim; its
+    // `config` slice mirrors the real `PluginRuntimeCore.config` API
+    // (../openclaw/src/plugins/runtime/types-core.ts:145) — `current()` reads the
+    // live snapshot, `mutateConfigFile(...)` writes the `mcp.servers.chorus`
+    // entry. No `unknown` cast needed.
+    const runtimeConfig = api.runtime?.config;
 
     if (!runtimeConfig?.mutateConfigFile) {
       logger.error(

package/src/openclaw-sdk.d.ts

@@ -42,11 +42,236 @@ declare module "openclaw/plugin-sdk/plugin-entry" {
     jsonSchema?: Record<string, unknown>;
   };
 
+  // ===========================================================================
+  // Runtime SDK surface (`api.runtime`) — typed against the REAL ../openclaw
+  // source so the daemon call sites are compile-time checked rather than
+  // `unknown`-cast. We declare ONLY the minimal slice the plugin consumes; the
+  // full `PluginRuntime` graph (subagent/nodes/channel/media/...) is not pulled
+  // in. Every shape below was verified field-by-field against the real source
+  // (file:line citations inline) — NOT from memory.
+  //
+  // WHY HAND-DECLARED (not imported from `openclaw/plugin-sdk`): the real
+  // package exports `./plugin-sdk` (package.json exports map) but NOT the
+  // `./plugin-sdk/plugin-entry` subpath this plugin imports, and the `openclaw`
+  // build resolvable in this workspace is an older 2026.3.x that lacks both.
+  // Importing the real defs would also couple this separately-published package
+  // to the full `openclaw` type graph (llm-core, markdown-core, …) and turn the
+  // peer into a build-time hard dependency. The plugin must build/pack
+  // standalone (peerDependencies.openclaw only), so we mirror the minimal slice.
+  // ===========================================================================
+
+  /**
+   * `BlockReplyPayload` — payload for the `onBlockReply` streaming callback.
+   * Verified: ../openclaw/src/agents/embedded-agent-payloads.ts:1-11.
+   * The plugin's transcript reporter reads only `.text`.
+   */
+  export type OpenClawBlockReplyPayload = {
+    text?: string;
+    mediaUrls?: string[];
+    audioAsVoice?: boolean;
+    trustedLocalMedia?: boolean;
+    sensitiveMedia?: boolean;
+    isReasoning?: boolean;
+    replyToId?: string;
+    replyToTag?: boolean;
+    replyToCurrent?: boolean;
+  };
+
+  /**
+   * `ReplyPayload` (subset) — payload for the `onToolResult` streaming callback.
+   * Verified: ../openclaw/src/auto-reply/reply-payload.ts:7-60 (only the fields
+   * the plugin may read are declared; the rest of the large union is omitted via
+   * the index signature).
+   */
+  export type OpenClawReplyPayload = {
+    text?: string;
+    mediaUrl?: string;
+    mediaUrls?: string[];
+    isError?: boolean;
+    isReasoning?: boolean;
+    isReasoningSnapshot?: boolean;
+    channelData?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+
+  /**
+   * What initiated an embedded run.
+   * Verified: ../openclaw/src/agents/embedded-agent-runner/run/params.ts:32
+   * (`EmbeddedRunTrigger`).
+   */
+  export type OpenClawEmbeddedRunTrigger =
+    | "cron"
+    | "heartbeat"
+    | "manual"
+    | "memory"
+    | "overflow"
+    | "user";
+
+  /**
+   * Params for `runtime.agent.runEmbeddedAgent`.
+   *
+   * The real `RunEmbeddedAgentParams` has ~100 fields, almost all optional;
+   * verified against ../openclaw/src/agents/embedded-agent-runner/run/params.ts.
+   * We declare exactly the fields the plugin passes/uses (required ones with
+   * their real required/optional-ness) plus the daemon-parity fields
+   * (`abortSignal` + per-message streaming callbacks) the dependent tasks
+   * consume, and keep an index signature for the untouched remainder so the
+   * type stays a faithful subset rather than a closed shape.
+   *
+   * Required-field cites (params.ts): sessionId:40, sessionFile:104,
+   * workspaceDir:105, prompt:111, timeoutMs:155, runId:166.
+   * Optional-field cites: sessionKey:41, agentId:46, trigger:51, agentDir:108,
+   * config:109, provider:122, model:123, disableMessageTool:91,
+   * runTimeoutOverrideMs:165, abortSignal:167, onAssistantMessageStart:190,
+   * onBlockReply:191, onReasoningStream:195-199, onToolResult:201.
+   */
+  export type RunEmbeddedAgentParams = {
+    sessionId: string;
+    sessionFile: string;
+    workspaceDir: string;
+    prompt: string;
+    timeoutMs: number;
+    runId: string;
+    sessionKey?: string;
+    agentId?: string;
+    trigger?: OpenClawEmbeddedRunTrigger;
+    agentDir?: string;
+    // The real type is `OpenClawConfig`; the plugin passes through the opaque
+    // `api.config` snapshot, so `unknown` keeps it pass-through-safe.
+    config?: unknown;
+    provider?: string;
+    model?: string;
+    disableMessageTool?: boolean;
+    runTimeoutOverrideMs?: number;
+    /** Cooperative mid-run interrupt; relayed through the whole run. (params.ts:167) */
+    abortSignal?: AbortSignal;
+    /** Fires when the assistant begins a message. (params.ts:190) */
+    onAssistantMessageStart?: () => void | Promise<void>;
+    /** Fires per finalized assistant text block — the transcript source. (params.ts:191) */
+    onBlockReply?: (payload: OpenClawBlockReplyPayload) => void | Promise<void>;
+    /** Fires for reasoning/thinking deltas; NOT posted to the transcript. (params.ts:195) */
+    onReasoningStream?: (payload: {
+      text?: string;
+      mediaUrls?: string[];
+      isReasoningSnapshot?: boolean;
+    }) => void | Promise<void>;
+    /** Fires per tool result. (params.ts:201) */
+    onToolResult?: (payload: OpenClawReplyPayload) => void | Promise<void>;
+    // The real type carries many more optional fields; allow them without
+    // re-declaring the full graph.
+    [key: string]: unknown;
+  };
+
+  /**
+   * Result of `runtime.agent.runEmbeddedAgent`.
+   * Verified: ../openclaw/src/agents/embedded-agent-runner/types.ts:179-212
+   * (`EmbeddedAgentRunResult`) and its `meta: EmbeddedAgentRunMeta` at :137-177.
+   * The plugin reads `meta.aborted` to distinguish a user-abort from a crash.
+   */
+  export type EmbeddedAgentRunMeta = {
+    durationMs: number;
+    /** True when the run was aborted via `abortSignal`. (types.ts:140) */
+    aborted?: boolean;
+    finalAssistantVisibleText?: string;
+    stopReason?: string;
+    [key: string]: unknown;
+  };
+  export type EmbeddedAgentRunResult = {
+    meta: EmbeddedAgentRunMeta;
+    payloads?: Array<{ text?: string; isError?: boolean; isReasoning?: boolean }>;
+    [key: string]: unknown;
+  };
+
+  /**
+   * Session store entry (subset).
+   * Verified: ../openclaw/src/config/sessions/types.ts — `sessionId:254`,
+   * `sessionFile?:256`. Returned by `getSessionEntry`.
+   */
+  export type OpenClawSessionEntry = {
+    sessionId: string;
+    sessionFile?: string;
+    [key: string]: unknown;
+  };
+
+  /**
+   * The `runtime.agent` slice the plugin consumes.
+   * Verified: ../openclaw/src/plugins/runtime/types-core.ts:180-221
+   * (`PluginRuntimeCore.agent`). Each member's signature confirmed at its real
+   * definition site (cited per member).
+   */
+  export type OpenClawRuntimeAgent = {
+    /** params.ts/run.ts:458 — `(params) => Promise<EmbeddedAgentRunResult>`. */
+    runEmbeddedAgent: (params: RunEmbeddedAgentParams) => Promise<EmbeddedAgentRunResult>;
+    /** agent-scope-config.ts:195 — positional `(cfg, agentId)`, returns the agent dir. */
+    resolveAgentDir: (cfg: unknown, agentId: string) => string;
+    /** agent-scope-config.ts:170 — positional `(cfg, agentId)`, returns the workspace dir. */
+    resolveAgentWorkspaceDir: (cfg: unknown, agentId: string) => string;
+    /** timeout.ts:15 — options-object `({ cfg }) => number`. */
+    resolveAgentTimeoutMs: (opts: {
+      cfg?: unknown;
+      overrideMs?: number | null;
+      overrideSeconds?: number | null;
+      minMs?: number;
+    }) => number;
+    session: {
+      /** store.ts:210 — `({ sessionKey, agentId? }) => SessionEntry | undefined`. */
+      getSessionEntry: (options: {
+        sessionKey: string;
+        agentId?: string;
+        env?: NodeJS.ProcessEnv;
+        storePath?: string;
+      }) => OpenClawSessionEntry | undefined;
+      /** paths.ts:267 — `(sessionId, entry?, opts?) => string`. */
+      resolveSessionFilePath: (
+        sessionId: string,
+        entry?: { sessionFile?: string },
+        opts?: { agentId?: string; sessionsDir?: string },
+      ) => string;
+      [key: string]: unknown;
+    };
+    [key: string]: unknown;
+  };
+
+  /**
+   * The `runtime.config` slice the plugin consumes (MCP-server registration).
+   * Verified: ../openclaw/src/plugins/runtime/types-core.ts:145-178
+   * (`PluginRuntimeCore.config`). The plugin uses `current()` to read the live
+   * config snapshot and `mutateConfigFile(...)` to write the `mcp.servers.chorus`
+   * entry; the real `mutateConfigFile` is generic — `mutate(draft)` mutates a
+   * `DeepReadonly`-cloned draft in place. We narrow `draft`/return to the MCP
+   * slice the plugin touches.
+   */
+  export type OpenClawRuntimeConfig = {
+    current?: () => { mcp?: { servers?: Record<string, unknown> } } | undefined;
+    mutateConfigFile?: (params: {
+      afterWrite: { mode: "auto" };
+      mutate: (draft: { mcp?: { servers?: Record<string, unknown> } }) => void;
+    }) => Promise<unknown>;
+    [key: string]: unknown;
+  };
+
+  /**
+   * The slice of `PluginRuntime` (`api.runtime`) the plugin consumes.
+   * Verified: ../openclaw/src/plugins/types.ts:2600 (`runtime: PluginRuntime`)
+   * → ../openclaw/src/plugins/runtime/types.ts (PluginRuntime = PluginRuntimeCore
+   * & …) → ../openclaw/src/plugins/runtime/types-core.ts (`agent` :180,
+   * `config` :145). The reverse control channel is NOT part of this runtime
+   * surface — it arrives over the SSE stream (`type: "control"`), handled in
+   * `sse-listener.ts` / the control handler, not via `api.runtime`. Confirmed:
+   * no `control`/`connection` member exists on `PluginRuntimeCore`.
+   */
+  export type OpenClawPluginRuntime = {
+    agent: OpenClawRuntimeAgent;
+    config: OpenClawRuntimeConfig;
+    [key: string]: unknown;
+  };
+
   /**
    * Permissive subset of `OpenClawPluginApi` used by this plugin's entry.
    *
    * Only the members this plugin touches are typed; the index signature keeps
    * the rest of the (large) host API accessible without importing it.
+   * Verified: ../openclaw/src/plugins/types.ts:2584-2600 (`OpenClawPluginApi`).
    */
   export type OpenClawPluginApi = {
     registrationMode: PluginRegistrationMode;
@@ -68,7 +293,13 @@ declare module "openclaw/plugin-sdk/plugin-entry" {
     }) => void;
     registerCommand: (command: unknown) => void;
     registerTool: (tool: unknown, opts?: unknown) => void;
-    runtime?: unknown;
+    /**
+     * In-process runtime helpers. Typed to the minimal slice the plugin uses
+     * (`agent`, `config`) — no longer bare `unknown`. Optional because the
+     * narrow registration modes (discovery/cli-metadata) may not expose it; the
+     * plugin guards `api.runtime` before use.
+     */
+    runtime?: OpenClawPluginRuntime;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     [key: string]: any;
   };