@try-works/dsh-righthand 0.1.6 → 0.1.8

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/files-tools.ts

@@ -0,0 +1,294 @@
+/**
+ * files-tools — rh_files_* over Cloudflare R2 (the user's own account).
+ * The first family on an actual Cloudflare primitive. S3-compatible API,
+ * signed with SigV4 (src/sigv4.ts, pinned to the AWS test vector).
+ *
+ * Credentials resolve at call time from the credential provider
+ * (R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY); accountId and bucket come
+ * from the righthand settings namespace. The client is a pure factory so
+ * tests drive it with a stubbed fetch.
+ * @module dsh-righthand/files-tools
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { signRequest, presignGet } from './sigv4.ts'
+
+export const name = 'righthand-files'
+export const inject = ['tools', 'credentials', 'settings']
+
+export const R2_ACCESS_KEY_REF = 'R2_ACCESS_KEY_ID'
+export const R2_SECRET_KEY_REF = 'R2_SECRET_ACCESS_KEY'
+
+export interface FilesConfig {
+  /** Bucket name; defaults to the righthand settings defaultR2Bucket. */
+  bucket?: string
+}
+
+export interface R2Options {
+  accountId: string
+  accessKeyId: string
+  secretAccessKey: string
+  bucket: string
+  fetchImpl?: typeof fetch
+  now?: () => Date
+}
+
+function amzDate(d: Date): string {
+  return d.toISOString().replace(/[:-]|\.\d{3}/g, '')
+}
+
+export interface ListEntry {
+  key: string
+  size: number
+  lastModified: string
+}
+
+/** Minimal ListObjectsV2 XML parse: Key / Size / LastModified triples. */
+function parseListXml(xml: string): ListEntry[] {
+  const out: ListEntry[] = []
+  const contents = xml.split('<Contents>').slice(1)
+  for (const block of contents) {
+    const grab = (tag: string): string => {
+      const a = block.indexOf('<' + tag + '>')
+      const b = block.indexOf('</' + tag + '>')
+      return a < 0 || b < 0 ? '' : block.slice(a + tag.length + 2, b)
+    }
+    const key = grab('Key')
+    if (key === '') continue
+    out.push({ key, size: Number(grab('Size') ?? 0), lastModified: grab('LastModified') })
+  }
+  return out
+}
+
+/**
+ * The R2 client factory. Pure over its options; every call signs fresh.
+ */
+export function createR2Client(opts: R2Options) {
+  const fetchImpl = opts.fetchImpl ?? fetch
+  const now = opts.now ?? (() => new Date())
+  const base = 'https://' + opts.accountId + '.r2.cloudflarestorage.com/' + opts.bucket
+
+  async function request(method: string, key: string, payload: string, extraHeaders: Record<string, string> = {}): Promise<Response> {
+    const url = base + '/' + key
+    const parsed = new URL(url)
+    const signed = signRequest({
+      method,
+      url,
+      headers: { host: parsed.host, ...extraHeaders },
+      payload,
+      accessKeyId: opts.accessKeyId,
+      secretAccessKey: opts.secretAccessKey,
+      region: 'auto',
+      amzDate: amzDate(now()),
+    })
+    return fetchImpl(url, { method, headers: signed.headers, body: payload === '' ? undefined : payload })
+  }
+
+  return {
+    async put(key: string, content: string, contentType?: string): Promise<{ key: string; size: number }> {
+      const res = await request('PUT', key, content, contentType ? { 'content-type': contentType } : {})
+      if (!res.ok) throw new Error('R2 PUT failed: HTTP ' + res.status)
+      return { key, size: Buffer.byteLength(content) }
+    },
+
+    async get(key: string): Promise<{ found: boolean; content: string; contentType: string }> {
+      const res = await request('GET', key, '')
+      if (res.status === 404) return { found: false, content: '', contentType: '' }
+      if (!res.ok) throw new Error('R2 GET failed: HTTP ' + res.status)
+      return { found: true, content: await res.text(), contentType: res.headers.get('content-type') ?? '' }
+    },
+
+    async list(prefix?: string, maxKeys?: number): Promise<ListEntry[]> {
+      const q = '?list-type=2' + (prefix ? '&prefix=' + encodeURIComponent(prefix) : '') + (maxKeys ? '&max-keys=' + maxKeys : '')
+      const url = base + '/' + q
+      const parsed = new URL(url)
+      const signed = signRequest({
+        method: 'GET',
+        url,
+        headers: { host: parsed.host },
+        payload: '',
+        accessKeyId: opts.accessKeyId,
+        secretAccessKey: opts.secretAccessKey,
+        region: 'auto',
+        amzDate: amzDate(now()),
+      })
+      const res = await fetchImpl(url, { method: 'GET', headers: signed.headers })
+      if (!res.ok) throw new Error('R2 list failed: HTTP ' + res.status)
+      return parseListXml(await res.text())
+    },
+
+    share(key: string, expiresSeconds: number): string {
+      return presignGet({
+        url: base + '/' + key,
+        accessKeyId: opts.accessKeyId,
+        secretAccessKey: opts.secretAccessKey,
+        region: 'auto',
+        amzDate: amzDate(now()),
+        expiresSeconds,
+      })
+    },
+
+    async delete(key: string): Promise<{ key: string; existed: boolean }> {
+      const res = await request('DELETE', key, '')
+      if (res.status === 404) return { key, existed: false }
+      if (!res.ok) throw new Error('R2 DELETE failed: HTTP ' + res.status)
+      return { key, existed: true }
+    },
+  }
+}
+
+
+export function apply(ctx: Context, config: FilesConfig = {}): void {
+  const ns = settingsNamespace('righthand')
+
+  /** Resolve accountId + credentials + bucket at call time. */
+  async function client(): Promise<ReturnType<typeof createR2Client>> {
+    const settings = ctx.settings.get(ns) as { accountId?: string; defaultR2Bucket?: string } | undefined
+    const accountId = settings?.accountId ?? ''
+    if (accountId === '') throw new Error('righthand accountId is not set (rh_settings_set { accountId })')
+    const bucket = config.bucket ?? settings?.defaultR2Bucket ?? ''
+    if (bucket === '') throw new Error('R2 bucket is not set (plugin config bucket or settings defaultR2Bucket)')
+    const access = await ctx.credentials.resolve(credentialRef(R2_ACCESS_KEY_REF))
+    const secret = await ctx.credentials.resolve(credentialRef(R2_SECRET_KEY_REF))
+    if (access === undefined || secret === undefined) {
+      throw new Error('R2 credentials are not set (rh_credential_set R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY)')
+    }
+    return createR2Client({ accountId, accessKeyId: access.value, secretAccessKey: secret.value, bucket })
+  }
+
+  ctx.tools.register(defineTool({
+    name: 'rh_files_put',
+    description: 'Store a file in the R2 bucket and return its key. Content is text (reports, CSV, transcripts, code); content type defaults to text/plain.',
+    parameters: {
+      key: { type: 'string', required: true, description: 'Object key, e.g. reports/2026-08-30.csv.' },
+      content: { type: 'string', required: true, description: 'The full text content to store.' },
+      contentType: { type: 'string', description: 'Content type, e.g. text/csv. Defaults to text/plain.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          key: { type: 'string', required: true },
+          size: { type: 'integer', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: 'stored ' + value.key + ' (' + value.size + ' bytes)' }],
+    },
+    async execute(args) {
+      const c = await client()
+      return c.put(args.key, args.content, args.contentType)
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_files_get',
+    description: 'Read a stored file back by its key. found: false means the key is absent, not an error.',
+    parameters: {
+      key: { type: 'string', required: true, description: 'The object key to read.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          found: { type: 'boolean', required: true },
+          key: { type: 'string', required: true },
+          content: { type: 'string' },
+          contentType: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.found && typeof value.content === 'string' ? value.content : '(absent)' }],
+    },
+    async execute(args) {
+      const c = await client()
+      const out = await c.get(args.key)
+      return {
+        key: args.key,
+        found: out.found,
+        ...out.found ? { content: out.content, contentType: out.contentType } : {},
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_files_list',
+    description: 'List objects in the bucket, optionally by key prefix. Newest first is not guaranteed by S3; entries carry lastModified.',
+    parameters: {
+      prefix: { type: 'string', description: 'Only keys starting with this, e.g. reports/.' },
+      maxKeys: { type: 'integer', description: 'Max entries (default 100).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          entries: { type: 'array', required: true, items: { type: 'json' } },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.entries.length + ' objects' }],
+    },
+    async execute(args) {
+      const c = await client()
+      const entries = await c.list(args.prefix, args.maxKeys)
+      return { entries: entries as any[] }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_files_share',
+    description: 'Get a presigned download URL for a key, valid for the given minutes (default 60, max 10080). Anyone with the URL can read the object for that window.',
+    parameters: {
+      key: { type: 'string', required: true, description: 'The object key to share.' },
+      minutes: { type: 'integer', description: 'Validity in minutes (default 60, max 10080 = 7 days).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          key: { type: 'string', required: true },
+          url: { type: 'string', required: true },
+          expiresAt: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.url }],
+    },
+    async execute(args) {
+      const minutes = Math.min(Math.max(args.minutes ?? 60, 1), 10080)
+      const c = await client()
+      const url = c.share(args.key, minutes * 60)
+      return { key: args.key, url, expiresAt: new Date(Date.now() + minutes * 60000).toISOString() }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_files_delete',
+    description: 'Delete an object by key. Returns whether it existed.',
+    parameters: {
+      key: { type: 'string', required: true, description: 'The object key to delete.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          key: { type: 'string', required: true },
+          existed: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: 'deleted ' + value.key + ': ' + value.existed }],
+    },
+    async execute(args) {
+      const c = await client()
+      return c.delete(args.key)
+    },
+  }))
+}
+
+
+
+

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 nineteen tools
+ * (secrets, settings, exec, text, weather, 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,6 +19,9 @@
  * - 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)
+ * - 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)
@@ -32,6 +37,9 @@ 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 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'
 
@@ -59,16 +67,24 @@ export function apply(ctx: Context, config: RighthandConfig = {}): void {
   ctx.plugin(taskTools)
   ctx.plugin(textTools)
   ctx.plugin(weatherTools)
+  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, guardTools, righthandSkills }
+export { storeTools, secretsTools, execTools, taskTools, textTools, weatherTools, 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 { 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'
 

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/secrets-tools.ts

@@ -27,6 +27,8 @@ export const righthandSettingsSchema = z.object({
   accountId: z.string().default(''),
   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. */
@@ -119,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 }
+      return { accountId: v.accountId, defaultScriptPrefix: v.defaultScriptPrefix, defaultZone: v.defaultZone, defaultR2Bucket: v.defaultR2Bucket, defaultNotifyTopic: v.defaultNotifyTopic }
     },
   }))