@try-works/dsh-righthand 0.1.7 → 0.1.9

package/src/events-tools.ts

@@ -0,0 +1,241 @@
+/**
+ * events-tools — rh_events_* over ctx.storageDomain.
+ * Reminders and the free-slot query. The agent IS the scheduler:
+ * rh_events_due is the check the agent runs each turn — an event whose
+ * time has come is returned once (pending → notified), so a missed run
+ * cannot go quiet without a record. Repeating events are one-off here;
+ * a real scheduler is the documented Cloudflare cron escalation.
+ * @module dsh-righthand/events-tools
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+import type { Domain } from '@deepseek-ai/dsh-storage-domain'
+import { z } from 'zod'
+
+export const name = 'righthand-events'
+export const inject = ['tools', 'storageDomain']
+
+export interface Event {
+  id: string
+  title: string
+  detail: string
+  at: string
+  state: 'pending' | 'notified' | 'cancelled',
+  createdAt: string
+}
+
+export const eventsDomain = defineDomain({
+  name: 'righthand_events',
+  version: 1,
+  tables: {
+    events: domainTable(z.object({
+      id: z.string(),
+      title: z.string(),
+      detail: z.string(),
+      at: z.string(),
+      state: z.enum(['pending', 'notified', 'cancelled']),
+      createdAt: z.string(),
+    })),
+  },
+})
+
+export type EventsDomain = Domain<typeof eventsDomain>
+
+function newId(): string {
+  return 'e-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 6)
+}
+
+/**
+ * Free slots: gaps of at least durationMinutes between pending events at or
+ * after now, within working hours 09:00–17:00, over the next horizonHours.
+ * Pure and exported for tests.
+ */
+export function freeSlots(events: readonly Event[], now: Date, durationMinutes: number, horizonHours = 24): string[] {
+  const horizonEnd = now.getTime() + horizonHours * 3600000
+  const busy = events
+    .filter(e => e.state === 'pending')
+    .map(e => new Date(e.at).getTime())
+    .filter(t => Number.isFinite(t) && t >= now.getTime() && t <= horizonEnd)
+    .sort((a, b) => a - b)
+  const slots: string[] = []
+  let cursor = now.getTime()
+  const dayStart = (t: number): number => {
+    const d = new Date(t)
+    d.setHours(9, 0, 0, 0)
+    return d.getTime()
+  }
+  const dayEnd = (t: number): number => {
+    const d = new Date(t)
+    d.setHours(17, 0, 0, 0)
+    return d.getTime()
+  }
+  const need = durationMinutes * 60000
+  for (const b of busy) {
+    let from = Math.max(cursor, dayStart(cursor))
+    if (from < b && b - from >= need && from + need <= dayEnd(from) && from + need <= horizonEnd) {
+      slots.push(new Date(from).toISOString())
+    }
+    cursor = Math.max(b, dayEnd(cursor) + 1)
+    if (cursor > horizonEnd) break
+  }
+  return slots
+}
+
+export function apply(ctx: Context): void {
+  let domain: EventsDomain | undefined
+  let ready: Promise<void> | undefined
+
+  ctx.effect(() => {
+    ready = (async () => {
+      domain = await ctx.storageDomain.open(eventsDomain)
+    })()
+    return () => { /* domain facility owns the domain */ }
+  })
+
+  const ensure = async (): Promise<EventsDomain> => {
+    if (domain === undefined) { await ready; }
+    if (domain === undefined) throw new Error('righthand events are not open (storageDomain not mounted)')
+    return domain
+  }
+
+  const all = async (): Promise<Event[]> => {
+    const d = await ensure()
+    return [...d.table('events').entries()].map(([, e]) => e)
+  }
+
+  ctx.tools.register(defineTool({
+    name: 'rh_events_create',
+    description: 'Schedule a reminder at an ISO datetime. One-off: the agent checks rh_events_due each turn and the event is delivered exactly once (pending to notified), so a missed run is never silently dropped.',
+    parameters: {
+      title: { type: 'string', required: true, description: 'What to be reminded of.' },
+      at: { type: 'string', required: true, description: 'ISO datetime when it is due, e.g. 2026-08-31T09:00:00Z.' },
+      detail: { type: 'string', description: 'Optional longer note.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          id: { type: 'string', required: true },
+          title: { type: 'string', required: true },
+          at: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: 'event ' + value.id + ': ' + value.title + ' at ' + value.at }],
+    },
+    async execute(args) {
+      const d = await ensure()
+      const at = new Date(args.at)
+      if (Number.isNaN(at.getTime())) throw new Error('at must be a valid ISO datetime')
+      const event: Event = {
+        id: newId(),
+        title: args.title.trim(),
+        detail: args.detail ?? '',
+        at: at.toISOString(),
+        state: 'pending',
+        createdAt: new Date().toISOString(),
+      }
+      if (event.title === '') throw new Error('an event needs a title')
+      await d.table('events').put(event.id, event)
+      return { id: event.id, title: event.title, at: event.at }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_events_due',
+    description: 'The pending events whose time has come (at <= now). Each is delivered exactly once: returned events are marked notified. This is the check to run every turn — the agent is the scheduler.',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          due: { type: 'array', required: true, items: { type: 'json' } },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.due.length === 0 ? '(nothing due)' : value.due.map((e: any) => e.title + ' at ' + e.at).join(' / ') }],
+    },
+    async execute() {
+      const d = await ensure()
+      const now = Date.now()
+      const due: Event[] = []
+      for (const e of [...d.table('events').entries()].map(([, v]) => v)) {
+        if (e.state === 'pending' && new Date(e.at).getTime() <= now) {
+          const notified: Event = { ...e, state: 'notified' }
+          await d.table('events').put(e.id, notified)
+          due.push(notified)
+        }
+      }
+      due.sort((a, b) => a.at.localeCompare(b.at))
+      return { due: due.map(e => ({ id: e.id, title: e.title, detail: e.detail, at: e.at })) as any[] }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_events_list',
+    description: 'List events: upcoming pending ones first, then notified and cancelled.',
+    parameters: {
+      state: { type: 'string', description: 'Filter: pending | notified | cancelled. Omit for all.' },
+    },
+    output: {
+      schema: { type: 'array', items: { type: 'json' } },
+      render: (_args, value) => [{ type: 'text', text: value.length === 0 ? '(no events)' : (value as any[]).map((e: any) => e.at + ' ' + e.title + ' [' + e.state + ']').join(' / ') }],
+    },
+    async execute(args) {
+      const events = await all()
+      const wanted = args.state ?? null
+      const filtered = wanted ? events.filter(e => e.state === wanted) : events
+      const rank = { pending: 0, notified: 1, cancelled: 2 } as Record<string, number>
+      filtered.sort((a, b) => (rank[a.state] - rank[b.state]) || a.at.localeCompare(b.at))
+      return filtered.map(e => ({ id: e.id, title: e.title, detail: e.detail, at: e.at, state: e.state })) as any[]
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_events_free',
+    description: 'When is there nothing booked: the next free slots of at least durationMinutes within working hours (09:00-17:00) over the next horizonHours.',
+    parameters: {
+      durationMinutes: { type: 'integer', required: true, description: 'How long the free block must be.' },
+      horizonHours: { type: 'integer', description: 'How far ahead to look (default 24).' },
+    },
+    output: {
+      schema: { type: 'array', items: { type: 'string' } },
+      render: (_args, value) => [{ type: 'text', text: value.length === 0 ? '(no free slot)' : (value as string[]).join(' / ') }],
+    },
+    async execute(args) {
+      const events = await all()
+      return freeSlots(events, new Date(), args.durationMinutes, args.horizonHours ?? 24)
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_events_cancel',
+    description: 'Cancel an event by id. Returns whether it existed. Cancelled events stay in the record — a cancellation is news too.',
+    parameters: {
+      id: { type: 'string', required: true, description: 'The event id.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          id: { type: 'string', required: true },
+          existed: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: 'cancelled ' + value.id + ': ' + value.existed }],
+    },
+    async execute(args) {
+      const d = await ensure()
+      const e = d.table('events').get(args.id)
+      if (e === undefined) return { id: args.id, existed: false }
+      await d.table('events').put(args.id, { ...e, state: 'cancelled' })
+      return { id: args.id, existed: true }
+    },
+  }))
+}
+
+
+

package/src/index.ts

@@ -8,8 +8,10 @@
  * The package's plugin entry (name/inject/apply) mounts the tool families
  * 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 other
- * seven tools instead of failing the boot.
+ * profile without `storageDomain` (e.g. headless) simply gets the
+ * 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
@@ -17,7 +19,10 @@
  * - 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)
  * - exec-tools:      rh_run / rh_run_bg over ctx.subprocess + ctx.jobs
  * - guard-tools:     tools/pre-execute policy (config.rules)
  * - skills:          the packaged dsh-righthand skill (ctx.skills)
@@ -33,7 +38,10 @@ 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'
 import * as righthandSkills from './skills.ts'
 import type { GuardRule } from './guard-tools.ts'
 
@@ -61,20 +69,27 @@ 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)
   ctx.plugin(guardTools, { rules: config.rules ?? [] })
   ctx.plugin(righthandSkills)
 }
 
 // Individual modules stay importable for selective mounting.
-export { storeTools, secretsTools, execTools, taskTools, textTools, weatherTools, filesTools, 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/notify-tools.ts

@@ -0,0 +1,62 @@
+/**
+ * notify-tools — rh_notify_send over ntfy.sh (keyless).
+ * Interrupt yourself on your own devices: publish to a topic; any phone
+ * subscribed to that topic gets it. The topic name is the only secret —
+ * choose one nobody can guess, like the digest of a random string.
+ * @module dsh-righthand/notify-tools
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { guardedFetch } from './weather-tools.ts'
+
+export const name = 'righthand-notify'
+export const inject = ['tools', 'settings']
+
+export interface NotifyConfig {
+  /** ntfy server base URL; default https://ntfy.sh (keyless publish). */
+  baseUrl?: string
+  /** Topic to publish to; defaults to the righthand settings defaultNotifyTopic. */
+  topic?: string
+}
+
+export function apply(ctx: Context, config: NotifyConfig = {}): void {
+  const ns = settingsNamespace('righthand')
+  const baseUrl = config.baseUrl ?? 'https://ntfy.sh'
+
+  ctx.tools.register(defineTool({
+    name: 'rh_notify_send',
+    description: 'Interrupt yourself on your own devices: publish a notification to a ntfy.sh topic (keyless). Any device subscribed to that topic receives it. The topic name is the only secret — use an unguessable one. Defaults: priority 1 and auto-delete after 24h.',
+    parameters: {
+      message: { type: 'string', required: true, description: 'The notification body.' },
+      title: { type: 'string', description: 'Notification title.' },
+      topic: { type: 'string', description: 'Topic to publish to; defaults to the settings defaultNotifyTopic.' },
+      priority: { type: 'integer', description: '1 (low/default) to 5 (urgent). Default 1.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          topic: { type: 'string', required: true },
+          sent: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: 'notified ' + value.topic }],
+    },
+    async execute(args) {
+      const settings = ctx.settings.get(ns) as { defaultNotifyTopic?: string } | undefined
+      const topic = args.topic ?? config.topic ?? settings?.defaultNotifyTopic ?? ''
+      if (topic === '') throw new Error('notify topic is not set (arg, plugin config, or settings defaultNotifyTopic)')
+      const priority = Math.min(Math.max(args.priority ?? 1, 1), 5)
+      const headers: Record<string, string> = { 'Priority': String(priority), 'X-TTL': '24h' }
+      if (args.title !== undefined) headers['Title'] = args.title
+      await guardedFetch(baseUrl + '/' + encodeURIComponent(topic), {
+        init: { method: 'POST', body: args.message, headers },
+      })
+      return { topic, sent: true }
+    },
+  }))
+}
+

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[]
+    },
+  }))
+}

package/src/secrets-tools.ts

@@ -28,6 +28,7 @@ export const righthandSettingsSchema = z.object({
   defaultScriptPrefix: z.string().default('rh-'),
   defaultZone: z.string().default(''),
   defaultR2Bucket: z.string().default(''),
+  defaultNotifyTopic: z.string().default(''),
 })
 
 /** Register the settings namespace + the secret/credential tools. */
@@ -120,7 +121,7 @@ export function apply(ctx: Context): void {
     },
     async execute() {
       const v = scope.get()
-      return { accountId: v.accountId, defaultScriptPrefix: v.defaultScriptPrefix, defaultZone: v.defaultZone, defaultR2Bucket: v.defaultR2Bucket }
+      return { accountId: v.accountId, defaultScriptPrefix: v.defaultScriptPrefix, defaultZone: v.defaultZone, defaultR2Bucket: v.defaultR2Bucket, defaultNotifyTopic: v.defaultNotifyTopic }
     },
   }))
 

package/src/weather-tools.ts

@@ -65,9 +65,15 @@ export function isBlockedIP(ip: string): boolean {
  * Fetch one URL with the SSRF checklist. `fetchImpl` and `resolve` are
  * injectable for tests; production uses the globals.
  */
+export interface GuardedFetchInit {
+  method?: string
+  body?: string
+  headers?: Record<string, string>
+}
+
 export async function guardedFetch(
   url: string,
-  deps: { fetchImpl?: typeof fetch; resolve?: (host: string) => Promise<string[]> } = {},
+  deps: { fetchImpl?: typeof fetch; resolve?: (host: string) => Promise<string[]>; init?: GuardedFetchInit } = {},
 ): Promise<string> {
   const fetchImpl = deps.fetchImpl ?? fetch
   const resolve = deps.resolve ?? (async (host: string) => (await lookup(host, { all: true })).map(a => a.address))
@@ -78,7 +84,7 @@ export async function guardedFetch(
     if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') throw new Error('blocked: non-http(s) URL')
     const ips = await resolve(parsed.hostname)
     if (ips.length === 0 || ips.some(isBlockedIP)) throw new Error('blocked: destination is not a public host')
-    const res = await fetchImpl(current, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), redirect: 'manual' })
+    const res = await fetchImpl(current, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), redirect: 'manual', method: deps.init?.method ?? 'GET', body: deps.init?.body, headers: deps.init?.headers })
     if (res.status >= 300 && res.status < 400) {
       const next = res.headers.get('location')
       if (next === null) throw new Error('blocked: redirect without location')