@flink-app/flink 2.0.0-alpha.66 → 2.0.0-alpha.68

package/CHANGELOG.md

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

package/cli/dev.ts

@@ -91,9 +91,9 @@ module.exports = async function dev(args: string[]) {
         try {
             await compile({ dir, entry, typeCheck: typecheck });
 
-            // Restart server
+            // Restart server — wait for old process to fully exit before binding port again
             if (serverProcess) {
-                serverProcess.kill();
+                await killAndWait(serverProcess);
                 serverProcess = null;
             }
             serverProcess = startServer(dir);
@@ -135,6 +135,23 @@ module.exports = async function dev(args: string[]) {
     });
 };
 
+function killAndWait(proc: ChildProcess): Promise<void> {
+    return new Promise((resolve) => {
+        if (proc.exitCode !== null) {
+            // Already exited
+            resolve();
+            return;
+        }
+        proc.once("exit", () => resolve());
+        proc.kill();
+        // Safety timeout: if the process doesn't exit within 5s, force-kill it
+        const timeout = setTimeout(() => {
+            proc.kill("SIGKILL");
+        }, 5000);
+        proc.once("exit", () => clearTimeout(timeout));
+    });
+}
+
 function startServer(dir: string): ChildProcess {
     console.log("🚀 Starting server...");
 

package/dist/cli/dev.js

@@ -123,24 +123,26 @@ module.exports = function dev(args) {
                                     rebuildStart = Date.now();
                                     _a.label = 1;
                                 case 1:
-                                    _a.trys.push([1, 3, , 4]);
+                                    _a.trys.push([1, 5, , 6]);
                                     return [4 /*yield*/, (0, cli_utils_1.compile)({ dir: dir, entry: entry, typeCheck: typecheck })];
                                 case 2:
                                     _a.sent();
-                                    // Restart server
-                                    if (serverProcess) {
-                                        serverProcess.kill();
-                                        serverProcess = null;
-                                    }
+                                    if (!serverProcess) return [3 /*break*/, 4];
+                                    return [4 /*yield*/, killAndWait(serverProcess)];
+                                case 3:
+                                    _a.sent();
+                                    serverProcess = null;
+                                    _a.label = 4;
+                                case 4:
                                     serverProcess = startServer(dir);
                                     rebuildTime = Date.now() - rebuildStart;
                                     logger.info("\u2705 Rebuild complete in ".concat(rebuildTime, "ms\n"));
-                                    return [3 /*break*/, 4];
-                                case 3:
+                                    return [3 /*break*/, 6];
+                                case 5:
                                     error_1 = _a.sent();
                                     logger.error("\u274C Rebuild failed: ".concat(error_1.message));
-                                    return [3 /*break*/, 4];
-                                case 4:
+                                    return [3 /*break*/, 6];
+                                case 6:
                                     isRebuilding = false;
                                     // If another change happened during rebuild, trigger again
                                     if (pendingRebuild) {
@@ -175,6 +177,22 @@ module.exports = function dev(args) {
         });
     });
 };
+function killAndWait(proc) {
+    return new Promise(function (resolve) {
+        if (proc.exitCode !== null) {
+            // Already exited
+            resolve();
+            return;
+        }
+        proc.once("exit", function () { return resolve(); });
+        proc.kill();
+        // Safety timeout: if the process doesn't exit within 5s, force-kill it
+        var timeout = setTimeout(function () {
+            proc.kill("SIGKILL");
+        }, 5000);
+        proc.once("exit", function () { return clearTimeout(timeout); });
+    });
+}
 function startServer(dir) {
     console.log("🚀 Starting server...");
     var fork = require("child_process").fork;

package/dist/src/ai/AgentRunner.js

@@ -196,18 +196,15 @@ var AgentRunner = /** @class */ (function () {
                         messages = compactedMessages;
                         // Log compaction for debugging
                         FlinkLog_1.log.debug("[Agent:".concat(this.agentName, "] Step ").concat(step, ": Compacted ").concat(beforeCount, " messages \u2192 ").concat(messages.length));
-                        // Debug logging: Show compacted messages if debug enabled
-                        if (this.agentProps.debug) {
-                            FlinkLog_1.log.debug("[Agent:".concat(this.agentName, "] Compacted messages:"), {
-                                messageCount: messages.length,
-                                messages: messages.map(function (m) { return ({
-                                    role: m.role,
-                                    contentPreview: typeof m.content === "string"
-                                        ? m.content.substring(0, 100) + (m.content.length > 100 ? "..." : "")
-                                        : "".concat(m.content.length, " blocks"),
-                                }); }),
-                            });
-                        }
+                        FlinkLog_1.log.debug("[Agent:".concat(this.agentName, "] Compacted messages:"), {
+                            messageCount: messages.length,
+                            messages: messages.map(function (m) { return ({
+                                role: m.role,
+                                contentPreview: typeof m.content === "string"
+                                    ? m.content.substring(0, 100) + (m.content.length > 100 ? "..." : "")
+                                    : "".concat(m.content.length, " blocks"),
+                            }); }),
+                        });
                         _o.label = 14;
                     case 14: return [3 /*break*/, 16];
                     case 15:
@@ -216,24 +213,20 @@ var AgentRunner = /** @class */ (function () {
                         FlinkLog_1.log.error("[Agent:".concat(this.agentName, "] Context compaction failed:"), error_1.message);
                         return [3 /*break*/, 16];
                     case 16:
-                        // Debug logging: Show what we're sending to the LLM
-                        if (this.agentProps.debug) {
-                            FlinkLog_1.log.debug("[Agent:".concat(this.agentName, "] Step ").concat(step, "/").concat(maxSteps, " - Calling LLM with:"), {
-                                instructions: resolvedInstructions,
-                                instructionsType: typeof this.agentProps.instructions === "function" ? "dynamic-callback" : "static",
-                                messageCount: messages.length,
-                                messages: messages.map(function (m) { return ({
-                                    role: m.role,
-                                    contentPreview: typeof m.content === "string"
-                                        ? m.content.substring(0, 100) + (m.content.length > 100 ? "..." : "")
-                                        : "".concat(m.content.length, " blocks"),
-                                }); }),
-                                toolCount: availableTools.length,
-                                tools: availableTools.map(function (t) { return t.name; }),
-                                maxTokens: this.maxTokens,
-                                temperature: this.temperature,
-                            });
-                        }
+                        FlinkLog_1.log.debug("[Agent:".concat(this.agentName, "] Step ").concat(step, "/").concat(maxSteps, " - Calling LLM with:"), {
+                            instructionsType: typeof this.agentProps.instructions === "function" ? "dynamic-callback" : "static",
+                            messageCount: messages.length,
+                            messages: messages.map(function (m) { return ({
+                                role: m.role,
+                                contentPreview: typeof m.content === "string"
+                                    ? m.content.substring(0, 100) + (m.content.length > 100 ? "..." : "")
+                                    : "".concat(m.content.length, " blocks"),
+                            }); }),
+                            toolCount: availableTools.length,
+                            tools: availableTools.map(function (t) { return t.name; }),
+                            maxTokens: this.maxTokens,
+                            temperature: this.temperature,
+                        });
                         llmStream = this.llmAdapter.stream({
                             instructions: resolvedInstructions,
                             messages: messages,
@@ -322,21 +315,18 @@ var AgentRunner = /** @class */ (function () {
                             usage: usage,
                             stopReason: stopReason,
                         };
-                        // Debug logging: Show what the LLM responded with
-                        if (this.agentProps.debug) {
-                            FlinkLog_1.log.debug("[Agent:".concat(this.agentName, "] Step ").concat(step, " - LLM Response:"), {
-                                textLength: ((_l = llmResponse.textContent) === null || _l === void 0 ? void 0 : _l.length) || 0,
-                                textPreview: ((_m = llmResponse.textContent) === null || _m === void 0 ? void 0 : _m.substring(0, 200)) + (llmResponse.textContent && llmResponse.textContent.length > 200 ? "..." : ""),
-                                toolCallsCount: llmResponse.toolCalls.length,
-                                toolCalls: llmResponse.toolCalls.map(function (tc) { return ({
-                                    name: tc.name,
-                                    inputKeys: Object.keys(tc.input),
-                                    input: tc.input,
-                                }); }),
-                                stopReason: llmResponse.stopReason,
-                                usage: llmResponse.usage,
-                            });
-                        }
+                        FlinkLog_1.log.debug("[Agent:".concat(this.agentName, "] Step ").concat(step, " - LLM Response:"), {
+                            textLength: ((_l = llmResponse.textContent) === null || _l === void 0 ? void 0 : _l.length) || 0,
+                            textPreview: ((_m = llmResponse.textContent) === null || _m === void 0 ? void 0 : _m.substring(0, 200)) + (llmResponse.textContent && llmResponse.textContent.length > 200 ? "..." : ""),
+                            toolCallsCount: llmResponse.toolCalls.length,
+                            toolCalls: llmResponse.toolCalls.map(function (tc) { return ({
+                                name: tc.name,
+                                inputKeys: Object.keys(tc.input),
+                                input: tc.input,
+                            }); }),
+                            stopReason: llmResponse.stopReason,
+                            usage: llmResponse.usage,
+                        });
                         // Extract text response
                         if (llmResponse.textContent) {
                             finalMessage = llmResponse.textContent;
@@ -379,13 +369,10 @@ var AgentRunner = /** @class */ (function () {
                         toolExecutor = this.tools.get(toolCall.name);
                         toolOutput = void 0;
                         toolError = void 0;
-                        // Debug logging: Tool execution start
-                        if (this.agentProps.debug) {
-                            FlinkLog_1.log.debug("[Agent:".concat(this.agentName, "] Executing tool '").concat(toolCall.name, "':"), {
-                                input: toolCall.input,
-                                inputSize: JSON.stringify(toolCall.input).length,
-                            });
-                        }
+                        FlinkLog_1.log.debug("[Agent:".concat(this.agentName, "] Executing tool '").concat(toolCall.name, "':"), {
+                            input: toolCall.input,
+                            inputSize: JSON.stringify(toolCall.input).length,
+                        });
                         _o.label = 40;
                     case 40:
                         _o.trys.push([40, 46, , 49]);
@@ -442,17 +429,14 @@ var AgentRunner = /** @class */ (function () {
                             output: toolResult.success ? toolResult.data : null,
                             error: toolResult.success ? undefined : toolResult.error,
                         });
-                        // Debug logging: Tool execution result
-                        if (this.agentProps.debug) {
-                            FlinkLog_1.log.debug("[Agent:".concat(this.agentName, "] Tool '").concat(toolCall.name, "' ").concat(toolResult.success ? "succeeded" : "failed", ":"), {
-                                success: toolResult.success,
-                                outputSize: toolResult.success ? JSON.stringify(toolResult.data).length : 0,
-                                outputPreview: toolResult.success
-                                    ? JSON.stringify(toolResult.data).substring(0, 200) + (JSON.stringify(toolResult.data).length > 200 ? "..." : "")
-                                    : toolResult.error,
-                                code: toolResult.code,
-                            });
-                        }
+                        FlinkLog_1.log.debug("[Agent:".concat(this.agentName, "] Tool '").concat(toolCall.name, "' ").concat(toolResult.success ? "succeeded" : "failed", ":"), {
+                            success: toolResult.success,
+                            outputSize: toolResult.success ? JSON.stringify(toolResult.data).length : 0,
+                            outputPreview: toolResult.success
+                                ? JSON.stringify(toolResult.data).substring(0, 200) + (JSON.stringify(toolResult.data).length > 200 ? "..." : "")
+                                : toolResult.error,
+                            code: toolResult.code,
+                        });
                         if (!toolResult.success) {
                             FlinkLog_1.log.warn("Tool ".concat(toolCall.name, " returned error:"), toolResult.error);
                         }

package/dist/src/ai/FlinkAgent.d.ts

@@ -116,17 +116,6 @@ export interface FlinkAgentProps<Ctx extends FlinkContext> {
         timeoutMs?: number;
     };
     permissions?: string | string[] | ((user?: any) => boolean);
-    /**
-     * Enable verbose debug logging for this agent
-     * When true, logs detailed information about:
-     * - Full LLM requests (messages, tools, parameters)
-     * - Full LLM responses (text, tool calls)
-     * - Tool execution details (input, output, errors)
-     * - Conversation state changes
-     *
-     * Useful for debugging tool calling issues and understanding agent behavior
-     */
-    debug?: boolean;
     /**
      * Callback to determine if history compaction is needed
      * Called before each LLM call in the agentic loop
@@ -297,7 +286,6 @@ export declare abstract class FlinkAgent<Ctx extends FlinkContext, ConversationC
         timeoutMs?: number;
     };
     permissions?: string | string[] | ((user?: any) => boolean);
-    debug?: boolean;
     protected shouldCompact?: ShouldCompactCallback;
     protected compactHistory?: CompactHistoryCallback;
     /**

package/dist/src/ai/FlinkAgent.js

@@ -647,7 +647,6 @@ var FlinkAgent = /** @class */ (function () {
             model: this.model,
             limits: this.limits,
             permissions: this.permissions,
-            debug: this.debug,
             // Pass context compaction callbacks
             shouldCompact: (_a = this.shouldCompact) === null || _a === void 0 ? void 0 : _a.bind(this),
             compactHistory: (_b = this.compactHistory) === null || _b === void 0 ? void 0 : _b.bind(this),

package/dist/src/ai/instructionFileLoader.js

@@ -78,6 +78,28 @@ var fs = __importStar(require("fs"));
 var path = __importStar(require("path"));
 var handlebars_1 = __importDefault(require("handlebars"));
 var fileCache = new Map();
+var IMPORT_REGEX = /\{\{\s*import\s+["']([^"']+)['"]\s*\}\}/g;
+function resolveImports(content, currentDir, visited) {
+    if (visited === void 0) { visited = new Set(); }
+    return content.replace(IMPORT_REGEX, function (match, importPath) {
+        var resolved = path.resolve(currentDir, importPath);
+        if (visited.has(resolved)) {
+            throw new Error("Circular import detected: ".concat(resolved));
+        }
+        var nextVisited = new Set(visited);
+        nextVisited.add(resolved);
+        try {
+            var importedContent = fs.readFileSync(resolved, "utf-8");
+            return resolveImports(importedContent, path.dirname(resolved), nextVisited);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new Error("Imported markdown file not found: ".concat(resolved, " (imported from: ").concat(currentDir, ")"));
+            }
+            throw err;
+        }
+    });
+}
 /**
  * Resolve a file path relative to project root (process.cwd()).
  * Leading `./` and `/` are normalised away — all paths are treated as project-root-relative.
@@ -97,7 +119,8 @@ function loadFile(filePath) {
             return cached;
         }
         var content = fs.readFileSync(resolvedPath, "utf-8");
-        var entry = { content: content, mtime: mtime };
+        var resolvedContent = resolveImports(content, path.dirname(resolvedPath));
+        var entry = { content: content, resolvedContent: resolvedContent, mtime: mtime };
         fileCache.set(resolvedPath, entry);
         return entry;
     }
@@ -110,14 +133,14 @@ function loadFile(filePath) {
 }
 function renderTemplate(entry, data) {
     if (entry.hasTemplateExpressions === false) {
-        return entry.content;
+        return entry.resolvedContent;
     }
     if (!entry.compiledTemplate) {
-        entry.hasTemplateExpressions = /\{\{/.test(entry.content);
+        entry.hasTemplateExpressions = /\{\{/.test(entry.resolvedContent);
         if (!entry.hasTemplateExpressions) {
-            return entry.content;
+            return entry.resolvedContent;
         }
-        entry.compiledTemplate = handlebars_1.default.compile(entry.content);
+        entry.compiledTemplate = handlebars_1.default.compile(entry.resolvedContent);
     }
     return entry.compiledTemplate(data);
 }

package/dist/src/schema-extraction/TypeScriptSourceParser.js

@@ -205,6 +205,11 @@ var TypeScriptSourceParser = /** @class */ (function () {
         if (primitives.includes(typeName.toLowerCase())) {
             return false;
         }
+        // Skip binary/non-serializable built-in types that can never have JSON schemas
+        var nonSerializableTypes = ['Buffer', 'ArrayBuffer', 'SharedArrayBuffer', 'Blob', 'ReadableStream', 'WritableStream', 'DataView', 'Uint8Array'];
+        if (nonSerializableTypes.includes(typeName)) {
+            return false;
+        }
         // Must be a named type (starts with uppercase letter)
         return /^[A-Z]/.test(typeName);
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "2.0.0-alpha.66",
+  "version": "2.0.0-alpha.68",
   "description": "Typescript only framework for creating REST-like APIs on top of Express and mongodb",
   "types": "dist/src/index.d.ts",
   "main": "dist/src/index.js",

package/src/ai/AgentRunner.ts

@@ -127,19 +127,16 @@ export class AgentRunner {
                         // Log compaction for debugging
                         log.debug(`[Agent:${this.agentName}] Step ${step}: Compacted ${beforeCount} messages → ${messages.length}`);
 
-                        // Debug logging: Show compacted messages if debug enabled
-                        if (this.agentProps.debug) {
-                            log.debug(`[Agent:${this.agentName}] Compacted messages:`, {
-                                messageCount: messages.length,
-                                messages: messages.map((m) => ({
-                                    role: m.role,
-                                    contentPreview:
-                                        typeof m.content === "string"
-                                            ? m.content.substring(0, 100) + (m.content.length > 100 ? "..." : "")
-                                            : `${(m.content as any[]).length} blocks`,
-                                })),
-                            });
-                        }
+                        log.debug(`[Agent:${this.agentName}] Compacted messages:`, {
+                            messageCount: messages.length,
+                            messages: messages.map((m) => ({
+                                role: m.role,
+                                contentPreview:
+                                    typeof m.content === "string"
+                                        ? m.content.substring(0, 100) + (m.content.length > 100 ? "..." : "")
+                                        : `${(m.content as any[]).length} blocks`,
+                            })),
+                        });
                     }
                 } catch (error: any) {
                     // Log error but don't fail execution - compaction is optional optimization
@@ -147,25 +144,21 @@ export class AgentRunner {
                 }
             }
 
-            // Debug logging: Show what we're sending to the LLM
-            if (this.agentProps.debug) {
-                log.debug(`[Agent:${this.agentName}] Step ${step}/${maxSteps} - Calling LLM with:`, {
-                    instructions: resolvedInstructions,
-                    instructionsType: typeof this.agentProps.instructions === "function" ? "dynamic-callback" : "static",
-                    messageCount: messages.length,
-                    messages: messages.map((m) => ({
-                        role: m.role,
-                        contentPreview:
-                            typeof m.content === "string"
-                                ? m.content.substring(0, 100) + (m.content.length > 100 ? "..." : "")
-                                : `${(m.content as any[]).length} blocks`,
-                    })),
-                    toolCount: availableTools.length,
-                    tools: availableTools.map((t) => t.name),
-                    maxTokens: this.maxTokens,
-                    temperature: this.temperature,
-                });
-            }
+            log.debug(`[Agent:${this.agentName}] Step ${step}/${maxSteps} - Calling LLM with:`, {
+                instructionsType: typeof this.agentProps.instructions === "function" ? "dynamic-callback" : "static",
+                messageCount: messages.length,
+                messages: messages.map((m) => ({
+                    role: m.role,
+                    contentPreview:
+                        typeof m.content === "string"
+                            ? m.content.substring(0, 100) + (m.content.length > 100 ? "..." : "")
+                            : `${(m.content as any[]).length} blocks`,
+                })),
+                toolCount: availableTools.length,
+                tools: availableTools.map((t) => t.name),
+                maxTokens: this.maxTokens,
+                temperature: this.temperature,
+            });
 
             // Call AI model via adapter using streaming
             const llmStream = this.llmAdapter.stream({
@@ -225,21 +218,18 @@ export class AgentRunner {
                 stopReason,
             };
 
-            // Debug logging: Show what the LLM responded with
-            if (this.agentProps.debug) {
-                log.debug(`[Agent:${this.agentName}] Step ${step} - LLM Response:`, {
-                    textLength: llmResponse.textContent?.length || 0,
-                    textPreview: llmResponse.textContent?.substring(0, 200) + (llmResponse.textContent && llmResponse.textContent.length > 200 ? "..." : ""),
-                    toolCallsCount: llmResponse.toolCalls.length,
-                    toolCalls: llmResponse.toolCalls.map((tc) => ({
-                        name: tc.name,
-                        inputKeys: Object.keys(tc.input),
-                        input: tc.input,
-                    })),
-                    stopReason: llmResponse.stopReason,
-                    usage: llmResponse.usage,
-                });
-            }
+            log.debug(`[Agent:${this.agentName}] Step ${step} - LLM Response:`, {
+                textLength: llmResponse.textContent?.length || 0,
+                textPreview: llmResponse.textContent?.substring(0, 200) + (llmResponse.textContent && llmResponse.textContent.length > 200 ? "..." : ""),
+                toolCallsCount: llmResponse.toolCalls.length,
+                toolCalls: llmResponse.toolCalls.map((tc) => ({
+                    name: tc.name,
+                    inputKeys: Object.keys(tc.input),
+                    input: tc.input,
+                })),
+                stopReason: llmResponse.stopReason,
+                usage: llmResponse.usage,
+            });
 
             // Extract text response
             if (llmResponse.textContent) {
@@ -293,13 +283,10 @@ export class AgentRunner {
                 let toolOutput: any;
                 let toolError: string | undefined;
 
-                // Debug logging: Tool execution start
-                if (this.agentProps.debug) {
-                    log.debug(`[Agent:${this.agentName}] Executing tool '${toolCall.name}':`, {
-                        input: toolCall.input,
-                        inputSize: JSON.stringify(toolCall.input).length,
-                    });
-                }
+                log.debug(`[Agent:${this.agentName}] Executing tool '${toolCall.name}':`, {
+                    input: toolCall.input,
+                    inputSize: JSON.stringify(toolCall.input).length,
+                });
 
                 try {
                     if (!toolExecutor) {
@@ -352,17 +339,14 @@ export class AgentRunner {
                         error: toolResult.success ? undefined : toolResult.error,
                     });
 
-                    // Debug logging: Tool execution result
-                    if (this.agentProps.debug) {
-                        log.debug(`[Agent:${this.agentName}] Tool '${toolCall.name}' ${toolResult.success ? "succeeded" : "failed"}:`, {
-                            success: toolResult.success,
-                            outputSize: toolResult.success ? JSON.stringify(toolResult.data).length : 0,
-                            outputPreview: toolResult.success
-                                ? JSON.stringify(toolResult.data).substring(0, 200) + (JSON.stringify(toolResult.data).length > 200 ? "..." : "")
-                                : toolResult.error,
-                            code: (toolResult as any).code,
-                        });
-                    }
+                    log.debug(`[Agent:${this.agentName}] Tool '${toolCall.name}' ${toolResult.success ? "succeeded" : "failed"}:`, {
+                        success: toolResult.success,
+                        outputSize: toolResult.success ? JSON.stringify(toolResult.data).length : 0,
+                        outputPreview: toolResult.success
+                            ? JSON.stringify(toolResult.data).substring(0, 200) + (JSON.stringify(toolResult.data).length > 200 ? "..." : "")
+                            : toolResult.error,
+                        code: (toolResult as any).code,
+                    });
 
                     if (!toolResult.success) {
                         log.warn(`Tool ${toolCall.name} returned error:`, toolResult.error);

package/src/ai/FlinkAgent.ts

@@ -130,17 +130,6 @@ export interface FlinkAgentProps<Ctx extends FlinkContext> {
         timeoutMs?: number; // Phase 2: Not yet implemented
     };
     permissions?: string | string[] | ((user?: any) => boolean);
-    /**
-     * Enable verbose debug logging for this agent
-     * When true, logs detailed information about:
-     * - Full LLM requests (messages, tools, parameters)
-     * - Full LLM responses (text, tool calls)
-     * - Tool execution details (input, output, errors)
-     * - Conversation state changes
-     *
-     * Useful for debugging tool calling issues and understanding agent behavior
-     */
-    debug?: boolean;
 
     /**
      * Callback to determine if history compaction is needed
@@ -319,7 +308,6 @@ export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any
     };
     limits?: { maxSteps?: number; timeoutMs?: number };
     permissions?: string | string[] | ((user?: any) => boolean);
-    debug?: boolean; // Enable verbose debug logging
     protected shouldCompact?: ShouldCompactCallback;
     protected compactHistory?: CompactHistoryCallback;
 
@@ -755,7 +743,6 @@ export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any
             model: this.model,
             limits: this.limits,
             permissions: this.permissions,
-            debug: this.debug,
             // Pass context compaction callbacks
             shouldCompact: this.shouldCompact?.bind(this),
             compactHistory: this.compactHistory?.bind(this),

package/src/ai/instructionFileLoader.ts

@@ -41,6 +41,7 @@ export type InstructionsReturn = string | { file: string; params?: Record<string
 
 interface FileCacheEntry {
     content: string;
+    resolvedContent: string;
     mtime: number;
     compiledTemplate?: Handlebars.TemplateDelegate;
     hasTemplateExpressions?: boolean;
@@ -48,6 +49,28 @@ interface FileCacheEntry {
 
 const fileCache = new Map<string, FileCacheEntry>();
 
+const IMPORT_REGEX = /\{\{\s*import\s+["']([^"']+)['"]\s*\}\}/g;
+
+function resolveImports(content: string, currentDir: string, visited: Set<string> = new Set()): string {
+    return content.replace(IMPORT_REGEX, (match, importPath) => {
+        const resolved = path.resolve(currentDir, importPath);
+        if (visited.has(resolved)) {
+            throw new Error(`Circular import detected: ${resolved}`);
+        }
+        const nextVisited = new Set(visited);
+        nextVisited.add(resolved);
+        try {
+            const importedContent = fs.readFileSync(resolved, "utf-8");
+            return resolveImports(importedContent, path.dirname(resolved), nextVisited);
+        } catch (err: any) {
+            if (err.code === "ENOENT") {
+                throw new Error(`Imported markdown file not found: ${resolved} (imported from: ${currentDir})`);
+            }
+            throw err;
+        }
+    });
+}
+
 /**
  * Resolve a file path relative to project root (process.cwd()).
  * Leading `./` and `/` are normalised away — all paths are treated as project-root-relative.
@@ -70,7 +93,8 @@ function loadFile(filePath: string): FileCacheEntry {
         }
 
         const content = fs.readFileSync(resolvedPath, "utf-8");
-        const entry: FileCacheEntry = { content, mtime };
+        const resolvedContent = resolveImports(content, path.dirname(resolvedPath));
+        const entry: FileCacheEntry = { content, resolvedContent, mtime };
         fileCache.set(resolvedPath, entry);
         return entry;
     } catch (err: any) {
@@ -83,15 +107,15 @@ function loadFile(filePath: string): FileCacheEntry {
 
 function renderTemplate(entry: FileCacheEntry, data: any): string {
     if (entry.hasTemplateExpressions === false) {
-        return entry.content;
+        return entry.resolvedContent;
     }
 
     if (!entry.compiledTemplate) {
-        entry.hasTemplateExpressions = /\{\{/.test(entry.content);
+        entry.hasTemplateExpressions = /\{\{/.test(entry.resolvedContent);
         if (!entry.hasTemplateExpressions) {
-            return entry.content;
+            return entry.resolvedContent;
         }
-        entry.compiledTemplate = Handlebars.compile(entry.content);
+        entry.compiledTemplate = Handlebars.compile(entry.resolvedContent);
     }
 
     return entry.compiledTemplate(data);

package/src/schema-extraction/TypeScriptSourceParser.ts

@@ -221,6 +221,12 @@ export class TypeScriptSourceParser {
             return false;
         }
 
+        // Skip binary/non-serializable built-in types that can never have JSON schemas
+        const nonSerializableTypes = ['Buffer', 'ArrayBuffer', 'SharedArrayBuffer', 'Blob', 'ReadableStream', 'WritableStream', 'DataView', 'Uint8Array'];
+        if (nonSerializableTypes.includes(typeName)) {
+            return false;
+        }
+
         // Must be a named type (starts with uppercase letter)
         return /^[A-Z]/.test(typeName);
     }