synabun 1.3.0

package/mcp-server/src/tools/leonardo-browser-tools.ts

@@ -0,0 +1,281 @@
+/**
+ * Leonardo.ai Browser MCP tools.
+ * 100% browser-based — all interaction happens via SynaBun's browser automation.
+ * No API key required.
+ *
+ * Tools: leonardo_browser_navigate, leonardo_browser_generate, leonardo_browser_library, leonardo_browser_download, leonardo_browser_reference
+ */
+
+import { z } from 'zod';
+import * as ni from '../services/neural-interface.js';
+import { text } from './response.js';
+
+const LEO_BASE = 'https://app.leonardo.ai';
+
+// ── Helper: resolve or create session ─────────────────────────
+
+async function getSession(): Promise<string | null> {
+  const resolved = await ni.resolveSession(undefined, { url: LEO_BASE });
+  if ('error' in resolved) return null;
+  return resolved.sessionId;
+}
+
+async function wait(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// ── Browser Navigate ──────────────────────────────────────────
+
+export const browserNavigateSchema = {
+  page: z.enum([
+    'home', 'library', 'image', 'video', 'upscaler',
+    'blueprints', 'flow-state', 'models',
+  ] as const).describe('Leonardo.ai page to navigate to.'),
+};
+
+export const browserNavigateDescription =
+  'Navigate the browser to a specific Leonardo.ai page. Always use this as the first step before any browser-based generation.';
+
+export async function handleBrowserNavigate(args: { page: string }) {
+  const sessionId = await getSession();
+  if (!sessionId) return text('No browser session available. Open Leonardo.ai in the browser first using browser_navigate or the Apps menu.');
+
+  const paths: Record<string, string> = {
+    'home': '/',
+    'library': '/library',
+    'image': '/image-generation',
+    'video': '/image-generation/video',
+    'upscaler': '/universal-upscaler',
+    'blueprints': '/blueprints',
+    'flow-state': '/flow-state',
+    'models': '/models-training',
+  };
+
+  const path = paths[args.page] || '/';
+  const res = await ni.navigate(sessionId, `${LEO_BASE}${path}`);
+  if (res.error) return text(`Navigation failed: ${res.error}`);
+
+  // Wait for page to settle
+  await wait(3000);
+
+  return text(`Navigated to Leonardo.ai ${args.page} page (${LEO_BASE}${path}). Use browser_snapshot to see the current UI state.`);
+}
+
+// ── Browser Generate (full UI automation) ─────────────────────
+
+export const browserGenerateSchema = {
+  prompt: z.string().describe('The generation prompt to type into Leonardo.ai.'),
+  type: z.enum(['image', 'video'] as const).optional().describe('Generation type. Default: image.'),
+};
+
+export const browserGenerateDescription =
+  'Fill the prompt field and click Generate on the current Leonardo.ai page. Set all other settings (model, style, dimensions, motion controls) BEFORE calling this — use browser_click, browser_fill, and browser_snapshot to configure the UI first. This tool only handles: navigate to correct page if needed → clear & fill prompt → click Generate.';
+
+export async function handleBrowserGenerate(args: {
+  prompt: string;
+  type?: string;
+}) {
+  const sessionId = await getSession();
+  if (!sessionId) return text('No browser session available. Open Leonardo.ai first.');
+
+  const genType = args.type || 'image';
+
+  // Check current URL — navigate only if not already on the right page
+  const snapshot = await ni.snapshot(sessionId);
+  const currentUrl = (snapshot as any)?.url || '';
+  const targetPath = genType === 'video' ? '/image-generation/video' : '/image-generation';
+
+  if (!currentUrl.includes(targetPath)) {
+    const navRes = await ni.navigate(sessionId, `${LEO_BASE}${targetPath}`);
+    if (navRes.error) return text(`Navigation failed: ${navRes.error}`);
+    await wait(3000);
+  }
+
+  // Clear and fill the prompt textbox
+  const fillRes = await ni.fill(sessionId, '[aria-label="Prompt"], textbox[name="Prompt"], textarea', args.prompt);
+  if (fillRes.error) return text(`Failed to fill prompt: ${fillRes.error}`);
+
+  await wait(500);
+
+  // Click the Generate button
+  const clickRes = await ni.click(sessionId, 'button[aria-label="Generate"], button:has-text("Generate")');
+  if (clickRes.error) return text(`Failed to click Generate: ${clickRes.error}`);
+
+  return text(`Generation started (${genType}).\n\nPrompt: "${args.prompt.substring(0, 120)}${args.prompt.length > 120 ? '...' : ''}"\n\nThe generation is processing in Leonardo.ai. Use browser_snapshot or browser_screenshot to check progress and see results. Results also appear in the library.`);
+}
+
+// ── Browser Library ───────────────────────────────────────────
+
+export const browserLibrarySchema = {
+  action: z.enum(['view', 'search'] as const).describe('Action: view (open library) or search (search for a term).'),
+  query: z.string().optional().describe('Search query (for search action).'),
+};
+
+export const browserLibraryDescription =
+  'Open or search Leonardo.ai\'s library to view past generations. Use browser_snapshot after to see results.';
+
+export async function handleBrowserLibrary(args: { action: string; query?: string }) {
+  const sessionId = await getSession();
+  if (!sessionId) return text('No browser session available.');
+
+  const navRes = await ni.navigate(sessionId, `${LEO_BASE}/library`);
+  if (navRes.error) return text(`Navigation failed: ${navRes.error}`);
+
+  await wait(2000);
+
+  if (args.action === 'search' && args.query) {
+    const fillRes = await ni.fill(sessionId, 'input[placeholder*="Search" i]', args.query);
+    if (fillRes.error) return text(`Failed to search: ${fillRes.error}`);
+    await ni.pressKey(sessionId, 'Enter');
+    return text(`Searched Leonardo.ai library for: "${args.query}". Use browser_snapshot to see results.`);
+  }
+
+  return text('Leonardo.ai library opened. Use browser_snapshot to see recent generations.');
+}
+
+// ── Browser Download / Screenshot ─────────────────────────────
+
+export const browserDownloadSchema = {
+  action: z.enum(['screenshot'] as const).describe('Action: screenshot (capture current Leonardo.ai page state).'),
+};
+
+export const browserDownloadDescription =
+  'Capture a screenshot of the current Leonardo.ai page. Use to verify generation results or UI state.';
+
+export async function handleBrowserDownload(args: { action: string }) {
+  const sessionId = await getSession();
+  if (!sessionId) return text('No browser session available.');
+
+  if (args.action === 'screenshot') {
+    const res = await ni.screenshot(sessionId);
+    if (res.error) return text(`Screenshot failed: ${res.error}`);
+    return text('Screenshot captured of the current Leonardo.ai page.');
+  }
+
+  return text(`Unknown action: ${args.action}`);
+}
+
+// ── Browser Reference (upload reference images) ──────────────
+
+export const browserReferenceSchema = {
+  type: z.enum([
+    'image_ref', 'style_ref', 'content_ref', 'character_ref',
+    'image_to_image', 'start_frame', 'end_frame',
+  ] as const).describe(
+    'Reference type. Image generation: image_ref, style_ref, content_ref, character_ref, image_to_image. ' +
+    'Video generation: start_frame, end_frame. Availability depends on the selected model — check the model advisor.',
+  ),
+  filePaths: z.array(z.string()).describe(
+    'Absolute file paths of images to upload as reference. Get paths from image_staged tool or from user-attached images.',
+  ),
+  autoClear: z.boolean().optional().describe(
+    'Auto-delete the source images from data/images/ after successful upload. Default: true.',
+  ),
+};
+
+export const browserReferenceDescription =
+  'Upload reference image(s) to Leonardo.ai for guided generation. Supports image references, style/content/character references, ' +
+  'image-to-image, and video start/end frames. Must be called AFTER selecting a model (reference type availability is model-dependent) ' +
+  'and BEFORE calling leonardo_browser_generate. Uses browser automation to click the reference panel, upload the file(s), and confirm. ' +
+  'By default, auto-clears uploaded images from the SynaBun image store after success.';
+
+export async function handleBrowserReference(args: {
+  type: string;
+  filePaths: string[];
+  autoClear?: boolean;
+}) {
+  const sessionId = await getSession();
+  if (!sessionId) return text('No browser session available. Open Leonardo.ai first.');
+
+  const { type, filePaths, autoClear = true } = args;
+  const isVideo = type === 'start_frame' || type === 'end_frame';
+
+  // Step 1: Open the reference panel
+  let openResult: { error?: string };
+
+  if (isVideo) {
+    // Video: click "Add Image Guidance to generation" button
+    openResult = await ni.evaluate(sessionId, `(() => {
+      const btns = document.querySelectorAll('button');
+      for (const b of btns) {
+        if (b.textContent.includes('Image Guidance') || b.textContent.includes('Add Image')) {
+          b.click(); return 'opened';
+        }
+      }
+      return 'not found';
+    })()`);
+  } else {
+    // Image: click "Add elements" button
+    openResult = await ni.evaluate(sessionId, `(() => {
+      const btns = document.querySelectorAll('button');
+      for (const b of btns) {
+        if (b.textContent.includes('Add elements') || b.textContent.includes('Add Elements')) {
+          b.click(); return 'opened';
+        }
+      }
+      return 'not found';
+    })()`);
+  }
+
+  if (openResult.error) return text(`Failed to open reference panel: ${openResult.error}`);
+  await wait(1500);
+
+  // Step 2: For image references, click the specific reference type tab/button
+  if (!isVideo) {
+    const typeLabels: Record<string, string[]> = {
+      'image_ref': ['Image Reference', 'Image Ref', 'Image Input'],
+      'style_ref': ['Style Reference', 'Style Ref'],
+      'content_ref': ['Content Reference', 'Content Ref'],
+      'character_ref': ['Character Reference', 'Character Ref'],
+      'image_to_image': ['Image to Image', 'Img2Img'],
+    };
+
+    const labels = typeLabels[type] || [type];
+    const labelSearch = labels.map(l => `b.textContent.includes('${l}')`).join(' || ');
+
+    const selectResult = await ni.evaluate(sessionId, `(() => {
+      const btns = document.querySelectorAll('button, [role="tab"], [role="menuitem"]');
+      for (const b of btns) {
+        if (${labelSearch}) { b.click(); return 'selected'; }
+      }
+      return 'not found — use browser_snapshot to see available options';
+    })()`);
+
+    if (selectResult.error) return text(`Failed to select reference type: ${selectResult.error}. Use browser_snapshot to see the panel.`);
+    await wait(1000);
+  }
+
+  // Step 3: Find file input and upload
+  const uploadResult = await ni.upload(sessionId, 'input[type="file"]', filePaths);
+  if (uploadResult.error) {
+    // Fallback: try broader selector
+    const fallback = await ni.upload(sessionId, 'input[accept*="image"]', filePaths);
+    if (fallback.error) {
+      return text(
+        `Failed to upload reference image(s): ${uploadResult.error}. ` +
+        `The file input may not be visible yet — try browser_snapshot to inspect the panel, ` +
+        `then use browser_upload manually with the correct selector.`,
+      );
+    }
+  }
+
+  await wait(1000);
+
+  // Step 4: Auto-clear source images if requested
+  if (autoClear) {
+    const { basename } = await import('path');
+    for (const fp of filePaths) {
+      const filename = basename(fp);
+      try {
+        await ni.deleteImage(filename);
+      } catch { /* ignore cleanup errors */ }
+    }
+  }
+
+  const typeLabel = type.replace(/_/g, ' ');
+  return text(
+    `Reference uploaded (${typeLabel}): ${filePaths.length} image(s).\n` +
+    `${autoClear ? 'Source images auto-cleared from store.\n' : ''}` +
+    `Use browser_snapshot to verify the reference is applied, then proceed with leonardo_browser_generate.`,
+  );
+}

package/mcp-server/src/tools/leonardo.ts

@@ -0,0 +1,28 @@
+/**
+ * Leonardo.ai MCP tool registration barrel.
+ * 100% browser-based — no API key required.
+ * Registers 4 Leonardo browser tools on the given server instance.
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import {
+  browserNavigateSchema, browserNavigateDescription, handleBrowserNavigate,
+  browserGenerateSchema, browserGenerateDescription, handleBrowserGenerate,
+  browserLibrarySchema, browserLibraryDescription, handleBrowserLibrary,
+  browserDownloadSchema, browserDownloadDescription, handleBrowserDownload,
+  browserReferenceSchema, browserReferenceDescription, handleBrowserReference,
+} from './leonardo-browser-tools.js';
+
+/**
+ * Register all Leonardo.ai MCP tools on the given server instance.
+ * These are browser-based tools that automate the Leonardo.ai web UI.
+ * Use the /leonardo skill for the full guided creation experience.
+ */
+export function registerLeonardoTools(server: McpServer) {
+  server.tool('leonardo_browser_navigate', browserNavigateDescription, browserNavigateSchema, handleBrowserNavigate);
+  server.tool('leonardo_browser_generate', browserGenerateDescription, browserGenerateSchema, handleBrowserGenerate);
+  server.tool('leonardo_browser_library', browserLibraryDescription, browserLibrarySchema, handleBrowserLibrary);
+  server.tool('leonardo_browser_download', browserDownloadDescription, browserDownloadSchema, handleBrowserDownload);
+  server.tool('leonardo_browser_reference', browserReferenceDescription, browserReferenceSchema, handleBrowserReference);
+}

package/mcp-server/src/tools/loop.ts

@@ -0,0 +1,348 @@
+import { z } from 'zod';
+import { readFileSync, writeFileSync, existsSync, unlinkSync, mkdirSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { text } from './response.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DATA_DIR = join(__dirname, '..', '..', 'data');
+// Loop state files and templates live in the project root data dir (Synabun/data/)
+const PROJECT_ROOT = process.env.SYNABUN_ROOT || join(__dirname, '..', '..', '..');
+const NI_DATA_DIR = join(PROJECT_ROOT, 'data');
+const LOOP_DIR = join(NI_DATA_DIR, 'loop');
+const LOOP_TEMPLATES_PATH = join(NI_DATA_DIR, 'loop-templates.json');
+
+const MAX_ITERATIONS = 50;
+const DEFAULT_ITERATIONS = 10;
+const MAX_MINUTES = 480;
+const DEFAULT_MINUTES = 60;
+
+function ensureLoopDir() {
+  if (!existsSync(LOOP_DIR)) {
+    mkdirSync(LOOP_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Resolve the session ID for loop state file.
+ * Priority: explicit param > CLAUDE_SESSION_ID env > SYNABUN_TERMINAL_SESSION env > scan.
+ *
+ * When SYNABUN_TERMINAL_SESSION is set (server-launched loop), find the loop file
+ * by matching the terminalSessionId field. This survives /clear (which changes
+ * CLAUDE_SESSION_ID) and prevents cross-loop contamination with multiple automations.
+ */
+function resolveSessionId(explicit?: string): string | null {
+  if (explicit) return explicit;
+  if (process.env.CLAUDE_SESSION_ID) return process.env.CLAUDE_SESSION_ID;
+
+  ensureLoopDir();
+
+  // Priority: find loop file owned by this terminal session (survives /clear)
+  const terminalSessionEnv = process.env.SYNABUN_TERMINAL_SESSION;
+  if (terminalSessionEnv) {
+    try {
+      const files = readdirSync(LOOP_DIR).filter(f => f.endsWith('.json') && !f.startsWith('pending-'));
+      for (const file of files) {
+        try {
+          const data = JSON.parse(readFileSync(join(LOOP_DIR, file), 'utf-8'));
+          if (data?.active && data.terminalSessionId === terminalSessionEnv) {
+            return file.replace('.json', '');
+          }
+        } catch { /* skip corrupt files */ }
+      }
+    } catch { /* dir read failed */ }
+  }
+
+  // Fallback: scan for any active loop file (legacy — no terminal scoping)
+  try {
+    const files = readdirSync(LOOP_DIR).filter(f => f.endsWith('.json'));
+    for (const file of files) {
+      try {
+        const data = JSON.parse(readFileSync(join(LOOP_DIR, file), 'utf-8'));
+        if (data?.active) return file.replace('.json', '');
+      } catch { /* skip corrupt files */ }
+    }
+  } catch { /* dir read failed */ }
+
+  return null;
+}
+
+function getLoopPath(sessionId: string): string {
+  return join(LOOP_DIR, `${sessionId}.json`);
+}
+
+export const loopSchema = {
+  action: z
+    .enum(['start', 'stop', 'status', 'update'] as const)
+    .describe('start: begin autonomous loop. stop: end loop. status: check current loop state. update: write iteration journal/progress.'),
+  task: z
+    .string()
+    .optional()
+    .describe('What to do each iteration (required for start).'),
+  iterations: z
+    .number()
+    .optional()
+    .describe(`Max iterations (1-${MAX_ITERATIONS}, default ${DEFAULT_ITERATIONS}).`),
+  max_minutes: z
+    .number()
+    .optional()
+    .describe(`Time cap in minutes (1-${MAX_MINUTES}, default ${DEFAULT_MINUTES}).`),
+  context: z
+    .string()
+    .optional()
+    .describe('Extra context injected each iteration.'),
+  session_id: z
+    .string()
+    .optional()
+    .describe('Claude Code session ID. Auto-detected if omitted.'),
+  template: z
+    .string()
+    .optional()
+    .describe('Load a saved template by name or id. Template values are used as defaults; explicit params override.'),
+  summary: z
+    .string()
+    .optional()
+    .describe('Brief summary of what this iteration accomplished (1-2 sentences, for journal). Used with action "update".'),
+  progress: z
+    .string()
+    .optional()
+    .describe('Rolling progress summary replacing the previous one. Used with action "update".'),
+};
+
+export const loopDescription =
+  'Autonomous loop control. Start a repeating task loop, check status, update progress journal, or stop it. The Stop hook drives iteration. Call "update" after each iteration with a brief summary to maintain context across compactions.';
+
+// ── Start ──────────────────────────────────────────────────────
+
+function loadTemplate(nameOrId: string): Record<string, unknown> | null {
+  try {
+    if (!existsSync(LOOP_TEMPLATES_PATH)) return null;
+    const templates = JSON.parse(readFileSync(LOOP_TEMPLATES_PATH, 'utf-8'));
+    if (!Array.isArray(templates)) return null;
+    const lower = nameOrId.toLowerCase();
+    return templates.find((t: Record<string, unknown>) =>
+      (t.id as string) === nameOrId ||
+      (t.name as string)?.toLowerCase() === lower
+    ) || null;
+  } catch { return null; }
+}
+
+function handleStart(args: {
+  task?: string;
+  iterations?: number;
+  max_minutes?: number;
+  context?: string;
+  session_id?: string;
+  template?: string;
+}) {
+  // Load template defaults if specified
+  if (args.template) {
+    const tpl = loadTemplate(args.template);
+    if (!tpl) {
+      return text(`Error: Template "${args.template}" not found. Check Settings → Automations for available templates.`);
+    }
+    // Template values as defaults; explicit params override
+    if (!args.task) args.task = tpl.task as string;
+    if (args.iterations === undefined) args.iterations = tpl.iterations as number;
+    if (args.max_minutes === undefined) args.max_minutes = tpl.maxMinutes as number;
+    if (!args.context && tpl.context) args.context = tpl.context as string;
+  }
+
+  if (!args.task?.trim()) {
+    return text('Error: "task" is required for start action. Describe what to do each iteration.');
+  }
+
+  const sessionId = resolveSessionId(args.session_id);
+  if (!sessionId) {
+    return text('Error: Could not determine session ID. Pass session_id explicitly or ensure CLAUDE_SESSION_ID is set.');
+  }
+
+  const iterations = Math.min(Math.max(args.iterations || DEFAULT_ITERATIONS, 1), MAX_ITERATIONS);
+  const maxMinutes = Math.min(Math.max(args.max_minutes || DEFAULT_MINUTES, 1), MAX_MINUTES);
+
+  ensureLoopDir();
+
+  // Check for existing active loop
+  const loopPath = getLoopPath(sessionId);
+  if (existsSync(loopPath)) {
+    try {
+      const existing = JSON.parse(readFileSync(loopPath, 'utf-8'));
+      if (existing?.active) {
+        return text(`Error: Loop already active (iteration ${existing.currentIteration}/${existing.totalIterations}). Stop it first with action "stop".`);
+      }
+    } catch { /* corrupt file, overwrite */ }
+  }
+
+  const state = {
+    active: true,
+    task: args.task.trim(),
+    totalIterations: iterations,
+    currentIteration: 0,
+    maxMinutes,
+    startedAt: new Date().toISOString(),
+    lastIterationAt: null as string | null,
+    context: args.context?.trim() || null,
+    retries: 0,
+    journal: [] as { iteration: number; summary: string; timestamp: string }[],
+    lastMemoryAt: 0,
+    memoryInterval: 5,
+    progressSummary: null as string | null,
+    awaitingNext: false,
+  };
+
+  writeFileSync(loopPath, JSON.stringify(state, null, 2));
+
+  return text([
+    `Loop started for session ${sessionId}.`,
+    `Task: ${state.task}`,
+    `Iterations: ${iterations} | Time cap: ${maxMinutes} min`,
+    state.context ? `Context: ${state.context}` : '',
+    '',
+    'The Stop hook will now drive autonomous iteration. Begin your first iteration.',
+  ].filter(Boolean).join('\n'));
+}
+
+// ── Stop ───────────────────────────────────────────────────────
+
+function handleStop(args: { session_id?: string }) {
+  const sessionId = resolveSessionId(args.session_id);
+  if (!sessionId) {
+    return text('No active loop found to stop.');
+  }
+
+  const loopPath = getLoopPath(sessionId);
+  if (!existsSync(loopPath)) {
+    return text('No active loop found for this session.');
+  }
+
+  let summary = '';
+  try {
+    const state = JSON.parse(readFileSync(loopPath, 'utf-8'));
+    const elapsed = Math.round((Date.now() - new Date(state.startedAt).getTime()) / 60000);
+    summary = ` Completed ${state.currentIteration}/${state.totalIterations} iterations in ${elapsed} min.`;
+  } catch { /* ok */ }
+
+  try { unlinkSync(loopPath); } catch { /* ok */ }
+
+  return text(`Loop stopped.${summary}`);
+}
+
+// ── Status ─────────────────────────────────────────────────────
+
+function handleStatus(args: { session_id?: string }) {
+  const sessionId = resolveSessionId(args.session_id);
+  if (!sessionId) {
+    return text('No active loop.');
+  }
+
+  const loopPath = getLoopPath(sessionId);
+  if (!existsSync(loopPath)) {
+    return text('No active loop for this session.');
+  }
+
+  let state;
+  try {
+    state = JSON.parse(readFileSync(loopPath, 'utf-8'));
+  } catch {
+    return text('Loop state file is corrupt.');
+  }
+
+  if (!state.active) {
+    const finishedAt = state.finishedAt ? ` Finished at ${state.finishedAt}.` : '';
+    return text(`Loop inactive (completed).${finishedAt} ${state.currentIteration}/${state.totalIterations} iterations done.`);
+  }
+
+  const elapsed = Math.round((Date.now() - new Date(state.startedAt).getTime()) / 60000);
+  const iterationsRemaining = state.totalIterations - (state.currentIteration || 0);
+
+  return text([
+    `Loop active: iteration ${state.currentIteration}/${state.totalIterations} (${iterationsRemaining} remaining)`,
+    `Task: ${state.task}`,
+    `Elapsed: ${elapsed} min`,
+    state.context ? `Context: ${state.context}` : '',
+    state.lastIterationAt ? `Last iteration: ${state.lastIterationAt}` : '',
+  ].filter(Boolean).join('\n'));
+}
+
+// ── Update (journal + progress) ───────────────────────────────
+
+function handleUpdate(args: {
+  session_id?: string;
+  summary?: string;
+  progress?: string;
+}) {
+  if (!args.summary && !args.progress) {
+    return text('Error: Provide "summary" (iteration journal) and/or "progress" (rolling summary) for update.');
+  }
+
+  const sessionId = resolveSessionId(args.session_id);
+  if (!sessionId) {
+    return text('No active loop to update.');
+  }
+
+  const loopPath = getLoopPath(sessionId);
+  if (!existsSync(loopPath)) {
+    return text('No loop state file found.');
+  }
+
+  let state: Record<string, unknown>;
+  try {
+    state = JSON.parse(readFileSync(loopPath, 'utf-8'));
+  } catch {
+    return text('Loop state file is corrupt.');
+  }
+
+  if (!state.active) {
+    return text('Loop is not active.');
+  }
+
+  // Append journal entry
+  if (args.summary) {
+    if (!Array.isArray(state.journal)) state.journal = [];
+    (state.journal as { iteration: number; summary: string; timestamp: string }[]).push({
+      iteration: (state.currentIteration as number) || 0,
+      summary: args.summary.slice(0, 200),
+      timestamp: new Date().toISOString(),
+    });
+    // Keep only last 10 entries
+    if ((state.journal as unknown[]).length > 10) {
+      state.journal = (state.journal as unknown[]).slice(-10);
+    }
+  }
+
+  // Update rolling progress summary
+  if (args.progress) {
+    state.progressSummary = args.progress.slice(0, 500);
+  }
+
+  writeFileSync(loopPath, JSON.stringify(state, null, 2));
+
+  return text(`Loop journal updated (iteration ${state.currentIteration}).`);
+}
+
+// ── Main dispatcher ────────────────────────────────────────────
+
+export async function handleLoop(args: {
+  action: string;
+  task?: string;
+  iterations?: number;
+  max_minutes?: number;
+  context?: string;
+  session_id?: string;
+  template?: string;
+  summary?: string;
+  progress?: string;
+}) {
+  switch (args.action) {
+    case 'start':
+      return handleStart(args);
+    case 'stop':
+      return handleStop(args);
+    case 'status':
+      return handleStatus(args);
+    case 'update':
+      return handleUpdate(args);
+    default:
+      return text(`Unknown action "${args.action}". Use: start, stop, status, update.`);
+  }
+}