onbuzz 4.4.0 → 4.6.0

package/src/tools/imageTool.js

@@ -8,6 +8,13 @@ import os from 'os';
 import { promises as fs } from 'fs';
 import { BaseTool } from './baseTool.js';
 import { getGalleryService } from '../services/galleryService.js';
+import {
+  resolveTargetFormat,
+  transcodeIfNeeded,
+  extensionFor,
+  ensureExtension,
+  DEFAULT_FORMAT,
+} from './imageFormat.js';
 
 /**
  * Configuration constants for image generation
@@ -224,19 +231,37 @@ export class ImageTool extends BaseTool {
 - Just output the command when you want to generate or edit an image
 - If generation fails, output a NEW command with corrections
 
-**USAGE — Generate:**
+**USAGE — Generate (default WebP):**
 \`\`\`json
 {
   "toolId": "image-gen",
   "parameters": {
     "prompt": "Detailed description of the image",
-    "outputPath": "images/filename.png",
+    "outputPath": "images/filename.webp",
     "size": "1024x1024"
   }
 }
 \`\`\`
 
-**USAGE — Generate with Transparency:**
+**USAGE — Force PNG output (when you specifically need lossless / older-tool compat):**
+\`\`\`json
+{
+  "toolId": "image-gen",
+  "parameters": {
+    "prompt": "Pixel-art icon set on white",
+    "outputPath": "images/icons.png"
+  }
+}
+\`\`\`
+Or, equivalently, with the explicit field:
+\`\`\`json
+{
+  "toolId": "image-gen",
+  "parameters": { "prompt": "Pixel-art icon set", "outputType": "png" }
+}
+\`\`\`
+
+**USAGE — Generate with Transparency (WebP supports alpha):**
 \`\`\`json
 {
   "toolId": "image-gen",
@@ -244,7 +269,7 @@ export class ImageTool extends BaseTool {
     "prompt": "A cute fox mascot on a transparent background",
     "model": "gpt-image-1.5",
     "transparency": true,
-    "outputPath": "images/fox-mascot.png"
+    "outputPath": "images/fox-mascot.webp"
   }
 }
 \`\`\`
@@ -257,14 +282,19 @@ export class ImageTool extends BaseTool {
     "prompt": "Remove the background and make it transparent",
     "sourceImage": "images/photo.png",
     "model": "gpt-image-1.5",
-    "outputPath": "images/photo-nobg.png"
+    "outputPath": "images/photo-nobg.webp"
   }
 }
 \`\`\`
+(The \`sourceImage\` can be any common format — PNG, JPEG, WebP, etc. The OUTPUT format is whatever you specify on \`outputPath\` / \`outputType\`, defaulting to WebP.)
 
 **Parameters:**
 - **prompt** (required): Description of image to generate OR editing instruction
 - **outputPath** (optional): Path to save image (permanent). Omit for temp file.
+  The file extension determines output format (.webp / .png / .jpg / .jpeg).
+- **outputType** (optional): Explicit format request when outputPath has no extension
+  or is omitted: 'webp' | 'png' | 'jpg' | 'jpeg'. Default: 'webp'.
+  An outputPath extension always wins over outputType if both are present.
 - **size** (optional): WIDTHxHEIGHT or preset name. DIFFERENT MODELS ACCEPT DIFFERENT SIZES — read the rules below. Default: 1024x1024.
 - **quality** (optional): "standard" or "hd" (default: standard)
 - **model** (optional): "gpt-image-1.5" or a flux variant. Default: auto. Auto-switches to gpt-image-1.5 if transparency=true OR sourceImage is set.
@@ -272,6 +302,13 @@ export class ImageTool extends BaseTool {
 - **mask** (optional): Path to mask image for editing (white=edit area, black=keep area)
 - **transparency** (optional): true to generate with transparent background (forces gpt-image-1.5)
 
+**Output format (NEW default: WebP):**
+The tool transcodes provider bytes (typically PNG) into WebP by default —
+smaller files, same visual quality. Force PNG with either an explicit
+.png extension on outputPath OR \`outputType: "png"\`. Pick PNG when you
+need lossless graphics or animated GIFs would otherwise be needed; WebP
+is the better default for photo-style outputs.
+
 ⚠ SIZE RULES — read before picking a size:
 
   (A) gpt-image-1.5 (auto-selected on transparency=true or sourceImage, or set explicitly):
@@ -391,10 +428,15 @@ Content moderation:
    */
   _parseImageParams(obj) {
     const outputPath = obj.outputPath || obj['output-path'] || null;
+    // Optional explicit format request. Accepts 'webp' (default if no
+    // outputPath ext), 'png', 'jpg' / 'jpeg'. The outputPath extension
+    // wins if both are present (handled in resolveTargetFormat).
+    const outputType = obj.outputType || obj['output-type'] || obj.format || null;
 
     return {
       prompt: obj.prompt || '',
       outputPath: outputPath,
+      outputType: outputType,
       saveToProject: outputPath !== null, // If path specified, save to project
       model: obj.model || IMAGE_CONFIG.DEFAULT_MODEL,
       size: obj.size || IMAGE_CONFIG.DEFAULT_SIZE,
@@ -417,10 +459,12 @@ Content moderation:
     };
 
     const outputPath = extractTag('output-path') || null;
+    const outputType = extractTag('output-type') || extractTag('format') || null;
 
     return {
       prompt: extractTag('prompt') || '',
       outputPath: outputPath,
+      outputType: outputType,
       saveToProject: outputPath !== null, // If path specified, save to project
       model: extractTag('model') || IMAGE_CONFIG.DEFAULT_MODEL,
       size: extractTag('size') || IMAGE_CONFIG.DEFAULT_SIZE,
@@ -468,6 +512,10 @@ Content moderation:
           sessionId,
           prompt: imageParams.prompt,
           outputPath: imageParams.outputPath,
+          // Explicit format request — used by the save path to decide the
+          // target format. Default behavior (no outputPath, no outputType):
+          // WebP. See imageFormat.resolveTargetFormat for precedence.
+          outputType: imageParams.outputType || null,
           saveToProject: imageParams.saveToProject,
           model: imageParams.model,
           size: imageParams.size,
@@ -1046,10 +1094,23 @@ Content moderation:
 
     try {
       if (b64Json) {
-        // Flux/GPT-Image response: Save base64 directly to disk
+        // Flux/GPT-Image response: Save base64 to disk, transcoding to
+        // the resolved target format (default webp). If transcoding
+        // fails, the helper falls back to writing original bytes — the
+        // call doesn't fail, but a warning is logged via the logger.
         this.logger?.info(`Saving base64 image to disk: ${resolvedOutputPath}`);
-        const imageBuffer = Buffer.from(b64Json, 'base64');
-        await fs.writeFile(resolvedOutputPath, imageBuffer);
+        const rawBuffer = Buffer.from(b64Json, 'base64');
+        const transcode = await transcodeIfNeeded(rawBuffer, job._targetFormat || DEFAULT_FORMAT, {
+          quality: 85, logger: this.logger,
+        });
+        await fs.writeFile(resolvedOutputPath, transcode.buffer);
+        if (transcode.transcoded) {
+          this.logger?.info(`Image transcoded ${transcode.inputFormat} → ${transcode.outputFormat}`, {
+            outputPath: resolvedOutputPath,
+            inputBytes:  rawBuffer.length,
+            outputBytes: transcode.buffer.length,
+          });
+        }
 
         // Verify the file was actually written
         const stat = await fs.stat(resolvedOutputPath);
@@ -1063,9 +1124,9 @@ Content moderation:
         // For web display, we'll use our local server endpoint (set below)
         displayUrl = null; // Will be converted to web URL later
       } else if (imageUrl) {
-        // URL response: Download from URL
+        // URL response: Download from URL, then transcode to target format.
         this.logger?.info(`Downloading image from URL: ${imageUrl.substring(0, 50)}...`);
-        await this._downloadImage(imageUrl, resolvedOutputPath);
+        await this._downloadImage(imageUrl, resolvedOutputPath, job._targetFormat || DEFAULT_FORMAT);
 
         // Verify the file was actually written
         const stat = await fs.stat(resolvedOutputPath);
@@ -1114,15 +1175,30 @@ Content moderation:
    * @private
    */
   async _resolveOutputPath(job) {
+    // Resolve target format ONCE here so the auto-generated filename
+    // uses the right extension. Caller should also use job._targetFormat
+    // (cached on the job) when transcoding bytes.
+    const { format: targetFormat } = resolveTargetFormat({
+      outputPath: job.outputPath,
+      outputType: job.outputType,
+    });
+    job._targetFormat = targetFormat;
+    const ext = extensionFor(targetFormat);
+
     if (job.saveToProject) {
       // Save to project directory
       const projectDir = job.projectDir || process.cwd();
 
       let outputPath = job.outputPath;
       if (!outputPath) {
-        // Auto-generate filename
+        // Auto-generate filename — DEFAULT format is webp now (was png).
+        // Agents that need PNG must pass an explicit outputPath with
+        // .png extension OR outputType:'png'.
         const timestamp = Date.now();
-        outputPath = `images/generated-${timestamp}.png`;
+        outputPath = `images/generated-${timestamp}.${ext}`;
+      } else {
+        // Append format extension when the agent supplied a name without one
+        outputPath = ensureExtension(outputPath, targetFormat);
       }
 
       const resolvedPath = path.isAbsolute(outputPath)
@@ -1149,9 +1225,10 @@ Content moderation:
       // Save to temp directory
       await fs.mkdir(this.tempDir, { recursive: true });
 
+      // Temp dir path — same default-extension policy as project save.
       let filename = job.outputPath
-        ? path.basename(job.outputPath)
-        : `generated-${job.jobId}.png`;
+        ? path.basename(ensureExtension(job.outputPath, targetFormat))
+        : `generated-${job.jobId}.${ext}`;
 
       return path.join(this.tempDir, filename);
     }
@@ -1161,7 +1238,7 @@ Content moderation:
    * Download image from URL
    * @private
    */
-  async _downloadImage(imageUrl, outputPath) {
+  async _downloadImage(imageUrl, outputPath, targetFormat = DEFAULT_FORMAT) {
     try {
       const response = await fetch(imageUrl, {
         signal: AbortSignal.timeout(IMAGE_CONFIG.DOWNLOAD_TIMEOUT)
@@ -1172,9 +1249,21 @@ Content moderation:
       }
 
       const buffer = Buffer.from(await response.arrayBuffer());
-      await fs.writeFile(outputPath, buffer);
-
-      this.logger?.info(`Image saved to: ${outputPath}`);
+      // Transcode to target format if needed (defensive: fallback writes
+      // original bytes if sharp can't load — see imageFormat.js).
+      const transcode = await transcodeIfNeeded(buffer, targetFormat, {
+        quality: 85, logger: this.logger,
+      });
+      await fs.writeFile(outputPath, transcode.buffer);
+      if (transcode.transcoded) {
+        this.logger?.info(`Downloaded image transcoded ${transcode.inputFormat} → ${transcode.outputFormat}`, {
+          outputPath,
+          inputBytes:  buffer.length,
+          outputBytes: transcode.buffer.length,
+        });
+      } else {
+        this.logger?.info(`Image saved to: ${outputPath}`);
+      }
 
     } catch (error) {
       if (error.name === 'TimeoutError') {

package/src/tools/jobDoneTool.js

@@ -178,6 +178,18 @@ IMPORTANT - COMPLETION TIMING: - Call this tool IMMEDIATELY when your task is co
               details: {
                 type: 'string',
                 description: 'Optional: Additional details about what was done, what failed, any files created, or next steps for the user'
+              },
+              outputs: {
+                // v2 flows: when this agent is running inside a flow node
+                // that declares typed outputs, populate this object with
+                // each declared field. Runtime validation rejects missing
+                // fields and triggers a retry — schema is permissive but
+                // runtime is strict. The text below is what the LLM sees
+                // alongside REQUIRED OUTPUTS in the system prompt; phrased
+                // strongly so model defaults toward including it.
+                type: 'object',
+                description: 'REQUIRED when your system prompt contains a "REQUIRED OUTPUTS" section (i.e. you are in a flow). Provide a JSON object with one key per declared output field name, holding the value matching the declared type. Example: if REQUIRED OUTPUTS lists "draft (text), wordCount (number)", emit outputs: { "draft": "<full text>", "wordCount": 850 }. Omitting any required field causes the flow node to fail and retry. Outside of flows this field is ignored.',
+                additionalProperties: true
               }
             },
             required: ['action', 'summary'],
@@ -217,6 +229,90 @@ IMPORTANT - COMPLETION TIMING: - Call this tool IMMEDIATELY when your task is co
       }
 
       const agentId = context.agentId;
+
+      // Phase 8: when this agent is running inside a flow node with
+      // declared outputs, validate action.outputs against the contract
+      // BEFORE signaling completion. Returning a tool error here gives
+      // the model immediate feedback in its current response cycle —
+      // it can re-call jobdone with the missing fields populated, no
+      // executor round-trip, no conversation reset.
+      //
+      // Falls through (no validation) when not in a flow OR when the
+      // node has no declared outputs — keeps non-flow uses untouched.
+      let activeFlowContract = null;
+      if (this.flowExecutor && agentId && typeof this.flowExecutor.getActiveContract === 'function') {
+        activeFlowContract = this.flowExecutor.getActiveContract(agentId);
+      }
+      if (activeFlowContract) {
+        const contract = activeFlowContract;
+        if (contract && Array.isArray(contract.outputs) && contract.outputs.length > 0) {
+          const provided = (action.outputs && typeof action.outputs === 'object') ? action.outputs : {};
+          const missing = [];
+          for (const decl of contract.outputs) {
+            if (!decl || typeof decl.name !== 'string') continue;
+            if (!(decl.name in provided) || provided[decl.name] === null || provided[decl.name] === undefined) {
+              missing.push(decl);
+            }
+          }
+          if (missing.length > 0) {
+            const declList = contract.outputs
+              .map(o => `  • ${o.name}: ${o.type}${o.description ? ` — ${o.description}` : ''}`).join('\n');
+            const exampleEntries = contract.outputs.map(o => {
+              let exVal = '<value>';
+              if (o.example !== undefined && o.example !== null) {
+                try { exVal = JSON.stringify(o.example); } catch {}
+              } else {
+                // Type-specific placeholders
+                if (o.type === 'text')          exVal = '"<your text>"';
+                else if (o.type === 'number')   exVal = '0';
+                else if (o.type === 'boolean')  exVal = 'true';
+                else if (o.type === 'json')     exVal = '{ "key": "value" }';
+                else if (o.type === 'file')     exVal = '"/path/to/file"';
+                else if (o.type === 'file[]')   exVal = '["/path/to/file"]';
+                else if (o.type === 'list<text>') exVal = '["item 1", "item 2"]';
+              }
+              return `      "${o.name}": ${exVal}`;
+            }).join(',\n');
+            const errorMsg =
+              `Cannot complete: missing required output field(s): ${missing.map(m => m.name).join(', ')}.
+
+This step's flow node declares ALL of these outputs:
+${declList}
+
+Re-call jobdone with EVERY field above populated in the "outputs" object.
+Use this exact shape (replace placeholder values with your real content):
+
+{
+  "toolId": "jobdone",
+  "actions": [{
+    "action": "complete",
+    "summary": "<your summary>",
+    "outputs": {
+${exampleEntries}
+    }
+  }]
+}
+
+The flow CANNOT proceed until all required output fields are populated.`;
+
+            this.logger?.info(`JobDone: Rejected — flow contract missing outputs`, {
+              agentId,
+              missing: missing.map(m => m.name),
+              declared: contract.outputs.map(o => o.name),
+            });
+
+            return {
+              success: false,
+              error: errorMsg,
+              output: errorMsg,
+              taskComplete: false,
+              flowContractViolation: true,
+              missingOutputs: missing.map(m => m.name),
+            };
+          }
+        }
+      }
+
       let agent = null;
       let agentInfo = '';
 
@@ -239,7 +335,16 @@ IMPORTANT - COMPLETION TIMING: - Call this tool IMMEDIATELY when your task is co
       // If there are pending tasks and the agent claims success, reject.
       // The agent must clear/complete its task list first.
       // Exception: success=false means the agent is giving up (stuck/unable to proceed).
-      if (pendingTasks.length > 0 && action.success !== false) {
+      //
+      // Flow exception: when this agent is running inside a flow node, the
+      // Phase 8 contract validation above is the authoritative gate. The
+      // task list contains scheduler-poke artifacts (auto-created from
+      // queued user messages) that aren't real "user-tracked work" — they
+      // exist purely so the scheduler picks the agent up. Letting the
+      // legacy pendingTasks check fire here would block legitimate
+      // contract-correct job-done calls and force the agent into a
+      // taskmanager dance for tasks the user never actually authored.
+      if (pendingTasks.length > 0 && action.success !== false && !activeFlowContract) {
         const taskListStr = pendingTasks
           .map((t, i) => `${i + 1}. [${t.status}] ${t.title}`)
           .join('\n');
@@ -284,12 +389,15 @@ IMPORTANT - COMPLETION TIMING: - Call this tool IMMEDIATELY when your task is co
           agent.lastCompletionDetails = action.details || null;
           await this.agentPool.persistAgentState(agentId);
 
-          // Signal flow executor directly (if agent is running inside a flow)
+          // Signal flow executor directly (if agent is running inside a flow).
+          // v2: forward structured `outputs` bag verbatim — the executor
+          // validates it against the node's declared contract.
           if (this.flowExecutor) {
             this.flowExecutor.notifyAgentCompletion(agentId, {
               summary: action.summary,
               details: action.details,
-              success: isSuccessful
+              success: isSuccessful,
+              outputs: action.outputs
             });
           }
 

package/src/tools/platformControl/ancestry.js

@@ -0,0 +1,85 @@
+/**
+ * Ancestry checks for platformControlTool's hard rules.
+ *
+ * Each agent record carries `createdBy: <agentId> | null`. An agent
+ * created via this tool inherits the caller's id as its parent;
+ * agents created via the UI have `createdBy: null` (no parent).
+ *
+ * The hard rule "no descendant modifies an ancestor" requires walking
+ * UP the caller's chain looking for the target. Done as a pure function
+ * over an `(id) → agent` lookup so it's testable without an agent pool.
+ *
+ * Defenses:
+ *   - Cycle detection (visited set). The data model isn't supposed to
+ *     have cycles, but a corrupt state file shouldn't crash the tool.
+ *   - Depth cap (CHAIN_MAX). Hard ceiling on chain walks; if a real
+ *     deployment ever sees a chain this deep, we have other problems.
+ *   - Missing-agent tolerance. If the lookup returns null mid-walk we
+ *     stop cleanly — orphaned chains are treated as "no further parent".
+ */
+
+export const CHAIN_MAX = 100;
+
+/**
+ * Returns true if `targetId` appears in `callerId`'s ancestor chain.
+ * Self is NOT counted as an ancestor here — the self-modify rule is a
+ * separate check at the call site (`targetId === callerId`).
+ *
+ * @param {string} callerId
+ * @param {string} targetId
+ * @param {(id: string) => ({ id?: string, createdBy?: string|null }|null|undefined)} getAgent
+ * @returns {boolean}
+ */
+export function isAncestor(callerId, targetId, getAgent) {
+  if (!callerId || !targetId) return false;
+  if (callerId === targetId) return false;        // self isn't an ancestor in this sense
+  if (typeof getAgent !== 'function') return false;
+
+  const visited = new Set([callerId]);
+  let cursorId = callerId;
+  for (let i = 0; i < CHAIN_MAX; i++) {
+    const cursor = getAgent(cursorId);
+    if (!cursor) return false;
+    const parentId = cursor.createdBy;
+    if (!parentId) return false;
+    if (parentId === targetId) return true;
+    if (visited.has(parentId)) return false;      // cycle — bail
+    visited.add(parentId);
+    cursorId = parentId;
+  }
+  return false;
+}
+
+/**
+ * Convenience: would `callerId` be blocked by the hard rules from
+ * mutating `targetId`? Combines self-modify + ancestor-modify checks.
+ */
+export function isProtectedFromCaller(callerId, targetId, getAgent) {
+  if (!callerId || !targetId) return false;
+  if (callerId === targetId) return true;          // self-modify forbidden
+  return isAncestor(callerId, targetId, getAgent);
+}
+
+/**
+ * Build a `getAgent` lookup from an iterable of agents (Map, array,
+ * agentPool.getAllAgents() result). Used by the tool when it has the
+ * full set in hand and doesn't want to do async lookups inside the
+ * pure ancestry walk.
+ */
+export function makeAgentLookup(agents) {
+  if (!agents) return () => null;
+  if (typeof agents.get === 'function' && typeof agents.has === 'function') {
+    return (id) => agents.get(id) || null;
+  }
+  if (Array.isArray(agents)) {
+    const map = new Map(agents.filter(a => a && a.id).map(a => [a.id, a]));
+    return (id) => map.get(id) || null;
+  }
+  // Plain object
+  if (typeof agents === 'object') {
+    return (id) => agents[id] || null;
+  }
+  return () => null;
+}
+
+export default { CHAIN_MAX, isAncestor, isProtectedFromCaller, makeAgentLookup };

package/src/tools/platformControl/cascadeService.js

@@ -0,0 +1,146 @@
+/**
+ * Cascade-on-delete service for platformControlTool.
+ *
+ * Independent of the tool's permission logic — that gates whether a
+ * delete is allowed; THIS module does the actual cleanup once the
+ * delete is approved. Modular + testable: every dependency is injected,
+ * each step is independently observable, and failures in earlier steps
+ * don't abort later ones unless `strict:true`.
+ *
+ * Why this lives in its own file:
+ *   - The tool's dispatch is already long; embedding the cleanup choreography
+ *     would obscure the permission logic.
+ *   - The cleanup needs to be testable WITHOUT spinning up real services
+ *     (real ScheduleService writes files, real AgentPool spawns processes).
+ *   - Future deletions (delete-team-with-cascade, delete-agent-with-flow-cleanup)
+ *     can plug new steps in here without touching the tool dispatcher.
+ *
+ * Step order for cascadeDeleteAgent — in this exact order, on purpose:
+ *   1. Schedules: deleted FIRST so they can't fire mid-cleanup and re-spawn work.
+ *   2. Memories: small file deletion; if it fails, agent state is still cleanable.
+ *   3. Team memberships: removes the agentId from every team that contains it.
+ *   4. The agent itself (agentPool.deleteAgent): handles attachments, terminal
+ *      processes, visual editor, persistent state — all already implemented there.
+ *
+ * Each step yields an entry on the report. The caller surfaces this to
+ * the agent making the call so they know what happened.
+ */
+
+/**
+ * @param {object} args
+ * @param {string} args.agentId
+ * @param {object} args.scheduleService   — `listSchedules`, `deleteSchedule`
+ * @param {object} args.memoryService     — `deleteMemoryFile(agentId)`
+ * @param {object} args.stateManager      — `getAllTeams`, `removeAgentFromTeam`
+ * @param {object} args.agentPool         — `deleteAgent(agentId)`
+ * @param {object} [args.logger]          — { warn(msg, meta) }
+ * @param {boolean} [args.strict=false]   — abort on first failure
+ * @returns {Promise<{
+ *   schedulesDeleted: number,
+ *   memoriesCleaned: boolean,
+ *   teamsLeft: string[],
+ *   agentDeleted: boolean,
+ *   errors: Array<{ step: string, error: string }>,
+ * }>}
+ */
+export async function cascadeDeleteAgent({
+  agentId,
+  scheduleService,
+  memoryService,
+  stateManager,
+  agentPool,
+  logger,
+  strict = false,
+}) {
+  if (!agentId) throw new Error('cascadeDeleteAgent: agentId is required');
+
+  const report = {
+    schedulesDeleted: 0,
+    memoriesCleaned: false,
+    teamsLeft: [],
+    agentDeleted: false,
+    errors: [],
+  };
+  const log = logger || { warn() {} };
+
+  // Wrapper so each step is independently fail-tolerant. In strict mode,
+  // the first failure throws and skips the rest.
+  const step = async (name, fn) => {
+    try { await fn(); }
+    catch (err) {
+      const msg = err?.message || String(err);
+      report.errors.push({ step: name, error: msg });
+      log.warn(`[cascadeDeleteAgent] step "${name}" failed`, { agentId, error: msg });
+      if (strict) throw err;
+    }
+  };
+
+  // 1. Schedules
+  await step('schedules', async () => {
+    if (!scheduleService) return;
+    const all = typeof scheduleService.listSchedules === 'function'
+      ? scheduleService.listSchedules() : [];
+    const owned = (Array.isArray(all) ? all : []).filter(s =>
+      s && s.targetType === 'agent' && s.targetId === agentId);
+    for (const s of owned) {
+      await scheduleService.deleteSchedule(s.id);
+      report.schedulesDeleted++;
+    }
+  });
+
+  // 2. Memory file
+  await step('memories', async () => {
+    if (!memoryService || typeof memoryService.deleteMemoryFile !== 'function') return;
+    const ok = await memoryService.deleteMemoryFile(agentId);
+    report.memoriesCleaned = !!ok;
+  });
+
+  // 3. Team memberships
+  await step('teams', async () => {
+    if (!stateManager || typeof stateManager.getAllTeams !== 'function') return;
+    const teams = await stateManager.getAllTeams();
+    const containing = (Array.isArray(teams) ? teams : []).filter(t =>
+      t && Array.isArray(t.memberAgentIds) && t.memberAgentIds.includes(agentId));
+    for (const t of containing) {
+      await stateManager.removeAgentFromTeam(t.id, agentId);
+      report.teamsLeft.push(t.id);
+    }
+  });
+
+  // 4. The agent record itself.
+  await step('agentPool', async () => {
+    if (!agentPool || typeof agentPool.deleteAgent !== 'function') {
+      throw new Error('agentPool.deleteAgent unavailable');
+    }
+    await agentPool.deleteAgent(agentId);
+    report.agentDeleted = true;
+  });
+
+  return report;
+}
+
+/**
+ * Team delete is much simpler — `stateManager.deleteTeam` already
+ * removes the team record (and the memberships die with it because
+ * they live INSIDE the team object, not in a separate join table).
+ *
+ * Kept here for symmetry and to centralize "what does cascade-delete
+ * mean per resource type" in one file.
+ */
+export async function cascadeDeleteTeam({ teamId, stateManager, logger }) {
+  if (!teamId) throw new Error('cascadeDeleteTeam: teamId is required');
+  const log = logger || { warn() {} };
+  const report = { teamDeleted: false, errors: [] };
+  try {
+    await stateManager.deleteTeam(teamId);
+    report.teamDeleted = true;
+  } catch (err) {
+    const msg = err?.message || String(err);
+    report.errors.push({ step: 'team', error: msg });
+    log.warn('[cascadeDeleteTeam] failed', { teamId, error: msg });
+    throw err;       // unlike agent cascade, team-delete is a single op; rethrow.
+  }
+  return report;
+}
+
+export default { cascadeDeleteAgent, cascadeDeleteTeam };