site-agent-pro 1.0.0

package/dist/submissions/model.js

@@ -0,0 +1,56 @@
+import crypto from "node:crypto";
+import { config } from "../config.js";
+import { buildDefaultTradeRunOptions } from "../trade/policy.js";
+import { SubmissionSchema } from "./types.js";
+import { buildInitialAgentRuns } from "../core/agentProfiles.js";
+import { buildCustomTaskSuite } from "../core/customTaskSuite.js";
+import { normalizeCustomTasks, SUBMISSION_TASKS_REQUIRED_MESSAGE } from "./customTasks.js";
+export function computeExpiresAt(createdAt) {
+    const createdMs = new Date(createdAt).getTime();
+    return new Date(createdMs + config.reportTtlDays * 24 * 60 * 60 * 1000).toISOString();
+}
+export function isExpired(expiresAt, now = Date.now()) {
+    return new Date(expiresAt).getTime() <= now;
+}
+export function createSubmissionRecord(args) {
+    const createdAt = new Date().toISOString();
+    const id = crypto.randomUUID();
+    const reportToken = crypto.randomBytes(18).toString("base64url");
+    const agentCount = Math.min(5, Math.max(1, Math.round(args.agentCount ?? args.agentRuns?.length ?? 1)));
+    const customTasks = normalizeCustomTasks(args.customTasks ?? []);
+    if (customTasks.length === 0) {
+        throw new Error(SUBMISSION_TASKS_REQUIRED_MESSAGE);
+    }
+    const customSuite = buildCustomTaskSuite(customTasks);
+    const agentRuns = args.agentRuns ?? buildInitialAgentRuns(agentCount, customSuite);
+    return SubmissionSchema.parse({
+        id,
+        url: args.url,
+        createdAt,
+        startedAt: null,
+        completedAt: null,
+        expiresAt: computeExpiresAt(createdAt),
+        status: "queued",
+        reportToken,
+        publicReportPath: `/r/${reportToken}`,
+        headed: Boolean(args.headed),
+        mobile: Boolean(args.mobile),
+        ignoreHttpsErrors: Boolean(args.ignoreHttpsErrors),
+        tradeOptions: {
+            ...buildDefaultTradeRunOptions(),
+            ...(args.tradeOptions ?? {})
+        },
+        customTasks,
+        instructionText: args.instructionText?.trim() || customTasks.join("\n"),
+        instructionFileName: args.instructionFileName?.trim() || null,
+        agentCount,
+        completedAgentCount: 0,
+        failedAgentCount: 0,
+        agentRuns,
+        runId: null,
+        runDir: null,
+        error: null,
+        reportSummary: null,
+        overallScore: null
+    });
+}

package/dist/submissions/publicUrl.js

@@ -0,0 +1,76 @@
+function isPrivateIpv4(hostname) {
+    const parts = hostname.split(".").map((part) => Number(part));
+    if (parts.length !== 4 || parts.some((part) => Number.isNaN(part))) {
+        return false;
+    }
+    const [a, b] = parts;
+    if (a === 10 || a === 127) {
+        return true;
+    }
+    if (a === 169 && b === 254) {
+        return true;
+    }
+    if (a === 192 && b === 168) {
+        return true;
+    }
+    if (a === 172 && b !== undefined && b >= 16 && b <= 31) {
+        return true;
+    }
+    if (a === 0) {
+        return true;
+    }
+    return false;
+}
+function isPrivateIpv6(hostname) {
+    const normalized = hostname.toLowerCase();
+    return normalized === "::1" || normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe80:");
+}
+function isLocalHostname(hostname) {
+    const normalized = hostname.toLowerCase();
+    return normalized === "localhost" || normalized.endsWith(".localhost") || normalized.endsWith(".local");
+}
+export const DEFAULT_SUBMISSION_TARGET_MODE = "public";
+export function parseSubmissionTargetMode(value) {
+    return value === "localhost" ? "localhost" : DEFAULT_SUBMISSION_TARGET_MODE;
+}
+export function validateSubmissionUrl(rawUrl, args = {}) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl.trim());
+    }
+    catch {
+        return { valid: false, reason: "Enter a valid http or https URL." };
+    }
+    if (!["http:", "https:"].includes(parsed.protocol)) {
+        return { valid: false, reason: "Only http and https URLs are allowed." };
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    const canUsePrivateHosts = Boolean(args.allowPrivateHosts) && args.targetMode === "localhost";
+    if (!canUsePrivateHosts && isLocalHostname(hostname)) {
+        return {
+            valid: false,
+            reason: args.allowPrivateHosts
+                ? "Switch target to Localhost/private dev site to use localhost, .localhost, or .local addresses."
+                : "Localhost, .localhost, and .local addresses are not allowed in V1. Use a public URL."
+        };
+    }
+    if (!canUsePrivateHosts && (isPrivateIpv4(hostname) || isPrivateIpv6(hostname))) {
+        return {
+            valid: false,
+            reason: args.allowPrivateHosts
+                ? "Switch target to Localhost/private dev site to use 127.0.0.1 or private network addresses."
+                : "Private network addresses are not allowed in V1. Use a public URL."
+        };
+    }
+    parsed.hash = "";
+    return {
+        valid: true,
+        normalizedUrl: parsed.toString()
+    };
+}
+export function validatePublicUrl(rawUrl) {
+    return validateSubmissionUrl(rawUrl, {
+        allowPrivateHosts: false,
+        targetMode: DEFAULT_SUBMISSION_TARGET_MODE
+    });
+}

package/dist/submissions/service.js

@@ -0,0 +1,74 @@
+import { processSubmissionBatch } from "../core/processSubmissionBatch.js";
+import { createSubmissionRecord, listSubmissions, readSubmission, writeSubmission } from "./store.js";
+export class SubmissionService {
+    activeSubmissionId = null;
+    queue = [];
+    async createSubmission(args) {
+        const submission = createSubmissionRecord(args);
+        writeSubmission(submission);
+        this.enqueue(submission.id);
+        return submission;
+    }
+    async getSubmission(id) {
+        return readSubmission(id);
+    }
+    resumePendingSubmissions() {
+        for (const submission of listSubmissions()) {
+            if (submission.status === "queued" || submission.status === "running") {
+                const resetSubmission = {
+                    ...submission,
+                    status: "queued",
+                    startedAt: submission.status === "running" ? null : submission.startedAt,
+                    completedAt: null,
+                    error: null
+                };
+                writeSubmission(resetSubmission);
+                this.enqueue(resetSubmission.id);
+            }
+        }
+    }
+    enqueue(id) {
+        if (!this.queue.includes(id) && this.activeSubmissionId !== id) {
+            this.queue.push(id);
+        }
+        void this.processQueue();
+    }
+    async processQueue() {
+        if (this.activeSubmissionId || this.queue.length === 0) {
+            return;
+        }
+        const nextId = this.queue.shift();
+        if (!nextId) {
+            return;
+        }
+        this.activeSubmissionId = nextId;
+        try {
+            await this.runSubmission(nextId);
+        }
+        finally {
+            this.activeSubmissionId = null;
+            if (this.queue.length > 0) {
+                void this.processQueue();
+            }
+        }
+    }
+    async runSubmission(id) {
+        const submission = readSubmission(id);
+        if (!submission) {
+            return;
+        }
+        await processSubmissionBatch({
+            submission: {
+                ...submission,
+                startedAt: new Date().toISOString()
+            },
+            writeSubmission: async (nextSubmission) => {
+                writeSubmission(nextSubmission);
+            },
+            uploadRunArtifacts: async () => {
+                return;
+            },
+            source: "submission_form"
+        });
+    }
+}

package/dist/submissions/store.js

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir, readUtf8, resolveSubmissionsDir, writeJson } from "../utils/files.js";
+import { SubmissionSchema } from "./types.js";
+const SUBMISSIONS_DIR = resolveSubmissionsDir();
+function submissionPath(id) {
+    return path.join(SUBMISSIONS_DIR, `${id}.json`);
+}
+export function getSubmissionsDir() {
+    ensureDir(SUBMISSIONS_DIR);
+    return SUBMISSIONS_DIR;
+}
+export function writeSubmission(submission) {
+    writeJson(submissionPath(submission.id), SubmissionSchema.parse(submission));
+}
+export function readSubmission(id) {
+    const filePath = submissionPath(id);
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    return SubmissionSchema.parse(JSON.parse(readUtf8(filePath)));
+}
+export function listSubmissions() {
+    getSubmissionsDir();
+    return fs
+        .readdirSync(SUBMISSIONS_DIR, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .map((entry) => SubmissionSchema.parse(JSON.parse(readUtf8(path.join(SUBMISSIONS_DIR, entry.name)))))
+        .sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+export function findSubmissionByReportToken(reportToken) {
+    return listSubmissions().find((submission) => submission.reportToken === reportToken) ?? null;
+}
+export function findSubmissionByRunId(runId) {
+    return listSubmissions().find((submission) => submission.runId === runId) ?? null;
+}
+export { createSubmissionRecord } from "./model.js";

package/dist/submissions/types.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { TradeRunOptionsSchema } from "../trade/types.js";
+export const SubmissionStatusSchema = z.enum(["queued", "running", "completed", "failed"]);
+const TenPointNullableScoreSchema = z
+    .number()
+    .finite()
+    .min(0)
+    .max(100)
+    .transform((value) => {
+    const scaled = value > 10 ? value / 10 : value;
+    return Math.min(10, Math.max(1, Math.round(scaled)));
+})
+    .pipe(z.number().int().min(1).max(10))
+    .nullable();
+export const SubmissionAgentRunSchema = z.object({
+    id: z.string(),
+    index: z.number().int().min(1).max(5),
+    label: z.string(),
+    profileLabel: z.string(),
+    personaName: z.string(),
+    personaVariantKey: z.string(),
+    status: SubmissionStatusSchema,
+    startedAt: z.string().nullable(),
+    completedAt: z.string().nullable(),
+    runId: z.string().nullable(),
+    runDir: z.string().nullable(),
+    clickReplayAvailable: z.boolean().optional(),
+    clickReplayArtifact: z.string().nullable().optional(),
+    videoArtifact: z.string().nullable().optional(),
+    error: z.string().nullable(),
+    reportSummary: z.string().nullable(),
+    overallScore: TenPointNullableScoreSchema
+});
+export const SubmissionSchema = z.object({
+    id: z.string(),
+    url: z.string().url(),
+    createdAt: z.string(),
+    startedAt: z.string().nullable(),
+    completedAt: z.string().nullable(),
+    expiresAt: z.string(),
+    status: SubmissionStatusSchema,
+    reportToken: z.string(),
+    publicReportPath: z.string(),
+    headed: z.boolean(),
+    mobile: z.boolean(),
+    ignoreHttpsErrors: z.boolean(),
+    tradeOptions: TradeRunOptionsSchema.default({
+        enabled: false,
+        dryRun: false,
+        strategy: "auto",
+        confirmations: 1
+    }),
+    customTasks: z.array(z.string().min(1)).max(12).default([]),
+    instructionText: z.string().default(""),
+    instructionFileName: z.string().nullable().default(null),
+    agentCount: z.number().int().min(1).max(5).default(1),
+    completedAgentCount: z.number().int().nonnegative().default(0),
+    failedAgentCount: z.number().int().nonnegative().default(0),
+    agentRuns: z.array(SubmissionAgentRunSchema).max(5).default([]),
+    runId: z.string().nullable(),
+    runDir: z.string().nullable(),
+    error: z.string().nullable(),
+    reportSummary: z.string().nullable(),
+    overallScore: TenPointNullableScoreSchema
+});

package/dist/trade/engine.js

@@ -0,0 +1,241 @@
+import crypto from "node:crypto";
+import { sendTransaction } from "../wallet/wallet.js";
+import { encodeErc20Transfer, parseTokenAmount, waitForEvmReceipt } from "./evm/erc20.js";
+import { appendTradeExecutionRecord, computeInstructionFingerprint, readTradeExecutionRecords } from "./session.js";
+import { validateSellInstruction } from "./validator.js";
+function cleanErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.replace(/\u001b\[[0-9;]*m/g, "").replace(/\s+/g, " ").trim() || "Unknown trade execution error";
+}
+function serializeJsonSafe(value) {
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => serializeJsonSafe(item));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, nestedValue]) => [key, serializeJsonSafe(nestedValue)]));
+    }
+    return value;
+}
+function createExecutionRecord(args) {
+    return {
+        id: crypto.randomUUID(),
+        fingerprint: args.fingerprint,
+        time: new Date().toISOString(),
+        source: args.source,
+        strategy: args.requestedStrategy,
+        selectedMode: args.selectedMode,
+        dryRun: args.dryRun,
+        status: args.status,
+        instruction: args.instruction,
+        validation: args.validation,
+        txHash: args.txHash ?? null,
+        confirmationsRequested: args.confirmationsRequested,
+        confirmationsReached: args.confirmationsReached ?? 0,
+        receipt: args.receipt ?? null,
+        error: args.error ?? null,
+        note: args.note
+    };
+}
+function resolveSelectedMode(args) {
+    if (args.instruction.mode === "dapp_managed") {
+        return "dapp_managed";
+    }
+    if (args.instruction.mode === "deposit_address_transfer") {
+        return "deposit_address_transfer";
+    }
+    return "unsupported";
+}
+function strategyAllowsMode(args) {
+    if (args.runOptions.strategy === "auto") {
+        return true;
+    }
+    if (args.runOptions.strategy === "dapp_only") {
+        return args.selectedMode === "dapp_managed";
+    }
+    if (args.runOptions.strategy === "deposit_only") {
+        return args.selectedMode === "deposit_address_transfer";
+    }
+    return false;
+}
+export async function executeTradeInstruction(args) {
+    const fingerprint = computeInstructionFingerprint(args.instruction);
+    const selectedMode = resolveSelectedMode({
+        instruction: args.instruction,
+        runOptions: args.runOptions
+    });
+    const { validation, normalizedInstruction } = await validateSellInstruction({
+        instruction: args.instruction,
+        policy: args.policy,
+        runOptions: args.runOptions
+    });
+    if (!strategyAllowsMode({ selectedMode, runOptions: args.runOptions })) {
+        const blockedRecord = createExecutionRecord({
+            fingerprint,
+            source: args.source,
+            requestedStrategy: args.runOptions.strategy,
+            selectedMode,
+            dryRun: args.runOptions.dryRun,
+            status: "blocked",
+            instruction: normalizedInstruction,
+            validation: {
+                ok: false,
+                reasons: [
+                    `Requested trade strategy '${args.runOptions.strategy}' does not allow the extracted mode '${selectedMode}'.`,
+                    ...validation.reasons
+                ]
+            },
+            confirmationsRequested: args.runOptions.confirmations,
+            note: `Blocked trade execution because strategy '${args.runOptions.strategy}' does not permit '${selectedMode}'.`
+        });
+        appendTradeExecutionRecord(args.runDir, blockedRecord);
+        return blockedRecord;
+    }
+    if (!validation.ok) {
+        const blockedRecord = createExecutionRecord({
+            fingerprint,
+            source: args.source,
+            requestedStrategy: args.runOptions.strategy,
+            selectedMode,
+            dryRun: args.runOptions.dryRun,
+            status: "blocked",
+            instruction: normalizedInstruction,
+            validation,
+            confirmationsRequested: args.runOptions.confirmations,
+            note: `Blocked trade execution after validation: ${validation.reasons.join(" ")}`
+        });
+        appendTradeExecutionRecord(args.runDir, blockedRecord);
+        return blockedRecord;
+    }
+    const previousExecution = readTradeExecutionRecords(args.runDir).find((record) => record.fingerprint === fingerprint &&
+        !record.dryRun &&
+        (record.status === "broadcast" || record.status === "confirmed"));
+    if (previousExecution) {
+        const blockedRecord = createExecutionRecord({
+            fingerprint,
+            source: args.source,
+            requestedStrategy: args.runOptions.strategy,
+            selectedMode,
+            dryRun: args.runOptions.dryRun,
+            status: "blocked",
+            instruction: normalizedInstruction,
+            validation,
+            confirmationsRequested: args.runOptions.confirmations,
+            txHash: previousExecution.txHash,
+            note: "Blocked duplicate trade execution because the same instruction was already broadcast in this run."
+        });
+        appendTradeExecutionRecord(args.runDir, blockedRecord);
+        return blockedRecord;
+    }
+    if (args.runOptions.dryRun) {
+        const dryRunRecord = createExecutionRecord({
+            fingerprint,
+            source: args.source,
+            requestedStrategy: args.runOptions.strategy,
+            selectedMode,
+            dryRun: true,
+            status: "dry_run",
+            instruction: normalizedInstruction,
+            validation,
+            confirmationsRequested: args.runOptions.confirmations,
+            note: `Dry run validated a ${selectedMode} trade without broadcasting a transaction.`
+        });
+        appendTradeExecutionRecord(args.runDir, dryRunRecord);
+        return dryRunRecord;
+    }
+    if (selectedMode === "dapp_managed") {
+        const blockedRecord = createExecutionRecord({
+            fingerprint,
+            source: args.source,
+            requestedStrategy: args.runOptions.strategy,
+            selectedMode,
+            dryRun: false,
+            status: "blocked",
+            instruction: normalizedInstruction,
+            validation,
+            confirmationsRequested: args.runOptions.confirmations,
+            note: "Dapp-managed trades must be initiated by the page through the injected wallet provider; the direct trade engine only broadcasts deposit-address transfers."
+        });
+        appendTradeExecutionRecord(args.runDir, blockedRecord);
+        return blockedRecord;
+    }
+    if (selectedMode !== "deposit_address_transfer") {
+        const blockedRecord = createExecutionRecord({
+            fingerprint,
+            source: args.source,
+            requestedStrategy: args.runOptions.strategy,
+            selectedMode: "unsupported",
+            dryRun: false,
+            status: "blocked",
+            instruction: normalizedInstruction,
+            validation,
+            confirmationsRequested: args.runOptions.confirmations,
+            note: "The extracted trade mode is not supported by the direct trade engine."
+        });
+        appendTradeExecutionRecord(args.runDir, blockedRecord);
+        return blockedRecord;
+    }
+    try {
+        const tx = normalizedInstruction.assetKind === "native"
+            ? {
+                to: normalizedInstruction.recipientAddress,
+                value: await parseTokenAmount(normalizedInstruction.amount, normalizedInstruction.tokenDecimals ?? 18),
+                chainId: normalizedInstruction.chainId
+            }
+            : {
+                to: normalizedInstruction.tokenContract,
+                data: await encodeErc20Transfer({
+                    recipientAddress: normalizedInstruction.recipientAddress,
+                    amountBaseUnits: await parseTokenAmount(normalizedInstruction.amount, normalizedInstruction.tokenDecimals ?? 0)
+                }),
+                value: 0n,
+                chainId: normalizedInstruction.chainId
+            };
+        const txHash = await sendTransaction(tx);
+        const receipt = await waitForEvmReceipt({
+            txHash,
+            confirmations: Math.max(0, args.runOptions.confirmations),
+            timeoutMs: args.policy.receiptTimeoutMs
+        });
+        const confirmed = Boolean(receipt);
+        const record = createExecutionRecord({
+            fingerprint,
+            source: args.source,
+            requestedStrategy: args.runOptions.strategy,
+            selectedMode,
+            dryRun: false,
+            status: confirmed ? "confirmed" : "broadcast",
+            instruction: normalizedInstruction,
+            validation,
+            txHash,
+            confirmationsRequested: args.runOptions.confirmations,
+            confirmationsReached: confirmed ? Math.max(1, args.runOptions.confirmations) : 0,
+            receipt: serializeJsonSafe(receipt),
+            note: confirmed
+                ? `Broadcast and confirmed ${normalizedInstruction.assetKind} transfer ${txHash}.`
+                : `Broadcast ${normalizedInstruction.assetKind} transfer ${txHash}, but no receipt was observed before timeout.`
+        });
+        appendTradeExecutionRecord(args.runDir, record);
+        return record;
+    }
+    catch (error) {
+        const message = cleanErrorMessage(error);
+        const failedRecord = createExecutionRecord({
+            fingerprint,
+            source: args.source,
+            requestedStrategy: args.runOptions.strategy,
+            selectedMode,
+            dryRun: false,
+            status: "failed",
+            instruction: normalizedInstruction,
+            validation,
+            confirmationsRequested: args.runOptions.confirmations,
+            error: message,
+            note: `Trade execution failed: ${message}`
+        });
+        appendTradeExecutionRecord(args.runDir, failedRecord);
+        return failedRecord;
+    }
+}

package/dist/trade/evm/erc20.js

@@ -0,0 +1,44 @@
+import { getWalletConfig, getWalletProvider } from "../../wallet/wallet.js";
+async function loadEthers() {
+    const mod = (await import("ethers"));
+    return mod.default ?? mod;
+}
+async function resolveRpcProvider() {
+    const walletConfig = await getWalletConfig();
+    if (!walletConfig?.rpcUrl) {
+        throw new Error("Wallet RPC configuration is required for EVM trade execution.");
+    }
+    const ethers = await loadEthers();
+    return new ethers.JsonRpcProvider(walletConfig.rpcUrl);
+}
+export async function parseTokenAmount(value, decimals) {
+    const ethers = await loadEthers();
+    return ethers.parseUnits(value, decimals);
+}
+export async function encodeErc20Transfer(args) {
+    const ethers = await loadEthers();
+    const iface = new ethers.Interface(["function transfer(address to, uint256 amount) returns (bool)"]);
+    return iface.encodeFunctionData("transfer", [args.recipientAddress, args.amountBaseUnits]);
+}
+export async function readNativeBalance(address) {
+    const provider = await resolveRpcProvider();
+    return provider.getBalance(address);
+}
+export async function readErc20Balance(args) {
+    const ethers = await loadEthers();
+    const provider = await resolveRpcProvider();
+    const iface = new ethers.Interface(["function balanceOf(address owner) view returns (uint256)"]);
+    const data = iface.encodeFunctionData("balanceOf", [args.owner]);
+    const result = await provider.call({ to: args.contract, data });
+    return BigInt(result);
+}
+export async function waitForEvmReceipt(args) {
+    const provider = (await getWalletProvider());
+    if (provider?.waitForTransaction) {
+        const receipt = await provider.waitForTransaction(args.txHash, args.confirmations, args.timeoutMs);
+        return receipt ?? null;
+    }
+    const rpcProvider = await resolveRpcProvider();
+    const receipt = await rpcProvider.waitForTransaction(args.txHash, args.confirmations, args.timeoutMs);
+    return receipt ?? null;
+}