newo 3.7.1 → 3.7.2

package/src/domain/strategies/sync/V2ProjectSyncStrategy.ts

@@ -33,6 +33,7 @@ import type {
   Skill,
   FlowEvent,
   FlowState,
+  FlowMetadata,
   ProjectData,
   ProjectMap,
   SkillMetadata
@@ -51,7 +52,14 @@ import {
   getCustomerAttributes,
   listLibraries,
   updateLibrarySkill,
+  getFlow,
 } from '../../../api.js';
+import {
+  syncFlowMetadata,
+  emptyFlowSyncCounts,
+  totalFlowSyncOps,
+  describeFlowSyncCounts
+} from '../../../sync/flow-metadata.js';
 import type { LibraryResponse } from '../../../api.js';
 import {
   ensureStateOnly,
@@ -84,7 +92,10 @@ import {
   buildV2InlineSkill,
   buildV2FlowEvent,
   buildV2StateField,
+  parseV2FlowYaml,
   type V2InlineSkill,
+  type V2FlowEvent,
+  type V2StateField,
 } from '../../../format/v2-yaml.js';
 import { isContentDifferent } from '../../../sync/skill-files.js';
 import yaml from 'js-yaml';
@@ -648,6 +659,15 @@ export class V2ProjectSyncStrategy implements ISyncStrategy<ProjectMeta, LocalPr
     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
@@ -671,6 +691,115 @@ export class V2ProjectSyncStrategy implements ISyncStrategy<ProjectMeta, LocalPr
     return result;
   }
 
+  /**
+   * Recognize the V2 flow YAML location: .../agents/{agent}/flows/{flow}/{flow}.yaml
+   * Distinguishes it from skill scripts, library YAMLs, and attribute files.
+   */
+  private isV2FlowYamlPath(p: string): boolean {
+    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.
+   */
+  private async pushV2FlowYamlUpdate(
+    client: AxiosInstance,
+    change: ChangeItem<LocalProjectData>,
+    mapData: ProjectMap,
+    newHashes: HashStore
+  ): Promise<number> {
+    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: FlowMetadata = {
+      id: flowData.id,
+      idn: v2Flow.idn,
+      title: v2Flow.title,
+      description: v2Flow.description ?? '',
+      default_runner_type: (v2Flow.default_runner_type as 'guidance' | 'nsl') || 'guidance',
+      default_model: {
+        provider_idn: v2Flow.default_provider_idn,
+        model_idn: v2Flow.default_model_idn,
+      },
+      events: (v2Flow.events || []).map((e: V2FlowEvent) => {
+        const out: FlowEvent = {
+          id: '',
+          idn: e.idn,
+          description: '',
+          skill_selector: e.skill_selector as 'first' | 'last' | 'random' | 'all',
+          interrupt_mode: (e.interrupt_mode || 'queue') as 'allow' | 'deny' | '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: V2StateField) => {
+        const out: FlowState = {
+          id: '',
+          idn: s.idn,
+          title: s.title || s.idn,
+          scope: (s.scope || 'flow') as 'flow' | 'agent' | 'project' | 'global',
+          ...(s.default_value != null ? { default_value: s.default_value } : {}),
+        };
+        return out;
+      }),
+    };
+
+    let remoteFlow = null;
+    try {
+      remoteFlow = await getFlow(client, flowData.id);
+    } catch (error: any) {
+      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
    *
@@ -801,6 +930,24 @@ export class V2ProjectSyncStrategy implements ISyncStrategy<ProjectMeta, LocalPr
     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: {} as LocalProjectData,
+                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(

package/src/sync/flow-metadata.ts

@@ -0,0 +1,345 @@
+/**
+ * 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 {
+  listFlowEvents,
+  listFlowStates,
+  createFlowEvent,
+  updateFlowEvent,
+  deleteFlowEvent,
+  createFlowState,
+  updateFlowState,
+  deleteFlowState,
+  updateFlow
+} from '../api.js';
+import type {
+  FlowMetadata,
+  FlowEvent,
+  FlowState,
+  CreateFlowEventRequest,
+  UpdateFlowEventRequest,
+  CreateFlowStateRequest,
+  UpdateFlowStateRequest,
+  UpdateFlowRequest
+} from '../types.js';
+
+export interface FlowMetadataSyncCounts {
+  flowsUpdated: number;
+  eventsCreated: number;
+  eventsUpdated: number;
+  eventsDeleted: number;
+  statesCreated: number;
+  statesUpdated: number;
+  statesDeleted: number;
+  errors: string[];
+}
+
+export function emptyFlowSyncCounts(): FlowMetadataSyncCounts {
+  return {
+    flowsUpdated: 0,
+    eventsCreated: 0,
+    eventsUpdated: 0,
+    eventsDeleted: 0,
+    statesCreated: 0,
+    statesUpdated: 0,
+    statesDeleted: 0,
+    errors: []
+  };
+}
+
+/**
+ * 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 function flowEventDiffers(local: FlowEvent, remote: FlowEvent): boolean {
+  return (
+    normalizeStr(local.description) !== normalizeStr(remote.description) ||
+    normalizeStr(local.skill_selector) !== normalizeStr(remote.skill_selector) ||
+    normalizeStr(local.skill_idn) !== normalizeStr(remote.skill_idn) ||
+    normalizeStr(local.state_idn) !== normalizeStr(remote.state_idn) ||
+    normalizeStr(local.interrupt_mode) !== normalizeStr(remote.interrupt_mode) ||
+    normalizeStr(local.integration_idn) !== normalizeStr(remote.integration_idn) ||
+    normalizeStr(local.connector_idn) !== normalizeStr(remote.connector_idn)
+  );
+}
+
+export function flowStateDiffers(local: FlowState, remote: FlowState): boolean {
+  return (
+    normalizeStr(local.title) !== normalizeStr(remote.title) ||
+    normalizeStr(local.default_value) !== normalizeStr(remote.default_value) ||
+    normalizeStr(local.scope) !== normalizeStr(remote.scope)
+  );
+}
+
+/**
+ * Normalizes nullable/undefined string fields so YAML round-trips don't
+ * register as differences. `null`, `undefined`, and missing all collapse to ''.
+ */
+function normalizeStr(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  return String(value);
+}
+
+function buildEventCreateRequest(local: FlowEvent): CreateFlowEventRequest {
+  return {
+    idn: local.idn,
+    description: local.description ?? '',
+    skill_selector: local.skill_selector,
+    ...(local.skill_idn != null ? { skill_idn: local.skill_idn } : {}),
+    state_idn: local.state_idn ?? null,
+    interrupt_mode: local.interrupt_mode,
+    integration_idn: local.integration_idn ?? '',
+    connector_idn: local.connector_idn ?? ''
+  };
+}
+
+function buildEventUpdateRequest(local: FlowEvent): UpdateFlowEventRequest {
+  return {
+    idn: local.idn,
+    description: local.description ?? '',
+    skill_selector: local.skill_selector,
+    skill_idn: local.skill_idn ?? null,
+    state_idn: local.state_idn ?? null,
+    interrupt_mode: local.interrupt_mode,
+    integration_idn: local.integration_idn ?? null,
+    connector_idn: local.connector_idn ?? null
+  };
+}
+
+function buildStateCreateRequest(local: FlowState): CreateFlowStateRequest {
+  const req: CreateFlowStateRequest = {
+    title: local.title || local.idn,
+    idn: local.idn,
+    scope: local.scope
+  };
+  if (local.default_value != null) {
+    req.default_value = local.default_value;
+  }
+  return req;
+}
+
+function buildStateUpdateRequest(local: FlowState): UpdateFlowStateRequest {
+  const req: UpdateFlowStateRequest = {
+    title: local.title || local.idn,
+    idn: local.idn,
+    scope: local.scope
+  };
+  if (local.default_value != null) {
+    req.default_value = local.default_value;
+  }
+  return req;
+}
+
+function shouldUpdateFlow(local: FlowMetadata, remote: { title: string; description: string | null; default_runner_type?: string }): boolean {
+  return (
+    normalizeStr(local.title) !== normalizeStr(remote.title) ||
+    normalizeStr(local.description) !== normalizeStr(remote.description) ||
+    normalizeStr(local.default_runner_type) !== normalizeStr(remote.default_runner_type)
+  );
+}
+
+/**
+ * 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 async 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> {
+  // 1. Flow-level fields (title, description, runner type)
+  if (remoteFlow && shouldUpdateFlow(local, remoteFlow)) {
+    try {
+      const updateRequest: UpdateFlowRequest = {
+        idn: local.idn,
+        title: local.title,
+        description: local.description ?? '',
+        default_runner_type: local.default_runner_type,
+        default_model: local.default_model
+      };
+      await updateFlow(client, flowId, updateRequest);
+      counts.flowsUpdated++;
+      if (verbose) {
+        console.log(`    ↑ Updated flow metadata: ${local.idn} (title: "${remoteFlow.title}" → "${local.title}")`);
+      }
+    } catch (error: unknown) {
+      const msg = error instanceof Error ? error.message : String(error);
+      counts.errors.push(`Failed to update flow ${local.idn}: ${msg}`);
+      console.error(`    ❌ Failed to update flow ${local.idn}: ${msg}`);
+    }
+  }
+
+  // 2. Events
+  let remoteEvents: FlowEvent[] = [];
+  try {
+    remoteEvents = await listFlowEvents(client, flowId);
+  } catch (error: unknown) {
+    const msg = error instanceof Error ? error.message : String(error);
+    counts.errors.push(`Failed to list events for flow ${local.idn}: ${msg}`);
+    return;
+  }
+
+  const localEvents = local.events ?? [];
+  const remoteByIdn = new Map(remoteEvents.map(e => [e.idn, e]));
+  const localByIdn = new Map(localEvents.map(e => [e.idn, e]));
+
+  // Create or update events present locally
+  for (const localEvent of localEvents) {
+    const remote = remoteByIdn.get(localEvent.idn);
+    if (!remote) {
+      // Create
+      try {
+        await createFlowEvent(client, flowId, buildEventCreateRequest(localEvent));
+        counts.eventsCreated++;
+        if (verbose) console.log(`    ↑ Created event: ${local.idn}/${localEvent.idn}`);
+      } catch (error: unknown) {
+        const msg = error instanceof Error ? error.message : String(error);
+        counts.errors.push(`Failed to create event ${localEvent.idn} in flow ${local.idn}: ${msg}`);
+        console.error(`    ❌ Failed to create event ${localEvent.idn}: ${msg}`);
+      }
+    } else if (flowEventDiffers(localEvent, remote)) {
+      try {
+        await updateFlowEvent(client, remote.id, buildEventUpdateRequest(localEvent));
+        counts.eventsUpdated++;
+        if (verbose) console.log(`    ↑ Updated event: ${local.idn}/${localEvent.idn}`);
+      } catch (error: unknown) {
+        const msg = error instanceof Error ? error.message : String(error);
+        counts.errors.push(`Failed to update event ${localEvent.idn} in flow ${local.idn}: ${msg}`);
+        console.error(`    ❌ Failed to update event ${localEvent.idn}: ${msg}`);
+      }
+    }
+  }
+
+  // Delete events present remotely but missing locally
+  for (const remoteEvent of remoteEvents) {
+    if (!localByIdn.has(remoteEvent.idn)) {
+      try {
+        await deleteFlowEvent(client, remoteEvent.id);
+        counts.eventsDeleted++;
+        if (verbose) console.log(`    ↑ Deleted event: ${local.idn}/${remoteEvent.idn}`);
+      } catch (error: unknown) {
+        const msg = error instanceof Error ? error.message : String(error);
+        counts.errors.push(`Failed to delete event ${remoteEvent.idn} in flow ${local.idn}: ${msg}`);
+        console.error(`    ❌ Failed to delete event ${remoteEvent.idn}: ${msg}`);
+      }
+    }
+  }
+
+  // 3. State fields
+  let remoteStates: FlowState[] = [];
+  try {
+    remoteStates = await listFlowStates(client, flowId);
+  } catch (error: unknown) {
+    const msg = error instanceof Error ? error.message : String(error);
+    counts.errors.push(`Failed to list states for flow ${local.idn}: ${msg}`);
+    return;
+  }
+
+  const localStates = local.state_fields ?? [];
+  const remoteStatesByIdn = new Map(remoteStates.map(s => [s.idn, s]));
+  const localStatesByIdn = new Map(localStates.map(s => [s.idn, s]));
+
+  for (const localState of localStates) {
+    const remote = remoteStatesByIdn.get(localState.idn);
+    if (!remote) {
+      try {
+        await createFlowState(client, flowId, buildStateCreateRequest(localState));
+        counts.statesCreated++;
+        if (verbose) console.log(`    ↑ Created state: ${local.idn}/${localState.idn}`);
+      } catch (error: unknown) {
+        const msg = error instanceof Error ? error.message : String(error);
+        counts.errors.push(`Failed to create state ${localState.idn} in flow ${local.idn}: ${msg}`);
+        console.error(`    ❌ Failed to create state ${localState.idn}: ${msg}`);
+      }
+    } else if (flowStateDiffers(localState, remote)) {
+      try {
+        await updateFlowState(client, remote.id, buildStateUpdateRequest(localState));
+        counts.statesUpdated++;
+        if (verbose) console.log(`    ↑ Updated state: ${local.idn}/${localState.idn}`);
+      } catch (error: unknown) {
+        const msg = error instanceof Error ? error.message : String(error);
+        counts.errors.push(`Failed to update state ${localState.idn} in flow ${local.idn}: ${msg}`);
+        console.error(`    ❌ Failed to update state ${localState.idn}: ${msg}`);
+      }
+    }
+  }
+
+  for (const remoteState of remoteStates) {
+    if (!localStatesByIdn.has(remoteState.idn)) {
+      try {
+        await deleteFlowState(client, remoteState.id);
+        counts.statesDeleted++;
+        if (verbose) console.log(`    ↑ Deleted state: ${local.idn}/${remoteState.idn}`);
+      } catch (error: unknown) {
+        const msg = error instanceof Error ? error.message : String(error);
+        counts.errors.push(`Failed to delete state ${remoteState.idn} in flow ${local.idn}: ${msg}`);
+        console.error(`    ❌ Failed to delete state ${remoteState.idn}: ${msg}`);
+      }
+    }
+  }
+}
+
+/**
+ * Combined count of operations across all categories.
+ */
+export function totalFlowSyncOps(counts: FlowMetadataSyncCounts): number {
+  return (
+    counts.flowsUpdated +
+    counts.eventsCreated + counts.eventsUpdated + counts.eventsDeleted +
+    counts.statesCreated + counts.statesUpdated + counts.statesDeleted
+  );
+}
+
+/**
+ * Human-readable summary line for the push report.
+ */
+export function describeFlowSyncCounts(counts: FlowMetadataSyncCounts): string {
+  const parts: string[] = [];
+  if (counts.flowsUpdated) parts.push(`${counts.flowsUpdated} flow(s)`);
+  if (counts.eventsCreated || counts.eventsUpdated || counts.eventsDeleted) {
+    const eventOps: string[] = [];
+    if (counts.eventsCreated) eventOps.push(`+${counts.eventsCreated}`);
+    if (counts.eventsUpdated) eventOps.push(`~${counts.eventsUpdated}`);
+    if (counts.eventsDeleted) eventOps.push(`-${counts.eventsDeleted}`);
+    parts.push(`events ${eventOps.join('/')}`);
+  }
+  if (counts.statesCreated || counts.statesUpdated || counts.statesDeleted) {
+    const stateOps: string[] = [];
+    if (counts.statesCreated) stateOps.push(`+${counts.statesCreated}`);
+    if (counts.statesUpdated) stateOps.push(`~${counts.statesUpdated}`);
+    if (counts.statesDeleted) stateOps.push(`-${counts.statesDeleted}`);
+    parts.push(`states ${stateOps.join('/')}`);
+  }
+  return parts.join(', ');
+}

package/src/sync/push.ts

@@ -1,13 +1,14 @@
 /**
  * Push operations for changed files
  */
-import { updateSkill, createAgent, createFlow, createSkill, publishFlow } from '../api.js';
+import { updateSkill, createAgent, createFlow, createSkill, publishFlow, getFlow } from '../api.js';
 import {
   ensureState,
   mapPath,
   skillMetadataPath,
   projectDir,
-  agentMetadataPath
+  agentMetadataPath,
+  flowMetadataPath
 } from '../fsutil.js';
 import {
   validateSkillFolder,
@@ -21,6 +22,12 @@ import { generateFlowsYaml } from './metadata.js';
 import { isProjectMap, isLegacyProjectMap } from './projects.js';
 import { flowsYamlPath } from '../fsutil.js';
 import { pushAllProjectAttributes } from './attributes.js';
+import {
+  syncFlowMetadata,
+  emptyFlowSyncCounts,
+  totalFlowSyncOps,
+  describeFlowSyncCounts
+} from './flow-metadata.js';
 import type { AxiosInstance } from 'axios';
 import type {
   ProjectData,
@@ -506,6 +513,72 @@ export async function pushChanged(client: AxiosInstance, customer: CustomerConfi
     }
   }
 
+  // Sync flow metadata (title, events, state_fields) for any flow whose
+  // metadata.yaml hash has changed. This closes the loop on GH issue #3:
+  // previously push only updated skill scripts, leaving local edits to
+  // flow events and title silently un-synced.
+  const flowSyncCounts = emptyFlowSyncCounts();
+  for (const [projectIdn, projectData] of Object.entries(projects)) {
+    for (const [agentIdn, agentObj] of Object.entries(projectData.agents)) {
+      for (const [flowIdn, flowObj] of Object.entries(agentObj.flows)) {
+        if (!flowObj.id) continue;
+
+        const metaPath = flowMetadataPath(customer.idn, projectIdn, agentIdn, flowIdn);
+        if (!(await fs.pathExists(metaPath))) continue;
+
+        const metaContent = await fs.readFile(metaPath, 'utf8');
+        const metaHash = sha256(metaContent);
+        const oldHash = hashes[metaPath];
+
+        if (oldHash === metaHash) {
+          if (verbose) console.log(`    ✓ Flow metadata unchanged: ${flowIdn}`);
+          continue;
+        }
+
+        if (verbose) console.log(`    🔄 Flow metadata changed, syncing: ${agentIdn}/${flowIdn}`);
+
+        let localFlow: FlowMetadata;
+        try {
+          localFlow = yaml.load(metaContent) as FlowMetadata;
+        } catch (error) {
+          console.error(`❌ Failed to parse flow metadata for ${flowIdn}: ${error instanceof Error ? error.message : String(error)}`);
+          continue;
+        }
+
+        let remoteFlow = null;
+        try {
+          remoteFlow = await getFlow(client, flowObj.id);
+        } catch (error: any) {
+          // 404 means the flow ID is stale; skip flow-level update but still
+          // try to sync children since list endpoints may still work.
+          if (verbose) {
+            console.log(`    ⚠️  Could not GET flow ${flowIdn}: ${error.response?.status ?? error.message}`);
+          }
+        }
+
+        const opsBefore = totalFlowSyncOps(flowSyncCounts);
+        await syncFlowMetadata(client, flowObj.id, localFlow, remoteFlow, verbose, flowSyncCounts);
+        const opsAfter = totalFlowSyncOps(flowSyncCounts);
+
+        if (opsAfter > opsBefore) {
+          pushed += (opsAfter - opsBefore);
+          metadataChanged = true;
+        }
+        // Hash is updated regardless of whether ops happened, so we don't
+        // re-scan the same untouched flow on the next push.
+        newHashes[metaPath] = metaHash;
+      }
+    }
+  }
+
+  const totalFlowOps = totalFlowSyncOps(flowSyncCounts);
+  if (totalFlowOps > 0) {
+    console.log(`↑ Flow metadata synced: ${describeFlowSyncCounts(flowSyncCounts)}`);
+  }
+  if (flowSyncCounts.errors.length > 0) {
+    console.warn(`⚠️  ${flowSyncCounts.errors.length} flow-metadata error(s) during push.`);
+  }
+
   if (verbose) console.log(`🔄 Scanned ${scanned} files, found ${pushed} changes`);
 
   // Push project attributes for all projects

package/src/types.ts

@@ -521,6 +521,23 @@ export interface CreateFlowEventResponse {
   id: string;
 }
 
+/**
+ * Payload for PATCH /api/v1/designer/flows/events/{eventId}
+ *
+ * Required fields per probe testing: idn, skill_selector, interrupt_mode.
+ * Sending the full event body is the platform's expected shape.
+ */
+export interface UpdateFlowEventRequest {
+  idn: string;
+  description?: string | null;
+  skill_selector: string;
+  skill_idn?: string | null;
+  state_idn?: string | null;
+  interrupt_mode: string;
+  integration_idn?: string | null;
+  connector_idn?: string | null;
+}
+
 export interface CreateFlowStateRequest {
   title: string;
   idn: string;
@@ -532,6 +549,29 @@ export interface CreateFlowStateResponse {
   id: string;
 }
 
+/**
+ * Payload for PUT /api/v1/designer/flows/states/{stateId}
+ */
+export interface UpdateFlowStateRequest {
+  title: string;
+  idn: string;
+  default_value?: string;
+  scope: string;
+}
+
+/**
+ * Payload for PATCH /api/v1/designer/flows/{flowId}
+ *
+ * Empty body returns 500; the platform requires the full descriptor.
+ */
+export interface UpdateFlowRequest {
+  idn: string;
+  title: string;
+  description?: string;
+  default_runner_type: RunnerType;
+  default_model: ModelConfig;
+}
+
 export interface CreateSkillParameterRequest {
   name: string;
   default_value?: string;