@repogo/plugins 0.1.35 → 0.1.37

package/README.md

@@ -7,8 +7,9 @@ phone draw its data live and run its methods when you tap.
 
 - [Quick start](#quick-start)
 - [Where plugins live](#where-plugins-live)
-- [Methods](#methods): queries, mutations, streams
-- [Data](#data): namespaces, collections, kv, streams, buckets
+- [Methods](#methods): queries, mutations, streams, cached queries
+- [Data](#data): namespaces, collections, kv, streams, buckets, uploads
+- [Workflows](#workflows)
 - [Crons](#crons)
 - [Logging](#logging)
 - [The context](#the-context)
@@ -90,6 +91,18 @@ show it and keep it current. Give each a `description`; agents read it to choose
 a method. `output`, a zod schema of the result, tells agents and cards its
 field names.
 
+A query that returns a list takes `limit`, with a default and a maximum in its
+schema, and returns only what a card or the voice agent shows of each item:
+ids, titles, status. A `get` returns one in full, and long text (a body, a log)
+is cut short in the list. Answers stay small, so cards draw fast and an agent
+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" }),
+```
+
 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
@@ -107,6 +120,27 @@ tail: stream(z.object({ file: z.string() }), async function* ({ file }, ctx) {
 }),
 ```
 
+A **cached** query is for answers that are slow to get, such as a CLI's list
+or another service's API. It answers at once with what it saved last time.
+When that answer is older than `fresh`, `run` goes again in the background,
+and a card showing it redraws only if the answer changed. With nothing saved
+yet, the first call waits for `run`, and its error is the card's.
+
+```ts
+projects: cached(z.object({ limit: z.number().int().min(1).max(200).default(100) }),
+  async ({ limit }) => listProjects(limit),
+  { fresh: "1m", shared: true, description: "Every project the login can see" }),
+```
+
+- 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).
+- 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.
+
 ## Data
 
 A plugin declares its data in four kinds, each with a schema, and gets typed
@@ -255,6 +289,37 @@ checks it against the schema; with `revision`, it fails if the file changed
 since you read it. Writes through `ctx` are checked; files written by hand are
 indexed with their `status` instead.
 
+### Uploads
+
+A card's `<Upload>` lets the user take a photo, record a video, or pick
+photos or files on their phone, and hands them to one of your methods as
+`files`. Declare the field with `upload()`:
+
+```ts
+import { definePlugin, method, upload, z } from "@repogo/plugins";
+
+ingest: method(z.object({ files: z.array(upload()), month: z.string() }), async ({ files, month }, ctx) => {
+  for (const file of files) {
+    await ctx.buckets.receipts.put({ body: Bun.file(file.path), name: file.name, folder: month });
+  }
+  return { added: files.length };
+}),
+```
+
+Each file is `{ id, name, type, size, path }`. `type` is its MIME type, and
+`path` is where the host staged it on the environment. The phone sends the
+bytes before the call, encrypted like every call, and the call starts once
+they've all arrived. A staged file is deleted a day after its last use, so
+copy what you keep: into a bucket, as above, or wherever you like. `files` is
+always an array, even for one file.
+
+`upload()` accepts only files the host attached to the running call. Input
+written by hand, such as an agent's `plugin_call` with a made-up `path`, fails
+validation, and so does a call that sends its own `files` alongside the
+upload's. A method the upload's method calls with `ctx.call` may pass the
+files on. In tests, `app.call("receipts.ingest", { month: "may" }, { files })`
+stands in for the host.
+
 ### Generated methods
 
 Every collection, kv, stream and bucket gets methods named
@@ -277,6 +342,140 @@ 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.
 
+## Workflows
+
+> **Experimental.** Workflows are new and may change in ways that need edits
+> to your plugins: their methods, statuses and options aren't settled yet.
+
+A workflow keeps progress across host restarts. Define it beside `methods`;
+`workflow(input, run, options)` follows the same shape as `method`:
+
+```ts
+import { definePlugin, workflow, z } from "@repogo/plugins";
+
+export default definePlugin({
+  namespace: "myproject.reports",
+  workflows: {
+    report: workflow(z.object({ url: z.url() }), async ({ url }, ctx) => {
+      const report = await ctx.step.run("fetch", async ({ signal }) => {
+        const response = await fetch(url, { signal });
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        return { title: await response.text() };
+      }, { kind: "query", attempts: 3, timeout: "30s" });
+
+      await ctx.sleep("5m");
+
+      return await ctx.step.run("save", async () => {
+        await ctx.kv.reports.set("latest", report);
+        return report;
+      });
+    }, { timeout: "30d", maxOffline: "14d", retention: "30d" }),
+  },
+  kv: { reports: z.object({ title: z.string() }) },
+});
+```
+
+For a plugin folder named `reports`, the host generates:
+
+- `reports.report.list({ limit?, status?, cursor? })`: bounded summaries and a next cursor.
+- `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.
+- `reports.report.cancelAll({ status? })`: cancel every unfinished run in the project, or only those in one status; returns `{ cancelled }`.
+- `reports.report.retry({ id })`: retry a safely failed query step.
+- `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;
+it does not preapprove later host actions. An unattended workflow refuses
+confirmation-gated plugin methods. 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.
+
+Await each step and use a unique, stable name. Keep effects inside step callbacks:
+the handler runs from the beginning after recovery, and completed callbacks
+return their recorded JSON instead of running again. Steps are sequential;
+nesting, overlap and reusing a name fail the run. Return JSON, including an
+explicit `null` for a step with no result. Large payloads belong in buckets;
+a journal record is limited to 1 MiB, a run journal to 64 MiB. `get` omits
+input or final results above 16 KiB and sets their truncation flags.
+
+Use `await ctx.sleep("5m")` between steps for a durable wait. No ID is needed:
+the runner identifies each sleep by its position among the workflow's operations.
+It saves an absolute wake time, releases the executor, and resumes without
+repeating completed steps. Loops and consecutive sleeps each get a separate
+position. The first recorded duration wins on replay, even when the expression
+that supplied it later changes. Durations follow the SDK convention (strings
+like `"5m"` or milliseconds), must be positive, and cannot exceed 365 days.
+
+Always await sleep at the workflow level, outside step callbacks; do not catch
+its internal waiting signal or detach background workflow operations. Branch
+using recorded step results so replay follows the same operation order.
+The original run timeout and `maxOffline` still apply during sleep. A sleep
+past the run deadline expires at that deadline; an unavailable environment
+resumes only when available and within those limits. `list`/`get` show
+`waiting` with `nextAttemptAt` as the wake time, and detail rows identify sleeps
+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.
+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;
+a callback must settle before another attempt can begin.
+
+Mutation steps get one attempt. An interrupted or timed-out mutation becomes
+`unknown`: its external effect may have happened, and it is never automatically
+repeated. Reconcile that effect before starting new work. Cancellation cannot
+roll back remote effects. Manual retry only extends the budget of a failed
+query, keeps its completed prefix and original lifetime, and rejects cancelled,
+expired, unknown, permanent-failure and invalid-result runs.
+
+### When you edit a workflow
+
+A run always executes the plugin's current code, loaded from its folder as a
+method call is; nothing is frozen at start. When a run resumes after an edit,
+its finished steps still return their recorded results, so:
+
+- An edit that keeps the recorded steps in the same order, such as a fix
+  inside a step or a new step at the end, carries on with the new code.
+- An edit the recorded steps can't follow, such as a renamed, removed or
+  reordered step, stops the run in `attention`: not finished, and not run
+  again on its own. Its `error` says which step it expected. `restart` starts
+  it over on the current code, running finished steps again, with the same id,
+  key and input and a fresh `timeout`. `cancel` or
+  `cancelAll({ status: "attention" })` drops it.
+
+Nested workflow starts from inside a run are not supported.
+
+The host resumes work without an open phone or page. `timeout` is a wall-clock
+run lifetime, including waits. `maxOffline` expires work when the environment
+or workflow service has been unavailable for that long. A persistent network
+outage is also tracked when the environment has no nonlocal network address;
+this passive check does not probe external services or prove internet access.
+Individual API failures use the step's retry budget. The host records expiry on its next wake.
+Shutdown suspends work without recording user cancellation. A finished run's
+journal stays until its `retention` passes. Admission refuses new runs above
+its storage budget rather than evicting active history. Missing or corrupt
+journals block execution. The default environment-wide budget is 512 MiB.
+Each unfinished, blocked or attention run reserves 130 MiB for its journal and
+one snapshot of its state, including while sleeping. This admits at most three
+unfinished runs, fewer when retained history consumes the remaining space;
+admission reports storage full. Checkpoint replacement temporarily keeps both
+snapshots, so peak disk use can exceed that reservation. The admission budget
+is not a free-disk guarantee.
+
+For integration tests, import `testWorkflowRuntime` from
+`@repogo/plugins/testing` and pass the fixture's plugins directory. It uses real
+temporary storage and a subprocess per run, as the host does. Call the same lifecycle methods,
+use `await app.wait("reports.report", id)` to await a terminal/blocked run, and
+`await app.close()` afterward. The in-memory `testRuntime({ plugin })` helper
+does not execute durable workflows.
+
+
 ## Crons
 
 What runs with no one looking is listed in one file the user owns,
@@ -345,7 +544,8 @@ Every method, handler and cron gets `ctx`:
 | `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 |
+| `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 |
@@ -374,6 +574,46 @@ calling chat when an agent called the plugin. It waits up to `timeout`
 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.
 
+### Live Activities
+
+`ctx.activity` puts a card on the Lock Screen and in the Dynamic Island.
+Its `title`, `body` and `page` are a notice's, and the plugin sets
+everything else too. Send the whole state each time: the same `id` updates
+it, a field left out takes its default, and `status: "done"` or `"failed"`
+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 show = (current: number, body: string) =>
+    ctx.activity({ id: `deploy:${project}`, title: `Deploying ${project}`, body, page,
+      symbol: "shippingbox", progress: { kind: "steps", steps, current } });
+  await show(0, "Building");
+  // …
+  await ctx.activity({ id: `deploy:${project}`, title: `${project} is live`, body: "web.app", page,
+    status: "done", symbol: "globe", tint: "blue", label: "Live",
+    progress: { kind: "steps", steps, current: steps.length } });
+}),
+```
+
+| Field | Unless said |
+| --- | --- |
+| `body` | No line under the title |
+| `page` | A tap opens the app |
+| `symbol` | `circle.dotted`; a check once done, a cross once failed |
+| `tint` | White; green once done, red once failed |
+| `label` | "2 of 4", "40%", "Done" or "Failed"; `""` hides it |
+| `compactLabel` | The `label`, else "2/4" or "40%" |
+| `progress` | None. `{ kind: "steps", steps, current }` draws a segment per step, the ones before `current` complete; `{ kind: "bar", value }` a bar from 0 to 1 |
+| `timer` | `{ kind: "elapsed" }` from the first start. `{ kind: "countdown", endsAt }` counts down to a Unix ms time and ends nothing; `{ kind: "none" }` hides it |
+
+- The phones get the latest state at most every 5 seconds; a start and an end go at once.
+- A state that comes to more than Apple's 4 KB as a push is refused.
+- A plugin shows at most two at once; one left without an update for an hour stops counting.
+- A query can't call it, as it can't write.
+- The text reaches Apple and RepoGo's relay as is, as a `notify` alert's does: keep secrets out of it.
+
 ### MCP servers
 
 `ctx.mcp` reaches the MCP servers the user connected in RepoGo, by the key

package/dist/cache.d.ts

@@ -0,0 +1,27 @@
+import type { Database } from "./database";
+/** How a `cached` method keeps its answers: fresh for this long, shared by every project or not. */
+export type CacheOptions = {
+    fresh: number;
+    shared: boolean;
+    timeout: number;
+};
+export declare class AnswerCache {
+    private database;
+    private namespace;
+    private announce;
+    /** One fetch per key at a time; a card and a background check share it. */
+    private inflight;
+    constructor(database: Database, namespace: string, announce: (tags: string[]) => void);
+    setup(): Promise<void>;
+    /**
+     * The saved answer at once, checked again in the background when it's
+     * older than `fresh`. With none saved, the caller waits for the fetch.
+     */
+    read(key: string, options: CacheOptions, fetch: () => unknown): Promise<unknown>;
+    /** Settles once no fetch is out. */
+    idle(): Promise<void>;
+    private refresh;
+    private save;
+}
+/** A key for one answer: the method, the project unless it's shared, and the input with its keys sorted. */
+export declare function cacheKey(method: string, root: string | null, input: unknown): string;

package/dist/context.d.ts

@@ -2,7 +2,7 @@ import type { Bucket } from "./buckets";
 import type { Collection } from "./collections";
 import type { Kv } from "./kv";
 import type { Stream } from "./streams";
-import type { MethodKind } from "./define";
+import type { HTTPAccess, 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 = {
@@ -10,9 +10,66 @@ export type Notice = {
     body: string;
     /** A page target, `.repogo/tabs/vercel.md?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;
     /** Alerts sharing a collapse id replace one another; defaults to the plugin and title. */
     collapse?: string;
 };
+/** A Live Activity's color: the cards' named colors, less `secondary`. */
+export type ActivityTint = "primary" | "accent" | "success" | "warning" | "danger" | "blue" | "green" | "orange" | "red" | "purple" | "pink" | "teal" | "yellow" | "gray";
+/** A segment per step, or one bar. */
+export type ActivityProgress = {
+    kind: "steps";
+    /** 1 to 8 names of at most 24 characters. */
+    steps: string[];
+    /** The active step, 0 to `steps.length`; the ones before it are complete. */
+    current: number;
+} | {
+    kind: "bar";
+    /** 0 to 1. */
+    value: number;
+};
+/** The card's clock, which the phone ticks with no pushes. */
+export type ActivityTimer = {
+    kind: "elapsed";
+    /** Unix ms; the activity's first start unless said. */
+    startedAt?: number;
+} | {
+    kind: "countdown";
+    /** Unix ms; reaching it ends nothing. */
+    endsAt: number;
+} | {
+    kind: "none";
+};
+/**
+ * A Live Activity on the user's phones, sent whole each time: the same `id`
+ * updates it, a field left out takes its default, and status `done` or
+ * `failed` ends it with this state.
+ */
+export type Activity = {
+    /** The activity's id within the plugin, at most 64 bytes. */
+    id: string;
+    /** At most 60 characters, as a notice's title. */
+    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. */
+    page?: string;
+    /** An SF Symbol name, `shippingbox`; `circle.dotted`, or a check or a cross once ended, unless said. */
+    symbol?: string;
+    /** Colors the symbol, the progress and the label; white, or green or red once ended, unless said. */
+    tint?: ActivityTint;
+    /** The card's value, at most 24 characters; "2 of 4", "40%" or the status unless said, and "" hides it. */
+    label?: string;
+    /** The Dynamic Island's value, at most 10 characters; the label, or "2/4", unless said. */
+    compactLabel?: string;
+    /** No progress unless said. */
+    progress?: ActivityProgress;
+    /** Elapsed since the first start unless said. */
+    timer?: ActivityTimer;
+    /** `running` unless said; `done` and `failed` end it. */
+    status?: "running" | "done" | "failed";
+};
 /** One method as `ctx.plugins()` and the agent's `plugins` tool list it. */
 export type ManifestMethod = {
     /** `<plugin>.<method>`, the name `ctx.call` takes. */
@@ -21,6 +78,8 @@ export type ManifestMethod = {
     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;
     /** JSON Schema of the input, and of the output when the method declares one. */
     input: unknown;
     output: unknown;
@@ -77,7 +136,7 @@ export type Manifest = {
     }[];
 };
 /** 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";
+export type Caller = "card" | "agent" | "cron" | "code" | "http";
 /** 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. */
@@ -126,6 +185,12 @@ export type Context = {
     signal: AbortSignal;
     /** Sends an alert to every phone paired with this environment. */
     notify: (notice: Notice) => void;
+    /**
+     * Shows or updates a Live Activity on every paired phone:
+     * `await ctx.activity({ id: "deploy", title: "Deploying", progress: { kind: "steps", steps: ["Build", "Ship"], current: 0 } })`.
+     * A plugin shows at most two at once.
+     */
+    activity: (activity: Activity) => Promise<void>;
     /**
      * Starts a chat with `prompt` and waits for the agent's whole answer:
      * `await ctx.agent("Why is the build failing?", { agent: "claude" })`.

package/dist/define.d.ts

@@ -1,5 +1,8 @@
 import type { z } from "zod";
+import type { CacheOptions } from "./cache";
 import type { Context } from "./context";
+import { type Duration } from "./duration";
+import type { Workflow } from "./workflow/definition";
 import type { Retain } from "./streams";
 export type Collections = Record<string, z.ZodObject>;
 /** A stream's lines' schema, or that and how long it keeps them (7 days or 50 MB a key unless it says). */
@@ -25,8 +28,17 @@ export type Method<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodT
      * runs, such as "Delete every item?". Methods without one run on tap.
      */
     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. */
+    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.
+ */
+export type HTTPAccess = "key" | "none";
 export type Handler = (payload: any, ctx: Context) => unknown | Promise<unknown>;
 export type PluginDefinition = {
     /** One line, shown to the agent in the index of plugins. */
@@ -46,6 +58,7 @@ export type PluginDefinition = {
     /** Append-only JSONL per key, in `<namespace>/streams/<name>/`, kept as `retain` says. */
     streams?: Record<string, StreamDefinition>;
     methods?: Record<string, Method<any, any>>;
+    workflows?: Record<string, Workflow<any, any>>;
     on?: Record<string, Handler>;
     /**
      * Data named here gets no generated methods (list, create, delete…), so cards
@@ -59,6 +72,24 @@ export declare function method<I extends z.ZodType, O extends z.ZodType = z.ZodT
     output?: O;
     description?: string;
     confirm?: string;
+    http?: true | {
+        auth: HTTPAccess;
+    };
+}): Method<I, O>;
+/**
+ * A query 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).
+ */
+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;
+    shared?: boolean;
+    timeout?: Duration;
+    output?: O;
+    description?: string;
 }): Method<I, O>;
 /**
  * A method that sends items as they happen: a log tail, a build's output. Each

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export { definePlugin, method, stream } from "./define";
-export type { PluginDefinition, Method, MethodKind, StreamDefinition } from "./define";
-export type { AgentOptions, AgentReply, Caller, Context, CronEntry, CronStatus, Manifest, ManifestCron, ManifestMethod, ManifestStorage } from "./context";
+export { cached, definePlugin, method, stream } from "./define";
+export { upload, type UploadedFile } from "./uploads";
+export type { PluginDefinition, Method, MethodKind, HTTPAccess, 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";
 export type { KvEntry, SetOptions } from "./kv";
@@ -8,3 +9,8 @@ export type { Retain, StreamEntry, StreamKey } from "./streams";
 export type { Duration } from "./duration";
 export { MethodError, toCallError, type CallError } from "./errors";
 export { z } from "zod";
+export { workflow, type Workflow, type WorkflowContext, type WorkflowOptions } from "./workflow/definition";
+export { NonRetryable } from "./workflow/errors";
+export type { StepContext } from "./workflow/definition";
+export type { StepOptions } from "./workflow/policy";
+export type { RunSummary } from "./workflow/contracts";

package/dist/index.js

@@ -1,8 +1,46 @@
 // @bun
-import {
-  MethodError,
-  toCallError
-} from "./index-83w1fk10.js";
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  z: () => z3,
+  workflow: () => workflow,
+  upload: () => upload,
+  toCallError: () => toCallError,
+  stream: () => stream,
+  method: () => method,
+  definePlugin: () => definePlugin,
+  cached: () => cached,
+  NonRetryable: () => NonRetryable,
+  MethodError: () => MethodError
+});
+
+// src/duration.ts
+var unitMs = { s: 1000, m: 60000, h: 3600000, d: 86400000 };
+function parseDuration(duration) {
+  if (typeof duration === "number") {
+    if (!Number.isFinite(duration) || duration <= 0)
+      throw new Error(`a duration is a positive number of ms: ${duration}`);
+    return duration;
+  }
+  const match = /^(\d+(?:\.\d+)?)([smhd])$/.exec(duration);
+  if (!match)
+    throw new Error(`a duration is like "30s", "5m", "1h" or "7d": ${duration}`);
+  const ms = Number(match[1]) * unitMs[match[2]];
+  if (ms <= 0)
+    throw new Error(`a duration is longer than zero: ${duration}`);
+  return ms;
+}
 
 // src/define.ts
 function definePlugin(plugin) {
@@ -15,20 +53,98 @@ function method(input, run, options = {}) {
     kind: options.kind ?? "mutation",
     output: options.output,
     description: options.description,
-    confirm: options.confirm
+    confirm: options.confirm,
+    http: options.http === true ? "key" : options.http?.auth
+  };
+}
+function cached(input, run, options) {
+  return {
+    input,
+    run,
+    kind: "query",
+    output: options.output,
+    description: options.description,
+    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."
+  });
+}
+// src/errors.ts
+import { z as z2 } 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 z2.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 } from "zod";
+import { z as z3 } from "zod";
+
+// src/workflow/scope.ts
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
+var attemptScope = new AsyncLocalStorage2;
+var workflowScope = new AsyncLocalStorage2;
+
+// src/workflow/definition.ts
+function workflowContext(base, run) {
+  return {
+    ...base,
+    ...run,
+    get signal() {
+      return attemptScope.getStore()?.signal ?? run.signal;
+    },
+    step: { run: (name, callback, options) => run.step.run(name, (context) => callback({ ...context, runId: run.runId, idempotencyKey: `${run.runId}:${name}` }), options) }
+  };
+}
+function workflow(input, run, options = {}) {
+  return { input, run, ...options };
+}
+// src/workflow/errors.ts
+class NonRetryable extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NonRetryable";
+  }
+}
 export {
-  z,
+  z3 as z,
+  workflow,
+  upload,
   toCallError,
   stream,
   method,
   definePlugin,
+  cached,
+  NonRetryable,
   MethodError
 };
+export { parseDuration, callFiles, MethodError, toCallError, attemptScope, workflowScope, workflowContext, exports_src };