ocean-crew 0.0.0-stage → 0.4.0

package/dist/host/work/approvals.js

@@ -0,0 +1,290 @@
+// Approvals. A member's group Session is hidden, so DSH's approval card never shows there
+// and the turn would wait forever: Ocean Crew answers those requests itself, from the
+// group chat. A Bot's own chat keeps DSH's card, but Ocean Crew can answer those too
+// (IM chats, the phone app): the request is raced — whichever side answers first wins,
+// and the other card withdraws.
+//
+// arguments hash, target, audience) and the permission revision of the Session it came
+// from. Answering reloads the world first: an expired card, a Session that changed
+// hands, changed permissions, or a mismatched ref is settled as cancelled and refused as
+// stale, so a click can never approve an action other than the one it was shown for.
+import { createHash, randomUUID } from "node:crypto";
+const OUTCOMES = { allow: "allowed-once", reject: "rejected" };
+// A card that waits this long is settled unanswerable; the tool call is asked again.
+const DEFAULT_TTL_MS = 15 * 60_000;
+// A stable hash of the action's arguments: two approvals of the same tool with different
+// arguments must never share a ref, and the same arguments must always hash the same.
+export function argsHashOf(value) {
+    const seen = new Set();
+    const stable = (input) => {
+        if (input === null || typeof input !== "object")
+            return input;
+        if (seen.has(input))
+            return "[circular]";
+        seen.add(input);
+        if (Array.isArray(input))
+            return input.map(stable);
+        const out = {};
+        for (const key of Object.keys(input).sort())
+            out[key] = stable(input[key]);
+        return out;
+    };
+    let text;
+    try {
+        text = JSON.stringify(stable(value) ?? "");
+    }
+    catch {
+        text = String(value);
+    }
+    return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+const refOf = (request, owner, permissionRevision, now, ttlMs) => {
+    const args = request.args ?? request.arguments ?? request.input;
+    const targetInput = request.target;
+    const target = typeof targetInput === "string"
+        ? targetInput
+        : targetInput !== null && typeof targetInput === "object"
+            ? JSON.stringify(targetInput)
+            : undefined;
+    return {
+        ...(typeof request.workId === "string" ? { workId: request.workId } : {}),
+        ...(typeof request.runId === "string" ? { runId: request.runId } : {}),
+        toolCallId: typeof request.callId === "string" ? request.callId : "",
+        argsHash: argsHashOf(args),
+        ...(target !== undefined ? { target } : {}),
+        audience: owner === undefined ? "bot" : "group",
+        ...(permissionRevision !== undefined ? { permissionRevision } : {}),
+        expiry: now + ttlMs,
+    };
+};
+export function install(rt) {
+    const runtime = rt;
+    const { ctx } = rt;
+    const pending = new Map();
+    const approvalListeners = new Set();
+    const onApproval = (listener) => {
+        approvalListeners.add(listener);
+        return () => approvalListeners.delete(listener);
+    };
+    const emit = (kind, data) => {
+        for (const listener of approvalListeners) {
+            try {
+                listener(kind, data);
+            }
+            catch (error) {
+                rt.warn("ocean-crew: approval listener failed: %s", error);
+            }
+        }
+    };
+    const ttlOf = () => {
+        const configured = rt.config?.approvalTtlMs;
+        return typeof configured === "number" && Number.isFinite(configured) && configured > 0
+            ? configured
+            : DEFAULT_TTL_MS;
+    };
+    // Settles an entry: it leaves the pending set, the approval note goes, and listeners
+    // hear how it ended. Idempotent; false when it was already settled elsewhere.
+    const settle = (entry, outcome) => {
+        if (!pending.has(entry.id))
+            return false;
+        pending.delete(entry.id);
+        runtime.noteApproval?.(entry.sessionId, undefined);
+        emit("settled", { id: entry.id, outcome });
+        return true;
+    };
+    // Resolves the DSH request with one outcome: the card withdraws for that answer.
+    const respond = (entry, outcome) => {
+        if (!settle(entry, outcome))
+            return;
+        entry.resolve?.(outcome);
+        entry.cleanup?.();
+    };
+    // The same, settled under a different name for the window (expired, refused).
+    const withdraw = (entry, settledAs) => {
+        if (!pending.has(entry.id))
+            return;
+        pending.delete(entry.id);
+        runtime.noteApproval?.(entry.sessionId, undefined);
+        emit("settled", { id: entry.id, outcome: settledAs });
+        entry.resolve?.("cancelled");
+        entry.cleanup?.();
+    };
+    // Why an open approval can no longer be trusted, or undefined while it still holds.
+    // Checked both by the window's poll (a stale card is withdrawn) and by the answer.
+    const staleReason = (entry, now = Date.now()) => {
+        if (entry.ref.expiry <= now)
+            return "This approval expired; ask for it again.";
+        const owner = runtime.groupOwners.get(entry.sessionId);
+        const chatOwner = runtime.chatOwners.get(entry.sessionId);
+        if (entry.roomId !== undefined && (owner === undefined || owner.roomId !== entry.roomId))
+            return "This approval is no longer open: its group chat changed.";
+        if (entry.roomId === undefined && chatOwner !== entry.botId)
+            return "This approval is no longer open: its conversation changed.";
+        if (entry.ref.permissionRevision !== undefined && typeof runtime.permissionRevision === "function") {
+            const current = runtime.permissionRevision(entry.sessionId);
+            if (current !== entry.ref.permissionRevision)
+                return "The Bot's permissions changed after it asked; ask again.";
+        }
+        return undefined;
+    };
+    const sweep = () => {
+        const now = Date.now();
+        for (const entry of [...pending.values()]) {
+            if (staleReason(entry, now) !== undefined)
+                withdraw(entry, "expired");
+        }
+    };
+    // Ahead of DSH's own answerer, which would hold a hidden Session's request unseen.
+    ctx.on("approval/request", (request, next) => {
+        const sessionId = request.agent?.session?.id ?? request.agent?.id;
+        const owner = sessionId === undefined ? undefined : runtime.groupOwners.get(sessionId);
+        const botId = owner?.botId ?? (sessionId === undefined ? undefined : runtime.chatOwners.get(sessionId));
+        if (botId === undefined || sessionId === undefined)
+            return next();
+        const now = Date.now();
+        const id = randomUUID();
+        const entry = {
+            id,
+            sessionId,
+            botId,
+            ...(owner ? { roomId: owner.roomId } : {}),
+            tool: String(request.toolName ?? ""),
+            reason: String(request.reason ?? "").slice(0, 500),
+            detail: runtime.callDetail?.(sessionId, String(request.callId ?? "")) ?? {},
+            at: now,
+            ref: refOf(request, owner, runtime.permissionRevision?.(sessionId), now, ttlOf()),
+        };
+        pending.set(id, entry);
+        runtime.noteApproval?.(sessionId, { tool: entry.tool, reason: entry.reason.slice(0, 200) });
+        emit("open", { ...entry, answerable: true });
+        if (owner === undefined) {
+            // An own-chat approval races DSH's card. The card sees `linked`, our own
+            // AbortSignal: answering here resolves the request, then withdraws the card;
+            // an answer there settles `next()` first and is adopted. An abort of the
+            // original signal cancels either way.
+            const original = request.signal;
+            const linked = new AbortController();
+            request.signal = linked.signal;
+            return new Promise((resolve, reject) => {
+                const complete = (outcome) => {
+                    respond(entry, outcome);
+                };
+                entry.answer = complete;
+                entry.resolve = (outcome) => resolve(outcome);
+                entry.cleanup = () => {
+                    linked.abort();
+                    if (request.signal === linked.signal)
+                        request.signal = original;
+                };
+                if (original?.aborted)
+                    entry.answer("cancelled");
+                else
+                    original?.addEventListener("abort", () => entry.answer?.("cancelled"), { once: true });
+                Promise.resolve(next()).then((outcome) => {
+                    if (!pending.has(id))
+                        return;
+                    complete(String(outcome));
+                }, 
+                // DSH's answerer threw: close the entry and give the caller the error
+                // the way the pre-race code did, instead of hanging forever.
+                (error) => {
+                    if (!settle(entry, "cancelled"))
+                        return;
+                    reject(error);
+                    entry.cleanup?.();
+                });
+            });
+        }
+        runtime.yieldRoomTurn?.(sessionId);
+        return new Promise((resolve) => {
+            entry.answer = (outcome) => {
+                respond(entry, outcome);
+            };
+            entry.resolve = (outcome) => resolve(outcome);
+            if (request.signal?.aborted)
+                entry.answer("cancelled");
+            request.signal?.addEventListener("abort", () => entry.answer?.("cancelled"), { once: true });
+        });
+    }, { prepend: true });
+    const approvalsView = () => {
+        sweep();
+        return [...pending.values()].map((entry) => {
+            const { answer, resolve: _resolve, cleanup: _cleanup, ...card } = entry;
+            return { ...card, answerable: answer !== undefined };
+        });
+    };
+    const waitsForApproval = (sessionId) => [...pending.values()].some((entry) => entry.sessionId === sessionId);
+    // The user answered a card. The world is reloaded before the answer is applied: the
+    // action must still be the one the card was shown for, with the same permissions and
+    // in the same conversation. A card that no longer holds is withdrawn and refused.
+    function answerApproval(id, choice, expected) {
+        const entry = pending.get(String(id ?? ""));
+        if (entry?.answer === undefined)
+            throw Object.assign(new Error("This approval is no longer open"), { code: "bot/stale" });
+        const outcome = OUTCOMES[choice];
+        if (outcome === undefined)
+            throw Object.assign(new Error("Choose allow or reject"), { code: "bot/invalid" });
+        const stale = staleReason(entry);
+        if (stale !== undefined) {
+            withdraw(entry, "expired");
+            throw Object.assign(new Error(stale), { code: "bot/stale" });
+        }
+        if (expected !== undefined) {
+            if (expected.toolCallId !== undefined && expected.toolCallId !== entry.ref.toolCallId) {
+                withdraw(entry, "mismatched");
+                throw Object.assign(new Error("This card no longer matches the action it was asked for; ask again."), {
+                    code: "bot/stale",
+                });
+            }
+            if (expected.argsHash !== undefined && expected.argsHash !== entry.ref.argsHash) {
+                withdraw(entry, "mismatched");
+                throw Object.assign(new Error("The action changed since this card was shown; ask again."), {
+                    code: "bot/stale",
+                });
+            }
+            if (expected.target !== undefined && expected.target !== entry.ref.target) {
+                withdraw(entry, "mismatched");
+                throw Object.assign(new Error("The target changed since this card was shown; ask again."), {
+                    code: "bot/stale",
+                });
+            }
+            if (expected.permissionRevision !== undefined &&
+                expected.permissionRevision !== entry.ref.permissionRevision) {
+                withdraw(entry, "expired");
+                throw Object.assign(new Error("The Bot's permissions changed after it asked; ask again."), {
+                    code: "bot/stale",
+                });
+            }
+        }
+        entry.answer(outcome);
+    }
+    // A group Session that leaves its group has no card left to answer from.
+    const cancelApprovals = (sessionId) => {
+        for (const entry of pending.values()) {
+            if (entry.sessionId === sessionId)
+                entry.answer?.("cancelled");
+        }
+    };
+    // A permission change after a card was shown invalidates it: the grant cannot outlive
+    // the authority it was asked under. The turn gets `cancelled`, so tightening takes
+    // effect before the action runs.
+    const invalidateApprovals = (sessionIds) => {
+        const wanted = new Set(sessionIds);
+        for (const entry of [...pending.values()]) {
+            if (wanted.has(entry.sessionId))
+                withdraw(entry, "expired");
+        }
+    };
+    // What a turn's work view shows for a Bot waiting on one of its approvals.
+    const approvalFor = (botId) => approvalsView().find((entry) => entry.botId === botId);
+    Object.assign(rt, {
+        approvalsView,
+        waitsForApproval,
+        answerApproval,
+        cancelApprovals,
+        invalidateApprovals,
+        onApproval,
+        approvalFor,
+        approvalRefOf: (entry) => entry.ref,
+    });
+}

package/dist/host/work/avatar-library.js

@@ -0,0 +1,155 @@
+// The avatar library: photos the user imported once, kept in the Bot data folder so the
+// same picture can be picked for several Bots and outlives the Bot that used it. Every
+// image is named by the hash of its bytes, so the same picture is stored once, and the
+// index and the images are written whole, so a half-written file is never read.
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { replaceFile } from "../core/files.js";
+import { avatarBytes } from "./avatar.js";
+const EXTENSIONS = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/webp": "webp",
+    "image/gif": "gif",
+};
+const HASH = /^[0-9a-f]{64}$/;
+const MAX_PHOTOS = 500;
+// How many photos one answer carries. A window asks for the rest when it wants them,
+// so a big library does not become one huge reply.
+const MAX_LISTED = 48;
+const NAME_MAX = 120;
+const INDEX_VERSION = 1;
+const messageOf = (error) => typeof error === "object" && error !== null && "message" in error && typeof error.message === "string"
+    ? error.message
+    : String(error);
+export function install(rt) {
+    const root = typeof rt.home === "string" ? join(rt.home, "avatars") : undefined;
+    const files = root === undefined ? undefined : join(root, "files");
+    const indexPath = root === undefined ? undefined : join(root, "index.json");
+    const fileOf = (entry) => join(files, `${entry.id}.${EXTENSIONS[entry.mime]}`);
+    // One write at a time: two imports that overlap would each read the index, and the
+    // second write would drop what the first one added.
+    let queue = Promise.resolve();
+    const serial = (task) => {
+        const run = queue.then(task, task);
+        queue = run.then(() => { }, () => { });
+        return run;
+    };
+    // The index on disk, with the entries that can be trusted: an id that is a hash, a
+    // known type, and a name that is text.
+    const readIndex = async () => {
+        if (indexPath === undefined)
+            return [];
+        let parsed;
+        try {
+            parsed = JSON.parse(await readFile(indexPath, "utf8"));
+        }
+        catch {
+            return [];
+        }
+        const items = Array.isArray(parsed?.items) ? parsed.items : [];
+        return items
+            .filter((entry) => typeof entry?.id === "string" &&
+            HASH.test(entry.id) &&
+            EXTENSIONS[entry.mime ?? ""] !== undefined)
+            .map((entry) => ({
+            id: entry.id,
+            name: String(entry.name ?? "").slice(0, NAME_MAX),
+            mime: entry.mime,
+            bytes: Number(entry.bytes) || 0,
+            createdAt: Number(entry.createdAt) || 0,
+        }));
+    };
+    const writeIndex = async (items) => {
+        await mkdir(root, { recursive: true });
+        const temp = `${indexPath}.${process.pid}.${randomUUID()}.tmp`;
+        await writeFile(temp, JSON.stringify({ version: INDEX_VERSION, items }, null, 2), "utf8");
+        await replaceFile(temp, indexPath);
+    };
+    const writeImage = async (entry, bytes) => {
+        await mkdir(files, { recursive: true });
+        const path = fileOf(entry);
+        const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+        await writeFile(temp, bytes);
+        await replaceFile(temp, path);
+    };
+    const there = async (path) => stat(path).then(() => true, () => false);
+    // One photo at a time, so a photo that cannot be read does not lose the others. The
+    // picture is checked as an image, and the same bytes are kept once.
+    const importPhotos = (items) => serial(async () => {
+        if (root === undefined)
+            throw new Error("This host keeps no Bot data folder, so it has no avatar library.");
+        const index = await readIndex();
+        const result = { imported: [], duplicates: [], failed: [] };
+        for (const item of items) {
+            const name = String(item?.name ?? "")
+                .trim()
+                .slice(0, NAME_MAX);
+            try {
+                const { bytes, mime } = avatarBytes(item?.image);
+                const id = createHash("sha256").update(bytes).digest("hex");
+                const known = index.find((entry) => entry.id === id);
+                if (known) {
+                    // The same picture again: the one that is there stays, and its file is put
+                    // back when it went missing.
+                    if (!(await there(fileOf(known))))
+                        await writeImage(known, bytes);
+                    result.duplicates.push({ id: known.id, name: known.name });
+                    continue;
+                }
+                if (index.length >= MAX_PHOTOS)
+                    throw new Error(`The avatar library holds at most ${MAX_PHOTOS} photos.`);
+                const entry = {
+                    id,
+                    name: name || "photo",
+                    mime: mime,
+                    bytes: bytes.length,
+                    createdAt: Date.now(),
+                };
+                await writeImage(entry, bytes);
+                await writeIndex([...index, entry]);
+                index.push(entry);
+                result.imported.push(entry);
+            }
+            catch (error) {
+                result.failed.push({ name, message: messageOf(error) });
+            }
+        }
+        return result;
+    });
+    // The photos the user can pick, with the image itself, so the window needs one
+    // request to draw the library. The newest come first, and a library with many photos
+    // is asked for page by page.
+    const libraryView = async ({ offset = 0, limit = MAX_LISTED, } = {}) => {
+        const index = await readIndex();
+        const ordered = [...index].reverse().sort((a, b) => b.createdAt - a.createdAt);
+        const start = Math.max(0, Math.floor(Number(offset)) || 0);
+        const count = Math.min(MAX_LISTED, Math.max(1, Math.floor(Number(limit)) || MAX_LISTED));
+        const items = [];
+        const page = ordered.slice(start, start + count);
+        for (const entry of page) {
+            const bytes = await readFile(fileOf(entry)).catch(() => undefined);
+            if (bytes === undefined)
+                continue;
+            items.push({ ...entry, image: `data:${entry.mime};base64,${bytes.toString("base64")}` });
+        }
+        // The next page starts where this one stopped, even when a photo went missing.
+        return { items, total: ordered.length, next: start + page.length };
+    };
+    // A photo leaves the library; the Bots that use it keep their own copy.
+    const deletePhoto = (id) => serial(async () => {
+        const index = await readIndex();
+        const entry = index.find((item) => item.id === id);
+        if (entry === undefined)
+            return false;
+        await writeIndex(index.filter((item) => item.id !== id));
+        await rm(fileOf(entry), { force: true });
+        return true;
+    });
+    Object.assign(rt, {
+        avatarLibraryView: libraryView,
+        avatarLibraryImport: importPhotos,
+        avatarLibraryDelete: deletePhoto,
+    });
+}

package/dist/host/work/avatar.js

@@ -0,0 +1,132 @@
+// Avatar input for create_bot and update_bot: a local image path or a data URL, read
+// into the data URL a Bot keeps in avatar.image. There is no image library in the host,
+// so images are not resized; a small square image is asked for, and every kind of input
+// is capped at what the stored format holds.
+import { readFile, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { MAX_AVATAR_IMAGE } from "../core/constants.js";
+// Base64 is four characters for every three bytes, and the data URL adds a mime
+// prefix, so a raw image must stay under this to fit MAX_AVATAR_IMAGE once stored.
+const LONGEST_PREFIX = "data:image/jpeg;base64,";
+const MAX_BYTES = Math.floor((MAX_AVATAR_IMAGE - LONGEST_PREFIX.length) / 4) * 3;
+const HINT = "Use a square image; 256x256 is recommended.";
+const MIMES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
+const ascii = (bytes, start, end) => bytes.subarray(start, end).toString("latin1");
+// The real format, from the bytes themselves: an extension, a Content-Type header, or
+// the mime in a data URL can all be wrong.
+function mimeOf(bytes) {
+    if (bytes.length >= 8 && ascii(bytes, 0, 8) === "\x89PNG\r\n\x1a\n")
+        return "image/png";
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return "image/jpeg";
+    if (bytes.length >= 6 && /^GIF8[79]a$/.test(ascii(bytes, 0, 6)))
+        return "image/gif";
+    if (bytes.length >= 12 && ascii(bytes, 0, 4) === "RIFF" && ascii(bytes, 8, 12) === "WEBP")
+        return "image/webp";
+    return undefined;
+}
+const tooLarge = (size) => `The avatar image is too large: ${size} bytes, and the limit is ${MAX_BYTES} bytes (about 120 KB). ${HINT}`;
+const NOT_IMAGE = `The avatar must be a PNG, JPEG, WebP, or GIF image. ${HINT}`;
+function toDataUrl(bytes) {
+    if (bytes.length > MAX_BYTES)
+        throw new Error(tooLarge(bytes.length));
+    const mime = mimeOf(bytes);
+    if (mime === undefined)
+        throw new Error(NOT_IMAGE);
+    const url = `data:${mime};base64,${bytes.toString("base64")}`;
+    if (url.length > MAX_AVATAR_IMAGE)
+        throw new Error(tooLarge(bytes.length));
+    return url;
+}
+const expandHome = (text) => {
+    if (text === "~")
+        return homedir();
+    if (/^~[\\/]/.test(text))
+        return join(homedir(), text.slice(2));
+    return text;
+};
+// The `code` an OS error carries; a thrown value is unknown to TypeScript.
+const errorCode = (error) => {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+};
+const errorMessage = (error) => (error instanceof Error ? error.message : String(error));
+async function readLocal(path, baseDir, isData) {
+    const full = resolve(baseDir ?? process.cwd(), expandHome(path));
+    // Checked and read at the real path, where links lead, so a link cannot reach into
+    // DSH's data, and one changed after the check is not followed.
+    let real;
+    let info;
+    try {
+        real = await realpath(full);
+        info = await stat(real);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            throw new Error(`There is no image file at ${full}. Pass the path of an existing image file.`);
+        throw new Error(`Cannot read the image at ${full}: ${errorCode(error) === "EACCES" ? "permission denied" : errorMessage(error)}`);
+    }
+    if (!info.isFile())
+        throw new Error(`${full} is not an image file. Pass the path of an image file.`);
+    if (await isData?.(real))
+        throw new Error(`${full} is in DeepSeek Harness data, so it cannot be a Bot's photo. Pass an image from another folder.`);
+    if (info.size > MAX_BYTES)
+        throw new Error(tooLarge(info.size));
+    let bytes;
+    try {
+        bytes = await readFile(real);
+    }
+    catch (error) {
+        throw new Error(`Cannot read the image at ${full}: ${errorCode(error) === "EACCES" ? "permission denied" : errorMessage(error)}`);
+    }
+    if (bytes.length > MAX_BYTES)
+        throw new Error(tooLarge(bytes.length));
+    return toDataUrl(bytes);
+}
+function readDataUrl(value) {
+    const comma = value.indexOf(",");
+    if (comma === -1)
+        throw new Error(`The avatar data URL has no comma before its image data. ${HINT}`);
+    const header = value.slice("data:".length, comma);
+    const [mime = "", ...params] = header.split(";").map((part) => part.trim().toLowerCase());
+    if (!MIMES.has(mime))
+        throw new Error(`The avatar data URL must hold a PNG, JPEG, WebP, or GIF image. ${HINT}`);
+    if (!params.includes("base64"))
+        throw new Error("The avatar data URL must be base64 encoded, as in data:image/png;base64,...");
+    const payload = value.slice(comma + 1).replace(/\s/g, "");
+    if (payload === "" || payload.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(payload))
+        throw new Error("The avatar data URL does not hold valid base64 image data.");
+    const bytes = Buffer.from(payload, "base64");
+    return { url: toDataUrl(bytes), bytes, mime: mimeOf(bytes) };
+}
+/** The image behind an avatar data URL: the bytes, the type they really are, and the
+ * canonical data URL. The same checks as for a Bot's own avatar apply. */
+export function avatarBytes(value) {
+    return readDataUrl(String(value ?? ""));
+}
+// module directly from tools.js;
+export function install(rt) {
+    Object.assign(rt, { readAvatar, avatarBytes });
+}
+/** Returns the data URL for avatar.image, or throws with a line the user can read.
+ * `baseDir` is where a relative local path starts, and `isData` says whether a real path
+ * lies in data a Bot may not read from. Links are not fetched: the host would reach
+ * addresses, such as local services, that dsh's own web fetch refuses. */
+export async function readAvatar(input, { baseDir, isData } = {}) {
+    const value = typeof input === "string" ? input.trim() : "";
+    if (value === "")
+        throw new Error(`Give an image path or a data URL. ${HINT}`);
+    if (/^data:/i.test(value))
+        return readDataUrl(value).url;
+    if (/^https?:\/\//i.test(value))
+        throw new Error("An http(s) link is not downloaded here. Save the image to a file and pass its path, or pass a data URL.");
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value))
+        throw new Error(`The avatar must be a local image path or a data URL. ${HINT}`);
+    // A network path (\\host\share) would make Windows connect to that host and sign in.
+    if (/^[\\/]{2}/.test(value))
+        throw new Error("A network path is not read here. Copy the image to this computer and pass its path, or pass a data URL.");
+    return readLocal(value, baseDir, isData);
+}