@protobase/cli 0.72.2 → 0.73.0

package/dist/cli/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.72.2";
+var version = "0.73.0";
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/cli",
-  "version": "0.72.2",
+  "version": "0.73.0",
   "description": "The protobase command: scaffold, doctor, dev, build and serve a Protobase project.",
   "license": "Apache-2.0",
   "repository": {
@@ -43,13 +43,13 @@
   "dependencies": {
     "@better-auth/core": "^1.7.12",
     "@hono/node-server": "^2.1.3",
-    "@protobase/config": "0.72.2",
-    "@protobase/layout": "0.72.2",
-    "@protobase/query": "0.72.2",
-    "@protobase/schema": "0.72.2",
-    "@protobase/server": "0.72.2",
-    "@protobase/ui": "0.72.2",
-    "@protobase/workflows": "0.72.2",
+    "@protobase/config": "0.73.0",
+    "@protobase/layout": "0.73.0",
+    "@protobase/query": "0.73.0",
+    "@protobase/schema": "0.73.0",
+    "@protobase/server": "0.73.0",
+    "@protobase/ui": "0.73.0",
+    "@protobase/workflows": "0.73.0",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/vite-plugin": "^11.10.0",

package/skills/protobase/references/features/workflows.md

@@ -16,7 +16,7 @@ Graphs of steps the server runs along their edges, written in a language a model
 - [Runs and step records](../reference/workflows.md#runs-and-their-steps) (beta): Each run started by hand through the API, from the app's code or by a trigger, with every step's input, output, logs, timing, tries and error recorded, secrets blanked out.
 - [Run debugger](../reference/workflows.md#following-and-debugging-a-run) (beta): Each workflow lists its runs with their status, who started them, when and for how long; a run shown on its workflow's page marks every step's status on the graph of the version it ran on, live while it runs, with each step's input, output, logs, timing, tries and error, secrets blanked out.
 - [Re-run from the failed step](../reference/workflows.md#re-running-a-failed-run) (beta): Once the workflow is fixed, a failed run runs again from the step that failed, keeping what the steps before it gave; a test run starts the workflow with a sample input from its page.
-- [Replay a run](../reference/workflows.md#replaying-a-run) (beta): A run that ended runs again from the start on its version and input without sending its outside writes, such as mail, record writes and requests other than GET, which give what they gave then, while its reads come from the step cache or run again, so you can work on what formed a message without sending it twice.
+- [Replay a run](../reference/workflows.md#replaying-a-run) (beta): replay a finished run on your workflow as it is now, with the same input. Steps that write are held back and reads come from the step cache or run again, so you can try a change on the same data without sending anything again.
 - [Runs that survive restarts](../reference/workflows.md#how-a-run-is-run) (beta): A run takes up where it stood after a restart or a crashed worker, never running a saved step again, and every limit fails closed.
 - [Who may run workflows](../reference/workflows.md#who-may-do-what) (beta): Making, changing and running workflows and reading their runs are each granted by name, within the tenant.
 - [Workflows over MCP](../reference/mcp.md#workflows) (beta): AI clients find, write, validate, change by a small edit and test-run workflows as the signed-in person, and read each step of a run to fix the one that failed and re-run it from there.

package/skills/protobase/references/reference/mcp.md

@@ -100,7 +100,7 @@ In an app with [workflows](workflows.md), the endpoint also offers tools to find
 | `list_connections` | The person's own [connected accounts](workflows.md#connecting-an-account), by each connection the app's plugins declare: its key and label, and each account's `id`, scopes and `needs_sign_in`. A definition's `connections` binds an account by its `id`. It returns no token, and no one else's accounts. |
 | `create_workflow` | Creates a workflow from its `name`, `description` and `definition`, and returns its `id`, `version` and ETag. |
 | `update_workflow` | Changes a workflow's definition by an `edit` or whole, as `definition`, and its `name` or `description`, and returns its `id`, new `version` and ETag. With the `etag` that `get_workflow` gave, it fails when someone changed the workflow since; an edit without one is saved against the version it was applied to. |
-| `run_workflow` | Starts a run of a workflow's current version with an `input`, and returns its `run_id` and `status`. With `rerun_of`, a failed run's id, it [re-runs](workflows.md#re-running-a-failed-run) that run from its failed step instead, on its input; with `replay: true` too, it [replays](workflows.md#replaying-a-run) a run that ended, sending none of its outside writes. |
+| `run_workflow` | Starts a run of a workflow's current version with an `input`, and returns its `run_id` and `status`. With `rerun_of`, a failed run's id, it [re-runs](workflows.md#re-running-a-failed-run) that run from its failed step instead, on its input; with `replay: true` too, it [replays](workflows.md#replaying-a-run) any ended run of the workflow on its current version, with that run's input, sending none of its outside writes. |
 | `enable_workflow` | Turns a workflow's trigger on (`enabled: true`) on the `version` it names, which must be the workflow's current version, or off, and returns its `enabled_version`. A workflow saved since that version is refused, so an approval never turns on a version the person did not see. One that uses a [connected account](workflows.md#connecting-an-account) is turned on only by the account's owner in the admin app: the tool answers `own-sign-in-only` and says so. |
 | `new_webhook_url` | Issues a new URL and secret for a workflow that starts from a [webhook trigger](workflows.md#appwebhook), keeping a `secret` the sender makes when given one, and returns `{ url, secret }`, shown this once; the old URL stops. |
 

package/skills/protobase/references/reference/workflow-plugins.md

@@ -105,6 +105,7 @@ lookup: {
   label: 'Company lookup',
   description: 'Finds a company by its registration number.',
   input: { type: 'object', required: ['number'], properties: { number: { type: 'string' } } },
+  writes: false,
   cache: { choice: 'force', ttl: '1 day', when: (input) => input.number !== '' },
   run: async ({ input, fetch }) => (await fetch(`https://registry.example/companies/${input.number}`)).json(),
 }

package/skills/protobase/references/reference/workflows.md

@@ -24,7 +24,7 @@ It adds five resources, over a `workflows` schema that [`protobase migration`](c
 | --- | --- |
 | `workflows` | A name, a description and the definition. Each save that changes the definition is checked, and kept as the workflow's next version, saved by the caller. |
 | `workflow_versions` | Every version of every definition as it was saved, with who saved it and when. Read-only. |
-| `workflow_runs` | A run, started by creating it with `workflow_id` and an `input`, or with `rerun_of` to [re-run a failed run](#re-running-a-failed-run), and `replay: true` too to [replay a run](#replaying-a-run); it runs the version its workflow had then, a replay the replayed run's. Its status, output, error and timing are written by the runner. |
+| `workflow_runs` | A run, started by creating it with `workflow_id` and an `input`, or with `rerun_of` to [re-run a failed run](#re-running-a-failed-run), and `replay: true` too to [replay a run](#replaying-a-run); it runs the version its workflow had then, and a re-run or a replay the input of the run it names. Its status, output, error and timing are written by the runner. |
 | `workflow_steps` | Every step of every run. Read-only. |
 | `workflow_triggers` | The trigger of each enabled workflow that has one besides `manual`: its type, status and last error. Read-only. |
 
@@ -339,11 +339,15 @@ A kept step's card says it is from the earlier run, as it finished before the re
 
 ### Replaying a run
 
-A run that ended, succeeded or failed, offers *Replay* where it is shown. It opens the form for a new run with `workflow_id`, `rerun_of` and `replay` filled in; creating it, through the form or `POST /api/v1/workflow_runs` with `{ "workflow_id": "...", "rerun_of": "...", "replay": true }`, starts a run that runs from the start on the replayed run's version and input, so you can look into what formed a message, such as a mail sent with the wrong contents, without sending it again:
+:::caution[Beta]
+A replay holds back only the steps whose type declares that it writes, and a held-back step whose state shaped its result with `Output` in the replayed run gets no result.
+:::
+
+A run that ended, succeeded or failed, offers *Replay* where it is shown. It opens the form for a new run with `workflow_id`, `rerun_of` and `replay` filled in; creating it, through the form or `POST /api/v1/workflow_runs` with `{ "workflow_id": "...", "rerun_of": "...", "replay": true }`, starts a run from the start on the workflow as it is now and on the replayed run's input, acting as the same people as any run started now. A developer whose workflow sent a mail with the wrong contents fixes the steps that formed it, saves, and replays the run, again until the mail is right, without sending it:
 
-- a step whose type writes, such as `app:mail.send`, `app:records.create`, `app:records.update`, an `app:http` request with any method but `GET`, and a plugin's step that does not say it only reads, is not called: it gives what the replayed run's step of the same place gave, its output and variables, or a `null` output when that run has none there, and its logs say *Not sent: replay*;
+- a step whose type writes, such as `app:mail.send`, `app:records.create`, `app:records.update`, an `app:http` request with any method but `GET`, and a plugin's step that does not say it only reads, is not called, and its logs say *Not sent: replay*. It takes the result of the replayed run's step of the same state, in the same Map item, and the same visit of that state, so states added or removed elsewhere do not change what it gets; its `Output`, `Assign` and `Next` then apply as the workflow has them now. A step whose visit failed fails with the same error and cause, which only a `Catch` takes, since every retry would give that error again. One the replayed run has no such step for, or whose state there was no Task or shaped its result with `Output`, gives a `null` output and goes on to its next state. <gap>A replay cannot give a held-back step the result of a state that shaped it with `Output` because steps do not record a Task's result before its `Output`.</gap>;
 - a step that only reads, such as `app:records.get`, `app:records.list`, an `app:http` `GET`, or a plugin's step that says so, is served from the [step cache](workflow-plugins.md#caching-results) when its type caches and an earlier result matches, saying so in its logs, with a line for each secret that changed since that result was kept; otherwise it runs again, as the same people a run of that version acts as;
-- Pass, Choice, Map, Succeed and Fail states compute as always, and a Wait goes on at once.
+- Pass, Choice, Map, Succeed and Fail states compute as always, so a fixed composition shows in the held-back step's input, and a Wait goes on at once.
 
 A replay given an `input` of its own is refused with `rerun-input`, and one without `rerun_of` with `replay-without-run`. It is refused, and nothing starts, when the replayed run is not one of the workflow's runs in the person's tenant (409, as for a workflow that is not there), has not ended (`run-not-ended`), or when the person may not start runs of the workflow, read the run, or read all of its steps (404). A step holds back only as its type declares: a plugin's step that writes while it declares it only reads runs in a replay too, so a replay is no guard against a plugin that declares it wrongly.