@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/CHANGELOG.md

@@ -1,5 +1,1056 @@
 # @flink-app/flink
 
+## 2.0.0-alpha.100
+
+### Patch Changes
+
+-   6e8166a: Fix handler `Params`/`Query` metadata extraction for semicolon-free `type` aliases (#77). The build-time source parser previously required `;` delimiters: a `type Params = { ... }` written without trailing/field semicolons would either extract only the first property or fail entirely (registering empty param metadata silently). `findTypeDefinition` now terminates an object type alias at its closing brace when no trailing `;` is present, and `extractPropertiesFromObjectType` now treats a top-level newline as a property separator while still preserving multi-line union/nested-object types.
+
+## 2.0.0-alpha.99
+
+### Minor Changes
+
+-   ed9cd2c: Extend `onError` callback to also fire for request validation (400 Bad request) and response validation (500 Bad response) failures, in addition to handler-thrown errors. Streaming handler errors continue to be delivered via `stream.error()` and do not trigger `onError`.
+
+    The callback context now also includes the app context as `ctx`, so handlers can use repos/plugins (e.g. `context.ctx.repos.errorLogRepo`) from within `onError`. `FlinkOptions` is now generic over the app context (`FlinkOptions<C>`) with a default of `FlinkContext`, keeping existing usages backward compatible.
+
+## 2.0.0-alpha.98
+
+### Minor Changes
+
+-   2f4a132: feat: expose verified token on the request
+
+    The JWT auth plugin now populates `req.token` (the decoded, signature-verified
+    payload) and `req.rawToken` (the original token string) after successful
+    authentication. Handlers can read token claims such as `jti` directly instead of
+    re-extracting and re-decoding the bearer token with an unverified decode.
+
+    ```ts
+    // Before
+    const authHeader = req.headers.authorization;
+    const bearer = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : undefined;
+    const decoded = bearer ? (jsonwebtoken.decode(bearer) as { jti?: string }) : null;
+    const sessionId = decoded?.jti ?? legacySessionId(req.user._id);
+
+    // After
+    const { jti } = (req.token as { jti?: string }) ?? {};
+    const sessionId = jti ?? legacySessionId(req.user._id);
+    ```
+
+    `token` / `rawToken` are added as optional fields on the core `FlinkRequest`
+    type, populated by auth plugins that have a token concept.
+
+## 2.0.0-alpha.97
+
+### Minor Changes
+
+-   eed6bc1: Pass host application context to auth plugins.
+
+    `FlinkAuthPlugin.authenticateRequest` now receives the host app's context as an optional third argument. Flink core supplies it on every authenticated request, so auth plugins can access repos/services without the caller wiring up a lazy accessor or maintaining a module-level mutable reference.
+
+    For `@flink-app/jwt-auth-plugin`, this means `getUser` receives the context directly:
+
+    ```typescript
+    jwtAuthPlugin({
+        getUser: async (tokenData, req, ctx) => {
+            const user = await ctx?.repos.userRepo.getById(tokenData._id);
+            return user ? { username: user.username, _id: user._id } : null;
+        },
+    });
+    ```
+
+    The `getContext` option previously added in alpha.96 is no longer needed and has been removed — remove it from your `jwtAuthPlugin({ … })` call. The third `ctx` parameter on `getUser` is optional, so callbacks that ignore it are unaffected.
+
+## 2.0.0-alpha.96
+
+### Patch Changes
+
+-   Fix double-JSON-encoding of tool results on conversation reload.
+
+    `ConversationAgent.convertToAgentMessages` was re-stringifying tool result payloads that `ToolExecutor.formatResultForAI` had already serialized to a JSON string. Each reload escaped the value one more level, corrupting tool history on every continuation turn (visible through any LLM adapter, including Anthropic). Strings are now passed through untouched; non-string values are still stringified for backward compatibility with older storage rows.
+
+## 2.0.0-alpha.95
+
+## 2.0.0-alpha.94
+
+## 2.0.0-alpha.93
+
+## 2.0.0-alpha.92
+
+### Minor Changes
+
+-   8d23d56: Add global `AgentObserver` for app-level agent tracing
+
+    A new `observer` option on `FlinkOptions.ai` lets applications register a single, app-wide hook that fires for every agent execution — covering both streamed and awaited (`response.result`) callers without per-agent plumbing.
+
+    Events expose data that was previously only internal to `AgentRunner`:
+
+    -   `onRun` — pre-loop, with resolved system instructions and initial messages.
+    -   `onLlmCall` — per step, immediately before the adapter call. `messages` reflects post-compaction state and `tools` reflects per-step permission filtering.
+    -   `onStep` — per step end, with `assistantText`, per-step `toolCalls`, and `usage`.
+    -   `onFinish` — post-loop (success or error), with the final result, total `durationMs`, and the error message on failure.
+
+    All events share a stable `runId` per execution; the same ID is now also returned on `AgentExecuteResult.runId` so apps can correlate persisted results with observer traces.
+
+    Observer callbacks are fire-and-forget: they may return a promise but the framework does not await them, and any thrown/rejected errors are caught and logged without affecting agent execution.
+
+    The existing per-agent `beforeRun` / `onStep` / `afterRun` hooks remain unchanged — use the observer for cross-cutting concerns (tracing, APM, cost accounting, dev tools) and per-agent hooks for business logic that needs to block or mutate state (conversation persistence, guardrails).
+
+    Example:
+
+    ```typescript
+    new FlinkApp({
+        ai: {
+            llms: { default: new AnthropicAdapter({ ... }) },
+            observer: {
+                onRun(e) {
+                    trace.start(e.runId, { agentId: e.agentId, instructions: e.instructions });
+                },
+                onLlmCall(e) {
+                    trace.recordLlmCall(e.runId, e.step, e.messages, e.tools);
+                },
+                onStep(e) {
+                    trace.recordStep(e.runId, e.step, e.assistantText, e.toolCalls, e.usage);
+                },
+                onFinish(e) {
+                    trace.finish(e.runId, { result: e.result, error: e.error, durationMs: e.durationMs });
+                },
+            },
+        },
+    });
+    ```
+
+## 2.0.0-alpha.91
+
+## 2.0.0-alpha.90
+
+### Minor Changes
+
+-   0d84b5f: Add optional `meta` field to error responses for structured context
+
+    The `error` object in `FlinkResponse` now supports an optional `meta?: unknown`
+    field for passing structured payloads alongside an error (e.g. payment decline
+    codes, retry hints, gateway metadata). All six error helpers (`notFound`,
+    `conflict`, `badRequest`, `unauthorized`, `forbidden`, `internalServerError`)
+    accept it as an optional third argument.
+
+    The value must be JSON-serializable. If serialization fails (e.g. `BigInt`,
+    circular references), the framework silently strips `meta` and logs a warning
+    before sending the response.
+
+    ```typescript
+    return badRequest("Payment declined", "paymentDeclined", {
+        gatewayCode: "insufficient_funds",
+        attemptId: "att_123",
+    });
+    ```
+
+    Fully additive — existing callers are unaffected.
+
+## 2.0.0-alpha.89
+
+## 2.0.0-alpha.88
+
+## 2.0.0-alpha.87
+
+### Patch Changes
+
+-   Register Handlebars raw helper so {{{{raw}}}}...{{{{/raw}}}} blocks in agent instruction files pass content through literally instead of silently dropping it
+
+## 2.0.0-alpha.86
+
+## 2.0.0-alpha.85
+
+## 2.0.0-alpha.84
+
+## 2.0.0-alpha.83
+
+### Minor Changes
+
+-   Add FlinkService as optional business logic layer with auto-discovery, ctx injection, async onInit(), and mockCtx() test helper
+
+## 2.0.0-alpha.82
+
+## 2.0.0-alpha.81
+
+## 2.0.0-alpha.80
+
+## 2.0.0-alpha.79
+
+## 2.0.0-alpha.78
+
+## 2.0.0-alpha.77
+
+## 2.0.0-alpha.76
+
+## 2.0.0-alpha.75
+
+## 2.0.0-alpha.74
+
+### Patch Changes
+
+-   feat: add leader election for horizontally scaled job scheduling
+
+    Adds MongoDB-based leader election so that when multiple instances of a Flink app are running, only one (the leader) executes scheduled jobs. If the leader goes down, another instance takes over automatically. Includes dedicated scheduler logger and improved robustness.
+
+-   fix: add updateById method to FlinkRepo for convenient document updates by ID
+
+## 2.0.0-alpha.73
+
+### Patch Changes
+
+-   fix(flink): register static routes before parameterized routes to prevent e.g. GET /jobs/by-tags being matched by GET /jobs/:id
+
+## 2.0.0-alpha.72
+
+### Patch Changes
+
+-   fix(test-utils): accept typed FlinkApp instances in init() by casting internally
+
+## 2.0.0-alpha.71
+
+## 2.0.0-alpha.70
+
+## 2.0.0-alpha.69
+
+## 2.0.0-alpha.68
+
+## 2.0.0-alpha.67
+
+### Patch Changes
+
+-   418cb54: feat(instructions): add `{{import "..."}}` directive for composable markdown instruction files
+
+    Markdown instruction files can now import other markdown files using `{{import "./path/to/file.md"}}`. Imports resolve relative to the containing file, support recursive chaining, and detect circular imports with a clear error message. Handlebars template variables continue to work normally across all imported content.
+
+-   70d574c: refactor(agent): remove debug flag in favour of log levels
+
+    The `debug` property on `FlinkAgent` and `FlinkAgentProps` is removed. Verbose agent logging (LLM requests, responses, tool calls, compaction) is now always emitted at the `debug` log level and can be enabled via the standard Flink log level configuration (e.g. `LOG_LEVEL=debug` or per-logger overrides). This removes a redundant knob that duplicated what log levels already provide.
+
+## 2.0.0-alpha.66
+
+### Patch Changes
+
+-   5593d26: fix(tools): resolve cross-schema \$ref into \$defs for LLM providers
+
+    Tools using auto-generated schemas with TypeScript type references (e.g. a shared Canvas.ElementInput type) produced schemas with \$ref values like `"Canvas.ElementInput"`. AJV handled these fine via its schema registry, but OpenAI rejects them with "reference can only point to definitions defined at the top level of the schema".
+
+    ToolExecutor now resolves all cross-schema refs into a self-contained \$defs block, rewriting \$ref values to the standard #/\$defs/... format before returning the schema to LLM adapters. The openai-adapter sanitizer also now recurses into \$defs entries.
+
+## 2.0.0-alpha.65
+
+## 2.0.0-alpha.64
+
+### Patch Changes
+
+-   95b99ee: Add image and binary Buffer response support
+
+    Handlers can now return a Node.js `Buffer` as `data` when `responseType` is set to an image or binary MIME type. The buffer is sent as raw bytes with the correct `Content-Type` — no JSON wrapping.
+
+    Common image and binary MIME types are now first-class literals in `RouteProps.responseType` with autocomplete support: `"image/png"`, `"image/jpeg"`, `"image/gif"`, `"image/webp"`, `"image/svg+xml"`, `"application/pdf"`, `"application/octet-stream"`.
+
+    Example:
+
+    ```typescript
+    export const Route: RouteProps = {
+        path: "/logo",
+        responseType: "image/png",
+    };
+
+    const handler: GetHandler<Ctx, Buffer> = async () => {
+        const buf = await fs.promises.readFile("./assets/logo.png");
+        return { data: buf };
+    };
+    ```
+
+## 2.0.0-alpha.63
+
+### Patch Changes
+
+-   810df2c: Fix FlinkJob afterDelay: "0ms" running in a tight loop instead of once. Zero-delay jobs now run immediately via setImmediate (exactly once) rather than being registered with a 0ms scheduler interval. Also adds specs covering uncaught exception handling for all job scheduling modes.
+-   8dd0752: fix: prevent server crash when handler returns no data with a response schema defined
+
+    When a PATCH (or any) handler returned `{ status: 204 }` without a `data` field,
+    `JSON.stringify(undefined)` returned the JS value `undefined`, causing
+    `JSON.parse(undefined)` to throw a `SyntaxError` that crashed the entire server process.
+
+    New behaviour:
+
+    -   Status 204 + no data → skip validation silently (intentional no-content response)
+    -   Non-204 status + no data + response schema defined → return 500 bad response with a
+        descriptive error message (surfaces the developer mistake without crashing the server)
+    -   Data present → validate against schema as before
+
+## 2.0.0-alpha.62
+
+### Minor Changes
+
+-   Add file-based agent instructions with Handlebars templating
+
+    The `instructions()` method now supports returning a file path or `{ file, params? }` object:
+
+    -   Return a string ending in `.md`, `.txt`, `.yaml`, `.yml`, `.xml`, etc. to auto-load from disk
+    -   Return `{ file: "instructions/agent.md", params: { tier: "premium" } }` for Handlebars templates
+    -   All paths resolve relative to the project root (`process.cwd()`)
+    -   Files are cached with mtime-based invalidation
+    -   Template variables `{{ctx}}`, `{{agentContext}}`, and `{{user}}` are always available
+
+    Also fixes a bug where `getRequestPermissions()` returning `[]` outside a request context
+    would override `user.permissions` in the fallback chain, causing permission checks to fail.
+
+## 2.0.0-alpha.61
+
+## 2.0.0-alpha.60
+
+## 2.0.0-alpha.59
+
+### Minor Changes
+
+-   dbc2119: feat: add generic compiler extension system and @flink-app/inbound-email-plugin
+
+    Add `compilerPlugins` to `FlinkConfig` and `FlinkCompilerPlugin` interface so plugins can declare custom scan directories for auto-discovery. The TypeScript compiler reads these at build time, generates the corresponding `.flink/generatedXxx.ts` registration files, and includes them in the start script.
+
+    Introduce `@flink-app/inbound-email-plugin` as the first consumer of this system. It starts an SMTP server and automatically routes inbound emails to matching `EmailHandler` files discovered in `src/email-handlers/`. User and permission context are injected via `AsyncLocalStorage` for seamless integration with Flink tools and agents.
+
+## 2.0.0-alpha.58
+
+### Patch Changes
+
+-   Move @flink-app/ts-source-to-json-schema to dependencies (was incorrectly in devDependencies) and make @swc/core an optional peer dependency with graceful fallback to tsc
+
+## 2.0.0-alpha.57
+
+### Minor Changes
+
+-   ef7f495: Add AsyncLocalStorage for automatic user/permissions injection in tools
+
+    **New Features:**
+
+    -   Tools now receive `user` and `permissions` parameters automatically from AsyncLocalStorage
+    -   Declarative permissions in tool definitions - framework checks before execution
+    -   No more need for explicit `agent.withUser()` bindings
+    -   Context flows automatically: handler → agent → tools
+
+    **API Changes:**
+
+    -   `ToolExecutor.execute()` signature: `(input, overrides?)` instead of `(input, user?, permissions?)`
+    -   `FlinkTool` handler signature includes `user?` and `permissions?` parameters
+    -   Permission checking supports explicit permissions without requiring user object
+
+    **Testing:**
+
+    -   New test utilities: `withRequestContext()`, `createMockUser()`, `createMockRequestContext()`
+    -   Override support for unit testing: `execute(input, { user, permissions })`
+    -   13 new AsyncLocalStorage integration tests
+
+    **Developer Experience:**
+
+    ```typescript
+    // Before: Manual user passing
+    await agent.withUser(req.user).execute({ message: "..." });
+
+    // After: Automatic context flow
+    await agent.execute({ message: "..." });
+
+    // Tools with declarative permissions
+    export const Tool: FlinkToolProps = {
+        permissions: ["car:read"], // ✨ Checked by framework
+    };
+
+    const handler: FlinkTool<Ctx, In, Out> = async ({
+        input,
+        ctx,
+        user,
+        permissions, // ✨ Auto-injected
+    }) => {
+        // Permission already verified - just implement logic
+    };
+    ```
+
+-   2d53aa4: feat: automatic schema derivation for FlinkTools
+
+    FlinkTools now support automatic schema generation from TypeScript type parameters, eliminating the need for manual Zod or JSON Schema definitions.
+
+    **New Features:**
+
+    -   Auto-generate input/output schemas from `FlinkTool<Ctx, Input, Output>` type parameters
+    -   Support for TypeScript interfaces, inline types, and primitive types
+    -   Three-tier validation precedence: Manual Zod > Manual JSON > Auto-generated
+    -   Automatic ToolResult unwrapping (extracts `T` from `ToolResult<T>`)
+
+    **Breaking Changes:** None - fully backward compatible with existing tools
+
+    **Migration:**
+
+    ```typescript
+    // Before (manual schemas required)
+    export const Tool: FlinkToolProps = {
+        id: "search-cars",
+        description: "Search for cars",
+        inputSchema: z.object({ brand: z.string() }),
+        outputSchema: z.string(),
+    };
+
+    const SearchTool: FlinkTool<AppCtx, z.infer<typeof Tool.inputSchema>, z.infer<typeof Tool.outputSchema>> = async ({ input }) => {
+        return { success: true, data: "result" };
+    };
+
+    // After (schemas auto-generated from types)
+    interface SearchInput {
+        brand: string;
+    }
+
+    export const Tool: FlinkToolProps = {
+        id: "search-cars",
+        description: "Search for cars",
+        // No schemas needed!
+    };
+
+    const SearchTool: FlinkTool<AppCtx, SearchInput, string> = async ({ input }) => {
+        return { success: true, data: "result" };
+    };
+    ```
+
+    **Technical Details:**
+
+    -   Schemas extracted during TypeScript compilation via ts-morph
+    -   JSON schemas generated via ts-json-schema-generator
+    -   `__schemas` export automatically added to tool source files
+    -   JSDoc comments preserved in generated schemas
+
+-   b3cc5d1: feat(ai): add comprehensive cache metrics support for token usage tracking
+
+    ## Overview
+
+    Added detailed cache metrics to LLM adapters for better cost optimization and performance tracking. Both OpenAI and Anthropic adapters now capture and expose cache-related token counts.
+
+    ## What's New
+
+    ### LLMUsage Interface
+
+    -   New `LLMUsage` interface with cache-related fields:
+        -   `cachedInputTokens`: Tokens served from cache (lower cost)
+        -   `cacheCreationInputTokens`: Tokens written to cache (Anthropic only, higher cost)
+
+    ### OpenAI Adapter
+
+    -   Captures `cached_tokens` from `input_tokens_details`
+    -   Provides 10% cost savings for cached tokens
+    -   Includes cache metrics in usage logs
+
+    ### Anthropic Adapter
+
+    -   Captures `cache_read_input_tokens` (10% cost)
+    -   Captures `cache_creation_input_tokens` (125% cost)
+    -   Full visibility into cache economics
+
+    ### AgentRunner
+
+    -   Automatically aggregates cache metrics across multi-turn conversations
+    -   Includes cache data in sub-agent call tracking
+    -   Available in `AgentExecuteResult.usage`
+
+    ## Cache Economics
+
+    **OpenAI:**
+
+    -   Cached tokens: ~10% of regular token cost
+    -   Significant savings for repeated context
+
+    **Anthropic:**
+
+    -   Cache read: 10% of regular token cost
+    -   Cache write: 125% of regular token cost (one-time cost, then 10% on reads)
+    -   Minimum cache threshold: 2048 tokens
+
+    ## Example Usage
+
+    ```typescript
+    const result = await agent.execute({ message: "Hello" });
+
+    console.log(result.usage);
+    // {
+    //   inputTokens: 2006,
+    //   outputTokens: 300,
+    //   cachedInputTokens: 1920,  // 95% cache hit!
+    // }
+
+    // Calculate actual billed input tokens
+    const billedTokens = result.usage.inputTokens - (result.usage.cachedInputTokens || 0);
+    console.log(`Only ${billedTokens} tokens charged at full rate`);
+    ```
+
+    ## Breaking Changes
+
+    None - all cache fields are optional and backwards compatible.
+
+-   d377fac: Add context compaction feature for automatic message history management in agents
+
+    Agents can now automatically manage message history size during long-running conversations using two new optional callbacks: `shouldCompact` and `compactHistory`. This prevents context window overflow and helps control token costs.
+
+    Features:
+
+    -   `shouldCompact` callback to determine when compaction is needed (message count, size, token estimation, or custom logic)
+    -   `compactHistory` callback to perform the actual compaction (sliding window, keep first+last, summarization, or custom strategy)
+    -   Default compaction strategy (keep last 10 messages) when only `shouldCompact` is provided
+    -   Async support for both callbacks
+    -   Comprehensive error handling - failures are logged but don't break execution
+    -   Debug logging to monitor compaction events
+    -   Compaction occurs before each LLM call in the agentic loop
+
+    Example usage:
+
+    ```typescript
+    export default class ChatAgent extends FlinkAgent<AppCtx> {
+        id = "chat-agent";
+        description = "Chat assistant with history management";
+        instructions = "You are a helpful assistant...";
+
+        // Compact when history exceeds 20 messages
+        shouldCompact = (messages, step) => messages.length > 20;
+
+        // Keep only last 10 messages
+        compactHistory = (messages, step) => messages.slice(-10);
+    }
+    ```
+
+    This is a fully opt-in feature with no impact on existing agents.
+
+-   90f80c7: Add `responseType` route option for non-JSON responses
+
+    Set `responseType` in `RouteProps` to send the handler's `data` field as a raw
+    response with the given content type instead of the standard JSON envelope.
+    Response schema validation is automatically skipped.
+
+    Accepts Express shorthand names (`"html"`, `"csv"`, `"text"`, `"xml"`) or any
+    full MIME type string.
+
+    ```typescript
+    export const Route: RouteProps = {
+        path: "/dashboard",
+        responseType: "html",
+    };
+
+    const handler: GetHandler<Ctx, void> = async ({ ctx }) => {
+        return {
+            data: `<!DOCTYPE html><html><body><h1>Dashboard</h1></body></html>`,
+        };
+    };
+
+    export default handler;
+    ```
+
+    ```typescript
+    export const Route: RouteProps = {
+        path: "/export",
+        responseType: "csv",
+    };
+
+    const handler: GetHandler<Ctx, void> = async ({ ctx }) => {
+        return { data: `id,name\n1,Alice\n2,Bob` };
+    };
+
+    export default handler;
+    ```
+
+-   f0887e7: feat: simplified conversation persistence with InMemoryConversationAgent
+
+    **New Features:**
+
+    1. **ConversationAgent Base Class** - Abstract base class for automatic conversation persistence:
+
+        ```typescript
+        export default class ChatAgent extends ConversationAgent<AppContext> {
+            id = "chat-agent";
+            description = "Chat assistant with automatic persistence";
+            instructions = "You are a helpful assistant...";
+            tools = ["search-knowledge"];
+
+            protected async loadConversation(conversationId: string) {
+                const conv = await this.ctx.repos.conversationRepo.getById(conversationId);
+                return conv
+                    ? {
+                          messages: conv.messages,
+                          providerMetadata: conv.providerMetadata,
+                      }
+                    : null;
+            }
+
+            protected async saveConversation(conversationId: string, data: ConversationData) {
+                await this.ctx.repos.conversationRepo.upsert({
+                    _id: conversationId,
+                    messages: data.messages,
+                    providerMetadata: data.providerMetadata,
+                });
+            }
+        }
+        ```
+
+    2. **InMemoryConversationAgent** - Opinionated convenience class for rapid prototyping:
+
+        ```typescript
+        export default class MyAgent extends InMemoryConversationAgent<AppContext> {
+            id = "my-agent";
+            description = "Quick prototype agent";
+            instructions = "You are a helpful assistant...";
+            tools = ["search-knowledge"];
+            // That's it! Storage already implemented
+        }
+
+        // Testing utilities
+        InMemoryConversationAgent.clearAll();
+        InMemoryConversationAgent.getConversationCount();
+        InMemoryConversationAgent.getAllConversationIds();
+        ```
+
+    3. **Provider Metadata Tracking** - Framework preserves provider-specific metadata:
+
+        ```typescript
+        const result = await agent.execute({
+            message: "Hello",
+            conversationId: "conv-123",
+        }).result;
+
+        // Metadata preserved for debugging/future use
+        console.log(result.providerMetadata); // { openai: { ... } }
+        ```
+
+    **Simplified Architecture:**
+
+    Removed persistence strategies in favor of always sending full conversation history:
+
+    -   ❌ Removed: `ConversationPersistenceStrategy` type ("auto" | "provider-optimized" | "full-history")
+    -   ❌ Removed: `persistenceStrategy` property from ConversationAgent
+    -   ❌ Removed: `persistenceStrategy` parameter from LLMAdapter.stream()
+    -   ❌ Removed: OpenAI's previousResponseId optimization and instruction hashing
+    -   ✅ Kept: Provider metadata preservation (for tracking/debugging/future use)
+    -   ✅ Kept: Full conversation history always sent for reliability
+
+    **Benefits:**
+
+    -   **Simplicity**: Single code path, easier to understand and maintain
+    -   **Reliability**: No optimization edge cases or hybrid logic bugs
+    -   **Debuggability**: Full conversation history always available
+    -   **Rapid Prototyping**: InMemoryConversationAgent removes boilerplate
+    -   **Future-Proof**: Can re-introduce optimizations with different architecture if needed
+
+    **Breaking Changes:**
+
+    For LLM Adapter Implementers:
+
+    -   Must remove `persistenceStrategy` parameter from `stream()` method signature
+
+    For Agent Users (Optional Cleanup):
+
+    -   Remove `persistenceStrategy` property from ConversationAgent subclasses (no longer used)
+    -   Remove `persistenceStrategy` from execute options (no longer supported)
+
+    **Migration:**
+
+    Existing ConversationAgent implementations continue to work - just remove any `persistenceStrategy` references:
+
+    ```typescript
+    // Before
+    export default class MyAgent extends ConversationAgent<AppContext> {
+      persistenceStrategy = "full-history"; // ❌ Remove this
+
+      protected async loadConversation(conversationId: string) { ... }
+      protected async saveConversation(conversationId: string, data: ConversationData) { ... }
+    }
+
+    // After
+    export default class MyAgent extends ConversationAgent<AppContext> {
+      // ✅ Just implement storage methods
+      protected async loadConversation(conversationId: string) { ... }
+      protected async saveConversation(conversationId: string, data: ConversationData) { ... }
+    }
+    ```
+
+    For rapid prototyping, use InMemoryConversationAgent instead:
+
+    ```typescript
+    // New option: Zero boilerplate
+    export default class MyAgent extends InMemoryConversationAgent<AppContext> {
+        id = "my-agent";
+        description = "Quick prototype";
+        instructions = "...";
+        tools = [];
+        // Storage already implemented!
+    }
+    ```
+
+-   68c46d3: feat(logging): add Java-style hierarchical prefix matching for component logging
+
+    Introduces hierarchical prefix matching inspired by Java logging frameworks (Log4j, Logback):
+
+    **Key Features:**
+
+    -   **Dot notation**: `flink.ai.openai` (like Java packages)
+    -   **Lowercase naming**: All logger names normalized to lowercase
+    -   **Case-insensitive**: `Flink.AI.OpenAI` → `flink.ai.openai`
+    -   **Hierarchical matching**: `flink.ai` matches all `flink.ai.*` loggers
+    -   **Precedence**: More specific configs override less specific (Java inheritance)
+
+    **Usage:**
+
+    Environment variables:
+
+    ```bash
+    # Simple hierarchical config (recommended)
+    LOG_LEVELS=flink.ai:debug,flink.database:warn
+
+    # Fine-grained overrides
+    LOG_LEVELS=flink.ai:debug,flink.ai.openai:trace
+
+    # Wildcard patterns (advanced)
+    LOG_LEVELS=flink.ai.*:debug,flink.database.**:warn
+    ```
+
+    Programmatic API:
+
+    ```typescript
+    // Hierarchical prefix (Java-style)
+    FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+
+    // Exact match
+    FlinkLogFactory.setComponentLevel("flink.ai.openai", "trace");
+
+    // Wildcard pattern
+    FlinkLogFactory.setWildcardLevel("flink.database.*", "warn");
+
+    // Get effective level
+    FlinkLogFactory.getEffectiveLevel("flink.ai.openai"); // "trace"
+    ```
+
+    **Breaking Changes:**
+
+    -   None - fully backward compatible with existing exact match configurations
+
+    **Migration:**
+    Existing logger names can be migrated to dot notation for hierarchical matching:
+
+    ```typescript
+    // Before: FlinkLogFactory.createLogger("OpenAI")
+    // After: FlinkLogFactory.createLogger("flink.ai.openai")
+    ```
+
+-   ### `flink dev` - Fast development mode with SWC
+
+    -   Add `flink dev` command with fast watch mode using SWC for near-instant recompilation
+    -   Migrate compilation from `ts.emit()` to SWC for ~20x faster builds
+    -   Add background `tsc --watch` for async type checking during dev mode
+    -   Add build timing logs for performance visibility
+
+    ### Logging configuration via `flink.config.js`
+
+    -   Add support for `flink.config.js` configuration file for logging setup
+    -   Refactor `FlinkLogFactory` for simpler log export and configuration
+
+    ### Plugin handler JSON schema support
+
+    -   Add direct JSON schema support for plugin handlers via `inputJsonSchema`/`outputJsonSchema`
+    -   Allows plugins (generic-auth, management-api) to define handler schemas without TypeScript type extraction
+
+    ### CLI improvements
+
+    -   Fix tsc binary resolution by walking up directory tree (monorepo support)
+    -   Put tsc watch buildinfo in `.flink/` instead of project root
+    -   Extract shared CLI utilities and deduplicate compiler pipeline
+
+    ### Compiler fixes
+
+    -   Fix void/any type handling in schema extraction
+    -   Use project source files for SWC emit instead of disk globs
+    -   Move `__file` metadata to registration objects instead of source files
+
+    ### `create-flink-app` updates
+
+    -   Modernize default template with `flink dev` and `flink.config.js` logging config
+
+### Patch Changes
+
+-   4ad44c0: fix: preserve assistant messages in conversation history
+
+    Fixed critical bugs where assistant messages were being filtered out:
+
+    **Core Framework Fix:**
+
+    -   `AgentRunner.convertMessages()` now properly converts `toolCalls` array to `LLMContentBlock[]` format
+    -   Assistant messages with tool calls are preserved with correct content block structure
+
+    **OpenAI Adapter Fix:**
+
+    -   Removed incorrect code that was skipping assistant text messages
+    -   OpenAI Responses API DOES support `{ role: "assistant", content: "..." }` in input
+    -   Full conversation history now works correctly (both with and without `previousResponseId`)
+
+    **Result:**
+
+    -   ✅ Multi-turn conversations work with full history (client-side)
+    -   ✅ Multi-turn conversations work with `previousResponseId` (server-side, optimal)
+    -   ✅ No more consecutive user messages violating API requirements
+    -   ✅ Assistant messages preserved in all scenarios
+
+-   4ad44c0: fix: enable JSDoc descriptions in generated JSON schemas
+
+    **Changed `jsDoc` mode from "basic" to "extended"** in TypeScript schema generator to properly extract JSDoc comments from source files.
+
+    **What works now:**
+
+    -   ✅ JSDoc comments are now included as `description` fields in generated JSON schemas
+    -   ✅ Works for schemas using direct type references: `GetHandler<Ctx, Car>`
+    -   ✅ Works for schemas using `extends`: `interface Foo extends Car {}`
+
+    **Example:**
+
+    ```typescript
+    // Schema with JSDoc
+    interface Car {
+      /**
+       * Vehicle model name
+       */
+      model: string;
+    }
+
+    // Generated JSON Schema now includes:
+    {
+      "properties": {
+        "model": {
+          "type": "string",
+          "description": "Vehicle model name"  // ✅ Description preserved!
+        }
+      }
+    }
+    ```
+
+    **Limitations:**
+
+    -   ❌ Doesn't work for utility types like `Partial<Car>`, `Omit<Car, "id">` where inline properties are generated
+    -   For these cases, define explicit intermediate interfaces with JSDoc instead
+
+    **Migration:** No action required - existing schemas without JSDoc continue to work. Add JSDoc block comments to schema properties to get descriptions in generated JSON schemas.
+
+## 2.0.0-alpha.57
+
+### Minor Changes
+
+-   feat: add content-hash-based schema caching for 70% faster builds
+
+    Implements intelligent schema caching to dramatically improve build performance when schemas and their dependencies haven't changed. This provides **70% faster schema generation** on subsequent builds with accurate, content-based cache invalidation.
+
+    **Performance Impact:**
+
+    -   First build: Baseline (generates all schemas)
+    -   Subsequent builds: 70% faster schema generation when schemas unchanged
+    -   Partial changes: Only regenerates affected schemas and their dependents
+
+    **How It Works:**
+
+    -   Computes SHA-256 content hashes of schema files and all dependencies
+    -   Cache stored in `.flink/schema-cache.json` (automatically gitignored)
+    -   Tracks handler/tool source files and their transitive dependencies
+    -   Cache invalidates when:
+        -   Schema file content changes
+        -   Any dependency content changes (imports, types, etc.)
+        -   Dependency set changes (imports added/removed)
+        -   TypeScript version changes (major/minor)
+
+    **Example Build Output:**
+
+    ```bash
+    # First build (cache miss)
+    ✓ Schema generation completed in 510ms (28 handlers, 4 tools)
+      [Cache: 0 hits, 28 misses, 0 invalidated]
+
+    # Second build (cache hit)
+    ✓ Schema generation completed in 153ms (28 handlers, 4 tools)
+      [Cache: 28 hits, 0 misses, 0 invalidated]
+
+    # After modifying Car.ts
+    ✓ Schema generation completed in 250ms (28 handlers, 4 tools)
+      [Cache: 5 hits, 0 misses, 23 invalidated]
+    ```
+
+    **Benefits:**
+
+    -   Zero configuration - automatic and transparent
+    -   Git-friendly - content-based hashing works correctly with git operations
+    -   Accurate invalidation - only regenerates when actual content changes
+    -   Smart dependency tracking - tracks all imported types and their dependencies
+
+    **Migration:** No action needed - caching is automatic. The cache file is gitignored and can be safely deleted if needed.
+
+## 2.0.0-alpha.56
+
+### Patch Changes
+
+-   Zod 3.x compat
+-   0203256: fix: add Zod 3.x compatibility for tool schema generation
+
+    Tools now work with both Zod 3.25+ and Zod 4.x. The `ToolExecutor` will use:
+
+    -   Zod 4's built-in `z.toJSONSchema()` if available
+    -   `zod-to-json-schema` package for Zod 3.x compatibility (fallback)
+
+    This allows apps to use their preferred Zod version without upgrading to 4.x.
+
+    **Changes:**
+
+    -   Improved `fallbackSchema()` to use `zod-to-json-schema` instead of returning empty schema
+    -   Added Zod as peer dependency (>=3.25.0 <5.0.0) for version flexibility
+    -   Better error handling and logging for schema generation failures
+
+    **Migration:** No action needed - fully backward compatible.
+
+## 2.0.0-alpha.55
+
+### Minor Changes
+
+-   497b7c2: feat: add dynamic instructions via callback for FlinkAgent
+
+    Agent instructions can now be either a static string or a callback function that generates dynamic instructions based on context. This enables powerful use cases like:
+
+    -   Multi-language support (respond in user's preferred language)
+    -   Multi-tenant SaaS (tenant-specific business rules and behavior)
+    -   User tier-based behavior (VIP vs standard customers)
+    -   Context-aware responses (conversation history, time-based, metadata-driven)
+
+    **Breaking Changes:** None - fully backwards compatible with existing string instructions.
+
+    **Example:**
+
+    ```typescript
+    export default class SupportAgent extends FlinkAgent<AppCtx> {
+        description = "Customer support specialist";
+
+        instructions = async (ctx, agentContext) => {
+            const profile = await ctx.repos.userRepo.getById(agentContext.user.id);
+            return `You are a support agent. Customer: ${profile.name}, Tier: ${profile.tier}`;
+        };
+
+        tools = [];
+    }
+    ```
+
+    The callback receives:
+
+    -   `ctx`: FlinkContext with access to repos, plugins, etc.
+    -   `agentContext`: AgentExecuteContext with user, conversationId, metadata
+
+    Instructions are resolved once per execution at the start of the agentic loop, providing natural caching and optimal performance.
+
+### Patch Changes
+
+-   3267206: chore: remove deprecated declarative agent pattern and update documentation
+
+    Removed the unused `Agent?: FlinkAgentProps` property from FlinkAgentFile type. This old declarative pattern was never used - agents have always used the class-based pattern (extending FlinkAgent).
+
+    Also updated TypeScriptCompiler documentation to accurately reflect that agents are classes extending FlinkAgent, removing outdated references to "declarative props" and "(new pattern)" comments.
+
+    This cleanup simplifies the codebase and removes confusion about supported agent patterns.
+
+-   3267206: fix: prevent infinite delegation loop in circular delegation test
+
+    Fixed test bug where createStreamingMock would reuse the last mocked response indefinitely. In the circular delegation test, both agents' last response was a tool_use that delegated, causing the test to loop until maxSteps (10) was reached, generating thousands of log lines.
+
+    Added final response with no tool calls to properly terminate the delegation chain. This reduces test output from thousands of lines to expected levels while maintaining proper test coverage of recursion depth limits.
+
+## 2.0.0-alpha.53
+
+### Patch Changes
+
+-   669c806: fix: revert worker thread parallelization due to memory issues
+
+    Reverts the worker thread implementation for JSON schema generation due to critical memory exhaustion issues in large projects. Each worker was loading the entire TypeScript program (100-200MB), causing 1-2GB memory usage with multiple workers and crashing development environments.
+
+    The single-threaded schema generation remains stable and reliable for all project sizes.
+
+## 2.0.0-alpha.52
+
+### Patch Changes
+
+-   fe9f8f2: Improved compilation performance by parallelizing handler schema extraction. Projects with many handlers (90+) will see 3-10x faster build times.
+
+## 2.0.0-alpha.51
+
+## 2.0.0-alpha.50
+
+### Patch Changes
+
+-   Fix compiler incorrectly treating all files in src/tools/ as tools. The compiler now checks for FlinkToolProps export early and skips utility files, type definitions, and index files that aren't actual tools, preventing false "Missing FlinkToolProps export" errors.
+
+## 2.0.0-alpha.49
+
+### Patch Changes
+
+-   Typescript include fix
+
+## 2.0.0-alpha.48
+
+### Minor Changes
+
+-   AI features
+
+## 1.0.0
+
+### Minor Changes
+
+-   Align minor version, from now all packages in monorepo will have same version
+-   5c2ff97: Add schema validation bypass options to RouteProps
+
+    Handlers can now control schema validation behavior via the new `validation` property in `RouteProps`:
+
+    -   `ValidationMode.Validate` (default): Validate both request and response
+    -   `ValidationMode.SkipValidation`: Skip both request and response validation
+    -   `ValidationMode.ValidateRequest`: Validate only request, skip response validation
+    -   `ValidationMode.ValidateResponse`: Validate only response, skip request validation
+
+    This is useful for handlers that need custom validation logic or want to bypass validation for performance reasons. The feature is opt-in and defaults to existing behavior.
+
+    **Security Considerations:**
+
+    ⚠️ Use validation bypass options carefully:
+
+    -   `SkipValidation` and `ValidateRequest: false` allow unvalidated data to reach handlers, which can introduce security risks
+    -   Only skip validation when you have implemented custom validation logic or the endpoint is internal/trusted
+    -   Suitable use cases include: webhook handlers with custom signature verification, performance-critical internal endpoints, or handlers using alternative validation methods
+    -   When skipping response validation, ensure your code returns consistent data shapes to avoid breaking API contracts
+
+    Example usage:
+
+    ```typescript
+    // Skip validation for webhook with custom verification
+    export const Route: RouteProps = {
+        path: "/webhook",
+        validation: ValidationMode.SkipValidation,
+    };
+
+    // Validate request but allow flexible response during development
+    export const Route: RouteProps = {
+        path: "/api/debug",
+        validation: ValidationMode.ValidateRequest,
+    };
+    ```
+
+### Patch Changes
+
+-   ee21c29: Normalize query parameters to predictable string types
+
+    Query parameters are now automatically normalized to `string | string[]` types before reaching handlers:
+
+    -   Single values: converted to strings (e.g., `?page=1` → `{ page: "1" }`)
+    -   Repeated parameters: converted to string arrays (e.g., `?tag=a&tag=b` → `{ tag: ["a", "b"] }`)
+    -   All types (numbers, booleans, etc.) from Express parser are converted to strings
+
+    **Breaking Change (Minor):**
+
+    -   `Query` type changed from `{ [x: string]: string | string[] | undefined }` to `Record<string, string | string[]>`
+    -   `Params` type changed from `Request["params"]` to explicit `Record<string, string>`
+    -   Removed `undefined` from query/param types since normalization ensures values are never undefined
+    -   Updated OAuth and OIDC plugin query type definitions to satisfy new Query constraint
+
+    This ensures predictable query and path parameter handling regardless of Express parser configuration. Handlers can reliably parse string values as needed using `Number()`, `parseInt()`, boolean comparisons, etc.
+
 ## 0.14.3
 
 ### Patch Changes