@repogo/plugins 0.1.32 → 0.1.34

package/README.md

@@ -1,8 +1,21 @@
 # @repogo/plugins
 
-Write plugins for a [RepoGo](https://repogo.app) project: small apps on your
-environment with their own SQLite data, that agents call as tools and cards
-draw live on your phone.
+Plugins are small apps that run on your environment, the machine the RepoGo
+host runs on. A plugin keeps its own data, does work with your tools and APIs,
+and is reached two ways: agents call its methods as tools, and cards on your
+phone draw its data live and run its methods when you tap.
+
+- [Quick start](#quick-start)
+- [Where plugins live](#where-plugins-live)
+- [Methods](#methods): queries, mutations, streams
+- [Data](#data): namespaces, collections, kv, streams, buckets
+- [Crons](#crons)
+- [The context](#the-context)
+- [Events](#events)
+- [How cards and agents reach a plugin](#how-cards-and-agents-reach-a-plugin)
+- [Errors and confirmations](#errors-and-confirmations)
+
+## Quick start
 
 ```ts
 // .repogo/plugins/notes/app.ts
@@ -10,21 +23,75 @@ import { definePlugin, method, z } from "@repogo/plugins";
 
 export default definePlugin({
   description: "Notes for this project",
-  db: "myproject.notes",
-  collections: { notes: z.object({ text: z.string() }) },
+  namespace: "myproject.notes",
+  collections: { notes: z.object({ text: z.string(), done: z.boolean().default(false) }) },
   methods: {
-    search: method(z.object({ text: z.string() }), async ({ text }, ctx) =>
-      (await ctx.db.notes.list()).filter((note) => note.text.includes(text)), { kind: "query" }),
+    open: method(z.object({}), async (_, ctx) => ctx.collections.notes.list({ where: { done: false } }), {
+      kind: "query",
+      description: "Notes not done yet, newest first",
+    }),
     clear: method(z.object({}), async (_, ctx) => {
-      for (const note of await ctx.db.notes.list()) await ctx.db.notes.delete(note.id);
+      for (const note of await ctx.collections.notes.list({ limit: 500 })) await ctx.collections.notes.delete(note.id);
+      return null;
     }, { confirm: "Delete every note?" }),
   },
 });
 ```
 
-A `stream` sends items as they happen, for as long as a card shows it. Each
-`yield` is one item; `ctx.signal` aborts when the card goes, so hand it to what
-you start:
+That's a whole plugin. The host loads it on its next look at the folder (within
+a minute; at once when something calls it), and it gets:
+
+- `notes.open` and `notes.clear`, the methods it wrote;
+- `notes.notes.list`, `.get`, `.create`, `.update` and `.delete`, generated for its collection;
+- a `data.db` in `~/.repogo/plugin-data/myproject.notes/`.
+
+Add the package to `.repogo/plugins/package.json` (`bun add @repogo/plugins`) for
+types and editor help. The host runs plugins with its own copy of this package,
+the version it shipped with, so a plugin always matches its host. Plugins run on
+[Bun](https://bun.sh); install it on the environment.
+
+## Where plugins live
+
+| Folder | For | `ctx.root` |
+| --- | --- | --- |
+| `<project>/.repogo/plugins/<name>/app.ts` | One project | The project's checkout |
+| `~/.repogo/plugins/<name>/app.ts` | Every project (Vercel, Gmail, builds) | The project that called it |
+
+A plugin's name is its folder's: lowercase letters, digits and hyphens. A
+project plugin hides an environment one of the same name. Each folder's plugins
+run together in one Worker, so a plugin's blocking code stalls the others in its
+folder: use async APIs.
+
+Pages beside an environment plugin (`pages/*.md`) open from any project as
+`~/.repogo/plugins/<name>/pages/<page>.md`, and `~/.repogo/plugins/tab.json`
+names the tab of a project without its own.
+
+## Methods
+
+```ts
+method(input, run, { kind?, description?, output?, confirm? })
+stream(input, async function* run, { description? })
+```
+
+`input` is a zod schema; the call's input is checked against it and defaults
+filled in before `run` sees it. `run(input, ctx)` returns the result: anything
+JSON can carry.
+
+| Kind | Does | Who runs it |
+| --- | --- | --- |
+| `query` | Only reads; writing throws | Cards on their own, and again whenever data it read changes |
+| `mutation` (the default) | Reads and writes | Only when someone acts: a tap, an agent, a cron, other code |
+| `stream` | Only reads; yields items as they happen | A card while it shows it |
+
+Mark every method that only reads as `kind: "query"`: that's what lets a card
+show it and keep it current. Give each a `description`; agents read it to choose
+a method. `output`, a zod schema of the result, tells agents and cards its
+field names.
+
+A **stream** sends each `yield` to the card as it happens, for as long as the
+card shows it. `ctx.signal` aborts when the card goes, so hand it to what you
+start. Give items an `id`. An agent calling a stream gets what arrives within
+5 seconds, at most 200 items.
 
 ```ts
 tail: stream(z.object({ file: z.string() }), async function* ({ file }, ctx) {
@@ -38,24 +105,258 @@ tail: stream(z.object({ file: z.string() }), async function* ({ file }, ctx) {
 }),
 ```
 
-`db` names the SQLite file the collections live in, `~/.repogo/plugin-data/<db>.db`
-on the environment; left out, it is the plugin's folder name. Name a project's own
-data `<project>.<name>`. A bare name (`todos`) is shared by every plugin that
-names it, in any project, so they must agree on their collections' schemas.
-Data stays in place when the project moves. A plugin without collections has no file.
+## Data
 
-A plugin for every project goes in `~/.repogo/plugins/<name>/app.ts` instead
-of a project's folder: the same shape, run with `ctx.root` set to whichever
-project calls it. A project plugin of the same name takes precedence. Pages
-beside it (`pages/*.md`) are reachable from any project as
-`~/.repogo/plugins/<name>/pages/<page>.md`, and `~/.repogo/plugins/tab.json`
-lists the pages every project's tab shows.
+A plugin declares its data in four kinds, each with a schema, and gets typed
+access in `ctx` and generated methods for agents and cards:
+
+| Kind | Holds | `ctx` | On disk |
+| --- | --- | --- | --- |
+| `collections` | Records: tasks, notes, settings rows | `ctx.collections.<name>` | Rows in `data.db` |
+| `kv` | Keys to values, which may expire | `ctx.kv.<name>` | Rows in `data.db` |
+| `streams` | Append-only lines per key: a run's log, a job's output | `ctx.streams.<name>` | `streams/<name>/<key>/*.jsonl` |
+| `buckets` | Files, each with its meta | `ctx.buckets.<name>` | `buckets/<name>/<id>/` |
+
+Every write is checked against its schema, and every read and write is tracked,
+so a card showing a query refreshes when a write touches what it read: in this
+plugin, another plugin, or another project.
+
+### Namespaces
+
+`namespace` names where a plugin's data lives: the folder
+`~/.repogo/plugin-data/<namespace>/`, holding `data.db` and its streams' and
+buckets' files. Left out, it's the plugin's name. Plugins naming the same
+namespace share its data, in any project, so they must declare the same schemas.
+
+By convention a project's own data is `<project>.<name>` (`myproject.notes`),
+and data meant for every project a bare name (`todos`). That's only a
+convention: the same namespace is the same data. Data stays put when a project
+moves. A plugin with no data has no folder.
+
+### Collections
+
+```ts
+collections: { tasks: z.object({ title: z.string(), status: z.enum(["open", "done"]).default("open") }) }
+```
+
+```ts
+const task = await ctx.collections.tasks.create({ title: "Ship it" }); // { id, title, status, createdAt, updatedAt }
+await ctx.collections.tasks.get(task.id);                                // or null
+await ctx.collections.tasks.update(task.id, { status: "done" });         // only the fields given change
+await ctx.collections.tasks.list({ where: { status: "open" }, orderBy: "updatedAt", order: "desc", limit: 50 });
+await ctx.collections.tasks.delete(task.id);
+```
+
+`list` is newest first by default, at most 100 unless `limit` says (up to 500).
+`where` matches top-level fields exactly; `null` matches a missing one.
+
+### Kv
+
+```ts
+kv: { state: z.object({ step: z.string() }) }
+```
+
+```ts
+await ctx.kv.state.set("run-42", { step: "build" }, { ttl: "1h" }); // ttl: "30s", "5m", "1h", "7d" or ms
+await ctx.kv.state.get("run-42");                                     // { step: "build" }, or null
+await ctx.kv.state.entry("run-42");                                   // { key, value, expiresAt, createdAt, updatedAt }
+await ctx.kv.state.list({ prefix: "run-", limit: 100 });              // entries in key order
+await ctx.kv.state.delete("run-42");
+```
+
+The value's schema may be any zod type, not only an object. A key past its
+`ttl` reads as missing at once; a sweep every few seconds deletes it and
+refreshes cards. Setting a key again without a `ttl` keeps it until deleted.
+
+### Streams
+
+```ts
+streams: {
+  runs: z.object({ level: z.string(), text: z.string() }),
+  audit: { item: z.object({ text: z.string() }), retain: { age: "90d", bytes: 500_000_000 } },
+}
+```
+
+A stream is append-only JSON lines, split by key: one key per workflow run, job
+or day. Each line on disk is `{ offset, at, data }`, in
+`streams/<name>/<key>/<first offset>.jsonl`, a new file each megabyte, so you
+can `tail` and grep them.
+
+```ts
+await ctx.streams.runs.append("run-42", { level: "info", text: "built" }); // { id: "run-42:0", key, offset, at, data }
+await ctx.streams.runs.read("run-42", { from: 0, limit: 100 });
+for await (const line of ctx.streams.runs.follow("run-42", { signal: ctx.signal })) { /* … */ }
+await ctx.streams.runs.end("run-42");   // followers stop; appends fail
+await ctx.streams.runs.keys();          // [{ key, lines, bytes, endedAt, updatedAt }], newest first
+await ctx.streams.runs.delete("run-42");
+```
+
+`follow` replays the last 100 lines (or from `from`, or the last `last`), then
+yields each new one, until the key ends or the signal aborts. Keys are letters,
+digits, dots, dashes and underscores.
+
+A key is kept 7 days after its last line or its end, and past 50 MB its oldest
+files go. `retain` sets `{ age?, bytes? }` per stream, or `"forever"`. Offsets
+are never reused: after a crash between writing a line and recording it, the
+line is cut off before the next append.
+
+### Buckets
+
+```ts
+buckets: { photos: z.object({ caption: z.string().optional(), tags: z.array(z.string()).optional() }) }
+```
+
+A bucket keeps files, one folder per file named by its id, holding the file
+under its own name and its `meta.json`:
+
+```
+buckets/photos/
+  01a14cd8-ad7a-7000-8773-aa8bff079ece/
+    beach.jpg
+    meta.json        {"caption": "Sunset", "folder": "2026"}
+```
+
+The folders are the truth. Anyone may add a file by making a folder with the
+file in it, and change its meta by writing `meta.json`: an agent with its file
+tools, a script, Finder. The host indexes the bucket for `list` and `search` when
+the folder changes, and rescans it each minute. Meta may be missing or `{}`;
+its one reserved field, `folder`, places the file in a folder of the bucket's
+own. Each file reads with a `status`:
+
+| `status` | Meta | `problem` |
+| --- | --- | --- |
+| `ok` | Matches the schema | null |
+| `empty` | None, or `{}` | null |
+| `invalid` | Fails the schema; kept as written | Why |
+| `malformed` | Not a JSON object, or the folder doesn't hold exactly one file | Why |
+
+```ts
+const file = await ctx.buckets.photos.put({ name: "beach.jpg", body: bytes, folder: "2026", meta: { caption: "Sunset" } });
+// { id, name, folder, path, size, type, meta, status, problem, revision, createdAt, updatedAt }
+await ctx.buckets.photos.get(file.id);
+await ctx.buckets.photos.list({ folder: "2026", status: "ok", limit: 100 }); // newest first
+await ctx.buckets.photos.search("sunset trip");                            // name, folder and meta; words as prefixes
+await ctx.buckets.photos.update(file.id, { tags: ["trip"], caption: null }, { revision: file.revision });
+await ctx.buckets.photos.move(file.id, { name: "sunset.jpg", folder: "best" });
+const text = await (await ctx.buckets.photos.file(file.id)).text();          // a BunFile
+await ctx.buckets.photos.delete(file.id);
+```
+
+`body` is a string, bytes or a `Blob` (`Bun.file(path)` copies a file). `path`
+is the file on disk. `update` merges into the meta, `null` removing a field, and
+checks it against the schema; with `revision`, it fails if the file changed
+since you read it. Writes through `ctx` are checked; files written by hand are
+indexed with their `status` instead.
+
+### Generated methods
+
+Every collection, kv, stream and bucket gets methods named
+`<plugin>.<name>.<method>`, so a plugin that only declares data can be read and
+changed by agents and cards with no code of its own:
+
+| Kind | Queries | Mutations | Stream |
+| --- | --- | --- | --- |
+| Collection | `list`, `get` | `create`, `update`, `delete` (asks) | |
+| Kv | `get`, `list` | `set`, `delete` (asks) | |
+| Stream | `read`, `keys` | `append`, `end`, `delete` (asks) | `tail` |
+| Bucket | `list`, `search`, `get` | `put`, `update`, `move`, `delete` (asks) | |
+
+A bucket's `put` takes `text`, or `from`, an absolute path on the environment to
+copy: bytes never travel in a call. A method of your own with the same name as a
+generated one fails the plugin's load.
+
+## Crons
+
+```ts
+export default definePlugin({
+  methods: { watch: method(z.object({}), async (_, ctx) => { /* … */ }) },
+  crons: [
+    { method: "watch", schedule: "*/5 * * * *" },
+    { method: "digest", schedule: "0 9 * * 1-5", timezone: "America/New_York" },
+  ],
+});
+```
+
+The host calls the method with `{}` when it comes due, as a tap would, whether
+or not anyone is looking. `schedule` is five fields (minute hour day-of-month
+month day-of-week), or six with seconds first (`*/5 * * * * *`); each is `*`, a
+number, a range, a list or a step. `timezone` defaults to the environment's.
+
+A job still running isn't started again, a time the environment slept through
+is skipped, and nothing is retried. A cron naming a missing method, a stream, a
+method that needs input or asks first, or a schedule never due fails the
+plugin's load. The manifest shows each cron's `nextRunAt`, `lastRunAt`,
+`lastError` and `runs`.
+
+## The context
+
+Every method, handler and cron gets `ctx`:
+
+| Field | What |
+| --- | --- |
+| `plugin` | The plugin's name |
+| `root` | The calling project's checkout |
+| `collections`, `kv`, `streams`, `buckets` | The plugin's data |
+| `call(method, input)` | Runs a method of a plugin in the same folder; `"open"` is this plugin's own |
+| `plugins()` | The plugins in the same folder, with their methods |
+| `host(method, params)` | Runs one of the host's methods that agents and cards may call (`git.status`, `chats.list`, `actions.run`, …); others fail with `FORBIDDEN` |
+| `notify({ title, body, page?, collapse? })` | Alerts every paired phone; a tap opens `page`, and alerts sharing `collapse` replace each other |
+| `emit(event, payload)` | Sends `<plugin>.<event>` to handlers |
+| `signal` | Aborts when a stream's card goes |
+| `log(...)` | Writes to the host's plugin log |
+
+A query doesn't re-run when what a `ctx.host` method read changes.
+
+## Events
+
+Handlers in `on` run after the events they name:
+
+```ts
+on: {
+  "photos.created": async (file, ctx) => { /* caption it */ },
+  "tasks.updated": async ({ before, after }, ctx) => { /* … */ },
+}
+```
+
+| Source | Events |
+| --- | --- |
+| Collection | `<name>.created` (the record), `<name>.updated` (`{ before, after }`), `<name>.deleted` (the record) |
+| Kv | `<name>.created`, `<name>.updated`, `<name>.deleted` (the entry) |
+| Bucket | `<name>.created`, `<name>.changed` (the file's bytes), `<name>.metaChanged`, `<name>.deleted` (the file) |
+| Any method | `<method>` (`{ input, result }`) |
+
+Changes to a bucket's folder made by hand emit too, once the host sees them.
+Events run in memory: none is retried, and a handler that throws is logged.
+
+## How cards and agents reach a plugin
+
+**Agents** use two tools: `plugins` lists every plugin with its methods, input
+schemas, crons and `storage` (each bucket's and stream's folder), and
+`plugin_call` runs one. Call a new method once before a card names it.
+
+**Cards** name methods as `plugin:<plugin>.<method>`. A `Data` element runs a
+query, or follows a stream, and redraws when its data changes; a `Button` or
+`Item` action runs a mutation:
+
+```xml
+<Data name="photos" method="plugin:gallery.photos.search">
+  <Param name="query" value="{{q}}"/>
+  <Each in="photos" as="p"><Item label="{{p.name}}" subtitle="{{p.meta.caption}}"/></Each>
+</Data>
+<Button label="Mark done" action="plugin:notes.notes.update">
+  <Param name="id" value="{{note.id}}"/>
+  <Param name="done" value="true" type="boolean"/>
+</Button>
+```
+
+## Errors and confirmations
 
-A method may alert the user's phones: `ctx.notify({ title, body, page })`, where
-`page` is a page target a tap opens (`".repogo/tabs/vercel.md?project=a"`), and
-`collapse` lets a repeated alert replace itself.
+Throw `new MethodError(code, message)` for a failure the caller should read:
+`VALIDATION`, `NOT_FOUND`, `FORBIDDEN` or `INTERNAL`. Input that fails its
+schema answers `VALIDATION` with a message per field. Anything else thrown is
+`INTERNAL` with its message.
 
-Add it to `.repogo/plugins/package.json` (`bun add @repogo/plugins`) for types
-and editor help. The RepoGo host runs plugins with its own copy of this
-package, the version it shipped with, so a plugin always matches the host.
-Plugins run on [Bun](https://bun.sh); install it on the environment.
+A method's `confirm` is asked before a card's tap runs it. An agent's
+`plugin_call` gets it back as a `CONFIRM` error until it calls again with
+`confirmed: true`, once the user agrees. Only `ctx.call` from plugin code skips
+it. Give one to anything that can't be undone.

package/dist/buckets.d.ts

@@ -0,0 +1,88 @@
+import type { z } from "zod";
+import { Store, type StoreOptions } from "./store";
+/**
+ * How a file's meta reads: `ok` matches the bucket's schema, `empty` has none,
+ * `invalid` fails the schema, and `malformed` isn't JSON or its folder doesn't
+ * hold exactly one file. `problem` says why for the last two.
+ */
+export type FileStatus = "ok" | "empty" | "invalid" | "malformed";
+/** One file in a bucket. `path` is the file on disk; `meta` is its `meta.json` without `folder`. */
+export type BucketFile<T> = {
+    id: string;
+    name: string;
+    folder: string;
+    path: string;
+    size: number;
+    type: string;
+    meta: Partial<T>;
+    status: FileStatus;
+    problem: string | null;
+    revision: number;
+    createdAt: string;
+    updatedAt: string;
+};
+/** What `put` writes: the file's name, its bytes, and optionally where it sits and its meta. */
+export type PutFile<T> = {
+    name: string;
+    body: string | Uint8Array | ArrayBuffer | Blob;
+    folder?: string;
+    meta?: T;
+};
+export declare class Bucket<S extends z.ZodObject> extends Store {
+    private schema;
+    private table;
+    private searchTable;
+    private folder;
+    private watcher;
+    private settling;
+    private scanning;
+    private lastScan;
+    constructor(options: StoreOptions, name: string, schema: S);
+    /** The bucket's folder, for agents to add and read files. */
+    get path(): string;
+    setup(): Promise<void>;
+    put(file: PutFile<z.input<S>>): Promise<BucketFile<z.infer<S>>>;
+    get(id: string): Promise<BucketFile<z.infer<S>> | null>;
+    /** The file's bytes, to read as text, JSON, a stream or an ArrayBuffer. */
+    file(id: string): Promise<Bun.BunFile>;
+    /** Newest first; `folder` keeps one folder's files, `status` one status's. */
+    list(options?: {
+        folder?: string;
+        status?: FileStatus;
+        limit?: number;
+    }): Promise<BucketFile<z.infer<S>>[]>;
+    /** Files whose name, folder or meta text has every word of `query`, each as a prefix, best first. */
+    search(query: string, options?: {
+        limit?: number;
+    }): Promise<BucketFile<z.infer<S>>[]>;
+    /**
+     * Merges `meta` into the file's meta.json (`null` removes a field), checked
+     * against the schema. With `revision`, fails if the file changed since it was read.
+     */
+    update(id: string, meta: Partial<{
+        [K in keyof z.input<S>]: z.input<S>[K] | null;
+    }>, options?: {
+        revision?: number;
+    }): Promise<BucketFile<z.core.output<S>>>;
+    /** Renames the file, or moves it to another folder; its id stays. */
+    move(id: string, to: {
+        name?: string;
+        folder?: string;
+    }, options?: {
+        revision?: number;
+    }): Promise<BucketFile<z.core.output<S>>>;
+    delete(id: string): Promise<void>;
+    tick(now: number): Promise<void>;
+    close(): void;
+    /**
+     * Brings the table in line with the folders, one scan at a time. A folder
+     * whose prints match its row is skipped; rows go only once the listing worked.
+     */
+    scan(): Promise<void>;
+    private scanNow;
+    private reindex;
+    /** One file's folder as a row would hold it, or null when it's gone. */
+    private read;
+    private rewrite;
+    private toFile;
+}

package/dist/collections.d.ts

@@ -1,5 +1,5 @@
-import type { SQL } from "bun";
 import type { z } from "zod";
+import type { Database } from "./database";
 import type { EventBus } from "./events";
 export type Record_<T> = T & {
     id: string;
@@ -13,19 +13,16 @@ export type ListOptions = {
     limit?: number;
 };
 export declare class Collection<S extends z.ZodObject> {
-    private sql;
+    private database;
     private events;
     private plugin;
     private name;
     private schema;
     private table;
     readonly tag: string;
-    /** This Worker's writes run one at a time; the transaction holds off other Workers. */
-    private writes;
-    constructor(sql: SQL, events: EventBus, plugin: string, db: string, name: string, schema: S);
+    constructor(database: Database, events: EventBus, plugin: string, namespace: string, name: string, schema: S);
     setup(): Promise<void>;
-    private serial;
-    private transaction;
+    private get sql();
     create(input: z.input<S>): Promise<Record_<z.infer<S>>>;
     get(id: string): Promise<Record_<z.infer<S>> | null>;
     update(id: string, patch: Partial<z.input<S>>): Promise<Record_<z.infer<S>>>;

package/dist/context.d.ts

@@ -1,4 +1,8 @@
+import type { Bucket } from "./buckets";
 import type { Collection } from "./collections";
+import type { Kv } from "./kv";
+import type { Stream } from "./streams";
+import type { MethodKind } from "./define";
 /** An alert for the user's phones: what it says, and the page a tap opens. */
 export type Notice = {
     title: string;
@@ -8,13 +12,72 @@ export type Notice = {
     /** Alerts sharing a collapse id replace one another; defaults to the plugin and title. */
     collapse?: string;
 };
+/** One method as `ctx.plugins()` and the agent's `plugins` tool list it. */
+export type ManifestMethod = {
+    /** `<plugin>.<method>`, the name `ctx.call` takes. */
+    name: string;
+    kind: MethodKind;
+    description: string | null;
+    /** What a card asks before running it; null runs on tap. */
+    confirm: string | null;
+    /** JSON Schema of the input, and of the output when the method declares one. */
+    input: unknown;
+    output: unknown;
+};
+/** One cron and how it's going: times in ms, and what its last run threw. */
+export type ManifestCron = {
+    method: string;
+    schedule: string;
+    timezone: string;
+    nextRunAt: number | null;
+    lastRunAt: number | null;
+    lastError: string | null;
+    running: boolean;
+    runs: number;
+};
+/** Where a plugin's buckets and streams sit on disk, for an agent's own file tools, and its kv names. */
+export type ManifestStorage = {
+    buckets: {
+        name: string;
+        path: string;
+    }[];
+    kv: {
+        name: string;
+    }[];
+    streams: {
+        name: string;
+        path: string;
+    }[];
+};
+export type Manifest = {
+    plugins: {
+        name: string;
+        description: string | null;
+        methods: ManifestMethod[];
+        crons: ManifestCron[];
+        storage: ManifestStorage;
+    }[];
+};
 export type Context = {
     plugin: string;
     /** The project's checkout, for a plugin that reads the project's files. */
     root: string;
-    db: Record<string, Collection<any>>;
+    collections: Record<string, Collection<any>>;
+    buckets: Record<string, Bucket<any>>;
+    kv: Record<string, Kv<any>>;
+    streams: Record<string, Stream<any>>;
     call: (method: string, input?: unknown) => Promise<unknown>;
     emit: (name: string, payload: unknown) => Promise<void>;
+    /**
+     * Runs one of the host's methods, the ones agents and cards can call:
+     * `ctx.host("git.status", { path: ctx.root })`. Its answer doesn't re-run a query.
+     */
+    host: (method: string, params?: unknown) => Promise<unknown>;
+    /**
+     * The plugins beside this one, in the same folder (the project's, or the
+     * environment's), with their methods: what `call` can reach.
+     */
+    plugins: () => Manifest["plugins"];
     /** Aborts when a stream's last watcher leaves; a query or mutation's never does. */
     signal: AbortSignal;
     /** Sends an alert to every phone paired with this environment. */

package/dist/database.d.ts

@@ -0,0 +1,11 @@
+import { SQL } from "bun";
+export declare class Database {
+    readonly sql: SQL;
+    private writes;
+    private constructor();
+    static open(path: string): Promise<Database>;
+    /** Runs `work` alone in a transaction; it commits when `work` returns and rolls back when it throws. */
+    transaction<T>(work: () => Promise<T>): Promise<T>;
+    close(): void;
+    private run;
+}

package/dist/define.d.ts

@@ -1,6 +1,12 @@
 import type { z } from "zod";
 import type { Context } from "./context";
+import type { Retain } from "./streams";
 export type Collections = Record<string, z.ZodObject>;
+/** A stream's lines' schema, or that and how long it keeps them (7 days or 50 MB a key unless it says). */
+export type StreamDefinition = z.ZodType | {
+    item: z.ZodType;
+    retain: Retain;
+};
 /**
  * A query only reads, so cards may run it on their own and again when its data
  * changes. A mutation writes, and runs only when the user acts. A stream only
@@ -22,18 +28,36 @@ export type Method<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodT
     run: (input: z.infer<I>, ctx: Context) => unknown | Promise<unknown>;
 };
 export type Handler = (payload: any, ctx: Context) => unknown | Promise<unknown>;
+/**
+ * Runs one of the plugin's methods on a schedule, called with `{}` as a tap
+ * would: `{ method: "watch", schedule: "*\/5 * * * *" }`. `schedule` is a cron,
+ * five fields or six with seconds first; `timezone` defaults to the environment's.
+ */
+export type Cron = {
+    method: string;
+    schedule: string;
+    timezone?: string;
+};
 export type PluginDefinition = {
     /** One line, shown to the agent in the index of plugins. */
     description?: string;
     /**
-     * The data file the collections live in, `<db>.db` in the data dir; the
-     * plugin's folder name when left out. A project's own data is `<project>.<name>`
-     * (`repogo.plans`); a bare name (`todos`) is shared by every plugin that names it.
+     * Where the plugin's data lives: `<namespace>/` in the data dir, holding `data.db`
+     * and its buckets' and streams' files. Plugins naming the same namespace share its
+     * data. The plugin's folder name when left out; by convention a project's own is
+     * `<project>.<name>` (`repogo.plans`) and data for every project a bare name (`todos`).
      */
-    db?: string;
+    namespace?: string;
     collections?: Collections;
+    /** Files with a `meta.json` each, in `<namespace>/buckets/<name>/`; the schema is the meta's. */
+    buckets?: Record<string, z.ZodObject>;
+    /** Keys to values, in the namespace's `data.db`; a key may expire. */
+    kv?: Record<string, z.ZodType>;
+    /** Append-only JSONL per key, in `<namespace>/streams/<name>/`, kept as `retain` says. */
+    streams?: Record<string, StreamDefinition>;
     methods?: Record<string, Method<any, any>>;
     on?: Record<string, Handler>;
+    crons?: Cron[];
 };
 export declare function definePlugin<T extends PluginDefinition>(plugin: T): T;
 export declare function method<I extends z.ZodType, O extends z.ZodType = z.ZodType>(input: I, run: (input: z.infer<I>, ctx: Context) => unknown | Promise<unknown>, options?: {

package/dist/duration.d.ts

@@ -0,0 +1,3 @@
+/** A length of time as a plugin writes it: milliseconds, or a number and a unit (`"30s"`, `"5m"`, `"1h"`, `"7d"`). */
+export type Duration = number | `${number}${"s" | "m" | "h" | "d"}`;
+export declare function parseDuration(duration: Duration): number;

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export { definePlugin, method, stream } from "./define";
-export type { PluginDefinition, Method, MethodKind } from "./define";
-export type { Context } from "./context";
+export type { PluginDefinition, Method, MethodKind, Cron, StreamDefinition } from "./define";
+export type { Context, Manifest, ManifestCron, ManifestMethod, ManifestStorage } from "./context";
+export type { BucketFile, FileStatus, PutFile } from "./buckets";
+export type { KvEntry, SetOptions } from "./kv";
+export type { Retain, StreamEntry, StreamKey } from "./streams";
+export type { Duration } from "./duration";
 export { MethodError, toCallError, type CallError } from "./errors";
 export { z } from "zod";

package/dist/kv.d.ts

@@ -0,0 +1,32 @@
+import type { z } from "zod";
+import { type Duration } from "./duration";
+import { Store, type StoreOptions } from "./store";
+/** One key and its value, as `get` sees it and the generated methods send it. */
+export type KvEntry<T> = {
+    key: string;
+    value: T;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+/** `ttl`: how long the key lives; setting a key without one keeps it until deleted. */
+export type SetOptions = {
+    ttl?: Duration;
+};
+export declare class Kv<S extends z.ZodType> extends Store {
+    private schema;
+    private table;
+    constructor(options: StoreOptions, name: string, schema: S);
+    setup(): Promise<void>;
+    get(key: string): Promise<z.infer<S> | null>;
+    entry(key: string): Promise<KvEntry<z.infer<S>> | null>;
+    set(key: string, value: z.input<S>, options?: SetOptions): Promise<KvEntry<z.infer<S>>>;
+    delete(key: string): Promise<void>;
+    /** Live keys in key order, those starting with `prefix` when it's given. */
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+    }): Promise<KvEntry<z.infer<S>>[]>;
+    tick(now: number): Promise<void>;
+    private live;
+}

package/dist/store.d.ts

@@ -0,0 +1,32 @@
+import type { Database } from "./database";
+import type { EventBus } from "./events";
+/** What every kv, stream and bucket is built with: its namespace's file and folder, and the runtime's bus. */
+export type StoreOptions = {
+    database: Database;
+    events: EventBus;
+    namespace: string;
+    /** `<dataDir>/<namespace>`, the folder for what isn't rows. */
+    dir: string;
+    /** Tells cards a tag changed, for writes no call is tracking (the sweep, a scan). */
+    announce: (tags: string[]) => void;
+};
+export type StoreKind = "kv" | "streams" | "buckets";
+export declare abstract class Store {
+    protected options: StoreOptions;
+    readonly kind: StoreKind;
+    readonly name: string;
+    readonly tag: string;
+    readonly plugins: Set<string>;
+    constructor(options: StoreOptions, kind: StoreKind, name: string);
+    /** Brings the store's files and table up; called once, when the first plugin declares it. */
+    abstract setup(): Promise<void>;
+    /** Called every few seconds by the Worker: expiry, retention, reconciling with the disk. */
+    abstract tick(now: number): Promise<void>;
+    close(): void;
+    protected get sql(): Bun.SQL;
+    protected emit(event: string, payload: unknown): Promise<void>;
+}
+/** A table name for a store: its kind and name, letters, digits and underscores only. */
+export declare function tableName(kind: StoreKind, name: string): string;
+/** A key or id that is also a file name: no slashes, no leading dot, at most 128 characters. */
+export declare const safeName: RegExp;

package/dist/streams.d.ts

@@ -0,0 +1,79 @@
+import type { z } from "zod";
+import { type Duration } from "./duration";
+import { Store, type StoreOptions } from "./store";
+/** One line of a stream. `id` is `<key>:<offset>`, for cards; on disk a line is `{ offset, at, data }`. */
+export type StreamEntry<T> = {
+    id: string;
+    key: string;
+    offset: number;
+    at: string;
+    data: T;
+};
+/** One key of a stream: a run, a job, a day. */
+export type StreamKey = {
+    key: string;
+    lines: number;
+    bytes: number;
+    endedAt: string | null;
+    updatedAt: string;
+};
+/**
+ * How long a stream keeps what it was sent: a key untouched for `age` goes
+ * whole, and past `bytes` its oldest segments go. `"forever"` keeps everything.
+ */
+export type Retain = {
+    age?: Duration;
+    bytes?: number;
+} | "forever";
+export declare const defaultRetain: {
+    readonly age: "7d";
+    readonly bytes: 50000000;
+};
+export declare class Stream<S extends z.ZodType> extends Store {
+    private schema;
+    private table;
+    private folder;
+    private ageMs;
+    private maxBytes;
+    private lastRetain;
+    /** Followers in this Worker waiting on a key's next line. */
+    private waiting;
+    constructor(options: StoreOptions, name: string, schema: S, retain?: Retain);
+    /** The stream's folder, for agents to `tail`. */
+    get path(): string;
+    setup(): Promise<void>;
+    append(key: string, data: z.input<S>): Promise<StreamEntry<z.infer<S>>>;
+    /** Lines from `from` on (the oldest kept when it's older), at most `limit`. */
+    read(key: string, options?: {
+        from?: number;
+        limit?: number;
+    }): Promise<StreamEntry<z.infer<S>>[]>;
+    /**
+     * Replays from `from`, then yields each line as it's appended, until the key
+     * ends or `signal` aborts. Defaults to the last `last` lines (100).
+     */
+    follow(key: string, options: {
+        from?: number;
+        last?: number;
+        signal: AbortSignal;
+    }): AsyncGenerator<StreamEntry<z.core.output<S>>, void, unknown>;
+    /** Marks a key finished: followers stop, appends fail, and it goes once it's older than the retention age. */
+    end(key: string): Promise<void>;
+    keys(options?: {
+        limit?: number;
+    }): Promise<StreamKey[]>;
+    delete(key: string): Promise<void>;
+    tick(now: number): Promise<void>;
+    close(): void;
+    private retain;
+    private lines;
+    private cutUncommitted;
+    private start;
+    private row;
+    /** A key's segment files by first offset, oldest first. */
+    private segments;
+    private segmentPath;
+    /** Settles on this Worker's next append to `key`, after a poll interval for other Workers', or on abort. */
+    private nextAppend;
+    private wake;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repogo/plugins",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "Write RepoGo plugins: collections and methods over SQLite that agents and cards call",
   "type": "module",
   "exports": {