@saltcorn/copilot 0.8.0 → 0.8.2

package/app-constructor/tools.js

@@ -46,12 +46,13 @@ const task_tool = {
           type: "array",
           items: {
             type: "object",
-            required: ["requirement", "priority"],
+            required: ["name", "description", "priority", "depends_on"],
             additionalProperties: false,
             properties: {
               name: {
                 type: "string",
-                description: "A short name for the task",
+                description:
+                  "A short unique name for the task (snake_case). Every other task that depends on this task must use exactly this name in their depends_on array.",
               },
               description: {
                 type: "string",
@@ -65,7 +66,7 @@ const task_tool = {
               depends_on: {
                 type: "array",
                 description:
-                  "The names of the tasks that must be completed before this tasks can be started",
+                  "Names of tasks in THIS plan that must complete before this task starts. Every name listed here MUST exactly match the name of another task in this same plan_tasks call. Never reference a task name that is not present in the tasks array.",
                 items: {
                   type: "string",
                 },
@@ -78,4 +79,4 @@ const task_tool = {
   },
 };
 
-module.exports = { requirements_tool,task_tool };
+module.exports = { requirements_tool, task_tool };

package/app-constructor/view.js

@@ -159,6 +159,13 @@ const submit_specs = async (table_id, viewname, config, body, { req, res }) => {
       user_id: req.user?.id || undefined,
       body: spec,
     });
+  return {
+    json: {
+      success: "ok",
+      notify: "Specification saved",
+      notify_type: "success",
+    },
+  };
 };
 
 const virtual_triggers = () => {

package/builder-gen.js

@@ -6,8 +6,12 @@ const { edit_build_in_actions } = require("@saltcorn/data/viewable_fields");
 const { buildBuilderSchema } = require("./builder-schema");
 const { getLlmConfigurationSafe, canUseResponseFormat } = require("./common");
 const { build_schema_data } = require("@saltcorn/data/plugin-helper");
-const { RelationsFinder } = require("@saltcorn/common-code");
-const { RelationType } = require("@saltcorn/common-code");
+const {
+  GET_RELATION_PATHS_FUNCTION,
+  getRelationPaths,
+  getRelationPathsForPairs,
+  pickBestRelation,
+} = require("./relation-paths");
 
 const ACTION_SIZES = ["btn-sm", "btn-lg"];
 
@@ -40,7 +44,9 @@ Alternatively wrap groups of fields in a card with a descriptive title.`;
 const EDIT_ACTIONS = `\
 Use edit fieldviews, group related inputs, and finish with a row of actions: \
 a Save button (action_name "Save", style "btn btn-primary") and \
-a Cancel button (action_name "GoBack", style "btn btn-outline-secondary").`;
+a Cancel button (action_name "GoBack", style "btn btn-outline-secondary"). \
+To add a trigger button, add an extra action segment with action_name set to the trigger's name \
+exactly as it appears in the available actions list (ctx.actions).`;
 
 // ── Show-mode guidance blocks ─────────────────────────────────────────────────
 
@@ -73,7 +79,9 @@ only use "show_with_html" when the task explicitly requires rendering HTML conte
 
 const LISTCOLUMNS_VIEW_LINK = `\
 A view_link that opens the detail of a row MUST point to a Show-type view (viewtemplate "Show"). \
-Only include such a view_link if a Show view for this table is listed in the available views.`;
+Only include such a view_link if a Show view for this table is listed in the available views. \
+Every view_link requires a "relation" string — you MUST call get_relation_paths before generating the layout \
+whenever the layout will contain any view_link or embedded view segment.`;
 
 // ── Composed MODE_GUIDANCE ────────────────────────────────────────────────────
 
@@ -482,7 +490,10 @@ const prettifyActionName = (name) =>
 // Picks a valid fieldview from the field's available fieldviews only.
 // Never returns a fieldview that doesn't exist in field.fieldviews
 const pickFieldview = (field, mode, requestedFieldview = null) => {
-  const availableViews = field?.fieldviews || [];
+  const isEditMode = mode === "edit" || mode === "filter";
+  const availableViews = isEditMode
+    ? field?.editFieldviews || field?.fieldviews || []
+    : field?.fieldviews || [];
 
   // If no available fieldviews, return the first one or a safe default
   if (!availableViews.length) {
@@ -779,18 +790,13 @@ const normalizeSegment = (segment, ctx) => {
       let relation = clone.relation;
       if (!relation && ctx.table && ctx.schemaData) {
         try {
-          const finder = new RelationsFinder(
-            ctx.schemaData.tables,
-            ctx.schemaData.views,
-            6
-          );
-          const relations = finder.findRelations(
+          const relations = getRelationPaths(
             ctx.table.name,
             resolvedView,
-            []
+            ctx.schemaData
           );
           if (relations.length > 0) {
-            const picked = pickRelation(relations);
+            const picked = pickBestRelation(relations);
             if (picked) relation = picked.relationString;
           }
         } catch (e) {
@@ -801,7 +807,8 @@ const normalizeSegment = (segment, ctx) => {
       let viewLabel = clone.view_label || clone.view;
       let isFormula = clone.isFormula || {};
       const tmplMatch =
-        typeof viewLabel === "string" && viewLabel.match(/^\{\{\s*(.+?)\s*\}\}$/);
+        typeof viewLabel === "string" &&
+        viewLabel.match(/^\{\{\s*(.+?)\s*\}\}$/);
       if (tmplMatch) {
         viewLabel = tmplMatch[1];
         isFormula = { ...isFormula, label: true };
@@ -839,10 +846,19 @@ const normalizeSegment = (segment, ctx) => {
         child == null ? null : normalizeSegment(child, ctx)
       );
       if (!besides.some(Boolean)) return null;
-      return { ...clone, besides, list_columns: true };
+      // Drop 'type' — List viewtemplate expects { besides, list_columns: true } with no type field
+      const { type: _t, ...rest } = clone;
+      return { ...rest, besides, list_columns: true };
     }
     case "list_column": {
-      const contents = normalizeChild(clone.contents, ctx);
+      let raw = clone.contents;
+      // Saltcorn's list renderer handles `above` in a cell (wraps in Container)
+      // but silently drops a typeless `besides`. Convert it so both links render
+      // stacked in one column rather than disappearing.
+      if (raw && !raw.type && Array.isArray(raw.besides)) {
+        raw = { above: raw.besides };
+      }
+      const contents = normalizeChild(raw, ctx);
       return contents
         ? { ...clone, contents, header_label: clone.header_label || "" }
         : null;
@@ -950,7 +966,21 @@ const normalizeLayoutCandidate = (candidate, ctx) => {
     normalized = convertForeignLayout(candidate, ctx);
   }
   if (!normalized) return null;
-  const layout = Array.isArray(normalized) ? { above: normalized } : normalized;
+  let layout = Array.isArray(normalized) ? { above: normalized } : normalized;
+
+  // For listcolumns mode: if the LLM wrapped the list in a stack, unwrap it
+  if (
+    ctx.mode === "listcolumns" &&
+    layout.type === "stack" &&
+    Array.isArray(layout.above)
+  ) {
+    const listChild = layout.above.find((c) => c?.list_columns);
+    if (listChild) {
+      const { type: _t, ...rest } = listChild;
+      layout = rest;
+    }
+  }
+
   return sanitizeNoHtmlSegments(layout);
 };
 
@@ -989,6 +1019,11 @@ const buildPromptText = (userPrompt, ctx, schema) => {
       schema
     )}`
   );
+  parts.push(
+    `TOOL CALL REQUIRED: If the layout you are about to generate contains any view_link or embedded view (type "view") segment, ` +
+      `you MUST call get_relation_paths with all required source_table/target_view pairs BEFORE returning JSON. ` +
+      `Do NOT guess or omit the "relation" field — return the tool call first and use the result in the layout.`
+  );
   parts.push(
     `Based on the schema above, process the following user request and generate the layout JSON. Reminder: ONLY output valid JSON starting with { and ending with }, no markdown fences.\nUser request:\n"${userPrompt}"`
   );
@@ -1209,22 +1244,6 @@ const buildBracketObject = (node) => {
   return obj;
 };
 
-const pickRelation = (relations) => {
-  let own = null,
-    parent = null,
-    child = null;
-  for (const r of relations) {
-    if (r.type === RelationType.OWN) own = r;
-    else if (r.type === RelationType.PARENT_SHOW) parent = r;
-    else if (
-      r.type === RelationType.CHILD_LIST ||
-      r.type === RelationType.ONE_TO_ONE_SHOW
-    )
-      child = r;
-  }
-  return own || parent || child || relations[0];
-};
-
 const buildContext = async (mode, tableName) => {
   const normalizedMode = (mode || "show").toLowerCase();
   const ctx = {
@@ -1282,13 +1301,19 @@ const buildContext = async (mode, tableName) => {
   }
   if (rawFields?.then) rawFields = await rawFields;
   const fields = (rawFields || []).map((field) => {
-    let fieldviews = Object.keys(field.type?.fieldviews || {});
+    const fvDefs = field.type?.fieldviews || {};
+    let fieldviews = Object.keys(fvDefs);
     // FK fields have type "Key" (a string) so field.type?.fieldviews is empty;
     // ensure select and show are always available for them
     const typeName = field.type?.name || field.type || "";
     if (!fieldviews.length && String(typeName).startsWith("Key")) {
       fieldviews = ["select", "show"];
     }
+    // editFieldviews: only fieldviews where isEdit is not explicitly false
+    const editFieldviews = fieldviews.filter(
+      (fv) => fvDefs[fv]?.isEdit !== false
+    );
+
     const isPkName =
       table.pk_name &&
       typeof field.name === "string" &&
@@ -1313,6 +1338,7 @@ const buildContext = async (mode, tableName) => {
       is_pk_name: !!isPkName,
       default_fieldview: defaultFieldview,
       fieldviews: fieldviews.length ? fieldviews : ["show"],
+      editFieldviews: editFieldviews.length ? editFieldviews : fieldviews,
       attributes: field.attributes || {},
     };
   });
@@ -1397,6 +1423,79 @@ const buildErrorLayout = ({ message, mode, table }) => {
   };
 };
 
+const GET_RELATION_PATHS_TOOL = {
+  type: "function",
+  function: GET_RELATION_PATHS_FUNCTION,
+};
+
+/**
+ * Run the LLM allowing up to MAX_TOOL_ROUNDS get_relation_paths calls (depth
+ * escalation: 2 → 4 → 6) before producing the final layout JSON.
+ */
+const MAX_TOOL_ROUNDS = 4;
+const runWithRelationTools = async (llm, mainPrompt, opts) => {
+  const llm_add_message = getState().functions.llm_add_message;
+
+  const runChat = Array.isArray(opts.chat) ? [...opts.chat] : [];
+  runChat.push({ role: "user", content: mainPrompt });
+
+  // Drop response_format during tool phase; repair chain handles JSON after.
+  const toolOpts = { ...opts, tools: [GET_RELATION_PATHS_TOOL] };
+  delete toolOpts.response_format;
+  delete toolOpts.chat;
+
+  const schemaData = await build_schema_data();
+
+  for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+    const raw = await llm.run(null, { ...toolOpts, chat: runChat });
+
+    if (!raw?.hasToolCalls) {
+      return typeof raw === "string" ? raw : raw?.content ?? "";
+    }
+
+    // Append the assistant message so the next round has full context.
+    if (raw.ai_sdk && Array.isArray(raw.messages)) {
+      raw.messages
+        .filter((m) => m.role === "assistant")
+        .forEach((m) => runChat.push(m));
+    } else if (raw.tool_calls) {
+      runChat.push({
+        role: "assistant",
+        content: raw.content || null,
+        tool_calls: raw.tool_calls,
+      });
+    }
+
+    for (const tc of raw.getToolCalls()) {
+      let resultText;
+      if (tc.tool_name === "get_relation_paths") {
+        const maxDepth = tc.input.max_depth ?? 2;
+        const sections = getRelationPathsForPairs(
+          tc.input.pairs || [],
+          schemaData,
+          maxDepth
+        );
+        resultText =
+          sections.join("\n\n") +
+          `\n\nFor each pair above: analyse whether the listed paths include a suitable one for the intended relation type (ChildList, ParentShow, Own, etc.). ` +
+          `If a suitable path exists, set the "relation" property to the chosen path string for all types including Own. ` +
+          `If no suitable path exists for a pair (no paths listed, or none match the intended type), call get_relation_paths again with a higher max_depth (4, then 6). ` +
+          `Do not escalate just because multiple paths are listed — only escalate when none is appropriate.`;
+      } else {
+        resultText = `Unknown tool: ${tc.tool_name}`;
+      }
+      await llm_add_message.run("tool_response", resultText, {
+        chat: runChat,
+        tool_call: tc,
+      });
+    }
+  }
+
+  // Exhausted tool rounds — force final JSON answer.
+  const final = await llm.run(null, { ...opts, chat: runChat });
+  return typeof final === "string" ? final : final?.content ?? "";
+};
+
 module.exports = {
   normalizeLayoutCandidate,
   run: async (prompt, mode, table, existing_layout, chat) => {
@@ -1467,7 +1566,7 @@ module.exports = {
       if (!schema || !schema.schema) {
         throw new Error("Builder schema unavailable");
       }
-      rawResponse = await llm.run(llmPrompt, options);
+      rawResponse = await runWithRelationTools(llm, llmPrompt, options);
       payload = parseJsonPayload(rawResponse);
       const candidate = payload.layout ?? payload;
       const result = normalizeLayoutCandidate(candidate, ctx);
@@ -1510,6 +1609,7 @@ module.exports = {
   },
   isAsync: true,
   description: "Generate a builder layout",
+  hidden: true,
   arguments: [
     { name: "prompt", type: "String" },
     { name: "mode", type: "String" },

package/copilot-as-agent.js

@@ -49,6 +49,7 @@ const get_agent_view = () => {
         { skill_type: "Generate View" },
         { skill_type: "Registry editor" },
         { skill_type: "Javascript Action" },
+        { skill_type: "Generate trigger" },
         ...(typeof Plugin.loadAndSaveNewPlugin === "function"
           ? [{ skill_type: "Install Plugin" }]
           : []),
@@ -61,6 +62,7 @@ const get_agent_view = () => {
     min_role: 1,
     configuration: {
       agent_action,
+      show_prev_runs: true,
       viewname,
     },
   });

package/index.js

@@ -18,7 +18,6 @@ module.exports = {
   dependencies: ["@saltcorn/large-language-model", "@saltcorn/agents"],
   viewtemplates: features.workflows
     ? [
-        require("./chat-copilot"),
         require("./user-copilot"),
         require("./copilot-as-agent"),
         require("./app-constructor/view.js"),
@@ -44,7 +43,7 @@ module.exports = {
       require("./agent-skills/viewgen.js"),
       require("./agent-skills/registry-editor.js"),
       require("./agent-skills/js-action.js"),
-      require("./agent-skills/app-constructor-context.js"),
+      require("./agent-skills/triggergen.js"),
       ...(typeof Plugin.loadAndSaveNewPlugin === "function"
         ? [require("./agent-skills/install-plugin.js")]
         : []),

package/js-code-gen.js

@@ -57,6 +57,7 @@ module.exports = {
   },
   isAsync: true,
   description: "Generate JavaScript code for an action",
+  hidden: true,
   arguments: [
     { name: "description", type: "String" },
     { name: "existing_code", type: "String" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saltcorn/copilot",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "AI assistant for building Saltcorn applications",
   "main": "index.js",
   "dependencies": {

package/relation-paths.js

@@ -0,0 +1,269 @@
+const { RelationsFinder, RelationType } = require("@saltcorn/common-code");
+
+/**
+ * Relation path documentation included in LLM system prompts (viewgen, builder-gen).
+ *
+ * TWO FORMATS EXIST:
+ *
+ * New format (always generate this):
+ *   view: "viewname"  +  relation: ".sourcetable.segment1.segment2..."
+ *
+ *   Segment types:
+ *     Outbound FK (to parent):    FK field name alone,         e.g. trip_id
+ *     Inbound FK  (child rows):   childtable$fkfield,          e.g. packing_items$trip_id
+ *
+ *   Examples:
+ *     .trips.packing_items$trip_id            ChildList:    all packing_items for a trip
+ *     .packing_items.trip_id                  ParentShow:   the trip that owns a packing item
+ *     .artists.artist_plays_on_album$artist.album  ChildList through a join table
+ *     .users.orders$user_id.order_lines$order_id   RelationPath: multi-level
+ *
+ * Legacy format (may appear in existing configs — do not generate, understand only):
+ *   The type and path are encoded together in the view field, no separate relation field.
+ *     "Own:viewname"                     → same table, no relation
+ *     "ParentShow:viewname.table.fkfield" → outbound FK to parent
+ *     "ChildList:viewname.table.inbkey"  → inbound FK, one-to-many
+ *     "OneToOneShow:viewname.table.inbkey" → inbound FK, unique
+ *     "Independent:viewname"             → no FK relationship
+ *
+ * Relation types by new-format path structure:
+ *   Own          – zero segments, source and target are the same table
+ *   ParentShow   – single outbound-FK segment
+ *   OneToOneShow – single inbound-FK segment on a unique field
+ *   ChildList    – one or more inbound-FK segments (may mix outbound for join tables)
+ *   RelationPath – complex multi-level path mixing both segment types
+ */
+const RELATION_PATH_DOC = `
+## Relation paths
+
+Every view_link and embedded view segment requires two fields:
+- \`view\`: the view name (plain string, e.g. \`"packing_items_list"\`)
+- \`relation\`: a dot-separated path string (e.g. \`".trips.packing_items$trip_id"\`)
+
+**Always use this format. Never generate anything else.**
+
+---
+
+### Relation path format
+
+\`.sourcetable.segment1.segment2...\`
+
+Segment types:
+- **Outbound FK** (to a parent): FK field name alone — e.g. \`trip_id\`
+- **Inbound FK** (child rows): \`childtable$fkfield\` — e.g. \`packing_items$trip_id\`
+- **Same table** (no FK traversal): just the source table, no segments — e.g. \`".invoice_line_items"\`
+
+Examples:
+| relation string | meaning |
+|---|---|
+| \`.invoice_line_items\` | same-table link (no FK traversal) |
+| \`.trips.packing_items$trip_id\` | all packing_items for a trip |
+| \`.packing_items.trip_id\` | the trip that owns a packing_item |
+| \`.artists.artist_plays_on_album$artist.album\` | albums via join table |
+| \`.users.orders$user_id.order_lines$order_id\` | multi-level |
+
+---
+
+### Legacy format — read-only, never generate
+
+Any \`view\` field value that contains a colon (e.g. \`"ChildList:trips_list.packing_items.trip_id"\`,
+\`"Own:viewname"\`, \`"ParentShow:viewname.table.fkfield"\`) is legacy. You may encounter it in
+existing configs. Parse it to understand the relation, then always write back in the new format.
+
+| legacy view field | new format equivalent |
+|---|---|
+| \`"Own:viewname"\` | \`relation: ".sourcetable"\` |
+| \`"Independent:viewname"\` | no \`relation\` field needed |
+| \`"ParentShow:viewname.table.fkfield"\` | \`relation: ".sourcetable.fkfield"\` |
+| \`"ChildList:viewname.table.inbkey"\` | \`relation: ".sourcetable.childtable$inbkey"\` |
+| \`"OneToOneShow:viewname.table.inbkey"\` | \`relation: ".sourcetable.childtable$inbkey"\` |
+
+---
+
+### Using get_relation_paths
+
+Call it **once** with all source_table/target_view pairs you need. The tool always returns new-format
+path strings — use them as the \`relation\` field directly.
+
+**Depth escalation:** Start with \`max_depth=2\`. After receiving results, analyse each pair: does the
+result contain a path that matches the intended relation type? If yes, use it. If a pair has no
+suitable path (no paths at all, or none of the right type), call again with \`max_depth=4\`, then
+\`max_depth=6\` if still none. Do not escalate just because multiple paths are listed.
+
+Selecting among returned paths:
+- **ChildList** — target view shows multiple rows belonging to the current row.
+- **ParentShow** — target view shows the single parent the current row belongs to.
+- **OneToOneShow** — exactly one related child row via a unique FK.
+- **Own** — same table, no FK traversal. Relation string is just \`.sourcetable\`.
+- If multiple paths of the same type exist, pick the one whose FK field name best matches the task.
+- Prefer shorter paths (fewer segments) unless a longer one is clearly more appropriate.
+`;
+
+const typeToLabel = (type) => {
+  if (type === RelationType.OWN)
+    return "Own – source and target are the same table. Use this relation string as-is (no extra segments after the table name).";
+  if (type === RelationType.INDEPENDENT)
+    return "Independent – no FK relationship exists";
+  if (type === RelationType.PARENT_SHOW)
+    return "ParentShow – outbound FK to a parent record (many-to-one)";
+  if (type === RelationType.ONE_TO_ONE_SHOW)
+    return "OneToOneShow – unique inbound FK (one-to-one)";
+  if (type === RelationType.CHILD_LIST)
+    return "ChildList – inbound FK, one parent → many child rows";
+  return "RelationPath – complex multi-level path";
+};
+
+/**
+ * @param {string} sourceTableName
+ * @param {string} targetViewName
+ * @param {{ tables, views }} schemaData  pre-fetched via build_schema_data()
+ * @returns {Array<Relation>}  raw Relation objects from RelationsFinder
+ */
+function getRelationPaths(
+  sourceTableName,
+  targetViewName,
+  schemaData,
+  maxDepth = 6
+) {
+  if (!schemaData) return [];
+  try {
+    const finder = new RelationsFinder(
+      schemaData.tables,
+      schemaData.views,
+      maxDepth
+    );
+    return finder.findRelations(sourceTableName, targetViewName, []);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve multiple source_table/target_view pairs against pre-fetched schema data.
+ * All per-pair work is synchronous — call build_schema_data() once before invoking this.
+ * @param {Array<{source_table: string, target_view: string}>} pairs
+ * @param {{ tables, views }} schemaData
+ * @returns {Array<string>}  one formatted result string per pair
+ */
+function getRelationPathsForPairs(pairs, schemaData, maxDepth = 6) {
+  if (!schemaData)
+    return pairs.map(({ source_table, target_view }) =>
+      formatRelationPathResult(source_table, target_view, {
+        error: "Schema data unavailable",
+      })
+    );
+  const finder = new RelationsFinder(
+    schemaData.tables,
+    schemaData.views,
+    maxDepth
+  );
+  return pairs.map(({ source_table, target_view }) => {
+    const targetView = (schemaData.views || []).find(
+      (v) => v.name === target_view
+    );
+    if (!targetView)
+      return formatRelationPathResult(source_table, target_view, {
+        error: `View "${target_view}" not found in current schema`,
+      });
+    let relations;
+    try {
+      relations = finder.findRelations(source_table, target_view, []);
+    } catch (e) {
+      return formatRelationPathResult(source_table, target_view, {
+        error: `Failed to find relations: ${e.message}`,
+      });
+    }
+    return formatRelationPathResult(source_table, target_view, {
+      paths: relations.map((r) => ({
+        relation_string: r.relationString,
+        type: String(r.type),
+        label: typeToLabel(r.type),
+      })),
+    });
+  });
+}
+
+/**
+ * Pick the most useful relation from a list: Own > Parent > Child > first.
+ * Used as a fallback in builder-gen when the model doesn't specify a relation.
+ */
+function pickBestRelation(relations) {
+  if (!relations.length) return null;
+  let own = null,
+    parent = null,
+    child = null;
+  for (const r of relations) {
+    if (r.type === RelationType.OWN) own = r;
+    else if (r.type === RelationType.PARENT_SHOW) parent = r;
+    else if (
+      r.type === RelationType.CHILD_LIST ||
+      r.type === RelationType.ONE_TO_ONE_SHOW
+    )
+      child = r;
+  }
+  return own || parent || child || relations[0];
+}
+
+/**
+ * Format the result of getRelationPaths into a human-readable string for the model.
+ * Handles both found and not-found cases for one source_table/target_view pair.
+ */
+function formatRelationPathResult(source_table, target_view, result) {
+  if (result.error) return `${source_table} → ${target_view}: ${result.error}`;
+  if (!result.paths.length)
+    return `${source_table} → ${target_view}: no relation paths found (no FK relationship)`;
+  const lines = result.paths
+    .map((p) => `    "${p.relation_string}" — ${p.label}`)
+    .join("\n");
+  return `${source_table} → ${target_view}:\n${lines}`;
+}
+
+const GET_RELATION_PATHS_FUNCTION = {
+  name: "get_relation_paths",
+  description:
+    "Get all valid relation path strings for one or more source_table/target_view pairs. " +
+    "Call this before setting any 'relation' property on view_link columns or embedded view segments. " +
+    "Always start with max_depth=2 to keep the result compact. " +
+    "After receiving the results, analyse whether each pair has a suitable path for its intended relation type. " +
+    "If a pair has no suitable path, call again with max_depth=4, then max_depth=6 if still none. " +
+    "Stop as soon as every pair has a suitable path.",
+  parameters: {
+    type: "object",
+    required: ["pairs"],
+    properties: {
+      pairs: {
+        type: "array",
+        description:
+          "All source_table/target_view pairs you need relation paths for. Include every pair in one call.",
+        items: {
+          type: "object",
+          required: ["source_table", "target_view"],
+          properties: {
+            source_table: {
+              type: "string",
+              description: "The table of the view being built or updated.",
+            },
+            target_view: {
+              type: "string",
+              description: "The view to link to or embed.",
+            },
+          },
+        },
+      },
+      max_depth: {
+        type: "integer",
+        description:
+          "Maximum join depth to search. Start with 2. Escalate to 4, then 6, only if a pair has no suitable path in the current results — not just because paths exist, but because none match the intended relation type.",
+        default: 2,
+      },
+    },
+  },
+};
+
+module.exports = {
+  RELATION_PATH_DOC,
+  GET_RELATION_PATHS_FUNCTION,
+  getRelationPaths,
+  getRelationPathsForPairs,
+  pickBestRelation,
+};

package/standard-prompt.js

@@ -73,6 +73,7 @@ ${ds.join("\n")}`);
   },
   isAsync: true,
   description: "Return a standard prompt for writing code",
+  hidden: true,
   arguments: [
     {
       name: "options",

package/user-copilot.js

@@ -933,5 +933,7 @@ module.exports = {
   get_state_fields,
   tableless: true,
   run,
+  deprecated: true,
+  description: "Use Agents from the agent module instead",
   routes: { interact, delprevrun },
 };

package/workflow-gen.js

@@ -41,5 +41,6 @@ module.exports = {
   },
   isAsync: true,
   description: "Generate a workflow",
+  hidden: true,
   arguments: [{ name: "description", type: "String" }],
 };