@goodandready/dsh-image-gen 0.11.21 → 0.11.23

package/lib/generation-helpers.js

@@ -1,250 +1,266 @@
-// lib/generation-helpers.js
-// Extracted execution and prompt/caching helpers for generate_image tool (#349).
-
-import path from 'node:path'
-import { mkdir, writeFile } from 'node:fs/promises'
-import {
-  computeGenerationHash,
-  IMAGE_SIZES,
-  OUTPUT_FORMATS,
-  PROVIDER_KEYS,
-  buildSidecar,
-  ASPECT_RATIOS,
-  embedPngMetadata,
-  resolveStylePreset,
-  saveAttachmentSafe,
-} from './providers.js'
-import { enhancePrompt } from './prompt-enhancer.js'
-import { buildFaceConsistencyPrompt, getSessionAnchor, applyAnchorPromptHints } from './anchor-helpers.js'
-import { sanitizeNegativePrompt, supportsNegativePrompt } from './negative-sanitizer.js'
-import { recordSpend } from './cost-meter.js'
-import { setCachedGeneration } from './generation-cache.js'
-import {
-  readHistory,
-  writeHistory,
-  pruneHistory,
-} from './history.js'
-
-/** Run an array of async task functions with a concurrency cap */
-export async function asyncPool(tasks, concurrency = 3) {
-  const results = new Array(tasks.length)
-  let nextIdx = 0
-  async function worker() {
-    while (nextIdx < tasks.length) {
-      const idx = nextIdx++
-      results[idx] = await tasks[idx]()
-    }
-  }
-  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, () => worker())
-  await Promise.all(workers)
-  return results
-}
-
-/** Validates generation configuration and arguments */
-export function validateGenerationParams(cfg, args) {
-  if (cfg.enabled === false) {
-    throw new Error('Image generation is disabled in settings (dsh-image-gen.enabled is false); enable it in Settings → Image generation.')
-  }
-  const provider = PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal'
-  const deliverAs = cfg.deliverAs
-  const size = args.aspect_ratio ? 'custom' : (args.image_size ?? cfg.defaultSize)
-  if (!args.aspect_ratio && !IMAGE_SIZES.includes(size)) {
-    throw new Error(`Invalid image_size "${size}". One of: ${IMAGE_SIZES.join(', ')}`)
-  }
-  const aspectPixels = args.aspect_ratio ? ASPECT_RATIOS[args.aspect_ratio] : undefined
-  const format = args.output_format ?? cfg.defaultFormat
-  if (!OUTPUT_FORMATS.includes(format)) {
-    throw new Error(`Invalid output_format "${format}". One of: ${OUTPUT_FORMATS.join(', ')}`)
-  }
-  return { provider, deliverAs, size, aspectPixels, format }
-}
-
-/** Prepares enhanced prompt, style hints, facial identity, anchors, and sanitized negative prompt */
-export async function prepareGenerationPrompt({ ctx, cfg, args, exec, sessionId, provider, resolveSource }) {
-  const enhanced = await enhancePrompt(ctx, cfg, args.prompt, exec.signal, provider)
-  const effectiveStyle = args.style || cfg.stylePreset
-  const styleInfo = resolveStylePreset(effectiveStyle, args.negative_prompt, args.guidance_scale)
-  let effectivePrompt = styleInfo.promptSuffix ? `${enhanced.prompt}, ${styleInfo.promptSuffix}` : enhanced.prompt
-  let effectiveNegative = styleInfo.negativePrompt
-  const activeAnchor = getSessionAnchor(sessionId)
-  let resolvedFaceRef
-
-  const faceRefInput = args.face_reference || (activeAnchor && (activeAnchor.mode === 'face' || activeAnchor.mode === 'character') ? activeAnchor.image : undefined)
-  if (faceRefInput) {
-    try {
-      resolvedFaceRef = await resolveSource(ctx, exec, faceRefInput)
-    } catch (_err) {
-      /* non-fatal: face_reference resolve fallback */
-      resolvedFaceRef = { url: faceRefInput }
-    }
-    const facePlan = buildFaceConsistencyPrompt({
-      prompt: effectivePrompt,
-      faceStrength: args.face_strength || activeAnchor?.strength,
-      characterName: activeAnchor?.label,
-    })
-    effectivePrompt = facePlan.prompt
-    if (facePlan.negativePrompt) {
-      effectiveNegative = effectiveNegative ? `${effectiveNegative}, ${facePlan.negativePrompt}` : facePlan.negativePrompt
-    }
-  } else if (args.reference_image) {
-    effectivePrompt = `${effectivePrompt}, visual reference anchor`
-  } else if (activeAnchor) {
-    effectivePrompt = applyAnchorPromptHints(activeAnchor, effectivePrompt)
-  }
-
-  // #165: Negative prompt sanitizer for diffusion models
-  if (supportsNegativePrompt(provider, cfg.model || cfg.customModel)) {
-    effectiveNegative = sanitizeNegativePrompt({
-      positivePrompt: effectivePrompt,
-      userNegative: effectiveNegative,
-      autoInjectDefects: true,
-    })
-  }
-
-  return {
-    enhanced,
-    effectivePrompt,
-    effectiveNegative,
-    effectiveGuidance: styleInfo.guidanceScale,
-    styleInfo,
-    activeAnchor,
-    resolvedFaceRef,
-  }
-}
-
-/** Saves generated image to disk, sidecar, history, records spend, and builds return structure */
-export async function saveGeneratedImageArtifact({
-  ctx,
-  exec,
-  cfg,
-  args,
-  gen,
-  promptArg,
-  jobSeed,
-  provider,
-  deliverAs,
-  size,
-  format,
-  effectiveNegative,
-  effectiveGuidance,
-  enhanced,
-  slugify,
-  estimatedCost,
-  totalCount,
-}) {
-  const mediaType = gen.mediaType || 'image/png'
-  let bytes = gen.bytes
-  if (mediaType === 'image/png') {
-    bytes = embedPngMetadata(bytes, {
-      prompt: promptArg,
-      seed: gen.seed,
-      provider,
-      model: cfg.model || cfg.customModel,
-      negative_prompt: effectiveNegative,
-      guidance_scale: effectiveGuidance,
-      width: gen.width,
-      height: gen.height,
-    })
-  }
-  const extension = mediaType === 'image/jpeg' ? 'jpg' : mediaType === 'image/webp' ? 'webp' : 'png'
-  const stem = `${slugify(args.output_name || promptArg)}-${Date.now().toString(36)}-${jobSeed}`
-  const name = `${stem}.${extension}`
-
-  const { attachment, localUrl } = await saveAttachmentSafe(ctx, { bytes, mediaType, name })
-
-  const sessionCwd = exec?.agent?.session?.header?.cwd
-  const targetDir = (args.output_dir && String(args.output_dir).trim()) || cfg.outputDir || 'generated/images'
-  const outDir = path.resolve(sessionCwd || process.cwd(), targetDir)
-  await mkdir(outDir, { recursive: true })
-  const filePath = path.join(outDir, name)
-  await writeFile(filePath, bytes)
-
-  // Sidecar: metadata written alongside image file, making the output
-  // directory self-documenting without external database dependencies.
-  await writeFile(
-    path.join(outDir, `${stem}.json`),
-    JSON.stringify(buildSidecar({
-      prompt: promptArg,
-      size,
-      format,
-      seed: gen.seed,
-      provider,
-      deliverAs,
-      width: gen.width || attachment.width,
-      height: gen.height || attachment.height,
-      mediaType,
-      attachmentId: attachment.attachmentId,
-      url: deliverAs === 'image' && gen.sourceUrl ? gen.sourceUrl : localUrl,
-      cost: gen.cost,
-    }), null, 2),
-  )
-
-  const cacheHash = computeGenerationHash({
-    provider,
-    model: cfg.model || cfg.customModel,
-    prompt: promptArg,
-    seed: gen.seed,
-    size: args.image_size || cfg.defaultSize,
-    style: args.style || cfg.stylePreset,
-  })
-
-  // #170: Store in content-addressed disk cache
-  if (cfg.diskCache !== false) {
-    setCachedGeneration(cacheHash, {
-      bytes,
-      mediaType,
-      width: gen.width || attachment.width,
-      height: gen.height || attachment.height,
-      seed: gen.seed,
-      meta: { prompt: promptArg, provider, model: cfg.model || cfg.customModel, cost: gen.cost },
-    })
-  }
-  const entry = {
-    path: filePath,
-    prompt: promptArg,
-    provider,
-    model: cfg.model,
-    size,
-    format,
-    seed: gen.seed,
-    cacheHash,
-    thumbnailUrl: localUrl,
-    width: gen.width || attachment.width,
-    height: gen.height || attachment.height,
-    mediaType,
-    bytes: attachment.bytes,
-    createdAt: new Date().toISOString(),
-    attachmentId: attachment.attachmentId,
-  }
-  let current = await readHistory()
-  current = await pruneHistory(current, cfg.pruneDays)
-  current.unshift(entry)
-  if (current.length > (cfg.historyLimit || 50)) current.length = cfg.historyLimit || 50
-  await writeHistory(current)
-
-  // #167: Record spend in cost meter
-  recordSpend(gen.cost || (estimatedCost / totalCount), {
-    ctx,
-    meta: { provider, model: cfg.model || cfg.customModel, prompt: promptArg, seed: gen.seed },
-  })
-
-  return {
-    path: filePath,
-    url: deliverAs === 'image' && gen.sourceUrl ? gen.sourceUrl : localUrl,
-    width: gen.width || attachment.width,
-    height: gen.height || attachment.height,
-    seed: gen.seed,
-    prompt: promptArg,
-    ...(enhanced?.enhanced ? { originalPrompt: args.prompt } : {}),
-    cost: gen.cost,
-    format: mediaType.replace('image/', ''),
-    attachment: {
-      attachmentId: attachment.attachmentId,
-      mediaType: attachment.mediaType,
-      bytes: attachment.bytes,
-      width: attachment.width,
-      height: attachment.height,
-      name: attachment.name,
-    },
-  }
-}
+// lib/generation-helpers.js
+// Extracted execution and prompt/caching helpers for generate_image tool (#349).
+
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import {
+  computeGenerationHash,
+  IMAGE_SIZES,
+  OUTPUT_FORMATS,
+  PROVIDER_KEYS,
+  buildSidecar,
+  ASPECT_RATIOS,
+  embedPngMetadata,
+  resolveStylePreset,
+  saveAttachmentSafe,
+} from './providers.js'
+import { enhancePrompt } from './prompt-enhancer.js'
+import { buildFaceConsistencyPrompt, getSessionAnchor, applyAnchorPromptHints } from './anchor-helpers.js'
+import { sanitizeNegativePrompt, supportsNegativePrompt } from './negative-sanitizer.js'
+import { recordSpend } from './cost-meter.js'
+import { setCachedGeneration } from './generation-cache.js'
+import {
+  readHistory,
+  writeHistory,
+  pruneHistory,
+} from './history.js'
+
+/** Run an array of async task functions with a concurrency cap */
+export async function asyncPool(tasks, concurrency = 3) {
+  const results = new Array(tasks.length)
+  let nextIdx = 0
+  async function worker() {
+    while (nextIdx < tasks.length) {
+      const idx = nextIdx++
+      results[idx] = await tasks[idx]()
+    }
+  }
+  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, () => worker())
+  await Promise.all(workers)
+  return results
+}
+
+/** Validates generation configuration and arguments */
+export function validateGenerationParams(cfg, args) {
+  if (cfg.enabled === false) {
+    throw new Error('Image generation is disabled in settings (dsh-image-gen.enabled is false); enable it in Settings → Image generation.')
+  }
+  const provider = PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal'
+  const deliverAs = cfg.deliverAs
+  const size = args.aspect_ratio ? 'custom' : (args.image_size ?? cfg.defaultSize)
+  if (!args.aspect_ratio && !IMAGE_SIZES.includes(size)) {
+    throw new Error(`Invalid image_size "${size}". One of: ${IMAGE_SIZES.join(', ')}`)
+  }
+  const aspectPixels = args.aspect_ratio ? ASPECT_RATIOS[args.aspect_ratio] : undefined
+  const format = args.output_format ?? cfg.defaultFormat
+  if (!OUTPUT_FORMATS.includes(format)) {
+    throw new Error(`Invalid output_format "${format}". One of: ${OUTPUT_FORMATS.join(', ')}`)
+  }
+  return { provider, deliverAs, size, aspectPixels, format }
+}
+
+/** Prepares enhanced prompt, style hints, facial identity, anchors, and sanitized negative prompt */
+export async function prepareGenerationPrompt({ ctx, cfg, args, exec, sessionId, provider, resolveSource }) {
+  const enhanced = await enhancePrompt(ctx, cfg, args.prompt, exec.signal, provider)
+  const effectiveStyle = args.style || cfg.stylePreset
+  const styleInfo = resolveStylePreset(effectiveStyle, args.negative_prompt, args.guidance_scale)
+  let effectivePrompt = styleInfo.promptSuffix ? `${enhanced.prompt}, ${styleInfo.promptSuffix}` : enhanced.prompt
+  let effectiveNegative = styleInfo.negativePrompt
+  const activeAnchor = getSessionAnchor(sessionId)
+  let resolvedFaceRef
+
+  const faceRefInput = args.face_reference || (activeAnchor && (activeAnchor.mode === 'face' || activeAnchor.mode === 'character') ? activeAnchor.image : undefined)
+  if (faceRefInput) {
+    try {
+      resolvedFaceRef = await resolveSource(ctx, exec, faceRefInput)
+    } catch (_err) {
+      /* non-fatal: face_reference resolve fallback */
+      resolvedFaceRef = { url: faceRefInput }
+    }
+    const facePlan = buildFaceConsistencyPrompt({
+      prompt: effectivePrompt,
+      faceStrength: args.face_strength || activeAnchor?.strength,
+      characterName: activeAnchor?.label,
+    })
+    effectivePrompt = facePlan.prompt
+    if (facePlan.negativePrompt) {
+      effectiveNegative = effectiveNegative ? `${effectiveNegative}, ${facePlan.negativePrompt}` : facePlan.negativePrompt
+    }
+  } else if (args.reference_image) {
+    effectivePrompt = `${effectivePrompt}, visual reference anchor`
+  } else if (activeAnchor) {
+    effectivePrompt = applyAnchorPromptHints(activeAnchor, effectivePrompt)
+  }
+
+  // #165: Negative prompt sanitizer for diffusion models
+  if (supportsNegativePrompt(provider, cfg.model || cfg.customModel)) {
+    effectiveNegative = sanitizeNegativePrompt({
+      positivePrompt: effectivePrompt,
+      userNegative: effectiveNegative,
+      autoInjectDefects: true,
+    })
+  }
+
+  return {
+    enhanced,
+    effectivePrompt,
+    effectiveNegative,
+    effectiveGuidance: styleInfo.guidanceScale,
+    styleInfo,
+    activeAnchor,
+    resolvedFaceRef,
+  }
+}
+
+/** Saves generated image to disk, sidecar, history, records spend, and builds return structure */
+export async function saveGeneratedImageArtifact({
+  ctx,
+  exec,
+  cfg,
+  args,
+  gen,
+  promptArg,
+  jobSeed,
+  provider,
+  deliverAs,
+  size,
+  format,
+  effectiveNegative,
+  effectiveGuidance,
+  enhanced,
+  slugify,
+  estimatedCost,
+  totalCount,
+}) {
+  const mediaType = gen.mediaType || 'image/png'
+  let bytes = gen.bytes
+  if (mediaType === 'image/png') {
+    bytes = embedPngMetadata(bytes, {
+      prompt: promptArg,
+      seed: gen.seed,
+      provider,
+      model: cfg.model || cfg.customModel,
+      negative_prompt: effectiveNegative,
+      guidance_scale: effectiveGuidance,
+      width: gen.width,
+      height: gen.height,
+    })
+  }
+  const extension = mediaType === 'image/jpeg' ? 'jpg' : mediaType === 'image/webp' ? 'webp' : 'png'
+  const stem = `${slugify(args.output_name || promptArg)}-${Date.now().toString(36)}-${jobSeed}`
+  const name = `${stem}.${extension}`
+
+  const { attachment, localUrl } = await saveAttachmentSafe(ctx, { bytes, mediaType, name })
+
+  const sessionCwd = exec?.agent?.session?.header?.cwd
+  const targetDir = (args.output_dir && String(args.output_dir).trim()) || cfg.outputDir || 'generated/images'
+  const outDir = path.resolve(sessionCwd || process.cwd(), targetDir)
+  await mkdir(outDir, { recursive: true })
+  const filePath = path.join(outDir, name)
+  await writeFile(filePath, bytes)
+
+  // Sidecar: metadata written alongside image file, making the output
+  // directory self-documenting without external database dependencies.
+  await writeFile(
+    path.join(outDir, `${stem}.json`),
+    JSON.stringify(buildSidecar({
+      prompt: promptArg,
+      size,
+      format,
+      seed: gen.seed,
+      provider,
+      deliverAs,
+      width: gen.width || attachment.width,
+      height: gen.height || attachment.height,
+      mediaType,
+      attachmentId: attachment.attachmentId,
+      url: deliverAs === 'image' && gen.sourceUrl ? gen.sourceUrl : localUrl,
+      cost: gen.cost,
+    }), null, 2),
+  )
+
+  const effectiveModel = provider === 'custom'
+    ? (cfg.customModel || cfg.model || 'dall-e-3')
+    : (cfg.model || cfg.customModel)
+
+  const cacheHash = computeGenerationHash({
+    provider,
+    model: effectiveModel,
+    prompt: promptArg,
+    seed: gen.seed,
+    size: args.aspect_ratio ? 'custom' : (args.image_size || cfg.defaultSize),
+    style: args.style || cfg.stylePreset,
+    format: format || args.output_format || cfg.defaultFormat || 'png',
+    aspectRatio: args.aspect_ratio || cfg.defaultAspectRatio,
+    negativePrompt: args.negative_prompt || cfg.negativePrompt,
+    quality: args.quality,
+    strength: args.strength,
+    sourceImage: args.image || args.source_image,
+    maskImage: args.mask_image || args.mask,
+    reference: args.reference_images || args.reference_image,
+  })
+
+  // #170: Store in content-addressed disk cache
+  if (cfg.diskCache !== false) {
+    setCachedGeneration(cacheHash, {
+      bytes,
+      mediaType,
+      width: gen.width || attachment.width,
+      height: gen.height || attachment.height,
+      seed: gen.seed,
+      meta: { prompt: promptArg, provider, model: cfg.model || cfg.customModel, cost: gen.cost },
+    })
+  }
+  const entry = {
+    path: filePath,
+    prompt: promptArg,
+    provider,
+    model: cfg.model,
+    size,
+    format,
+    seed: gen.seed,
+    cacheHash,
+    thumbnailUrl: localUrl,
+    width: gen.width || attachment.width,
+    height: gen.height || attachment.height,
+    mediaType,
+    bytes: attachment.bytes,
+    createdAt: new Date().toISOString(),
+    attachmentId: attachment.attachmentId,
+  }
+  // Save to history (#385: historyLimit=0 skips history retention; bounds guard against negative values)
+  const historyLimit = typeof cfg.historyLimit === 'number' ? Math.max(0, Math.floor(cfg.historyLimit)) : 50
+  if (historyLimit > 0) {
+    let current = await readHistory()
+    current = await pruneHistory(current, cfg.pruneDays)
+    current.unshift(entry)
+    if (current.length > historyLimit) current.length = historyLimit
+    await writeHistory(current)
+  }
+
+  // #167: Record spend in cost meter
+  recordSpend(gen.cost || (estimatedCost / totalCount), {
+    ctx,
+    meta: { provider, model: cfg.model || cfg.customModel, prompt: promptArg, seed: gen.seed },
+  })
+
+  return {
+    path: filePath,
+    url: deliverAs === 'image' && gen.sourceUrl ? gen.sourceUrl : localUrl,
+    width: gen.width || attachment.width,
+    height: gen.height || attachment.height,
+    seed: gen.seed,
+    prompt: promptArg,
+    ...(enhanced?.enhanced ? { originalPrompt: args.prompt } : {}),
+    cost: gen.cost,
+    format: mediaType.replace('image/', ''),
+    attachment: {
+      attachmentId: attachment.attachmentId,
+      mediaType: attachment.mediaType,
+      bytes: attachment.bytes,
+      width: attachment.width,
+      height: attachment.height,
+      name: attachment.name,
+    },
+  }
+}

package/lib/index.js

@@ -371,10 +371,20 @@ export function apply(ctx, rawConfig) {
   // Vault route (#159)
   registerVaultRoutes(ctx)
 
-  // Session and cache teardown cleanup effect
+  // Reset loop guard when user sends a new message (#370)
+  if (typeof ctx.on === 'function') {
+    ctx.on('chat/message', (session) => {
+      if (session?.id) resetLoopGuard(session.id)
+    })
+    ctx.on('message', (session) => {
+      if (session?.id) resetLoopGuard(session.id)
+    })
+  }
+
+  // Session and cache teardown cleanup effect (#370)
   ctx.effect(() => () => {
     clearAllAnchors()
-    resetLoopGuard()
+    resetLoopGuard() // clears ALL session states from memory
   }, 'dsh-image-gen: session cleanup')
 
   // Tool registrations live in register-tools.js; each tool is a labeled ctx.effect (#216).

package/lib/loop-guard.js

@@ -1,7 +1,7 @@
 // lib/loop-guard.js
-// Fail-fast loop guard protecting against runaway agent retry loops (#168)
+// Fail-fast loop guard protecting against runaway agent retry loops (#168, #370)
 
-/** In-memory session tracking map: sessionId -> { count: number, lastPrompt: string, lastTimestamp: number } */
+/** In-memory session tracking map: sessionId -> { count: number, lastPrompt: string, lastTimestamp: number, lastTurnId: any } */
 const sessionStates = new Map()
 
 /** Default maximum consecutive generations without user interaction */
@@ -15,12 +15,16 @@ export const DEFAULT_MAX_CONSECUTIVE_GENERATIONS = 3
  * @param {number} [options.limit=3] - Maximum allowed calls
  * @param {string} [options.prompt=''] - Current prompt
  * @param {boolean} [options.isUserTurn=false] - Whether the user just submitted a turn (resets counter)
+ * @param {any} [options.turnId=null] - Canonical turn / message identifier
+ * @param {Object} [options.exec=null] - Tool execution context
  * @throws {Error} If consecutive generation limit is exceeded.
  */
 export function trackAndAssertLoopGuard(sessionId, {
   limit = DEFAULT_MAX_CONSECUTIVE_GENERATIONS,
   prompt = '',
   isUserTurn = false,
+  turnId = null,
+  exec = null,
 } = {}) {
   const sid = String(sessionId || 'default_session')
 
@@ -34,9 +38,27 @@ export function trackAndAssertLoopGuard(sessionId, {
     return { count: 0, remaining: Infinity, allowed: true }
   }
 
-  const current = sessionStates.get(sid) || { count: 0, lastPrompt: '', lastTimestamp: 0 }
+  const current = sessionStates.get(sid) || { count: 0, lastPrompt: '', lastTimestamp: 0, lastTurnId: null }
   const maxLimit = Math.max(1, Number(limit) || DEFAULT_MAX_CONSECUTIVE_GENERATIONS)
 
+  // Derive turn identifier from turnId or exec context
+  const session = exec?.agent?.session
+  const derivedTurnId = turnId ??
+    exec?.turnId ??
+    exec?.agent?.turnId ??
+    exec?.message?.id ??
+    session?.lastMessageId ??
+    session?.turnId ??
+    (Array.isArray(session?.messages) ? session.messages.length : null)
+
+  // If turn identifier changed, reset count for the new user turn
+  if (derivedTurnId !== null && derivedTurnId !== undefined) {
+    if (current.lastTurnId !== null && current.lastTurnId !== undefined && current.lastTurnId !== derivedTurnId) {
+      current.count = 0
+    }
+    current.lastTurnId = derivedTurnId
+  }
+
   if (current.count >= maxLimit) {
     throw new Error(
       `Generation loop limit reached (${current.count}/${maxLimit} consecutive generations). ` +
@@ -53,19 +75,21 @@ export function trackAndAssertLoopGuard(sessionId, {
 }
 
 /**
- * Resets loop guard counter for a session.
+ * Resets loop guard counter for a session, or clears all session states if sessionId is omitted.
  */
-/** @internal — test helper; not part of the plugin runtime API */
 export function resetLoopGuard(sessionId) {
-  const sid = String(sessionId || 'default_session')
+  if (!sessionId) {
+    sessionStates.clear()
+    return
+  }
+  const sid = String(sessionId)
   sessionStates.delete(sid)
 }
 
 /**
  * Gets current state for debugging/testing.
  */
-/** @internal — test helper; not part of the plugin runtime API */
 export function getLoopGuardState(sessionId) {
   const sid = String(sessionId || 'default_session')
-  return sessionStates.get(sid) || { count: 0, lastPrompt: '', lastTimestamp: 0 }
+  return sessionStates.get(sid) || { count: 0, lastPrompt: '', lastTimestamp: 0, lastTurnId: null }
 }