@try-works/dsh-righthand 0.1.6 → 0.1.8

package/README.md

@@ -28,6 +28,9 @@ dsh --profile <profile> --patch ./cordis.patch.yml
 | `rh_task_create` / `rh_task_list` / `rh_task_next` / `rh_task_update` / `rh_task_delete` | tasks | `ctx.storageDomain` (typed `righthand_tasks` domain; state machine open → done/failed) |
 | `rh_text_summarise` / `rh_text_extract` / `rh_text_classify` / `rh_text_translate` | text | `ctx.llm` (one model call per verb) |
 | `rh_weather_forecast` / `rh_weather_air` | weather | Open-Meteo (keyless), every request through the SSRF-guarded fetcher |
+| `rh_files_put` / `rh_files_get` / `rh_files_list` / `rh_files_share` / `rh_files_delete` | files | Cloudflare R2 (S3-compatible, SigV4-signed; credentials from `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY`, bucket from settings) |
+| `rh_events_create` / `rh_events_due` / `rh_events_list` / `rh_events_free` / `rh_events_cancel` | events | `ctx.storageDomain` (typed `righthand_events` domain; the agent is the scheduler — `rh_events_due` runs each turn) |
+| `rh_notify_send` | notify | ntfy.sh (keyless — the topic name is the only secret) |
 | `rh_credential_describe` / `rh_credential_set` / `rh_credential_unset` | secrets | `ctx.credentials` (values never echoed) |
 | `rh_settings_get` / `rh_settings_set` | secrets | `ctx.settings` (namespace `righthand`) |
 | `rh_run` | exec | `ctx.subprocess` (collect mode, bounded output) |
@@ -67,6 +70,8 @@ Namespace "righthand" (registered by the secrets family):
 | `accountId` | "" | Cloudflare account id used by righthand Cloudflare tools |
 | `defaultScriptPrefix` | "rh-" | default name prefix for generated workers/scripts |
 | `defaultZone` | "" | default Cloudflare zone |
+| `defaultR2Bucket` | "" | default R2 bucket for `rh_files_*` |
+| `defaultNotifyTopic` | "" | default ntfy topic for `rh_notify_send` |
 
 `rh_settings_get` returns the resolved values; `rh_settings_set` merges a
 partial patch (persisted by the harness settings provider).
@@ -84,6 +89,7 @@ canonical example of the current DSH-native form (tool-to-tool via
 |---|---|
 | `blueprint/daily-digest` | Collect sources, summarize, send on a schedule — extractive locally, LLM synthesis as escalation |
 | `blueprint/data-adapter` | Wrap one keyless public API as a tool family: guarded fetch, normalize, one tool per query. Worked example ships in the plugin: `rh_weather_*` |
+| (phase 5) `rh_files_*` on R2 | The first family on an actual Cloudflare primitive: S3-compatible API, SigV4 signing pinned to the AWS test vector, credentials from the credential provider |
 | `blueprint/research-radar` | Multi-source research over a rolling window (Reddit, X, YouTube, HN, Polymarket, web): score, dedupe, synthesize with citations |
 | `blueprint/web-scraper` | Fetch a page, extract title/headings/links/text, make it searchable — static HTML first, render/vision as escalation |
 | `blueprint/vision-worker` | Cloudflare Worker exposing kimi-k2.6 vision: route image requests for text-only models, return a versioned `VisionEnvelope` |
@@ -141,10 +147,11 @@ so the agent cannot deploy or destroy without the gate.
 
 ## Service availability
 
-The store and task families need `ctx.storageDomain`, which the web profile
-provides (`storage` + `storage-json` + `storage-domain` rows). In a profile
-without it — e.g. the headless bundle — those nine tools stay dormant and the
-other seven tools still register; the plugin never fails the boot.
+The store, task and events families need `ctx.storageDomain`, which the web
+profile provides (`storage` + `storage-json` + `storage-domain` rows). In a
+profile without it — e.g. the headless bundle — those fourteen tools stay
+dormant and the other nineteen tools (secrets, settings, exec, text, weather,
+files, notify) still register; the plugin never fails the boot.
 
 ## Development
 

package/lib/events-tools.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 type { Domain } from '@deepseek-ai/dsh-storage-domain';
+export declare const name = "righthand-events";
+export declare const inject: string[];
+export interface Event {
+    id: string;
+    title: string;
+    detail: string;
+    at: string;
+    state: 'pending' | 'notified' | 'cancelled';
+    createdAt: string;
+}
+export declare const eventsDomain: {
+    name: string;
+    version: number;
+    tables: {
+        events: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            id: string;
+            title: string;
+            detail: string;
+            at: string;
+            state: "pending" | "notified" | "cancelled";
+            createdAt: string;
+        }>;
+    };
+};
+export type EventsDomain = Domain<typeof eventsDomain>;
+/**
+ * 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 declare function freeSlots(events: readonly Event[], now: Date, durationMinutes: number, horizonHours?: number): string[];
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=events-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events-tools.d.ts","sourceRoot":"","sources":["../src/events-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGlD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAA;AAG7D,eAAO,MAAM,IAAI,qBAAqB,CAAA;AACtC,eAAO,MAAM,MAAM,UAA6B,CAAA;AAEhD,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;CAavB,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,YAAY,CAAC,CAAA;AAMtD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,YAAY,SAAK,GAAG,MAAM,EAAE,CA6BnH;AAED,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAwJxC"}

package/lib/events-tools.js

@@ -0,0 +1,219 @@
+/**
+ * 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 { defineTool } from '@deepseek-ai/dsh-tools';
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+import { z } from 'zod';
+export const name = 'righthand-events';
+export const inject = ['tools', 'storageDomain'];
+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(),
+        })),
+    },
+});
+function newId() {
+    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, now, durationMinutes, horizonHours = 24) {
+    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 = [];
+    let cursor = now.getTime();
+    const dayStart = (t) => {
+        const d = new Date(t);
+        d.setHours(9, 0, 0, 0);
+        return d.getTime();
+    };
+    const dayEnd = (t) => {
+        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) {
+    let domain;
+    let ready;
+    ctx.effect(() => {
+        ready = (async () => {
+            domain = await ctx.storageDomain.open(eventsDomain);
+        })();
+        return () => { };
+    });
+    const ensure = async () => {
+        if (domain === undefined) {
+            await ready;
+        }
+        if (domain === undefined)
+            throw new Error('righthand events are not open (storageDomain not mounted)');
+        return domain;
+    };
+    const all = async () => {
+        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 = {
+                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) => e.title + ' at ' + e.at).join(' / ') }],
+        },
+        async execute() {
+            const d = await ensure();
+            const now = Date.now();
+            const due = [];
+            for (const e of [...d.table('events').entries()].map(([, v]) => v)) {
+                if (e.state === 'pending' && new Date(e.at).getTime() <= now) {
+                    const notified = { ...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 })) };
+        },
+    }));
+    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.map((e) => 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 };
+            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 }));
+        },
+    }));
+    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.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 };
+        },
+    }));
+}
+//# sourceMappingURL=events-tools.js.map

package/lib/events-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-tools.js","sourceRoot":"","sources":["../src/events-tools.ts"],"names":[],"mappings":"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"}

package/lib/files-tools.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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';
+export declare const name = "righthand-files";
+export declare const inject: string[];
+export declare const R2_ACCESS_KEY_REF = "R2_ACCESS_KEY_ID";
+export declare 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;
+}
+export interface ListEntry {
+    key: string;
+    size: number;
+    lastModified: string;
+}
+/**
+ * The R2 client factory. Pure over its options; every call signs fresh.
+ */
+export declare function createR2Client(opts: R2Options): {
+    put(key: string, content: string, contentType?: string): Promise<{
+        key: string;
+        size: number;
+    }>;
+    get(key: string): Promise<{
+        found: boolean;
+        content: string;
+        contentType: string;
+    }>;
+    list(prefix?: string, maxKeys?: number): Promise<ListEntry[]>;
+    share(key: string, expiresSeconds: number): string;
+    delete(key: string): Promise<{
+        key: string;
+        existed: boolean;
+    }>;
+};
+export declare function apply(ctx: Context, config?: FilesConfig): void;
+//# sourceMappingURL=files-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"files-tools.d.ts","sourceRoot":"","sources":["../src/files-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAMlD,eAAO,MAAM,IAAI,oBAAoB,CAAA;AACrC,eAAO,MAAM,MAAM,UAAuC,CAAA;AAE1D,eAAO,MAAM,iBAAiB,qBAAqB,CAAA;AACnD,eAAO,MAAM,iBAAiB,yBAAyB,CAAA;AAEvD,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,MAAM,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AAMD,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;CACrB;AAmBD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS;aAsB3B,MAAM,WAAW,MAAM,gBAAgB,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;aAMtF,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;kBAOrE,MAAM,YAAY,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;eAmBxD,MAAM,kBAAkB,MAAM,GAAG,MAAM;gBAWhC,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;EAOxE;AAGD,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,WAAgB,GAAG,IAAI,CAkJlE"}

package/lib/files-tools.js

@@ -0,0 +1,259 @@
+/**
+ * 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 { 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.js";
+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';
+function amzDate(d) {
+    return d.toISOString().replace(/[:-]|\.\d{3}/g, '');
+}
+/** Minimal ListObjectsV2 XML parse: Key / Size / LastModified triples. */
+function parseListXml(xml) {
+    const out = [];
+    const contents = xml.split('<Contents>').slice(1);
+    for (const block of contents) {
+        const grab = (tag) => {
+            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) {
+    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, key, payload, extraHeaders = {}) {
+        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, content, contentType) {
+            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) {
+            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, maxKeys) {
+            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, expiresSeconds) {
+            return presignGet({
+                url: base + '/' + key,
+                accessKeyId: opts.accessKeyId,
+                secretAccessKey: opts.secretAccessKey,
+                region: 'auto',
+                amzDate: amzDate(now()),
+                expiresSeconds,
+            });
+        },
+        async delete(key) {
+            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, config = {}) {
+    const ns = settingsNamespace('righthand');
+    /** Resolve accountId + credentials + bucket at call time. */
+    async function client() {
+        const settings = ctx.settings.get(ns);
+        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 };
+        },
+    }));
+    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);
+        },
+    }));
+}
+//# sourceMappingURL=files-tools.js.map