newo 3.7.1 → 3.7.3

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.7.3] - 2026-05-25
+
+### Fixed
+
+- **Workflow Builder canvas blank-screen, take two** - JSON-typed attribute values that contain Markdown body text with `\_` escapes (Builder uses backslash-underscore to escape underscores) and/or structural newlines from pretty-printed JSON no longer corrupt the canvas on push. Two bugs were leaking through v3.7.1's STRING-coercion fix: (a) `yaml.dump` of a pretty-printed JSON string emitted a double-quoted scalar with `\n` escape sequences, which `patchYamlToPyyaml` then rewrote as a single-quoted scalar where `\n` became two literal chars - Builder's `JSON.parse` then choked on backslash-n as structural whitespace; (b) `\_` is not a valid JSON escape per RFC 8259 and Chrome V8's `JSON.parse` throws on it, silently blanking the Builder. Fix: `normalizeJsonValueForStorage` now strips invalid escape sequences via a quote-aware walker (`fixInvalidJsonEscapes`), then compacts via `JSON.parse` + `JSON.stringify` so the value is a single-line string that survives `yaml.dump` -> `patchYamlToPyyaml` without escape-sequence corruption. Existing pretty-printed canvases in `attributes.yaml` will be reformatted to compact form on next pull (one-time stylistic diff, no semantic loss). Change-detection (`jsonValuesEqual`) continues to canonicalize both sides so the new compact form does not trigger spurious pushes against remotes that may still be pretty. Reported by Bob in [#7](https://github.com/sabbah13/newo-cli/pull/7); 25 regression tests in `test/json-attribute-roundtrip.test.js` covering both bug families and the full pull -> dump -> patch -> reload -> `JSON.parse` pipeline.
+
+### Added
+
+- **`fixInvalidJsonEscapes(s)`** in `src/sync/json-attr-utils.ts` - quote-aware walker that strips invalid JSON escape sequences (`\_`, `\.`, etc.) inside JSON string values per RFC 8259. Preserves all valid escapes (`\" \\ \/ \b \f \n \r \t \uXXXX`) and structural characters outside strings.
+
+## [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
@@ -1039,7 +1061,9 @@ Another Item: $Price [Modifiers: modifier3]
 - GitHub Actions CI/CD integration
 - Robust authentication with token refresh
 
-[Unreleased]: https://github.com/sabbah13/newo-cli/compare/v3.7.1...HEAD
+[Unreleased]: https://github.com/sabbah13/newo-cli/compare/v3.7.3...HEAD
+[3.7.3]: https://github.com/sabbah13/newo-cli/compare/v3.7.2...v3.7.3
+[3.7.2]: https://github.com/sabbah13/newo-cli/compare/v3.7.1...v3.7.2
 [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

package/README.md

@@ -8,6 +8,8 @@
 **NEWO CLI** - Professional command-line tool for NEWO AI Agent development. Features **modular architecture**, **IDN-based file management**, and **comprehensive multi-customer support**.
 
 Sync NEWO "Project → Agent → Flow → Skills" structure to local files with:
+- 🆕 **Canvas blank-screen hardening** (v3.7.3) - JSON-typed attributes (e.g. Workflow Builder canvas) with Markdown `\_` escapes or structural newlines no longer corrupt the canvas on push ([#7](https://github.com/sabbah13/newo-cli/pull/7))
+- 🆕 **Flow metadata sync** (v3.7.2) - `newo push` now reconciles flow title, events, and state_fields from local `metadata.yaml` to the platform (closes [#3](https://github.com/sabbah13/newo-cli/issues/3))
 - 🆕 **Dual format support** (v3.6.0) - `cli_v1` (native) and `newo_v2` (platform compatible), auto-detected per customer
 - 🆕 **Libraries** (v3.6.0) - Pull/push shared reusable skills across agents within a project
 - 🆕 **Bulk export** (v3.6.0) - `newo export` downloads complete V2 ZIP from platform
@@ -153,6 +155,28 @@ NEWO_REFRESH_URL=custom_refresh_endpoint   # Custom refresh endpoint
 | `newo import-akb` | Import knowledge base articles | • Structured text parsing<br>• Bulk article import<br>• Validation and error reporting |
 | `newo meta` | Get project metadata (debug) | • Project structure analysis<br>• Metadata validation |
 
+### Flow Metadata Sync (NEW v3.7.2)
+
+`newo push` now reconciles **flow-level metadata** — title, `events:`, and `state_fields:` — from local YAML to the platform. Before v3.7.2 push only uploaded skill scripts, so edits to a flow's `metadata.yaml` (V1) or `{FlowIdn}.yaml` (V2) silently never reached the platform; events added via `newo create-event` could appear to disappear after a pull → push cycle. Closes [#3](https://github.com/sabbah13/newo-cli/issues/3).
+
+**How it works:**
+
+| Local change in `metadata.yaml` | What push does |
+|---|---|
+| `title:` changed | `PATCH /api/v1/designer/flows/{id}` with full descriptor |
+| New event in `events:` | `POST /api/v1/designer/flows/{id}/events` |
+| Event field edited | `PATCH /api/v1/designer/flows/events/{eventId}` |
+| Event removed from list | `DELETE /api/v1/designer/flows/events/{eventId}` |
+| Same for `state_fields:` | Mirrored CRUD against `/states` |
+
+**Safety:**
+
+- **Hash-gated**: flows whose `metadata.yaml` SHA256 is unchanged are *not* compared against the platform. Stale local trees cannot wipe events you created via the Builder UI.
+- **Full sync on changed flows**: when you *do* edit `metadata.yaml`, local becomes the source of truth for that flow. Events present on the platform but missing locally are deleted. To keep events created out-of-band, run `newo pull` before editing.
+- **Push output**: changed flows print `↑ Flow <flow>: events +N/~N/-N, states +N/~N/-N` so you see exactly what synced.
+
+**Available in:** legacy V1 push path (`pushChanged`), `ProjectSyncStrategy`, and `V2ProjectSyncStrategy`. Works the same with `newo push --format cli_v1` and `--format newo_v2`.
+
 ### Lint, Format, Check (NEW v3.7.0)
 
 Static-analysis over DSL files, powered by [`newo-dsl-analyzer`](https://www.npmjs.com/package/newo-dsl-analyzer). Same engine that runs in the VS Code extension - no drift between editor and CI.

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/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/flow-metadata.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Flow metadata sync — reconciles local flow metadata.yaml with the platform.
+ *
+ * Closes the gap behind GH issue #3 (push wiping flow event subscriptions and
+ * title): before this module existed, push only updated skill scripts. Local
+ * edits to flow title, events, or state_fields silently never reached the
+ * platform; new events created via `newo create-event` had no path to flow
+ * therefore disappeared from local metadata.yaml after a subsequent pull.
+ *
+ * Reconciliation strategy per flow (only runs when metadata.yaml hash changed):
+ *  - Compare local FlowMetadata against fresh GET responses from the platform
+ *  - Update flow title/description/runner via PATCH /api/v1/designer/flows/{id}
+ *  - For each child collection (events, state_fields):
+ *      • idn present locally + missing remotely → create
+ *      • idn present in both, contents differ   → update
+ *      • idn missing locally + present remotely → delete
+ *
+ * Hash-gating is critical: if the user never touched metadata.yaml, we never
+ * compute a remote diff, which means a stale or partially-pulled tree cannot
+ * accidentally wipe events that were created out-of-band via the Builder UI.
+ */
+import type { AxiosInstance } from 'axios';
+import type { FlowMetadata, FlowEvent, FlowState } from '../types.js';
+export interface FlowMetadataSyncCounts {
+    flowsUpdated: number;
+    eventsCreated: number;
+    eventsUpdated: number;
+    eventsDeleted: number;
+    statesCreated: number;
+    statesUpdated: number;
+    statesDeleted: number;
+    errors: string[];
+}
+export declare function emptyFlowSyncCounts(): FlowMetadataSyncCounts;
+/**
+ * True when remote FlowEvent fields differ from what the local metadata says.
+ * We only compare semantic fields the platform stores - `id` is platform-owned.
+ */
+export declare function flowEventDiffers(local: FlowEvent, remote: FlowEvent): boolean;
+export declare function flowStateDiffers(local: FlowState, remote: FlowState): boolean;
+/**
+ * Reconcile one flow's metadata with the platform.
+ *
+ * @param client          authenticated Axios client
+ * @param flowId          platform flow ID (UUID)
+ * @param local           parsed FlowMetadata from the customer's local YAML
+ * @param remoteFlow      flow data fetched from GET /flows/{id} - if null,
+ *                        flow-level updates are skipped (still syncs children).
+ *                        Pass null when caller already knows the GET endpoint
+ *                        will 404 (e.g. legacy data) or wants children-only.
+ * @param verbose         when true, emits per-operation log lines
+ * @param counts          shared counter mutated in place across multiple flows
+ */
+export declare function syncFlowMetadata(client: AxiosInstance, flowId: string, local: FlowMetadata, remoteFlow: {
+    title: string;
+    description: string | null;
+    default_runner_type?: string;
+} | null, verbose: boolean, counts: FlowMetadataSyncCounts): Promise<void>;
+/**
+ * Combined count of operations across all categories.
+ */
+export declare function totalFlowSyncOps(counts: FlowMetadataSyncCounts): number;
+/**
+ * Human-readable summary line for the push report.
+ */
+export declare function describeFlowSyncCounts(counts: FlowMetadataSyncCounts): string;
+//# sourceMappingURL=flow-metadata.d.ts.map