@xopcai/xopc 0.0.81 → 0.0.83

package/dist/src/gateway/security/loopback.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Loopback / browser-origin classification helpers used by rate-limit policy
+ * and other security middleware. Pure functions, no I/O.
+ */
+export declare function isLoopbackClientIp(clientIp: string | undefined): boolean;
+/** Browser Origin header points at the local gateway console. */
+export declare function isLoopbackBrowserOrigin(origin: string | undefined): boolean;
+/** Same-machine browser hitting the local gateway (Electron / local dev). */
+export declare function isLoopbackEmbeddedBrowserClient(origin: string | undefined, clientIp: string): boolean;
+/** Read X-Forwarded-For / X-Real-IP / CF-Connecting-IP. */
+export declare function getClientIpFromHeaders(headers: {
+    get(name: string): string | undefined;
+}): string;

package/dist/src/gateway/security/loopback.js

@@ -0,0 +1,45 @@
+import { isLoopbackHost } from "../host.js";
+//#region src/gateway/security/loopback.ts
+/**
+* Loopback / browser-origin classification helpers used by rate-limit policy
+* and other security middleware. Pure functions, no I/O.
+*/
+function isLoopbackClientIp(clientIp) {
+	if (!clientIp || clientIp === "unknown") return false;
+	const trimmed = clientIp.trim();
+	if (trimmed.includes(":") && !trimmed.includes(".")) return isLoopbackHost(trimmed.replace(/^\[/, "").replace(/\]$/, ""));
+	return isLoopbackHost(trimmed.split(":")[0]);
+}
+/** Browser Origin header points at the local gateway console. */
+function isLoopbackBrowserOrigin(origin) {
+	const trimmed = origin?.trim();
+	if (!trimmed || trimmed === "null") return false;
+	try {
+		return isLoopbackHost(new URL(trimmed).hostname);
+	} catch {
+		return false;
+	}
+}
+/** Same-machine browser hitting the local gateway (Electron / local dev). */
+function isLoopbackEmbeddedBrowserClient(origin, clientIp) {
+	if (!isLoopbackBrowserOrigin(origin)) return false;
+	if (clientIp === "unknown") return true;
+	return isLoopbackClientIp(clientIp);
+}
+/** Read X-Forwarded-For / X-Real-IP / CF-Connecting-IP. */
+function getClientIpFromHeaders(headers) {
+	const xff = headers.get("x-forwarded-for");
+	if (xff) {
+		const first = xff.split(",")[0]?.trim();
+		if (first) return first;
+	}
+	const real = headers.get("x-real-ip")?.trim();
+	if (real) return real;
+	const cf = headers.get("cf-connecting-ip")?.trim();
+	if (cf) return cf;
+	return "unknown";
+}
+//#endregion
+export { getClientIpFromHeaders, isLoopbackBrowserOrigin, isLoopbackClientIp, isLoopbackEmbeddedBrowserClient };
+
+//# sourceMappingURL=loopback.js.map

package/dist/src/gateway/security/loopback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.js","names":[],"sources":["../../../../src/gateway/security/loopback.ts"],"sourcesContent":["/**\n * Loopback / browser-origin classification helpers used by rate-limit policy\n * and other security middleware. Pure functions, no I/O.\n */\n\nimport { isLoopbackHost } from '../host.js';\n\nexport function isLoopbackClientIp(clientIp: string | undefined): boolean {\n  if (!clientIp || clientIp === 'unknown') return false;\n  const trimmed = clientIp.trim();\n  if (trimmed.includes(':') && !trimmed.includes('.')) {\n    return isLoopbackHost(trimmed.replace(/^\\[/, '').replace(/\\]$/, ''));\n  }\n  return isLoopbackHost(trimmed.split(':')[0]);\n}\n\n/** Browser Origin header points at the local gateway console. */\nexport function isLoopbackBrowserOrigin(origin: string | undefined): boolean {\n  const trimmed = origin?.trim();\n  if (!trimmed || trimmed === 'null') return false;\n  try {\n    return isLoopbackHost(new URL(trimmed).hostname);\n  } catch {\n    return false;\n  }\n}\n\n/** Same-machine browser hitting the local gateway (Electron / local dev). */\nexport function isLoopbackEmbeddedBrowserClient(\n  origin: string | undefined,\n  clientIp: string,\n): boolean {\n  if (!isLoopbackBrowserOrigin(origin)) return false;\n  if (clientIp === 'unknown') return true;\n  return isLoopbackClientIp(clientIp);\n}\n\n/** Read X-Forwarded-For / X-Real-IP / CF-Connecting-IP. */\nexport function getClientIpFromHeaders(headers: {\n  get(name: string): string | undefined;\n}): string {\n  const xff = headers.get('x-forwarded-for');\n  if (xff) {\n    const first = xff.split(',')[0]?.trim();\n    if (first) return first;\n  }\n  const real = headers.get('x-real-ip')?.trim();\n  if (real) return real;\n  const cf = headers.get('cf-connecting-ip')?.trim();\n  if (cf) return cf;\n  return 'unknown';\n}\n"],"mappings":";;;;;;AAOA,SAAgB,mBAAmB,UAAuC;AACxE,KAAI,CAAC,YAAY,aAAa,UAAW,QAAO;CAChD,MAAM,UAAU,SAAS,MAAM;AAC/B,KAAI,QAAQ,SAAS,IAAI,IAAI,CAAC,QAAQ,SAAS,IAAI,CACjD,QAAO,eAAe,QAAQ,QAAQ,OAAO,GAAG,CAAC,QAAQ,OAAO,GAAG,CAAC;AAEtE,QAAO,eAAe,QAAQ,MAAM,IAAI,CAAC,GAAG;;;AAI9C,SAAgB,wBAAwB,QAAqC;CAC3E,MAAM,UAAU,QAAQ,MAAM;AAC9B,KAAI,CAAC,WAAW,YAAY,OAAQ,QAAO;AAC3C,KAAI;AACF,SAAO,eAAe,IAAI,IAAI,QAAQ,CAAC,SAAS;SAC1C;AACN,SAAO;;;;AAKX,SAAgB,gCACd,QACA,UACS;AACT,KAAI,CAAC,wBAAwB,OAAO,CAAE,QAAO;AAC7C,KAAI,aAAa,UAAW,QAAO;AACnC,QAAO,mBAAmB,SAAS;;;AAIrC,SAAgB,uBAAuB,SAE5B;CACT,MAAM,MAAM,QAAQ,IAAI,kBAAkB;AAC1C,KAAI,KAAK;EACP,MAAM,QAAQ,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM;AACvC,MAAI,MAAO,QAAO;;CAEpB,MAAM,OAAO,QAAQ,IAAI,YAAY,EAAE,MAAM;AAC7C,KAAI,KAAM,QAAO;CACjB,MAAM,KAAK,QAAQ,IAAI,mBAAmB,EAAE,MAAM;AAClD,KAAI,GAAI,QAAO;AACf,QAAO"}

package/dist/src/gateway/service/agent-runner.d.ts

@@ -0,0 +1,108 @@
+/**
+ * GatewayAgentRunner — webchat agent invocation and the surrounding control
+ * surface (abort, steer, clarify-bridge plumbing, scheduled continuations).
+ *
+ * Was 200 lines of `GatewayService` covering seven concerns that all hung off
+ * the same handful of fields (`activeWebchatRunBySession`, `runAbortControllers`,
+ * `clarifyBridge`, `runRelay`):
+ *
+ *   - `runAgent(message, channel, chatId, ...)` — wraps {@link runGatewayAgent}
+ *   - `abortAgentRun(runId)` — POST /api/agent/abort + cleanup
+ *   - `steerWebchatAgent(chatId, message)` — Agent.steer queue at tool boundary
+ *   - `submitClarifyResponse(requestId, answer)` — UI answers a `clarify` call
+ *   - `enqueueWebchatPersistentGoalKickoff(sessionKey, goalText)` — initial
+ *     `/goal` kickoff posts the goal text as the next user turn
+ *   - `drainScheduledWebchatContinuation(sk, msg)` — background continuation
+ *     (extension scheduler + persistent-goal flow)
+ *   - `clarifyForSession({ sessionKey, request })` — clarify-bridge dispatch
+ *     used by `gatewayClarify.requestClarification` in AgentService
+ *
+ * Owns the two state maps (`activeWebchatRunBySession`, `runAbortControllers`)
+ * directly so peer coordinators (sessions-api, marketplace, config) cannot
+ * accidentally mutate them.
+ */
+import type { Config } from '../../config/schema.js';
+import type { MessageBus } from '../../infra/bus/index.js';
+import type { AgentService } from '../../agent/service.js';
+import type { ChannelManager } from '../../channels/manager.js';
+import type { SessionIndex } from '../../session/index.js';
+import { AgentRunRelay, type RelayEvent } from '../agent-run-relay.js';
+import { ClarifyBridge, type ClarifyBridgeRequest } from '../clarify-bridge.js';
+export interface GatewayAgentRunnerOptions {
+    bus: MessageBus;
+    sessionIndex: SessionIndex;
+    /** Resolved lazily — the runner is constructed before AgentService exists. */
+    getAgentService: () => AgentService;
+    getChannelManager: () => ChannelManager;
+    getConfig: () => Config;
+    /** SSE emit (re-used so `runAgent` events broadcast to subscribers). */
+    emit: (type: string, payload: unknown) => void;
+}
+export declare class GatewayAgentRunner {
+    private readonly opts;
+    readonly runRelay: AgentRunRelay;
+    /** Per-run abort for webchat (POST /api/agent/abort or client disconnect). */
+    private readonly runAbortControllers;
+    private readonly clarifyBridge;
+    /** Maps webchat session key → active `runId` for `clarify` tool routing. */
+    private readonly activeWebchatRunBySession;
+    constructor(opts: GatewayAgentRunnerOptions);
+    /** True when a webchat agent run is currently in-flight for `sessionKey`. */
+    hasActiveRun(sessionKey: string): boolean;
+    getActiveRunId(sessionKey: string): string | undefined;
+    getClarifyBridge(): ClarifyBridge;
+    /** Called from `GatewayService.stop()` so the bridge gets cleaned up. */
+    disposeClarifyBridge(): void;
+    runAgent(message: string, channel: string, chatId: string, attachments?: Array<{
+        type: string;
+        mimeType?: string;
+        data?: string;
+        name?: string;
+        size?: number;
+    }>, thinking?: string, runOptions?: {
+        signal?: AbortSignal;
+        clientCreatedAtMs?: number;
+    }): AsyncGenerator<{
+        type: string;
+        content?: string;
+        status?: string;
+        runId?: string;
+    }, {
+        status: string;
+        summary: string;
+    }, unknown>;
+    /** Abort an in-flight webchat agent run (matches `runId` from SSE `status`). */
+    abortAgentRun(runId: string): boolean;
+    /**
+     * Queue steering text for an active webchat run (`Agent.steer` /
+     * tool-boundary injection). `chatId` is the same as `POST /api/agent` body
+     * (`sessionKey` or legacy peer id).
+     */
+    steerWebchatAgent(chatId: string, message: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        code: 'BAD_REQUEST' | 'NO_ACTIVE_RUN' | 'STEER_FAILED';
+    }>;
+    /** Deliver a user's answer to a pending `clarify` tool call. */
+    submitClarifyResponse(requestId: string, answer: string): boolean;
+    /** Hermes-style: after HTTP sets a goal, enqueue the goal text as the next user turn. */
+    enqueueWebchatPersistentGoalKickoff(sessionKey: string, goalText: string): void;
+    /** Background drain for extension-initiated webchat turns (`scheduleWebchatContinuation`). */
+    drainScheduledWebchatContinuation(sessionKey: string, message: string): Promise<void>;
+    /**
+     * Resolve clarify-bridge config for `sessionKey`: who delivers the question
+     * (webchat SSE, Telegram message, or both), then start the bridge request.
+     * Rejects when neither path is available (e.g. CLI without webchat or TG).
+     *
+     * `publishSseFor(runId)` is the bridge into AgentService's
+     * `turnDispatcher.enqueueWebchatSseEvent`. We take it as a callback so the
+     * runner does not import AgentService statically.
+     */
+    requestClarification(opts: {
+        sessionKey: string;
+        request: ClarifyBridgeRequest;
+        publishSseFor: (runId: string) => (e: RelayEvent) => void;
+    }): Promise<string>;
+    private deliverTelegramClarify;
+}

package/dist/src/gateway/service/agent-runner.js

@@ -0,0 +1,184 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { buildSessionKey, init_session_key, parseSessionKey } from "../../routing/session-key.js";
+import { getDefaultAgentId, init_resolve_route } from "../../routing/resolve-route.js";
+import { AgentRunRelay } from "../agent-run-relay.js";
+import { ClarifyBridge } from "../clarify-bridge.js";
+import { runGatewayAgent } from "./run-gateway-agent.js";
+//#region src/gateway/service/agent-runner.ts
+init_session_key();
+init_resolve_route();
+init_logger();
+const log = createLogger("GatewayAgentRunner");
+var GatewayAgentRunner = class {
+	opts;
+	runRelay = new AgentRunRelay();
+	/** Per-run abort for webchat (POST /api/agent/abort or client disconnect). */
+	runAbortControllers = /* @__PURE__ */ new Map();
+	clarifyBridge = new ClarifyBridge();
+	/** Maps webchat session key → active `runId` for `clarify` tool routing. */
+	activeWebchatRunBySession = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.opts = opts;
+	}
+	/** True when a webchat agent run is currently in-flight for `sessionKey`. */
+	hasActiveRun(sessionKey) {
+		return this.activeWebchatRunBySession.has(sessionKey);
+	}
+	getActiveRunId(sessionKey) {
+		return this.activeWebchatRunBySession.get(sessionKey);
+	}
+	getClarifyBridge() {
+		return this.clarifyBridge;
+	}
+	/** Called from `GatewayService.stop()` so the bridge gets cleaned up. */
+	disposeClarifyBridge() {
+		this.clarifyBridge.dispose();
+	}
+	async *runAgent(message, channel, chatId, attachments, thinking, runOptions) {
+		const iter = runGatewayAgent({
+			config: this.opts.getConfig(),
+			agentService: this.opts.getAgentService(),
+			bus: this.opts.bus,
+			runRelay: this.runRelay,
+			runAbortControllers: this.runAbortControllers,
+			activeWebchatRunBySession: this.activeWebchatRunBySession,
+			sessionIndex: this.opts.sessionIndex,
+			emit: this.opts.emit
+		}, message, channel, chatId, attachments, thinking, runOptions);
+		let step = await iter.next();
+		while (!step.done) {
+			yield step.value;
+			step = await iter.next();
+		}
+		return step.value;
+	}
+	/** Abort an in-flight webchat agent run (matches `runId` from SSE `status`). */
+	abortAgentRun(runId) {
+		this.clarifyBridge.cancelForRun(runId);
+		const keysToMark = [];
+		for (const [sk, id] of this.activeWebchatRunBySession) if (id === runId) keysToMark.push(sk);
+		for (const sk of keysToMark) this.activeWebchatRunBySession.delete(sk);
+		const relaySk = this.runRelay.getSessionKey(runId);
+		if (relaySk && !keysToMark.includes(relaySk)) keysToMark.push(relaySk);
+		const c = this.runAbortControllers.get(runId);
+		if (!c) return false;
+		const cutoffTs = Date.now();
+		for (const sk of keysToMark) {
+			this.opts.sessionIndex.updateSessionMetadata(sk, { abortCutoffTimestamp: cutoffTs }).catch(() => {});
+			this.opts.sessionIndex.appendTranscriptContextEntry(sk, {
+				text: "Webchat agent run aborted",
+				data: {
+					runId,
+					abortCutoffTimestamp: cutoffTs
+				}
+			}).catch(() => {});
+		}
+		c.abort();
+		for (const sk of keysToMark) import("../../agent/embedded/runs.js").then(({ abortEmbeddedRun }) => abortEmbeddedRun(sk));
+		return true;
+	}
+	/**
+	* Queue steering text for an active webchat run (`Agent.steer` /
+	* tool-boundary injection). `chatId` is the same as `POST /api/agent` body
+	* (`sessionKey` or legacy peer id).
+	*/
+	async steerWebchatAgent(chatId, message) {
+		const trimmed = message.trim();
+		if (!trimmed) return {
+			ok: false,
+			code: "BAD_REQUEST"
+		};
+		const cfg = this.opts.getConfig();
+		const sessionKey = parseSessionKey(chatId) ? chatId : buildSessionKey({
+			agentId: getDefaultAgentId(cfg),
+			source: "webchat",
+			accountId: "default",
+			peerKind: "direct",
+			peerId: chatId
+		});
+		if (!this.activeWebchatRunBySession.has(sessionKey)) return {
+			ok: false,
+			code: "NO_ACTIVE_RUN"
+		};
+		if (!await this.opts.getAgentService().turnDispatcher.steerWebchatSession(sessionKey, trimmed)) return {
+			ok: false,
+			code: "STEER_FAILED"
+		};
+		return { ok: true };
+	}
+	/** Deliver a user's answer to a pending `clarify` tool call. */
+	submitClarifyResponse(requestId, answer) {
+		return this.clarifyBridge.handleResponse(requestId, answer);
+	}
+	/** Hermes-style: after HTTP sets a goal, enqueue the goal text as the next user turn. */
+	enqueueWebchatPersistentGoalKickoff(sessionKey, goalText) {
+		queueMicrotask(() => {
+			this.drainScheduledWebchatContinuation(sessionKey, goalText);
+		});
+	}
+	/** Background drain for extension-initiated webchat turns (`scheduleWebchatContinuation`). */
+	async drainScheduledWebchatContinuation(sessionKey, message) {
+		try {
+			const gen = this.runAgent(message, "webchat", sessionKey, void 0, void 0, { clientCreatedAtMs: Date.now() });
+			for await (const _ of gen);
+		} catch (err) {
+			log.warn({
+				err,
+				sessionKey
+			}, "Scheduled webchat continuation failed");
+		}
+	}
+	/**
+	* Resolve clarify-bridge config for `sessionKey`: who delivers the question
+	* (webchat SSE, Telegram message, or both), then start the bridge request.
+	* Rejects when neither path is available (e.g. CLI without webchat or TG).
+	*
+	* `publishSseFor(runId)` is the bridge into AgentService's
+	* `turnDispatcher.enqueueWebchatSseEvent`. We take it as a callback so the
+	* runner does not import AgentService statically.
+	*/
+	requestClarification(opts) {
+		const { sessionKey, request, publishSseFor } = opts;
+		const runId = this.activeWebchatRunBySession.get(sessionKey);
+		const publishSse = runId ? publishSseFor(runId) : void 0;
+		const deliver = parseSessionKey(sessionKey)?.source === "telegram" ? async (ctx) => {
+			await this.deliverTelegramClarify(ctx);
+		} : void 0;
+		if (!runId && !deliver) return Promise.reject(/* @__PURE__ */ new Error("Clarify is not available for this session (use webchat, Telegram, or CLI)"));
+		return this.clarifyBridge.startRequest({
+			sessionKey,
+			runId,
+			relay: this.runRelay,
+			publishSse,
+			request,
+			deliver
+		});
+	}
+	async deliverTelegramClarify(ctx) {
+		const parsed = parseSessionKey(ctx.sessionKey);
+		if (!parsed || parsed.source !== "telegram") return;
+		let body = ctx.request.question;
+		if (ctx.request.default) body += `\n\nDefault if unsure: ${ctx.request.default}`;
+		const choices = ctx.request.choices;
+		const buttonRows = choices && choices.length >= 2 ? choices.map((c, i) => [{
+			text: c.length > 64 ? `${c.slice(0, 61)}…` : c,
+			callback_data: `clarify:${ctx.requestId}:${i}`
+		}]) : void 0;
+		if (!buttonRows) body += "\n\nReply with your answer in this chat.";
+		await this.opts.getChannelManager().send({
+			channel: "telegram",
+			chat_id: parsed.peerId,
+			content: body,
+			metadata: {
+				accountId: parsed.accountId,
+				...parsed.threadId ? { threadId: parsed.threadId } : {}
+			},
+			buttons: buttonRows
+		});
+	}
+};
+//#endregion
+export { GatewayAgentRunner };
+
+//# sourceMappingURL=agent-runner.js.map

package/dist/src/gateway/service/agent-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runner.js","names":[],"sources":["../../../../src/gateway/service/agent-runner.ts"],"sourcesContent":["/**\n * GatewayAgentRunner — webchat agent invocation and the surrounding control\n * surface (abort, steer, clarify-bridge plumbing, scheduled continuations).\n *\n * Was 200 lines of `GatewayService` covering seven concerns that all hung off\n * the same handful of fields (`activeWebchatRunBySession`, `runAbortControllers`,\n * `clarifyBridge`, `runRelay`):\n *\n *   - `runAgent(message, channel, chatId, ...)` — wraps {@link runGatewayAgent}\n *   - `abortAgentRun(runId)` — POST /api/agent/abort + cleanup\n *   - `steerWebchatAgent(chatId, message)` — Agent.steer queue at tool boundary\n *   - `submitClarifyResponse(requestId, answer)` — UI answers a `clarify` call\n *   - `enqueueWebchatPersistentGoalKickoff(sessionKey, goalText)` — initial\n *     `/goal` kickoff posts the goal text as the next user turn\n *   - `drainScheduledWebchatContinuation(sk, msg)` — background continuation\n *     (extension scheduler + persistent-goal flow)\n *   - `clarifyForSession({ sessionKey, request })` — clarify-bridge dispatch\n *     used by `gatewayClarify.requestClarification` in AgentService\n *\n * Owns the two state maps (`activeWebchatRunBySession`, `runAbortControllers`)\n * directly so peer coordinators (sessions-api, marketplace, config) cannot\n * accidentally mutate them.\n */\nimport type { Config } from '../../config/schema.js';\nimport type { MessageBus } from '../../infra/bus/index.js';\nimport type { AgentService } from '../../agent/service.js';\nimport type { ChannelManager } from '../../channels/manager.js';\nimport type { SessionIndex } from '../../session/index.js';\nimport { AgentRunRelay, type RelayEvent } from '../agent-run-relay.js';\nimport { ClarifyBridge, type ClarifyBridgeRequest } from '../clarify-bridge.js';\nimport { buildSessionKey, parseSessionKey } from '../../routing/session-key.js';\nimport { getDefaultAgentId } from '../../routing/resolve-route.js';\nimport { runGatewayAgent } from './run-gateway-agent.js';\nimport { createLogger } from '../../utils/logger.js';\n\nconst log = createLogger('GatewayAgentRunner');\n\nexport interface GatewayAgentRunnerOptions {\n  bus: MessageBus;\n  sessionIndex: SessionIndex;\n  /** Resolved lazily — the runner is constructed before AgentService exists. */\n  getAgentService: () => AgentService;\n  getChannelManager: () => ChannelManager;\n  getConfig: () => Config;\n  /** SSE emit (re-used so `runAgent` events broadcast to subscribers). */\n  emit: (type: string, payload: unknown) => void;\n}\n\nexport class GatewayAgentRunner {\n  private readonly opts: GatewayAgentRunnerOptions;\n  readonly runRelay = new AgentRunRelay();\n  /** Per-run abort for webchat (POST /api/agent/abort or client disconnect). */\n  private readonly runAbortControllers = new Map<string, AbortController>();\n  private readonly clarifyBridge = new ClarifyBridge();\n  /** Maps webchat session key → active `runId` for `clarify` tool routing. */\n  private readonly activeWebchatRunBySession = new Map<string, string>();\n\n  constructor(opts: GatewayAgentRunnerOptions) {\n    this.opts = opts;\n  }\n\n  // ── Read-only accessors (so peers don't get a Map ref) ────────────────\n\n  /** True when a webchat agent run is currently in-flight for `sessionKey`. */\n  hasActiveRun(sessionKey: string): boolean {\n    return this.activeWebchatRunBySession.has(sessionKey);\n  }\n\n  getActiveRunId(sessionKey: string): string | undefined {\n    return this.activeWebchatRunBySession.get(sessionKey);\n  }\n\n  getClarifyBridge(): ClarifyBridge {\n    return this.clarifyBridge;\n  }\n\n  /** Called from `GatewayService.stop()` so the bridge gets cleaned up. */\n  disposeClarifyBridge(): void {\n    this.clarifyBridge.dispose();\n  }\n\n  // ── runAgent (webchat HTTP POST) ──────────────────────────────────────\n\n  async *runAgent(\n    message: string,\n    channel: string,\n    chatId: string,\n    attachments?: Array<{\n      type: string;\n      mimeType?: string;\n      data?: string;\n      name?: string;\n      size?: number;\n    }>,\n    thinking?: string,\n    runOptions?: { signal?: AbortSignal; clientCreatedAtMs?: number },\n  ): AsyncGenerator<\n    { type: string; content?: string; status?: string; runId?: string },\n    { status: string; summary: string },\n    unknown\n  > {\n    const iter = runGatewayAgent(\n      {\n        config: this.opts.getConfig(),\n        agentService: this.opts.getAgentService(),\n        bus: this.opts.bus,\n        runRelay: this.runRelay,\n        runAbortControllers: this.runAbortControllers,\n        activeWebchatRunBySession: this.activeWebchatRunBySession,\n        sessionIndex: this.opts.sessionIndex,\n        emit: this.opts.emit,\n      },\n      message,\n      channel,\n      chatId,\n      attachments,\n      thinking,\n      runOptions,\n    );\n\n    let step = await iter.next();\n    while (!step.done) {\n      yield step.value as { type: string; content?: string; status?: string; runId?: string };\n      step = await iter.next();\n    }\n    return step.value;\n  }\n\n  /** Abort an in-flight webchat agent run (matches `runId` from SSE `status`). */\n  abortAgentRun(runId: string): boolean {\n    this.clarifyBridge.cancelForRun(runId);\n    const keysToMark: string[] = [];\n    for (const [sk, id] of this.activeWebchatRunBySession) {\n      if (id === runId) {\n        keysToMark.push(sk);\n      }\n    }\n    for (const sk of keysToMark) {\n      this.activeWebchatRunBySession.delete(sk);\n    }\n    const relaySk = this.runRelay.getSessionKey(runId);\n    if (relaySk && !keysToMark.includes(relaySk)) {\n      keysToMark.push(relaySk);\n    }\n    const c = this.runAbortControllers.get(runId);\n    if (!c) {\n      return false;\n    }\n    const cutoffTs = Date.now();\n    for (const sk of keysToMark) {\n      void this.opts.sessionIndex\n        .updateSessionMetadata(sk, { abortCutoffTimestamp: cutoffTs })\n        .catch(() => {});\n      void this.opts.sessionIndex\n        .appendTranscriptContextEntry(sk, {\n          text: 'Webchat agent run aborted',\n          data: { runId, abortCutoffTimestamp: cutoffTs },\n        })\n        .catch(() => {});\n    }\n    c.abort();\n    for (const sk of keysToMark) {\n      void import('../../agent/embedded/runs.js').then(({ abortEmbeddedRun }) =>\n        abortEmbeddedRun(sk),\n      );\n    }\n    return true;\n  }\n\n  /**\n   * Queue steering text for an active webchat run (`Agent.steer` /\n   * tool-boundary injection). `chatId` is the same as `POST /api/agent` body\n   * (`sessionKey` or legacy peer id).\n   */\n  async steerWebchatAgent(\n    chatId: string,\n    message: string,\n  ): Promise<\n    { ok: true } | { ok: false; code: 'BAD_REQUEST' | 'NO_ACTIVE_RUN' | 'STEER_FAILED' }\n  > {\n    const trimmed = message.trim();\n    if (!trimmed) {\n      return { ok: false, code: 'BAD_REQUEST' };\n    }\n    const cfg = this.opts.getConfig();\n    const parsedKey = parseSessionKey(chatId);\n    const sessionKey = parsedKey\n      ? chatId\n      : buildSessionKey({\n          agentId: getDefaultAgentId(cfg),\n          source: 'webchat',\n          accountId: 'default',\n          peerKind: 'direct',\n          peerId: chatId,\n        });\n    if (!this.activeWebchatRunBySession.has(sessionKey)) {\n      return { ok: false, code: 'NO_ACTIVE_RUN' };\n    }\n    const steered = await this.opts\n      .getAgentService()\n      .turnDispatcher.steerWebchatSession(sessionKey, trimmed);\n    if (!steered) {\n      return { ok: false, code: 'STEER_FAILED' };\n    }\n    return { ok: true };\n  }\n\n  /** Deliver a user's answer to a pending `clarify` tool call. */\n  submitClarifyResponse(requestId: string, answer: string): boolean {\n    return this.clarifyBridge.handleResponse(requestId, answer);\n  }\n\n  /** Hermes-style: after HTTP sets a goal, enqueue the goal text as the next user turn. */\n  enqueueWebchatPersistentGoalKickoff(sessionKey: string, goalText: string): void {\n    queueMicrotask(() => {\n      void this.drainScheduledWebchatContinuation(sessionKey, goalText);\n    });\n  }\n\n  /** Background drain for extension-initiated webchat turns (`scheduleWebchatContinuation`). */\n  async drainScheduledWebchatContinuation(sessionKey: string, message: string): Promise<void> {\n    try {\n      const gen = this.runAgent(message, 'webchat', sessionKey, undefined, undefined, {\n        clientCreatedAtMs: Date.now(),\n      });\n      for await (const _ of gen) {\n        // Relay + `agent.stream` broadcast; UI attaches via pending runId + resume.\n      }\n    } catch (err) {\n      log.warn({ err, sessionKey }, 'Scheduled webchat continuation failed');\n    }\n  }\n\n  // ── Clarify dispatch (called from AgentService.gatewayClarify) ────────\n\n  /**\n   * Resolve clarify-bridge config for `sessionKey`: who delivers the question\n   * (webchat SSE, Telegram message, or both), then start the bridge request.\n   * Rejects when neither path is available (e.g. CLI without webchat or TG).\n   *\n   * `publishSseFor(runId)` is the bridge into AgentService's\n   * `turnDispatcher.enqueueWebchatSseEvent`. We take it as a callback so the\n   * runner does not import AgentService statically.\n   */\n  requestClarification(opts: {\n    sessionKey: string;\n    request: ClarifyBridgeRequest;\n    publishSseFor: (runId: string) => (e: RelayEvent) => void;\n  }): Promise<string> {\n    const { sessionKey, request, publishSseFor } = opts;\n    const runId = this.activeWebchatRunBySession.get(sessionKey);\n    const publishSse = runId ? publishSseFor(runId) : undefined;\n    const parsed = parseSessionKey(sessionKey);\n    const deliver =\n      parsed?.source === 'telegram'\n        ? async (ctx: {\n            sessionKey: string;\n            requestId: string;\n            request: ClarifyBridgeRequest;\n          }) => {\n            await this.deliverTelegramClarify(ctx);\n          }\n        : undefined;\n    if (!runId && !deliver) {\n      return Promise.reject(\n        new Error('Clarify is not available for this session (use webchat, Telegram, or CLI)'),\n      );\n    }\n    return this.clarifyBridge.startRequest({\n      sessionKey,\n      runId,\n      relay: this.runRelay,\n      publishSse,\n      request,\n      deliver,\n    });\n  }\n\n  private async deliverTelegramClarify(ctx: {\n    sessionKey: string;\n    requestId: string;\n    request: ClarifyBridgeRequest;\n  }): Promise<void> {\n    const parsed = parseSessionKey(ctx.sessionKey);\n    if (!parsed || parsed.source !== 'telegram') {\n      return;\n    }\n\n    let body = ctx.request.question;\n    if (ctx.request.default) {\n      body += `\\n\\nDefault if unsure: ${ctx.request.default}`;\n    }\n\n    const choices = ctx.request.choices;\n    const buttonRows =\n      choices && choices.length >= 2\n        ? choices.map((c, i) => [\n            {\n              text: c.length > 64 ? `${c.slice(0, 61)}…` : c,\n              callback_data: `clarify:${ctx.requestId}:${i}`,\n            },\n          ])\n        : undefined;\n\n    if (!buttonRows) {\n      body += '\\n\\nReply with your answer in this chat.';\n    }\n\n    await this.opts.getChannelManager().send({\n      channel: 'telegram',\n      chat_id: parsed.peerId,\n      content: body,\n      metadata: {\n        accountId: parsed.accountId,\n        ...(parsed.threadId ? { threadId: parsed.threadId } : {}),\n      },\n      buttons: buttonRows,\n    });\n  }\n}\n"],"mappings":"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"}

package/dist/src/gateway/service/config-coordinator.d.ts

@@ -0,0 +1,119 @@
+/**
+ * GatewayConfigCoordinator — owns config persistence, hot-reload, and the
+ * per-section reload handlers.
+ *
+ * Was 350 lines of `GatewayService` covering nine concerns:
+ *   - manual `reloadConfig()` (CLI/UI trigger)
+ *   - `saveConfig()` / `updateConfig()` (PATCH /api/config)
+ *   - `setBundledExtensionActivationTarget` (extension store install)
+ *   - `afterWeixinCredentialsPersisted` / `afterFeishuCredentialsPersisted`
+ *     (QR-login follow-ups that bypass the watcher)
+ *   - `ConfigHotReloader` (fs.watch → debounced per-section dispatch)
+ *   - Eight section reload handlers (models / agents / channels / cron /
+ *     heartbeat / tools / mcp / extensions)
+ *   - `scheduleChannelPluginsAfterPersist` (coalesces rapid saves so
+ *     Telegram/Weixin do not stop/start repeatedly)
+ *
+ * Pulled out so the gateway composition root stays focused on lifecycle, and
+ * each handler is reachable from one place when adding a new config section.
+ *
+ * **Config state ownership.** `GatewayService.config` is still the single
+ * source of truth — this coordinator reads it via `getConfig()` and writes it
+ * back via `setConfig()` after every reload / persist. We pass through rather
+ * than holding our own copy so other coordinators (sessions, marketplace,
+ * agent runner) see the latest config the moment a reload commits.
+ */
+import type { Config } from '../../config/schema.js';
+import type { AgentService } from '../../agent/service.js';
+import type { ChannelManager } from '../../channels/manager.js';
+import type { CronService } from '../../cron/index.js';
+import type { HeartbeatService } from '../heartbeat/index.js';
+import type { ExtensionLoader } from '../../extensions/loader.js';
+import type { MessageBus } from '../../infra/bus/index.js';
+export interface GatewayConfigCoordinatorOptions {
+    configPath: string;
+    bus: MessageBus;
+    /** Hot reload (fs.watch) — disabled in tests / certain CLI modes. */
+    enableHotReload: boolean;
+    getConfig: () => Config;
+    /** Writes the new config back into `GatewayService.config`. */
+    setConfig: (next: Config) => void;
+    getAgentService: () => AgentService;
+    getChannelManager: () => ChannelManager;
+    getCronService: () => CronService;
+    getHeartbeatService: () => HeartbeatService | null;
+    getExtensionLoader: () => ExtensionLoader | null;
+    /** Re-evaluate browser-extension server attachment after agent defaults change. */
+    reconcileBrowserExtensionServer: () => Promise<void>;
+    /** Latest channel status snapshot for the `channels.status` SSE event. */
+    getChannelsStatus: () => unknown;
+    /** SSE emit (used for `config.reload` + `channels.status`). */
+    emit: (type: string, payload: unknown) => void;
+}
+export declare class GatewayConfigCoordinator {
+    private readonly opts;
+    private configReloader;
+    private channelReloadFlushPromise;
+    private channelReloadPending;
+    constructor(opts: GatewayConfigCoordinatorOptions);
+    /** Start the fs.watch-based reloader (idempotent — only starts once). */
+    startHotReloader(): void;
+    stopHotReloader(): Promise<void>;
+    reloadConfig(): Promise<{
+        reloaded: boolean;
+        error?: string;
+    }>;
+    saveConfig(config: Config): Promise<{
+        saved: boolean;
+        error?: string;
+    }>;
+    /** Merge partial updates into `currentConfig` and persist. */
+    updateConfig(updates: Partial<Config>): Promise<{
+        updated: boolean;
+        error?: string;
+    }>;
+    /**
+     * App store (phase 1): persist `extensions.enabled` / `extensions.disabled`
+     * for a bundled extension. Marketplace-only extensions hot-load on enable;
+     * disable still needs a gateway restart to unload.
+     */
+    setBundledExtensionActivationTarget(extensionId: string, wanted: boolean): Promise<{
+        ok: boolean;
+        error?: string;
+        requiresGatewayRestart: boolean;
+    }>;
+    afterWeixinCredentialsPersisted(): Promise<void>;
+    afterFeishuCredentialsPersisted(): Promise<void>;
+    /**
+     * Apply `latest.channels` to every registered channel plugin (Telegram,
+     * Weixin, extensions). Single runtime path for: file watcher hot reload, API
+     * saves, and Weixin QR follow-up.
+     */
+    handleChannelsReload(newConfig: Config): Promise<void>;
+    /**
+     * Apply `gateway.heartbeat` from current config after PATCH /api/config (and
+     * when hot reload is off). File watcher uses `handleHeartbeatReload` with
+     * the same effect when paths match.
+     */
+    reloadHeartbeatFromCurrentConfig(): void;
+    private handleModelsReload;
+    private handleAgentDefaultsReload;
+    /**
+     * Coalesces rapid saves so Telegram/Weixin do not stop/start repeatedly.
+     * The persist path schedules the channel apply; the same coalescer absorbs
+     * follow-up saves until the first flush settles.
+     */
+    private scheduleChannelPluginsAfterPersist;
+    private handleCronReload;
+    private handleHeartbeatReload;
+    private handleToolsReload;
+    private handleMcpReload;
+    /** Dispatch config hot reload to extensions that registered `registerReload`. */
+    private handleExtensionsReload;
+    /**
+     * Persist and replace `currentConfig` with the validated file contents so
+     * runtime matches disk (PATCH merge objects can drift from Zod-normalized
+     * output).
+     */
+    private writeConfigAndReloadFromDisk;
+}