@joshualelon/clawdbot-skill-flow 0.1.0 → 0.2.1

package/README.md

@@ -15,6 +15,15 @@ Build deterministic, button-driven conversation flows without AI inference overh
 - **History Tracking** - JSONL append-only log for completed flows
 - **Cron Integration** - Schedule flows to run automatically via Clawdbot's cron system
 
+## Requirements
+
+- **Clawdbot**: v2026.1.25 or later (requires Telegram `sendPayload` support)
+  - PR: https://github.com/clawdbot/clawdbot/pull/1917
+  - **Important**: Telegram inline keyboard buttons will not work with older Clawdbot versions
+  - Text-based fallback will work on all versions
+- **Node.js**: 22+ (same as Clawdbot)
+- **Channels**: Currently optimized for Telegram (other channels use text-based menus)
+
 ## Quick Start
 
 ### 1. Install Plugin
@@ -196,6 +205,123 @@ Override default `next` on a per-button basis:
 }
 ```
 
+### Hooks System
+
+Customize flow behavior at key points without forking the plugin:
+
+```json
+{
+  "name": "pushups",
+  "description": "4-set pushup workout",
+  "hooks": "./hooks.js",
+  "steps": [...]
+}
+```
+
+**Available Hooks:**
+- `onStepRender(step, session)` - Modify step before rendering (e.g., dynamic buttons)
+- `onCapture(variable, value, session)` - Called after variable capture (e.g., log to Google Sheets)
+- `onFlowComplete(session)` - Called when flow completes (e.g., schedule next session)
+- `onFlowAbandoned(session, reason)` - Called on timeout/cancellation (e.g., track completion rates)
+
+**Example hooks file:**
+
+```javascript
+export default {
+  async onStepRender(step, session) {
+    // Generate dynamic buttons based on past performance
+    if (step.id === 'set1') {
+      const average = await calculateAverage(session.senderId);
+      return {
+        ...step,
+        buttons: [average - 5, average, average + 5, average + 10],
+      };
+    }
+    return step;
+  },
+
+  async onCapture(variable, value, session) {
+    // Log to Google Sheets in real-time
+    await sheets.append({
+      spreadsheetId: 'YOUR_SHEET_ID',
+      values: [[new Date(), session.senderId, variable, value]],
+    });
+  },
+
+  async onFlowComplete(session) {
+    // Schedule next workout
+    const nextDate = calculateNextWorkout();
+    await cron.create({
+      schedule: nextDate,
+      message: '/flow-start pushups',
+      userId: session.senderId,
+    });
+  },
+};
+```
+
+See `src/examples/pushups-hooks.example.js` for a complete reference.
+
+### Custom Storage Backends
+
+Replace or supplement the built-in JSONL storage:
+
+```json
+{
+  "name": "pushups",
+  "storage": {
+    "backend": "./storage.js",
+    "builtin": false
+  },
+  "steps": [...]
+}
+```
+
+**StorageBackend Interface:**
+
+```javascript
+export default {
+  async saveSession(session) {
+    // Write to Google Sheets, database, etc.
+  },
+
+  async loadHistory(flowName, options) {
+    // Return historical sessions for analytics
+    return [];
+  },
+};
+```
+
+Set `"builtin": false` to disable JSONL storage and only use the custom backend. Omit it (or set to `true`) to use both.
+
+See `src/examples/sheets-storage.example.js` for a complete reference.
+
+## Security
+
+### Hooks & Storage Backend Safety
+
+The plugin validates that all dynamically loaded files (hooks, storage backends) remain within the `~/.clawdbot/flows/` directory. This prevents directory traversal attacks.
+
+**Valid hook paths:**
+```json
+{
+  "name": "myflow",
+  "hooks": "./hooks.js",           // ✅ Relative to flow directory
+  "hooks": "hooks/custom.js"        // ✅ Subdirectory within flow
+}
+```
+
+**Invalid hook paths (will be rejected):**
+```json
+{
+  "hooks": "/etc/passwd",           // ❌ Absolute path outside flows
+  "hooks": "../../../etc/passwd",   // ❌ Directory traversal
+  "hooks": "~/malicious.js"         // ❌ Tilde expansion outside flows
+}
+```
+
+The plugin uses path validation similar to Clawdbot's core security patterns to ensure hooks and storage backends can only access files within their designated flow directory.
+
 ## How It Works
 
 ### Telegram Button Callbacks
@@ -231,24 +357,6 @@ This enables deterministic, instant responses for structured workflows.
     ├── metadata.json
     └── history.jsonl
 ```
-
-## Roadmap
-
-### v0.2.0
-- LLM-driven steps (e.g., "Ask user for feedback, then summarize")
-- External service integrations (Google Sheets, webhooks)
-- Flow analytics dashboard (completion rates, drop-off points)
-
-### v0.3.0
-- Visual flow builder (web UI)
-- Loops and repeats
-- Sub-flows (call another flow as a step)
-
-### v1.0.0
-- Production-ready comprehensive tests
-- Performance optimizations
-- Migration guides
-
 ## Contributing
 
 Issues and PRs welcome! This plugin follows Clawdbot's coding conventions.

package/clawdbot.plugin.json

@@ -1,8 +1,50 @@
 {
-  "id": "skill-flow",
+  "id": "clawdbot-skill-flow",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "properties": {}
+    "properties": {
+      "sessionTimeoutMinutes": {
+        "type": "number",
+        "minimum": 1,
+        "maximum": 1440,
+        "default": 30
+      },
+      "sessionCleanupIntervalMinutes": {
+        "type": "number",
+        "minimum": 1,
+        "maximum": 60,
+        "default": 5
+      },
+      "enableBuiltinHistory": {
+        "type": "boolean",
+        "default": true
+      },
+      "maxFlowsPerUser": {
+        "type": "number",
+        "minimum": 1,
+        "maximum": 1000
+      }
+    }
+  },
+  "uiHints": {
+    "sessionTimeoutMinutes": {
+      "label": "Session Timeout (minutes)",
+      "help": "How long before inactive flow sessions expire (1-1440 minutes)"
+    },
+    "sessionCleanupIntervalMinutes": {
+      "label": "Cleanup Interval (minutes)",
+      "help": "How often to check for expired sessions (1-60 minutes)",
+      "advanced": true
+    },
+    "enableBuiltinHistory": {
+      "label": "Enable History Logging",
+      "help": "Save completed flows to .jsonl files (can be disabled if using custom storage backend)"
+    },
+    "maxFlowsPerUser": {
+      "label": "Max Flows Per User",
+      "help": "Limit concurrent flows per user (leave empty for unlimited)",
+      "advanced": true
+    }
   }
 }

package/index.ts

@@ -3,6 +3,8 @@
  */
 
 import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { parseSkillFlowConfig } from "./src/config.js";
+import { initSessionStore } from "./src/state/session-store.js";
 import { createFlowStartCommand } from "./src/commands/flow-start.js";
 import { createFlowStepCommand } from "./src/commands/flow-step.js";
 import { createFlowCreateCommand } from "./src/commands/flow-create.js";
@@ -17,6 +19,12 @@ const plugin = {
   version: "0.1.0",
 
   register(api: ClawdbotPluginApi) {
+    // Parse and validate config
+    const config = parseSkillFlowConfig(api.pluginConfig);
+
+    // Initialize session store with config
+    initSessionStore(config);
+
     // Register commands
     api.registerCommand({
       name: "flow-start",
@@ -58,7 +66,10 @@ const plugin = {
       handler: createFlowDeleteCommand(api),
     });
 
-    api.logger.info("Skill Flow plugin registered successfully");
+    api.logger.info("Skill Flow plugin registered successfully", {
+      sessionTimeoutMinutes: config.sessionTimeoutMinutes,
+      enableBuiltinHistory: config.enableBuiltinHistory,
+    });
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshualelon/clawdbot-skill-flow",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Multi-step workflow orchestration plugin for Clawdbot",
   "keywords": [
@@ -16,7 +16,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/joshualelon/clawdbot-skill-flow.git"
+    "url": "git+https://github.com/joshualelon/clawdbot-skill-flow.git"
   },
   "homepage": "https://github.com/joshualelon/clawdbot-skill-flow#readme",
   "bugs": {
@@ -69,8 +69,7 @@
   },
   "lint-staged": {
     "*.ts": [
-      "oxlint --fix",
-      "tsc --noEmit"
+      "oxlint --fix"
     ]
   }
 }

package/src/commands/flow-step.ts

@@ -3,6 +3,7 @@
  */
 
 import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { parseSkillFlowConfig } from "../config.js";
 import { loadFlow } from "../state/flow-store.js";
 import {
   getSession,
@@ -12,6 +13,11 @@ import {
 } from "../state/session-store.js";
 import { saveFlowHistory } from "../state/history-store.js";
 import { processStep } from "../engine/executor.js";
+import {
+  loadHooks,
+  resolveFlowPath,
+  safeExecuteHook,
+} from "../engine/hooks-loader.js";
 
 export function createFlowStepCommand(api: ClawdbotPluginApi) {
   return async (args: {
@@ -48,23 +54,45 @@ export function createFlowStepCommand(api: ClawdbotPluginApi) {
     const stepId = stepData.substring(0, colonIndex);
     const valueStr = stepData.substring(colonIndex + 1);
 
-    // Get active session
-    const sessionKey = getSessionKey(args.senderId, flowName);
-    const session = getSession(sessionKey);
+    // Load flow first
+    const flow = await loadFlow(api, flowName);
 
-    if (!session) {
+    if (!flow) {
       return {
-        text: `Session expired or not found.\n\nUse /flow-start ${flowName} to restart the flow.`,
+        text: `Flow "${flowName}" not found.`,
       };
     }
 
-    // Load flow
-    const flow = await loadFlow(api, flowName);
+    // Get active session
+    const sessionKey = getSessionKey(args.senderId, flowName);
+    const session = getSession(sessionKey);
+
+    if (!session) {
+      // Load hooks and call onFlowAbandoned
+      if (flow.hooks) {
+        const hooksPath = resolveFlowPath(api, flow.name, flow.hooks);
+        const hooks = await loadHooks(api, hooksPath);
+        if (hooks?.onFlowAbandoned) {
+          await safeExecuteHook(
+            api,
+            "onFlowAbandoned",
+            hooks.onFlowAbandoned,
+            {
+              flowName,
+              currentStepId: stepId,
+              senderId: args.senderId,
+              channel: args.channel,
+              variables: {},
+              startedAt: 0,
+              lastActivityAt: 0,
+            },
+            "timeout"
+          );
+        }
+      }
 
-    if (!flow) {
-      deleteSession(sessionKey);
       return {
-        text: `Flow "${flowName}" not found.`,
+        text: `Session expired or not found.\n\nUse /flow-start ${flowName} to restart the flow.`,
       };
     }
 
@@ -72,7 +100,7 @@ export function createFlowStepCommand(api: ClawdbotPluginApi) {
     const value = /^\d+$/.test(valueStr) ? Number(valueStr) : valueStr;
 
     // Process step transition
-    const result = processStep(api, flow, session, stepId, value);
+    const result = await processStep(api, flow, session, stepId, value);
 
     // Update session or cleanup
     if (result.complete) {
@@ -81,7 +109,8 @@ export function createFlowStepCommand(api: ClawdbotPluginApi) {
         ...session,
         variables: result.updatedVariables,
       };
-      await saveFlowHistory(api, finalSession);
+      const config = parseSkillFlowConfig(api.pluginConfig);
+      await saveFlowHistory(api, finalSession, flow, config);
 
       // Cleanup session
       deleteSession(sessionKey);

package/src/config.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+export const SkillFlowConfigSchema = z
+  .object({
+    sessionTimeoutMinutes: z
+      .number()
+      .int()
+      .min(1)
+      .max(1440)
+      .default(30)
+      .describe("Session timeout in minutes (default: 30)"),
+
+    sessionCleanupIntervalMinutes: z
+      .number()
+      .int()
+      .min(1)
+      .max(60)
+      .default(5)
+      .describe("How often to clean up expired sessions (default: 5)"),
+
+    enableBuiltinHistory: z
+      .boolean()
+      .default(true)
+      .describe("Save completed flows to JSONL history files (default: true)"),
+
+    maxFlowsPerUser: z
+      .number()
+      .int()
+      .min(1)
+      .max(1000)
+      .optional()
+      .describe("Max concurrent flows per user (optional limit)"),
+  })
+  .strict();
+
+export type SkillFlowConfig = z.infer<typeof SkillFlowConfigSchema>;
+
+/**
+ * Parse and validate plugin config with defaults
+ */
+export function parseSkillFlowConfig(
+  raw: unknown
+): SkillFlowConfig {
+  return SkillFlowConfigSchema.parse(raw ?? {});
+}

package/src/engine/executor.ts

@@ -3,18 +3,24 @@
  */
 
 import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
-import type { FlowMetadata, FlowSession, ReplyPayload } from "../types.js";
+import type {
+  FlowMetadata,
+  FlowSession,
+  ReplyPayload,
+  FlowHooks,
+} from "../types.js";
 import { renderStep } from "./renderer.js";
 import { executeTransition } from "./transitions.js";
+import { loadHooks, resolveFlowPath, safeExecuteHook } from "./hooks-loader.js";
 
 /**
  * Start a flow from the beginning
  */
-export function startFlow(
+export async function startFlow(
   api: ClawdbotPluginApi,
   flow: FlowMetadata,
   session: FlowSession
-): ReplyPayload {
+): Promise<ReplyPayload> {
   const firstStep = flow.steps[0];
 
   if (!firstStep) {
@@ -23,24 +29,45 @@ export function startFlow(
     };
   }
 
-  return renderStep(api, flow, firstStep, session, session.channel);
+  // Load hooks if configured
+  let hooks: FlowHooks | null = null;
+  if (flow.hooks) {
+    const hooksPath = resolveFlowPath(api, flow.name, flow.hooks);
+    hooks = await loadHooks(api, hooksPath);
+  }
+
+  return renderStep(api, flow, firstStep, session, session.channel, hooks);
 }
 
 /**
  * Process a step transition and return next step or completion message
  */
-export function processStep(
+export async function processStep(
   api: ClawdbotPluginApi,
   flow: FlowMetadata,
   session: FlowSession,
   stepId: string,
   value: string | number
-): {
+): Promise<{
   reply: ReplyPayload;
   complete: boolean;
   updatedVariables: Record<string, string | number>;
-} {
-  const result = executeTransition(api, flow, session, stepId, value);
+}> {
+  // Load hooks if configured
+  let hooks: FlowHooks | null = null;
+  if (flow.hooks) {
+    const hooksPath = resolveFlowPath(api, flow.name, flow.hooks);
+    hooks = await loadHooks(api, hooksPath);
+  }
+
+  const result = await executeTransition(
+    api,
+    flow,
+    session,
+    stepId,
+    value,
+    hooks
+  );
 
   // Handle errors
   if (result.error) {
@@ -53,6 +80,13 @@ export function processStep(
 
   // Handle completion
   if (result.complete) {
+    const updatedSession = { ...session, variables: result.variables };
+
+    // Call onFlowComplete hook
+    if (hooks?.onFlowComplete) {
+      await safeExecuteHook(api, "onFlowComplete", hooks.onFlowComplete, updatedSession);
+    }
+
     const completionMessage = generateCompletionMessage(flow, result.variables);
     return {
       reply: { text: completionMessage },
@@ -80,7 +114,14 @@ export function processStep(
   }
 
   const updatedSession = { ...session, variables: result.variables };
-  const reply = renderStep(api, flow, nextStep, updatedSession, session.channel);
+  const reply = await renderStep(
+    api,
+    flow,
+    nextStep,
+    updatedSession,
+    session.channel,
+    hooks
+  );
 
   return {
     reply,

package/src/engine/hooks-loader.ts

@@ -0,0 +1,125 @@
+/**
+ * Hooks loader - Dynamically loads and executes flow hooks
+ */
+
+import type { FlowHooks, StorageBackend } from "../types.js";
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import {
+  resolvePathSafely,
+  validatePathWithinBase,
+} from "../security/path-validation.js";
+
+/**
+ * Load hooks from a file path
+ * @param api - Plugin API for logging
+ * @param hooksPath - Absolute path to hooks file
+ * @returns FlowHooks object or null if loading fails
+ */
+export async function loadHooks(
+  api: ClawdbotPluginApi,
+  hooksPath: string
+): Promise<FlowHooks | null> {
+  try {
+    // Validate path is within flows directory
+    const flowsDir = path.join(api.runtime.state.resolveStateDir(), "flows");
+    validatePathWithinBase(hooksPath, flowsDir, "hooks file");
+
+    // Check if file exists
+    await fs.access(hooksPath);
+
+    // Dynamically import the hooks module
+    const hooksModule = await import(hooksPath);
+
+    // Support both default export and named export
+    const hooks: FlowHooks = hooksModule.default ?? hooksModule;
+
+    api.logger.debug(`Loaded hooks from ${hooksPath}`);
+    return hooks;
+  } catch (error) {
+    api.logger.warn(`Failed to load hooks from ${hooksPath}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Load storage backend from a file path
+ * @param api - Plugin API for logging
+ * @param backendPath - Absolute path to storage backend file
+ * @returns StorageBackend or null if loading fails
+ */
+export async function loadStorageBackend(
+  api: ClawdbotPluginApi,
+  backendPath: string
+): Promise<StorageBackend | null> {
+  try {
+    // Validate path is within flows directory
+    const flowsDir = path.join(api.runtime.state.resolveStateDir(), "flows");
+    validatePathWithinBase(backendPath, flowsDir, "storage backend");
+
+    // Check if file exists
+    await fs.access(backendPath);
+
+    // Dynamically import the backend module
+    const backendModule = await import(backendPath);
+
+    // Support both default export and named export
+    const backend: StorageBackend = backendModule.default ?? backendModule;
+
+    api.logger.debug(`Loaded storage backend from ${backendPath}`);
+    return backend;
+  } catch (error) {
+    api.logger.warn(`Failed to load storage backend from ${backendPath}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Resolve relative path to absolute (relative to flow directory)
+ * @param api - Plugin API
+ * @param flowName - Name of the flow
+ * @param relativePath - Relative path from flow config
+ * @returns Absolute path
+ */
+export function resolveFlowPath(
+  api: ClawdbotPluginApi,
+  flowName: string,
+  relativePath: string
+): string {
+  const flowDir = path.join(
+    api.runtime.state.resolveStateDir(),
+    "flows",
+    flowName
+  );
+
+  // Validate that relativePath doesn't escape flowDir
+  return resolvePathSafely(flowDir, relativePath, "flow path");
+}
+
+/**
+ * Safe hook executor - wraps hook calls with error handling
+ * @param api - Plugin API for logging
+ * @param hookName - Name of the hook being called
+ * @param hookFn - The hook function to execute
+ * @param args - Arguments to pass to the hook
+ * @returns Result of hook or undefined if hook fails
+ */
+export async function safeExecuteHook<T, Args extends unknown[]>(
+  api: ClawdbotPluginApi,
+  hookName: string,
+  hookFn: ((...args: Args) => T | Promise<T>) | undefined,
+  ...args: Args
+): Promise<T | undefined> {
+  if (!hookFn) {
+    return undefined;
+  }
+
+  try {
+    const result = await hookFn(...args);
+    return result;
+  } catch (error) {
+    api.logger.error(`Hook ${hookName} failed:`, error);
+    return undefined;
+  }
+}

package/src/engine/renderer.ts

@@ -8,8 +8,10 @@ import type {
   FlowStep,
   FlowSession,
   ReplyPayload,
+  FlowHooks,
 } from "../types.js";
 import { normalizeButton } from "../validation.js";
+import { safeExecuteHook } from "./hooks-loader.js";
 
 /**
  * Interpolate variables in message text
@@ -69,7 +71,11 @@ function renderTelegram(
 
   return {
     text: message,
-    buttons: keyboard,
+    channelData: {
+      telegram: {
+        buttons: keyboard,
+      },
+    },
   };
 }
 
@@ -102,18 +108,34 @@ function renderFallback(
 /**
  * Render a flow step
  */
-export function renderStep(
-  _api: ClawdbotPluginApi,
+export async function renderStep(
+  api: ClawdbotPluginApi,
   flow: FlowMetadata,
   step: FlowStep,
   session: FlowSession,
-  channel: string
-): ReplyPayload {
+  channel: string,
+  hooks?: FlowHooks | null
+): Promise<ReplyPayload> {
+  // Call onStepRender hook if available
+  let finalStep = step;
+  if (hooks?.onStepRender) {
+    const modifiedStep = await safeExecuteHook(
+      api,
+      "onStepRender",
+      hooks.onStepRender,
+      step,
+      session
+    );
+    if (modifiedStep) {
+      finalStep = modifiedStep;
+    }
+  }
+
   // Channel-specific rendering
   if (channel === "telegram") {
-    return renderTelegram(flow.name, step, session.variables);
+    return renderTelegram(flow.name, finalStep, session.variables);
   }
 
   // Fallback for all other channels
-  return renderFallback(step, session.variables);
+  return renderFallback(finalStep, session.variables);
 }

package/src/engine/transitions.ts

@@ -8,8 +8,10 @@ import type {
   FlowStep,
   FlowSession,
   TransitionResult,
+  FlowHooks,
 } from "../types.js";
 import { normalizeButton, validateInput } from "../validation.js";
+import { safeExecuteHook } from "./hooks-loader.js";
 
 /**
  * Evaluate condition against session variables
@@ -86,13 +88,14 @@ function findNextStep(
 /**
  * Execute step transition
  */
-export function executeTransition(
-  _api: ClawdbotPluginApi,
+export async function executeTransition(
+  api: ClawdbotPluginApi,
   flow: FlowMetadata,
   session: FlowSession,
   stepId: string,
-  value: string | number
-): TransitionResult {
+  value: string | number,
+  hooks?: FlowHooks | null
+): Promise<TransitionResult> {
   // Find current step
   const step = flow.steps.find((s) => s.id === stepId);
 
@@ -124,10 +127,20 @@ export function executeTransition(
   const updatedVariables = { ...session.variables };
   if (step.capture) {
     // Convert to number if validation type is number
-    if (step.validate === "number") {
-      updatedVariables[step.capture] = Number(value);
-    } else {
-      updatedVariables[step.capture] = valueStr;
+    const capturedValue =
+      step.validate === "number" ? Number(value) : valueStr;
+    updatedVariables[step.capture] = capturedValue;
+
+    // Call onCapture hook
+    if (hooks?.onCapture) {
+      await safeExecuteHook(
+        api,
+        "onCapture",
+        hooks.onCapture,
+        step.capture,
+        capturedValue,
+        { ...session, variables: updatedVariables }
+      );
     }
   }
 

package/src/examples/pushups-hooks.example.js

@@ -0,0 +1,127 @@
+/**
+ * Example hooks file for pushups flow
+ *
+ * This file demonstrates how to use hooks to customize flow behavior.
+ * To use this with your pushups flow:
+ * 1. Copy this file to ~/.clawdbot/flows/pushups/hooks.js
+ * 2. Update pushups.json to reference it: "hooks": "./hooks.js"
+ *
+ * NOTE: This is just an example showing the API. The actual integrations
+ * (Google Sheets, calendar, etc.) would require additional dependencies
+ * and authentication setup.
+ */
+
+export default {
+  /**
+   * Dynamic button generation based on past performance
+   * Example: Center buttons around user's average reps
+   */
+  async onStepRender(step, _session) {
+    // Only modify rep-count steps
+    if (!step.id.startsWith('set')) {
+      return step;
+    }
+
+    // In a real implementation, you would:
+    // 1. Query past sessions (via custom storage backend or history.jsonl)
+    // 2. Calculate average reps for this step
+    // 3. Generate buttons centered around that average
+
+    // Example: Generate 5 buttons centered around 25 reps
+    const average = 25; // Would be calculated from history
+    const buttons = [
+      average - 10,
+      average - 5,
+      average,
+      average + 5,
+      average + 10,
+    ];
+
+    return {
+      ...step,
+      buttons,
+      message: `${step.message}\n\n💡 Your average: ${average} reps`,
+    };
+  },
+
+  /**
+   * Log each captured variable to external service
+   * Example: Append rep counts to Google Sheets
+   */
+  async onCapture(variable, value, _session) {
+    console.log(`[Hooks] Captured ${variable} = ${value}`);
+
+    // In a real implementation, you would:
+    // 1. Authenticate with Google Sheets API
+    // 2. Append [timestamp, userId, variable, value] to a spreadsheet
+    // 3. Handle errors gracefully
+
+    // Example pseudo-code:
+    // await sheets.append({
+    //   spreadsheetId: 'YOUR_SHEET_ID',
+    //   range: 'A:D',
+    //   values: [[new Date().toISOString(), session.senderId, variable, value]]
+    // });
+  },
+
+  /**
+   * Follow-up actions when flow completes
+   * Example: Schedule next workout, send summary
+   */
+  async onFlowComplete(session) {
+    console.log(`[Hooks] Flow completed for ${session.senderId}`);
+    console.log('Variables:', session.variables);
+
+    // Calculate total reps
+    const total =
+      (session.variables.set1 || 0) +
+      (session.variables.set2 || 0) +
+      (session.variables.set3 || 0) +
+      (session.variables.set4 || 0);
+
+    console.log(`Total reps: ${total}`);
+
+    // In a real implementation, you would:
+    // 1. Check calendar for next available slot
+    // 2. Create a cron job for that time
+    // 3. Create a calendar event
+    // 4. Send a congratulatory message
+
+    // Example pseudo-code:
+    // const nextWorkout = await calendar.findNextSlot();
+    // await cron.create({
+    //   schedule: nextWorkout,
+    //   command: '/flow-start pushups',
+    //   userId: session.senderId
+    // });
+    // await calendar.createEvent({
+    //   title: 'Pushups Workout',
+    //   start: nextWorkout,
+    //   duration: 30
+    // });
+  },
+
+  /**
+   * Track abandonment for analytics
+   * Example: Log to database for completion rate tracking
+   */
+  async onFlowAbandoned(session, reason) {
+    console.log(`[Hooks] Flow abandoned: ${reason}`);
+    console.log('Session:', session);
+
+    // In a real implementation, you would:
+    // 1. Log to analytics database
+    // 2. Track completion rates
+    // 3. Send reminder if appropriate
+
+    // Example pseudo-code:
+    // await db.logAbandonment({
+    //   userId: session.senderId,
+    //   flowName: session.flowName,
+    //   reason,
+    //   timestamp: Date.now(),
+    //   lastStep: session.currentStepId,
+    //   variables: session.variables
+    // });
+  },
+};

package/src/examples/sheets-storage.example.js

@@ -0,0 +1,126 @@
+/**
+ * Example custom storage backend for Google Sheets
+ *
+ * This file demonstrates how to implement a custom storage backend
+ * that writes completed sessions to Google Sheets instead of (or in addition to)
+ * the built-in JSONL files.
+ *
+ * To use this with your flow:
+ * 1. Copy this file to ~/.clawdbot/flows/<flowname>/storage.js
+ * 2. Update flow.json to reference it:
+ *    "storage": {
+ *      "backend": "./storage.js",
+ *      "builtin": false  // Set to false to only use custom backend
+ *    }
+ *
+ * NOTE: This is just an example showing the API. A real implementation
+ * would require:
+ * - npm install googleapis
+ * - Google Cloud project with Sheets API enabled
+ * - Service account credentials or OAuth tokens
+ * - Spreadsheet ID and appropriate permissions
+ */
+
+/**
+ * StorageBackend interface implementation
+ */
+export default {
+  /**
+   * Save a completed session to Google Sheets
+   * @param {FlowSession} session - The completed flow session
+   */
+  async saveSession(session) {
+    console.log('[Storage] Saving session to Google Sheets');
+    console.log('Session:', session);
+
+    // In a real implementation:
+    //
+    // 1. Authenticate with Google Sheets API
+    // const auth = await google.auth.getClient({
+    //   keyFile: 'path/to/credentials.json',
+    //   scopes: ['https://www.googleapis.com/auth/spreadsheets']
+    // });
+    // const sheets = google.sheets({ version: 'v4', auth });
+    //
+    // 2. Format session data as row
+    // const row = [
+    //   new Date().toISOString(),           // Timestamp
+    //   session.senderId,                   // User ID
+    //   session.flowName,                   // Flow name
+    //   JSON.stringify(session.variables),  // Variables (JSON)
+    //   session.variables.set1 || '',       // Individual columns per variable
+    //   session.variables.set2 || '',
+    //   session.variables.set3 || '',
+    //   session.variables.set4 || '',
+    // ];
+    //
+    // 3. Append to spreadsheet
+    // await sheets.spreadsheets.values.append({
+    //   spreadsheetId: 'YOUR_SPREADSHEET_ID',
+    //   range: 'Sheet1!A:H',  // Adjust range based on your columns
+    //   valueInputOption: 'RAW',
+    //   requestBody: {
+    //     values: [row]
+    //   }
+    // });
+    //
+    // 4. Handle errors
+    // try {
+    //   await sheets.spreadsheets.values.append(...);
+    // } catch (error) {
+    //   console.error('Failed to write to Google Sheets:', error);
+    //   throw error;  // Re-throw so plugin knows it failed
+    // }
+
+    // Placeholder for example
+    return Promise.resolve();
+  },
+
+  /**
+   * Load historical sessions from Google Sheets
+   * @param {string} flowName - Name of the flow
+   * @param {object} options - Query options
+   * @param {number} options.limit - Maximum number of sessions to return
+   * @param {string} options.senderId - Filter by user ID
+   * @returns {Promise<FlowSession[]>} Array of historical sessions
+   */
+  async loadHistory(flowName, options = {}) {
+    console.log('[Storage] Loading history from Google Sheets');
+    console.log('Flow:', flowName, 'Options:', options);
+
+    // In a real implementation:
+    //
+    // 1. Authenticate (same as above)
+    //
+    // 2. Read spreadsheet data
+    // const response = await sheets.spreadsheets.values.get({
+    //   spreadsheetId: 'YOUR_SPREADSHEET_ID',
+    //   range: 'Sheet1!A:H'
+    // });
+    // const rows = response.data.values || [];
+    //
+    // 3. Parse rows into FlowSession objects
+    // const sessions = rows
+    //   .filter(row => row[2] === flowName)  // Filter by flow name
+    //   .filter(row => !options.senderId || row[1] === options.senderId)
+    //   .map(row => ({
+    //     flowName: row[2],
+    //     senderId: row[1],
+    //     currentStepId: '',  // Not stored in this example
+    //     channel: '',        // Not stored in this example
+    //     variables: JSON.parse(row[3]),
+    //     startedAt: 0,       // Could parse from row[0]
+    //     lastActivityAt: 0,  // Could parse from row[0]
+    //   }));
+    //
+    // 4. Apply limit
+    // if (options.limit) {
+    //   return sessions.slice(-options.limit);  // Most recent N
+    // }
+    //
+    // return sessions;
+
+    // Placeholder for example
+    return Promise.resolve([]);
+  },
+};

package/src/security/path-validation.ts

@@ -0,0 +1,53 @@
+import path from "node:path";
+
+/**
+ * Validate that a resolved path stays within a base directory.
+ * Prevents directory traversal attacks like ../../../etc/passwd
+ * @throws Error if path escapes base directory
+ */
+export function validatePathWithinBase(
+  resolvedPath: string,
+  baseDir: string,
+  description: string = "path"
+): void {
+  const normalized = path.normalize(path.resolve(resolvedPath));
+  const normalizedBase = path.normalize(path.resolve(baseDir));
+
+  // Must be inside baseDir or be exactly baseDir
+  const insideOrEqual =
+    normalized === normalizedBase ||
+    normalized.startsWith(normalizedBase + path.sep);
+
+  if (!insideOrEqual) {
+    throw new Error(
+      `Path traversal detected: ${description} "${resolvedPath}" escapes base directory "${baseDir}"`
+    );
+  }
+}
+
+/**
+ * Safely resolve a relative path within a base directory
+ * @returns Absolute path if valid; throws if attempts to escape base
+ */
+export function resolvePathSafely(
+  basePath: string,
+  relativePath: string,
+  description: string = "path"
+): string {
+  const resolved = path.resolve(basePath, relativePath);
+  validatePathWithinBase(resolved, basePath, description);
+  return resolved;
+}
+
+/**
+ * Sanitize a filename for cross-platform compatibility
+ * Removes unsafe characters: < > : " / \ | ? * and control chars
+ */
+export function sanitizeFilename(name: string): string {
+  // Remove unsafe chars and control chars (U+0000-U+001F)
+  // eslint-disable-next-line no-control-regex
+  const unsafe = /[<>:"/\\|?*\x00-\x1f]/g;
+  const sanitized = name.trim().replace(unsafe, "_").replace(/\s+/g, "_");
+  // Collapse multiple underscores, trim leading/trailing, limit length
+  return sanitized.replace(/_+/g, "_").replace(/^_|_$/g, "").slice(0, 60);
+}

package/src/state/history-store.ts

@@ -5,7 +5,12 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
-import type { FlowSession } from "../types.js";
+import type { FlowSession, FlowMetadata } from "../types.js";
+import type { SkillFlowConfig } from "../config.js";
+import {
+  loadStorageBackend,
+  resolveFlowPath,
+} from "../engine/hooks-loader.js";
 
 /**
  * Get history file path for a flow
@@ -20,8 +25,36 @@ function getHistoryPath(api: ClawdbotPluginApi, flowName: string): string {
  */
 export async function saveFlowHistory(
   api: ClawdbotPluginApi,
-  session: FlowSession
+  session: FlowSession,
+  flow?: FlowMetadata,
+  config?: SkillFlowConfig
 ): Promise<void> {
+  // Use custom storage backend if configured
+  if (flow?.storage?.backend) {
+    try {
+      const backendPath = resolveFlowPath(
+        api,
+        session.flowName,
+        flow.storage.backend
+      );
+      const backend = await loadStorageBackend(api, backendPath);
+      if (backend) {
+        await backend.saveSession(session);
+      }
+    } catch (error) {
+      api.logger.error(
+        `Custom storage backend failed for flow ${session.flowName}:`,
+        error
+      );
+    }
+  }
+
+  // Write to built-in JSONL storage unless disabled by config or flow settings
+  const useBuiltin = config?.enableBuiltinHistory ?? flow?.storage?.builtin ?? true;
+  if (!useBuiltin) {
+    return;
+  }
+
   const historyPath = getHistoryPath(api, session.flowName);
 
   try {

package/src/state/session-store.ts

@@ -3,12 +3,13 @@
  */
 
 import type { FlowSession } from "../types.js";
+import type { SkillFlowConfig } from "../config.js";
 
-// Session timeout: 30 minutes
-const SESSION_TIMEOUT_MS = 30 * 60 * 1000;
+// Session timeout: 30 minutes (default, configurable)
+let SESSION_TIMEOUT_MS = 30 * 60 * 1000;
 
-// Cleanup interval: 5 minutes
-const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+// Cleanup interval: 5 minutes (default, configurable)
+let CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
 
 // In-memory session store
 const sessions = new Map<string, FlowSession>();
@@ -16,6 +17,23 @@ const sessions = new Map<string, FlowSession>();
 // Cleanup timer
 let cleanupTimer: NodeJS.Timeout | null = null;
 
+/**
+ * Initialize session store with configuration
+ */
+export function initSessionStore(config: SkillFlowConfig): void {
+  SESSION_TIMEOUT_MS = config.sessionTimeoutMinutes * 60 * 1000;
+  CLEANUP_INTERVAL_MS = config.sessionCleanupIntervalMinutes * 60 * 1000;
+
+  // Restart cleanup timer with new interval
+  if (cleanupTimer) {
+    clearInterval(cleanupTimer);
+    cleanupTimer = null;
+  }
+  if (sessions.size > 0) {
+    cleanupTimer = setInterval(cleanupExpiredSessions, CLEANUP_INTERVAL_MS);
+  }
+}
+
 /**
  * Generate session key
  */

package/src/types.ts

@@ -38,6 +38,11 @@ export interface FlowMetadata {
     cron?: string;
     event?: string;
   };
+  hooks?: string; // Path to hooks file (relative to flow directory)
+  storage?: {
+    backend?: string; // Path to custom storage backend
+    builtin?: boolean; // Also write to JSONL (default: true)
+  };
 }
 
 export interface FlowSession {
@@ -60,8 +65,76 @@ export interface TransitionResult {
 
 export interface ReplyPayload {
   text: string;
-  buttons?: Array<{
-    text: string;
-    callback_data: string;
-  }[]>;
+  channelData?: {
+    telegram?: {
+      buttons?: Array<Array<{ text: string; callback_data: string }>>;
+    };
+  };
+}
+
+/**
+ * Hooks interface for customizing flow behavior at key points.
+ * All hooks are optional and async-compatible.
+ */
+export interface FlowHooks {
+  /**
+   * Called before rendering a step. Return modified step (e.g., dynamic buttons).
+   * @param step - The step about to be rendered
+   * @param session - Current session state (variables, history)
+   * @returns Modified step or original
+   */
+  onStepRender?: (
+    step: FlowStep,
+    session: FlowSession
+  ) => FlowStep | Promise<FlowStep>;
+
+  /**
+   * Called after a variable is captured. Use for external logging.
+   * @param variable - Variable name
+   * @param value - Captured value
+   * @param session - Current session state
+   */
+  onCapture?: (
+    variable: string,
+    value: string | number,
+    session: FlowSession
+  ) => void | Promise<void>;
+
+  /**
+   * Called when flow completes (reaches terminal step). Use for follow-up actions.
+   * @param session - Final session state with all captured variables
+   */
+  onFlowComplete?: (session: FlowSession) => void | Promise<void>;
+
+  /**
+   * Called when flow is abandoned (timeout, user cancels).
+   * @param session - Session state at time of abandonment
+   * @param reason - "timeout" | "cancelled" | "error"
+   */
+  onFlowAbandoned?: (
+    session: FlowSession,
+    reason: "timeout" | "cancelled" | "error"
+  ) => void | Promise<void>;
+}
+
+/**
+ * Pluggable storage backend interface for custom persistence.
+ */
+export interface StorageBackend {
+  /**
+   * Save a completed session to storage.
+   * @param session - The completed flow session
+   */
+  saveSession(session: FlowSession): Promise<void>;
+
+  /**
+   * Load historical sessions for a flow.
+   * @param flowName - Name of the flow
+   * @param options - Query options (limit, filter by sender)
+   * @returns Array of historical sessions
+   */
+  loadHistory(
+    flowName: string,
+    options?: { limit?: number; senderId?: string }
+  ): Promise<FlowSession[]>;
 }

package/src/validation.ts

@@ -49,6 +49,14 @@ const TriggerSchema = z
   })
   .optional();
 
+// Storage backend schema
+const StorageSchema = z
+  .object({
+    backend: z.string().optional(),
+    builtin: z.boolean().optional(),
+  })
+  .optional();
+
 // Complete flow metadata schema
 export const FlowMetadataSchema = z.object({
   name: z.string(),
@@ -57,6 +65,8 @@ export const FlowMetadataSchema = z.object({
   author: z.string().optional(),
   steps: z.array(FlowStepSchema).min(1),
   triggers: TriggerSchema,
+  hooks: z.string().optional(),
+  storage: StorageSchema,
 });
 
 /**

package/types.d.ts

@@ -14,6 +14,7 @@ declare module "lockfile" {
 
 declare module "clawdbot/plugin-sdk" {
   export interface ClawdbotPluginApi {
+    pluginConfig?: Record<string, unknown>;
     logger: {
       info(...args: any[]): void;
       error(...args: any[]): void;