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

package/dist/common/scheduler.d.ts

@@ -3,6 +3,7 @@ import type { PreparedFlow } from './flow-semantics.js';
 import type { PreviousNode } from '../index.js';
 import type { AgentCheckpoint } from './runtime-contract.js';
 import * as Effect from 'effect/Effect';
+export declare const withWaitNotificationMessage: (value: JsonValue) => JsonValue;
 export declare const normalizeWaitComment: (value?: string | null) => string | null;
 export interface WaitResolution {
     readonly action: WaitAction;

package/dist/common/scheduler.js

@@ -10563,6 +10563,12 @@ function resolutionOutputPorts(node) {
 		pending: objectPort({
 			inputs,
 			prompt: { type: "string" },
+			pageUrl: { type: "string" },
+			message: {
+				type: "string",
+				minLength: 1,
+				pattern: "\\S"
+			},
 			...Object.fromEntries(actions.map((action) => [`${action}Url`, { type: "string" }])),
 			expiresAt: { type: "string" }
 		}),
@@ -10875,8 +10881,24 @@ var waitCommentSchema = string().trim().refine((value) => [...value].length <= 2
 function normalizeWaitComment$1(value) {
 	return waitCommentSchema.parse(value) || null;
 }
+function withWaitNotificationMessage$1(value) {
+	const source = schemaObject(value);
+	if (source == null || source.pageUrl !== void 0 && source.message !== void 0) return value;
+	const pageUrl = source.pageUrl === void 0 ? source.continueUrl ?? source.approveUrl : source.pageUrl;
+	if (typeof pageUrl != "string" || typeof source.prompt != "string" || typeof source.expiresAt != "string") return value;
+	return {
+		...source,
+		pageUrl,
+		message: source.message === void 0 ? [
+			source.prompt,
+			`Expires at: ${source.expiresAt}`,
+			`Review request: ${pageUrl}`
+		].join("\n\n") : source.message
+	};
+}
 //#endregion
 //#region src/execution/common/scheduler.ts
+var withWaitNotificationMessage = withWaitNotificationMessage$1;
 var normalizeWaitComment = normalizeWaitComment$1;
 var PortValidationError = class extends Error {};
 function usesPending(graph, nodeId) {
@@ -11349,7 +11371,7 @@ function runGraph(context, target, runId, launchInputs = {}, trigger, resume) {
 			const node = target.graph.nodes[nodeId];
 			const waitId = nanoid$1();
 			const notify = isResolutionNode(node) && usesPending(target.graph, nodeId);
-			const pending = yield* context.waits.create({
+			const notification = yield* context.waits.create({
 				jobId,
 				nodeId,
 				value,
@@ -11359,6 +11381,7 @@ function runGraph(context, target, runId, launchInputs = {}, trigger, resume) {
 				prompt: isResolutionNode(node) ? node.prompt : JSON.stringify(value, null, 2),
 				...isResolutionNode(node) ? {} : { notification: agentNotice(node, agents[jobId].input) }
 			});
+			const pending = notification == null ? notification : withWaitNotificationMessage(notification);
 			if (notify) {
 				validateOutputs(nodeId, node, { pending });
 				dependencies.release(nodeId, { pending }, ["pending"], false);
@@ -11553,7 +11576,30 @@ function runFlow(prepared, options) {
 	const emit = options.emit ?? (() => Effect.void);
 	return Effect.gen(function* () {
 		if (options.resume != null && (options.inputs != null || options.trigger != null || options.bindingValues != null)) return yield* Effect.fail(/* @__PURE__ */ new Error("A resumed Flow Run cannot accept launch inputs, binding values, or a Trigger seed."));
-		const checkpoint = options.resume == null ? void 0 : decodeFlowRunCheckpoint(options.resume.checkpoint);
+		const decoded = options.resume == null ? void 0 : decodeFlowRunCheckpoint(options.resume.checkpoint);
+		const outputs = (nodeId, value) => isResolutionNode(prepared.graph.nodes[nodeId]) && value.pending != null ? {
+			...value,
+			pending: withWaitNotificationMessage(value.pending)
+		} : value;
+		const checkpoint = decoded == null ? void 0 : {
+			...decoded,
+			results: Object.fromEntries(Object.entries(decoded.results).map(([id, result]) => [id, {
+				...result,
+				outputs: outputs(id, result.outputs)
+			}])),
+			dependencies: {
+				...decoded.dependencies,
+				nodes: Object.fromEntries(Object.entries(decoded.dependencies.nodes).map(([id, state]) => [id, {
+					...state,
+					...state.output == null ? {} : { output: outputs(id, state.output) },
+					input: Object.fromEntries(Object.entries(state.input).map(([source, result]) => [source, {
+						...result,
+						outputs: outputs(source, result.outputs)
+					}]))
+				}]))
+			},
+			waits: decoded.waits.map((wait) => wait.pending == null ? wait : Object.assign({}, wait, { pending: withWaitNotificationMessage(wait.pending) }))
+		};
 		if (checkpoint != null && new TextEncoder().encode(JSON.stringify(checkpoint)).byteLength > 16777216) return yield* Effect.fail(/* @__PURE__ */ new Error("Flow Run checkpoint exceeds 16 MiB."));
 		if (checkpoint == null && options.trigger == null) return yield* Effect.fail(/* @__PURE__ */ new Error("A Flow Run requires a Trigger seed."));
 		const triggerNode = options.trigger == null ? void 0 : prepared.graph.nodes[options.trigger.nodeId];
@@ -11576,4 +11622,4 @@ function runFlow(prepared, options) {
 	});
 }
 //#endregion
-export { PortValidationError, decodeFlowRunCheckpoint, normalizeWaitComment, runFlow, waitRetentionMs };
+export { PortValidationError, decodeFlowRunCheckpoint, normalizeWaitComment, runFlow, waitRetentionMs, withWaitNotificationMessage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-flow",
-  "version": "0.1.0-beta.63",
+  "version": "0.1.0-beta.65",
   "description": "TypeScript contracts and Browser runtime for Open Flow.",
   "license": "Apache-2.0",
   "repository": {

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

@@ -410,3 +410,32 @@ current online entries. The MCP equivalent is `flow_live({ flowId })`.
 A useful completion report identifies the Flow and Revision, what changed,
 what was actually checked or executed, and any remaining blocker. Its detail
 should match the task.
+
+## Workbench node annotations
+
+Node annotations from the Codex browser show the node title as the annotation name.
+Metadata contains `flowId`, `revisionId`, `nodeId`, and `syncState`, plus `description`
+when nonempty. The identity fields are never truncated; `revisionId` identifies the
+saved Revision. Descriptions may be shortened with an ellipsis to fit the annotation
+limits; read full content
+through the public API. The browser supplies the source page URL separately. Continue
+using the configured deployment and verify it matches the referenced Flow.
+Read the referenced node with the public read command before acting. Before editing,
+read the current Draft and use its revision checks; a captured annotation may be older
+than the current Draft. If the node no longer exists, report that instead of choosing
+another node by name.
+
+`syncState` describes the Workbench's known save state (`saved`, `dirty`, `saving`, or
+`failed`). The revision always identifies saved data; pending local changes, including
+unsaved code, are not part of that snapshot. An annotation does not save those changes
+or establish a CLI/MCP connection. Missing or invalid metadata is not sufficient to
+identify a node for editing.
+
+A multi-node annotation carries the same `flowId`, `revisionId`, and `syncState`,
+with `nodeIds` instead of `nodeId`. Parse `nodeIds` as a JSON-encoded string array
+and read every referenced node. The group contains business nodes and Triggers;
+Comment cards have no authoring node identity and are not included in this feature.
+If the complete list exceeds the annotation limits, metadata contains `nodeCount`
+and `error` instead of `nodeIds`. Ask for a smaller selection; never infer a partial
+list or treat a missing list as the whole Flow. The annotation captures the selection
+at creation time, not whichever nodes happen to be selected when the agent acts.