@dpantani/tdmcp 0.1.0 → 0.2.0

package/dist/cli/agent.js

@@ -3,7 +3,7 @@
 // src/cli/agent.ts
 import { pathToFileURL } from "url";
 import { parseArgs } from "util";
-import { z as z21 } from "zod";
+import { z as z22 } from "zod";
 
 // src/knowledge/index.ts
 import { existsSync as existsSync2, readdirSync, readFileSync } from "fs";
@@ -474,61 +474,164 @@ import { existsSync as existsSync3, readdirSync as readdirSync2, readFileSync as
 import { join as join2 } from "path";
 
 // src/recipes/schema.ts
+import { z as z2 } from "zod";
+
+// src/tools/layer2/createControlPanel.ts
 import { z } from "zod";
-var RecipeNodeSchema = z.object({
-  name: z.string().describe("Unique node name within the recipe (used for wiring)."),
-  type: z.string().describe("Operator type, e.g. 'noiseTOP'."),
-  parameters: z.record(z.string(), z.unknown()).default({}),
-  parent: z.string().optional().describe(
+
+// src/td-client/types.ts
+var TdError = class extends Error {
+  code;
+  constructor(message, code, options) {
+    super(message, options);
+    this.name = "TdError";
+    this.code = code;
+  }
+};
+var TdConnectionError = class extends TdError {
+  constructor(message, options) {
+    super(message, "TD_CONNECTION", options);
+    this.name = "TdConnectionError";
+  }
+};
+var TdTimeoutError = class extends TdError {
+  constructor(message, options) {
+    super(message, "TD_TIMEOUT", options);
+    this.name = "TdTimeoutError";
+  }
+};
+var TdApiError = class extends TdError {
+  status;
+  apiCode;
+  constructor(message, options) {
+    super(message, "TD_API", options);
+    this.name = "TdApiError";
+    this.status = options?.status;
+    this.apiCode = options?.apiCode;
+  }
+};
+function friendlyTdError(err) {
+  if (err instanceof TdError) return err.message;
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+// src/tools/result.ts
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+function errorResult(message) {
+  return { isError: true, content: [{ type: "text", text: message }] };
+}
+function jsonResult(summary, data) {
+  const text = `${summary}
+
+\`\`\`json
+${JSON.stringify(data, null, 2)}
+\`\`\``;
+  return { content: [{ type: "text", text }] };
+}
+function structuredResult(summary, data) {
+  return {
+    content: [{ type: "text", text: summary }],
+    structuredContent: data
+  };
+}
+async function guardTd(fn, onOk) {
+  try {
+    return onOk(await fn());
+  } catch (err) {
+    return errorResult(friendlyTdError(err));
+  }
+}
+
+// src/tools/layer2/createControlPanel.ts
+var controlSchema = z.object({
+  name: z.string().describe(
+    "Control label; also sanitized into a valid TD custom-parameter name (e.g. 'blur amount' \u2192 'Bluramount')."
+  ),
+  type: z.enum(["float", "int", "toggle", "menu", "rgb", "pulse", "string"]).default("float").describe(
+    "Widget kind: float/int sliders, a toggle, a dropdown menu, an RGB swatch, a momentary pulse, or a text field."
+  ),
+  label: z.string().optional().describe("Display label (defaults to `name`)."),
+  min: z.coerce.number().optional().describe("Slider lower bound (float/int) \u2014 also hard-clamped."),
+  max: z.coerce.number().optional().describe("Slider upper bound (float/int) \u2014 also hard-clamped."),
+  default: z.union([z.number(), z.boolean(), z.string()]).optional().describe("Initial value."),
+  menu_items: z.array(z.string()).optional().describe("Options for a 'menu' control."),
+  bind_to: z.array(z.string()).optional().describe(
+    "Parameters this control should drive, each written as 'nodePath.parName' (e.g. '/project1/sys/blur1.size'). Each target is switched to expression mode so moving the control moves the parameter live. Not supported for 'rgb'/'pulse'."
+  )
+});
+var createControlPanelSchema = z.object({
+  comp_path: z.string().default("/project1").describe(
+    "COMP that will receive the custom parameters \u2014 usually a generated system's container."
+  ),
+  page: z.string().default("Controls").describe("Name of the custom-parameter page to add the controls to."),
+  controls: z.array(controlSchema).min(1).describe("The controls (knobs/sliders/toggles/menus) to expose.")
+});
+
+// src/recipes/schema.ts
+var RecipeNodeSchema = z2.object({
+  name: z2.string().describe("Unique node name within the recipe (used for wiring)."),
+  type: z2.string().describe("Operator type, e.g. 'noiseTOP'."),
+  parameters: z2.record(z2.string(), z2.unknown()).default({}),
+  parent: z2.string().optional().describe(
     "Name of another recipe node (a COMP, e.g. a geometryCOMP) to nest this node inside of. The parent must appear earlier in `nodes`. Used to place SOPs inside a Geometry COMP."
   ),
-  render: z.boolean().optional().describe(
+  render: z2.boolean().optional().describe(
     "For a SOP nested in a geometryCOMP: make this the rendered geometry. Sets the render/display flags on it and clears its siblings, so the COMP renders this instead of its default torus."
   ),
-  comment: z.string().optional()
+  comment: z2.string().optional()
 });
-var RecipeConnectionSchema = z.object({
-  from: z.string().describe("Source node name."),
-  to: z.string().describe("Target node name."),
-  from_output: z.number().int().nonnegative().default(0),
-  to_input: z.number().int().nonnegative().default(0)
+var RecipeConnectionSchema = z2.object({
+  from: z2.string().describe("Source node name."),
+  to: z2.string().describe("Target node name."),
+  from_output: z2.number().int().nonnegative().default(0),
+  to_input: z2.number().int().nonnegative().default(0)
 });
-var RecipeParameterSchema = z.object({
-  name: z.string().describe("Friendly name of the exposed control."),
-  node: z.string().describe("Recipe node name the parameter belongs to."),
-  param: z.string().describe("TD parameter name on that node."),
-  value: z.unknown().optional(),
-  label: z.string().optional(),
-  min: z.number().optional(),
-  max: z.number().optional(),
-  description: z.string().optional()
+var RecipeParameterSchema = z2.object({
+  name: z2.string().describe("Friendly name of the exposed control."),
+  node: z2.string().describe("Recipe node name the parameter belongs to."),
+  param: z2.string().describe("TD parameter name on that node."),
+  value: z2.unknown().optional(),
+  label: z2.string().optional(),
+  min: z2.number().optional(),
+  max: z2.number().optional(),
+  description: z2.string().optional()
 });
-var RecipeGlslUniformSchema = z.object({
-  node: z.string().describe("Recipe node name of the GLSL TOP that declares the uniform."),
-  name: z.string().describe("Uniform name as referenced in the shader, e.g. 'uFeed'."),
-  kind: z.enum(["float", "vec", "color"]).default("float").describe(
+var RecipeGlslUniformSchema = z2.object({
+  node: z2.string().describe("Recipe node name of the GLSL TOP that declares the uniform."),
+  name: z2.string().describe("Uniform name as referenced in the shader, e.g. 'uFeed'."),
+  kind: z2.enum(["float", "vec", "color"]).default("float").describe(
     "Uniform kind: float (uniform float), vec (uniform vec2/3/4), color (rgba). float/vec use the Vectors page; color uses the Colors page."
   ),
-  value: z.union([z.number(), z.array(z.number())]).optional().describe("Initial value: a number for float, or an array of components for vec/color."),
-  label: z.string().optional(),
-  min: z.number().optional(),
-  max: z.number().optional(),
-  description: z.string().optional()
+  value: z2.union([z2.number(), z2.array(z2.number())]).optional().describe("Initial value: a number for float, or an array of components for vec/color."),
+  label: z2.string().optional(),
+  min: z2.number().optional(),
+  max: z2.number().optional(),
+  description: z2.string().optional()
 });
-var RecipeSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  description: z.string().default(""),
-  tags: z.array(z.string()).default([]),
-  difficulty: z.enum(["beginner", "intermediate", "advanced"]).default("intermediate"),
-  td_version_min: z.string().default("2023"),
-  nodes: z.array(RecipeNodeSchema).min(1),
-  connections: z.array(RecipeConnectionSchema).default([]),
-  parameters: z.array(RecipeParameterSchema).default([]),
-  glsl_uniforms: z.array(RecipeGlslUniformSchema).default([]),
-  glsl_code: z.record(z.string(), z.string()).optional(),
-  python_code: z.record(z.string(), z.string()).optional(),
-  preview_description: z.string().default("")
+var RecipeSchema = z2.object({
+  id: z2.string(),
+  name: z2.string(),
+  description: z2.string().default(""),
+  tags: z2.array(z2.string()).default([]),
+  difficulty: z2.enum(["beginner", "intermediate", "advanced"]).default("intermediate"),
+  td_version_min: z2.string().default("2023"),
+  nodes: z2.array(RecipeNodeSchema).min(1),
+  connections: z2.array(RecipeConnectionSchema).default([]),
+  parameters: z2.array(RecipeParameterSchema).default([]),
+  glsl_uniforms: z2.array(RecipeGlslUniformSchema).default([]),
+  glsl_code: z2.record(z2.string(), z2.string()).optional(),
+  python_code: z2.record(z2.string(), z2.string()).optional(),
+  /**
+   * Live controls to auto-expose on the system container: custom parameters (knobs/
+   * sliders/toggles) bound to node parameters so the built system is immediately
+   * playable. Each control's `bind_to` uses recipe node *names* ("nodeName.parName");
+   * buildFromRecipe rewrites them to the real created paths.
+   */
+  controls: z2.array(controlSchema).default([]),
+  preview_description: z2.string().default("")
 });
 
 // src/recipes/loader.ts
@@ -596,145 +699,110 @@ var RecipeLibrary = class {
   }
 };
 
-// src/td-client/types.ts
-var TdError = class extends Error {
-  code;
-  constructor(message, code, options) {
-    super(message, options);
-    this.name = "TdError";
-    this.code = code;
-  }
-};
-var TdConnectionError = class extends TdError {
-  constructor(message, options) {
-    super(message, "TD_CONNECTION", options);
-    this.name = "TdConnectionError";
-  }
-};
-var TdTimeoutError = class extends TdError {
-  constructor(message, options) {
-    super(message, "TD_TIMEOUT", options);
-    this.name = "TdTimeoutError";
-  }
-};
-var TdApiError = class extends TdError {
-  status;
-  apiCode;
-  constructor(message, options) {
-    super(message, "TD_API", options);
-    this.name = "TdApiError";
-    this.status = options?.status;
-    this.apiCode = options?.apiCode;
-  }
-};
-function friendlyTdError(err) {
-  if (err instanceof TdError) return err.message;
-  if (err instanceof Error) return err.message;
-  return String(err);
-}
-
 // src/td-client/validators.ts
-import { z as z2 } from "zod";
-var ApiEnvelopeSchema = z2.object({
-  ok: z2.boolean(),
-  data: z2.unknown().optional(),
-  error: z2.object({ code: z2.string().optional(), message: z2.string() }).optional()
+import { z as z3 } from "zod";
+var ApiEnvelopeSchema = z3.object({
+  ok: z3.boolean(),
+  data: z3.unknown().optional(),
+  error: z3.object({ code: z3.string().optional(), message: z3.string() }).optional()
 });
-var NodeRefSchema = z2.object({
-  path: z2.string(),
-  type: z2.string().default(""),
-  name: z2.string().default("")
+var NodeRefSchema = z3.object({
+  path: z3.string(),
+  type: z3.string().default(""),
+  name: z3.string().default(""),
+  /** Parameters that could not be applied at create time (unknown name or bad value). */
+  parameter_warnings: z3.array(z3.string()).optional()
 });
 var NodeDetailSchema = NodeRefSchema.extend({
-  parameters: z2.record(z2.string(), z2.unknown()).default({}),
-  inputs: z2.array(z2.string()).optional(),
-  outputs: z2.array(z2.string()).optional(),
-  family: z2.string().optional(),
-  errors: z2.array(z2.string()).optional()
+  parameters: z3.record(z3.string(), z3.unknown()).default({}),
+  inputs: z3.array(z3.string()).optional(),
+  outputs: z3.array(z3.string()).optional(),
+  family: z3.string().optional(),
+  errors: z3.array(z3.string()).optional()
 });
-var NodeListSchema = z2.object({ nodes: z2.array(NodeRefSchema).default([]) });
-var InfoSchema = z2.object({
-  td_version: z2.string().optional(),
-  python_version: z2.string().optional(),
-  build: z2.string().optional(),
-  bridge_version: z2.string().optional(),
-  project: z2.string().optional()
+var NodeListSchema = z3.object({ nodes: z3.array(NodeRefSchema).default([]) });
+var InfoSchema = z3.object({
+  td_version: z3.string().optional(),
+  python_version: z3.string().optional(),
+  build: z3.string().optional(),
+  bridge_version: z3.string().optional(),
+  project: z3.string().optional()
 });
-var NodeErrorSchema = z2.object({
-  path: z2.string(),
-  message: z2.string(),
-  type: z2.string().optional()
+var NodeErrorSchema = z3.object({
+  path: z3.string(),
+  message: z3.string(),
+  type: z3.string().optional()
 });
-var NodeErrorsSchema = z2.object({ errors: z2.array(NodeErrorSchema).default([]) });
-var PreviewSchema = z2.object({
-  path: z2.string(),
-  width: z2.number().int().positive(),
-  height: z2.number().int().positive(),
-  format: z2.string().default("png"),
-  base64: z2.string()
+var NodeErrorsSchema = z3.object({ errors: z3.array(NodeErrorSchema).default([]) });
+var PreviewSchema = z3.object({
+  path: z3.string(),
+  width: z3.number().int().positive(),
+  height: z3.number().int().positive(),
+  format: z3.string().default("png"),
+  base64: z3.string()
 });
-var ExecResultSchema = z2.object({
-  result: z2.unknown().optional(),
-  stdout: z2.string().optional(),
-  printed: z2.array(z2.string()).optional()
+var ExecResultSchema = z3.object({
+  result: z3.unknown().optional(),
+  stdout: z3.string().optional(),
+  printed: z3.array(z3.string()).optional()
 });
-var MethodResultSchema = z2.object({ result: z2.unknown() });
-var DeleteResultSchema = z2.object({ deleted: z2.string() });
-var ConnectionSchema = z2.object({
-  source_path: z2.string(),
-  source_output: z2.number().int().default(0),
-  target_path: z2.string(),
-  target_input: z2.number().int().default(0)
+var MethodResultSchema = z3.object({ result: z3.unknown() });
+var DeleteResultSchema = z3.object({ deleted: z3.string() });
+var ConnectionSchema = z3.object({
+  source_path: z3.string(),
+  source_output: z3.number().int().default(0),
+  target_path: z3.string(),
+  target_input: z3.number().int().default(0)
 });
-var TopologySchema = z2.object({
-  nodes: z2.array(NodeRefSchema).default([]),
-  connections: z2.array(ConnectionSchema).default([])
+var TopologySchema = z3.object({
+  nodes: z3.array(NodeRefSchema).default([]),
+  connections: z3.array(ConnectionSchema).default([])
 });
-var PerformanceSchema = z2.object({
-  nodes: z2.array(
-    z2.object({
-      path: z2.string(),
-      cook_time_ms: z2.number().default(0),
-      cook_count: z2.number().optional()
+var PerformanceSchema = z3.object({
+  nodes: z3.array(
+    z3.object({
+      path: z3.string(),
+      cook_time_ms: z3.number().default(0),
+      cook_count: z3.number().optional()
     })
   ).default([]),
-  total_cook_time_ms: z2.number().optional(),
-  gpu_memory_mb: z2.number().optional()
+  total_cook_time_ms: z3.number().optional(),
+  gpu_memory_mb: z3.number().optional()
 });
-var BatchOpResultSchema = z2.object({
-  action: z2.string(),
-  ok: z2.boolean(),
-  path: z2.string().optional(),
-  data: z2.unknown().optional(),
-  error: z2.string().optional()
+var BatchOpResultSchema = z3.object({
+  action: z3.string(),
+  ok: z3.boolean(),
+  path: z3.string().optional(),
+  data: z3.unknown().optional(),
+  error: z3.string().optional()
 });
-var BatchResultSchema = z2.object({ results: z2.array(BatchOpResultSchema).default([]) });
-var CreateNodeInputSchema = z2.object({
-  parent_path: z2.string(),
-  type: z2.string(),
-  name: z2.string().optional(),
-  parameters: z2.record(z2.string(), z2.unknown()).optional()
+var BatchResultSchema = z3.object({ results: z3.array(BatchOpResultSchema).default([]) });
+var CreateNodeInputSchema = z3.object({
+  parent_path: z3.string(),
+  type: z3.string(),
+  name: z3.string().optional(),
+  parameters: z3.record(z3.string(), z3.unknown()).optional()
 });
-var BatchOperationSchema = z2.discriminatedUnion("action", [
-  z2.object({
-    action: z2.literal("create"),
-    parent_path: z2.string(),
-    type: z2.string(),
-    name: z2.string().optional(),
-    parameters: z2.record(z2.string(), z2.unknown()).optional()
+var BatchOperationSchema = z3.discriminatedUnion("action", [
+  z3.object({
+    action: z3.literal("create"),
+    parent_path: z3.string(),
+    type: z3.string(),
+    name: z3.string().optional(),
+    parameters: z3.record(z3.string(), z3.unknown()).optional()
   }),
-  z2.object({
-    action: z2.literal("update"),
-    path: z2.string(),
-    parameters: z2.record(z2.string(), z2.unknown())
+  z3.object({
+    action: z3.literal("update"),
+    path: z3.string(),
+    parameters: z3.record(z3.string(), z3.unknown())
   }),
-  z2.object({ action: z2.literal("delete"), path: z2.string() }),
-  z2.object({
-    action: z2.literal("connect"),
-    source_path: z2.string(),
-    target_path: z2.string(),
-    source_output: z2.number().int().default(0),
-    target_input: z2.number().int().default(0)
+  z3.object({ action: z3.literal("delete"), path: z3.string() }),
+  z3.object({
+    action: z3.literal("connect"),
+    source_path: z3.string(),
+    target_path: z3.string(),
+    source_output: z3.number().int().default(0),
+    target_input: z3.number().int().default(0)
   })
 ]);
 
@@ -893,40 +961,46 @@ var TouchDesignerClient = class {
       recursive ? { recursive: true } : void 0
     );
   }
-  getNetworkPerformance(path) {
-    return this.request("GET", `/api/network/${segment(path)}/performance`, PerformanceSchema);
+  getNetworkPerformance(path, recursive = false) {
+    return this.request(
+      "GET",
+      `/api/network/${segment(path)}/performance`,
+      PerformanceSchema,
+      void 0,
+      recursive ? { recursive: true } : void 0
+    );
   }
 };
 
 // src/utils/config.ts
-import { z as z3 } from "zod";
-var ConfigSchema = z3.object({
+import { z as z4 } from "zod";
+var ConfigSchema = z4.object({
   /** TouchDesigner bridge host. */
-  tdHost: z3.string().min(1).default("127.0.0.1"),
+  tdHost: z4.string().min(1).default("127.0.0.1"),
   /** TouchDesigner bridge port (WebServer DAT). */
-  tdPort: z3.coerce.number().int().positive().max(65535).default(9980),
+  tdPort: z4.coerce.number().int().positive().max(65535).default(9980),
   /** MCP transport: `stdio` (default, for local clients) or `http` (Streamable HTTP, loopback-only). */
-  transport: z3.enum(["stdio", "http"]).default("stdio"),
+  transport: z4.enum(["stdio", "http"]).default("stdio"),
   /** Log verbosity (written to stderr). */
-  logLevel: z3.enum(["debug", "info", "warn", "error", "silent"]).default("info"),
+  logLevel: z4.enum(["debug", "info", "warn", "error", "silent"]).default("info"),
   /** Per-request timeout against the TD bridge, in milliseconds. */
-  requestTimeoutMs: z3.coerce.number().int().positive().default(1e4),
+  requestTimeoutMs: z4.coerce.number().int().positive().default(1e4),
   /** HTTP transport port (only used when transport=http). */
-  httpPort: z3.coerce.number().int().positive().max(65535).default(3939),
+  httpPort: z4.coerce.number().int().positive().max(65535).default(3939),
   /** Subscribe to TD WebSocket events and forward them as MCP logging notifications. */
-  events: z3.enum(["on", "off"]).default("on"),
+  events: z4.enum(["on", "off"]).default("on"),
   /**
    * Raw Python escape-hatch tools (`execute_python_script`, `exec_node_method`).
    * Set to "off" to lock them out for restricted setups; on by default.
    */
-  rawPython: z3.enum(["on", "off"]).default("on"),
+  rawPython: z4.enum(["on", "off"]).default("on"),
   /**
    * Optional shared bearer token for the TD bridge. When set, the server sends it
    * as `Authorization: Bearer <token>` and the bridge requires a match. Leave unset
    * (default) for the zero-config local flow. Set the SAME value in TouchDesigner's
    * environment (`TDMCP_BRIDGE_TOKEN`) to turn enforcement on.
    */
-  bridgeToken: z3.string().min(1).optional()
+  bridgeToken: z4.string().min(1).optional()
 });
 function loadConfig(env = process.env) {
   return ConfigSchema.parse({
@@ -982,53 +1056,22 @@ function buildToolContext(config, overrides = {}) {
 }
 
 // src/tools/layer3/compareTdNodes.ts
-import { z as z4 } from "zod";
-
-// src/tools/result.ts
-function textResult(text) {
-  return { content: [{ type: "text", text }] };
-}
-function errorResult(message) {
-  return { isError: true, content: [{ type: "text", text: message }] };
-}
-function jsonResult(summary, data) {
-  const text = `${summary}
-
-\`\`\`json
-${JSON.stringify(data, null, 2)}
-\`\`\``;
-  return { content: [{ type: "text", text }] };
-}
-function structuredResult(summary, data) {
-  return {
-    content: [{ type: "text", text: summary }],
-    structuredContent: data
-  };
-}
-async function guardTd(fn, onOk) {
-  try {
-    return onOk(await fn());
-  } catch (err) {
-    return errorResult(friendlyTdError(err));
-  }
-}
-
-// src/tools/layer3/compareTdNodes.ts
-var compareTdNodesSchema = z4.object({
-  path_a: z4.string().describe("First node path."),
-  path_b: z4.string().describe("Second node path."),
-  only_diff: z4.boolean().default(true).describe("Return only the parameters that differ (true) or also list the identical ones.")
+import { z as z5 } from "zod";
+var compareTdNodesSchema = z5.object({
+  path_a: z5.string().describe("First node path."),
+  path_b: z5.string().describe("Second node path."),
+  only_diff: z5.boolean().default(true).describe("Return only the parameters that differ (true) or also list the identical ones.")
 });
-var compareTdNodesOutputSchema = z4.object({
-  a: z4.string(),
-  b: z4.string(),
-  type_a: z4.string(),
-  type_b: z4.string(),
-  type_match: z4.boolean(),
-  differing_count: z4.number(),
-  same_count: z4.number(),
-  differing: z4.array(z4.object({ param: z4.string(), a: z4.unknown(), b: z4.unknown() })),
-  identical: z4.array(z4.string()).optional()
+var compareTdNodesOutputSchema = z5.object({
+  a: z5.string(),
+  b: z5.string(),
+  type_a: z5.string(),
+  type_b: z5.string(),
+  type_match: z5.boolean(),
+  differing_count: z5.number(),
+  same_count: z5.number(),
+  differing: z5.array(z5.object({ param: z5.string(), a: z5.unknown(), b: z5.unknown() })),
+  identical: z5.array(z5.string()).optional()
 });
 async function compareTdNodesImpl(ctx, args) {
   return guardTd(
@@ -1069,12 +1112,12 @@ async function compareTdNodesImpl(ctx, args) {
 }
 
 // src/tools/layer3/createTdNode.ts
-import { z as z5 } from "zod";
-var createTdNodeSchema = z5.object({
-  parent_path: z5.string().default("/project1").describe("Parent COMP path to create the node inside."),
-  type: z5.string().describe("Operator type string, e.g. 'noiseTOP', 'feedbackTOP', 'nullTOP', 'constantCHOP'."),
-  name: z5.string().optional().describe("Optional node name (auto-generated if omitted)."),
-  parameters: z5.record(z5.string(), z5.unknown()).optional().describe("Optional initial parameter overrides as key\u2192value pairs.")
+import { z as z6 } from "zod";
+var createTdNodeSchema = z6.object({
+  parent_path: z6.string().default("/project1").describe("Parent COMP path to create the node inside."),
+  type: z6.string().describe("Operator type string, e.g. 'noiseTOP', 'feedbackTOP', 'nullTOP', 'constantCHOP'."),
+  name: z6.string().optional().describe("Optional node name (auto-generated if omitted)."),
+  parameters: z6.record(z6.string(), z6.unknown()).optional().describe("Optional initial parameter overrides as key\u2192value pairs.")
 });
 async function createTdNodeImpl(ctx, args) {
   const warnings = [];
@@ -1091,14 +1134,25 @@ async function createTdNodeImpl(ctx, args) {
       name: args.name,
       parameters: args.parameters
     }),
-    (node) => jsonResult(`Created ${node.type || args.type} at ${node.path}.`, { node, warnings })
+    (node) => {
+      const allWarnings = [...warnings];
+      if (node.parameter_warnings?.length) {
+        allWarnings.push(
+          `These parameter(s) were not applied (unknown name or bad value): ${node.parameter_warnings.join(", ")}.`
+        );
+      }
+      return jsonResult(`Created ${node.type || args.type} at ${node.path}.`, {
+        node,
+        warnings: allWarnings
+      });
+    }
   );
 }
 
 // src/tools/layer3/deleteTdNode.ts
-import { z as z6 } from "zod";
-var deleteTdNodeSchema = z6.object({
-  path: z6.string().describe("Full path of the node to delete, e.g. '/project1/noise1'.")
+import { z as z7 } from "zod";
+var deleteTdNodeSchema = z7.object({
+  path: z7.string().describe("Full path of the node to delete, e.g. '/project1/noise1'.")
 });
 async function deleteTdNodeImpl(ctx, args) {
   return guardTd(
@@ -1108,12 +1162,12 @@ async function deleteTdNodeImpl(ctx, args) {
 }
 
 // src/tools/layer3/execNodeMethod.ts
-import { z as z7 } from "zod";
-var execNodeMethodSchema = z7.object({
-  path: z7.string().describe("Full path of the node to call the method on."),
-  method: z7.string().describe("Method name to call, e.g. 'cook', 'par', 'destroy', 'copy'."),
-  args: z7.array(z7.unknown()).default([]).describe("Positional arguments."),
-  kwargs: z7.record(z7.string(), z7.unknown()).default({}).describe("Keyword arguments.")
+import { z as z8 } from "zod";
+var execNodeMethodSchema = z8.object({
+  path: z8.string().describe("Full path of the node to call the method on."),
+  method: z8.string().describe("Method name to call, e.g. 'cook', 'par', 'destroy', 'copy'."),
+  args: z8.array(z8.unknown()).default([]).describe("Positional arguments."),
+  kwargs: z8.record(z8.string(), z8.unknown()).default({}).describe("Keyword arguments.")
 });
 async function execNodeMethodImpl(ctx, args) {
   return guardTd(
@@ -1123,12 +1177,12 @@ async function execNodeMethodImpl(ctx, args) {
 }
 
 // src/tools/layer3/executePythonScript.ts
-import { z as z8 } from "zod";
-var executePythonScriptSchema = z8.object({
-  script: z8.string().min(1).describe(
+import { z as z9 } from "zod";
+var executePythonScriptSchema = z9.object({
+  script: z9.string().min(1).describe(
     "Python source to execute inside TouchDesigner (runs in the TD process, not locally)."
   ),
-  return_output: z8.boolean().default(true).describe("Capture stdout / the value of the last expression and return it.")
+  return_output: z9.boolean().default(true).describe("Capture stdout / the value of the last expression and return it.")
 });
 async function executePythonScriptImpl(ctx, args) {
   return guardTd(
@@ -1138,7 +1192,7 @@ async function executePythonScriptImpl(ctx, args) {
 }
 
 // src/tools/layer3/findTdNodes.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 
 // src/tools/layer3/nodeMatch.ts
 function globToRegExp(pattern) {
@@ -1151,21 +1205,21 @@ function parentOf(path) {
 }
 
 // src/tools/layer3/findTdNodes.ts
-var findTdNodesSchema = z9.object({
-  parent_path: z9.string().default("/project1").describe("Where to search from."),
-  pattern: z9.string().optional().describe("Case-insensitive name/path filter with '*' wildcards (e.g. 'text*', '*noise*')."),
-  type: z9.string().optional().describe("Case-insensitive operator-type substring (e.g. 'TOP', 'noise')."),
-  recursive: z9.boolean().default(true).describe("Search the whole sub-network (true) or only direct children (false)."),
-  path_only: z9.boolean().default(false).describe("Return only matching paths."),
-  limit: z9.number().int().positive().default(50).describe("Max matches to return.")
+var findTdNodesSchema = z10.object({
+  parent_path: z10.string().default("/project1").describe("Where to search from."),
+  pattern: z10.string().optional().describe("Case-insensitive name/path filter with '*' wildcards (e.g. 'text*', '*noise*')."),
+  type: z10.string().optional().describe("Case-insensitive operator-type substring (e.g. 'TOP', 'noise')."),
+  recursive: z10.boolean().default(true).describe("Search the whole sub-network (true) or only direct children (false)."),
+  path_only: z10.boolean().default(false).describe("Return only matching paths."),
+  limit: z10.number().int().positive().default(50).describe("Max matches to return.")
 });
-var findTdNodesOutputSchema = z9.object({
-  parent_path: z9.string(),
-  recursive: z9.boolean(),
-  count: z9.number(),
-  truncated: z9.boolean(),
-  paths: z9.array(z9.string()).optional(),
-  matches: z9.array(NodeRefSchema).optional()
+var findTdNodesOutputSchema = z10.object({
+  parent_path: z10.string(),
+  recursive: z10.boolean(),
+  count: z10.number(),
+  truncated: z10.boolean(),
+  paths: z10.array(z10.string()).optional(),
+  matches: z10.array(NodeRefSchema).optional()
 });
 async function findTdNodesImpl(ctx, args) {
   const fetch2 = args.recursive ? async () => (await ctx.client.getNetworkTopology(args.parent_path, true)).nodes : async () => (await ctx.client.getNodes(args.parent_path)).nodes;
@@ -1189,9 +1243,9 @@ async function findTdNodesImpl(ctx, args) {
 }
 
 // src/tools/layer3/getModuleHelp.ts
-import { z as z10 } from "zod";
-var getModuleHelpSchema = z10.object({
-  name: z10.string().describe("Class or module name to get help for, e.g. 'OP', 'App', 'Project'.")
+import { z as z11 } from "zod";
+var getModuleHelpSchema = z11.object({
+  name: z11.string().describe("Class or module name to get help for, e.g. 'OP', 'App', 'Project'.")
 });
 function getModuleHelpImpl(ctx, args) {
   const cls = ctx.knowledge.getPythonClass(args.name);
@@ -1220,9 +1274,9 @@ function getModuleHelpImpl(ctx, args) {
 }
 
 // src/tools/layer3/getTdClassDetails.ts
-import { z as z11 } from "zod";
-var getTdClassDetailsSchema = z11.object({
-  class_name: z11.string().describe("Python class name, e.g. 'OP', 'TOP', 'App', 'CHOP'.")
+import { z as z12 } from "zod";
+var getTdClassDetailsSchema = z12.object({
+  class_name: z12.string().describe("Python class name, e.g. 'OP', 'TOP', 'App', 'CHOP'.")
 });
 function getTdClassDetailsImpl(ctx, args) {
   const cls = ctx.knowledge.getPythonClass(args.class_name);
@@ -1240,9 +1294,9 @@ function getTdClassDetailsImpl(ctx, args) {
 }
 
 // src/tools/layer3/getTdClasses.ts
-import { z as z12 } from "zod";
-var getTdClassesSchema = z12.object({
-  filter: z12.string().optional().describe("Optional case-insensitive substring to filter class names by.")
+import { z as z13 } from "zod";
+var getTdClassesSchema = z13.object({
+  filter: z13.string().optional().describe("Optional case-insensitive substring to filter class names by.")
 });
 function getTdClassesImpl(ctx, args) {
   let classes = ctx.knowledge.listPythonClasses();
@@ -1279,17 +1333,17 @@ async function getTdInfoImpl(ctx) {
 }
 
 // src/tools/layer3/getTdNodeErrors.ts
-import { z as z13 } from "zod";
-var getTdNodeErrorsSchema = z13.object({
-  path: z13.string().describe("Full path of the node (or network root) to check for errors."),
-  recursive: z13.boolean().default(false).describe("If true, check the whole network under `path`; otherwise just that node."),
-  summary: z13.boolean().default(false).describe("Return only counts grouped by error type instead of the full error list.")
+import { z as z14 } from "zod";
+var getTdNodeErrorsSchema = z14.object({
+  path: z14.string().describe("Full path of the node (or network root) to check for errors."),
+  recursive: z14.boolean().default(false).describe("If true, check the whole network under `path`; otherwise just that node."),
+  summary: z14.boolean().default(false).describe("Return only counts grouped by error type instead of the full error list.")
 });
-var getTdNodeErrorsOutputSchema = z13.object({
-  path: z13.string(),
-  total: z13.number(),
-  errors: z13.array(NodeErrorSchema).optional(),
-  by_type: z13.record(z13.string(), z13.number()).optional()
+var getTdNodeErrorsOutputSchema = z14.object({
+  path: z14.string(),
+  total: z14.number(),
+  errors: z14.array(NodeErrorSchema).optional(),
+  by_type: z14.record(z14.string(), z14.number()).optional()
 });
 async function getTdNodeErrorsImpl(ctx, args) {
   return guardTd(
@@ -1318,11 +1372,11 @@ async function getTdNodeErrorsImpl(ctx, args) {
 }
 
 // src/tools/layer3/getTdNodeParameters.ts
-import { z as z14 } from "zod";
-var getTdNodeParametersSchema = z14.object({
-  path: z14.string().describe("Full path of the node to inspect."),
-  keys: z14.array(z14.string()).optional().describe("Only return these parameter names (case-sensitive). Omit to return all parameters."),
-  omit_io: z14.boolean().default(false).describe("Drop the inputs/outputs lists from the result to save context.")
+import { z as z15 } from "zod";
+var getTdNodeParametersSchema = z15.object({
+  path: z15.string().describe("Full path of the node to inspect."),
+  keys: z15.array(z15.string()).optional().describe("Only return these parameter names (case-sensitive). Omit to return all parameters."),
+  omit_io: z15.boolean().default(false).describe("Drop the inputs/outputs lists from the result to save context.")
 });
 async function getTdNodeParametersImpl(ctx, args) {
   return guardTd(
@@ -1352,29 +1406,29 @@ async function getTdNodeParametersImpl(ctx, args) {
 }
 
 // src/tools/layer3/getTdNodes.ts
-import { z as z15 } from "zod";
-var getTdNodesSchema = z15.object({
-  parent_path: z15.string().default("/project1").describe("Parent COMP whose direct children should be listed."),
-  pattern: z15.string().optional().describe(
+import { z as z16 } from "zod";
+var getTdNodesSchema = z16.object({
+  parent_path: z16.string().default("/project1").describe("Parent COMP whose direct children should be listed."),
+  pattern: z16.string().optional().describe(
     "Case-insensitive filter on node name/path. Supports '*' wildcards (e.g. 'text*', '*noise*')."
   ),
-  path_only: z15.boolean().default(false).describe("Return only the list of node paths, dropping type/name."),
-  limit: z15.number().int().positive().optional().describe("Cap the number of nodes returned."),
-  detail_level: z15.enum(["summary", "full"]).default("summary").describe(
+  path_only: z16.boolean().default(false).describe("Return only the list of node paths, dropping type/name."),
+  limit: z16.number().int().positive().optional().describe("Cap the number of nodes returned."),
+  detail_level: z16.enum(["summary", "full"]).default("summary").describe(
     "'summary' (default) returns a count, a type breakdown and the first few paths; 'full' returns every node. Use 'full' (or path_only) when you need the complete list."
   )
 });
 var SAMPLE_SIZE = 10;
-var getTdNodesOutputSchema = z15.object({
-  parent_path: z15.string(),
-  count: z15.number(),
-  detail_level: z15.enum(["summary", "full"]),
-  truncated: z15.boolean(),
-  by_type: z15.record(z15.string(), z15.number()).optional(),
-  sample: z15.array(z15.string()).optional(),
-  paths: z15.array(z15.string()).optional(),
-  nodes: z15.array(NodeRefSchema).optional(),
-  hint: z15.string().optional()
+var getTdNodesOutputSchema = z16.object({
+  parent_path: z16.string(),
+  count: z16.number(),
+  detail_level: z16.enum(["summary", "full"]),
+  truncated: z16.boolean(),
+  by_type: z16.record(z16.string(), z16.number()).optional(),
+  sample: z16.array(z16.string()).optional(),
+  paths: z16.array(z16.string()).optional(),
+  nodes: z16.array(NodeRefSchema).optional(),
+  hint: z16.string().optional()
 });
 async function getTdNodesImpl(ctx, args) {
   return guardTd(
@@ -1429,11 +1483,11 @@ async function getTdNodesImpl(ctx, args) {
 }
 
 // src/tools/layer3/getTdPerformance.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 
 // src/feedback/performanceMonitor.ts
-async function checkPerformance(client, path, targetFps = 60) {
-  const perf = await client.getNetworkPerformance(path);
+async function checkPerformance(client, path, targetFps = 60, recursive = true) {
+  const perf = await client.getNetworkPerformance(path, recursive);
   const frameBudgetMs = 1e3 / targetFps;
   const warnings = [];
   for (const node of perf.nodes) {
@@ -1449,31 +1503,35 @@ async function checkPerformance(client, path, targetFps = 60) {
       `Total cook time ${totalCookMs.toFixed(2)}ms exceeds the ${frameBudgetMs.toFixed(2)}ms budget at ${targetFps}fps.`
     );
   }
-  return { path, targetFps, frameBudgetMs, totalCookMs, nodes: perf.nodes, warnings };
+  const nodes = [...perf.nodes].sort((a, b) => b.cook_time_ms - a.cook_time_ms);
+  return { path, targetFps, frameBudgetMs, totalCookMs, nodes, warnings };
 }
 
 // src/tools/layer3/getTdPerformance.ts
-var getTdPerformanceSchema = z16.object({
-  root_path: z16.string().default("/project1").describe("Network root to measure cook times under."),
-  target_fps: z16.number().positive().default(60).describe("Frame-rate target used to flag slow nodes.")
+var getTdPerformanceSchema = z17.object({
+  root_path: z17.string().default("/project1").describe("Network root to measure cook times under."),
+  target_fps: z17.number().positive().default(60).describe("Frame-rate target used to flag slow nodes."),
+  recursive: z17.boolean().default(true).describe(
+    "Measure every descendant (true, default) so cook time inside generated containers is counted, not just the root's direct children."
+  )
 });
-var getTdPerformanceOutputSchema = z16.object({
-  path: z16.string(),
-  targetFps: z16.number(),
-  frameBudgetMs: z16.number(),
-  totalCookMs: z16.number(),
-  nodes: z16.array(
-    z16.object({
-      path: z16.string(),
-      cook_time_ms: z16.number(),
-      cook_count: z16.number().optional()
+var getTdPerformanceOutputSchema = z17.object({
+  path: z17.string(),
+  targetFps: z17.number(),
+  frameBudgetMs: z17.number(),
+  totalCookMs: z17.number(),
+  nodes: z17.array(
+    z17.object({
+      path: z17.string(),
+      cook_time_ms: z17.number(),
+      cook_count: z17.number().optional()
     })
   ),
-  warnings: z16.array(z16.string())
+  warnings: z17.array(z17.string())
 });
 async function getTdPerformanceImpl(ctx, args) {
   return guardTd(
-    () => checkPerformance(ctx.client, args.root_path, args.target_fps),
+    () => checkPerformance(ctx.client, args.root_path, args.target_fps, args.recursive),
     (report) => structuredResult(
       report.warnings.length === 0 ? `Within budget: ${report.totalCookMs.toFixed(2)}ms total under ${args.root_path} (${args.target_fps}fps).` : `${report.warnings.length} performance warning(s) under ${args.root_path}.`,
       report
@@ -1482,7 +1540,7 @@ async function getTdPerformanceImpl(ctx, args) {
 }
 
 // src/tools/layer3/getTdTopology.ts
-import { z as z17 } from "zod";
+import { z as z18 } from "zod";
 
 // src/feedback/networkVerifier.ts
 async function verifyNetwork(client, path) {
@@ -1503,14 +1561,14 @@ async function verifyNetwork(client, path) {
 }
 
 // src/tools/layer3/getTdTopology.ts
-var getTdTopologySchema = z17.object({
-  root_path: z17.string().default("/project1").describe("Network root to map.")
+var getTdTopologySchema = z18.object({
+  root_path: z18.string().default("/project1").describe("Network root to map.")
 });
-var getTdTopologyOutputSchema = z17.object({
-  path: z17.string(),
-  nodeCount: z17.number(),
-  connectionCount: z17.number(),
-  issues: z17.array(z17.string()),
+var getTdTopologyOutputSchema = z18.object({
+  path: z18.string(),
+  nodeCount: z18.number(),
+  connectionCount: z18.number(),
+  issues: z18.array(z18.string()),
   topology: TopologySchema
 });
 async function getTdTopologyImpl(ctx, args) {
@@ -1524,27 +1582,27 @@ async function getTdTopologyImpl(ctx, args) {
 }
 
 // src/tools/layer3/snapshotTdGraph.ts
-import { z as z18 } from "zod";
+import { z as z19 } from "zod";
 var MAX_PARAM_NODES = 60;
-var snapshotTdGraphSchema = z18.object({
-  path: z18.string().default("/project1").describe("Network root to snapshot."),
-  include_params: z18.boolean().default(false).describe("Also fetch each node's parameters (one request per node; capped for large graphs).")
+var snapshotTdGraphSchema = z19.object({
+  path: z19.string().default("/project1").describe("Network root to snapshot."),
+  include_params: z19.boolean().default(false).describe("Also fetch each node's parameters (one request per node; capped for large graphs).")
 });
-var snapshotTdGraphOutputSchema = z18.object({
-  path: z18.string(),
-  nodeCount: z18.number(),
-  connectionCount: z18.number(),
-  issues: z18.array(z18.string()),
-  params_truncated: z18.boolean(),
-  nodes: z18.array(
-    z18.object({
-      path: z18.string(),
-      type: z18.string(),
-      name: z18.string(),
-      parameters: z18.record(z18.string(), z18.unknown()).optional()
+var snapshotTdGraphOutputSchema = z19.object({
+  path: z19.string(),
+  nodeCount: z19.number(),
+  connectionCount: z19.number(),
+  issues: z19.array(z19.string()),
+  params_truncated: z19.boolean(),
+  nodes: z19.array(
+    z19.object({
+      path: z19.string(),
+      type: z19.string(),
+      name: z19.string(),
+      parameters: z19.record(z19.string(), z19.unknown()).optional()
     })
   ),
-  connections: z18.array(ConnectionSchema)
+  connections: z19.array(ConnectionSchema)
 });
 async function snapshotTdGraphImpl(ctx, args) {
   return guardTd(
@@ -1585,25 +1643,25 @@ async function snapshotTdGraphImpl(ctx, args) {
 }
 
 // src/tools/layer3/summarizeTdErrors.ts
-import { z as z19 } from "zod";
-var summarizeTdErrorsSchema = z19.object({
-  path: z19.string().default("/project1").describe("Network root to collect errors under."),
-  group_by: z19.enum(["message", "type", "parent"]).default("message").describe(
+import { z as z20 } from "zod";
+var summarizeTdErrorsSchema = z20.object({
+  path: z20.string().default("/project1").describe("Network root to collect errors under."),
+  group_by: z20.enum(["message", "type", "parent"]).default("message").describe(
     "How to cluster errors: by exact message, by error type, or by parent container (to find a common upstream cause)."
   )
 });
-var summarizeTdErrorsOutputSchema = z19.object({
-  path: z19.string(),
-  total: z19.number(),
-  group_by: z19.enum(["message", "type", "parent"]),
-  groups: z19.array(
-    z19.object({
-      key: z19.string(),
-      count: z19.number(),
-      sample: z19.object({ path: z19.string(), message: z19.string() })
+var summarizeTdErrorsOutputSchema = z20.object({
+  path: z20.string(),
+  total: z20.number(),
+  group_by: z20.enum(["message", "type", "parent"]),
+  groups: z20.array(
+    z20.object({
+      key: z20.string(),
+      count: z20.number(),
+      sample: z20.object({ path: z20.string(), message: z20.string() })
     })
   ),
-  suggestions: z19.array(z19.string())
+  suggestions: z20.array(z20.string())
 });
 async function summarizeTdErrorsImpl(ctx, args) {
   return guardTd(
@@ -1650,10 +1708,10 @@ async function summarizeTdErrorsImpl(ctx, args) {
 }
 
 // src/tools/layer3/updateTdNodeParameters.ts
-import { z as z20 } from "zod";
-var updateTdNodeParametersSchema = z20.object({
-  path: z20.string().describe("Full path of the node whose parameters to update."),
-  parameters: z20.record(z20.string(), z20.unknown()).describe("Parameter overrides as key\u2192value pairs, e.g. { period: 4, amplitude: 0.5 }.")
+import { z as z21 } from "zod";
+var updateTdNodeParametersSchema = z21.object({
+  path: z21.string().describe("Full path of the node whose parameters to update."),
+  parameters: z21.record(z21.string(), z21.unknown()).describe("Parameter overrides as key\u2192value pairs, e.g. { period: 4, amplitude: 0.5 }.")
 });
 async function updateTdNodeParametersImpl(ctx, args) {
   return guardTd(
@@ -1667,7 +1725,7 @@ async function updateTdNodeParametersImpl(ctx, args) {
 // src/cli/agent.ts
 var r = (schema, run, summary, opts = {}) => ({ schema, run, summary, mutates: !!opts.mutates, unsafe: !!opts.unsafe });
 var COMMANDS = {
-  info: r(z21.object({}), (ctx) => getTdInfoImpl(ctx), "Health check + TD/bridge info."),
+  info: r(z22.object({}), (ctx) => getTdInfoImpl(ctx), "Health check + TD/bridge info."),
   "nodes list": r(
     getTdNodesSchema,
     getTdNodesImpl,
@@ -1803,7 +1861,7 @@ async function runCli(argv, opts = {}) {
       summary: cmd2.summary,
       mutates: cmd2.mutates,
       unsafe: cmd2.unsafe,
-      input: z21.toJSONSchema(cmd2.schema)
+      input: z22.toJSONSchema(cmd2.schema)
     };
     return { stdout: `${JSON.stringify(doc, null, 2)}
 `, stderr: "", code: 0 };