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

package/dist/common/canvas-commands.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export declare const canvasMinZoom = 0.1;
+export declare const canvasMaxZoom = 3;
+/** Transient operations on each connected canvas's own viewport. */
+export declare const canvasCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"focus">;
+    nodeId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"zoom">;
+    zoom: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"pan">;
+    dx: z.ZodNumber;
+    dy: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"fit">;
+}, z.core.$strict>], "type">;
+export type CanvasCommand = z.infer<typeof canvasCommandSchema>;
+export type CanvasCommandSubscriber = (execute: (command: CanvasCommand) => void) => () => void;

package/dist/common/control-api-conformance.js

@@ -11468,6 +11468,26 @@ var ControlClient = class {
 			method: "POST"
 		}));
 	}
+	async broadcastCanvas(flowId, command) {
+		const source = record$1(await this.request(`/v1/flows/${segment(flowId)}/canvas`, {
+			method: "POST",
+			body: JSON.stringify({
+				version: 1,
+				command
+			})
+		}));
+		exact(source, [
+			"version",
+			"flowId",
+			"broadcast"
+		]);
+		if (source.version != 1 || source.broadcast !== true || source.flowId !== flowId) return invalidResponse();
+		return {
+			version: 1,
+			flowId: string(source.flowId),
+			broadcast: true
+		};
+	}
 	async getFlow(flowId) {
 		return flow(await this.request(`/v1/flows/${segment(flowId)}`));
 	}

package/dist/common/control-api.d.ts

@@ -1,3 +1,5 @@
+import type { CanvasCommand } from './canvas-commands.js';
+export type { CanvasCommand, CanvasCommandSubscriber } from './canvas-commands.js';
 import type { LiveDetails } from './liveDetails.js';
 export { liveEntries } from './liveDetails.js';
 export type { LiveDetails, LiveEntry } from './liveDetails.js';
@@ -30,6 +32,11 @@ export type { JsonValue, TriggerKeySnapshot, WaitAction } from '../browser/flow-
 export type { RunStatus } from './run-lifecycle.js';
 export { ApiError, controlErrorCode, controlErrorMetadata, type ControlErrorCode } from './control-api-errors.js';
 export type { FlowCatalogEvent, FlowChangeEvent } from './flow-notifications.js';
+export interface CanvasBroadcast {
+    readonly version: 1;
+    readonly flowId: string;
+    readonly broadcast: true;
+}
 export type ControlRequest = (path: string, init?: RequestInit) => Promise<Response>;
 export interface ErrorListener {
     readonly flowId: string;
@@ -791,6 +798,7 @@ export declare class ControlClient {
         readonly idempotencyKey?: string;
     }): Promise<Flow>;
     createFlow(name: string, idempotencyKey?: string, teamId?: string): Promise<Flow>;
+    broadcastCanvas(flowId: string, command: CanvasCommand): Promise<CanvasBroadcast>;
     getFlow(flowId: string): Promise<Flow>;
     getErrorListeners(flowId: string, signal?: AbortSignal): Promise<readonly ErrorListener[]>;
     renameFlow(flowId: string, name: string): Promise<Flow>;

package/dist/common/control-api.js

@@ -12124,6 +12124,26 @@ var ControlClient = class {
 			method: "POST"
 		}));
 	}
+	async broadcastCanvas(flowId, command) {
+		const source = record(await this.request(`/v1/flows/${segment(flowId)}/canvas`, {
+			method: "POST",
+			body: JSON.stringify({
+				version: 1,
+				command
+			})
+		}));
+		exact(source, [
+			"version",
+			"flowId",
+			"broadcast"
+		]);
+		if (source.version != 1 || source.broadcast !== true || source.flowId !== flowId) return invalidResponse();
+		return {
+			version: 1,
+			flowId: string(source.flowId),
+			broadcast: true
+		};
+	}
 	async getFlow(flowId) {
 		return flow(await this.request(`/v1/flows/${segment(flowId)}`));
 	}

package/dist/common/control-requests.d.ts

@@ -1,3 +1,4 @@
+export { canvasCommandSchema } from './canvas-commands.js';
 export * from './authoring.js';
 import type { JsonValue } from '../browser/flow-change.js';
 import type { DraftOperation } from './draftOperations.js';
@@ -9,6 +10,22 @@ export declare const waitActionBodySchema: {
     };
 };
 export declare const controlRequests: {
+    canvas: (value: unknown) => {
+        command: {
+            type: "focus";
+            nodeId: string;
+        } | {
+            type: "zoom";
+            zoom: number;
+        } | {
+            type: "pan";
+            dx: number;
+            dy: number;
+        } | {
+            type: "fit";
+        };
+        version: 1;
+    };
     authoringCheck: (value: unknown) => {
         revisionId: string;
     };

package/dist/common/control-requests.js

@@ -5852,6 +5852,23 @@ function preprocess(fn, schema) {
 		out: schema
 	});
 }
+/** Transient operations on each connected canvas's own viewport. */
+var canvasCommandSchema = discriminatedUnion("type", [
+	strictObject({
+		type: literal("focus"),
+		nodeId: string().min(1)
+	}),
+	strictObject({
+		type: literal("zoom"),
+		zoom: number().min(.1).max(3)
+	}),
+	strictObject({
+		type: literal("pan"),
+		dx: number(),
+		dy: number()
+	}),
+	strictObject({ type: literal("fit") })
+]);
 //#endregion
 //#region ../../node_modules/.bun/dequal@2.0.3/node_modules/dequal/lite/index.mjs
 var has = Object.prototype.hasOwnProperty;
@@ -14012,6 +14029,10 @@ var trigger = strictObject({
 	outputs: record$3(string(), json)
 });
 var schemas = {
+	canvas: strictObject({
+		command: canvasCommandSchema,
+		version
+	}),
 	authoringCheck: authoringCheckSchema,
 	authoringEdit: authoringRequestSchema,
 	authoringRead: authoringReadSchema,
@@ -14123,6 +14144,7 @@ function decoder(schema) {
 	return (value) => schema.parse(value);
 }
 var controlRequests = {
+	canvas: decoder(schemas.canvas),
 	authoringCheck: decoder(schemas.authoringCheck),
 	authoringEdit: decoder(schemas.authoringEdit),
 	authoringRead: decoder(schemas.authoringRead),
@@ -14171,4 +14193,4 @@ function controlRequestSchema(name) {
 	return schema;
 }
 //#endregion
-export { AuthoringError, authoringCheckResponse, authoringCheckSchema, authoringConfigurations, authoringDiagnosticSchema, authoringDiagnostics, authoringEditResponse, authoringEditSchema, authoringExample, authoringExamples, authoringNode, authoringReadResponse, authoringReadSchema, authoringRequestContract, authoringRequestSchema, authoringSchema, authoringSchemaQuery, authoringSearchResponse, authoringSearchSchema, authoringSourceSchema, authoringTypes, compileAuthoring, controlRequestSchema, controlRequests, decodeDraftOperations, draftOperationsSchema, readAuthoring, resolveDraftOperations, searchAuthoring, waitActionBodySchema };
+export { AuthoringError, authoringCheckResponse, authoringCheckSchema, authoringConfigurations, authoringDiagnosticSchema, authoringDiagnostics, authoringEditResponse, authoringEditSchema, authoringExample, authoringExamples, authoringNode, authoringReadResponse, authoringReadSchema, authoringRequestContract, authoringRequestSchema, authoringSchema, authoringSchemaQuery, authoringSearchResponse, authoringSearchSchema, authoringSourceSchema, authoringTypes, canvasCommandSchema, compileAuthoring, controlRequestSchema, controlRequests, decodeDraftOperations, draftOperationsSchema, readAuthoring, resolveDraftOperations, searchAuthoring, waitActionBodySchema };

package/dist/common/flow-notifications.d.ts

@@ -1,3 +1,4 @@
+import type { CanvasCommand } from '../common/canvas-commands.js';
 export type FlowCatalogEvent = {
     readonly kind: 'flows.changed';
     readonly version: 1;
@@ -7,6 +8,11 @@ export type FlowCatalogEvent = {
     readonly version: 1;
 };
 export type FlowChangeEvent = {
+    readonly kind: 'canvas.command';
+    readonly flowId: string;
+    readonly command: CanvasCommand;
+    readonly version: 1;
+} | {
     readonly accessRevision: number;
     readonly flowId: string;
     readonly kind: 'access.changed';

package/dist/common/mcp.d.ts

@@ -3,6 +3,48 @@ import { z } from 'zod';
 export declare const mcpProtocolVersion = "2026-07-28";
 export declare const mcpInstructions: string;
 export declare const mcpTools: {
+    flow_canvas: {
+        description: string;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+        inputSchema: {
+            '~standard': {
+                version: 1;
+                vendor: string;
+                jsonSchema: {
+                    input: () => Record<string, unknown>;
+                    output: () => Record<string, unknown>;
+                };
+                validate(value: unknown): {
+                    value: {
+                        flowId: string;
+                        command: {
+                            type: "focus";
+                            nodeId: string;
+                        } | {
+                            type: "zoom";
+                            zoom: number;
+                        } | {
+                            type: "pan";
+                            dx: number;
+                            dy: number;
+                        } | {
+                            type: "fit";
+                        };
+                    };
+                } | {
+                    issues: {
+                        message: string;
+                        path: string[];
+                    }[];
+                };
+            };
+        };
+    };
     flow_live: {
         description: string;
         annotations: {

package/dist/common/mcp.js

@@ -5851,6 +5851,23 @@ function preprocess(fn, schema) {
 		out: schema
 	});
 }
+/** Transient operations on each connected canvas's own viewport. */
+var canvasCommandSchema = discriminatedUnion("type", [
+	strictObject({
+		type: literal("focus"),
+		nodeId: string$1().min(1)
+	}),
+	strictObject({
+		type: literal("zoom"),
+		zoom: number().min(.1).max(3)
+	}),
+	strictObject({
+		type: literal("pan"),
+		dx: number(),
+		dy: number()
+	}),
+	strictObject({ type: literal("fit") })
+]);
 //#endregion
 //#region ../../node_modules/.bun/dequal@2.0.3/node_modules/dequal/lite/index.mjs
 var has = Object.prototype.hasOwnProperty;
@@ -11670,6 +11687,26 @@ var ControlClient = class {
 			method: "POST"
 		}));
 	}
+	async broadcastCanvas(flowId, command) {
+		const source = record(await this.request(`/v1/flows/${segment(flowId)}/canvas`, {
+			method: "POST",
+			body: JSON.stringify({
+				version: 1,
+				command
+			})
+		}));
+		exact(source, [
+			"version",
+			"flowId",
+			"broadcast"
+		]);
+		if (source.version != 1 || source.broadcast !== true || source.flowId !== flowId) return invalidResponse();
+		return {
+			version: 1,
+			flowId: string(source.flowId),
+			broadcast: true
+		};
+	}
 	async getFlow(flowId) {
 		return flow$1(await this.request(`/v1/flows/${segment(flowId)}`));
 	}
@@ -12390,14 +12427,14 @@ var mutationKey = id.max(256).describe("Stable identity for this mutation. Retry
 var pageLimit = int().min(1).max(100).default(50);
 var flow = id.describe("Exact Flow ID returned by flow_list or flow_create.");
 var run = id.describe("Exact Run ID returned by flow_run or run_list.");
-var mcpInstructions = "Use flow_list, flow_read and flow_search to inspect root workflows. Read node type schemas with flow_schema. Use flow_edit with the observed baseRevision and a stable requestId. Node edits affect only the selected node. Text edits require exactly one match. Execution edges and input sources are independent. Legacy Subflow content is unsupported. Edits can save incomplete drafts; inspect returned diagnostics and use flow_check before running. Use flow_check before flow_run. Select an explicit Trigger node ID and fixed revision or publication. A new Flow has no Trigger until you add one. Before adding a Feishu Trigger, use event_source_list and compare its Connection IDs with connector_connections in the Flow scope. If no source is available, create and verify one in Workbench. Use flow_publish to publish a fixed Revision, then poll flow_publish_status until succeeded or failed. Use flow_live to inspect current online entries after publication. Use flow_set_enabled to enable or disable the observed Live publication. flow_run returns an accepted Run, not its final result. Find Runs with run_list, poll run_get and use run_result after terminal. Resolve a waiting Run only with an explicit run_resolve_wait action allowed by run_get. Use run_results and run_result_read to inspect stored Agent tool results; these are separate from the terminal Run result. Retry flow_edit with identical arguments and the same requestId. Retry flow_create, flow_import, flow_publish and flow_run only with identical arguments and the same idempotencyKey; a new key can execute the Flow again. Other mutations use the same resource identity and arguments when retrying. Cancel a Run explicitly with run_cancel. Use nextCursor and nextAfter to read subsequent pages. Connector-backed deployments may require a Team; inspect connector_teams before creating a Flow.";
-function tool(description, schema, readOnly) {
+var mcpInstructions = "Use flow_list, flow_read and flow_search to inspect root workflows. Read node type schemas with flow_schema. Use flow_edit with the observed baseRevision and a stable requestId. Node edits affect only the selected node. Text edits require exactly one match. Execution edges and input sources are independent. Legacy Subflow content is unsupported. Edits can save incomplete drafts; inspect returned diagnostics and use flow_check before running. Use flow_check before flow_run. Select an explicit Trigger node ID and fixed revision or publication. A new Flow has no Trigger until you add one. Before adding a Feishu Trigger, use event_source_list and compare its Connection IDs with connector_connections in the Flow scope. If no source is available, create and verify one in Workbench. Use flow_publish to publish a fixed Revision, then poll flow_publish_status until succeeded or failed. Use flow_live to inspect current online entries after publication. Use flow_set_enabled to enable or disable the observed Live publication. flow_run returns an accepted Run, not its final result. Find Runs with run_list, poll run_get and use run_result after terminal. Resolve a waiting Run only with an explicit run_resolve_wait action allowed by run_get. Use run_results and run_result_read to inspect stored Agent tool results; these are separate from the terminal Run result. Retry flow_edit with identical arguments and the same requestId. Retry flow_create, flow_import, flow_publish and flow_run only with identical arguments and the same idempotencyKey; a new key can execute the Flow again. Canvas commands are transient broadcasts without execution confirmation; never automatically retry flow_canvas because pan is relative. Other mutations use the same resource identity and arguments when retrying. Cancel a Run explicitly with run_cancel. Use nextCursor and nextAfter to read subsequent pages. Connector-backed deployments may require a Team; inspect connector_teams before creating a Flow.";
+function tool(description, schema, readOnly, idempotent = true) {
 	return {
 		description,
 		annotations: {
 			readOnlyHint: readOnly,
 			destructiveHint: !readOnly,
-			idempotentHint: true,
+			idempotentHint: idempotent,
 			openWorldHint: true
 		},
 		inputSchema: { "~standard": {
@@ -12418,6 +12455,10 @@ function tool(description, schema, readOnly) {
 	};
 }
 var mcpTools = {
+	flow_canvas: tool("Broadcast a transient canvas command to connected Workbenches viewing this Flow. Success only confirms Server broadcast, not delivery or execution. No replay, session selection or Presentation save. Pan uses screen pixels (positive right/down); zoom is an absolute ratio (0.1–3); fit includes all nodes. Repeating pan moves again.", strictObject({
+		flowId: flow,
+		command: canvasCommandSchema
+	}), false, false),
 	flow_live: tool("Read the current published Flow, enablement and online entries, including Webhook URLs and request fields. Draft changes do not affect this view. An unpublished Flow returns not-published with no entries.", strictObject({ flowId: flow }), true),
 	flow_list: tool("List Flows in this deployment. Continue with nextCursor; cursors are compatible with the Control API.", strictObject({
 		cursor: id.optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-flow",
-  "version": "0.1.0-beta.63",
+  "version": "0.1.0-beta.64",
   "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.