@qvac/harness 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -8,6 +8,52 @@ While the major version is `0`, a breaking change bumps the minor version.
 
 ## [Unreleased]
 
+## [0.7.3] - 2026-10-01
+
+### Added
+
+- A tool result may carry `answer: true` beside its `content` to end the turn
+  with that content as the reply, without another round through the model.
+  The `tool-result` event still fires. `weather_lookup` uses it for an
+  ambiguous or unknown place: the question that lists the namesakes, or the
+  not-found line, is the reply.
+
+### Fixed
+
+- `weather_lookup` finds the place before it asks for the weather. It looks the
+  city up on Open-Meteo's geocoder, `geocoding-api.open-meteo.com`, a new
+  outbound host, and asks wttr.in for the forecast at the coordinates of the
+  place it picked, which leads the report. A bare "Nassau" now reports Nassau,
+  Bahamas. It used to ask wttr.in by name, whose own geocoder put it in
+  Westbury, New York. A name that places of a similar size share, such as
+  Springfield, gets a question listing up to four of them instead of a
+  forecast: any namesake with a tenth of the largest one's population counts.
+  A country or state in the request picks among them. When the geocoder is
+  blocked, slow or failing, or knows no such place, the lookup asks wttr.in by
+  name, as before. The resource label names both hosts.
+
+## [0.7.2] - 2026-10-01
+
+### Added
+
+- `web_fetch` attaches a plain-text file (.txt, .csv, .json…) to the chat
+  besides returning its text, so the user can open or save it and `exec` can
+  stage it to read past the returned text. The result carries its
+  `attachmentId`, `fileName` and `byteLength`. A body cut at the fetch cap is
+  not attached, and a host that cannot store files gets the text alone, as
+  with page images. (#147, #148)
+
+### Changed
+
+- Speech sounds cleaner on desktops. Devices on the `mid` profile and up now
+  speak with Supertonic 3 FP16 (`Supertonic3-FP16`, 207 MB) instead of Q8_0
+  (127 MB), at 16 inference steps instead of 5, which removes the artifacts
+  the 5-step output had. Synthesis takes about 2.7× as long, still around 7×
+  faster than real time on an M-series Mac. Phones (`low`) and `tiny` devices
+  keep Q4_0 at 5 steps. A host that prefetches `infraModelsFor` downloads the
+  FP16 model once; `Supertonic3-Q8_0` stays in the catalog, and now also runs
+  at 16 steps when a host asks for it by name. (#149)
+
 ## [0.7.1] - 2026-09-30
 
 ### Added
@@ -1019,7 +1065,9 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
 - GPU stats are read through `bare-gpu-info`, so every dependency installs from
   the public npm registry. (#12)
 
-[Unreleased]: https://github.com/tetherto/qvac-harness/compare/v0.7.1...HEAD
+[Unreleased]: https://github.com/tetherto/qvac-harness/compare/v0.7.3...HEAD
+[0.7.3]: https://github.com/tetherto/qvac-harness/compare/v0.7.2...v0.7.3
+[0.7.2]: https://github.com/tetherto/qvac-harness/compare/v0.7.1...v0.7.2
 [0.7.1]: https://github.com/tetherto/qvac-harness/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/tetherto/qvac-harness/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/tetherto/qvac-harness/compare/v0.5.0...v0.6.0

package/dist-lib/index.js

@@ -21,7 +21,7 @@ import { buildWavBuffer } from './lib/wav-encode.js';
 import { createVoiceLane, packSamples, speakOnce, speakStreamOnce, transcribeOnce, transcribeStreaming, SUPERTONIC_SAMPLE_RATE } from './lib/capabilities/voice.js';
 import { pushQueue } from './lib/queue.js';
 import { AbortedError, raceAbort } from './lib/helpers/race-abort.js';
-import { audioGenDownloadMetadata, customProjectionMap, defaultProjectionMap, defaultTtsFor, defaultVoiceModel, diffusionDownloadMetadata, curatedModelAsset, infraModelsFor, modelAddonOf, modelNameToCapabilityProfile, musicModelSet, residentSrc, setCustomModels } from './lib/models/model-catalog.js';
+import { audioGenDownloadMetadata, categoryModelConfig, customProjectionMap, defaultProjectionMap, defaultTtsFor, defaultVoiceModel, diffusionDownloadMetadata, curatedModelAsset, infraModelsFor, modelAddonOf, modelNameToCapabilityProfile, musicModelSet, residentSrc, setCustomModels } from './lib/models/model-catalog.js';
 import { createModelStatusCache, customModelRows, invalidateModelStatusCache, mergeCustomRows, listModels } from './lib/models/model-list.js';
 import { deleteModelFiles, summarizeDelete } from './lib/models/model-delete.js';
 import { createEmbedPool, createLoadTracker, createModelPool, createVoicePool, awaitModelCapacity, evictIdle, evictIdleWhere, evictModel, evictModelWithin, isResident, leaseResidentModel, leaseCount, loadedModels, loadingModels, settledModels, modelKey, modelOf, releaseModel, resolveLoadOptions, progressState } from './lib/models/model-pool.js';
@@ -662,6 +662,7 @@ export class Harness extends ReadyResource {
             modelType: 'tts-ggml',
             addon: 'tts',
             modelConfig: TTS_MODEL_CONFIG,
+            modelConfigFor: categoryModelConfig,
             loads: this._loads
         });
     }

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

@@ -232,6 +232,15 @@ function callSucceeded(result, outcome) {
     const exitCode = isRecord(result) ? result.exitCode : undefined;
     return typeof exitCode !== 'number' || exitCode === 0;
 }
+function isAnswerResult(result) {
+    return (isRecord(result) &&
+        result.answer === true &&
+        typeof result.content === 'string' &&
+        result.content.trim().length > 0);
+}
+function answerOf(result) {
+    return isAnswerResult(result) ? result.content : undefined;
+}
 function retryHints(result) {
     if (!result || typeof result !== 'object' || Array.isArray(result))
         return {};
@@ -1038,6 +1047,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
             ];
             let cappedCalls = 0;
             let progressed = false;
+            let answer;
             runOutcomes.beginRound();
             for (const { call, tool, args, rawCall, rejection, intent } of resolved) {
                 if (signal?.aborted)
@@ -1144,6 +1154,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 }
                 else if (execution.executed && callSucceeded(output, executionOutcome)) {
                     progressed = true;
+                    answer ??= answerOf(output);
                 }
                 runOutcomes.record(output, executionOutcome);
                 if (searchCapped) {
@@ -1197,6 +1208,13 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 failed.clear();
                 blockedRepeats = 0;
             }
+            if (answer !== undefined) {
+                yield { type: 'content', text: answer };
+                history.push({ role: 'assistant', content: answer });
+                said = answer;
+                outcome = 'answered';
+                break;
+            }
             history.push({ role: 'user', content: TOOL_CONTINUATION_NUDGE });
             if (blockedRepeats >= MAX_BLOCKED_REPEATS) {
                 break;

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

@@ -1,6 +1,7 @@
 import type { ModelRegistryEntry, ToolDialect } from '@qvac/sdk';
 import type { ImageModelSet } from '../tools/generate-image.ts';
 import type { MusicModelStages } from '../tools/generate-music.ts';
+import type { ModelSrc } from './context.ts';
 import type { ModelAddon } from './model-source.ts';
 export interface SdkModelAsset extends ModelRegistryEntry {
     readonly src: string;
@@ -22,8 +23,10 @@ export interface CategoryDefault {
     readonly name: string;
     readonly category: ModelCategory;
     readonly asset: SdkModelAsset;
+    readonly modelConfig?: Readonly<Record<string, unknown>>;
 }
 export declare const CATEGORY_DEFAULTS: ReadonlyArray<CategoryDefault>;
+export declare function categoryModelConfig(modelSrc: ModelSrc): Readonly<Record<string, unknown>> | undefined;
 export declare function defaultVoiceModel(category: ModelCategory): string;
 export declare function defaultTtsFor(profile: CapabilityProfile): CategoryDefault;
 export interface CatalogModel {

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

@@ -1,4 +1,4 @@
-import { AUDIOGEN_ACESTEP_5HZ_LM_0_6B_Q8_0, AUDIOGEN_ACESTEP_V15_SFT_Q8_0, AUDIOGEN_ACESTEP_V15_TURBO_Q4_K_M, AUDIOGEN_ACESTEP_V15_TURBO_Q8_0, AUDIOGEN_QWEN3_EMBEDDING_0_6B_Q8_0, AUDIOGEN_VAE_BF16, EMBEDDINGGEMMA_300M_Q4_0, FLUX_2_KLEIN_4B_Q4_0, FLUX_2_KLEIN_4B_VAE, HEALTHCARE_1_7B_MEDICAL_Q4_K_M, HEALTHCARE_4B_MEDICAL_Q4_K_M, MMPROJ_QWEN3_5_2B_MULTIMODAL_Q8_0, MMPROJ_QWEN3_5_4B_MULTIMODAL_Q8_0, MMPROJ_QWEN3_5_9B_MULTIMODAL_F16, MMPROJ_QWEN3_6_27B_MULTIMODAL_F16, MMPROJ_QWEN3_6_35B_A3B_MULTIMODAL_F16, MMPROJ_QWEN3_8_27B_MULTIMODAL_F16, QWEN3_5_2B_MULTIMODAL_Q4_K_M, QWEN3_5_4B_MULTIMODAL_Q4_K_M, QWEN3_5_9B_MULTIMODAL_Q4_K_M, PARAKEET_TDT_0_6B_V3_Q8_0, QWEN3_4B_Q4_K_M, QWEN3_6_27B_MULTIMODAL_Q4_K_XL, QWEN3_6_35B_A3B_MULTIMODAL_Q4_K_M, QWEN3_8_27B_MULTIMODAL_UD_Q4_K_XL, SD_V2_1_1B_Q8_0, SDXL_BASE_1_0_3B_Q4_0, TTS_MULTILINGUAL_SUPERTONIC3_Q4_0, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0 } from '@qvac/sdk/models';
+import { AUDIOGEN_ACESTEP_5HZ_LM_0_6B_Q8_0, AUDIOGEN_ACESTEP_V15_SFT_Q8_0, AUDIOGEN_ACESTEP_V15_TURBO_Q4_K_M, AUDIOGEN_ACESTEP_V15_TURBO_Q8_0, AUDIOGEN_QWEN3_EMBEDDING_0_6B_Q8_0, AUDIOGEN_VAE_BF16, EMBEDDINGGEMMA_300M_Q4_0, FLUX_2_KLEIN_4B_Q4_0, FLUX_2_KLEIN_4B_VAE, HEALTHCARE_1_7B_MEDICAL_Q4_K_M, HEALTHCARE_4B_MEDICAL_Q4_K_M, MMPROJ_QWEN3_5_2B_MULTIMODAL_Q8_0, MMPROJ_QWEN3_5_4B_MULTIMODAL_Q8_0, MMPROJ_QWEN3_5_9B_MULTIMODAL_F16, MMPROJ_QWEN3_6_27B_MULTIMODAL_F16, MMPROJ_QWEN3_6_35B_A3B_MULTIMODAL_F16, MMPROJ_QWEN3_8_27B_MULTIMODAL_F16, QWEN3_5_2B_MULTIMODAL_Q4_K_M, QWEN3_5_4B_MULTIMODAL_Q4_K_M, QWEN3_5_9B_MULTIMODAL_Q4_K_M, PARAKEET_TDT_0_6B_V3_Q8_0, QWEN3_4B_Q4_K_M, QWEN3_6_27B_MULTIMODAL_Q4_K_XL, QWEN3_6_35B_A3B_MULTIMODAL_Q4_K_M, QWEN3_8_27B_MULTIMODAL_UD_Q4_K_XL, SD_V2_1_1B_Q8_0, SDXL_BASE_1_0_3B_Q4_0, TTS_MULTILINGUAL_SUPERTONIC3_FP16, TTS_MULTILINGUAL_SUPERTONIC3_Q4_0, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0 } from '@qvac/sdk/models';
 import { detectToolDialect } from './tool-dialect.js';
 import { defaultTtsModelName } from './tts-model-default.js';
 import { CAPABILITY_PROFILE_ORDER, QWEN_35_2B, QWEN_35_4B, QWEN_35_9B, QWEN_36_27B, QWEN_36_35B_A3B, QWEN_38_27B, MEDPSY_1_7B, MEDPSY_4B, isCapabilityProfile, meetsMinCapabilityProfile, modelNameToCapabilityProfile, capabilityProfileToModelName, isMultimodalLlm, AGENT_MODEL_NAMES, modelDisplayName, capabilityProfileModelLabel, DEFAULT_IMAGE_MODEL_CHOICE, IMAGE_CHOICE_CATALOG, isMobilePlatform, runnableModelName } from './model-catalog-constants.js';
@@ -62,9 +62,21 @@ export function defaultProjectionMap() {
     }
     return map;
 }
+const TTS_FULL_STEPS = { ttsNumInferenceSteps: 16 };
 export const CATEGORY_DEFAULTS = [
     { name: 'Supertonic3-Q4_0', category: 'tts', asset: TTS_MULTILINGUAL_SUPERTONIC3_Q4_0 },
-    { name: 'Supertonic3-Q8_0', category: 'tts', asset: TTS_MULTILINGUAL_SUPERTONIC3_Q8_0 },
+    {
+        name: 'Supertonic3-Q8_0',
+        category: 'tts',
+        asset: TTS_MULTILINGUAL_SUPERTONIC3_Q8_0,
+        modelConfig: TTS_FULL_STEPS
+    },
+    {
+        name: 'Supertonic3-FP16',
+        category: 'tts',
+        asset: TTS_MULTILINGUAL_SUPERTONIC3_FP16,
+        modelConfig: TTS_FULL_STEPS
+    },
     {
         name: 'Parakeet-TDT-0.6B-v3-Q8_0',
         category: 'transcription',
@@ -72,6 +84,10 @@ export const CATEGORY_DEFAULTS = [
     },
     { name: 'EmbeddingGemma-300M-Q4_0', category: 'embedding', asset: EMBEDDINGGEMMA_300M_Q4_0 }
 ];
+export function categoryModelConfig(modelSrc) {
+    const src = typeof modelSrc === 'string' ? modelSrc : modelSrc.src;
+    return CATEGORY_DEFAULTS.find((entry) => entry.asset.src === src)?.modelConfig;
+}
 export function defaultVoiceModel(category) {
     const entry = CATEGORY_DEFAULTS.find((candidate) => candidate.category === category);
     if (!entry) {

package/dist-lib/lib/models/model-pool.d.ts

@@ -156,8 +156,9 @@ export interface VoicePoolOptions {
     modelType: string;
     addon: ModelAddon;
     modelConfig?: Record<string, unknown> | undefined;
+    modelConfigFor?: (modelSrc: ModelSrc) => Readonly<Record<string, unknown>> | undefined;
     openclCacheDir?: (() => string | undefined) | undefined;
     loads?: LoadTracker;
 }
-export declare function createVoicePool(loadSdk: LoadVoiceSdk, notify: NotifyFn, { modelType, addon, modelConfig, openclCacheDir, loads }: VoicePoolOptions): ModelPuddle;
+export declare function createVoicePool(loadSdk: LoadVoiceSdk, notify: NotifyFn, { modelType, addon, modelConfig, modelConfigFor, openclCacheDir, loads }: VoicePoolOptions): ModelPuddle;
 export {};

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

@@ -392,14 +392,16 @@ export function createEmbedPool(loadSdk, notify, { faults, batchSize = DEFAULT_E
         ...NO_IDLE_GC
     });
 }
-export function createVoicePool(loadSdk, notify, { modelType, addon, modelConfig, openclCacheDir, loads = createLoadTracker() }) {
+export function createVoicePool(loadSdk, notify, { modelType, addon, modelConfig, modelConfigFor, openclCacheDir, loads = createLoadTracker() }) {
     const wantsGpu = modelConfig?.['useGPU'] === true;
     let gpuRefused = false;
     const load = async (model) => {
         const sdk = await loadSdk();
         const modelSrc = await resolveModelSrc(sdk, model, addon);
+        const tuned = modelConfigFor?.(modelSrc);
+        const loadConfig = tuned ? { ...modelConfig, ...tuned } : modelConfig;
         const attempt = () => {
-            const config = gpuRefused ? { ...modelConfig, useGPU: false } : modelConfig;
+            const config = gpuRefused ? { ...loadConfig, useGPU: false } : loadConfig;
             const openclCache = gpuRefused ? undefined : openclCacheDir?.();
             return loads.track(sdk.loadModel({
                 modelSrc,

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

@@ -1,9 +1,9 @@
 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'
+    mid: 'Supertonic3-FP16',
+    high: 'Supertonic3-FP16',
+    xhigh: 'Supertonic3-FP16'
 };
 export const TTS_MODEL_NAMES = [
     ...new Set(Object.values(TTS_MODEL_BY_PROFILE))

package/dist-lib/lib/tools/weather-lookup/geocode.d.ts

@@ -0,0 +1,26 @@
+import { type AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { FetchFn } from '../http-request.ts';
+import { type HostResolver } from '../url-guard.ts';
+import { type ResolvedPlace } from './place.ts';
+export declare const GEOCODER_HOST = "geocoding-api.open-meteo.com";
+export declare const GEOCODE_TIMEOUT_MS = 5000;
+export interface Candidate extends ResolvedPlace {
+    readonly latitude: number;
+    readonly longitude: number;
+    readonly population: number | undefined;
+}
+export interface Chosen {
+    readonly place: Candidate;
+    readonly verified: boolean;
+}
+export type Choice = Chosen | {
+    readonly contenders: readonly Candidate[];
+};
+export interface GeocodeRequest {
+    readonly fetch: FetchFn;
+    readonly resolveHost: HostResolver;
+    readonly signal: BareAbortSignal;
+    readonly timeoutMs: number;
+}
+export declare function geocode(city: string, lookup: GeocodeRequest): Promise<Candidate[]>;
+export declare function choose(city: string, qualifier: string | null, candidates: readonly Candidate[]): Choice | null;

package/dist-lib/lib/tools/weather-lookup/geocode.js

@@ -0,0 +1,110 @@
+import { AbortController } from 'bare-abort-controller';
+import { z } from 'zod';
+import { errorMessage } from '../../guards.js';
+import { hlog } from '../../log.js';
+import { resolveOutboundUrl } from '../url-guard.js';
+import { checkQualifier, describePlace, fold } from './place.js';
+export const GEOCODER_HOST = 'geocoding-api.open-meteo.com';
+const MAX_BODY_BYTES = 200_000;
+export const GEOCODE_TIMEOUT_MS = 5_000;
+const CONTENDER_RATIO = 10;
+const MAX_LISTED = 4;
+const GeocodeSchema = z.object({
+    results: z
+        .array(z.object({
+        name: z.string(),
+        latitude: z.number(),
+        longitude: z.number(),
+        country: z.string().optional(),
+        admin1: z.string().optional(),
+        population: z.number().optional()
+    }))
+        .optional()
+});
+export async function geocode(city, lookup) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(undefined), lookup.timeoutMs);
+    const onLookupAbort = () => controller.abort(undefined);
+    lookup.signal.addEventListener('abort', onLookupAbort);
+    try {
+        return await search(city, lookup, controller.signal);
+    }
+    catch (err) {
+        if (lookup.signal.aborted) {
+            throw err;
+        }
+        hlog('warn: weather geocoder failed, asking wttr.in by name', { err: errorMessage(err) });
+        return [];
+    }
+    finally {
+        clearTimeout(timeout);
+        lookup.signal.removeEventListener('abort', onLookupAbort);
+    }
+}
+async function search(city, { fetch, resolveHost }, signal) {
+    const query = `name=${encodeURIComponent(city)}&count=10&language=en&format=json`;
+    const url = new URL(`https://${GEOCODER_HOST}/v1/search?${query}`);
+    const check = await resolveOutboundUrl(url, resolveHost, signal);
+    if (check.blocked) {
+        throw new Error(check.blocked);
+    }
+    const response = await fetch(url, {
+        method: 'GET',
+        headers: { Accept: 'application/json' },
+        signal,
+        redirect: 'manual',
+        validatedAddresses: check.addresses,
+        maxBytes: MAX_BODY_BYTES
+    });
+    if (response.status !== 200) {
+        throw new Error(`geocoder answered HTTP ${response.status}`);
+    }
+    const { results = [] } = GeocodeSchema.parse(JSON.parse(await response.text()));
+    return results.map((result) => ({
+        area: result.name,
+        region: result.admin1 ?? '',
+        country: result.country ?? '',
+        latitude: result.latitude,
+        longitude: result.longitude,
+        population: result.population
+    }));
+}
+export function choose(city, qualifier, candidates) {
+    const exact = candidates.filter((candidate) => fold(candidate.area) === fold(city));
+    const top = byPopulation(exact)[0] ?? candidates[0];
+    if (top === undefined) {
+        return null;
+    }
+    if (qualifier !== null) {
+        return qualified(qualifier, { exact, candidates, top });
+    }
+    const contenders = contendersOf(exact);
+    if (contenders.length > 1) {
+        return { contenders };
+    }
+    return { place: top, verified: exact.includes(top) };
+}
+function qualified(qualifier, { exact, candidates, top }) {
+    const named = (pool) => pool.find((candidate) => checkQualifier(qualifier, candidate) === 'match');
+    const namesake = named(byPopulation(exact));
+    if (namesake !== undefined) {
+        return { place: namesake, verified: true };
+    }
+    return { place: named(candidates) ?? top, verified: false };
+}
+function contendersOf(exact) {
+    const pool = byPopulation(exact);
+    const top = pool[0]?.population;
+    if (top === undefined) {
+        return [];
+    }
+    const lines = pool.map(describePlace);
+    return pool
+        .filter((candidate, index) => candidate.population !== undefined &&
+        candidate.population * CONTENDER_RATIO >= top &&
+        lines.indexOf(describePlace(candidate)) === index)
+        .slice(0, MAX_LISTED);
+}
+function byPopulation(candidates) {
+    return [...candidates].sort((a, b) => (b.population ?? -1) - (a.population ?? -1));
+}

package/dist-lib/lib/tools/weather-lookup/place.js

@@ -17,6 +17,8 @@ const QUALIFIER_ALIASES = [
     ['united arab emirates', 'united arab emirates'],
     ['uae', 'united arab emirates'],
     ['holland', 'netherlands'],
+    ['schweiz', 'switzerland'],
+    ['suisse', 'switzerland'],
     ['deutschland', 'germany'],
     ['espana', 'spain'],
     ['italia', 'italy']
@@ -103,7 +105,9 @@ export function fold(value) {
         .trim();
 }
 export function describePlace(place) {
-    return [place.area, place.region, place.country].filter((part) => part.length > 0).join(', ');
+    return [place.area, place.region, place.country]
+        .filter((part, index, parts) => part.length > 0 && parts.indexOf(part) === index)
+        .join(', ');
 }
 export function qualifierOf(location) {
     const comma = location.indexOf(',');

package/dist-lib/lib/tools/weather-lookup.d.ts

@@ -4,5 +4,6 @@ import { type HostResolver } from './url-guard.ts';
 export interface WeatherLookupToolOptions {
     fetch?: FetchFn;
     resolveHost?: HostResolver;
+    geocodeTimeoutMs?: number;
 }
-export declare function createWeatherLookupTool({ fetch: fetchImpl, resolveHost }?: WeatherLookupToolOptions): ToolDefinition;
+export declare function createWeatherLookupTool({ fetch, resolveHost, geocodeTimeoutMs }?: WeatherLookupToolOptions): ToolDefinition;

package/dist-lib/lib/tools/weather-lookup.js

@@ -4,12 +4,13 @@ import { lookupHost } from '../dns-lookup.js';
 import { errorMessage } from '../guards.js';
 import { isRedirectStatus } from './http-request/request.js';
 import { resolveOutboundUrl } from './url-guard.js';
+import { choose, geocode, GEOCODE_TIMEOUT_MS, GEOCODER_HOST } from './weather-lookup/geocode.js';
 import { checkQualifier, cityMatches, describePlace, qualifierOf } from './weather-lookup/place.js';
 import { placeOf, renderReport, WeatherJsonSchema } from './weather-lookup/report.js';
 const WEATHER_HOST = 'wttr.in';
 const LOOKUP_TIMEOUT_MS = 15_000;
 const MAX_BODY_BYTES = 400_000;
-export function createWeatherLookupTool({ fetch: fetchImpl, resolveHost = lookupHost } = {}) {
+export function createWeatherLookupTool({ fetch = noRedirectFetch, resolveHost = lookupHost, geocodeTimeoutMs = GEOCODE_TIMEOUT_MS } = {}) {
     return {
         name: 'weather_lookup',
         toolset: 'http-request',
@@ -17,7 +18,8 @@ export function createWeatherLookupTool({ fetch: fetchImpl, resolveHost = lookup
         autoApprove: true,
         description: 'Look up the current weather and a three-day forecast for a place, via wttr.in. ' +
             'Returns the place the service resolved on its first line, then the conditions now and ' +
-            'one line per day. Use it for any question about weather, temperature or forecast.',
+            'one line per day. Use it for any question about weather, temperature or forecast. ' +
+            'When a name matches several places it answers with a question listing them.',
         parameters: {
             type: 'object',
             properties: {
@@ -30,93 +32,122 @@ export function createWeatherLookupTool({ fetch: fetchImpl, resolveHost = lookup
             required: ['location']
         },
         effect: () => 'read',
-        resource: () => ({ kind: 'host', label: WEATHER_HOST }),
-        async execute(args, ctx) {
-            const raw = args.location;
-            if (typeof raw !== 'string' || raw.trim().length === 0) {
-                return { error: 'location must be a non-empty string' };
-            }
-            const location = raw.trim();
-            if (ctx?.signal?.aborted) {
-                return { error: 'weather_lookup cancelled' };
-            }
-            const url = new URL(`https://${WEATHER_HOST}/${encodeURIComponent(location)}?format=j1`);
-            const fetch = fetchImpl ?? noRedirectFetch;
-            const controller = new AbortController();
-            const timeout = setTimeout(() => controller.abort(undefined), LOOKUP_TIMEOUT_MS);
-            const onCallerAbort = () => controller.abort(undefined);
-            ctx?.signal?.addEventListener('abort', onCallerAbort);
-            try {
-                const check = await resolveOutboundUrl(url, resolveHost, ctx?.signal);
-                if (check.blocked) {
-                    return { error: check.blocked };
-                }
-                const response = await fetch(url, {
-                    method: 'GET',
-                    headers: { Accept: 'application/json' },
-                    signal: controller.signal,
-                    redirect: 'manual',
-                    validatedAddresses: check.addresses,
-                    maxBytes: MAX_BODY_BYTES
-                });
-                if (isRedirectStatus(response.status)) {
-                    return { error: `${WEATHER_HOST} redirected the lookup for "${location}"` };
-                }
-                const body = await response.text();
-                if (/location not found/i.test(body)) {
-                    return { content: notFound(location) };
-                }
-                if (response.status !== 200) {
-                    return { error: unavailable(`it answered HTTP ${response.status}`), code: 'transport' };
-                }
-                let json;
-                try {
-                    json = WeatherJsonSchema.parse(JSON.parse(body));
-                }
-                catch {
-                    return { error: unavailable('it did not return a forecast') };
-                }
-                const place = placeOf(json);
-                if (place === null) {
-                    return { content: notFound(location) };
-                }
-                const qualifier = qualifierOf(location);
-                const verdict = qualifier === null ? null : checkQualifier(qualifier, place);
-                const named = cityMatches(location, place);
-                if (verdict === 'contradiction' && !named) {
-                    return {
-                        content: `No such place: "${location}". ${WEATHER_HOST} resolved it to ` +
-                            `${describePlace(place)}, which is somewhere else.`
-                    };
-                }
-                const verified = qualifier === null ? named : verdict === 'match';
-                return { content: renderReport(json, place, { asked: location, verified }) };
-            }
-            catch (err) {
-                if (ctx?.signal?.aborted) {
-                    return { error: 'weather_lookup cancelled' };
-                }
-                if (controller.signal.aborted) {
-                    return {
-                        error: `weather_lookup timed out after ${LOOKUP_TIMEOUT_MS} ms`,
-                        code: 'timeout'
-                    };
-                }
-                return {
-                    error: unavailable(errorMessage(err)),
-                    code: 'transport'
-                };
-            }
-            finally {
-                clearTimeout(timeout);
-                ctx?.signal?.removeEventListener('abort', onCallerAbort);
-            }
-        }
+        resource: () => ({ kind: 'host', label: `${GEOCODER_HOST}, ${WEATHER_HOST}` }),
+        execute: (args, ctx) => execute(args.location, ctx?.signal, { fetch, resolveHost, timeoutMs: geocodeTimeoutMs })
     };
 }
+async function execute(raw, callerSignal, deps) {
+    if (typeof raw !== 'string' || raw.trim().length === 0) {
+        return { error: 'location must be a non-empty string' };
+    }
+    const location = raw.trim();
+    if (callerSignal?.aborted) {
+        return { error: 'weather_lookup cancelled' };
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(undefined), LOOKUP_TIMEOUT_MS);
+    const onCallerAbort = () => controller.abort(undefined);
+    callerSignal?.addEventListener('abort', onCallerAbort);
+    try {
+        return await lookup(location, { ...deps, signal: controller.signal });
+    }
+    catch (err) {
+        return failure(err, controller.signal, callerSignal);
+    }
+    finally {
+        clearTimeout(timeout);
+        callerSignal?.removeEventListener('abort', onCallerAbort);
+    }
+}
+async function lookup(location, request) {
+    const city = (location.split(',')[0] ?? '').trim();
+    const candidates = city.length === 0 ? [] : await geocode(city, request);
+    const choice = choose(city, qualifierOf(location), candidates);
+    if (choice === null) {
+        return byName(location, request);
+    }
+    if ('contenders' in choice) {
+        return reply(which(city, choice.contenders));
+    }
+    return byCoordinates(location, choice, request);
+}
+async function byCoordinates(location, { place, verified }, request) {
+    const fetched = await forecast(`${place.latitude},${place.longitude}`, location, request);
+    if (!('json' in fetched)) {
+        return fetched;
+    }
+    return { content: renderReport(fetched.json, place, { asked: location, verified }) };
+}
+async function byName(location, request) {
+    const fetched = await forecast(encodeURIComponent(location), location, request);
+    if (!('json' in fetched)) {
+        return fetched;
+    }
+    const place = placeOf(fetched.json);
+    if (place === null) {
+        return reply(notFound(location));
+    }
+    const qualifier = qualifierOf(location);
+    const verdict = qualifier === null ? null : checkQualifier(qualifier, place);
+    const named = cityMatches(location, place);
+    if (verdict === 'contradiction' && !named) {
+        return reply(`No such place: "${location}". ${WEATHER_HOST} resolved it to ` +
+            `${describePlace(place)}, which is somewhere else.`);
+    }
+    const verified = qualifier === null ? named : verdict === 'match';
+    return { content: renderReport(fetched.json, place, { asked: location, verified }) };
+}
+async function forecast(path, location, request) {
+    const url = new URL(`https://${WEATHER_HOST}/${path}?format=j1`);
+    const check = await resolveOutboundUrl(url, request.resolveHost, request.signal);
+    if (check.blocked) {
+        return { error: check.blocked };
+    }
+    const response = await request.fetch(url, {
+        method: 'GET',
+        headers: { Accept: 'application/json' },
+        signal: request.signal,
+        redirect: 'manual',
+        validatedAddresses: check.addresses,
+        maxBytes: MAX_BODY_BYTES
+    });
+    if (isRedirectStatus(response.status)) {
+        return { error: `${WEATHER_HOST} redirected the lookup for "${location}"` };
+    }
+    return readForecast(response.status, await response.text(), location);
+}
+function readForecast(status, body, location) {
+    if (/location not found/i.test(body)) {
+        return reply(notFound(location));
+    }
+    if (status !== 200) {
+        return { error: unavailable(`it answered HTTP ${status}`), code: 'transport' };
+    }
+    try {
+        return { json: WeatherJsonSchema.parse(JSON.parse(body)) };
+    }
+    catch {
+        return { error: unavailable('it did not return a forecast') };
+    }
+}
+function failure(err, signal, callerSignal) {
+    if (callerSignal?.aborted) {
+        return { error: 'weather_lookup cancelled' };
+    }
+    if (signal.aborted) {
+        return { error: `weather_lookup timed out after ${LOOKUP_TIMEOUT_MS} ms`, code: 'timeout' };
+    }
+    return { error: unavailable(errorMessage(err)), code: 'transport' };
+}
 function unavailable(reason) {
     return `The weather service could not be reached: ${reason}.`;
 }
+function reply(content) {
+    return { content, answer: true };
+}
 function notFound(location) {
     return `No such place: "${location}". ${WEATHER_HOST} does not know it.`;
 }
+function which(city, places) {
+    return `Which ${city}: ${places.map(describePlace).join('; ')}?`;
+}

package/dist-lib/lib/tools/web-fetch.js

@@ -32,7 +32,8 @@ export function createWebFetchTool({ fetch: fetchImpl, resolveHost = lookupHost
             'shares, when a search snippet is not enough to answer. ' +
             'When the URL serves a file rather than a page — PDF, .docx, .xlsx, .pptx, an image, any ' +
             'binary — this is also the tool that downloads it: the bytes become a chat attachment and ' +
-            'the result carries its attachmentId. It is the only way to get a remote file into the ' +
+            'the result carries its attachmentId. A plain-text file (.txt, .csv, .json…) is attached ' +
+            'too, and its text is also returned. It is the only way to get a remote file into the ' +
             'chat; exec has no network and http_request truncates binary bodies.',
         parameters: {
             type: 'object',
@@ -133,13 +134,22 @@ export function createWebFetchTool({ fetch: fetchImpl, resolveHost = lookupHost
                 const imagesLine = attached.length
                     ? `\n\n[Attached ${attached.length === 1 ? 'image' : 'images'}: ${attached.join(', ')} — shown to the user automatically]`
                     : '';
+                const file = isHtml
+                    ? null
+                    : await attachTextFile(response, { url: currentUrl, mimeType, attach: ctx?.attach });
+                const fileLine = file
+                    ? `\n\n[Attached the file "${file.fileName}" (${Math.round(file.byteLength / 1024)}KB) — the user can open or save it; stage it with exec as inputs [{ "attachmentId": "${file.id}", "path": "${file.fileName}" }] to read past the text above]`
+                    : '';
                 const video = isHtml ? pageVideoRef(body, currentUrl) : null;
                 const videoLine = video
                     ? `\n\n[This page's video: ${video.url} — share this link when the user wants to watch it]`
                     : '';
                 const header = page.title ? `${page.title}\nSource: ${url}` : `Source: ${url}`;
                 return {
-                    content: `${header}\n\n${text}${imagesLine}${videoLine}`,
+                    attachmentId: file?.id,
+                    fileName: file?.fileName,
+                    byteLength: file?.byteLength,
+                    content: `${header}\n\n${text}${fileLine}${imagesLine}${videoLine}`,
                     data: {
                         results: [
                             {
@@ -201,6 +211,30 @@ async function attachDocument(response, { url, mimeType, attach }) {
             'user to attach a file this call already attached.'
     };
 }
+async function attachTextFile(response, { url, mimeType, attach }) {
+    if (!attach)
+        return null;
+    const bytes = await response.bytes?.();
+    if (!bytes || bytes.byteLength === 0 || bytes.byteLength >= MAX_PAGE_BYTES) {
+        return null;
+    }
+    const mime = mimeType || 'text/plain';
+    try {
+        return await attach({
+            fileName: attachmentFileName(url, mime),
+            mimeType: mime,
+            bytes,
+            raw: true
+        });
+    }
+    catch {
+        return null;
+    }
+}
+const TEXT_EXTENSIONS = {
+    'text/plain': 'txt',
+    'text/markdown': 'md'
+};
 const MIME_EXTENSIONS = {
     'application/pdf': 'pdf',
     'application/msword': 'doc',
@@ -234,7 +268,8 @@ function attachmentFileName(url, mimeType) {
     if (extension && acceptableExtensions(mimeType).has(extension)) {
         return base;
     }
-    if (mimeType === 'application/octet-stream' && /^[a-z][\w-]*$/.test(extension)) {
+    const trustsUrl = mimeType === 'application/octet-stream' || !isBinaryMime(mimeType);
+    if (trustsUrl && /^[a-z][\w-]*$/.test(extension)) {
         return base;
     }
     return `${base}.${extensionFor(mimeType)}`;
@@ -248,7 +283,7 @@ function acceptableExtensions(mimeType) {
     return accepted;
 }
 function extensionFor(mimeType) {
-    const known = MIME_EXTENSIONS[mimeType];
+    const known = MIME_EXTENSIONS[mimeType] ?? TEXT_EXTENSIONS[mimeType];
     if (known) {
         return known;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/harness",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "type": "module",
   "engines": {
     "bare": ">=1.34.0"
@@ -606,6 +606,10 @@
       "types": "./dist-lib/lib/tools/weather-lookup.d.ts",
       "default": "./dist-lib/lib/tools/weather-lookup.js"
     },
+    "./lib/tools/weather-lookup/geocode.ts": {
+      "types": "./dist-lib/lib/tools/weather-lookup/geocode.d.ts",
+      "default": "./dist-lib/lib/tools/weather-lookup/geocode.js"
+    },
     "./lib/tools/weather-lookup/place.ts": {
       "types": "./dist-lib/lib/tools/weather-lookup/place.d.ts",
       "default": "./dist-lib/lib/tools/weather-lookup/place.js"