@relvo/mcp 0.1.2 → 0.1.3

package/dist/client/agent-run.js

@@ -0,0 +1,681 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, lstat, open, readFile, realpath, link, rename, unlink, writeFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { z } from "zod";
+import { platformToolInputSchema, platformCreateExecutionSchema, platformQuoteSchema, platformExecutionIdSchema, platformJsonObjectSchema } from "../schema/platformPublicExecution.js";
+import { fitToolResultPage, toolResultSelectionSchema, TOOL_RESULT_PAGE_MAX_CHARS, TOOL_RESULT_PAGE_MAX_ITEMS } from "../schema/toolResultContext.js";
+import { platformFundingShortfallSchema } from "../schema/platformFunding.js";
+import { AUTO_CAPABILITY_VARIANTS } from "../schema/platformCapabilityFamilies.js";
+const keySchema = z.string().regex(/^[A-Za-z0-9._:-]{8,128}$/);
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/);
+const recoveryReferencePattern = /^run:([a-f0-9]{64}):([A-Za-z0-9._:-]{8,128})$/;
+const recoveryReferenceSchema = z.string().regex(recoveryReferencePattern);
+function pathText(text) {
+    const parts = text.startsWith("/") ? text.split("/").slice(1).map(part => part.replaceAll("~1", "/").replaceAll("~0", "~")) : text.replaceAll("[]", "[*]").match(/[^.[\]]+/g) ?? [];
+    return parts.map(part => part.replace(/^(['"])(.*)\1$/, "$2")).filter((part, index) => part !== "" && !(index === 0 && part === "$"));
+}
+const looseResultPath = z.union([z.array(z.union([z.string().max(256), z.number().int().nonnegative().safe().transform(String)])),
+    z.string().max(4096).transform(pathText)]);
+const pathSchema = looseResultPath.pipe(z.array(z.string().max(256)).max(24));
+const TEXT_PAGE_MAX_CHARS = 20_000;
+const selectionSchema = toolResultSelectionSchema.extend({ path: looseResultPath.optional().pipe(toolResultSelectionSchema.shape.path),
+    limit: z.number().int().min(1).optional(), maxChars: z.number().int().min(1).optional(),
+    find: z.array(z.string().min(1).max(50)).max(32).refine(terms => terms.join("").length <= 400, "find takes at most 400 characters of terms in all.").optional() });
+const picksSchema = z.record(z.string().min(1).max(80), pathSchema).refine(value => Object.keys(value).length <= 24);
+export const agentRunSchema = platformToolInputSchema.extend({
+    maximumChargeMicros: z.number().int().nonnegative().safe().nullable().optional().describe("Optional user-requested Relvo spending ceiling. Omit or use null when none was requested; do not invent a limit or ask for one. 0 permits only zero Relvo charges. 1 USD = 1000000 micros. Does not cap external account charges."),
+    externalBillingAccepted: z.boolean().default(false).describe("True only when the user has authorized this connected-account or BYOK usage and its external cost or quota use. The Relvo ceiling still applies; this never authorizes sending, publishing or unrelated account changes."),
+    idempotencyKey: keySchema.describe("Unique per purchase (add a random suffix). Save before calling. Reuse unchanged after lost replies; never replace unknown work."),
+    waitSeconds: z.number().int().min(1).max(60).default(25),
+    selection: selectionSchema.optional().describe("Optional result path/page/fields. fields works on objects and rows. Full output remains stored."),
+    pick: picksSchema.optional().describe("Optional named exact result paths, e.g. {title:[\"data\",\"title\"]}; with a path, may be relative to it (each row of its page). Missing paths are reported; null/false/0 are preserved."),
+    file: z.boolean().optional().describe("Write the whole selected path (fields applied) to a private local file instead of returning it: JSON Lines, one row per line, for an array. Returns the path for the host's file tools."),
+}).strict();
+export const agentResumeSchema = z.object({ runId: z.union([recoveryReferenceSchema, digestSchema, platformExecutionIdSchema]), waitSeconds: agentRunSchema.shape.waitSeconds,
+    selection: agentRunSchema.shape.selection, pick: agentRunSchema.shape.pick, file: agentRunSchema.shape.file }).strict();
+export const agentResultSchema = z.object({ id: platformExecutionIdSchema, ...selectionSchema.shape,
+    pick: agentRunSchema.shape.pick, file: agentRunSchema.shape.file, waitSeconds: agentRunSchema.shape.waitSeconds }).strict();
+const PENDING = ["queued", "running", "waiting"];
+const savedSchema = z.object({ version: z.literal(1), requestHash: digestSchema, idempotencyKey: keySchema,
+    quote: platformQuoteSchema, purchase: platformCreateExecutionSchema }).strict();
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const isApiError = (error, code) => error instanceof Error && error.name === "PlatformApiError" && "code" in error && error.code === code;
+const RUN_FIELDS = new Set(["provider", "relevanceCheck"]);
+const invalidFields = z.object({ name: z.literal("PlatformApiError"), code: z.literal("platform_invalid_tool_arguments"), fields: z.array(z.string()).min(1) });
+function withRunFieldsMoved(error, request) {
+    const refused = invalidFields.safeParse(error);
+    if (!refused.success || !refused.data.fields.every(field => RUN_FIELDS.has(field) && Object.hasOwn(request.arguments, field)
+        && (field === "provider" ? request.provider : request.relevanceCheck) === undefined))
+        return undefined;
+    const fields = refused.data.fields, moved = platformToolInputSchema.safeParse({ ...request, ...Object.fromEntries(fields.map(field => [field, request.arguments[field]])),
+        arguments: Object.fromEntries(Object.entries(request.arguments).filter(([key]) => !fields.includes(key))) });
+    return moved.success ? moved.data : undefined;
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object")
+        return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+    return JSON.stringify(value);
+}
+const keyForm = (key) => key.toLowerCase().replace(/[_-]/g, "");
+function ownKey(object, key) {
+    if (Object.hasOwn(object, key))
+        return key;
+    const matches = Object.keys(object).filter(name => keyForm(name) === keyForm(key));
+    return matches.length === 1 ? matches[0] : undefined;
+}
+function childAt(value, part) {
+    if (value === undefined || value === null || typeof value !== "object" || Array.isArray(value))
+        return {};
+    const name = ownKey(value, part);
+    return name === undefined ? {} : { name, value: value[name] };
+}
+function at(value, path) {
+    let current = value;
+    for (const key of path) {
+        if (current === null || typeof current !== "object")
+            return { found: false };
+        if (Array.isArray(current)) {
+            if (key === "length") {
+                current = current.length;
+                continue;
+            }
+            const index = /^(?:0|-?[1-9][0-9]*)$/.test(key) ? Number(key) < 0 ? current.length + Number(key) : Number(key) : -1;
+            if (index < 0 || index >= current.length)
+                return { found: false };
+            current = current[index];
+        }
+        else {
+            const own = ownKey(current, key);
+            if (own === undefined)
+                return { found: false };
+            current = current[own];
+        }
+    }
+    return { found: true, value: current };
+}
+function shape(value, depth = 0) {
+    if (Array.isArray(value))
+        return { kind: "array", length: value.length, ...(value.length && depth < 2 ? { firstItem: shape(value[0], depth + 1) } : {}) };
+    if (value !== null && typeof value === "object")
+        return { kind: "object", totalKeys: Object.keys(value).length, keys: Object.keys(value).filter(key => key.length <= 256).slice(0, 64),
+            ...(depth < 1 ? { children: Object.fromEntries(Object.entries(value).filter(([key, child]) => key.length <= 256 && child !== null && typeof child === "object").slice(0, 2).map(([key, child]) => [key, shape(child, depth + 1)])) } : {}) };
+    return { kind: value === null ? "null" : typeof value, ...(typeof value === "string" ? { length: value.length } : {}) };
+}
+function rowFields(row, fields) {
+    if (!fields?.length)
+        return row;
+    if (row === null || typeof row !== "object" || Array.isArray(row))
+        throw new Error("Select row fields only on objects; inspect the retained result shape.");
+    return objectFields(row, fields);
+}
+function objectFields(row, fields) {
+    const picked = {};
+    for (const key of fields) {
+        const own = ownKey(row, key);
+        if (own !== undefined) {
+            picked[own] = row[own];
+            continue;
+        }
+        const parts = [];
+        let value = row;
+        for (const part of key.split(".")) {
+            const child = childAt(value, part);
+            value = child.value;
+            parts.push(child.name ?? part);
+        }
+        if (parts.length < 2 || value === undefined)
+            continue;
+        let target = picked;
+        for (const part of parts.slice(0, -1)) {
+            const existing = target[part];
+            const copy = existing !== null && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+            target[part] = copy;
+            target = copy;
+        }
+        target[parts[parts.length - 1]] = value;
+    }
+    return picked;
+}
+function cell(picked, field) {
+    const own = childAt(picked, field);
+    if (own.name !== undefined)
+        return own.value ?? null;
+    let value = picked;
+    for (const part of field.split("."))
+        value = childAt(value, part).value;
+    return value ?? null;
+}
+const TABLE_AFTER_ROWS = 20;
+function rowWindow(row, path, index) {
+    const fields = {}, fragments = [], references = [];
+    for (const [key, value] of Object.entries(row)) {
+        const target = [...path, String(index), key];
+        if (typeof value === "string" && value.length > 512) {
+            let end = 512;
+            if (/[\uD800-\uDBFF]/.test(value[end - 1] ?? "") && /[\uDC00-\uDFFF]/.test(value[end] ?? ""))
+                end++;
+            fragments.push({ path: target, text: value.slice(0, end), offset: 0, totalChars: value.length, nextOffset: end });
+        }
+        else if (value !== null && typeof value === "object" && Buffer.byteLength(JSON.stringify(value)) > 512) {
+            references.push({ path: target, shape: shape(value) });
+        }
+        else
+            fields[key] = value;
+    }
+    return { index, fields, ...(fragments.length ? { fragments } : {}), ...(references.length ? { references } : {}) };
+}
+function findInText(text, terms, offset, pageBytes) {
+    const pattern = new RegExp(terms.map(term => term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|"), "giu");
+    const matches = [];
+    let used = 1, position = offset;
+    while (position < text.length) {
+        const newline = text.indexOf("\n", position), end = newline < 0 ? text.length : newline;
+        const line = text.slice(position, end);
+        for (let cursor = 0; cursor < line.length;) {
+            pattern.lastIndex = cursor;
+            const hit = pattern.exec(line);
+            if (!hit)
+                break;
+            let from = line.length > 600 ? Math.max(cursor, hit.index - 200) : 0, to = Math.min(line.length, from + 600);
+            if (/[\uDC00-\uDFFF]/.test(line[from] ?? ""))
+                from--;
+            if (/[\uD800-\uDBFF]/.test(line[to - 1] ?? ""))
+                to++;
+            const match = { offset: position + from, text: line.slice(from, to) }, size = Buffer.byteLength(JSON.stringify(match)) + 1;
+            if (used + size > pageBytes && matches.length)
+                return { matches, total: text.length, nextOffset: position + from };
+            matches.push(match);
+            used += size;
+            cursor = to;
+        }
+        position = end + 1;
+    }
+    return { matches, total: text.length, nextOffset: null };
+}
+function pathSlice(value, requested) {
+    const path = requested.map((segment, index) => segment === "*" && Array.isArray(at(value, requested.slice(0, index)).value) ? ":" : segment);
+    const isSlice = (segment) => /^(-?\d+)?:(-?\d+)?$/.test(segment);
+    const sliceAt = path.findIndex((segment, index) => isSlice(segment) && path.slice(index + 1).every(part => !isSlice(part) && !part.includes(".")));
+    const slice = sliceAt < 0 ? null : /^(-?\d+)?:(-?\d+)?$/.exec(path[sliceAt]);
+    if (!slice)
+        return undefined;
+    const sliced = at(value, path.slice(0, sliceAt)).value, length = Array.isArray(sliced) ? sliced.length : 0;
+    const bound = (text) => text === undefined ? undefined : Number(text) < 0 ? Math.max(0, length + Number(text)) : Number(text);
+    return { path: path.slice(0, sliceAt), start: bound(slice[1]) ?? 0, end: bound(slice[2]), ...(sliceAt < path.length - 1 ? { field: path.slice(sliceAt + 1).join(".") } : {}) };
+}
+function rowPicks(value, picks) {
+    let path;
+    const relative = {};
+    for (const [label, pick] of Object.entries(picks)) {
+        const index = pick.findIndex((segment, position) => (segment === "*" || /^(-?\d+)?:(-?\d+)?$/.test(segment)) && Array.isArray(at(value, pick.slice(0, position)).value));
+        const prefix = index < 0 ? undefined : [...pick.slice(0, index), pick[index] === "*" ? ":" : pick[index]];
+        if (!prefix || path && JSON.stringify(prefix) !== JSON.stringify(path))
+            return undefined;
+        path = prefix;
+        relative[label] = pick.slice(index + 1);
+    }
+    return path && { path, picks: relative };
+}
+export function agentResultView(value, raw, picks, rowsOnly = false) {
+    const rows = picks && !rowsOnly && !raw?.path?.length ? rowPicks(value, picks) : undefined;
+    if (rows)
+        return agentResultView(value, { ...raw, path: rows.path }, rows.picks, true);
+    const requested = selectionSchema.parse(raw ?? {});
+    const parsed = { ...requested, limit: Math.min(requested.limit ?? 20, TOOL_RESULT_PAGE_MAX_ITEMS) };
+    const textChars = Math.min(requested.maxChars ?? requested.limit ?? TOOL_RESULT_PAGE_MAX_CHARS, TEXT_PAGE_MAX_CHARS);
+    const slice = pathSlice(value, parsed.path);
+    const input = slice ? { ...parsed, path: slice.path, offset: slice.start, ...(slice.field ? { fields: [slice.field] } : {}),
+        limit: slice.end !== undefined ? Math.min(Math.max(0, slice.end - slice.start), TOOL_RESULT_PAGE_MAX_ITEMS) : parsed.limit } : parsed;
+    const located = at(value, input.path);
+    if (!located.found)
+        return { found: false, path: input.path, shape: shape(value), retained: true };
+    const source = located.value ?? null;
+    if (slice && Array.isArray(source) && slice.start >= Math.min(slice.end ?? source.length, source.length))
+        return { value: [], path: input.path, total: source.length, nextOffset: null, retained: true };
+    const bytes = (item) => Buffer.byteLength(JSON.stringify(item));
+    if (!picks && !input.fields?.length && input.offset === 0 && input.path.length < 16 && source !== null && typeof source === "object" && !Array.isArray(source) && bytes(source) > 8000) {
+        const collections = Object.entries(source).filter(([, child]) => child !== null && typeof child === "object");
+        const metadata = Object.fromEntries(Object.entries(source).filter(([, child]) => child === null || typeof child !== "object"));
+        if (collections.length === 1 && bytes(metadata) <= 512)
+            return { ...agentResultView(value, { ...input, limit: requested.limit, path: [...input.path, collections[0][0]] }), autoSelected: true, envelopeShape: shape(source) };
+        const texts = Object.entries(source).filter(([, child]) => typeof child === "string" && bytes(child) > 512);
+        const fields = Object.fromEntries(Object.entries(source).filter(([key]) => key !== texts[0]?.[0]));
+        if (!collections.length && texts.length === 1 && bytes(fields) <= 512)
+            return { ...agentResultView(value, { ...input, limit: undefined, path: [...input.path, texts[0][0]] }), autoSelected: true, fields };
+    }
+    if (!picks && typeof source === "string" && requested.find?.length)
+        return { ...findInText(source, requested.find, input.offset, Math.max(8000, textChars)), path: input.path, retained: true,
+            instruction: "Each match is a line containing a term; offset is where its text starts. Read around a match with offset and maxChars, or search on from nextOffset." };
+    if (!picks && Array.isArray(source) && input.fields?.length && input.limit > TABLE_AFTER_ROWS) {
+        const columns = input.fields, rows = source.slice(input.offset, input.offset + input.limit).map(row => { const picked = rowFields(row, columns); return columns.map(field => cell(picked, field)); });
+        let lower = 1, upper = rows.length, count = 0;
+        while (lower <= upper) {
+            const middle = Math.floor((lower + upper) / 2);
+            if (bytes({ columns, rows: rows.slice(0, middle) }) <= TEXT_PAGE_MAX_CHARS) {
+                count = middle;
+                lower = middle + 1;
+            }
+            else
+                upper = middle - 1;
+        }
+        if (!count)
+            return { offloaded: true, path: input.path, shape: shape(source), retained: true, instruction: "Read narrower paths or fewer rows from the same execution; do not regenerate." };
+        return { table: { columns, rows: rows.slice(0, count) }, path: input.path, total: source.length, returned: count,
+            nextOffset: input.offset + count < source.length ? input.offset + count : null, retained: true };
+    }
+    let output, total = 1, returned = 1, paged = !picks;
+    const missing = [];
+    if (picks) {
+        const choose = (base, found) => Object.fromEntries(Object.entries(picks).flatMap(([label, path]) => {
+            const item = at(base, path);
+            if (!item.found)
+                return [];
+            found.add(label);
+            return [[label, item.value ?? null]];
+        }));
+        let found = new Set();
+        output = rowsOnly ? {} : choose(value, found);
+        if (!found.size && (rowsOnly || input.path.length)) {
+            const relative = new Set(), rows = Array.isArray(source) ? source.slice(input.offset, input.offset + input.limit) : undefined;
+            const chosen = rows ? rows.map(row => choose(row, relative)) : choose(source, relative);
+            if (relative.size) {
+                output = chosen;
+                found = relative;
+                if (rows && Array.isArray(source)) {
+                    total = source.length;
+                    returned = rows.length;
+                    paged = true;
+                }
+            }
+        }
+        missing.push(...Object.keys(picks).filter(label => !found.has(label)));
+    }
+    else if (Array.isArray(source)) {
+        total = source.length;
+        const rows = source.slice(input.offset, input.offset + input.limit);
+        output = rows.map(row => rowFields(row, input.fields));
+        returned = rows.length;
+    }
+    else if (source !== null && typeof source === "object") {
+        const fields = input.fields?.length ? input.fields : undefined, keys = fields ?? Object.keys(source);
+        const present = fields ? fields.filter(field => Object.keys(objectFields(source, [field])).length) : keys;
+        missing.push(...(fields ?? []).filter(field => !present.includes(field)));
+        total = present.length;
+        const page = present.slice(input.offset, input.offset + input.limit);
+        output = fields ? objectFields(source, page) : Object.fromEntries(page.map(key => [key, source[key]]));
+        returned = page.length;
+    }
+    else if (typeof source === "string") {
+        total = source.length;
+        let end = Math.min(source.length, input.offset + textChars);
+        if (end < source.length && /[\uD800-\uDBFF]/.test(source[end - 1] ?? "") && /[\uDC00-\uDFFF]/.test(source[end] ?? ""))
+            end++;
+        output = source.slice(input.offset, end);
+        returned = output.length;
+    }
+    else
+        output = input.offset ? null : source;
+    if (!picks && Array.isArray(output) && bytes(output) > 8000 && output.some(row => bytes(row) > 4000)) {
+        const windows = [];
+        for (const [index, row] of output.entries()) {
+            if (row === null || typeof row !== "object" || Array.isArray(row))
+                break;
+            windows.push(rowWindow(row, input.path, input.offset + index));
+        }
+        if (windows.length === output.length) {
+            const page = fitToolResultPage({ path: input.path, kind: "array", offset: input.offset, total, nextOffset: input.offset + windows.length < total ? input.offset + windows.length : null,
+                context: { offloaded: false, preview: windows, totalBytes: bytes(windows) } }, candidate => bytes(candidate.context.preview) <= 8000);
+            if (bytes(page.context.preview) <= 8000)
+                return { rowWindows: page.context.preview, path: input.path, total, nextOffset: page.nextOffset,
+                    retained: true, instruction: "fields are exact complete values; fragments are incomplete text excerpts with exact source paths/cursors. Read needed missing details from the same execution; never treat a fragment as a complete URL or identifier." };
+        }
+    }
+    const pageBytes = typeof output === "string" ? Math.max(8000, textChars) : requested.limit !== undefined || slice?.end !== undefined ? TEXT_PAGE_MAX_CHARS : 8000;
+    if (paged && (Array.isArray(output) || typeof output === "string") && bytes(output) > pageBytes) {
+        const page = fitToolResultPage({ path: input.path, kind: Array.isArray(output) ? "array" : "string", offset: input.offset, total, nextOffset: null,
+            context: { offloaded: false, preview: output, totalBytes: bytes(output) } }, candidate => bytes(candidate.context.preview) <= pageBytes);
+        output = page.context.preview;
+        if (typeof output === "string" || Array.isArray(output))
+            returned = output.length;
+    }
+    if (bytes(output) > pageBytes)
+        return { offloaded: true, path: input.path, shape: shape(source), retained: true,
+            instruction: "Read narrower paths or fewer rows from the same execution; do not regenerate." };
+    const short = paged && Array.isArray(output) && returned < Math.min(input.limit, total - input.offset);
+    return { value: output, ...(missing.length ? { missing } : {}), path: input.path, total, ...(short ? { returned } : {}),
+        nextOffset: !paged || input.offset + returned >= total ? null : input.offset + returned, retained: true };
+}
+export function resultFilesFor(env, cwd = process.cwd()) {
+    return env.RELVO_RESULT_DIRECTORY ? { directory: env.RELVO_RESULT_DIRECTORY } : { directory: join(cwd, ".relvo", "results"), within: cwd };
+}
+export class AgentRun {
+    client;
+    directory;
+    resultFiles;
+    topUp;
+    constructor(client, directory = join(tmpdir(), `relvo-runs-${process.getuid?.() ?? "user"}`), resultFiles, topUp) {
+        this.client = client;
+        this.directory = directory;
+        this.resultFiles = resultFiles;
+        this.topUp = topUp;
+    }
+    async resultFolder() {
+        if (!this.resultFiles) {
+            const path = join(await this.folder(), "results");
+            await mkdir(path, { recursive: true, mode: 0o700 });
+            return path;
+        }
+        const { directory, within } = this.resultFiles;
+        const escape = new Error("The result directory must not lead outside the working directory.");
+        let current = within;
+        for (const part of within ? relative(within, directory).split(sep) : []) {
+            current = join(current ?? "", part);
+            const info = await lstat(current).catch(error => { if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return null; throw error; });
+            if (!info)
+                break;
+            if (info.isSymbolicLink())
+                throw escape;
+        }
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink() || process.getuid && info.uid !== process.getuid())
+            throw new Error("The result directory must be a directory that belongs to this user.");
+        if (within && await realpath(directory) !== join(await realpath(within), relative(within, directory)))
+            throw escape;
+        await writeFile(join(directory, ".gitignore"), "*\n", { flag: "wx", mode: 0o600 }).catch(error => {
+            if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+                throw error;
+        });
+        return directory;
+    }
+    async alternatives(tool, maximumChargeMicros) {
+        const results = [];
+        try {
+            const definition = (await this.client.tool(tool)).data;
+            const providers = (definition.providers ?? []).filter(item => item.available && item.id !== "auto"), plans = [];
+            const family = AUTO_CAPABILITY_VARIANTS[tool];
+            if (family) {
+                for (const name of family) {
+                    const provider = providers.find(item => name.startsWith(item.id + "_"));
+                    if (provider)
+                        plans.push({ name, provider: provider.id });
+                }
+            }
+            else
+                for (const provider of providers.slice(0, 4)) {
+                    const candidates = (await this.client.searchTools({ query: definition.name.replaceAll("_", " "), provider: provider.id, limit: 12, summary: true })).data.tools;
+                    plans.push(...candidates.filter(item => item.name !== tool && item.name.startsWith(provider.id + "_")).map(item => ({ name: item.name, provider: provider.id })));
+                }
+            for (const plan of plans.slice(0, 12)) {
+                if (results.some(item => item.tool === plan.name))
+                    continue;
+                try {
+                    const candidate = (await this.client.tool(plan.name)).data;
+                    if (!candidate.available)
+                        continue;
+                    const quote = (await this.client.quote({ tool: candidate.name, arguments: candidate.example, provider: plan.provider })).data;
+                    if (quote.maximumChargeMicros > maximumChargeMicros || quote.funding === "provider" || quote.funding === "mixed" || quote.externalBillingProviders?.length)
+                        continue;
+                    const core = { tool: candidate.name, provider: plan.provider, description: candidate.description.slice(0, 400), example: candidate.example,
+                        quotedExampleCeilingMicros: quote.maximumChargeMicros };
+                    const inline = candidate.inputSchema !== undefined && Buffer.byteLength(JSON.stringify([...results, { ...core, inputSchema: candidate.inputSchema }])) <= 7500;
+                    results.push({ ...core, quoteBasis: "example", schemaComplete: inline, ...(inline ? { inputSchema: candidate.inputSchema } : { inspectWith: "tool" }) });
+                    if (results.length === 3)
+                        return results;
+                }
+                catch { }
+            }
+        }
+        catch { }
+        return results;
+    }
+    async folder() {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const root = await lstat(this.directory);
+        if (!root.isDirectory() || root.isSymbolicLink() || root.mode & 0o077 || process.getuid && root.uid !== process.getuid())
+            throw new Error("The private run directory must belong to this user and allow owner access only.");
+        const path = join(this.directory, await this.client.requestJournalScope());
+        await mkdir(path, { recursive: true, mode: 0o700 });
+        const scoped = await lstat(path);
+        if (!scoped.isDirectory() || scoped.isSymbolicLink() || scoped.mode & 0o077 || process.getuid && scoped.uid !== process.getuid())
+            throw new Error("Invalid private run directory.");
+        return path;
+    }
+    async read(runId) {
+        const path = join(await this.folder(), digestSchema.parse(runId) + ".json");
+        try {
+            const info = await lstat(path);
+            if (!info.isFile() || info.isSymbolicLink() || info.mode & 0o077)
+                throw new Error("Invalid saved run file.");
+            return savedSchema.parse(JSON.parse(await readFile(path, "utf8")));
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+    }
+    async persist(runId, plan, replace = false) {
+        const directory = await this.folder(), destination = join(directory, runId + ".json"), temporary = join(directory, randomUUID() + ".tmp");
+        const file = await open(temporary, "wx", 0o600);
+        try {
+            await file.writeFile(JSON.stringify(plan));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        if (replace)
+            await rename(temporary, destination);
+        else {
+            try {
+                await link(temporary, destination);
+            }
+            catch (error) {
+                if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+                    throw error;
+            }
+            finally {
+                await unlink(temporary);
+            }
+        }
+        const stored = await this.read(runId);
+        if (!stored || stored.requestHash !== plan.requestHash)
+            throw new Error("This run key is bound to another request. Retain the original purchase.");
+        return stored;
+    }
+    async run(raw) {
+        const input = agentRunSchema.parse(raw), { waitSeconds, selection, pick, file, idempotencyKey, maximumChargeMicros: requestedCeiling, externalBillingAccepted, intent: _intent, ...sent } = input;
+        const maximumChargeMicros = requestedCeiling ?? undefined;
+        if (file && pick)
+            throw new Error("file writes one selected path; use selection, not pick.");
+        const requestHash = hash(canonical(platformJsonObjectSchema.parse({ tool: sent.tool, arguments: sent.arguments,
+            ...(maximumChargeMicros === undefined ? {} : { maximumChargeMicros }),
+            ...(sent.provider === undefined ? {} : { provider: sent.provider }), ...(sent.relevanceCheck === undefined ? {} : { relevanceCheck: sent.relevanceCheck }),
+            ...(sent.sessionId === undefined ? {} : { sessionId: sent.sessionId }) }))), runId = hash(idempotencyKey);
+        let saved = await this.read(runId);
+        if (saved && saved.requestHash !== requestHash)
+            throw new Error("This run key is bound to another request. Recover the original run instead.");
+        const purchase = async () => {
+            const quoted = (body) => {
+                const quoteInput = { ...body, ...(input.intent ? { intent: input.intent } : {}) };
+                return this.client.quote({ ...quoteInput, ...(maximumChargeMicros === undefined ? {} : { maximumChargeMicros }) }).catch(error => {
+                    if (maximumChargeMicros !== undefined && isApiError(error, "platform_invalid_tool_request"))
+                        return this.client.quote(quoteInput);
+                    throw error;
+                });
+            };
+            let request = sent;
+            const quotedRequest = await quoted(request).catch(error => {
+                const moved = withRunFieldsMoved(error, request);
+                if (!moved)
+                    throw error;
+                request = moved;
+                return quoted(moved);
+            }).catch(async (error) => {
+                const recovered = await this.recover(idempotencyKey, input, requestHash).catch(lookup => {
+                    if (isApiError(lookup, "platform_idempotency_key_used_for_another_request"))
+                        throw lookup;
+                    return null;
+                });
+                if (recovered)
+                    return recovered;
+                throw error;
+            });
+            if ("admitted" in quotedRequest)
+                return quotedRequest;
+            const quote = quotedRequest.data;
+            const external = quote.funding === "provider" || quote.funding === "mixed" || Boolean(quote.externalBillingProviders?.length);
+            const overBudget = maximumChargeMicros !== undefined && quote.maximumChargeMicros > maximumChargeMicros;
+            if (overBudget || external && !externalBillingAccepted) {
+                const recovered = await this.recover(idempotencyKey, input, requestHash);
+                if (recovered)
+                    return recovered;
+                const alternatives = !request.provider && overBudget && maximumChargeMicros !== undefined ? await this.alternatives(request.tool, maximumChargeMicros) : [];
+                return { runId: await this.reference(idempotencyKey), admitted: false, quote,
+                    reason: overBudget ? "The quote exceeds the authorized Relvo ceiling. No execution was submitted." : "External account usage has not been accepted. No execution was submitted.",
+                    ...(external && !externalBillingAccepted ? { next: "If the user already authorized this connected-account or BYOK usage and its external costs or quotas fit that authorization, repeat with externalBillingAccepted:true. Otherwise obtain the missing authorization. maximumChargeMicros caps only Relvo charges. You may also use platform_quote and platform_execute for an explicitly accepted quote; retain the same request and purchase key." } : {}),
+                    ...(alternatives.length ? { alternatives, next: "These are candidate tools, not guaranteed equivalents. Reuse included complete schemas; inspect only missing constraints. Choose only a matching capability and quote/run actual inputs with the listed provider pinned. Example prices never authorize a purchase or a larger task budget." } : {}) };
+            }
+            return savedSchema.parse({ version: 1, requestHash, idempotencyKey, quote,
+                purchase: { ...request, ...quote.plan, ...(input.intent ? { intent: input.intent } : {}), maximumChargeMicros: maximumChargeMicros ?? quote.maximumChargeMicros, priceVersion: quote.priceVersion, runRequestHash: requestHash } });
+        };
+        if (!saved) {
+            const planned = await purchase();
+            if ("admitted" in planned)
+                return planned;
+            saved = await this.persist(runId, planned);
+        }
+        try {
+            return await this.submit(saved, input);
+        }
+        catch (error) {
+            if (!isApiError(error, "platform_quote_changed"))
+                throw error;
+            const planned = await purchase();
+            if ("admitted" in planned)
+                return planned;
+            return this.submit(await this.persist(runId, planned, true), input);
+        }
+    }
+    async resume(raw) {
+        const input = agentResumeSchema.parse(raw);
+        if (input.file && input.pick)
+            throw new Error("file writes one selected path; use selection, not pick.");
+        const reference = recoveryReferencePattern.exec(input.runId), idempotencyKey = reference?.[2];
+        if (reference && reference[1] !== await this.client.requestJournalScope())
+            throw new Error("Saved purchase unavailable in this credential scope. Inspect project history; do not replace unknown work.");
+        if (!reference && !digestSchema.safeParse(input.runId).success)
+            return this.result({ id: input.runId, waitSeconds: input.waitSeconds, ...input.selection, ...(input.pick ? { pick: input.pick } : {}), ...(input.file ? { file: input.file } : {}) });
+        const saved = await this.read(idempotencyKey ? hash(idempotencyKey) : input.runId);
+        if (!saved && idempotencyKey) {
+            const recovered = await this.recover(idempotencyKey, input);
+            if (recovered)
+                return recovered;
+        }
+        if (!saved)
+            throw new Error("Saved purchase unavailable in this credential scope. Inspect project history; do not replace unknown work.");
+        try {
+            return await this.submit(saved, input);
+        }
+        catch (error) {
+            if (!isApiError(error, "platform_quote_changed"))
+                throw error;
+            throw new Error("The price changed before this purchase was admitted, so nothing was bought. Call run again with the same request and idempotency key: it quotes the new price and retains any supplied ceiling.");
+        }
+    }
+    async reference(idempotencyKey) { return `run:${await this.client.requestJournalScope()}:${idempotencyKey}`; }
+    async recover(idempotencyKey, view, requestHash) {
+        const execution = (await this.client.recoverExecution({ idempotencyKey, requestHash })).data.execution;
+        return execution ? this.finish(await this.reference(idempotencyKey), execution, null, view) : null;
+    }
+    async submit(saved, view) {
+        let execution, toppedUp = null;
+        try {
+            execution = (await this.client.createExecution(saved.purchase, saved.idempotencyKey)).data;
+        }
+        catch (error) {
+            if (isApiError(error, "platform_idempotency_key_used_for_another_request")) {
+                const recovered = await this.recover(saved.idempotencyKey, view, saved.requestHash);
+                if (recovered)
+                    return recovered;
+                throw error;
+            }
+            const shortfall = error instanceof Error && error.name === "PlatformApiError" && "shortfall" in error ? platformFundingShortfallSchema.safeParse(error.shortfall).data : undefined;
+            toppedUp = shortfall && this.topUp ? await this.topUp(shortfall) : null;
+            if (!toppedUp)
+                throw error;
+            execution = (await this.client.createExecution(saved.purchase, saved.idempotencyKey)).data;
+        }
+        return this.finish(await this.reference(saved.idempotencyKey), execution, saved.quote, view, toppedUp);
+    }
+    async finish(runId, execution, quote, { waitSeconds, selection, pick, file }, toppedUp = null) {
+        let timedOut = false;
+        if (PENDING.includes(execution.status)) {
+            const waited = await this.client.waitExecution(execution.id, waitSeconds * 1000);
+            timedOut = waited.timedOut;
+            execution = waited.data ?? execution;
+        }
+        const view = { ...this.view(runId, execution, quote, timedOut, selection, pick), ...(toppedUp ? { toppedUp } : {}) };
+        return file && execution.status === "succeeded" ? { ...view, file: await this.exportFile(execution.id, execution.output, selection?.path ?? [], selection?.fields) } : view;
+    }
+    view(runId, execution, quote, timedOut, selection, pick) {
+        return { runId, admitted: true, ...(quote?.plan ? { quote: { plan: quote.plan } } : {}), id: execution.id, status: execution.status, timedOut,
+            reservedMicros: execution.reservedMicros, chargedMicros: ["succeeded", "failed", "cancelled"].includes(execution.status) ? execution.chargedMicros : null,
+            errorCode: execution.errorCode, ...(execution.status === "succeeded" ? { result: agentResultView(execution.output, selection, pick) } : {}),
+            ...(PENDING.includes(execution.status) ? { next: "Still running and paid for: operation:result {id} waits for it again. Answer from it only after it succeeds or fails." } : {}),
+            retained: { readWith: "result", input: { id: execution.id } } };
+    }
+    async exportFile(id, output, requested, requestedFields) {
+        const slice = pathSlice(output, requested), selected = slice?.path ?? requested, fields = slice?.field ? [slice.field] : requestedFields;
+        const located = at(output, selected);
+        if (!located.found)
+            return { found: false, path: selected, shape: shape(output) };
+        const found = located.value ?? null;
+        let value = slice && Array.isArray(found) ? found.slice(slice.start, slice.end) : found, path = selected;
+        if (found !== null && typeof found === "object" && !Array.isArray(found) && !fields?.some(key => Object.hasOwn(found, key))) {
+            const arrays = Object.entries(found).filter(([, child]) => Array.isArray(child));
+            if (arrays.length === 1) {
+                path = [...requested, arrays[0][0]];
+                value = arrays[0][1];
+            }
+        }
+        const rows = Array.isArray(value) ? value.map(row => rowFields(row, fields)) : null;
+        const text = rows ? rows.map(row => JSON.stringify(row) + "\n").join("") : JSON.stringify(rowFields(value, fields)) + "\n";
+        const directory = await this.resultFolder();
+        const rowsOf = slice && Array.isArray(found) && (slice.start > 0 || slice.end !== undefined && slice.end < found.length) ? { rows: [slice.start, slice.end ?? null] } : {};
+        const destination = join(directory, `${hash(id)}-${hash(JSON.stringify({ path, fields: fields ?? [], ...rowsOf })).slice(0, 16)}.${rows ? "jsonl" : "json"}`);
+        const temporary = join(directory, randomUUID() + ".tmp"), file = await open(temporary, "wx", 0o600);
+        try {
+            await file.writeFile(text);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, destination);
+        return { path: destination, format: rows ? "jsonl" : "json", ...(rows ? { rows: rows.length } : {}), bytes: Buffer.byteLength(text), selectedPath: path,
+            use: rows ? "One JSON object per line: filter with jq -c 'select(...)', search with grep, or page with Read." : "Filter with jq or read it with Read." };
+    }
+    async result(raw) {
+        const { id, pick, file, waitSeconds, ...selection } = agentResultSchema.parse(raw);
+        if (file && pick)
+            throw new Error("file writes one selected path; use path and fields, not pick.");
+        let execution = (await this.client.execution(id)).data, timedOut = false;
+        if (PENDING.includes(execution.status)) {
+            const waited = await this.client.waitExecution(id, waitSeconds * 1000);
+            timedOut = waited.timedOut;
+            execution = waited.data ?? execution;
+        }
+        if (execution.status === "succeeded" && file)
+            return { id: execution.id, status: execution.status, file: await this.exportFile(execution.id, execution.output, selection.path, selection.fields) };
+        if (execution.status === "succeeded")
+            return { id: execution.id, status: execution.status, result: agentResultView(execution.output, selection, pick) };
+        const { runId: _runId, admitted: _admitted, timedOut: _timedOut, ...view } = this.view("", execution, null, false);
+        return timedOut ? { ...view, timedOut } : view;
+    }
+}