@wowok/agent-mcp 2.3.13 → 2.3.14

package/dist/harness/checkpoint.d.ts

@@ -0,0 +1,8 @@
+import type { Checkpoint } from "./types.js";
+export declare function saveCheckpoint(cp: Checkpoint): void;
+export declare function loadCheckpoint(taskId: string, checkpointId: string): Checkpoint | null;
+export declare function loadLatestCheckpoint(taskId: string): Checkpoint | null;
+export declare function listCheckpoints(taskId: string): Checkpoint[];
+export declare function listTasks(): string[];
+export declare function deleteCheckpoint(taskId: string, checkpointId: string): void;
+export declare function createCheckpoint(taskId: string, phase: string, phaseStatus: Checkpoint["phase_status"], odgSnapshot: Checkpoint["odg_snapshot"], userDecisions: Record<string, unknown>, operationLog: Checkpoint["operation_log"], nextPhase: string, semanticSummary: Checkpoint["semantic_summary"]): Checkpoint;

package/dist/harness/checkpoint.js

@@ -0,0 +1,129 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync, openSync, closeSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const CHECKPOINT_ROOT = join(homedir(), ".wowok", "checkpoints");
+function getTaskDir(taskId) {
+    return join(CHECKPOINT_ROOT, taskId);
+}
+function getCheckpointPath(taskId, checkpointId) {
+    return join(getTaskDir(taskId), `${checkpointId}.json`);
+}
+function getLatestPath(taskId) {
+    return join(getTaskDir(taskId), "latest.json");
+}
+function acquireLock(filePath) {
+    const lockPath = filePath + ".lock";
+    try {
+        const fd = openSync(lockPath, "wx");
+        closeSync(fd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function releaseLock(filePath) {
+    const lockPath = filePath + ".lock";
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+    }
+}
+export function saveCheckpoint(cp) {
+    const taskDir = getTaskDir(cp.task_id);
+    if (!existsSync(taskDir)) {
+        mkdirSync(taskDir, { recursive: true });
+    }
+    const cpPath = getCheckpointPath(cp.task_id, cp.checkpoint_id);
+    const latestPath = getLatestPath(cp.task_id);
+    if (!acquireLock(cpPath)) {
+        throw new Error(`Cannot acquire lock for checkpoint ${cp.checkpoint_id} — another process may be writing`);
+    }
+    try {
+        writeFileSync(cpPath, JSON.stringify(cp, null, 2), "utf8");
+        writeFileSync(latestPath, JSON.stringify(cp, null, 2), "utf8");
+    }
+    finally {
+        releaseLock(cpPath);
+    }
+}
+export function loadCheckpoint(taskId, checkpointId) {
+    const cpPath = getCheckpointPath(taskId, checkpointId);
+    if (!existsSync(cpPath))
+        return null;
+    try {
+        const raw = readFileSync(cpPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function loadLatestCheckpoint(taskId) {
+    const latestPath = getLatestPath(taskId);
+    if (!existsSync(latestPath))
+        return null;
+    try {
+        const raw = readFileSync(latestPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function listCheckpoints(taskId) {
+    const taskDir = getTaskDir(taskId);
+    if (!existsSync(taskDir))
+        return [];
+    const files = readdirSync(taskDir)
+        .filter((f) => f.endsWith(".json") && f !== "latest.json")
+        .sort();
+    return files
+        .map((f) => {
+        try {
+            const raw = readFileSync(join(taskDir, f), "utf8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((cp) => cp !== null);
+}
+export function listTasks() {
+    if (!existsSync(CHECKPOINT_ROOT))
+        return [];
+    return readdirSync(CHECKPOINT_ROOT, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+}
+export function deleteCheckpoint(taskId, checkpointId) {
+    const cpPath = getCheckpointPath(taskId, checkpointId);
+    if (existsSync(cpPath)) {
+        if (!acquireLock(cpPath)) {
+            throw new Error(`Cannot acquire lock for deletion of ${checkpointId}`);
+        }
+        try {
+            unlinkSync(cpPath);
+        }
+        finally {
+            releaseLock(cpPath);
+        }
+    }
+}
+export function createCheckpoint(taskId, phase, phaseStatus, odgSnapshot, userDecisions, operationLog, nextPhase, semanticSummary) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return {
+        checkpoint_id: `CP-${phase.replace(/\s+/g, "")}-${phaseStatus}-${timestamp}`,
+        task_id: taskId,
+        timestamp: new Date().toISOString(),
+        phase,
+        phase_status: phaseStatus,
+        odg_snapshot: odgSnapshot,
+        user_decisions: userDecisions,
+        operation_log: operationLog,
+        next_phase: nextPhase,
+        semantic_summary: semanticSummary,
+    };
+}

package/dist/harness/index.d.ts

@@ -0,0 +1,33 @@
+export * from "./types.js";
+export * from "./plan.js";
+export * from "./verify.js";
+export * from "./recover.js";
+export * from "./checkpoint.js";
+import type { DecisionPoint } from "./plan.js";
+import type { VerifyInput } from "./verify.js";
+import type { ODG, ExpectedResult, VerifyReport, RecoveryAction, Checkpoint } from "./types.js";
+export declare class Harness {
+    private context;
+    plan(userInput: string, taskId?: string): ODG;
+    classifyIntent(userInput: string): import("./plan.js").IntentClassification;
+    getDecisions(odg: ODG): DecisionPoint[];
+    detectCycles(odg: ODG): string[] | null;
+    getScenarioRegistry(): import("./types.js").ScenarioTemplate[];
+    expect(operation: string, intent: string, operationType: string, data?: Record<string, unknown>): ExpectedResult;
+    verify(input: VerifyInput): VerifyReport;
+    recover(errorCode: string, operationId: string, context?: {
+        operation_type?: string;
+        data?: Record<string, unknown>;
+    }): RecoveryAction;
+    resetRecovery(operationId: string): void;
+    getBackoffDelay(attempt: number): number;
+    getRecoveryRules(): Record<string, import("./recover.js").RecoveryRule>;
+    checkpoint(taskId: string, phase: string, phaseStatus: Checkpoint["phase_status"], odgSnapshot: Checkpoint["odg_snapshot"], userDecisions: Record<string, unknown>, operationLog: Checkpoint["operation_log"], nextPhase: string, semanticSummary: Checkpoint["semantic_summary"]): Checkpoint;
+    loadCheckpoint(taskId: string): Checkpoint | null;
+    listCheckpoints(taskId: string): Checkpoint[];
+    listTasks(): string[];
+    setContext(key: string, value: unknown): void;
+    getContext<T>(key: string): T | undefined;
+}
+export declare function getHarness(): Harness;
+export declare function setHarness(h: Harness): void;

package/dist/harness/index.js

@@ -0,0 +1,75 @@
+export * from "./types.js";
+export * from "./plan.js";
+export * from "./verify.js";
+export * from "./recover.js";
+export * from "./checkpoint.js";
+import { classifyIntent, generateODG, identifyDecisionPoints, detectCycles, SCENARIO_REGISTRY } from "./plan.js";
+import { verify, generateExpected } from "./verify.js";
+import { recover, resetAttempts, getBackoffDelay, RECOVERY_RULES } from "./recover.js";
+import { saveCheckpoint, loadLatestCheckpoint, listCheckpoints, listTasks, createCheckpoint } from "./checkpoint.js";
+export class Harness {
+    context = new Map();
+    plan(userInput, taskId) {
+        return generateODG(userInput, taskId);
+    }
+    classifyIntent(userInput) {
+        return classifyIntent(userInput);
+    }
+    getDecisions(odg) {
+        return identifyDecisionPoints(odg);
+    }
+    detectCycles(odg) {
+        return detectCycles(odg);
+    }
+    getScenarioRegistry() {
+        return SCENARIO_REGISTRY;
+    }
+    expect(operation, intent, operationType, data) {
+        return generateExpected(operation, intent, operationType, data);
+    }
+    verify(input) {
+        return verify(input);
+    }
+    recover(errorCode, operationId, context) {
+        return recover(errorCode, operationId, context);
+    }
+    resetRecovery(operationId) {
+        resetAttempts(operationId);
+    }
+    getBackoffDelay(attempt) {
+        return getBackoffDelay(attempt);
+    }
+    getRecoveryRules() {
+        return RECOVERY_RULES;
+    }
+    checkpoint(taskId, phase, phaseStatus, odgSnapshot, userDecisions, operationLog, nextPhase, semanticSummary) {
+        const cp = createCheckpoint(taskId, phase, phaseStatus, odgSnapshot, userDecisions, operationLog, nextPhase, semanticSummary);
+        saveCheckpoint(cp);
+        return cp;
+    }
+    loadCheckpoint(taskId) {
+        return loadLatestCheckpoint(taskId);
+    }
+    listCheckpoints(taskId) {
+        return listCheckpoints(taskId);
+    }
+    listTasks() {
+        return listTasks();
+    }
+    setContext(key, value) {
+        this.context.set(key, value);
+    }
+    getContext(key) {
+        return this.context.get(key);
+    }
+}
+let singleton = null;
+export function getHarness() {
+    if (!singleton) {
+        singleton = new Harness();
+    }
+    return singleton;
+}
+export function setHarness(h) {
+    singleton = h;
+}

package/dist/harness/plan.d.ts

@@ -0,0 +1,18 @@
+import type { ODG, ScenarioTemplate } from "./types.js";
+export declare const SCENARIO_REGISTRY: ScenarioTemplate[];
+export interface IntentClassification {
+    scenario: string;
+    matched_keywords: string[];
+    confidence: number;
+    fallback: boolean;
+}
+export declare function classifyIntent(userInput: string): IntentClassification;
+export declare function generateODG(userInput: string, taskId?: string): ODG;
+export interface DecisionPoint {
+    round: string;
+    question: string;
+    options: string[];
+    default?: string;
+}
+export declare function identifyDecisionPoints(odg: ODG): DecisionPoint[];
+export declare function detectCycles(odg: ODG): string[] | null;

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