Add TypeSpec AI Tools emitter to generate Effect Schemas

packages/spec/api/flow.tsp

@@ -2,6 +2,7 @@ using DevTools;
 
 namespace Api.Flow;
 
+@AITools.explorationTool(#{ name: "ValidateWorkflow", title: "Validate Workflow", description: "Validate a workflow by checking its structure, connections, and node configurations for errors." })
 @TanStackDB.collection
 model Flow {
   @primaryKey flowId: Id;
@@ -17,14 +18,18 @@ model FlowDuplicateRequest {
 
 op FlowDuplicate(...FlowDuplicateRequest): {};
 
+@AITools.aiTool(#{ category: AITools.ToolCategory.Execution, title: "Run Flow" })
+@doc("Execute a workflow from the start node.")
 model FlowRunRequest {
-  flowId: Id;
+  @doc("The ULID of the workflow to run") flowId: Id;
 }
 
 op FlowRun(...FlowRunRequest): {};
 
+@AITools.aiTool(#{ category: AITools.ToolCategory.Execution, title: "Stop Flow" })
+@doc("Stop a running workflow execution.")
 model FlowStopRequest {
-  flowId: Id;
+  @doc("The ULID of the workflow to stop") flowId: Id;
 }
 
 op FlowStop(...FlowStopRequest): {};
@@ -35,6 +40,11 @@ model FlowVersion {
   @foreignKey flowId: Id;
 }
 
+@AITools.explorationTool(#{ name: "GetFlowVariable", title: "Get Flow Variable", description: "Get a flow variable by its primary key." })
+@AITools.mutationTool(
+  #{ operation: AITools.CrudOperation.Insert, title: "Create Variable", name: "CreateVariable", description: "Create a new workflow variable that can be referenced in node expressions." },
+  #{ operation: AITools.CrudOperation.Update, title: "Update Variable", name: "UpdateVariable", description: "Update an existing workflow variable." }
+)
 @TanStackDB.collection
 model FlowVariable {
   @primaryKey flowVariableId: Id;
@@ -47,6 +57,12 @@ enum HandleKind {
   Loop,
 }
 
+@AITools.explorationTool(#{ name: "GetEdge", title: "Get Edge", description: "Get a edge by its primary key." })
+@AITools.mutationTool(
+  #{ operation: AITools.CrudOperation.Insert, title: "Connect Sequential Nodes", name: "ConnectSequentialNodes", exclude: #["sourceHandle"], description: "Connect two nodes in a sequential flow. Use this for ManualStart, JavaScript, and HTTP nodes which have a single output." },
+  #{ operation: AITools.CrudOperation.Insert, title: "Connect Branching Nodes", name: "ConnectBranchingNodes", description: "Connect a branching node (Condition, For, ForEach) to another node. Requires sourceHandle: 'then' or 'else' for Condition nodes, 'then' or 'loop' for For/ForEach nodes." },
+  #{ operation: AITools.CrudOperation.Delete, title: "Disconnect Nodes", name: "DisconnectNodes", description: "Remove an edge connection between nodes." }
+)
 @TanStackDB.collection
 model Edge {
   @primaryKey edgeId: Id;
@@ -78,6 +94,11 @@ model Position {
   y: float32;
 }
 
+@AITools.explorationTool(#{ name: "GetNode", title: "Get Node", description: "Get a node by its primary key." })
+@AITools.mutationTool(
+  #{ operation: AITools.CrudOperation.Update, title: "Update Node Config", name: "UpdateNodeConfig", exclude: #["kind"], description: "Update general node properties like name or position." },
+  #{ operation: AITools.CrudOperation.Delete, title: "Delete Node", name: "DeleteNode", description: "Delete a node from the workflow. Also removes all connected edges." }
+)
 @TanStackDB.collection
 model Node {
   @primaryKey nodeId: Id;
@@ -89,10 +110,14 @@ model Node {
   @visibility(Lifecycle.Read) info?: string;
 }
 
+@AITools.explorationTool(#{ name: "GetNodeHttp", title: "Get Node Http", description: "Get a node http by its primary key." })
+@AITools.mutationTool(
+  #{ operation: AITools.CrudOperation.Insert, title: "Create HTTP Node", name: "CreateHttpNode", parent: "Node", exclude: #["kind"], description: "Create a new HTTP request node that makes an API call." }
+)
 @TanStackDB.collection
 model NodeHttp {
   @primaryKey nodeId: Id;
-  @foreignKey httpId: Id;
+  @doc("The ULID of the HTTP request definition to use") @foreignKey httpId: Id;
   @foreignKey deltaHttpId?: Id;
 }
 
@@ -101,28 +126,45 @@ enum ErrorHandling {
   Break,
 }
 
+@AITools.explorationTool(#{ name: "GetNodeFor", title: "Get Node For", description: "Get a node for by its primary key." })
+@AITools.mutationTool(
+  #{ operation: AITools.CrudOperation.Insert, title: "Create For Loop Node", name: "CreateForNode", parent: "Node", exclude: #["kind"], description: "Create a for-loop node that iterates a fixed number of times." }
+)
 @TanStackDB.collection
 model NodeFor {
   @primaryKey nodeId: Id;
-  iterations: int32;
+  @doc("Number of iterations to perform") iterations: int32;
   condition: string;
   errorHandling: ErrorHandling;
 }
 
+@AITools.explorationTool(#{ name: "GetNodeForEach", title: "Get Node For Each", description: "Get a node for each by its primary key." })
+@AITools.mutationTool(
+  #{ operation: AITools.CrudOperation.Insert, title: "Create ForEach Loop Node", name: "CreateForEachNode", parent: "Node", exclude: #["kind"], description: "Create a forEach node that iterates over an array or object." }
+)
 @TanStackDB.collection
 model NodeForEach {
   @primaryKey nodeId: Id;
-  path: string;
+  @doc("Path to the array/object to iterate (e.g., \"input.items\")") path: string;
   condition: string;
   errorHandling: ErrorHandling;
 }
 
+@AITools.explorationTool(#{ name: "GetNodeCondition", title: "Get Node Condition", description: "Get a node condition by its primary key." })
+@AITools.mutationTool(
+  #{ operation: AITools.CrudOperation.Insert, title: "Create Condition Node", name: "CreateConditionNode", parent: "Node", exclude: #["kind"], description: "Create a condition node that routes flow based on a boolean expression. Has THEN and ELSE output handles." }
+)
 @TanStackDB.collection
 model NodeCondition {
   @primaryKey nodeId: Id;
   condition: string;
 }
 
+@AITools.explorationTool(#{ name: "GetNodeJs", title: "Get Node Js", description: "Get a node js by its primary key." })
+@AITools.mutationTool(
+  #{ operation: AITools.CrudOperation.Insert, title: "Create JavaScript Node", name: "CreateJsNode", parent: "Node", exclude: #["kind"], description: "Create a new JavaScript node in the workflow. JS nodes can transform data, make calculations, or perform custom logic." },
+  #{ operation: AITools.CrudOperation.Update, title: "Update Node Code", name: "UpdateNodeCode", description: "Update the JavaScript code of a JS node." }
+)
 @TanStackDB.collection
 model NodeJs {
   @primaryKey nodeId: Id;

packages/spec/api/main.tsp

@@ -1,6 +1,7 @@
 import "@the-dev-tools/spec-lib/core";
 import "@the-dev-tools/spec-lib/protobuf";
 import "@the-dev-tools/spec-lib/tanstack-db";
+import "@the-dev-tools/spec-lib/ai-tools";
 
 import "./environment.tsp";
 import "./export.tsp";
@@ -20,11 +21,11 @@ alias Id = bytes;
 
 model CommonTableFields<TParent extends Reflection.Model> {
   ...Keys<TParent, #{ primary: KeyAs.Foreign, foreign: KeyAs.Omit }>;
-  key: string;
-  enabled: boolean;
-  value: string;
-  description: string;
-  order: float32;
+  @doc("Variable name (used to reference it in expressions)") key: string;
+  @doc("Whether the variable is active") enabled: boolean;
+  @doc("Variable value") value: string;
+  @doc("Description of what the variable is for") description: string;
+  @doc("Display order") order: float32;
 }
 
 @DevTools.project

packages/spec/package.json

@@ -4,12 +4,25 @@
   "type": "module",
   "files": [
     "dist",
+    "src",
     "go.mod",
     "go.sum"
   ],
   "exports": {
     "./buf/*": "./dist/buf/typescript/*.ts",
-    "./tanstack-db/*": "./dist/tanstack-db/typescript/*.ts"
+    "./tanstack-db/*": "./dist/tanstack-db/typescript/*.ts",
+    "./tools": "./src/tools/index.ts",
+    "./tools/schemas": "./dist/tools/schemas.ts",
+    "./tools/common": "./src/tools/common.ts",
+    "./tools/execution": "./dist/ai-tools/v1/execution.ts",
+    "./tools/exploration": "./dist/ai-tools/v1/exploration.ts",
+    "./tools/mutation": "./dist/ai-tools/v1/mutation.ts"
+  },
+  "scripts": {
+    "generate:schemas": "tsx src/tools/generate.ts"
+  },
+  "dependencies": {
+    "effect": "catalog:"
   },
   "devDependencies": {
     "@bufbuild/buf": "catalog:",
@@ -18,8 +31,8 @@
     "@the-dev-tools/eslint-config": "workspace:^",
     "@the-dev-tools/spec-lib": "workspace:^",
     "@types/node": "catalog:",
-    "effect": "catalog:",
     "prettier": "catalog:",
+    "tsx": "^4.19.0",
     "typescript": "catalog:"
   }
 }