takomi 2.1.37 → 2.1.39

package/plugins/takomi-flow/scripts/lib/generation.mjs

@@ -0,0 +1,90 @@
+import path from 'node:path';
+import { defaultProfileDir, FLOW_URL, readJson, resolvePath } from './paths.mjs';
+import { normalizeRequest, canSpend } from './request.mjs';
+import { closeFlowBrowser, launchFlowBrowser } from './browser.mjs';
+import { createRun, baseResult, saveResult } from './result.mjs';
+import { capture, ensureProjectEditor, fillPrompt, inspectFlowState, openFlow, submitGeneration, tryDownloadAssets } from './flow-ui.mjs';
+import { handleGenerationFollowups, waitForGenerationOutcome } from './flow-outcome.mjs';
+import { catalogAssets } from './media.mjs';
+import { createSettingsPlan } from './settings-plan.mjs';
+
+export async function generateFromRequest(args = {}) {
+  if (!args.request) throw new Error('generate requires a request path.');
+  const request = normalizeRequest(readJson(path.resolve(args.request)));
+  const run = createRun(request, 'generate');
+  const result = baseResult('blocked', run, {
+    command: 'generate',
+    kind: request.kind,
+    prompt: request.prompt,
+    flowUrl: FLOW_URL,
+    settingsPlan: createSettingsPlan(request),
+  });
+  if (!canSpend(request)) {
+    result.manualActions.push('Set request allowSpend=true or TAKOMI_FLOW_ALLOW_SPEND=true to submit a Flow generation.');
+    saveResult(run, result);
+    return result;
+  }
+  const browser = await launchFlowBrowser({
+    profileDir: resolvePath(args.profileDir, defaultProfileDir()),
+    downloadsDir: run.downloadsDir,
+    browserChannel: args.browserChannel,
+    cdpUrl: args.cdpUrl,
+    headless: Boolean(args.headless),
+  });
+  try {
+    await openFlow(browser.page);
+    result.screenshots.push(await capture(browser.page, run, 'before-prompt'));
+    const state = await inspectFlowState(browser.page);
+    if (state.manualActions.length) {
+      requireManual(result, state.manualActions);
+      return result;
+    }
+    if (!(await ensureProjectEditor(browser.page))) {
+      requireManual(result, ['New project button or project editor was not found. Open a Flow project manually, then retry with --cdp-url.']);
+      return result;
+    }
+    result.projectUrl = browser.page.url();
+    result.screenshots.push(await capture(browser.page, run, 'project-editor'));
+    if (!(await fillPrompt(browser.page, request.prompt))) {
+      requireManual(result, ['Prompt box was not found. Update Flow selectors or paste the prompt manually.']);
+      return result;
+    }
+    result.screenshots.push(await capture(browser.page, run, 'prompt-filled'));
+    if (!(await submitGeneration(browser.page))) {
+      requireManual(result, ['Generate/Create button was not found. Submit manually in the opened browser.']);
+      return result;
+    }
+    result.projectUrl = browser.page.url();
+    await handleGenerationFollowups(browser.page, request);
+    result.generationOutcome = await waitForGenerationOutcome(browser.page, request);
+    result.projectUrl = browser.page.url();
+    result.screenshots.push(await capture(browser.page, run, 'after-wait'));
+    result.assets = await tryDownloadAssets(browser.page, run, request.variations);
+    if (result.assets.length) {
+      result.assetCatalogPath = (await catalogAssets(run, result.assets, { frames: request.extractFrames || 0 })).catalogPath;
+    }
+    result.status = result.assets.length ? 'downloaded' : 'manual_action_required';
+    if (!result.assets.length) {
+      result.manualActions.push(nextActionForOutcome(result.generationOutcome));
+    }
+    return result;
+  } catch (error) {
+    result.status = 'failed';
+    result.errors.push(error.message);
+    return result;
+  } finally {
+    await closeFlowBrowser(browser);
+    saveResult(run, result);
+  }
+}
+
+function requireManual(result, actions) {
+  result.status = 'manual_action_required';
+  result.manualActions.push(...actions);
+}
+
+function nextActionForOutcome(outcome = {}) {
+  if (outcome.status === 'failed') return 'Flow reported generation failure. Inspect the browser/run screenshots.';
+  if (outcome.status === 'timeout') return 'Generation did not finish before the wait timeout. Leave trusted Chrome open and run inspect/observe again.';
+  return 'Generation may still be running or download controls changed. Inspect the browser/run screenshots.';
+}

package/plugins/takomi-flow/scripts/lib/inspect.mjs

@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { defaultRunsDir, readJson } from './paths.mjs';
+
+export function inspectRun(target) {
+  const runPath = resolveRunJson(target);
+  const data = readJson(runPath);
+  return summarize(data, runPath);
+}
+
+export function latestRun(outputDir = defaultRunsDir()) {
+  const root = path.resolve(outputDir);
+  if (!fs.existsSync(root)) {
+    throw new Error(`Output directory does not exist: ${root}`);
+  }
+  const candidates = fs.readdirSync(root, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => path.join(root, entry.name, 'run.json'))
+    .filter(filePath => fs.existsSync(filePath))
+    .sort();
+  if (!candidates.length) {
+    throw new Error(`No TakomiFlow runs found in: ${root}`);
+  }
+  return summarize(readJson(candidates[candidates.length - 1]), candidates[candidates.length - 1]);
+}
+
+export function listRuns(outputDir = defaultRunsDir(), limit = 20) {
+  const root = path.resolve(outputDir);
+  if (!fs.existsSync(root)) {
+    return { schemaVersion: 1, outputDir: root, runs: [] };
+  }
+  const runFiles = fs.readdirSync(root, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => path.join(root, entry.name, 'run.json'))
+    .filter(filePath => fs.existsSync(filePath))
+    .sort()
+    .reverse()
+    .slice(0, Math.max(1, Number.parseInt(limit || '20', 10) || 20));
+  return {
+    schemaVersion: 1,
+    outputDir: root,
+    runs: runFiles.map(filePath => summarize(readJson(filePath), filePath)),
+  };
+}
+
+function resolveRunJson(target) {
+  if (!target) throw new Error('inspect requires --run <run.json|run-dir>');
+  const resolved = path.resolve(target);
+  if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+    return path.join(resolved, 'run.json');
+  }
+  return resolved;
+}
+
+export function resolveRun(target) {
+  const runJsonPath = resolveRunJson(target);
+  const data = readJson(runJsonPath);
+  return {
+    runId: data.runId || path.basename(path.dirname(runJsonPath)),
+    runDir: path.dirname(runJsonPath),
+    downloadsDir: path.join(path.dirname(runJsonPath), 'downloads'),
+    screenshotsDir: path.join(path.dirname(runJsonPath), 'screenshots'),
+    data,
+  };
+}
+
+function summarize(data, runJsonPath) {
+  return {
+    status: data.status,
+    runId: data.runId,
+    command: data.command,
+    kind: data.kind,
+    projectUrl: data.projectUrl,
+    flowUrl: data.flowUrl,
+    assets: data.assets || [],
+    screenshots: data.screenshots || [],
+    errors: data.errors || [],
+    manualActions: data.manualActions || [],
+    metadataPath: data.metadataPath || runJsonPath,
+  };
+}

package/plugins/takomi-flow/scripts/lib/mcp-prompts.mjs

@@ -0,0 +1,39 @@
+import * as z from 'zod/v4';
+import { collectPrompt, imagePrompt, reviewPrompt, videoPrompt } from './prompts.mjs';
+
+export function registerPrompts(server) {
+  server.registerPrompt('takomi_flow_video_workflow', {
+    description: 'Guide an agent through a safe TakomiFlow video generation workflow.',
+    argsSchema: {
+      topic: z.string().optional(),
+      aspectRatio: z.string().optional(),
+      variations: z.string().optional(),
+    },
+  }, args => videoPrompt(args));
+
+  server.registerPrompt('takomi_flow_image_workflow', {
+    description: 'Guide an agent through a safe TakomiFlow image generation workflow.',
+    argsSchema: {
+      topic: z.string().optional(),
+      aspectRatio: z.string().optional(),
+      variations: z.string().optional(),
+    },
+  }, args => imagePrompt(args));
+
+  server.registerPrompt('takomi_flow_review_workflow', {
+    description: 'Guide an agent through reviewing TakomiFlow run results and assets.',
+    argsSchema: {
+      run: z.string().optional(),
+      frames: z.string().optional(),
+    },
+  }, args => reviewPrompt(args));
+
+  server.registerPrompt('takomi_flow_collect_workflow', {
+    description: 'Guide an agent through collecting reviewed TakomiFlow outputs into a downstream folder.',
+    argsSchema: {
+      run: z.string().optional(),
+      targetDir: z.string().optional(),
+      includeFrames: z.string().optional(),
+    },
+  }, args => collectPrompt(args));
+}

package/plugins/takomi-flow/scripts/lib/mcp-resources.mjs

@@ -0,0 +1,16 @@
+import { RESOURCES, readResourceFile } from './resource-files.mjs';
+
+export function registerResources(server) {
+  for (const resource of RESOURCES) {
+    server.registerResource(resource.name, resource.uri, {
+      mimeType: resource.mimeType,
+      description: resource.description,
+    }, async () => ({
+      contents: [{
+        uri: resource.uri,
+        mimeType: resource.mimeType,
+        text: readResourceFile(resource.file),
+      }],
+    }));
+  }
+}

package/plugins/takomi-flow/scripts/lib/mcp-tools.mjs

@@ -0,0 +1,150 @@
+import * as z from 'zod/v4';
+import * as api from './api.mjs';
+
+export function registerTools(server) {
+  const register = toolRegister(server);
+  register('takomi_flow_capabilities', 'List supported TakomiFlow kinds, modes, outputs, commands, and safety rules.', {}, () => api.capabilities());
+  register('takomi_flow_doctor', 'Check local TakomiFlow readiness: Playwright, FFmpeg, FFprobe, profile path, and output path.', {
+    profileDir: z.string().optional(),
+    outputDir: z.string().optional(),
+  }, args => api.doctor(args));
+  register('takomi_flow_audit', 'Summarize TakomiFlow readiness, safe actions, gated actions, and recent run state.', {
+    profileDir: z.string().optional(),
+    outputDir: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+  }, args => api.audit(args));
+  register('takomi_flow_examples', 'Return TakomiFlow example requests and downstream handoff patterns.', {
+    name: z.string().optional(),
+  }, args => api.examples(args));
+  register('takomi_flow_plan', 'Create a safe agent execution plan with MCP calls, CLI fallbacks, gates, and expected outputs.', {
+    kind: z.enum(['video', 'image']),
+    prompt: z.string(),
+    variations: z.number().int().positive().optional(),
+    aspectRatio: z.string().optional(),
+    durationSeconds: z.number().positive().optional(),
+    mode: z.string().optional(),
+    modelHint: z.string().optional(),
+    outputDir: z.string().optional(),
+    allowSpend: z.boolean().optional(),
+    extractFrames: z.number().int().nonnegative().optional(),
+    sourceAssets: z.array(z.string()).optional(),
+    submit: z.boolean().optional(),
+    targetDir: z.string().optional(),
+  }, args => api.plan(args));
+  registerRequestTools(register);
+  registerBrowserTools(register);
+  registerResultTools(register);
+}
+
+function registerRequestTools(register) {
+  register('takomi_flow_template', 'Return or write a video/image request template.', {
+    kind: z.enum(['video', 'image']).optional(),
+    outputDir: z.string().optional(),
+  }, args => api.template(args));
+  const requestShape = {
+    kind: z.enum(['video', 'image']),
+    prompt: z.string(),
+    variations: z.number().int().positive().optional(),
+    aspectRatio: z.string().optional(),
+    durationSeconds: z.number().positive().optional(),
+    mode: z.string().optional(),
+    modelHint: z.string().optional(),
+    outputDir: z.string().optional(),
+    allowSpend: z.boolean().optional(),
+    extractFrames: z.number().int().nonnegative().optional(),
+    sourceAssets: z.array(z.string()).optional(),
+    notes: z.string().optional(),
+  };
+  register('takomi_flow_prepare', 'Create a prepared request JSON file for a Flow image or video generation.', requestShape, args => api.prepare(args));
+  register('takomi_flow_workflow', 'Prepare, validate, and optionally submit a Flow image/video generation from one agent call.', {
+    ...requestShape,
+    submit: z.boolean().optional(),
+    allowBrowser: z.boolean().optional(),
+    profileDir: z.string().optional(),
+    browserChannel: z.string().optional(),
+    cdpUrl: z.string().optional(),
+    headless: z.boolean().optional(),
+  }, args => api.workflow(args));
+  register('takomi_flow_validate', 'Validate a TakomiFlow request JSON before opening Flow or spending credits.', {
+    request: z.string(),
+  }, args => api.validate(args));
+}
+
+function registerBrowserTools(register) {
+  register('takomi_flow_observe', 'Open Flow and observe UI controls/screenshots. Requires allowBrowser=true.', {
+    allowBrowser: z.boolean(),
+    profileDir: z.string().optional(),
+    outputDir: z.string().optional(),
+    browserChannel: z.string().optional(),
+    cdpUrl: z.string().optional(),
+    headless: z.boolean().optional(),
+  }, args => requireBrowser(args, () => api.observe(args)));
+  register('takomi_flow_generate', 'Run guarded Flow generation from a request file. Requires allowBrowser=true and request allowSpend=true to submit.', {
+    allowBrowser: z.boolean(),
+    request: z.string(),
+    profileDir: z.string().optional(),
+    browserChannel: z.string().optional(),
+    cdpUrl: z.string().optional(),
+    headless: z.boolean().optional(),
+  }, args => requireBrowser(args, () => api.generate(args)));
+}
+
+function registerResultTools(register) {
+  register('takomi_flow_selftest', 'Run deterministic no-spend TakomiFlow checks, including media catalog/frame extraction.', {
+    outputDir: z.string().optional(),
+  }, args => api.selftest(args));
+  register('takomi_flow_inspect', 'Summarize a TakomiFlow run.json or run directory.', { run: z.string() }, args => api.inspect(args));
+  register('takomi_flow_latest', 'Summarize the latest TakomiFlow run under an output directory.', {
+    outputDir: z.string().optional(),
+  }, args => api.latest(args));
+  register('takomi_flow_runs', 'List recent TakomiFlow runs under an output directory.', {
+    outputDir: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+  }, args => api.runs(args));
+  register('takomi_flow_assets', 'Catalog downloaded run assets and optionally extract video review frames.', {
+    run: z.string(),
+    frames: z.number().int().nonnegative().optional(),
+  }, args => api.assets(args));
+  register('takomi_flow_review', 'Inspect a run, catalog assets, extract review frames, and write a Markdown handoff.', {
+    run: z.string(),
+    frames: z.number().int().nonnegative().optional(),
+    reportPath: z.string().optional(),
+  }, args => api.review(args));
+  register('takomi_flow_collect', 'Copy reviewed assets, frames, report, and manifest into a downstream target folder.', {
+    run: z.string(),
+    targetDir: z.string(),
+    frames: z.number().int().nonnegative().optional(),
+    includeFrames: z.boolean().optional(),
+    reportPath: z.string().optional(),
+  }, args => api.collect(args));
+  register('takomi_flow_report', 'Create a Markdown report for a run or recent TakomiFlow history.', {
+    run: z.string().optional(),
+    outputDir: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+    reportPath: z.string().optional(),
+  }, args => api.report(args));
+}
+
+function toolRegister(server) {
+  return (name, description, inputSchema, handler) => {
+    server.registerTool(name, { description, inputSchema }, async args => {
+      const structuredContent = await handler(args || {});
+      return {
+        content: [{ type: 'text', text: JSON.stringify(structuredContent, null, 2) }],
+        structuredContent,
+      };
+    });
+  };
+}
+
+function requireBrowser(args, handler) {
+  if (!args?.allowBrowser) {
+    return {
+      schemaVersion: 1,
+      status: 'blocked',
+      errors: [],
+      manualActions: ['Set allowBrowser=true to permit TakomiFlow to open or drive a browser.'],
+    };
+  }
+  return handler();
+}

package/plugins/takomi-flow/scripts/lib/media.mjs

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { ensureDir, writeJson } from './paths.mjs';
+
+const execFileAsync = promisify(execFile);
+const VIDEO_EXTENSIONS = new Set(['.mp4', '.mov', '.webm', '.mkv', '.avi']);
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif']);
+
+export async function catalogAssets(run, assets = [], options = {}) {
+  const catalog = [];
+  const frameCount = Math.max(0, Number.parseInt(options.frames || '0', 10) || 0);
+  for (const assetPath of assets) {
+    const absolutePath = path.resolve(assetPath);
+    if (!fs.existsSync(absolutePath)) {
+      catalog.push({ path: absolutePath, exists: false, errors: ['Asset file not found.'] });
+      continue;
+    }
+    const kind = classifyAsset(absolutePath);
+    const item = {
+      path: absolutePath,
+      exists: true,
+      kind,
+      bytes: fs.statSync(absolutePath).size,
+      frames: [],
+      metadata: {},
+      errors: [],
+    };
+    if (kind === 'video') {
+      item.metadata = await probeMedia(absolutePath).catch(error => ({ probeError: error.message }));
+      if (frameCount > 0) {
+        item.frames = await extractFrames(absolutePath, path.join(run.runDir, 'frames'), frameCount)
+          .catch(error => {
+            item.errors.push(error.message);
+            return [];
+          });
+      }
+    }
+    catalog.push(item);
+  }
+  const catalogPath = path.join(run.runDir, 'assets.json');
+  writeJson(catalogPath, { schemaVersion: 1, runId: run.runId, assets: catalog });
+  return { catalogPath, assets: catalog };
+}
+
+export function classifyAsset(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (VIDEO_EXTENSIONS.has(ext)) return 'video';
+  if (IMAGE_EXTENSIONS.has(ext)) return 'image';
+  return 'unknown';
+}
+
+async function probeMedia(filePath) {
+  const { stdout } = await execFileAsync('ffprobe', [
+    '-v', 'error',
+    '-show_entries', 'format=duration,size:stream=width,height,codec_type,codec_name',
+    '-of', 'json',
+    filePath,
+  ]);
+  return JSON.parse(stdout);
+}
+
+async function extractFrames(filePath, framesDir, count) {
+  ensureDir(framesDir);
+  const outputPattern = path.join(framesDir, `${path.basename(filePath, path.extname(filePath))}_%03d.jpg`);
+  await execFileAsync('ffmpeg', [
+    '-y',
+    '-i', filePath,
+    '-vf', 'fps=1,scale=640:-1',
+    '-frames:v', String(count),
+    outputPattern,
+  ]);
+  return fs.readdirSync(framesDir)
+    .filter(name => name.startsWith(path.basename(filePath, path.extname(filePath))) && name.endsWith('.jpg'))
+    .sort()
+    .map(name => path.join(framesDir, name));
+}

package/plugins/takomi-flow/scripts/lib/observe.mjs

@@ -0,0 +1,54 @@
+import { defaultProfileDir, defaultRunsDir, FLOW_URL, resolvePath } from './paths.mjs';
+import { closeFlowBrowser, launchFlowBrowser } from './browser.mjs';
+import { createRun, baseResult, saveResult } from './result.mjs';
+import { capture, inspectFlowState, openFlow } from './flow-ui.mjs';
+
+export async function observeFlow(options = {}) {
+  const outputDir = resolvePath(options.outputDir, defaultRunsDir());
+  const run = createRun({ outputDir }, 'observe');
+  const profileDir = resolvePath(options.profileDir, defaultProfileDir());
+  const browser = await launchFlowBrowser({
+    profileDir,
+    downloadsDir: run.downloadsDir,
+    browserChannel: options.browserChannel,
+    cdpUrl: options.cdpUrl,
+    headless: options.headless === true,
+  });
+  const result = baseResult('ok', run, { command: 'observe', flowUrl: FLOW_URL, profileDir });
+  try {
+    await openFlow(browser.page);
+    result.screenshots.push(await capture(browser.page, run, 'observe-flow'));
+    Object.assign(result, await inspectFlowState(browser.page));
+    result.controls = await collectControls(browser.page);
+    if (result.manualActions.length) result.status = 'manual_action_required';
+  } catch (error) {
+    result.status = 'failed';
+    result.errors.push(error.message);
+  } finally {
+    await closeFlowBrowser(browser);
+    saveResult(run, result);
+  }
+  return result;
+}
+
+async function collectControls(page) {
+  return page.evaluate(() => {
+    const text = node => (node.innerText || node.textContent || node.getAttribute('aria-label') || '').trim();
+    const pick = selector => Array.from(document.querySelectorAll(selector))
+      .slice(0, 80)
+      .map(node => ({
+        tag: node.tagName.toLowerCase(),
+        text: text(node).slice(0, 120),
+        ariaLabel: node.getAttribute('aria-label') || '',
+        placeholder: node.getAttribute('placeholder') || '',
+        role: node.getAttribute('role') || '',
+        type: node.getAttribute('type') || '',
+      }))
+      .filter(item => item.text || item.ariaLabel || item.placeholder || item.role || item.type);
+    return {
+      buttons: pick('button,[role="button"]'),
+      inputs: pick('input,textarea,[contenteditable="true"],[role="textbox"]'),
+      links: pick('a'),
+    };
+  }).catch(error => ({ error: error.message }));
+}

package/plugins/takomi-flow/scripts/lib/paths.mjs

@@ -0,0 +1,37 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+export const FLOW_URL = process.env.TAKOMI_FLOW_URL || 'https://labs.google/fx/tools/flow';
+
+export function defaultProfileDir() {
+  return path.join(os.homedir(), '.takomi-flow', 'browser-profile');
+}
+
+export function defaultRunsDir() {
+  return path.join(os.homedir(), '.takomi-flow', 'runs');
+}
+
+export function timestampId(label = 'flow') {
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace('.', '-').replace('T', '-').replace('Z', '');
+  return `${stamp}-${label}`;
+}
+
+export function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+  return dirPath;
+}
+
+export function resolvePath(value, fallback) {
+  return path.resolve(value || fallback);
+}
+
+export function writeJson(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`);
+  return filePath;
+}
+
+export function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}

package/plugins/takomi-flow/scripts/lib/playwright-loader.mjs

@@ -0,0 +1,23 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+export async function loadPlaywright() {
+  try {
+    return await import('playwright');
+  } catch (firstError) {
+    try {
+      const requireFromCwd = createRequire(path.join(process.cwd(), 'package.json'));
+      return requireFromCwd('playwright');
+    } catch {
+      const message = [
+        'Playwright is required for TakomiFlow browser automation.',
+        'Install it in the plugin folder with:',
+        '  cd C:\\Users\\johno\\plugins\\takomi-flow',
+        '  pnpm install',
+        '',
+        `Original import error: ${firstError.message}`,
+      ].join('\n');
+      throw new Error(message);
+    }
+  }
+}

package/plugins/takomi-flow/scripts/lib/prompts.mjs

@@ -0,0 +1,72 @@
+export function videoPrompt(args = {}) {
+  const variations = normalizeVariations(args.variations);
+  return promptResult('TakomiFlow video workflow', [
+    'Use TakomiFlow to prepare a Google Flow video request.',
+    `Topic or prompt: ${args.topic || '<ask the user for the video prompt>'}`,
+    `Aspect ratio: ${args.aspectRatio || '16:9'}`,
+    `Variations: ${variations}`,
+    'Read takomi-flow://contract and takomi-flow://templates/video if available.',
+    'Run capabilities, prepare, validate, then generate only with explicit browser and spend approval.',
+    'After generation, inspect the run and catalog assets with frame extraction.',
+  ]);
+}
+
+export function imagePrompt(args = {}) {
+  const variations = normalizeVariations(args.variations);
+  return promptResult('TakomiFlow image workflow', [
+    'Use TakomiFlow to prepare a Google Flow image request.',
+    `Topic or prompt: ${args.topic || '<ask the user for the image prompt>'}`,
+    `Aspect ratio: ${args.aspectRatio || '1:1'}`,
+    `Variations: ${variations}`,
+    'Read takomi-flow://contract and takomi-flow://templates/image if available.',
+    'Run capabilities, prepare, validate, then generate only with explicit browser and spend approval.',
+    'After generation, inspect the run and catalog downloaded assets.',
+  ]);
+}
+
+export function reviewPrompt(args = {}) {
+  return promptResult('TakomiFlow review workflow', [
+    'Use TakomiFlow to review a completed or partial Flow run.',
+    `Run path: ${args.run || '<ask for the run.json path or run directory>'}`,
+    `Review frames: ${normalizeFrames(args.frames)}`,
+    'Run inspect or latest if the user did not provide a run path.',
+    'Run review with frame extraction to produce assets.json, report.md, and next actions.',
+    'If downloaded assets are present and a downstream project needs them, run collect after review.',
+    'Report run status, errors, manual actions, asset paths, frame paths, and reportPath.',
+  ]);
+}
+
+export function collectPrompt(args = {}) {
+  return promptResult('TakomiFlow collect workflow', [
+    'Use TakomiFlow to package reviewed Flow outputs for another project or pipeline.',
+    `Run path: ${args.run || '<ask for the run.json path or run directory>'}`,
+    `Target folder: ${args.targetDir || '<ask for the downstream target folder>'}`,
+    `Include frames: ${args.includeFrames === 'false' ? 'false' : 'true'}`,
+    'Run review first when asset quality or errors are unknown.',
+    'Run collect with a target directory and include frames when video review frames are useful downstream.',
+    'Return the copied asset paths, copied frame paths, report path, and takomi-flow-collection.json manifest path.',
+  ]);
+}
+
+function normalizeVariations(value) {
+  const parsed = Number.parseInt(value || '1', 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 1;
+}
+
+function normalizeFrames(value) {
+  const parsed = Number.parseInt(value || '4', 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : 4;
+}
+
+function promptResult(description, lines) {
+  return {
+    description,
+    messages: [{
+      role: 'user',
+      content: {
+        type: 'text',
+        text: lines.join('\n'),
+      },
+    }],
+  };
+}