@useorgx/openclaw-plugin 0.4.8 → 0.7.0

package/dist/http/routes/runtime-hooks.js

@@ -0,0 +1,437 @@
+import { backupCorruptFileSync, writeFileAtomicSync } from "../../fs-utils.js";
+import { readOpenClawGatewayPort, readOpenClawSettingsSnapshot } from "../../openclaw-settings.js";
+import { getOrgxPluginConfigDir } from "../../paths.js";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+export function registerRuntimeHookRoutes(router, deps) {
+    async function renderRuntimeHookConfig(res) {
+        try {
+            const snapshot = readOpenClawSettingsSnapshot();
+            const port = readOpenClawGatewayPort(snapshot.raw);
+            const runtimeHookUrl = `http://127.0.0.1:${port}/orgx/api/hooks/runtime`;
+            const hookToken = deps.resolveRuntimeHookToken();
+            const hooksDir = join(getOrgxPluginConfigDir(), "hooks");
+            const hookScriptPath = join(hooksDir, "post-reporting-event.mjs");
+            const hookScriptInstalled = existsSync(hookScriptPath);
+            const codexHome = (process.env.CODEX_HOME ?? "").trim();
+            const codexCandidates = [
+                codexHome ? join(codexHome, "config.toml") : null,
+                join(homedir(), ".codex", "config.toml"),
+                join(homedir(), ".config", "codex", "config.toml"),
+            ].filter(Boolean);
+            const codexConfigPath = codexCandidates.find((candidate) => existsSync(candidate)) ??
+                (codexCandidates[0] ?? null);
+            let codexInstalled = false;
+            let codexHasNotify = false;
+            if (codexConfigPath && existsSync(codexConfigPath)) {
+                const raw = readFileSync(codexConfigPath, "utf8");
+                codexHasNotify = /^\s*notify\s*=/m.test(raw);
+                codexInstalled =
+                    raw.includes("post-reporting-event.mjs") && raw.includes("--source_client=codex");
+            }
+            const codexNotifyConflict = Boolean(codexHasNotify && !codexInstalled);
+            const claudeCandidates = [
+                join(homedir(), ".claude", "settings.json"),
+                join(homedir(), ".config", "claude", "settings.json"),
+            ];
+            const claudeSettingsPath = claudeCandidates.find((candidate) => existsSync(candidate)) ?? claudeCandidates[0];
+            let claudeInstalled = false;
+            if (claudeSettingsPath && existsSync(claudeSettingsPath)) {
+                const raw = readFileSync(claudeSettingsPath, "utf8");
+                claudeInstalled =
+                    raw.includes("post-reporting-event.mjs") &&
+                        raw.includes("--source_client=claude-code");
+            }
+            deps.sendJson(res, 200, {
+                ok: true,
+                runtimeHookUrl,
+                hookToken,
+                hookTokenHint: deps.maskSecret(hookToken),
+                paths: {
+                    hookScriptPath,
+                    codexConfigPath,
+                    claudeSettingsPath,
+                },
+                installed: {
+                    hookScript: hookScriptInstalled,
+                    codex: codexInstalled,
+                    claudeCode: claudeInstalled,
+                },
+                conflicts: {
+                    codexNotify: codexNotifyConflict,
+                },
+            });
+        }
+        catch (err) {
+            deps.sendJson(res, 500, {
+                ok: false,
+                error: deps.safeErrorMessage(err),
+            });
+        }
+    }
+    router.add("GET", "hooks/runtime/config", async ({ res }) => renderRuntimeHookConfig(res), "Get runtime hook wiring config");
+    router.add("HEAD", "hooks/runtime/config", async ({ res }) => renderRuntimeHookConfig(res), "Get runtime hook wiring config (HEAD)");
+    router.add("POST", "hooks/runtime/setup", async ({ req, res }) => {
+        try {
+            const payloadRecord = await deps.parseJsonRequest(req);
+            const requestedTargets = Array.isArray(payloadRecord.targets)
+                ? payloadRecord.targets
+                : [];
+            const requested = requestedTargets
+                .map((value) => typeof value === "string" ? value.trim().toLowerCase() : "")
+                .filter((value) => value.length > 0);
+            const targets = new Set();
+            for (const value of requested) {
+                if (value === "codex")
+                    targets.add("codex");
+                if (value === "claude" || value === "claude-code" || value === "claude_code") {
+                    targets.add("claude-code");
+                }
+            }
+            if (targets.size === 0) {
+                targets.add("codex");
+                targets.add("claude-code");
+            }
+            const snapshot = readOpenClawSettingsSnapshot();
+            const port = readOpenClawGatewayPort(snapshot.raw);
+            const runtimeHookUrl = `http://127.0.0.1:${port}/orgx/api/hooks/runtime`;
+            const hookToken = deps.resolveRuntimeHookToken();
+            const hooksDir = join(getOrgxPluginConfigDir(), "hooks");
+            mkdirSync(hooksDir, { recursive: true, mode: 0o700 });
+            const hookScriptPath = join(hooksDir, "post-reporting-event.mjs");
+            const handlerFilename = fileURLToPath(import.meta.url);
+            const distDir = resolve(join(handlerFilename, ".."));
+            const bundledScriptPath = resolve(distDir, "hooks", "post-reporting-event.mjs");
+            const fallbackScriptPath = resolve(distDir, "..", "templates", "hooks", "scripts", "post-reporting-event.mjs");
+            let scriptContent = "";
+            let hookScriptSourcePath = bundledScriptPath;
+            try {
+                scriptContent = readFileSync(bundledScriptPath, "utf8");
+            }
+            catch {
+                hookScriptSourcePath = fallbackScriptPath;
+                scriptContent = readFileSync(fallbackScriptPath, "utf8");
+            }
+            writeFileAtomicSync(hookScriptPath, scriptContent, {
+                mode: 0o700,
+                encoding: "utf8",
+            });
+            const result = {
+                ok: true,
+                runtimeHookUrl,
+                hookTokenHint: deps.maskSecret(hookToken),
+                hookScriptPath,
+                hookScriptSourcePath,
+                targets: {
+                    codex: targets.has("codex"),
+                    claudeCode: targets.has("claude-code"),
+                },
+                codex: {
+                    path: null,
+                    installed: false,
+                    conflict: false,
+                },
+                claudeCode: {
+                    path: null,
+                    installed: false,
+                },
+            };
+            if (targets.has("codex")) {
+                const codexHome = (process.env.CODEX_HOME ?? "").trim();
+                const codexCandidates = [
+                    codexHome ? join(codexHome, "config.toml") : null,
+                    join(homedir(), ".codex", "config.toml"),
+                    join(homedir(), ".config", "codex", "config.toml"),
+                ].filter(Boolean);
+                const codexConfigPath = codexCandidates.find((candidate) => existsSync(candidate)) ??
+                    codexCandidates[0];
+                result.codex.path = codexConfigPath;
+                const notifySnippet = [
+                    "",
+                    "# OrgX runtime telemetry (installed by OpenClaw plugin)",
+                    "notify = [",
+                    '  "node",',
+                    `  "${hookScriptPath}",`,
+                    '  "--event=heartbeat",',
+                    '  "--source_client=codex",',
+                    '  "--phase=execution",',
+                    '  "--message=Codex heartbeat",',
+                    `  "--runtime_hook_url=${runtimeHookUrl}",`,
+                    `  "--hook_token=${hookToken}",`,
+                    "]",
+                    "",
+                ].join("\n");
+                if (!existsSync(codexConfigPath)) {
+                    mkdirSync(dirname(codexConfigPath), { recursive: true, mode: 0o700 });
+                    const initial = [
+                        "# Codex config.toml",
+                        "# Auto-generated OrgX hook wiring (safe to edit).",
+                        notifySnippet.trimEnd(),
+                        "",
+                    ].join("\n");
+                    writeFileAtomicSync(codexConfigPath, initial, {
+                        mode: 0o600,
+                        encoding: "utf8",
+                    });
+                    result.codex.installed = true;
+                }
+                else {
+                    const raw = readFileSync(codexConfigPath, "utf8");
+                    const alreadyInstalled = raw.includes("post-reporting-event.mjs") &&
+                        raw.includes("--source_client=codex");
+                    const hasNotify = /^\s*notify\s*=/m.test(raw);
+                    if (alreadyInstalled) {
+                        result.codex.installed = true;
+                    }
+                    else if (hasNotify) {
+                        result.codex.conflict = true;
+                    }
+                    else {
+                        const next = raw.replace(/\s*$/, "") + notifySnippet;
+                        writeFileAtomicSync(codexConfigPath, next, {
+                            mode: 0o600,
+                            encoding: "utf8",
+                        });
+                        result.codex.installed = true;
+                    }
+                }
+            }
+            if (targets.has("claude-code")) {
+                const claudeCandidates = [
+                    join(homedir(), ".claude", "settings.json"),
+                    join(homedir(), ".config", "claude", "settings.json"),
+                ];
+                const claudeSettingsPath = claudeCandidates.find((candidate) => existsSync(candidate)) ??
+                    claudeCandidates[0];
+                result.claudeCode.path = claudeSettingsPath;
+                mkdirSync(dirname(claudeSettingsPath), { recursive: true, mode: 0o700 });
+                let settings = {};
+                if (existsSync(claudeSettingsPath)) {
+                    const raw = readFileSync(claudeSettingsPath, "utf8");
+                    const parsed = deps.parseJsonSafe(raw);
+                    if (!parsed) {
+                        backupCorruptFileSync(claudeSettingsPath);
+                    }
+                    else {
+                        settings = parsed;
+                    }
+                }
+                const hooksRoot = settings.hooks &&
+                    typeof settings.hooks === "object" &&
+                    !Array.isArray(settings.hooks)
+                    ? settings.hooks
+                    : {};
+                settings.hooks = hooksRoot;
+                const ensureClaudeHook = (hookName, matcher, command) => {
+                    const list = Array.isArray(hooksRoot[hookName])
+                        ? hooksRoot[hookName]
+                        : [];
+                    let rule = list.find((entry) => entry &&
+                        typeof entry === "object" &&
+                        entry.matcher === matcher);
+                    if (!rule) {
+                        rule = { matcher, hooks: [] };
+                        list.push(rule);
+                    }
+                    if (!Array.isArray(rule.hooks)) {
+                        rule.hooks = [];
+                    }
+                    const hooks = rule.hooks;
+                    const already = hooks.some((entry) => entry &&
+                        entry.type === "command" &&
+                        typeof entry.command === "string" &&
+                        entry.command.includes("post-reporting-event.mjs") &&
+                        entry.command.includes(command));
+                    if (!already) {
+                        hooks.push({ type: "command", command });
+                    }
+                    hooksRoot[hookName] = list;
+                };
+                const baseArgs = `--runtime_hook_url=${runtimeHookUrl} --hook_token=${hookToken}`;
+                const startCmd = `node ${hookScriptPath} --event=session_start --source_client=claude-code --phase=intent --message=\"Claude session started\" ${baseArgs}`;
+                const toolCmd = `node ${hookScriptPath} --event=task_update --source_client=claude-code --phase=execution --message=\"Claude tool completed\" ${baseArgs}`;
+                const stopCmd = `node ${hookScriptPath} --event=session_stop --source_client=claude-code --phase=completed --message=\"Claude session completed\" ${baseArgs}`;
+                ensureClaudeHook("SessionStart", "", startCmd);
+                ensureClaudeHook("PostToolUse", "Write|Edit|Bash", toolCmd);
+                ensureClaudeHook("Stop", "", stopCmd);
+                writeFileAtomicSync(claudeSettingsPath, `${JSON.stringify(settings, null, 2)}\n`, {
+                    mode: 0o600,
+                    encoding: "utf8",
+                });
+                result.claudeCode.installed = true;
+            }
+            deps.sendJson(res, 200, result);
+        }
+        catch (err) {
+            deps.sendJson(res, 500, {
+                ok: false,
+                error: deps.safeErrorMessage(err),
+            });
+        }
+    }, "Install runtime hooks for Codex/Claude Code");
+    router.add("*", "hooks/runtime/setup", ({ res }) => {
+        deps.sendJson(res, 405, {
+            ok: false,
+            error: "Use POST /orgx/api/hooks/runtime/setup",
+        });
+    }, "Reject unsupported methods for hooks/runtime/setup");
+    async function renderRuntimeStream(req, res) {
+        const write = res.write?.bind(res);
+        if (!write) {
+            deps.sendJson(res, 501, { ok: false, error: "Streaming not supported" });
+            return;
+        }
+        res.writeHead(200, {
+            "Content-Type": "text/event-stream; charset=utf-8",
+            "Cache-Control": "no-cache, no-transform",
+            Connection: "keep-alive",
+            ...deps.securityHeaders,
+            ...deps.corsHeaders,
+        });
+        const subscriberId = deps.randomUUID();
+        const subscriber = {
+            id: subscriberId,
+            write: (chunk) => write(chunk) !== false,
+            end: () => {
+                if (!res.writableEnded) {
+                    res.end();
+                }
+            },
+        };
+        deps.runtimeStreamSubscribers.set(subscriberId, subscriber);
+        deps.ensureRuntimeStreamTimers();
+        try {
+            const initial = deps.listRuntimeInstances({ limit: 320 });
+            deps.writeRuntimeSseEvent(subscriber, "runtime.updated", initial);
+        }
+        catch {
+            // ignore
+        }
+        const close = () => {
+            deps.runtimeStreamSubscribers.delete(subscriberId);
+            try {
+                subscriber.end();
+            }
+            catch {
+                // ignore
+            }
+            if (deps.runtimeStreamSubscribers.size === 0) {
+                deps.stopRuntimeStreamTimers();
+            }
+        };
+        req.on?.("close", close);
+        req.on?.("aborted", close);
+        res.on?.("close", close);
+        res.on?.("finish", close);
+    }
+    router.add("GET", "hooks/runtime/stream", async ({ req, res }) => renderRuntimeStream(req, res), "Subscribe to runtime stream");
+    router.add("HEAD", "hooks/runtime/stream", async ({ req, res }) => renderRuntimeStream(req, res), "Subscribe to runtime stream (HEAD)");
+    router.add("POST", "hooks/runtime", async ({ req, query, res }) => {
+        const reqWithHeaders = req;
+        const expectedHookToken = deps.resolveRuntimeHookToken();
+        const providedHookToken = deps.pickHeaderString(reqWithHeaders.headers ?? {}, [
+            "x-orgx-hook-token",
+            "x-hook-token",
+        ]) ??
+            query.get("hook_token") ??
+            query.get("token");
+        if (!providedHookToken || providedHookToken.trim() !== expectedHookToken) {
+            deps.sendJson(res, 401, {
+                ok: false,
+                error: "Invalid hook token",
+            });
+            return;
+        }
+        try {
+            const payloadRecord = await deps.parseJsonRequest(req);
+            const payload = {
+                source_client: deps.pickString(payloadRecord, ["source_client", "sourceClient"]) ?? "unknown",
+                event: deps.pickString(payloadRecord, ["event", "hook_event"]) ?? "heartbeat",
+                run_id: deps.pickString(payloadRecord, [
+                    "run_id",
+                    "runId",
+                    "session_id",
+                    "sessionId",
+                ]),
+                correlation_id: deps.pickString(payloadRecord, ["correlation_id", "correlationId"]),
+                initiative_id: deps.pickString(payloadRecord, ["initiative_id", "initiativeId"]),
+                workstream_id: deps.pickString(payloadRecord, ["workstream_id", "workstreamId"]),
+                task_id: deps.pickString(payloadRecord, ["task_id", "taskId"]),
+                agent_id: deps.pickString(payloadRecord, ["agent_id", "agentId"]),
+                agent_name: deps.pickString(payloadRecord, ["agent_name", "agentName"]),
+                phase: deps.pickString(payloadRecord, ["phase"]),
+                progress_pct: deps.pickNumber(payloadRecord, ["progress_pct", "progressPct"]) ?? null,
+                message: deps.pickString(payloadRecord, ["message", "summary"]),
+                metadata: payloadRecord.metadata && typeof payloadRecord.metadata === "object"
+                    ? payloadRecord.metadata
+                    : null,
+                timestamp: deps.pickString(payloadRecord, ["timestamp", "time", "ts"]),
+            };
+            const instance = deps.upsertRuntimeInstanceFromHook(payload);
+            deps.broadcastRuntimeSse("runtime.updated", instance);
+            deps.clearSnapshotResponseCache();
+            const fallbackPhaseByEvent = {
+                session_start: "intent",
+                heartbeat: "execution",
+                progress: "execution",
+                task_update: "execution",
+                session_stop: "completed",
+                error: "blocked",
+            };
+            const phase = deps.normalizeHookPhase(payload.phase ?? fallbackPhaseByEvent[instance.event] ?? "execution");
+            const level = instance.event === "error" ? "error" : phase === "blocked" ? "warn" : "info";
+            const message = payload.message ?? `${instance.displayName} ${instance.event.replace(/_/g, " ")}`;
+            let forwarded = false;
+            let forwardError = null;
+            if (instance.initiativeId) {
+                try {
+                    await deps.emitActivity({
+                        initiative_id: instance.initiativeId,
+                        run_id: instance.runId ?? undefined,
+                        correlation_id: instance.runId
+                            ? undefined
+                            : (instance.correlationId ?? undefined),
+                        source_client: deps.normalizeRuntimeSourceForReporting(instance.sourceClient),
+                        message,
+                        phase,
+                        progress_pct: instance.progressPct ?? undefined,
+                        level,
+                        metadata: {
+                            source: "runtime_hook_relay",
+                            hook_event: instance.event,
+                            instance_id: instance.id,
+                            runtime_client: instance.sourceClient,
+                            task_id: instance.taskId,
+                            workstream_id: instance.workstreamId,
+                            ...(instance.metadata ?? {}),
+                        },
+                    });
+                    forwarded = true;
+                }
+                catch (err) {
+                    forwardError = deps.safeErrorMessage(err);
+                }
+            }
+            deps.sendJson(res, 200, {
+                ok: true,
+                instance_id: instance.id,
+                state: instance.state,
+                last_seen_at: instance.lastHeartbeatAt ?? instance.lastEventAt,
+                run_id: instance.runId ?? null,
+                forwarded,
+                forward_error: forwardError,
+            });
+        }
+        catch (err) {
+            deps.sendJson(res, 500, {
+                ok: false,
+                error: deps.safeErrorMessage(err),
+            });
+        }
+    }, "Ingest runtime hook events");
+    router.add("*", "hooks/runtime", ({ res }) => {
+        deps.sendJson(res, 405, { ok: false, error: "Use POST /orgx/api/hooks/runtime" });
+    }, "Reject unsupported methods for hooks/runtime");
+}

package/dist/http/routes/sentinels-catalog.d.ts

@@ -0,0 +1,7 @@
+import type { Router } from "../router.js";
+type SentinelsCatalogDeps<TRes> = {
+    sendJson: (res: TRes, status: number, payload: unknown) => void;
+    safeErrorMessage: (err: unknown) => string;
+};
+export declare function registerSentinelsCatalogRoutes<TReq, TRes>(router: Router<Record<string, never>, TReq, TRes>, deps: SentinelsCatalogDeps<TRes>): void;
+export {};

package/dist/http/routes/sentinels-catalog.js

@@ -0,0 +1,24 @@
+import { listBuiltInSentinels } from "../helpers/sentinel-catalog.js";
+export function registerSentinelsCatalogRoutes(router, deps) {
+    async function handle(res, domain) {
+        try {
+            const sentinels = listBuiltInSentinels({ domain });
+            deps.sendJson(res, 200, {
+                generatedAt: new Date().toISOString(),
+                domain: domain ?? null,
+                sentinels,
+            });
+        }
+        catch (err) {
+            deps.sendJson(res, 500, {
+                error: deps.safeErrorMessage(err),
+            });
+        }
+    }
+    router.add("GET", "sentinels/catalog", async ({ query, res }) => {
+        return handle(res, query?.get("domain") ?? undefined);
+    }, "Sentinel catalog");
+    router.add("HEAD", "sentinels/catalog", async ({ query, res }) => {
+        return handle(res, query?.get("domain") ?? undefined);
+    }, "Sentinel catalog (HEAD)");
+}

package/dist/http/routes/settings-byok.d.ts

@@ -0,0 +1,23 @@
+import type { ByokKeysRecord } from "../../byok-store.js";
+import type { Router } from "../router.js";
+type JsonRecord = Record<string, unknown>;
+type RegisterSettingsByokRoutesDeps<TReq, TRes> = {
+    parseJsonRequest: (req: TReq) => Promise<JsonRecord>;
+    readByokKeys: () => ByokKeysRecord | null;
+    writeByokKeys: (input: Partial<ByokKeysRecord>) => ByokKeysRecord;
+    maskSecret: (value: string | null) => string | null;
+    listAgents: () => Promise<Array<{
+        id?: string;
+        isDefault?: boolean;
+    }>>;
+    listOpenClawProviderModels: (input: {
+        agentId: string;
+        provider: "openai" | "anthropic" | "openrouter";
+    }) => Promise<Array<{
+        key: string;
+    }>>;
+    sendJson: (res: TRes, status: number, payload: unknown) => void;
+    safeErrorMessage: (err: unknown) => string;
+};
+export declare function registerSettingsByokRoutes<TReq, TRes>(router: Router<Record<string, never>, TReq, TRes>, deps: RegisterSettingsByokRoutesDeps<TReq, TRes>): void;
+export {};

package/dist/http/routes/settings-byok.js

@@ -0,0 +1,163 @@
+function readEnvByokKeys() {
+    return {
+        openai: process.env.OPENAI_API_KEY ?? null,
+        anthropic: process.env.ANTHROPIC_API_KEY ?? null,
+        openrouter: process.env.OPENROUTER_API_KEY ?? null,
+    };
+}
+export function registerSettingsByokRoutes(router, deps) {
+    async function renderByokSettings(req, method, res) {
+        const stored = deps.readByokKeys();
+        const envKeys = readEnvByokKeys();
+        const effectiveOpenai = stored?.openaiApiKey ?? envKeys.openai ?? null;
+        const effectiveAnthropic = stored?.anthropicApiKey ?? envKeys.anthropic ?? null;
+        const effectiveOpenrouter = stored?.openrouterApiKey ?? envKeys.openrouter ?? null;
+        const toProvider = (input) => {
+            const hasStored = typeof input.storedValue === "string" && input.storedValue.trim().length > 0;
+            const hasEnv = typeof input.envValue === "string" && input.envValue.trim().length > 0;
+            const source = hasStored ? "stored" : hasEnv ? "env" : "none";
+            return {
+                configured: Boolean(input.effective && input.effective.trim().length > 0),
+                source,
+                masked: deps.maskSecret(input.effective),
+            };
+        };
+        if (method === "POST") {
+            try {
+                const payload = await deps.parseJsonRequest(req);
+                const updates = {};
+                const setIfPresent = (key, aliases) => {
+                    for (const alias of aliases) {
+                        if (!Object.prototype.hasOwnProperty.call(payload, alias))
+                            continue;
+                        const raw = payload[alias];
+                        if (raw === null || typeof raw === "string") {
+                            updates[key] = raw;
+                            return;
+                        }
+                    }
+                };
+                setIfPresent("openaiApiKey", [
+                    "openaiApiKey",
+                    "openai_api_key",
+                    "openaiKey",
+                    "openai_key",
+                ]);
+                setIfPresent("anthropicApiKey", [
+                    "anthropicApiKey",
+                    "anthropic_api_key",
+                    "anthropicKey",
+                    "anthropic_key",
+                ]);
+                setIfPresent("openrouterApiKey", [
+                    "openrouterApiKey",
+                    "openrouter_api_key",
+                    "openrouterKey",
+                    "openrouter_key",
+                ]);
+                const saved = deps.writeByokKeys(updates);
+                const nextEffectiveOpenai = saved.openaiApiKey ?? envKeys.openai ?? null;
+                const nextEffectiveAnthropic = saved.anthropicApiKey ?? envKeys.anthropic ?? null;
+                const nextEffectiveOpenrouter = saved.openrouterApiKey ?? envKeys.openrouter ?? null;
+                deps.sendJson(res, 200, {
+                    ok: true,
+                    updatedAt: saved.updatedAt,
+                    providers: {
+                        openai: toProvider({
+                            storedValue: saved.openaiApiKey,
+                            envValue: envKeys.openai,
+                            effective: nextEffectiveOpenai,
+                        }),
+                        anthropic: toProvider({
+                            storedValue: saved.anthropicApiKey,
+                            envValue: envKeys.anthropic,
+                            effective: nextEffectiveAnthropic,
+                        }),
+                        openrouter: toProvider({
+                            storedValue: saved.openrouterApiKey,
+                            envValue: envKeys.openrouter,
+                            effective: nextEffectiveOpenrouter,
+                        }),
+                    },
+                });
+            }
+            catch (err) {
+                deps.sendJson(res, 500, { ok: false, error: deps.safeErrorMessage(err) });
+            }
+            return;
+        }
+        deps.sendJson(res, 200, {
+            ok: true,
+            updatedAt: stored?.updatedAt ?? null,
+            providers: {
+                openai: toProvider({
+                    storedValue: stored?.openaiApiKey,
+                    envValue: envKeys.openai,
+                    effective: effectiveOpenai,
+                }),
+                anthropic: toProvider({
+                    storedValue: stored?.anthropicApiKey,
+                    envValue: envKeys.anthropic,
+                    effective: effectiveAnthropic,
+                }),
+                openrouter: toProvider({
+                    storedValue: stored?.openrouterApiKey,
+                    envValue: envKeys.openrouter,
+                    effective: effectiveOpenrouter,
+                }),
+            },
+        });
+    }
+    async function renderByokHealth(query, res) {
+        let agentId = (query.get("agentId") ?? query.get("agent_id") ?? "").trim();
+        if (!agentId) {
+            try {
+                const agents = await deps.listAgents();
+                const defaultAgent = agents.find((entry) => Boolean(entry.isDefault)) ?? agents[0] ?? null;
+                const candidate = defaultAgent && typeof defaultAgent.id === "string"
+                    ? defaultAgent.id.trim()
+                    : "";
+                if (candidate)
+                    agentId = candidate;
+            }
+            catch {
+                // ignore
+            }
+        }
+        if (!agentId)
+            agentId = "main";
+        const providers = {};
+        for (const provider of ["openai", "anthropic", "openrouter"]) {
+            try {
+                const models = await deps.listOpenClawProviderModels({ agentId, provider });
+                providers[provider] = {
+                    ok: true,
+                    modelCount: models.length,
+                    sample: models.slice(0, 4).map((model) => model.key),
+                };
+            }
+            catch (err) {
+                providers[provider] = {
+                    ok: false,
+                    error: deps.safeErrorMessage(err),
+                };
+            }
+        }
+        deps.sendJson(res, 200, {
+            ok: true,
+            agentId,
+            providers,
+        });
+    }
+    router.add("GET", "settings/byok", async ({ req, res }) => renderByokSettings(req, "GET", res), "Read BYOK settings");
+    router.add("POST", "settings/byok", async ({ req, res }) => renderByokSettings(req, "POST", res), "Write BYOK settings");
+    router.add("HEAD", "settings/byok", async ({ req, res }) => renderByokSettings(req, "GET", res), "Read BYOK settings (HEAD)");
+    router.add("GET", "settings/byok/health", async ({ query, res }) => renderByokHealth(query, res), "Probe BYOK provider health");
+    router.add("HEAD", "settings/byok/health", async ({ query, res }) => renderByokHealth(query, res), "Probe BYOK provider health (HEAD)");
+    router.add("*", "settings/byok", ({ res }) => {
+        deps.sendJson(res, 405, { ok: false, error: "Method not allowed" });
+    }, "Reject unsupported methods for settings/byok");
+    router.add("*", "settings/byok/health", ({ res }) => {
+        deps.sendJson(res, 405, { ok: false, error: "Method not allowed" });
+    }, "Reject unsupported methods for settings/byok/health");
+}

package/dist/http/routes/summary.d.ts

@@ -0,0 +1,18 @@
+import type { OrgSnapshot } from "../../types.js";
+import type { Router } from "../router.js";
+type SummaryRoutesDeps<TRes> = {
+    getSnapshot: () => OrgSnapshot | null;
+    getOrgSnapshot: () => Promise<OrgSnapshot>;
+    sendJson: (res: TRes, status: number, payload: unknown) => void;
+    writeHead: (res: TRes, status: number, headers: Record<string, string>) => void;
+    end: (res: TRes) => void;
+    securityHeaders: Record<string, string>;
+    corsHeaders: Record<string, string>;
+    formatStatus: (snapshot: OrgSnapshot | null) => unknown;
+    formatAgents: (snapshot: OrgSnapshot | null) => unknown;
+    formatActivity: (snapshot: OrgSnapshot | null) => unknown;
+    formatInitiatives: (snapshot: OrgSnapshot | null) => unknown;
+    getOnboardingState: () => Promise<unknown>;
+};
+export declare function registerSummaryRoutes<TReq, TRes>(router: Router<Record<string, never>, TReq, TRes>, deps: SummaryRoutesDeps<TRes>): void;
+export {};