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

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @flink-app/flink
 
+## 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/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/package.json

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