@flink-app/flink 2.0.0-alpha.65 → 2.0.0-alpha.67

package/CHANGELOG.md

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

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/ToolExecutor.d.ts

@@ -6,6 +6,7 @@ export declare class ToolExecutor<Ctx extends FlinkContext> {
     private toolFn;
     private ctx;
     private autoSchemas?;
+    private allSchemas?;
     private ajv;
     private compiledInputValidator?;
     private compiledOutputValidator?;
@@ -14,7 +15,7 @@ export declare class ToolExecutor<Ctx extends FlinkContext> {
         outputSchema?: any;
         inputTypeHint?: "void" | "any" | "named";
         outputTypeHint?: "void" | "any" | "named";
-    } | undefined, allSchemas?: Record<string, any>);
+    } | undefined, allSchemas?: Record<string, any> | undefined);
     /**
      * Execute the tool with input
      * @param input - Tool input data
@@ -26,6 +27,15 @@ export declare class ToolExecutor<Ctx extends FlinkContext> {
         conversationContext?: any;
     }): Promise<ToolResult<any>>;
     getToolSchema(): FlinkToolSchema;
+    /**
+     * Resolve cross-schema $ref values into $defs so the schema is self-contained.
+     *
+     * Flink's schema manifest stores schemas as separate documents with IDs like
+     * "Canvas.ElementInput". These are valid for AJV (which uses a schema registry),
+     * but LLM providers like OpenAI require a single self-contained schema where all
+     * $ref values point to #/$defs/... entries at the top level.
+     */
+    private resolveSchemaRefs;
     /**
      * Get tool result for AI consumption
      * Formats ToolResult into string for AI context

package/dist/src/ai/ToolExecutor.js

@@ -51,6 +51,7 @@ var ToolExecutor = /** @class */ (function () {
         this.toolFn = toolFn;
         this.ctx = ctx;
         this.autoSchemas = autoSchemas;
+        this.allSchemas = allSchemas;
         this.ajv = new ajv_1.default({ allErrors: true });
         // Pre-populate AJV with all schemas so $ref references resolve across schema boundaries
         if (allSchemas) {
@@ -263,7 +264,7 @@ var ToolExecutor = /** @class */ (function () {
             return {
                 name: this.toolProps.id,
                 description: this.toolProps.description,
-                inputSchema: this.autoSchemas.inputSchema,
+                inputSchema: this.resolveSchemaRefs(this.autoSchemas.inputSchema),
             };
         }
         // No schema provided - return schema based on type hint
@@ -304,6 +305,68 @@ var ToolExecutor = /** @class */ (function () {
             };
         }
     };
+    /**
+     * Resolve cross-schema $ref values into $defs so the schema is self-contained.
+     *
+     * Flink's schema manifest stores schemas as separate documents with IDs like
+     * "Canvas.ElementInput". These are valid for AJV (which uses a schema registry),
+     * but LLM providers like OpenAI require a single self-contained schema where all
+     * $ref values point to #/$defs/... entries at the top level.
+     */
+    ToolExecutor.prototype.resolveSchemaRefs = function (schema) {
+        var _this = this;
+        if (!this.allSchemas)
+            return schema;
+        var defs = {};
+        var collectRefs = function (node, visited) {
+            if (!node || typeof node !== "object")
+                return;
+            if (node.$ref && typeof node.$ref === "string" && !node.$ref.startsWith("#")) {
+                var refId = node.$ref;
+                if (!visited.has(refId) && _this.allSchemas[refId]) {
+                    visited.add(refId);
+                    // Clone and strip top-level JSON Schema meta fields not valid inside $defs
+                    var def = JSON.parse(JSON.stringify(_this.allSchemas[refId]));
+                    delete def.$id;
+                    delete def.$schema;
+                    defs[refId] = def;
+                    // Recurse into the referenced schema to collect its deps
+                    collectRefs(def, visited);
+                }
+            }
+            for (var _i = 0, _a = Object.values(node); _i < _a.length; _i++) {
+                var value = _a[_i];
+                collectRefs(value, visited);
+            }
+        };
+        var visited = new Set();
+        collectRefs(schema, visited);
+        if (Object.keys(defs).length === 0)
+            return schema;
+        // Deep clone and rewrite all non-standard $ref values to #/$defs/<id>
+        var resolved = JSON.parse(JSON.stringify(schema));
+        delete resolved.$id;
+        delete resolved.$schema;
+        var rewriteRefs = function (node) {
+            if (!node || typeof node !== "object")
+                return;
+            if (node.$ref && typeof node.$ref === "string" && !node.$ref.startsWith("#")) {
+                node.$ref = "#/$defs/".concat(node.$ref);
+            }
+            for (var _i = 0, _a = Object.values(node); _i < _a.length; _i++) {
+                var value = _a[_i];
+                rewriteRefs(value);
+            }
+        };
+        rewriteRefs(resolved);
+        // Also rewrite refs inside the collected defs
+        for (var _i = 0, _a = Object.values(defs); _i < _a.length; _i++) {
+            var def = _a[_i];
+            rewriteRefs(def);
+        }
+        resolved.$defs = defs;
+        return resolved;
+    };
     /**
      * Get tool result for AI consumption
      * Formats ToolResult into string for AI context

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "2.0.0-alpha.65",
+  "version": "2.0.0-alpha.67",
   "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/spec/ToolExecutor.spec.ts

@@ -276,6 +276,119 @@ describe("ToolExecutor", () => {
             expect(schema.description).toBe("Get weather for a city");
             expect(schema.inputSchema).toBeDefined();
         });
+
+        describe("cross-schema $ref resolution", () => {
+            const allSchemas = {
+                "MyTool.Input": {
+                    $id: "MyTool.Input",
+                    $schema: "http://json-schema.org/draft-07/schema#",
+                    type: "object",
+                    properties: {
+                        id: { type: "string" },
+                        item: { $ref: "Shared.Item" },
+                    },
+                    required: ["id", "item"],
+                },
+                "Shared.Item": {
+                    $id: "Shared.Item",
+                    $schema: "http://json-schema.org/draft-07/schema#",
+                    type: "object",
+                    properties: {
+                        name: { type: "string" },
+                        tag: { $ref: "Shared.Tag" },
+                    },
+                    required: ["name"],
+                },
+                "Shared.Tag": {
+                    $id: "Shared.Tag",
+                    $schema: "http://json-schema.org/draft-07/schema#",
+                    type: "string",
+                    enum: ["foo", "bar"],
+                },
+            };
+
+            it("should resolve cross-schema $refs into $defs", () => {
+                const toolProps: FlinkToolProps = { id: "my-tool", description: "Test" };
+                const toolFn: FlinkTool<any> = async () => ({ success: true, data: {} });
+                const executor = new ToolExecutor(
+                    toolProps,
+                    toolFn,
+                    mockCtx,
+                    { inputSchema: allSchemas["MyTool.Input"], inputTypeHint: "named" },
+                    allSchemas
+                );
+
+                const { inputSchema } = executor.getToolSchema();
+
+                // $ref values should use JSON pointer format
+                expect(inputSchema.properties.item.$ref).toBe("#/$defs/Shared.Item");
+
+                // All transitively referenced schemas should be in $defs
+                expect(inputSchema.$defs).toBeDefined();
+                expect(inputSchema.$defs["Shared.Item"]).toBeDefined();
+                expect(inputSchema.$defs["Shared.Tag"]).toBeDefined();
+
+                // $refs inside $defs should also be rewritten
+                expect(inputSchema.$defs["Shared.Item"].properties.tag.$ref).toBe("#/$defs/Shared.Tag");
+            });
+
+            it("should strip $id and $schema from inlined $defs", () => {
+                const toolProps: FlinkToolProps = { id: "my-tool", description: "Test" };
+                const toolFn: FlinkTool<any> = async () => ({ success: true, data: {} });
+                const executor = new ToolExecutor(
+                    toolProps,
+                    toolFn,
+                    mockCtx,
+                    { inputSchema: allSchemas["MyTool.Input"], inputTypeHint: "named" },
+                    allSchemas
+                );
+
+                const { inputSchema } = executor.getToolSchema();
+
+                expect(inputSchema.$defs["Shared.Item"].$id).toBeUndefined();
+                expect(inputSchema.$defs["Shared.Item"].$schema).toBeUndefined();
+                expect(inputSchema.$defs["Shared.Tag"].$id).toBeUndefined();
+                expect(inputSchema.$defs["Shared.Tag"].$schema).toBeUndefined();
+            });
+
+            it("should strip $id and $schema from root schema", () => {
+                const toolProps: FlinkToolProps = { id: "my-tool", description: "Test" };
+                const toolFn: FlinkTool<any> = async () => ({ success: true, data: {} });
+                const executor = new ToolExecutor(
+                    toolProps,
+                    toolFn,
+                    mockCtx,
+                    { inputSchema: allSchemas["MyTool.Input"], inputTypeHint: "named" },
+                    allSchemas
+                );
+
+                const { inputSchema } = executor.getToolSchema();
+
+                expect(inputSchema.$id).toBeUndefined();
+                expect(inputSchema.$schema).toBeUndefined();
+            });
+
+            it("should return schema unchanged when no cross-schema refs exist", () => {
+                const simpleSchema = {
+                    $id: "Simple.Input",
+                    type: "object",
+                    properties: { name: { type: "string" } },
+                };
+                const toolProps: FlinkToolProps = { id: "simple-tool", description: "Test" };
+                const toolFn: FlinkTool<any> = async () => ({ success: true, data: {} });
+                const executor = new ToolExecutor(
+                    toolProps,
+                    toolFn,
+                    mockCtx,
+                    { inputSchema: simpleSchema, inputTypeHint: "named" },
+                    allSchemas
+                );
+
+                const { inputSchema } = executor.getToolSchema();
+
+                expect(inputSchema.$defs).toBeUndefined();
+            });
+        });
     });
 
     describe("Result formatting for AI", () => {

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/ToolExecutor.ts

@@ -23,7 +23,7 @@ export class ToolExecutor<Ctx extends FlinkContext> {
             inputTypeHint?: 'void' | 'any' | 'named';
             outputTypeHint?: 'void' | 'any' | 'named';
         },
-        allSchemas?: Record<string, any>
+        private allSchemas?: Record<string, any>
     ) {
         // Pre-populate AJV with all schemas so $ref references resolve across schema boundaries
         if (allSchemas) {
@@ -238,7 +238,7 @@ export class ToolExecutor<Ctx extends FlinkContext> {
             return {
                 name: this.toolProps.id,
                 description: this.toolProps.description,
-                inputSchema: this.autoSchemas.inputSchema,
+                inputSchema: this.resolveSchemaRefs(this.autoSchemas.inputSchema),
             };
         }
 
@@ -280,6 +280,73 @@ export class ToolExecutor<Ctx extends FlinkContext> {
         }
     }
 
+    /**
+     * Resolve cross-schema $ref values into $defs so the schema is self-contained.
+     *
+     * Flink's schema manifest stores schemas as separate documents with IDs like
+     * "Canvas.ElementInput". These are valid for AJV (which uses a schema registry),
+     * but LLM providers like OpenAI require a single self-contained schema where all
+     * $ref values point to #/$defs/... entries at the top level.
+     */
+    private resolveSchemaRefs(schema: any): any {
+        if (!this.allSchemas) return schema;
+
+        const defs: Record<string, any> = {};
+
+        const collectRefs = (node: any, visited: Set<string>): void => {
+            if (!node || typeof node !== "object") return;
+
+            if (node.$ref && typeof node.$ref === "string" && !node.$ref.startsWith("#")) {
+                const refId = node.$ref;
+                if (!visited.has(refId) && this.allSchemas![refId]) {
+                    visited.add(refId);
+                    // Clone and strip top-level JSON Schema meta fields not valid inside $defs
+                    const def = JSON.parse(JSON.stringify(this.allSchemas![refId]));
+                    delete def.$id;
+                    delete def.$schema;
+                    defs[refId] = def;
+                    // Recurse into the referenced schema to collect its deps
+                    collectRefs(def, visited);
+                }
+            }
+
+            for (const value of Object.values(node)) {
+                collectRefs(value, visited);
+            }
+        };
+
+        const visited = new Set<string>();
+        collectRefs(schema, visited);
+
+        if (Object.keys(defs).length === 0) return schema;
+
+        // Deep clone and rewrite all non-standard $ref values to #/$defs/<id>
+        const resolved = JSON.parse(JSON.stringify(schema));
+        delete resolved.$id;
+        delete resolved.$schema;
+
+        const rewriteRefs = (node: any): void => {
+            if (!node || typeof node !== "object") return;
+
+            if (node.$ref && typeof node.$ref === "string" && !node.$ref.startsWith("#")) {
+                node.$ref = `#/$defs/${node.$ref}`;
+            }
+
+            for (const value of Object.values(node)) {
+                rewriteRefs(value);
+            }
+        };
+
+        rewriteRefs(resolved);
+        // Also rewrite refs inside the collected defs
+        for (const def of Object.values(defs)) {
+            rewriteRefs(def);
+        }
+
+        resolved.$defs = defs;
+        return resolved;
+    }
+
     /**
      * Get tool result for AI consumption
      * Formats ToolResult into string for AI context

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);