@useorgx/openclaw-plugin 0.4.6 → 0.4.9

package/dist/http/helpers/openclaw-cli.d.ts

@@ -0,0 +1,37 @@
+import type { OrgXClient } from "../../api.js";
+import type { BillingStatus } from "../../types.js";
+export type OpenClawProvider = "anthropic" | "openrouter" | "openai";
+export declare function resolveByokEnvOverrides(): Record<string, string>;
+export declare function modelImpliesByok(model: string | null): boolean;
+export declare function fetchBillingStatusSafe(client: OrgXClient): Promise<BillingStatus | null>;
+export declare function listOpenClawAgents(): Promise<Array<Record<string, unknown>>>;
+export declare function spawnOpenClawAgentTurn(input: {
+    agentId: string;
+    sessionId: string;
+    message: string;
+    thinking?: string | null;
+}): {
+    pid: number | null;
+};
+export declare function normalizeOpenClawProvider(value: string | null): OpenClawProvider | null;
+export declare function listOpenClawProviderModels(input: {
+    agentId: string;
+    provider: OpenClawProvider;
+}): Promise<Array<{
+    key: string;
+    tags: string[];
+}>>;
+export declare function configureOpenClawProviderRouting(input: {
+    agentId: string;
+    provider: OpenClawProvider;
+    requestedModel?: string | null;
+}): Promise<{
+    provider: OpenClawProvider;
+    model: string;
+}>;
+export declare function resolveAutoOpenClawProvider(): OpenClawProvider | null;
+export declare function isPidAlive(pid: number): boolean;
+export declare function stopDetachedProcess(pid: number): Promise<{
+    stopped: boolean;
+    wasRunning: boolean;
+}>;

package/dist/http/helpers/openclaw-cli.js

@@ -0,0 +1,283 @@
+import { spawn } from "node:child_process";
+import { readByokKeys } from "../../byok-store.js";
+import { parseJsonSafe } from "../../json-utils.js";
+import { readOpenClawSettingsSnapshot, resolvePreferredOpenClawProvider, } from "../../openclaw-settings.js";
+export function resolveByokEnvOverrides() {
+    const stored = readByokKeys();
+    const env = {};
+    const openai = stored?.openaiApiKey?.trim() ?? "";
+    const anthropic = stored?.anthropicApiKey?.trim() ?? "";
+    const openrouter = stored?.openrouterApiKey?.trim() ?? "";
+    if (openai)
+        env.OPENAI_API_KEY = openai;
+    if (anthropic)
+        env.ANTHROPIC_API_KEY = anthropic;
+    if (openrouter)
+        env.OPENROUTER_API_KEY = openrouter;
+    return env;
+}
+async function runCommandCollect(input) {
+    const timeoutMs = input.timeoutMs ?? 10_000;
+    return await new Promise((resolve, reject) => {
+        const child = spawn(input.command, input.args, {
+            env: input.env ? { ...process.env, ...input.env } : process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        const timer = timeoutMs
+            ? setTimeout(() => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    // best effort
+                }
+                reject(new Error(`Command timed out after ${timeoutMs}ms`));
+            }, timeoutMs)
+            : null;
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve({ stdout, stderr, exitCode: typeof code === "number" ? code : null });
+        });
+    });
+}
+export function modelImpliesByok(model) {
+    const lower = (model ?? "").trim().toLowerCase();
+    if (!lower)
+        return false;
+    return (lower.includes("openrouter") ||
+        lower.includes("anthropic") ||
+        lower.includes("openai"));
+}
+export async function fetchBillingStatusSafe(client) {
+    try {
+        return await client.getBillingStatus();
+    }
+    catch {
+        return null;
+    }
+}
+export async function listOpenClawAgents() {
+    const result = await runCommandCollect({
+        command: "openclaw",
+        args: ["agents", "list", "--json"],
+        timeoutMs: 5_000,
+        env: resolveByokEnvOverrides(),
+    });
+    if (result.exitCode !== 0) {
+        throw new Error(result.stderr.trim() || "openclaw agents list failed");
+    }
+    const parsed = parseJsonSafe(result.stdout);
+    if (!Array.isArray(parsed)) {
+        throw new Error("openclaw agents list returned invalid JSON");
+    }
+    return parsed.filter((entry) => Boolean(entry && typeof entry === "object"));
+}
+export function spawnOpenClawAgentTurn(input) {
+    const args = [
+        "agent",
+        "--agent",
+        input.agentId,
+        "--session-id",
+        input.sessionId,
+        "--message",
+        input.message,
+    ];
+    if (input.thinking) {
+        args.push("--thinking", input.thinking);
+    }
+    const child = spawn("openclaw", args, {
+        env: { ...process.env, ...resolveByokEnvOverrides() },
+        stdio: "ignore",
+        detached: true,
+    });
+    child.unref();
+    return { pid: child.pid ?? null };
+}
+export function normalizeOpenClawProvider(value) {
+    const raw = (value ?? "").trim().toLowerCase();
+    if (!raw)
+        return null;
+    if (raw === "auto")
+        return null;
+    if (raw === "claude")
+        return "anthropic";
+    if (raw === "anthropic")
+        return "anthropic";
+    if (raw === "openrouter" || raw === "open-router")
+        return "openrouter";
+    if (raw === "openai")
+        return "openai";
+    return null;
+}
+async function setOpenClawAgentModel(input) {
+    const agentId = input.agentId.trim();
+    const model = input.model.trim();
+    if (!agentId || !model) {
+        throw new Error("agentId and model are required");
+    }
+    const result = await runCommandCollect({
+        command: "openclaw",
+        args: ["models", "--agent", agentId, "set", model],
+        timeoutMs: 10_000,
+        env: resolveByokEnvOverrides(),
+    });
+    if (result.exitCode !== 0) {
+        throw new Error(result.stderr.trim() || `openclaw models set failed for ${agentId}`);
+    }
+}
+export async function listOpenClawProviderModels(input) {
+    const providerArgs = input.provider === "openai" ? ["openai-codex", "openai"] : [input.provider];
+    let lastError = null;
+    for (const providerArg of providerArgs) {
+        const result = await runCommandCollect({
+            command: "openclaw",
+            args: [
+                "models",
+                "--agent",
+                input.agentId,
+                "list",
+                "--provider",
+                providerArg,
+                "--json",
+            ],
+            timeoutMs: 10_000,
+            env: resolveByokEnvOverrides(),
+        });
+        if (result.exitCode !== 0) {
+            lastError = new Error(result.stderr.trim() || "openclaw models list failed");
+            continue;
+        }
+        const parsed = parseJsonSafe(result.stdout);
+        if (!parsed || typeof parsed !== "object") {
+            const trimmed = result.stdout.trim();
+            if (!trimmed || /no models found/i.test(trimmed)) {
+                if (providerArg === providerArgs[providerArgs.length - 1])
+                    return [];
+                continue;
+            }
+            lastError = new Error("openclaw models list returned invalid JSON");
+            continue;
+        }
+        const modelsRaw = "models" in parsed && Array.isArray(parsed.models)
+            ? parsed.models
+            : [];
+        const models = modelsRaw
+            .map((entry) => {
+            if (!entry || typeof entry !== "object")
+                return null;
+            const row = entry;
+            const key = typeof row.key === "string" ? row.key.trim() : "";
+            const tags = Array.isArray(row.tags)
+                ? row.tags.filter((t) => typeof t === "string")
+                : [];
+            if (!key)
+                return null;
+            return { key, tags };
+        })
+            .filter((entry) => Boolean(entry));
+        if (models.length > 0 || providerArg === providerArgs[providerArgs.length - 1]) {
+            return models;
+        }
+    }
+    throw lastError ?? new Error("openclaw models list failed");
+}
+function pickPreferredModel(models) {
+    if (models.length === 0)
+        return null;
+    const preferred = models.find((m) => m.tags.some((t) => t === "default"));
+    return preferred?.key ?? models[0]?.key ?? null;
+}
+export async function configureOpenClawProviderRouting(input) {
+    const requestedModel = (input.requestedModel ?? "").trim() || null;
+    // Fast path: use known aliases where possible.
+    const aliasByProvider = {
+        anthropic: "sonnet",
+        openrouter: "sonnet",
+        openai: null,
+    };
+    const candidate = requestedModel ?? aliasByProvider[input.provider];
+    if (candidate) {
+        try {
+            await setOpenClawAgentModel({ agentId: input.agentId, model: candidate });
+            return { provider: input.provider, model: candidate };
+        }
+        catch {
+            // Fall through to discovery-based selection.
+        }
+    }
+    const models = await listOpenClawProviderModels({
+        agentId: input.agentId,
+        provider: input.provider,
+    });
+    const selected = pickPreferredModel(models);
+    if (!selected) {
+        throw new Error(`No ${input.provider} models configured for agent ${input.agentId}. Add a model in OpenClaw and retry.`);
+    }
+    await setOpenClawAgentModel({ agentId: input.agentId, model: selected });
+    return { provider: input.provider, model: selected };
+}
+export function resolveAutoOpenClawProvider() {
+    try {
+        const settings = readOpenClawSettingsSnapshot();
+        const provider = resolvePreferredOpenClawProvider(settings.raw);
+        if (!provider)
+            return null;
+        return provider;
+    }
+    catch {
+        return null;
+    }
+}
+export function isPidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function stopDetachedProcess(pid) {
+    const alive = isPidAlive(pid);
+    if (!alive) {
+        return { stopped: true, wasRunning: false };
+    }
+    const tryKill = (signal) => {
+        try {
+            // Detached child becomes its own process group (pgid = pid) on Unix.
+            process.kill(-pid, signal);
+            return;
+        }
+        catch {
+            // Fall back to direct pid kill.
+        }
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // ignore
+        }
+    };
+    tryKill("SIGTERM");
+    await new Promise((resolve) => setTimeout(resolve, 450));
+    if (isPidAlive(pid)) {
+        tryKill("SIGKILL");
+    }
+    return { stopped: !isPidAlive(pid), wasRunning: true };
+}

package/dist/http/helpers/runtime-sse.d.ts

@@ -0,0 +1,20 @@
+import { Buffer } from "node:buffer";
+import type { RuntimeInstanceRecord } from "../../runtime-instance-store.js";
+export type RuntimeStreamSubscriber = {
+    id: string;
+    write: (chunk: Buffer) => boolean;
+    end: () => void;
+};
+type CreateRuntimeSseHubDeps = {
+    listRuntimeInstances: (input: {
+        limit: number;
+    }) => RuntimeInstanceRecord[];
+};
+export declare function createRuntimeSseHub(deps: CreateRuntimeSseHubDeps): {
+    runtimeStreamSubscribers: Map<string, RuntimeStreamSubscriber>;
+    writeRuntimeSseEvent: (subscriber: RuntimeStreamSubscriber, event: string, payload: unknown) => void;
+    stopRuntimeStreamTimers: () => void;
+    broadcastRuntimeSse: (event: string, payload: unknown) => void;
+    ensureRuntimeStreamTimers: () => void;
+};
+export {};

package/dist/http/helpers/runtime-sse.js

@@ -0,0 +1,110 @@
+import { Buffer } from "node:buffer";
+export function createRuntimeSseHub(deps) {
+    const runtimeStreamSubscribers = new Map();
+    let runtimeStreamKeepaliveTimer = null;
+    let runtimeStreamStalenessTimer = null;
+    let runtimeStreamFingerprintById = new Map();
+    function runtimeStreamFingerprint(instance) {
+        return [
+            instance.state,
+            instance.lastHeartbeatAt ?? "",
+            instance.lastEventAt ?? "",
+            instance.progressPct ?? "",
+            instance.phase ?? "",
+        ].join("|");
+    }
+    function writeRuntimeSseEvent(subscriber, event, payload) {
+        const data = JSON.stringify(payload ?? null);
+        subscriber.write(Buffer.from(`event: ${event}
+data: ${data}
+
+`, "utf8"));
+    }
+    function stopRuntimeStreamTimers() {
+        if (runtimeStreamKeepaliveTimer) {
+            clearInterval(runtimeStreamKeepaliveTimer);
+            runtimeStreamKeepaliveTimer = null;
+        }
+        if (runtimeStreamStalenessTimer) {
+            clearInterval(runtimeStreamStalenessTimer);
+            runtimeStreamStalenessTimer = null;
+        }
+        runtimeStreamFingerprintById = new Map();
+    }
+    function broadcastRuntimeSse(event, payload) {
+        if (runtimeStreamSubscribers.size === 0)
+            return;
+        for (const subscriber of runtimeStreamSubscribers.values()) {
+            try {
+                writeRuntimeSseEvent(subscriber, event, payload);
+            }
+            catch {
+                try {
+                    subscriber.end();
+                }
+                catch {
+                    // ignore
+                }
+                runtimeStreamSubscribers.delete(subscriber.id);
+            }
+        }
+        if (runtimeStreamSubscribers.size === 0) {
+            stopRuntimeStreamTimers();
+        }
+    }
+    function ensureRuntimeStreamTimers() {
+        if (runtimeStreamKeepaliveTimer || runtimeStreamStalenessTimer)
+            return;
+        runtimeStreamKeepaliveTimer = setInterval(() => {
+            if (runtimeStreamSubscribers.size === 0) {
+                stopRuntimeStreamTimers();
+                return;
+            }
+            const payload = Buffer.from(`: ping ${Date.now()}
+`, "utf8");
+            for (const subscriber of runtimeStreamSubscribers.values()) {
+                try {
+                    subscriber.write(payload);
+                }
+                catch {
+                    try {
+                        subscriber.end();
+                    }
+                    catch {
+                        // ignore
+                    }
+                    runtimeStreamSubscribers.delete(subscriber.id);
+                }
+            }
+        }, 20_000);
+        runtimeStreamKeepaliveTimer.unref?.();
+        runtimeStreamStalenessTimer = setInterval(() => {
+            if (runtimeStreamSubscribers.size === 0) {
+                stopRuntimeStreamTimers();
+                return;
+            }
+            // listRuntimeInstances applies staleness before returning.
+            const instances = deps.listRuntimeInstances({ limit: 600 });
+            const nextFingerprintById = new Map();
+            for (const instance of instances) {
+                const fingerprint = runtimeStreamFingerprint(instance);
+                nextFingerprintById.set(instance.id, fingerprint);
+                const previous = runtimeStreamFingerprintById.get(instance.id);
+                if (previous && previous === fingerprint) {
+                    continue;
+                }
+                runtimeStreamFingerprintById.set(instance.id, fingerprint);
+                broadcastRuntimeSse("runtime.updated", instance);
+            }
+            runtimeStreamFingerprintById = nextFingerprintById;
+        }, 15_000);
+        runtimeStreamStalenessTimer.unref?.();
+    }
+    return {
+        runtimeStreamSubscribers,
+        writeRuntimeSseEvent,
+        stopRuntimeStreamTimers,
+        broadcastRuntimeSse,
+        ensureRuntimeStreamTimers,
+    };
+}

package/dist/http/helpers/value-utils.d.ts

@@ -0,0 +1,6 @@
+export declare function pickString(record: Record<string, unknown>, keys: string[]): string | null;
+export declare function pickNumber(record: Record<string, unknown>, keys: string[]): number | null;
+export declare function pickHeaderString(headers: Record<string, string | string[] | undefined>, keys: string[]): string | null;
+export declare function toIsoString(value: string | null): string | null;
+export declare function parsePositiveInt(raw: string | null, fallback: number): number;
+export declare function parseBooleanQuery(raw: string | null): boolean;

package/dist/http/helpers/value-utils.js

@@ -0,0 +1,67 @@
+export function pickString(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string") {
+            const trimmed = value.trim();
+            if (trimmed.length > 0)
+                return trimmed;
+        }
+    }
+    return null;
+}
+export function pickNumber(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return value;
+        }
+        if (typeof value === "string" && value.trim().length > 0) {
+            const parsed = Number(value);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+    }
+    return null;
+}
+export function pickHeaderString(headers, keys) {
+    for (const key of keys) {
+        const candidates = [key, key.toLowerCase(), key.toUpperCase()];
+        for (const candidate of candidates) {
+            const raw = headers[candidate];
+            if (typeof raw === "string" && raw.trim().length > 0) {
+                return raw.trim();
+            }
+            if (Array.isArray(raw)) {
+                const first = raw.find((value) => typeof value === "string" && value.trim().length > 0);
+                if (first)
+                    return first.trim();
+            }
+        }
+    }
+    return null;
+}
+export function toIsoString(value) {
+    if (!value)
+        return null;
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        return null;
+    return new Date(parsed).toISOString();
+}
+export function parsePositiveInt(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.max(1, Math.floor(parsed));
+}
+export function parseBooleanQuery(raw) {
+    if (!raw)
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return (normalized === "1" ||
+        normalized === "true" ||
+        normalized === "yes" ||
+        normalized === "on");
+}

package/dist/http/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * HTTP Handler — Serves the React dashboard SPA and API proxy endpoints.
+ *
+ * Registered at the `/orgx` prefix. Handles:
+ *   /orgx/live           → dashboard SPA (index.html)
+ *   /orgx/live/assets/*  → static assets (JS, CSS, images)
+ *   /orgx/api/status     → org status summary
+ *   /orgx/api/agents     → agent states
+ *   /orgx/api/activity   → activity feed
+ *   /orgx/api/initiatives → initiative data
+ *   /orgx/api/health     → plugin diagnostics + outbox/sync status
+ *   /orgx/api/onboarding → onboarding / config state
+ *   /orgx/api/agent-suite/status → suite provisioning plan (OpenClaw-local)
+ *   /orgx/api/agent-suite/install → install/update suite (OpenClaw-local)
+ *   /orgx/api/delegation/preflight → delegation preflight
+ *   /orgx/api/runs/:id/checkpoints → list/create checkpoints
+ *   /orgx/api/runs/:id/checkpoints/:checkpointId/restore → restore checkpoint
+ *   /orgx/api/runs/:id/actions/:action → run control action
+ */
+import type { OrgXClient } from "../api.js";
+import type { OnboardingState, OrgXConfig, OrgSnapshot } from "../types.js";
+import { type OutboxAdapter } from "../adapters/outbox.js";
+type OpenClawAdapter = {
+    listAgents?: () => Promise<Array<Record<string, unknown>>>;
+    spawnAgentTurn?: (input: {
+        agentId: string;
+        sessionId: string;
+        message: string;
+        thinking?: string | null;
+    }) => {
+        pid: number | null;
+    };
+    stopDetachedProcess?: (pid: number) => Promise<{
+        stopped: boolean;
+        wasRunning: boolean;
+    }>;
+    isPidAlive?: (pid: number) => boolean;
+};
+interface PluginRequest {
+    method?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    on?: (event: string, listener: (...args: unknown[]) => void) => void;
+    once?: (event: string, listener: (...args: unknown[]) => void) => void;
+}
+interface PluginResponse {
+    writeHead(status: number, headers?: Record<string, string>): void;
+    end(body?: string | Buffer): void;
+    write?(chunk: string | Buffer): boolean | void;
+    on?: (event: string, listener: (...args: unknown[]) => void) => void;
+    once?: (event: string, listener: (...args: unknown[]) => void) => void;
+    writableEnded?: boolean;
+}
+interface OnboardingController {
+    getState: () => OnboardingState;
+    startPairing: (input: {
+        openclawVersion?: string;
+        platform?: string;
+        deviceName?: string;
+    }) => Promise<{
+        pairingId: string;
+        connectUrl: string;
+        expiresAt: string;
+        pollIntervalMs: number;
+        state: OnboardingState;
+    }>;
+    getStatus: () => Promise<OnboardingState>;
+    submitManualKey: (input: {
+        apiKey: string;
+        userId?: string;
+    }) => Promise<OnboardingState>;
+    disconnect: () => Promise<OnboardingState>;
+}
+interface DiagnosticsProvider {
+    getHealth?: (input?: {
+        probeRemote?: boolean;
+    }) => Promise<unknown>;
+}
+export declare function createHttpHandler(config: OrgXConfig & {
+    dashboardEnabled?: boolean;
+    pluginVersion?: string;
+    installationId?: string | null;
+}, client: OrgXClient, getSnapshot: () => OrgSnapshot | null, onboarding: OnboardingController, diagnostics?: DiagnosticsProvider, adapters?: {
+    outbox?: OutboxAdapter;
+    openclaw?: OpenClawAdapter;
+}): (req: PluginRequest, res: PluginResponse) => Promise<boolean>;
+export {};