@useorgx/openclaw-plugin 0.4.8 → 0.7.0

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

@@ -0,0 +1,34 @@
+import type { OnboardingState } from "../../types.js";
+import type { Router } from "../router.js";
+type JsonRecord = Record<string, unknown>;
+type OnboardingControllerLike = {
+    startPairing: (input: {
+        openclawVersion?: string;
+        platform?: string;
+        deviceName?: string;
+    }) => Promise<{
+        pairingId: string;
+        connectUrl: string;
+        expiresAt: string | null;
+        pollIntervalMs: number | null;
+        state: OnboardingState;
+    }>;
+    getStatus: () => Promise<OnboardingState>;
+    submitManualKey: (input: {
+        apiKey: string;
+        userId?: string;
+    }) => Promise<OnboardingState>;
+    disconnect: () => Promise<OnboardingState>;
+};
+type RegisterOnboardingRoutesDeps<TReq, TRes> = {
+    onboarding: OnboardingControllerLike;
+    parseJsonRequest: (req: TReq) => Promise<JsonRecord>;
+    pickString: (input: unknown, keys: string[]) => string | null;
+    pickHeaderString: (headers: unknown, names: string[]) => string | null;
+    isUserScopedApiKey: (apiKey: string) => boolean;
+    sendJson: (res: TRes, status: number, payload: unknown) => void;
+    safeErrorMessage: (err: unknown) => string;
+    getOnboardingState: (state: OnboardingState) => OnboardingState;
+};
+export declare function registerOnboardingRoutes<TReq, TRes>(router: Router<Record<string, never>, TReq, TRes>, deps: RegisterOnboardingRoutesDeps<TReq, TRes>): void;
+export {};

package/dist/http/routes/onboarding.js

@@ -0,0 +1,101 @@
+export function registerOnboardingRoutes(router, deps) {
+    router.add("GET", "onboarding/status", async ({ res }) => {
+        try {
+            const state = await deps.onboarding.getStatus();
+            deps.sendJson(res, 200, {
+                ok: true,
+                data: deps.getOnboardingState(state),
+            });
+        }
+        catch (err) {
+            deps.sendJson(res, 500, {
+                ok: false,
+                error: deps.safeErrorMessage(err),
+            });
+        }
+    }, "Read onboarding status");
+    router.add("POST", "onboarding/start", async ({ req, res }) => {
+        try {
+            const payload = await deps.parseJsonRequest(req);
+            const started = await deps.onboarding.startPairing({
+                openclawVersion: deps.pickString(payload, ["openclawVersion", "openclaw_version"]) ??
+                    undefined,
+                platform: deps.pickString(payload, ["platform"]) ?? undefined,
+                deviceName: deps.pickString(payload, ["deviceName", "device_name"]) ?? undefined,
+            });
+            deps.sendJson(res, 200, {
+                ok: true,
+                data: {
+                    pairingId: started.pairingId,
+                    connectUrl: started.connectUrl,
+                    expiresAt: started.expiresAt,
+                    pollIntervalMs: started.pollIntervalMs,
+                    state: deps.getOnboardingState(started.state),
+                },
+            });
+        }
+        catch (err) {
+            deps.sendJson(res, 400, {
+                ok: false,
+                error: deps.safeErrorMessage(err),
+            });
+        }
+    }, "Start onboarding pairing flow");
+    router.add("POST", "onboarding/manual-key", async ({ req, res }) => {
+        try {
+            const payload = await deps.parseJsonRequest(req);
+            const reqWithHeaders = req;
+            const authHeader = deps.pickHeaderString(reqWithHeaders.headers, ["authorization"]);
+            const bearerApiKey = authHeader && authHeader.toLowerCase().startsWith("bearer ")
+                ? authHeader.slice("bearer ".length).trim()
+                : null;
+            const headerApiKey = deps.pickHeaderString(reqWithHeaders.headers, [
+                "x-orgx-api-key",
+                "x-api-key",
+            ]);
+            const apiKey = deps.pickString(payload, ["apiKey", "api_key"]) ??
+                headerApiKey ??
+                bearerApiKey;
+            if (!apiKey) {
+                deps.sendJson(res, 400, {
+                    ok: false,
+                    error: "apiKey is required",
+                });
+                return;
+            }
+            const requestedUserId = deps.pickString(payload, ["userId", "user_id"]) ??
+                deps.pickHeaderString(reqWithHeaders.headers, ["x-orgx-user-id", "x-user-id"]) ??
+                undefined;
+            const userId = deps.isUserScopedApiKey(apiKey) ? undefined : requestedUserId;
+            const state = await deps.onboarding.submitManualKey({
+                apiKey,
+                userId,
+            });
+            deps.sendJson(res, 200, {
+                ok: true,
+                data: deps.getOnboardingState(state),
+            });
+        }
+        catch (err) {
+            deps.sendJson(res, 400, {
+                ok: false,
+                error: deps.safeErrorMessage(err),
+            });
+        }
+    }, "Submit manual OrgX API key");
+    router.add("POST", "onboarding/disconnect", async ({ res }) => {
+        try {
+            const state = await deps.onboarding.disconnect();
+            deps.sendJson(res, 200, {
+                ok: true,
+                data: deps.getOnboardingState(state),
+            });
+        }
+        catch (err) {
+            deps.sendJson(res, 500, {
+                ok: false,
+                error: deps.safeErrorMessage(err),
+            });
+        }
+    }, "Disconnect onboarding session");
+}

package/dist/http/routes/realtime-orchestrator.d.ts

@@ -0,0 +1,10 @@
+import type { Router } from "../router.js";
+type JsonRecord = Record<string, unknown>;
+type RegisterRealtimeOrchestratorRoutesDeps<TReq, TRes> = {
+    parseJsonRequest: (req: TReq) => Promise<JsonRecord>;
+    rawRequest: (method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE", path: string, body?: unknown) => Promise<unknown>;
+    sendJson: (res: TRes, status: number, payload: unknown) => void;
+    safeErrorMessage: (err: unknown) => string;
+};
+export declare function registerRealtimeOrchestratorRoutes<TReq, TRes>(router: Router<Record<string, never>, TReq, TRes>, deps: RegisterRealtimeOrchestratorRoutesDeps<TReq, TRes>): void;
+export {};

package/dist/http/routes/realtime-orchestrator.js

@@ -0,0 +1,74 @@
+function parseStatusCodeFromError(message) {
+    const normalized = message.trim();
+    const match = normalized.match(/^(\d{3})\b/);
+    if (!match)
+        return 500;
+    const value = Number(match[1]);
+    if (!Number.isFinite(value))
+        return 500;
+    if (value < 400 || value > 599)
+        return 500;
+    return value;
+}
+export function registerRealtimeOrchestratorRoutes(router, deps) {
+    router.add("POST", "realtime/session", async ({ req, res }) => {
+        try {
+            const payload = await deps.parseJsonRequest(req);
+            const upstream = await deps.rawRequest("POST", "/api/client/orchestrator/realtime/session", payload);
+            deps.sendJson(res, 200, upstream);
+        }
+        catch (err) {
+            const message = deps.safeErrorMessage(err);
+            deps.sendJson(res, parseStatusCodeFromError(message), { ok: false, error: message });
+        }
+    }, "Create an ephemeral GPT realtime session for orchestrator voice control");
+    router.add("POST", "orchestrator/commands/preview", async ({ req, res }) => {
+        try {
+            const payload = await deps.parseJsonRequest(req);
+            const upstream = await deps.rawRequest("POST", "/api/client/orchestrator/commands/preview", payload);
+            deps.sendJson(res, 200, upstream);
+        }
+        catch (err) {
+            const message = deps.safeErrorMessage(err);
+            deps.sendJson(res, parseStatusCodeFromError(message), { ok: false, error: message });
+        }
+    }, "Preview inferred orchestrator actions from natural language input");
+    router.add("POST", "orchestrator/commands/apply", async ({ req, res }) => {
+        try {
+            const payload = await deps.parseJsonRequest(req);
+            const upstream = await deps.rawRequest("POST", "/api/client/orchestrator/commands/apply", payload);
+            deps.sendJson(res, 200, upstream);
+        }
+        catch (err) {
+            const message = deps.safeErrorMessage(err);
+            deps.sendJson(res, parseStatusCodeFromError(message), { ok: false, error: message });
+        }
+    }, "Apply confirmed orchestrator actions");
+    router.add("GET", "orchestrator/commands/*", async ({ path, res }) => {
+        const match = path.match(/^orchestrator\/commands\/([^/]+)$/);
+        if (!match) {
+            deps.sendJson(res, 404, { ok: false, error: "Unknown API endpoint" });
+            return;
+        }
+        let commandId = "";
+        try {
+            commandId = decodeURIComponent(match[1] ?? "").trim();
+        }
+        catch {
+            deps.sendJson(res, 400, { ok: false, error: "invalid command id encoding" });
+            return;
+        }
+        if (!commandId) {
+            deps.sendJson(res, 400, { ok: false, error: "command id is required" });
+            return;
+        }
+        try {
+            const upstream = await deps.rawRequest("GET", `/api/client/orchestrator/commands/${encodeURIComponent(commandId)}`);
+            deps.sendJson(res, 200, upstream);
+        }
+        catch (err) {
+            const message = deps.safeErrorMessage(err);
+            deps.sendJson(res, parseStatusCodeFromError(message), { ok: false, error: message });
+        }
+    }, "Read orchestrator command status");
+}

package/dist/http/routes/run-control.d.ts

@@ -0,0 +1,27 @@
+import type { Router } from "../router.js";
+type JsonRecord = Record<string, unknown>;
+type RunAction = "pause" | "resume" | "cancel" | "rollback" | "complete";
+type RegisterRunControlRoutesDeps<TReq, TRes> = {
+    parseJsonRequest: (req: TReq) => Promise<JsonRecord>;
+    pickString: (input: Record<string, unknown>, keys: string[]) => string | null;
+    listRunCheckpoints: (runId: string) => Promise<unknown>;
+    createRunCheckpoint: (runId: string, input: {
+        reason?: string;
+        payload?: Record<string, unknown>;
+    }) => Promise<unknown>;
+    restoreRunCheckpoint: (runId: string, input: {
+        checkpointId: string;
+        reason?: string;
+    }) => Promise<unknown>;
+    runAction: (runId: string, action: Exclude<RunAction, "complete">, input: {
+        checkpointId?: string;
+        reason?: string;
+    }) => Promise<unknown>;
+    markRunCompleted: (runId: string, input: {
+        reason?: string;
+    }) => Promise<unknown>;
+    sendJson: (res: TRes, status: number, payload: unknown) => void;
+    safeErrorMessage: (err: unknown) => string;
+};
+export declare function registerRunControlRoutes<TReq, TRes>(router: Router<Record<string, never>, TReq, TRes>, deps: RegisterRunControlRoutesDeps<TReq, TRes>): void;
+export {};

package/dist/http/routes/run-control.js

@@ -0,0 +1,96 @@
+export function registerRunControlRoutes(router, deps) {
+    router.add("*", "runs/*", async ({ req, res, path }) => {
+        const method = (req.method ?? "GET").toUpperCase();
+        const runCheckpointsMatch = path.match(/^runs\/([^/]+)\/checkpoints$/);
+        const runCheckpointRestoreMatch = path.match(/^runs\/([^/]+)\/checkpoints\/([^/]+)\/restore$/);
+        const runActionMatch = path.match(/^runs\/([^/]+)\/actions\/([^/]+)$/);
+        if (runCheckpointsMatch) {
+            const runId = decodeURIComponent(runCheckpointsMatch[1]);
+            if (method === "POST") {
+                try {
+                    const payload = await deps.parseJsonRequest(req);
+                    const reason = deps.pickString(payload, ["reason"]) ?? undefined;
+                    const rawPayload = payload.payload;
+                    const checkpointPayload = rawPayload && typeof rawPayload === "object" && !Array.isArray(rawPayload)
+                        ? rawPayload
+                        : undefined;
+                    const data = await deps.createRunCheckpoint(runId, {
+                        reason,
+                        payload: checkpointPayload,
+                    });
+                    deps.sendJson(res, 200, data);
+                }
+                catch (err) {
+                    deps.sendJson(res, 500, { error: deps.safeErrorMessage(err) });
+                }
+                return;
+            }
+            if (method === "GET" || method === "HEAD") {
+                try {
+                    const data = await deps.listRunCheckpoints(runId);
+                    deps.sendJson(res, 200, data);
+                }
+                catch (err) {
+                    deps.sendJson(res, 500, { error: deps.safeErrorMessage(err) });
+                }
+                return;
+            }
+            deps.sendJson(res, 405, { error: "Method not allowed" });
+            return;
+        }
+        if (runCheckpointRestoreMatch) {
+            if (method !== "POST") {
+                deps.sendJson(res, 405, { error: "Use POST for this endpoint" });
+                return;
+            }
+            try {
+                const runId = decodeURIComponent(runCheckpointRestoreMatch[1]);
+                const checkpointId = decodeURIComponent(runCheckpointRestoreMatch[2]);
+                const payload = await deps.parseJsonRequest(req);
+                const reason = deps.pickString(payload, ["reason"]) ?? undefined;
+                const data = await deps.restoreRunCheckpoint(runId, {
+                    checkpointId,
+                    reason,
+                });
+                deps.sendJson(res, 200, data);
+            }
+            catch (err) {
+                deps.sendJson(res, 500, { error: deps.safeErrorMessage(err) });
+            }
+            return;
+        }
+        if (runActionMatch) {
+            if (method !== "POST") {
+                deps.sendJson(res, 405, { error: "Use POST for this endpoint" });
+                return;
+            }
+            try {
+                const runId = decodeURIComponent(runActionMatch[1]);
+                const action = decodeURIComponent(runActionMatch[2]);
+                const payload = await deps.parseJsonRequest(req);
+                const checkpointId = deps.pickString(payload, ["checkpointId", "checkpoint_id"]);
+                const reason = deps.pickString(payload, ["reason"]);
+                if (action === "complete") {
+                    const data = await deps.markRunCompleted(runId, {
+                        reason: reason ?? undefined,
+                    });
+                    deps.sendJson(res, 200, data);
+                    return;
+                }
+                const data = await deps.runAction(runId, action, {
+                    checkpointId: checkpointId ?? undefined,
+                    reason: reason ?? undefined,
+                });
+                deps.sendJson(res, 200, data);
+            }
+            catch (err) {
+                const actionLabel = runActionMatch ? runActionMatch[2] : "unknown";
+                const runLabel = runActionMatch ? runActionMatch[1] : "unknown";
+                console.error(`[run-control] ${actionLabel} failed for run ${runLabel}:`, err);
+                deps.sendJson(res, 500, { error: deps.safeErrorMessage(err) });
+            }
+            return;
+        }
+        deps.sendJson(res, 404, { error: "Unknown API endpoint" });
+    }, "Run control (checkpoints/actions)");
+}

package/dist/http/routes/runtime-hooks.d.ts

@@ -0,0 +1,69 @@
+import type { RuntimeHookPayload } from "../../runtime-instance-store.js";
+import type { Router } from "../router.js";
+type JsonRecord = Record<string, unknown>;
+type RuntimeStreamSubscriber = {
+    id: string;
+    write: (chunk: Buffer) => boolean;
+    end: () => void;
+};
+type RuntimeInstanceLike = {
+    id: string;
+    state: string;
+    event: string;
+    displayName: string;
+    lastHeartbeatAt: string | null;
+    lastEventAt: string;
+    runId: string | null;
+    correlationId: string | null;
+    initiativeId: string | null;
+    sourceClient: string;
+    taskId: string | null;
+    workstreamId: string | null;
+    progressPct: number | null;
+    metadata: Record<string, unknown> | null;
+};
+type RegisterRuntimeHookRoutesDeps<TReq, TRes> = {
+    parseJsonRequest: (req: TReq) => Promise<JsonRecord>;
+    pickString: (record: Record<string, unknown>, keys: string[]) => string | null;
+    pickNumber: (record: Record<string, unknown>, keys: string[]) => number | null;
+    pickHeaderString: (headers: Record<string, string | string[] | undefined>, names: string[]) => string | null;
+    resolveRuntimeHookToken: () => string;
+    maskSecret: (value: string | null) => string | null;
+    parseJsonSafe: <T>(value: string) => T | null;
+    sendJson: (res: TRes, status: number, payload: unknown) => void;
+    safeErrorMessage: (err: unknown) => string;
+    randomUUID: () => string;
+    listRuntimeInstances: (input: {
+        limit: number;
+    }) => unknown;
+    writeRuntimeSseEvent: (subscriber: RuntimeStreamSubscriber, event: string, payload: unknown) => void;
+    runtimeStreamSubscribers: Map<string, RuntimeStreamSubscriber>;
+    ensureRuntimeStreamTimers: () => void;
+    stopRuntimeStreamTimers: () => void;
+    upsertRuntimeInstanceFromHook: (payload: RuntimeHookPayload) => RuntimeInstanceLike;
+    broadcastRuntimeSse: (event: string, payload: unknown) => void;
+    clearSnapshotResponseCache: () => void;
+    normalizeHookPhase: (value: string | null) => "intent" | "execution" | "blocked" | "review" | "handoff" | "completed";
+    normalizeRuntimeSourceForReporting: (value: unknown) => string;
+    emitActivity: (input: {
+        initiative_id: string;
+        run_id?: string;
+        correlation_id?: string;
+        source_client: string;
+        message: string;
+        phase: "intent" | "execution" | "blocked" | "review" | "handoff" | "completed";
+        progress_pct?: number;
+        level: "info" | "warn" | "error";
+        metadata?: Record<string, unknown>;
+    }) => Promise<unknown>;
+    securityHeaders: Record<string, string>;
+    corsHeaders: Record<string, string>;
+};
+export declare function registerRuntimeHookRoutes<TReq, TRes extends {
+    write?: (chunk: string | Buffer) => boolean | void;
+    end: () => void;
+    writeHead: (statusCode: number, headers?: Record<string, string>) => unknown;
+    writableEnded?: boolean;
+    on?: (event: string, listener: () => void) => void;
+}>(router: Router<Record<string, never>, TReq, TRes>, deps: RegisterRuntimeHookRoutesDeps<TReq, TRes>): void;
+export {};