@repogo/plugins 0.1.42 → 0.1.44

package/README.md

@@ -3,11 +3,12 @@
 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.
+phone draw its data live and run its methods when you tap. A method may also
+opt into plain HTTP, for this machine's containers or the public.
 
 - [Quick start](#quick-start)
 - [Where plugins live](#where-plugins-live)
-- [Methods](#methods): queries, mutations, streams, cached queries
+- [Methods](#methods): reads, writes, destructive methods, streams, cached reads, [serving over HTTP](#serving-over-http)
 - [Data](#data): namespaces, collections, kv, streams, buckets, uploads
 - [Workflows](#workflows)
 - [Crons](#crons)
@@ -15,28 +16,28 @@ phone draw its data live and run its methods when you tap.
 - [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)
+- [Errors and approvals](#errors-and-approvals)
 - [Testing](#testing)
 
 ## Quick start
 
 ```ts
-// .repogo/plugins/notes/app.ts
+// ~/.repogo/plugins/notes/app.ts
 import { definePlugin, method, z } from "@repogo/plugins";
 
 export default definePlugin({
-  description: "Notes for this project",
-  namespace: "myproject.notes",
+  description: "Notes for any project",
+  namespace: "notes",
   collections: { notes: z.object({ text: z.string(), done: z.boolean().default(false) }) },
   methods: {
     open: method(z.object({}), async (_, ctx) => ctx.collections.notes.list({ where: { done: false } }), {
-      kind: "query",
+      effect: "read",
       description: "Notes not done yet, newest first",
     }),
     clear: method(z.object({}), async (_, ctx) => {
       for (const note of await ctx.collections.notes.list({ limit: 500 })) await ctx.collections.notes.delete(note.id);
       return null;
-    }, { confirm: "Delete every note?" }),
+    }, { effect: "destructive", approve: "Delete every note?" }),
   },
 });
 ```
@@ -46,9 +47,9 @@ 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/`.
+- a `data.db` in `~/.repogo/plugin-data/notes/`.
 
-Add the package to `.repogo/plugins/package.json` (`bun add @repogo/plugins`) for
+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.
@@ -57,30 +58,43 @@ the version it shipped with, so a plugin always matches its host. Plugins run on
 
 | 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.
+| `~/.repogo/plugins/<name>/app.ts` | Every project | The project that called it |
+
+Plugins live only on the environment, in folders the user put there. A project
+can't ship plugin code: the host never imports a repo's `.repogo/plugins`, so
+cloning or opening a project never runs anything in it. A plugin about one
+project (its keys, its database, its plans) is still an environment plugin: it
+reads that project from `ctx.root`, and says so instead of acting when it's
+called from a project it doesn't fit.
+
+A project ships no pages either: the app loads `.ui` and `.html` pages only
+from `~/.repogo/plugins`, so a cloned repo can't put its own page, and the
+script an `.html` page runs, in front of the user. A page about one project
+lives beside its plugin and takes the project as state (`?project=…`).
+
+A plugin's name is its folder's: lowercase letters, digits and hyphens. The
+environment's plugins run together in one Worker, so a plugin's blocking code
+stalls the others: use async APIs. They load together too: one that fails to
+load (a throw at import, a destructive method without an `approve`, data without
+a `namespace`, a method named like a generated one) stops every plugin in the
+folder, and each call answers its error, until it's fixed.
 
 Pages beside an environment plugin (`pages/*.ui`, or `pages/*.md`) open from
 any project as `~/.repogo/plugins/<name>/pages/<page>.ui`. A
 `.ui` page is card markup with no fence; a `.md` page is writing with cards.
 
-In the full iOS app, `~/.repogo/plugins/plugin.ui` supplies a shared Plugins
-tab. A project’s `.repogo/plugin.ui` overrides the entire page for that
-project; entries are not merged. If neither exists, the tab is absent.
-Both are plain card markup without a code fence. Read and preserve existing
+In the full iOS app, `~/.repogo/plugins/plugin.ui` is the Plugins tab in
+every project; a project's `.repogo/plugin.ui` is never read. If it doesn't
+exist, the tab is absent. It is plain card markup without a code fence. Read and preserve existing
 entries, and link to plugin pages with `page:` actions.
 
-A user-facing plugin needs both its saved page and a link from the applicable `plugin.ui`. Saving a file in `.repogo/tabs` or naming it `index.ui` does not register a project tab. Plugin discovery can list a page without a navigation entry; verify the effective `plugin.ui` links to the existing page.
+A user-facing plugin needs both its saved page and a link from `~/.repogo/plugins/plugin.ui`. Saving a file in a pages folder or naming it `index.ui` does not add it to the tab. Plugin discovery can list a page without a navigation entry; verify `plugin.ui` links to the existing page.
 
 ## Methods
 
 ```ts
-method(input, run, { kind?, description?, output?, confirm? })
+method(input, run, { effect?, description?, output?, approve?, approveUpTo?, http? })
+cached(input, run, { fresh, shared?, timeout?, description?, output?, http? })
 stream(input, async function* run, { description? })
 ```
 
@@ -88,14 +102,19 @@ stream(input, async function* run, { description? })
 filled in before `run` sees it. `run(input, ctx)` returns the result: anything
 JSON can carry.
 
-| Kind | Does | Who runs it |
+| Effect | 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
+| `read` | Only reads; writing throws | Cards on their own, and again whenever data it read changes |
+| `write` (the default) | Reads and writes | Only when someone acts: a tap, an agent, a cron, other code |
+| `destructive` | Writes what can't be undone; needs an `approve` | Only after the user answers its question |
+| `stream()` | A read that yields items as they happen | A card while it shows it |
+
+Mark every method that only reads `effect: "read"`: that's what lets a card
+show it and keep it current. Mark what can't be undone (a delete, a send, a
+deploy) `effect: "destructive"` with an `approve` question; a destructive method
+without one doesn't load. A method with an `approve` asks before it runs, from
+a tap or an agent ([Errors and approvals](#errors-and-approvals)), and never
+runs from a cron. 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.
 
@@ -108,13 +127,14 @@ or the voice agent reads the whole of one.
 ```ts
 open: method(z.object({ limit: z.number().int().min(1).max(100).default(20) }), async ({ limit }, ctx) =>
   (await ctx.collections.notes.list({ where: { done: false }, limit })).map(({ id, text }) => ({ id, text: text.slice(0, 200) })),
-  { kind: "query", description: "Notes not done yet, newest first" }),
+  { effect: "read", description: "Notes not done yet, newest first" }),
 ```
 
 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.
+start. Give items an `id`. An agent calling a stream, or `ctx.call` on one,
+gets `{ items, done }`: what arrives within 5 seconds, at most 200 items, with
+`done` false when it was cut off.
 
 ```ts
 tail: stream(z.object({ file: z.string() }), async function* ({ file }, ctx) {
@@ -142,13 +162,93 @@ projects: cached(z.object({ limit: z.number().int().min(1).max(200).default(100)
 
 - Answers are kept per method, input and project (`ctx.root`). `shared: true`
   keeps one for every project, for answers that don't depend on it.
-- `run` is read-only, like a query's, and has `timeout` (a minute unless it says).
+- `run` is read-only, like any read's, and has `timeout` (a minute unless it says).
 - A background check that fails keeps the saved answer, goes to the plugin's
   logs, and is tried again after another `fresh`.
 - Answers live in the namespace's `data.db`, so a plugin with a cached method
   needs a `namespace`. An answer over 1 MB is returned but not saved, and one
   nobody has asked for in 30 days is deleted.
 
+### Serving over HTTP
+
+Cards, agents and crons reach every method. A method answers plain HTTP too
+when its `http` option names an address, with who may call it there. `method`
+and `cached` take it; a stream or a method with an `approve` is never served,
+since no one is there to watch or answer.
+
+```ts
+today: cached(z.object({}), async () => sales(), { fresh: "5m", http: { device: "none" } }),
+```
+
+| Address | Where | Reached at |
+| --- | --- | --- |
+| `device` | This machine's loopback and its Apple containers' gateways, port 47444; Docker Desktop's containers reach it through `host.docker.internal` | `http://127.0.0.1:47444/<plugin>/<method>` |
+| `public` | The environment's own name, through the tunnel | `https://h-<host id>.repogo.dev/<plugin>/<method>` |
+
+| Access | Who may call |
+| --- | --- |
+| `key` | Only a caller sending the plugin's key as `Authorization: Bearer <key>`, which the host checks before the method runs |
+| `none` | Anyone who reaches the address. On `device` the network is the boundary; on `public` it's anyone with the URL, since a method doesn't see the request's headers to check a signature |
+
+`http: true` is `{ public: "key" }`. An address a method doesn't name answers
+404, as do a method that doesn't exist and a missing or wrong key, so callers
+can't learn which plugins are installed.
+
+`repogo urls shop` lists each of a plugin's methods served over HTTP with its
+URLs, filled in with this host's id.
+
+Each plugin has one key, for all its methods that take one, at both
+addresses. `repogo keys shop` prints it, making it the first time; running it
+again shows the same key. `repogo keys shop --new` replaces it, and the old
+one stops working at once; `repogo keys shop --delete` leaves the methods
+answering no one. RepoGo's tools for agents and a plugin's `ctx.host` can't
+reach keys, though anything that runs commands as you can run `repogo keys`,
+as it can read your plugins' own secrets. The method itself never sees the key.
+
+A POST's JSON body is the input as it is. A GET's query is the input, as
+strings, and only a `read` may be called that way:
+link previews and crawlers fetch any URL they're shown, so a write answers
+405 to a GET. The answer is the result as JSON, or `{ error, fields }` with
+400, 403 or 404 for a `MethodError` with those codes, in its own words. Any
+other error, such as a failed `fetch`, answers 500 `Internal server error`,
+since its text may hold a token or a path; the host logs the real one. The
+device address takes calls only from this machine and its containers'
+networks, and refuses a browser's, since any web page can reach loopback.
+
+A body that isn't JSON answers 400, as does one over 1 MB at the device
+address (413 at the public one), and the public address answers 429 to a
+caller sending too many. A plugin folder that fails to load answers 502. HEAD is a
+GET, and a query key given twice keeps its first value. HTTP calls have no
+project: `ctx.root` is the home folder. `ctx.caller` is `http` for a public call and `device`
+for one at the device address.
+
+When an HTTP caller hangs up, or the public address stops waiting after 60
+seconds, `ctx.signal` aborts: hand it to `fetch` and `Bun.spawn` so the work
+stops. The public address runs at most 32 calls at once and answers 503 to
+another; a call counts until its method returns, so one that ignores the
+signal keeps its place until it's done.
+
+A method served over HTTP runs with all of `ctx`: one that starts an agent,
+runs an action or calls another method lets its caller do the same. Every
+container on this machine reaches every method open to `device`, and so does
+every account and app on it. Open only what you'd show anyone who can reach
+the address: reads, never a send or a delete.
+
+**A plugin elsewhere that stands in for one here.** `GET /<plugin>` at the
+device address lists the methods it serves there with no key, with their
+schemas, and `remotePlugin` builds a plugin from it. In a container, a plugin
+of the same name whose `app.ts` is only this serves the Mac's plugin, and its
+pages, copied or mounted, work unchanged; the code, keys and data stay on the Mac:
+
+```ts
+import { remotePlugin } from "@repogo/plugins";
+export default await remotePlugin("http://192.168.64.1:47444", "shop");
+```
+
+It reads the list when the plugin loads, so it fails to load while the Mac
+can't be reached. A page's button for a method the Mac doesn't serve there
+fails, as it would for any missing method.
+
 ## Data
 
 A plugin declares its data in four kinds, each with a schema, and gets typed
@@ -193,7 +293,9 @@ await ctx.collections.tasks.delete(task.id);
 await ctx.collections.tasks.deleteMany({ where: { status: "done" }, offset: 100, limit: 500 }); // done ones past the newest 100, 500 at a time
 ```
 
-`list` is newest first by default, at most 100 unless `limit` says (the generated `list` takes up to 500).
+`list` is newest first by default, at most 100 unless `limit` says. The
+generated `list` cards and agents call takes `limit` (up to 500), `offset`,
+`orderBy` and `order` but no `where`: write a `read` method to filter.
 `where` matches top-level fields exactly; `null` matches a missing one.
 `orderBy` is `id`, `createdAt`, `updatedAt` or one of the record's own fields, and
 `offset` passes over that many first. `deleteMany` takes the same options and
@@ -377,7 +479,7 @@ export default definePlugin({
         await ctx.kv.reports.set("latest", report);
         return report;
       });
-    }, { timeout: "30d", maxOffline: "14d", retention: "30d" }),
+    }, { timeout: "30d", maxOffline: "14d", retention: "30d" }), // the defaults
   },
   kv: { reports: z.object({ title: z.string() }) },
 });
@@ -385,7 +487,7 @@ export default definePlugin({
 
 For a plugin folder named `reports`, the host generates:
 
-- `reports.report.list({ limit?, status?, cursor? })`: bounded summaries and a next cursor.
+- `reports.report.list({ limit?, status?, cursor? })`: bounded summaries (20 unless `limit` says, at most 100) and a next cursor. A status is `pending`, `running`, `waiting`, `attention`, `completed`, `failed`, `cancelled`, `expired`, `unknown` or `blocked`.
 - `reports.report.get({ id })`: one summary, input, result, error and the latest 20 operations (steps and sleeps).
 - `reports.report.start({ input, key? })`: persist and queue a run; returns its summary immediately.
 - `reports.report.cancel({ id })`: persist cancellation intent and abort active work.
@@ -394,9 +496,9 @@ For a plugin folder named `reports`, the host generates:
 - `reports.report.restart({ id })`: start a run that needs attention over from the beginning, on the current code.
 
 These use the existing plugin methods, `ctx.call`, cards and subscriptions.
-The namespace is required. `confirm` on the workflow confirms its start;
+The namespace is required. `approve` on the workflow asks before its start;
 it does not preapprove later host actions. An unattended workflow refuses
-confirmation-gated plugin methods. The calling project and caller
+plugin methods that ask. The calling project and caller
 are preserved. A start `key` deduplicates within that project, plugin and
 workflow while its run is retained; reusing it with different input fails.
 
@@ -428,8 +530,10 @@ with `kind: "sleep"`. Terminal runs have no pending wake time.
 `attempts` counts the first invocation and defaults to 1. Only steps declared
 `kind: "query"` may automatically retry; they cannot write SDK data or call
 mutations. Within query steps, use `ctx.mcp` for read-aware host access;
-generic `ctx.host`, notifications and agent starts are refused. Query backoff defaults to full jitter with initial `2s`, factor 2
-and maximum `1m`. Import `NonRetryable` and throw it for a permanent failure.
+generic `ctx.host`, notifications and agent starts are refused. A step's `kind`
+defaults to `"mutation"`, and `attempts` is at most 100. Query backoff,
+`backoff: { initial, factor, max }`, defaults to full jitter with initial `2s`,
+factor 2 and maximum `1m`. Import `NonRetryable` and throw it for a permanent failure.
 Step `timeout` defaults to `5m`. The callback receives `signal`, `attempt`,
 `attempts`, `runId`, `stepId` and an `idempotencyKey` stable across its attempts.
 Pass its signal to fetch or subprocess APIs. A timeout aborts cooperatively;
@@ -500,8 +604,8 @@ itself. Each line names a plugin, one of its methods and a schedule:
 
 | Field | What |
 | --- | --- |
-| `plugin`, `method` | The plugin's folder name and one of its methods, called with `{}` as a tap would |
-| `project` | The project whose `.repogo/plugins` holds it, an absolute path or one starting `~/`; left out, `~/.repogo/plugins` |
+| `plugin`, `method` | The plugin's folder name and one of the methods it wrote (not a generated or workflow one), called with `{}` as a tap would |
+| `project` | The project the run gets as `ctx.root`, an absolute path or one starting `~/`; left out, the home folder. The plugin is always the environment's |
 | `schedule` | A cron: five fields (minute hour day-of-month month day-of-week), or six with seconds first (`*/5 * * * * *`); each `*`, a number, a range, a list or a step |
 | `timezone` | Defaults to the environment's |
 | `enabled` | `false` keeps the line without running it |
@@ -520,15 +624,15 @@ isn't valid JSON pauses every line until it's fixed. Each line also shows
 has the same for a plugin's own, and a query reading them re-runs around each run.
 
 Schedule something only when the user asks for it. A cron's `ctx.root` is its
-project, or the home folder for a plugin in `~/.repogo/plugins`. Plugins in one
-folder share a thread: code that blocks it holds up every other cron there, and
-the host's log names the crons that were running when it happened.
+line's project, or the home folder without one. Plugins share a thread: code
+that blocks it holds up every other cron, and the host's log names the crons
+that were running when it happened.
 
 ## Logging
 
 Write `console.log` (or `warn`, `error`, `debug`); nothing else is needed. The
 host keeps every line with the plugin, the method and the call that wrote it,
-who called (`card`, `agent`, `cron`), and the chat for an agent's call, plus
+who called (`card`, `agent`, `cron`, `code`, or `http` and `device` for HTTP), and the chat for an agent's call, plus
 the arguments as JSON. An error a method throws, or one nothing caught, is
 kept too, with its stack. Read them with the agent's `plugins_logs` tool, or on
 a card with `<Data method="repogo:plugins.logs">`, which reloads as lines land:
@@ -545,18 +649,18 @@ Every method, handler and cron gets `ctx`:
 | Field | What |
 | --- | --- |
 | `plugin` | The plugin's name |
-| `caller` | Who started the call: `card`, `agent`, `cron`, or `code` |
+| `caller` | Who started the call: `card`, `agent`, `cron`, `code`, or a request at the public (`http`) or device (`device`) address |
 | `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` |
+| `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`, and one that doesn't exist with `INTERNAL` |
 | `mcp(server, tool, input)` | Runs a tool of an MCP server the user connected in RepoGo and switched on for the calling project; see below |
 | `notify({ title, body, page?, url?, collapse? })` | Alerts every paired phone; a tap opens `url` (an `https` or `itms-services` link) if set, else `page`, and alerts sharing `collapse` replace each other |
 | `activity({ id, title, body?, page?, symbol?, tint?, label?, compactLabel?, progress?, timer?, status? })` | Shows or updates a Live Activity on every paired phone; see below |
 | `agent(prompt, { agent, project?, title?, timeout? })` | Starts a chat with `prompt` and waits for the agent's whole answer: `{ chatId, text }`; see below |
 | `emit(event, payload)` | Sends `<plugin>.<event>` to handlers |
-| `signal` | Aborts when a stream's card goes |
+| `signal` | Aborts when a stream's card goes, or when an HTTP caller leaves before a read or write answers |
 | `log(...)` | The same as `console.log` |
 
 A query doesn't re-run when what a `ctx.host` method read changes.
@@ -593,7 +697,7 @@ ends it with that state, left up for 15 minutes:
 ```ts
 deploy: method(z.object({ project: z.string() }), async ({ project }, ctx) => {
   const steps = ["Build", "Test", "Deploy", "Verify"];
-  const page = `.repogo/tabs/deploys.ui?project=${project}`;
+  const page = `~/.repogo/plugins/deploys/pages/index.ui?project=${project}`;
   const show = (current: number, body: string) =>
     ctx.activity({ id: `deploy:${project}`, title: `Deploying ${project}`, body, page,
       symbol: "shippingbox", progress: { kind: "steps", steps, current } });
@@ -633,11 +737,11 @@ or CLI of its own. It answers the tool's structured content, else its text
 customers: method(z.object({}), async (_, ctx) => {
   const list = await ctx.mcp("stripe", "stripe_api_read", { stripe_api_operation_id: "GetCustomers", /* … */ });
   return list.data.map((c) => ({ id: c.id, email: c.email }));
-}, { kind: "query" }),
+}, { effect: "read" }),
 ```
 
-A query may run only the server's read-only tools, as a card's `Data` may. A
-tool marked destructive runs only from a method with a `confirm`, or one
+A read may run only the server's read-only tools, as a card's `Data` may. A
+tool marked destructive runs only from a method with an `approve`, or one
 called from it with `ctx.call`: the user's answer to that question is its
 yes. A refusal throws `FORBIDDEN`; a tool's own error throws `INTERNAL` with
 its message. Only servers switched on for `ctx.root` answer, so a cron of an
@@ -661,23 +765,25 @@ on: {
 | 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.
+Changes to a bucket's folder made by hand emit too, once the host sees them;
+streams emit none. A plugin's `on` hears only its own events, and runs inside
+the call that emitted them, so a slow handler delays that call's answer.
 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 a line per method
-(its kind, whether it asks first, and its input's fields, optional ones ending
+(its effect, whether it asks first, and its input's fields, optional ones ending
 in `?`), and every line of `~/.repogo/crons.json` with how it's going.
 `plugins` with `plugin` set answers that plugin in full: each method's input
-and output JSON Schema and confirm, its `storage` (each bucket's and stream's
+and output JSON Schema, `approve` and `approveUpTo`, its `storage` (each bucket's and stream's
 folder), the pages that show its methods, and the cron lines naming it.
 `plugin_call` runs one. Inspect a method's schema before naming it in a card.
-Verify query fields with a read-only call. Do not execute mutations just to
+Verify a read's fields with a read-only call. Do not execute writes just to
 check a card; run them only when the user's task calls for that action.
 
 **Cards** name methods as `plugin:<plugin>.<method>`. A `Data` element runs a
-query, or follows a stream, and redraws when its data changes. `Button`,
+read, or follows a stream, and redraws when its data changes. `Button`,
 `Item` and `Swipe` actions call methods; on iOS, `Toggle` can call one on a
 user flip. `Upload` calls a plugin method with staged files. Params must match
 the discovered input schema. These fragments assume `q` and `note` are supplied
@@ -701,10 +807,10 @@ by the enclosing card:
 ### Saving from a switch
 
 Prefer SDK storage for plugin-owned data. A storage declaration generates
-methods; ordinary saves do not need a custom mutation. For example:
+methods; ordinary saves do not need a custom write method. For example:
 
 ```ts
-// .repogo/plugins/preferences/app.ts
+// ~/.repogo/plugins/preferences/app.ts
 import { definePlugin, z } from "@repogo/plugins";
 
 export default definePlugin({
@@ -738,19 +844,47 @@ Inside plugin code, `ctx.kv.flags.set("alerts", true)` saves the same value.
 The generated `preferences.flags.get({ key: "alerts" })` returns an entry with
 `value` and timestamps, while `ctx.kv.flags.get("alerts")` returns the value alone.
 
-## Errors and confirmations
+## Errors and approvals
+
+Throw `new MethodError(code, message, fieldErrors?)` for a failure the caller
+should read: `VALIDATION`, `NOT_FOUND`, `FORBIDDEN` or `INTERNAL`.
+`fieldErrors` maps a JSON pointer (`"/minutes"`) to its message, and reaches an
+HTTP caller as `fields`. Input that fails its schema answers `VALIDATION` with
+a message per field. Anything else thrown is
+`INTERNAL` with its message. An HTTP caller gets only the first three in their
+words; `INTERNAL` reaches it as `Internal server error`
+([Serving over HTTP](#serving-over-http)).
+
+A method's `approve` is the question asked before it runs. `{{field}}` in it
+is filled from the call's input, so it can say what it acts on:
+`approve: "Restart {{machine}}?"`. A `destructive` method must have one.
+
+- **A card's tap** always asks it first.
+- **An agent's `plugin_call`** asks it in the chat, as a tool approval, and runs
+  the method only on the user's yes. `approveUpTo` names the least strict chat
+  mode that still asks; the method asks in that mode and every stricter one,
+  and runs unasked in the rest. The modes, strictest first, are
+  `approval-required`, `auto-accept-edits` and `full-access`; unset is
+  `full-access`, so it asks in every mode. A chat whose mode the host can't
+  tell asks.
+- **Plan mode:** an agent's call to any method that isn't a `read` is refused,
+  with or without an `approve`.
+- **Code:** `ctx.call` from plugin code skips it, and an unattended workflow
+  or cron refuses methods that ask.
 
-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.
+```ts
+upload: method(Build, run, {
+  effect: "destructive",
+  approve: "Upload build {{buildNumber}}?",              // asks in every mode
+}),
+rename: method(Rename, run, {
+  approve: "Rename {{name}}?",
+  approveUpTo: "auto-accept-edits",                       // full access runs it unasked
+}),
+```
 
-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. Ordinary `ctx.call` from plugin code skips
-it; an unattended workflow refuses confirmation-gated methods. Give one to anything that can't be undone. `{{field}}` in the question is
-filled from the call's input, so it can say what it acts on:
-`confirm: "Restart {{machine}}?"`.
+In full access an agent can run commands without asking, so there the
+question catches a careless call rather than stopping a determined one.
 
 ## Testing
 
@@ -762,12 +896,16 @@ user's MCP servers:
 import { testRuntime } from "@repogo/plugins/testing";
 import notes from "./app";
 
-const app = await testRuntime({ notes });
-await app.call("notes.add", { text: "hi" });
+const app = await testRuntime({ notes });                 // { root?, mcp?, host? } as a second argument
+await app.call("notes.notes.create", { text: "hi" });
 await app.call("notes.clear", {}, { confirmed: false }); // throws CONFIRM, as an unanswered tap
-app.setCrons([{ plugin: "notes", method: "tidy", schedule: "* * * * *" }]); // as a crons.json line would
+app.setCrons([{ plugin: "notes", method: "open", schedule: "* * * * *" }]); // a crons.json line, with root for project
 await app.tickCrons(Date.now() + 60_000);                // runs whatever is due by then
 app.notices;                                             // every ctx.notify so far
 app.logs;                                                // every console line so far, with its method and caller
+app.manifest();                                          // the plugins and methods, as the host lists them
 await app.close();
 ```
+
+`call` takes `{ confirmed?, caller?, root?, chat?, files? }`; leaving
+`confirmed` out runs a `confirm` method without asking, as `ctx.call` does.

package/dist/context.d.ts

@@ -2,13 +2,13 @@ import type { Bucket } from "./buckets";
 import type { Collection } from "./collections";
 import type { Kv } from "./kv";
 import type { Stream } from "./streams";
-import type { HTTPAccess, MethodKind } from "./define";
+import type { Effect, HTTPAddresses, PermissionMode } from "./define";
 import type { Duration } from "./duration";
 /** An alert for the user's phones: what it says, and the page a tap opens. */
 export type Notice = {
     title: string;
     body: string;
-    /** A page target, `.repogo/tabs/vercel.md?project=a`; a tap opens it. */
+    /** A page target, `~/.repogo/plugins/vercel/pages/index.ui?project=a`; a tap opens it. */
     page?: string;
     /** An `https` or `itms-services` link a tap opens instead of the page, such as a build's install. */
     url?: string;
@@ -53,7 +53,7 @@ export type Activity = {
     title: string;
     /** At most 120 characters, as a notice's body. */
     body?: string;
-    /** A page target of the calling project, `.repogo/tabs/deploys.ui?project=web`; a tap opens it. */
+    /** A page target, `~/.repogo/plugins/deploys/pages/index.ui?project=web`; a tap opens it. */
     page?: string;
     /** An SF Symbol name, `shippingbox`; `circle.dotted`, or a check or a cross once ended, unless said. */
     symbol?: string;
@@ -74,12 +74,16 @@ export type Activity = {
 export type ManifestMethod = {
     /** `<plugin>.<method>`, the name `ctx.call` takes. */
     name: string;
-    kind: MethodKind;
+    effect: Effect;
+    /** A read that sends items as they happen. */
+    stream: boolean;
     description: string | null;
     /** What a card asks before running it; null runs on tap. */
-    confirm: string | null;
-    /** Who may call it at the environment's own address; null, no one. */
-    http: HTTPAccess | null;
+    approve: string | null;
+    /** The least strict chat mode an agent's call still asks in; null with no approve. */
+    approveUpTo: PermissionMode | null;
+    /** Who may call it over HTTP, at each address; null, no one anywhere. */
+    http: HTTPAddresses | null;
     /** JSON Schema of the input, and of the output when the method declares one. */
     input: unknown;
     output: unknown;
@@ -113,13 +117,15 @@ export type ManifestStorage = {
 };
 /**
  * One schedule the host gives a Worker, from a line of `~/.repogo/crons.json`: call
- * `<plugin>.<method>` with `{}` when `schedule` comes due in `timezone` (the environment's).
+ * `<plugin>.<method>` with `{}` when `schedule` comes due in `timezone` (the environment's),
+ * with `root` (the line's project) as `ctx.root`, else the Worker's own.
  */
 export type CronEntry = {
     plugin: string;
     method: string;
     schedule: string;
     timezone?: string;
+    root?: string;
 };
 /** A schedule and how it's going; `error` says why it couldn't be set, and then nothing runs. */
 export type CronStatus = ManifestCron & {
@@ -135,8 +141,8 @@ export type Manifest = {
         storage: ManifestStorage;
     }[];
 };
-/** Who started a call: a tap or a card's query, an agent's `plugin_call`, a cron, or plugin code with none of those behind it. */
-export type Caller = "card" | "agent" | "cron" | "code" | "http";
+/** Who started a call: a tap or a card's query, an agent's `plugin_call`, a cron, plugin code with none of those behind it, or a request at the public (`http`) or device address. */
+export type Caller = "card" | "agent" | "cron" | "code" | "http" | "device";
 /** How `ctx.agent` runs a chat: which agent, in which project, and how long to wait for its answer. */
 export type AgentOptions = {
     /** `claude` or `codex`, as `agents.list` names them. */
@@ -173,15 +179,15 @@ export type Context = {
      * Runs a tool of an MCP server the user switched on for the calling project:
      * `ctx.mcp("stripe", "stripe_api_read", { … })`, answering the tool's result.
      * A query may run only read-only tools; a destructive tool runs only from a
-     * method with a `confirm`. Its answer doesn't re-run a query.
+     * method with an `approve`. Its answer doesn't re-run a query.
      */
     mcp: (server: string, tool: string, input?: 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.
+     * The plugins beside this one in the environment's plugins folder, 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. */
+    /** Aborts when a stream's last watcher leaves, or when an HTTP caller of a read or write goes away first. */
     signal: AbortSignal;
     /** Sends an alert to every phone paired with this environment. */
     notify: (notice: Notice) => void;