@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/interface/profile-interface.js

@@ -0,0 +1,223 @@
+import { z } from 'zod';
+import { LEXICON_KEYS } from '../guardrails/lexicon.js';
+import { CACHE_MODES, CACHE_TTLS, COMPACTION_METERS, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, KEY_SLOT_NAME, LIVE_ACTIVITY_HANDLINGS, LIVE_END_SENSITIVITIES, LIVE_START_SENSITIVITIES, PROTOCOLS, PROVIDERS, SPEECH_AUDIO_FORMATS, STREAM_MODES, THINKING_LEVELS, } from '../kernel/schema.js';
+import { traceAttributesSchema } from '../observability/trace-schema.js';
+const modelBinding = z.object({
+    protocol: z.enum(PROTOCOLS),
+    provider: z.enum(PROVIDERS),
+    apiId: z.string(),
+    efforts: z.record(z.string(), z.enum(THINKING_LEVELS)).optional(),
+    defaultEffort: z.string().optional(),
+    allowEffortSelect: z.boolean().optional(),
+    summaries: z.boolean().optional(),
+    maxOutputTokens: z.number().optional(),
+    temperature: z.number().optional(),
+    builtInTools: z.array(z.string()).optional(),
+    key: z.string().regex(KEY_SLOT_NAME).optional(),
+    fallbackKey: z.string().regex(KEY_SLOT_NAME).optional(),
+    compaction: z
+        .object({
+        maxTokens: z.number(),
+        compactAt: z.number(),
+        previousExchanges: z.number(),
+        profile: z.string().optional(),
+        timing: z.enum(COMPACTION_TIMINGS),
+        meter: z.enum(COMPACTION_METERS).optional(),
+    })
+        .optional(),
+    cache: z.object({ mode: z.enum(CACHE_MODES), ttl: z.enum(CACHE_TTLS).optional() }).optional(),
+    store: z.boolean().optional(),
+    persistViaInteractionId: z.boolean().optional(),
+    server: z.string().optional(),
+});
+const outputs = z.object({
+    structured: z
+        .union([
+        z.string(),
+        z.object({ by: z.string(), map: z.record(z.string(), z.string()), fallback: z.string() }),
+        z.null(),
+    ])
+        .optional(),
+    streaming: z
+        .object({ mode: z.enum(STREAM_MODES).optional(), streamThoughts: z.boolean().optional() })
+        .optional(),
+});
+const sensitiveGroups = z.object({
+    ids: z.boolean(),
+    financial: z.boolean(),
+    network: z.boolean(),
+    credentials: z.boolean(),
+});
+const urlCheck = z.union([
+    z.literal(false),
+    z.object({ hosts: z.array(z.string()), fromTools: z.boolean() }),
+]);
+const guardrails = z.object({
+    quota: z.object({ perDay: z.number() }).optional(),
+    canary: z.boolean(),
+    sanitizeInput: z.boolean(),
+    redactSensitive: sensitiveGroups,
+    hasEgress: z.boolean(),
+    egressChecks: z
+        .object({
+        sensitive: sensitiveGroups,
+        boundary: z.boolean(),
+        injection: z.boolean(),
+        images: urlCheck,
+        links: urlCheck,
+    })
+        .nullable(),
+});
+const observability = z.object({
+    record: z.boolean(),
+    writeTo: z.union([z.literal(false), z.string()]).optional(),
+    sampleRate: z.number(),
+    include: z.object({
+        upstreamLog: z.boolean(),
+        outboundWire: z.boolean(),
+        evidenceRaw: z.boolean(),
+        usage: z.boolean(),
+        guardrailDecisions: z.boolean(),
+        guardrailMatchPreview: z.boolean(),
+    }),
+    scrub: z.object({ sensitive: z.boolean(), injection: z.boolean(), canary: z.boolean() }),
+    resource: traceAttributesSchema,
+    retainForDays: z.number(),
+    rotateAfterMiB: z.number(),
+    hasOnWriteError: z.boolean(),
+});
+const inputs = z.object({
+    text: z.boolean(),
+    attachments: z.object({ accept: z.array(z.string()), acceptAttr: z.string() }).nullable(),
+    voice: z.object({ accept: z.array(z.string()) }).nullable(),
+    maxFiles: z.number().optional(),
+    maxBytes: z.number().optional(),
+    maxTurnBytes: z.number().optional(),
+    limitsByMime: z.record(z.string(), z.number()).optional(),
+    slots: z.record(z.string(), z.array(z.string())).optional(),
+});
+const resumption = z.object({
+    allowContinue: z.array(z.enum(CONTINUE_STOP_KINDS)).optional(),
+    autoContinue: z.array(z.enum(CONTINUE_STOP_KINDS)).optional(),
+    maxContinues: z.number().optional(),
+});
+const mediaTurnBehaviour = z.object({ resumption: resumption.optional() });
+const tools = z.object({ allow: z.array(z.string()), t2Loader: z.string().optional() });
+const common = {
+    id: z.string(),
+    models: z.record(z.string(), modelBinding),
+    defaultModel: z.string(),
+    allowModelSelect: z.boolean().optional(),
+    maxSteps: z.number().optional(),
+    key: z.string().regex(KEY_SLOT_NAME).optional(),
+    fallbackKey: z.string().regex(KEY_SLOT_NAME).optional(),
+    lexicon: z.partialRecord(z.enum(LEXICON_KEYS), z.string()),
+    guardrails: guardrails.optional(),
+    observability: observability.optional(),
+};
+const systemPrompt = z.union([
+    z.string(),
+    z
+        .array(z.union([z.string(), z.strictObject({ private: z.string().min(1) })]))
+        .min(1)
+        .readonly(),
+]);
+const identity = z.object({
+    handle: z.string(),
+    system: systemPrompt.optional(),
+    systemByRole: z.record(z.string(), systemPrompt).optional(),
+});
+const profileInterface = z.discriminatedUnion('type', [
+    z.object({
+        ...common,
+        type: z.literal('text'),
+        identity,
+        outputs: outputs.optional(),
+        inputs,
+        tools,
+        turnBehaviour: z
+            .object({ resumption: resumption.optional(), allowSteering: z.boolean().optional() })
+            .optional(),
+        canStop: z.literal(true),
+        allowSteering: z.boolean(),
+    }),
+    z.object({
+        ...common,
+        type: z.literal('image'),
+        identity,
+        outputs: outputs.optional(),
+        image: z.object({
+            aspectRatio: z.string().optional(),
+            resolution: z.string().optional(),
+            mimeType: z.string().optional(),
+            quality: z.string().optional(),
+            background: z.string().optional(),
+            n: z.number().int().min(1).optional(),
+            seed: z.number().int().optional(),
+            outputCompression: z.number().int().min(0).max(100).optional(),
+            references: z
+                .array(z.union([
+                z.object({ mimeType: z.string(), data: z.string(), name: z.string().optional() }),
+                z.object({ mimeType: z.string(), uri: z.string(), name: z.string().optional() }),
+            ]))
+                .optional(),
+            includeText: z.boolean().optional(),
+        }),
+        inputs,
+        tools,
+        turnBehaviour: mediaTurnBehaviour.optional(),
+        canStop: z.literal(true),
+    }),
+    z.object({
+        ...common,
+        type: z.literal('speech'),
+        identity: z.object({ handle: z.string() }),
+        outputs: outputs.optional(),
+        speech: z.object({
+            voice: z.string().optional(),
+            format: z.enum(SPEECH_AUDIO_FORMATS).optional(),
+        }),
+        inputs,
+        turnBehaviour: mediaTurnBehaviour.optional(),
+        canStop: z.literal(true),
+    }),
+    z.object({
+        ...common,
+        type: z.literal('live'),
+        identity,
+        live: z.object({
+            ingress: z
+                .object({
+                audio: z.boolean().optional(),
+                video: z.boolean().optional(),
+                text: z.boolean().optional(),
+            })
+                .optional(),
+            voice: z.string().optional(),
+            vad: z
+                .object({
+                activityHandling: z.enum(LIVE_ACTIVITY_HANDLINGS).optional(),
+                startSensitivity: z.enum(LIVE_START_SENSITIVITIES).optional(),
+                endSensitivity: z.enum(LIVE_END_SENSITIVITIES).optional(),
+                prefixPaddingMs: z.number().optional(),
+                silenceDurationMs: z.number().optional(),
+            })
+                .optional(),
+            sessionResumption: z.boolean().optional(),
+            contextCompression: z
+                .object({
+                triggerTokens: z.number().optional(),
+                slidingWindow: z.object({ targetTokens: z.number().optional() }),
+            })
+                .optional(),
+            transcription: z
+                .object({ input: z.boolean().optional(), output: z.boolean().optional() })
+                .optional(),
+        }),
+        tools: z.object({ allow: z.array(z.string()) }),
+        turnBehaviour: z.object({ allowSteering: z.boolean().optional() }).optional(),
+    }),
+]);
+true;
+/** `ProfileInterface`, checked: unnamed fields are dropped, a malformed one fails. */
+export const profileInterfaceSchema = profileInterface;

package/esm/src/interface/session.d.ts

@@ -0,0 +1,64 @@
+import type { ToolGateAuth } from '../kernel/tools/gate-answer.js';
+import type { ToolGate, TurnToolSnapshot } from '../kernel/tools/types.js';
+import type { ModelId, ToolId, TurnEvent, TurnHistoryMessage } from '../kernel/types.js';
+import type { TranscriptBlock, UserTurnDraft } from './types.js';
+export type { ToolGateAuth };
+export type GatedToolContext = {
+    name: string;
+    callId: string;
+    arguments: Record<string, unknown>;
+    /** The call's `ToolCallRequest.thoughtSignature`, for recording the call in history. */
+    thoughtSignature?: string;
+    gateKind: ToolGate['kind'];
+    permission?: ToolGate['permission'];
+    summary?: string;
+    /** Set on a sign-in gate. */
+    auth?: ToolGateAuth;
+};
+export type AwaitingToolContext = {
+    name: string;
+    callId: string;
+    arguments: Record<string, unknown>;
+    kind: string;
+    prompt: string;
+    options?: string[];
+};
+export type InterfaceTurnSession = {
+    history: TurnHistoryMessage[];
+    /** Google Interactions id for server-side continuity; cleared on branch. */
+    previousInteractionId?: string;
+    sessionPermissions: string[];
+    /** Last turn `tokens.input` for compaction meter `timing: 'before'`. */
+    inputTokens?: number;
+    /** Host override for compaction meter `history`. */
+    historyTokens?: number;
+    /** Active pre_tool gate awaiting host resume. */
+    gatedTool: GatedToolContext | null;
+    /** Completed ask_user (or similar) awaiting host UI — turn may already be done. */
+    awaitingTool: AwaitingToolContext | null;
+    /** Kernel events for the assistant segment still in flight (gate / resume / continue). */
+    assistantEvents: TurnEvent[];
+    /** User draft for the turn that produced `assistantEvents`. */
+    pendingUserDraft: UserTurnDraft | null;
+    /** Snapshot from the last gate `done` event — pass to `invokeTool({ snapshot })`. */
+    toolSnapshot?: TurnToolSnapshot;
+    /** T2 tool ids promoted during the current assistant segment (loader `loaded` outputs). */
+    promotedToolIds: ToolId[];
+    /** User-selected model id when `allowModelSelect` is enabled on the profile. */
+    selectedModel?: ModelId;
+    /** Selected effort alias when the active model has `allowEffortSelect`. */
+    selectedEffort?: string;
+};
+declare function emptyInterfaceTurnSession(): InterfaceTurnSession;
+/**
+ * Every call still waiting on its gate, in the order the model made them. One
+ * step can leave several: a gate holds only its own call.
+ */
+declare function gatedToolsFromEvents(events: readonly TurnEvent[]): GatedToolContext[];
+/** The gate the user answers next: the first call still waiting. */
+declare function gatedToolFromEvents(events: readonly TurnEvent[]): GatedToolContext | null;
+declare function awaitingFromEvents(events: readonly TurnEvent[]): AwaitingToolContext | null;
+declare function applyTurnEventsToSession(session: InterfaceTurnSession, events: readonly TurnEvent[]): InterfaceTurnSession;
+/** Drops `previousInteractionId` so the next turn sends the rebuilt history, not a stale handle. */
+declare function branchInterfaceTurnSession(session: InterfaceTurnSession, blocks: readonly TranscriptBlock[]): InterfaceTurnSession;
+export { applyTurnEventsToSession, awaitingFromEvents, branchInterfaceTurnSession, emptyInterfaceTurnSession, gatedToolFromEvents, gatedToolsFromEvents, };

package/esm/src/interface/session.js

@@ -0,0 +1,121 @@
+import { isAwaitingUserInput } from '../kernel/stages.js';
+import { findLast } from '../kernel/util/find-last.js';
+import { historyFromTranscriptBlocks } from './history.js';
+import { toolCallsOf } from './tool-calls.js';
+import { promotedToolIdsFromEvents, toolSnapshotFromEvents } from './tool-invoke.js';
+function emptyInterfaceTurnSession() {
+    return {
+        history: [],
+        sessionPermissions: [],
+        gatedTool: null,
+        awaitingTool: null,
+        assistantEvents: [],
+        pendingUserDraft: null,
+        promotedToolIds: [],
+    };
+}
+/**
+ * Every call still waiting on its gate, in the order the model made them. One
+ * step can leave several: a gate holds only its own call.
+ */
+function gatedToolsFromEvents(events) {
+    const paused = events.some((event) => event.type === 'done' && (event.stop.kind === 'gate' || event.stop.kind === 'tool'));
+    if (!paused)
+        return [];
+    return toolCallsOf(events).flatMap((call) => {
+        if (call.state?.phase !== 'gate')
+            return [];
+        const { gate } = call.state;
+        return [
+            {
+                name: call.name,
+                callId: call.callId,
+                arguments: call.arguments,
+                ...(call.thoughtSignature ? { thoughtSignature: call.thoughtSignature } : {}),
+                gateKind: gate.kind,
+                permission: gate.permission,
+                summary: gate.summary,
+                ...(gate.kind === 'auth'
+                    ? {
+                        auth: {
+                            slot: gate.authChallenge.slot,
+                            authType: gate.authChallenge.authType,
+                            service: gate.authChallenge.service,
+                        },
+                    }
+                    : {}),
+            },
+        ];
+    });
+}
+/** The gate the user answers next: the first call still waiting. */
+function gatedToolFromEvents(events) {
+    return gatedToolsFromEvents(events)[0] ?? null;
+}
+function awaitingFromEvents(events) {
+    const call = findLast(toolCallsOf(events), (c) => c.state?.phase === 'complete');
+    if (call?.state?.phase !== 'complete')
+        return null;
+    const { output } = call.state;
+    if (!isAwaitingUserInput(output))
+        return null;
+    return {
+        name: call.name,
+        callId: call.callId,
+        arguments: call.arguments,
+        kind: output.kind,
+        prompt: output.prompt,
+        options: output.options,
+    };
+}
+function applyTurnEventsToSession(session, events) {
+    let previousInteractionId = session.previousInteractionId;
+    let inputTokens = session.inputTokens;
+    let historyTokens = session.historyTokens;
+    let toolSnapshot = session.toolSnapshot;
+    let promotedToolIds = session.promotedToolIds;
+    for (const event of events) {
+        if ((event.type === 'tokens' || event.type === 'done') && event.interactionId) {
+            previousInteractionId = event.interactionId;
+        }
+        // A call's own input size, not the turn's sum (`done.tokens`).
+        if (event.type === 'tokens' && event.tokens.input) {
+            inputTokens = event.tokens.input;
+        }
+        if (event.type === 'done' && event.compaction?.tokens !== undefined) {
+            historyTokens = event.compaction.tokens;
+        }
+    }
+    const snapshotFromDone = toolSnapshotFromEvents(events);
+    if (snapshotFromDone) {
+        toolSnapshot = snapshotFromDone;
+    }
+    const newPromoted = promotedToolIdsFromEvents(events);
+    if (newPromoted.length > 0) {
+        promotedToolIds = [...new Set([...promotedToolIds, ...newPromoted])];
+    }
+    const gated = gatedToolFromEvents(events);
+    return {
+        ...session,
+        previousInteractionId,
+        inputTokens,
+        historyTokens,
+        gatedTool: gated,
+        awaitingTool: awaitingFromEvents(events),
+        toolSnapshot,
+        promotedToolIds,
+    };
+}
+/** Drops `previousInteractionId` so the next turn sends the rebuilt history, not a stale handle. */
+function branchInterfaceTurnSession(session, blocks) {
+    return {
+        ...emptyInterfaceTurnSession(),
+        history: historyFromTranscriptBlocks(blocks),
+        sessionPermissions: [...session.sessionPermissions],
+        inputTokens: session.inputTokens,
+        historyTokens: session.historyTokens,
+        selectedModel: session.selectedModel,
+        selectedEffort: session.selectedEffort,
+    };
+}
+export { applyTurnEventsToSession, awaitingFromEvents, branchInterfaceTurnSession, emptyInterfaceTurnSession, gatedToolFromEvents, gatedToolsFromEvents, };

package/esm/src/interface/tool-calls.d.ts

@@ -0,0 +1,20 @@
+import type { ToolCallEvent, TurnEvent, TurnEventOf } from '../kernel/types.js';
+import type { ToolCall } from './types.js';
+/**
+ * The raw call comes first for every call (`turnEventSchema`); a phase for a call never made is a
+ * broken stream.
+ */
+declare function applyToolEvent(call: ToolCall | undefined, tool: ToolCallEvent): ToolCall;
+/** Every call in `events`, in the order the model made them. */
+declare function toolCallsOf(events: readonly TurnEvent[]): ToolCall[];
+/** The arguments a call ran with: the user's edit, else the model's. */
+declare function toolCallRanWith(call: ToolCall): Record<string, unknown>;
+/** A tool event that settles its call: the call completed or failed. */
+type SettledToolCallEvent = TurnEventOf<'tool'> & {
+    tool: Extract<ToolCallEvent, {
+        phase: 'complete' | 'error';
+    }>;
+};
+declare function settlesToolCall(event: TurnEvent, callId: string): event is SettledToolCallEvent;
+export type { SettledToolCallEvent };
+export { applyToolEvent, settlesToolCall, toolCallRanWith, toolCallsOf };

package/esm/src/interface/tool-calls.js

@@ -0,0 +1,73 @@
+// The model's raw call is the one owner of a call's arguments. The transcript, the interface
+// session and history read calls through this fold only.
+import { TheoremError } from '../guardrails/error.js';
+/**
+ * The raw call comes first for every call (`turnEventSchema`); a phase for a call never made is a
+ * broken stream.
+ */
+function applyToolEvent(call, tool) {
+    if (tool.phase === undefined) {
+        return {
+            name: tool.name,
+            callId: tool.callId,
+            arguments: tool.arguments,
+            ...(tool.thoughtSignature ? { thoughtSignature: tool.thoughtSignature } : {}),
+            ...(tool.stepId ? { stepId: tool.stepId } : {}),
+            artifacts: [],
+        };
+    }
+    if (call === undefined) {
+        throw new TheoremError('bad_response', `Tool event '${tool.phase}' for call '${tool.callId}' arrived before the call.`);
+    }
+    switch (tool.phase) {
+        case 'running': {
+            // A resumed call runs again: it is open until its next settle.
+            const { endedAt: _settled, ...open } = call;
+            return {
+                ...open,
+                state: tool,
+                startedAt: tool.at,
+                ...(tool.edited ? { edited: tool.edited } : {}),
+                ...(tool.activity ? { activity: tool.activity } : {}),
+            };
+        }
+        case 'complete':
+            return {
+                ...call,
+                state: tool,
+                endedAt: tool.at,
+                ...(tool.activityPast ? { activityPast: tool.activityPast } : {}),
+            };
+        case 'error':
+        case 'cancel':
+        case 'gate':
+            return { ...call, state: tool, endedAt: tool.at };
+        case 'artifact':
+            return { ...call, artifacts: [...call.artifacts, tool.artifact] };
+        case 'progress':
+        case 'trace':
+        case 'warning':
+            return call;
+    }
+}
+/** Every call in `events`, in the order the model made them. */
+function toolCallsOf(events) {
+    const calls = new Map();
+    for (const event of events) {
+        if (event.type !== 'tool')
+            continue;
+        const { tool } = event;
+        calls.set(tool.callId, applyToolEvent(calls.get(tool.callId), tool));
+    }
+    return [...calls.values()];
+}
+/** The arguments a call ran with: the user's edit, else the model's. */
+function toolCallRanWith(call) {
+    return call.edited?.to ?? call.arguments;
+}
+function settlesToolCall(event, callId) {
+    if (event.type !== 'tool' || event.tool.callId !== callId)
+        return false;
+    return event.tool.phase === 'complete' || event.tool.phase === 'error';
+}
+export { applyToolEvent, settlesToolCall, toolCallRanWith, toolCallsOf };

package/esm/src/interface/tool-invoke.d.ts

@@ -0,0 +1,4 @@
+import type { ToolId, TurnEvent, TurnToolSnapshot } from '../kernel/types.js';
+declare function promotedToolIdsFromEvents(events: readonly TurnEvent[]): ToolId[];
+declare function toolSnapshotFromEvents(events: readonly TurnEvent[]): TurnToolSnapshot | undefined;
+export { promotedToolIdsFromEvents, toolSnapshotFromEvents };

package/esm/src/interface/tool-invoke.js

@@ -0,0 +1,20 @@
+import { extractLoadedIds } from '../kernel/tools/resolve.js';
+import { findLast } from '../kernel/util/find-last.js';
+function promotedToolIdsFromEvents(events) {
+    const ids = new Set();
+    for (const event of events) {
+        if (event.type !== 'tool' || event.tool.phase !== 'complete') {
+            continue;
+        }
+        for (const id of extractLoadedIds(event.tool.output) ?? []) {
+            ids.add(id);
+        }
+    }
+    return [...ids];
+}
+function toolSnapshotFromEvents(events) {
+    // Only a `done` that stopped on `tool` or `gate` carries one (`DoneEvent`).
+    const done = findLast(events, (event) => event.type === 'done' && event.tools !== undefined);
+    return done?.type === 'done' ? done.tools : undefined;
+}
+export { promotedToolIdsFromEvents, toolSnapshotFromEvents };

package/esm/src/interface/tool-media.d.ts

@@ -0,0 +1,9 @@
+export type PromotedToolMedia = {
+    url: string;
+    mimeType: string;
+    /** A smaller copy of the same file, when the output also carried one. */
+    previewUrl?: string;
+};
+export declare function promotedMediaFromUrlString(raw: string): PromotedToolMedia | undefined;
+/** One file at several sizes is promoted once: `url` its largest copy, `previewUrl` its smallest. */
+export declare function collectPromotedMediaFromToolOutput(output: unknown): PromotedToolMedia[];

package/esm/src/interface/tool-media.js

@@ -0,0 +1,112 @@
+const EXT_MIME = {
+    avif: 'image/avif',
+    gif: 'image/gif',
+    heic: 'image/heic',
+    heif: 'image/heif',
+    jpeg: 'image/jpeg',
+    jpg: 'image/jpeg',
+    png: 'image/png',
+    svg: 'image/svg+xml',
+    webp: 'image/webp',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    mov: 'video/quicktime',
+    ogv: 'video/ogg',
+    mp3: 'audio/mpeg',
+    m4a: 'audio/mp4',
+    ogg: 'audio/ogg',
+    wav: 'audio/wav',
+};
+function mimeForPathname(pathname) {
+    const base = pathname.split('/').pop() ?? pathname;
+    const dot = base.lastIndexOf('.');
+    if (dot <= 0 || dot === base.length - 1)
+        return undefined;
+    const ext = base.slice(dot + 1).toLowerCase();
+    return EXT_MIME[ext];
+}
+export function promotedMediaFromUrlString(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return undefined;
+    const mimeType = mimeForPathname(parsed.pathname);
+    if (!mimeType)
+        return undefined;
+    return { url: parsed.href, mimeType };
+}
+/** MediaWiki resizes: `…/thumb/<a>/<ab>/<File>/<N>px-<File>` is `<N>` wide; the original is `…/<a>/<ab>/<File>`. */
+const MEDIAWIKI_THUMB = /^(.*)\/thumb(\/.+\/([^/]+))\/(\d+)px-\3(?:\.[a-z0-9]+)?$/i;
+/**
+ * The underlying file, so one picture at several sizes counts once (Wikipedia
+ * summaries carry `thumbnail` and `originalimage`, sometimes on different
+ * wikimedia.org hosts). `width` ranks copies; the original ranks highest.
+ */
+function mediaAsset(url) {
+    const parsed = new URL(url);
+    const site = parsed.hostname.split('.').slice(-2).join('.');
+    // Tracking parameters never change the file; other query parameters may.
+    for (const name of [...parsed.searchParams.keys()]) {
+        if (name.startsWith('utm_'))
+            parsed.searchParams.delete(name);
+    }
+    const thumb = MEDIAWIKI_THUMB.exec(parsed.pathname);
+    const pathname = thumb ? `${thumb[1]}${thumb[2]}` : parsed.pathname;
+    return {
+        key: `${site}${pathname}${parsed.search}`,
+        width: thumb ? Number(thumb[4]) : Number.POSITIVE_INFINITY,
+    };
+}
+/** One file at several sizes is promoted once: `url` its largest copy, `previewUrl` its smallest. */
+export function collectPromotedMediaFromToolOutput(output) {
+    const seen = new Map();
+    const out = [];
+    const visit = (value) => {
+        if (typeof value === 'string') {
+            const media = promotedMediaFromUrlString(value);
+            if (!media)
+                return;
+            const asset = mediaAsset(media.url);
+            const prior = seen.get(asset.key);
+            if (!prior) {
+                seen.set(asset.key, { index: out.length, largest: asset.width, smallest: asset.width });
+                out.push(media);
+                return;
+            }
+            const current = out[prior.index];
+            if (asset.width > prior.largest) {
+                prior.largest = asset.width;
+                out[prior.index] = {
+                    ...current,
+                    url: media.url,
+                    previewUrl: current.previewUrl ?? current.url,
+                };
+            }
+            else if (asset.width < prior.smallest) {
+                prior.smallest = asset.width;
+                out[prior.index] = { ...current, previewUrl: media.url };
+            }
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        if (value !== null && typeof value === 'object') {
+            for (const nested of Object.values(value)) {
+                visit(nested);
+            }
+        }
+    };
+    visit(output);
+    return out;
+}