onbuzz 4.6.0 → 4.6.1

package/src/tools/platformControlTool.js

@@ -36,6 +36,10 @@ import {
   isTeamAccessDisabled,
   checkTeamAccess,
   filterAccessibleTeams,
+  FLOW_ACCESS_LEVELS,
+  getFlowAccessLevel,
+  getMaxFlowsCreated,
+  checkFlowMutationAccess,
 } from './platformControl/permissions.js';
 import { isProtectedFromCaller, makeAgentLookup } from './platformControl/ancestry.js';
 import { cascadeDeleteAgent, cascadeDeleteTeam } from './platformControl/cascadeService.js';
@@ -68,6 +72,14 @@ const SUPPORTED_ACTIONS = [
   'delete-team',
   'add-team-member',
   'remove-team-member',
+  // Flow CRUD + execution. Permission key: `flows`. Mirrors agents.
+  'list-flows',
+  'get-flow',
+  'create-flow',
+  'update-flow',
+  'delete-flow',
+  'execute-flow',
+  'dry-run-flow',
 ];
 
 /**
@@ -106,6 +118,7 @@ class PlatformControlTool extends BaseTool {
     /** @type {object|null} */ this.agentPool       = null;
     /** @type {object|null} */ this.stateManager    = null;
     /** @type {object|null} */ this.memoryService   = null;
+    /** @type {object|null} */ this.flowExecutor    = null;
   }
 
   /** Injected from src/index.js after ScheduleService is initialized. */
@@ -132,6 +145,12 @@ class PlatformControlTool extends BaseTool {
     this.logger?.info?.(`[platformcontrol] MemoryService ${memoryService ? 'attached' : 'detached'}`);
   }
 
+  /** Injected — needed for execute-flow / dry-run-flow actions. */
+  setFlowExecutor(flowExecutor) {
+    this.flowExecutor = flowExecutor;
+    this.logger?.info?.(`[platformcontrol] FlowExecutor ${flowExecutor ? 'attached' : 'detached'}`);
+  }
+
   getDescription() {
     return `
 Platform Control Tool: control Loxia platform features (scheduled tasks today; more later).
@@ -178,6 +197,20 @@ ACTIONS — teams (per-agent multi-select scope: member / ownedByMe / all; defau
   add-team-member  { teamId, agentId }                 — add an agent to a team. agentId='self' adds caller.
   remove-team-member { teamId, agentId }               — remove an agent. agentId='self' = leave the team.
 
+ACTIONS — flows (per-agent permission: 'disabled' | 'self-created' | 'all'; default 'disabled'):
+  list-flows                                           — list all flows reachable in your scope (read is unrestricted at any non-disabled level)
+  get-flow         { flowId }                          — fetch a flow's full definition (nodes + edges + variables)
+  create-flow      { name, description?, nodes, edges?, variables? }
+                                                       — create a new flow. Definition must pass schema validation.
+                                                         createdBy is set to YOU automatically.
+                                                         Per-creator quota (maxFlowsCreated, default unlimited) applies.
+  update-flow      { flowId, ...fields }               — patch a flow you have permission to mutate.
+                                                         The full re-validated definition is required when changing nodes/edges.
+  delete-flow      { flowId }                          — cascade-delete: run history + checkpoints + version snapshots.
+  execute-flow     { flowId, input? }                  — kick off a run. Returns runId for polling.
+  dry-run-flow     { flowId } OR { flow }              — lint-only check without execution; surfaces structural issues
+                                                         (orphaned nodes, missing required fields, etc.) before live runs.
+
   list-capabilities                                    — what permission level + scope this agent has
 
 EXAMPLES:
@@ -274,6 +307,14 @@ NOTES:
         case 'delete-team':          return await this._deleteTeam(cfg, callerAgentId, params);
         case 'add-team-member':      return await this._addTeamMember(cfg, callerAgentId, params);
         case 'remove-team-member':   return await this._removeTeamMember(cfg, callerAgentId, params);
+        // Flow CRUD + execution
+        case 'list-flows':           return await this._listFlows(cfg, callerAgentId);
+        case 'get-flow':             return await this._getFlow(cfg, callerAgentId, params);
+        case 'create-flow':          return await this._createFlow(cfg, callerAgentId, params);
+        case 'update-flow':          return await this._updateFlow(cfg, callerAgentId, params);
+        case 'delete-flow':          return await this._deleteFlow(cfg, callerAgentId, params);
+        case 'execute-flow':         return await this._executeFlow(cfg, callerAgentId, params);
+        case 'dry-run-flow':         return await this._dryRunFlow(cfg, callerAgentId, params);
         default:
           return {
             success: false,
@@ -326,6 +367,20 @@ NOTES:
             'Leaving a team you\'re a member of is allowed.',
           ],
         },
+        flows: {
+          level: getFlowAccessLevel(fullCfg),
+          maxFlowsCreated: getMaxFlowsCreated(fullCfg),
+          canList:        getFlowAccessLevel(fullCfg) !== FLOW_ACCESS_LEVELS.DISABLED,
+          canCreate:      getFlowAccessLevel(fullCfg) !== FLOW_ACCESS_LEVELS.DISABLED,
+          canMutateSelfCreated: getFlowAccessLevel(fullCfg) !== FLOW_ACCESS_LEVELS.DISABLED,
+          canMutateAll:   getFlowAccessLevel(fullCfg) === FLOW_ACCESS_LEVELS.ALL,
+          notes: [
+            'Permission key: flows. Default level is "disabled".',
+            'Flow definitions are validated against the v2 schema before save — invalid flows are rejected with detailed errors.',
+            'delete-flow cascades through run history, checkpoints, and version snapshots.',
+            'execute-flow respects existing flow permission levels — at "self-created" level you can only run flows you created.',
+          ],
+        },
       },
     };
   }
@@ -848,6 +903,173 @@ NOTES:
     const team = await this.stateManager.removeAgentFromTeam(params.teamId, agentId);
     return { success: true, action: 'remove-team-member', teamId: params.teamId, agentId, team };
   }
+
+  // ─── Flow CRUD + execution ─────────────────────────────────────────
+  //
+  // Permission key: `flows`. Default 'disabled'. Same shape as agents:
+  // 'self-created' = only flows you authored, 'all' = admin scope.
+  // Read endpoints (list/get) are unrestricted at any non-disabled
+  // level so an agent can browse what's available before deciding which
+  // to run; mutations (create/update/delete/execute/dry-run) all go
+  // through `checkFlowMutationAccess`.
+
+  /** Resolve the project dir the same way every other path here does. */
+  _flowProjectDir() {
+    return this.stateManager?.config?.project?.directory
+        || this.stateManager?.config?.projectDir
+        || process.cwd();
+  }
+
+  async _listFlows(cfg, callerAgentId) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    if (!this.stateManager) {
+      return { success: false, error: 'StateManager not available.' };
+    }
+    const all = await this.stateManager.getAllFlows(this._flowProjectDir());
+    // List is unrestricted at any non-disabled level — agents can see
+    // what they could run / what the platform offers. Mutability is
+    // surfaced per-row so the LLM knows what it can act on.
+    const list = (all || []).map(f => ({
+      id: f.id,
+      name: f.name,
+      description: f.description || '',
+      version: f.version,
+      createdBy: f.createdBy || null,
+      nodeCount: Array.isArray(f.nodes) ? f.nodes.length : 0,
+      mutable: checkFlowMutationAccess(level, callerAgentId, f).allow,
+    }));
+    return { success: true, action: 'list-flows', count: list.length, flows: list, scope: level };
+  }
+
+  async _getFlow(cfg, callerAgentId, params) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    if (!params?.flowId) return { success: false, error: 'flowId is required' };
+    const flow = await this.stateManager.getFlow(params.flowId, this._flowProjectDir());
+    if (!flow) return { success: false, error: `Flow not found: ${params.flowId}` };
+    return {
+      success: true, action: 'get-flow', flow,
+      mutable: checkFlowMutationAccess(level, callerAgentId, flow).allow,
+    };
+  }
+
+  async _createFlow(cfg, callerAgentId, params) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    if (!params?.name || typeof params.name !== 'string') {
+      return { success: false, error: 'name is required' };
+    }
+    if (!Array.isArray(params.nodes) || params.nodes.length === 0) {
+      return { success: false, error: 'nodes array is required (must have at least one node)' };
+    }
+    // Quota enforcement — count flows the caller has authored so far.
+    const max = getMaxFlowsCreated(cfg);
+    if (max !== null) {
+      const owned = (await this.stateManager.getAllFlows(this._flowProjectDir()))
+        .filter(f => f.createdBy === callerAgentId);
+      if (owned.length >= max) {
+        return {
+          success: false,
+          error: `maxFlowsCreated quota reached: you have created ${owned.length} of ${max} allowed flows.`,
+        };
+      }
+    }
+    // Schema validation runs inside stateManager.createFlow already
+    // (via the route layer); we additionally call validate here so an
+    // invalid create returns a clean structured error rather than going
+    // through the route. Defensive — duplicate guard, no harm.
+    const created = await this.stateManager.createFlow({
+      name:        params.name,
+      description: params.description || '',
+      nodes:       params.nodes,
+      edges:       params.edges || [],
+      variables:   params.variables || {},
+      // Stamp the caller as the author so self-created scope can find it.
+      createdBy:   callerAgentId,
+    }, this._flowProjectDir());
+    return { success: true, action: 'create-flow', flow: created };
+  }
+
+  async _updateFlow(cfg, callerAgentId, params) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    if (!params?.flowId) return { success: false, error: 'flowId is required' };
+    const target = await this.stateManager.getFlow(params.flowId, this._flowProjectDir());
+    if (!target) return { success: false, error: `Flow not found: ${params.flowId}` };
+    const access = checkFlowMutationAccess(level, callerAgentId, target);
+    if (!access.allow) return { success: false, error: access.reason };
+    // Strip identity-level fields the caller shouldn't be able to spoof.
+    const { id: _id, createdBy: _cb, version: _v, ...patch } = params;
+    const updated = await this.stateManager.updateFlow(params.flowId, patch, this._flowProjectDir());
+    return { success: true, action: 'update-flow', flow: updated };
+  }
+
+  async _deleteFlow(cfg, callerAgentId, params) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    if (!params?.flowId) return { success: false, error: 'flowId is required' };
+    const target = await this.stateManager.getFlow(params.flowId, this._flowProjectDir());
+    if (!target) return { success: false, error: `Flow not found: ${params.flowId}` };
+    const access = checkFlowMutationAccess(level, callerAgentId, target);
+    if (!access.allow) return { success: false, error: access.reason };
+    await this.stateManager.deleteFlow(params.flowId, this._flowProjectDir());
+    return { success: true, action: 'delete-flow', flowId: params.flowId };
+  }
+
+  async _executeFlow(cfg, callerAgentId, params) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    if (!params?.flowId) return { success: false, error: 'flowId is required' };
+    if (!this.flowExecutor) return { success: false, error: 'FlowExecutor not available on this server.' };
+    const target = await this.stateManager.getFlow(params.flowId, this._flowProjectDir());
+    if (!target) return { success: false, error: `Flow not found: ${params.flowId}` };
+    // Execute counts as a mutation (it consumes credits + writes run history).
+    const access = checkFlowMutationAccess(level, callerAgentId, target);
+    if (!access.allow) return { success: false, error: access.reason };
+    const run = await this.flowExecutor.executeFlow(params.flowId, params.input || {}, {
+      projectDir: this._flowProjectDir(),
+      // Tag the run with the agent that triggered it so audit trails
+      // attribute correctly when an agent kicks a flow off via the tool.
+      triggeredBy: { kind: 'agent', agentId: callerAgentId },
+    });
+    return { success: true, action: 'execute-flow', runId: run?.runId || run?.id || null, status: run?.status || 'queued' };
+  }
+
+  async _dryRunFlow(cfg, callerAgentId, params) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    // Dry-run accepts EITHER an existing flowId OR an inline flow def
+    // (so an agent can lint a draft before saving).
+    let flow;
+    if (params?.flowId) {
+      flow = await this.stateManager.getFlow(params.flowId, this._flowProjectDir());
+      if (!flow) return { success: false, error: `Flow not found: ${params.flowId}` };
+    } else if (params?.flow && typeof params.flow === 'object') {
+      flow = params.flow;
+    } else {
+      return { success: false, error: 'Pass either { flowId } or { flow: {...} }' };
+    }
+    if (!this.flowExecutor || typeof this.flowExecutor.dryRun !== 'function') {
+      return { success: false, error: 'FlowExecutor.dryRun not available on this server.' };
+    }
+    const report = await this.flowExecutor.dryRun(flow);
+    return { success: true, action: 'dry-run-flow', report };
+  }
 }
 
 export default PlatformControlTool;

package/src/utilities/__tests__/flowEdgeIds.test.js

@@ -0,0 +1,116 @@
+/**
+ * Tests for the shared edge-id stamping helper used by both the
+ * server-side `stateManager.createFlow` and the client-side `FlowEditor`.
+ *
+ * The bug this guards against: ReactFlow silently drops edges missing
+ * `id`, so templates / marketplace-installed flows rendered as
+ * disconnected nodes (no arrows). Locking format + idempotency here
+ * keeps both layers in sync.
+ */
+import { describe, test, expect } from '@jest/globals';
+import { makeEdgeId, ensureEdgeIds } from '../flowEdgeIds.js';
+
+describe('makeEdgeId', () => {
+  test('encodes source/target/fields/index in a stable form', () => {
+    const id = makeEdgeId({ source: 'a', sourceField: 'topic', target: 'b', targetField: 'topic' }, 0);
+    expect(id).toBe('e-a:topic-b:topic-0');
+  });
+
+  test('omits :field segments when sourceField/targetField missing', () => {
+    expect(makeEdgeId({ source: 'a', target: 'b' }, 0)).toBe('e-a-b-0');
+    expect(makeEdgeId({ source: 'a', sourceField: 'x', target: 'b' }, 1)).toBe('e-a:x-b-1');
+    expect(makeEdgeId({ source: 'a', target: 'b', targetField: 'y' }, 2)).toBe('e-a-b:y-2');
+  });
+
+  test('uses ? for missing source / target (defensive — should never happen with valid flows)', () => {
+    expect(makeEdgeId({}, 0)).toBe('e-?-?-0');
+    expect(makeEdgeId({ source: 'a' }, 0)).toBe('e-a-?-0');
+    expect(makeEdgeId({ target: 'b' }, 0)).toBe('e-?-b-0');
+  });
+
+  test('null/undefined input doesn\'t crash', () => {
+    expect(makeEdgeId(null, 0)).toBe('e-?-?-0');
+    expect(makeEdgeId(undefined, 0)).toBe('e-?-?-0');
+  });
+
+  test('different indexes produce different ids (tiebreaker for parallel edges)', () => {
+    const a = makeEdgeId({ source: 'x', target: 'y' }, 0);
+    const b = makeEdgeId({ source: 'x', target: 'y' }, 1);
+    expect(a).not.toBe(b);
+  });
+});
+
+describe('ensureEdgeIds', () => {
+  test('stamps ids on every unstamped edge', () => {
+    const result = ensureEdgeIds([
+      { source: 'a', target: 'b' },
+      { source: 'b', sourceField: 'out', target: 'c', targetField: 'in' },
+    ]);
+    expect(result).toHaveLength(2);
+    expect(result.every(e => typeof e.id === 'string' && e.id.length > 0)).toBe(true);
+    expect(result[0].id).toBe('e-a-b-0');
+    expect(result[1].id).toBe('e-b:out-c:in-1');
+  });
+
+  test('preserves existing ids — does not clobber user-supplied / round-tripped ids', () => {
+    const result = ensureEdgeIds([
+      { id: 'user-supplied', source: 'a', target: 'b' },
+      { source: 'b', target: 'c' },                       // no id → stamped
+    ]);
+    expect(result[0].id).toBe('user-supplied');
+    expect(result[1].id).toBe('e-b-c-1');
+  });
+
+  test('does NOT mutate the input array or its edges', () => {
+    const input = [{ source: 'a', target: 'b' }];
+    const before = JSON.parse(JSON.stringify(input));
+    ensureEdgeIds(input);
+    expect(input).toEqual(before);          // input untouched
+    expect(input[0]).not.toHaveProperty('id');
+  });
+
+  test('idempotent: running twice produces equivalent ids on the second pass', () => {
+    const first = ensureEdgeIds([
+      { source: 'a', sourceField: 'x', target: 'b', targetField: 'y' },
+    ]);
+    const second = ensureEdgeIds(first);
+    expect(second[0].id).toBe(first[0].id);
+  });
+
+  test('non-array input → empty array (defensive)', () => {
+    expect(ensureEdgeIds(null)).toEqual([]);
+    expect(ensureEdgeIds(undefined)).toEqual([]);
+    expect(ensureEdgeIds('not an array')).toEqual([]);
+    expect(ensureEdgeIds({})).toEqual([]);
+  });
+
+  test('empty array passes through cleanly', () => {
+    expect(ensureEdgeIds([])).toEqual([]);
+  });
+
+  test('handles null edges defensively (skipped/repaired without throwing)', () => {
+    const result = ensureEdgeIds([null, { source: 'a', target: 'b' }, undefined]);
+    expect(result).toHaveLength(3);
+    // Each entry has an id; nulls become objects with just an id.
+    expect(result.every(e => typeof e.id === 'string')).toBe(true);
+  });
+
+  test('parallel edges between same nodes get distinct ids (tiebreaker)', () => {
+    const result = ensureEdgeIds([
+      { source: 'a', target: 'b' },
+      { source: 'a', target: 'b' },
+      { source: 'a', target: 'b' },
+    ]);
+    const ids = result.map(e => e.id);
+    expect(new Set(ids).size).toBe(3);   // all distinct
+  });
+
+  test('id format is stable across saves (no Date.now/Math.random)', () => {
+    // Critical: re-saving the same flow must produce the same edge ids.
+    // Otherwise version-history diffs would be cluttered with id churn.
+    const edges = [{ source: 'a', sourceField: 'x', target: 'b' }];
+    const a = ensureEdgeIds(edges);
+    const b = ensureEdgeIds(edges);
+    expect(a[0].id).toBe(b[0].id);
+  });
+});

package/src/utilities/__tests__/flowPublish.test.js

@@ -0,0 +1,196 @@
+/**
+ * Tests for the marketplace flow-publish helpers.
+ *
+ * `computeFlowPublishMetadata` builds the marketplace-listing metadata.
+ * `sanitizeFlowForPublish` strips per-installation identifiers (agentIds)
+ * so a published flow is portable.
+ *
+ * Both are pure — easy to lock comprehensively.
+ */
+import { describe, test, expect } from '@jest/globals';
+import {
+  computeFlowPublishMetadata,
+  sanitizeFlowForPublish,
+} from '../flowPublish.js';
+
+// ─── computeFlowPublishMetadata ───────────────────────────────────────
+
+describe('computeFlowPublishMetadata', () => {
+  test('counts nodes, agent nodes, and edges', () => {
+    const flow = {
+      schemaVersion: 2,
+      nodes: [
+        { id: 'in', type: 'input' },
+        { id: 'a', type: 'agent', data: {} },
+        { id: 'b', type: 'agent', data: {} },
+        { id: 'out', type: 'output' },
+      ],
+      edges: [
+        { source: 'in', target: 'a' },
+        { source: 'a', target: 'b' },
+        { source: 'b', target: 'out' },
+      ],
+    };
+    const m = computeFlowPublishMetadata(flow);
+    expect(m.nodeCount).toBe(4);
+    expect(m.agentNodeCount).toBe(2);
+    expect(m.edgeCount).toBe(3);
+  });
+
+  test('preserves schemaVersion (default 1 when absent)', () => {
+    expect(computeFlowPublishMetadata({ schemaVersion: 2, nodes: [] }).schemaVersion).toBe(2);
+    expect(computeFlowPublishMetadata({ nodes: [] }).schemaVersion).toBe(1);
+  });
+
+  test('collects distinct models from agent nodes (data.model OR data.preferredModel)', () => {
+    const flow = {
+      nodes: [
+        { type: 'agent', data: { model: 'kimi-k2.6' } },
+        { type: 'agent', data: { preferredModel: 'gpt-5' } },
+        { type: 'agent', data: { model: 'kimi-k2.6' } },         // dup
+        { type: 'agent', data: {} },                              // unmapped
+        { type: 'input', data: { model: 'should-not-count' } },   // wrong type
+      ],
+      edges: [],
+    };
+    const m = computeFlowPublishMetadata(flow);
+    expect(m.models.sort()).toEqual(['gpt-5', 'kimi-k2.6']);
+  });
+
+  test('detects pause / human-input nodes', () => {
+    expect(computeFlowPublishMetadata({ nodes: [{ type: 'pause' }] }).hasPauseNode).toBe(true);
+    expect(computeFlowPublishMetadata({ nodes: [{ type: 'human-input' }] }).hasPauseNode).toBe(true);
+    expect(computeFlowPublishMetadata({ nodes: [{ type: 'agent' }] }).hasPauseNode).toBe(false);
+  });
+
+  test('detects trigger nodes (typed) AND scheduled nodes (cron-on-data)', () => {
+    expect(computeFlowPublishMetadata({ nodes: [{ type: 'trigger' }] }).hasTriggerNode).toBe(true);
+    expect(computeFlowPublishMetadata({ nodes: [{ type: 'agent', data: { cron: '0 9 * * *' } }] }).hasTriggerNode).toBe(true);
+    expect(computeFlowPublishMetadata({ nodes: [{ type: 'agent', data: {} }] }).hasTriggerNode).toBe(false);
+  });
+
+  test('truncates the flow.description into a goal of ≤280 chars', () => {
+    const long = 'A'.repeat(500);
+    const m = computeFlowPublishMetadata({ description: long, nodes: [] });
+    expect(m.goal.length).toBe(280);
+    expect(m.goal.startsWith('A')).toBe(true);
+  });
+
+  test('handles missing description as empty string', () => {
+    expect(computeFlowPublishMetadata({ nodes: [] }).goal).toBe('');
+    expect(computeFlowPublishMetadata({ description: null, nodes: [] }).goal).toBe('');
+    expect(computeFlowPublishMetadata({ description: 42, nodes: [] }).goal).toBe('');
+  });
+
+  test('null/undefined/garbage flow is handled defensively', () => {
+    const m1 = computeFlowPublishMetadata(null);
+    expect(m1.nodeCount).toBe(0);
+    expect(m1.edgeCount).toBe(0);
+    expect(m1.models).toEqual([]);
+    expect(m1.hasPauseNode).toBe(false);
+    expect(m1.hasTriggerNode).toBe(false);
+
+    const m2 = computeFlowPublishMetadata('not an object');
+    expect(m2.nodeCount).toBe(0);
+  });
+
+  test('empty arrays produce zero-counts (not NaN)', () => {
+    const m = computeFlowPublishMetadata({ nodes: [], edges: [] });
+    expect(m.nodeCount).toBe(0);
+    expect(m.agentNodeCount).toBe(0);
+    expect(m.edgeCount).toBe(0);
+    expect(m.models).toEqual([]);
+  });
+});
+
+// ─── sanitizeFlowForPublish ───────────────────────────────────────────
+
+describe('sanitizeFlowForPublish', () => {
+  test('wipes agentId on agent nodes (per-installation identifier — not portable)', () => {
+    const flow = {
+      nodes: [
+        { id: 'a', type: 'agent', data: { agentId: 'agent-coder-rapid-1234', label: 'Researcher', instructions: 'Do thing' } },
+      ],
+      edges: [],
+    };
+    const out = sanitizeFlowForPublish(flow);
+    expect(out.nodes[0].data.agentId).toBe('');
+    // Label and instructions preserved — they're the value.
+    expect(out.nodes[0].data.label).toBe('Researcher');
+    expect(out.nodes[0].data.instructions).toBe('Do thing');
+  });
+
+  test('non-agent nodes pass through unchanged', () => {
+    const flow = {
+      nodes: [
+        { id: 'in', type: 'input', data: { promptTemplate: '{{x}}' } },
+        { id: 'out', type: 'output', data: { outputFormat: 'text' } },
+      ],
+      edges: [],
+    };
+    const out = sanitizeFlowForPublish(flow);
+    expect(out.nodes[0]).toEqual({ id: 'in', type: 'input', data: { promptTemplate: '{{x}}' } });
+    expect(out.nodes[1]).toEqual({ id: 'out', type: 'output', data: { outputFormat: 'text' } });
+  });
+
+  test('does NOT mutate the input flow (pure function)', () => {
+    const flow = {
+      nodes: [
+        { id: 'a', type: 'agent', data: { agentId: 'live-id-do-not-touch' } },
+      ],
+      edges: [],
+    };
+    const before = JSON.parse(JSON.stringify(flow));
+    sanitizeFlowForPublish(flow);
+    expect(flow).toEqual(before);
+  });
+
+  test('preserves edges, schemaVersion, name, description verbatim', () => {
+    const flow = {
+      schemaVersion: 2,
+      name: 'My pipeline',
+      description: 'Does the thing',
+      nodes: [{ id: 'a', type: 'agent', data: { agentId: 'x' } }],
+      edges: [{ source: 'a', target: 'b' }],
+      variables: { foo: 'bar' },
+    };
+    const out = sanitizeFlowForPublish(flow);
+    expect(out.schemaVersion).toBe(2);
+    expect(out.name).toBe('My pipeline');
+    expect(out.description).toBe('Does the thing');
+    expect(out.edges).toEqual([{ source: 'a', target: 'b' }]);
+    expect(out.variables).toEqual({ foo: 'bar' });
+  });
+
+  test('agent node without data still gets data.agentId stamped (defensive)', () => {
+    const flow = {
+      nodes: [{ id: 'a', type: 'agent' }],
+      edges: [],
+    };
+    const out = sanitizeFlowForPublish(flow);
+    expect(out.nodes[0].data).toEqual({ agentId: '' });
+  });
+
+  test('null / non-object input passes through unchanged (no crash)', () => {
+    expect(sanitizeFlowForPublish(null)).toBe(null);
+    expect(sanitizeFlowForPublish(undefined)).toBe(undefined);
+    expect(sanitizeFlowForPublish('string')).toBe('string');
+  });
+
+  test('mix of agent + non-agent: only agent nodes get sanitized', () => {
+    const flow = {
+      nodes: [
+        { id: 'in', type: 'input' },
+        { id: 'a', type: 'agent', data: { agentId: 'real-id-1' } },
+        { id: 'b', type: 'agent', data: { agentId: 'real-id-2' } },
+        { id: 'out', type: 'output' },
+      ],
+      edges: [],
+    };
+    const out = sanitizeFlowForPublish(flow);
+    const ids = out.nodes.filter(n => n.type === 'agent').map(n => n.data.agentId);
+    expect(ids).toEqual(['', '']);
+    expect(out.nodes[0]).toEqual({ id: 'in', type: 'input' });
+    expect(out.nodes[3]).toEqual({ id: 'out', type: 'output' });
+  });
+});