@oomol-lab/open-flow 0.1.0-beta.65 → 0.1.0-beta.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-flow",
-  "version": "0.1.0-beta.65",
+  "version": "0.1.0-beta.67",
   "description": "TypeScript contracts and Browser runtime for Open Flow.",
   "license": "Apache-2.0",
   "repository": {
@@ -29,6 +29,10 @@
       "types": "./dist/common/openapi.d.ts",
       "import": "./dist/common/openapi.js"
     },
+    "./workflow": {
+      "types": "./dist/common/workflow.d.ts",
+      "import": "./dist/common/workflow.js"
+    },
     "./connector-action": {
       "types": "./dist/common/connector-action.d.ts",
       "import": "./dist/common/connector-action.js"

package/skills/open-flow/SKILL.md

@@ -14,6 +14,15 @@ Consult the references relevant to the task:
 - [n8n conversion](references/flow-n8n-conversion.md): represent collections,
   branches, provider operations and state while preserving source behavior.
 
+Keep generated Flow and node names short enough to scan on the canvas. Aim for
+2–4 English words or 4–8 Chinese characters, using the user's language unless
+the workflow has an established naming language. Name a Flow by its main purpose
+and a node by its action and object, such as `AI Trend Digest`, `Fetch trends`,
+`Verify sources`, or `发布文章`. Keep only qualifiers needed to distinguish similar
+nodes. Put detailed behavior in descriptions; avoid sentences, repeated workflow
+context, and obscure abbreviations. Preserve names explicitly supplied by the
+user, and do not rename unrelated existing nodes.
+
 <!-- agentic:if localDevelopment -->
 
 Run commands from this repository's root. The development CLI connects to the

package/skills/open-flow/references/flow-authoring.md

@@ -106,7 +106,7 @@ Absence, explicit null, an unset binding and an inherited default are distinct.
 
 ### Connect execution and data
 
-This complete edit adds a Manual Trigger, a calculation, and a formatter. It
+This complete edit adds a Start node, a calculation, and a formatter. It
 needs no Connector or model. `total` is a business output; `amount` is a named
 input whose binding reads it. Both execution edges and data bindings are visible.
 
@@ -115,7 +115,7 @@ input whose binding reads it. Both execution edges and data bindings are visible
   "baseRevision": "REVISION",
   "requestId": "example-code-and-data",
   "edits": [
-    { "op": "node.add", "as": "start", "type": "manual", "name": "Start" },
+    { "op": "node.add", "as": "start", "type": "start", "name": "Start" },
     {
       "op": "node.add",
       "as": "calculate",
@@ -151,6 +151,13 @@ Common sources are `{"kind":"value","value":...}`,
 `{"kind":"variable","name":"VARIABLE"}`. An output source may omit `port`
 when there is one output, or select a nested `field`. Each node schema advertises
 supported sources. A Trigger cannot read downstream results before the Run starts.
+
+For workflow business outputs, add one `outputs` node with `config.outputDefs` as a named schema/nullable/description map. Set sources with `node.add.inputs` or `input.set` and connect execution predecessors. Outputs owns its definitions and mappings; deleting it removes both. Node details expose definitions and inputs. Run results expose business `outputs` separately from node logs. A `workflow` node with `config: { "flowId": "TARGET_FLOW_ID" }` calls the target's current enabled Live with Start. Published interface snapshots supply its ports. A changed Revision with the same interface remains callable; changed interfaces require `node.refresh`. Snapshot comparison ignores descriptions and port ordering, but preserves schema, nullability and node-presence differences.
+
+Workflow target selection may retain an owned unpublished or disabled Flow. Without a loaded interface,
+the call stores an empty source revision; checks report the target problem or missing interface.
+After the target becomes available, `node.refresh` loads its current Live contract. Selection and
+workflow-call checks do not validate Start presence. Start remains required at actual Live invocation.
 Schema `{}` accepts dynamic JSON; it does not convert objects or arrays into text.
 
 ### Change one prompt rule
@@ -282,15 +289,18 @@ unavailable action and an action lacking an active Connection are different
 problems. Actions marked `authenticated: false` need no account. Connection
 selection rules come from the selected node contract.
 
-| Capability                      | Relevant schema and configuration                                                                                       |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| Provider read or write          | `connector`: discovered `action`, optional `connectionId`, named input bindings.                                        |
-| Provider event                  | `poll` or `integration`: discovered `key`, Connection and any static inputs; polling also has a schedule.               |
-| Manual, HTTP or scheduled entry | `manual`, `webhook`, `cron`: business payload fields or schedule. A Manual Trigger has no output parameters.            |
-| Workflow failure handler        | `error`: published upstream Flows' automatic Run failures; not a node-level catch or a handler for manual Run failures. |
-| Fixed HTTP operation            | `openapi`: an OpenAPI source, path and method; resolved authentication choices and ports appear in node details.        |
-| Reusable constants              | `value`: named JSON values and optional output constraints.                                                             |
-| Durable interaction             | `wait`, `approval`: prompt and named inputs; resume through the Run's Wait ID.                                          |
+For Connector Tasks, independent Code Actions, Agent tools and notifications, an omitted `connectionId` means unconfigured; `connectionId: ""` explicitly defers account configuration. Deferred selections pass account readiness checks but fail with `connector.connection-required` if invoked. Deferred Agent tools are excluded from the callable tool set. Provider Triggers still require a nonempty account ID. Public edits and portable exports preserve the empty string; clear the field to return to the unconfigured state.
+
+| Capability                      | Relevant schema and configuration                                                                                                  |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Provider read or write          | `connector`: discovered `action`, optional `connectionId`, named input bindings.                                                   |
+| Provider event                  | `poll` or `integration`: discovered `key`, Connection and any static inputs; polling also has a schedule.                          |
+| Manual, HTTP or scheduled entry | `start`, `webhook`, `cron`: workflow `inputDefs`, HTTP body fields, or schedule.                                                   |
+| Workflow failure handler        | `error`: published upstream Flows' automatic Run failures; not a node-level catch or a handler for manual Run failures.            |
+| Call another workflow           | `workflow`: select an owned published Flow ID; inputs and outputs derive from its saved contract. Use `node.refresh` to update it. |
+| Fixed HTTP operation            | `openapi`: an OpenAPI source, path and method; resolved authentication choices and ports appear in node details.                   |
+| Reusable constants              | `value`: named JSON values and optional output constraints.                                                                        |
+| Durable interaction             | `wait`, `approval`: prompt and named inputs; resume through the Run's Wait ID.                                                     |
 
 Connector and LLM services are configured on the Server. Missing capabilities
 should be described in terms of the required operation or event, without silently
@@ -311,14 +321,16 @@ and `validation`. A Draft may save with diagnostics. `valid`, `invalid` and
 Use the edit's validation or request a check of a specific Revision. Structural
 validity does not demonstrate business behavior, model quality or runtime account
 access. An authorized test Run can exercise meaningful input cases. Draft Run
-readiness concerns the selected Trigger's path and dependencies; publishing and
-Live Runs require the complete Flow to be ready.
+readiness concerns the selected Trigger's path and dependencies. Publishing and
+Live Runs require the complete Flow to be ready. Explicit Live Runs must select a Start node. Other Triggers can be simulated only in Draft Runs; their Live Runs originate from their event sources.
 
-A sole Manual Trigger is selected automatically; otherwise specify `--trigger`.
-`--outputs` supplies named Trigger outputs. `--input` supplies per-node input
+The Start node is selected automatically even when other Triggers exist; use `--trigger` to choose another entry for a Draft test. A sole legacy Manual Trigger remains supported for Draft tests.
+`--outputs` supplies named Start parameters or other Trigger outputs. Required Start parameters must be present, omitted nullable parameters become null, and unknown parameters are rejected. Start parameters have no defaults. `--input` supplies per-node input
 overrides; command help gives their shape. Live Runs use `--source live` and
 `--expected-publication` instead of `--expected-revision`.
 
+Declare parameters on Start: `{"op":"node.add","as":"start","type":"start","name":"Start","config":{"inputDefs":{"message":{"schema":{"type":"string"},"nullable":false},"note":{"schema":{"type":"string"},"nullable":true}}}}`. Read definitions in Start node details at `config.inputDefs`; `flow_live.inputDefs` remains a derived view of the published Start. Update with `node.update set.config.inputDefs`, and clear node-relative paths such as `["config","inputDefs","message","description"]`. Downstream nodes bind `{ "kind": "output", "node": "$start", "port": "message" }` with separate execution edges. Call with `--outputs '{"message":"Hello"}'`; note becomes null. REST and MCP use `trigger.outputs`. Deleting Start removes its configuration; undo restores it, while a new Start has empty definitions.
+
 ### Inspect or continue an existing Run
 
 ```bash
@@ -384,7 +396,7 @@ commands when relevant.
 belongs to the host. An open Workbench receives Revision notifications, so a CLI
 edit does not require a page reload.
 
-`live` includes Manual entry nodes without a runtime binding. `trigger search`
+`live` includes Start and legacy Manual entry nodes without a runtime binding. `trigger search`
 and `trigger show` discover provider definitions; `live` inspects the Flow's
 current online entries. The MCP equivalent is `flow_live({ flowId })`.