feat(hooks): add TTL-based cleanup for hook sessions

Hook sessions (e.g., from Gmail hooks) now auto-cleanup after a configurable TTL.

Changes:
- Add `hooks.sessionTtlMs` config option (default: 24 hours)
- Add `cleanupStaleHookSessions()` function that deletes stale hook sessions
- Run cleanup hourly via existing maintenance interval
- Only affects sessions with keys starting with "hook:"
- Sessions + transcripts are deleted after TTL expires

Config example:
```yaml
hooks:
  sessionTtlMs: 86400000  # 24 hours (default)
  # Set to 0 to disable cleanup
```

This prevents hook sessions from accumulating indefinitely while still
allowing time for debugging (sessions are kept for 24h by default).

src/config/types.hooks.ts

@@ -36,6 +36,8 @@ export type HookMappingConfig = {
   thinking?: string;
   timeoutSeconds?: number;
   transform?: HookMappingTransform;
+  /** Session cleanup after hook completes: "delete" archives the session, "keep" preserves it (default: "keep"). */
+  cleanup?: "delete" | "keep";
 };
 
 export type HooksGmailTailscaleMode = "off" | "serve" | "funnel";
@@ -67,6 +69,8 @@ export type HooksGmailConfig = {
   model?: string;
   /** Optional thinking level override for Gmail hook processing. */
   thinking?: "off" | "minimal" | "low" | "medium" | "high";
+  /** Session cleanup after Gmail hook completes: "delete" archives the session, "keep" preserves it (default: "delete" for Gmail). */
+  cleanup?: "delete" | "keep";
 };
 
 export type InternalHookHandlerConfig = {
@@ -121,4 +125,6 @@ export type HooksConfig = {
   gmail?: HooksGmailConfig;
   /** Internal agent event hooks */
   internal?: InternalHooksConfig;
+  /** TTL in milliseconds for hook sessions before auto-cleanup (default: 86400000 = 24h). Set to 0 to disable. */
+  sessionTtlMs?: number;
 };

src/config/zod-schema.hooks.ts

@@ -40,6 +40,7 @@ export const HookMappingSchema = z
       })
       .strict()
       .optional(),
+    cleanup: z.union([z.literal("delete"), z.literal("keep")]).optional(),
   })
   .strict()
   .optional();
@@ -125,6 +126,7 @@ export const HooksGmailSchema = z
         z.literal("high"),
       ])
       .optional(),
+    cleanup: z.union([z.literal("delete"), z.literal("keep")]).optional(),
   })
   .strict()
   .optional();

src/config/zod-schema.ts

@@ -242,6 +242,7 @@ export const MoltbotSchema = z
         mappings: z.array(HookMappingSchema).optional(),
         gmail: HooksGmailSchema,
         internal: InternalHooksSchema,
+        sessionTtlMs: z.number().int().min(0).optional(),
       })
       .strict()
       .optional(),

src/gateway/hooks-mapping.ts

@@ -22,6 +22,7 @@ export type HookMappingResolved = {
   thinking?: string;
   timeoutSeconds?: number;
   transform?: HookMappingTransformResolved;
+  cleanup?: "delete" | "keep";
 };
 
 export type HookMappingTransformResolved = {
@@ -55,6 +56,7 @@ export type HookAction =
       model?: string;
       thinking?: string;
       timeoutSeconds?: number;
+      cleanup?: "delete" | "keep";
     };
 
 export type HookMappingResult =
@@ -73,6 +75,7 @@ const hookPresetMappings: Record<string, HookMappingConfig[]> = {
       sessionKey: "hook:gmail:{{messages[0].id}}",
       messageTemplate:
         "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
+      // Sessions are cleaned up via TTL (hooks.sessionTtlMs, default 24h)
     },
   ],
 };
@@ -94,6 +97,7 @@ type HookTransformResult = Partial<{
   model: string;
   thinking: string;
   timeoutSeconds: number;
+  cleanup: "delete" | "keep";
 }> | null;
 
 type HookTransformFn = (
@@ -103,16 +107,21 @@ type HookTransformFn = (
 export function resolveHookMappings(hooks?: HooksConfig): HookMappingResolved[] {
   const presets = hooks?.presets ?? [];
   const gmailAllowUnsafe = hooks?.gmail?.allowUnsafeExternalContent;
+  const gmailCleanup = hooks?.gmail?.cleanup;
   const mappings: HookMappingConfig[] = [];
   if (hooks?.mappings) mappings.push(...hooks.mappings);
   for (const preset of presets) {
     const presetMappings = hookPresetMappings[preset];
     if (!presetMappings) continue;
-    if (preset === "gmail" && typeof gmailAllowUnsafe === "boolean") {
+    if (preset === "gmail") {
       mappings.push(
         ...presetMappings.map((mapping) => ({
           ...mapping,
-          allowUnsafeExternalContent: gmailAllowUnsafe,
+          ...(typeof gmailAllowUnsafe === "boolean" && {
+            allowUnsafeExternalContent: gmailAllowUnsafe,
+          }),
+          // Allow config override; fall back to preset default (delete)
+          cleanup: gmailCleanup ?? mapping.cleanup,
         })),
       );
       continue;
@@ -192,6 +201,7 @@ function normalizeHookMapping(
     thinking: mapping.thinking,
     timeoutSeconds: mapping.timeoutSeconds,
     transform,
+    cleanup: mapping.cleanup,
   };
 }
 
@@ -237,6 +247,7 @@ function buildActionFromMapping(
       model: renderOptional(mapping.model, ctx),
       thinking: renderOptional(mapping.thinking, ctx),
       timeoutSeconds: mapping.timeoutSeconds,
+      cleanup: mapping.cleanup,
     },
   };
 }
@@ -277,6 +288,7 @@ function mergeAction(
     model: override.model ?? baseAgent?.model,
     thinking: override.thinking ?? baseAgent?.thinking,
     timeoutSeconds: override.timeoutSeconds ?? baseAgent?.timeoutSeconds,
+    cleanup: override.cleanup ?? baseAgent?.cleanup,
   });
 }
 

src/gateway/hooks-session-cleanup.ts

@@ -0,0 +1,83 @@
+/**
+ * TTL-based cleanup for hook sessions.
+ * Runs periodically to delete stale hook sessions older than the configured TTL.
+ */
+
+import type { MoltbotConfig } from "../config/config.js";
+import { loadCombinedSessionStoreForGateway, listSessionsFromStore } from "./session-utils.js";
+import { callGateway } from "./call.js";
+import type { createSubsystemLogger } from "../logging/subsystem.js";
+
+type SubsystemLogger = ReturnType<typeof createSubsystemLogger>;
+
+const DEFAULT_HOOK_SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const HOOK_SESSION_PREFIX = "hook:";
+
+export type HookSessionCleanupResult = {
+  checked: number;
+  deleted: number;
+  errors: number;
+};
+
+/**
+ * Clean up stale hook sessions older than TTL.
+ * Returns counts of checked/deleted/errored sessions.
+ */
+export async function cleanupStaleHookSessions(params: {
+  cfg: MoltbotConfig;
+  log?: SubsystemLogger;
+}): Promise<HookSessionCleanupResult> {
+  const { cfg, log } = params;
+
+  // Get TTL from config (0 = disabled)
+  const ttlMs = cfg.hooks?.sessionTtlMs ?? DEFAULT_HOOK_SESSION_TTL_MS;
+  if (ttlMs <= 0) {
+    return { checked: 0, deleted: 0, errors: 0 };
+  }
+
+  const cutoffMs = Date.now() - ttlMs;
+
+  // List all sessions
+  const { storePath, store } = loadCombinedSessionStoreForGateway(cfg);
+  const allSessions = listSessionsFromStore({
+    cfg,
+    storePath,
+    store,
+    opts: { limit: 10000 }, // High limit to get all sessions
+  });
+
+  // Filter to hook sessions that are stale
+  const staleSessions = allSessions.sessions.filter((session) => {
+    // Check if it's a hook session (key starts with "hook:")
+    if (!session.key.startsWith(HOOK_SESSION_PREFIX)) return false;
+    // Check if it's older than TTL
+    const lastActivity = session.updatedAt ?? 0;
+    return lastActivity < cutoffMs;
+  });
+
+  let deleted = 0;
+  let errors = 0;
+
+  for (const session of staleSessions) {
+    try {
+      await callGateway({
+        method: "sessions.delete",
+        params: { key: session.key, deleteTranscript: true },
+        timeoutMs: 10_000,
+      });
+      deleted++;
+      log?.debug?.(`cleaned up stale hook session: ${session.key}`);
+    } catch (err) {
+      errors++;
+      log?.warn?.(`failed to cleanup hook session ${session.key}: ${String(err)}`);
+    }
+  }
+
+  if (deleted > 0 || errors > 0) {
+    log?.info?.(
+      `hook session cleanup: checked=${staleSessions.length} deleted=${deleted} errors=${errors}`,
+    );
+  }
+
+  return { checked: staleSessions.length, deleted, errors };
+}

src/gateway/server-http.ts

@@ -47,6 +47,7 @@ type HookDispatchers = {
     thinking?: string;
     timeoutSeconds?: number;
     allowUnsafeExternalContent?: boolean;
+    cleanup?: "delete" | "keep";
   }) => string;
 };
 
@@ -182,6 +183,7 @@ export function createHooksRequestHandler(
             thinking: mapped.action.thinking,
             timeoutSeconds: mapped.action.timeoutSeconds,
             allowUnsafeExternalContent: mapped.action.allowUnsafeExternalContent,
+            cleanup: mapped.action.cleanup,
           });
           sendJson(res, 202, { ok: true, runId });
           return true;

src/gateway/server-maintenance.ts

@@ -1,5 +1,7 @@
 import type { HealthSummary } from "../commands/health.js";
+import { loadConfig } from "../config/config.js";
 import { abortChatRunById, type ChatAbortControllerEntry } from "./chat-abort.js";
+import { cleanupStaleHookSessions } from "./hooks-session-cleanup.js";
 import { setBroadcastHealthUpdate } from "./server/health-state.js";
 import type { ChatRunEntry } from "./server-chat.js";
 import {
@@ -71,9 +73,22 @@ export function startGatewayMaintenanceTimers(params: {
     .refreshGatewayHealthSnapshot({ probe: true })
     .catch((err) => params.logHealth.error(`initial refresh failed: ${formatError(err)}`));
 
+  // Hook session cleanup counter (run hourly = every 60 iterations at 60s interval)
+  let hookCleanupCounter = 0;
+  const HOOK_CLEANUP_INTERVAL = 60; // Run every 60 iterations (1 hour)
+
   // dedupe cache cleanup
   const dedupeCleanup = setInterval(() => {
     const now = Date.now();
+
+    // Hook session TTL cleanup (runs hourly)
+    hookCleanupCounter++;
+    if (hookCleanupCounter >= HOOK_CLEANUP_INTERVAL) {
+      hookCleanupCounter = 0;
+      void cleanupStaleHookSessions({ cfg: loadConfig() }).catch(() => {
+        // Best-effort cleanup; errors are logged inside the function
+      });
+    }
     for (const [k, v] of params.dedupe) {
       if (now - v.ts > DEDUPE_TTL_MS) params.dedupe.delete(k);
     }

src/gateway/server/hooks.ts

@@ -42,6 +42,7 @@ export function createGatewayHooksRequestHandler(params: {
     thinking?: string;
     timeoutSeconds?: number;
     allowUnsafeExternalContent?: boolean;
+    cleanup?: "delete" | "keep";
   }) => {
     const sessionKey = value.sessionKey.trim() ? value.sessionKey.trim() : `hook:${randomUUID()}`;
     const mainSessionKey = resolveMainSessionKeyFromConfig();
@@ -73,9 +74,9 @@ export function createGatewayHooksRequestHandler(params: {
     const runId = randomUUID();
     void (async () => {
       try {
-        const cfg = loadConfig();
+        const runCfg = loadConfig();
         const result = await runCronIsolatedAgentTurn({
-          cfg,
+          cfg: runCfg,
           deps,
           job,
           message: value.message,
@@ -99,6 +100,9 @@ export function createGatewayHooksRequestHandler(params: {
         if (value.wakeMode === "now") {
           requestHeartbeatNow({ reason: `hook:${jobId}:error` });
         }
+      } finally {
+        // Note: TTL-based cleanup is handled by cleanupStaleHookSessions()
+        // Sessions are kept for debugging (default 24h TTL via hooks.sessionTtlMs)
       }
     })();