@useorgx/openclaw-plugin 0.4.8 → 0.7.0

package/dist/http/helpers/hash-utils.d.ts

@@ -0,0 +1 @@
+export { idempotencyKey, stableHash } from "../../hash-utils.js";

package/dist/http/helpers/hash-utils.js

@@ -0,0 +1 @@
+export { idempotencyKey, stableHash } from "../../hash-utils.js";

package/dist/http/helpers/kickoff-context.d.ts

@@ -0,0 +1,12 @@
+import type { OrgXClient } from "../../api.js";
+import type { KickoffContext, KickoffContextRequest } from "../../types.js";
+export declare function fetchKickoffContextSafe(client: OrgXClient, payload: KickoffContextRequest): Promise<KickoffContext | null>;
+export declare function renderKickoffMessage(input: {
+    baseMessage: string;
+    kickoff: KickoffContext | null;
+    domain: string | null;
+    requiredSkills: string[];
+}): {
+    message: string;
+    contextHash: string | null;
+};

package/dist/http/helpers/kickoff-context.js

@@ -0,0 +1,228 @@
+function normalizeKickoffContextResponse(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    if (typeof record.context_hash === "string" && record.context_hash.trim().length > 0) {
+        return record;
+    }
+    if (record.ok === true && record.data && typeof record.data === "object") {
+        const data = record.data;
+        if (typeof data.context_hash === "string" && data.context_hash.trim().length > 0) {
+            return data;
+        }
+    }
+    return null;
+}
+export async function fetchKickoffContextSafe(client, payload) {
+    try {
+        const anyClient = client;
+        if (typeof anyClient.getKickoffContext === "function") {
+            const resp = await anyClient.getKickoffContext(payload);
+            return normalizeKickoffContextResponse(resp);
+        }
+        if (typeof anyClient.rawRequest === "function") {
+            const resp = await anyClient.rawRequest("POST", "/api/client/kickoff-context", payload ?? {});
+            return normalizeKickoffContextResponse(resp);
+        }
+    }
+    catch {
+        // best effort: fall back to local kickoff message
+    }
+    return null;
+}
+function normalizeKickoffLines(input) {
+    if (!Array.isArray(input))
+        return [];
+    return input
+        .map((line) => (typeof line === "string" ? line.trim() : ""))
+        .filter((line) => line.length > 0);
+}
+export function renderKickoffMessage(input) {
+    const base = input.baseMessage.trim();
+    const kickoff = input.kickoff;
+    if (!kickoff)
+        return { message: base, contextHash: null };
+    const title = (kickoff.task?.title ??
+        kickoff.workstream?.title ??
+        kickoff.initiative?.title ??
+        "").trim();
+    const overview = (kickoff.overview ?? "").trim();
+    const acceptance = normalizeKickoffLines(kickoff.acceptance_criteria ?? null);
+    const constraints = normalizeKickoffLines(kickoff.constraints ?? null);
+    const risks = normalizeKickoffLines(kickoff.risks ?? null);
+    const reporting = normalizeKickoffLines(kickoff.reporting_expectations ?? null);
+    const decisions = Array.isArray(kickoff.decisions) ? kickoff.decisions : [];
+    const artifacts = Array.isArray(kickoff.artifacts) ? kickoff.artifacts : [];
+    const allow = normalizeKickoffLines(kickoff.tool_scope?.allow ?? null);
+    const deny = normalizeKickoffLines(kickoff.tool_scope?.deny ?? null);
+    const toolNotes = (kickoff.tool_scope?.notes ?? "").trim();
+    const personaVoice = (kickoff.persona?.voice ?? "").trim();
+    const collaborationStyle = (kickoff.persona?.collaboration_style ?? "").trim();
+    const personaDefaults = normalizeKickoffLines(kickoff.persona?.defaults ?? null);
+    const runtimeSettings = kickoff.runtime_settings && typeof kickoff.runtime_settings === "object"
+        ? kickoff.runtime_settings
+        : null;
+    const customRunInstructions = runtimeSettings && typeof runtimeSettings.custom_run_instructions === "string"
+        ? runtimeSettings.custom_run_instructions.trim()
+        : "";
+    const runtimeFlagLines = [
+        runtimeSettings && typeof runtimeSettings.decision_v2_enabled === "boolean"
+            ? `- Decision V2: ${runtimeSettings.decision_v2_enabled ? "enabled" : "disabled"}`
+            : null,
+        runtimeSettings && typeof runtimeSettings.decision_dedupe_enabled === "boolean"
+            ? `- Decision dedupe: ${runtimeSettings.decision_dedupe_enabled ? "enabled" : "disabled"}`
+            : null,
+        runtimeSettings &&
+            typeof runtimeSettings.decision_evidence_required_for_blocking === "boolean"
+            ? `- Blocking evidence required: ${runtimeSettings.decision_evidence_required_for_blocking ? "enabled" : "disabled"}`
+            : null,
+        runtimeSettings &&
+            typeof runtimeSettings.decision_auto_resolve_guarded_enabled === "boolean"
+            ? `- Guarded auto-resolve: ${runtimeSettings.decision_auto_resolve_guarded_enabled ? "enabled" : "disabled"}`
+            : null,
+    ].filter((line) => Boolean(line));
+    const contextHash = kickoff.context_hash?.trim() || null;
+    const schemaVersion = (kickoff.schema_version ?? "").trim();
+    const lines = [];
+    lines.push("# Kickoff");
+    lines.push("");
+    if (title) {
+        lines.push(`## Target`);
+        lines.push(`- ${title}`);
+        lines.push("");
+    }
+    if (overview) {
+        lines.push("## Overview");
+        lines.push(overview);
+        lines.push("");
+    }
+    else if (base) {
+        lines.push("## Objective");
+        lines.push(base);
+        lines.push("");
+    }
+    if (acceptance.length > 0) {
+        lines.push("## Acceptance Criteria");
+        for (const item of acceptance)
+            lines.push(`- ${item}`);
+        lines.push("");
+    }
+    if (constraints.length > 0) {
+        lines.push("## Constraints");
+        for (const item of constraints)
+            lines.push(`- ${item}`);
+        lines.push("");
+    }
+    if (risks.length > 0) {
+        lines.push("## Risks");
+        for (const item of risks)
+            lines.push(`- ${item}`);
+        lines.push("");
+    }
+    if (decisions.length > 0 || artifacts.length > 0) {
+        lines.push("## References");
+        for (const item of decisions) {
+            const decisionTitle = typeof item?.title === "string"
+                ? String(item.title).trim()
+                : "";
+            const id = typeof item?.id === "string" ? String(item.id).trim() : "";
+            const label = decisionTitle || id || "decision";
+            lines.push(`- Decision: ${label}`);
+        }
+        for (const item of artifacts) {
+            const artifactTitle = typeof item?.title === "string"
+                ? String(item.title).trim()
+                : "";
+            const id = typeof item?.id === "string" ? String(item.id).trim() : "";
+            const label = artifactTitle || id || "artifact";
+            lines.push(`- Artifact: ${label}`);
+        }
+        lines.push("");
+    }
+    lines.push("## Operating Mode");
+    if (input.domain)
+        lines.push(`- Domain: ${input.domain}`);
+    if (input.requiredSkills.length > 0) {
+        lines.push(`- Skills: ${input.requiredSkills.join(", ")}`);
+    }
+    lines.push("- Communicate early when blocked. Provide options, tradeoffs, and a recommendation.");
+    lines.push("- Verify before claiming done. Prefer proof (commands/tests) over confidence.");
+    lines.push("");
+    if (runtimeFlagLines.length > 0 || customRunInstructions) {
+        lines.push("## Runtime Settings");
+        for (const line of runtimeFlagLines)
+            lines.push(line);
+        if (customRunInstructions) {
+            lines.push("- Custom run instructions:");
+            lines.push(`  ${customRunInstructions}`);
+        }
+        lines.push("");
+    }
+    if (personaVoice || collaborationStyle || personaDefaults.length > 0) {
+        lines.push("## Behavior");
+        if (personaVoice)
+            lines.push(`- Voice: ${personaVoice}`);
+        if (collaborationStyle)
+            lines.push(`- Collaboration style: ${collaborationStyle}`);
+        for (const item of personaDefaults)
+            lines.push(`- Default: ${item}`);
+        lines.push("");
+    }
+    if (allow.length > 0 || deny.length > 0 || toolNotes) {
+        lines.push("## Tool Scope");
+        if (allow.length > 0)
+            lines.push(`- Allow: ${allow.join(", ")}`);
+        if (deny.length > 0)
+            lines.push(`- Deny: ${deny.join(", ")}`);
+        if (toolNotes)
+            lines.push(`- Notes: ${toolNotes}`);
+        lines.push("");
+    }
+    if (reporting.length > 0) {
+        lines.push("## Reporting");
+        for (const item of reporting)
+            lines.push(`- ${item}`);
+        lines.push("");
+    }
+    const teamContext = kickoff.team_context;
+    if (teamContext) {
+        const completions = Array.isArray(teamContext.recent_completions)
+            ? teamContext.recent_completions.slice(0, 5)
+            : [];
+        const teamDecisions = Array.isArray(teamContext.recent_decisions)
+            ? teamContext.recent_decisions.slice(0, 3)
+            : [];
+        if (completions.length > 0 || teamDecisions.length > 0) {
+            lines.push("## Team Activity");
+            lines.push("Recent work by other agents (for awareness, not direct action):");
+            for (const c of completions) {
+                const outputs = Array.isArray(c.key_outputs) && c.key_outputs.length > 0
+                    ? ` (${c.key_outputs.join(", ")})`
+                    : "";
+                lines.push(`- [${c.domain}] ${c.task_title}: ${c.summary}${outputs}`);
+            }
+            if (teamDecisions.length > 0) {
+                lines.push("");
+                lines.push("Recent decisions:");
+                for (const d of teamDecisions) {
+                    lines.push(`- ${d.title}: ${d.resolution}`);
+                }
+            }
+            lines.push("");
+            lines.push("Reference naturally when relevant. Do not summarize back.");
+            lines.push("");
+        }
+    }
+    if (contextHash || schemaVersion) {
+        lines.push("## Provenance");
+        if (schemaVersion)
+            lines.push(`- kickoff_schema: ${schemaVersion}`);
+        if (contextHash)
+            lines.push(`- kickoff_context_hash: ${contextHash}`);
+        lines.push("");
+    }
+    return {
+        message: lines.join("\n").trimEnd(),
+        contextHash,
+    };
+}

package/dist/http/helpers/llm-client.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+export type LlmSource = "llm" | "heuristic";
+export interface LlmRequest {
+    /** Namespace for cache keys (e.g. "retro", "turn_summary", "classify_status") */
+    taskId: string;
+    systemPrompt: string;
+    userPrompt: string;
+    /** Override default model. Use DEFAULT_GENERATION_MODEL for longer outputs. */
+    model?: string;
+    /** Default 0.1 */
+    temperature?: number;
+    /** Default 128 */
+    maxTokens?: number;
+    /** Default 4000ms */
+    timeoutMs?: number;
+    /** Default 12h. Set 0 to disable caching. */
+    cacheTtlMs?: number;
+}
+export interface LlmResponse<T> {
+    result: T;
+    source: LlmSource;
+    model: string | null;
+}
+export declare function resolveApiKey(): string | null;
+/** Reset cached key (for testing or key rotation). */
+export declare function resetApiKeyCache(): void;
+/**
+ * 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 declare function callLlm(request: LlmRequest, fallback: () => string, parse?: (raw: string) => string | null): Promise<LlmResponse<string>>;
+/**
+ * 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 declare function callLlmJson<T>(request: LlmRequest, parse: (raw: string) => T | null, fallback: () => T): Promise<LlmResponse<T>>;

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;
+}