@useorgx/openclaw-plugin 0.4.8 → 0.7.0

package/dist/retro/quality-rubric.js

@@ -0,0 +1,213 @@
+import { callLlmJson } from "../http/helpers/llm-client.js";
+function toFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function toNonNegativeCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : 0;
+}
+/**
+ * Compute domain-specific quality modifier based on artifact metadata.
+ * Returns delta (positive = bonus, negative = penalty) and reasons.
+ */
+export function computeDomainQualityModifier(domain, artifactMetadata) {
+    if (!domain || !artifactMetadata)
+        return { delta: 0, reasons: [] };
+    let delta = 0;
+    const reasons = [];
+    const meta = artifactMetadata;
+    // Helper to check nested dotted paths or flat keys
+    const has = (key) => {
+        if (key in meta && meta[key] != null) {
+            const v = meta[key];
+            if (typeof v === "string")
+                return v.trim().length > 0;
+            if (Array.isArray(v))
+                return v.length > 0;
+            return true;
+        }
+        const parts = key.split(".");
+        let cur = meta;
+        for (const p of parts) {
+            if (cur == null || typeof cur !== "object")
+                return false;
+            cur = cur[p];
+        }
+        if (cur == null)
+            return false;
+        if (typeof cur === "string")
+            return cur.trim().length > 0;
+        if (Array.isArray(cur))
+            return cur.length > 0;
+        return true;
+    };
+    switch (domain) {
+        case "engineering":
+            if (has("verification.tests_passed") || has("verification")) {
+                delta += 1;
+                reasons.push("Engineering artifact includes test verification.");
+            }
+            if (!has("commit_sha")) {
+                delta -= 1;
+                reasons.push("Engineering artifact missing commit_sha.");
+            }
+            break;
+        case "product":
+            if (has("acceptance_criteria")) {
+                delta += 1;
+                reasons.push("Product artifact includes acceptance criteria.");
+            }
+            if (!has("success_metric")) {
+                delta -= 1;
+                reasons.push("Product artifact missing success metric.");
+            }
+            break;
+        case "design":
+            if (has("evidence_url")) {
+                delta += 1;
+                reasons.push("Design artifact includes evidence URL.");
+            }
+            if (!has("tokens_referenced")) {
+                delta -= 1;
+                reasons.push("Design artifact missing token references.");
+            }
+            break;
+        case "marketing":
+            if (has("measurement_hook")) {
+                delta += 1;
+                reasons.push("Marketing artifact includes measurement hook.");
+            }
+            if (!has("audience")) {
+                delta -= 1;
+                reasons.push("Marketing artifact missing target audience.");
+            }
+            break;
+        case "sales":
+            if (has("next_action")) {
+                delta += 1;
+                reasons.push("Sales artifact includes next action.");
+            }
+            if (!has("buyer_stage")) {
+                delta -= 1;
+                reasons.push("Sales artifact missing buyer stage.");
+            }
+            break;
+        case "operations":
+            if (has("rollback_path")) {
+                delta += 1;
+                reasons.push("Operations artifact includes rollback path.");
+            }
+            if (!has("affected_systems")) {
+                delta -= 1;
+                reasons.push("Operations artifact missing affected systems.");
+            }
+            break;
+        case "orchestration":
+            if (has("unblocked_work")) {
+                delta += 1;
+                reasons.push("Orchestration artifact includes unblocked work.");
+            }
+            if (!has("rationale")) {
+                delta -= 1;
+                reasons.push("Orchestration artifact missing rationale.");
+            }
+            break;
+    }
+    return { delta, reasons };
+}
+export function computeRetroQualityRubricScore(input) {
+    let score = input.success ? 5 : 2;
+    const reasons = [];
+    if (input.hadError || (input.errorMessage?.trim() ?? "").length > 0) {
+        score -= 1;
+        reasons.push("Run ended with error signal.");
+    }
+    const followUpsCount = toNonNegativeCount(input.followUpsCount);
+    if (!input.success && followUpsCount < 1) {
+        score -= 1;
+        reasons.push("Failure run missing actionable follow-up.");
+    }
+    const decisionsCount = toNonNegativeCount(input.decisionsCount);
+    if (!input.success && decisionsCount < 1) {
+        score -= 1;
+        reasons.push("Failure run missing decision signal.");
+    }
+    const wrongCount = toNonNegativeCount(input.whatWentWrongCount);
+    if (input.success && wrongCount > 0) {
+        score -= 1;
+        reasons.push("Success run still reported retrospective issues.");
+    }
+    const tokens = toFiniteNumber(input.tokens);
+    if (tokens === null || tokens <= 0) {
+        score -= 1;
+        reasons.push("Missing or invalid token telemetry.");
+    }
+    const costUsd = toFiniteNumber(input.costUsd);
+    if (costUsd !== null && costUsd > 10) {
+        score -= 1;
+        reasons.push("Run cost exceeded preferred threshold ($10).");
+    }
+    // Domain-specific modifiers (stacks with generic signals)
+    const domainMod = computeDomainQualityModifier(input.domain, input.artifactMetadata);
+    score += domainMod.delta;
+    reasons.push(...domainMod.reasons);
+    const normalized = Math.max(1, Math.min(5, Math.round(score)));
+    if (reasons.length === 0) {
+        reasons.push("Outcome met baseline quality rubric expectations.");
+    }
+    return { score: normalized, reasons };
+}
+export async function computeRetroQualityWithLlm(input) {
+    const lines = [
+        `Outcome: ${input.success ? "success" : "failure"}`,
+        `Error present: ${input.hadError || (input.errorMessage?.trim() ?? "").length > 0 ? "yes" : "no"}`,
+    ];
+    if (input.errorMessage?.trim()) {
+        lines.push(`Error message: ${input.errorMessage.trim()}`);
+    }
+    const tokens = toFiniteNumber(input.tokens);
+    if (tokens !== null)
+        lines.push(`Tokens used: ${tokens}`);
+    const costUsd = toFiniteNumber(input.costUsd);
+    if (costUsd !== null)
+        lines.push(`Cost (USD): ${costUsd.toFixed(4)}`);
+    const decisionsCount = toNonNegativeCount(input.decisionsCount);
+    lines.push(`Decisions recorded: ${decisionsCount}`);
+    const followUpsCount = toNonNegativeCount(input.followUpsCount);
+    lines.push(`Follow-ups recorded: ${followUpsCount}`);
+    const issuesCount = toNonNegativeCount(input.whatWentWrongCount);
+    lines.push(`Issues reported: ${issuesCount}`);
+    if (input.executionContext?.trim()) {
+        lines.push(`Execution context: ${input.executionContext.trim()}`);
+    }
+    const userPrompt = lines.join("\n");
+    const systemPrompt = "Score this autonomous agent run on a 1-5 quality scale. Consider: task completion, error handling, resource efficiency, follow-up quality, and decision signals. Return JSON: {\"score\": <1-5>, \"reasons\": [\"...\", ...]}. Each reason should be specific and actionable, not generic.";
+    const { result, source } = await callLlmJson({
+        taskId: "quality_rubric",
+        systemPrompt,
+        userPrompt,
+        model: "openai/gpt-4.1-nano",
+        maxTokens: 256,
+        cacheTtlMs: 12 * 60 * 60_000,
+    }, (raw) => {
+        try {
+            const parsed = JSON.parse(raw);
+            const score = parsed.score;
+            if (typeof score !== "number" || !Number.isInteger(score) || score < 1 || score > 5) {
+                return null;
+            }
+            const reasons = parsed.reasons;
+            if (!Array.isArray(reasons) ||
+                reasons.length === 0 ||
+                !reasons.every((r) => typeof r === "string" && r.length > 0)) {
+                return null;
+            }
+            return { score, reasons };
+        }
+        catch {
+            return null;
+        }
+    }, () => computeRetroQualityRubricScore(input));
+    return { ...result, source };
+}

package/dist/runtime-cleanup.d.ts

@@ -0,0 +1,18 @@
+type CleanupLogger = {
+    info?: (message: string, meta?: Record<string, unknown>) => void;
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+};
+export declare function cleanupOrgxRuntime(logger?: CleanupLogger): Promise<{
+    watchdog: {
+        pid: number | null;
+        wasRunning: boolean;
+        stopped: boolean;
+    };
+    runs: {
+        attempted: number;
+        stopped: number;
+        failed: number;
+        markedStopped: number;
+    };
+}>;
+export {};

package/dist/runtime-cleanup.js

@@ -0,0 +1,87 @@
+import { pathToFileURL } from "node:url";
+import { markAgentRunStopped, readAgentRuns } from "./agent-run-store.js";
+import { stopGatewayWatchdog } from "./gateway-watchdog.js";
+function isPidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sendSignal(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+        return;
+    }
+    catch {
+        // Fall back to direct process kill.
+    }
+    try {
+        process.kill(pid, signal);
+    }
+    catch {
+        // best effort
+    }
+}
+async function stopDetachedPid(pid) {
+    if (!isPidAlive(pid))
+        return true;
+    sendSignal(pid, "SIGTERM");
+    await new Promise((resolve) => setTimeout(resolve, 450));
+    if (isPidAlive(pid)) {
+        sendSignal(pid, "SIGKILL");
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+    return !isPidAlive(pid);
+}
+export async function cleanupOrgxRuntime(logger = console) {
+    const watchdog = await stopGatewayWatchdog(logger);
+    const runningRuns = Object.values(readAgentRuns().runs ?? {}).filter((run) => run?.status === "running");
+    let attempted = 0;
+    let stopped = 0;
+    let failed = 0;
+    let markedStopped = 0;
+    for (const run of runningRuns) {
+        if (!run || typeof run !== "object")
+            continue;
+        attempted += 1;
+        let runStopped = false;
+        if (typeof run.pid === "number" && Number.isFinite(run.pid) && run.pid > 0) {
+            runStopped = await stopDetachedPid(run.pid);
+        }
+        else {
+            runStopped = true;
+        }
+        if (runStopped)
+            stopped += 1;
+        else
+            failed += 1;
+        if (markAgentRunStopped(run.runId)) {
+            markedStopped += 1;
+        }
+    }
+    const summary = {
+        watchdog,
+        runs: { attempted, stopped, failed, markedStopped },
+    };
+    logger.info?.("[orgx] Runtime cleanup summary", summary);
+    return summary;
+}
+function isDirectRun() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    return import.meta.url === pathToFileURL(entry).href;
+}
+if (isDirectRun()) {
+    cleanupOrgxRuntime().catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[orgx] runtime cleanup failed: ${message}`);
+        // Never block uninstall/update for best-effort cleanup.
+        process.exitCode = 0;
+    });
+}

package/dist/runtime-instance-store.js

@@ -1,7 +1,8 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { getOrgxPluginConfigDir, getOrgxPluginConfigPath } from "./paths.js";
 import { backupCorruptFileSync, writeJsonFileAtomicSync } from "./fs-utils.js";
+import { clearStoreFileSync, ensureStoreDirSync, parseJsonSafe, } from "./stores/json-store.js";
 const MAX_INSTANCES = 600;
 export const DEFAULT_RUNTIME_HEARTBEAT_TIMEOUT_MS = 90_000;
 function runtimeDir() {
@@ -14,33 +15,12 @@ function hookTokenFile() {
     return getOrgxPluginConfigPath("runtime-hook-token.txt");
 }
 function ensureRuntimeDir() {
-    const dir = runtimeDir();
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    try {
-        chmodSync(dir, 0o700);
-    }
-    catch {
-        // best effort
-    }
+    ensureStoreDirSync(runtimeDir());
 }
 function writeHookTokenFile(token) {
     ensureRuntimeDir();
     const file = hookTokenFile();
     writeFileSync(file, `${token}\n`, { encoding: "utf8", mode: 0o600 });
-    try {
-        chmodSync(file, 0o600);
-    }
-    catch {
-        // best effort
-    }
-}
-function parseJson(value) {
-    try {
-        return JSON.parse(value);
-    }
-    catch {
-        return null;
-    }
 }
 function normalizeNullableString(value) {
     if (typeof value !== "string")
@@ -201,7 +181,7 @@ export function readRuntimeInstances() {
             return { updatedAt: new Date().toISOString(), instances: {} };
         }
         const raw = readFileSync(file, "utf8");
-        const parsed = parseJson(raw);
+        const parsed = parseJsonSafe(raw);
         if (!parsed || typeof parsed !== "object") {
             backupCorruptFileSync(file);
             return { updatedAt: new Date().toISOString(), instances: {} };
@@ -349,13 +329,7 @@ export function listRuntimeInstances(options) {
         .slice(0, limit);
 }
 export function clearRuntimeInstances() {
-    const file = runtimeFile();
-    try {
-        rmSync(file, { force: true });
-    }
-    catch {
-        // best effort
-    }
+    clearStoreFileSync(runtimeFile());
 }
 export function resolveRuntimeHookToken() {
     const envToken = normalizeNullableString(process.env.ORGX_HOOK_TOKEN);

package/dist/services/background.d.ts

@@ -0,0 +1,34 @@
+export interface RegisterServiceApi {
+    registerService: (service: {
+        id: string;
+        start: () => Promise<void>;
+        stop: () => Promise<void>;
+    }) => void;
+    log?: {
+        info?: (msg: string, meta?: Record<string, unknown>) => void;
+    };
+}
+export interface RegisterSyncServiceDeps {
+    api: RegisterServiceApi;
+    syncIntervalMs: number;
+    ensureGatewayWatchdog: (logger: Record<string, unknown>) => {
+        started: boolean;
+        pid?: number | null;
+    };
+    stopGatewayWatchdog?: () => Promise<{
+        pid: number | null;
+        wasRunning: boolean;
+        stopped: boolean;
+    }>;
+    stopTrackedAgentRuns?: () => Promise<{
+        attempted: number;
+        stopped: number;
+        failed: number;
+        markedStopped: number;
+    }>;
+    doSync: () => Promise<void>;
+    scheduleNextSync: () => void;
+    setSyncServiceRunning: (running: boolean) => void;
+    clearSyncTimer: () => void;
+}
+export declare function registerSyncService(deps: RegisterSyncServiceDeps): void;

package/dist/services/background.js

@@ -0,0 +1,45 @@
+export function registerSyncService(deps) {
+    deps.api.registerService({
+        id: "orgx-sync",
+        start: async () => {
+            deps.setSyncServiceRunning(true);
+            const watchdog = deps.ensureGatewayWatchdog((deps.api.log ?? {}));
+            if (watchdog.started) {
+                deps.api.log?.info?.("[orgx] Gateway watchdog started", {
+                    pid: watchdog.pid,
+                });
+            }
+            deps.api.log?.info?.("[orgx] Starting sync service", {
+                interval: deps.syncIntervalMs,
+            });
+            await deps.doSync();
+            deps.scheduleNextSync();
+        },
+        stop: async () => {
+            deps.setSyncServiceRunning(false);
+            deps.clearSyncTimer();
+            if (deps.stopTrackedAgentRuns) {
+                try {
+                    const result = await deps.stopTrackedAgentRuns();
+                    deps.api.log?.info?.("[orgx] Stopped tracked agent runs on plugin stop", result);
+                }
+                catch (err) {
+                    deps.api.log?.info?.("[orgx] Failed stopping tracked agent runs on plugin stop", {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            if (deps.stopGatewayWatchdog) {
+                try {
+                    const result = await deps.stopGatewayWatchdog();
+                    deps.api.log?.info?.("[orgx] Gateway watchdog teardown on plugin stop", result);
+                }
+                catch (err) {
+                    deps.api.log?.info?.("[orgx] Failed stopping watchdog on plugin stop", {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        },
+    });
+}

package/dist/services/experiment-randomization.d.ts

@@ -0,0 +1,21 @@
+export interface RandomizationArm {
+    id: string;
+    weight: number;
+}
+export interface RandomizationRequest {
+    experimentId: string;
+    subjectKey: string;
+    channel: string;
+    arms: RandomizationArm[];
+    seed?: string;
+}
+export interface RandomizationResult {
+    experimentId: string;
+    subjectKey: string;
+    channel: string;
+    assignmentKey: string;
+    exposureKey: string;
+    bucket: number;
+    armId: string;
+}
+export declare function randomizeExperimentAssignment(request: RandomizationRequest): RandomizationResult;

package/dist/services/experiment-randomization.js

@@ -0,0 +1,63 @@
+import { stableHash } from "../hash-utils.js";
+const MAX_UINT53 = 0x1fffffffffffff;
+export function randomizeExperimentAssignment(request) {
+    const experimentId = sanitizeIdentifier(request.experimentId, "experimentId");
+    const subjectKey = sanitizeIdentifier(request.subjectKey, "subjectKey");
+    const channel = sanitizeIdentifier(request.channel, "channel");
+    const normalizedArms = normalizeArms(request.arms);
+    const seed = typeof request.seed === "string" && request.seed.trim().length > 0 ? request.seed.trim() : "v1";
+    const assignmentKey = stableHash(`exp:${experimentId}:subject:${subjectKey}:seed:${seed}`);
+    const bucket = bucketFromHash(assignmentKey);
+    const armId = pickWeightedArm(bucket, normalizedArms);
+    return {
+        experimentId,
+        subjectKey,
+        channel,
+        assignmentKey,
+        exposureKey: stableHash(`exp:${experimentId}:subject:${subjectKey}:arm:${armId}:seed:${seed}`),
+        bucket,
+        armId,
+    };
+}
+function normalizeArms(arms) {
+    if (!Array.isArray(arms) || arms.length === 0) {
+        throw new Error("arms must include at least one entry");
+    }
+    const sanitized = arms.map((arm, index) => {
+        const id = sanitizeIdentifier(arm?.id, `arms[${index}].id`);
+        const weight = Number.isFinite(arm?.weight) ? Number(arm.weight) : Number.NaN;
+        if (!Number.isFinite(weight) || weight <= 0) {
+            throw new Error(`arms[${index}].weight must be > 0`);
+        }
+        return { id, weight };
+    });
+    const totalWeight = sanitized.reduce((sum, arm) => sum + arm.weight, 0);
+    if (totalWeight <= 0) {
+        throw new Error("arms total weight must be > 0");
+    }
+    return sanitized.map((arm) => ({ id: arm.id, weight: arm.weight / totalWeight }));
+}
+function pickWeightedArm(bucket, arms) {
+    let cursor = 0;
+    for (const arm of arms) {
+        cursor += arm.weight;
+        if (bucket < cursor) {
+            return arm.id;
+        }
+    }
+    return arms[arms.length - 1].id;
+}
+function sanitizeIdentifier(value, field) {
+    if (typeof value !== "string") {
+        throw new Error(`${field} must be a string`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error(`${field} cannot be empty`);
+    }
+    return trimmed;
+}
+function bucketFromHash(hash) {
+    const first53Bits = hash.slice(0, 14);
+    return parseInt(first53Bits, 16) / MAX_UINT53;
+}

package/dist/services/instrumentation.d.ts

@@ -0,0 +1,29 @@
+type ToolLike = {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (callId: string, params?: unknown) => Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+    }>;
+};
+type ServiceLike = {
+    id: string;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+};
+type ApiLike = {
+    registerTool: (tool: ToolLike, options?: {
+        optional?: boolean;
+    }) => void;
+    registerService: (service: ServiceLike) => void;
+};
+export declare function instrumentPluginApi(input: {
+    api: ApiLike;
+    installationId: string;
+    pluginVersion: string;
+    toErrorMessage: (err: unknown) => string;
+}): void;
+export {};