@repogo/plugins 0.1.42 → 0.1.44

package/dist/define.d.ts

@@ -11,34 +11,58 @@ export type StreamDefinition = z.ZodType | {
     retain: Retain;
 };
 /**
- * A query only reads, so cards may run it on their own and again when its data
- * changes. A mutation writes, and runs only when the user acts. A stream only
- * reads too, and sends items as they happen for as long as someone watches.
- * Unmarked methods are mutations: repeating one is never assumed safe.
+ * 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 (`approve`).
+ * Unmarked methods write: repeating one is never assumed safe.
  */
-export type MethodKind = "query" | "mutation" | "stream";
+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. */
     output?: O;
-    kind: MethodKind;
+    effect: Effect;
+    /** Set by `stream`: a read that sends items as they happen. */
+    stream?: true;
     description?: string;
     /**
-     * For what can't be undone: the question a card's button asks before it
-     * runs, such as "Delete every item?". Methods without one run on tap.
+     * 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.
+     */
+    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.
      */
-    confirm?: string;
-    /** Who may call it at the environment's own address; unset, no one. */
-    http?: HTTPAccess;
-    /** Set by `cached`: the query answers from what it saved, and checks again when that's old. */
+    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. */
@@ -67,22 +91,26 @@ export type PluginDefinition = {
     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?: {
-    kind?: MethodKind;
+type MethodOptions<O extends z.ZodType> = {
     output?: O;
     description?: string;
-    confirm?: string;
-    http?: true | {
-        auth: HTTPAccess;
-    };
-}): Method<I, O>;
+    http?: HTTPOption;
+    approveUpTo?: PermissionMode;
+} & ({
+    effect: "destructive";
+    approve: string;
+} | {
+    effect?: "read" | "write";
+    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>;
 /**
- * A query that answers at once from what it saved last time, for answers that
+ * A read that answers at once from what it saved last time, for answers that
  * are slow to get: a CLI's list, another service's API. When the saved answer
  * is older than `fresh`, `run` goes again in the background, and cards showing
  * it redraw only if the answer changed. With nothing saved, the first call
  * waits for `run`. Each project keeps its own answers unless `shared`.
- * `run` is read-only, like a query's; it has `timeout` (a minute unless it says).
+ * `run` is read-only, like any read's; it has `timeout` (a minute unless it says).
  */
 export declare function cached<I extends z.ZodType, O extends z.ZodType = z.ZodType>(input: I, run: (input: z.infer<I>, ctx: Context) => unknown | Promise<unknown>, options: {
     fresh: Duration;
@@ -90,13 +118,15 @@ 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
  * `yield` is one item; a card shows them as a list that grows. It runs while
  * someone watches and `ctx.signal` aborts when the last one leaves, so pass it
- * on (`Bun.spawn(cmd, { signal: ctx.signal })`). Like a query, it may not write.
+ * on (`Bun.spawn(cmd, { signal: ctx.signal })`). Like any read, it may not write.
  */
 export declare function stream<I extends z.ZodType>(input: I, run: (input: z.infer<I>, ctx: Context) => AsyncIterable<unknown>, options?: {
     description?: string;
 }): Method<I>;
+export {};

package/dist/generated.d.ts

@@ -1,14 +1,15 @@
 import { z } from "zod";
 import type { Bucket } from "./buckets";
-import type { MethodKind } from "./define";
+import type { Effect } from "./define";
 import type { Kv } from "./kv";
 import type { Stream } from "./streams";
 export type Generated = {
-    kind: MethodKind;
+    effect: Effect;
+    stream?: true;
     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, MethodKind, 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";

package/dist/index.js

@@ -13,11 +13,12 @@ var __export = (target, all) => {
 // src/index.ts
 var exports_src = {};
 __export(exports_src, {
-  z: () => z3,
+  z: () => z4,
   workflow: () => workflow,
   upload: () => upload,
   toCallError: () => toCallError,
   stream: () => stream,
+  remotePlugin: () => remotePlugin,
   method: () => method,
   definePlugin: () => definePlugin,
   cached: () => cached,
@@ -43,45 +44,54 @@ function parseDuration(duration) {
 }
 
 // src/define.ts
+var permissionModes = ["approval-required", "auto-accept-edits", "full-access"];
+function httpAddresses(option) {
+  return option === true ? { public: "key" } : option;
+}
 function definePlugin(plugin) {
   return plugin;
 }
 function method(input, run, options = {}) {
+  if ("kind" in options)
+    throw new Error('method: kind is now effect: "read", "write" or "destructive"');
+  if ("confirm" in options)
+    throw new Error('method: confirm is now approve: "Delete {{id}}?"');
+  if (options.approveUpTo !== undefined && !permissionModes.includes(options.approveUpTo)) {
+    throw new Error(`method: approveUpTo is one of ${permissionModes.join(", ")}`);
+  }
+  if (options.approveUpTo !== undefined && !options.approve)
+    throw new Error("method: approveUpTo needs an approve question to ask");
   return {
     input,
     run,
-    kind: options.kind ?? "mutation",
+    effect: options.effect ?? "write",
     output: options.output,
     description: options.description,
-    confirm: options.confirm,
-    http: options.http === true ? "key" : options.http?.auth
+    approve: options.approve,
+    approveUpTo: options.approveUpTo,
+    http: httpAddresses(options.http)
   };
 }
 function cached(input, run, options) {
   return {
     input,
     run,
-    kind: "query",
+    effect: "read",
     output: options.output,
     description: options.description,
+    http: httpAddresses(options.http),
     cache: { fresh: parseDuration(options.fresh), shared: options.shared ?? false, timeout: parseDuration(options.timeout ?? "1m") }
   };
 }
 function stream(input, run, options = {}) {
-  return { input, run, kind: "stream", description: options.description };
-}
-// src/uploads.ts
-import { AsyncLocalStorage } from "async_hooks";
-import { z } from "zod";
-var callFiles = new AsyncLocalStorage;
-function upload() {
-  return z.object({ id: z.string(), name: z.string(), type: z.string(), size: z.number(), path: z.string() }).refine((file) => (callFiles.getStore() ?? []).some((held) => held.id === file.id && held.path === file.path), {
-    message: "Not a file uploaded for this call."
-  });
+  return { input, run, effect: "read", stream: true, description: options.description };
 }
-// src/errors.ts
+// src/remote.ts
 import { z as z2 } from "zod";
 
+// src/errors.ts
+import { z } from "zod";
+
 class MethodError extends Error {
   code;
   fieldErrors;
@@ -95,7 +105,7 @@ function toCallError(error) {
   if (error instanceof MethodError) {
     return { code: error.code, message: error.message, ...error.fieldErrors ? { fieldErrors: error.fieldErrors } : {} };
   }
-  if (error instanceof z2.ZodError) {
+  if (error instanceof z.ZodError) {
     const fieldErrors = {};
     for (const issue of error.issues)
       fieldErrors["/" + issue.path.join("/")] ??= issue.message;
@@ -106,8 +116,43 @@ function toCallError(error) {
   return { code: "INTERNAL", message: error instanceof Error ? error.message : String(error) };
 }
 
-// src/index.ts
+// src/remote.ts
+var codes = { 400: "VALIDATION", 403: "FORBIDDEN", 404: "NOT_FOUND" };
+async function remotePlugin(url, name) {
+  const base = `${url.replace(/\/$/, "")}/${name}`;
+  const response = await fetch(base);
+  if (!response.ok)
+    throw new Error(`remotePlugin: ${base} answered ${response.status}`);
+  const listing = await response.json();
+  const methods = {};
+  for (const m of listing.methods) {
+    methods[m.name] = method(z2.fromJSONSchema(m.input), (input) => call(`${base}/${m.name}`, input), {
+      effect: m.effect,
+      description: m.description ?? undefined,
+      output: m.output ? z2.fromJSONSchema(m.output) : undefined
+    });
+  }
+  return { description: listing.description ?? undefined, methods };
+}
+async function call(url, input) {
+  const response = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(input) });
+  const answer = await response.json().catch(() => null);
+  if (response.ok)
+    return answer;
+  throw new MethodError(codes[response.status] ?? "INTERNAL", answer?.error ?? `${url} answered ${response.status}`, answer?.fields ?? undefined);
+}
+// src/uploads.ts
+import { AsyncLocalStorage } from "async_hooks";
 import { z as z3 } from "zod";
+var callFiles = new AsyncLocalStorage;
+function upload() {
+  return z3.object({ id: z3.string(), name: z3.string(), type: z3.string(), size: z3.number(), path: z3.string() }).refine((file) => (callFiles.getStore() ?? []).some((held) => held.id === file.id && held.path === file.path), {
+    message: "Not a file uploaded for this call."
+  });
+}
+
+// src/index.ts
+import { z as z4 } from "zod";
 
 // src/workflow/scope.ts
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
@@ -136,15 +181,16 @@ class NonRetryable extends Error {
   }
 }
 export {
-  z3 as z,
+  z4 as z,
   workflow,
   upload,
   toCallError,
   stream,
+  remotePlugin,
   method,
   definePlugin,
   cached,
   NonRetryable,
   MethodError
 };
-export { parseDuration, callFiles, MethodError, toCallError, attemptScope, workflowScope, workflowContext, exports_src };
+export { parseDuration, MethodError, toCallError, callFiles, attemptScope, workflowScope, workflowContext, exports_src };

package/dist/remote.d.ts

@@ -0,0 +1,7 @@
+import { type PluginDefinition } from "./define";
+/**
+ * A plugin whose methods run on another host: each method `name` opens to
+ * `device` at `url` (such as http://192.168.64.1:47444), with its schemas, as
+ * a request there. That host keeps the plugin's code, keys and data.
+ */
+export declare function remotePlugin(url: string, name: string): Promise<PluginDefinition>;

package/dist/runtime.d.ts

@@ -2,17 +2,19 @@ import { z } from "zod";
 import { type Schedule } from "./cron";
 import type { Caller, CronEntry, CronStatus, Manifest, Notice } from "./context";
 export type { Manifest, ManifestCron, ManifestMethod } from "./context";
-import type { HTTPAccess, PluginDefinition, MethodKind } from "./define";
+import type { Effect, HTTPAddresses, PermissionMode, PluginDefinition } from "./define";
 import { EventBus } from "./events";
 import type { WorkflowBridge } from "./workflow/contracts";
 import { type UploadedFile } from "./uploads";
 export type RegisteredMethod = {
     name: string;
     plugin: string;
-    kind: MethodKind;
+    effect: Effect;
+    stream?: true;
     description?: string;
-    confirm?: string;
-    http?: HTTPAccess;
+    approve?: string;
+    approveUpTo?: PermissionMode;
+    http?: HTTPAddresses;
     input: z.ZodType;
     output?: z.ZodType;
     /** `raw` is the input as sent, before defaults filled it in. */
@@ -35,9 +37,11 @@ type NoticeListener = (notice: SentNotice) => void;
 export type HostCaller = (plugin: string, method: string, params: unknown) => Promise<unknown>;
 /** A schedule as the runtime keeps it: read once, with its last run. */
 type CronJob = {
-    /** The plugin, method, schedule and zone: an entry the host sends again keeps its job, and its state. */
+    /** The plugin, method, schedule, zone and root: an entry the host sends again keeps its job, and its state. */
     signature: string;
     plugin: string;
+    /** The project the run gets as `ctx.root`; none keeps the Worker's own. */
+    root?: string;
     /** `<plugin>.<method>`. */
     method: string;
     schedule: string;
@@ -71,11 +75,11 @@ export declare class Runtime {
     private constructor();
     /** The caller's project while a call runs, for plugins that serve every project. */
     private callRoot;
-    /** A running stream's signal, `ctx.signal` to the code it runs. */
+    /** A running stream's or cancelable call's signal, `ctx.signal` to the code it runs. */
     private callSignal;
     /** Who started the outermost call, `ctx.caller` to the code it runs. */
     private callCaller;
-    /** Whether the user answered a `confirm` for this call or one it runs within, which a destructive MCP tool needs. */
+    /** Whether the user answered an `approve` for this call or one it runs within, which a destructive MCP tool needs. */
     private callConfirmed;
     /** Read through `ctx.plugins()` and written as each cron run starts and ends; this runtime's own, so other Workers aren't stirred. */
     private cronsTag;
@@ -98,9 +102,9 @@ export declare class Runtime {
         caller: Caller;
     }): Promise<unknown>;
     /**
-     * Calls a method and reports what it read and wrote. `expect: "query"` is how
+     * Calls a method and reports what it read and wrote. `expect: "read"` is how
      * a card runs a method on its own: it refuses anything that might write, and
-     * so does everything the query calls.
+     * so does everything the read calls.
      */
     /**
      * `confirmed` is false for a tap the user hasn't answered; `ctx.call` leaves it out.
@@ -108,12 +112,13 @@ export declare class Runtime {
      * pass on to the code the method calls.
      */
     call(name: string, input?: unknown, options?: {
-        expect?: MethodKind;
+        expect?: "read";
         confirmed?: boolean;
         root?: string;
         caller?: Caller;
         chat?: string;
         files?: UploadedFile[];
+        signal?: AbortSignal;
     }): Promise<CallResult>;
     /**
      * Runs a stream method, passing each item it yields to `onItem` until it

package/dist/testing.d.ts

@@ -41,7 +41,7 @@ export type TestMCP = (call: TestMCPCall) => unknown;
 /** Stands in for the host's methods (`chats.start`, `git.status`, …) behind `ctx.host` and `ctx.agent`; throw a MethodError to refuse. */
 export type TestHost = (method: string, params: unknown) => unknown;
 /**
- * `const app = await testRuntime({ notes })`, then `await app.call("notes.add", { text: "hi" })`.
+ * `const app = await testRuntime({ notes })`, then `await app.call("notes.notes.create", { text: "hi" })`.
  * `ctx.root` is an empty temporary folder unless `root` names a fixture project;
  * `mcp` answers `ctx.mcp`, `host` the other host methods. Console lines still print.
  */