@wowok/agent-mcp 2.6.9 → 2.7.1

package/dist/evaluation/engine.js

@@ -0,0 +1,175 @@
+import { REQUIREMENT_PASS_THRESHOLD, effectiveWeight, isDataSourceEnabled, isRuleEnabled, normalizeInjection, } from "./user-injection.js";
+const LEVELS = [
+    { min: 85, level: "low" },
+    { min: 70, level: "medium_low" },
+    { min: 50, level: "medium_high" },
+    { min: 0, level: "high" },
+];
+export function levelFromScore(score) {
+    for (const l of LEVELS) {
+        if (score >= l.min)
+            return l.level;
+    }
+    return "high";
+}
+function appliesTo(ids, evaluationId) {
+    if (!ids || ids.length === 0)
+        return true;
+    return ids.includes(evaluationId);
+}
+export class EvaluationEngine {
+    static instance = null;
+    dataSources = new Map();
+    rules = new Map();
+    static Instance() {
+        if (!EvaluationEngine.instance) {
+            EvaluationEngine.instance = new EvaluationEngine();
+        }
+        return EvaluationEngine.instance;
+    }
+    registerDataSource(ds) {
+        if (!ds.id || this.dataSources.has(ds.id))
+            return false;
+        this.dataSources.set(ds.id, ds);
+        return true;
+    }
+    unregisterDataSource(id) {
+        return this.dataSources.delete(id);
+    }
+    registerRule(rule) {
+        if (!rule.id || this.rules.has(rule.id))
+            return false;
+        this.rules.set(rule.id, rule);
+        return true;
+    }
+    unregisterRule(id) {
+        return this.rules.delete(id);
+    }
+    getRule(id) {
+        return this.rules.get(id);
+    }
+    listRules() {
+        return Array.from(this.rules.values());
+    }
+    getDataSource(id) {
+        return this.dataSources.get(id);
+    }
+    listDataSources() {
+        return Array.from(this.dataSources.values());
+    }
+    async evaluate(evaluationId, entities, injection) {
+        const inj = normalizeInjection(injection);
+        const ctx = {
+            evaluation_id: evaluationId,
+            entities,
+            facts: {},
+            injection: inj,
+            now: Date.now(),
+        };
+        const trace = [];
+        for (const ds of this.dataSources.values()) {
+            if (!appliesTo(ds.evaluation_ids, evaluationId))
+                continue;
+            if (!isDataSourceEnabled(ds.id, inj)) {
+                trace.push({ kind: "override", id: ds.id, detail: "data source disabled by user override" });
+                continue;
+            }
+            if (ds.isEnabled && !ds.isEnabled(ctx))
+                continue;
+            const extracted = await ds.extract(ctx);
+            Object.assign(ctx.facts, extracted);
+            trace.push({
+                kind: "data_source",
+                id: ds.id,
+                detail: `extracted ${Object.keys(extracted).length} fact(s)`,
+            });
+        }
+        const breakdown = [];
+        const redFlags = [];
+        for (const rule of this.rules.values()) {
+            if (!appliesTo(rule.evaluation_ids, evaluationId))
+                continue;
+            if (!isRuleEnabled(rule.id, inj)) {
+                trace.push({ kind: "override", id: rule.id, detail: "rule disabled by user override" });
+                continue;
+            }
+            if (rule.isEnabled && !rule.isEnabled(ctx))
+                continue;
+            const contribution = rule.evaluate(ctx);
+            if (!contribution)
+                continue;
+            const weight = effectiveWeight(rule, inj);
+            breakdown.push({
+                rule_id: rule.id,
+                dimension: rule.dimension,
+                score: contribution.score,
+                weight,
+                reason: contribution.reason,
+                matched: contribution.matched,
+                mismatched: contribution.mismatched,
+                red_flag: contribution.red_flag,
+            });
+            if (contribution.red_flag) {
+                redFlags.push(contribution.reason ?? `${rule.id} triggered a hard block`);
+            }
+            trace.push({ kind: "rule", id: rule.id, detail: `score=${contribution.score} weight=${weight}` });
+        }
+        const total = aggregateScore(breakdown);
+        let blocked = redFlags.length > 0;
+        for (const req of inj.requirements ?? []) {
+            const item = breakdown.find((b) => b.rule_id === req.rule_id);
+            if (req.condition === "require") {
+                if (!item || item.score < REQUIREMENT_PASS_THRESHOLD || item.red_flag) {
+                    blocked = true;
+                    redFlags.push(req.note ?? `Requirement requires rule '${req.rule_id}' to pass`);
+                }
+            }
+            else if (req.condition === "forbid") {
+                if (item && item.red_flag) {
+                    blocked = true;
+                    redFlags.push(req.note ?? `Requirement forbids rule '${req.rule_id}' from triggering`);
+                }
+            }
+        }
+        const summary = buildSummary(evaluationId, total, breakdown, redFlags, blocked);
+        return {
+            evaluation_id: evaluationId,
+            total,
+            level: levelFromScore(total),
+            breakdown,
+            red_flags: redFlags,
+            blocked,
+            trace,
+            summary,
+        };
+    }
+}
+function aggregateScore(breakdown) {
+    if (breakdown.length === 0)
+        return 0;
+    let weighted = 0;
+    let weightSum = 0;
+    for (const b of breakdown) {
+        weighted += b.score * b.weight;
+        weightSum += b.weight;
+    }
+    if (weightSum <= 0)
+        return 0;
+    return clamp(Math.round(weighted / weightSum), 0, 100);
+}
+function clamp(n, min, max) {
+    return Math.max(min, Math.min(max, n));
+}
+function buildSummary(evaluationId, total, breakdown, redFlags, blocked) {
+    const parts = [`Evaluation '${evaluationId}': score ${total}/100`];
+    if (blocked) {
+        parts.push(`BLOCKED (${redFlags.length} red flag(s))`);
+    }
+    else {
+        parts.push(`${breakdown.length} rule(s) evaluated`);
+    }
+    return parts.join(" — ");
+}
+export function getEvaluationEngine() {
+    return EvaluationEngine.Instance();
+}

package/dist/evaluation/extract.d.ts

@@ -0,0 +1,30 @@
+import type { CapabilityVector } from "./capability.js";
+export interface ServiceExtractInput {
+    object: string;
+    description: string;
+    location: string;
+    sales?: Array<{
+        name?: string;
+        price: number | bigint | string;
+        wip_hash?: string;
+    }>;
+    arbitrations?: string[];
+    compensation_fund?: number | bigint | string;
+    buy_guard?: string | null;
+    machine?: string | null;
+    um?: string | null;
+    bPublished?: boolean;
+    bPaused?: boolean;
+    order_allocators?: unknown;
+    owner?: string;
+}
+export interface DemandExtractInput {
+    object: string;
+    description: string;
+    location: string;
+    rewards?: string[];
+    um?: string | null;
+    owner?: string;
+}
+export declare function extractServiceCapability(input: ServiceExtractInput, overrides?: Partial<CapabilityVector>): CapabilityVector;
+export declare function extractDemandCapability(input: DemandExtractInput, overrides?: Partial<CapabilityVector>): CapabilityVector;

package/dist/evaluation/extract.js

@@ -0,0 +1,115 @@
+import { parseRegion } from "./region.js";
+import { findSimilarIndustries, inferTraitsFromDescription } from "../knowledge/industry-generalizer.js";
+const BUILTIN_SCENARIOS = [
+    "freelance", "rental", "education", "travel", "subscription", "retail",
+];
+function enrichFromDescription(description) {
+    const text = description?.trim();
+    if (!text) {
+        return { industry: "general", industry_confidence: 0, tags: [], keywords: [] };
+    }
+    const { traits, confidence, matched_keywords } = inferTraitsFromDescription(text);
+    const similar = findSimilarIndustries(traits, 3);
+    const top = similar[0];
+    const industry = top && BUILTIN_SCENARIOS.includes(top.industry)
+        ? top.industry
+        : "general";
+    const hasSignal = matched_keywords.length > 0 || (top?.similarity ?? 0) > 0.2;
+    return {
+        industry: hasSignal ? industry : "general",
+        industry_confidence: hasSignal ? Math.max(confidence, top?.similarity ?? 0) : 0,
+        tags: hasSignal ? similar.slice(0, 3).map((s) => s.industry) : [],
+        keywords: matched_keywords,
+    };
+}
+export function extractServiceCapability(input, overrides) {
+    const sales = input.sales ?? [];
+    const prices = sales
+        .map((s) => toBigInt(s.price))
+        .filter((p) => p !== undefined);
+    const arbitrations = input.arbitrations ?? [];
+    const compensation = toBigInt(input.compensation_fund) ?? 0n;
+    const enriched = enrichFromDescription(input.description);
+    const capabilities = {
+        has_arbitration: arbitrations.length > 0,
+        has_refund_path: arbitrations.length > 0 && compensation > 0n,
+        has_milestone_nodes: false,
+        has_compensation_fund: compensation > 0n,
+        has_wip_verification: sales.some((s) => !!s.wip_hash),
+        has_messenger: input.um != null,
+        has_buy_guard: input.buy_guard != null,
+        has_dynamic_pricing: false,
+        is_published: input.bPublished === true,
+        is_paused: input.bPaused === true,
+    };
+    const base = {
+        id: input.object,
+        kind: "service",
+        owner: input.owner ?? "",
+        industry: enriched.industry,
+        industry_confidence: enriched.industry_confidence,
+        region: parseRegion(input.location),
+        price_min: prices.length > 0 ? minBigInt(prices) : undefined,
+        price_max: prices.length > 0 ? maxBigInt(prices) : undefined,
+        token_type: "",
+        ticket_size: "medium",
+        trust_score: 50,
+        reputation_like_ratio: 1,
+        arbitration_independent: false,
+        merchant_history_count: 0,
+        capabilities,
+        tags: enriched.tags,
+        keywords: enriched.keywords,
+    };
+    return { ...base, ...overrides };
+}
+export function extractDemandCapability(input, overrides) {
+    const enriched = enrichFromDescription(input.description);
+    const base = {
+        id: input.object,
+        kind: "demand",
+        owner: input.owner ?? "",
+        industry: enriched.industry,
+        industry_confidence: enriched.industry_confidence,
+        region: parseRegion(input.location),
+        price_min: undefined,
+        price_max: undefined,
+        token_type: "",
+        ticket_size: "medium",
+        trust_score: 50,
+        reputation_like_ratio: 1,
+        arbitration_independent: false,
+        merchant_history_count: 0,
+        capabilities: {
+            has_arbitration: false,
+            has_refund_path: false,
+            has_milestone_nodes: false,
+            has_compensation_fund: false,
+            has_wip_verification: false,
+            has_messenger: input.um != null,
+            has_buy_guard: false,
+            has_dynamic_pricing: false,
+            is_published: true,
+            is_paused: false,
+        },
+        tags: enriched.tags,
+        keywords: enriched.keywords,
+    };
+    return { ...base, ...overrides };
+}
+function toBigInt(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    try {
+        return BigInt(v);
+    }
+    catch {
+        return undefined;
+    }
+}
+function minBigInt(values) {
+    return values.reduce((a, b) => (a < b ? a : b));
+}
+function maxBigInt(values) {
+    return values.reduce((a, b) => (a > b ? a : b));
+}

package/dist/evaluation/gap.d.ts

@@ -0,0 +1,2 @@
+import type { CapabilityGapReport, CapabilityVector } from "./capability.js";
+export declare function summarizeCapabilityGaps(demand: CapabilityVector, service: CapabilityVector): CapabilityGapReport;

package/dist/evaluation/gap.js

@@ -0,0 +1,100 @@
+import { requiredCapabilities } from "./capability.js";
+import { relateRegion } from "./region.js";
+const IMPACT = {
+    has_arbitration: "critical",
+    has_refund_path: "critical",
+    has_compensation_fund: "major",
+    has_wip_verification: "major",
+    has_milestone_nodes: "minor",
+    has_messenger: "minor",
+    has_buy_guard: "minor",
+    has_dynamic_pricing: "minor",
+};
+const SUGGEST = {
+    has_arbitration: "bind an independent Arbitration object to the Service",
+    has_refund_path: "configure a refund path (Arbitration + compensation_fund, or a refund Allocator)",
+    has_compensation_fund: "deposit compensation_fund to cover the order amount",
+    has_wip_verification: "set a wip_hash on the sale to prevent tampering",
+    has_milestone_nodes: "add milestone nodes to the Machine workflow",
+    has_messenger: "bind a Contact (um) to enable Messenger",
+    has_buy_guard: "configure a buy_guard for purchase eligibility",
+    has_dynamic_pricing: "configure discount/dynamic pricing",
+};
+export function summarizeCapabilityGaps(demand, service) {
+    const satisfied = [];
+    const missing = [];
+    for (const k of requiredCapabilities(demand.capabilities)) {
+        const ok = service.capabilities[k];
+        const gap = {
+            dimension: k,
+            requirement: `requires ${k}`,
+            provided: ok ? "provided" : "missing",
+            status: ok ? "satisfied" : "missing",
+            impact: ok ? "minor" : (IMPACT[k] ?? "minor"),
+            suggestion: ok ? "" : (SUGGEST[k] ?? ""),
+        };
+        (ok ? satisfied : missing).push(gap);
+    }
+    if (demand.industry !== "general" && demand.industry !== service.industry) {
+        missing.push({
+            dimension: "industry",
+            requirement: demand.industry,
+            provided: service.industry,
+            status: "missing",
+            impact: "major",
+            suggestion: `switch to a service in the '${demand.industry}' industry`,
+        });
+    }
+    const rel = relateRegion(demand.region, service.region);
+    if (rel === "mismatch") {
+        missing.push({
+            dimension: "region",
+            requirement: demand.region.raw,
+            provided: service.region.raw,
+            status: "missing",
+            impact: "critical",
+            suggestion: "choose a service in a compatible region",
+        });
+    }
+    else if (rel === "overlap") {
+        missing.push({
+            dimension: "region",
+            requirement: demand.region.raw,
+            provided: service.region.raw,
+            status: "partial",
+            impact: "minor",
+            suggestion: "different city in the same province",
+        });
+    }
+    if (demand.price_max !== undefined && service.price_min !== undefined && service.price_min > demand.price_max) {
+        missing.push({
+            dimension: "price",
+            requirement: `≤ ${demand.price_max}`,
+            provided: `${service.price_min}`,
+            status: "missing",
+            impact: "major",
+            suggestion: "negotiate a lower price or raise the budget",
+        });
+    }
+    if (service.trust_score < demand.trust_score) {
+        missing.push({
+            dimension: "trust",
+            requirement: `≥ ${demand.trust_score}`,
+            provided: `${service.trust_score}`,
+            status: "missing",
+            impact: "major",
+            suggestion: "find a more trustworthy merchant or require more safeguards",
+        });
+    }
+    const total = satisfied.length + missing.length;
+    const coverage = total === 0 ? 100 : Math.round((satisfied.length / total) * 100);
+    return {
+        entity_id: service.id,
+        satisfied,
+        missing,
+        coverage_score: coverage,
+        summary: missing.length === 0
+            ? `Service fully covers the demand's requirements (${coverage}/100)`
+            : `${missing.length} requirement(s) unmet (coverage ${coverage}/100): ${missing.map((m) => m.dimension).join(", ")}`,
+    };
+}

package/dist/evaluation/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./types.js";
+export * from "./user-injection.js";
+export * from "./region.js";
+export * from "./capability.js";
+export * from "./extract.js";
+export * from "./gap.js";
+export * from "./composer.js";
+export * from "./node-game.js";
+export * from "./arbitration-game.js";
+export * from "./builtins/index.js";
+export { EvaluationEngine, getEvaluationEngine, levelFromScore } from "./engine.js";

package/dist/evaluation/index.js

@@ -0,0 +1,11 @@
+export * from "./types.js";
+export * from "./user-injection.js";
+export * from "./region.js";
+export * from "./capability.js";
+export * from "./extract.js";
+export * from "./gap.js";
+export * from "./composer.js";
+export * from "./node-game.js";
+export * from "./arbitration-game.js";
+export * from "./builtins/index.js";
+export { EvaluationEngine, getEvaluationEngine, levelFromScore } from "./engine.js";

package/dist/evaluation/node-game.d.ts

@@ -0,0 +1,34 @@
+import type { ExecutionPath, ParticipationPerspective } from "../participation/radar-core.js";
+export interface NodeForwardInput {
+    name: string;
+    to_node: string;
+    execution_path: ExecutionPath;
+    guard?: string;
+    consequence?: string;
+}
+export interface NodeGameInput {
+    current_node: string;
+    perspective: ParticipationPerspective;
+    operable: NodeForwardInput[];
+    waiting_on: Array<{
+        role: string;
+        forwards: string[];
+    }>;
+}
+export interface NodeGameAction {
+    forward: string;
+    to_node: string;
+    execution_path: ExecutionPath;
+    guard?: string;
+    favorability: number;
+    is_optimal: boolean;
+    payoff_note: string;
+    risk: "low" | "medium" | "high";
+}
+export interface NodeGameAdvice {
+    current_node: string;
+    perspective: ParticipationPerspective;
+    actions: NodeGameAction[];
+    summary: string;
+}
+export declare function evaluateNodeGame(input: NodeGameInput): NodeGameAdvice;

package/dist/evaluation/node-game.js

@@ -0,0 +1,57 @@
+export function evaluateNodeGame(input) {
+    const actions = input.operable.map((f) => {
+        const s = scoreForward(f, input.perspective);
+        return {
+            forward: f.name,
+            to_node: f.to_node,
+            execution_path: f.execution_path,
+            guard: f.guard,
+            favorability: s.favorability,
+            is_optimal: false,
+            payoff_note: s.payoff,
+            risk: s.risk,
+        };
+    });
+    actions.sort((a, b) => b.favorability - a.favorability);
+    if (actions.length > 0) {
+        actions[0].is_optimal = true;
+    }
+    return {
+        current_node: input.current_node,
+        perspective: input.perspective,
+        actions,
+        summary: buildSummary(input, actions),
+    };
+}
+function scoreForward(f, perspective) {
+    const isCompletion = !!f.consequence?.startsWith("Completion");
+    const isRefund = !!f.consequence?.startsWith("Refund");
+    if (perspective === "customer") {
+        if (isRefund) {
+            return { favorability: 90, payoff: "funds return to you (refund/cancel path)", risk: "low" };
+        }
+        if (isCompletion) {
+            return { favorability: 40, payoff: "releases escrowed funds to the merchant — only confirm if the deliverable matches the agreement", risk: "high" };
+        }
+        return { favorability: 60, payoff: "advances the order to the next node", risk: "medium" };
+    }
+    if (perspective === "operator") {
+        if (isCompletion) {
+            return { favorability: 90, payoff: "settlement + shorter fund-settlement cycle", risk: "low" };
+        }
+        if (isRefund) {
+            return { favorability: 20, payoff: "refund — downside, recorded on-chain (arb-loss/stall stats)", risk: "high" };
+        }
+        return { favorability: 70, payoff: "advance the workflow to shorten settlement", risk: "low" };
+    }
+    return { favorability: 50, payoff: "neutral (observer)", risk: "medium" };
+}
+function buildSummary(input, actions) {
+    if (actions.length === 0) {
+        return input.waiting_on.length > 0
+            ? `Waiting on ${input.waiting_on.map((w) => w.role).join(", ")}`
+            : `No operable actions at node '${input.current_node || "(entry)"}'`;
+    }
+    const top = actions[0];
+    return `Optimal for ${input.perspective}: '${top.forward}' → '${top.to_node}' (${top.payoff_note})`;
+}

package/dist/evaluation/region.d.ts

@@ -0,0 +1,10 @@
+export interface Region {
+    mode: "remote" | "physical";
+    country?: string;
+    province?: string;
+    city?: string;
+    raw: string;
+}
+export type RegionRelation = "exact" | "contains" | "overlap" | "compatible" | "mismatch";
+export declare function parseRegion(raw: string): Region;
+export declare function relateRegion(a: Region, b: Region): RegionRelation;

package/dist/evaluation/region.js

@@ -0,0 +1,36 @@
+const REMOTE_KEYWORDS = ["remote", "online", "anywhere"];
+export function parseRegion(raw) {
+    const trimmed = raw?.trim() ?? "";
+    const lower = trimmed.toLowerCase();
+    const isRemote = REMOTE_KEYWORDS.some((k) => lower.includes(k));
+    if (isRemote) {
+        return { mode: "remote", raw: trimmed };
+    }
+    return { mode: "physical", raw: trimmed };
+}
+export function relateRegion(a, b) {
+    if (a.mode === "remote" || b.mode === "remote") {
+        return "compatible";
+    }
+    const na = normalizePhysical(a.raw);
+    const nb = normalizePhysical(b.raw);
+    if (!na || !nb) {
+        return "mismatch";
+    }
+    if (na === nb) {
+        return "exact";
+    }
+    if (na.includes(nb) || nb.includes(na)) {
+        return "contains";
+    }
+    if (a.province && b.province && a.province === b.province) {
+        return "overlap";
+    }
+    return "mismatch";
+}
+function normalizePhysical(raw) {
+    return raw
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "");
+}

package/dist/evaluation/types.d.ts

@@ -0,0 +1,76 @@
+export interface DataSource {
+    id: string;
+    description: string;
+    evaluation_ids?: string[];
+    isEnabled?: (ctx: EvaluationContext) => boolean;
+    extract(ctx: EvaluationContext): Promise<Record<string, unknown>> | Record<string, unknown>;
+}
+export interface EvaluationRule {
+    id: string;
+    description: string;
+    dimension: string;
+    weight: number;
+    evaluation_ids?: string[];
+    isEnabled?: (ctx: EvaluationContext) => boolean;
+    evaluate(ctx: EvaluationContext): RuleContribution | null;
+}
+export interface RuleContribution {
+    score: number;
+    weight: number;
+    reason?: string;
+    matched?: string[];
+    mismatched?: string[];
+    red_flag?: boolean;
+}
+export interface UserRequirement {
+    rule_id: string;
+    condition: "require" | "forbid";
+    note?: string;
+}
+export interface UserInjection {
+    intent?: string;
+    preferences?: Record<string, unknown>;
+    requirements?: UserRequirement[];
+    overrides?: {
+        rules?: Record<string, {
+            enabled?: boolean;
+            weight?: number;
+        }>;
+        data_sources?: Record<string, {
+            enabled?: boolean;
+        }>;
+    };
+}
+export interface EvaluationContext {
+    evaluation_id: string;
+    entities: Record<string, unknown>;
+    facts: Record<string, unknown>;
+    injection?: UserInjection;
+    now?: number;
+}
+export type EvaluationLevel = "low" | "medium_low" | "medium_high" | "high";
+export interface EvaluationBreakdown {
+    rule_id: string;
+    dimension: string;
+    score: number;
+    weight: number;
+    reason?: string;
+    matched?: string[];
+    mismatched?: string[];
+    red_flag?: boolean;
+}
+export interface EvaluationTraceEntry {
+    kind: "data_source" | "rule" | "override";
+    id: string;
+    detail: string;
+}
+export interface EvaluationResult {
+    evaluation_id: string;
+    total: number;
+    level: EvaluationLevel;
+    breakdown: EvaluationBreakdown[];
+    red_flags: string[];
+    blocked: boolean;
+    trace: EvaluationTraceEntry[];
+    summary: string;
+}

package/dist/evaluation/types.js

@@ -0,0 +1 @@
+export {};

package/dist/evaluation/user-injection.d.ts

@@ -0,0 +1,6 @@
+import type { EvaluationRule, UserInjection } from "./types.js";
+export declare const REQUIREMENT_PASS_THRESHOLD = 60;
+export declare function normalizeInjection(injection?: UserInjection): UserInjection;
+export declare function isRuleEnabled(ruleId: string, injection?: UserInjection): boolean;
+export declare function isDataSourceEnabled(dataSourceId: string, injection?: UserInjection): boolean;
+export declare function effectiveWeight(rule: EvaluationRule, injection?: UserInjection): number;