@repogo/plugins 0.1.34 → 0.1.35

package/README.md

@@ -10,10 +10,12 @@ phone draw its data live and run its methods when you tap.
 - [Methods](#methods): queries, mutations, streams
 - [Data](#data): namespaces, collections, kv, streams, buckets
 - [Crons](#crons)
+- [Logging](#logging)
 - [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)
+- [Testing](#testing)
 
 ## Quick start
 
@@ -62,9 +64,9 @@ 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.
+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.
 
 ## Methods
 
@@ -125,8 +127,9 @@ plugin, another plugin, or another project.
 
 `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.
+buckets' files. A plugin that keeps data (any collection, kv, stream or bucket)
+must name one, or it fails to load. 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
@@ -145,10 +148,14 @@ await ctx.collections.tasks.get(task.id);                                // or n
 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);
+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 (up to 500).
 `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
+deletes exactly what `list` would return, in one transaction, returning how many.
 
 ### Kv
 
@@ -265,28 +272,64 @@ 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.
 
+Data named in `private` gets none of these, so cards and agents reach it only
+through the plugin's own methods: `private: ["actions", "lines"]` for an audit
+log no tap can edit. It hides methods; it isn't a lock. Another plugin naming
+the same namespace and store can still read and write it.
+
 ## 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" },
-  ],
-});
+What runs with no one looking is listed in one file the user owns,
+`~/.repogo/crons.json`, not in a plugin's code: a repo you clone can't schedule
+itself. Each line names a plugin, one of its methods and a schedule:
+
+```json
+[
+  { "plugin": "incidents", "method": "watch", "schedule": "*/5 * * * *" },
+  { "project": "~/code/shop", "plugin": "backup", "method": "run", "schedule": "0 3 * * *", "timezone": "America/New_York" },
+  { "plugin": "digest", "method": "send", "schedule": "0 9 * * 1-5", "enabled": false }
+]
 ```
 
-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.
+| 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` |
+| `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 |
+
+The host reads the file every minute, and again when the agent's `plugins` tool
+lists what's there, so an edit shows at once. A folder opened only for its
+schedules imports just the plugins they name; the others beside them don't run.
+A line removed or disabled is never started again; a run already going finishes.
 
 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`.
+is skipped, and nothing is retried. A line naming something missing, a stream, a
+method that needs input or asks first, a bad schedule, or the same method twice
+says why in `plugins` (each line's `error`), and the others run. A file that
+isn't valid JSON pauses every line until it's fixed. Each line also shows
+`nextRunAt`, `lastRunAt`, `lastError`, `lastDurationMs` and `runs`; `ctx.plugins()`
+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.
+
+## 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
+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 `plugin_logs` tool, or on
+a card with `<Data method="repogo:plugins.logs">`, which reloads as lines land:
+`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
+the noisiest plugin once the log passes 2 GB. A line is cut at 8 KB: a payload
+belongs in the plugin's own data, not its log.
 
 ## The context
 
@@ -295,18 +338,63 @@ Every method, handler and cron gets `ctx`:
 | Field | What |
 | --- | --- |
 | `plugin` | The plugin's name |
+| `caller` | Who started the call: `card`, `agent`, `cron`, or `code` |
 | `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` |
+| `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?, collapse? })` | Alerts every paired phone; a tap opens `page`, and alerts sharing `collapse` replace each other |
+| `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 |
-| `log(...)` | Writes to the host's plugin log |
+| `log(...)` | The same as `console.log` |
 
 A query doesn't re-run when what a `ctx.host` method read changes.
 
+### An agent's answer
+
+`ctx.agent` hands a question to Claude or Codex and answers with what it said,
+so a cron can watch, investigate and notify with the finding:
+
+```ts
+watch: method(z.object({}), async (_, ctx) => {
+  const down = await failing(ctx);
+  if (!down.length) return null;
+  const { text, chatId } = await ctx.agent(`Say in two sentences why ${down[0]} is down.`, { agent: "claude" });
+  await ctx.notify({ title: `${down[0]} is down`, body: text, page: `chat:${chatId}` });
+  return text;
+}),
+```
+
+The chat runs in `project` (the calling project unless said), under the
+calling chat when an agent called the plugin. It waits up to `timeout`
+(10 minutes unless said) and then throws, naming the chat, which keeps
+running. The same two host methods are there by hand: `ctx.host("chats.start", …)`
+and `ctx.host("chats.wait", …)`, for a chat you want to link to rather than wait for.
+
+### MCP servers
+
+`ctx.mcp` reaches the MCP servers the user connected in RepoGo, by the key
+cards name them with, using the user's own sign-in, so a plugin needs no key
+or CLI of its own. It answers the tool's structured content, else its text
+(parsed when it's JSON):
+
+```ts
+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" }),
+```
+
+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
+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
+environment plugin, whose root is the home folder, reaches none.
+
 ## Events
 
 Handlers in `on` run after the events they name:
@@ -330,8 +418,12 @@ 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
+**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
+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
+folder), the pages that show its methods, and the cron lines naming it.
 `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
@@ -359,4 +451,26 @@ schema answers `VALIDATION` with a message per field. Anything else thrown is
 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.
+it. 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}}?"`.
+
+## Testing
+
+`@repogo/plugins/testing` runs plugins as the host does, with real data in a
+temporary folder; `host` and `mcp` stand in for the host's methods and the
+user's MCP servers:
+
+```ts
+import { testRuntime } from "@repogo/plugins/testing";
+import notes from "./app";
+
+const app = await testRuntime({ notes });
+await app.call("notes.add", { 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
+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
+await app.close();
+```

package/dist/collections.d.ts

@@ -8,9 +8,12 @@ export type Record_<T> = T & {
 };
 export type ListOptions = {
     where?: Record<string, string | number | boolean | null>;
-    orderBy?: "createdAt" | "updatedAt";
+    /** `id`, `createdAt`, `updatedAt`, or one of the record's own top-level fields. */
+    orderBy?: "createdAt" | "updatedAt" | (string & {});
     order?: "asc" | "desc";
     limit?: number;
+    /** Records to pass over first, in the same order: `offset: 300` is everything past the newest 300. */
+    offset?: number;
 };
 export declare class Collection<S extends z.ZodObject> {
     private database;
@@ -28,6 +31,13 @@ export declare class Collection<S extends z.ZodObject> {
     update(id: string, patch: Partial<z.input<S>>): Promise<Record_<z.infer<S>>>;
     delete(id: string): Promise<void>;
     list(options?: ListOptions): Promise<Record_<z.infer<S>>[]>;
+    /**
+     * Deletes the records `list(options)` would return, with its same defaults,
+     * in one transaction, and returns how many. Each emits its `deleted` event.
+     */
+    deleteMany(options?: ListOptions): Promise<number>;
+    /** The query `list` and `deleteMany` share, so both pick out the same records. */
+    private select;
     private eventName;
     private toRecord;
 }

package/dist/context.d.ts

@@ -3,6 +3,7 @@ import type { Collection } from "./collections";
 import type { Kv } from "./kv";
 import type { Stream } from "./streams";
 import type { MethodKind } 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;
@@ -32,6 +33,8 @@ export type ManifestCron = {
     nextRunAt: number | null;
     lastRunAt: number | null;
     lastError: string | null;
+    /** How long its last run took: a run far past its interval blocked or waited on something. */
+    lastDurationMs: number | null;
     running: boolean;
     runs: number;
 };
@@ -49,6 +52,21 @@ export type ManifestStorage = {
         path: string;
     }[];
 };
+/**
+ * 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).
+ */
+export type CronEntry = {
+    plugin: string;
+    method: string;
+    schedule: string;
+    timezone?: string;
+};
+/** A schedule and how it's going; `error` says why it couldn't be set, and then nothing runs. */
+export type CronStatus = ManifestCron & {
+    plugin: string;
+    error: string | null;
+};
 export type Manifest = {
     plugins: {
         name: string;
@@ -58,8 +76,27 @@ 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";
+/** 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. */
+    agent: string;
+    /** The project the chat runs in; the calling project unless said. */
+    project?: string;
+    title?: string;
+    /** How long to wait for the answer; 10 minutes unless said. */
+    timeout?: Duration;
+};
+/** What the agent answered, and the chat it answered in, to open or message later. */
+export type AgentReply = {
+    chatId: string;
+    text: string;
+};
 export type Context = {
     plugin: string;
+    /** Who started the outermost call; `ctx.call` passes it on. */
+    caller: Caller;
     /** The project's checkout, for a plugin that reads the project's files. */
     root: string;
     collections: Record<string, Collection<any>>;
@@ -73,6 +110,13 @@ export type Context = {
      * `ctx.host("git.status", { path: ctx.root })`. Its answer doesn't re-run a query.
      */
     host: (method: string, params?: unknown) => Promise<unknown>;
+    /**
+     * 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.
+     */
+    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.
@@ -82,5 +126,12 @@ export type Context = {
     signal: AbortSignal;
     /** Sends an alert to every phone paired with this environment. */
     notify: (notice: Notice) => void;
+    /**
+     * Starts a chat with `prompt` and waits for the agent's whole answer:
+     * `await ctx.agent("Why is the build failing?", { agent: "claude" })`.
+     * Throws once `timeout` passes, naming the chat, which keeps running.
+     */
+    agent: (prompt: string, options: AgentOptions) => Promise<AgentReply>;
+    /** The same as `console.log`: every console line is kept with the plugin and the call that wrote it. */
     log: (...args: unknown[]) => void;
 };

package/dist/cron.d.ts

@@ -0,0 +1,21 @@
+export type Schedule = {
+    seconds: Set<number> | null;
+    minutes: Set<number>;
+    hours: Set<number>;
+    days: Set<number>;
+    months: Set<number>;
+    weekdays: Set<number>;
+    /** Day fields given as other than `*`, for cron's either-day rule. */
+    daysRestricted: boolean;
+    weekdaysRestricted: boolean;
+};
+/** Reads a schedule, or throws saying what's wrong with it. */
+export declare function parseSchedule(source: string): Schedule;
+/** Throws unless `zone` is a time zone this machine knows, such as "America/New_York". */
+export declare function checkTimezone(zone: string): void;
+/**
+ * The first due time strictly after `after` (ms), in `zone`, or null when there
+ * is none within four years (`0 0 31 2 *`). A wall time that a fall-back night
+ * shows twice is due only the first time.
+ */
+export declare function nextDue(s: Schedule, after: number, zone: string): number | null;

package/dist/define.d.ts

@@ -28,23 +28,13 @@ 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;
     /**
      * 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
+     * data. Required once the plugin keeps data; by convention a project's own is
      * `<project>.<name>` (`repogo.plans`) and data for every project a bare name (`todos`).
      */
     namespace?: string;
@@ -57,7 +47,11 @@ export type PluginDefinition = {
     streams?: Record<string, StreamDefinition>;
     methods?: Record<string, Method<any, any>>;
     on?: Record<string, Handler>;
-    crons?: Cron[];
+    /**
+     * Data named here gets no generated methods (list, create, delete…), so cards
+     * and agents reach it only through the plugin's own: an audit log, say.
+     */
+    private?: string[];
 };
 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/generated.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { Bucket } from "./buckets";
+import type { MethodKind } from "./define";
+import type { Kv } from "./kv";
+import type { Stream } from "./streams";
+export type Generated = {
+    kind: MethodKind;
+    description: string;
+    input: z.ZodType;
+    output?: z.ZodType;
+    confirm?: string;
+    run: (input: any, signal: AbortSignal) => unknown;
+};
+export declare function kvMethods(name: string, kv: Kv<any>, schema: z.ZodType): Record<string, Generated>;
+export declare function streamMethods(name: string, stream: Stream<any>, schema: z.ZodType): Record<string, Generated>;
+export declare function bucketMethods(name: string, bucket: Bucket<any>, schema: z.ZodObject): Record<string, Generated>;

package/dist/index-83w1fk10.js

@@ -0,0 +1,28 @@
+// src/errors.ts
+import { z } from "zod";
+
+class MethodError extends Error {
+  code;
+  fieldErrors;
+  constructor(code, message, fieldErrors) {
+    super(message);
+    this.code = code;
+    this.fieldErrors = fieldErrors;
+  }
+}
+function toCallError(error) {
+  if (error instanceof MethodError) {
+    return { code: error.code, message: error.message, ...error.fieldErrors ? { fieldErrors: error.fieldErrors } : {} };
+  }
+  if (error instanceof z.ZodError) {
+    const fieldErrors = {};
+    for (const issue of error.issues)
+      fieldErrors["/" + issue.path.join("/")] ??= issue.message;
+    const messages = Object.values(fieldErrors);
+    const message = messages.length === 1 ? messages[0] : "Check the highlighted fields.";
+    return { code: "VALIDATION", message, fieldErrors };
+  }
+  return { code: "INTERNAL", message: error instanceof Error ? error.message : String(error) };
+}
+
+export { MethodError, toCallError };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { definePlugin, method, stream } from "./define";
-export type { PluginDefinition, Method, MethodKind, Cron, StreamDefinition } from "./define";
-export type { Context, Manifest, ManifestCron, ManifestMethod, ManifestStorage } from "./context";
+export type { PluginDefinition, Method, MethodKind, StreamDefinition } from "./define";
+export type { 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";
 export type { KvEntry, SetOptions } from "./kv";
 export type { Retain, StreamEntry, StreamKey } from "./streams";

package/dist/index.js

@@ -1,4 +1,9 @@
 // @bun
+import {
+  MethodError,
+  toCallError
+} from "./index-83w1fk10.js";
+
 // src/define.ts
 function definePlugin(plugin) {
   return plugin;
@@ -16,37 +21,11 @@ function method(input, run, options = {}) {
 function stream(input, run, options = {}) {
   return { input, run, kind: "stream", description: options.description };
 }
-// src/errors.ts
-import { z } from "zod";
-
-class MethodError extends Error {
-  code;
-  fieldErrors;
-  constructor(code, message, fieldErrors) {
-    super(message);
-    this.code = code;
-    this.fieldErrors = fieldErrors;
-  }
-}
-function toCallError(error) {
-  if (error instanceof MethodError) {
-    return { code: error.code, message: error.message, ...error.fieldErrors ? { fieldErrors: error.fieldErrors } : {} };
-  }
-  if (error instanceof z.ZodError) {
-    const fieldErrors = {};
-    for (const issue of error.issues)
-      fieldErrors["/" + issue.path.join("/")] ??= issue.message;
-    const messages = Object.values(fieldErrors);
-    const message = messages.length === 1 ? messages[0] : "Check the highlighted fields.";
-    return { code: "VALIDATION", message, fieldErrors };
-  }
-  return { code: "INTERNAL", message: error instanceof Error ? error.message : String(error) };
-}
 
 // src/index.ts
-import { z as z2 } from "zod";
+import { z } from "zod";
 export {
-  z2 as z,
+  z,
   toCallError,
   stream,
   method,

package/dist/logs.d.ts

@@ -0,0 +1,55 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Caller } from "./context";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogRecord = {
+    /** ms since the epoch. */
+    at: number;
+    plugin: string;
+    level: LogLevel;
+    /** `<plugin>.<method>` of the run the line was written in; empty outside a run. */
+    method: string;
+    caller: Caller | "";
+    /** One id per outermost call, so a call's lines read together. */
+    callId: string;
+    /** The chat whose agent made the call, for `caller: "agent"`. */
+    chatId: string;
+    /** The arguments formatted as the console prints them, at most `textLimit` characters. */
+    text: string;
+    /** The arguments as given, as JSON can carry them. */
+    data: unknown[];
+};
+/** What a line is attributed to: the plugin, and the run when there is one. */
+export type LogContext = {
+    plugin: string;
+    method?: string;
+    caller?: Caller;
+    callId?: string;
+    chatId?: string;
+};
+/** The run the code writing a line is in; the runtime sets it around every method, handler and cron. */
+export declare const logContext: AsyncLocalStorage<LogContext>;
+/**
+ * Runs `work` as an outermost run under `context`. An error nothing catches
+ * reaches its handler with no async context, so the newest run going is the
+ * best guess at whose it is.
+ */
+export declare function runWith<T>(context: LogContext, work: () => Promise<T>): Promise<T>;
+/** A line longer than this is cut: a dumped payload is read in the plugin's own data, not its log. */
+export declare const textLimit: number;
+type Sink = (record: LogRecord) => void;
+/**
+ * Replaces `console.log`, `info`, `debug`, `warn` and `error` with ones that
+ * record each call. `passThrough` keeps printing them too, for tests.
+ */
+export declare function captureConsole(to: Sink, options?: {
+    passThrough?: boolean;
+}): void;
+/** Puts the console back and stops recording. */
+export declare function releaseConsole(): void;
+/**
+ * Records one line under `context`, else the current run, else the newest run
+ * going, as an error nothing caught lands in. With no capture installed the
+ * line prints as the console would.
+ */
+export declare function record(level: LogLevel, args: unknown[], context?: LogContext): void;
+export {};