@timqi/pier 0.0.8 → 0.0.15

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) {
@@ -216,6 +224,15 @@ export class Router {
                     });
                 });
             }
+            // A queued message with no turn left to deliver it. `decide` reads the
+            // state once, so a steer chosen against a turn that ends before the call
+            // lands sits in Pi's queue until some *later* turn reads it — on IM that
+            // is indistinguishable from the message never arriving (§5b). Pi drains
+            // its own queues up to the agent_end handler, so a non-empty queue on an
+            // idle session is exactly the message that missed that window.
+            if (payload.type === "queue-state" && (payload.steering.length || payload.followUp.length)) {
+                this.promoteQueued(session, key);
+            }
             // Every turn-end reaches the channel, empty text included: an adapter's
             // per-turn UI (Telegram's 👀 receipts) is retired here, and a turn that
             // settled with nothing to say still has to settle.
@@ -237,9 +254,69 @@ export class Router {
             unsubscribe,
         });
     }
+    /** Sessions whose queue is being promoted right now. `clearQueue` and the
+     *  prompt that follows it both emit queue-state of their own, so without
+     *  this the handler would re-enter on its own effects. */
+    promoting = new Set();
+    /**
+     * Turn a stranded queue into the turn it was waiting for. Not routed through
+     * `dispatch`: the text was prefixed when it was first dispatched
+     * (identity.ts), and sending it back through would head it a second time.
+     *
+     * Only ever reached from a queue-state event, never from a turn ending: Pi
+     * leaves the queue alone on `abort()`, so promoting on idle would make /stop
+     * start the very turn it was asked to stop. Recovering *those* messages stays
+     * the web's recall route, which hands them back to the composer.
+     */
+    promoteQueued(session, key) {
+        if (session.state !== "idle" || this.promoting.has(session.id))
+            return;
+        this.promoting.add(session.id);
+        void (async () => {
+            try {
+                // Re-read: a turn may have started since the event, and it will drain
+                // the queue itself — clearing it here would take the messages out of it.
+                if (session.state !== "idle")
+                    return;
+                const { steering, followUp } = await session.clearQueue();
+                const text = [...steering, ...followUp].join("\n").trim();
+                if (!text)
+                    return;
+                // A drain is "no new turns", and this would be one. Told to the
+                // conversation rather than dropped, because the message is now out of
+                // the queue and nothing else would ever mention it (§5b).
+                if (this.draining) {
+                    this.report(session.id, key, `queued message not taken — Pier is restarting; send it again: ${truncate(text)}`);
+                    return;
+                }
+                log.info(`promoting ${String(steering.length + followUp.length)} queued message(s) → session ${session.id}`);
+                await session.prompt(text);
+            }
+            catch (err) {
+                this.report(session.id, key, `delivering the queued messages failed: ${String(err)}`);
+            }
+            finally {
+                this.promoting.delete(session.id);
+            }
+        })();
+    }
     async abort(sessionId) {
         await this.bySession.get(sessionId)?.session.abort();
     }
+    /**
+     * Drop what this session was told about who is speaking, so the next message
+     * carries a full header again.
+     *
+     * For the surfaces that take a prefixed message back *out* of the context it
+     * was counted into — a recalled queue, a rewound turn. The tracker's whole
+     * job is "the model has already been told" (identity.ts), and a header that
+     * never reached the model, or reached it and was then rewound away, makes
+     * every later message from that speaker unattributed in a group chat. One
+     * redundant header is the same price eviction already pays.
+     */
+    forgetSender(sessionId) {
+        this.senders.forget(sessionId);
+    }
     /** Refuse new work from every surface; in-flight turns keep running. */
     beginDrain() {
         this.draining = true;
@@ -288,16 +365,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 +380,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 +398,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 +418,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) {
@@ -368,6 +453,9 @@ export class Router {
         // Turn outcomes flow through the event stream; a rejected call surfaces
         // there too, never as a thrown exception across the seam.
         session[action](prompt).catch((err) => {
+            // The header was counted as delivered a line above; this message never
+            // arrived, so the next one from this speaker must carry it again.
+            this.senders.forget(session.id);
             this.report(session.id, msg.key, String(err));
         });
         return { sessionId: session.id };

package/dist/db.js

@@ -166,6 +166,93 @@ 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;
+  `,
+    // 7 — the session listing, so a transcript is read once (agent/listing.ts).
+    `
+  -- One row per session file. (size, mtime) is what makes the row usable
+  -- without opening the file; parsed_bytes is where reading resumes when it
+  -- grew, and is always a line boundary. Derived from disk and disposable: a
+  -- deleted row costs one re-read, never a fact.
+  CREATE TABLE session_index (
+    path TEXT PRIMARY KEY,
+    id TEXT NOT NULL,
+    cwd TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    name TEXT,
+    first_message TEXT,
+    size INTEGER NOT NULL,
+    mtime INTEGER NOT NULL,
+    parsed_bytes INTEGER NOT NULL
+  );
+  `,
+    // 8 — Projects holds a working set: what is warm, plus what is kept.
+    `
+  -- Membership was permanent, so every throwaway session stayed in the rail
+  -- until someone removed it by hand. last_active is the lease: the end of a
+  -- turn renews it, and web/session-state.ts stops listing a row that ran out.
+  -- kept opts one row out of expiry entirely — what the pin control now means.
+  ALTER TABLE session_state ADD COLUMN kept INTEGER NOT NULL DEFAULT 0;
+  ALTER TABLE session_state ADD COLUMN last_active INTEGER;
+  -- Left NULL on purpose: the honest value is when the transcript was last
+  -- written, which only a listing knows. web/server.ts pays one for a database
+  -- carrying rows without it, the same gate the pin backfill already uses, so
+  -- the first rail after an upgrade is dated by use and not by creation.
+  `,
+    // 9 — the summary a transcript already carries is read, not mirrored.
+    `
+  -- Dropped rather than left unread: a column nobody writes still answers when
+  -- somebody selects it, and the next reader has no way to tell a stale title
+  -- from a current one. The pre-migration backup beside the database is the
+  -- way back, not a row of fossils. cwd stays — it is the key a project's
+  -- manual place is stamped on, and it never changes for a session.
+  ALTER TABLE session_state DROP COLUMN title;
+  ALTER TABLE session_state DROP COLUMN created_at;
+  ALTER TABLE session_state DROP COLUMN last_active;
+  `,
+    // 10 — taking a session into Projects is itself an act, and it is dated.
+    `
+  -- When a hand last put this session in Projects (pin, or a keep toggle).
+  -- Not the mirror migration 9 removed: last_active was a copy of a fact the
+  -- transcript owns, while this one exists nowhere else — pinning a cold
+  -- session back is a statement that it is warm again, and without a record of
+  -- *when* it was made the row is dropped by the same read that drew it.
+  -- NULL for every row that predates this: never pinned within a lease.
+  ALTER TABLE session_state ADD COLUMN pinned_at INTEGER;
+  `,
+    // 11 — Projects holds what a hand put there, for as long as the hand says.
+    `
+  -- The lease is gone, so both of its columns are. It expired nothing: a row
+  -- it dropped kept its transcript, its place and its ownership, and one more
+  -- turn brought it back — so what it actually did was hide rows nobody asked
+  -- it to hide, and kept existed only to opt out of that. On the instance this
+  -- was decided on, the lease had never dropped a row: 20 pinned sessions,
+  -- none past seven days, one kept. Removing a row from Projects is the ✓ on
+  -- the row, and it stays the only way out.
+  ALTER TABLE session_state DROP COLUMN kept;
+  ALTER TABLE session_state DROP COLUMN pinned_at;
+  `,
+    // 12 — one row is how two processes take turns (src/tools.ts).
+    `
+  -- The tools sync, held across processes: the token says who holds it, the
+  -- heartbeat says they are still alive. Both processes already open this
+  -- database, and BEGIN IMMEDIATE is real mutual exclusion — a lock file with
+  -- a pid in it is neither, which is what this replaces. One row, because
+  -- there is one thing to serialize; the second lock can bring its own table
+  -- and its own reason for existing.
+  CREATE TABLE tools_sync_lock (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    token TEXT NOT NULL,
+    heartbeat_at INTEGER NOT NULL
+  );
   `,
 ];
 let shared;

package/dist/extensions/index.js

@@ -0,0 +1,37 @@
+// 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.
+ *  Half of one list; src/tools.ts has the other. */
+export const bundledInfo = (enabled) => BUNDLED.map(({ name, summary, tools }) => ({
+    source: "bundled",
+    kind: "extension",
+    name,
+    summary,
+    adds: 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,62 @@
+// 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();
+}
+const digest = (value) => createHash("sha256").update(value).digest("hex").slice(0, 12);
+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";
+    // The URL alone is not the file's identity: a page fetched again is a
+    // different document, and keying on the URL overwrote the copy an older
+    // transcript's `artifactPath` still points at — the one promise this file
+    // makes. Content decides, so a refetch that changed writes a new file and one
+    // that did not costs nothing.
+    const path = join(ARTIFACT_DIR, `${host}-${digest(url.toString())}-${digest(text)}.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;
+}

package/dist/extensions/web/content.js

@@ -0,0 +1,130 @@
+import { isObject } from "./json.js";
+import { languageLabel } from "./language.js";
+/**
+ * The one reader of a cited page, wherever it turns up: an Anthropic search
+ * result, a citation on a text block, a fetch result, an OpenAI action source.
+ * All four spell it `{url, title?}` (OpenAI sometimes as a bare string), all
+ * four had their own copy of this, and they disagreed about the fallback
+ * title. Keyed by url; the first real title wins over a url used as one.
+ */
+export function putSource(into, value) {
+    const url = typeof value === "string"
+        ? value
+        : isObject(value) && typeof value.url === "string"
+            ? value.url
+            : undefined;
+    if (!url)
+        return;
+    const source = isObject(value) ? value : {};
+    const titled = typeof source.title === "string" && source.title;
+    const existing = into.get(url);
+    if (existing && (!titled || existing.title !== existing.url))
+        return;
+    into.set(url, {
+        title: titled || url,
+        url,
+        ...(typeof source.page_age === "string" ? { pageAge: source.page_age } : {}),
+    });
+}
+/** Everything the answer cited: what a fetch was allowed to say it read. */
+export function sourcesFrom(content) {
+    const sources = new Map();
+    const add = (value) => putSource(sources, value);
+    for (const block of content) {
+        if (!isObject(block))
+            continue;
+        if (Array.isArray(block.citations))
+            block.citations.forEach(add);
+        if (block.type === "web_search_tool_result" && Array.isArray(block.content)) {
+            block.content.forEach(add);
+        }
+        if (block.type === "web_fetch_tool_result" && isObject(block.content))
+            add(block.content);
+    }
+    return [...sources.values()].map(({ title, url }) => ({ title, url }));
+}
+/** Only what the search itself returned, in the order it ranked them. */
+export function searchResultsFrom(content) {
+    const results = new Map();
+    for (const block of content) {
+        if (!isObject(block) || block.type !== "web_search_tool_result")
+            continue;
+        if (!Array.isArray(block.content))
+            continue;
+        for (const item of block.content)
+            putSource(results, item);
+    }
+    return [...results.values()];
+}
+export function searchQueriesFrom(content) {
+    const queries = [];
+    for (const block of content) {
+        if (!isObject(block) || block.type !== "server_tool_use" || block.name !== "web_search") {
+            continue;
+        }
+        if (!isObject(block.input) || typeof block.input.query !== "string")
+            continue;
+        queries.push({ query: block.input.query, language: languageLabel(block.input.query) });
+    }
+    return queries;
+}
+export function searchOutcomeFrom(content, model, backend, spent) {
+    return {
+        text: textFrom(content),
+        queries: searchQueriesFrom(content),
+        results: searchResultsFrom(content),
+        model,
+        backend,
+        truncated: spent.stopReason === "max_tokens",
+        usage: spent.usage,
+        errors: spent.errors,
+    };
+}
+export function textFrom(content) {
+    return content
+        .filter((block) => isObject(block) && block.type === "text" && typeof block.text === "string")
+        .map((block) => block.text)
+        .join("\n\n")
+        .trim();
+}
+export function fetchedDocument(content) {
+    for (const block of content) {
+        if (!isObject(block) || block.type !== "web_fetch_tool_result")
+            continue;
+        if (!isObject(block.content))
+            continue;
+        const result = block.content;
+        if (result.type !== "web_fetch_result" || !isObject(result.content))
+            continue;
+        const source = isObject(result.content.source) ? result.content.source : undefined;
+        return {
+            url: typeof result.url === "string" ? result.url : undefined,
+            retrievedAt: typeof result.retrieved_at === "string" ? result.retrieved_at : undefined,
+            text: source?.type === "text" && typeof source.data === "string"
+                ? source.data
+                : undefined,
+        };
+    }
+    return {};
+}
+export function appendSources(text, sources) {
+    if (!sources.length)
+        return text;
+    return `${text}\n\nSources:\n${sources.map(({ title, url }) => `- [${title}](${url})`).join("\n")}`;
+}
+export function formatSearchResult(briefing, results, maxResults, queries) {
+    const queryList = queries
+        .map(({ query, language }, index) => `${index + 1}. [${language}] ${query}`)
+        .join("\n");
+    const listing = results
+        .slice(0, maxResults)
+        .map((result, index) => `${index + 1}. [${result.title}](${result.url})${result.pageAge ? ` — ${result.pageAge}` : ""}`)
+        .join("\n");
+    return [
+        briefing,
+        queryList ? `Queries used:\n${queryList}` : "",
+        listing ? `Search results:\n${listing}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+}