@qvac/core 0.0.0 → 0.1.0

package/dist-lib/lib/assistant.js

@@ -0,0 +1,2706 @@
+import defaultFetch from '#fetch';
+import b4a from 'b4a';
+import { AbortController } from 'bare-abort-controller';
+import fs from 'fs';
+import crypto from 'hypercore-crypto';
+import os from 'os';
+import path from 'path';
+import { attachmentTurn, skillLoadedTurn } from '@qvac/harness/lib/capabilities/tool-turns.ts';
+import { diffusionDownloadName, mediaModelNameFor } from '@qvac/harness/lib/models/model-catalog.ts';
+import { readSetup as normalizeSkillSetup } from '@qvac/harness/lib/tools/skills/manifest-parse.ts';
+import { SKILL_STATE } from '@qvac/harness/lib/tools/skills/skill-state.ts';
+import { toolsetEnabled } from '@qvac/harness/lib/tools/toolsets.ts';
+import { RAG_CITATION_LINE } from '@qvac/harness/lib/prompt.ts';
+import { acceptedRepairCount, historyBranches, isPromptChunk } from "./core/prompt-history.js";
+import ReadyGuard from 'ready-guard';
+import ReadyResource from 'ready-resource';
+import { local } from '../spec/index.js';
+import { isMeshTransition } from "./api/current-mesh.js";
+import { buildTitlePrompt, deriveChatTitle, isDefaultChatTitle, parseTitleResponse } from "./chat-title.js";
+import { matchApprovalRule } from "./core/approval-rules.js";
+import { attachTurnDocumentIds, groupAttachmentsByMessage, formatRagContext, chooseRagNotice, RAG_KNOWLEDGE_OFF_NOTICE, RAG_TRUNCATED_NOTICE, RAG_UNAVAILABLE_NOTICE, createRagSourceTagFilter, citedByPhraseOverlap, formatFullDocumentContext, isFullTextHit, isTruncatedFullTextHit, sourcesFromHits, WEB_TOOLS, webSourcesFromToolResult, withoutDataChannel } from "./core/files/index.js";
+import { isAudioAttachment } from "./core/audio-attachment.js";
+import { annotateDocumentAttachments, documentUnreadNotice, documentUnreadReason, isDocumentAttachment } from "./core/document-attachment.js";
+import { HISTORY_CHUNK_TYPES } from "./core/chunk.js";
+import { imageCacheName, sweepImageCache } from "./core/image/cache-sweep.js";
+import { IMAGE_MIMES, normalizeImageForModel } from "./core/image/normalize.js";
+import { summarizeRuns } from "./diagnostics.js";
+import { resolveFsGrants } from "./fs-drive-bridge.js";
+import { fsGrantKey, fsWriteGrantKey } from "./fs-grant-keys.js";
+import { fsGrantsFrom, grantedDirsFrom } from "./fs-grants.js";
+import { defaultImageCacheDir } from "./image-cache-dir.js";
+import { ModelCatalogRevisionHub } from "./model-catalog-revision.js";
+import { agentRekeyFingerprint, chatKvCacheKey, chatRepairKvCacheKey, disappearedChatIds } from "./kv-cache-reclaim.js";
+import { buildCompactionPrompt, canCompact, foldReducesPrompt, COMPACTION_KEEP_TURNS, COMPACTION_TURN_PREFIX, isContextOverflowFailure, nearContextLimit, compactionBoundary, compactionTurn, foldCompactedChunks, lastCompactedThroughId, parseCompactionSummary } from "./compaction.js";
+import { isMobilePlatform, runnableModelName } from "./model-clamp.js";
+import { ModelDownloadReconciler } from "./model-download.js";
+import { AbortedError, raceAbort } from '@qvac/harness/race-abort';
+import { RunTranscript } from "./run-transcript.js";
+import { searchKnowledge } from "./knowledge-search.js";
+import { isLifecycleTeardown, knownAbortOutcome, RUN_ABORT_REASONS, RUN_FAILURE_REASONS, runFailureNotice } from "./run-notices.js";
+import { encodeAgentSkillReadiness } from "./skill-readiness.js";
+const QvacState = local.getEnum('@local/qvac-state');
+export const IMAGE_ONLY_USER_PROMPT = 'The user sent one or more images without any accompanying text. Describe what the images show and respond to anything notable in them.';
+export const DOCUMENT_ONLY_USER_PROMPT = 'The user sent one or more documents without any accompanying text. Summarize the attached documents.';
+export const IMAGE_AND_DOCUMENT_USER_PROMPT = 'The user sent one or more images together with one or more documents, and no accompanying text. Describe what the images show and summarize the attached documents.';
+function backfillDocumentOnlyTurn(messages) {
+    const last = messages.findLast((turn) => turn.role === 'user');
+    if (!last || last.content.trim())
+        return;
+    last.content = last.attachments?.length
+        ? IMAGE_AND_DOCUMENT_USER_PROMPT
+        : DOCUMENT_ONLY_USER_PROMPT;
+}
+function backfillImageOnlyTurns(messages) {
+    for (const turn of messages) {
+        if (turn.role !== 'user' || turn.content.trim())
+            continue;
+        if (turn.attachments?.length)
+            turn.content = IMAGE_ONLY_USER_PROMPT;
+    }
+}
+export function unreadableImagesNotice(fileNames) {
+    const plural = fileNames.length > 1;
+    return (`[Attached image${plural ? 's' : ''}: ${fileNames.join(', ')} — could not be read, so ` +
+        `${plural ? 'they are' : 'it is'} not visible to you. Tell the user the upload failed and ` +
+        `ask for a re-upload; never describe or recreate ${plural ? 'them' : 'it'}]`);
+}
+export function annotateUnreadableImages(unreadable) {
+    for (const [turn, names] of unreadable) {
+        const notice = unreadableImagesNotice(names);
+        turn.content = turn.content ? `${turn.content}\n${notice}` : notice;
+    }
+}
+async function raceInactivity(promise, signal, timeoutMs) {
+    let timer = null;
+    const expired = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('blob read timed out')), timeoutMs);
+    });
+    try {
+        return await raceAbort(Promise.race([promise, expired]), signal);
+    }
+    finally {
+        if (timer !== null)
+            clearTimeout(timer);
+    }
+}
+async function drainBody(body, signal, timeoutMs) {
+    if (!body)
+        return null;
+    const reader = body.getReader();
+    const parts = [];
+    try {
+        for (;;) {
+            const read = await raceInactivity(reader.read(), signal, timeoutMs);
+            if (read.done)
+                break;
+            parts.push(b4a.from(read.value));
+        }
+    }
+    catch {
+        await reader.cancel();
+        return null;
+    }
+    return b4a.concat(parts);
+}
+export function unheardAudioNotice(label, reason, opts = {}) {
+    const retry = opts.retryable === false ? '' : ', and ask them to try again';
+    return (`${label} could not be transcribed (${reason}). Tell the user the audio was not ` +
+        `transcribed and why${retry}; never invent what it might contain.`);
+}
+function silentAudioNotice(fileName) {
+    return (`Attached audio "${fileName}" was transcribed and contained no detectable speech. ` +
+        'Tell the user; never invent what it might contain.');
+}
+function audioTranscriptBlock(fileName, transcript) {
+    return [
+        `The audio file "${fileName}" has already been transcribed on-device. You cannot open the file itself — use the transcript below as its full content and answer from it.`,
+        'Transcript:',
+        transcript
+    ].join('\n');
+}
+export function harnessListModels(harness) {
+    return async ({ type, cachedOnly, fullRegistry } = {}) => ({
+        models: [
+            ...((await harness.list?.({
+                type: type ?? undefined,
+                cachedOnly: cachedOnly ?? undefined,
+                fullRegistry: fullRegistry ?? undefined
+            })) ?? [])
+        ]
+    });
+}
+export function harnessDeleteModel(harness) {
+    return async ({ name }) => (await harness.deleteModel?.(name)) ?? { name, removed: 0, freedBytes: 0 };
+}
+export function harnessClearKvCache(harness) {
+    return async () => (await harness.clearKvCache?.()) ?? {
+        status: 'unsupported',
+        error: 'Harness does not support KV cache deletion'
+    };
+}
+export function harnessTranscribe(harness) {
+    return async ({ audio, model }) => {
+        if (!harness.transcribe)
+            throw new Error('harness does not support transcribe');
+        return { text: await harness.transcribe({ audio, model: model ?? '' }) };
+    };
+}
+export function harnessSpeak(harness) {
+    return async ({ text, model }) => {
+        if (!harness.speak)
+            throw new Error('harness does not support speak');
+        const { audio, sampleRate } = await harness.speak({ text, model: model ?? '' });
+        return { audio, sampleRate };
+    };
+}
+export function harnessSkillCatalog(harness, syncCredentials) {
+    return async (agentId, modelName, options) => {
+        if (options?.refresh)
+            await syncCredentials?.();
+        return {
+            skills: ((await harness.skills?.(agentId, modelName, options)) ?? []).map(toEngineSkill)
+        };
+    };
+}
+export function harnessSkillManagement(harness) {
+    return {
+        async listManagedSkills() {
+            return {
+                skills: ((await harness.listManagedSkills?.()) ?? []).map((skill) => ({
+                    name: skill.name,
+                    origin: skill.origin,
+                    overridesBase: skill.overridesBase
+                }))
+            };
+        },
+        async readSkillFile(name) {
+            const file = await harness.readSkillFile?.(name);
+            return file ? { found: true, content: file.content, origin: file.origin } : { found: false };
+        },
+        async writeSkillFile(name, content) {
+            if (!harness.writeSkillFile)
+                return { ok: false };
+            return harness.writeSkillFile(name, content);
+        },
+        async copySkillForEdit(name) {
+            return { copied: (await harness.copyBaseForEdit?.(name))?.copied ?? false };
+        },
+        async deleteOverlaySkill(name) {
+            return { removed: (await harness.deleteOverlaySkill?.(name))?.removed ?? false };
+        }
+    };
+}
+export function harnessTools(harness) {
+    return async () => ({
+        tools: ((await harness.tools?.()) ?? []).map((tool) => ({
+            ...toolReportEntry(tool),
+            description: tool.description
+        }))
+    });
+}
+function toolReportEntry(tool) {
+    return {
+        name: tool.name,
+        promptChars: tool.promptChars ?? 0,
+        toolset: tool.toolset ?? null,
+        skillGated: tool.skillGated === true,
+        scopeRequired: tool.scopeRequired === true,
+        rootsRequired: tool.rootsRequired === true,
+        writeRootsRequired: tool.writeRootsRequired === true
+    };
+}
+export function harnessSpeakStream(harness) {
+    return async function* (text) {
+        if (!harness.speakStream)
+            throw new Error('harness does not support speakStream');
+        for await (const { audio, sampleRate } of harness.speakStream({ model: '', text })) {
+            yield { audio, sampleRate };
+        }
+    };
+}
+function toEngineSkill(skill) {
+    const setup = normalizeSkillSetup(skill.setup);
+    return {
+        name: skill.name,
+        description: skill.description,
+        tools: [...skill.tools],
+        credentials: [...skill.credentials],
+        allowList: [...skill.allowList],
+        platforms: [...skill.platform],
+        status: skill.status,
+        ...(skill.requires ? { requirements: toEngineSkillRequirements(skill.requires) } : {}),
+        ...(skill.install ? { install: skill.install.map(toEngineInstallStep) } : {}),
+        ...(setup ? { setup: toEngineSkillSetup(setup) } : {}),
+        ...(skill.stub !== undefined ? { stub: skill.stub } : {}),
+        ...(skill.minCapabilityProfile ? { minCapabilityProfile: skill.minCapabilityProfile } : {}),
+        ...(skill.emoji ? { emoji: skill.emoji } : {})
+    };
+}
+function toEngineSkillRequirements(requires) {
+    return {
+        binaries: (requires.bins ?? []).map((bin) => ({
+            bin,
+            minVersion: requires.binMinVersions?.[bin]?.min,
+            command: requires.binMinVersions?.[bin]?.command
+        })),
+        credentials: [...(requires.credentials ?? [])]
+    };
+}
+function toEngineInstallStep(step) {
+    return {
+        id: step.id,
+        kind: step.kind,
+        label: step.label,
+        ...(step.formula ? { formula: step.formula } : {}),
+        ...(step.command ? { command: step.command } : {}),
+        ...(step.manual !== undefined ? { manual: step.manual } : {}),
+        ...(step.bins ? { bins: [...step.bins] } : {})
+    };
+}
+function toEngineSkillSetup(setup) {
+    return {
+        ...(setup.summary ? { summary: setup.summary } : {}),
+        ...(setup.routes
+            ? {
+                routes: setup.routes.map((route) => ({
+                    kind: route.kind,
+                    label: route.label,
+                    ...(route.provider ? { provider: route.provider } : {}),
+                    ...(route.credentialKey ? { credentialKey: route.credentialKey } : {}),
+                    ...(route.description ? { description: route.description } : {}),
+                    ...(route.helpUrl ? { helpUrl: route.helpUrl } : {}),
+                    ...(route.steps ? { steps: [...route.steps] } : {}),
+                    ...(route.configSteps ? { configSteps: [...route.configSteps] } : {}),
+                    ...(route.fields
+                        ? {
+                            fields: route.fields.map((field) => ({
+                                key: field.key,
+                                label: field.label,
+                                ...(field.placeholder ? { placeholder: field.placeholder } : {}),
+                                ...(field.secret !== undefined ? { secret: field.secret } : {}),
+                                ...(field.required !== undefined ? { required: field.required } : {})
+                            }))
+                        }
+                        : {}),
+                    ...(route.satisfied !== undefined ? { satisfied: route.satisfied } : {})
+                }))
+            }
+            : {})
+    };
+}
+const FINAL_FLUSH_MS = 10_000;
+const UPLOAD_FRAME_BYTES = 64 * 1024;
+const TERMINAL_STATES = new Set(['completed', 'failed', 'canceled']);
+function settledWithin(write, ms) {
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), ms);
+    });
+    const landed = write.then(() => true, () => true);
+    return Promise.race([landed, expired]).finally(() => clearTimeout(timer));
+}
+function isDeniedResult(result) {
+    if (!result || typeof result !== 'object')
+        return false;
+    return result.denied === true;
+}
+const CONSUME_RETRY_MS = 1000;
+const CONSUME_RETRY_MAX_MS = 30000;
+const BLOB_READ_TIMEOUT_MS = 15_000;
+function nextRetryDelay(err, current) {
+    return isMeshTransition(err) ? Math.min(current * 2, CONSUME_RETRY_MAX_MS) : CONSUME_RETRY_MS;
+}
+const SUSPENDED = RUN_ABORT_REASONS.suspended;
+const OWNERSHIP_LOST = RUN_ABORT_REASONS.ownershipLost;
+const RUN_SETTLED = RUN_ABORT_REASONS.runSettled;
+const RUNNER_DIED = RUN_ABORT_REASONS.runnerDied;
+const RUNNER_CLOSED = RUN_ABORT_REASONS.runnerClosed;
+const HISTORY_TYPES = HISTORY_CHUNK_TYPES;
+const SKILL_TOOL = 'skill';
+function isSetUpHere(status) {
+    return status === SKILL_STATE.ready || status === SKILL_STATE.incompatibleModel;
+}
+function sameNameList(left, right) {
+    return left.length === right.length && left.every((name, index) => name === right[index]);
+}
+function withConfigDefaults(agent, config) {
+    if (agent.ctxSize || !config?.ctxSize)
+        return agent;
+    return { ...agent, ctxSize: config.ctxSize };
+}
+export async function listHistoryChunks(engine, chatId) {
+    const [history, toolResults, runStatuses] = await Promise.all([
+        engine.listChunks({ chatId, types: HISTORY_TYPES }),
+        engine.listChunks({ chatId, type: 'tool-result' }),
+        engine.listChunks({ chatId, type: 'run-status' })
+    ]);
+    return [
+        ...(history.chunks ?? []),
+        ...(toolResults.chunks ?? []),
+        ...(runStatuses.chunks ?? [])
+    ].sort((a, b) => a.seq - b.seq);
+}
+function latestAttemptStarts(chunks) {
+    const starts = new Map();
+    for (const chunk of chunks) {
+        if (chunk.type !== 'run-status' || !chunk.runId)
+            continue;
+        if (TERMINAL_STATES.has(chunk.runStatus?.state ?? ''))
+            continue;
+        starts.set(chunk.runId, chunk.seq);
+    }
+    return starts;
+}
+function beforeLatestAttempt(chunk, starts) {
+    if (!chunk.runId)
+        return false;
+    const start = starts.get(chunk.runId);
+    return start !== undefined && chunk.seq < start;
+}
+export function historyFromChunks(chunks, stale = {}) {
+    const attemptStarts = latestAttemptStarts(chunks);
+    const staleRunIds = stale.runIds ?? new Set();
+    const staleQuestionChunkIds = stale.questionChunkIds ?? new Set();
+    const folded = foldCompactedChunks(chunks);
+    const source = folded.chunks;
+    const attachments = [];
+    const userMessages = [];
+    for (const chunk of source) {
+        if (chunk.type === 'attachment')
+            attachments.push(chunk);
+        else if (chunk.userMessage)
+            userMessages.push(chunk);
+    }
+    const byMessage = groupAttachmentsByMessage(attachments, userMessages);
+    const history = [];
+    const replayedSkills = new Set();
+    if (folded.summary)
+        history.push({ role: 'user', content: compactionTurn(folded.summary) });
+    const byRun = new Map();
+    const anchor = (runId) => {
+        let turn = byRun.get(runId);
+        if (!turn) {
+            turn = { role: 'assistant', content: '' };
+            byRun.set(runId, turn);
+            history.push(turn);
+        }
+        return turn;
+    };
+    for (const chunk of source) {
+        if (chunk.userMessage) {
+            if (staleQuestionChunkIds.has(chunk.id))
+                continue;
+            const turn = { role: 'user', content: chunk.userMessage.text };
+            const refs = (byMessage.get(chunk.id) ?? [])
+                .map((attachmentChunk) => attachmentChunk.attachment)
+                .filter((ref) => !ref.deletedAt);
+            const images = refs.filter((ref) => IMAGE_MIMES.has(ref.mimeType.toLowerCase()));
+            const audio = refs.filter((ref) => isAudioAttachment(ref.fileName, ref.mimeType));
+            const documents = refs.filter((ref) => isDocumentAttachment(ref));
+            if (images.length)
+                turn.images = images;
+            if (audio.length)
+                turn.audioAttachments = audio;
+            if (documents.length)
+                turn.documents = documents;
+            history.push(turn);
+            continue;
+        }
+        if (chunk.attachment)
+            continue;
+        if (chunk.type === 'run-request' && chunk.runId) {
+            anchor(chunk.runId);
+            continue;
+        }
+        if (chunk.toolResult?.name === SKILL_TOOL) {
+            if (chunk.runId && staleRunIds.has(chunk.runId))
+                continue;
+            if (beforeLatestAttempt(chunk, attemptStarts))
+                continue;
+            const loaded = chunk.toolResult.result?.name;
+            if (typeof loaded === 'string' && !replayedSkills.has(loaded)) {
+                replayedSkills.add(loaded);
+                history.push({ role: 'tool', content: skillLoadedTurn(loaded) });
+            }
+            continue;
+        }
+        if (chunk.toolResult) {
+            if (chunk.runId && staleRunIds.has(chunk.runId))
+                continue;
+            if (beforeLatestAttempt(chunk, attemptStarts))
+                continue;
+            const produced = attachmentTurn(chunk.toolResult.name, chunk.toolResult.result);
+            if (produced)
+                history.push({ role: 'tool', content: produced });
+            continue;
+        }
+        if (!chunk.content)
+            continue;
+        if (chunk.runId && staleRunIds.has(chunk.runId))
+            continue;
+        if (beforeLatestAttempt(chunk, attemptStarts))
+            continue;
+        anchor(chunk.runId).content += chunk.content.text;
+    }
+    return history.filter((turn) => turn.role === 'user' || turn.content.length > 0);
+}
+function withoutOccupancy(metrics) {
+    if (!metrics)
+        return metrics;
+    const { cacheTokens, promptTokens, ...rest } = metrics;
+    return rest;
+}
+function inputAvailableToRun(chunk, requestSeq) {
+    const userInput = Boolean(chunk.userMessage || (chunk.attachment && !chunk.runId));
+    return !userInput || chunk.seq < requestSeq;
+}
+function normalizeQuestion(text) {
+    return text.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+const GENERIC_ACKNOWLEDGEMENTS = new Set([
+    'yes',
+    'y',
+    'yeah',
+    'yep',
+    'yup',
+    'ok',
+    'okay',
+    'k',
+    'sure',
+    'fine',
+    'no',
+    'n',
+    'nope',
+    'nah',
+    'again',
+    'continue',
+    'go on',
+    'go ahead',
+    'keep going',
+    'proceed',
+    'do it',
+    'more',
+    'please',
+    'thanks',
+    'thank you',
+    'retry',
+    'redo'
+]);
+function isGenericAcknowledgement(question) {
+    return GENERIC_ACKNOWLEDGEMENTS.has(question.replace(/[?.!]+$/, '').trim());
+}
+export function staleToolRunIds(historyChunks, approvalChunks, currentRunId) {
+    const empty = { runIds: new Set(), questionChunkIds: new Set() };
+    const toolRuns = new Set();
+    for (const chunk of approvalChunks) {
+        if (chunk.runId)
+            toolRuns.add(chunk.runId);
+    }
+    if (!toolRuns.size)
+        return empty;
+    const turnOrder = [];
+    const turnText = new Map();
+    const turnRuns = new Map();
+    const runChunk = new Map();
+    let lastUser = null;
+    for (const chunk of historyChunks) {
+        if (chunk.userMessage) {
+            lastUser = { text: chunk.userMessage.text, chunkId: chunk.id };
+            continue;
+        }
+        if (chunk.type === 'run-request' && chunk.runId && lastUser !== null) {
+            const chunkId = lastUser.chunkId;
+            if (!turnText.has(chunkId)) {
+                turnOrder.push(chunkId);
+                turnText.set(chunkId, lastUser.text);
+            }
+            turnRuns.set(chunkId, [...(turnRuns.get(chunkId) ?? []), chunk.runId]);
+            runChunk.set(chunk.runId, chunkId);
+        }
+    }
+    const currentChunkId = runChunk.get(currentRunId) ?? lastUser?.chunkId;
+    if (currentChunkId === undefined)
+        return empty;
+    const currentText = turnText.get(currentChunkId) ?? lastUser?.text;
+    if (currentText === undefined)
+        return empty;
+    const target = normalizeQuestion(currentText);
+    if (isGenericAcknowledgement(target))
+        return empty;
+    const currentIndex = turnOrder.indexOf(currentChunkId);
+    const start = currentIndex === -1 ? turnOrder.length - 1 : currentIndex - 1;
+    const runIds = new Set();
+    const questionChunkIds = new Set();
+    let blockHadApproval = false;
+    for (let i = start; i >= 0; i--) {
+        const chunkId = turnOrder[i];
+        if (normalizeQuestion(turnText.get(chunkId)) !== target)
+            break;
+        questionChunkIds.add(chunkId);
+        for (const rid of turnRuns.get(chunkId) ?? []) {
+            runIds.add(rid);
+            if (toolRuns.has(rid))
+                blockHadApproval = true;
+        }
+    }
+    if (!blockHadApproval)
+        return empty;
+    return { runIds, questionChunkIds };
+}
+export class QvacAssistant extends ReadyResource {
+    _engine;
+    _harness;
+    _log;
+    _imageCacheDir;
+    _imageCacheMaxBytes;
+    _imageCacheMaxAgeMs;
+    _downloadRetryMs;
+    _platform;
+    _mobileClass;
+    _preloadCurrentAgentModel;
+    _drives;
+    _blobReadTimeoutMs;
+    _warmAbort = new AbortController();
+    _warmedModel = false;
+    _warmedModelName = null;
+    _modelStatusLogged = new Map();
+    _deviceId;
+    _info;
+    _lastCapabilities;
+    _readySkills;
+    _recordingReadiness = false;
+    _readinessDirty = false;
+    _reconciling;
+    _onlineBoot = new ReadyGuard();
+    _capability;
+    _downloads;
+    _state;
+    _harnessDiagnostics;
+    _harnessDeath;
+    _refreshingDiagnostics;
+    _requests;
+    _retry;
+    _retryMs = CONSUME_RETRY_MS;
+    _chatList;
+    _agentList;
+    _chatListWatch;
+    _agentWatch;
+    _runs;
+    _seen;
+    _lifecycle;
+    _audioTranscripts;
+    _chats;
+    _runImageCacheNames;
+    _reconciledCompactions;
+    _modelCatalog = new ModelCatalogRevisionHub();
+    _onHarnessStatus;
+    _onModelCatalogEvent;
+    constructor(engine, harness, { logger = null, imageCacheDir, imageCacheMaxBytes, imageCacheMaxAgeMs, downloadRetryMs, platform = os.platform(), preloadCurrentAgentModel = true, drives, blobReadTimeoutMs = BLOB_READ_TIMEOUT_MS } = {}) {
+        super();
+        this._engine = engine;
+        this._harness = harness;
+        this._drives = drives;
+        this._log = logger;
+        this._imageCacheDir = imageCacheDir ?? defaultImageCacheDir();
+        this._imageCacheMaxBytes = imageCacheMaxBytes;
+        this._imageCacheMaxAgeMs = imageCacheMaxAgeMs;
+        this._downloadRetryMs = downloadRetryMs;
+        this._platform = platform;
+        this._mobileClass = isMobilePlatform(platform);
+        this._preloadCurrentAgentModel = preloadCurrentAgentModel;
+        this._blobReadTimeoutMs = blobReadTimeoutMs;
+        this._deviceId = null;
+        this._info = { toolNames: [], skills: [], supportsImages: false };
+        this._lastCapabilities = null;
+        this._readySkills = null;
+        this._reconciling = false;
+        this._capability = null;
+        this._downloads = null;
+        this._state = QvacState.RESUME;
+        this._harnessDiagnostics = null;
+        this._harnessDeath = null;
+        this._refreshingDiagnostics = false;
+        this._requests = null;
+        this._retry = null;
+        this._chatList = null;
+        this._agentList = null;
+        this._chatListWatch = this._rearmingWatch('chat-list', () => this._watchChatList());
+        this._agentWatch = this._rearmingWatch('agent', () => this._watchAgents());
+        this._runs = new Map();
+        this._seen = new Set();
+        this._lifecycle = new AbortController();
+        this._audioTranscripts = new Map();
+        this._chats = new Map();
+        this._runImageCacheNames = new Map();
+        this._reconciledCompactions = new Map();
+        this._onHarnessStatus = (status) => {
+            this._log?.warn('assistant', 'harness status', status);
+            if (harnessDied(status)) {
+                this._harnessDeath = harnessDeathReason(status);
+                for (const run of this._runs.values())
+                    run.controller.abort(RUNNER_DIED);
+            }
+            else {
+                this._harnessDeath = null;
+            }
+            this.emit('harness-status', status);
+        };
+        this._onModelCatalogEvent = (state) => {
+            this._logModelStatus(state);
+            if (modelCatalogChanged(state))
+                this._modelCatalog.notify();
+            const progress = imageDownloadProgress(state);
+            if (progress)
+                this._downloads?.observeImageProgress(progress);
+        };
+    }
+    async _open() {
+        this._log?.info('assistant', 'host platform resolved', {
+            platform: this._platform,
+            mobileClass: this._mobileClass
+        });
+        const info = await this._engine.deviceInfo({});
+        this._deviceId = info.id;
+        this._harness.on?.('status', this._onHarnessStatus);
+        this._harness.on?.('model', this._onModelCatalogEvent);
+        this._info = await this._describeHarness();
+        await this._clearPersistedPauses();
+        this._downloads = new ModelDownloadReconciler({
+            engine: this._engine,
+            harness: this._harness,
+            deviceId: this._deviceId,
+            onCacheChanged: () => {
+                this._modelCatalog.notify();
+                void this._reportCapabilities();
+                this._triggerModelWarm();
+            },
+            retryMs: this._downloadRetryMs,
+            logger: this._log,
+            mobileClass: this._mobileClass
+        });
+        this._downloads.start();
+        this._startConsume();
+        this._chatListWatch.start();
+        this._agentWatch.start();
+        void this._bootOnline();
+        this._triggerModelWarm();
+        void this.onlineReady().then(() => this._triggerModelWarm(), noop);
+    }
+    _triggerModelWarm() {
+        if (!this._preloadCurrentAgentModel)
+            return;
+        void this._warmCurrentAgentModel().catch((err) => this._log?.warn('assistant', 'current agent model warm failed', err));
+    }
+    async _warmCurrentAgentModel() {
+        if (this._warmedModel)
+            return;
+        const deviceId = this._deviceId;
+        const config = await this._engine.getConfig({}).catch(() => null);
+        const agent = await this._currentAgent(config?.activeAgentId ?? null, deviceId);
+        if (!agent?.modelName || !agent.providerDeviceId?.equals(deviceId) || this.suspended)
+            return;
+        const model = runnableModelName(agent.modelName, await this._ensureCapability(), this._mobileClass);
+        const rows = await this._harness.list?.({ cachedOnly: true }).catch(() => null);
+        if (!rows?.some((row) => row.name === model && row.isCached)) {
+            this._log?.info('models', 'model warm skipped', { model, reason: 'not cached' });
+            return;
+        }
+        if (this._warmedModel)
+            return;
+        this._warmedModel = true;
+        this._warmedModelName = model;
+        this._log?.info('models', 'model warm started', { model, agentModel: agent.modelName });
+        const started = Date.now();
+        await this._harness.warmModel?.({
+            model,
+            agent: withConfigDefaults(agent, config),
+            signal: this._warmAbort.signal
+        });
+        this._log?.info('models', 'model warm done', { model, ms: Date.now() - started });
+    }
+    async _currentAgent(activeAgentId, deviceId) {
+        if (activeAgentId) {
+            const agent = await this._engine.getAgent({ id: activeAgentId }).catch(() => null);
+            if (agent && !agent.deletedAt)
+                return agent;
+        }
+        const { agents } = await this._engine.listAgents({}).catch(() => ({ agents: [] }));
+        const all = agents ?? [];
+        return (all.find((agent) => agent.isDefault && agent.providerDeviceId?.equals(deviceId)) ??
+            all.find((agent) => agent.isDefault) ??
+            all[0] ??
+            null);
+    }
+    async _bootOnline() {
+        void this._onlineBoot.ready().catch(noop);
+        try {
+            await Promise.allSettled([
+                this._sweepImageCache(),
+                this._reportCapabilities(),
+                this._reconcileDeviceProfile()
+            ]);
+        }
+        finally {
+            this._onlineBoot.exit();
+        }
+    }
+    async onlineReady() {
+        if (!this.opened)
+            await this.ready();
+        await this._onlineBoot.ready();
+    }
+    async _clearPersistedPauses() {
+        try {
+            const config = await this._engine.getConfig({});
+            for (const name of config.pausedModels ?? []) {
+                await this._engine.setModelPaused({ name, paused: false });
+            }
+        }
+        catch (err) {
+            this._log?.warn('assistant', 'clearing persisted model pauses failed', err);
+        }
+    }
+    async ensureMediaModelUnpaused(category, model) {
+        try {
+            const name = model || mediaModelNameFor(category, await this._persistedProfile());
+            const config = await this._engine.getConfig({});
+            if (!(config.pausedModels ?? []).includes(name))
+                return true;
+            await this._engine.setModelPaused({ name, paused: false });
+            return true;
+        }
+        catch (err) {
+            this._log?.warn('assistant', 'ensuring media model unpaused failed', err);
+            return false;
+        }
+    }
+    async _persistedProfile() {
+        const deviceId = this._deviceId;
+        if (!deviceId)
+            return 'mid';
+        const { devices } = await this._engine.listDevices({}).catch(() => ({ devices: [] }));
+        const self = (devices ?? []).find((device) => device.id.equals(deviceId));
+        return self?.capabilityProfile ?? 'mid';
+    }
+    async _sweepImageCache() {
+        try {
+            const keep = await this._referencedImageNames();
+            await sweepImageCache(this._imageCacheDir, {
+                maxBytes: this._imageCacheMaxBytes,
+                maxAgeMs: this._imageCacheMaxAgeMs,
+                inUse: (name) => this._imageCacheInUse(name),
+                ...(keep ? { keep } : {})
+            });
+        }
+        catch (err) {
+            this._log?.warn('assistant', 'image cache sweep failed', err);
+        }
+    }
+    _imageCacheInUse(name) {
+        for (const names of this._runImageCacheNames.values())
+            if (names.has(name))
+                return true;
+        return false;
+    }
+    async _referencedImageNames() {
+        try {
+            const { chats } = await this._engine.listChats({});
+            if (!chats?.length)
+                return null;
+            const keep = new Set();
+            for (const chat of chats) {
+                const { chunks } = await this._engine.listChunks({ chatId: chat.id, type: 'attachment' });
+                for (const chunk of chunks ?? []) {
+                    const attachment = chunk.attachment;
+                    if (attachment && !attachment.deletedAt)
+                        keep.add(imageCacheName(attachment));
+                }
+            }
+            return keep;
+        }
+        catch {
+            return null;
+        }
+    }
+    async _describeHarness() {
+        const described = await this._harness.describe?.();
+        return (described ?? {
+            toolNames: this._harness.toolNames ?? [],
+            skills: this._harness.skillNames ?? [],
+            supportsImages: this._harness.supportsImages ?? false
+        });
+    }
+    diagnosticsSlice() {
+        const harness = this._harness.diagnostics?.() ?? this._harnessDiagnostics;
+        void this._refreshHarnessDiagnostics();
+        const runs = [...this._runs.entries()].map(([runId, run]) => ({
+            runId,
+            chatId: run.chatId,
+            model: run.model
+        }));
+        return {
+            harness,
+            assistant: summarizeRuns(runs, this.suspended),
+            platform: this._platform,
+            mobileClass: this._mobileClass,
+            memoryBudget: this._capability?.memoryBudget ?? null
+        };
+    }
+    async _refreshHarnessDiagnostics() {
+        if (this._refreshingDiagnostics || !this._harness.fetchDiagnostics)
+            return;
+        this._refreshingDiagnostics = true;
+        try {
+            this._harnessDiagnostics = await this._harness.fetchDiagnostics();
+        }
+        catch {
+        }
+        finally {
+            this._refreshingDiagnostics = false;
+        }
+    }
+    async _reportCapabilities() {
+        let models;
+        try {
+            models = (await this._harness.list?.()) ?? [];
+        }
+        catch (err) {
+            this._log?.warn('assistant', '_reportCapabilities: harness.list failed — keeping last catalog', err);
+            return;
+        }
+        const installedModelNames = models.map((model) => model.name);
+        const cachedModelNames = models.filter((model) => model.isCached).map((model) => model.name);
+        let toolCatalog = null;
+        if (this._harness.tools) {
+            try {
+                toolCatalog = (await this._harness.tools()).map(toolReportEntry);
+            }
+            catch (err) {
+                this._log?.warn('assistant', '_reportCapabilities: harness.tools failed', err);
+            }
+        }
+        const key = JSON.stringify([
+            this._info.toolNames,
+            this._info.skills,
+            installedModelNames,
+            cachedModelNames,
+            this._readySkills,
+            toolCatalog
+        ]);
+        if (key === this._lastCapabilities)
+            return;
+        try {
+            await this._engine.saveDeviceCapabilities({
+                installedToolNames: this._info.toolNames,
+                installedSkillNames: this._info.skills,
+                installedModelNames,
+                cachedModelNames,
+                ...(this._readySkills ? { readySkillNames: this._readySkills } : {}),
+                ...(toolCatalog ? { toolCatalog } : {})
+            });
+            this._lastCapabilities = key;
+        }
+        catch (err) {
+            if (isMeshTransition(err))
+                return;
+            this._log?.error('assistant', 'saveDeviceCapabilities failed', err);
+        }
+    }
+    async _ensureCapability() {
+        if (this._capability)
+            return this._capability;
+        let probed;
+        try {
+            probed = await this._harness.capability?.();
+        }
+        catch (err) {
+            this._log?.warn('assistant', '_reconcileDeviceProfile: harness.capability failed', err);
+            return null;
+        }
+        if (!probed?.recommendedModelName)
+            return null;
+        this._capability = probed;
+        return probed;
+    }
+    async _reconcileDeviceProfile() {
+        const deviceId = this._deviceId;
+        if (!deviceId || this._reconciling)
+            return;
+        this._reconciling = true;
+        try {
+            const capability = await this._ensureCapability();
+            if (!capability)
+                return;
+            const { devices } = await this._engine.listDevices({}).catch(() => ({ devices: [] }));
+            const self = (devices ?? []).find((device) => device.id.equals(deviceId));
+            if (!self)
+                return;
+            const profileUpdated = !(self.capabilityProfile === capability.capabilityProfile &&
+                self.recommendedModelName === capability.recommendedModelName &&
+                self.platform === this._platform);
+            const profile = {
+                publicKey: b4a.toString(deviceId, 'hex'),
+                name: self.name,
+                platform: this._platform,
+                mobileClass: this._mobileClass,
+                capabilityProfile: capability.capabilityProfile,
+                recommendedModelName: capability.recommendedModelName,
+                ...(capability.memoryBudget ? { memoryBudget: capability.memoryBudget } : {})
+            };
+            if (profileUpdated) {
+                try {
+                    await this._engine.saveDeviceProfile({
+                        capabilityProfile: capability.capabilityProfile,
+                        recommendedModelName: capability.recommendedModelName,
+                        platform: this._platform
+                    });
+                }
+                catch (err) {
+                    this._log?.error('assistant', 'saveDeviceProfile failed', profile, err);
+                    return;
+                }
+            }
+            this._log?.info('assistant', 'device profile resolved', { ...profile, profileUpdated });
+        }
+        finally {
+            this._reconciling = false;
+        }
+    }
+    async _close() {
+        if (this._retry)
+            clearTimeout(this._retry);
+        this._chatListWatch.stop();
+        this._agentWatch.stop();
+        this._harness.off?.('status', this._onHarnessStatus);
+        this._harness.off?.('model', this._onModelCatalogEvent);
+        this._warmAbort.abort(RUNNER_CLOSED);
+        this._onlineBoot.destroy(new Error('assistant is closing'));
+        for (const run of this._runs.values())
+            run.controller.abort(RUNNER_CLOSED);
+        await this._downloads?.close();
+        this._modelCatalog.close();
+        await this._requests?.return?.();
+        await this._chatList?.return?.();
+        await this._agentList?.return?.();
+        this._lifecycle.abort(RUNNER_CLOSED);
+        await Promise.allSettled([...this._runs.values()].map((run) => run.done));
+    }
+    get suspended() {
+        return this._state === QvacState.SUSPEND;
+    }
+    async presuspend() {
+        if (this.closing)
+            return;
+        this._state = QvacState.PRESUSPEND;
+        this._log?.info('assistant', 'presuspend');
+    }
+    async suspend() {
+        this._log?.info('assistant', 'suspend called');
+        if (this._state === QvacState.SUSPEND)
+            return;
+        if (this.closing)
+            return;
+        this._state = QvacState.SUSPEND;
+        this._log?.info('assistant', 'suspending', { runs: this._runs.size });
+        if (this._retry)
+            clearTimeout(this._retry);
+        this._chatListWatch.stop();
+        this._agentWatch.stop();
+        await this._downloads?.suspend();
+        await this._requests?.return?.();
+        await this._chatList?.return?.();
+        await this._agentList?.return?.();
+        for (const run of this._runs.values())
+            run.controller.abort(SUSPENDED);
+        this._warmedModel = false;
+        this._warmedModelName = null;
+        this._modelCatalog.notify();
+    }
+    async wakeup() {
+        if (this.closing)
+            return;
+        this._state = QvacState.WAKEUP;
+        this._log?.info('assistant', 'wakeup');
+        await this.resume();
+        this._triggerModelWarm();
+    }
+    async resume() {
+        this._log?.info('assistant', 'resume called');
+        if (this._state === QvacState.RESUME)
+            return;
+        if (this.closing)
+            return;
+        if (this._state === QvacState.PRESUSPEND) {
+            this._state = QvacState.RESUME;
+            return;
+        }
+        this._state = QvacState.RESUME;
+        this._log?.info('assistant', 'resuming');
+        await Promise.allSettled([...this._runs.values()].map((run) => run.done));
+        this._downloads?.resume();
+        if (this.opened) {
+            this._startConsume();
+            this._chatListWatch.start();
+            this._agentWatch.start();
+        }
+    }
+    async listModels(options) {
+        return (await this._harness.list?.(options)) ?? [];
+    }
+    async deleteModel(name) {
+        return (await this._harness.deleteModel?.(name)) ?? { name, removed: 0, freedBytes: 0 };
+    }
+    modelCatalogWatch() {
+        return this._modelCatalog.watch();
+    }
+    async retryModelDownload(name) {
+        if (!this._downloads)
+            throw new Error('model download reconciler is unavailable');
+        await this._downloads.retry(name);
+    }
+    async skills(agentId, modelName, options) {
+        if (!this.opened)
+            await this.ready();
+        if (agentId) {
+            const agent = await this._engine.getAgent({ id: agentId }).catch(() => null);
+            const deviceId = this._deviceId;
+            if (agent && deviceId && !agent.providerDeviceId?.equals(deviceId)) {
+                agentId = null;
+                options = { ...options, skipCredentialProbe: true };
+            }
+        }
+        const resolved = (await this._harness.skills?.(agentId, modelName, options)) ?? [];
+        this._recordSkillReadiness().catch(noop);
+        return resolved;
+    }
+    async _recordSkillReadiness() {
+        this._readinessDirty = true;
+        if (this._recordingReadiness)
+            return;
+        this._recordingReadiness = true;
+        try {
+            while (this._readinessDirty) {
+                this._readinessDirty = false;
+                const unscoped = (await this._harness.skills?.(null, null, { skipCredentialProbe: true })) ?? [];
+                const ready = unscoped
+                    .filter((skill) => isSetUpHere(skill.status))
+                    .map((skill) => skill.name);
+                const deviceId = this._deviceId;
+                if (deviceId) {
+                    const { agents } = await this._engine.listAgents({});
+                    const local = (agents ?? []).filter((agent) => !agent.deletedAt && agent.providerDeviceId?.equals(deviceId));
+                    for (const agent of local) {
+                        const resolved = (await this._harness.skills?.(agent.id, agent.modelName, {
+                            skipCredentialProbe: true
+                        })) ?? [];
+                        ready.push(...encodeAgentSkillReadiness(agent.id, resolved.filter((skill) => isSetUpHere(skill.status)).map((skill) => skill.name)));
+                    }
+                }
+                ready.sort();
+                if (this._readySkills && sameNameList(this._readySkills, ready))
+                    continue;
+                this._readySkills = ready;
+                await this._reportCapabilities();
+            }
+        }
+        finally {
+            this._recordingReadiness = false;
+        }
+    }
+    async tools() {
+        return (await this._harness.tools?.()) ?? [];
+    }
+    _startConsume() {
+        this._consume().then(() => this._rearmConsume(null), (err) => this._rearmConsume(err));
+    }
+    _rearmingWatch(label, run) {
+        let retryMs = CONSUME_RETRY_MS;
+        let timer = null;
+        const rearm = (err) => {
+            if (this.closing || this.suspended)
+                return;
+            if (err !== null && !isMeshTransition(err)) {
+                this._log?.error('assistant', `${label} watch failed — restarting`, err);
+            }
+            const delay = isMeshTransition(err) ? retryMs : CONSUME_RETRY_MS;
+            retryMs = nextRetryDelay(err, delay);
+            timer = setTimeout(start, delay);
+        };
+        const start = () => {
+            run().then(() => rearm(null), (err) => rearm(err));
+        };
+        return {
+            start,
+            stop: () => {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        };
+    }
+    async _watchChatList() {
+        const stream = this._engine.chatsWatch({});
+        this._chatList = stream[Symbol.asyncIterator]();
+        let known = null;
+        while (true) {
+            const { value, done } = await this._chatList.next();
+            if (done || this.closing || this.suspended)
+                return;
+            const ids = (value.chats ?? []).map((chat) => chat.id);
+            if (known !== null) {
+                for (const chatId of disappearedChatIds(known, ids)) {
+                    this._reconciledCompactions.delete(chatId);
+                    void this._deleteChatKvCache(chatId, 'chat deleted');
+                }
+            }
+            known = new Set(ids);
+            await this._sweepImageCache();
+        }
+    }
+    async _watchAgents() {
+        const stream = this._engine.agentsWatch({});
+        this._agentList = stream[Symbol.asyncIterator]();
+        let known = null;
+        while (true) {
+            const { value, done } = await this._agentList.next();
+            if (done || this.closing || this.suspended)
+                return;
+            const agents = value.agents ?? [];
+            const next = new Map(agents.map((agent) => [agent.id, agentRekeyFingerprint(agent)]));
+            if (known !== null) {
+                for (const agent of agents) {
+                    const previous = known.get(agent.id);
+                    if (previous !== undefined && previous !== next.get(agent.id)) {
+                        void this._reclaimAgentChatCaches(agent.id);
+                    }
+                }
+            }
+            known = next;
+        }
+    }
+    async _reclaimAgentChatCaches(agentId) {
+        try {
+            const { chats } = await this._engine.listChats({});
+            for (const chat of chats ?? []) {
+                if (chat.agentId === agentId)
+                    await this._deleteChatKvCache(chat.id, 'agent re-key');
+            }
+        }
+        catch (err) {
+            this._log?.warn('assistant', 'agent re-key cache reclaim failed', { agentId, err });
+        }
+    }
+    async _reconcileCompaction(chatId) {
+        const deviceId = this._deviceId;
+        const { chunks } = await this._engine
+            .listChunks({ chatId, type: 'compaction' })
+            .catch(() => ({ chunks: [] }));
+        let newest = null;
+        for (const chunk of chunks ?? [])
+            if (!newest || chunk.seq > newest.seq)
+                newest = chunk;
+        if (!newest || newest.originDeviceId?.equals(deviceId))
+            return;
+        if (this._reconciledCompactions.get(chatId) === newest.id)
+            return;
+        const gone = await this._deleteChatKvCache(chatId, 'compaction from another device');
+        if (gone)
+            this._reconciledCompactions.set(chatId, newest.id);
+    }
+    async deleteChatKvCache(chatId) {
+        return ((await this._harness.deleteKvCache?.(chatKvCacheKey(chatId))) ?? {
+            status: 'unsupported',
+            error: 'Harness does not support KV cache deletion'
+        });
+    }
+    async _deleteChatKvCache(chatId, reason) {
+        try {
+            const result = await this.deleteChatKvCache(chatId);
+            if (result.status === 'failure') {
+                this._log?.warn('assistant', 'chat kv-cache deletion failed', {
+                    chatId,
+                    reason,
+                    error: result.error
+                });
+                return false;
+            }
+            return true;
+        }
+        catch (err) {
+            this._log?.warn('assistant', 'chat kv-cache deletion failed', { chatId, reason, err });
+            return false;
+        }
+    }
+    _rearmConsume(err) {
+        if (this.closing || this.suspended)
+            return;
+        if (err !== null && !isMeshTransition(err)) {
+            this._log?.error('assistant', 'run-request watch failed — restarting', err);
+        }
+        else {
+            this._log?.debug('assistant', 'rearming consume', {
+                cause: err === null ? 'stream end' : 'mesh transition'
+            });
+        }
+        this._lastCapabilities = null;
+        const delay = isMeshTransition(err) ? this._retryMs : CONSUME_RETRY_MS;
+        this._retryMs = nextRetryDelay(err, delay);
+        this._retry = setTimeout(() => this._startConsume(), delay);
+    }
+    async _consume() {
+        const stream = this._engine.runRequestsWatch({});
+        this._requests = stream[Symbol.asyncIterator]();
+        this._reportCapabilities().catch(noop);
+        this._reconcileDeviceProfile().catch(noop);
+        while (true) {
+            const { value, done } = await this._requests.next();
+            if (done || this.closing || this.suspended)
+                return;
+            const requests = value.chunks ?? [];
+            for (const chunk of requests)
+                this._dispatch(chunk);
+            const live = new Set(requests.map((c) => c.runId));
+            for (const id of this._seen)
+                if (!live.has(id))
+                    this._seen.delete(id);
+        }
+    }
+    _dispatch(request) {
+        const runId = request.runId;
+        if (!runId || this._runs.has(runId) || this._seen.has(runId))
+            return;
+        this._seen.add(runId);
+        const settle = (async () => {
+            const agentId = request.runRequest?.agentId;
+            const agent = await this._engine.getAgent({ id: agentId }).catch(() => null);
+            if (!agent) {
+                this._seen.delete(runId);
+                return;
+            }
+            if (!agent.providerDeviceId?.equals(this._deviceId))
+                return;
+            if (await this._isHandled(request))
+                return;
+            this._log?.info('runs', 'run claimed', { runId, chatId: request.chatId, agentId });
+            const controller = new AbortController();
+            const prior = this._chats.get(request.chatId) ?? Promise.resolve();
+            const done = prior.then(() => this._execute(request, agent, controller));
+            const link = done.catch(noop);
+            this._chats.set(request.chatId, link);
+            this._runs.set(runId, {
+                controller,
+                done,
+                chatId: request.chatId,
+                model: agent.modelName,
+                executing: false
+            });
+            try {
+                await done;
+            }
+            finally {
+                this._runImageCacheNames.delete(runId);
+                this._runs.delete(runId);
+                this._yieldDownloads();
+                if (this._chats.get(request.chatId) === link)
+                    this._chats.delete(request.chatId);
+                this._reportCapabilities().catch(noop);
+            }
+        })();
+        settle.catch((err) => this._log?.error('assistant', `run ${runId} failed`, err));
+    }
+    async _citeWebSources(transcript, runId, result) {
+        const records = webSourcesFromToolResult(result);
+        if (records.length === 0)
+            return;
+        try {
+            await transcript.chunk({ type: 'sources', sources: { sources: records } });
+        }
+        catch (err) {
+            this._log?.warn('assistant', 'web sources chunk skipped', { runId, err });
+        }
+    }
+    async _searchKnowledge(chatId, messages, attachmentIds, signal, preparing) {
+        let lastUser;
+        for (let index = messages.length - 1; index >= 0; index--) {
+            if (messages[index].role === 'user') {
+                lastUser = messages[index];
+                break;
+            }
+        }
+        const query = lastUser?.content.trim();
+        if (!lastUser || !query)
+            return null;
+        try {
+            const search = await searchKnowledge(this._engine, {
+                chatId,
+                query,
+                attachmentIds: attachmentIds.length > 0 ? [...attachmentIds] : undefined
+            }, { signal, preparing });
+            if (!search.enabled)
+                return null;
+            if (!search.hasKnowledge)
+                return null;
+            return { search, lastUser, hits: search.hits ?? [] };
+        }
+        catch (err) {
+            if (err instanceof AbortedError)
+                return null;
+            this._log?.warn('assistant', 'knowledge search unavailable', err);
+            return null;
+        }
+    }
+    async _isHandled(request) {
+        const { chunks } = await this._engine.listChunks({
+            chatId: request.chatId,
+            type: 'run-status'
+        });
+        return (chunks ?? []).some((c) => c.runId === request.runId && TERMINAL_STATES.has(c.runStatus?.state ?? ''));
+    }
+    async _execute(request, agent, controller) {
+        const { chatId } = request;
+        const runId = request.runId;
+        const deviceId = this._deviceId;
+        if (this.suspended) {
+            this._seen.delete(runId);
+            return;
+        }
+        if (await this._isHandled(request))
+            return;
+        const fresh = await this._engine.getAgent({ id: agent.id }).catch(() => null);
+        if (!fresh || fresh.deletedAt || !fresh.providerDeviceId?.equals(deviceId))
+            return;
+        agent = fresh;
+        await this._reconcileCompaction(chatId);
+        if (request.parentId)
+            await this._deleteChatKvCache(chatId, 'superseding run');
+        const model = runnableModelName(agent.modelName, await this._ensureCapability(), this._mobileClass);
+        if (model !== agent.modelName) {
+            this._log?.warn('runs', 'model clamped to what this device can run', {
+                runId,
+                chatId,
+                requested: agent.modelName,
+                model
+            });
+            const inflight = this._runs.get(runId);
+            if (inflight)
+                this._runs.set(runId, { ...inflight, model });
+        }
+        const config = await this._engine.getConfig({}).catch(noop);
+        const configuredAgent = withConfigDefaults(agent, config);
+        this._log?.info('runs', 'run model resolved', {
+            runId,
+            model,
+            agentModel: agent.modelName,
+            warmedModel: this._warmedModelName
+        });
+        const transcript = new RunTranscript(this._engine, {
+            chatId,
+            runId,
+            deviceId,
+            model,
+            log: this._log
+        });
+        await this._compactIfNearFull({
+            chatId,
+            transcript,
+            trigger: 'before-run',
+            signal: controller.signal
+        });
+        const toolConfigsPromise = this._loadToolConfigs(agent.id);
+        const fsGrantsPromise = this._loadFsGrants(agent.id);
+        const all = await listHistoryChunks(this._engine, chatId);
+        const branches = historyBranches(all, runId);
+        const currentRepair = branches.repairByRunId.get(runId);
+        const repairParent = currentRepair
+            ? all.find((chunk) => chunk.id === currentRepair.parentId)
+            : undefined;
+        const acceptedRepairs = acceptedRepairCount(branches, runId);
+        const history = all.filter((chunk) => Boolean(chunk.compaction) ||
+            (chunk.runId !== runId &&
+                inputAvailableToRun(chunk, request.seq) &&
+                (!repairParent || chunk.seq <= repairParent.seq || chunk.runId === repairParent.runId) &&
+                isPromptChunk(chunk, branches)));
+        const { chunks: priorAsks } = await this._engine.listChunks({
+            chatId,
+            type: 'approval-request'
+        });
+        const { chunks: priorResults } = await this._engine.listChunks({ chatId, type: 'tool-result' });
+        let ran = (priorResults ?? []).some((chunk) => chunk.runId === runId &&
+            chunk.toolResult?.name !== SKILL_TOOL &&
+            !isDeniedResult(chunk.toolResult?.result));
+        const messages = historyFromChunks(history, staleToolRunIds(history, priorAsks ?? [], runId));
+        if (currentRepair)
+            messages.push({ role: 'user', content: currentRepair.promptText });
+        const diagramRepair = currentRepair !== undefined;
+        const runAgent = diagramRepair
+            ? {
+                ...configuredAgent,
+                toolsScope: 'selected',
+                enabledTools: [],
+                skillsScope: 'selected',
+                enabledSkills: []
+            }
+            : configuredAgent;
+        const seesImages = this._harness.supportsImagesFor
+            ? this._harness.supportsImagesFor(model)
+            : (this._harness.supportsImages ?? this._info.supportsImages) !== false;
+        let unreadableImages = new Map();
+        if (!seesImages) {
+            const dropped = messages.reduce((count, turn) => count + (turn.images?.length ?? 0), 0);
+            if (dropped && (this._harness.supportsImages ?? this._info.supportsImages)) {
+                this._log?.warn('assistant', `no projection pairing for ${model} — dropped ${dropped} image(s)`);
+            }
+            for (const turn of messages) {
+                if (turn.images?.length) {
+                    const names = turn.images.map((image) => image.fileName).join(', ');
+                    turn.content += `\n[Attached image${turn.images.length > 1 ? 's' : ''}: ${names} — not visible to this model]`;
+                }
+                delete turn.images;
+            }
+        }
+        else {
+            unreadableImages = await this._hydrateImages(messages, controller.signal, runId);
+        }
+        const settledWatch = this._watchSettled(chatId, runId, controller);
+        const ownershipWatch = this._watchOwnership(agent.id, controller);
+        let readinessError = null;
+        try {
+            await this._downloads?.waitUntilCached(model, controller.signal);
+        }
+        catch (err) {
+            readinessError = err instanceof Error ? err : new Error(String(err));
+        }
+        if (controller.signal.aborted) {
+            try {
+                const outcome = this._abortOutcome(runId, controller.signal.reason);
+                if (outcome.kind === 'replay')
+                    this._seen.delete(runId);
+                if (outcome.kind === 'failed') {
+                    await transcript.status({ state: 'failed', reason: outcome.reason });
+                }
+            }
+            finally {
+                transcript.close();
+                ownershipWatch.stop();
+                settledWatch.stop();
+            }
+            return;
+        }
+        if (readinessError) {
+            try {
+                await transcript.status({ state: 'failed', reason: runFailureNotice(readinessError) });
+            }
+            finally {
+                transcript.close();
+                ownershipWatch.stop();
+                settledWatch.stop();
+            }
+            return;
+        }
+        const inflight = this._runs.get(runId);
+        if (inflight)
+            this._runs.set(runId, { ...inflight, executing: true });
+        this._yieldDownloads();
+        const busyChatId = this._modelHolder(runId, chatId, model);
+        const executing = await transcript.status(busyChatId
+            ? { state: 'executing', progress: { phase: 'queued', busyChatId } }
+            : { state: 'executing' });
+        const runStatusId = executing.id;
+        const approvals = this._createApprove(chatId, runId, deviceId, agent.id, () => ran);
+        const modelWatch = this._watchModelProgress((runStatus) => transcript.progress(runStatusId, runStatus), busyChatId !== null);
+        let metrics;
+        const sourceTagFilter = createRagSourceTagFilter();
+        const retrievedRecords = [];
+        let answerText = '';
+        let ragInjected = false;
+        const flushTranscript = async () => {
+            const tail = sourceTagFilter.flush();
+            if (tail) {
+                answerText += tail;
+                await transcript.text('content', tail);
+            }
+            await transcript.flush();
+        };
+        let titleOutcome = null;
+        try {
+            const attachTurnIds = attachTurnDocumentIds(history);
+            if (attachTurnIds.length > 0)
+                backfillDocumentOnlyTurn(messages);
+            const knowledge = !diagramRepair &&
+                (toolsetEnabled('knowledge', runAgent.disabledToolsets) || attachTurnIds.length > 0)
+                ? await this._searchKnowledge(chatId, messages, attachTurnIds, controller.signal, modelWatch.documents)
+                : null;
+            if (controller.signal.aborted) {
+                const outcome = this._abortOutcome(runId, controller.signal.reason);
+                if (outcome.kind === 'replay') {
+                    this._seen.delete(runId);
+                    return;
+                }
+                if (outcome.kind === 'handoff')
+                    return;
+                await transcript.status({ state: 'failed', reason: outcome.reason, metrics });
+                return;
+            }
+            let documentsInjected = false;
+            let sourcesWritten = false;
+            if (knowledge) {
+                try {
+                    if (knowledge.search.errorMessage) {
+                        this._log?.warn('assistant', 'knowledge search failed', {
+                            error: knowledge.search.errorMessage
+                        });
+                    }
+                    const fullTextOnly = knowledge.hits.length > 0 && knowledge.hits.every(isFullTextHit);
+                    if (fullTextOnly) {
+                        knowledge.lastUser.content = `${formatFullDocumentContext(knowledge.hits)}\n\nThe user's message:\n${knowledge.lastUser.content}`;
+                        documentsInjected = true;
+                        if (knowledge.hits.some(isTruncatedFullTextHit)) {
+                            await transcript.chunk({
+                                type: 'sources',
+                                sources: { sources: [], notice: RAG_TRUNCATED_NOTICE }
+                            });
+                            sourcesWritten = true;
+                        }
+                    }
+                    else {
+                        const records = sourcesFromHits(knowledge.hits);
+                        const notice = chooseRagNotice({
+                            errorMessage: knowledge.search.errorMessage,
+                            hitCount: records.length,
+                            searchedCount: knowledge.search.searchedCount ?? 0,
+                            indexEmpty: Boolean(knowledge.search.indexEmpty),
+                            hasKnowledge: Boolean(knowledge.search.hasKnowledge),
+                            pendingReferenced: Boolean(knowledge.search.pendingReferenced),
+                            failedFiles: knowledge.search.failedFiles ?? [],
+                            pendingFiles: knowledge.search.pendingFiles ?? []
+                        });
+                        sourceTagFilter.add(records.map((record) => record.title));
+                        retrievedRecords.push(...records.map((record, index) => ({
+                            ...record,
+                            excerpt: knowledge.hits[index]?.content ?? record.excerpt
+                        })));
+                        await transcript.chunk({
+                            type: 'sources',
+                            sources: { sources: records, notice: notice ?? undefined }
+                        });
+                        sourcesWritten = true;
+                        if (records.length > 0) {
+                            knowledge.lastUser.content = `${formatRagContext(knowledge.hits, knowledge.search.availableFiles ?? [])}\n\nThe user's message:\n${knowledge.lastUser.content}\n\n${RAG_CITATION_LINE}`;
+                            ragInjected = true;
+                            documentsInjected = true;
+                        }
+                        else if (knowledge.search.availableFiles?.length) {
+                            knowledge.lastUser.content += `\n\n[Files indexed and available now: ${knowledge.search.availableFiles.join(', ')}. No relevant excerpts were retrieved for this question. Their current availability supersedes earlier indexing notices.]`;
+                        }
+                    }
+                    if (knowledge.search.pendingFiles?.length) {
+                        knowledge.lastUser.content += `\n\n[Files not yet available for this reply: ${knowledge.search.pendingFiles.join(', ')}.]`;
+                    }
+                }
+                catch (err) {
+                    this._log?.warn('assistant', 'knowledge injection skipped', err);
+                }
+            }
+            const hasAudio = messages.some((turn) => turn.audioAttachments?.length);
+            if (hasAudio)
+                modelWatch.transcribe(true);
+            await this._hydrateAudio(messages, controller.signal);
+            if (hasAudio)
+                modelWatch.transcribe(false);
+            backfillImageOnlyTurns(messages);
+            annotateDocumentAttachments(messages);
+            if (!diagramRepair && attachTurnIds.length > 0 && !documentsInjected) {
+                const reason = documentUnreadReason({
+                    knowledgeOn: toolsetEnabled('knowledge', runAgent.disabledToolsets),
+                    failedFiles: knowledge?.search?.failedFiles,
+                    attachedCount: attachTurnIds.length
+                });
+                const lastUser = messages.findLast((turn) => turn.role === 'user');
+                if (lastUser) {
+                    lastUser.content = `${lastUser.content}\n${documentUnreadNotice(reason, attachTurnIds.length > 1)}`;
+                }
+                if (!sourcesWritten) {
+                    try {
+                        await transcript.chunk({
+                            type: 'sources',
+                            sources: {
+                                sources: [],
+                                notice: reason === 'knowledge-off' ? RAG_KNOWLEDGE_OFF_NOTICE : RAG_UNAVAILABLE_NOTICE
+                            }
+                        });
+                    }
+                    catch (err) {
+                        this._log?.warn('assistant', 'unread-document notice skipped', err);
+                    }
+                }
+            }
+            annotateUnreadableImages(unreadableImages);
+            const toolConfigs = await toolConfigsPromise;
+            const { roots, write } = await fsGrantsPromise;
+            const { grantedDirs, grantedDrives, driveOp } = await resolveFsGrants(roots, this._drives, (key, err) => this._log?.warn('assistant', 'drive grant dropped', {
+                key,
+                error: err instanceof Error ? err.message : String(err)
+            }));
+            if (await this._isHandled(request))
+                return;
+            const cacheKey = diagramRepair ? undefined : chatRepairKvCacheKey(chatId, acceptedRepairs);
+            this._log?.info('runs', 'completion requested', {
+                runId,
+                model,
+                cacheKey,
+                turns: messages.length
+            });
+            const events = this._harness.completion({
+                model,
+                agent: runAgent,
+                messages,
+                cacheKey,
+                thinkingDefault: config ? (config.thinkingEnabled ? 'enabled' : 'disabled') : undefined,
+                toolConfigs,
+                grantedDirs,
+                grantedDrives,
+                driveOp,
+                grantedWriteDirs: write,
+                approve: approvals.approve,
+                attach: (input) => this._uploadGenerated(chatId, runId, deviceId, input),
+                fetchAttachment: (query) => this._fetchAttachment(chatId, query),
+                ragSearch: async (input) => {
+                    const found = await raceAbort(this._engine.ragSearch({
+                        chatId,
+                        query: input.query,
+                        mode: 'tool',
+                        limit: input.limit
+                    }), controller.signal);
+                    const hits = found.hits ?? [];
+                    const records = sourcesFromHits(hits);
+                    if (records.length > 0) {
+                        try {
+                            sourceTagFilter.add(records.map((record) => record.title));
+                            retrievedRecords.push(...records.map((record, index) => ({
+                                ...record,
+                                excerpt: hits[index]?.content ?? record.excerpt
+                            })));
+                            await transcript.chunk({
+                                type: 'sources',
+                                sources: { sources: records }
+                            });
+                        }
+                        catch (err) {
+                            this._log?.warn('assistant', 'rag tool sources chunk skipped', { runId, err });
+                        }
+                    }
+                    return {
+                        enabled: found.enabled === true,
+                        indexEmpty: found.indexEmpty === true,
+                        hasKnowledge: found.hasKnowledge === true,
+                        pendingReferenced: found.pendingReferenced === true,
+                        errorMessage: found.errorMessage ?? undefined,
+                        hits
+                    };
+                },
+                progress: (update) => modelWatch.image(update),
+                generationParams: diagramRepair ? { reasoning_budget: 0 } : undefined,
+                signal: controller.signal
+            });
+            let harnessEvents = 0;
+            for await (const event of events) {
+                harnessEvents++;
+                modelWatch.clear();
+                if (event.type === 'content' || event.type === 'thinking') {
+                    const text = event.type === 'content'
+                        ? sourceTagFilter.push(event.text)
+                        : event.text;
+                    if (text) {
+                        if (event.type === 'content')
+                            answerText += text;
+                        await transcript.text(event.type, text);
+                    }
+                    continue;
+                }
+                if (event.type === 'metrics') {
+                    const { type, ...rest } = event;
+                    metrics = rest;
+                    this._log?.info('runs', 'run metrics', { runId, ...runMetricsSummary(rest) });
+                    continue;
+                }
+                await flushTranscript();
+                if (event.type === 'error') {
+                    const folded = isContextOverflowFailure(event.message) &&
+                        (await this._runCompaction({
+                            chatId,
+                            transcript,
+                            trigger: 'overflow',
+                            signal: controller.signal
+                        }));
+                    await transcript.status({
+                        state: 'failed',
+                        reason: runFailureNotice(event.message),
+                        metrics
+                    });
+                    if (folded) {
+                        await this._engine
+                            .runAgent({ chatId, agentId: agent.id, parentRunId: runId })
+                            .catch((err) => this._log?.warn('runs', 'compaction retry not queued', { runId, err }));
+                    }
+                    titleOutcome = 'ended';
+                    return;
+                }
+                if (event.type === 'aborted') {
+                    const outcome = this._abortOutcome(runId, controller.signal.reason);
+                    if (outcome.kind === 'replay') {
+                        this._seen.delete(runId);
+                        return;
+                    }
+                    if (outcome.kind === 'handoff')
+                        return;
+                    await transcript.status({ state: 'failed', reason: outcome.reason, metrics });
+                    titleOutcome = 'ended';
+                    return;
+                }
+                if (event.type === 'tool-call') {
+                    this._log?.info('runs', 'tool call', { runId, name: event.name });
+                    await transcript.chunk({
+                        type: 'tool-call',
+                        toolCall: {
+                            name: event.name,
+                            arguments: event.args
+                        },
+                        effect: event.effect === 'read' ? 'read' : 'write',
+                        display: event.display,
+                        rawCall: typeof event.rawCall === 'string' ? event.rawCall : undefined
+                    });
+                }
+                else if (event.type === 'tool-result') {
+                    if (isDeniedResult(event.result)) {
+                        this._log?.info('approvals', 'tool ran denied', { runId, tool: event.name });
+                    }
+                    else if (event.name !== SKILL_TOOL) {
+                        ran = true;
+                    }
+                    if (WEB_TOOLS.includes(String(event.name))) {
+                        await this._citeWebSources(transcript, runId, event.result);
+                    }
+                    await transcript.chunk({
+                        type: 'tool-result',
+                        toolResult: { name: event.name, result: withoutDataChannel(event.result) }
+                    });
+                }
+                else if (event.type === 'tool-activity') {
+                    void this._engine
+                        .recordToolActivity({
+                        agentId: runAgent.id,
+                        toolName: event.name,
+                        decision: event.decision,
+                        effect: event.effect,
+                        arguments: event.args,
+                        resource: event.resource ?? undefined,
+                        chatId,
+                        runId,
+                        at: Date.now()
+                    })
+                        .catch((err) => this._log?.warn('runs', 'tool activity record failed', { runId, err }));
+                }
+                else {
+                    this._log?.warn('assistant', 'unknown harness event dropped', { type: event.type });
+                }
+            }
+            this._log?.info('runs', 'harness stream ended', { runId, events: harnessEvents });
+            if (await settledWithin(flushTranscript(), FINAL_FLUSH_MS)) {
+                this._log?.info('runs', 'final flush done', { runId });
+            }
+            else {
+                this._log?.warn('runs', 'completing over a stranded flush', {
+                    runId,
+                    pending: transcript.pending()
+                });
+            }
+            const citedTitles = ragInjected ? citedByPhraseOverlap(answerText, retrievedRecords) : null;
+            const foldedNow = metrics
+                ? await this._compactIfNearFull({
+                    chatId,
+                    transcript,
+                    trigger: 'turn-filled-window',
+                    metrics: metrics,
+                    signal: controller.signal
+                })
+                : false;
+            const settled = foldedNow ? withoutOccupancy(metrics) : metrics;
+            await transcript.status({
+                state: 'completed',
+                metrics: citedTitles ? { ...settled, citedTitles } : settled
+            });
+            titleOutcome = 'completed';
+        }
+        catch (err) {
+            const outcome = controller.signal.aborted
+                ? this._abortOutcome(runId, controller.signal.reason)
+                : null;
+            if (outcome?.kind === 'replay') {
+                this._seen.delete(runId);
+                return;
+            }
+            if (outcome?.kind === 'handoff')
+                return;
+            await flushTranscript();
+            await transcript.status({ state: 'failed', reason: runFailureNotice(err), metrics });
+            titleOutcome = 'ended';
+        }
+        finally {
+            transcript.close();
+            modelWatch.stop();
+            ownershipWatch.stop();
+            await approvals.settle({ preservePending: isLifecycleTeardown(controller.signal.reason) });
+            settledWatch.stop();
+            if (titleOutcome && !diagramRepair) {
+                void this._autoTitle(chatId, messages, model, runAgent, titleOutcome === 'completed');
+            }
+        }
+    }
+    async _loadToolConfigs(agentId) {
+        const { configs } = await this._engine.listToolConfigs({ agentId }).catch((err) => {
+            this._log?.warn('assistant', 'tool configs read failed', err);
+            return { configs: [] };
+        });
+        const map = {};
+        for (const row of configs ?? []) {
+            if (row?.toolName && row.settings && typeof row.settings === 'object') {
+                map[row.toolName] = row.settings;
+            }
+        }
+        return map;
+    }
+    async _loadFsGrants(agentId) {
+        const [roots, write] = await Promise.all([
+            this._readRootGrants(fsGrantKey(agentId)),
+            this._readWriteGrants(fsWriteGrantKey(agentId))
+        ]);
+        return { roots, write };
+    }
+    async _readRootGrants(key) {
+        const { value } = await this._engine.configGet({ key }).catch((err) => {
+            this._log?.warn('assistant', 'fs grants read failed', { key, err });
+            return { value: null };
+        });
+        return fsGrantsFrom(value);
+    }
+    async _readWriteGrants(key) {
+        const { value } = await this._engine.configGet({ key }).catch((err) => {
+            this._log?.warn('assistant', 'fs write grants read failed', { key, err });
+            return { value: null };
+        });
+        return grantedDirsFrom(value);
+    }
+    async _fetchAttachment(chatId, { attachmentId, signal, meta } = {}) {
+        if (!attachmentId) {
+            const { chunks } = await raceAbort(this._engine.listChunks({ chatId, type: 'attachment' }), signal);
+            attachmentId = (chunks ?? [])
+                .map((chunk) => chunk.attachment)
+                .filter((file) => file && !file.deletedAt && IMAGE_MIMES.has(file.mimeType.toLowerCase()))
+                .at(-1)?.id;
+        }
+        if (!attachmentId)
+            return null;
+        const stream = this._engine.fileRead({ chatId, fileId: attachmentId, metadataOnly: meta });
+        const abort = () => stream.destroy();
+        const pieces = [];
+        let head = null;
+        stream.on('error', noop);
+        signal?.addEventListener('abort', abort, { once: true });
+        try {
+            if (signal?.aborted)
+                throw new AbortedError();
+            for await (const frame of stream) {
+                if (frame.metadata) {
+                    const { id, fileName, mimeType, byteLength } = frame.metadata;
+                    head = { id, fileName, mimeType, byteLength };
+                }
+                if (frame.data)
+                    pieces.push(frame.data);
+            }
+            if (signal?.aborted)
+                throw new AbortedError();
+            return head && (meta ? head : { ...head, bytes: Buffer.concat(pieces) });
+        }
+        finally {
+            signal?.removeEventListener('abort', abort);
+            stream.destroy();
+        }
+    }
+    async _readBlob(url, signal) {
+        if (!url || signal?.aborted)
+            return null;
+        const pending = defaultFetch(url).catch(() => null);
+        try {
+            const response = await raceInactivity(pending, signal, this._blobReadTimeoutMs);
+            const bytes = response?.ok
+                ? await drainBody(response.body, signal, this._blobReadTimeoutMs)
+                : null;
+            return bytes?.length ? bytes : null;
+        }
+        catch {
+            pending.then((response) => response?.body?.cancel(), noop);
+            return null;
+        }
+    }
+    async _uploadGenerated(chatId, runId, deviceId, { fileName, mimeType, bytes, raw }) {
+        const duplex = this._engine.uploadAttachment();
+        duplex.write({ chatId, runId, originDeviceId: deviceId, fileName, mimeType, raw });
+        const buf = Buffer.isBuffer(bytes)
+            ? bytes
+            : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        for (let i = 0; i < buf.length; i += UPLOAD_FRAME_BYTES) {
+            duplex.write({ data: buf.subarray(i, i + UPLOAD_FRAME_BYTES) });
+        }
+        duplex.end();
+        let attachment = null;
+        for await (const frame of duplex) {
+            if (frame.attachment)
+                attachment = frame.attachment;
+        }
+        if (!attachment)
+            throw new Error('attachment upload ended without a record');
+        return attachment;
+    }
+    async _hydrateAudio(messages, signal) {
+        const turns = messages.filter((turn) => turn.audioAttachments?.length);
+        if (!turns.length)
+            return;
+        for (const turn of turns) {
+            for (const ref of turn.audioAttachments ?? []) {
+                if (signal.aborted)
+                    return;
+                const block = await this._transcribeAttachment(ref, signal);
+                turn.content = turn.content.trim() ? `${turn.content}\n\n${block}` : block;
+            }
+            delete turn.audioAttachments;
+        }
+    }
+    async _transcribeAttachment(ref, signal) {
+        const label = `Attached audio "${ref.fileName}"`;
+        const cached = this._audioTranscripts.get(ref.blobId);
+        if (cached !== undefined) {
+            return cached ? audioTranscriptBlock(ref.fileName, cached) : silentAudioNotice(ref.fileName);
+        }
+        if (!this._harness.transcribe) {
+            return unheardAudioNotice(label, 'transcription is unavailable on this device', {
+                retryable: false
+            });
+        }
+        try {
+            const bytes = await this._readBlob(ref.url, signal);
+            if (!bytes) {
+                return unheardAudioNotice(label, 'its content has not reached this device — the upload may still be syncing');
+            }
+            const model = mediaModelNameFor('transcription', await this._persistedProfile());
+            await this.ensureMediaModelUnpaused('transcription', model);
+            await this._downloads?.waitUntilCached(model, signal);
+            const text = (await this._harness.transcribe({ model: '', audio: bytes, signal })).trim();
+            this._audioTranscripts.set(ref.blobId, text);
+            if (!text)
+                return silentAudioNotice(ref.fileName);
+            return audioTranscriptBlock(ref.fileName, text);
+        }
+        catch (err) {
+            if (signal.aborted)
+                throw err;
+            this._log?.warn('assistant', `audio transcription failed — ${ref.fileName}`, err);
+            return unheardAudioNotice(label, 'transcription failed on this device');
+        }
+    }
+    async _hydrateImages(messages, signal, runId) {
+        const unreadable = new Map();
+        const turns = messages.filter((turn) => turn.images?.length);
+        if (!turns.length)
+            return unreadable;
+        const inUse = new Set(turns.flatMap((turn) => (turn.images ?? []).map(imageCacheName)));
+        this._runImageCacheNames.set(runId, inUse);
+        const dir = this._imageCacheDir;
+        await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+        for (const turn of turns) {
+            const dropped = [];
+            for (const image of turn.images ?? []) {
+                try {
+                    const file = await this._hydrateImage(dir, image, signal);
+                    turn.attachments = [...(turn.attachments ?? []), { path: file }];
+                }
+                catch (err) {
+                    if (signal.aborted)
+                        throw err;
+                    this._log?.error('assistant', `image hydration failed — skipped ${image.fileName}`, err);
+                    dropped.push(image.fileName);
+                }
+            }
+            if (dropped.length)
+                unreadable.set(turn, dropped);
+            delete turn.images;
+        }
+        return unreadable;
+    }
+    async _hydrateImage(dir, image, signal) {
+        const file = path.join(dir, imageCacheName(image));
+        const cached = await fs.promises.stat(file).catch(() => null);
+        if (!cached?.size) {
+            const raw = await this._readBlob(image.url, signal);
+            if (signal.aborted)
+                throw new Error('hydration aborted');
+            if (!raw)
+                throw new Error(`empty download for ${image.fileName}`);
+            const bytes = await normalizeImageForModel(raw);
+            const staging = `${file}.partial-${crypto.randomBytes(4).toString('hex')}`;
+            await fs.promises.writeFile(staging, bytes, { mode: 0o600 });
+            await fs.promises.rename(staging, file);
+        }
+        else {
+            const now = new Date();
+            await fs.promises.utimes(file, now, now).catch(() => null);
+        }
+        return file;
+    }
+    async _compactIfNearFull(params) {
+        const { chatId, transcript, trigger, signal } = params;
+        const metrics = params.metrics ?? (await this._lastRunMetrics(chatId));
+        if (!nearContextLimit(metrics.cacheTokens, metrics.ctxSize))
+            return false;
+        if (!canCompact(metrics.ctxSize)) {
+            this._log?.debug('runs', 'chat near its window but under the compaction floor', {
+                chatId,
+                ctxSize: metrics.ctxSize
+            });
+            return false;
+        }
+        return this._runCompaction({ chatId, transcript, trigger, signal, occupancy: metrics });
+    }
+    async _runCompaction(params) {
+        const { chatId, transcript, trigger, signal } = params;
+        let statusId = null;
+        const started = Date.now();
+        try {
+            const result = await this.compactChat(chatId, {
+                onFold: async () => {
+                    const status = await transcript.status({
+                        state: 'executing',
+                        progress: { phase: 'compacting' }
+                    });
+                    statusId = status.id;
+                },
+                ...(signal ? { signal } : {})
+            });
+            this._log?.info('runs', 'compaction', {
+                chatId,
+                trigger,
+                compacted: result.compacted,
+                reason: result.reason ?? null,
+                foldedTurns: result.foldedTurns ?? 0,
+                cacheTokens: params.occupancy?.cacheTokens ?? null,
+                ctxSize: params.occupancy?.ctxSize ?? null,
+                announced: statusId !== null,
+                ms: Date.now() - started
+            });
+            return result.compacted;
+        }
+        catch (err) {
+            this._log?.warn('runs', 'compaction failed', { chatId, trigger, err });
+            return false;
+        }
+        finally {
+            if (trigger === 'before-run' && statusId) {
+                await transcript.progress(statusId, { state: 'executing' }).catch(noop);
+            }
+        }
+    }
+    async _lastRunMetrics(chatId) {
+        const deviceId = this._deviceId;
+        const { chunks } = await this._engine
+            .listChunks({ chatId, type: 'run-status' })
+            .catch(() => ({ chunks: [] }));
+        const statuses = chunks ?? [];
+        for (let index = statuses.length - 1; index >= 0; index--) {
+            const chunk = statuses[index];
+            const metrics = chunk.runStatus?.metrics;
+            if (chunk.runStatus?.state !== 'completed' || !metrics)
+                continue;
+            if (!chunk.originDeviceId?.equals(deviceId))
+                return {};
+            const parsed = metrics;
+            return { cacheTokens: parsed.cacheTokens, ctxSize: parsed.ctxSize };
+        }
+        return {};
+    }
+    async compactChat(chatId, options = {}) {
+        if (!this.opened)
+            await this.ready();
+        const deviceId = this._deviceId;
+        const chat = await this._engine.getChat({ id: chatId }).catch(() => null);
+        if (!chat)
+            return { compacted: false, reason: 'unknown chat' };
+        const agent = await this._engine.getAgent({ id: chat.agentId }).catch(() => null);
+        if (!agent || !agent.providerDeviceId?.equals(deviceId)) {
+            return { compacted: false, reason: 'not the provider device' };
+        }
+        const model = runnableModelName(agent.modelName, await this._ensureCapability(), this._mobileClass);
+        const config = await this._engine.getConfig({}).catch(() => null);
+        const ctxSize = agent.ctxSize || config?.ctxSize || undefined;
+        if (ctxSize !== undefined && !canCompact(ctxSize)) {
+            return { compacted: false, reason: 'below-floor' };
+        }
+        const stored = await listHistoryChunks(this._engine, chatId);
+        const branches = historyBranches(stored);
+        const chunks = stored.filter((chunk) => isPromptChunk(chunk, branches));
+        const { chunks: priorAsks } = await this._engine
+            .listChunks({ chatId, type: 'approval-request' })
+            .catch(() => ({ chunks: [] }));
+        const lastThroughId = lastCompactedThroughId(chunks);
+        const lastThroughSeq = chunks.find((chunk) => chunk.id === lastThroughId)?.seq ?? -1;
+        const userTurns = chunks.filter((chunk) => chunk.userMessage).length;
+        let announced = false;
+        let keepTurns = COMPACTION_KEEP_TURNS;
+        for (;;) {
+            const boundary = compactionBoundary(chunks, keepTurns);
+            if (!boundary)
+                return { compacted: false, reason: 'nothing-to-fold' };
+            const through = chunks.find((chunk) => chunk.id === boundary.throughId);
+            if (!through)
+                return { compacted: false, reason: 'nothing-to-fold' };
+            if (through.seq <= lastThroughSeq)
+                return { compacted: false, reason: 'already-compacted' };
+            const inRange = chunks.filter((chunk) => chunk.seq <= through.seq);
+            const folded = historyFromChunks(inRange, staleToolRunIds(inRange, priorAsks ?? [], ''));
+            if (!announced) {
+                await options.onFold?.();
+                announced = true;
+            }
+            const attempt = await this._summarize(folded, model, withConfigDefaults(agent, config), options.signal);
+            if (!attempt.summary) {
+                if (attempt.overflowed && boundary.foldedTurns > 1) {
+                    keepTurns = userTurns - Math.floor(boundary.foldedTurns / 2);
+                    continue;
+                }
+                return { compacted: false, reason: 'the model produced no summary' };
+            }
+            const summary = attempt.summary;
+            if (!foldReducesPrompt(folded, summary)) {
+                return { compacted: false, reason: 'summary-not-smaller' };
+            }
+            if (options.signal?.aborted)
+                return { compacted: false, reason: 'canceled' };
+            await this._engine.appendChunk({
+                chatId,
+                type: 'compaction',
+                compaction: { summary, throughId: boundary.throughId },
+                originDeviceId: deviceId
+            });
+            await this._deleteChatKvCache(chatId, 'compaction');
+            this._log?.info('runs', 'chat compacted', {
+                chatId,
+                foldedTurns: boundary.foldedTurns,
+                summaryChars: summary.length
+            });
+            return { compacted: true, foldedTurns: boundary.foldedTurns };
+        }
+    }
+    async _summarize(turns, model, agent, signal) {
+        const hasPriorSummary = turns[0]?.content.startsWith(COMPACTION_TURN_PREFIX) === true;
+        const events = this._harness.completion({
+            model,
+            agent: {
+                ...agent,
+                toolsScope: 'selected',
+                enabledTools: [],
+                skillsScope: 'selected',
+                enabledSkills: []
+            },
+            messages: [
+                {
+                    role: 'user',
+                    content: buildCompactionPrompt(turns.map((turn) => ({ role: turn.role, content: turn.content })), hasPriorSummary)
+                }
+            ],
+            generationParams: { reasoning_budget: 0 },
+            signal: signal ?? this._lifecycle.signal
+        });
+        let text = '';
+        let failed = null;
+        for await (const event of events) {
+            if (event.type === 'content' && typeof event.text === 'string')
+                text += event.text;
+            else if (event.type === 'error') {
+                failed = typeof event.message === 'string' ? event.message : 'summarizer failed';
+                break;
+            }
+            else if (event.type === 'aborted') {
+                failed = 'summarizer aborted';
+                break;
+            }
+            else if (event.type === 'done')
+                break;
+        }
+        if (failed !== null) {
+            this._log?.warn('runs', 'summarizer failed mid-stream', { chars: text.length, failed });
+            return { summary: null, overflowed: isContextOverflowFailure(failed) };
+        }
+        return { summary: parseCompactionSummary(text), overflowed: false };
+    }
+    async _autoTitle(chatId, messages, model, agent, probe) {
+        try {
+            const first = messages.find((turn) => turn.role === 'user' && turn.content.trim());
+            if (!first)
+                return;
+            const chat = await this._engine.getChat({ id: chatId });
+            if (!isDefaultChatTitle(chat?.title))
+                return;
+            await this._generateChatTitle({ chatId, input: first.content, model, agent, probe });
+        }
+        catch (err) {
+            this._log?.warn('runs', 'auto-title skipped', { chatId, err });
+        }
+    }
+    async _generateChatTitle(params) {
+        const { chatId, input, model, agent, probe } = params;
+        const prompt = input.trim();
+        if (!prompt)
+            return null;
+        let generated = null;
+        if (probe && !this.closing) {
+            try {
+                generated = await this._titleFromCompletion({
+                    input: prompt,
+                    model,
+                    agent,
+                    signal: this._lifecycle.signal
+                });
+            }
+            catch (err) {
+                this._log?.warn('runs', 'title completion failed', { chatId, err });
+            }
+        }
+        const title = generated ?? deriveChatTitle(prompt);
+        if (!title)
+            return null;
+        await this._engine.renameChat({ id: chatId, title });
+        this._log?.info('runs', 'chat titled', {
+            chatId,
+            title,
+            source: generated ? 'model' : 'heuristic'
+        });
+        return title;
+    }
+    async _titleFromCompletion(params) {
+        const { input, model, agent, signal } = params;
+        const events = this._harness.completion({
+            model,
+            agent: {
+                ...agent,
+                toolsScope: 'selected',
+                enabledTools: [],
+                skillsScope: 'selected',
+                enabledSkills: []
+            },
+            messages: [{ role: 'user', content: buildTitlePrompt(input) }],
+            generationParams: { reasoning_budget: 0 },
+            responseFormat: {
+                type: 'json_schema',
+                json_schema: {
+                    name: 'chat_title',
+                    schema: {
+                        type: 'object',
+                        properties: { title: { type: 'string' } },
+                        required: ['title'],
+                        additionalProperties: false
+                    }
+                }
+            },
+            signal
+        });
+        let text = '';
+        for await (const event of events) {
+            if (event.type === 'content' && typeof event.text === 'string')
+                text += event.text;
+            else if (event.type === 'error' || event.type === 'aborted' || event.type === 'done')
+                break;
+        }
+        return parseTitleResponse(text);
+    }
+    _createApprove(chatId, runId, deviceId, agentId, hasRun) {
+        const waiters = new Map();
+        let latestChunks = [];
+        let watcher = null;
+        let closing = false;
+        const pump = async (source) => {
+            while (true) {
+                const { value, done } = await source.next();
+                if (done)
+                    return;
+                latestChunks = value.chunks ?? [];
+                for (const chunk of latestChunks) {
+                    const status = chunk.approvalRequest?.status;
+                    if (!status || status === 'pending')
+                        continue;
+                    const waiter = waiters.get(chunk.id);
+                    if (!waiter)
+                        continue;
+                    waiters.delete(chunk.id);
+                    this._log?.info('approvals', `answer ${status}`, {
+                        runId,
+                        chatId,
+                        chunkId: chunk.id,
+                        tool: waiter.tool
+                    });
+                    waiter.resolve(status === 'approved');
+                }
+            }
+        };
+        const ensureWatch = () => {
+            if (watcher)
+                return;
+            const opened = this._engine
+                .chunksWatch({ chatId, type: 'approval-request' })[Symbol.asyncIterator]();
+            watcher = opened;
+            pump(opened)
+                .catch((err) => {
+                if (closing)
+                    this._log?.debug('assistant', 'approval watch closed', err);
+                else
+                    this._log?.error('assistant', 'approval watch failed', err);
+            })
+                .finally(() => {
+                for (const [id, waiter] of waiters) {
+                    this._log?.warn('approvals', 'deny: answer watch closed', {
+                        runId,
+                        chunkId: id,
+                        tool: waiter.tool
+                    });
+                    waiter.resolve(false);
+                }
+                if (watcher === opened)
+                    watcher = null;
+            });
+        };
+        const asksForRun = async () => {
+            const { chunks } = await this._engine
+                .listChunks({ chatId, type: 'approval-request' })
+                .catch(() => ({ chunks: [] }));
+            return (chunks ?? []).filter((chunk) => chunk.runId === runId);
+        };
+        const sameCall = (chunk, call) => {
+            const ask = chunk.approvalRequest;
+            if (!ask || ask.name !== call.name)
+                return false;
+            return ((ask.resource?.kind ?? null) === (call.resource?.kind ?? null) &&
+                (ask.resource?.label ?? null) === (call.resource?.label ?? null) &&
+                JSON.stringify(ask.arguments) === JSON.stringify(call.arguments));
+        };
+        const park = (chunkId, tool) => {
+            const status = latestChunks.find((c) => c.id === chunkId)?.approvalRequest?.status;
+            if (status && status !== 'pending') {
+                this._log?.info('approvals', `answer ${status} (raced the ask)`, { runId, chunkId, tool });
+                return Promise.resolve(status === 'approved');
+            }
+            return new Promise((resolve) => waiters.set(chunkId, { resolve, tool }));
+        };
+        const approve = async (call) => {
+            const { rules } = await this._engine.listApprovalRules({}).catch((err) => {
+                this._log?.warn('approvals', 'rule lookup failed, asking instead', { runId, err });
+                return { rules: [] };
+            });
+            const rule = matchApprovalRule(rules ?? [], {
+                toolName: call.name,
+                resource: call.resource,
+                agentId
+            });
+            if (rule) {
+                this._log?.info('approvals', `rule ${rule.decision}`, {
+                    runId,
+                    chatId,
+                    tool: call.name,
+                    resource: call.resource?.label
+                });
+                return rule.decision === 'allow';
+            }
+            ensureWatch();
+            const prior = (await asksForRun()).findLast((chunk) => sameCall(chunk, call));
+            if (prior) {
+                const status = prior.approvalRequest?.status;
+                if (!status || status === 'pending') {
+                    this._log?.info('approvals', 'rebinding the ask this run parked on', {
+                        runId,
+                        chatId,
+                        chunkId: prior.id,
+                        tool: call.name
+                    });
+                    return park(prior.id, call.name);
+                }
+                if (!hasRun()) {
+                    this._log?.info('approvals', `answer ${status} (from before the app closed)`, {
+                        runId,
+                        chatId,
+                        chunkId: prior.id,
+                        tool: call.name
+                    });
+                    return status === 'approved';
+                }
+                this._log?.info('approvals', 'asking again: the replay would repeat a call that ran', {
+                    runId,
+                    chatId,
+                    priorChunkId: prior.id,
+                    tool: call.name
+                });
+            }
+            const approvalRequest = {
+                status: 'pending',
+                name: call.name,
+                arguments: call.arguments,
+                resource: call.resource ?? undefined,
+                agentId
+            };
+            const chunk = await this._engine.appendChunk({
+                chatId,
+                runId,
+                type: 'approval-request',
+                approvalRequest,
+                originDeviceId: deviceId,
+                effect: call.effect === 'read' ? 'read' : 'write',
+                intent: call.intent ?? undefined,
+                display: call.display ?? undefined
+            });
+            this._log?.info('approvals', 'ask', {
+                runId,
+                chatId,
+                chunkId: chunk.id,
+                tool: call.name,
+                resource: call.resource?.label
+            });
+            return park(chunk.id, call.name);
+        };
+        const settle = async ({ preservePending = false } = {}) => {
+            if (!preservePending) {
+                for (const ask of await asksForRun()) {
+                    if (ask.approvalRequest?.status !== 'pending')
+                        continue;
+                    this._log?.warn('approvals', 'deny: unanswered at run end', {
+                        runId,
+                        chunkId: ask.id,
+                        tool: ask.approvalRequest?.name
+                    });
+                    await this._engine.resolveApproval({ id: ask.id, approved: false });
+                }
+                for (const waiter of waiters.values())
+                    waiter.resolve(false);
+            }
+            waiters.clear();
+            closing = true;
+            await watcher?.return?.();
+            watcher = null;
+        };
+        return { approve, settle };
+    }
+    _abortOutcome(runId, reason) {
+        const known = knownAbortOutcome(reason);
+        if (reason === RUNNER_DIED && this._harnessDeath) {
+            return { kind: 'failed', reason: this._harnessDeath };
+        }
+        if (known)
+            return known;
+        if (this.suspended)
+            return { kind: 'replay' };
+        if (reason !== undefined) {
+            this._log?.warn('runs', 'run aborted for an unrecognised reason', { runId, reason });
+        }
+        return { kind: 'failed', reason: RUN_FAILURE_REASONS.runtimeEndedTurn };
+    }
+    _watchSettled(chatId, runId, controller) {
+        const it = this._engine.chunksWatch({ chatId, type: 'run-status' })[Symbol.asyncIterator]();
+        const watching = (async () => {
+            while (true) {
+                const { value, done } = await it.next();
+                if (done)
+                    return;
+                const settled = (value.chunks ?? []).some((c) => c.runId === runId && TERMINAL_STATES.has(c.runStatus?.state ?? ''));
+                if (settled) {
+                    controller.abort(RUN_SETTLED);
+                    return;
+                }
+            }
+        })();
+        watching.catch((err) => {
+            if (this.closing || isStreamDestroyed(err))
+                return;
+            this._log?.error('assistant', 'settled watch failed', err);
+        });
+        return {
+            stop: () => {
+                it.return?.()?.catch?.(noop);
+            }
+        };
+    }
+    _watchOwnership(agentId, controller) {
+        const deviceId = this._deviceId;
+        const it = this._engine.agentsWatch({})[Symbol.asyncIterator]();
+        const watching = (async () => {
+            while (true) {
+                const { value, done } = await it.next();
+                if (done)
+                    return;
+                const row = (value.agents ?? []).find((a) => a.id === agentId);
+                if (!row || row.deletedAt || !row.providerDeviceId?.equals(deviceId)) {
+                    controller.abort(OWNERSHIP_LOST);
+                    return;
+                }
+            }
+        })();
+        watching.catch((err) => {
+            if (this.closing || isStreamDestroyed(err))
+                return;
+            this._log?.error('assistant', 'ownership watch failed', err);
+        });
+        return {
+            stop: () => {
+                it.return?.()?.catch?.(noop);
+            }
+        };
+    }
+    _yieldDownloads() {
+        this._downloads?.yieldToRuns([...this._runs.values()].filter((run) => run.executing).map((run) => run.model));
+    }
+    _logModelStatus(state) {
+        if (typeof state !== 'object' || state === null)
+            return;
+        if (!('status' in state) || typeof state.status !== 'string')
+            return;
+        if (!('model' in state) || typeof state.model !== 'string')
+            return;
+        const { status, model } = state;
+        if (status === 'downloading' || this._modelStatusLogged.get(model) === status)
+            return;
+        this._modelStatusLogged.set(model, status);
+        this._log?.info('models', `model ${status}`, { model });
+    }
+    _modelHolder(runId, chatId, model) {
+        for (const [id, run] of this._runs) {
+            if (id !== runId && run.executing && run.chatId !== chatId && run.model === model) {
+                return run.chatId;
+            }
+        }
+        return null;
+    }
+    _watchModelProgress(update, queued = false) {
+        let last = '';
+        let showing = queued;
+        let transcribing = false;
+        let documents = false;
+        const apply = (progress) => {
+            const runStatus = progress
+                ? { state: 'executing', progress }
+                : { state: 'executing' };
+            if (documents)
+                runStatus.reason = 'preparing-documents';
+            const key = JSON.stringify(runStatus);
+            if (key === last)
+                return;
+            last = key;
+            showing = progress !== null || documents;
+            update(runStatus).catch(noop);
+        };
+        const onModel = (state) => {
+            if (state.status === 'loading')
+                apply({ phase: 'loading', model: state.model });
+            else if (state.status === 'downloading') {
+                const percentage = Math.floor((state.percentage ?? 0) / 10) * 10;
+                apply({ phase: 'downloading', model: state.model, percentage });
+            }
+            else
+                apply(transcribing ? { phase: 'transcribing' } : null);
+        };
+        if (this._harness.on && this._harness.off)
+            this._harness.on('model', onModel);
+        return {
+            documents: (active) => {
+                documents = active;
+                apply(null);
+            },
+            transcribe: (active) => {
+                transcribing = active;
+                apply(active ? { phase: 'transcribing' } : null);
+            },
+            image: (progress) => {
+                if (!progress)
+                    return apply(null);
+                apply({ phase: 'generating', percentage: Math.floor(progress.percentage / 10) * 10 });
+            },
+            stop: () => this._harness.off?.('model', onModel),
+            clear: () => {
+                if (!showing)
+                    return;
+                showing = false;
+                last = JSON.stringify({ state: 'executing' });
+                update({ state: 'executing' }).catch(noop);
+            }
+        };
+    }
+}
+function noop() { }
+function runMetricsSummary(metrics) {
+    const { timeToFirstToken, promptTokens, promptTokensPerSecond, cacheTokens, tokensPerSecond, totalTokens, durationMs } = metrics;
+    return {
+        timeToFirstToken,
+        promptTokens,
+        promptTokensPerSecond,
+        cacheTokens,
+        tokensPerSecond,
+        totalTokens,
+        durationMs
+    };
+}
+function isStreamDestroyed(err) {
+    return typeof err === 'object' && err !== null && 'code' in err && err.code === 'STREAM_DESTROYED';
+}
+function harnessDeathReason(status) {
+    const HARNESS_DIED = RUN_FAILURE_REASONS.harnessDied;
+    if (typeof status !== 'object' || status === null)
+        return HARNESS_DIED;
+    const record = status;
+    const detail = typeof record.error === 'string' && record.error ? record.error : null;
+    const code = typeof record.code === 'string' && record.code ? record.code : null;
+    if (!detail)
+        return code ? `${HARNESS_DIED} (${code})` : HARNESS_DIED;
+    return code ? `${HARNESS_DIED}: ${detail} (${code})` : `${HARNESS_DIED}: ${detail}`;
+}
+function harnessDied(status) {
+    if (typeof status !== 'object' || status === null || !('state' in status))
+        return false;
+    return status.state === 'died';
+}
+function modelCatalogChanged(state) {
+    return (typeof state === 'object' &&
+        state !== null &&
+        'catalogChanged' in state &&
+        state.catalogChanged === true);
+}
+function imageDownloadProgress(state) {
+    if (typeof state !== 'object' ||
+        state === null ||
+        !('status' in state) ||
+        (state.status !== 'downloading' && state.status !== 'downloaded') ||
+        !('model' in state) ||
+        typeof state.model !== 'string' ||
+        !('percentage' in state) ||
+        typeof state.percentage !== 'number' ||
+        !Number.isFinite(state.percentage) ||
+        !('downloaded' in state) ||
+        typeof state.downloaded !== 'number' ||
+        !Number.isFinite(state.downloaded) ||
+        !('total' in state) ||
+        typeof state.total !== 'number' ||
+        !Number.isFinite(state.total)) {
+        return null;
+    }
+    const model = diffusionDownloadName(state.model);
+    if (!model)
+        return null;
+    return {
+        model,
+        phase: state.status === 'downloading' ? 'downloading' : 'complete',
+        percentage: state.percentage,
+        downloaded: state.downloaded,
+        total: state.total
+    };
+}