@syengup/friday-channel-next 0.0.1

package/README.md

@@ -0,0 +1,35 @@
+# Friday Next Channel Plugin
+
+`friday-next` is an OpenClaw channel plugin for Apple apps (iOS/macOS) using HTTP + standard SSE.
+
+## Features
+
+- Channel id: `friday-next` (alongside legacy `friday` if configured)
+- **Transparent proxy SSE**: forwards OpenClaw `onAgentEvent` as `event: agent`, dispatch `deliver` as `event: deliver`, tool hooks as `event: tool-hook`, channel pushes as `event: outbound`
+- **Single synthetic event**: `connected` (`deviceId`, `serverTime`, `lastSeq`)
+- **Disk-backed SSE replay** per `deviceId` (JSONL + `Last-Event-ID` / `lastEventId`) for offline gaps and restarts
+- File upload/download (`POST /friday-next/files`, `GET /friday-next/files/:id`)
+- Cancel (`POST /friday-next/cancel`) and status with `activeRuns` (`GET /friday-next/status`)
+
+## Endpoints
+
+- `GET /friday-next/events?deviceId=...`
+- `POST /friday-next/messages`
+- `POST /friday-next/files`
+- `GET /friday-next/files/:id`
+- `POST /friday-next/cancel`
+- `GET /friday-next/status`
+
+See **`API.md`** (English) and **`API.zh-CN.md`** (Chinese) for payloads, event shapes, offline queue paths, and breaking changes.
+
+## Testing
+
+- `pnpm test:unit` — Vitest unit tests (excludes `*.e2e.test.ts`)
+- `pnpm test:e2e` — in-process app simulator (`vitest.e2e.config.ts`)
+- `pnpm test` — `test:unit` then `test:e2e`
+- `pnpm test:smoke` — optional live gateway smoke (gateway running; token from env or config)
+
+## Migration
+
+- There is **no** `GET/DELETE /friday-next/history`; clients must reconstruct state from SSE.
+- Legacy SSE names (`final`, `run-start`, `run-complete`, `run-error`, `reasoning`, `attachment`, `tts`, `block`, …) are **not** emitted; use `agent` + `deliver` + `tool-hook` + `outbound`.

package/index.ts

@@ -0,0 +1,191 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { PluginHookBeforeToolCallEvent, PluginHookAfterToolCallEvent, PluginHookToolContext } from "openclaw/plugin-sdk/plugins/types";
+import { fridayNextChannelPlugin } from "./src/channel.js";
+import { setFridayNextRuntime } from "./src/runtime.js";
+import { resolveFridayNextConfig } from "./src/config.js";
+import { getHostOpenClawConfigSnapshot } from "./src/host-config.js";
+import { registerFridayNextHttpRoutes } from "./src/http/server.js";
+import { getFridayNextRuntime } from "./src/runtime.js";
+import { sseEmitter } from "./src/sse/emitter.js";
+import {
+  forwardAgentEventRaw,
+  getLastRegisteredFridayDeviceId,
+  resolveFridayDeviceIdForSessionKey,
+} from "./src/friday-session.js";
+import { setFridayAgentForwardRuntime } from "./src/agent-forward-runtime.js";
+import { getOpenClawAgentRunContext } from "./src/agent-run-context-bridge.js";
+
+export { fridayNextChannelPlugin } from "./src/channel.js";
+export { setFridayNextRuntime } from "./src/runtime.js";
+
+/** `api.on` returns void — register tool hooks at most once per process. */
+let fridayNextToolHooksRegistered = false;
+let disposeAgentEventListener: (() => void) | null = null;
+/** Avoid duplicate `registerHttpRoute` when gateway re-invokes `registerFull`. */
+let fridayNextPluginHttpRegistered = false;
+
+function deviceIdFromToolContext(ctx: PluginHookToolContext): string | null {
+  if (ctx.runId) {
+    const d = sseEmitter.getDeviceIdByRunId(ctx.runId);
+    if (d) return d;
+  }
+  const sk =
+    typeof ctx.sessionKey === "string" && ctx.sessionKey.trim()
+      ? ctx.sessionKey.trim()
+      : (ctx.runId ? getOpenClawAgentRunContext(ctx.runId)?.sessionKey?.trim() : undefined) ?? "";
+  if (sk) {
+    const d = resolveFridayDeviceIdForSessionKey(sk);
+    if (d) return d;
+  }
+  const sole = sseEmitter.getSoleConnectedDeviceId();
+  if (sole) return sole;
+  const last = getLastRegisteredFridayDeviceId();
+  if (last) return last;
+  return null;
+}
+
+function isFridaySessionKey(sk: string): boolean {
+  return /^friday-next-/i.test(sk) || /^agent:main:friday-next-/i.test(sk);
+}
+
+function shouldForwardToolEventToFriday(ctx: PluginHookToolContext): boolean {
+  if (ctx.runId) {
+    if (sseEmitter.getDeviceIdByRunId(ctx.runId)) return true;
+    const runSk = getOpenClawAgentRunContext(ctx.runId)?.sessionKey?.trim() ?? "";
+    if (runSk) {
+      if (resolveFridayDeviceIdForSessionKey(runSk)) return true;
+      if (isFridaySessionKey(runSk)) return true;
+    }
+  }
+
+  const sk = typeof ctx.sessionKey === "string" ? ctx.sessionKey.trim() : "";
+  if (sk) {
+    if (resolveFridayDeviceIdForSessionKey(sk)) return true;
+    if (isFridaySessionKey(sk)) return true;
+  }
+
+  return false;
+}
+
+export default defineChannelPluginEntry({
+  id: "friday-next",
+  name: "Friday Next",
+  description: "Friday Next Apple 应用通道",
+  plugin: fridayNextChannelPlugin as ChannelPlugin,
+  setRuntime: setFridayNextRuntime,
+  registerFull: (api: OpenClawPluginApi) => {
+    setFridayAgentForwardRuntime(api);
+    if (!fridayNextPluginHttpRegistered) {
+      fridayNextPluginHttpRegistered = true;
+      registerFridayNextHttpRoutes(api);
+    } else {
+      const cfg = resolveFridayNextConfig(getHostOpenClawConfigSnapshot(getFridayNextRuntime().config));
+      sseEmitter.setBacklogLimit(cfg.sseBacklogPerDevice);
+    }
+
+    disposeAgentEventListener?.();
+    disposeAgentEventListener = api.runtime.events.onAgentEvent((evt: any) => {
+      forwardAgentEventRaw({
+        runId: evt.runId,
+        seq: evt.seq,
+        ts: evt.ts,
+        stream: evt.stream as string,
+        data: evt.data as Record<string, unknown>,
+        sessionKey: evt.sessionKey,
+      });
+    });
+
+    if (fridayNextToolHooksRegistered) {
+      return;
+    }
+    fridayNextToolHooksRegistered = true;
+
+    api.on("subagent_delivery_target", (event: any) => {
+      if (!event.expectsCompletionMessage) return;
+      const ch = event.requesterOrigin?.channel?.trim().toLowerCase();
+      if (ch !== "friday-next") return;
+      const sk = event.requesterSessionKey?.trim();
+      if (!sk) return;
+      const raw = resolveFridayDeviceIdForSessionKey(sk);
+      if (!raw) return;
+      const to = raw.toUpperCase();
+      return {
+        origin: {
+          channel: "friday-next",
+          accountId: event.requesterOrigin?.accountId?.trim() || "default",
+          to,
+        },
+      };
+    });
+
+    api.on("before_tool_call", (event: PluginHookBeforeToolCallEvent, ctx: PluginHookToolContext) => {
+      if (!shouldForwardToolEventToFriday(ctx)) return;
+      const deviceId = deviceIdFromToolContext(ctx);
+      const runId = ctx.runId ?? "(unknown)";
+
+      const logLine = (detail: string) => {
+        const ts = new Date().toISOString();
+        console.error(
+          `[Friday-HOOK] [${ts}] [TOOL_CALL] toolName=${event.toolName} runId=${runId} deviceId=${deviceId ?? "(unknown)"} detail=${detail}`,
+        );
+      };
+
+      if (!deviceId) {
+        logLine("SKIP_no_deviceId");
+        return;
+      }
+
+      logLine("START");
+      sseEmitter.broadcastToolEvent(deviceId.toUpperCase(), runId, {
+        type: "tool-hook",
+        data: {
+          when: "before",
+          runId,
+          deviceId: deviceId.toUpperCase(),
+          sessionKey: ctx.sessionKey,
+          toolName: event.toolName,
+          params: event.params,
+          ts: Date.now(),
+        },
+      });
+    });
+
+    api.on("after_tool_call", (event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext) => {
+      if (!shouldForwardToolEventToFriday(ctx)) return;
+      const deviceId = deviceIdFromToolContext(ctx);
+      const runId = ctx.runId ?? "(unknown)";
+
+      const logLine = (detail: string) => {
+        const ts = new Date().toISOString();
+        console.error(
+          `[Friday-HOOK] [${ts}] [TOOL_DONE] toolName=${event.toolName} runId=${runId} deviceId=${deviceId ?? "(unknown)"} detail=${detail}`,
+        );
+      };
+
+      if (!deviceId) {
+        logLine("SKIP_no_deviceId");
+        return;
+      }
+
+      logLine("END");
+      const normalizedDeviceId = deviceId.toUpperCase();
+      sseEmitter.broadcastToolEvent(normalizedDeviceId, runId, {
+        type: "tool-hook",
+        data: {
+          when: "after",
+          runId,
+          deviceId: normalizedDeviceId,
+          sessionKey: ctx.sessionKey,
+          toolName: event.toolName,
+          toolCallId: event.toolCallId,
+          error: event.error ?? null,
+          result: event.result,
+          durationMs: event.durationMs ?? null,
+          ts: Date.now(),
+        },
+      });
+    });
+  },
+});

package/install.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+import { cpSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const PLUGIN_DIR = process.argv[2] || join(homedir(), ".openclaw", "extensions", "friday-channel-next");
+const OPENCLAW_CONFIG = join(homedir(), ".openclaw", "openclaw.json");
+const REPO_URL = process.env.FRIDAY_NEXT_REPO || "https://github.com/SyengUp/openclaw-fridaynext-channel.git";
+
+const G = (s) => `\x1b[32m${s}\x1b[0m`;
+const Y = (s) => `\x1b[33m${s}\x1b[0m`;
+const R = (s) => `\x1b[31m${s}\x1b[0m`;
+
+function log(msg) {
+  console.log(`${G("[friday-next]")} ${msg}`);
+}
+function warn(msg) {
+  console.log(`${Y("[friday-next]")} ${msg}`);
+}
+function err(msg) {
+  console.error(`${R("[friday-next]")} ${msg}`);
+}
+
+function has(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Running from an npm/npx package when we have the full source (index.ts + package.json)
+// and are NOT already inside the target plugin dir.
+function isRunningFromNpmPackage() {
+  return (
+    resolve(__dirname) !== resolve(PLUGIN_DIR) &&
+    existsSync(join(__dirname, "package.json")) &&
+    existsSync(join(__dirname, "index.ts"))
+  );
+}
+
+// --------------- prerequisites ---------------
+
+const required = ["pnpm", "node", "openclaw"];
+const missing = required.filter((c) => !has(c));
+if (missing.length) {
+  missing.forEach((c) => err(`${c} is required but not found. Install it first.`));
+  process.exit(1);
+}
+
+if (!existsSync(OPENCLAW_CONFIG)) {
+  err(`OpenClaw config not found at ${OPENCLAW_CONFIG}`);
+  err("Make sure OpenClaw is installed and has been run at least once.");
+  process.exit(1);
+}
+
+// --------------- acquire source ---------------
+
+if (existsSync(PLUGIN_DIR)) {
+  log(`Plugin directory found: ${PLUGIN_DIR}`);
+} else if (isRunningFromNpmPackage()) {
+  log(`Copying plugin from npm package to ${PLUGIN_DIR} ...`);
+  cpSync(__dirname, PLUGIN_DIR, {
+    recursive: true,
+    filter: (src) => {
+      const rel = relative(__dirname, src);
+      if (rel === "") return true; // root dir
+      const top = rel.split(sep)[0];
+      return ![".git", "node_modules", "dist", "attachments", ".claude"].includes(top);
+    },
+  });
+} else {
+  if (!has("git")) {
+    err("git is required for installation from GitHub. Install git first or use npx @openclaw/friday-channel-next.");
+    process.exit(1);
+  }
+  log(`Cloning plugin to ${PLUGIN_DIR} ...`);
+  execSync(`git clone "${REPO_URL}" "${PLUGIN_DIR}"`, { stdio: "inherit" });
+}
+
+process.chdir(PLUGIN_DIR);
+
+// --------------- install + build ---------------
+
+log("Installing dependencies...");
+try {
+  execSync("pnpm install --frozen-lockfile", { stdio: "inherit" });
+} catch {
+  execSync("pnpm install", { stdio: "inherit" });
+}
+
+log("Building TypeScript...");
+execSync("pnpm build", { stdio: "inherit" });
+
+// --------------- configure OpenClaw ---------------
+
+log("Configuring OpenClaw...");
+
+const config = JSON.parse(readFileSync(OPENCLAW_CONFIG, "utf8"));
+
+if (!config.plugins) config.plugins = {};
+if (!Array.isArray(config.plugins.allow)) config.plugins.allow = [];
+if (!config.plugins.allow.includes("friday-next")) {
+  config.plugins.allow.push("friday-next");
+  console.log("  + Added friday-next to plugins.allow");
+}
+
+if (!config.plugins.entries) config.plugins.entries = {};
+if (!config.plugins.entries["friday-next"]) {
+  config.plugins.entries["friday-next"] = { enabled: true };
+  console.log("  + Added friday-next to plugins.entries (enabled)");
+} else if (!config.plugins.entries["friday-next"].enabled) {
+  config.plugins.entries["friday-next"].enabled = true;
+  console.log("  + Enabled friday-next in plugins.entries");
+}
+
+if (!config.channels) config.channels = {};
+if (!config.channels["friday-next"]) {
+  config.channels["friday-next"] = { enabled: true, transport: "http+sse" };
+  console.log("  + Added friday-next channel config (auth defaults to gateway token)");
+} else {
+  if (!config.channels["friday-next"].enabled) {
+    config.channels["friday-next"].enabled = true;
+    console.log("  + Enabled friday-next channel");
+  }
+  if (!config.channels["friday-next"].transport) {
+    config.channels["friday-next"].transport = "http+sse";
+    console.log("  + Set friday-next transport to http+sse");
+  }
+}
+
+if (!config.gateway) config.gateway = {};
+if (config.gateway.bind !== "lan") {
+  config.gateway.bind = "lan";
+  console.log("  + Set gateway.bind to lan");
+}
+
+writeFileSync(OPENCLAW_CONFIG, JSON.stringify(config, null, 2) + "\n", "utf8");
+console.log("  Config updated.");
+
+// --------------- restart gateway ---------------
+
+log("Restarting OpenClaw gateway...");
+execSync("openclaw gateway restart", { stdio: "inherit" });
+
+log("--------------------------------------------------");
+log("Installation complete! Friday Next channel is now active.");
+log("");
+log("The channel uses your gateway auth token by default.");
+log("To use a different token, set FRIDAY_NEXT_AUTH_TOKEN env var or");
+log("add authToken to channels.friday-next in openclaw.json.");
+log("--------------------------------------------------");

package/install.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+
+# Friday Next plugin installer — one-click setup for the friday-next channel
+# Usage:
+#   ./install.sh [plugin-dir]
+#   curl -fsSL https://raw.githubusercontent.com/SyengUp/openclaw-fridaynext-channel/main/install.sh | bash
+
+set -e
+
+PLUGIN_DIR="${1:-$HOME/.openclaw/extensions/friday-channel-next}"
+OPENCLAW_CONFIG="$HOME/.openclaw/openclaw.json"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+log()  { printf "%b%s\\n" "${GREEN}[friday-next]${NC} " "$1"; }
+warn() { printf "%b%s\\n" "${YELLOW}[friday-next]${NC} " "$1"; }
+err()  { printf "%b%s\\n" "${RED}[friday-next]${NC} " "$1" >&2; }
+
+trap 'err "Install failed."' ERR
+
+# Check prerequisites
+for cmd in pnpm node git openclaw; do
+  if ! command -v "$cmd" &>/dev/null; then
+    err "$cmd is required but not found. Install it first."
+    exit 1
+  fi
+done
+
+if [ ! -f "$OPENCLAW_CONFIG" ]; then
+  err "OpenClaw config not found at $OPENCLAW_CONFIG"
+  err "Make sure OpenClaw is installed and has been run at least once."
+  exit 1
+fi
+
+# Step 1: Clone (if needed), install deps, and build
+
+if [ -d "$PLUGIN_DIR" ]; then
+  log "Plugin directory found: $PLUGIN_DIR"
+else
+  log "Cloning plugin to $PLUGIN_DIR ..."
+  REPO_URL="${FRIDAY_NEXT_REPO:-https://github.com/SyengUp/openclaw-fridaynext-channel.git}"
+  git clone "$REPO_URL" "$PLUGIN_DIR"
+fi
+
+cd "$PLUGIN_DIR"
+
+log "Installing dependencies..."
+pnpm install --frozen-lockfile 2>/dev/null || pnpm install
+
+log "Building TypeScript..."
+pnpm build
+
+# Step 2: Configure OpenClaw
+
+log "Configuring OpenClaw..."
+
+node --input-type=module -e '
+import fs from "node:fs";
+
+const configPath = process.argv[1];
+const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+
+if (!config.plugins) config.plugins = {};
+if (!Array.isArray(config.plugins.allow)) config.plugins.allow = [];
+if (!config.plugins.allow.includes("friday-next")) {
+  config.plugins.allow.push("friday-next");
+  console.log("  + Added friday-next to plugins.allow");
+}
+
+if (!config.plugins.entries) config.plugins.entries = {};
+if (!config.plugins.entries["friday-next"]) {
+  config.plugins.entries["friday-next"] = { enabled: true };
+  console.log("  + Added friday-next to plugins.entries (enabled)");
+} else if (!config.plugins.entries["friday-next"].enabled) {
+  config.plugins.entries["friday-next"].enabled = true;
+  console.log("  + Enabled friday-next in plugins.entries");
+}
+
+if (!config.channels) config.channels = {};
+if (!config.channels["friday-next"]) {
+  config.channels["friday-next"] = { enabled: true, transport: "http+sse" };
+  console.log("  + Added friday-next channel config (auth defaults to gateway token)");
+} else {
+  if (!config.channels["friday-next"].enabled) {
+    config.channels["friday-next"].enabled = true;
+    console.log("  + Enabled friday-next channel");
+  }
+  if (!config.channels["friday-next"].transport) {
+    config.channels["friday-next"].transport = "http+sse";
+    console.log("  + Set friday-next transport to http+sse");
+  }
+}
+
+if (!config.gateway) config.gateway = {};
+if (config.gateway.bind !== "lan") {
+  config.gateway.bind = "lan";
+  console.log("  + Set gateway.bind to lan");
+}
+
+fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+console.log("  Config updated.");
+' "$OPENCLAW_CONFIG"
+
+# Step 3: Restart gateway
+
+log "Restarting OpenClaw gateway..."
+openclaw gateway restart
+
+log "--------------------------------------------------"
+log "Installation complete! Friday Next channel is now active."
+log ""
+log "The channel uses your gateway auth token by default."
+log "To use a different token, set FRIDAY_NEXT_AUTH_TOKEN env var or"
+log "add authToken to channels.friday-next in openclaw.json."
+log "--------------------------------------------------"

package/openclaw.plugin.json

@@ -0,0 +1,53 @@
+{
+  "id": "friday-next",
+  "channels": ["friday-next"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  },
+  "channelConfigs": {
+    "friday-next": {
+      "label": "Friday Next",
+      "description": "HTTP+SSE channel for the Friday iOS client.",
+      "schema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "transport": { "type": "string" },
+          "pathPrefix": { "type": "string" },
+          "historyLimit": { "type": "integer", "minimum": 1, "maximum": 200 },
+          "historyDir": { "type": "string" },
+          "logLevel": { "type": "string", "enum": ["debug", "info", "warn", "error"] },
+          "authToken": { "type": "string" },
+          "cors": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": { "type": "boolean" },
+              "allowOrigin": { "type": "string" }
+            }
+          },
+          "sse": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "keepaliveSec": { "type": "integer", "minimum": 5, "maximum": 120 },
+              "backlogPerDevice": { "type": "integer", "minimum": 0, "maximum": 1000 }
+            }
+          }
+        }
+      },
+      "uiHints": {
+        "authToken": {
+          "label": "Bearer auth token",
+          "sensitive": true
+        }
+      }
+    }
+  },
+  "channelEnvVars": {
+    "friday-next": ["FRIDAY_NEXT_AUTH_TOKEN"]
+  }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@syengup/friday-channel-next",
+  "version": "0.0.1",
+  "description": "OpenClaw Friday Next Apple channel plugin",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "src/",
+    "install.mjs",
+    "install.sh",
+    "tsconfig.json",
+    "pnpm-lock.yaml",
+    "openclaw.plugin.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "pnpm test:unit && pnpm test:e2e",
+    "test:unit": "vitest run",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:smoke": "node scripts/e2e-smoke.mjs",
+    "test:msg-live": "node scripts/message-roundtrip-live.mjs"
+  },
+  "bin": {
+    "install-friday-next": "./install.mjs"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "friday-next",
+      "label": "Friday Next",
+      "selectionLabel": "Friday Next (Apple App)",
+      "detailLabel": "Friday Next Apple App",
+      "docsPath": "/channels/friday-next",
+      "docsLabel": "friday-next",
+      "blurb": "Apple app channel with HTTP + SSE v2 streaming.",
+      "systemImage": "iphone.radiowaves.left.and.right",
+      "markdownCapable": true
+    },
+    "bundle": {
+      "stageRuntimeDependencies": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "chalk": "^5.6.2",
+    "jiti": "^2.6.1",
+    "json5": "^2.2.3",
+    "tslog": "^4.10.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5",
+    "zod": "^4.3.6"
+  }
+}

package/src/agent/abort-run.ts

@@ -0,0 +1,10 @@
+export async function abortRun(runId: string): Promise<void> {
+  if (process.env.VITEST !== "true") {
+    try {
+      const { abortAgentHarnessRun } = await import("openclaw/plugin-sdk/agent-harness");
+      abortAgentHarnessRun(runId);
+    } catch {
+      // optional at runtime
+    }
+  }
+}

package/src/agent/active-runs.ts

@@ -0,0 +1,26 @@
+/** Tracks agent runs that have emitted lifecycle `phase: start` without matching `end`/`error`. */
+
+const active = new Set<string>();
+
+export function observeAgentEventForActiveRuns(evt: {
+  stream: string;
+  runId: string;
+  data: Record<string, unknown>;
+}): void {
+  if (evt.stream !== "lifecycle") return;
+  const phase = evt.data.phase;
+  if (phase === "start") active.add(evt.runId);
+  if (phase === "end" || phase === "error") active.delete(evt.runId);
+}
+
+export function getActiveRunIds(): string[] {
+  return [...active];
+}
+
+export function getActiveRunCount(): number {
+  return active.size;
+}
+
+export function resetActiveRunsForTest(): void {
+  active.clear();
+}

package/src/agent/dispatch-bridge.ts

@@ -0,0 +1,18 @@
+type DispatchFn = (args: unknown) => Promise<unknown> | unknown;
+
+let overrideDispatch: DispatchFn | null = null;
+
+export function runFridayDispatch(args: Parameters<DispatchFn>[0]): ReturnType<DispatchFn> {
+  if (overrideDispatch) return overrideDispatch(args);
+  return import("openclaw/plugin-sdk/reply-dispatch-runtime").then((m) =>
+    m.dispatchReplyWithDispatcher(args as never),
+  );
+}
+
+export function __setMockFridayDispatchForTests(fn: DispatchFn): void {
+  overrideDispatch = fn;
+}
+
+export function __resetMockFridayDispatchForTests(): void {
+  overrideDispatch = null;
+}