@try-works/dsh-righthand 0.1.8 → 0.1.10

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,SAAS,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,SAAS,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,SAAS,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,WAAW,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,WAAW,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,eAAe,MAAM,aAAa,CAAA;AAG9C,MAAM,CAAC,MAAM,IAAI,GAAG,eAAe,CAAA;AAEnC,iFAAiF;AACjF,MAAM,CAAC,MAAM,MAAM,GAAa,EAAE,CAAA;AAQlC;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,GAAY,EAAE,SAA0B,EAAE;IAC9D,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;IACtB,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IACxB,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACrB,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACrB,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACrB,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IACxB,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;IACtB,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;IACvB,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;IACvB,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC,CAAA;IACrD,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAA;AAC7B,CAAC;AAED,6DAA6D;AAC7D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,CAAA;AACrJ,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEtF,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAEhD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAC/F,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACvF,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,SAAS,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,SAAS,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,SAAS,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,WAAW,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,WAAW,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,WAAW,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,eAAe,MAAM,aAAa,CAAA;AAG9C,MAAM,CAAC,MAAM,IAAI,GAAG,eAAe,CAAA;AAEnC,iFAAiF;AACjF,MAAM,CAAC,MAAM,MAAM,GAAa,EAAE,CAAA;AAQlC;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,GAAY,EAAE,SAA0B,EAAE;IAC9D,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;IACtB,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IACxB,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACrB,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACrB,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACrB,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IACxB,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;IACvB,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;IACtB,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;IACvB,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;IACvB,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC,CAAA;IACrD,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAA;AAC7B,CAAC;AAED,6DAA6D;AAC7D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,CAAA;AAClK,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEtF,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAEhD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAC/F,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,kBAAkB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAClH,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACvF,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA"}

package/lib/places-tools.d.ts

@@ -0,0 +1,48 @@
+/**
+ * places-tools - the second keyless data-adapter family (after weather).
+ * Geocoding, reverse geocoding and nearby search over Nominatim
+ * (OpenStreetMap, keyless), elevation over Open-Meteo (keyless).
+ *
+ * Every request goes through guardedFetch (the SSRF checklist from
+ * blueprint/data-adapter); Nominatim requests carry a User-Agent per its
+ * usage policy (max 1 req/s - agent-paced calls only).
+ * @module dsh-righthand/places-tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "righthand-places";
+export declare const inject: string[];
+export interface PlacesConfig {
+    /** Nominatim endpoint; default https://nominatim.openstreetmap.org (keyless). */
+    nominatimUrl?: string;
+    /** Open-Meteo elevation endpoint; default https://api.open-meteo.com/v1/elevation (keyless). */
+    elevationUrl?: string;
+    /** User-Agent sent with Nominatim requests (its usage policy requires one). */
+    userAgent?: string;
+}
+/** The stable place shape callers see - the wire JSON is Nominatim's. */
+export interface PlaceOut {
+    name: string;
+    lat: number;
+    lon: number;
+    displayName: string;
+    category: string;
+    type: string;
+    address: Record<string, string>;
+}
+/** Normalize one Nominatim result (search or reverse) to PlaceOut. */
+export declare function normalizePlace(raw: any): PlaceOut;
+export declare function normalizePlaces(raw: any): PlaceOut[];
+/** Normalize the Open-Meteo elevation response { elevation: [8.0] }. */
+export interface ElevationOut {
+    elevation: number;
+}
+export declare function normalizeElevation(raw: any): ElevationOut;
+/** Haversine distance in km between two lat/lon pairs. */
+export declare function distanceKm(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * The Nominatim viewbox for a radius around a point, as
+ * left,top,right,bottom (lon,lat pairs) - the order the API expects.
+ */
+export declare function nearbyViewbox(latitude: number, longitude: number, radiusKm: number): string;
+export declare function apply(ctx: Context, config?: PlacesConfig): void;
+//# sourceMappingURL=places-tools.d.ts.map

package/lib/places-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"places-tools.d.ts","sourceRoot":"","sources":["../src/places-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,eAAO,MAAM,IAAI,qBAAqB,CAAA;AACtC,eAAO,MAAM,MAAM,UAAY,CAAA;AAE/B,MAAM,WAAW,YAAY;IAC3B,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAQD,yEAAyE;AACzE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,CAgBjD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,EAAE,CAGpD;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,GAAG,GAAG,YAAY,CAGzD;AAED,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQzF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAS3F;AAED,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,YAAiB,GAAG,IAAI,CA0HnE"}

package/lib/places-tools.js

@@ -0,0 +1,191 @@
+/**
+ * places-tools - the second keyless data-adapter family (after weather).
+ * Geocoding, reverse geocoding and nearby search over Nominatim
+ * (OpenStreetMap, keyless), elevation over Open-Meteo (keyless).
+ *
+ * Every request goes through guardedFetch (the SSRF checklist from
+ * blueprint/data-adapter); Nominatim requests carry a User-Agent per its
+ * usage policy (max 1 req/s - agent-paced calls only).
+ * @module dsh-righthand/places-tools
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { guardedFetch } from "./weather-tools.js";
+export const name = 'righthand-places';
+export const inject = ['tools'];
+const DEFAULTS = {
+    nominatimUrl: 'https://nominatim.openstreetmap.org',
+    elevationUrl: 'https://api.open-meteo.com/v1/elevation',
+    userAgent: 'dsh-righthand (agent data adapter)',
+};
+/** Normalize one Nominatim result (search or reverse) to PlaceOut. */
+export function normalizePlace(raw) {
+    const address = {};
+    if (raw !== null && typeof raw === 'object' && raw.address !== null && typeof raw.address === 'object') {
+        for (const [k, v] of Object.entries(raw.address)) {
+            if (typeof v === 'string')
+                address[k] = v;
+        }
+    }
+    return {
+        name: typeof raw.name === 'string' ? raw.name : '',
+        lat: Number(raw.lat ?? 0),
+        lon: Number(raw.lon ?? 0),
+        displayName: typeof raw.display_name === 'string' ? raw.display_name : '',
+        category: typeof raw.category === 'string' ? raw.category : '',
+        type: typeof raw.type === 'string' ? raw.type : '',
+        address,
+    };
+}
+export function normalizePlaces(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map(normalizePlace);
+}
+export function normalizeElevation(raw) {
+    const arr = Array.isArray(raw.elevation) ? raw.elevation : [];
+    return { elevation: Number(arr[0] ?? 0) };
+}
+/** Haversine distance in km between two lat/lon pairs. */
+export function distanceKm(lat1, lon1, lat2, lon2) {
+    const rad = Math.PI / 180;
+    const dLat = (lat2 - lat1) * rad;
+    const dLon = (lon2 - lon1) * rad;
+    const sLat = Math.sin(dLat / 2);
+    const sLon = Math.sin(dLon / 2);
+    const a = sLat * sLat + Math.cos(lat1 * rad) * Math.cos(lat2 * rad) * sLon * sLon;
+    return 6371 * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+/**
+ * The Nominatim viewbox for a radius around a point, as
+ * left,top,right,bottom (lon,lat pairs) - the order the API expects.
+ */
+export function nearbyViewbox(latitude, longitude, radiusKm) {
+    const dy = radiusKm / 110.57;
+    const cos = Math.cos(latitude * Math.PI / 180);
+    const dx = radiusKm / (111.32 * (cos === 0 ? 1 : cos));
+    const left = longitude - dx;
+    const top = latitude + dy;
+    const right = longitude + dx;
+    const bottom = latitude - dy;
+    return [left, top, right, bottom].map(v => v.toFixed(6)).join(',');
+}
+export function apply(ctx, config = {}) {
+    const cfg = { ...DEFAULTS, ...config };
+    const nomHeaders = { 'User-Agent': cfg.userAgent };
+    ctx.tools.register(defineTool({
+        name: 'rh_places_geocode',
+        description: 'Geocode a place query with Nominatim (OpenStreetMap, keyless): text in, ranked places out. Covers search too. Respects the 1 req/s public usage policy - agent-paced calls only.',
+        parameters: {
+            query: { type: 'string', required: true, description: 'Free-text place query, e.g. "big ben london" or "Eiffel Tower".' },
+            limit: { type: 'integer', description: 'Max results, default 5 (max 20).' },
+        },
+        output: {
+            schema: { type: 'array', items: { type: 'json' } },
+            render: (_args, value) => {
+                const arr = value;
+                const text = arr.length === 0 ? '(no places found)' : arr.length + ' place(s): ' + arr.map(p => p.name !== '' ? p.name : p.displayName).join('; ');
+                return [{ type: 'text', text }];
+            },
+        },
+        async execute(args) {
+            const limit = Math.min(Math.max(1, Math.round(args.limit ?? 5)), 20);
+            const qs = new URLSearchParams({ q: args.query, format: 'jsonv2', addressdetails: '1', limit: String(limit) });
+            const body = await guardedFetch(cfg.nominatimUrl + '/search?' + qs.toString(), { init: { headers: nomHeaders } });
+            return normalizePlaces(JSON.parse(body));
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'rh_places_address',
+        description: 'Reverse geocode a lat/lon with Nominatim (OpenStreetMap, keyless): coordinates in, the closest address out.',
+        parameters: {
+            latitude: { type: 'number', required: true, description: 'Latitude.' },
+            longitude: { type: 'number', required: true, description: 'Longitude.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    name: { type: 'string', required: true },
+                    lat: { type: 'number', required: true },
+                    lon: { type: 'number', required: true },
+                    displayName: { type: 'string', required: true },
+                    category: { type: 'string', required: true },
+                    type: { type: 'string', required: true },
+                    address: { type: 'json', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: value.displayName }],
+        },
+        async execute(args) {
+            const qs = new URLSearchParams({ lat: String(args.latitude), lon: String(args.longitude), format: 'jsonv2', addressdetails: '1' });
+            const body = await guardedFetch(cfg.nominatimUrl + '/reverse?' + qs.toString(), { init: { headers: nomHeaders } });
+            const raw = JSON.parse(body);
+            if (raw.error)
+                throw new Error('Nominatim: ' + raw.error);
+            return normalizePlace(raw);
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'rh_places_elevation',
+        description: 'Elevation at a lat/lon from Open-Meteo (keyless), in metres.',
+        parameters: {
+            latitude: { type: 'number', required: true, description: 'Latitude.' },
+            longitude: { type: 'number', required: true, description: 'Longitude.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    latitude: { type: 'number', required: true },
+                    longitude: { type: 'number', required: true },
+                    elevation: { type: 'number', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: value.elevation + ' m' }],
+        },
+        async execute(args) {
+            const qs = new URLSearchParams({ latitude: String(args.latitude), longitude: String(args.longitude) });
+            const body = await guardedFetch(cfg.elevationUrl + '?' + qs.toString());
+            const out = normalizeElevation(JSON.parse(body));
+            return { latitude: args.latitude, longitude: args.longitude, elevation: out.elevation };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'rh_places_nearby',
+        description: 'Places matching a query within radiusKm of a point (Nominatim bounded search, keyless): results sorted nearest first with distanceKm attached.',
+        parameters: {
+            query: { type: 'string', required: true, description: 'What to look for, e.g. "cafe" or "pharmacy".' },
+            latitude: { type: 'number', required: true, description: 'Centre latitude.' },
+            longitude: { type: 'number', required: true, description: 'Centre longitude.' },
+            radiusKm: { type: 'number', description: 'Search radius, default 1 (min 0.1, max 20).' },
+            limit: { type: 'integer', description: 'Max results, default 5 (max 20).' },
+        },
+        output: {
+            schema: { type: 'array', items: { type: 'json' } },
+            render: (_args, value) => {
+                const arr = value;
+                const text = arr.length === 0 ? '(no nearby places)' : arr.map((p) => (p.name !== '' ? p.name : p.displayName) + ' (' + p.distanceKm.toFixed(1) + ' km)').join('; ');
+                return [{ type: 'text', text }];
+            },
+        },
+        async execute(args) {
+            const radius = Math.min(Math.max(0.1, Number(args.radiusKm ?? 1)), 20);
+            const limit = Math.min(Math.max(1, Math.round(args.limit ?? 5)), 20);
+            const qs = new URLSearchParams({
+                q: args.query,
+                viewbox: nearbyViewbox(args.latitude, args.longitude, radius),
+                bounded: '1',
+                format: 'jsonv2',
+                addressdetails: '1',
+                limit: String(limit),
+            });
+            const body = await guardedFetch(cfg.nominatimUrl + '/search?' + qs.toString(), { init: { headers: nomHeaders } });
+            return normalizePlaces(JSON.parse(body))
+                .map(p => ({ ...p, distanceKm: distanceKm(args.latitude, args.longitude, p.lat, p.lon) }))
+                .sort((a, b) => a.distanceKm - b.distanceKm);
+        },
+    }));
+}
+//# sourceMappingURL=places-tools.js.map

package/lib/places-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"places-tools.js","sourceRoot":"","sources":["../src/places-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,MAAM,CAAC,MAAM,IAAI,GAAG,kBAAkB,CAAA;AACtC,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,CAAA;AAW/B,MAAM,QAAQ,GAA2B;IACvC,YAAY,EAAE,qCAAqC;IACnD,YAAY,EAAE,yCAAyC;IACvD,SAAS,EAAE,oCAAoC;CAChD,CAAA;AAaD,sEAAsE;AACtE,MAAM,UAAU,cAAc,CAAC,GAAQ;IACrC,MAAM,OAAO,GAA2B,EAAE,CAAA;IAC1C,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACvG,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACjD,IAAI,OAAO,CAAC,KAAK,QAAQ;gBAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QAC3C,CAAC;IACH,CAAC;IACD,OAAO;QACL,IAAI,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;QAClD,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;QACzB,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;QACzB,WAAW,EAAE,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE;QACzE,QAAQ,EAAE,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE;QAC9D,IAAI,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;QAClD,OAAO;KACR,CAAA;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAQ;IACtC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAA;IAClC,OAAO,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;AAChC,CAAC;AAOD,MAAM,UAAU,kBAAkB,CAAC,GAAQ;IACzC,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAA;IAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAA;AAC3C,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,IAAY,EAAE,IAAY,EAAE,IAAY;IAC/E,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,GAAG,GAAG,CAAA;IACzB,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,GAAG,CAAA;IAChC,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,GAAG,CAAA;IAChC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAA;IAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAA;IAC/B,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAA;IACjF,OAAO,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,SAAiB,EAAE,QAAgB;IACjF,MAAM,EAAE,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,GAAG,GAAG,CAAC,CAAA;IAC9C,MAAM,EAAE,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IACtD,MAAM,IAAI,GAAG,SAAS,GAAG,EAAE,CAAA;IAC3B,MAAM,GAAG,GAAG,QAAQ,GAAG,EAAE,CAAA;IACzB,MAAM,KAAK,GAAG,SAAS,GAAG,EAAE,CAAA;IAC5B,MAAM,MAAM,GAAG,QAAQ,GAAG,EAAE,CAAA;IAC5B,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACpE,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,GAAY,EAAE,SAAuB,EAAE;IAC3D,MAAM,GAAG,GAA2B,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,EAAE,CAAA;IAE9D,MAAM,UAAU,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,SAAS,EAAE,CAAA;IAElD,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC5B,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,kLAAkL;QAC/L,UAAU,EAAE;YACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,iEAAiE,EAAE;YACzH,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,kCAAkC,EAAE;SAC5E;QACD,MAAM,EAAE;YACN,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;YAClD,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;gBACvB,MAAM,GAAG,GAAG,KAAc,CAAA;gBAC1B,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,GAAG,aAAa,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBAClJ,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;YACjC,CAAC;SACF;QACD,KAAK,CAAC,OAAO,CAAC,IAAI;YAChB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;YACpE,MAAM,EAAE,GAAG,IAAI,eAAe,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;YAC9G,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,YAAY,GAAG,UAAU,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,CAAC,CAAA;YACjH,OAAO,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAU,CAAA;QACnD,CAAC;KACF,CAAC,CAAC,CAAA;IAEH,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC5B,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,6GAA6G;QAC1H,UAAU,EAAE;YACV,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE;YACtE,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE;SACzE;QACD,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,oBAAoB,EAAE,KAAK;gBAC3B,UAAU,EAAE;oBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;oBACxC,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;oBACvC,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;oBACvC,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;oBAC/C,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;oBAC5C,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;oBACxC,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;iBAC1C;aACF;YACD,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;SACtE;QACD,KAAK,CAAC,OAAO,CAAC,IAAI;YAChB,MAAM,EAAE,GAAG,IAAI,eAAe,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC,CAAA;YAClI,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,YAAY,GAAG,WAAW,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,CAAC,CAAA;YAClH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YAC5B,IAAI,GAAG,CAAC,KAAK;gBAAE,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,GAAG,CAAC,KAAK,CAAC,CAAA;YACzD,OAAO,cAAc,CAAC,GAAG,CAAQ,CAAA;QACnC,CAAC;KACF,CAAC,CAAC,CAAA;IAEH,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC5B,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EAAE,8DAA8D;QAC3E,UAAU,EAAE;YACV,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE;YACtE,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE;SACzE;QACD,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,oBAAoB,EAAE,KAAK;gBAC3B,UAAU,EAAE;oBACV,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;oBAC5C,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;oBAC7C,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;iBAC9C;aACF;YACD,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,IAAI,EAAE,CAAC;SAC3E;QACD,KAAK,CAAC,OAAO,CAAC,IAAI;YAChB,MAAM,EAAE,GAAG,IAAI,eAAe,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAA;YACtG,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,YAAY,GAAG,GAAG,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAA;YACvE,MAAM,GAAG,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;YAChD,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAA;QACzF,CAAC;KACF,CAAC,CAAC,CAAA;IAEH,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC5B,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE,gJAAgJ;QAC7J,UAAU,EAAE;YACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,8CAA8C,EAAE;YACtG,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE;YAC7E,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,mBAAmB,EAAE;YAC/E,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6CAA6C,EAAE;YACxF,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,kCAAkC,EAAE;SAC5E;QACD,MAAM,EAAE;YACN,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;YAClD,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;gBACvB,MAAM,GAAG,GAAG,KAAc,CAAA;gBAC1B,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACzK,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;YACjC,CAAC;SACF;QACD,KAAK,CAAC,OAAO,CAAC,IAAI;YAChB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;YACtE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;YACpE,MAAM,EAAE,GAAG,IAAI,eAAe,CAAC;gBAC7B,CAAC,EAAE,IAAI,CAAC,KAAK;gBACb,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC;gBAC7D,OAAO,EAAE,GAAG;gBACZ,MAAM,EAAE,QAAQ;gBAChB,cAAc,EAAE,GAAG;gBACnB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;aACrB,CAAC,CAAA;YACF,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,YAAY,GAAG,UAAU,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,CAAC,CAAA;YACjH,OAAO,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;iBACrC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;iBACzF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAU,CAAA;QACzD,CAAC;KACF,CAAC,CAAC,CAAA;AACL,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-righthand",
   "description": "DeepSeek Harness plugin: DSH-native righthand tools — durable KV store, credential/settings management, governed exec, and a tool guard",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -74,6 +74,7 @@
     "lib",
     "src",
     "skills",
+    "docs",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"

package/skills/dsh-righthand/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dsh-righthand
-description: Use when a task needs the righthand toolkit — durable key-value storage (rh_store_*), a task board (rh_task_*), reminders (rh_events_*), credential and settings management (rh_credential_* / rh_settings_*), governed command execution (rh_run / rh_run_bg), language work (rh_text_*), weather/air data (rh_weather_*), R2 file tools (rh_files_*), ntfy push (rh_notify_send), or its tool guard policy. Covers tool reference, guard semantics, and service availability.
+description: Use when a task needs the righthand toolkit — durable key-value storage (rh_store_*), a task board (rh_task_*), reminders (rh_events_*), credential and settings management (rh_credential_* / rh_settings_*), governed command execution (rh_run / rh_run_bg), language work (rh_text_*), weather/air data (rh_weather_*), places data (rh_places_*), R2 file tools (rh_files_*), ntfy push (rh_notify_send), or its tool guard policy. Covers tool reference, guard semantics, and service availability.
 ---
 
 # dsh-righthand
@@ -18,6 +18,7 @@ The righthand toolkit: DSH-native tools over the harness's own services. Use thi
 | exec | `rh_run` / `rh_run_bg` | `ctx.subprocess` + `ctx.jobs` | Running one command (argv array, no shell interpretation). `rh_run` collects bounded output; `rh_run_bg` starts an owner-scoped background job and returns its id. |
 | text | `rh_text_summarise` / `rh_text_extract` / `rh_text_classify` / `rh_text_translate` | `ctx.llm` (one model call per verb) | Language work: shorten, turn into JSON matching a schema, sort into your labels with confidence, or translate preserving formatting. |
 | weather | `rh_weather_forecast` / `rh_weather_air` | Open-Meteo (keyless) via the SSRF-guarded fetcher | Current conditions + 3-day min/max, or PM2.5/PM10/AQI, for a lat/lon. Keyless only — anything needing an API token is out of scope. |
+| places | `rh_places_geocode` / `rh_places_address` / `rh_places_elevation` / `rh_places_nearby` | Nominatim/OSM + Open-Meteo (both keyless) via the SSRF-guarded fetcher | Geocode text to places, reverse a lat/lon to an address, get elevation, or find what is near a point — `rh_places_geocode` covers keyword search too. |
 | files | `rh_files_put` / `rh_files_get` / `rh_files_list` / `rh_files_share` / `rh_files_delete` | Cloudflare R2 (the user's own account) | Store/read/list/share/delete objects in an R2 bucket. `rh_files_share` returns a presigned download URL valid for N minutes (default 60, max 7 days) — anyone with the URL can read it for that window. |
 | events | `rh_events_create` / `rh_events_due` / `rh_events_list` / `rh_events_free` / `rh_events_cancel` | `ctx.storageDomain` (typed `righthand_events` domain) | Reminders. The agent IS the scheduler: `rh_events_due` each turn returns pending events whose time has come and marks them notified — delivered exactly once, never silently dropped. `rh_events_free` finds free slots within local working hours 09:00–17:00. |
 | notify | `rh_notify_send` | ntfy.sh (keyless) | Interrupt yourself on your own devices: publish to a topic; subscribed devices receive it. The topic name is the only secret — use an unguessable one. |
@@ -28,6 +29,8 @@ The righthand toolkit: DSH-native tools over the harness's own services. Use thi
 - One domain `righthand_store`: a `rows` table (string key → JSON value + timestamp) and a global write counter.
 - `rh_store_get` returns `{ found, key, value?, updatedAt? }` — `found: false` means the key is absent, not an error.
 - Writes are durable (backend flush before commit) and serialized on one write chain; values must be JSON-serializable.
+- The key prefix IS the collection (`task:`, `digest:`, `run:`, `uptime:`, `deploy:`); `rh_store_list` + a prefix filter is the query language. See `docs/scenario-patterns.md` for the conventions, the receipt pattern and undo trails.
+- Build, then keep one receipt key per run (`{ ...result, fetchedAt }`) — the store is the agent's durable trail; delete scenario keys when a run is only a test.
 
 ## Events semantics
 
@@ -48,6 +51,13 @@ The righthand toolkit: DSH-native tools over the harness's own services. Use thi
 - Content is text (`text/plain` default, override with `contentType`); `rh_files_get` returns `found: false` for absent keys, not an error.
 - `rh_files_share` presigns a GET — treat the URL as a secret for its validity window.
 
+## Places semantics
+
+- Two keyless providers: Nominatim (geocoding, reverse, nearby) and Open-Meteo (elevation). No tokens; requests carry a User-Agent because Nominatim's public usage policy requires one — respect the 1 req/s limit, agent-paced calls only.
+- The wire shape is the provider's; the tool shape is `{ name, lat, lon, displayName, category, type, address }`. Search tools return a root array.
+- `rh_places_nearby` bounds the query with a viewbox (`bounded=1`) and attaches a computed `distanceKm`, sorted nearest first.
+- A reverse geocode miss surfaces as a clean error, not a zeroed place.
+
 ## Weather semantics
 
 - Keyless only: Open-Meteo, no token. Every request goes through `guardedFetch` — public destinations only (loopback/private/link-local/multicast refused), every redirect hop revalidated, size and time capped.
@@ -84,6 +94,8 @@ The righthand toolkit: DSH-native tools over the harness's own services. Use thi
 | `defaultR2Bucket` | `""` | default R2 bucket for `rh_files_*` |
 | `defaultNotifyTopic` | `""` | default ntfy topic for `rh_notify_send` |
 
+Schema wall: `rh_settings_set` accepts keys the schema does not define, but `rh_settings_get` never returns them — an unregistered key looks written and silently disappears. Register new keys in the schema (a plugin change) or keep ad-hoc knobs in `rh_store`.
+
 ## Guard policy
 
 Rules come from the plugin config (`rules: [{ toolPrefix, mode, ask?, destructive? }]`). `deny` throws before dispatch; `ask` defers to the policy function (return true to allow); `allow` passes through. Tools matching no rule are unaffected. Prefixes match by prefix — `rh_run` also covers `rh_run_bg`.
@@ -92,5 +104,5 @@ Rules come from the plugin config (`rules: [{ toolPrefix, mode, ask?, destructiv
 
 ## Service availability
 
-- **web profile**: all thirty-three tools register (`storageDomain` is provided by the web app rows).
-- **other profiles** (e.g. headless): the store, task and events families stay dormant (no `storageDomain`); the other nineteen tools (secrets, settings, exec, text, weather, files, notify) still register. The plugin never fails the boot.
+- **web profile**: all thirty-seven tools register (`storageDomain` is provided by the web app rows).
+- **other profiles** (e.g. headless): the store, task and events families stay dormant (no `storageDomain`); the other twenty-three tools (secrets, settings, exec, text, weather, places, files, notify) still register. The plugin never fails the boot.

package/src/index.ts

@@ -9,9 +9,9 @@
  * and the packaged skill as child fibers; each child waits on its own
  * services, so a
  * profile without `storageDomain` (e.g. headless) simply gets the
- * store/task/events families dormant and the other nineteen tools
- * (secrets, settings, exec, text, weather, files, notify) instead of
- * failing the boot.
+ * store/task/events families dormant and the other twenty-three tools
+ * (secrets, settings, exec, text, weather, places, files, notify) instead
+ * of failing the boot.
  *
  * Modules (each individually mountable via `export * as ...`):
  * - store-tools:     rh_store_put/get/delete/list over ctx.storageDomain
@@ -19,6 +19,7 @@
  * - task-tools:      rh_task_create/list/next/update/delete over ctx.storageDomain
  * - text-tools:      rh_text_summarise/extract/classify/translate over ctx.llm
  * - weather-tools:   rh_weather_forecast/air over Open-Meteo (keyless, SSRF-guarded)
+ * - places-tools:    rh_places_geocode/address/elevation/nearby (Nominatim + Open-Meteo, keyless)
  * - files-tools:     rh_files_put/get/list/share/delete over Cloudflare R2
  * - events-tools:    rh_events_create/due/list/free/cancel over ctx.storageDomain
  * - notify-tools:    rh_notify_send over ntfy.sh (keyless)
@@ -37,6 +38,7 @@ import * as guardTools from './guard-tools.ts'
 import * as taskTools from './task-tools.ts'
 import * as textTools from './text-tools.ts'
 import * as weatherTools from './weather-tools.ts'
+import * as placesTools from './places-tools.ts'
 import * as filesTools from './files-tools.ts'
 import * as eventsTools from './events-tools.ts'
 import * as notifyTools from './notify-tools.ts'
@@ -67,6 +69,7 @@ export function apply(ctx: Context, config: RighthandConfig = {}): void {
   ctx.plugin(taskTools)
   ctx.plugin(textTools)
   ctx.plugin(weatherTools)
+  ctx.plugin(placesTools)
   ctx.plugin(filesTools)
   ctx.plugin(eventsTools)
   ctx.plugin(notifyTools)
@@ -75,16 +78,18 @@ export function apply(ctx: Context, config: RighthandConfig = {}): void {
 }
 
 // Individual modules stay importable for selective mounting.
-export { storeTools, secretsTools, execTools, taskTools, textTools, weatherTools, filesTools, eventsTools, notifyTools, guardTools, righthandSkills }
+export { storeTools, secretsTools, execTools, taskTools, textTools, weatherTools, placesTools, filesTools, eventsTools, notifyTools, guardTools, righthandSkills }
 export { SKILL_NAME, SKILL_DESCRIPTION, skillDirectory, skillBody } from './skills.ts'
 export type { GuardRule } from './guard-tools.ts'
 export { guardFactsFor } from './guard-tools.ts'
 export type { GuardFacts } from './guard-tools.ts'
 export { isBlockedIP, guardedFetch, normalizeForecast, normalizeAir } from './weather-tools.ts'
+export { normalizePlace, normalizePlaces, normalizeElevation, distanceKm, nearbyViewbox } from './places-tools.ts'
 export { createR2Client, R2_ACCESS_KEY_REF, R2_SECRET_KEY_REF } from './files-tools.ts'
 export { signRequest, presignGet } from './sigv4.ts'
 export { freeSlots } from './events-tools.ts'
 export type { Event } from './events-tools.ts'
 export type { R2Options, ListEntry } from './files-tools.ts'
 export type { WeatherConfig, ForecastOut, AirOut } from './weather-tools.ts'
+export type { PlacesConfig, PlaceOut, ElevationOut } from './places-tools.ts'
 

package/src/places-tools.ts

@@ -0,0 +1,227 @@
+/**
+ * places-tools - the second keyless data-adapter family (after weather).
+ * Geocoding, reverse geocoding and nearby search over Nominatim
+ * (OpenStreetMap, keyless), elevation over Open-Meteo (keyless).
+ *
+ * Every request goes through guardedFetch (the SSRF checklist from
+ * blueprint/data-adapter); Nominatim requests carry a User-Agent per its
+ * usage policy (max 1 req/s - agent-paced calls only).
+ * @module dsh-righthand/places-tools
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { guardedFetch } from './weather-tools.ts'
+
+export const name = 'righthand-places'
+export const inject = ['tools']
+
+export interface PlacesConfig {
+  /** Nominatim endpoint; default https://nominatim.openstreetmap.org (keyless). */
+  nominatimUrl?: string
+  /** Open-Meteo elevation endpoint; default https://api.open-meteo.com/v1/elevation (keyless). */
+  elevationUrl?: string
+  /** User-Agent sent with Nominatim requests (its usage policy requires one). */
+  userAgent?: string
+}
+
+const DEFAULTS: Required<PlacesConfig> = {
+  nominatimUrl: 'https://nominatim.openstreetmap.org',
+  elevationUrl: 'https://api.open-meteo.com/v1/elevation',
+  userAgent: 'dsh-righthand (agent data adapter)',
+}
+
+/** The stable place shape callers see - the wire JSON is Nominatim's. */
+export interface PlaceOut {
+  name: string
+  lat: number
+  lon: number
+  displayName: string
+  category: string
+  type: string
+  address: Record<string, string>
+}
+
+/** Normalize one Nominatim result (search or reverse) to PlaceOut. */
+export function normalizePlace(raw: any): PlaceOut {
+  const address: Record<string, string> = {}
+  if (raw !== null && typeof raw === 'object' && raw.address !== null && typeof raw.address === 'object') {
+    for (const [k, v] of Object.entries(raw.address)) {
+      if (typeof v === 'string') address[k] = v
+    }
+  }
+  return {
+    name: typeof raw.name === 'string' ? raw.name : '',
+    lat: Number(raw.lat ?? 0),
+    lon: Number(raw.lon ?? 0),
+    displayName: typeof raw.display_name === 'string' ? raw.display_name : '',
+    category: typeof raw.category === 'string' ? raw.category : '',
+    type: typeof raw.type === 'string' ? raw.type : '',
+    address,
+  }
+}
+
+export function normalizePlaces(raw: any): PlaceOut[] {
+  if (!Array.isArray(raw)) return []
+  return raw.map(normalizePlace)
+}
+
+/** Normalize the Open-Meteo elevation response { elevation: [8.0] }. */
+export interface ElevationOut {
+  elevation: number
+}
+
+export function normalizeElevation(raw: any): ElevationOut {
+  const arr = Array.isArray(raw.elevation) ? raw.elevation : []
+  return { elevation: Number(arr[0] ?? 0) }
+}
+
+/** Haversine distance in km between two lat/lon pairs. */
+export function distanceKm(lat1: number, lon1: number, lat2: number, lon2: number): number {
+  const rad = Math.PI / 180
+  const dLat = (lat2 - lat1) * rad
+  const dLon = (lon2 - lon1) * rad
+  const sLat = Math.sin(dLat / 2)
+  const sLon = Math.sin(dLon / 2)
+  const a = sLat * sLat + Math.cos(lat1 * rad) * Math.cos(lat2 * rad) * sLon * sLon
+  return 6371 * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
+}
+
+/**
+ * The Nominatim viewbox for a radius around a point, as
+ * left,top,right,bottom (lon,lat pairs) - the order the API expects.
+ */
+export function nearbyViewbox(latitude: number, longitude: number, radiusKm: number): string {
+  const dy = radiusKm / 110.57
+  const cos = Math.cos(latitude * Math.PI / 180)
+  const dx = radiusKm / (111.32 * (cos === 0 ? 1 : cos))
+  const left = longitude - dx
+  const top = latitude + dy
+  const right = longitude + dx
+  const bottom = latitude - dy
+  return [left, top, right, bottom].map(v => v.toFixed(6)).join(',')
+}
+
+export function apply(ctx: Context, config: PlacesConfig = {}): void {
+  const cfg: Required<PlacesConfig> = { ...DEFAULTS, ...config }
+
+  const nomHeaders = { 'User-Agent': cfg.userAgent }
+
+  ctx.tools.register(defineTool({
+    name: 'rh_places_geocode',
+    description: 'Geocode a place query with Nominatim (OpenStreetMap, keyless): text in, ranked places out. Covers search too. Respects the 1 req/s public usage policy - agent-paced calls only.',
+    parameters: {
+      query: { type: 'string', required: true, description: 'Free-text place query, e.g. "big ben london" or "Eiffel Tower".' },
+      limit: { type: 'integer', description: 'Max results, default 5 (max 20).' },
+    },
+    output: {
+      schema: { type: 'array', items: { type: 'json' } },
+      render: (_args, value) => {
+        const arr = value as any[]
+        const text = arr.length === 0 ? '(no places found)' : arr.length + ' place(s): ' + arr.map(p => p.name !== '' ? p.name : p.displayName).join('; ')
+        return [{ type: 'text', text }]
+      },
+    },
+    async execute(args) {
+      const limit = Math.min(Math.max(1, Math.round(args.limit ?? 5)), 20)
+      const qs = new URLSearchParams({ q: args.query, format: 'jsonv2', addressdetails: '1', limit: String(limit) })
+      const body = await guardedFetch(cfg.nominatimUrl + '/search?' + qs.toString(), { init: { headers: nomHeaders } })
+      return normalizePlaces(JSON.parse(body)) as any[]
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_places_address',
+    description: 'Reverse geocode a lat/lon with Nominatim (OpenStreetMap, keyless): coordinates in, the closest address out.',
+    parameters: {
+      latitude: { type: 'number', required: true, description: 'Latitude.' },
+      longitude: { type: 'number', required: true, description: 'Longitude.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          name: { type: 'string', required: true },
+          lat: { type: 'number', required: true },
+          lon: { type: 'number', required: true },
+          displayName: { type: 'string', required: true },
+          category: { type: 'string', required: true },
+          type: { type: 'string', required: true },
+          address: { type: 'json', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.displayName }],
+    },
+    async execute(args) {
+      const qs = new URLSearchParams({ lat: String(args.latitude), lon: String(args.longitude), format: 'jsonv2', addressdetails: '1' })
+      const body = await guardedFetch(cfg.nominatimUrl + '/reverse?' + qs.toString(), { init: { headers: nomHeaders } })
+      const raw = JSON.parse(body)
+      if (raw.error) throw new Error('Nominatim: ' + raw.error)
+      return normalizePlace(raw) as any
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_places_elevation',
+    description: 'Elevation at a lat/lon from Open-Meteo (keyless), in metres.',
+    parameters: {
+      latitude: { type: 'number', required: true, description: 'Latitude.' },
+      longitude: { type: 'number', required: true, description: 'Longitude.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          latitude: { type: 'number', required: true },
+          longitude: { type: 'number', required: true },
+          elevation: { type: 'number', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.elevation + ' m' }],
+    },
+    async execute(args) {
+      const qs = new URLSearchParams({ latitude: String(args.latitude), longitude: String(args.longitude) })
+      const body = await guardedFetch(cfg.elevationUrl + '?' + qs.toString())
+      const out = normalizeElevation(JSON.parse(body))
+      return { latitude: args.latitude, longitude: args.longitude, elevation: out.elevation }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_places_nearby',
+    description: 'Places matching a query within radiusKm of a point (Nominatim bounded search, keyless): results sorted nearest first with distanceKm attached.',
+    parameters: {
+      query: { type: 'string', required: true, description: 'What to look for, e.g. "cafe" or "pharmacy".' },
+      latitude: { type: 'number', required: true, description: 'Centre latitude.' },
+      longitude: { type: 'number', required: true, description: 'Centre longitude.' },
+      radiusKm: { type: 'number', description: 'Search radius, default 1 (min 0.1, max 20).' },
+      limit: { type: 'integer', description: 'Max results, default 5 (max 20).' },
+    },
+    output: {
+      schema: { type: 'array', items: { type: 'json' } },
+      render: (_args, value) => {
+        const arr = value as any[]
+        const text = arr.length === 0 ? '(no nearby places)' : arr.map((p: any) => (p.name !== '' ? p.name : p.displayName) + ' (' + p.distanceKm.toFixed(1) + ' km)').join('; ')
+        return [{ type: 'text', text }]
+      },
+    },
+    async execute(args) {
+      const radius = Math.min(Math.max(0.1, Number(args.radiusKm ?? 1)), 20)
+      const limit = Math.min(Math.max(1, Math.round(args.limit ?? 5)), 20)
+      const qs = new URLSearchParams({
+        q: args.query,
+        viewbox: nearbyViewbox(args.latitude, args.longitude, radius),
+        bounded: '1',
+        format: 'jsonv2',
+        addressdetails: '1',
+        limit: String(limit),
+      })
+      const body = await guardedFetch(cfg.nominatimUrl + '/search?' + qs.toString(), { init: { headers: nomHeaders } })
+      return normalizePlaces(JSON.parse(body))
+        .map(p => ({ ...p, distanceKm: distanceKm(args.latitude, args.longitude, p.lat, p.lon) }))
+        .sort((a, b) => a.distanceKm - b.distanceKm) as any[]
+    },
+  }))
+}