@myclaw163/openclaw-clawclaw 0.1.42

package/dist/index.mjs

@@ -0,0 +1,1640 @@
+import { createRequire } from "node:module";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { spawn, spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { delimiter, join, sep } from "node:path";
+import { createInterface } from "node:readline";
+import { randomUUID } from "node:crypto";
+import * as Sentry from "@sentry/node";
+//#region src/cli-resolve.ts
+/**
+* Shared package-bin resolver used by index.ts (clawclaw-cli) and stream.ts (openclaw).
+*
+* 不同包的 bin 文件布局不一样:
+*   - clawclaw-cli: <root>/bin/clawclaw-cli.mjs
+*   - openclaw:     <root>/openclaw.mjs (无 bin 子目录)
+* 所以 binRelPath 必须由调用方显式提供。
+*/
+function resolvePackageBin(importMetaUrl, packageName, binRelPath) {
+	try {
+		let dir = createRequire(importMetaUrl).resolve(packageName);
+		while (dir && dir !== join(dir, "..")) {
+			const next = dir.slice(0, dir.lastIndexOf(sep));
+			if (next === dir || !next) break;
+			dir = next;
+			if (existsSync(join(dir, "package.json"))) break;
+		}
+		const binJs = join(dir, binRelPath);
+		if (existsSync(binJs) && statSync(binJs).isFile()) return binJs;
+	} catch {}
+	return null;
+}
+//#endregion
+//#region src/sentry.ts
+/**
+* sentry — monitor 生命周期事件上报
+* ─────────────────────────────────────────
+* 在 stream.ts 的 Instance 生命周期关键节点调用:
+*   - startInstance()      → monitor.started gid=xxx   (info)
+*   - NDJSON exit_reason:game_start → game.started gid=xxx (info)
+*   - NDJSON exit_reason:game_over  → game.exited gid=xxx  (info)
+*   - child close=0         → monitor.exited gid=xxx    (info)
+*   - child close≠0         → monitor.crashed gid=xxx   (warning)
+*   - restart 成功          → monitor.restarted gid=xxx (info)
+*   - restart 失败          → monitor.respawn_failed gid=xxx (error)
+*   - maxRestarts 耗尽      → monitor.restart_gave_up gid=xxx (error)
+*
+* 每条消息含 gid=<gameId> 前缀方便 Sentry 面板直接搜索;tags 中含 game_id / session_key。
+* 按 game_id 分组即可区分每一局,按 session_key 区分不同 agent 会话。
+*
+* 设计要点:
+*   - 延迟初始化:仅在上报时才 Sentry.init(),未配置 DSN 时完全跳过
+*   - 所有 Sentry 调用外层 try/catch,失败不影响主流程
+*   - 统一用 captureMessage,按 level 区分 severity
+*   - 进程退出前调用 closeSentry() 确保缓冲区事件被 flush
+*/
+let dsn = null;
+let initialized = false;
+let initFailed = false;
+let sentryLogger = null;
+/** 从 plugin config 设置 DSN。调用方在 registerStreamTools 中调用。
+*  优先级: openclaw.json 显式配 > manifest default > SENTRY_DSN 环境变量 > null(关闭) */
+function configureSentry(dsnFromConfig, logger) {
+	dsn = dsnFromConfig?.trim() || process.env.SENTRY_DSN?.trim() || null;
+	sentryLogger = logger ?? null;
+	initialized = false;
+	initFailed = false;
+}
+/** 上报 monitor 生命周期事件。dsn 未配置时静默跳过。 */
+function captureMonitorEvent(message, level, tags, extra) {
+	if (!dsn) return;
+	ensureInit();
+	if (!initialized) return;
+	try {
+		Sentry.withScope((scope) => {
+			setScopeContext(scope, tags, extra);
+			Sentry.captureMessage(`[monitor] ${message}`, level);
+		});
+	} catch {}
+}
+/**
+* 上报 terminal error（restart 耗尽 / respawn 失败）。
+* 使用 captureException 让 Sentry 按 error type + stack 自动分组,
+* 可在 Issues 面板中走 assign→resolve 工作流。
+*/
+function captureMonitorException(message, tags, extra) {
+	if (!dsn) return;
+	ensureInit();
+	if (!initialized) return;
+	try {
+		Sentry.withScope((scope) => {
+			setScopeContext(scope, tags, extra);
+			Sentry.captureException(/* @__PURE__ */ new Error(`[monitor] ${message}`));
+		});
+	} catch {}
+}
+/**
+* 关闭 Sentry,flush 缓冲区中的待发送事件。
+* 应在进程退出/插件卸载时调用,避免 crash 事件丢失。
+* 调用后仍可继续上报(下次 captureMonitorEvent 会重新 init)。
+*/
+async function closeSentry() {
+	if (!initialized) return;
+	try {
+		await Sentry.close(2e3);
+	} catch {}
+	initialized = false;
+}
+function setScopeContext(scope, tags, extra) {
+	if (tags) for (const [k, v] of Object.entries(tags)) scope.setTag(k, v);
+	if (extra) for (const [k, v] of Object.entries(extra)) scope.setExtra(k, v);
+}
+function ensureInit() {
+	if (initialized || !dsn || initFailed) return;
+	try {
+		Sentry.init({
+			dsn,
+			tracesSampleRate: 0,
+			defaultIntegrations: false,
+			integrations: [],
+			release: process.env.SENTRY_RELEASE ?? "openclaw-clawclaw",
+			environment: process.env.SENTRY_ENVIRONMENT ?? process.env.NODE_ENV ?? "production"
+		});
+		initialized = true;
+	} catch (e) {
+		initFailed = true;
+		sentryLogger?.warn?.(`[clawclaw:sentry] Sentry.init failed (DSN may be invalid or unreachable): ${e?.message ?? e}`);
+	}
+}
+//#endregion
+//#region src/stream.ts
+/**
+* stream — port of the former standalone `openclaw-monitor` plugin into
+* openclaw-clawclaw, scoped to ClawClaw needs.
+*
+* Pattern: spawn a background command, capture its stdout/stderr line-by-line,
+* debounce + batch them, then inject each batch back into the originating
+* OpenClaw session as a new agent turn via `openclaw agent --deliver`.
+*
+* Public tools (registered by registerStreamTools):
+*   clawclaw_game_status   — list running background streams + stats
+*   clawclaw_game_start    — start `ccl game start` as a background stream (handles fresh start + reattach)
+*   clawclaw_game_stop     — stop one or all running streams
+*
+* `ccl game start` now handles both fresh matchmaking and reattaching to an
+* existing game (crash recovery). The old `ccl watch` streaming command has
+* been retired — its spectator-URL replacement is auto-generated as clawclaw_watch.
+*/
+let abortAgentHarnessRun;
+let resolveActiveEmbeddedRunSessionId;
+import("openclaw/plugin-sdk/agent-harness-runtime").then((m) => {
+	abortAgentHarnessRun = m?.abortAgentHarnessRun;
+	resolveActiveEmbeddedRunSessionId = m?.resolveActiveEmbeddedRunSessionId;
+}).catch(() => {});
+const STREAM_DEFAULTS = {
+	agentTimeoutMs: 18e4,
+	debounceMs: 300,
+	minIntervalMs: 1e3,
+	maxBatchLines: 150,
+	maxQueueLines: 1e3,
+	maxInstances: 8,
+	emitLifecycleEvents: true,
+	autoRestart: true,
+	maxRestarts: 5,
+	restartBackoffBaseMs: 1e3,
+	restartBackoffMaxMs: 3e4,
+	maxConcurrentInjects: 1,
+	idleTimeoutMs: 12e4,
+	sessionNotFoundMaxRetries: 2,
+	maxBatchAgeMs: 3e3
+};
+const ID_REGEX = /^[A-Za-z0-9_-]{1,32}$/;
+const instances = /* @__PURE__ */ new Map();
+let streamConfig = {};
+let streamLogger = null;
+let resolvedOpenclawCli = null;
+/** Resolver passed in by the host plugin to find ccl (for the auto/event-stream shortcuts). */
+let resolvedCcl = null;
+function cfg(key) {
+	const camelKey = `stream${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+	const v = streamConfig[camelKey];
+	return v === void 0 || v === null ? STREAM_DEFAULTS[key] : v;
+}
+function generateId() {
+	return `mon-${randomUUID().slice(0, 8)}`;
+}
+function resolveOpenclawCli(override) {
+	const isWin = process.platform === "win32";
+	const exeNames = isWin ? [
+		"openclaw.cmd",
+		"openclaw.exe",
+		"openclaw"
+	] : ["openclaw"];
+	const candidates = [];
+	if (override) candidates.push(override);
+	if (!override) {
+		const binJs = resolvePackageBin(import.meta.url, "openclaw", "openclaw.mjs");
+		if (binJs) return {
+			exe: process.execPath,
+			prefixArgs: [binJs],
+			display: `${process.execPath} ${binJs}`
+		};
+	}
+	const pathDirs = (process.env.PATH || "").split(delimiter).filter(Boolean);
+	for (const dir of pathDirs) for (const exe of exeNames) candidates.push(`${dir}${sep}${exe}`);
+	for (const c of candidates) {
+		try {
+			if (!existsSync(c) || !statSync(c).isFile()) continue;
+		} catch {
+			continue;
+		}
+		const lower = c.toLowerCase();
+		if (lower.endsWith(".exe")) return {
+			exe: c,
+			prefixArgs: [],
+			display: c
+		};
+		if (lower.endsWith(".mjs") || lower.endsWith(".js")) return {
+			exe: process.execPath,
+			prefixArgs: [c],
+			display: `${process.execPath} ${c}`
+		};
+		if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
+			const lastSep = c.lastIndexOf(sep);
+			const dir = lastSep >= 0 ? c.substring(0, lastSep) : ".";
+			const fname = c.substring(lastSep + 1).replace(/\.(cmd|bat)$/i, "");
+			const heuristicMjs = `${dir}${sep}node_modules${sep}${fname}${sep}${fname}.mjs`;
+			try {
+				if (existsSync(heuristicMjs) && statSync(heuristicMjs).isFile()) return {
+					exe: process.execPath,
+					prefixArgs: [heuristicMjs],
+					display: `${process.execPath} ${heuristicMjs}`
+				};
+			} catch {}
+			continue;
+		}
+		if (!isWin) return {
+			exe: c,
+			prefixArgs: [],
+			display: c
+		};
+	}
+	return null;
+}
+function killTree(child) {
+	if (!child || child.killed || child.exitCode != null) return;
+	if (process.platform === "win32") {
+		try {
+			spawn("taskkill", [
+				"/T",
+				"/F",
+				"/PID",
+				String(child.pid)
+			], {
+				windowsHide: true,
+				stdio: "ignore"
+			});
+		} catch {}
+		try {
+			child.kill("SIGKILL");
+		} catch {}
+	} else {
+		try {
+			process.kill(-child.pid, "SIGTERM");
+		} catch {
+			try {
+				child.kill("SIGTERM");
+			} catch {}
+		}
+		setTimeout(() => {
+			try {
+				process.kill(-child.pid, "SIGKILL");
+			} catch {
+				try {
+					child.kill("SIGKILL");
+				} catch {}
+			}
+		}, 5e3).unref();
+	}
+}
+let injectingCount = 0;
+const injectWaiters = [];
+function acquireInjectSlot() {
+	const cap = Math.max(1, Number(cfg("maxConcurrentInjects")) || 1);
+	if (injectingCount < cap) {
+		injectingCount++;
+		return Promise.resolve();
+	}
+	return new Promise((res) => {
+		injectWaiters.push(() => {
+			injectingCount++;
+			res();
+		});
+	});
+}
+function releaseInjectSlot() {
+	injectingCount = Math.max(0, injectingCount - 1);
+	const next = injectWaiters.shift();
+	if (next) next();
+}
+async function spawnAgentInject(args) {
+	await acquireInjectSlot();
+	try {
+		return await spawnAgentInjectRaw(args);
+	} finally {
+		releaseInjectSlot();
+	}
+}
+function spawnAgentInjectRaw(args) {
+	const { sessionId, message, timeoutMs, channel, replyTo, replyAccount } = args;
+	return new Promise((resolve) => {
+		if (!resolvedOpenclawCli) {
+			resolve({
+				ok: false,
+				code: "cli_missing",
+				error: "openclaw CLI not found"
+			});
+			return;
+		}
+		const cliArgs = [
+			...resolvedOpenclawCli.prefixArgs,
+			"agent",
+			"--session-id",
+			sessionId,
+			"--message",
+			message,
+			"--deliver",
+			"--json"
+		];
+		if (channel) cliArgs.push("--channel", channel);
+		if (replyTo) cliArgs.push("--reply-to", replyTo);
+		if (replyAccount) cliArgs.push("--reply-account", replyAccount);
+		let child;
+		try {
+			child = spawn(resolvedOpenclawCli.exe, cliArgs, {
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				windowsHide: true
+			});
+		} catch (e) {
+			resolve({
+				ok: false,
+				code: "spawn_failed",
+				error: e?.message ?? String(e)
+			});
+			return;
+		}
+		let stdout = "";
+		let stderr = "";
+		let finished = false;
+		const finish = (result) => {
+			if (finished) return;
+			finished = true;
+			clearTimeout(timer);
+			resolve(result);
+		};
+		const timer = setTimeout(() => {
+			try {
+				child.kill("SIGKILL");
+			} catch {}
+			finish({
+				ok: false,
+				code: "timeout",
+				error: `agent CLI did not return within ${timeoutMs}ms`
+			});
+		}, timeoutMs);
+		child.stdout?.on("data", (c) => {
+			stdout += c.toString();
+		});
+		child.stderr?.on("data", (c) => {
+			stderr += c.toString();
+		});
+		child.on("error", (e) => finish({
+			ok: false,
+			code: "spawn_error",
+			error: e.message
+		}));
+		child.on("close", (code) => {
+			if (code === 0) {
+				finish({
+					ok: true,
+					stdout,
+					stderr
+				});
+				return;
+			}
+			let errCode = "exit_nonzero";
+			let errMsg = stderr.trim() || stdout.trim() || `exit ${code}`;
+			try {
+				const parsed = JSON.parse(stdout);
+				if (parsed && typeof parsed === "object") {
+					if (parsed.code) errCode = String(parsed.code);
+					if (parsed.error) errMsg = String(parsed.error);
+				}
+			} catch {}
+			if (errCode === "exit_nonzero") {
+				const lower = errMsg.toLowerCase();
+				if (lower.includes("session") && (lower.includes("not found") || lower.includes("unknown") || lower.includes("missing") || lower.includes("does not exist"))) errCode = "session_not_found";
+			}
+			finish({
+				ok: false,
+				code: errCode,
+				error: errMsg
+			});
+		});
+	});
+}
+function emitPerfLog(inst, event, extra) {
+	const ts = Date.now();
+	const line = `[stream:${inst.id}] [perf] ${event} ts=${ts}${extra ? " " + extra : ""}`;
+	if (streamLogger?.info) streamLogger.info(line);
+	if (inst.perfLogFile) try {
+		appendFileSync(inst.perfLogFile, line + "\n");
+	} catch {}
+}
+function armIdleWatchdog(inst) {
+	if (inst.idleTimeoutMs <= 0 || inst.stopped) return;
+	if (inst.idleWatchdogTimer) clearTimeout(inst.idleWatchdogTimer);
+	inst.idleWatchdogTimer = setTimeout(() => onIdleTimeout(inst), inst.idleTimeoutMs);
+	inst.idleWatchdogTimer.unref?.();
+}
+function onIdleTimeout(inst) {
+	inst.idleWatchdogTimer = null;
+	if (inst.stopped) return;
+	const idleMs = Date.now() - inst.lastLineAt;
+	if (idleMs < inst.idleTimeoutMs) {
+		const remaining = Math.max(1, inst.idleTimeoutMs - idleMs);
+		inst.idleWatchdogTimer = setTimeout(() => onIdleTimeout(inst), remaining);
+		inst.idleWatchdogTimer.unref?.();
+		return;
+	}
+	if (!cfg("emitLifecycleEvents")) return;
+	const idleSec = Math.round(idleMs / 1e3);
+	const msg = `${inst.prefix}[STREAM_IDLE id=${inst.id} idleSec=${idleSec} pid=${inst.child.pid ?? "?"}]`;
+	spawnAgentInject({
+		sessionId: inst.capturedSessionId,
+		message: msg,
+		timeoutMs: cfg("agentTimeoutMs"),
+		channel: inst.capturedChannel,
+		replyTo: inst.capturedReplyTo,
+		replyAccount: inst.capturedReplyAccount
+	}).catch((e) => {
+		streamLogger?.warn?.(`[stream:${inst.id}] STREAM_IDLE inject failed: ${e?.message ?? e}`);
+	});
+}
+const PREEMPT_REGEX = /"trigger"\s*:\s*"(speech_your_turn|vote_phase_start)"/;
+const PREEMPT_DEDUP_MS = 1e3;
+function matchPreemptTrigger(line) {
+	const m = PREEMPT_REGEX.exec(line);
+	return m ? m[1] : null;
+}
+const GAME_EVENT_REGEX = /"exit_reason"\s*:\s*\[?"(game_start|game_over)"/;
+function matchGameEvent(line) {
+	const m = GAME_EVENT_REGEX.exec(line);
+	return m ? m[1] : null;
+}
+const SERVER_GAME_ID_REGEX = /"game_id"\s*:\s*"([^"]+)"/;
+/** 从 NDJSON 行中提取服务端 game_id，替换本地生成的临时 id */
+function captureServerGameId(inst, line) {
+	const m = SERVER_GAME_ID_REGEX.exec(line);
+	if (m && m[1] !== inst.gameId) {
+		const isFirst = !inst.gameId;
+		inst.gameId = m[1];
+		if (isFirst) captureMonitorEvent(`monitor.started gid=${inst.gameId}`, "info", {
+			monitor_id: inst.id,
+			game_id: inst.gameId,
+			command: inst.command,
+			session_key: inst.capturedSessionKey ?? ""
+		}, {
+			pid: inst.child.pid,
+			autoRestart: inst.spawnOpts.autoRestart,
+			maxRestarts: inst.spawnOpts.maxRestarts
+		});
+	}
+}
+function preemptCancel(inst, trigger) {
+	if (!abortAgentHarnessRun) {
+		emitPerfLog(inst, "preempt_skipped", `reason=sdk_unavailable`);
+		return;
+	}
+	const now = Date.now();
+	if (trigger === inst.lastPreemptTrigger && now - inst.lastPreemptAt < PREEMPT_DEDUP_MS) {
+		emitPerfLog(inst, "preempt_deduped", `trigger=${trigger} sinceLast=${now - inst.lastPreemptAt}ms`);
+		return;
+	}
+	inst.lastPreemptTrigger = trigger;
+	inst.lastPreemptAt = now;
+	let sessionId;
+	if (inst.capturedSessionKey && resolveActiveEmbeddedRunSessionId) try {
+		sessionId = resolveActiveEmbeddedRunSessionId(inst.capturedSessionKey);
+	} catch (e) {
+		emitPerfLog(inst, "preempt_resolve_failed", `key=${inst.capturedSessionKey} err=${e?.message ?? e}`);
+	}
+	sessionId ??= inst.capturedSessionId;
+	if (!sessionId) {
+		emitPerfLog(inst, "preempt_skipped", `reason=no_session`);
+		return;
+	}
+	let aborted = false;
+	try {
+		aborted = abortAgentHarnessRun(sessionId) === true;
+	} catch (e) {
+		emitPerfLog(inst, "preempt_abort_failed", `sessionId=${sessionId} err=${e?.message ?? e}`);
+		return;
+	}
+	emitPerfLog(inst, "preempt_done", `sessionId=${sessionId} aborted=${aborted}`);
+}
+function enqueueLine(inst, line) {
+	if (inst.stopped) return;
+	if (inst.filterRegex) {
+		let matched = true;
+		try {
+			matched = inst.filterRegex.test(String(line));
+		} catch (e) {
+			streamLogger?.warn?.(`[stream:${inst.id}] filter regex threw, passing line through: ${e?.message ?? e}`);
+		}
+		if (!matched) return;
+	}
+	captureServerGameId(inst, line);
+	const trigger = matchPreemptTrigger(line);
+	if (trigger) {
+		preemptCancel(inst, trigger);
+		inst.flushAllPending = true;
+	}
+	const gameEvent = matchGameEvent(line);
+	if (gameEvent === "game_start") captureMonitorEvent(`game.started gid=${inst.gameId}`, "info", {
+		monitor_id: inst.id,
+		game_id: inst.gameId,
+		command: inst.command,
+		session_key: inst.capturedSessionKey ?? ""
+	});
+	else if (gameEvent === "game_over") captureMonitorEvent(`game.exited gid=${inst.gameId}`, "info", {
+		monitor_id: inst.id,
+		game_id: inst.gameId,
+		command: inst.command,
+		session_key: inst.capturedSessionKey ?? ""
+	});
+	inst.lastLineAt = Date.now();
+	armIdleWatchdog(inst);
+	if (inst.pendingLines.length === 0) inst.batchStartedAt = Date.now();
+	inst.pendingLines.push(line);
+	if (inst.pendingLines.length > inst.maxQueueLines) {
+		const drop = inst.pendingLines.length - inst.maxQueueLines;
+		inst.pendingLines.splice(0, drop);
+		inst.stats.dropped += drop;
+		streamLogger?.warn?.(`[stream:${inst.id}] backpressure: dropped ${drop} oldest lines (cap ${inst.maxQueueLines})`);
+	}
+	emitPerfLog(inst, "line_enqueued", `delta=${Date.now() - inst.lastLineTs}ms pending=${inst.pendingLines.length}`);
+	const ageExceeded = Date.now() - inst.batchStartedAt >= inst.maxBatchAgeMs;
+	if (trigger || inst.pendingLines.length >= inst.maxBatchLines || ageExceeded) flushNow(inst);
+	else {
+		if (inst.flushTimer) clearTimeout(inst.flushTimer);
+		inst.flushTimer = setTimeout(() => flushNow(inst), inst.debounceMs);
+	}
+}
+function flushNow(inst) {
+	if (inst.flushTimer) {
+		clearTimeout(inst.flushTimer);
+		inst.flushTimer = null;
+	}
+	if (inst.stopped) return;
+	if (inst.pendingLines.length === 0) return;
+	if (inst.inFlight) {
+		inst.flushTimer = setTimeout(() => flushNow(inst), inst.debounceMs);
+		return;
+	}
+	const take = inst.flushAllPending ? inst.pendingLines.length : inst.maxBatchLines;
+	inst.flushAllPending = false;
+	const lines = inst.pendingLines.splice(0, take);
+	inst.batchStartedAt = inst.pendingLines.length === 0 ? 0 : Date.now();
+	inst.flushStartTs = Date.now();
+	emitPerfLog(inst, "flush_start", `deltaFromLine=${inst.flushStartTs - inst.lastLineTs}ms batch=${lines.length} pending=${inst.pendingLines.length}`);
+	dispatch(inst, lines).catch((e) => {
+		streamLogger?.warn?.(`[stream:${inst.id}] dispatch crashed: ${e?.message ?? e}`);
+	});
+	if (!inst.stopped && inst.pendingLines.length > 0) inst.flushTimer = setTimeout(() => flushNow(inst), inst.debounceMs);
+}
+async function acquireSerial(inst) {
+	if (!inst.inFlight) {
+		inst.inFlight = true;
+		return;
+	}
+	await new Promise((res) => inst.inFlightWaiters.push(res));
+	inst.inFlight = true;
+}
+function releaseSerial(inst) {
+	inst.inFlight = false;
+	const next = inst.inFlightWaiters.shift();
+	if (next) next();
+}
+/** Fire-and-forget inject that respects the per-instance serial lock. */
+function injectSerialized(inst, message) {
+	acquireSerial(inst).then(() => spawnAgentInject({
+		sessionId: inst.capturedSessionId,
+		message,
+		timeoutMs: cfg("agentTimeoutMs"),
+		channel: inst.capturedChannel,
+		replyTo: inst.capturedReplyTo,
+		replyAccount: inst.capturedReplyAccount
+	})).finally(() => releaseSerial(inst)).catch(() => {});
+}
+const MAX_DISPATCH_RETRIES = 1;
+/** Windows CreateProcess 命令行上限 ~32KB,留余量设为 24KB。超过此值自动分片。 */
+const MAX_MESSAGE_BYTES = 24e3;
+/** 将 message 按近似字节数拆分为多组 lines,尽量不切割单行。 */
+function splitLinesByBytes(lines, maxBytes, prefixLen) {
+	const chunks = [];
+	let cur = [];
+	let curBytes = 0;
+	for (const line of lines) {
+		const lineBytes = Buffer.byteLength(line, "utf-8") + prefixLen + 1;
+		if (cur.length > 0 && curBytes + lineBytes > maxBytes) {
+			chunks.push(cur);
+			cur = [];
+			curBytes = 0;
+		}
+		cur.push(line);
+		curBytes += lineBytes;
+	}
+	if (cur.length > 0) chunks.push(cur);
+	return chunks;
+}
+/** 单次注入(含重试),返回注入结果并更新 stats。调用方负责 serial lock。 */
+async function injectBatch(inst, lines) {
+	const message = lines.map((l) => `${inst.prefix}${l}`).join("\n");
+	let result = {
+		ok: false,
+		code: "not_attempted",
+		error: ""
+	};
+	for (let attempt = 0; attempt <= MAX_DISPATCH_RETRIES; attempt++) {
+		const injectStart = Date.now();
+		result = await spawnAgentInject({
+			sessionId: inst.capturedSessionId,
+			message,
+			timeoutMs: cfg("agentTimeoutMs"),
+			channel: inst.capturedChannel,
+			replyTo: inst.capturedReplyTo,
+			replyAccount: inst.capturedReplyAccount
+		});
+		emitPerfLog(inst, "inject_done", `ok=${result.ok} code=${result.code} duration=${Date.now() - injectStart}ms attempt=${attempt} totalFromFlush=${Date.now() - inst.flushStartTs}ms`);
+		inst.lastDispatchAt = Date.now();
+		if (result.ok) break;
+		if (result.code === "session_not_found") break;
+		if (attempt < MAX_DISPATCH_RETRIES) streamLogger?.warn?.(`[stream:${inst.id}] dispatch retry ${attempt + 1}/${MAX_DISPATCH_RETRIES}: ${result.code} ${result.error}`);
+	}
+	if (result.ok) {
+		inst.stats.batches += 1;
+		inst.stats.lines += lines.length;
+		inst.stats.lastError = null;
+		inst.sessionNotFoundCount = 0;
+	} else {
+		inst.stats.lastError = `${result.code}: ${result.error}`;
+		streamLogger?.warn?.(`[stream:${inst.id}] inject failed: ${result.code} ${result.error}`);
+		inst.stats.dropped += lines.length;
+		if (result.code === "session_not_found") {
+			inst.sessionNotFoundCount += 1;
+			if (inst.sessionNotFoundCount > inst.sessionNotFoundMaxRetries) {
+				streamLogger?.warn?.(`[stream:${inst.id}] session_not_found ${inst.sessionNotFoundCount}x consecutively, stopping`);
+				stopInstance(inst.id, {
+					reason: "session_not_found",
+					emitLifecycle: false
+				}).catch(() => {});
+			}
+		} else inst.sessionNotFoundCount = 0;
+	}
+	return result;
+}
+async function dispatch(inst, lines) {
+	await acquireSerial(inst);
+	emitPerfLog(inst, "serial_acquired", `waitMs=${Date.now() - inst.flushStartTs}ms`);
+	try {
+		if (inst.stopped) {
+			inst.pendingLines = [...lines, ...inst.pendingLines];
+			return;
+		}
+		const wait = inst.lastDispatchAt + inst.minIntervalMs - Date.now();
+		if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+		emitPerfLog(inst, "interval_waited", `delta=${Date.now() - inst.flushStartTs}ms waited=${Math.max(0, wait)}ms`);
+		const chunks = splitLinesByBytes(lines, MAX_MESSAGE_BYTES, Buffer.byteLength(inst.prefix, "utf-8"));
+		for (let ci = 0; ci < chunks.length; ci++) {
+			if (inst.stopped) break;
+			if (ci > 0) {
+				const chunkWait = inst.lastDispatchAt + inst.minIntervalMs - Date.now();
+				if (chunkWait > 0) await new Promise((r) => setTimeout(r, chunkWait));
+			}
+			const result = await injectBatch(inst, chunks[ci]);
+			if (chunks.length > 1) emitPerfLog(inst, "chunk_injected", `chunk=${ci + 1}/${chunks.length} lines=${chunks[ci].length}`);
+			if (!result.ok && result.code === "session_not_found") break;
+		}
+	} finally {
+		releaseSerial(inst);
+		if (!inst.stopped && inst.pendingLines.length > 0 && !inst.flushTimer) inst.flushTimer = setTimeout(() => flushNow(inst), inst.debounceMs);
+	}
+}
+async function stopInstance(id, opts = {}) {
+	const { reason = "manual", emitLifecycle = true } = opts;
+	const inst = instances.get(id);
+	if (!inst) return null;
+	if (inst.stopped) return inst;
+	inst.stopped = true;
+	inst.explicitStop = true;
+	if (inst.restartTimer) {
+		clearTimeout(inst.restartTimer);
+		inst.restartTimer = null;
+	}
+	if (inst.flushTimer) {
+		clearTimeout(inst.flushTimer);
+		inst.flushTimer = null;
+	}
+	if (inst.idleWatchdogTimer) {
+		clearTimeout(inst.idleWatchdogTimer);
+		inst.idleWatchdogTimer = null;
+	}
+	if (inst.stdoutRl) {
+		inst.stdoutRl.close();
+		inst.stdoutRl = null;
+	}
+	if (inst.stderrRl) {
+		inst.stderrRl.close();
+		inst.stderrRl = null;
+	}
+	const drained = inst.pendingLines.splice(0, inst.pendingLines.length);
+	killTree(inst.child);
+	await new Promise((res) => {
+		if (inst.child.exitCode != null || inst.child.signalCode != null) return res();
+		let done = false;
+		const finish = () => {
+			if (!done) {
+				done = true;
+				res();
+			}
+		};
+		inst.child.once("close", finish);
+		setTimeout(finish, 6e3).unref();
+	});
+	instances.delete(id);
+	if (inst.perfLogFile) try {
+		const durSec = ((Date.now() - inst.startedAt) / 1e3).toFixed(1);
+		appendFileSync(inst.perfLogFile, `[SESSION_END id=${id} reason=${reason} ranSec=${durSec} batches=${inst.stats.batches} lines=${inst.stats.lines} dropped=${inst.stats.dropped} ts=${Date.now()}]
+`);
+	} catch {}
+	const emitTail = emitLifecycle && cfg("emitLifecycleEvents") && reason !== "gateway_stop";
+	if (drained.length > 0 || emitTail) {
+		let message = drained.map((l) => `${inst.prefix}${l}`).join("\n");
+		if (emitTail) {
+			const dur = ((Date.now() - inst.startedAt) / 1e3).toFixed(1);
+			const tail = `${inst.prefix}[STREAM_STOPPED id=${id} reason=${reason} ranSec=${dur} batches=${inst.stats.batches} lines=${inst.stats.lines}]`;
+			message = message ? message + "\n" + tail : tail;
+		}
+		injectSerialized(inst, message);
+	}
+	return inst;
+}
+function spawnChildProc(opts) {
+	return spawn(opts.command, opts.args, {
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		shell: opts.useShell,
+		windowsHide: true,
+		cwd: opts.cwd || process.cwd(),
+		env: {
+			...process.env,
+			NO_COLOR: "1",
+			FORCE_COLOR: "0",
+			...opts.env ?? {}
+		},
+		detached: process.platform !== "win32"
+	});
+}
+function attachChildListeners(inst) {
+	const child = inst.child;
+	const id = inst.id;
+	if (inst.stdoutRl) {
+		inst.stdoutRl.close();
+		inst.stdoutRl = null;
+	}
+	if (inst.stderrRl) {
+		inst.stderrRl.close();
+		inst.stderrRl = null;
+	}
+	if (child.stdout) {
+		const rl = createInterface({ input: child.stdout });
+		inst.stdoutRl = rl;
+		rl.on("line", (line) => {
+			inst.lastLineTs = Date.now();
+			emitPerfLog(inst, "line_recv");
+			enqueueLine(inst, line);
+		});
+	}
+	if (child.stderr) {
+		const rl = createInterface({ input: child.stderr });
+		inst.stderrRl = rl;
+		rl.on("line", (line) => {
+			inst.lastLineTs = Date.now();
+			emitPerfLog(inst, "line_recv", "stream=stderr");
+			enqueueLine(inst, `[stderr] ${line}`);
+		});
+	}
+	child.on("error", (e) => {
+		streamLogger?.warn?.(`[stream:${id}] child error: ${e?.message ?? e}`);
+	});
+	child.on("close", (code, signal) => {
+		if (inst.stopped) return;
+		const cleanExit = code === 0;
+		if (inst.autoRestart && !inst.explicitStop && !cleanExit && inst.restartTimestamps.length < inst.maxRestarts) {
+			const attempt = inst.restartTimestamps.length + 1;
+			inst.restartTimestamps.push(Date.now());
+			inst.stats.restarts += 1;
+			captureMonitorEvent(`monitor.crashed gid=${inst.gameId} attempt=${attempt}/${inst.maxRestarts}`, "warning", {
+				monitor_id: id,
+				game_id: inst.gameId,
+				command: inst.command,
+				session_key: inst.capturedSessionKey ?? ""
+			}, {
+				code,
+				signal,
+				attempt,
+				maxRestarts: inst.maxRestarts,
+				pid: child.pid
+			});
+			const backoff = Math.min(inst.restartBackoffBaseMs * Math.pow(2, attempt - 1), inst.restartBackoffMaxMs);
+			if (inst.flushTimer) {
+				clearTimeout(inst.flushTimer);
+				inst.flushTimer = null;
+			}
+			if (inst.idleWatchdogTimer) {
+				clearTimeout(inst.idleWatchdogTimer);
+				inst.idleWatchdogTimer = null;
+			}
+			if (cfg("emitLifecycleEvents")) {
+				const msg = `${inst.prefix}[STREAM_RESTART id=${id} code=${code ?? signal ?? "?"} attempt=${attempt}/${inst.maxRestarts} delayMs=${backoff}]`;
+				spawnAgentInject({
+					sessionId: inst.capturedSessionId,
+					message: msg,
+					timeoutMs: cfg("agentTimeoutMs"),
+					channel: inst.capturedChannel,
+					replyTo: inst.capturedReplyTo,
+					replyAccount: inst.capturedReplyAccount
+				}).catch((e) => {
+					streamLogger?.warn?.(`[stream:${inst.id}] STREAM_RESTART inject failed: ${e?.message ?? e}`);
+				});
+			}
+			inst.restartTimer = setTimeout(() => {
+				inst.restartTimer = null;
+				if (inst.explicitStop || inst.stopped) return;
+				try {
+					inst.child = spawnChildProc(inst.spawnOpts);
+					inst.startedAt = Date.now();
+					inst.lastLineAt = Date.now();
+					attachChildListeners(inst);
+					armIdleWatchdog(inst);
+					captureMonitorEvent(`monitor.restarted gid=${inst.gameId} attempt=${attempt}/${inst.maxRestarts}`, "info", {
+						monitor_id: id,
+						game_id: inst.gameId,
+						command: inst.command,
+						session_key: inst.capturedSessionKey ?? ""
+					}, {
+						attempt,
+						maxRestarts: inst.maxRestarts,
+						pid: inst.child.pid
+					});
+				} catch (e) {
+					streamLogger?.warn?.(`[stream:${id}] respawn failed: ${e?.message ?? e}`);
+					inst.stopped = true;
+					captureMonitorException(`monitor.respawn_failed gid=${inst.gameId} attempt=${attempt}/${inst.maxRestarts}`, {
+						monitor_id: id,
+						game_id: inst.gameId,
+						command: inst.command,
+						session_key: inst.capturedSessionKey ?? ""
+					}, {
+						attempt,
+						maxRestarts: inst.maxRestarts,
+						error: e?.message ?? String(e)
+					});
+					if (cfg("emitLifecycleEvents")) {
+						const failMsg = `${inst.prefix}[STREAM_RESTART_FAILED id=${id} reason=spawn_error error=${e?.message ?? e}]`;
+						spawnAgentInject({
+							sessionId: inst.capturedSessionId,
+							message: failMsg,
+							timeoutMs: cfg("agentTimeoutMs"),
+							channel: inst.capturedChannel,
+							replyTo: inst.capturedReplyTo,
+							replyAccount: inst.capturedReplyAccount
+						}).catch((e2) => {
+							streamLogger?.warn?.(`[stream:${inst.id}] STREAM_RESTART_FAILED inject failed: ${e2?.message ?? e2}`);
+						});
+					}
+					setTimeout(() => instances.delete(id), 200).unref();
+				}
+			}, backoff);
+			return;
+		}
+		if (inst.flushTimer) {
+			clearTimeout(inst.flushTimer);
+			inst.flushTimer = null;
+		}
+		if (inst.idleWatchdogTimer) {
+			clearTimeout(inst.idleWatchdogTimer);
+			inst.idleWatchdogTimer = null;
+		}
+		const drained = inst.pendingLines.splice(0, inst.pendingLines.length);
+		inst.stopped = true;
+		const emitExit = cfg("emitLifecycleEvents");
+		if (drained.length > 0 || emitExit) {
+			let message = drained.map((l) => `${inst.prefix}${l}`).join("\n");
+			if (emitExit) {
+				const gaveUp = inst.autoRestart && !inst.explicitStop && inst.restartTimestamps.length >= inst.maxRestarts && inst.restartTimestamps.length > 0;
+				if (gaveUp) captureMonitorException(`monitor.restart_gave_up gid=${inst.gameId} attempts=${inst.maxRestarts}`, {
+					monitor_id: id,
+					game_id: inst.gameId,
+					command: inst.command,
+					session_key: inst.capturedSessionKey ?? ""
+				}, {
+					lastCode: code ?? signal,
+					totalAttempts: inst.maxRestarts,
+					pid: child.pid
+				});
+				else if (cleanExit) {
+					const ranSec = ((Date.now() - inst.startedAt) / 1e3).toFixed(1);
+					captureMonitorEvent(`monitor.exited gid=${inst.gameId} code=0 ranSec=${ranSec}`, "info", {
+						monitor_id: id,
+						game_id: inst.gameId,
+						command: inst.command,
+						session_key: inst.capturedSessionKey ?? ""
+					}, {
+						code: 0,
+						ranSec,
+						batches: inst.stats.batches,
+						lines: inst.stats.lines,
+						pid: child.pid
+					});
+				}
+				const tail = gaveUp ? `${inst.prefix}[STREAM_RESTART_GAVE_UP id=${id} attempts=${inst.maxRestarts} lastCode=${code ?? signal ?? "?"}]` : `${inst.prefix}[STREAM_EXIT id=${id} code=${code ?? signal ?? "?"}]`;
+				message = message ? message + "\n" + tail : tail;
+			}
+			injectSerialized(inst, message);
+		}
+		setTimeout(() => instances.delete(id), 200).unref();
+	});
+}
+function startInstance(opts) {
+	const child = spawnChildProc(opts);
+	const inst = {
+		id: opts.id,
+		command: opts.command,
+		args: opts.args,
+		cwd: opts.cwd || process.cwd(),
+		filterRegex: opts.filterRegex,
+		prefix: opts.prefix,
+		debounceMs: opts.debounceMs,
+		minIntervalMs: opts.minIntervalMs,
+		maxBatchLines: opts.maxBatchLines,
+		maxQueueLines: opts.maxQueueLines,
+		capturedSessionId: opts.capturedSessionId,
+		capturedSessionKey: opts.capturedSessionKey,
+		capturedChannel: opts.capturedChannel,
+		capturedReplyTo: opts.capturedReplyTo,
+		capturedReplyAccount: opts.capturedReplyAccount,
+		child,
+		stdoutRl: null,
+		stderrRl: null,
+		pendingLines: [],
+		flushTimer: null,
+		inFlight: false,
+		inFlightWaiters: [],
+		lastDispatchAt: 0,
+		startedAt: Date.now(),
+		stopped: false,
+		explicitStop: false,
+		autoRestart: opts.autoRestart,
+		maxRestarts: opts.maxRestarts,
+		restartBackoffBaseMs: opts.restartBackoffBaseMs,
+		restartBackoffMaxMs: opts.restartBackoffMaxMs,
+		restartTimestamps: [],
+		restartTimer: null,
+		spawnOpts: opts,
+		stats: {
+			batches: 0,
+			lines: 0,
+			dropped: 0,
+			lastError: null,
+			restarts: 0
+		},
+		lastLineAt: Date.now(),
+		idleTimeoutMs: opts.idleTimeoutMs,
+		idleWatchdogTimer: null,
+		sessionNotFoundCount: 0,
+		sessionNotFoundMaxRetries: opts.sessionNotFoundMaxRetries,
+		maxBatchAgeMs: opts.maxBatchAgeMs,
+		batchStartedAt: 0,
+		lastLineTs: Date.now(),
+		flushStartTs: 0,
+		lastPreemptAt: 0,
+		lastPreemptTrigger: null,
+		flushAllPending: false,
+		perfLogFile: null,
+		gameId: ""
+	};
+	const perfDir = streamConfig?.streamPerfLogDir;
+	if (perfDir) try {
+		if (!existsSync(perfDir)) mkdirSync(perfDir, { recursive: true });
+		inst.perfLogFile = `${perfDir}/perf-${opts.id}.log`;
+		appendFileSync(inst.perfLogFile, `[SESSION_START id=${opts.id} ts=${Date.now()}]
+`);
+	} catch {}
+	instances.set(opts.id, inst);
+	attachChildListeners(inst);
+	armIdleWatchdog(inst);
+	return inst;
+}
+async function doStart(ctx, params) {
+	if (!resolvedOpenclawCli) return "Error: openclaw CLI not found. Set plugins.entries.clawclaw.config.streamOpenclawCli to its absolute path.";
+	const command = String(params?.command ?? "").trim();
+	if (!command) return "Error: command is required.";
+	const id = params?.id ? String(params.id) : generateId();
+	if (!ID_REGEX.test(id)) return "Error: id must match /^[A-Za-z0-9_-]{1,32}$/.";
+	const max = cfg("maxInstances");
+	if (instances.size >= max && !instances.has(id)) return `Error: max ${max} concurrent streams. Stop one before starting another.`;
+	let filterRegex = null;
+	if (params?.filter) try {
+		filterRegex = new RegExp(String(params.filter));
+	} catch (e) {
+		return `Error: invalid filter regex: ${e?.message ?? e}`;
+	}
+	const args = Array.isArray(params?.args) ? params.args.map(String) : [];
+	let useShell;
+	if (params?.shell === void 0 || params?.shell === null) useShell = !/^(node|node\.exe)$/i.test(command);
+	else if (typeof params.shell === "boolean" || typeof params.shell === "string") useShell = params.shell;
+	else return "Error: shell must be boolean or string (path to shell binary).";
+	const prefix = params?.prefix != null ? String(params.prefix) : `[stream:${id}] `;
+	if (instances.has(id)) await stopInstance(id, {
+		reason: "replaced",
+		emitLifecycle: false
+	});
+	let inst;
+	try {
+		inst = startInstance({
+			id,
+			command,
+			args,
+			cwd: params?.cwd ? String(params.cwd) : void 0,
+			env: params?.env && typeof params.env === "object" ? params.env : void 0,
+			filterRegex,
+			prefix,
+			debounceMs: Number(params?.debounceMs ?? cfg("debounceMs")),
+			minIntervalMs: Number(params?.minIntervalMs ?? cfg("minIntervalMs")),
+			maxBatchLines: Number(params?.maxBatchLines ?? cfg("maxBatchLines")),
+			maxQueueLines: Number(params?.maxQueueLines ?? cfg("maxQueueLines")),
+			useShell,
+			capturedSessionId: ctx.sessionId,
+			capturedSessionKey: ctx.sessionKey,
+			capturedChannel: ctx.deliveryContext?.channel ?? ctx.messageChannel,
+			capturedReplyTo: ctx.deliveryContext?.to ?? ctx.currentChannelId,
+			capturedReplyAccount: ctx.deliveryContext?.accountId ?? ctx.agentAccountId,
+			autoRestart: params?.autoRestart != null ? Boolean(params.autoRestart) : cfg("autoRestart"),
+			maxRestarts: Number(params?.maxRestarts ?? cfg("maxRestarts")),
+			restartBackoffBaseMs: cfg("restartBackoffBaseMs"),
+			restartBackoffMaxMs: cfg("restartBackoffMaxMs"),
+			idleTimeoutMs: Number(cfg("idleTimeoutMs")),
+			sessionNotFoundMaxRetries: Number(cfg("sessionNotFoundMaxRetries")),
+			maxBatchAgeMs: Number(cfg("maxBatchAgeMs"))
+		});
+	} catch (e) {
+		return `Error: failed to spawn '${command}': ${e?.message ?? e}`;
+	}
+	return [
+		`Stream started.`,
+		`  id: ${inst.id}`,
+		`  pid: ${inst.child.pid ?? "?"}`,
+		`  command: ${command}${args.length ? " " + args.join(" ") : ""}`,
+		`  session: ${ctx.sessionKey ?? "(unknown key)"} / ${ctx.sessionId}`,
+		`  filter: ${filterRegex ? filterRegex.source : "(none)"}`,
+		`  debounce=${inst.debounceMs}ms minInterval=${inst.minIntervalMs}ms maxBatch=${inst.maxBatchLines} maxQueue=${inst.maxQueueLines}`,
+		`  autoRestart=${inst.autoRestart} maxRestarts=${inst.maxRestarts}`
+	].join("\n");
+}
+function shortcutCclCommand() {
+	if (!resolvedCcl) return null;
+	return {
+		command: resolvedCcl.exe,
+		baseArgs: [...resolvedCcl.prefixArgs]
+	};
+}
+let globalHandlersRegistered = false;
+function registerGlobalCrashGuards() {
+	if (globalHandlersRegistered) return;
+	globalHandlersRegistered = true;
+	process.on("unhandledRejection", (reason) => {
+		streamLogger?.warn?.(`[clawclaw:stream] unhandledRejection swallowed: ${reason?.stack ?? reason?.message ?? String(reason)}`);
+	});
+	process.on("uncaughtException", (err) => {
+		streamLogger?.warn?.(`[clawclaw:stream] uncaughtException swallowed: ${err?.stack ?? err?.message ?? String(err)}`);
+	});
+}
+function registerStreamTools(api, configSlice, cclInvoker) {
+	streamLogger = api.logger;
+	streamConfig = configSlice ?? {};
+	resolvedCcl = cclInvoker;
+	resolvedOpenclawCli = resolveOpenclawCli(configSlice?.streamOpenclawCli);
+	configureSentry(configSlice?.streamSentryDsn, streamLogger);
+	registerGlobalCrashGuards();
+	if (!resolvedOpenclawCli) streamLogger?.warn?.("[clawclaw] openclaw CLI not found for stream subsystem; clawclaw_stream_* tools will fail. Set plugins.entries.clawclaw.config.streamOpenclawCli.");
+	else streamLogger?.info?.(`[clawclaw:stream] using openclaw CLI: ${resolvedOpenclawCli.display}`);
+	api.registerTool((ctx) => {
+		if (!ctx?.sessionId) return null;
+		return {
+			name: "clawclaw_game_status",
+			description: "List all running background game streams with their stats (pid, runtime, batches, lines, queue depth, last error).",
+			parameters: {
+				type: "object",
+				additionalProperties: false,
+				properties: {}
+			},
+			async execute(_callId) {
+				if (instances.size === 0) return "No streams running.";
+				const lines = [`Streams (${instances.size}):`];
+				for (const inst of instances.values()) {
+					const ageSec = ((Date.now() - inst.startedAt) / 1e3).toFixed(1);
+					const cmd = inst.command + (inst.args.length ? " " + inst.args.join(" ") : "");
+					const sameSession = inst.capturedSessionId === ctx.sessionId ? "" : " (other session)";
+					lines.push(`- ${inst.id}${sameSession} | pid=${inst.child.pid ?? "?"} | session=${inst.capturedSessionKey ?? "?"} | ran=${ageSec}s | batches=${inst.stats.batches} | lines=${inst.stats.lines} | dropped=${inst.stats.dropped} | queue=${inst.pendingLines.length} | restarts=${inst.stats.restarts}/${inst.maxRestarts}${inst.autoRestart ? "" : " (autoRestart=off)"} | lastErr=${inst.stats.lastError ?? "-"} | cmd=${cmd}`);
+				}
+				return lines.join("\n");
+			}
+		};
+	}, { name: "clawclaw_game_status" });
+	api.registerTool((ctx) => {
+		if (!ctx?.sessionId) return null;
+		return {
+			name: "clawclaw_game_stop",
+			description: "Stop one (by id) or all background streams started via clawclaw_game_start. Use after `ccl game quit` (in-game) — the stream does not auto-exit when the daemon stops mid-game. ",
+			parameters: {
+				type: "object",
+				additionalProperties: false,
+				properties: { id: {
+					type: "string",
+					description: "Instance id; omit to stop all."
+				} }
+			},
+			async execute(_callId, params) {
+				if (instances.size === 0) return "No streams running.";
+				if (params?.id) {
+					const id = String(params.id);
+					if (!instances.has(id)) return `No stream with id '${id}'.`;
+					const inst = await stopInstance(id, { reason: "manual" });
+					if (!inst) return `Failed to stop ${id}.`;
+					return `Stopped ${id} (ran ${((Date.now() - inst.startedAt) / 1e3).toFixed(1)}s, ${inst.stats.batches} batches, ${inst.stats.lines} lines, ${inst.stats.dropped} dropped).`;
+				}
+				const ids = [...instances.keys()];
+				for (const id of ids) try {
+					await stopInstance(id, { reason: "manual" });
+				} catch {}
+				return `Stopped ${ids.length} stream(s): ${ids.join(", ")}.`;
+			}
+		};
+	}, { name: "clawclaw_game_stop" });
+	api.registerTool((ctx) => {
+		if (!ctx?.sessionId) return null;
+		return {
+			name: "clawclaw_game_start",
+			description: "Start `ccl game start` as a background stream — attaches to an active game or joins the queue, waits for allocation, then pushes every matchmaking + gameplay event as new agent turns until game_over. One launch per match cycle. Also use for crash recovery (re-attach after a non-zero exit) — re-using the same id replaces the dead instance. Use clawclaw_game_stop({id}) to stop mid-cycle (after ccl game leave / quit).",
+			parameters: {
+				type: "object",
+				additionalProperties: false,
+				properties: { id: {
+					type: "string",
+					description: "Optional instance id; auto-generated if omitted. Re-using an id replaces a dead instance."
+				} }
+			},
+			async execute(_callId, params) {
+				const c = shortcutCclCommand();
+				if (!c) return "Error: ccl invoker not resolved; cannot run shortcut.";
+				return await doStart(ctx, {
+					command: c.command,
+					args: [
+						...c.baseArgs,
+						"game",
+						"start"
+					],
+					id: params?.id,
+					prefix: `[clawclaw:game] `,
+					shell: false,
+					env: { CLAWCLAW_STREAMED: "1" }
+				});
+			}
+		};
+	}, { name: "clawclaw_game_start" });
+	if (typeof api.on === "function") api.on("gateway_stop", async () => {
+		for (const id of [...instances.keys()]) try {
+			await stopInstance(id, {
+				reason: "gateway_stop",
+				emitLifecycle: false
+			});
+		} catch {}
+		await closeSentry();
+	});
+}
+//#endregion
+//#region src/index.ts
+/**
+* openclaw-clawclaw — OpenClaw plugin entry
+* ─────────────────────────────────────────
+* 工具组成:
+*   - typed `clawclaw_*` 工具:大部分由 `ccl _schema` 元数据自动生成;
+*     少数(如 clawclaw_do)手写覆盖以补足 schema 表达不出的约束(如 oneOf)。
+*   - clawclaw_run:raw passthrough,仅在 typed 工具未覆盖时使用,需 confirm:true。
+*
+* 对 clawclaw-cli 升级的兼容性:新增 `ccl <cmd>` 子命令时,只需重启 gateway,
+* 自动生成的工具会立刻暴露,无需重新发布插件。
+*/
+const PLUGIN_ID = "clawclaw";
+let pluginConfig = {};
+let pluginLogger = null;
+let resolvedCli = null;
+function readPluginConfigSlice(rootCfg) {
+	const entry = rootCfg?.plugins?.entries?.[PLUGIN_ID];
+	if (entry && typeof entry === "object" && entry.config && typeof entry.config === "object") return entry.config;
+	return {};
+}
+function resolveCliInvoker(override) {
+	const isWin = process.platform === "win32";
+	const candidates = [];
+	if (override) candidates.push(override);
+	if (!override) {
+		const binJs = resolvePackageBin(import.meta.url, "clawclaw-cli", join("bin", "clawclaw-cli.mjs"));
+		if (binJs) return {
+			exe: process.execPath,
+			prefixArgs: [binJs],
+			display: `${process.execPath} ${binJs}`
+		};
+	}
+	const exeNames = isWin ? [
+		"ccl.cmd",
+		"ccl.exe",
+		"ccl",
+		"clawclaw-cli.cmd",
+		"clawclaw-cli.exe",
+		"clawclaw-cli"
+	] : ["ccl", "clawclaw-cli"];
+	const pathDirs = (process.env.PATH || "").split(delimiter).filter(Boolean);
+	for (const dir of pathDirs) for (const exe of exeNames) candidates.push(`${dir}${sep}${exe}`);
+	for (const c of candidates) {
+		try {
+			if (!existsSync(c) || !statSync(c).isFile()) continue;
+		} catch {
+			continue;
+		}
+		const lower = c.toLowerCase();
+		if (lower.endsWith(".exe")) return {
+			exe: c,
+			prefixArgs: [],
+			display: c
+		};
+		if (lower.endsWith(".mjs") || lower.endsWith(".js")) return {
+			exe: process.execPath,
+			prefixArgs: [c],
+			display: `${process.execPath} ${c}`
+		};
+		if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
+			const lastSep = c.lastIndexOf(sep);
+			const dir = lastSep >= 0 ? c.substring(0, lastSep) : ".";
+			const fname = c.substring(lastSep + 1).replace(/\.(cmd|bat)$/i, "");
+			const heuristicMjs = join(dir, "node_modules", fname === "ccl" ? "clawclaw-cli" : fname, "bin", "clawclaw-cli.mjs");
+			try {
+				if (existsSync(heuristicMjs) && statSync(heuristicMjs).isFile()) return {
+					exe: process.execPath,
+					prefixArgs: [heuristicMjs],
+					display: `${process.execPath} ${heuristicMjs}`
+				};
+			} catch {}
+			continue;
+		}
+		if (!isWin) return {
+			exe: c,
+			prefixArgs: [],
+			display: c
+		};
+	}
+	return null;
+}
+async function runCcl(args, opts = {}) {
+	if (!resolvedCli) throw new Error("clawclaw-cli executable not found; set plugins.entries.clawclaw.config.cclPath");
+	const { timeoutMs = pluginConfig.spawnTimeoutMs ?? 3e4 } = opts;
+	const env = {
+		...process.env,
+		NO_COLOR: "1"
+	};
+	if (pluginConfig.workspaceDir) env.CLAWCLAW_WORKSPACE_DIR = pluginConfig.workspaceDir;
+	return await new Promise((resolve, reject) => {
+		const child = spawn(resolvedCli.exe, [...resolvedCli.prefixArgs, ...args], {
+			env,
+			windowsHide: true
+		});
+		let stdout = "";
+		let stderr = "";
+		const timer = setTimeout(() => {
+			try {
+				child.kill("SIGKILL");
+			} catch {}
+			reject(/* @__PURE__ */ new Error(`ccl ${args.join(" ")} timed out after ${timeoutMs}ms`));
+		}, timeoutMs);
+		child.stdout.on("data", (b) => {
+			stdout += b.toString();
+		});
+		child.stderr.on("data", (b) => {
+			stderr += b.toString();
+		});
+		child.on("error", (e) => {
+			clearTimeout(timer);
+			reject(e);
+		});
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			if (code !== 0) {
+				reject(/* @__PURE__ */ new Error(`ccl ${args.join(" ")} exited ${code}: ${stderr.trim() || stdout.trim()}`));
+				return;
+			}
+			const trimmed = stdout.trim();
+			if (!trimmed) {
+				resolve({
+					ok: true,
+					raw: ""
+				});
+				return;
+			}
+			try {
+				resolve(JSON.parse(trimmed));
+			} catch {
+				resolve({ raw: trimmed });
+			}
+		});
+	});
+}
+/**
+* NOTE: OpenClaw host invokes tool handlers as `execute(toolCallId, params)` (2 args).
+* This helper wraps the caller-provided 1-arg `execute(params)` to match the host
+* 2-arg convention internally, so call sites stay clean.
+*/
+function tool(name, description, parameters, execute) {
+	return (ctx) => {
+		if (!ctx?.sessionId) return null;
+		return {
+			name,
+			description,
+			parameters,
+			async execute(_callId, params) {
+				return await execute(params);
+			}
+		};
+	};
+}
+/** Run `ccl _schema` synchronously at register() time. Returns null on failure. */
+function fetchSchemaSync(invoker) {
+	try {
+		const r = spawnSync(invoker.exe, [...invoker.prefixArgs, "_schema"], {
+			env: {
+				...process.env,
+				NO_COLOR: "1"
+			},
+			windowsHide: true,
+			timeout: 15e3,
+			encoding: "utf-8"
+		});
+		if (r.status !== 0) {
+			pluginLogger?.warn?.(`[clawclaw] schema fetch failed (exit ${r.status}); auto-generation skipped. stderr: ${(r.stderr ?? "").slice(0, 400)}`);
+			return null;
+		}
+		return JSON.parse(r.stdout);
+	} catch (e) {
+		pluginLogger?.warn?.(`[clawclaw] schema fetch threw: ${e?.message ?? e}; auto-generation skipped`);
+		return null;
+	}
+}
+function inferOptionType(opt) {
+	if (!opt.takesValue) return { type: "boolean" };
+	if (typeof opt.defaultValue === "number") return {
+		type: "integer",
+		default: opt.defaultValue
+	};
+	if (typeof opt.defaultValue === "string" && /^-?\d+$/.test(opt.defaultValue)) return {
+		type: "integer",
+		default: Number(opt.defaultValue)
+	};
+	if (opt.flags.includes("<number>") || /\bnumber\b/i.test(opt.description ?? "")) return opt.defaultValue !== void 0 ? {
+		type: "integer",
+		default: opt.defaultValue
+	} : { type: "integer" };
+	return opt.defaultValue !== void 0 ? {
+		type: "string",
+		default: opt.defaultValue
+	} : { type: "string" };
+}
+function inferArgumentType(arg) {
+	if (arg.variadic) return {
+		type: "array",
+		items: { type: "string" }
+	};
+	return { type: "string" };
+}
+function buildParametersSchema(opts, args, meta) {
+	const properties = {};
+	const required = [];
+	for (const o of opts) {
+		if (!o.long) continue;
+		const inferred = inferOptionType(o);
+		properties[o.attributeName] = {
+			...inferred,
+			...o.description ? { description: o.description } : {}
+		};
+		if (o.mandatory) required.push(o.attributeName);
+	}
+	for (const a of args) {
+		properties[a.name] = {
+			...inferArgumentType(a),
+			...a.description ? { description: a.description } : {}
+		};
+		if (a.required && !a.variadic) required.push(a.name);
+	}
+	if (meta?.requiresConfirm || meta?.sensitive) {
+		properties.confirm = {
+			type: "boolean",
+			description: "MUST be true to proceed. This command is marked " + (meta?.sensitive ? "SENSITIVE (writes credentials / consumes quota / similar). " : "as requiring explicit confirmation. ") + "Setting this acknowledges the consequence."
+		};
+		required.push("confirm");
+	}
+	const schema = {
+		type: "object",
+		additionalProperties: false,
+		properties
+	};
+	if (required.length) schema.required = required;
+	return schema;
+}
+function buildExecutor(commandPath, opts, args, meta) {
+	const cmdParts = commandPath.split(/\s+/).filter(Boolean);
+	const requireConfirm = meta?.requiresConfirm || meta?.sensitive;
+	return async (params) => {
+		if (requireConfirm && params?.confirm !== true) throw new Error(`ccl ${commandPath} requires { confirm: true } (marked as ${meta?.sensitive ? "sensitive" : "requires-confirm"})`);
+		const cliArgs = [...cmdParts];
+		for (const o of opts) {
+			if (!o.long) continue;
+			if (o.attributeName === "confirm") continue;
+			const v = params?.[o.attributeName];
+			if (v === void 0 || v === null) continue;
+			if (!o.takesValue) {
+				if (v === true) cliArgs.push(o.long);
+			} else cliArgs.push(o.long, String(v));
+		}
+		for (const a of args) {
+			const v = params?.[a.name];
+			if (v === void 0 || v === null) continue;
+			if (a.variadic && Array.isArray(v)) cliArgs.push(...v.map(String));
+			else cliArgs.push(String(v));
+		}
+		return await runCcl(cliArgs, { timeoutMs: meta?.timeoutMs });
+	};
+}
+/** Hand-written overrides — auto-gen will skip these so the curated version wins. */
+const OVERRIDDEN_TOOL_NAMES = new Set([
+	"clawclaw_state",
+	"clawclaw_do",
+	"clawclaw_events",
+	"clawclaw_account_info",
+	"clawclaw_game_start",
+	"clawclaw_game_stop"
+]);
+/** Skip these command paths from auto-gen entirely (e.g., upgrade is unsafe for LLM). */
+const SKIP_PATHS = new Set([
+	"upgrade",
+	"game join",
+	"game queue"
+]);
+/** Track which tool names came from auto-gen, for diagnostic logging. */
+function emitAutoTools(schema, api) {
+	const names = [];
+	const visit = (node) => {
+		if (node.leaf && node.path) {
+			const toolName = `clawclaw_${node.path.replace(/\s+/g, "_")}`;
+			if (OVERRIDDEN_TOOL_NAMES.has(toolName)) return;
+			if (SKIP_PATHS.has(node.path)) return;
+			const meta = node.meta;
+			const params = buildParametersSchema(node.options, node.arguments, meta);
+			const exec = buildExecutor(node.path, node.options, node.arguments, meta);
+			const desc = [[
+				meta?.sensitive && "⚠️ SENSITIVE",
+				meta?.requiresConfirm && "⚠️ REQUIRES confirm:true",
+				meta?.longRunning && `⚠️ LONG-RUNNING (timeout ${(meta.timeoutMs ?? 0) / 1e3}s)`
+			].filter(Boolean).join(" · ") || null, node.description || `Run \`ccl ${node.path}\``].filter(Boolean).join("\n");
+			api.registerTool(tool(toolName, desc, params, exec), { name: toolName });
+			names.push(toolName);
+		}
+		for (const sub of node.subcommands) visit(sub);
+	};
+	visit(schema);
+	return {
+		count: names.length,
+		names
+	};
+}
+const rawToolFactory = tool("clawclaw_run", "RAW PASSTHROUGH — only use when no typed clawclaw_* tool covers the action. Spawns `ccl <command> <...args>` directly with no parameter validation. Set `confirm: true` to acknowledge using this bypass. Prefer typed tools for safety, schema, and discoverability.", {
+	type: "object",
+	additionalProperties: false,
+	required: ["command", "confirm"],
+	properties: {
+		command: {
+			type: "string",
+			description: "CCL command path (may contain spaces for subcommands), e.g. \"state\", \"account leaderboard\", \"watch\". Will be split on whitespace."
+		},
+		args: {
+			type: "array",
+			items: { type: "string" },
+			description: "Additional CLI arguments after the command path.",
+			default: []
+		},
+		confirm: {
+			type: "boolean",
+			description: "MUST be true. Acknowledges that the typed clawclaw_* tools were considered first and do not cover the requested action."
+		}
+	}
+}, async (args) => {
+	if (args?.confirm !== true) throw new Error("clawclaw_run requires { confirm: true } to acknowledge typed clawclaw_* tools were considered first");
+	const cmdParts = (args.command ?? "").trim().split(/\s+/).filter(Boolean);
+	if (!cmdParts.length) throw new Error("clawclaw_run: command is required");
+	return await runCcl([...cmdParts, ...args.args ?? []]);
+});
+var src_default = definePluginEntry({
+	id: PLUGIN_ID,
+	name: "ClawClaw (龙虾杀)",
+	description: "Play ClawClaw (龙虾杀) social deduction game via clawclaw-cli.",
+	register(api) {
+		pluginLogger = api.logger;
+		pluginConfig = readPluginConfigSlice(api.config);
+		resolvedCli = resolveCliInvoker(pluginConfig.cclPath);
+		if (!resolvedCli) pluginLogger?.warn?.("[clawclaw] clawclaw-cli (ccl) not found; tools will fail at execute time. Install via `npm i -g clawclaw-cli` or set plugins.entries.clawclaw.config.cclPath.");
+		else pluginLogger?.info?.(`[clawclaw] using ccl: ${resolvedCli.display}`);
+		api.registerTool(tool("clawclaw_state", "Read the current ClawClaw game state (phase / position / players / corpses / tasks / meeting / events). Read-only; safe to call any time. Returns parsed JSON from `ccl state`.", {
+			type: "object",
+			additionalProperties: false,
+			properties: { full: {
+				type: "boolean",
+				description: "Return full state instead of brief summary. Default false."
+			} }
+		}, async (args) => {
+			const cliArgs = ["state"];
+			if (args?.full) cliArgs.push("--full");
+			return await runCcl(cliArgs);
+		}), { name: "clawclaw_state" });
+		api.registerTool(tool("clawclaw_do", "Submit a single player communication action: SPEECH, VOTE, or THINK. Provide exactly one of `speech` / `vote` / `think`. Optionally attach `audioUrl` to a speech for TTS.", {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				speech: {
+					type: "string",
+					description: "Text to broadcast to nearby players or as a meeting speech."
+				},
+				vote: {
+					type: "string",
+					description: "Player name to vote out (meeting vote sub-phase only)."
+				},
+				think: {
+					type: "string",
+					description: "Spectator-visible reasoning. Standalone = no-op think action."
+				},
+				audioUrl: {
+					type: "string",
+					description: "Optional TTS audio URL. Only meaningful with `speech`."
+				}
+			}
+		}, async (args) => {
+			const a = args ?? {};
+			const primary = [
+				"speech",
+				"vote",
+				"think"
+			].filter((k) => typeof a[k] === "string" && a[k].length > 0);
+			if (primary.length === 0) throw new Error("clawclaw_do: must provide one of speech / vote / think");
+			if (primary.length > 1) throw new Error(`clawclaw_do: provide exactly one primary action (got: ${primary.join(", ")})`);
+			const cliArgs = ["do"];
+			if (a.speech) cliArgs.push("--speech", a.speech);
+			if (a.vote) cliArgs.push("--vote", a.vote);
+			if (a.think) cliArgs.push("--think", a.think);
+			if (a.audioUrl && a.speech) cliArgs.push("--url", a.audioUrl);
+			return await runCcl(cliArgs);
+		}), { name: "clawclaw_do" });
+		api.registerTool(tool("clawclaw_events", "Fetch recent game events. Read-only. Filter by `type` and limit count via `last`. For destructive --clear, use the `clawclaw_run` tool with `{ command: \"events --clear\", confirm: true }`.", {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				last: {
+					type: "integer",
+					minimum: 1,
+					maximum: 500,
+					default: 10,
+					description: "Number of most-recent events."
+				},
+				type: {
+					type: "string",
+					description: "Filter by event type (e.g. \"kill\", \"speech\", \"vote\")."
+				}
+			}
+		}, async (args) => {
+			const cliArgs = [
+				"events",
+				"-n",
+				String(args?.last ?? 10)
+			];
+			if (args?.type) cliArgs.push("--type", args.type);
+			return await runCcl(cliArgs);
+		}), { name: "clawclaw_events" });
+		api.registerTool(tool("clawclaw_account_info", "Return the currently-active ClawClaw account: agent name, Claw Key, persona, and spectator URL. Read-only.", {
+			type: "object",
+			additionalProperties: false,
+			properties: {}
+		}, async () => await runCcl(["account", "info"])), { name: "clawclaw_account_info" });
+		let autoStats = {
+			count: 0,
+			names: []
+		};
+		if (resolvedCli) {
+			const schema = fetchSchemaSync(resolvedCli);
+			if (schema) {
+				autoStats = emitAutoTools(schema, api);
+				pluginLogger?.info?.(`[clawclaw] auto-generated ${autoStats.count} tool(s) from schema: ${autoStats.names.join(", ")}`);
+			}
+		}
+		api.registerTool(rawToolFactory, { name: "clawclaw_run" });
+		registerStreamTools(api, pluginConfig, resolvedCli);
+		const handWrittenInIndex = 4;
+		const streamCount = 3;
+		pluginLogger?.info?.(`[clawclaw] tools registered: ${handWrittenInIndex} hand-written + ${autoStats.count} auto + 1 raw + ${streamCount} stream = ${handWrittenInIndex + autoStats.count + 1 + streamCount} total`);
+	}
+});
+//#endregion
+export { src_default as default };