@repogo/plugins 0.1.43 → 0.1.45

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): reads, writes, destructive methods, streams, cached reads
+- [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,7 +16,7 @@ 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
@@ -36,7 +37,7 @@ export default definePlugin({
     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;
-    }, { effect: "destructive", confirm: "Delete every note?" }),
+    }, { effect: "destructive", approve: "Delete every note?" }),
   },
 });
 ```
@@ -73,7 +74,10 @@ 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.
+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
@@ -89,7 +93,8 @@ A user-facing plugin needs both its saved page and a link from `~/.repogo/plugin
 ## Methods
 
 ```ts
-method(input, run, { effect?, 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? })
 ```
 
@@ -101,14 +106,15 @@ JSON can carry.
 | --- | --- | --- |
 | `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 a `confirm` | Only after the user answers its question, on a tap |
+| `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 a `confirm` question; a destructive method
-without one doesn't load. A method with a `confirm` never runs from an agent's
-`plugin_call` or a cron: the agent draws a button, and the user's tap asks. Give each a `description`; agents read it to choose
+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.
 
@@ -126,8 +132,9 @@ open: method(z.object({ limit: z.number().int().min(1).max(100).default(20) }),
 
 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) {
@@ -162,6 +169,87 @@ projects: cached(z.object({ limit: z.number().int().min(1).max(200).default(100)
   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:
+call it by an address, `localhost` or `host.docker.internal`, not another name.
+
+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
@@ -206,7 +294,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
@@ -390,7 +480,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() }) },
 });
@@ -398,7 +488,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.
@@ -407,9 +497,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.
 
@@ -441,8 +531,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;
@@ -513,7 +605,7 @@ 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 |
+| `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 |
@@ -541,10 +633,10 @@ that were running when it happened.
 
 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:
+kept too, with its stack. Read them with the agent's `plugins_logs` tool, or
+from a plugin with `ctx.host("plugins.logs", …)` for a card to show:
 `plugin`, `level` (that level and worse), `method`, `since`, `until`, `query`
 (a substring) and `limit` narrow it. The `plugins` tool shows each plugin's
 `errors` in the last hour. Lines older than 7 days go, and the oldest hours of
@@ -558,18 +650,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 may call, and `actions.*` (`git.status`, `chats.list`, `actions.run`, …); others fail with `FORBIDDEN`, and one that doesn't exist with `INTERNAL`. It's how a host read reaches a card, which can't call the host's methods itself |
 | `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.
@@ -650,7 +742,7 @@ customers: method(z.object({}), async (_, ctx) => {
 ```
 
 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 a `confirm`, or one
+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
@@ -674,7 +766,9 @@ 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
@@ -683,7 +777,7 @@ Events run in memory: none is retried, and a handler that throws is logged.
 (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 a read's fields with a read-only call. Do not execute writes just to
@@ -751,20 +845,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` never runs it: it gets the question back as a `CONFIRM` error and
-draws a button, and the user's tap asks. Ordinary `ctx.call` from plugin code skips
-it; an unattended workflow refuses confirmation-gated methods. A `destructive`
-method must have one. `{{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
 
@@ -776,12 +897,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 { Effect, HTTPAccess } 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;
@@ -79,9 +79,11 @@ export type ManifestMethod = {
     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;
@@ -139,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. */
@@ -177,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 read or write'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;

package/dist/define.d.ts

@@ -13,10 +13,16 @@ export type StreamDefinition = z.ZodType | {
 /**
  * What a method does. `read` only reads, so cards may run it on their own and
  * again when its data changes. `write` changes data, and runs only when the
- * user acts. `destructive` can't be undone, and must ask first (`confirm`).
+ * user acts. `destructive` can't be undone, and must ask first (`approve`).
  * Unmarked methods write: repeating one is never assumed safe.
  */
 export type Effect = "read" | "write" | "destructive";
+/**
+ * The chat's permission modes, strictest first, as RepoGo names them for every
+ * agent. `approveUpTo` names the least strict one a method still asks in.
+ */
+export declare const permissionModes: readonly ["approval-required", "auto-accept-edits", "full-access"];
+export type PermissionMode = (typeof permissionModes)[number];
 export type Method<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> = {
     input: I;
     /** What it returns; the agent and cards read field names from it. */
@@ -29,18 +35,34 @@ export type Method<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodT
      * The question asked before it runs, such as "Delete {{name}}?", filled from
      * its input; required for a destructive method. Methods without one run on tap.
      */
-    confirm?: string;
-    /** Who may call it at the environment's own address; unset, no one. */
-    http?: HTTPAccess;
+    approve?: string;
+    /**
+     * The least strict chat mode in which an agent's call still asks `approve`:
+     * it asks in that mode and every stricter one, and runs unasked in the rest.
+     * Unset is "full-access", every mode. A card's tap always asks.
+     */
+    approveUpTo?: PermissionMode;
+    /** Who may call it over HTTP, at each address; an address it doesn't name serves it to no one. */
+    http?: HTTPAddresses;
     /** Set by `cached`: the read answers from what it saved, and checks again when that's old. */
     cache?: CacheOptions;
     run: (input: z.infer<I>, ctx: Context) => unknown | Promise<unknown>;
 };
 /**
- * `key`: the host checks a key the caller sends. `none`: anyone reaches the
- * method, which checks the caller itself, such as a provider's signature.
+ * `key`: the caller sends the plugin's key as a bearer token, which the host
+ * checks before the method runs. `none`: anyone who reaches the address may call.
  */
 export type HTTPAccess = "key" | "none";
+/**
+ * `public`: the environment's own address, through the tunnel. `device`: this
+ * machine's loopback and its containers' gateway, where the network is the boundary.
+ */
+export type HTTPAddresses = {
+    device?: HTTPAccess;
+    public?: HTTPAccess;
+};
+/** `true` is `{ public: "key" }`. */
+export type HTTPOption = true | HTTPAddresses;
 export type Handler = (payload: any, ctx: Context) => unknown | Promise<unknown>;
 export type PluginDefinition = {
     /** One line, shown to the agent in the index of plugins. */
@@ -72,15 +94,14 @@ export declare function definePlugin<T extends PluginDefinition>(plugin: T): T;
 type MethodOptions<O extends z.ZodType> = {
     output?: O;
     description?: string;
-    http?: true | {
-        auth: HTTPAccess;
-    };
+    http?: HTTPOption;
+    approveUpTo?: PermissionMode;
 } & ({
     effect: "destructive";
-    confirm: string;
+    approve: string;
 } | {
     effect?: "read" | "write";
-    confirm?: string;
+    approve?: string;
 });
 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?: MethodOptions<O>): Method<I, O>;
 /**
@@ -97,6 +118,7 @@ export declare function cached<I extends z.ZodType, O extends z.ZodType = z.ZodT
     timeout?: Duration;
     output?: O;
     description?: string;
+    http?: HTTPOption;
 }): Method<I, O>;
 /**
  * A method that sends items as they happen: a log tail, a build's output. Each

package/dist/generated.d.ts

@@ -9,7 +9,7 @@ export type Generated = {
     description: string;
     input: z.ZodType;
     output?: z.ZodType;
-    confirm?: string;
+    approve?: string;
     run: (input: any, signal: AbortSignal) => unknown;
 };
 export declare function kvMethods(name: string, kv: Kv<any>, schema: z.ZodType): Record<string, Generated>;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { cached, definePlugin, method, stream } from "./define";
+export { remotePlugin } from "./remote";
 export { upload, type UploadedFile } from "./uploads";
-export type { PluginDefinition, Method, Effect, HTTPAccess, StreamDefinition } from "./define";
+export type { PluginDefinition, Method, Effect, PermissionMode, HTTPAccess, HTTPAddresses, HTTPOption, StreamDefinition } from "./define";
 export type { Activity, ActivityProgress, ActivityTimer, ActivityTint, AgentOptions, AgentReply, Caller, Context, CronEntry, CronStatus, Manifest, ManifestCron, ManifestMethod, ManifestStorage } from "./context";
 export type { LogLevel, LogRecord } from "./logs";
 export type { BucketFile, FileStatus, PutFile } from "./buckets";