@wowok/agent-mcp 2.3.13 → 2.3.16

package/dist/harness/plan.js

@@ -0,0 +1,252 @@
+export const SCENARIO_REGISTRY = [
+    {
+        name: "freelance",
+        keywords: ["freelance", "service", "deliverable", "client", "gig", "consult", "design", "develop"],
+        description: "Service delivery with escrow: publish → order → deliver → accept → withdraw",
+        default_permissions: { provider: 1000, customer: "namedOperator", arbiter: 1500 },
+        objects: [
+            { type: "Permission", reversible: true, dependencies: [], user_decisions: ["reuse existing or create new?"], estimated_time: "2min" },
+            { type: "Service", reversible: true, dependencies: ["Permission"], user_decisions: ["name", "description", "token_type"], estimated_time: "3min" },
+            { type: "Machine", reversible: true, dependencies: ["Service"], user_decisions: ["state graph", "operators"], estimated_time: "10min" },
+            { type: "Guard", reversible: false, dependencies: ["Machine"], user_decisions: ["guard table", "submission fields"], risk_flags: ["immutable_after_creation"], estimated_time: "5min" },
+            { type: "Guard", reversible: false, dependencies: ["Machine"], user_decisions: ["refund guard"], risk_flags: ["immutable_after_creation"], estimated_time: "5min" },
+            { type: "Allocation", reversible: true, dependencies: ["Service", "Guard"], user_decisions: ["sharing ratios", "allocators"], estimated_time: "5min" },
+        ],
+        phases: [
+            { name: "Foundation", object_types: ["Permission", "Service"] },
+            { name: "Business Logic", object_types: ["Machine"] },
+            { name: "Trust Layer", object_types: ["Guard"] },
+            { name: "Revenue", object_types: ["Allocation"] },
+            { name: "Publish", object_types: ["Service"] },
+        ],
+    },
+    {
+        name: "rental",
+        keywords: ["rent", "rental", "lease", "property", "item", "deposit", "tenant", "landlord"],
+        description: "Item rental with deposit: publish → rent → inspect → return/refund",
+        default_permissions: { provider: 1000, customer: "namedOperator", arbiter: 1500 },
+        objects: [
+            { type: "Permission", reversible: true, dependencies: [], user_decisions: ["reuse existing or create new?"], estimated_time: "2min" },
+            { type: "Service", reversible: true, dependencies: ["Permission"], user_decisions: ["name", "deposit amount", "rental terms"], estimated_time: "3min" },
+            { type: "Machine", reversible: true, dependencies: ["Service"], user_decisions: ["rental states", "return/inspect flow"], estimated_time: "10min" },
+            { type: "Guard", reversible: false, dependencies: ["Machine"], user_decisions: ["return guard", "damage guard"], risk_flags: ["immutable_after_creation"], estimated_time: "5min" },
+            { type: "Guard", reversible: false, dependencies: ["Machine"], user_decisions: ["refund guard"], risk_flags: ["immutable_after_creation"], estimated_time: "5min" },
+            { type: "Allocation", reversible: true, dependencies: ["Service", "Guard"], user_decisions: ["deposit/refund allocation", "damage compensation"], estimated_time: "5min" },
+        ],
+        phases: [
+            { name: "Foundation", object_types: ["Permission", "Service"] },
+            { name: "Business Logic", object_types: ["Machine"] },
+            { name: "Trust Layer", object_types: ["Guard"] },
+            { name: "Revenue", object_types: ["Allocation"] },
+            { name: "Publish", object_types: ["Service"] },
+        ],
+    },
+    {
+        name: "digital_goods",
+        keywords: ["digital", "download", "ebook", "software", "license", "instant", "content"],
+        description: "Instant digital delivery: publish → buy → instant delivery",
+        default_permissions: { provider: 1000, customer: "namedOperator" },
+        objects: [
+            { type: "Permission", reversible: true, dependencies: [], estimated_time: "2min" },
+            { type: "Service", reversible: true, dependencies: ["Permission"], user_decisions: ["name", "price", "delivery method"], estimated_time: "3min" },
+            { type: "Machine", reversible: true, dependencies: ["Service"], user_decisions: ["instant delivery states"], estimated_time: "5min" },
+            { type: "Allocation", reversible: true, dependencies: ["Service"], user_decisions: ["revenue split"], estimated_time: "3min" },
+        ],
+        phases: [
+            { name: "Foundation", object_types: ["Permission", "Service"] },
+            { name: "Business Logic", object_types: ["Machine"] },
+            { name: "Revenue", object_types: ["Allocation"] },
+            { name: "Publish", object_types: ["Service"] },
+        ],
+    },
+    {
+        name: "travel_package",
+        keywords: ["travel", "tour", "trip", "package", "booking", "itinerary", "vacation", "hotel"],
+        description: "Multi-stage service with milestones: publish → book → itinerary → complete",
+        default_permissions: { provider: 1000, customer: "namedOperator", arbiter: 1500 },
+        objects: [
+            { type: "Permission", reversible: true, dependencies: [], estimated_time: "2min" },
+            { type: "Service", reversible: true, dependencies: ["Permission"], user_decisions: ["name", "package details", "pricing tiers"], estimated_time: "5min" },
+            { type: "Machine", reversible: true, dependencies: ["Service"], user_decisions: ["booking states", "milestone flow", "cancellation"], estimated_time: "15min" },
+            { type: "Guard", reversible: false, dependencies: ["Machine"], user_decisions: ["booking guard", "cancellation guard"], risk_flags: ["immutable_after_creation"], estimated_time: "5min" },
+            { type: "Allocation", reversible: true, dependencies: ["Service", "Guard"], user_decisions: ["milestone payments", "refund policy"], estimated_time: "5min" },
+        ],
+        phases: [
+            { name: "Foundation", object_types: ["Permission", "Service"] },
+            { name: "Business Logic", object_types: ["Machine"] },
+            { name: "Trust Layer", object_types: ["Guard"] },
+            { name: "Revenue", object_types: ["Allocation"] },
+            { name: "Publish", object_types: ["Service"] },
+        ],
+    },
+    {
+        name: "general",
+        keywords: [],
+        description: "Fallback for unmatched scenarios — generic service template",
+        default_permissions: { provider: 1000, customer: "namedOperator" },
+        objects: [
+            { type: "Permission", reversible: true, dependencies: [], estimated_time: "2min" },
+            { type: "Service", reversible: true, dependencies: ["Permission"], user_decisions: ["name", "description", "token_type"], estimated_time: "3min" },
+            { type: "Machine", reversible: true, dependencies: ["Service"], user_decisions: ["state graph"], estimated_time: "10min" },
+            { type: "Guard", reversible: false, dependencies: ["Machine"], user_decisions: ["guard requirements"], risk_flags: ["immutable_after_creation"], estimated_time: "5min" },
+            { type: "Allocation", reversible: true, dependencies: ["Service"], user_decisions: ["sharing"], estimated_time: "5min" },
+        ],
+        phases: [
+            { name: "Foundation", object_types: ["Permission", "Service"] },
+            { name: "Business Logic", object_types: ["Machine"] },
+            { name: "Trust Layer", object_types: ["Guard"] },
+            { name: "Revenue", object_types: ["Allocation"] },
+            { name: "Publish", object_types: ["Service"] },
+        ],
+    },
+];
+export function classifyIntent(userInput) {
+    const lower = userInput.toLowerCase();
+    let bestMatch = null;
+    let bestScore = 0;
+    let matchedKeywords = [];
+    for (const scenario of SCENARIO_REGISTRY) {
+        if (scenario.keywords.length === 0)
+            continue;
+        const hits = scenario.keywords.filter((kw) => lower.includes(kw));
+        if (hits.length > bestScore) {
+            bestScore = hits.length;
+            bestMatch = scenario;
+            matchedKeywords = hits;
+        }
+    }
+    if (bestMatch && bestScore > 0) {
+        const confidence = Math.min(bestScore / 3, 1.0);
+        return {
+            scenario: bestMatch.name,
+            matched_keywords: matchedKeywords,
+            confidence,
+            fallback: false,
+        };
+    }
+    return {
+        scenario: "general",
+        matched_keywords: [],
+        confidence: 0.3,
+        fallback: true,
+    };
+}
+let nodeIdCounter = 0;
+function nextNodeId(type) {
+    nodeIdCounter++;
+    return `${type.toLowerCase()}_${nodeIdCounter}`;
+}
+export function generateODG(userInput, taskId) {
+    const classification = classifyIntent(userInput);
+    const template = SCENARIO_REGISTRY.find((s) => s.name === classification.scenario) ?? SCENARIO_REGISTRY[SCENARIO_REGISTRY.length - 1];
+    const objects = template.objects.map((obj) => ({
+        id: nextNodeId(obj.type),
+        type: obj.type,
+        status: "not_created",
+        reversible: obj.reversible,
+        dependencies: [],
+        user_decisions: obj.user_decisions,
+        risk_flags: obj.risk_flags,
+        estimated_time: obj.estimated_time,
+    }));
+    const typeToLatestId = new Map();
+    for (const obj of objects) {
+        const depTypes = template.objects.find((t) => t.type === obj.type)?.dependencies ?? [];
+        obj.dependencies = depTypes
+            .map((depType) => typeToLatestId.get(depType))
+            .filter((id) => id !== undefined);
+        typeToLatestId.set(obj.type, obj.id);
+    }
+    const phases = template.phases.map((phase) => {
+        const phaseObjectIds = objects
+            .filter((obj) => phase.object_types.includes(obj.type))
+            .map((obj) => obj.id);
+        return { name: phase.name, objects: phaseObjectIds };
+    });
+    return {
+        task_id: taskId ?? `task_${Date.now()}`,
+        scenario: classification.scenario,
+        objects,
+        phases,
+    };
+}
+export function identifyDecisionPoints(odg) {
+    const decisions = [];
+    const scenario = SCENARIO_REGISTRY.find((s) => s.name === odg.scenario);
+    decisions.push({
+        round: "R1",
+        question: `I've classified your intent as "${odg.scenario}". Is this correct?`,
+        options: ["Yes, correct", "No, let me clarify"],
+    });
+    decisions.push({
+        round: "R2",
+        question: "Do you have existing Permission objects to reuse, or should I create a new one?",
+        options: ["Create new", "Reuse existing", "Show me what I have"],
+    });
+    decisions.push({
+        round: "R3",
+        question: "What is the service name, description, and pricing token?",
+        options: ["WOW (default)", "USDT", "USDC", "Custom token"],
+        default: "WOW (default)",
+    });
+    if (scenario?.default_permissions.arbiter) {
+        decisions.push({
+            round: "R4",
+            question: "Permission model: provider=1000, customer uses namedOperator, arbiter=1500. Adjust?",
+            options: ["Use defaults", "Customize"],
+            default: "Use defaults",
+        });
+    }
+    decisions.push({
+        round: "R5",
+        question: "What are the service states and transitions? (entry → states → terminals)",
+        options: ["Use scenario template", "Custom design"],
+    });
+    const guardNodes = odg.objects.filter((o) => o.type === "Guard");
+    if (guardNodes.length > 0) {
+        decisions.push({
+            round: "R6",
+            question: `${guardNodes.length} Guard(s) needed. What should each Guard verify?`,
+            options: ["Withdrawal guard", "Refund guard", "Delivery guard", "Custom"],
+        });
+    }
+    decisions.push({
+        round: "R7",
+        question: "How should revenue be split? (e.g., merchant 80%, platform 20%)",
+        options: ["100% to merchant", "80/20 split", "Custom split"],
+        default: "100% to merchant",
+    });
+    return decisions;
+}
+export function detectCycles(odg) {
+    const visited = new Set();
+    const stack = new Set();
+    const cycleNodes = [];
+    function dfs(nodeId, path) {
+        if (stack.has(nodeId)) {
+            const cycleStart = path.indexOf(nodeId);
+            cycleNodes.push(...path.slice(cycleStart), nodeId);
+            return true;
+        }
+        if (visited.has(nodeId))
+            return false;
+        visited.add(nodeId);
+        stack.add(nodeId);
+        const node = odg.objects.find((o) => o.id === nodeId);
+        if (node) {
+            for (const dep of node.dependencies) {
+                if (dfs(dep, [...path, nodeId]))
+                    return true;
+            }
+        }
+        stack.delete(nodeId);
+        return false;
+    }
+    for (const obj of odg.objects) {
+        if (!visited.has(obj.id)) {
+            if (dfs(obj.id, []))
+                return cycleNodes;
+        }
+    }
+    return null;
+}

package/dist/harness/recover.d.ts

@@ -0,0 +1,17 @@
+import type { RecoveryAction, RecoveryStrategy } from "./types.js";
+export interface RecoveryRule {
+    error_code: string;
+    strategy: RecoveryStrategy;
+    max_attempts: number;
+    automation: "full" | "semi" | "manual";
+    detail: string;
+    user_prompt?: string;
+    adjusted_params?: Record<string, unknown>;
+}
+export declare const RECOVERY_RULES: Record<string, RecoveryRule>;
+export declare function resetAttempts(operationId: string): void;
+export declare function recover(errorCode: string, operationId: string, context?: {
+    operation_type?: string;
+    data?: Record<string, unknown>;
+}): RecoveryAction;
+export declare function getBackoffDelay(attempt: number): number;

package/dist/harness/recover.js

@@ -0,0 +1,139 @@
+export const RECOVERY_RULES = {
+    insufficient_balance: {
+        error_code: "insufficient_balance",
+        strategy: "claim_faucet",
+        max_attempts: 3,
+        automation: "semi",
+        detail: "1. Claim faucet tokens (testnet) 2. Prompt user to top up (mainnet) 3. Retry original operation",
+        user_prompt: "Insufficient balance for gas or operation. On testnet, claim faucet tokens. On mainnet, please top up your wallet and retry.",
+    },
+    network_error: {
+        error_code: "network_error",
+        strategy: "retry",
+        max_attempts: 5,
+        automation: "full",
+        detail: "Exponential backoff retry: 1s / 2s / 4s / 8s / 16s. Switch RPC node if available.",
+    },
+    guard_rejected: {
+        error_code: "guard_rejected",
+        strategy: "fill_submission",
+        max_attempts: 2,
+        automation: "semi",
+        detail: "1. Parse Guard table structure 2. Prompt user to fill submission fields 3. Resubmit with call_with_submission",
+        user_prompt: "Guard verification rejected. Please fill in the required submission data and resubmit.",
+    },
+    immutable_violation: {
+        error_code: "immutable_violation",
+        strategy: "recreate",
+        max_attempts: 1,
+        automation: "semi",
+        detail: "1. Stop modification attempt 2. Evaluate creating a new object as replacement 3. Re-plan affected phases",
+        user_prompt: "Cannot modify an immutable object. A new object must be created as a replacement. Confirm to proceed with recreation.",
+    },
+    permission_denied: {
+        error_code: "permission_denied",
+        strategy: "switch_account",
+        max_attempts: 2,
+        automation: "semi",
+        detail: "1. Query object's permission_guard 2. List accounts with permission 3. Switch account or prompt user to add permission",
+        user_prompt: "Current account lacks permission for this operation. Switch to an authorized account or update the Permission object.",
+    },
+    object_not_found: {
+        error_code: "object_not_found",
+        strategy: "query_and_retry",
+        max_attempts: 3,
+        automation: "semi",
+        detail: "1. Re-query the object (may be sync delay) 2. If truly absent, search for similar objects 3. Prompt user to reselect",
+        user_prompt: "Referenced object not found. It may be a synchronization delay. Retrying... If the issue persists, please select a valid object.",
+    },
+    state_conflict: {
+        error_code: "state_conflict",
+        strategy: "adjust_params",
+        max_attempts: 2,
+        automation: "full",
+        detail: "1. Query object's current true state 2. Update ODG status annotations 3. Adjust subsequent operations (e.g., skip completed steps)",
+    },
+    invalid_parameter: {
+        error_code: "invalid_parameter",
+        strategy: "adjust_params",
+        max_attempts: 2,
+        automation: "semi",
+        detail: "1. Query the relevant schema 2. Auto-fix obvious errors (e.g., BigInt vs string) 3. If unfixable, prompt user",
+        user_prompt: "Parameter validation failed. Please check the parameter types and values against the schema and retry.",
+    },
+    unknown: {
+        error_code: "unknown",
+        strategy: "escalate_human",
+        max_attempts: 1,
+        automation: "manual",
+        detail: "1. Report full error context to telemetry 2. Escalate to human intervention 3. Flag for Loop Engineering rule addition",
+        user_prompt: "An unclassified error occurred. Please review the error details and contact support if needed. This error has been logged for tool improvement.",
+    },
+};
+const operationAttempts = new Map();
+function getAttemptCount(operationId, errorCode) {
+    const opMap = operationAttempts.get(operationId);
+    if (!opMap)
+        return 0;
+    return opMap.get(errorCode) ?? 0;
+}
+function incrementAttempt(operationId, errorCode) {
+    if (!operationAttempts.has(operationId)) {
+        operationAttempts.set(operationId, new Map());
+    }
+    const opMap = operationAttempts.get(operationId);
+    const current = (opMap.get(errorCode) ?? 0) + 1;
+    opMap.set(errorCode, current);
+    return current;
+}
+function getTotalAttempts(operationId) {
+    const opMap = operationAttempts.get(operationId);
+    if (!opMap)
+        return 0;
+    let total = 0;
+    for (const count of opMap.values())
+        total += count;
+    return total;
+}
+export function resetAttempts(operationId) {
+    operationAttempts.delete(operationId);
+}
+export function recover(errorCode, operationId, context) {
+    const rule = RECOVERY_RULES[errorCode] ?? RECOVERY_RULES.unknown;
+    const TOTAL_RETRY_LIMIT = 5;
+    const totalAttempts = getTotalAttempts(operationId);
+    const typeAttempts = getAttemptCount(operationId, errorCode);
+    if (totalAttempts >= TOTAL_RETRY_LIMIT) {
+        return {
+            strategy: "stop",
+            should_retry: false,
+            max_attempts: TOTAL_RETRY_LIMIT,
+            current_attempt: totalAttempts,
+            detail: `Total retry limit (${TOTAL_RETRY_LIMIT}) reached for operation ${operationId}. Escalating to human intervention.`,
+            user_prompt: "Maximum retry attempts reached. Manual intervention required.",
+        };
+    }
+    if (typeAttempts >= rule.max_attempts) {
+        return {
+            strategy: "escalate_human",
+            should_retry: false,
+            max_attempts: rule.max_attempts,
+            current_attempt: typeAttempts,
+            detail: `Per-error-code retry limit (${rule.max_attempts}) reached for ${errorCode}. Escalating to human.`,
+            user_prompt: `Recovery attempts for ${errorCode} exhausted. Manual intervention required.`,
+        };
+    }
+    const currentAttempt = incrementAttempt(operationId, errorCode);
+    return {
+        strategy: rule.strategy,
+        should_retry: rule.automation === "full" || currentAttempt < rule.max_attempts,
+        max_attempts: rule.max_attempts,
+        current_attempt: currentAttempt,
+        adjusted_params: rule.adjusted_params,
+        user_prompt: rule.user_prompt,
+        detail: rule.detail,
+    };
+}
+export function getBackoffDelay(attempt) {
+    return Math.pow(2, attempt - 1) * 1000;
+}

package/dist/harness/types.d.ts

@@ -0,0 +1,137 @@
+export type ObjectType = "Permission" | "Service" | "Machine" | "Guard" | "Allocation" | "Progress" | "Repository" | "Treasury" | "Reward" | "Demand" | "Order" | "Arbitration" | "Contact" | "Personal" | "Payment";
+export type ObjectStatus = "not_created" | "created_unpublished" | "published" | "failed";
+export interface ODGNode {
+    id: string;
+    type: ObjectType;
+    status: ObjectStatus;
+    reversible: boolean;
+    dependencies: string[];
+    user_decisions?: string[];
+    risk_flags?: string[];
+    estimated_time?: string;
+    address?: string;
+}
+export interface ODGPhase {
+    name: string;
+    objects: string[];
+    description?: string;
+}
+export interface ODG {
+    task_id: string;
+    scenario: string;
+    objects: ODGNode[];
+    phases: ODGPhase[];
+}
+export interface ExpectedObject {
+    role: string;
+    expect_fields?: Record<string, unknown>;
+}
+export interface ExpectedFundFlow {
+    role: string;
+    amount?: string;
+    coinType?: string;
+    from?: string | null;
+    to?: string | null;
+}
+export interface ExpectedEvent {
+    type: string;
+    expect_count?: string;
+}
+export interface ExpectedResult {
+    operation: string;
+    intent: string;
+    pre_conditions: Array<{
+        check: string;
+        error: string;
+    }>;
+    expected: {
+        result_type: "transaction" | "submission" | "error" | "data" | "null";
+        semantic_created?: ExpectedObject[];
+        semantic_modified?: ExpectedObject[];
+        semantic_released?: ExpectedFundFlow[];
+        events?: ExpectedEvent[];
+        state_transition?: {
+            from: string;
+            to: string;
+        };
+    };
+    post_verification?: Array<{
+        tool: string;
+        params: Record<string, unknown>;
+        assert: string;
+    }>;
+}
+export type VerifyStatus = "pass" | "warn" | "fail";
+export interface VerifyMismatch {
+    dimension: "created" | "modified" | "released" | "state" | "event";
+    expected: string;
+    actual: string;
+    severity: VerifyStatus;
+    detail: string;
+}
+export interface VerifyReport {
+    status: VerifyStatus;
+    mismatches: VerifyMismatch[];
+    summary: string;
+    timestamp: string;
+}
+export type RecoveryStrategy = "retry" | "claim_faucet" | "fill_submission" | "recreate" | "switch_account" | "query_and_retry" | "adjust_params" | "escalate_human" | "stop";
+export interface RecoveryAction {
+    strategy: RecoveryStrategy;
+    should_retry: boolean;
+    adjusted_params?: Record<string, unknown>;
+    user_prompt?: string;
+    max_attempts: number;
+    current_attempt: number;
+    detail: string;
+}
+export type PhaseStatus = "in_progress" | "completed" | "failed";
+export interface Checkpoint {
+    checkpoint_id: string;
+    task_id: string;
+    timestamp: string;
+    phase: string;
+    phase_status: PhaseStatus;
+    odg_snapshot: Record<string, {
+        status: ObjectStatus;
+        address?: string;
+        reversible: boolean;
+        tested?: boolean;
+    }>;
+    user_decisions: Record<string, unknown>;
+    operation_log: Array<{
+        op_id: string;
+        tool: string;
+        params?: Record<string, unknown>;
+        result_digest?: string;
+        status: VerifyStatus;
+    }>;
+    next_phase: string;
+    semantic_summary: {
+        total_ops: number;
+        success_ops: number;
+        failed_ops: number;
+        recoveries: number;
+    };
+}
+export interface ScenarioTemplate {
+    name: string;
+    keywords: string[];
+    objects: Array<Omit<ODGNode, "id" | "status" | "address">>;
+    phases: Array<{
+        name: string;
+        object_types: ObjectType[];
+    }>;
+    default_permissions: {
+        provider?: number;
+        customer?: "namedOperator";
+        arbiter?: number;
+    };
+    description: string;
+}
+export interface HarnessContext {
+    odg?: ODG;
+    current_phase?: string;
+    checkpoint?: Checkpoint;
+    user_decisions?: Record<string, unknown>;
+}

package/dist/harness/types.js

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

package/dist/harness/verify.d.ts

@@ -0,0 +1,42 @@
+import type { ExpectedResult, VerifyReport } from "./types.js";
+export interface VerifyInput {
+    expected: ExpectedResult;
+    actual: {
+        result_type?: string;
+        semantic?: {
+            intent?: string;
+            status?: string;
+            summary?: string;
+            created?: Array<{
+                id: string;
+                role: string;
+                immutable?: boolean;
+            }>;
+            modified?: Array<{
+                id: string;
+                role: string;
+            }>;
+            released?: Array<{
+                amount: string;
+                coinType: string;
+                role: string;
+                from?: string | null;
+                to?: string | null;
+            }>;
+            events?: Array<{
+                event_type: string;
+                business_meaning: string;
+                category: string;
+            }>;
+            next_actions?: Array<{
+                action: string;
+                priority: string;
+            }>;
+            warnings?: string[];
+        };
+        error_code?: string;
+        error?: string;
+    };
+}
+export declare function verify(input: VerifyInput): VerifyReport;
+export declare function generateExpected(operation: string, intent: string, operationType: string, data?: Record<string, unknown>): ExpectedResult;