@qvac/harness 0.0.0 → 0.1.1

package/dist-lib/lib/models/model-source.js

@@ -0,0 +1,21 @@
+import { audioGenModelByName, curatedModelAsset, customModelSrc } from "./model-catalog.js";
+export async function resolveModelSrc(sdk, model, addon = 'llm') {
+    if (/^(\/|~|\.|file:|https?:|registry:|pear:|hyper:)/.test(model))
+        return model;
+    const custom = customModelSrc(model);
+    if (custom)
+        return custom;
+    if (addon === 'audiogen') {
+        const audio = audioGenModelByName(model);
+        if (!audio)
+            throw new Error(`audiogen model not found: ${model}`);
+        return audio.src;
+    }
+    const asset = curatedModelAsset(model, addon);
+    if (asset)
+        return asset;
+    const [entry] = await sdk.modelRegistrySearch({ filter: model, addon });
+    if (!entry)
+        throw new Error(`model not found in registry: ${model} (addon=${addon})`);
+    return { ...entry, src: `registry://${entry.registrySource}/${entry.registryPath}` };
+}

package/dist-lib/lib/models/music-catalog.d.ts

@@ -0,0 +1,12 @@
+export declare const MUSIC_MODEL_CHOICES: readonly ["turbo", "turbo-hq", "sft"];
+export type MusicModelChoice = (typeof MUSIC_MODEL_CHOICES)[number];
+export declare const GENERATE_MUSIC_TOOL = "generate_music";
+export declare const DEFAULT_MUSIC_MODEL_CHOICE: MusicModelChoice;
+export type MusicChoiceEntry = {
+    readonly choice: MusicModelChoice;
+    readonly label: string;
+    readonly sizeBytesApprox: number;
+    readonly requiresGpu: boolean;
+    readonly notes: string;
+};
+export declare const MUSIC_CHOICE_CATALOG: ReadonlyArray<MusicChoiceEntry>;

package/dist-lib/lib/models/music-catalog.js

@@ -0,0 +1,26 @@
+export const MUSIC_MODEL_CHOICES = ['turbo', 'turbo-hq', 'sft'];
+export const GENERATE_MUSIC_TOOL = 'generate_music';
+export const DEFAULT_MUSIC_MODEL_CHOICE = 'turbo';
+export const MUSIC_CHOICE_CATALOG = [
+    {
+        choice: 'turbo',
+        label: 'ACE-Step 1.5 Turbo (Q4)',
+        sizeBytesApprox: 3_300_000_000,
+        requiresGpu: false,
+        notes: 'Fastest, fits phone memory. Good default.'
+    },
+    {
+        choice: 'turbo-hq',
+        label: 'ACE-Step 1.5 Turbo (Q8)',
+        sizeBytesApprox: 4_400_000_000,
+        requiresGpu: true,
+        notes: 'Higher-precision Turbo. Wants a desktop GPU.'
+    },
+    {
+        choice: 'sft',
+        label: 'ACE-Step 1.5 SFT (Q8)',
+        sizeBytesApprox: 4_400_000_000,
+        requiresGpu: true,
+        notes: 'Fine-tuned quality. Wants a desktop GPU.'
+    }
+];

package/dist-lib/lib/models/opencl-cache.d.ts

@@ -0,0 +1,5 @@
+export declare const OPENCL_CACHE_MAX_AGE_MS: number;
+export declare function openclEngineKey(sdkVersion?: string): string;
+export declare function openclCacheRoot(env?: Record<string, string | undefined>, hostPlatform?: string): string | undefined;
+export declare function openclCacheDir(env?: Record<string, string | undefined>, hostPlatform?: string, sdkVersion?: string): string | undefined;
+export declare function prepareOpenclCache(env?: Record<string, string | undefined>, hostPlatform?: string, sdkVersion?: string, now?: number): void;

package/dist-lib/lib/models/opencl-cache.js

@@ -0,0 +1,50 @@
+import fs from 'fs';
+import { platform } from 'os';
+import path from 'path';
+import process from 'process';
+import sdkPkg from '@qvac/sdk/package' with { type: 'json' };
+const OPENCL_CACHE_DIR_ENV = 'QVAC_OPENCL_CACHE_DIR';
+export const OPENCL_CACHE_MAX_AGE_MS = 60 * 60 * 1000;
+const noop = () => { };
+export function openclEngineKey(sdkVersion = sdkPkg.version) {
+    return `sdk-${sdkVersion}`.replace(/[^A-Za-z0-9._-]/g, '_');
+}
+export function openclCacheRoot(env = process.env, hostPlatform = platform()) {
+    if (hostPlatform !== 'android')
+        return undefined;
+    const dir = env[OPENCL_CACHE_DIR_ENV];
+    if (!dir?.startsWith('/'))
+        return undefined;
+    return dir.split('/').includes('..') ? undefined : dir;
+}
+export function openclCacheDir(env = process.env, hostPlatform = platform(), sdkVersion) {
+    const root = openclCacheRoot(env, hostPlatform);
+    return root === undefined ? undefined : path.join(root, openclEngineKey(sdkVersion));
+}
+export function prepareOpenclCache(env = process.env, hostPlatform = platform(), sdkVersion, now = Date.now()) {
+    const root = openclCacheRoot(env, hostPlatform);
+    if (root === undefined)
+        return;
+    const key = openclEngineKey(sdkVersion);
+    try {
+        fs.mkdirSync(path.join(root, key), { recursive: true });
+    }
+    catch {
+        return;
+    }
+    fs.promises.readdir(root).then((names) => {
+        for (const name of names) {
+            if (name === key)
+                continue;
+            const entry = path.join(root, name);
+            fs.promises
+                .stat(entry)
+                .then((stat) => {
+                if (now - stat.mtimeMs > OPENCL_CACHE_MAX_AGE_MS) {
+                    return fs.promises.rm(entry, { recursive: true, force: true }).catch(noop);
+                }
+            })
+                .catch(noop);
+        }
+    }, noop);
+}

package/dist-lib/lib/models/sdk-faults.d.ts

@@ -0,0 +1,21 @@
+import type { EmbedDevice } from './embed-config.ts';
+export declare function isSdkGpuDeviceLostError(err: unknown): boolean;
+export declare function isSdkModelWedgedError(err: unknown): boolean;
+export declare function isContextOverflowError(err: unknown): boolean;
+export type GpuFaultDecision = 'reload' | 'fallback';
+export declare function createGpuFaultEscalation(): {
+    recordFault(onGpu: boolean): GpuFaultDecision;
+    reset(): void;
+};
+export type GpuFaultState = ReturnType<typeof createGpuFaultState>;
+export declare function createGpuFaultState({ device, gpuLayers }?: {
+    device?: EmbedDevice;
+    gpuLayers?: number;
+}): {
+    readonly device: EmbedDevice;
+    readonly generation: number;
+    gpuLayers(): number;
+    key(model: string): string;
+    recordFault(bornAt: number): void;
+    reset(): void;
+};

package/dist-lib/lib/models/sdk-faults.js

@@ -0,0 +1,66 @@
+export function isSdkGpuDeviceLostError(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const message = err.message;
+    if (typeof message !== 'string')
+        return false;
+    return /ErrorDeviceLost/i.test(message) || /VK_ERROR_DEVICE_LOST/i.test(message);
+}
+export function isSdkModelWedgedError(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const message = err.message;
+    if (typeof message !== 'string')
+        return false;
+    return /failed to (decode next token|eval chunk)/i.test(message);
+}
+export function isContextOverflowError(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    return err.name === 'CONTEXT_OVERFLOW';
+}
+export function createGpuFaultEscalation() {
+    let count = 0;
+    return {
+        recordFault(onGpu) {
+            count += 1;
+            return onGpu && count >= 2 ? 'fallback' : 'reload';
+        },
+        reset() {
+            count = 0;
+        }
+    };
+}
+const GPU_LAYERS_FULL = 99;
+const GPU_LAYERS_NONE = 0;
+export function createGpuFaultState({ device, gpuLayers } = {}) {
+    const escalation = createGpuFaultEscalation();
+    let current = device ?? 'gpu';
+    let generation = 0;
+    let lastFaulted = -1;
+    return {
+        get device() {
+            return current;
+        },
+        get generation() {
+            return generation;
+        },
+        gpuLayers() {
+            return gpuLayers ?? (current === 'gpu' ? GPU_LAYERS_FULL : GPU_LAYERS_NONE);
+        },
+        key(model) {
+            return [model, current, generation].join('\0');
+        },
+        recordFault(bornAt) {
+            if (bornAt <= lastFaulted)
+                return;
+            lastFaulted = bornAt;
+            generation += 1;
+            if (escalation.recordFault(current === 'gpu') === 'fallback')
+                current = 'cpu';
+        },
+        reset() {
+            escalation.reset();
+        }
+    };
+}

package/dist-lib/lib/models/tool-dialect.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDialect } from '@qvac/sdk';
+export declare function detectToolDialect(src: string, name?: string): ToolDialect | undefined;

package/dist-lib/lib/models/tool-dialect.js

@@ -0,0 +1,19 @@
+export function detectToolDialect(src, name) {
+    const basename = src
+        .toLowerCase()
+        .split(/[/\\?#]/)
+        .filter(Boolean)
+        .pop() ?? '';
+    const tag = `${(name ?? '').toLowerCase()}|${basename}`;
+    if (/qwen3[._-]?[56](?![a-z0-9])/.test(tag))
+        return 'qwen35';
+    if (/gemma[-_]?4(?=[^a-z0-9]|$)/.test(tag))
+        return 'gemma4';
+    if (/gpt[_-]?oss/.test(tag))
+        return 'harmony';
+    if (/deepseek[-_. ]?v(?:4|3[._-]?2)(?![0-9])/.test(tag))
+        return 'dsml';
+    if (/lfm[_-]?\d/.test(tag))
+        return 'pythonic';
+    return undefined;
+}

package/dist-lib/lib/models/tts-model-default.d.ts

@@ -0,0 +1,3 @@
+export type TtsCapabilityProfile = 'tiny' | 'low' | 'mid' | 'high' | 'xhigh';
+export declare const TTS_MODEL_NAMES: ReadonlyArray<string>;
+export declare function defaultTtsModelName(profile: TtsCapabilityProfile): string;

package/dist-lib/lib/models/tts-model-default.js

@@ -0,0 +1,13 @@
+const TTS_MODEL_BY_PROFILE = {
+    tiny: 'Supertonic3-Q4_0',
+    low: 'Supertonic3-Q4_0',
+    mid: 'Supertonic3-Q8_0',
+    high: 'Supertonic3-Q8_0',
+    xhigh: 'Supertonic3-Q8_0'
+};
+export const TTS_MODEL_NAMES = [
+    ...new Set(Object.values(TTS_MODEL_BY_PROFILE))
+];
+export function defaultTtsModelName(profile) {
+    return TTS_MODEL_BY_PROFILE[profile];
+}

package/dist-lib/lib/no-redirect-fetch-bare.d.ts

@@ -0,0 +1,15 @@
+import { type BareLookupAll } from './validating-lookup.ts';
+import { type NoRedirectFetchInit, type NoRedirectFetchResponse } from './no-redirect-fetch-impl.ts';
+export type { NoRedirectFetchResponse };
+export type ConnectionAgent = {
+    createConnection(opts: {
+        readonly host?: string;
+    }): unknown;
+};
+export type AgentCtor<A extends ConnectionAgent> = new (opts: object) => A;
+export declare class BlockedHostError extends Error {
+    readonly code = "EBLOCKEDHOST";
+    constructor(host: string);
+}
+export declare function makeValidatingAgent<A extends ConnectionAgent>(Agent: AgentCtor<A>, lookup: BareLookupAll): A;
+export default function noRedirectFetch(url: URL, init?: NoRedirectFetchInit): Promise<NoRedirectFetchResponse>;

package/dist-lib/lib/no-redirect-fetch-bare.js

@@ -0,0 +1,59 @@
+import http, { Agent as HttpAgent } from 'bare-http1';
+import https, { Agent as HttpsAgent } from 'bare-https';
+import * as bareDns from 'bare-dns';
+import { isPrivateOrBlocked } from "./tools/private-ip.js";
+import { makeValidatingLookup } from "./validating-lookup.js";
+import { runNoRedirectFetch } from "./no-redirect-fetch-impl.js";
+export class BlockedHostError extends Error {
+    code = 'EBLOCKEDHOST';
+    constructor(host) {
+        super(`Connection to "${host}" is blocked (private/loopback/metadata).`);
+        this.name = 'BlockedHostError';
+    }
+}
+function isLiteralIp(host) {
+    if (host.includes(':')) {
+        return true;
+    }
+    return /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
+}
+export function makeValidatingAgent(Agent, lookup) {
+    const agent = new Agent({ keepAlive: 1000, timeout: 5000, lookup });
+    const original = agent.createConnection.bind(agent);
+    agent.createConnection = (opts) => {
+        const host = opts.host;
+        if (typeof host === 'string' && isLiteralIp(host) && isPrivateOrBlocked(host)) {
+            throw new BlockedHostError(host);
+        }
+        return original(opts);
+    };
+    return agent;
+}
+const rawAllLookup = (hostname, opts, cb) => {
+    bareDns.lookup(hostname, opts, cb);
+};
+const validatingLookup = makeValidatingLookup(rawAllLookup);
+const httpAgent = makeValidatingAgent(HttpAgent, validatingLookup);
+const httpsAgent = makeValidatingAgent(HttpsAgent, validatingLookup);
+export default function noRedirectFetch(url, init = {}) {
+    const request = (target, opts, onresponse) => {
+        const common = { method: readMethod(opts.method), headers: opts.headers };
+        const forward = (res) => onresponse(res);
+        return target.protocol === 'https:'
+            ? https.request(target.href, { ...common, agent: httpsAgent }, forward)
+            : http.request(target.href, { ...common, agent: httpAgent }, forward);
+    };
+    return runNoRedirectFetch(request, url, init);
+}
+function readMethod(method) {
+    if (method === 'GET' ||
+        method === 'POST' ||
+        method === 'PUT' ||
+        method === 'DELETE' ||
+        method === 'PATCH' ||
+        method === 'HEAD' ||
+        method === 'OPTIONS') {
+        return method;
+    }
+    throw new Error(`unsupported HTTP method: ${method}`);
+}

package/dist-lib/lib/no-redirect-fetch-impl.d.ts

@@ -0,0 +1,39 @@
+export interface FetchRequestLike {
+    on(event: 'error', listener: (err: Error) => void): void;
+    write(chunk: string): void;
+    end(): void;
+    destroy(err?: Error): void;
+}
+export interface FetchResponseLike {
+    statusCode: number;
+    headers: Record<string, string | string[] | number | undefined>;
+    on(event: 'data', listener: (chunk: Uint8Array) => void): void;
+    on(event: 'error', listener: (err: Error) => void): void;
+    on(event: 'end', listener: () => void): void;
+}
+export type BareRequestFn<Response extends FetchResponseLike = FetchResponseLike, Request extends FetchRequestLike = FetchRequestLike> = (url: URL, opts: {
+    method: string;
+    headers: Record<string, string>;
+    validatedAddresses?: readonly string[] | undefined;
+}, onresponse: (res: Response) => void) => Request;
+export interface NoRedirectFetchInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: {
+        readonly aborted: boolean;
+        addEventListener(type: 'abort', listener: () => void): void;
+    };
+    validatedAddresses?: readonly string[] | undefined;
+    maxBytes?: number;
+    truncate?: boolean;
+}
+export interface NoRedirectFetchResponse {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): string;
+    bytes(): Uint8Array;
+}
+export declare function runNoRedirectFetch<Response extends FetchResponseLike, Request extends FetchRequestLike>(request: BareRequestFn<Response, Request>, url: URL, init?: NoRedirectFetchInit): Promise<NoRedirectFetchResponse>;

package/dist-lib/lib/no-redirect-fetch-impl.js

@@ -0,0 +1,80 @@
+import b4a from 'b4a';
+import { DEFAULT_USER_AGENT } from "./user-agent.js";
+const UA_SNIFFING_HOSTS = new Set(['wttr.in']);
+export function runNoRedirectFetch(request, url, init = {}) {
+    return new Promise((resolve, reject) => {
+        const headers = { ...init.headers };
+        if (init.body !== undefined &&
+            !Object.keys(headers).some((h) => h.toLowerCase() === 'content-length')) {
+            headers['content-length'] = String(b4a.byteLength(init.body));
+        }
+        if (!Object.keys(headers).some((h) => h.toLowerCase() === 'user-agent')) {
+            headers['user-agent'] = UA_SNIFFING_HOSTS.has(url.hostname.toLowerCase())
+                ? ''
+                : DEFAULT_USER_AGENT;
+        }
+        const method = init.method ?? 'GET';
+        const req = request(url, { method, headers, validatedAddresses: init.validatedAddresses }, (res) => {
+            const chunks = [];
+            let received = 0;
+            let settled = false;
+            const respond = () => {
+                if (settled)
+                    return;
+                settled = true;
+                const body = b4a.concat(chunks);
+                const responseHeaders = {};
+                for (const [name, value] of Object.entries(res.headers)) {
+                    responseHeaders[name.toLowerCase()] = String(value);
+                }
+                resolve({
+                    status: res.statusCode,
+                    headers: { get: (name) => responseHeaders[name.toLowerCase()] ?? null },
+                    text: () => b4a.toString(body, 'utf8'),
+                    bytes: () => body
+                });
+            };
+            const fail = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(err);
+            };
+            res.on('data', (chunk) => {
+                received += chunk.byteLength;
+                if (init.maxBytes !== undefined && received > init.maxBytes) {
+                    if (init.truncate) {
+                        const allowed = chunk.byteLength - (received - init.maxBytes);
+                        if (allowed > 0)
+                            chunks.push(chunk.subarray(0, allowed));
+                        respond();
+                        req.destroy();
+                        return;
+                    }
+                    const err = new Error(`response exceeded ${init.maxBytes} bytes`);
+                    req.destroy(err);
+                    fail(err);
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            res.on('error', fail);
+            res.on('end', respond);
+        });
+        req.on('error', reject);
+        if (init.signal) {
+            const abort = () => {
+                const err = new Error('This operation was aborted');
+                err.name = 'AbortError';
+                req.destroy(err);
+                reject(err);
+            };
+            if (init.signal.aborted)
+                return abort();
+            init.signal.addEventListener('abort', abort);
+        }
+        if (init.body !== undefined)
+            req.write(init.body);
+        req.end();
+    });
+}

package/dist-lib/lib/no-redirect-fetch-node.d.ts

@@ -0,0 +1,4 @@
+import * as http from 'node:http';
+import { type NoRedirectFetchInit, type NoRedirectFetchResponse } from './no-redirect-fetch-impl.ts';
+export default function noRedirectFetch(url: URL, init?: NoRedirectFetchInit): Promise<NoRedirectFetchResponse>;
+export declare function createLookup(validatedAddresses: readonly string[] | undefined): NonNullable<http.RequestOptions['lookup']>;

package/dist-lib/lib/no-redirect-fetch-node.js

@@ -0,0 +1,52 @@
+import * as dns from 'node:dns';
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { isPrivateOrBlocked } from "./tools/private-ip.js";
+import { runNoRedirectFetch } from "./no-redirect-fetch-impl.js";
+export default function noRedirectFetch(url, init = {}) {
+    const request = (target, options, onresponse) => {
+        const common = {
+            method: options.method,
+            headers: options.headers,
+            lookup: createLookup(options.validatedAddresses)
+        };
+        const forward = (res) => onresponse(res);
+        return (target.protocol === 'https:' ? https : http).request(target.href, common, forward);
+    };
+    return runNoRedirectFetch(request, url, init);
+}
+export function createLookup(validatedAddresses) {
+    return (hostname, options, callback) => {
+        const wantsAll = typeof options === 'object' && options !== null && options.all === true;
+        const cb = callback;
+        const fail = () => {
+            cb(new Error(`Requests to "${hostname}" resolve to a blocked address.`), '', 0);
+        };
+        const respond = (records) => {
+            if (records.length === 0 || records.some((record) => isPrivateOrBlocked(record.address))) {
+                fail();
+                return;
+            }
+            if (wantsAll) {
+                cb(null, records);
+                return;
+            }
+            const [first] = records;
+            cb(null, first.address, first.family);
+        };
+        if (validatedAddresses !== undefined) {
+            respond(validatedAddresses.map((address) => ({
+                address,
+                family: address.includes(':') ? 6 : 4
+            })));
+            return;
+        }
+        dns.lookup(hostname, { all: true }, (err, records) => {
+            if (err) {
+                cb(err, '', 0);
+                return;
+            }
+            respond(records);
+        });
+    };
+}

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

@@ -0,0 +1,22 @@
+export declare const RAG_CITATION_LINE = "After your answer, add one final line naming the files you used, written exactly as [Sources: file-a.pdf, file-b.md] - or [Sources: none] if the excerpts did not answer the question. This line is required, it is the only place square brackets belong, and it is removed before the user sees it.";
+export declare function currentTimeAnnotation(now?: Date): string;
+export declare function annotateLastUserTime<T extends {
+    role: string;
+    content: string;
+}>(turns: ReadonlyArray<T>, now?: Date): T[];
+export interface SystemPromptInput {
+    bio?: string | null | undefined;
+    toolNames?: ReadonlyArray<string>;
+    skillsSection?: string | null;
+}
+export interface SystemPromptParts {
+    text: string;
+    bioChars: number;
+    skillsChars: number;
+}
+export declare function systemPromptParts({ bio, toolNames, skillsSection }: SystemPromptInput): SystemPromptParts;
+export declare function buildSystemPrompt(input: SystemPromptInput): string;
+export declare function skillsPromptSection(activeSkills: ReadonlyArray<{
+    name: string;
+    description: string;
+}>): string | null;

package/dist-lib/lib/prompt.js

@@ -0,0 +1,77 @@
+const BASE_GUIDELINES = [
+    'When the request is ambiguous, ask for clarification rather than guessing.'
+];
+const TOOL_GUIDELINES = [
+    'Request one action at a time; inspect the result before deciding the next step.',
+    'If a tool fails, analyze the error and try a corrective action before asking the user for help.',
+    'If a tool reports missing auth, setup, or approval, take the next tool step to complete it. Do not ask the user in chat whether to request approval; the policy/UI layer handles that.',
+    'If the user asks you to use a tool, emit a tool call. Never claim external information was fetched or a side effect completed unless a tool result from this turn proves it.',
+    'After tool execution, summarize the result for the user in plain language.',
+    'Every gated tool takes an `intent`: one short sentence, addressed to the user, saying plainly what that call does for them — the outcome in their words, never the code. It is the only thing the approval prompt shows them, so never leave it out and never paste the command into it.'
+];
+const EXEC_FILE_GUIDELINE = 'You CAN create and deliver files: run code with `exec` and declare the file names in `outputs` — each produced file is attached to the chat for the user to open or save. Never claim you cannot produce a file, and never instruct the user to run code or use another app to make one.';
+const EXEC_ATTACHED_IMAGE_GUIDELINE = 'An image the user attached is a file you can use, not just something to look at: when they want it inside a file you build, stage that attachment as an `exec` input and embed it. Never generate a replacement for an image the user attached, and if you truly cannot use it, say so rather than delivering the file without it.';
+const SKILL_GUIDELINES = [
+    'Tools are typed callable functions; skills are markdown guidance for when and how to use them.',
+    'Before your first action on a request, check the skills list. If a skill covers the capability you are about to use, call the `skill` tool to load its full instructions FIRST — before any other tool call, and before asking the user a follow-up; the instructions usually answer it.',
+    'Never use a capability whose skill you have not loaded this conversation, and never claim a capability is unavailable without checking the skills list.',
+    'Loaded instructions may point to more files in the skill (e.g. references/edit.md). Call the `skill` tool again with `name` and `file` to load one BEFORE doing the work it covers — never guess what a referenced file contains.'
+];
+const CITATION_GUIDELINE = 'Search results arrive prefixed with source labels (`[1]`, `[Source 2: file, ...]`, `Source: <url>`). Do NOT echo those labels or refer to sources by number — they are shown to the user separately. Name a source (its file name or site) in natural prose when you rely on it. If the user explicitly asks for numbered references, produce them normally.';
+export const RAG_CITATION_LINE = 'After your answer, add one final line naming the files you used, written exactly as [Sources: file-a.pdf, file-b.md] - or [Sources: none] if the excerpts did not answer the question. This line is required, it is the only place square brackets belong, and it is removed before the user sees it.';
+const METADATA_SECTION = `## Message Metadata
+
+User messages may include metadata such as [Current local time: ...]. This is contextual information provided by the system, not part of the user's query. Use it only when relevant and never repeat it unless the user asks about the current date or time.`;
+export function currentTimeAnnotation(now = new Date()) {
+    const p = (n) => String(n).padStart(2, '0');
+    const stamp = `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())} ${p(now.getHours())}:${p(now.getMinutes())}:${p(now.getSeconds())}`;
+    const offset = -now.getTimezoneOffset();
+    const sign = offset < 0 ? '-' : '+';
+    const abs = Math.abs(offset);
+    return `[Current local time: ${stamp} (UTC${sign}${p(Math.floor(abs / 60))}:${p(abs % 60)})]`;
+}
+export function annotateLastUserTime(turns, now) {
+    const result = [...turns];
+    for (let i = result.length - 1; i >= 0; i--) {
+        const turn = result[i];
+        if (!turn || turn.role !== 'user')
+            continue;
+        result[i] = { ...turn, content: `${currentTimeAnnotation(now)}\n\n${turn.content}` };
+        break;
+    }
+    return result;
+}
+function buildGuidelines(active) {
+    const lines = [...BASE_GUIDELINES];
+    if (active.size > 0)
+        lines.push(...TOOL_GUIDELINES);
+    if (active.has('exec'))
+        lines.push(EXEC_FILE_GUIDELINE, EXEC_ATTACHED_IMAGE_GUIDELINE);
+    if (active.has('skill'))
+        lines.push(...SKILL_GUIDELINES);
+    if (active.has('web_search') || active.has('web_fetch')) {
+        lines.push(CITATION_GUIDELINE);
+    }
+    return `**Guidelines:**\n${lines.map((line) => `- ${line}`).join('\n')}`;
+}
+export function systemPromptParts({ bio, toolNames = [], skillsSection }) {
+    const active = new Set(toolNames);
+    const header = active.size
+        ? 'You are a helpful AI assistant with access to tools.'
+        : 'You are a helpful AI assistant.';
+    const preamble = `${header}\n\n${METADATA_SECTION}`;
+    const skills = active.has('skill') ? skillsSection : null;
+    const text = [preamble, bio, skills, buildGuidelines(active)]
+        .filter((part) => Boolean(part))
+        .join('\n\n');
+    return { text, bioChars: (bio ?? '').length, skillsChars: (skills ?? '').length };
+}
+export function buildSystemPrompt(input) {
+    return systemPromptParts(input).text;
+}
+export function skillsPromptSection(activeSkills) {
+    if (!activeSkills.length)
+        return null;
+    const lines = activeSkills.map((skill) => `- ${skill.name}: ${skill.description}`).join('\n');
+    return `Skills available this turn. You MUST call the \`skill\` tool with its name BEFORE using the capability it describes — load the skill first, then act.\n${lines}`;
+}

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

@@ -0,0 +1,9 @@
+export interface PushQueue<T> extends AsyncIterable<T> {
+    push(item: T): Promise<void>;
+    end(): void;
+    readonly size: number;
+}
+export interface PushQueueOptions {
+    highWaterMark?: number;
+}
+export declare function pushQueue<T>({ highWaterMark }?: PushQueueOptions): PushQueue<T>;