@timqi/pier 0.0.8 → 0.0.9

package/README.md

@@ -19,7 +19,7 @@ versioned from `0.0.1` on — earlier databases are not migrated. Read
 - Node 24 or newer (`node:sqlite` is used unflagged)
 - Linux: Python 3, `make` and a C/C++ compiler for `node-pty`
 - A provider account (Anthropic, OpenAI, …) — configure its API key or OAuth
-  login from Console → Settings → Providers after signing in
+  login from Console → Settings → Models after signing in
 - A user-writable global npm prefix if `pier update` should update a service
 - Optional: the `sqlite3` CLI, for backups and password resets
 
@@ -43,10 +43,10 @@ is behind it — there is no default password and no unclaimed window. Lost it?
 Open `http://localhost:3141`, sign in, then:
 
 - **Console → Settings** — everything the instance is configured with, one
-  tab per topic: Providers (API-key/OAuth logins), Models (the menu of
-  favored models agents are advised with), Channels (Slack Socket-Mode or
-  Telegram bot tokens; chats are discovered when the bot first sees traffic,
-  gated by the mention/bind rules you set), Agent files (Pi configuration),
+  tab per topic: Models (API-key/OAuth logins, and the menu of favored models
+  agents are advised with), Agent (Pi configuration, skills, extensions),
+  Channels (Slack Socket-Mode or Telegram bot tokens; chats are discovered
+  when the bot first sees traffic, gated by the mention/bind rules you set),
   plus the public URL, password and master key
 - **New session** — pick a directory; that is where the agent's shell runs
 
@@ -61,17 +61,34 @@ an existing Pi setup:
 PI_CODING_AGENT_DIR="$HOME/.pi/agent" pier serve
 ```
 
+Pier exports that variable for the SDK, so anything it starts inherits it — a
+shell in the Web Terminal included. A second Pier launched from there with its
+own `PIER_HOME` derives its own agent directory rather than adopting the first
+one's; setting `PI_CODING_AGENT_DIR` again on that command line still wins.
+
 Console → Settings is the normal setup path:
 
-- **Providers** configures built-in or custom endpoints and API-key/OAuth login.
-  Stored credentials are sealed in Pier's SQLite database; they are not written
-  back to `models.json`.
-- **Agent files** edits `SYSTEM.md`, `AGENTS.md`, `settings.json`, and advanced
+- **Models** configures built-in or custom endpoints and API-key/OAuth login,
+  then pins the few models this deployment favors. Stored credentials are
+  sealed in Pier's SQLite database; they are not written back to `models.json`.
+  **Test** sends one real request on a model you pick and shows both halves of
+  it — the body as the provider received it, and what came back — so a wrong
+  base URL, a revoked key, a gateway rewriting the request or a model the
+  endpoint never had says so here instead of in a session.
+- **Agent** edits `SYSTEM.md`, `AGENTS.md`, `settings.json`, and advanced
   `models.json` structure in the Pi agent directory — globally, or per project
   scope, where it also shows that project's `.pi/skills` and `.pi/extensions`
   resources. Changes apply when a session next opens; saving here recycles the
   idle ones for you, and **Settings → Instance → Reload** does it for files
   something else changed — an agent, or an editor on the box.
+  The same tab lists the extensions Pier ships with, under Global — they live
+  inside the package, so there is nothing to install and an update never
+  touches your own `extensions` directory, and if an extension of yours
+  already registers the same tool, Pier's copy stands down. `web` is the one
+  shipped today: the public web through the provider's own hosted web tools —
+  `web_search` on an authenticated Anthropic or OpenAI model, `web_fetch` on an
+  Anthropic one (OpenAI hosts no fetch tool), and no other key or service. The
+  page says which tools a switch adds and what each needs before you flip it.
 
 On first credential access, Pier imports an existing `auth.json` into its sealed
 store and renames the source to `auth.json.imported`. Literal provider keys left

package/dist/agent/pi.js

@@ -1,7 +1,8 @@
-// The ONLY file allowed to import @earendil-works/pi-*. Implements the
-// AgentFactory/AgentSession seam from src/core/types.ts on the Pi SDK.
-// No Pi type may appear in an exported signature.
+// The only file outside src/extensions allowed to import @earendil-works/pi-*.
+// Implements the AgentFactory/AgentSession seam from src/core/types.ts on the
+// Pi SDK. No Pi type may appear in an exported signature.
 import { createAgentSession, CredentialSynchronizationError, DefaultResourceLoader, defineTool, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { inlineExtensions } from "../extensions/index.js";
 import { logger } from "../log.js";
 import { toChatTurns, toSessionEvents, turnMetaAt, } from "./events.js";
 import { defaultAgentDir, PiConfigStore } from "./config.js";
@@ -13,6 +14,13 @@ const log = logger("agent");
  * a tool error the agent can retry with an explicit longer timeout, instead of
  * killing the whole run. */
 const BASH_DEFAULT_TIMEOUT_SECONDS = 600;
+/** A probe nobody is watching is a hung page: the Console waits on this. */
+const PROVIDER_CHECK_TIMEOUT_MS = 20_000;
+/** An ordinary budget, not a token: a 1-token cap is a request no real turn
+ *  ever makes, and answers about it are answers about a different request. */
+const PROVIDER_CHECK_MAX_TOKENS = 8192;
+/** Neither half of a probe is worth more than a screen. */
+const clip = (text) => text.length > 4000 ? `${text.slice(0, 4000)}\n[… ${text.length - 4000} more characters]` : text;
 /** Pier's baseline replaces Pi's generic default; a user's SYSTEM.md follows it. */
 const PIER_SYSTEM_PROMPT = `You are a general-purpose agent with a live workspace: you can read and change files and run shell commands. Act with expert care — do the work, verify results, and state what you could not check.
 
@@ -35,6 +43,28 @@ const bashTimeoutDefault = (pi) => {
         }
     });
 };
+/**
+ * A bundled extension stands down when a copy on disk already registers one of
+ * its tools. Pi loads both and reports the clash as a diagnostic nobody reads,
+ * leaving two tools of the same name and no way to tell which one answered;
+ * the copy the user put there wins, and the journal says so (§5b).
+ */
+export const standDownShadowed = (base) => {
+    const inline = (ext) => ext.path.startsWith("<inline:");
+    const onDisk = new Set(base.extensions.filter((ext) => !inline(ext)).flatMap((ext) => [...ext.tools.keys()]));
+    if (!onDisk.size)
+        return base;
+    return {
+        ...base,
+        extensions: base.extensions.filter((ext) => {
+            const clash = inline(ext) && [...ext.tools.keys()].filter((tool) => onDisk.has(tool));
+            if (!clash || !clash.length)
+                return true;
+            log.info(`bundled ${ext.path} stood down — ${clash.join(", ")} already loaded from disk`);
+            return false;
+        }),
+    };
+};
 export class PiSession {
     pi;
     pinned;
@@ -177,6 +207,7 @@ export class PiAgentFactory {
     credentials;
     providerConfig;
     pinned;
+    enabledExtensions;
     constructor(extraTools = [], 
     /** Appended as a virtual context file, so Pi's own prompt stays intact.
      * Read per session, not captured once: it carries settings a user can
@@ -193,13 +224,17 @@ export class PiAgentFactory {
     credentials, providerConfig = new PiConfigStore(), 
     /** Operator-pinned models (Console → Settings → Models), surfaced first in
      * every picker. A getter for the same reason `instructions` is one. */
-    pinned = () => []) {
+    pinned = () => [], 
+    /** Which bundled extensions the Console has switched on. A getter for the
+     * same reason again: the toggle takes effect on the next session open. */
+    enabledExtensions = () => []) {
         this.extraTools = extraTools;
         this.instructions = instructions;
         this.skillPaths = skillPaths;
         this.credentials = credentials;
         this.providerConfig = providerConfig;
         this.pinned = pinned;
+        this.enabledExtensions = enabledExtensions;
     }
     /** One runtime for the whole process; catalogs are global, not per session. */
     catalog;
@@ -276,6 +311,65 @@ export class PiAgentFactory {
             };
         });
     }
+    /**
+     * One real request on the model the operator named. `configured` only ever
+     * meant "a credential is stored", and a wrong base URL, a revoked key, a
+     * gateway rewriting the request and a model this endpoint has never heard of
+     * all look identical until a turn fails hours later.
+     *
+     * The request goes out through a fetch of our own for one reason: what a
+     * provider (or a proxy in front of it) was actually sent, and what it
+     * actually said, is the answer here — a summary of either would be Pier's
+     * word for someone else's.
+     */
+    async check(providerId, modelId) {
+        const started = Date.now();
+        const signal = AbortSignal.timeout(PROVIDER_CHECK_TIMEOUT_MS);
+        let request = "";
+        let body = Promise.resolve("");
+        const recorded = async (input, init) => {
+            request = typeof init?.body === "string" ? init.body : "";
+            const response = await globalThis.fetch(input, init);
+            // Cloned, not consumed: the SDK still needs to read the real stream.
+            body = response.clone().text().then(clip, () => "");
+            return response;
+        };
+        const answered = (text, ok) => ({
+            ok,
+            model: modelId,
+            ms: Date.now() - started,
+            request: clip(request),
+            response: text,
+        });
+        try {
+            const runtime = await this.refreshedRuntime();
+            const model = runtime.getModel(providerId, modelId);
+            if (!model)
+                throw new Error(`unknown model: ${providerId}/${modelId}`);
+            const answer = await runtime.completeSimple(model, { messages: [{ role: "user", content: "hi", timestamp: Date.now() }] }, { maxTokens: PROVIDER_CHECK_MAX_TOKENS, signal, fetch: recorded });
+            // A refusal can arrive as a message rather than a throw; the stop reason
+            // is the only thing separating it from an answer.
+            const refused = answer.stopReason === "error" || answer.stopReason === "aborted";
+            if (refused) {
+                throw new Error(answer.errorMessage ?? `the provider stopped: ${answer.stopReason}`);
+            }
+            const text = answer.content
+                .filter((part) => part.type === "text")
+                .map((part) => part.text)
+                .join("")
+                .trim();
+            // An empty answer is still an answer; say which kind of nothing it was.
+            return answered(clip(text) || `(no text; stop reason: ${answer.stopReason})`, true);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            log.warn(`provider check failed for ${providerId}/${modelId}`, err);
+            const raw = await body;
+            return answered(signal.aborted
+                ? `no answer within ${PROVIDER_CHECK_TIMEOUT_MS / 1000}s (${error})`
+                : raw || error, false);
+        }
+    }
     async setup(input) {
         const builtins = await this.builtinIds();
         if (input.kind === "builtin" && !builtins.has(input.id)) {
@@ -344,7 +438,11 @@ export class PiAgentFactory {
             // Pi's generic default, preserving the user's later instruction layer.
             systemPromptOverride: pierSystemPrompt,
             additionalSkillPaths: this.skillPaths,
-            extensionFactories: [{ name: "pier-bash-timeout", factory: bashTimeoutDefault, hidden: true }],
+            extensionFactories: [
+                { name: "pier-bash-timeout", factory: bashTimeoutDefault, hidden: true },
+                ...inlineExtensions(this.enabledExtensions()),
+            ],
+            extensionsOverride: standDownShadowed,
             agentsFilesOverride: (current) => {
                 const content = this.instructions();
                 return {

package/dist/channels/conversations.js

@@ -29,6 +29,16 @@ export class ConversationStore {
         session_id = excluded.session_id, updated_at = excluded.updated_at
     `).run(key.channelId, key.conversationId, sessionId, Date.now());
     }
+    /** Which channel owns this session, durably — the router's own answer is
+     * in-memory and becomes undefined the moment an idle session is evicted, so
+     * a surface asking "was this turn already delivered to a chat?" long after
+     * the turn cannot use it. Sessions with no row are nobody's conversation. */
+    channelOf(sessionId) {
+        const row = this.db.prepare(`
+      SELECT channel_id FROM conversations WHERE session_id = ? LIMIT 1
+    `).get(sessionId);
+        return row?.channel_id;
+    }
     /** Drop a mapping whose session Pi no longer has, so the next message
      * starts a fresh one instead of failing forever. */
     forget(key) {

package/dist/core/router.js

@@ -17,6 +17,11 @@ const truncate = (message) => message.length > 600 ? `${message.slice(0, 600)}
 function keyOf(key) {
     return `${key.channelId}:${key.conversationId}`;
 }
+/** `web:<id>` and `task:<id>` are two names for one session id, and neither is
+ *  a chat — no Channel is registered under them. So they share a lock in
+ *  `ensure`, and which of the two a session records costs nothing but the
+ *  answer to "what is it answering". */
+const isAlias = (key) => key.channelId === "web" || key.channelId === "task";
 export class Router {
     hub;
     resolve;
@@ -101,6 +106,9 @@ export class Router {
      */
     async evictIdle(ttlMs = IDLE_TTL_MS, now = Date.now(), { includeWatched = false } = {}) {
         let evicted = 0;
+        // Snapshot on purpose: this loop awaits dispose(), so another turn may
+        // attach or drop a session while it is suspended.
+        // oxlint-disable-next-line unicorn/no-useless-spread
         for (const [id, attached] of [...this.bySession]) {
             if (attached.session.state === "streaming")
                 continue;
@@ -162,7 +170,7 @@ export class Router {
         const existing = this.bySession.get(session.id);
         if (existing?.session === session) {
             this.byKey.set(keyOf(key), session);
-            existing.activeAt = Date.now();
+            this.reached(session, key);
             return;
         }
         if (existing) {
@@ -288,16 +296,14 @@ export class Router {
         let session = this.byKey.get(keyOf(key));
         // Web and task conversation ids are session ids. Reuse an attached
         // instance so two surfaces never open the same Pi transcript twice.
-        if (!session && (key.channelId === "web" || key.channelId === "task")) {
+        if (!session && isAlias(key)) {
             session = this.bySession.get(key.conversationId)?.session;
             if (session)
                 this.byKey.set(keyOf(key), session);
         }
         if (!session) {
             // Aliases share one lock: web:<id> and task:<id> must not each open one.
-            const lock = key.channelId === "web" || key.channelId === "task"
-                ? `session:${key.conversationId}`
-                : keyOf(key);
+            const lock = isAlias(key) ? `session:${key.conversationId}` : keyOf(key);
             const inflight = this.opening.get(lock);
             // A second caller rides the first one's resolve — which attaches before
             // this continuation runs, having awaited it first — and registers its own
@@ -305,7 +311,7 @@ export class Router {
             if (inflight) {
                 session = await inflight;
                 this.byKey.set(keyOf(key), session);
-                return this.reached(session);
+                return this.reached(session, key);
             }
             try {
                 // Inside the try: a resolver that throws synchronously is the same
@@ -323,7 +329,7 @@ export class Router {
             }
             this.attach(key, session);
         }
-        return this.reached(session);
+        return this.reached(session, key);
     }
     /** A session that would not open has no event stream of its own to report on
      *  — unless its id is what we were asked for, which is what a web or task key
@@ -343,11 +349,21 @@ export class Router {
             .catch((e) => log.error(`could not report it to ${key.channelId}`, e));
     }
     /** Reached for, so not idle — every surface that uses a session comes
-     *  through `ensure`, including the ones that only read it. */
-    reached(session) {
+     *  through `ensure`, including the ones that only read it.
+     *
+     *  Also where a session learns which of its two aliases is current: a task
+     *  callback (tasks/outbox.ts) opens a workbench session under `task:<id>`
+     *  whenever nothing had it attached, and the key from that first attach used
+     *  to stand forever — so the workbench's own next turn was still "a task",
+     *  and the notification for it (web/push.ts) was never sent. A chat key is
+     *  never overwritten: that one is also where turn-ends are delivered. */
+    reached(session, key) {
         const attached = this.bySession.get(session.id);
-        if (attached)
-            attached.activeAt = Date.now();
+        if (!attached)
+            return session;
+        attached.activeAt = Date.now();
+        if (isAlias(key) && isAlias(attached.key))
+            attached.key = key;
         return session;
     }
     async dispatch(msg) {

package/dist/db.js

@@ -166,6 +166,15 @@ const MIGRATIONS = [
     private_key TEXT NOT NULL,
     created_at INTEGER NOT NULL
   );
+  `,
+    // 6 — Projects keeps the order the workbench was put in, by hand.
+    `
+  -- Manual order, both nullable: a row nobody has dragged sorts on top of the
+  -- list it belongs to, so a fresh database needs no backfill. sort places a
+  -- session inside its project; project_sort places the project, carried on
+  -- every one of its rows because a project is a cwd, not a table.
+  ALTER TABLE session_state ADD COLUMN sort INTEGER;
+  ALTER TABLE session_state ADD COLUMN project_sort INTEGER;
   `,
 ];
 let shared;

package/dist/extensions/index.js

@@ -0,0 +1,34 @@
+// The extensions Pier ships with — the list, and nothing else.
+//
+// An extension is Pi-shaped by construction (it takes an ExtensionAPI), so
+// this area is the second one allowed to import the Pi SDK. Nothing outside
+// agent/ imports it: the Console sees names and summaries, which agent/ hands
+// over as plain data through the ConfigStore seam.
+//
+// Bundled rather than dropped in <agentDir>/extensions because a copy on disk
+// has an owner problem — an update either clobbers the user's edits or skips
+// them forever. These ship inside the package, load as inline factories, and
+// stand down when a copy on disk already registers the same tools.
+import web from "./web/index.js";
+export const BUNDLED = [
+    {
+        name: "web",
+        summary: "The public web through the provider's own hosted web tools — no extra " +
+            "key, no second service, no new dependency.",
+        tools: [
+            { name: "web_search", needs: "an authenticated Anthropic or OpenAI model" },
+            { name: "web_fetch", needs: "an authenticated Anthropic model — OpenAI hosts no fetch tool" },
+        ],
+        factory: web,
+    },
+];
+/** The catalog a surface may show: no Pi types, nothing it cannot render. */
+export const bundledInfo = (enabled) => BUNDLED.map(({ name, summary, tools }) => ({
+    name,
+    summary,
+    tools,
+    enabled: enabled.includes(name),
+}));
+/** The enabled ones as Pi inline extensions; unknown names are not ours. */
+export const inlineExtensions = (enabled) => BUNDLED.filter((ext) => enabled.includes(ext.name))
+    .map(({ name, factory }) => ({ name, factory }));

package/dist/extensions/web/anthropic.js

@@ -0,0 +1,118 @@
+import { postJson } from "./http.js";
+import { isObject } from "./json.js";
+const tokensFrom = (value) => {
+    const usage = isObject(value) ? value : {};
+    const count = (field) => (typeof field === "number" ? field : 0);
+    return { input: count(usage.input_tokens), output: count(usage.output_tokens) };
+};
+const NATIVE_TOOL_TYPES = {
+    web_search: "web_search_20250305",
+    web_fetch: "web_fetch_20250910",
+};
+const findCode = (value) => {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const code = findCode(item);
+            if (code)
+                return code;
+        }
+        return undefined;
+    }
+    if (!isObject(value))
+        return undefined;
+    return typeof value.error_code === "string" ? value.error_code : findCode(value.content);
+};
+/**
+ * Every server-tool failure in the turn. A list, not the first one, and not a
+ * throw: these arrive per invocation — the third search can fail while the
+ * first two are in the transcript and the briefing is written from them. This
+ * used to abort the whole call on any of them, which threw away a good answer
+ * over `max_uses_exceeded`, a code we provoke ourselves by budgeting the
+ * searches the prompt then asks for.
+ */
+function toolErrors(content) {
+    const codes = [];
+    for (const block of content) {
+        if (!isObject(block) || typeof block.type !== "string")
+            continue;
+        if (!block.type.endsWith("_tool_result"))
+            continue;
+        const code = findCode(block.content);
+        if (code)
+            codes.push(`${block.type}: ${code}`);
+    }
+    return [...new Set(codes)];
+}
+/** Whether anything usable came back at all: prose the model wrote, or a tool
+ *  result that is not itself an error. This is what decides failure now. */
+function hasContent(content) {
+    return content.some((block) => {
+        if (!isObject(block) || typeof block.type !== "string")
+            return false;
+        if (block.type === "text")
+            return typeof block.text === "string" && block.text.trim() !== "";
+        if (!block.type.endsWith("_tool_result"))
+            return false;
+        return findCode(block.content) === undefined;
+    });
+}
+export async function callNativeTool(request, name, prompt, options, signal, 
+/** Progress for the surface the call came from: a hosted search is tens of
+ *  seconds of nothing otherwise (§5b). */
+note) {
+    const tool = {
+        type: NATIVE_TOOL_TYPES[name],
+        name,
+        max_uses: options.maxUses,
+    };
+    if (options.allowedDomains?.length)
+        tool.allowed_domains = options.allowedDomains;
+    if (options.blockedDomains?.length)
+        tool.blocked_domains = options.blockedDomains;
+    if (name === "web_fetch") {
+        tool.citations = { enabled: true };
+        tool.max_content_tokens = options.maxContentTokens ?? 20_000;
+    }
+    const messages = [{ role: "user", content: prompt }];
+    const accumulated = [];
+    const spent = { input: 0, output: 0 };
+    for (let continuation = 0; continuation < 3; continuation++) {
+        if (continuation)
+            note?.(`still working — round ${continuation + 1}`);
+        const data = await postJson("Anthropic", request.url, request.headers, {
+            model: request.model,
+            max_tokens: request.maxTokens,
+            messages,
+            tools: [tool],
+            ...(continuation === 0 ? { tool_choice: { type: "tool", name } } : {}),
+        }, signal);
+        if (!Array.isArray(data.content)) {
+            throw new Error("Anthropic returned an invalid Messages response");
+        }
+        accumulated.push(...data.content);
+        const round = tokensFrom(data.usage);
+        spent.input += round.input;
+        spent.output += round.output;
+        if (data.stop_reason === "pause_turn") {
+            messages.push({ role: "assistant", content: data.content });
+            continue;
+        }
+        const errors = toolErrors(accumulated);
+        const used = accumulated.some((block) => isObject(block) &&
+            (block.type === "server_tool_use" || block.type === `${name}_tool_result`));
+        // Only now, with the whole turn in hand, is "this failed" answerable.
+        if (!used)
+            throw new Error(errors.join("; ") || `Claude did not invoke ${name}`);
+        if (!hasContent(accumulated)) {
+            throw new Error(errors.join("; ") || `${name} returned nothing usable`);
+        }
+        return {
+            content: accumulated,
+            model: request.model,
+            ...(typeof data.stop_reason === "string" ? { stopReason: data.stop_reason } : {}),
+            usage: spent,
+            errors,
+        };
+    }
+    throw new Error(`${name} exceeded the continuation limit`);
+}

package/dist/extensions/web/artifacts.js

@@ -0,0 +1,57 @@
+// A fetched page kept whole on disk, so the digest in the transcript is never
+// the only copy: the model gets the distillate, the path gets the document.
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { logger } from "../../log.js";
+import { pierPath } from "../../paths.js";
+const log = logger("web");
+const ARTIFACT_DIR = process.env.PIER_WEB_ARTIFACT_DIR?.trim() ||
+    pierPath("artifacts", "web");
+const RETENTION_DAYS = Number(process.env.PIER_WEB_ARTIFACT_DAYS) || 30;
+/** Retention is measured in days, so sweeping more than hourly is a directory
+ *  walk per fetch buying nothing. Per process; a restart sweeps again. */
+const PRUNE_EVERY_MS = 3_600_000;
+let prunedAt = 0;
+/** Drops expired artifacts and the temp files a crashed run left behind. */
+async function prune() {
+    prunedAt = Date.now();
+    const cutoff = Date.now() - RETENTION_DAYS * 86_400_000;
+    const names = await readdir(ARTIFACT_DIR);
+    await Promise.all(names.map(async (name) => {
+        const file = join(ARTIFACT_DIR, name);
+        const info = await stat(file).catch(() => undefined);
+        if (info?.isFile() && info.mtimeMs < cutoff)
+            await rm(file, { force: true });
+    }));
+}
+function displayUrl(url) {
+    const redacted = new URL(url);
+    for (const key of redacted.searchParams.keys()) {
+        if (/token|key|secret|signature|credential|auth/i.test(key)) {
+            redacted.searchParams.set(key, "REDACTED");
+        }
+    }
+    return redacted.toString();
+}
+export async function saveArtifact(url, text, retrievedAt) {
+    await mkdir(ARTIFACT_DIR, { recursive: true, mode: 0o700 });
+    const host = url.hostname.replace(/[^a-zA-Z0-9.-]+/g, "-").slice(0, 80) || "page";
+    const hash = createHash("sha256").update(url.toString()).digest("hex").slice(0, 16);
+    const path = join(ARTIFACT_DIR, `${host}-${hash}.md`);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    const header = [
+        `Source: ${displayUrl(url)}`,
+        `Retrieved: ${retrievedAt || new Date().toISOString()}`,
+        "",
+    ].join("\n");
+    await writeFile(temporary, `${header}${text}`, { encoding: "utf8", mode: 0o600 });
+    await rename(temporary, path);
+    // Housekeeping must not fail a successful fetch, but it must not vanish either.
+    if (Date.now() - prunedAt >= PRUNE_EVERY_MS) {
+        await prune().catch((error) => {
+            log.warn("artifact prune failed", error);
+        });
+    }
+    return path;
+}