@useorgx/openclaw-plugin 0.4.8 → 0.4.9

package/dist/contracts/types.d.ts

@@ -4,6 +4,7 @@
  * Types for the plugin's API client and tool interfaces.
  * Mirrors the server-side types in orgx/lib/client-integration/types.ts
  */
+export type { HandoffEvent, HandoffSummary, LiveActivityItem, LiveActivityType, LiveDecision, OnboardingKeySource, OnboardingNextAction, OnboardingState, OnboardingStatus, RunPhase, RuntimeInstance, RuntimeInstanceState, RuntimeProviderLogo, RuntimeSourceClient, SessionTreeEdge, SessionTreeGroup, SessionTreeNode, SessionTreeResponse, } from './shared-types.js';
 export interface OrgXConfig {
     /** OrgX API key */
     apiKey: string;
@@ -24,23 +25,6 @@ export interface OrgXConfig {
      */
     autoInstallAgentSuiteOnConnect?: boolean;
 }
-export type OnboardingStatus = 'idle' | 'starting' | 'awaiting_browser_auth' | 'pairing' | 'connected' | 'error' | 'manual_key';
-export type OnboardingNextAction = 'connect' | 'wait_for_browser' | 'open_dashboard' | 'enter_manual_key' | 'retry' | 'reconnect';
-export interface OnboardingState {
-    status: OnboardingStatus;
-    hasApiKey: boolean;
-    connectionVerified: boolean;
-    workspaceName: string | null;
-    lastError: string | null;
-    nextAction: OnboardingNextAction;
-    docsUrl: string;
-    keySource: 'config' | 'environment' | 'persisted' | 'openclaw-config-file' | 'legacy-dev' | 'none';
-    installationId: string | null;
-    connectUrl: string | null;
-    pairingId: string | null;
-    expiresAt: string | null;
-    pollIntervalMs: number | null;
-}
 export interface OrgSnapshot {
     /** Active initiatives */
     initiatives: Initiative[];
@@ -265,7 +249,6 @@ export interface BillingUrlResult {
     url: string | null;
     checkout_url?: string | null;
 }
-export type RunPhase = 'intent' | 'execution' | 'blocked' | 'review' | 'handoff' | 'completed';
 export interface HandoffWorkspaceState {
     git?: {
         branch?: string | null;
@@ -397,7 +380,6 @@ export interface EntityListFilters {
     [key: string]: unknown;
 }
 export type ReportingSourceClient = 'openclaw' | 'codex' | 'claude-code' | 'api';
-export type RuntimeSourceClient = ReportingSourceClient | 'unknown';
 export type ReportingPhase = 'intent' | 'execution' | 'blocked' | 'review' | 'handoff' | 'completed';
 export type ReportingLevel = 'info' | 'warn' | 'error';
 export type TaskStatus = 'todo' | 'in_progress' | 'done' | 'blocked';
@@ -538,118 +520,3 @@ export interface RecordRunRetroResponse {
     event_id: string | null;
     auth_mode?: 'service' | 'api_key';
 }
-export type LiveActivityType = 'run_started' | 'run_completed' | 'run_failed' | 'artifact_created' | 'decision_requested' | 'decision_resolved' | 'handoff_requested' | 'handoff_claimed' | 'handoff_fulfilled' | 'blocker_created' | 'milestone_completed' | 'delegation';
-export type RuntimeInstanceState = 'active' | 'stale' | 'stopped' | 'error';
-export interface RuntimeInstance {
-    id: string;
-    sourceClient: RuntimeSourceClient;
-    displayName: string;
-    providerLogo: 'codex' | 'openai' | 'anthropic' | 'openclaw' | 'orgx' | 'unknown';
-    state: RuntimeInstanceState;
-    runId: string | null;
-    correlationId: string | null;
-    initiativeId: string | null;
-    workstreamId: string | null;
-    taskId: string | null;
-    agentId: string | null;
-    agentName: string | null;
-    phase: string | null;
-    progressPct: number | null;
-    currentTask: string | null;
-    lastHeartbeatAt: string | null;
-    lastEventAt: string;
-    lastMessage: string | null;
-    metadata: Record<string, unknown> | null;
-}
-export interface LiveActivityItem {
-    id: string;
-    type: LiveActivityType;
-    title: string;
-    description: string | null;
-    agentId: string | null;
-    agentName: string | null;
-    requesterAgentId: string | null;
-    requesterAgentName: string | null;
-    executorAgentId: string | null;
-    executorAgentName: string | null;
-    runId: string | null;
-    initiativeId: string | null;
-    timestamp: string;
-    phase?: RunPhase | null;
-    state?: string | null;
-    kind?: string | null;
-    summary?: string | null;
-    decisionRequired?: boolean;
-    costDelta?: number | null;
-    runtimeClient?: RuntimeSourceClient | null;
-    runtimeLabel?: string | null;
-    runtimeProvider?: RuntimeInstance['providerLogo'] | null;
-    instanceId?: string | null;
-    lastHeartbeatAt?: string | null;
-    metadata?: Record<string, unknown>;
-}
-export interface SessionTreeNode {
-    id: string;
-    parentId: string | null;
-    runId: string;
-    title: string;
-    agentId: string | null;
-    agentName: string | null;
-    status: string;
-    progress: number | null;
-    initiativeId: string | null;
-    workstreamId: string | null;
-    groupId: string;
-    groupLabel: string;
-    startedAt: string | null;
-    updatedAt: string | null;
-    lastEventAt: string | null;
-    lastEventSummary: string | null;
-    blockers: string[];
-    phase?: RunPhase | null;
-    state?: string | null;
-    eta?: string | null;
-    cost?: number | null;
-    checkpointCount?: number | null;
-    blockerReason?: string | null;
-    runtimeClient?: RuntimeSourceClient | null;
-    runtimeLabel?: string | null;
-    runtimeProvider?: RuntimeInstance['providerLogo'] | null;
-    instanceId?: string | null;
-    lastHeartbeatAt?: string | null;
-}
-export interface SessionTreeEdge {
-    parentId: string;
-    childId: string;
-}
-export interface SessionTreeGroup {
-    id: string;
-    label: string;
-    status: string | null;
-}
-export interface SessionTreeResponse {
-    nodes: SessionTreeNode[];
-    edges: SessionTreeEdge[];
-    groups: SessionTreeGroup[];
-}
-export interface HandoffEvent {
-    id: string;
-    handoffId: string;
-    eventType: string;
-    actorType: string | null;
-    actorId: string | null;
-    payload: Record<string, unknown> | null;
-    createdAt: string;
-}
-export interface HandoffSummary {
-    id: string;
-    title: string;
-    status: string;
-    priority: string | null;
-    summary: string | null;
-    currentActorType: string | null;
-    currentActorId: string | null;
-    createdAt: string;
-    updatedAt: string;
-    events: HandoffEvent[];
-}

package/dist/contracts/types.js

@@ -5,3 +5,8 @@
  * Mirrors the server-side types in orgx/lib/client-integration/types.ts
  */
 export {};
+// =============================================================================
+// LIVE SESSION GRAPH + HANDOFFS
+// =============================================================================
+// Live/session/handoff activity shapes are imported and re-exported from
+// ./shared-types.ts to keep dashboard and plugin contracts in lockstep.

package/dist/entities/auto-assignment.d.ts

@@ -0,0 +1,36 @@
+export type AutoAssignedAgent = {
+    id: string;
+    name: string;
+    domain: string | null;
+};
+export declare function autoAssignEntityForCreate(input: {
+    client: {
+        getLiveAgents: (payload: {
+            initiative: string | null;
+            includeIdle: boolean;
+        }) => Promise<{
+            agents?: unknown[];
+        }>;
+        delegationPreflight: (payload: {
+            intent: string;
+        }) => Promise<{
+            data?: {
+                recommended_split?: Array<{
+                    owner_domain?: string | null;
+                }>;
+            };
+        }>;
+        updateEntity: (entityType: string, entityId: string, payload: Record<string, unknown>) => Promise<unknown>;
+    };
+    toErrorMessage: (err: unknown) => string;
+    entityType: string;
+    entityId: string;
+    initiativeId: string | null;
+    title: string;
+    summary: string | null;
+}): Promise<{
+    assignmentSource: "orchestrator" | "fallback" | "manual";
+    assignedAgents: AutoAssignedAgent[];
+    warnings: string[];
+    updatedEntity: Record<string, unknown> | null;
+}>;

package/dist/entities/auto-assignment.js

@@ -0,0 +1,115 @@
+export async function autoAssignEntityForCreate(input) {
+    const warnings = [];
+    const byKey = new Map();
+    const addAgent = (agent) => {
+        const key = `${agent.id}:${agent.name}`.toLowerCase();
+        if (!byKey.has(key))
+            byKey.set(key, agent);
+    };
+    let liveAgents = [];
+    try {
+        const agentResp = await input.client.getLiveAgents({
+            initiative: input.initiativeId,
+            includeIdle: true,
+        });
+        liveAgents = (Array.isArray(agentResp.agents) ? agentResp.agents : [])
+            .map((raw) => {
+            if (!raw || typeof raw !== "object")
+                return null;
+            const record = raw;
+            const id = (typeof record.id === "string" && record.id.trim()) ||
+                (typeof record.agentId === "string" && record.agentId.trim()) ||
+                "";
+            const name = (typeof record.name === "string" && record.name.trim()) ||
+                (typeof record.agentName === "string" && record.agentName.trim()) ||
+                id;
+            if (!name)
+                return null;
+            return {
+                id: id || `name:${name}`,
+                name,
+                domain: (typeof record.domain === "string" && record.domain.trim()) ||
+                    (typeof record.role === "string" && record.role.trim()) ||
+                    null,
+                status: (typeof record.status === "string" && record.status.trim()) || null,
+            };
+        })
+            .filter((agent) => agent !== null);
+    }
+    catch (err) {
+        warnings.push(`live agents unavailable (${input.toErrorMessage(err)})`);
+    }
+    const orchestrator = liveAgents.find((agent) => /holt|orchestrator/i.test(agent.name) ||
+        /orchestrator/i.test(agent.domain ?? ""));
+    if (orchestrator)
+        addAgent(orchestrator);
+    let assignmentSource = "fallback";
+    try {
+        const preflight = await input.client.delegationPreflight({
+            intent: `${input.title}${input.summary ? `: ${input.summary}` : ""}`,
+        });
+        const recommendations = preflight.data?.recommended_split ?? [];
+        const recommendedDomains = [
+            ...new Set(recommendations
+                .map((entry) => String(entry.owner_domain ?? "").trim().toLowerCase())
+                .filter(Boolean)),
+        ];
+        for (const domain of recommendedDomains) {
+            const match = liveAgents.find((agent) => (agent.domain ?? "").toLowerCase().includes(domain));
+            if (match)
+                addAgent(match);
+        }
+        if (recommendedDomains.length > 0) {
+            assignmentSource = "orchestrator";
+        }
+    }
+    catch (err) {
+        warnings.push(`delegation preflight failed (${input.toErrorMessage(err)})`);
+    }
+    if (byKey.size === 0) {
+        const haystack = `${input.title} ${input.summary ?? ""}`.toLowerCase();
+        const domainHints = [];
+        if (/market|campaign|thread|article|tweet|copy/.test(haystack)) {
+            domainHints.push("marketing");
+        }
+        else if (/design|ux|ui|a11y/.test(haystack)) {
+            domainHints.push("design");
+        }
+        else if (/ops|runbook|incident|reliability/.test(haystack)) {
+            domainHints.push("operations");
+        }
+        else if (/sales|deal|pipeline/.test(haystack)) {
+            domainHints.push("sales");
+        }
+        else {
+            domainHints.push("engineering", "product");
+        }
+        for (const domain of domainHints) {
+            const match = liveAgents.find((agent) => (agent.domain ?? "").toLowerCase().includes(domain));
+            if (match)
+                addAgent(match);
+        }
+    }
+    if (byKey.size === 0 && liveAgents.length > 0) {
+        addAgent(liveAgents[0]);
+        warnings.push("fallback selected first available live agent");
+    }
+    const assignedAgents = Array.from(byKey.values());
+    let updatedEntity = null;
+    try {
+        updatedEntity = (await input.client.updateEntity(input.entityType, input.entityId, {
+            assigned_agent_ids: assignedAgents.map((agent) => agent.id),
+            assigned_agent_names: assignedAgents.map((agent) => agent.name),
+            assignment_source: assignmentSource,
+        }));
+    }
+    catch (err) {
+        warnings.push(`assignment update failed (${input.toErrorMessage(err)})`);
+    }
+    return {
+        assignmentSource,
+        assignedAgents,
+        warnings,
+        updatedEntity,
+    };
+}

package/dist/entity-comment-store.js

@@ -1,7 +1,8 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, } from "node:fs";
+import { existsSync, readFileSync, } 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_COMMENTS_PER_ENTITY = 240;
 const MAX_TOTAL_COMMENTS = 1_500;
 function commentsDir() {
@@ -11,22 +12,7 @@ function commentsFile() {
     return getOrgxPluginConfigPath("entity-comments.json");
 }
 function ensureDir() {
-    const dir = commentsDir();
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    try {
-        chmodSync(dir, 0o700);
-    }
-    catch {
-        // best effort
-    }
-}
-function parseJson(value) {
-    try {
-        return JSON.parse(value);
-    }
-    catch {
-        return null;
-    }
+    ensureStoreDirSync(commentsDir());
 }
 function entityKey(entityType, entityId) {
     return `${entityType.trim().toLowerCase()}:${entityId.trim()}`;
@@ -63,7 +49,7 @@ function readStore() {
             return { updatedAt: new Date().toISOString(), commentsByEntity: {} };
         }
         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(), commentsByEntity: {} };
@@ -180,11 +166,5 @@ export function mergeEntityComments(remote, local) {
     return list;
 }
 export function clearEntityCommentsStore() {
-    const file = commentsFile();
-    try {
-        rmSync(file, { force: true });
-    }
-    catch {
-        // best effort
-    }
+    clearStoreFileSync(commentsFile());
 }

package/dist/hash-utils.d.ts

@@ -0,0 +1,2 @@
+export declare function stableHash(value: string): string;
+export declare function idempotencyKey(parts: Array<string | null | undefined>): string;

package/dist/hash-utils.js

@@ -0,0 +1,12 @@
+import { createHash } from "node:crypto";
+export function stableHash(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function idempotencyKey(parts) {
+    const raw = parts
+        .filter((part) => typeof part === "string" && part.length > 0)
+        .join(":");
+    const cleaned = raw.replace(/[^a-zA-Z0-9:_-]/g, "-").slice(0, 84);
+    const suffix = stableHash(raw).slice(0, 20);
+    return `${cleaned}:${suffix}`.slice(0, 120);
+}

package/dist/http/helpers/activity-headline.d.ts

@@ -0,0 +1,10 @@
+export type ActivityHeadlineSource = "llm" | "heuristic";
+export declare function summarizeActivityHeadline(input: {
+    text: string;
+    title?: string | null;
+    type?: string | null;
+}): Promise<{
+    headline: string;
+    source: ActivityHeadlineSource;
+    model: string | null;
+}>;

package/dist/http/helpers/activity-headline.js

@@ -0,0 +1,192 @@
+import { createHash } from "node:crypto";
+import { pickString } from "./value-utils.js";
+const ACTIVITY_HEADLINE_TIMEOUT_MS = 4_000;
+const ACTIVITY_HEADLINE_CACHE_TTL_MS = 12 * 60 * 60_000;
+const ACTIVITY_HEADLINE_CACHE_MAX = 1_000;
+const ACTIVITY_HEADLINE_MAX_INPUT_CHARS = 8_000;
+const DEFAULT_ACTIVITY_HEADLINE_MODEL = "openai/gpt-4.1-nano";
+const activityHeadlineCache = new Map();
+let resolvedActivitySummaryApiKey;
+function normalizeSpaces(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function stripMarkdownLite(value) {
+    return value
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/`([^`]+)`/g, "$1")
+        .replace(/\*\*([^*]+)\*\*/g, "$1")
+        .replace(/__([^_]+)__/g, "$1")
+        .replace(/\*([^*\n]+)\*/g, "$1")
+        .replace(/_([^_\n]+)_/g, "$1")
+        .replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, "$1")
+        .replace(/^\s{0,3}#{1,6}\s+/gm, "")
+        .replace(/^\s*[-*]\s+/gm, "")
+        .replace(/^\s*\d+\.\s+/gm, "")
+        .replace(/\r\n/g, "\n")
+        .trim();
+}
+function cleanActivityHeadline(value) {
+    const lines = stripMarkdownLite(value)
+        .split("\n")
+        .map((line) => normalizeSpaces(line))
+        .filter((line) => line.length > 0 && !/^\|?[:\-| ]+\|?$/.test(line));
+    const headline = lines[0] ?? "";
+    if (!headline)
+        return "";
+    if (headline.length <= 108)
+        return headline;
+    return `${headline.slice(0, 107).trimEnd()}…`;
+}
+function heuristicActivityHeadline(text, title) {
+    const cleanedText = cleanActivityHeadline(text);
+    if (cleanedText.length > 0)
+        return cleanedText;
+    const cleanedTitle = cleanActivityHeadline(title ?? "");
+    if (cleanedTitle.length > 0)
+        return cleanedTitle;
+    return "Activity update";
+}
+function resolveActivitySummaryApiKey() {
+    if (resolvedActivitySummaryApiKey !== undefined) {
+        return resolvedActivitySummaryApiKey;
+    }
+    const candidates = [
+        process.env.ORGX_ACTIVITY_SUMMARY_API_KEY ?? "",
+        process.env.OPENROUTER_API_KEY ?? "",
+    ];
+    const key = candidates.find((candidate) => candidate.trim().length > 0)?.trim() ?? "";
+    resolvedActivitySummaryApiKey = key || null;
+    return resolvedActivitySummaryApiKey;
+}
+function trimActivityHeadlineCache() {
+    while (activityHeadlineCache.size > ACTIVITY_HEADLINE_CACHE_MAX) {
+        const firstKey = activityHeadlineCache.keys().next().value;
+        if (!firstKey)
+            break;
+        activityHeadlineCache.delete(firstKey);
+    }
+}
+function extractCompletionText(payload) {
+    const choices = payload.choices;
+    if (!Array.isArray(choices) || choices.length === 0)
+        return null;
+    const first = choices[0];
+    if (!first || typeof first !== "object")
+        return null;
+    const firstRecord = first;
+    const message = firstRecord.message;
+    if (message && typeof message === "object") {
+        const content = message.content;
+        if (typeof content === "string") {
+            return content;
+        }
+        if (Array.isArray(content)) {
+            const textParts = content
+                .map((part) => {
+                if (typeof part === "string")
+                    return part;
+                if (!part || typeof part !== "object")
+                    return "";
+                const record = part;
+                return typeof record.text === "string" ? record.text : "";
+            })
+                .filter((part) => part.length > 0);
+            if (textParts.length > 0) {
+                return textParts.join(" ");
+            }
+        }
+    }
+    return pickString(firstRecord, ["text", "content"]);
+}
+export async function summarizeActivityHeadline(input) {
+    const normalizedText = normalizeSpaces(input.text).slice(0, ACTIVITY_HEADLINE_MAX_INPUT_CHARS);
+    const normalizedTitle = normalizeSpaces(input.title ?? "");
+    const normalizedType = normalizeSpaces(input.type ?? "");
+    const heuristic = heuristicActivityHeadline(normalizedText, normalizedTitle);
+    const cacheKey = createHash("sha256")
+        .update(`${normalizedType}\n${normalizedTitle}\n${normalizedText}`)
+        .digest("hex");
+    const cached = activityHeadlineCache.get(cacheKey);
+    if (cached && cached.expiresAt > Date.now()) {
+        return { headline: cached.headline, source: cached.source, model: null };
+    }
+    const apiKey = resolveActivitySummaryApiKey();
+    if (!apiKey) {
+        activityHeadlineCache.set(cacheKey, {
+            headline: heuristic,
+            source: "heuristic",
+            expiresAt: Date.now() + ACTIVITY_HEADLINE_CACHE_TTL_MS,
+        });
+        trimActivityHeadlineCache();
+        return { headline: heuristic, source: "heuristic", model: null };
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), ACTIVITY_HEADLINE_TIMEOUT_MS);
+    const model = process.env.ORGX_ACTIVITY_SUMMARY_MODEL?.trim() || DEFAULT_ACTIVITY_HEADLINE_MODEL;
+    const prompt = [
+        "Create one short activity title for a dashboard header.",
+        "Rules:",
+        "- Max 96 characters.",
+        "- Keep key numbers/status markers (for example: 15 tasks, 0 blocked).",
+        "- No markdown, no quotes, no trailing period unless needed.",
+        "- Prefer plain language over jargon.",
+        "",
+        `Type: ${normalizedType || "activity"}`,
+        normalizedTitle ? `Current title: ${normalizedTitle}` : "",
+        "Full detail:",
+        normalizedText,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    try {
+        const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                model,
+                temperature: 0.1,
+                max_tokens: 48,
+                messages: [
+                    {
+                        role: "system",
+                        content: "You write concise activity headers for operational dashboards. Return only the header text.",
+                    },
+                    {
+                        role: "user",
+                        content: prompt,
+                    },
+                ],
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`headline model request failed (${response.status})`);
+        }
+        const payload = (await response.json());
+        const generated = cleanActivityHeadline(extractCompletionText(payload) ?? "");
+        const headline = generated || heuristic;
+        const source = generated ? "llm" : "heuristic";
+        activityHeadlineCache.set(cacheKey, {
+            headline,
+            source,
+            expiresAt: Date.now() + ACTIVITY_HEADLINE_CACHE_TTL_MS,
+        });
+        trimActivityHeadlineCache();
+        return { headline, source, model };
+    }
+    catch {
+        activityHeadlineCache.set(cacheKey, {
+            headline: heuristic,
+            source: "heuristic",
+            expiresAt: Date.now() + ACTIVITY_HEADLINE_CACHE_TTL_MS,
+        });
+        trimActivityHeadlineCache();
+        return { headline: heuristic, source: "heuristic", model: null };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/http/helpers/artifact-fallback.d.ts

@@ -0,0 +1,13 @@
+import type { LiveActivityItem } from "../../types.js";
+type ListActivityPageResult = {
+    activities: LiveActivityItem[];
+    nextCursor: string | null;
+};
+type BuildArtifactFallbackDeps = {
+    listActivityPage: (input: {
+        limit: number;
+        cursor: string | null;
+    }) => ListActivityPageResult;
+};
+export declare function createLocalArtifactDetailFallbackBuilder(deps: BuildArtifactFallbackDeps): (artifactId: string, warning: string) => Record<string, unknown> | null;
+export {};