@noimosai/platform-mcp 0.1.3 → 0.1.5

package/dist/client/agent-run.js

@@ -0,0 +1,1425 @@
+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, platformArtifactSchema, validatePlatformArgumentIdentifiers, } 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";
+import { platformExecutionHasPartialOutput } from "../schema/platformPublicExecution.js";
+import { PLATFORM_META_LIMITS } from "../schema/platformMetaTools.js";
+import { PlatformApiError } from "./browser.js";
+import { platformExecutionGuidance, platformUpstreamRefusalNext, } from "./failure-recovery.js";
+const keySchema = z.string().regex(/^[A-Za-z0-9._:-]{8,128}$/);
+export const RETAINED_READ_MS = 5 * 60 * 1000;
+function lastFinishedExecution() {
+    let kept;
+    return {
+        read: (id) => kept?.execution.id === id && Date.now() < kept.until ? kept.execution : undefined,
+        keep: (execution) => {
+            kept = { until: Date.now() + RETAINED_READ_MS, execution };
+        },
+    };
+}
+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 pickRecordSchema = z
+    .record(z.string().min(1).max(80), pathSchema)
+    .refine((value) => Object.keys(value).length <= 24);
+const picksSchema = z.preprocess((value) => Array.isArray(value)
+    ? Object.fromEntries(value.map((path) => [Array.isArray(path) ? path.join(".") : String(path), path]))
+    : value, pickRecordSchema);
+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(true)
+        .describe("Connected-account and BYOK usage runs by default; false stops before submitting when the user asked to avoid that account's or key's charges or quota use. The Relvo ceiling still applies; this never authorizes sending, publishing or unrelated account changes."),
+    idempotencyKey: keySchema.describe("A new random key, such as a UUID, for every new request, even one repeating an earlier conversation's: a key that already ran returns that run's stored result, not new data. 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 agentParallelSchema = z
+    .object({
+    calls: z
+        .array(z
+        .object(agentRunSchema.shape)
+        .omit({ waitSeconds: true, selection: true, pick: true, file: true })
+        .strict()
+        .superRefine((value, context) => validatePlatformArgumentIdentifiers(value.tool, value.arguments, context)))
+        .min(1)
+        .max(PLATFORM_META_LIMITS.batch)
+        .describe("Independent catalog tool calls. Each needs its own saved key; dependent work belongs in a later call. Returns admission receipts without waiting for completion."),
+    maximumChargeMicros: agentRunSchema.shape.maximumChargeMicros.describe("Optional total Relvo reservation ceiling. When supplied, every call must also have a ceiling and their sum must fit. Omit or use null when none was requested. External charges are separate."),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (new Set(value.calls.map((call) => call.idempotencyKey)).size !== value.calls.length)
+        context.addIssue({
+            code: "custom",
+            path: ["calls"],
+            message: "Each call needs its own retained idempotency key.",
+        });
+    if (value.maximumChargeMicros != null) {
+        if (value.calls.some((call) => call.maximumChargeMicros == null))
+            context.addIssue({
+                code: "custom",
+                path: ["calls"],
+                message: "A total ceiling requires an explicit ceiling on every call.",
+            });
+        else if (value.calls.reduce((sum, call) => sum + BigInt(call.maximumChargeMicros ?? 0), 0n) >
+            BigInt(value.maximumChargeMicros))
+            context.addIssue({
+                code: "custom",
+                path: ["maximumChargeMicros"],
+                message: "Call ceilings exceed the total reservation ceiling.",
+            });
+    }
+    if (Buffer.byteLength(JSON.stringify(value)) > PLATFORM_META_LIMITS.requestBytes)
+        context.addIssue({ code: "custom", message: "Parallel input exceeds its byte limit." });
+});
+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();
+export const agentResultsSchema = z
+    .object({
+    ids: z
+        .array(platformExecutionIdSchema)
+        .min(1)
+        .max(PLATFORM_META_LIMITS.batch)
+        .describe("Execution IDs to read together, such as every executionId a parallel call returned."),
+    ...selectionSchema.shape,
+    pick: agentRunSchema.shape.pick,
+    waitSeconds: agentRunSchema.shape.waitSeconds,
+})
+    .strict();
+const PENDING = ["queued", "running", "waiting"];
+const RESULT_SELECTION_KEYS = [...Object.keys(selectionSchema.shape), "pick"];
+const savedSchema = z
+    .object({
+    version: z.literal(1),
+    requestHash: digestSchema,
+    idempotencyKey: keySchema,
+    quote: platformQuoteSchema,
+    purchase: platformCreateExecutionSchema,
+})
+    .strict();
+const EARLIER_RUN_MS = 10 * 60_000;
+const NO_COMPATIBLE_ALTERNATIVES_NEXT = "No source this project runs could apply these inputs together; sourceRefusals names the inputs each could not apply and the only ones it applies. Run this tool again with just those inputs, dropping one only if the user did not ask for it; an input outside every source's applies is refused the same way. alternatives are tools of the sources it does run, not equivalents: run one, with its provider pinned, only if its own inputs express the request. Otherwise tell the user which condition could not be applied, and offer connecting a provider the tool lists as own_key only if they want it.";
+const DOWNLOAD_NOTE = "Generated files are private and are not in result. Get each one's download URL (valid 5 minutes) with platform_artifact_url {id, artifactId}: platform operation:call on the compact MCP, or relvo artifact-url / relvo download on the CLI. Give the URL only to the user who asked.";
+const EARLIER_RUN_NOTE = "This idempotency key already ran this request at createdAt, so this is that run's stored result, not new data. If the user wants current results, run again with a new idempotency key.";
+export function outputArtifacts(value, depth = 0) {
+    if (depth > 3 || value === null || typeof value !== "object")
+        return [];
+    if (Array.isArray(value))
+        return value.flatMap((item) => outputArtifacts(item, depth + 1));
+    const own = Array.isArray(value.artifacts)
+        ? value.artifacts.flatMap((item) => platformArtifactSchema.safeParse(item).data ?? [])
+        : [];
+    const found = [
+        ...own,
+        ...Object.entries(value).flatMap(([key, child]) => key === "artifacts" ? [] : outputArtifacts(child, depth + 1)),
+    ];
+    return [...new Map(found.map((artifact) => [artifact.id, artifact])).values()];
+}
+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 nestedPath(value, path) {
+    const found = [];
+    let visits = 0;
+    const visit = (node, prefix) => {
+        if (found.length > 1 ||
+            ++visits > 2000 ||
+            prefix.length > 3 ||
+            node === null ||
+            typeof node !== "object")
+            return;
+        if (prefix.length && at(node, path).found) {
+            found.push(prefix);
+            return;
+        }
+        const children = Array.isArray(node)
+            ? node.slice(0, 20).map((child, index) => [String(index), child])
+            : Object.entries(node).slice(0, 64);
+        for (const [key, child] of children)
+            visit(child, [...prefix, key]);
+    };
+    if (path.length)
+        visit(value, []);
+    return found.length === 1 ? [...found[0], ...path] : undefined;
+}
+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 absentFields(rows, fields = []) {
+    const objects = rows.flatMap((row) => row !== null && typeof row === "object" && !Array.isArray(row) ? [row] : []);
+    if (!objects.length || objects.length !== rows.length)
+        return [];
+    return fields.filter((field) => !objects.some((row) => Object.keys(objectFields(row, [field])).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 };
+}
+const FIND_NEEDS_TEXT = "find searches one text and this selection is not one, so this view is not filtered by it. Select a text with path, such as items[0].body, to search it.";
+export function agentResultView(value, raw, picks) {
+    const view = selectedView(value, raw, picks);
+    return selectionSchema.parse(raw ?? {}).find?.length &&
+        !("matches" in view) &&
+        view.found !== false
+        ? { ...view, findNotApplied: FIND_NEEDS_TEXT }
+        : view;
+}
+function selectedView(value, raw, picks, rowsOnly = false) {
+    const rows = picks && !rowsOnly && !raw?.path?.length ? rowPicks(value, picks) : undefined;
+    if (rows)
+        return selectedView(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) {
+        const nested = slice ? undefined : nestedPath(value, input.path);
+        return nested
+            ? {
+                ...selectedView(value, { ...input, limit: requested.limit, path: nested }, picks, rowsOnly),
+                autoSelected: true,
+                requestedPath: input.path,
+            }
+            : { 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 {
+                ...selectedView(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 {
+                ...selectedView(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.",
+        };
+    const absent = !picks && Array.isArray(source)
+        ? absentFields(source, input.fields)
+        : [];
+    if (absent.length && absent.length === input.fields?.length)
+        return {
+            found: false,
+            path: input.path,
+            missing: absent,
+            shape: shape(source),
+            retained: true,
+        };
+    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) },
+            ...(absent.length ? { missing: absent } : {}),
+            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;
+        missing.push(...absent);
+    }
+    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 && (source === null || typeof source !== "object"))
+        missing.push(...(input.fields ?? []));
+    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 };
+}
+const readableByOthers = (mode) => process.platform !== "win32" && (mode & 0o077) !== 0;
+const failureText = (error) => error instanceof Error ? error.message : "The result could not be read.";
+export class AgentRun {
+    client;
+    directory;
+    resultFiles;
+    topUp;
+    retained;
+    constructor(client, directory = join(tmpdir(), `relvo-runs-${process.getuid?.() ?? "user"}`), resultFiles, topUp, retained = lastFinishedExecution()) {
+        this.client = client;
+        this.directory = directory;
+        this.resultFiles = resultFiles;
+        this.topUp = topUp;
+        this.retained = retained;
+    }
+    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 });
+                }
+            }
+            for (const provider of providers
+                .filter((item) => !plans.some((plan) => plan.provider === item.id))
+                .slice(0, 4)) {
+                const candidates = (await this.client.searchTools({
+                    query: definition.title ?? 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() ||
+            readableByOthers(root.mode) ||
+            (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() ||
+            readableByOthers(scoped.mode) ||
+            (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() || readableByOthers(info.mode))
+                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 parallel(raw, signal) {
+        const input = agentParallelSchema.parse(raw), results = new Array(input.calls.length);
+        let next = 0;
+        await Promise.all(Array.from({ length: Math.min(input.calls.length, PLATFORM_META_LIMITS.concurrency) }, async () => {
+            for (let index = next++; index < input.calls.length; index = next++) {
+                const call = input.calls[index], receipt = { index, tool: call.tool, idempotencyKey: call.idempotencyKey };
+                try {
+                    const result = await this.run(call, signal, { waitForCompletion: false });
+                    results[index] =
+                        "id" in result
+                            ? {
+                                ...receipt,
+                                admission: "accepted",
+                                runId: result.runId,
+                                executionId: result.id,
+                                status: result.status,
+                                reservedMicros: result.reservedMicros,
+                                chargedMicros: result.chargedMicros,
+                                ...(result.errorCode ? { errorCode: result.errorCode } : {}),
+                                ...(result.reconnectUrl ? { reconnectUrl: result.reconnectUrl } : {}),
+                                ...("earlierRun" in result ? { earlierRun: result.earlierRun } : {}),
+                                ...platformExecutionGuidance(result),
+                            }
+                            : {
+                                ...receipt,
+                                admission: "rejected",
+                                runId: result.runId,
+                                error: result.reason,
+                            };
+                }
+                catch (error) {
+                    const api = error instanceof PlatformApiError ? error : undefined;
+                    results[index] = {
+                        ...receipt,
+                        admission: api && api.status >= 400 && api.status < 500 && api.status !== 408
+                            ? "rejected"
+                            : "unknown",
+                        error: (api?.guidance ? api.summary : failureText(error)).slice(0, 400),
+                        ...(api?.code ? { errorCode: api.code } : {}),
+                        ...(api?.shortfall ? { shortfall: api.shortfall } : {}),
+                        ...(api?.reconnectUrl ? { reconnectUrl: api.reconnectUrl } : {}),
+                        ...api?.guidance,
+                        ...(api?.billing ? { billing: api.billing } : {}),
+                        ...(api?.billingUrl
+                            ? {
+                                fundingRecovery: {
+                                    billingUrl: api.billingUrl,
+                                    ...(api.shortfall ? { shortfall: api.shortfall } : {}),
+                                },
+                            }
+                            : {}),
+                    };
+                }
+            }
+        }));
+        const recoveryInstructions = {};
+        const receipts = results.map(({ recovery, billing, ...receipt }) => {
+            const compact = { ...receipt };
+            if (recovery) {
+                const { instruction, ...action } = recovery;
+                if (instruction)
+                    recoveryInstructions[recovery.action] = instruction;
+                compact.recovery = action;
+            }
+            if (billing) {
+                const { note: _note, ...charge } = billing;
+                compact.billing = charge;
+            }
+            return compact;
+        });
+        return {
+            allAccepted: results.every((result) => result.admission === "accepted"),
+            results: receipts,
+            ...(Object.keys(recoveryInstructions).length ? { recoveryInstructions } : {}),
+            instruction: "Admission is not completion. Read the accepted executionIds together with one result {ids:[...]}; needs_review still requires approval. For unknown admission repeat the identical call and key, never replace accepted or uncertain work. Dependent calls must wait for their inputs." +
+                (results.some((result) => result.billing)
+                    ? " Report Relvo billing per call; zero is only Relvo's charge. Earlier or external-provider charges remain separate."
+                    : ""),
+        };
+    }
+    async run(raw, signal, options = {}) {
+        const input = agentRunSchema.parse(raw), { waitSeconds, selection, pick, file, idempotencyKey, maximumChargeMicros: requestedCeiling, externalBillingAccepted, intent: _intent, ...sent } = input;
+        const maximumChargeMicros = requestedCeiling ?? undefined;
+        const view = {
+            ...input,
+            signal,
+            waitSeconds: options.waitForCompletion === false ? 0 : waitSeconds,
+            startedAt: Date.now(),
+        };
+        signal?.throwIfAborted();
+        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 }),
+                }, signal)
+                    .catch((error) => {
+                    if (maximumChargeMicros !== undefined &&
+                        isApiError(error, "platform_invalid_tool_request"))
+                        return this.client.quote(quoteInput, signal);
+                    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) => {
+                signal?.throwIfAborted();
+                const recovered = await this.recover(idempotencyKey, view, 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, view, 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."
+                        : "This run declined external account usage (externalBillingAccepted:false). No execution was submitted.",
+                    ...(external && !externalBillingAccepted
+                        ? {
+                            next: "This tool is billed by the connected account or the project's own key. Use a tool Relvo bills instead, or run it with externalBillingAccepted omitted once the user allows that usage; 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, view);
+        }
+        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), view);
+        }
+    }
+    async resume(raw, signal) {
+        const input = agentResumeSchema.parse(raw);
+        const view = { ...input, signal };
+        signal?.throwIfAborted();
+        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 } : {}),
+            }, signal);
+        const saved = await this.read(idempotencyKey ? hash(idempotencyKey) : input.runId);
+        if (!saved && idempotencyKey) {
+            const recovered = await this.recover(idempotencyKey, view);
+            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, view);
+        }
+        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 }, view.signal)).data.execution;
+        return execution ? this.finish(execution.id, execution, null, view) : null;
+    }
+    async submit(saved, view) {
+        let execution, toppedUp = null;
+        try {
+            execution = (await this.client.createExecution(saved.purchase, saved.idempotencyKey, view.signal)).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, view.signal)).data;
+        }
+        return this.finish(execution.id, execution, saved.quote, view, toppedUp);
+    }
+    async finish(runId, execution, quote, { waitSeconds, selection, pick, file, signal, startedAt }, toppedUp = null) {
+        let timedOut = false;
+        if (waitSeconds > 0 && PENDING.includes(execution.status)) {
+            try {
+                const waited = await this.client.waitExecution(execution.id, waitSeconds * 1000, signal);
+                timedOut = waited.timedOut;
+                execution = waited.data ?? execution;
+            }
+            catch {
+                timedOut = true;
+            }
+        }
+        this.keep(execution);
+        const earlier = startedAt !== undefined && Date.parse(execution.createdAt) < startedAt - EARLIER_RUN_MS;
+        const alternatives = execution.status === "failed" && execution.errorCode === "platform_no_compatible_provider"
+            ? await this.alternatives(execution.tool, quote?.maximumChargeMicros ?? execution.reservedMicros ?? 0)
+            : [];
+        const view = {
+            ...this.view(runId, execution, quote, timedOut, selection, pick),
+            ...(toppedUp ? { toppedUp } : {}),
+            ...(earlier
+                ? {
+                    earlierRun: {
+                        createdAt: execution.createdAt,
+                        note: EARLIER_RUN_NOTE,
+                    },
+                }
+                : {}),
+            ...(alternatives.length ? { alternatives, next: NO_COMPATIBLE_ALTERNATIVES_NEXT } : {}),
+        };
+        if (!file || (execution.status !== "succeeded" && !this.hasPartial(execution)))
+            return view;
+        try {
+            return {
+                ...view,
+                file: await this.exportFile(execution.id, execution.output, selection?.path ?? [], selection?.fields),
+            };
+        }
+        catch (error) {
+            return {
+                ...view,
+                fileError: `${failureText(error)} The saved output is retained: result {id} reads it.`,
+            };
+        }
+    }
+    keep(execution) {
+        if (execution.status === "succeeded" || this.hasPartial(execution)) {
+            try {
+                this.retained.keep(execution);
+            }
+            catch {
+            }
+        }
+    }
+    hasPartial(execution) {
+        return platformExecutionHasPartialOutput(execution);
+    }
+    readableResult(execution, selection, pick, partial = false) {
+        try {
+            const result = agentResultView(execution.output, selection, pick);
+            return partial ? { partialResult: result } : { result };
+        }
+        catch (error) {
+            return {
+                resultError: `${failureText(error)} The saved output is retained: result {id} reads it with another selection.`,
+            };
+        }
+    }
+    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.sourceRefusals?.length ? { sourceRefusals: execution.sourceRefusals } : {}),
+            ...(execution.reconnectUrl
+                ? {
+                    reconnectUrl: execution.reconnectUrl,
+                    next: "Show the user reconnectUrl to reconnect the account, then run this again.",
+                }
+                : {}),
+            ...platformExecutionGuidance(execution),
+            ...(execution.status === "succeeded" ? this.readableResult(execution, selection, pick) : {}),
+            ...(this.hasPartial(execution)
+                ? {
+                    ...this.readableResult(execution, selection, pick, true),
+                    next: "The task did not finish. Report partialResult as incomplete saved output, with the failure and charge; do not repeat completed work.",
+                }
+                : {}),
+            ...this.pendingNext(execution),
+            ...this.refusal(execution),
+            ...this.downloads(execution),
+            retained: {
+                readWith: "result",
+                input: { id: execution.id },
+                optionalInput: RESULT_SELECTION_KEYS,
+            },
+        };
+    }
+    pendingNext(execution) {
+        if (!PENDING.includes(execution.status))
+            return {};
+        return execution.rateLimitedUntil
+            ? {
+                rateLimitedUntil: execution.rateLimitedUntil,
+                next: `The app's rate limit holds this call until rateLimitedUntil; it is sent again by itself. Read it with result {id} after that time and do not repurchase. Sending more calls to this app meanwhile only adds refusals.`,
+            }
+            : {
+                next: "Still pending: result {id} (on the CLI, relvo result <id> --wait 60) waits for the same execution. Do not repurchase; answer only after it succeeds or fails.",
+            };
+    }
+    refusal({ upstreamRefusal, reconnectUrl }) {
+        return upstreamRefusal
+            ? {
+                upstreamRefusal,
+                ...(reconnectUrl ? { reconnectUrl } : {}),
+                next: platformUpstreamRefusalNext(upstreamRefusal, reconnectUrl),
+            }
+            : {};
+    }
+    downloads(execution) {
+        const ids = execution.status === "succeeded" || this.hasPartial(execution)
+            ? outputArtifacts(execution.output ?? null).map((artifact) => artifact.id)
+            : [];
+        return ids.length
+            ? {
+                downloads: {
+                    with: "platform_artifact_url",
+                    inputs: ids.map((artifactId) => ({ id: execution.id, artifactId })),
+                    note: DOWNLOAD_NOTE,
+                },
+            }
+            : {};
+    }
+    async exportFile(id, output, requested, requestedFields) {
+        const slice = pathSlice(output, requested), direct = slice?.path ?? requested, fields = slice?.field ? [slice.field] : requestedFields;
+        const first = at(output, direct), nested = first.found || slice ? undefined : nestedPath(output, direct);
+        const selected = nested ?? direct, located = nested ? at(output, nested) : first;
+        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 = [...(nested ?? 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, signal) {
+        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.");
+        return this.readExecution(id, selection, pick, file, waitSeconds * 1000, signal);
+    }
+    async results(raw, signal) {
+        const { ids, pick, waitSeconds, ...selection } = agentResultsSchema.parse(raw);
+        const unique = [...new Set(ids)], until = Date.now() + waitSeconds * 1000, results = new Array(unique.length);
+        let next = 0;
+        await Promise.all(Array.from({ length: Math.min(unique.length, PLATFORM_META_LIMITS.concurrency) }, async () => {
+            for (let index = next++; index < unique.length; index = next++) {
+                const id = unique[index];
+                try {
+                    results[index] = await this.readExecution(id, selection, pick, undefined, Math.max(0, until - Date.now()), signal);
+                }
+                catch (error) {
+                    results[index] = { id, error: failureText(error) };
+                }
+            }
+        }));
+        return { results };
+    }
+    async readExecution(id, selection, pick, file, waitMs, signal) {
+        const retained = this.retained.read(id);
+        if (retained)
+            await this.retained.authorize?.(id);
+        let execution = retained ?? (await this.client.execution(id, signal)).data, timedOut = false;
+        if (waitMs >= 1000 && PENDING.includes(execution.status)) {
+            const waited = await this.client.waitExecution(id, waitMs, signal);
+            timedOut = waited.timedOut;
+            execution = waited.data ?? execution;
+        }
+        if (!retained)
+            this.keep(execution);
+        if (execution.status === "succeeded" && file)
+            return {
+                id: execution.id,
+                status: execution.status,
+                chargedMicros: execution.chargedMicros,
+                file: await this.exportFile(execution.id, execution.output, selection.path, selection.fields),
+                ...this.refusal(execution),
+                ...this.downloads(execution),
+            };
+        if (execution.status === "succeeded")
+            return {
+                id: execution.id,
+                status: execution.status,
+                chargedMicros: execution.chargedMicros,
+                result: agentResultView(execution.output, selection, pick),
+                ...this.refusal(execution),
+                ...this.downloads(execution),
+            };
+        const { runId: _runId, admitted: _admitted, timedOut: _timedOut, ...view } = this.view("", execution, null, false, selection, pick);
+        if (this.hasPartial(execution) && file)
+            return {
+                ...view,
+                file: await this.exportFile(execution.id, execution.output, selection.path, selection.fields),
+            };
+        return timedOut ? { ...view, timedOut } : view;
+    }
+}