@qvac/harness 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -8,6 +8,30 @@ 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
@@ -1041,7 +1065,8 @@ 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.2...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

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/harness",
-  "version": "0.7.2",
+  "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"