newo 3.7.0 → 3.7.2

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.7.2] - 2026-05-17
+
+### Fixed
+
+- **`newo push` now syncs flow metadata (title, events, state_fields) to the platform** — closes [#3](https://github.com/sabbah13/newo-cli/issues/3). Previously `newo push` only uploaded skill scripts; edits to a flow's `metadata.yaml` (V1) or `{FlowIdn}.yaml` (V2) silently never reached the platform, and events added via `newo create-event` could appear to disappear after a subsequent push because the local-side definition lagged the remote one. Push now performs hash-gated reconciliation per flow: when `metadata.yaml` changes locally it calls `PATCH /api/v1/designer/flows/{id}` for title/description/runner, then create/update/delete child events and state_fields against `/events` and `/states` so the platform mirrors local. Hash-gating is critical — flows whose `metadata.yaml` is untouched are never even compared, so stale local trees cannot accidentally wipe events created out-of-band via the Builder UI. Wired into the legacy `pushChanged` path, `ProjectSyncStrategy`, and `V2ProjectSyncStrategy`. Reported by Bob (issue #3).
+
+### Added
+
+- **`updateFlow`, `updateFlowEvent`, `updateFlowState`, `deleteFlowState`, `getFlow` API wrappers** in `src/api.ts` for the previously-undocumented `PATCH /api/v1/designer/flows/{id}`, `PATCH /api/v1/designer/flows/events/{id}`, `PUT /api/v1/designer/flows/states/{id}`, `DELETE /api/v1/designer/flows/states/{id}`, and `GET /api/v1/designer/flows/{id}` endpoints. Empty payload returns 500; the platform requires the full descriptor.
+- **`src/sync/flow-metadata.ts`** module — pure-logic reconciler shared by both V1 and V2 push paths. Comparator helpers `flowEventDiffers`/`flowStateDiffers` normalize null/undefined/empty so YAML round-trips don't trigger spurious updates.
+- **18 unit tests** in `test/flow-metadata.test.js` covering create/update/delete event flows, state CRUD in a single pass, no-op when local matches remote, and graceful error handling that records failures without aborting the loop.
+
+## [3.7.1] - 2026-04-29
+
+### Fixed
+
+- **Workflow Builder canvas blank-screen after `newo push --only attributes`** - JSON-typed project/customer attributes (e.g. `project_attributes_private_dynamic_workflow_builder_canvas`) are now always coerced to a JSON STRING when persisted to `attributes.yaml` and when sent on push. Previously, when the API returned the `value` field as a parsed object, `yaml.dump` serialized it as a YAML structure and the next push sent `{"value": {...object...}}` instead of `{"value": "...json..."}` - the platform stored a shape Builder could not render and the canvas blanked out. Change-detection now compares both sides as canonical (compact) JSON, so pretty- vs compact-printed forms and string vs object representations no longer trigger spurious pushes. String-typed values are left bit-for-bit untouched, so no churn on existing repos. New helpers in `src/sync/json-attr-utils.ts` are wired into both `src/sync/attributes.ts` and `src/domain/strategies/sync/AttributeSyncStrategy.ts`. Reported by Bob; 19 regression tests in `test/json-attribute-roundtrip.test.js`.
+
 ## [3.7.0] - 2026-04-23
 
 ### Added
@@ -1033,7 +1051,8 @@ Another Item: $Price [Modifiers: modifier3]
 - GitHub Actions CI/CD integration
 - Robust authentication with token refresh
 
-[Unreleased]: https://github.com/sabbah13/newo-cli/compare/v3.3.0...HEAD
+[Unreleased]: https://github.com/sabbah13/newo-cli/compare/v3.7.1...HEAD
+[3.7.1]: https://github.com/sabbah13/newo-cli/compare/v3.7.0...v3.7.1
 [3.3.0]: https://github.com/sabbah13/newo-cli/compare/v3.2.0...v3.3.0
 [3.2.0]: https://github.com/sabbah13/newo-cli/compare/v3.1.0...v3.2.0
 [3.1.0]: https://github.com/sabbah13/newo-cli/compare/v3.0.0...v3.1.0

package/dist/api.d.ts

@@ -1,10 +1,32 @@
 import { type AxiosInstance } from 'axios';
-import type { ProjectMeta, Agent, Skill, FlowEvent, FlowState, AkbImportArticle, CustomerProfile, CustomerAttribute, CustomerAttributesResponse, UserPersonaResponse, UserPersona, ChatHistoryParams, ChatHistoryResponse, CreateAgentRequest, CreateAgentResponse, CreateFlowRequest, CreateFlowResponse, CreateSkillRequest, CreateSkillResponse, CreateFlowEventRequest, CreateFlowEventResponse, CreateFlowStateRequest, CreateFlowStateResponse, CreateSkillParameterRequest, CreateSkillParameterResponse, CreateCustomerAttributeRequest, CreateCustomerAttributeResponse, CreatePersonaRequest, CreatePersonaResponse, CreateProjectRequest, CreateProjectResponse, PublishFlowRequest, PublishFlowResponse, Integration, Connector, CreateSandboxPersonaRequest, CreateSandboxPersonaResponse, CreateActorRequest, CreateActorResponse, SendChatMessageRequest, ConversationActsParams, ConversationActsResponse, ScriptAction, IntegrationSetting, CreateConnectorRequest, CreateConnectorResponse, UpdateConnectorRequest, OutgoingWebhook, IncomingWebhook, PersonaSearchResponse, AkbTopicsResponse, Registry, RegistryItem, AddProjectFromRegistryRequest, CreateNewoCustomerRequest, CreateNewoCustomerResponse, LogsQueryParams, LogsResponse } from './types.js';
+import type { ProjectMeta, Agent, Skill, FlowEvent, FlowState, AkbImportArticle, CustomerProfile, CustomerAttribute, CustomerAttributesResponse, UserPersonaResponse, UserPersona, ChatHistoryParams, ChatHistoryResponse, CreateAgentRequest, CreateAgentResponse, CreateFlowRequest, CreateFlowResponse, CreateSkillRequest, CreateSkillResponse, CreateFlowEventRequest, CreateFlowEventResponse, UpdateFlowEventRequest, CreateFlowStateRequest, CreateFlowStateResponse, UpdateFlowStateRequest, UpdateFlowRequest, CreateSkillParameterRequest, CreateSkillParameterResponse, CreateCustomerAttributeRequest, CreateCustomerAttributeResponse, CreatePersonaRequest, CreatePersonaResponse, CreateProjectRequest, CreateProjectResponse, PublishFlowRequest, PublishFlowResponse, Integration, Connector, CreateSandboxPersonaRequest, CreateSandboxPersonaResponse, CreateActorRequest, CreateActorResponse, SendChatMessageRequest, ConversationActsParams, ConversationActsResponse, ScriptAction, IntegrationSetting, CreateConnectorRequest, CreateConnectorResponse, UpdateConnectorRequest, OutgoingWebhook, IncomingWebhook, PersonaSearchResponse, AkbTopicsResponse, Registry, RegistryItem, AddProjectFromRegistryRequest, CreateNewoCustomerRequest, CreateNewoCustomerResponse, LogsQueryParams, LogsResponse } from './types.js';
 export declare function makeClient(verbose?: boolean, token?: string): Promise<AxiosInstance>;
 export declare function listProjects(client: AxiosInstance): Promise<ProjectMeta[]>;
 export declare function listAgents(client: AxiosInstance, projectId: string): Promise<Agent[]>;
 export declare function getProjectMeta(client: AxiosInstance, projectId: string): Promise<ProjectMeta>;
 export declare function listFlowSkills(client: AxiosInstance, flowId: string): Promise<Skill[]>;
+/**
+ * Fetch a single flow's top-level descriptor.
+ *
+ * Used by push to detect whether local metadata.yaml title/description
+ * differ from the platform before patching.
+ */
+export interface FlowDescriptor {
+    id: string;
+    idn: string;
+    title: string;
+    description: string | null;
+    agent_id: string;
+    default_runner_type: string;
+    default_model: {
+        provider_idn: string;
+        model_idn: string;
+    };
+    publication_datetime?: string;
+    last_change_datetime?: string;
+    creation_datetime?: string;
+}
+export declare function getFlow(client: AxiosInstance, flowId: string): Promise<FlowDescriptor>;
 export declare function getSkill(client: AxiosInstance, skillId: string): Promise<Skill>;
 export declare function updateSkill(client: AxiosInstance, skillObject: Skill): Promise<void>;
 export declare function listFlowEvents(client: AxiosInstance, flowId: string): Promise<FlowEvent[]>;
@@ -32,8 +54,18 @@ export declare function createSkill(client: AxiosInstance, flowId: string, skill
 export declare function deleteSkill(client: AxiosInstance, skillId: string): Promise<void>;
 export declare function deleteSkillById(client: AxiosInstance, skillId: string): Promise<void>;
 export declare function createFlowEvent(client: AxiosInstance, flowId: string, eventData: CreateFlowEventRequest): Promise<CreateFlowEventResponse>;
+export declare function updateFlowEvent(client: AxiosInstance, eventId: string, eventData: UpdateFlowEventRequest): Promise<void>;
 export declare function deleteFlowEvent(client: AxiosInstance, eventId: string): Promise<void>;
 export declare function createFlowState(client: AxiosInstance, flowId: string, stateData: CreateFlowStateRequest): Promise<CreateFlowStateResponse>;
+export declare function updateFlowState(client: AxiosInstance, stateId: string, stateData: UpdateFlowStateRequest): Promise<void>;
+export declare function deleteFlowState(client: AxiosInstance, stateId: string): Promise<void>;
+/**
+ * Update flow metadata (title, description, runner type, default model).
+ *
+ * Uses PATCH /api/v1/designer/flows/{flowId}. The platform requires the
+ * full flow descriptor; sending a partial body returns 500.
+ */
+export declare function updateFlow(client: AxiosInstance, flowId: string, flowData: UpdateFlowRequest): Promise<void>;
 export declare function createSkillParameter(client: AxiosInstance, skillId: string, paramData: CreateSkillParameterRequest): Promise<CreateSkillParameterResponse>;
 export declare function createCustomerAttribute(client: AxiosInstance, attributeData: CreateCustomerAttributeRequest): Promise<CreateCustomerAttributeResponse>;
 export declare function createProject(client: AxiosInstance, projectData: CreateProjectRequest): Promise<CreateProjectResponse>;

package/dist/api.js

@@ -77,6 +77,10 @@ export async function listFlowSkills(client, flowId) {
     const response = await client.get(`/api/v1/designer/flows/${flowId}/skills`);
     return response.data;
 }
+export async function getFlow(client, flowId) {
+    const response = await client.get(`/api/v1/designer/flows/${flowId}`);
+    return response.data;
+}
 export async function getSkill(client, skillId) {
     const response = await client.get(`/api/v1/designer/skills/${skillId}`);
     return response.data;
@@ -221,6 +225,9 @@ export async function createFlowEvent(client, flowId, eventData) {
     const response = await client.post(`/api/v1/designer/flows/${flowId}/events`, eventData);
     return response.data;
 }
+export async function updateFlowEvent(client, eventId, eventData) {
+    await client.patch(`/api/v1/designer/flows/events/${eventId}`, eventData);
+}
 export async function deleteFlowEvent(client, eventId) {
     await client.delete(`/api/v1/designer/flows/events/${eventId}`);
 }
@@ -228,6 +235,21 @@ export async function createFlowState(client, flowId, stateData) {
     const response = await client.post(`/api/v1/designer/flows/${flowId}/states`, stateData);
     return response.data;
 }
+export async function updateFlowState(client, stateId, stateData) {
+    await client.put(`/api/v1/designer/flows/states/${stateId}`, stateData);
+}
+export async function deleteFlowState(client, stateId) {
+    await client.delete(`/api/v1/designer/flows/states/${stateId}`);
+}
+/**
+ * Update flow metadata (title, description, runner type, default model).
+ *
+ * Uses PATCH /api/v1/designer/flows/{flowId}. The platform requires the
+ * full flow descriptor; sending a partial body returns 500.
+ */
+export async function updateFlow(client, flowId, flowData) {
+    await client.patch(`/api/v1/designer/flows/${flowId}`, flowData);
+}
 export async function createSkillParameter(client, skillId, paramData) {
     // Debug the parameter creation request
     console.log('Creating parameter for skill:', skillId);

package/dist/domain/strategies/sync/AttributeSyncStrategy.js

@@ -15,6 +15,7 @@ import path from 'path';
 import { getCustomerAttributes, getProjectAttributes, updateCustomerAttribute, updateProjectAttribute, listProjects } from '../../../api.js';
 import { writeFileSafe, customerAttributesPath, customerAttributesMapPath } from '../../../fsutil.js';
 import { patchYamlToPyyaml } from '../../../format/yaml-patch.js';
+import { isJsonValueType, normalizeJsonValueForStorage, jsonValuesEqual } from '../../../sync/json-attr-utils.js';
 import { sha256, saveHashes, loadHashes } from '../../../hash.js';
 /**
  * AttributeSyncStrategy - Handles attribute synchronization
@@ -142,8 +143,15 @@ export class AttributeSyncStrategy {
      */
     cleanAttribute(attr) {
         let processedValue = attr.value;
-        // Handle JSON string values
-        if (typeof attr.value === 'string' && attr.value.startsWith('[{') && attr.value.endsWith('}]')) {
+        // Coerce JSON-typed values to a STRING. The API may return parsed
+        // objects for `value_type: json`; if we let yaml.dump turn them into
+        // YAML structures, the next push sends an object and the Workflow
+        // Builder canvas blanks out. See src/sync/json-attr-utils.ts.
+        if (isJsonValueType(attr.value_type)) {
+            processedValue = normalizeJsonValueForStorage(attr.value);
+        }
+        else if (typeof attr.value === 'string' && attr.value.startsWith('[{') && attr.value.endsWith('}]')) {
+            // Legacy: reformat array-of-objects JSON strings for readability
             try {
                 const parsed = JSON.parse(attr.value);
                 processedValue = JSON.stringify(parsed, null, 0);
@@ -243,10 +251,22 @@ export class AttributeSyncStrategy {
             const remoteAttr = remoteMap.get(localAttr.idn);
             if (!remoteAttr)
                 continue;
-            if (String(localAttr.value) !== String(remoteAttr.value)) {
+            // For JSON-typed attrs, compare canonical JSON (handles
+            // pretty/compact and string/object differences). Always send the
+            // value as a STRING so the platform stores the canvas the way the
+            // Workflow Builder expects to read it back.
+            const isJson = isJsonValueType(localAttr.value_type);
+            const valuesAreEqual = isJson
+                ? jsonValuesEqual(localAttr.value, remoteAttr.value)
+                : String(localAttr.value) === String(remoteAttr.value);
+            if (!valuesAreEqual) {
+                const valueToSend = isJson
+                    ? normalizeJsonValueForStorage(localAttr.value)
+                    : localAttr.value;
                 await updateCustomerAttribute(client, {
-                    id: attributeId,
-                    ...localAttr
+                    ...localAttr,
+                    value: valueToSend,
+                    id: attributeId
                 });
                 updatedCount++;
                 this.logger.info(`  ✓ Updated customer attribute: ${localAttr.idn}`);
@@ -286,10 +306,20 @@ export class AttributeSyncStrategy {
             const remoteAttr = remoteMap.get(localAttr.idn);
             if (!remoteAttr)
                 continue;
-            if (String(localAttr.value) !== String(remoteAttr.value)) {
+            // Same canonical-JSON / always-string-on-push policy as customer
+            // attributes (see pushCustomerAttributes for rationale).
+            const isJson = isJsonValueType(localAttr.value_type);
+            const valuesAreEqual = isJson
+                ? jsonValuesEqual(localAttr.value, remoteAttr.value)
+                : String(localAttr.value) === String(remoteAttr.value);
+            if (!valuesAreEqual) {
+                const valueToSend = isJson
+                    ? normalizeJsonValueForStorage(localAttr.value)
+                    : localAttr.value;
                 await updateProjectAttribute(client, project.id, {
-                    id: attributeId,
-                    ...localAttr
+                    ...localAttr,
+                    value: valueToSend,
+                    id: attributeId
                 });
                 updatedCount++;
                 this.logger.info(`  ✓ Updated project attribute: ${projectIdn}/${localAttr.idn}`);

package/dist/domain/strategies/sync/ProjectSyncStrategy.d.ts

@@ -75,6 +75,13 @@ export declare class ProjectSyncStrategy implements ISyncStrategy<ProjectMeta, L
      * Push changed projects to NEWO platform
      */
     push(customer: CustomerConfig, changes?: ChangeItem<LocalProjectData>[]): Promise<PushResult>;
+    /**
+     * Push a flow metadata.yaml change — syncs title, events, and state_fields
+     * to the platform. Closes GH issue #3 (events/title silently un-synced).
+     *
+     * Path shape: newo_customers/{customer}/projects/{project}/{agent}/{flow}/metadata.yaml
+     */
+    private pushFlowMetadataUpdate;
     /**
      * Push a skill update
      */

package/dist/domain/strategies/sync/ProjectSyncStrategy.js

@@ -12,7 +12,8 @@
  */
 import fs from 'fs-extra';
 import yaml from 'js-yaml';
-import { listProjects, listAgents, listFlowSkills, listFlowEvents, listFlowStates, updateSkill, publishFlow, listLibraries, updateLibrarySkill, } from '../../../api.js';
+import { listProjects, listAgents, listFlowSkills, listFlowEvents, listFlowStates, updateSkill, publishFlow, listLibraries, updateLibrarySkill, getFlow, } from '../../../api.js';
+import { syncFlowMetadata, emptyFlowSyncCounts, totalFlowSyncOps, describeFlowSyncCounts } from '../../../sync/flow-metadata.js';
 import { ensureState, writeFileSafe, mapPath, projectMetadataPath, agentMetadataPath, flowMetadataPath, skillMetadataPath, skillScriptPath, skillFolderPath, flowsYamlPath, customerProjectsDir, projectDir, libraryMetadataPath, librarySkillMetadataPath, librarySkillScriptPath, } from '../../../fsutil.js';
 import { sha256, saveHashes, loadHashes } from '../../../hash.js';
 import { generateFlowsYaml } from '../../../sync/metadata.js';
@@ -354,6 +355,23 @@ export class ProjectSyncStrategy {
         for (const change of changes) {
             try {
                 if (change.operation === 'modified') {
+                    // Flow-level metadata.yaml needs different handling than a skill
+                    // script: we sync title/events/state_fields rather than uploading a
+                    // file. Detected by filename. (GH issue #3)
+                    if (change.path.endsWith('/metadata.yaml') && !change.path.includes('/libraries/')) {
+                        const pathParts = change.path.split('/');
+                        // {customer}/projects/{project}/{agent}/{flow}/metadata.yaml
+                        // Last 5 segments end with metadata.yaml; skip if it's a skill
+                        // metadata file (one extra segment) - skill metadata is handled
+                        // by V1 legacy push, not by this strategy yet.
+                        const tail = pathParts.slice(-5);
+                        const isFlowMeta = tail[0] === 'projects' || tail[2] && tail[4] === 'metadata.yaml';
+                        if (isFlowMeta && tail.length === 5) {
+                            const updateResult = await this.pushFlowMetadataUpdate(client, change, mapData, newHashes);
+                            result.updated += updateResult;
+                            continue;
+                        }
+                    }
                     const isLibrary = change.path.includes('/libraries/');
                     if (isLibrary) {
                         const updateResult = await this.pushLibrarySkillUpdate(client, change, mapData, newHashes);
@@ -381,6 +399,53 @@ export class ProjectSyncStrategy {
         }
         return result;
     }
+    /**
+     * Push a flow metadata.yaml change — syncs title, events, and state_fields
+     * to the platform. Closes GH issue #3 (events/title silently un-synced).
+     *
+     * Path shape: newo_customers/{customer}/projects/{project}/{agent}/{flow}/metadata.yaml
+     */
+    async pushFlowMetadataUpdate(client, change, mapData, newHashes) {
+        const pathParts = change.path.split('/');
+        // Tail: projects/{project}/{agent}/{flow}/metadata.yaml
+        const flowIdn = pathParts[pathParts.length - 2] || '';
+        const agentIdn = pathParts[pathParts.length - 3] || '';
+        const projectIdn = pathParts[pathParts.length - 4] || '';
+        const projectData = mapData.projects[projectIdn];
+        const agentData = projectData?.agents[agentIdn];
+        const flowData = agentData?.flows[flowIdn];
+        if (!flowData?.id) {
+            this.logger.warn(`Flow metadata change but flow not in project map: ${projectIdn}/${agentIdn}/${flowIdn}`);
+            return 0;
+        }
+        const content = await fs.readFile(change.path, 'utf8');
+        let localFlow;
+        try {
+            localFlow = yaml.load(content);
+        }
+        catch (error) {
+            throw new Error(`Failed to parse ${change.path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        let remoteFlow = null;
+        try {
+            remoteFlow = await getFlow(client, flowData.id);
+        }
+        catch (error) {
+            this.logger.verbose(`Could not GET flow ${flowIdn}: ${error.response?.status ?? error.message}`);
+        }
+        const counts = emptyFlowSyncCounts();
+        await syncFlowMetadata(client, flowData.id, localFlow, remoteFlow, false, counts);
+        const total = totalFlowSyncOps(counts);
+        if (total > 0) {
+            this.logger.info(`↑ Flow ${flowIdn}: ${describeFlowSyncCounts(counts)}`);
+        }
+        for (const err of counts.errors) {
+            this.logger.warn(err);
+        }
+        // Stamp the hash so the next push skips this file unless it changes again.
+        newHashes[change.path] = sha256(content);
+        return total;
+    }
     /**
      * Push a skill update
      */
@@ -488,6 +553,21 @@ export class ProjectSyncStrategy {
         for (const [projectIdn, projectData] of Object.entries(mapData.projects)) {
             for (const [agentIdn, agentData] of Object.entries(projectData.agents)) {
                 for (const [flowIdn, flowData] of Object.entries(agentData.flows)) {
+                    // Flow metadata change detection (title/events/state_fields).
+                    // Surfaced as a change so push() picks it up alongside skill edits.
+                    const flowMetaPath = flowMetadataPath(customer.idn, projectIdn, agentIdn, flowIdn);
+                    if (await fs.pathExists(flowMetaPath)) {
+                        const content = await fs.readFile(flowMetaPath, 'utf8');
+                        const currentHash = sha256(content);
+                        const storedHash = hashes[flowMetaPath];
+                        if (storedHash !== currentHash) {
+                            changes.push({
+                                item: {},
+                                operation: 'modified',
+                                path: flowMetaPath
+                            });
+                        }
+                    }
                     for (const [skillIdn, _skillData] of Object.entries(flowData.skills)) {
                         const skillFile = await getSingleSkillFile(customer.idn, projectIdn, agentIdn, flowIdn, skillIdn);
                         if (skillFile) {

package/dist/domain/strategies/sync/V2ProjectSyncStrategy.d.ts

@@ -54,6 +54,17 @@ export declare class V2ProjectSyncStrategy implements ISyncStrategy<ProjectMeta,
      */
     private pullLibrary;
     push(customer: CustomerConfig, changes?: ChangeItem<LocalProjectData>[]): Promise<PushResult>;
+    /**
+     * Recognize the V2 flow YAML location: .../agents/{agent}/flows/{flow}/{flow}.yaml
+     * Distinguishes it from skill scripts, library YAMLs, and attribute files.
+     */
+    private isV2FlowYamlPath;
+    /**
+     * Push V2 flow YAML changes. Closes GH issue #3 for newo_v2 layout.
+     * Parses the V2 YAML, converts to V1-shaped FlowMetadata, and reuses the
+     * shared syncFlowMetadata routine that calls PATCH/POST/DELETE per child.
+     */
+    private pushV2FlowYamlUpdate;
     /**
      * Push a V2 skill update
      *

package/dist/domain/strategies/sync/V2ProjectSyncStrategy.js

@@ -14,12 +14,13 @@
  *           skills/{SkillIdn}.nsl|.nslg
  */
 import fs from 'fs-extra';
-import { listProjects, listAgents, listFlowSkills, listFlowEvents, listFlowStates, updateSkill, publishFlow, getProjectAttributes, getCustomerAttributes, listLibraries, updateLibrarySkill, } from '../../../api.js';
+import { listProjects, listAgents, listFlowSkills, listFlowEvents, listFlowStates, updateSkill, publishFlow, getProjectAttributes, getCustomerAttributes, listLibraries, updateLibrarySkill, getFlow, } from '../../../api.js';
+import { syncFlowMetadata, emptyFlowSyncCounts, totalFlowSyncOps, describeFlowSyncCounts } from '../../../sync/flow-metadata.js';
 import { ensureStateOnly, writeFileSafe, mapPath, } from '../../../fsutil.js';
 import { sha256, saveHashes, loadHashes } from '../../../hash.js';
 import { v2ImportVersionPath, v2ProjectYamlPath, v2AgentYamlPath, v2FlowYamlPath, v2SkillScriptPath, v2SkillRelativePath, v2ProjectAttributesPath, v2CustomerAttributesPath, v2AkbDir, v2AkbPath, v2LibraryYamlPath, v2LibrarySkillScriptPath, v2LibrarySkillRelativePath, } from '../../../format/paths-v2.js';
 import { V2_IMPORT_VERSION, } from '../../../format/types.js';
-import { generateV2FlowYaml, generateV2ProjectYaml, generateV2AgentYaml, buildV2InlineSkill, buildV2FlowEvent, buildV2StateField, } from '../../../format/v2-yaml.js';
+import { generateV2FlowYaml, generateV2ProjectYaml, generateV2AgentYaml, buildV2InlineSkill, buildV2FlowEvent, buildV2StateField, parseV2FlowYaml, } from '../../../format/v2-yaml.js';
 import { isContentDifferent } from '../../../sync/skill-files.js';
 import yaml from 'js-yaml';
 import { patchYamlToPyyaml } from '../../../format/yaml-patch.js';
@@ -440,6 +441,14 @@ export class V2ProjectSyncStrategy {
         for (const change of changes) {
             try {
                 if (change.operation === 'modified') {
+                    // V2 flow YAML: newo_customers/{cust}/{proj}/agents/{agent}/flows/{flow}/{flow}.yaml
+                    // The flow YAML carries title, events, and state_fields inline, so
+                    // changes there must sync to the platform like V1 metadata.yaml.
+                    if (this.isV2FlowYamlPath(change.path)) {
+                        const count = await this.pushV2FlowYamlUpdate(client, change, mapData, newHashes);
+                        result.updated += count;
+                        continue;
+                    }
                     // Detect if this is a library skill or flow skill by path
                     const isLibrary = change.path.includes('/libraries/');
                     const count = isLibrary
@@ -458,6 +467,103 @@ export class V2ProjectSyncStrategy {
         }
         return result;
     }
+    /**
+     * Recognize the V2 flow YAML location: .../agents/{agent}/flows/{flow}/{flow}.yaml
+     * Distinguishes it from skill scripts, library YAMLs, and attribute files.
+     */
+    isV2FlowYamlPath(p) {
+        const parts = p.split('/');
+        const file = parts[parts.length - 1];
+        if (!file || !file.endsWith('.yaml'))
+            return false;
+        // .../agents/{agent}/flows/{flow}/{flow}.yaml → last 5 parts:
+        //   agents, {agent}, flows, {flow}, {flow}.yaml
+        if (parts.length < 5)
+            return false;
+        const flowsKeyword = parts[parts.length - 3];
+        const agentsKeyword = parts[parts.length - 5];
+        const flowFolder = parts[parts.length - 2] || '';
+        const stem = file.slice(0, -'.yaml'.length);
+        return flowsKeyword === 'flows' && agentsKeyword === 'agents' && stem === flowFolder;
+    }
+    /**
+     * Push V2 flow YAML changes. Closes GH issue #3 for newo_v2 layout.
+     * Parses the V2 YAML, converts to V1-shaped FlowMetadata, and reuses the
+     * shared syncFlowMetadata routine that calls PATCH/POST/DELETE per child.
+     */
+    async pushV2FlowYamlUpdate(client, change, mapData, newHashes) {
+        const parts = change.path.split('/');
+        const flowIdn = parts[parts.length - 2] || '';
+        const agentIdn = parts[parts.length - 4] || '';
+        const projectIdn = parts[parts.length - 6] || '';
+        const projectData = mapData.projects[projectIdn];
+        const agentData = projectData?.agents[agentIdn];
+        const flowData = agentData?.flows[flowIdn];
+        if (!flowData?.id) {
+            this.logger.warn(`[newo_v2] Flow YAML change but flow not in project map: ${projectIdn}/${agentIdn}/${flowIdn}`);
+            return 0;
+        }
+        const v2Flow = await parseV2FlowYaml(change.path);
+        // Convert V2 → V1-shaped FlowMetadata for the shared sync routine.
+        // V2 events lack `id` and `description`; we fill defaults so the shape
+        // matches FlowEvent[] / FlowState[] expected by syncFlowMetadata.
+        // Optional fields are omitted (not set to undefined) to satisfy
+        // exactOptionalPropertyTypes.
+        const localMeta = {
+            id: flowData.id,
+            idn: v2Flow.idn,
+            title: v2Flow.title,
+            description: v2Flow.description ?? '',
+            default_runner_type: v2Flow.default_runner_type || 'guidance',
+            default_model: {
+                provider_idn: v2Flow.default_provider_idn,
+                model_idn: v2Flow.default_model_idn,
+            },
+            events: (v2Flow.events || []).map((e) => {
+                const out = {
+                    id: '',
+                    idn: e.idn,
+                    description: '',
+                    skill_selector: e.skill_selector,
+                    interrupt_mode: (e.interrupt_mode || 'queue'),
+                    ...(e.skill_idn != null ? { skill_idn: e.skill_idn } : {}),
+                    ...(e.state_idn != null ? { state_idn: e.state_idn } : {}),
+                    ...(e.integration_idn != null ? { integration_idn: e.integration_idn } : {}),
+                    ...(e.connector_idn != null ? { connector_idn: e.connector_idn } : {}),
+                };
+                return out;
+            }),
+            state_fields: (v2Flow.state_fields || []).map((s) => {
+                const out = {
+                    id: '',
+                    idn: s.idn,
+                    title: s.title || s.idn,
+                    scope: (s.scope || 'flow'),
+                    ...(s.default_value != null ? { default_value: s.default_value } : {}),
+                };
+                return out;
+            }),
+        };
+        let remoteFlow = null;
+        try {
+            remoteFlow = await getFlow(client, flowData.id);
+        }
+        catch (error) {
+            this.logger.verbose(`[newo_v2] Could not GET flow ${flowIdn}: ${error.response?.status ?? error.message}`);
+        }
+        const counts = emptyFlowSyncCounts();
+        await syncFlowMetadata(client, flowData.id, localMeta, remoteFlow, false, counts);
+        const total = totalFlowSyncOps(counts);
+        if (total > 0) {
+            this.logger.info(`[newo_v2] ↑ Flow ${flowIdn}: ${describeFlowSyncCounts(counts)}`);
+        }
+        for (const err of counts.errors) {
+            this.logger.warn(err);
+        }
+        const content = await fs.readFile(change.path, 'utf8');
+        newHashes[change.path] = sha256(content);
+        return total;
+    }
     /**
      * Push a V2 skill update
      *
@@ -562,6 +668,23 @@ export class V2ProjectSyncStrategy {
         for (const [projectIdn, projectData] of Object.entries(mapData.projects)) {
             // Flow skills
             for (const [agentIdn, agentData] of Object.entries(projectData.agents)) {
+                for (const [flowIdn, _flowData] of Object.entries(agentData.flows)) {
+                    // V2 stores flow events / state_fields / title inline in the flow
+                    // YAML. Detect changes here so push() can sync them (GH issue #3).
+                    const flowYamlPath = v2FlowYamlPath(customer.idn, projectIdn, agentIdn, flowIdn);
+                    if (await fs.pathExists(flowYamlPath)) {
+                        const content = await fs.readFile(flowYamlPath, 'utf8');
+                        const currentHash = sha256(content);
+                        const storedHash = hashes[flowYamlPath];
+                        if (storedHash !== currentHash) {
+                            changes.push({
+                                item: {},
+                                operation: 'modified',
+                                path: flowYamlPath
+                            });
+                        }
+                    }
+                }
                 for (const [flowIdn, flowData] of Object.entries(agentData.flows)) {
                     for (const [skillIdn, skillMeta] of Object.entries(flowData.skills)) {
                         const scriptPath = v2SkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skillIdn, skillMeta.runner_type);

package/dist/sync/attributes.js

@@ -7,6 +7,7 @@ import path from 'path';
 import fs from 'fs-extra';
 import yaml from 'js-yaml';
 import { patchYamlToPyyaml } from '../format/yaml-patch.js';
+import { isJsonValueType, normalizeJsonValueForStorage, jsonValuesEqual } from './json-attr-utils.js';
 /**
  * Save customer attributes to YAML format and return content for hashing
  */
@@ -28,16 +29,23 @@ export async function saveCustomerAttributes(client, customer, verbose = false)
             if (attr.id) {
                 idMapping[attr.idn] = attr.id;
             }
-            // Special handling for complex JSON string values
+            // Coerce JSON-typed values to a STRING. The API can return the value
+            // as a parsed object for `value_type: json` attributes; if we let
+            // yaml.dump serialize that as a YAML structure the next push sends
+            // `{"value": {...}}` instead of `{"value": "..."}` and the Workflow
+            // Builder canvas breaks. See src/sync/json-attr-utils.ts for the
+            // full rationale.
             let processedValue = attr.value;
-            if (typeof attr.value === 'string' && attr.value.startsWith('[{') && attr.value.endsWith('}]')) {
+            if (isJsonValueType(attr.value_type)) {
+                processedValue = normalizeJsonValueForStorage(attr.value);
+            }
+            else if (typeof attr.value === 'string' && attr.value.startsWith('[{') && attr.value.endsWith('}]')) {
+                // Legacy: reformat array-of-objects JSON strings for readability
                 try {
-                    // Parse and reformat JSON for better readability
                     const parsed = JSON.parse(attr.value);
-                    processedValue = JSON.stringify(parsed, null, 0); // No extra spacing, but valid JSON
+                    processedValue = JSON.stringify(parsed, null, 0); // compact, valid JSON
                 }
                 catch (e) {
-                    // Keep original if parsing fails
                     processedValue = attr.value;
                 }
             }
@@ -114,9 +122,13 @@ export async function saveProjectAttributes(client, customer, projectId, project
             if (attr.id) {
                 idMapping[attr.idn] = attr.id;
             }
-            // Special handling for complex JSON string values
+            // Coerce JSON-typed values to a STRING. See json-attr-utils.ts for
+            // why this matters (Workflow Builder canvas blank-screen bug).
             let processedValue = attr.value;
-            if (typeof attr.value === 'string' && attr.value.startsWith('[{') && attr.value.endsWith('}]')) {
+            if (isJsonValueType(attr.value_type)) {
+                processedValue = normalizeJsonValueForStorage(attr.value);
+            }
+            else if (typeof attr.value === 'string' && attr.value.startsWith('[{') && attr.value.endsWith('}]')) {
                 try {
                     const parsed = JSON.parse(attr.value);
                     processedValue = JSON.stringify(parsed, null, 0);
@@ -243,17 +255,31 @@ export async function pushProjectAttributes(client, customer, projectId, project
         }
         // Value type is already parsed (we removed !enum tags above)
         const valueType = localAttr.value_type;
-        // Check if value changed (use ?? to preserve 0, false, empty string)
-        const localValue = String(localAttr.value ?? '');
-        const remoteValue = String(remoteAttr.value ?? '');
-        if (localValue !== remoteValue) {
+        const isJson = isJsonValueType(valueType);
+        // Check if value changed.
+        // For JSON-typed values, compare canonical (compact) JSON so that
+        // pretty- vs compact-printed forms don't register as changes and
+        // string vs object representations compare equal. For everything
+        // else, fall back to the existing String() comparison (which still
+        // preserves 0, false, "" via ??).
+        const valuesAreEqual = isJson
+            ? jsonValuesEqual(localAttr.value, remoteAttr.value)
+            : String(localAttr.value ?? '') === String(remoteAttr.value ?? '');
+        if (!valuesAreEqual) {
             if (verbose)
                 console.log(`   🔄 Updating project attribute: ${localAttr.idn}`);
             try {
+                // Always send JSON-typed values as a STRING. If the API or our
+                // YAML loader handed us an object, the platform stores it
+                // differently from the original string and the Workflow Builder
+                // canvas blanks out.
+                const valueToSend = isJson
+                    ? normalizeJsonValueForStorage(localAttr.value)
+                    : localAttr.value;
                 const attributeToUpdate = {
                     id: attributeId,
                     idn: localAttr.idn,
-                    value: localAttr.value,
+                    value: valueToSend,
                     title: localAttr.title,
                     description: localAttr.description,
                     group: localAttr.group,