@qvac/harness 0.8.5 → 0.8.6

package/dist-lib/lib/audio-transcode-bare.d.ts

@@ -1,2 +1,2 @@
+export declare function decodeToPcm16kMono(input: Uint8Array): AsyncGenerator<Uint8Array>;
 export declare function transcodeToWav16kMono(input: Uint8Array): Promise<Uint8Array | null>;
-export declare function transcodeToPcm16kMono(input: Uint8Array): Promise<Uint8Array | null>;

package/dist-lib/lib/audio-transcode-bare.js

@@ -92,13 +92,12 @@ const YIELD_EVERY_PACKETS = 32;
 function yieldToLoop() {
     return new Promise((resolve) => setTimeout(resolve, 0));
 }
-async function decodeToPcmChunks(inputFormat, { stream, decoder, rate }) {
-    const chunks = [];
+async function* decodeToPcmChunks(inputFormat, { stream, decoder, rate }) {
     const packet = new ffmpeg.Packet();
     const flush = new ffmpeg.Packet();
     const frame = new ffmpeg.Frame();
     const samples = new ffmpeg.Samples();
-    const target = { frame, samples, chunks, rate };
+    const target = { frame, samples, chunks: [], rate };
     let resampler = null;
     let packets = 0;
     try {
@@ -107,13 +106,15 @@ async function decodeToPcmChunks(inputFormat, { stream, decoder, rate }) {
                 resampler = drainDecodedFrames(decoder, resampler, target);
             }
             packet.unref();
+            yield* target.chunks.splice(0);
             if (++packets % YIELD_EVERY_PACKETS === 0) {
                 await yieldToLoop();
             }
         }
         decoder.sendPacket(flush);
         resampler = drainDecodedFrames(decoder, resampler, target);
-        chunks.push(...flushResampler(resampler, samples, rate));
+        yield* target.chunks.splice(0);
+        yield* flushResampler(resampler, samples, rate);
     }
     finally {
         resampler?.destroy();
@@ -121,35 +122,31 @@ async function decodeToPcmChunks(inputFormat, { stream, decoder, rate }) {
         flush.destroy();
         packet.destroy();
     }
-    return chunks;
 }
-async function decodeInputToPcm(input, rate) {
-    let inputFormat = null;
+export async function* decodeToPcm16kMono(input) {
+    const inputFormat = new ffmpeg.InputFormatContext(bufferReadIO(input));
     let decoder = null;
     try {
-        const format = new ffmpeg.InputFormatContext(bufferReadIO(input));
-        inputFormat = format;
-        const stream = format.getBestStream(ffmpeg.constants.mediaTypes.AUDIO);
+        const stream = inputFormat.getBestStream(ffmpeg.constants.mediaTypes.AUDIO);
         decoder = stream.decoder();
         decoder.open();
-        const chunks = await decodeToPcmChunks(format, { stream, decoder, rate });
-        return chunks.length === 0 ? null : b4a.concat(chunks);
-    }
-    catch (e) {
-        hlog('audio decode/resample failed', { error: errorMessage(e) });
-        return null;
+        yield* decodeToPcmChunks(inputFormat, { stream, decoder, rate: TARGET_SAMPLE_RATE });
     }
     finally {
-        if (decoder) {
-            decoder.destroy();
-        }
-        inputFormat?.destroy();
+        decoder?.destroy();
+        inputFormat.destroy();
     }
 }
 export async function transcodeToWav16kMono(input) {
-    const pcm = await decodeInputToPcm(input, TARGET_SAMPLE_RATE);
-    return pcm ? buildWavBuffer(pcm) : null;
-}
-export async function transcodeToPcm16kMono(input) {
-    return decodeInputToPcm(input, TARGET_SAMPLE_RATE);
+    const chunks = [];
+    try {
+        for await (const chunk of decodeToPcm16kMono(input)) {
+            chunks.push(chunk);
+        }
+    }
+    catch (e) {
+        hlog('audio decode/resample failed', { error: errorMessage(e) });
+        return null;
+    }
+    return chunks.length === 0 ? null : buildWavBuffer(b4a.concat(chunks));
 }

package/dist-lib/lib/audio-transcode-node.d.ts

@@ -1,2 +1,2 @@
 export declare function transcodeToWav16kMono(_input: Uint8Array): Promise<Uint8Array | null>;
-export declare function transcodeToPcm16kMono(_input: Uint8Array): Promise<Uint8Array | null>;
+export declare function decodeToPcm16kMono(_input: Uint8Array): AsyncGenerator<Uint8Array>;

package/dist-lib/lib/audio-transcode-node.js

@@ -1,6 +1,4 @@
 export async function transcodeToWav16kMono(_input) {
     return null;
 }
-export async function transcodeToPcm16kMono(_input) {
-    return null;
-}
+export async function* decodeToPcm16kMono(_input) { }

package/dist-lib/lib/capabilities/audio-resample.d.ts

@@ -11,5 +11,5 @@ export interface ResampledAudio {
     readonly transcoded: boolean;
 }
 export declare function resampleForTranscription(bytes: Uint8Array): Promise<ResampledAudio>;
-export declare function pcmForTranscription(bytes: Uint8Array): Promise<Uint8Array | null>;
+export declare function pcmForTranscription(bytes: Uint8Array): AsyncGenerator<Uint8Array>;
 export {};

package/dist-lib/lib/capabilities/audio-resample.js

@@ -1,5 +1,5 @@
 import b4a from 'b4a';
-import { transcodeToPcm16kMono, transcodeToWav16kMono } from '#audio-transcode';
+import { decodeToPcm16kMono, transcodeToWav16kMono } from '#audio-transcode';
 const TARGET_SAMPLE_RATE = 16000;
 const TARGET_CHANNELS = 1;
 const TARGET_BITS_PER_SAMPLE = 16;
@@ -73,12 +73,11 @@ function wavPcmData(bytes) {
     }
     return null;
 }
-export async function pcmForTranscription(bytes) {
-    if (wavFormat(bytes) && !needsResample(bytes)) {
-        const pcm = wavPcmData(bytes);
-        if (pcm) {
-            return pcm;
-        }
+export async function* pcmForTranscription(bytes) {
+    const pcm = wavFormat(bytes) && !needsResample(bytes) ? wavPcmData(bytes) : null;
+    if (pcm) {
+        yield pcm;
+        return;
     }
-    return transcodeToPcm16kMono(bytes);
+    yield* decodeToPcm16kMono(bytes);
 }

package/dist-lib/lib/capabilities/completion.d.ts

@@ -1,4 +1,4 @@
-import type { CompletionFinal, Tool as SdkTool, ToolDialect } from '@qvac/sdk';
+import type { CompletionEvent as SdkCompletionEvent, CompletionFinal, Tool as SdkTool, ToolDialect } from '@qvac/sdk';
 import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
 import { type TextEvent } from '../helpers/thinking.ts';
 import type { ToolCallDisplay } from '../tool-call-display.ts';
@@ -266,7 +266,7 @@ export interface InferenceTokens {
 export type CompletionEvent = TextEvent | ToolCallEvent | ToolResultEvent | ToolActivityEvent | ErrorEvent | AbortedEvent | MetricsEvent | InferenceCallEvent | InferenceSentEvent;
 export interface CompletionSdkResult {
     requestId?: string;
-    tokenStream: AsyncIterable<string>;
+    events: AsyncIterable<SdkCompletionEvent>;
     final: Promise<CompletionFinal>;
 }
 export type ResponseFormat = {
@@ -296,6 +296,9 @@ export interface CompletionSdk {
     cancel?(params: {
         requestId: string;
     }): Promise<void>;
+    deleteCache?(params: {
+        kvCacheKey: string;
+    }): Promise<unknown>;
 }
 export interface RoundModelLease {
     modelId: string;

package/dist-lib/lib/capabilities/completion.js

@@ -14,7 +14,7 @@ import { HookPipeline } from '../hooks/pipeline.js';
 import { fallbackToolLabel } from '../helpers/tool-label.js';
 import { hlog } from '../log.js';
 import { resolveLlmGenerationParams } from '../models/llm-presets.js';
-import { customToolDialect } from '../models/model-catalog.js';
+import { toolDialectFor } from '../models/model-catalog.js';
 import { isContextOverflowError, isSdkModelWedgedError } from '../models/sdk-faults.js';
 import { annotateLastUserTime, skillsPromptSection, systemPromptParts } from '../prompt.js';
 import { isMetadataMethod } from '../tools/mcp/protocol.js';
@@ -459,6 +459,13 @@ function unprovenReplay(state, final) {
     }
     return state.unproven;
 }
+async function* contentDeltas(events) {
+    for await (const event of events) {
+        if (event.type === 'contentDelta') {
+            yield event.text;
+        }
+    }
+}
 async function* runRoundTokens(result, state, { sdk, signal, startInThink = false }) {
     const cancelThisRound = () => {
         if (result.requestId) {
@@ -466,7 +473,7 @@ async function* runRoundTokens(result, state, { sdk, signal, startInThink = fals
         }
     };
     signal?.addEventListener('abort', cancelThisRound, { once: true });
-    const tokens = stopAtControlToken(result.tokenStream, (token) => {
+    const tokens = stopAtControlToken(contentDeltas(result.events), (token) => {
         state.stopToken = token;
     });
     let tokenEvents = 0;
@@ -674,6 +681,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
     let runError;
     const runOutcomes = createRunOutcomeTracker();
     const landed = runOutcomes.confirmedWrites;
+    let preloadCacheKey;
     async function* runTurn() {
         if (signal?.aborted)
             throw new AbortedError();
@@ -753,7 +761,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
             }
             skillIcon = skillEmoji(skillName) ?? skillIcon;
         }
-        const toolDialect = model ? customToolDialect(model) : undefined;
+        const toolDialect = model ? toolDialectFor(model) : undefined;
         let turns = messages;
         let preloadedSkill = null;
         const preload = mention ?? resolveImplicitSkill(lastUserContent(messages), activeSkills);
@@ -834,7 +842,8 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
         }
         logSelection();
         let history = annotateLastUserTime(systemContent ? [{ role: 'system', content: systemContent }, ...turns] : turns);
-        let roundCacheKey = preloadedSkill === null ? cacheKey : undefined;
+        preloadCacheKey = childCacheKey(cacheKey, preloadedSkill, messages.length);
+        let roundCacheKey = preloadedSkill === null ? cacheKey : preloadCacheKey;
         const runUsage = () => usageBreakdown(promptParts, stats.cacheTokens, model);
         const denied = new Set();
         const failed = new Map();
@@ -1323,7 +1332,16 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
             outcome: runOutcome,
             error: runError
         });
+        if (preloadCacheKey) {
+            await sdk.deleteCache?.({ kvCacheKey: preloadCacheKey }).catch(noop);
+        }
+    }
+}
+function childCacheKey(cacheKey, preloadedSkill, turnCount) {
+    if (preloadedSkill === null || cacheKey === undefined) {
+        return undefined;
     }
+    return `${cacheKey}/p${turnCount}`;
 }
 function toolDecision({ auto, skipAll, approved }) {
     if (auto)

package/dist-lib/lib/capabilities/download.d.ts

@@ -45,4 +45,6 @@ export type SdkOrLoader = DownloadSdk | (() => Promise<DownloadSdk>);
 export interface DownloadEventStream extends Readable {
     [Symbol.asyncIterator](): AsyncIterableIterator<DownloadEvent>;
 }
-export declare function download(sdkOrLoader: SdkOrLoader, args: DownloadArgs, onSettled?: () => void): DownloadEventStream;
+type TerminalEvent = Exclude<DownloadEvent, DownloadProgressEvent>;
+export declare function download(sdkOrLoader: SdkOrLoader, args: DownloadArgs, onSettled?: (event: TerminalEvent) => void): DownloadEventStream;
+export {};

package/dist-lib/lib/capabilities/download.js

@@ -17,7 +17,7 @@ export function download(sdkOrLoader, args, onSettled) {
         settled = true;
         stream.push(event);
         stream.push(null);
-        onSettled?.();
+        onSettled?.(event);
     };
     const cancelOp = () => {
         if (cancelSent || opDone || !requestId || !sdkRef?.cancel)

package/dist-lib/lib/capabilities/preview-model-source.d.ts

@@ -41,6 +41,7 @@ export type PreviewFetch = (url: string, init?: {
     redirect?: 'follow';
 }) => Promise<PreviewResponse>;
 export interface FitQuery {
+    src: string;
     sha256Checksum: string;
     name: string;
     contextTokens: number;

package/dist-lib/lib/capabilities/preview-model-source.js

@@ -365,6 +365,7 @@ async function assess({ file, header }, taskType, deps) {
     }
     try {
         return await deps.assessFit({
+            src: file.src,
             sha256Checksum: file.sha256,
             name: header.name ?? file.label,
             contextTokens: defaultContextSize(file.src, header.contextLength)

package/dist-lib/lib/capabilities/usage-breakdown.js

@@ -1,8 +1,11 @@
+import { toolDialectFor } from '../models/model-catalog.js';
 import { detectToolDialect } from '../models/tool-dialect.js';
 const QWEN35 = { prose: 4.38, schema: 4.08, toolBlockTokens: 189 };
 const DENSITY_BY_DIALECT = new Map([['qwen35', QWEN35]]);
 export function densityFor(modelName) {
-    const dialect = modelName ? detectToolDialect(modelName, modelName) : undefined;
+    const dialect = modelName
+        ? (toolDialectFor(modelName) ?? detectToolDialect(modelName, modelName))
+        : undefined;
     return (dialect && DENSITY_BY_DIALECT.get(dialect)) ?? QWEN35;
 }
 export function promptUsageParts({ system, toolSchemas }) {

package/dist-lib/lib/capabilities/voice.d.ts

@@ -75,7 +75,11 @@ export interface TranscribeStreamingOptions {
     modelId: string;
     signal?: BareAbortSignal | undefined;
 }
-export declare function transcribeStreaming(sdk: VoiceSdk, pcm: Uint8Array, { modelId, signal }: TranscribeStreamingOptions): Promise<string>;
+export interface TranscribeAudioOptions extends TranscribeStreamingOptions {
+    audio: Buffer;
+}
+export declare function transcribeAudio(sdk: VoiceSdk, pcm: AsyncIterable<Uint8Array>, { modelId, signal, audio }: TranscribeAudioOptions): Promise<string>;
+export declare function transcribeStreaming(sdk: VoiceSdk, pcm: AsyncIterable<Uint8Array>, opts: TranscribeStreamingOptions): Promise<string>;
 export declare function speakStreamOnce(sdk: VoiceSdk, modelId: string, text: AsyncIterable<string>): AsyncGenerator<SpeakResult>;
 export declare function speakable(text: string): string;
 export declare function speakOnce(sdk: VoiceSdk, modelId: string, text: string): Promise<number[]>;

package/dist-lib/lib/capabilities/voice.js

@@ -2,6 +2,7 @@ import b4a from 'b4a';
 import { errorMessage } from '../guards.js';
 import { AbortedError } from '../helpers/race-abort.js';
 import { hlog } from '../log.js';
+import { buildWavBuffer } from '../wav-encode.js';
 import { normalizeForSpeech } from './speech-text.js';
 export const SUPERTONIC_SAMPLE_RATE = 44100;
 export function createVoiceLane() {
@@ -14,31 +15,19 @@ export function createVoiceLane() {
 }
 const TRANSCRIBE_SAMPLE_RATE = 16000;
 const TRANSCRIBE_CHUNK_BYTES = TRANSCRIBE_SAMPLE_RATE * 2;
+const TRANSCRIBE_STREAM_MIN_BYTES = TRANSCRIBE_CHUNK_BYTES * 60;
+const TRANSCRIBE_SEGMENT_SECONDS = 300;
 const PARAKEET_STREAMING = { emitPartials: false, chunkMs: 5000 };
 const TRANSCRIBE_WITH_METADATA = false;
 const TRANSCRIBE_PACE_MS = 40;
 function pace(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-const TRANSCRIBE_DRAIN_IDLE_MS = 3000;
-const TRANSCRIBE_DRAIN_MAX_MS = 60_000;
-async function writePaced(session, data, signal) {
-    for (let offset = 0; offset < data.length; offset += TRANSCRIBE_CHUNK_BYTES) {
+async function writePaced(session, pcm, signal) {
+    for await (const second of pcm) {
         if (signal?.aborted)
             return;
-        session.write(data.subarray(offset, offset + TRANSCRIBE_CHUNK_BYTES));
-        await pace(TRANSCRIBE_PACE_MS);
-    }
-}
-async function drainUntilIdle(lastPieceAt, streamClosed, signal) {
-    const deadline = Date.now() + TRANSCRIBE_DRAIN_MAX_MS;
-    for (;;) {
-        if (signal?.aborted || streamClosed() || Date.now() >= deadline)
-            return;
-        const last = lastPieceAt();
-        if (last > 0 && Date.now() - last >= TRANSCRIBE_DRAIN_IDLE_MS) {
-            return;
-        }
+        session.write(second);
         await pace(TRANSCRIBE_PACE_MS);
     }
 }
@@ -59,7 +48,93 @@ function transcribePiece(piece) {
     }
     return null;
 }
-export async function transcribeStreaming(sdk, pcm, { modelId, signal }) {
+async function* inSeconds(pcm) {
+    let pending = [];
+    let size = 0;
+    for await (const chunk of pcm) {
+        pending.push(chunk);
+        size += chunk.length;
+        if (size < TRANSCRIBE_CHUNK_BYTES) {
+            continue;
+        }
+        const joined = pending.length === 1 ? chunk : b4a.concat(pending);
+        let offset = 0;
+        for (; joined.length - offset >= TRANSCRIBE_CHUNK_BYTES; offset += TRANSCRIBE_CHUNK_BYTES) {
+            yield joined.subarray(offset, offset + TRANSCRIBE_CHUNK_BYTES);
+        }
+        size = joined.length - offset;
+        pending = size > 0 ? [joined.subarray(offset)] : [];
+    }
+    if (size > 0) {
+        yield b4a.concat(pending);
+    }
+}
+async function readHead(seconds, signal) {
+    const head = { seconds: [], bytes: 0 };
+    try {
+        while (head.bytes < TRANSCRIBE_STREAM_MIN_BYTES && !signal?.aborted) {
+            const next = await seconds.next();
+            if (next.done) {
+                break;
+            }
+            head.seconds.push(next.value);
+            head.bytes += next.value.length;
+        }
+    }
+    catch (err) {
+        hlog('audio decode/resample failed', { error: errorMessage(err) });
+        return null;
+    }
+    return head;
+}
+async function* resume(head, rest) {
+    yield* head.seconds;
+    yield* { [Symbol.asyncIterator]: () => rest };
+}
+export async function transcribeAudio(sdk, pcm, { modelId, signal, audio }) {
+    const seconds = inSeconds(pcm);
+    const head = await readHead(seconds, signal);
+    if (signal?.aborted) {
+        await seconds.return(undefined);
+        throw new AbortedError();
+    }
+    if (!head || head.bytes === 0) {
+        return transcribeOnce(sdk, modelId, audio);
+    }
+    if (head.bytes < TRANSCRIBE_STREAM_MIN_BYTES) {
+        return transcribeOnce(sdk, modelId, buildWavBuffer(b4a.concat(head.seconds)));
+    }
+    try {
+        return await transcribeStreaming(sdk, resume(head, seconds), { modelId, signal });
+    }
+    finally {
+        await seconds.return(undefined);
+    }
+}
+async function* segment(first, rest) {
+    yield first;
+    for (let n = 1; n < TRANSCRIBE_SEGMENT_SECONDS; n++) {
+        const next = await rest.next();
+        if (next.done) {
+            return;
+        }
+        yield next.value;
+    }
+}
+export async function transcribeStreaming(sdk, pcm, opts) {
+    const seconds = pcm[Symbol.asyncIterator]();
+    const parts = [];
+    try {
+        for (let first = await seconds.next(); !first.done; first = await seconds.next()) {
+            parts.push(await transcribeSession(sdk, segment(first.value, seconds), opts));
+        }
+    }
+    finally {
+        await seconds.return?.();
+    }
+    return parts.filter(Boolean).join(' ');
+}
+async function transcribeSession(sdk, pcm, { modelId, signal }) {
     const session = await sdk.transcribeStream({
         modelId,
         metadata: TRANSCRIBE_WITH_METADATA,
@@ -67,27 +142,20 @@ export async function transcribeStreaming(sdk, pcm, { modelId, signal }) {
     });
     const onAbort = () => session.destroy();
     signal?.addEventListener('abort', onAbort, { once: true });
-    let lastPieceAt = 0;
-    let streamClosed = false;
     const collect = (async () => {
         let out = '';
         for await (const piece of session) {
-            lastPieceAt = Date.now();
             const seg = transcribePiece(piece);
             if (!seg) {
                 continue;
             }
             out += !out || seg.append ? seg.text : ` ${seg.text}`;
         }
-        streamClosed = true;
         return out.replace(/\s+/g, ' ').trim();
     })();
-    collect.catch(() => {
-        streamClosed = true;
-    });
+    collect.catch(noop);
     try {
         await writePaced(session, pcm, signal);
-        await drainUntilIdle(() => lastPieceAt, () => streamClosed, signal);
         if (!signal?.aborted) {
             session.end();
         }

package/dist-lib/lib/connect.d.ts

@@ -3,7 +3,7 @@ import { type Transport } from './rpc-session.ts';
 import { type KvCacheDeletionResult } from './capabilities/kv-cache.ts';
 import type { CustomModelEntry } from './models/model-catalog.ts';
 import { type ModelSourcePreview, type PreviewModelSourceContext } from './capabilities/preview-model-source.ts';
-import type { CapabilityInfo, CompletionContext, CredentialEntry, DetectedLanguage, DetectLanguageContext, DownloadContext, EmbedContext, HarnessContract, HarnessDiagnostics, HarnessEvent, HarnessInfo, InfraModel, InvokeContext, ListModelsOptions, ModelInfo, ResolvedSkillCatalogEntry, SkillsOptions, SkillWriteResult, SpeakContext, SpeakResult, SpeakStreamContext, ToolCatalogEntry, TranscribeContext, LoadModelContext, LoadModelResult, UnloadModelContext, UnloadModelResult, WarmModelContext } from './contract-types.ts';
+import type { CapabilityInfo, CompletionContext, CredentialEntry, DetectedLanguage, DetectLanguageContext, DownloadContext, EmbedContext, HarnessContract, HarnessDiagnostics, HarnessEvent, HarnessInfo, InfraModel, InvokeContext, ListModelsOptions, ModelInfo, ResolvedSkillCatalogEntry, SkillsOptions, SkillWriteResult, SpeakContext, SpeakResult, SpeakStreamContext, ToolCatalogEntry, TranscribeContext, LoadModelContext, LoadModelResult, MemoryUsage, UnloadModelContext, UnloadModelResult, WarmModelContext, DownloadsAllowedOptions } from './contract-types.ts';
 import { type EmbedDevice } from './models/embed-config.ts';
 import type { DeleteModelSummary } from './models/model-delete.ts';
 import type { CopyBaseResult, DeleteOverlayResult, ManagedSkill, SkillFileContent } from './tools/skills/overlay-crud.ts';
@@ -36,6 +36,9 @@ export declare class RemoteHarness extends EventEmitter implements HarnessContra
     setCredentials(entries: ReadonlyArray<CredentialEntry>): Promise<void>;
     setSkillSettings(entries: ReadonlyArray<SkillSettingEntry>): Promise<void>;
     setModelIdleTimeout(ms: number): Promise<void>;
+    setModelMemoryCap(percent: number): Promise<void>;
+    memoryUsage(): Promise<MemoryUsage>;
+    setDownloadsAllowed({ allowed }: DownloadsAllowedOptions): Promise<void>;
     listManagedSkills(): Promise<ManagedSkill[]>;
     readSkillFile(name: string): Promise<SkillFileContent | null>;
     writeSkillFile(name: string, content: string): Promise<SkillWriteResult>;

package/dist-lib/lib/connect.js

@@ -422,6 +422,18 @@ export class RemoteHarness extends EventEmitter {
         const { client } = await this._ensure();
         await client.setModelIdleTimeout({ ms });
     }
+    async setModelMemoryCap(percent) {
+        const { client } = await this._ensure();
+        await client.setModelMemoryCap({ percent });
+    }
+    async memoryUsage() {
+        const { client } = await this._ensure();
+        return await client.memoryUsage({});
+    }
+    async setDownloadsAllowed({ allowed }) {
+        const { client } = await this._ensure();
+        await client.setDownloadsAllowed({ allowed });
+    }
     async listManagedSkills() {
         const { client } = await this._ensure();
         const response = await client.listManagedSkills({});
@@ -566,10 +578,11 @@ export class RemoteHarness extends EventEmitter {
             cachedOnly: options.cachedOnly,
             fullRegistry: options.fullRegistry
         });
-        return (response.models ?? []).map(({ actualSize, label, ...row }) => ({
+        return (response.models ?? []).map(({ actualSize, label, memoryBytes, ...row }) => ({
             ...row,
             actualSize: actualSize || undefined,
             label: label || undefined,
+            memoryBytes: memoryBytes || undefined,
             taskType: addonTaskType(row.type)
         }));
     }

package/dist-lib/lib/contract-types.d.ts

@@ -95,6 +95,9 @@ export interface HarnessEvent {
     message?: string;
     [key: string]: unknown;
 }
+export interface DownloadsAllowedOptions {
+    allowed: boolean;
+}
 export interface ModelState {
     status: string;
     model?: string;
@@ -107,6 +110,7 @@ export interface ModelState {
         model: string;
         refs: number;
     }>;
+    addon?: string | null;
 }
 export interface WarmModelContext {
     model: string;
@@ -118,6 +122,9 @@ export interface LoadModelResult {
     loaded: boolean;
     reason?: 'memory';
 }
+export interface MemoryUsage {
+    readonly usedBytes: number;
+}
 export interface UnloadModelContext {
     model: string;
 }
@@ -223,6 +230,9 @@ export interface HarnessContract {
         agentId?: string | null;
     }>): void | Promise<void>;
     setModelIdleTimeout?(ms: number): void | Promise<void>;
+    setModelMemoryCap?(percent: number): void | Promise<void>;
+    memoryUsage?(): Promise<MemoryUsage>;
+    setDownloadsAllowed?(options: DownloadsAllowedOptions): void | Promise<void>;
     listManagedSkills?(): Promise<ManagedSkill[]>;
     readSkillFile?(name: string): Promise<SkillFileContent | null>;
     writeSkillFile?(name: string, content: string): Promise<{

package/dist-lib/lib/models/download-gate.d.ts

@@ -0,0 +1,20 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { ModelAddon } from './model-source.ts';
+export interface HeldModel {
+    readonly model: string;
+    readonly addon: ModelAddon;
+}
+export interface DownloadGateOptions {
+    isCached(model: string, addon: ModelAddon): Promise<boolean>;
+    onHeld(held: HeldModel): void;
+    onDropped(held: HeldModel): void;
+}
+export type HoldFn = (model: string, addon: ModelAddon, signal?: BareAbortSignal) => Promise<void>;
+export interface DownloadGate {
+    readonly allowed: boolean;
+    setAllowed(allowed: boolean): void;
+    downloaded(): void;
+    hold: HoldFn;
+    abandon(): void;
+}
+export declare function createDownloadGate({ isCached, onHeld, onDropped }: DownloadGateOptions): DownloadGate;

package/dist-lib/lib/models/download-gate.js

@@ -0,0 +1,73 @@
+import { AbortedError, raceAbort } from '../helpers/race-abort.js';
+function deferred() {
+    const next = Promise.withResolvers();
+    next.promise.catch(noop);
+    return next;
+}
+export function createDownloadGate({ isCached, onHeld, onDropped }) {
+    let allowed = true;
+    let woke = deferred();
+    let dropped = deferred();
+    const wake = () => {
+        const woken = woke;
+        woke = deferred();
+        woken.resolve();
+    };
+    const wait = async (held, signal, onWait) => {
+        const drop = dropped;
+        const cancelled = () => signal?.aborted === true || drop !== dropped;
+        for (;;) {
+            const change = Promise.race([raceAbort(woke.promise, signal), drop.promise]);
+            change.catch(noop);
+            const ready = allowed || (await isCached(held.model, held.addon).catch(() => false));
+            if (cancelled()) {
+                throw new AbortedError();
+            }
+            if (ready) {
+                return;
+            }
+            onWait();
+            await change;
+        }
+    };
+    return {
+        get allowed() {
+            return allowed;
+        },
+        setAllowed(next) {
+            allowed = next;
+            if (allowed) {
+                wake();
+            }
+        },
+        downloaded: wake,
+        async hold(model, addon, signal) {
+            if (allowed)
+                return;
+            if (signal?.aborted)
+                throw new AbortedError();
+            const held = { model, addon };
+            let shown = false;
+            try {
+                await wait(held, signal, () => {
+                    if (!shown) {
+                        shown = true;
+                        onHeld(held);
+                    }
+                });
+            }
+            catch (err) {
+                if (shown) {
+                    onDropped(held);
+                }
+                throw err;
+            }
+        },
+        abandon() {
+            const abandoned = dropped;
+            dropped = deferred();
+            abandoned.reject(new AbortedError());
+        }
+    };
+}
+function noop() { }