@useorgx/openclaw-plugin 0.7.11 → 0.7.15

package/dist/http/index.js

@@ -46,10 +46,11 @@ import { summarizeActivityHeadline } from "./helpers/activity-headline.js";
 import { createAutoContinueEngine, } from "./helpers/auto-continue-engine.js";
 import { createAutopilotOperations, } from "./helpers/autopilot-operations.js";
 import { mapDecisionEntity } from "./helpers/decision-mapper.js";
-import { idempotencyKey, stableHash } from "./helpers/hash-utils.js";
+import { deterministicActivityId, idempotencyKey, stableHash } from "./helpers/hash-utils.js";
 import { createCodexBinResolver, } from "./helpers/autopilot-slice-utils.js";
 import { createLocalArtifactDetailFallbackBuilder } from "./helpers/artifact-fallback.js";
 import { buildMissionControlGraph, deriveExecutionPolicy, dedupeStrings, isDispatchableWorkstreamStatus, isDoneStatus, isInProgressStatus, isTodoStatus, listEntitiesSafe, normalizeEntityMutationPayload, pickStringArray, resolveAutoAssignments, selectSliceTasksByScope, } from "./helpers/mission-control.js";
+import { QueueState, LaneState, RunStatus, RunnerSource, } from "./helpers/queue-constants.js";
 import { configureOpenClawProviderRouting, fetchBillingStatusSafe, isPidAlive, listOpenClawAgents, listOpenClawProviderModels, modelImpliesByok, normalizeOpenClawProvider, resolveAutoOpenClawProvider, resolveByokEnvOverrides, spawnOpenClawAgentTurn, stopDetachedProcess, } from "./helpers/openclaw-cli.js";
 import { fetchKickoffContextSafe, renderKickoffMessage } from "./helpers/kickoff-context.js";
 import { createDispatchLifecycle } from "./helpers/dispatch-lifecycle.js";
@@ -177,6 +178,9 @@ function safeErrorMessage(err) {
         if (normalized.includes("failed to fetch") || normalized.includes("network")) {
             return "network request failed";
         }
+        if (normalized.includes("relation does not exist")) {
+            return sanitized;
+        }
         if (normalized.includes("internal_error") || normalized.includes("internal server error")) {
             return "temporary server issue";
         }
@@ -380,6 +384,16 @@ function deriveStructuredActivityBucket(input) {
         "nonBlockingDecisionCount",
     ]) ?? 0;
     if (event === "autopilot_slice_result") {
+        const parsedStatus = typeof metadata?.parsed_status === "string"
+            ? metadata.parsed_status.trim().toLowerCase()
+            : typeof metadata?.parsedStatus === "string"
+                ? metadata.parsedStatus.trim().toLowerCase()
+                : "";
+        if (parsedStatus === "completed" && decisionRequired === false) {
+            if (artifacts > 0)
+                return "artifact";
+            return "message";
+        }
         // Any blocked slice result needs decision-first surfacing in the Activity UX.
         if (input.phase === "blocked")
             return "decision";
@@ -712,26 +726,10 @@ function activityMetadataStr(metadata, keys) {
     }
     return null;
 }
-const SEMANTIC_ACTIVITY_EVENTS = new Set([
-    "autopilot_slice_result",
-    "auto_continue_started",
-    "auto_continue_stopped",
-    "next_up_manual_dispatch_started",
-    "autopilot_slice_mcp_handshake_failed",
-    "autopilot_slice_timeout",
-    "autopilot_slice_log_stall",
-    "auto_continue_spawn_guard_blocked",
-    "auto_continue_spawn_guard_rate_limited",
-    "autopilot_autofix_scheduled",
-    "autopilot_autofix_executed",
-    "autopilot_autofix_skipped",
-]);
 function semanticActivityKey(item) {
     const metadata = asActivityMetadataRecord(item.metadata);
     const eventRaw = metadata?.event;
     const event = typeof eventRaw === "string" ? eventRaw.trim().toLowerCase() : "";
-    if (!event || !SEMANTIC_ACTIVITY_EVENTS.has(event))
-        return null;
     const runLike = (typeof item.runId === "string" && item.runId.trim().length > 0
         ? item.runId.trim()
         : null) ??
@@ -755,6 +753,8 @@ function semanticActivityKey(item) {
     const stopReason = activityMetadataStr(metadata, ["stop_reason", "stopReason"]);
     const parsedStatus = activityMetadataStr(metadata, ["parsed_status", "parsedStatus"]);
     const title = (item.title ?? "").trim().toLowerCase();
+    if (!event && !runLike && !correlationId)
+        return null;
     if (!runLike && !correlationId && !workstreamId && !taskId)
         return null;
     return [
@@ -769,6 +769,27 @@ function semanticActivityKey(item) {
         title,
     ].join("|");
 }
+function activityRichness(item) {
+    let score = 0;
+    const meta = item.metadata;
+    if (meta)
+        score += Object.keys(meta).length;
+    if (item.summary)
+        score += 2;
+    if (item.description)
+        score += 2;
+    if (item.agentName)
+        score += 1;
+    if (item.runtimeLabel)
+        score += 1;
+    if (item.runtimeProvider)
+        score += 1;
+    if (item.phase)
+        score += 1;
+    if (item.state)
+        score += 1;
+    return score;
+}
 function mergeActivities(base, extra, limit) {
     const merged = [...(base ?? []), ...(extra ?? [])].sort((a, b) => {
         const timestampDelta = Date.parse(b.timestamp) - Date.parse(a.timestamp);
@@ -779,15 +800,28 @@ function mergeActivities(base, extra, limit) {
     const deduped = [];
     const seenIds = new Set();
     const seenSemantic = new Set();
+    const semanticIdx = new Map();
     for (const item of merged) {
-        if (seenIds.has(item.id))
+        if (seenIds.has(item.id)) {
+            const existingIdx = deduped.findIndex(d => d.id === item.id);
+            if (existingIdx >= 0 && activityRichness(item) > activityRichness(deduped[existingIdx])) {
+                deduped[existingIdx] = item;
+            }
             continue;
+        }
         seenIds.add(item.id);
         const sk = semanticActivityKey(item);
-        if (sk && seenSemantic.has(sk))
+        if (sk && seenSemantic.has(sk)) {
+            const existingIdx = semanticIdx.get(sk);
+            if (activityRichness(item) > activityRichness(deduped[existingIdx])) {
+                deduped[existingIdx] = item;
+            }
             continue;
-        if (sk)
+        }
+        if (sk) {
             seenSemantic.add(sk);
+            semanticIdx.set(sk, deduped.length);
+        }
         deduped.push(item);
         if (deduped.length >= limit)
             break;
@@ -2173,11 +2207,11 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
             initiativeStatusById.set(initiativeId, override.status);
         }
         const queueRank = (state) => {
-            if (state === "running")
+            if (state === QueueState.RUNNING)
                 return 0;
-            if (state === "queued")
+            if (state === QueueState.QUEUED)
                 return 1;
-            if (state === "blocked")
+            if (state === QueueState.BLOCKED)
                 return 2;
             return 3;
         };
@@ -2322,12 +2356,12 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
                 const hasRunning = statusValues.some((status) => isInProgressStatus(status));
                 const hasQueued = statusValues.some((status) => status === "queued" || status === "pending");
                 const queueState = hasRunning
-                    ? "running"
+                    ? QueueState.RUNNING
                     : hasBlocked
-                        ? "blocked"
+                        ? QueueState.BLOCKED
                         : hasQueued
-                            ? "queued"
-                            : "idle";
+                            ? QueueState.QUEUED
+                            : QueueState.IDLE;
                 const latestRunner = [];
                 const latestRunnerSeen = new Set();
                 pushRunnerAgent(latestRunner, latestRunnerSeen, {
@@ -2341,7 +2375,7 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
                 const runnerAgentId = primaryRunner?.id ?? "unassigned";
                 const runnerAgentName = primaryRunner?.name ?? "Unassigned";
                 const pinKey = `${entry.initiativeId}:${entry.workstreamId}`;
-                if (isSuppressed(entry.initiativeId, entry.workstreamId) && queueState !== "running") {
+                if (isSuppressed(entry.initiativeId, entry.workstreamId) && queueState !== QueueState.RUNNING) {
                     continue;
                 }
                 fallbackItems.push({
@@ -2360,7 +2394,7 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
                     runnerAgentId,
                     runnerAgentName,
                     runnerAgents,
-                    runnerSource: "fallback",
+                    runnerSource: RunnerSource.FALLBACK,
                     queueState,
                     blockReason: hasBlocked
                         ? entry.blockers[0] ??
@@ -2545,7 +2579,7 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
                     : [];
                 const runScopedToCurrentWorkstream = scopedAllowedWorkstreams.length === 1 &&
                     scopedAllowedWorkstreams[0] === workstream.id &&
-                    autoContinueRun?.status === "running";
+                    autoContinueRun?.status === RunStatus.RUNNING;
                 const activeRunIds = Array.isArray(autoContinueRun?.activeSliceRunIds)
                     ? autoContinueRun.activeSliceRunIds
                         .filter((id) => typeof id === "string" && id.trim().length > 0)
@@ -2595,20 +2629,26 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
                 const sliceMilestoneId = defaultScope === "milestone"
                     ? scopeSelection.milestoneIds[0] ?? pin?.preferredMilestoneId ?? null
                     : null;
-                let queueState = laneState === "running"
-                    ? "running"
-                    : runScopedToCurrentWorkstream
-                        ? "running"
-                        : candidateTask
-                            ? "queued"
-                            : "idle";
+                // Only mark as "running" when the lane is actively executing a slice.
+                // runScopedToCurrentWorkstream means the initiative run targets this
+                // workstream, but the lane may be idle between slices — don't conflate
+                // "scoped to a running initiative" with "actively executing".
+                const laneIsActivelyRunning = laneState === LaneState.RUNNING ||
+                    (runScopedToCurrentWorkstream && activeRunIds.length > 0);
+                let queueState = laneIsActivelyRunning
+                    ? QueueState.RUNNING
+                    : candidateTask
+                        ? QueueState.QUEUED
+                        : runScopedToCurrentWorkstream
+                            ? QueueState.QUEUED
+                            : QueueState.IDLE;
                 let blockReason = null;
-                if (laneState === "blocked") {
-                    queueState = "blocked";
+                if (laneState === LaneState.BLOCKED) {
+                    queueState = QueueState.BLOCKED;
                     blockReason = autoContinueLane?.blockedReason ?? "Blocked";
                 }
-                else if (laneState === "waiting_dependency") {
-                    queueState = "blocked";
+                else if (laneState === LaneState.WAITING_DEPENDENCY) {
+                    queueState = QueueState.BLOCKED;
                     if (Array.isArray(autoContinueLane?.waitingOnWorkstreamIds) &&
                         autoContinueLane.waitingOnWorkstreamIds.length > 0) {
                         const waitingTitles = autoContinueLane.waitingOnWorkstreamIds
@@ -2626,12 +2666,12 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
                         blockReason = "Waiting on dependency workstreams";
                     }
                 }
-                else if (laneState === "rate_limited") {
-                    queueState = "blocked";
+                else if (laneState === LaneState.RATE_LIMITED) {
+                    queueState = QueueState.BLOCKED;
                     blockReason = autoContinueLane?.blockedReason ?? "Rate-limited";
                 }
                 if (!autoContinueRun && !readyTask && candidateTask) {
-                    queueState = "blocked";
+                    queueState = QueueState.BLOCKED;
                     const blockedDeps = candidateTask.dependencyIds
                         .map((depId) => nodeById.get(depId))
                         .filter((dependency) => Boolean(dependency && !isDoneStatus(dependency.status)))
@@ -2649,7 +2689,7 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
                 if (!candidateTask && !autoContinueRun && !pin) {
                     continue;
                 }
-                if (isSuppressed(initiativeId, workstream.id) && queueState !== "running") {
+                if (isSuppressed(initiativeId, workstream.id) && queueState !== QueueState.RUNNING) {
                     continue;
                 }
                 runningWorkstreams.add(workstream.id);
@@ -2684,10 +2724,10 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
                 }
                 const runnerAgents = assignedRunnerAgents.length > 0 ? assignedRunnerAgents : inferredRunnerAgents;
                 const runnerSource = assignedRunnerAgents.length > 0
-                    ? "assigned"
+                    ? RunnerSource.ASSIGNED
                     : runnerAgents.length > 0
-                        ? "inferred"
-                        : "fallback";
+                        ? RunnerSource.INFERRED
+                        : RunnerSource.FALLBACK;
                 const primaryRunner = runnerAgents[0] ?? null;
                 const runnerAgentId = primaryRunner?.id ?? "unassigned";
                 const runnerAgentName = primaryRunner?.name ?? "Unassigned";
@@ -2781,14 +2821,14 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
                         : activeTaskId
                             ? [activeTaskId]
                             : [];
-                    const queueState = laneState === "running"
-                        ? "running"
-                        : laneState === "blocked" ||
-                            laneState === "waiting_dependency" ||
-                            laneState === "rate_limited"
-                            ? "blocked"
-                            : "queued";
-                    if (isSuppressed(initiativeId, workstream.id) && queueState !== "running") {
+                    const queueState = laneState === LaneState.RUNNING
+                        ? QueueState.RUNNING
+                        : laneState === LaneState.BLOCKED ||
+                            laneState === LaneState.WAITING_DEPENDENCY ||
+                            laneState === LaneState.RATE_LIMITED
+                            ? QueueState.BLOCKED
+                            : QueueState.QUEUED;
+                    if (isSuppressed(initiativeId, workstream.id) && queueState !== QueueState.RUNNING) {
                         continue;
                     }
                     const runRunnerAgents = [];
@@ -2814,9 +2854,9 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
                         runnerAgentId: runPrimaryRunner?.id ?? "unassigned",
                         runnerAgentName: runPrimaryRunner?.name ?? "Unassigned",
                         runnerAgents: runRunnerAgents,
-                        runnerSource: runPrimaryRunner ? "inferred" : "fallback",
+                        runnerSource: runPrimaryRunner ? RunnerSource.INFERRED : RunnerSource.FALLBACK,
                         queueState,
-                        blockReason: queueState === "blocked"
+                        blockReason: queueState === QueueState.BLOCKED
                             ? lane?.blockedReason ?? "Blocked"
                             : null,
                         isPinned: Boolean(pinnedByKey.get(`${initiativeId}:${workstream.id}`)),
@@ -3240,10 +3280,11 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
                 broadcastRuntimeSse("runtime.updated", runtimeRecord);
             }
             clearSnapshotResponseCache();
+            const activityId = deterministicActivityId("run_completed", normalizedRunId, nowIso, runtimeRecord?.agentId ?? existingRun?.agentId ?? null, "dashboard_run_mark_completed");
             try {
                 appendActivityItems([
                     {
-                        id: randomUUID(),
+                        id: activityId,
                         type: "run_completed",
                         title: message,
                         description: reason,
@@ -3275,7 +3316,7 @@ export function createHttpHandler(config, client, getSnapshot, onboarding, diagn
             try {
                 const outboxSessionId = runtimeRecord?.initiativeId ?? existingRun?.initiativeId ?? normalizedRunId;
                 const outboxActivityItem = {
-                    id: randomUUID(),
+                    id: activityId,
                     type: "run_completed",
                     title: message,
                     description: reason,

package/dist/http/routes/chat.js

@@ -1,25 +1,5 @@
 import { getChatThread, linkChatThreadScope, listChatThreads, recordChatLaunch, sendChatMessage, updateChatLaunchStatus, } from "../../chat-store.js";
-function asRecord(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return null;
-    return value;
-}
-function asStringArray(value) {
-    if (!Array.isArray(value))
-        return [];
-    const out = [];
-    const seen = new Set();
-    for (const entry of value) {
-        if (typeof entry !== "string")
-            continue;
-        const trimmed = entry.trim();
-        if (!trimmed || seen.has(trimmed))
-            continue;
-        seen.add(trimmed);
-        out.push(trimmed);
-    }
-    return out;
-}
+import { asRecord, asStringArray } from "../../lib/type-coercion.js";
 function normalizeStatus(value) {
     const normalized = (value ?? "").trim().toLowerCase();
     if (normalized === "requested" ||

package/dist/http/routes/live-snapshot.js

@@ -450,29 +450,7 @@ export function registerLiveSnapshotRoutes(router, deps) {
         try {
             const buffered = await deps.readOutboxItems();
             if (buffered.length > 0) {
-                const merged = [...activity, ...buffered]
-                    .sort((a, b) => {
-                    const d = Date.parse(b.timestamp) - Date.parse(a.timestamp);
-                    if (d !== 0)
-                        return d;
-                    return b.id.localeCompare(a.id);
-                })
-                    .slice(0, activityLimit);
-                const deduped = [];
-                const seenIds = new Set();
-                const seenSemantic = new Set();
-                for (const item of merged) {
-                    if (seenIds.has(item.id))
-                        continue;
-                    seenIds.add(item.id);
-                    const sk = deps.semanticActivityKey(item);
-                    if (sk && seenSemantic.has(sk))
-                        continue;
-                    if (sk)
-                        seenSemantic.add(sk);
-                    deduped.push(item);
-                }
-                activity = deduped;
+                activity = deps.mergeActivities(activity, buffered, activityLimit);
             }
         }
         catch (err) {
@@ -500,6 +478,9 @@ export function registerLiveSnapshotRoutes(router, deps) {
             agents: agentContexts,
             runs: runContexts,
         });
+        // Final dedup pass after enrichment — catches items that became
+        // semantically identical after runtime/agent context decoration.
+        activity = deps.mergeActivities(activity, [], activityLimit);
         activity = activity.filter((item) => !shouldHideActivityItem(item));
         sessions = normalizeReportingBlockedSessions({
             sessions,

package/dist/http/routes/mission-control-actions.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { resolveWorkspaceScope as resolveCanonicalWorkspaceScope } from "../helpers/workspace-scope.js";
+import { asRecord, asString, asStringArray } from "../../lib/type-coercion.js";
 import { buildDispatchGatewayEnvelope } from "./dispatch-gateway-envelope.js";
 const PLAY_QUEUE_LOOKUP_TIMEOUT_MS = (() => {
     const raw = process.env.ORGX_PLAY_QUEUE_LOOKUP_TIMEOUT_MS;
@@ -194,24 +195,7 @@ function shouldResetTaskStatus(status, states) {
     }
     return false;
 }
-function asRecord(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return null;
-    return value;
-}
-function asString(value) {
-    if (typeof value !== "string")
-        return null;
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : null;
-}
-function asStringArray(value) {
-    if (!Array.isArray(value))
-        return [];
-    return value
-        .map((entry) => asString(entry))
-        .filter((entry) => Boolean(entry));
-}
+// asRecord, asString, asStringArray imported from ../../lib/type-coercion.js
 function parseCycleGraphNodes(graph) {
     const root = asRecord(graph);
     const rawNodes = Array.isArray(root?.nodes) ? root.nodes : [];

package/dist/http/routes/mission-control-read.js

@@ -1,34 +1,7 @@
 import { listBuiltInSentinels } from "../helpers/sentinel-catalog.js";
 import { resolveWorkspaceScope, workspaceScopeFromHeaders, } from "../helpers/workspace-scope.js";
-function asRecord(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return null;
-    return value;
-}
-function asString(value) {
-    if (typeof value !== "string")
-        return null;
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : null;
-}
-function asArray(value) {
-    if (Array.isArray(value))
-        return value;
-    if (typeof value !== "string")
-        return [];
-    const trimmed = value.trim();
-    try {
-        const parsed = JSON.parse(trimmed);
-        if (Array.isArray(parsed))
-            return parsed;
-        if (parsed && typeof parsed === "object")
-            return [parsed];
-        return [];
-    }
-    catch {
-        return [];
-    }
-}
+import { asRecord, asString, asNumber, asArray, asStringArray, } from "../../lib/type-coercion.js";
+// asRecord, asString, asArray, asNumber, asStringArray imported from ../../lib/type-coercion.js
 function normalizeRunnerValue(value) {
     const raw = asString(value);
     if (!raw)
@@ -105,29 +78,7 @@ function mergeRunnerAgents(...groups) {
     }
     return output;
 }
-function asNumber(value) {
-    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;
-}
-function asStringArray(value) {
-    const entries = asArray(value);
-    if (entries.length === 0)
-        return [];
-    const values = [];
-    for (const entry of entries) {
-        const normalized = asString(entry);
-        if (!normalized)
-            continue;
-        values.push(normalized);
-    }
-    return dedupeStrings(values);
-}
+// asNumber, asStringArray imported from ../../lib/type-coercion.js
 function isCanonicalAllScopeMismatch(canonicalRecord, useAllScope) {
     if (!useAllScope)
         return false;
@@ -846,64 +797,10 @@ export function registerMissionControlReadRoutes(router, deps) {
             sendRouteError(res, 400, "mission-control.read.auto-continue.status.validation", workspaceScope.error);
             return;
         }
-        const scopedProjectId = workspaceScope.workspaceId;
         const initiativeId = query.get("initiative_id") ?? query.get("initiativeId") ?? "";
         const id = initiativeId.trim();
-        let scopedInitiatives = null;
-        if (scopedProjectId) {
-            try {
-                const ids = await deps.listInitiativeIdsForProject({ projectId: scopedProjectId });
-                scopedInitiatives = new Set(ids);
-            }
-            catch {
-                // best effort: if scope lookup is unavailable, fall back to unscoped run resolution.
-                scopedInitiatives = null;
-            }
-        }
-        const statusRank = (value) => {
-            const normalized = (value ?? "").trim().toLowerCase();
-            if (normalized === "running")
-                return 0;
-            if (normalized === "stopping")
-                return 1;
-            if (normalized === "blocked")
-                return 2;
-            if (normalized === "stopped")
-                return 3;
-            return 4;
-        };
-        const updatedEpoch = (value) => {
-            const parsed = Date.parse(value ?? "");
-            return Number.isFinite(parsed) ? parsed : 0;
-        };
         if (!id) {
-            const scopedRuns = Array.from(deps.autoContinueRuns.values()).filter((run) => {
-                const runInitiativeId = (run.initiativeId ?? "").trim();
-                if (!runInitiativeId)
-                    return false;
-                if (scopedInitiatives && !scopedInitiatives.has(runInitiativeId))
-                    return false;
-                return true;
-            });
-            scopedRuns.sort((left, right) => {
-                const statusDelta = statusRank(left.status) - statusRank(right.status);
-                if (statusDelta !== 0)
-                    return statusDelta;
-                return updatedEpoch(right.updatedAt) - updatedEpoch(left.updatedAt);
-            });
-            const run = scopedRuns[0] ?? null;
-            deps.sendJson(res, 200, {
-                ok: true,
-                initiativeId: run?.initiativeId ?? null,
-                run,
-                defaults: {
-                    tokenBudget: deps.defaultAutoContinueTokenBudget(),
-                    maxParallelSlices: typeof deps.defaultAutoContinueMaxParallelSlices === "function"
-                        ? deps.defaultAutoContinueMaxParallelSlices()
-                        : 1,
-                    tickMs: deps.autoContinueTickMs,
-                },
-            });
+            sendRouteError(res, 400, "mission-control.read.auto-continue.status.validation", "initiativeId is required");
             return;
         }
         const run = deps.autoContinueRuns.get(id) ?? null;

package/dist/lib/type-coercion.d.ts

@@ -0,0 +1,10 @@
+/** Safely cast unknown to a Record, or null if not a plain object. */
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+/** Safely cast unknown to a trimmed non-empty string, or null. */
+export declare function asString(value: unknown): string | null;
+/** Safely cast unknown to a finite number, or null. */
+export declare function asNumber(value: unknown): number | null;
+/** Safely cast unknown to an array. Attempts JSON parse for string values. */
+export declare function asArray(value: unknown): unknown[];
+/** Extract a deduplicated string array from unknown. */
+export declare function asStringArray(value: unknown): string[];

package/dist/lib/type-coercion.js

@@ -0,0 +1,82 @@
+// ---------------------------------------------------------------------------
+// Shared type-coercion helpers for safe parsing of unknown API data.
+// Previously duplicated across 20+ files.
+// ---------------------------------------------------------------------------
+/** Safely cast unknown to a Record, or null if not a plain object. */
+export function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return null;
+    return value;
+}
+/** Safely cast unknown to a trimmed non-empty string, or null. */
+export function asString(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/** Safely cast unknown to a finite number, or null. */
+export function asNumber(value) {
+    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;
+}
+/** Safely cast unknown to an array. Attempts JSON parse for string values. */
+export function asArray(value) {
+    if (Array.isArray(value))
+        return value;
+    if (asRecord(value))
+        return [value];
+    if (typeof value !== "string")
+        return [];
+    const trimmed = value.trim();
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed))
+            return parsed;
+        if (asRecord(parsed))
+            return [parsed];
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Extract a deduplicated string array from unknown. */
+export function asStringArray(value) {
+    const entries = asArray(value);
+    if (entries.length === 0) {
+        const scalar = asString(value);
+        if (!scalar)
+            return [];
+        const fallbackEntries = scalar.includes(",") ? scalar.split(",") : [scalar];
+        const seenFallback = new Set();
+        const fallbackValues = [];
+        for (const entry of fallbackEntries) {
+            const normalized = asString(entry);
+            if (!normalized || seenFallback.has(normalized))
+                continue;
+            seenFallback.add(normalized);
+            fallbackValues.push(normalized);
+        }
+        return fallbackValues;
+    }
+    const seen = new Set();
+    const values = [];
+    for (const entry of entries) {
+        const normalized = asString(entry);
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        values.push(normalized);
+    }
+    return values;
+}