@useorgx/openclaw-plugin 0.4.9 → 0.7.0

package/dist/http/helpers/llm-client.js

@@ -0,0 +1,256 @@
+/**
+ * Shared LLM client for classification, summarization, and generation tasks.
+ *
+ * Generalizes the pattern from activity-headline.ts into a reusable client
+ * with in-memory caching, timeout, and heuristic fallback.
+ */
+import { createHash } from "node:crypto";
+import { pickString } from "./value-utils.js";
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const DEFAULT_MODEL = "openai/gpt-4.1-nano";
+const DEFAULT_GENERATION_MODEL = "openai/gpt-4.1-mini";
+const DEFAULT_TIMEOUT_MS = 4_000;
+const DEFAULT_CACHE_TTL_MS = 12 * 60 * 60_000; // 12 hours
+const CACHE_MAX_ENTRIES = 2_000;
+const OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions";
+const cache = new Map();
+function cacheKey(taskId, content) {
+    return `${taskId}:${createHash("sha256").update(content).digest("hex")}`;
+}
+function trimCache() {
+    while (cache.size > CACHE_MAX_ENTRIES) {
+        const firstKey = cache.keys().next().value;
+        if (!firstKey)
+            break;
+        cache.delete(firstKey);
+    }
+}
+function getCached(key) {
+    const entry = cache.get(key);
+    if (entry && entry.expiresAt > Date.now())
+        return entry;
+    if (entry)
+        cache.delete(key);
+    return null;
+}
+function setCached(key, value, source, ttlMs) {
+    if (ttlMs <= 0)
+        return;
+    cache.set(key, { value, source, expiresAt: Date.now() + ttlMs });
+    trimCache();
+}
+// ---------------------------------------------------------------------------
+// API key resolution
+// ---------------------------------------------------------------------------
+let resolvedApiKey;
+export function resolveApiKey() {
+    if (resolvedApiKey !== undefined)
+        return resolvedApiKey;
+    const candidates = [
+        process.env.ORGX_LLM_API_KEY ?? "",
+        process.env.ORGX_ACTIVITY_SUMMARY_API_KEY ?? "",
+        process.env.OPENROUTER_API_KEY ?? "",
+    ];
+    const key = candidates.find((c) => c.trim().length > 0)?.trim() ?? "";
+    resolvedApiKey = key || null;
+    return resolvedApiKey;
+}
+/** Reset cached key (for testing or key rotation). */
+export function resetApiKeyCache() {
+    resolvedApiKey = undefined;
+}
+// ---------------------------------------------------------------------------
+// OpenRouter completion
+// ---------------------------------------------------------------------------
+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"]);
+}
+// ---------------------------------------------------------------------------
+// Public API: text completion
+// ---------------------------------------------------------------------------
+/**
+ * Call LLM for a text completion with automatic caching and heuristic fallback.
+ *
+ * @param request - The LLM request configuration
+ * @param fallback - Heuristic fallback that produces a result when LLM is unavailable
+ * @param parse - Optional transform on the raw LLM text (default: identity)
+ */
+export async function callLlm(request, fallback, parse) {
+    const ttl = request.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    const key = cacheKey(request.taskId, `${request.systemPrompt}\n${request.userPrompt}`);
+    const cached = getCached(key);
+    if (cached) {
+        return { result: cached.value, source: cached.source, model: null };
+    }
+    const apiKey = resolveApiKey();
+    if (!apiKey) {
+        const heuristic = fallback();
+        setCached(key, heuristic, "heuristic", ttl);
+        return { result: heuristic, source: "heuristic", model: null };
+    }
+    const model = process.env.ORGX_LLM_MODEL?.trim() || request.model || DEFAULT_MODEL;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), request.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        const response = await fetch(OPENROUTER_URL, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                model,
+                temperature: request.temperature ?? 0.1,
+                max_tokens: request.maxTokens ?? 128,
+                messages: [
+                    { role: "system", content: request.systemPrompt },
+                    { role: "user", content: request.userPrompt },
+                ],
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`LLM request failed (${response.status})`);
+        }
+        const payload = (await response.json());
+        const raw = extractCompletionText(payload) ?? "";
+        const parsed = parse ? parse(raw) : raw.trim();
+        if (parsed && parsed.length > 0) {
+            setCached(key, parsed, "llm", ttl);
+            return { result: parsed, source: "llm", model };
+        }
+        const heuristic = fallback();
+        setCached(key, heuristic, "heuristic", ttl);
+        return { result: heuristic, source: "heuristic", model };
+    }
+    catch {
+        const heuristic = fallback();
+        setCached(key, heuristic, "heuristic", ttl);
+        return { result: heuristic, source: "heuristic", model: null };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API: JSON-structured completion
+// ---------------------------------------------------------------------------
+/**
+ * Call LLM expecting a JSON response. Parses and validates via the provided parser.
+ *
+ * @param request - The LLM request (systemPrompt should instruct JSON output)
+ * @param parse - Parse raw JSON string into typed result, return null on failure
+ * @param fallback - Heuristic fallback
+ */
+export async function callLlmJson(request, parse, fallback) {
+    const ttl = request.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    const key = cacheKey(request.taskId, `${request.systemPrompt}\n${request.userPrompt}`);
+    const cached = getCached(key);
+    if (cached) {
+        const parsed = parse(cached.value);
+        if (parsed !== null) {
+            return { result: parsed, source: cached.source, model: null };
+        }
+    }
+    const apiKey = resolveApiKey();
+    if (!apiKey) {
+        const heuristic = fallback();
+        return { result: heuristic, source: "heuristic", model: null };
+    }
+    const model = process.env.ORGX_LLM_MODEL?.trim() || request.model || DEFAULT_GENERATION_MODEL;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), request.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        const response = await fetch(OPENROUTER_URL, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                model,
+                temperature: request.temperature ?? 0.1,
+                max_tokens: request.maxTokens ?? 512,
+                messages: [
+                    { role: "system", content: request.systemPrompt },
+                    { role: "user", content: request.userPrompt },
+                ],
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`LLM request failed (${response.status})`);
+        }
+        const payload = (await response.json());
+        const raw = extractCompletionText(payload) ?? "";
+        // Try to extract JSON from markdown fences or raw text
+        const jsonStr = extractJsonFromText(raw);
+        const parsed = parse(jsonStr);
+        if (parsed !== null) {
+            setCached(key, jsonStr, "llm", ttl);
+            return { result: parsed, source: "llm", model };
+        }
+        return { result: fallback(), source: "heuristic", model };
+    }
+    catch {
+        return { result: fallback(), source: "heuristic", model: null };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function extractJsonFromText(text) {
+    const trimmed = text.trim();
+    // Try markdown JSON fence
+    const fenceMatch = trimmed.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+    if (fenceMatch?.[1])
+        return fenceMatch[1].trim();
+    // Try raw JSON (starts with { or [)
+    if (trimmed.startsWith("{") || trimmed.startsWith("["))
+        return trimmed;
+    // Try to find JSON embedded in text
+    const jsonStart = trimmed.indexOf("{");
+    if (jsonStart >= 0) {
+        const candidate = trimmed.slice(jsonStart);
+        try {
+            JSON.parse(candidate);
+            return candidate;
+        }
+        catch {
+            // fall through
+        }
+    }
+    return trimmed;
+}

package/dist/http/helpers/mission-control.d.ts

@@ -23,6 +23,19 @@ export interface MissionControlNode {
     expectedDurationHours: number;
     expectedBudgetUsd: number;
     assignedAgents: MissionControlAssignedAgent[];
+    behaviorConfigId?: string | null;
+    behaviorConfigVersion?: string | null;
+    behaviorConfigHash?: string | null;
+    behaviorPolicySource?: string | null;
+    behaviorContext?: string | null;
+    behaviorRequiresApproval?: boolean | null;
+    behaviorApprovalStatus?: string | null;
+    behaviorApprovalDecisionId?: string | null;
+    behaviorAutomationLevel?: "auto" | "supervised" | "manual" | null;
+    sliceScopePreference?: "adaptive" | "task" | "milestone" | "workstream" | null;
+    maxSliceTasks?: number | null;
+    maxParallelAgents?: number | null;
+    dependencyMode?: "strict" | "relaxed" | null;
     updatedAt: string | null;
 }
 export interface MissionControlEdge {
@@ -30,6 +43,33 @@ export interface MissionControlEdge {
     to: string;
     kind: "depends_on";
 }
+export interface MissionControlCycleDiagnostics {
+    detected: boolean;
+    cycleEdgeCount: number;
+    removedEdges: Array<{
+        from: string;
+        to: string;
+    }>;
+    affectedNodes: Array<{
+        nodeId: string;
+        nodeType: MissionControlNodeType;
+        removedDependencyIds: string[];
+        remainingDependencyIds: string[];
+    }>;
+}
+export type SliceScope = "task" | "milestone" | "workstream";
+export type SliceScopePreference = "adaptive" | SliceScope;
+export interface MissionControlExecutionPolicy {
+    domain: string;
+    requiredSkills: string[];
+    profile?: string | null;
+    sliceScopePreference?: SliceScopePreference | null;
+    maxSliceTasks?: number | null;
+    maxParallelAgents?: number | null;
+    dependencyMode?: "strict" | "relaxed" | null;
+}
+export declare const SLICE_SCOPE_MAX_TASKS: Record<SliceScope, number>;
+export declare const SLICE_SCOPE_TIMEOUT_MULTIPLIER: Record<SliceScope, number>;
 export declare const ORGX_SKILL_BY_DOMAIN: Record<string, string>;
 interface BudgetEnvBounds {
     min?: number;
@@ -67,6 +107,7 @@ export declare function buildMissionControlGraph(client: OrgXClient, initiativeI
     edges: MissionControlEdge[];
     recentTodos: string[];
     degraded: string[];
+    cycleDiagnostics?: MissionControlCycleDiagnostics;
 }>;
 export declare function normalizeEntityMutationPayload(payload: Record<string, unknown>): Record<string, unknown>;
 export declare function resolveAutoAssignments(input: {
@@ -85,10 +126,68 @@ export declare function resolveAutoAssignments(input: {
 }>;
 export declare function normalizeExecutionDomain(value: string | null | undefined): string | null;
 export declare function inferExecutionDomainFromText(...values: Array<string | null | undefined>): string;
-export declare function deriveExecutionPolicy(taskNode: MissionControlNode, workstreamNode: MissionControlNode | null): {
-    domain: string;
-    requiredSkills: string[];
+export declare function selectSliceTasksByScope(input: {
+    scope: SliceScope;
+    workstreamId: string;
+    milestoneId?: string | null;
+    recentTodos: string[];
+    nodeById: Map<string, MissionControlNode>;
+    includeVerification: boolean;
+}): {
+    tasks: MissionControlNode[];
+    milestoneIds: string[];
+};
+export declare function evaluateScopeCompletion(input: {
+    scope: SliceScope;
+    milestoneIds: string[];
+    workstreamId: string;
+    nodeById: Map<string, MissionControlNode>;
+}): {
+    scopeComplete: boolean;
+    remainingTasks: number;
+};
+export declare function deriveExecutionPolicy(taskNode: MissionControlNode, workstreamNode: MissionControlNode | null): MissionControlExecutionPolicy;
+export declare function deriveBehaviorConfigContext(taskNode: MissionControlNode, workstreamNode: MissionControlNode | null): {
+    configId: string | null;
+    version: string | null;
+    hash: string | null;
+    policySource: string | null;
+    context: string | null;
+    requiresApproval: boolean;
+    approvalStatus: string | null;
+    approvalDecisionId: string | null;
 };
+export declare function deriveBehaviorAutomationLevel(taskNode: MissionControlNode, workstreamNode: MissionControlNode | null): "auto" | "supervised" | "manual";
+export declare function detectBehaviorConfigDrift(input: {
+    taskNode: MissionControlNode;
+    workstreamNode: MissionControlNode | null;
+    behaviorConfig: {
+        configId: string | null;
+        version: string | null;
+        hash: string | null;
+        policySource: string | null;
+        context: string | null;
+    };
+    behaviorAutomationLevel: "auto" | "supervised" | "manual";
+}): {
+    fields: Array<"config_id" | "version" | "hash" | "policy_source" | "context" | "automation_level">;
+    declared: {
+        configId: string | null;
+        version: string | null;
+        hash: string | null;
+        policySource: string | null;
+        context: string | null;
+        automationLevel: "auto" | "supervised" | "manual" | null;
+    };
+    runtime: {
+        configId: string | null;
+        version: string | null;
+        hash: string | null;
+        policySource: string | null;
+        context: string | null;
+        automationLevel: "auto" | "supervised" | "manual";
+    };
+} | null;
 export declare function spawnGuardIsRateLimited(result: unknown): boolean;
 export declare function summarizeSpawnGuardBlockReason(result: unknown): string;
 export {};