@qearlyao/familiar 0.2.3 → 0.2.5

package/dist/config.js

@@ -2,6 +2,8 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
 import { parse } from "smol-toml";
+import { parseModelRef, resolveProviderSetting } from "./models.js";
+import { readEnum } from "./util/guards.js";
 const loggedConfigWarnings = new Set();
 const DEFAULT_MEMORY_EMBEDDING_BASE_URLS = {
     google: "https://generativelanguage.googleapis.com/v1beta",
@@ -72,88 +74,28 @@ function warnOnce(key, message) {
     loggedConfigWarnings.add(key);
     console.warn(message);
 }
-function readCacheRetention(value, path = "agent.cache_retention") {
-    if (value === "none" || value === "short" || value === "long")
-        return value;
-    throw new Error(`Config value ${path} must be one of "none", "short", or "long"`);
-}
-function readThinkingLevel(value) {
-    if (value === "off" ||
-        value === "minimal" ||
-        value === "low" ||
-        value === "medium" ||
-        value === "high" ||
-        value === "xhigh") {
-        return value;
-    }
-    throw new Error('Config value agent.thinking_level must be one of "off", "minimal", "low", "medium", "high", or "xhigh"');
-}
-function readDiscordReplyMode(value) {
-    if (value === "plain" || value === "reply")
-        return value;
-    throw new Error('Config value discord.reply_mode must be one of "plain" or "reply"');
-}
-function readDiscordChunkMode(value) {
-    if (value === "simple" || value === "paragraph" || value === "newline")
-        return value;
-    throw new Error('Config value discord.chunk_mode must be one of "simple", "paragraph", or "newline"');
-}
-function readDiscordDispatchMode(value, path) {
-    if (value === "steer" || value === "queue" || value === "collect")
-        return value;
-    throw new Error(`Config value ${path} must be one of "steer", "queue", or "collect"`);
-}
-function readDiscordChannelTrigger(value) {
-    if (value === "mention" || value === "always")
-        return value;
-    throw new Error('Config value discord.channel_trigger must be one of "mention" or "always"');
-}
-function readCronFrequency(value, path) {
-    if (value === "once" || value === "hourly" || value === "daily" || value === "weekly" || value === "monthly") {
-        return value;
-    }
-    throw new Error(`Config value ${path} must be one of "once", "hourly", "daily", "weekly", or "monthly"`);
-}
-function readCronDeliveryMode(value, path) {
-    if (value === "queue" || value === "follow_up")
-        return value;
-    throw new Error(`Config value ${path} must be one of "queue" or "follow_up"`);
-}
-function readWebAuthMode(value) {
-    if (value === "tailscale-only" || value === "bearer" || value === "public-2fa")
-        return value;
-    throw new Error('Config value web.auth_mode must be one of "tailscale-only", "bearer", or "public-2fa"');
-}
-function readTtsProvider(value) {
-    if (value === "elevenlabs")
-        return value;
-    throw new Error('Config value tts.provider must be "elevenlabs"');
-}
-function readImageGenApi(value) {
-    if (value === "openrouter-images")
-        return value;
-    throw new Error('Config value image_gen.api must be "openrouter-images"');
-}
-function readMediaUnderstandingProvider(value) {
-    if (value === "groq" || value === "google")
-        return value;
-    throw new Error('Config value media_understanding provider must be "groq" or "google"');
-}
-function readMemoryEmbeddingFormat(value, path = "memory.embedding.format") {
-    if (value === "gemini" || value === "openai" || value === "voyage")
-        return value;
-    throw new Error(`Config value ${path} must be one of "gemini", "openai", or "voyage"`);
-}
-function readBrowserBackend(value) {
-    if (value === "opencli" || value === "browser-harness")
-        return value;
-    throw new Error('Config value browser.backend must be "opencli" or "browser-harness"');
-}
-function readBrowserWindowMode(value) {
-    if (value === "foreground" || value === "background")
-        return value;
-    throw new Error('Config value browser.window must be one of "foreground" or "background"');
-}
+const CACHE_RETENTIONS = ["none", "short", "long"];
+const THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+];
+const DISCORD_REPLY_MODES = ["plain", "reply"];
+const DISCORD_CHUNK_MODES = ["simple", "paragraph", "newline"];
+const DISCORD_DISPATCH_MODES = ["steer", "queue", "collect"];
+const DISCORD_CHANNEL_TRIGGERS = ["mention", "always"];
+const CRON_FREQUENCIES = ["once", "hourly", "daily", "weekly", "monthly"];
+const CRON_DELIVERY_MODES = ["queue", "follow_up"];
+const WEB_AUTH_MODES = ["tailscale-only", "bearer", "public-2fa"];
+const TTS_PROVIDERS = ["elevenlabs"];
+const IMAGE_GEN_APIS = ["openrouter-images"];
+const MEDIA_UNDERSTANDING_PROVIDERS = ["groq", "google"];
+const MEMORY_EMBEDDING_FORMATS = ["gemini", "openai", "voyage"];
+const BROWSER_BACKENDS = ["opencli", "browser-harness"];
+const BROWSER_WINDOW_MODES = ["foreground", "background"];
 function readBoolean(value, fallback, path) {
     if (value === undefined)
         return fallback;
@@ -169,9 +111,6 @@ function readInteger(value, fallback, path, min = 0) {
     }
     return value;
 }
-function resolveProviderSetting(records, provider, model) {
-    return records[`${provider}/${model}`] ?? records[provider];
-}
 function readNumberInRange(value, fallback, path, min, max) {
     if (value === undefined)
         return fallback;
@@ -242,15 +181,8 @@ function parseProviderModelRef(value, path) {
     throw new Error(`Config value ${path} must be a provider/model id`);
 }
 function maybeParseProviderModelRef(value) {
-    const trimmed = value.trim();
-    const separator = trimmed.indexOf("/");
-    if (separator <= 0 || separator === trimmed.length - 1)
-        return undefined;
-    const provider = trimmed.slice(0, separator).trim();
-    const modelId = trimmed.slice(separator + 1).trim();
-    if (!provider || !modelId)
-        return undefined;
-    return { provider, modelId, key: `${provider}/${modelId}` };
+    const parsed = parseModelRef(value);
+    return parsed ? { provider: parsed.provider, modelId: parsed.id, key: parsed.key } : undefined;
 }
 function assertKnownKeys(value, path, knownKeys) {
     const known = new Set(knownKeys);
@@ -308,7 +240,7 @@ function readCronJobs(cron) {
         if (seen.has(id))
             throw new Error(`Duplicate cron job id: ${id}`);
         seen.add(id);
-        const frequency = readCronFrequency(readConfigString(job.frequency, "once", `${prefix}.frequency`), `${prefix}.frequency`);
+        const frequency = readEnum(readConfigString(job.frequency, "once", `${prefix}.frequency`), `${prefix}.frequency`, CRON_FREQUENCIES);
         const runAt = readOptionalConfigString(job.run_at, `${prefix}.run_at`);
         const time = readOptionalConfigString(job.time, `${prefix}.time`);
         assertCronRunAt(runAt, `${prefix}.run_at`);
@@ -326,7 +258,7 @@ function readCronJobs(cron) {
             id,
             enabled: readBoolean(job.enabled, true, `${prefix}.enabled`),
             frequency,
-            deliveryMode: readCronDeliveryMode(readConfigString(job.delivery_mode, "queue", `${prefix}.delivery_mode`), `${prefix}.delivery_mode`),
+            deliveryMode: readEnum(readConfigString(job.delivery_mode, "queue", `${prefix}.delivery_mode`), `${prefix}.delivery_mode`, CRON_DELIVERY_MODES),
             prompt: readString(job.prompt, `${prefix}.prompt`),
             ...(runAt ? { runAt } : {}),
             ...(time ? { time } : {}),
@@ -425,9 +357,9 @@ export async function loadConfig(workspacePathInput) {
         warnOnce("memory.embedding.api", "Config value memory.embedding.api is deprecated; use memory.embedding.format instead.");
         memoryEmbeddingFormatRaw = memoryEmbedding.api;
     }
-    const memoryEmbeddingFormat = readMemoryEmbeddingFormat(readOptionalString(memoryEmbeddingFormatRaw, "gemini"), memoryEmbedding.format === undefined && memoryEmbedding.api !== undefined
+    const memoryEmbeddingFormat = readEnum(readOptionalString(memoryEmbeddingFormatRaw, "gemini"), memoryEmbedding.format === undefined && memoryEmbedding.api !== undefined
         ? "memory.embedding.api"
-        : "memory.embedding.format");
+        : "memory.embedding.format", MEMORY_EMBEDDING_FORMATS);
     const memoryEmbeddingProvider = readConfigString(memoryEmbedding.provider, "google", "memory.embedding.provider");
     const memoryEmbeddingModel = readConfigString(memoryEmbedding.model, "gemini-embedding-2", "memory.embedding.model");
     const memoryEmbeddingBaseUrl = readOptionalConfigString(memoryEmbedding.base_url, "memory.embedding.base_url") ??
@@ -507,29 +439,29 @@ export async function loadConfig(workspacePathInput) {
             token: readString(process.env.DISCORD_TOKEN, "DISCORD_TOKEN"),
             ownerId,
             allowedChannels: readStringArray(discord.allowed_channels, "discord.allowed_channels"),
-            replyMode: readDiscordReplyMode(readOptionalString(discord.reply_mode, "plain")),
-            chunkMode: readDiscordChunkMode(readOptionalString(discord.chunk_mode, "paragraph")),
-            dmMode: readDiscordDispatchMode(readOptionalString(discord.dm_mode, "steer"), "discord.dm_mode"),
-            channelMode: readDiscordDispatchMode(readOptionalString(discord.channel_mode, "collect"), "discord.channel_mode"),
-            channelTrigger: readDiscordChannelTrigger(readOptionalString(discord.channel_trigger, "mention")),
+            replyMode: readEnum(readOptionalString(discord.reply_mode, "plain"), "discord.reply_mode", DISCORD_REPLY_MODES),
+            chunkMode: readEnum(readOptionalString(discord.chunk_mode, "paragraph"), "discord.chunk_mode", DISCORD_CHUNK_MODES),
+            dmMode: readEnum(readOptionalString(discord.dm_mode, "steer"), "discord.dm_mode", DISCORD_DISPATCH_MODES),
+            channelMode: readEnum(readOptionalString(discord.channel_mode, "collect"), "discord.channel_mode", DISCORD_DISPATCH_MODES),
+            channelTrigger: readEnum(readOptionalString(discord.channel_trigger, "mention"), "discord.channel_trigger", DISCORD_CHANNEL_TRIGGERS),
             collectDebounceMs: readInteger(discord.collect_debounce_ms, 4000, "discord.collect_debounce_ms"),
             allowBotMessages: readBoolean(discord.allow_bot_messages, false, "discord.allow_bot_messages"),
         },
         web: {
             port: readInteger(web.port, 8787, "web.port"),
-            authMode: readWebAuthMode(readOptionalString(web.auth_mode, "tailscale-only")),
+            authMode: readEnum(readOptionalString(web.auth_mode, "tailscale-only"), "web.auth_mode", WEB_AUTH_MODES),
             bearerToken: readOptionalString(web.bearer_token, "") || undefined,
             totpSecret: readOptionalString(web.totp_secret, "") || undefined,
             bindAddress: readOptionalString(web.bind_address, "127.0.0.1"),
         },
         browser: {
             enabled: readBoolean(browser.enabled, false, "browser.enabled"),
-            backend: readBrowserBackend(readOptionalString(browser.backend, "opencli")),
+            backend: readEnum(readOptionalString(browser.backend, "opencli"), "browser.backend", BROWSER_BACKENDS),
             opencliCommand: readOptionalString(browser.opencli_command, "opencli"),
             harnessCommand: readOptionalString(browser.harness_command, "browser-harness"),
             session: readOptionalString(browser.session, "familiar"),
             profile: readOptionalString(browser.profile, "") || undefined,
-            windowMode: readBrowserWindowMode(readOptionalString(browser.window, "background")),
+            windowMode: readEnum(readOptionalString(browser.window, "background"), "browser.window", BROWSER_WINDOW_MODES),
             timeoutMs: readInteger(browser.timeout_ms, 60_000, "browser.timeout_ms", 1),
             maxOutputChars: readInteger(browser.max_output_chars, 12_000, "browser.max_output_chars", 1000),
             readWrite: readBoolean(browser.read_write, false, "browser.read_write"),
@@ -542,10 +474,10 @@ export async function loadConfig(workspacePathInput) {
             baseUrl: usingLegacyAgentModel ? baseUrl : undefined,
             apiKeyEnv: usingLegacyAgentModel ? apiKeyEnv : undefined,
             provider: usingLegacyAgentModel ? provider : undefined,
-            cacheRetention: readCacheRetention(readOptionalString(agentCacheRetentionRaw, "long"), agent.cache_retention === undefined && agent.cacheRetention !== undefined
+            cacheRetention: readEnum(readOptionalString(agentCacheRetentionRaw, "long"), agent.cache_retention === undefined && agent.cacheRetention !== undefined
                 ? "agent.cacheRetention"
-                : "agent.cache_retention"),
-            thinkingLevel: readThinkingLevel(readOptionalString(agent.thinking_level, "medium")),
+                : "agent.cache_retention", CACHE_RETENTIONS),
+            thinkingLevel: readEnum(readOptionalString(agent.thinking_level, "medium"), "agent.thinking_level", THINKING_LEVELS),
         },
         heartbeat: {
             enabled: readBoolean(heartbeat.enabled, false, "heartbeat.enabled"),
@@ -563,7 +495,7 @@ export async function loadConfig(workspacePathInput) {
             apiKeyEnvs: modelApiKeyEnvs,
         },
         tts: {
-            provider: readTtsProvider(readOptionalString(tts.provider, "elevenlabs")),
+            provider: readEnum(readOptionalString(tts.provider, "elevenlabs"), "tts.provider", TTS_PROVIDERS),
             apiKeyEnv: readOptionalString(tts.api_key_env, "ELEVENLABS_API_KEY"),
             voiceId: readOptionalString(tts.voice_id, ""),
             modelId: readOptionalString(tts.model_id, "eleven_multilingual_v2"),
@@ -581,17 +513,17 @@ export async function loadConfig(workspacePathInput) {
             enabled: readBoolean(imageGen.enabled, true, "image_gen.enabled"),
             model: readConfigString(imageGen.model, "openrouter/google/gemini-2.5-flash-image", "image_gen.model"),
             fallbackModel: readOptionalConfigString(imageGen.fallback_model, "image_gen.fallback_model"),
-            api: readImageGenApi(readOptionalString(imageGen.api, "openrouter-images")),
+            api: readEnum(readOptionalString(imageGen.api, "openrouter-images"), "image_gen.api", IMAGE_GEN_APIS),
             timeoutMs: readInteger(imageGen.timeout_ms, 120_000, "image_gen.timeout_ms", 1),
         },
         mediaUnderstanding: {
             audio: {
-                provider: readMediaUnderstandingProvider(readOptionalString(mediaUnderstandingAudio.provider, "groq")),
+                provider: readEnum(readOptionalString(mediaUnderstandingAudio.provider, "groq"), "media.understanding.audio.provider", MEDIA_UNDERSTANDING_PROVIDERS),
                 model: readOptionalString(mediaUnderstandingAudio.model, "whisper-large-v3"),
                 apiKeyEnv: readOptionalString(mediaUnderstandingAudio.api_key_env, "GROQ_API_KEY"),
             },
             video: {
-                provider: readMediaUnderstandingProvider(readOptionalString(mediaUnderstandingVideo.provider, "google")),
+                provider: readEnum(readOptionalString(mediaUnderstandingVideo.provider, "google"), "media.understanding.video.provider", MEDIA_UNDERSTANDING_PROVIDERS),
                 model: readOptionalString(mediaUnderstandingVideo.model, "gemini-3-flash-preview"),
                 apiKeyEnv: readOptionalString(mediaUnderstandingVideo.api_key_env, "GEMINI_API_KEY"),
             },

package/dist/contact-note.js

@@ -1,23 +1,13 @@
-import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { readFileOrNull } from "./util/fs.js";
 let contactNotePath = resolve(process.cwd(), "CONTACT.md");
 let cachedNickname = null;
-function isMissingFile(error) {
-    return error instanceof Error && "code" in error && error.code === "ENOENT";
-}
 export function setContactNotePath(path) {
     contactNotePath = path;
     cachedNickname = null;
 }
 export async function loadContactNote() {
-    try {
-        return await readFile(contactNotePath, "utf8");
-    }
-    catch (error) {
-        if (isMissingFile(error))
-            return null;
-        throw error;
-    }
+    return readFileOrNull(contactNotePath, "utf8");
 }
 export function parseContactNickname(raw, fallback) {
     let remaining = raw?.trim() ?? "";

package/dist/data-retention.js

@@ -1,5 +1,6 @@
 import { lstat, readdir, rm } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { isEnoent } from "./util/fs.js";
 export async function runDataRetention(config, now = Date.now()) {
     if (config.data.transcripts.retentionDays > 0) {
         console.warn("data.transcripts.retention_days is configured; transcript replay may lose restart context after retention.");
@@ -49,6 +50,3 @@ async function listFiles(root) {
     }));
     return nested.flat();
 }
-function isEnoent(error) {
-    return !!error && typeof error === "object" && "code" in error && error.code === "ENOENT";
-}

package/dist/discord.js

@@ -7,7 +7,7 @@ import { createAgentEventRecorder, storedAgentEventFromAgentEvent, thinkingDurat
 import { chatChannelKey, createChatLog } from "./chat-log.js";
 import { materializeInboundAttachments, promptImagesFromAttachments } from "./inbound-attachments.js";
 import { ConversationRuntime } from "./runtime.js";
-import { appendSchedulerLog, buildCronInjectionText, buildHeartbeatInjectionText, dueCronSlot, isHeartbeatDue, loadSchedulerState, saveSchedulerState, } from "./scheduler.js";
+import { appendSchedulerLog, buildCronInjectionText, buildHeartbeatInjectionText, dueCronSlot, formatIdleDuration, isHeartbeatDue, loadSchedulerState, saveSchedulerState, } from "./scheduler.js";
 import { parseAgentReply as parseSilentMarker } from "./silent-marker.js";
 const FAMILIAR_COMMAND_NAME = "familiar";
 const THINKING_CHOICES = ["off", "minimal", "low", "medium", "high", "xhigh"];
@@ -917,7 +917,7 @@ export async function startDiscordDaemon(config, familiarAgent, settings, memory
                     schedulerState.heartbeat = { lastFiredAt: new Date(queuedNow).toISOString() };
                     await saveScheduler();
                     const text = buildHeartbeatInjectionText({ now: queuedNow, idleSince: latestUserInteractionAt });
-                    await heartbeatRuntime.noteHeartbeat(`started after ${Math.floor((queuedNow - latestUserInteractionAt) / 60_000)} idle minute(s)`);
+                    await heartbeatRuntime.noteHeartbeat(`heartbeat stirred after ${formatIdleDuration(queuedNow - latestUserInteractionAt)}`);
                     return scheduledUserMessage(text, queuedNow);
                 }, async (event) => {
                     updateAgentEventSummary(summary, event);

package/dist/generated-media.js

@@ -1,5 +1,6 @@
 import { lstat, mkdir, readdir, rm } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
+import { isEnoent } from "./util/fs.js";
 export function createGeneratedMediaSink() {
     const attachments = [];
     return {
@@ -41,7 +42,7 @@ export async function cleanupGeneratedAttachments(config, now = Date.now()) {
         entries = await readdir(dir);
     }
     catch (error) {
-        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
+        if (isEnoent(error))
             return 0;
         throw error;
     }
@@ -52,7 +53,7 @@ export async function cleanupGeneratedAttachments(config, now = Date.now()) {
         if (!fileStat?.isFile() || fileStat.mtimeMs > cutoff)
             continue;
         await rm(path).catch((error) => {
-            if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT"))
+            if (!isEnoent(error))
                 throw error;
         });
         removed++;

package/dist/hot-reload.js

@@ -2,6 +2,7 @@ import { watch } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { basename, relative, resolve, sep } from "node:path";
 import { refreshContactNote } from "./contact-note.js";
+import { isEnoent } from "./util/fs.js";
 const ROOT_FILES = new Set([
     "config.toml",
     ".env",
@@ -13,9 +14,6 @@ const ROOT_FILES = new Set([
     "HEARTBEAT.md",
 ]);
 const SKILLS_DIR = "skills";
-function isEnoent(error) {
-    return !!error && typeof error === "object" && error.code === "ENOENT";
-}
 function shouldReloadForPath(workspacePath, changedPath) {
     const relativePath = relative(workspacePath, resolve(changedPath));
     if (!relativePath || relativePath.startsWith("..") || relativePath.split(sep).includes(".."))

package/dist/image-gen.js

@@ -1,27 +1,23 @@
 import { randomUUID } from "node:crypto";
 import { lstat, writeFile } from "node:fs/promises";
-import { basename, extname, isAbsolute, relative, resolve } from "node:path";
+import { homedir } from "node:os";
+import { basename, isAbsolute, relative, resolve } from "node:path";
 import { findEnvKeys, generateImages, getEnvApiKey, getImageModels, getImageProviders, } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { ensureGeneratedAttachmentsDir } from "./generated-media.js";
 import { ensureInlineImageDerivative } from "./image-derivatives.js";
 import { promptImagesFromAttachments } from "./inbound-attachments.js";
 import { parseModelRef } from "./models.js";
+import { imageMimeTypeFromPath, sniffImageMimeType } from "./util/image-mime.js";
 const IMAGE_GEN_NOTICE_PREFIX = "Generated image attachment:";
 const OPENROUTER_IMAGE_BASE_URL = "https://openrouter.ai/api/v1";
-const IMAGE_MIME_BY_EXTENSION = {
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".png": "image/png",
-    ".gif": "image/gif",
-    ".webp": "image/webp",
-};
 const imageGenSchema = Type.Object({
     prompt: Type.String({ description: "Image generation prompt." }),
     referenceImages: Type.Optional(Type.Array(Type.String(), {
-        description: "Optional. Image attachment IDs or names, or workspace-relative image file paths, to use as visual references. Prefer IDs from the attachment tags when available.",
+        description: "Optional. Image attachment IDs or names, or workspace-relative, absolute, or ~/ image file paths, to use as visual references. Prefer IDs from the attachment tags when available.",
     })),
 }, { additionalProperties: false });
+const MAX_REMOTE_IMAGE_BYTES = 12 * 1024 * 1024;
 function formatImageGenNotice(name) {
     return `${IMAGE_GEN_NOTICE_PREFIX} ${name}`;
 }
@@ -107,20 +103,6 @@ function textOutput(result) {
         .filter(Boolean)
         .join("\n");
 }
-function imageMimeTypeFromBytes(buffer) {
-    if (buffer.subarray(0, 3).equals(Buffer.from([0xff, 0xd8, 0xff])))
-        return "image/jpeg";
-    if (buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
-        return "image/png";
-    }
-    if (buffer.subarray(0, 6).toString("ascii") === "GIF87a" || buffer.subarray(0, 6).toString("ascii") === "GIF89a") {
-        return "image/gif";
-    }
-    if (buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WEBP") {
-        return "image/webp";
-    }
-    return undefined;
-}
 function recoveredImageFromBase64(value) {
     const data = value.trim();
     if (!/^[A-Za-z0-9+/]+={0,2}$/.test(data) || data.length % 4 !== 0)
@@ -128,7 +110,7 @@ function recoveredImageFromBase64(value) {
     const buffer = Buffer.from(data, "base64");
     if (!buffer.length)
         return undefined;
-    const detectedMimeType = imageMimeTypeFromBytes(buffer);
+    const detectedMimeType = sniffImageMimeType(buffer);
     if (!detectedMimeType)
         return undefined;
     return {
@@ -136,7 +118,7 @@ function recoveredImageFromBase64(value) {
         data,
     };
 }
-function recoveredImageFromText(text) {
+function recoveredInlineImageFromText(text) {
     const trimmed = text.trim();
     const dataUrlMatch = trimmed.match(/^data:(image\/[^;]+);base64,([A-Za-z0-9+/]+={0,2})$/);
     if (dataUrlMatch)
@@ -147,7 +129,80 @@ function recoveredImageFromText(text) {
     }
     return recoveredImageFromBase64(trimmed);
 }
-function normalizeCompatibleImageText(result) {
+function imageUrlFromMarkdownText(text) {
+    const match = text.match(/!\[[^\]]*]\((https?:\/\/[^)\s]+)\)/i);
+    if (!match?.[1])
+        return undefined;
+    try {
+        const url = new URL(match[1]);
+        if (url.protocol !== "https:" && url.protocol !== "http:")
+            return undefined;
+        return url;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readBoundedResponseBody(response, maxBytes) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        const buffer = Buffer.from(await response.arrayBuffer());
+        return buffer.byteLength > maxBytes ? undefined : buffer;
+    }
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const chunk = Buffer.from(value);
+            total += chunk.byteLength;
+            if (total > maxBytes)
+                return undefined;
+            chunks.push(chunk);
+        }
+        return Buffer.concat(chunks);
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+async function recoveredImageFromRemoteUrl(url, options) {
+    try {
+        const response = await fetch(url, { signal: options.signal });
+        if (!response.ok)
+            return undefined;
+        const contentLength = Number(response.headers.get("content-length") ?? 0);
+        if (contentLength > MAX_REMOTE_IMAGE_BYTES)
+            return undefined;
+        const bytes = await readBoundedResponseBody(response, MAX_REMOTE_IMAGE_BYTES);
+        if (!bytes)
+            return undefined;
+        const detectedMimeType = sniffImageMimeType(bytes);
+        if (!detectedMimeType)
+            return undefined;
+        return {
+            mimeType: detectedMimeType,
+            data: bytes.toString("base64"),
+        };
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw error;
+        return undefined;
+    }
+}
+async function recoveredImageFromText(text, options) {
+    const inlineImage = recoveredInlineImageFromText(text);
+    if (inlineImage)
+        return inlineImage;
+    const url = imageUrlFromMarkdownText(text);
+    if (!url)
+        return undefined;
+    return recoveredImageFromRemoteUrl(url, options);
+}
+async function normalizeCompatibleImageText(result, options) {
     if (result.output.some((item) => item.type === "image"))
         return result;
     const output = [];
@@ -156,7 +211,7 @@ function normalizeCompatibleImageText(result) {
             output.push(item);
             continue;
         }
-        const recovered = recoveredImageFromText(item.text);
+        const recovered = await recoveredImageFromText(item.text, options);
         if (!recovered) {
             output.push(item);
             continue;
@@ -167,11 +222,12 @@ function normalizeCompatibleImageText(result) {
         return result;
     return { ...result, output };
 }
-function mimeTypeFromPath(path) {
-    return IMAGE_MIME_BY_EXTENSION[extname(path).toLowerCase()];
-}
 function resolveWorkspaceReferencePath(config, rawRef) {
-    const path = isAbsolute(rawRef) ? resolve(rawRef) : resolve(config.workspacePath, rawRef);
+    if (rawRef === "~" || rawRef.startsWith("~/"))
+        return resolve(homedir(), rawRef.slice(2));
+    if (isAbsolute(rawRef))
+        return resolve(rawRef);
+    const path = resolve(config.workspacePath, rawRef);
     const workspaceRelative = relative(config.workspacePath, path);
     if (!workspaceRelative || workspaceRelative.startsWith("..") || isAbsolute(workspaceRelative)) {
         throw new Error(`Reference image path must be inside the workspace: ${rawRef}`);
@@ -190,7 +246,7 @@ async function collectWorkspaceReferenceImages(config, rawRef) {
     }
     if (!pathStat.isFile())
         throw new Error(`Reference image path is not a file or folder: ${rawRef}`);
-    const mimeType = mimeTypeFromPath(path);
+    const mimeType = imageMimeTypeFromPath(path);
     if (!mimeType)
         throw new Error(`Reference image path is not a supported image: ${rawRef}`);
     return [
@@ -327,22 +383,19 @@ async function writeGeneratedImages(config, mediaSink, result) {
 async function tryGenerateImages(config, ref, prompt, references, workspaceRefs, signal, generate) {
     const model = resolveImageModel(config, ref);
     const context = await buildImageContext(model, prompt, references, workspaceRefs, config);
+    const result = await generate(model, context, {
+        apiKey: resolveImageModelApiKey(config, model),
+        signal,
+        timeoutMs: config.imageGen.timeoutMs,
+    });
     return {
         model,
-        result: normalizeCompatibleImageText(await generate(model, context, {
-            apiKey: resolveImageModelApiKey(config, model),
-            signal,
-            timeoutMs: config.imageGen.timeoutMs,
-        })),
+        result: await normalizeCompatibleImageText(result, { signal }),
     };
 }
 function attemptDetails(model, result) {
     return {
-        provider: model.provider,
-        model: model.id,
-        api: model.api,
-        baseUrl: model.baseUrl,
-        ...(result.responseId ? { responseId: result.responseId } : {}),
+        model: `${model.provider}/${model.id}`,
         stopReason: result.stopReason,
         ...(result.errorMessage ? { errorMessage: result.errorMessage } : {}),
     };
@@ -378,18 +431,8 @@ export function createImageGenTool(config, mediaSink, deps = {}) {
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
-                    let baseUrl = "";
-                    try {
-                        baseUrl = resolveImageModel(config, ref).baseUrl;
-                    }
-                    catch {
-                        baseUrl = "";
-                    }
                     attempts.push({
-                        provider: ref.provider,
-                        model: ref.id,
-                        api: config.imageGen.api,
-                        baseUrl,
+                        model: `${ref.provider}/${ref.id}`,
                         stopReason: "error",
                         errorMessage: message,
                     });
@@ -414,8 +457,10 @@ export function createImageGenTool(config, mediaSink, deps = {}) {
             if (!selected)
                 throw new Error(`Image generation failed: ${selectedError}`);
             const attachments = await writeGeneratedImages(config, mediaSink, selected.result);
+            const primaryAttachment = attachments[0];
             const notices = attachments.map((attachment) => formatImageGenNotice(attachment.name));
             const sideText = textOutput(selected.result);
+            const selectedAttempt = attempts.at(-1);
             return {
                 content: [
                     {
@@ -424,15 +469,11 @@ export function createImageGenTool(config, mediaSink, deps = {}) {
                     },
                 ],
                 details: {
-                    provider: selected.model.provider,
-                    model: selected.model.id,
-                    api: selected.model.api,
-                    baseUrl: selected.model.baseUrl,
-                    prompt,
-                    ...(selected.result.responseId ? { responseId: selected.result.responseId } : {}),
+                    model: `${selected.model.provider}/${selected.model.id}`,
                     ...(sideText ? { textOutput: sideText } : {}),
-                    attachments,
-                    attempts,
+                    ...(primaryAttachment ? { id: primaryAttachment.id, localPath: primaryAttachment.localPath } : {}),
+                    stopReason: selectedAttempt?.stopReason ?? selected.result.stopReason,
+                    ...(selectedAttempt?.errorMessage ? { errorMessage: selectedAttempt.errorMessage } : {}),
                 },
             };
         },