@useorgx/openclaw-plugin 0.4.9 → 0.7.2

package/dist/services/background.js

@@ -18,6 +18,28 @@ export function registerSyncService(deps) {
         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/skill-pack-state.d.ts

@@ -1,15 +1,32 @@
 import type { SkillPack } from "./contracts/types.js";
 import type { OrgxSkillPackOverrides } from "./agent-suite.js";
+export type SkillPackPolicy = {
+    frozen: boolean;
+    pinnedChecksum: string | null;
+};
+export type SkillPackPolicyDiff = {
+    field: "policy.frozen" | "policy.pinnedChecksum";
+    before: boolean | string | null;
+    after: boolean | string | null;
+};
+export type SkillPackPolicyAuditEntry = {
+    id: string;
+    changedAt: string;
+    changedBy: string;
+    action: "policy.update" | "policy.rollback";
+    reason: string | null;
+    rollbackOfAuditId: string | null;
+    diff: SkillPackPolicyDiff[];
+    beforePolicy: SkillPackPolicy;
+    afterPolicy: SkillPackPolicy;
+};
 export type SkillPackState = {
     version: 1;
     updatedAt: string;
     lastCheckedAt: string | null;
     lastError: string | null;
     etag: string | null;
-    policy: {
-        frozen: boolean;
-        pinnedChecksum: string | null;
-    };
+    policy: SkillPackPolicy;
     pack: {
         name: string;
         version: string;
@@ -23,6 +40,9 @@ export type SkillPackState = {
         updated_at: string | null;
     } | null;
     overrides: OrgxSkillPackOverrides | null;
+    audit: {
+        entries: SkillPackPolicyAuditEntry[];
+    };
 };
 export declare function readSkillPackState(input?: {
     openclawDir?: string;
@@ -36,11 +56,22 @@ export declare function updateSkillPackPolicy(input: {
     pinnedChecksum?: string | null;
     pinToCurrent?: boolean;
     clearPin?: boolean;
+    changedBy?: string;
+    reason?: string;
+}): SkillPackState;
+export declare function rollbackSkillPackPolicy(input?: {
+    openclawDir?: string;
+    auditId?: string;
+    changedBy?: string;
+    reason?: string;
 }): SkillPackState;
 export declare function toOrgxSkillPackOverrides(input: {
     pack: SkillPack;
     etag: string | null;
-}): OrgxSkillPackOverrides;
+}): {
+    overrides: OrgxSkillPackOverrides;
+    validationErrors: string[];
+};
 export declare function refreshSkillPackState(input: {
     getSkillPack: (args: {
         name?: string;

package/dist/skill-pack-state.js

@@ -2,8 +2,10 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { writeFileAtomicSync } from "./fs-utils.js";
 import { getOpenClawDir } from "./paths.js";
+import { validateOpenClawSkillPackManifest } from "./contracts/skill-pack-schema.js";
 const STORE_VERSION = 1;
 const STATE_FILENAME = "orgx-skill-pack-state.json";
+const AUDIT_HISTORY_LIMIT = 50;
 function nowIso() {
     return new Date().toISOString();
 }
@@ -16,6 +18,94 @@ function coerceString(value) {
 function statePath(openclawDir) {
     return join(openclawDir, STATE_FILENAME);
 }
+function clonePolicy(input) {
+    return {
+        frozen: Boolean(input.frozen),
+        pinnedChecksum: coerceString(input.pinnedChecksum),
+    };
+}
+function normalizeChangedBy(input) {
+    if (typeof input !== "string")
+        return "unknown";
+    const value = input.trim();
+    return value.length > 0 ? value : "unknown";
+}
+function normalizeReason(input) {
+    return typeof input === "string" && input.trim().length > 0 ? input.trim() : null;
+}
+function nextAuditId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function computePolicyDiff(before, after) {
+    const diff = [];
+    if (before.frozen !== after.frozen) {
+        diff.push({
+            field: "policy.frozen",
+            before: before.frozen,
+            after: after.frozen,
+        });
+    }
+    if (before.pinnedChecksum !== after.pinnedChecksum) {
+        diff.push({
+            field: "policy.pinnedChecksum",
+            before: before.pinnedChecksum,
+            after: after.pinnedChecksum,
+        });
+    }
+    return diff;
+}
+function appendPolicyAuditEntry(entries, entry) {
+    return [entry, ...entries].slice(0, AUDIT_HISTORY_LIMIT);
+}
+function parseAuditEntries(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const entries = [];
+    for (const candidate of raw) {
+        if (!isRecord(candidate))
+            continue;
+        const beforePolicyRaw = isRecord(candidate.beforePolicy) ? candidate.beforePolicy : null;
+        const afterPolicyRaw = isRecord(candidate.afterPolicy) ? candidate.afterPolicy : null;
+        if (!beforePolicyRaw || !afterPolicyRaw)
+            continue;
+        const diffRaw = Array.isArray(candidate.diff) ? candidate.diff : [];
+        const diff = [];
+        for (const diffEntry of diffRaw) {
+            if (!isRecord(diffEntry))
+                continue;
+            const field = diffEntry.field;
+            if (field !== "policy.frozen" && field !== "policy.pinnedChecksum")
+                continue;
+            diff.push({
+                field,
+                before: typeof diffEntry.before === "boolean" || diffEntry.before === null
+                    ? diffEntry.before
+                    : coerceString(diffEntry.before),
+                after: typeof diffEntry.after === "boolean" || diffEntry.after === null
+                    ? diffEntry.after
+                    : coerceString(diffEntry.after),
+            });
+        }
+        entries.push({
+            id: coerceString(candidate.id) ?? nextAuditId(),
+            changedAt: coerceString(candidate.changedAt) ?? nowIso(),
+            changedBy: normalizeChangedBy(candidate.changedBy),
+            action: candidate.action === "policy.rollback" ? "policy.rollback" : "policy.update",
+            reason: normalizeReason(candidate.reason),
+            rollbackOfAuditId: coerceString(candidate.rollbackOfAuditId),
+            diff,
+            beforePolicy: {
+                frozen: Boolean(beforePolicyRaw.frozen),
+                pinnedChecksum: coerceString(beforePolicyRaw.pinnedChecksum),
+            },
+            afterPolicy: {
+                frozen: Boolean(afterPolicyRaw.frozen),
+                pinnedChecksum: coerceString(afterPolicyRaw.pinnedChecksum),
+            },
+        });
+    }
+    return entries.slice(0, AUDIT_HISTORY_LIMIT);
+}
 export function readSkillPackState(input) {
     const openclawDir = input?.openclawDir ?? getOpenClawDir();
     const path = statePath(openclawDir);
@@ -29,6 +119,7 @@ export function readSkillPackState(input) {
         pack: null,
         remote: null,
         overrides: null,
+        audit: { entries: [] },
     };
     try {
         if (!existsSync(path))
@@ -43,6 +134,7 @@ export function readSkillPackState(input) {
         const pack = isRecord(parsed.pack) ? parsed.pack : null;
         const remote = isRecord(parsed.remote) ? parsed.remote : null;
         const overrides = isRecord(parsed.overrides) ? parsed.overrides : null;
+        const audit = isRecord(parsed.audit) ? parsed.audit : null;
         return {
             version: STORE_VERSION,
             updatedAt: coerceString(parsed.updatedAt) ?? nowIso(),
@@ -72,6 +164,9 @@ export function readSkillPackState(input) {
             overrides: overrides
                 ? overrides
                 : null,
+            audit: {
+                entries: parseAuditEntries(audit?.entries),
+            },
         };
     }
     catch {
@@ -88,7 +183,12 @@ export function writeSkillPackState(state, input) {
 }
 export function updateSkillPackPolicy(input) {
     const prev = readSkillPackState({ openclawDir: input.openclawDir });
+    const beforePolicy = clonePolicy(prev.policy);
     const nextPolicy = { ...prev.policy };
+    const activeChecksum = prev.pack?.checksum ?? null;
+    const remoteChecksum = prev.remote?.checksum ?? null;
+    const hasInactiveRemoteCandidate = Boolean(remoteChecksum && remoteChecksum !== activeChecksum);
+    const blockedByActivationValidation = hasInactiveRemoteCandidate && hasActivationValidationFailure(prev.lastError);
     if (typeof input.frozen === "boolean") {
         nextPolicy.frozen = input.frozen;
     }
@@ -96,10 +196,20 @@ export function updateSkillPackPolicy(input) {
         nextPolicy.pinnedChecksum = null;
     }
     else if (input.pinToCurrent) {
+        if (blockedByActivationValidation) {
+            throw new Error("Cannot pin_to_current: remote config failed eval/manifest checks and is not active.");
+        }
         nextPolicy.pinnedChecksum = prev.pack?.checksum ?? prev.remote?.checksum ?? null;
     }
     else if (typeof input.pinnedChecksum === "string") {
-        nextPolicy.pinnedChecksum = input.pinnedChecksum.trim() || null;
+        const requestedChecksum = input.pinnedChecksum.trim() || null;
+        if (requestedChecksum &&
+            remoteChecksum &&
+            requestedChecksum === remoteChecksum &&
+            blockedByActivationValidation) {
+            throw new Error("Cannot pin checksum to remote config: eval/manifest checks are failing for that candidate.");
+        }
+        nextPolicy.pinnedChecksum = requestedChecksum;
     }
     else if (input.pinnedChecksum === null) {
         nextPolicy.pinnedChecksum = null;
@@ -109,48 +219,155 @@ export function updateSkillPackPolicy(input) {
         updatedAt: nowIso(),
         policy: nextPolicy,
     };
+    const diff = computePolicyDiff(beforePolicy, next.policy);
+    if (diff.length > 0) {
+        const entry = {
+            id: nextAuditId(),
+            changedAt: next.updatedAt,
+            changedBy: normalizeChangedBy(input.changedBy),
+            action: "policy.update",
+            reason: normalizeReason(input.reason),
+            rollbackOfAuditId: null,
+            diff,
+            beforePolicy,
+            afterPolicy: clonePolicy(next.policy),
+        };
+        next.audit = {
+            entries: appendPolicyAuditEntry(prev.audit.entries, entry),
+        };
+    }
     writeSkillPackState(next, { openclawDir: input.openclawDir });
     return next;
 }
+export function rollbackSkillPackPolicy(input) {
+    const prev = readSkillPackState({ openclawDir: input?.openclawDir });
+    const normalizedAuditId = typeof input?.auditId === "string" && input.auditId.trim().length > 0
+        ? input.auditId.trim()
+        : null;
+    const target = normalizedAuditId
+        ? prev.audit.entries.find((entry) => entry.id === normalizedAuditId) ?? null
+        : prev.audit.entries[0] ?? null;
+    if (!target) {
+        throw new Error("No policy audit entry available for rollback");
+    }
+    const beforePolicy = clonePolicy(prev.policy);
+    const afterPolicy = clonePolicy(target.beforePolicy);
+    const diff = computePolicyDiff(beforePolicy, afterPolicy);
+    if (diff.length === 0) {
+        return prev;
+    }
+    const changedAt = nowIso();
+    const rollbackEntry = {
+        id: nextAuditId(),
+        changedAt,
+        changedBy: normalizeChangedBy(input?.changedBy),
+        action: "policy.rollback",
+        reason: normalizeReason(input?.reason) ?? `Rollback to audit ${target.id}`,
+        rollbackOfAuditId: target.id,
+        diff,
+        beforePolicy,
+        afterPolicy,
+    };
+    const next = {
+        ...prev,
+        updatedAt: changedAt,
+        policy: afterPolicy,
+        audit: {
+            entries: appendPolicyAuditEntry(prev.audit.entries, rollbackEntry),
+        },
+    };
+    writeSkillPackState(next, { openclawDir: input?.openclawDir });
+    return next;
+}
 function asRecord(value) {
     return isRecord(value) ? value : null;
 }
-function parseOpenclawSkillOverridesFromManifest(manifest) {
-    const root = manifest ?? {};
+function asBoolean(value) {
+    return typeof value === "boolean" ? value : null;
+}
+function asFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function normalizeStatus(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim().toLowerCase().replace(/[\s-]+/g, "_");
+    return normalized.length > 0 ? normalized : null;
+}
+function hasActivationValidationFailure(lastError) {
+    if (!lastError)
+        return false;
+    const normalized = lastError.toLowerCase();
+    return (normalized.includes("eval framework checks did not pass") ||
+        normalized.includes("eval gate blocked activation") ||
+        normalized.includes("manifest validation errors"));
+}
+function evalGateErrorForPack(pack) {
+    const manifest = asRecord(pack.manifest);
+    if (!manifest) {
+        return "SkillPack eval framework checks did not pass: missing manifest object";
+    }
     const candidates = [
-        asRecord(root.openclaw_skills),
-        asRecord(root.openclawSkills),
-        asRecord(asRecord(root.openclaw)?.skills),
-    ].filter(Boolean);
-    const out = {};
+        { label: "eval_framework", value: asRecord(manifest.eval_framework) },
+        { label: "evalFramework", value: asRecord(manifest.evalFramework) },
+        { label: "evaluation_result", value: asRecord(manifest.evaluation_result) },
+        { label: "evaluationResult", value: asRecord(manifest.evaluationResult) },
+        { label: "evaluation", value: asRecord(manifest.evaluation) },
+        { label: "quality_gate", value: asRecord(manifest.quality_gate) },
+        { label: "qualityGate", value: asRecord(manifest.qualityGate) },
+    ];
     for (const candidate of candidates) {
-        for (const [k, v] of Object.entries(candidate)) {
-            if (typeof v !== "string")
-                continue;
-            const key = k.trim().toLowerCase();
-            if (!key)
-                continue;
-            out[key] = v;
+        if (!candidate.value)
+            continue;
+        const passed = asBoolean(candidate.value.passed) ??
+            asBoolean(candidate.value.ok) ??
+            asBoolean(candidate.value.success) ??
+            asBoolean(candidate.value.allowed);
+        if (passed != null) {
+            return passed
+                ? null
+                : `SkillPack eval framework checks did not pass: ${candidate.label}.passed=false`;
+        }
+        const status = normalizeStatus(candidate.value.status);
+        if (status) {
+            const passStatuses = new Set(["pass", "passed", "ok", "success", "approved", "green"]);
+            const failStatuses = new Set(["fail", "failed", "rejected", "error", "blocked", "red"]);
+            if (passStatuses.has(status))
+                return null;
+            if (failStatuses.has(status)) {
+                return `SkillPack eval framework checks did not pass: ${candidate.label}.status=${status}`;
+            }
+        }
+        const checksTotal = asFiniteNumber(candidate.value.checks_total) ??
+            asFiniteNumber(candidate.value.total_checks);
+        const checksPassed = asFiniteNumber(candidate.value.checks_passed) ??
+            asFiniteNumber(candidate.value.passed_checks);
+        if (checksTotal != null && checksPassed != null && checksTotal > 0) {
+            return checksPassed >= checksTotal
+                ? null
+                : `SkillPack eval framework checks did not pass: ${candidate.label}.checks=${checksPassed}/${checksTotal}`;
         }
     }
-    return out;
+    return "SkillPack eval framework checks did not pass: missing pass signal in manifest";
 }
 export function toOrgxSkillPackOverrides(input) {
-    const manifest = asRecord(input.pack.manifest) ?? {};
-    const rawOverrides = parseOpenclawSkillOverridesFromManifest(manifest);
+    const manifest = asRecord(input.pack.manifest);
+    const validation = validateOpenClawSkillPackManifest(manifest ?? {});
     const openclaw_skills = {};
-    for (const [k, v] of Object.entries(rawOverrides)) {
-        // Domains are normalized to lowercase keys in the manifest.
+    for (const [k, v] of Object.entries(validation.openclaw_skills)) {
         openclaw_skills[k] = v;
     }
     return {
-        source: "server",
-        name: input.pack.name,
-        version: input.pack.version,
-        checksum: input.pack.checksum,
-        etag: input.etag,
-        updated_at: input.pack.updated_at ?? null,
-        openclaw_skills,
+        overrides: {
+            source: "server",
+            name: input.pack.name,
+            version: input.pack.version,
+            checksum: input.pack.checksum,
+            etag: input.etag,
+            updated_at: input.pack.updated_at ?? null,
+            openclaw_skills,
+        },
+        validationErrors: validation.errors,
     };
 }
 export async function refreshSkillPackState(input) {
@@ -201,7 +418,33 @@ export async function refreshSkillPackState(input) {
             writeSkillPackState(next, { openclawDir: input.openclawDir });
             return { state: next, changed: false };
         }
-        const overrides = toOrgxSkillPackOverrides({ pack: result.pack, etag: result.etag ?? null });
+        const { overrides, validationErrors } = toOrgxSkillPackOverrides({
+            pack: result.pack,
+            etag: result.etag ?? null,
+        });
+        const evalGateError = evalGateErrorForPack(result.pack);
+        const activationErrors = [];
+        if (validationErrors.length > 0) {
+            activationErrors.push(`SkillPack manifest validation errors: ${validationErrors.join("; ")}`);
+        }
+        if (evalGateError) {
+            activationErrors.push(evalGateError);
+        }
+        const activationValidationError = activationErrors.length > 0 ? activationErrors.join(" | ") : null;
+        // Guardrail: never activate a config that fails eval/manifest validation.
+        // Keep it staged in `remote` + `lastError` so operators can inspect/fix it.
+        if (activationValidationError) {
+            const next = {
+                ...prev,
+                updatedAt: nowIso(),
+                lastCheckedAt: nowIso(),
+                lastError: activationValidationError,
+                etag: result.etag ?? prev.etag,
+                remote: remoteMeta,
+            };
+            writeSkillPackState(next, { openclawDir: input.openclawDir });
+            return { state: next, changed: false };
+        }
         const next = {
             version: STORE_VERSION,
             updatedAt: nowIso(),
@@ -217,6 +460,7 @@ export async function refreshSkillPackState(input) {
             },
             remote: remoteMeta,
             overrides,
+            audit: prev.audit,
         };
         writeSkillPackState(next, { openclawDir: input.openclawDir });
         return { state: next, changed: prev.pack?.checksum !== next.pack?.checksum };
@@ -225,7 +469,7 @@ export async function refreshSkillPackState(input) {
         ...prev,
         updatedAt: nowIso(),
         lastCheckedAt: nowIso(),
-        lastError: !result.ok ? result.error : prev.lastError,
+        lastError: result.ok === false ? result.error : prev.lastError,
     };
     writeSkillPackState(next, { openclawDir: input.openclawDir });
     return { state: next, changed: false };

package/dist/sync/local-agent-telemetry.d.ts

@@ -0,0 +1,13 @@
+import type { AgentRunRecord } from "../agent-run-store.js";
+import type { AgentState } from "../types.js";
+export declare function buildLocalAgentMirrorsFromSnapshot(input: {
+    agents: AgentState[] | null | undefined;
+}): AgentState[];
+/**
+ * Derive live local agent states from active OpenClaw runs so sync can mirror
+ * local runtime telemetry into OrgX.
+ */
+export declare function buildLocalSyncAgentsFromRuns(input: {
+    runs: Record<string, AgentRunRecord>;
+    mirrors?: AgentState[] | null;
+}): AgentState[];