@flink-app/flink 2.0.0-alpha.56 → 2.0.0-alpha.58

package/CHANGELOG.md

@@ -1,5 +1,573 @@
 # @flink-app/flink
 
+## 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