Add TypeSpec AI Tools emitter to generate Effect Schemas

packages/spec/api/flow.tsp

@@ -17,14 +17,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 +39,11 @@ model FlowVersion {
   @foreignKey flowId: Id;
 }
 
+@AITools.explorationTool
+@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 +56,12 @@ enum HandleKind {
   Loop,
 }
 
+@AITools.explorationTool
+@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 +93,11 @@ model Position {
   y: float32;
 }
 
+@AITools.explorationTool
+@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, description: "Delete a node from the workflow. Also removes all connected edges." }
+)
 @TanStackDB.collection
 model Node {
   @primaryKey nodeId: Id;
@@ -89,10 +109,14 @@ model Node {
   @visibility(Lifecycle.Read) info?: string;
 }
 
+@AITools.explorationTool
+@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 +125,45 @@ enum ErrorHandling {
   Break,
 }
 
+@AITools.explorationTool
+@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
+@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
+@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
+@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,21 @@
   "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": "./dist/ai-tools/v1/index.ts",
+    "./tools/common": "./dist/ai-tools/v1/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"
+  },
+  "dependencies": {
+    "effect": "catalog:"
   },
   "devDependencies": {
     "@bufbuild/buf": "catalog:",
@@ -18,8 +27,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:"
   }
 }

packages/spec/tsconfig.lib.json

@@ -1,6 +1,6 @@
 {
   "extends": "../../tsconfig.json",
-  "include": ["dist", "lib"],
+  "include": ["dist", "lib", "src/tools"],
   "exclude": ["node_modules", "*.ts"],
   "references": [
     {

packages/spec/tspconfig.yaml

@@ -3,6 +3,7 @@ output-dir: '{project-root}/dist'
 emit:
   - '@the-dev-tools/spec-lib/protobuf'
   - '@the-dev-tools/spec-lib/tanstack-db'
+  - '@the-dev-tools/spec-lib/ai-tools'
 
 options:
   '@the-dev-tools/spec-lib':

tools/spec-lib/package.json

@@ -17,6 +17,11 @@
       "types": "./dist/src/tanstack-db/index.d.ts",
       "default": "./dist/src/tanstack-db/index.js",
       "typespec": "./src/tanstack-db/main.tsp"
+    },
+    "./ai-tools": {
+      "types": "./dist/src/ai-tools/index.d.ts",
+      "default": "./dist/src/ai-tools/index.js",
+      "typespec": "./src/ai-tools/main.tsp"
     }
   },
   "devDependencies": {