@useatlas/create 0.0.1

package/templates/nextjs-standalone/src/lib/agent-query.ts

@@ -0,0 +1,178 @@
+/**
+ * Shared agent query execution logic.
+ *
+ * Used by both the synchronous JSON endpoint (POST /api/v1/query) and the
+ * Slack bot routes to run the Atlas agent to completion and extract
+ * structured results from the tool calls.
+ */
+
+import { runAgent } from "@atlas/api/lib/agent";
+import { createLogger, withRequestContext } from "@atlas/api/lib/logger";
+
+const log = createLogger("agent-query");
+
+export interface PendingAction {
+  id: string;
+  type: string;
+  target: string;
+  summary: string;
+}
+
+export interface AgentQueryResult {
+  answer: string;
+  sql: string[];
+  data: { columns: string[]; rows: Record<string, unknown>[] }[];
+  steps: number;
+  usage: { totalTokens: number };
+  pendingActions?: PendingAction[];
+}
+
+/**
+ * Run the Atlas agent on a single question and return structured results.
+ *
+ * Creates a UIMessage from the question, optionally loads Salesforce tools,
+ * invokes the agent loop, and extracts SQL queries, data, and the final
+ * answer from tool results.
+ */
+export async function executeAgentQuery(
+  question: string,
+  requestId?: string,
+  options?: { priorMessages?: Array<{ role: "user" | "assistant"; content: string }> },
+): Promise<AgentQueryResult> {
+  const id = requestId ?? crypto.randomUUID();
+
+  return withRequestContext({ requestId: id }, async () => {
+    const priorUIMessages = (options?.priorMessages ?? []).map((m, i) => ({
+      id: `${id}-prior-${i}`,
+      role: m.role as "user" | "assistant",
+      parts: [{ type: "text" as const, text: m.content }],
+    }));
+
+    const messages = [
+      ...priorUIMessages,
+      {
+        id,
+        role: "user" as const,
+        parts: [{ type: "text" as const, text: question }],
+      },
+    ];
+
+    // Optionally include Salesforce tools and actions
+    let toolRegistry;
+    const includeActions = process.env.ATLAS_ACTIONS_ENABLED === "true";
+    let includeSalesforce = false;
+    try {
+      const { listSalesforceSources } = await import(
+        "@atlas/api/lib/db/salesforce"
+      );
+      includeSalesforce = listSalesforceSources().length > 0;
+    } catch (err: unknown) {
+      const code = (err as { code?: string })?.code;
+      const isModuleNotFound =
+        code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND";
+      if (!isModuleNotFound) {
+        log.error(
+          { err: err instanceof Error ? err : new Error(String(err)) },
+          "Failed to initialize Salesforce tool registry — falling back to default tools",
+        );
+      }
+    }
+    if (includeSalesforce || includeActions) {
+      try {
+        const { buildRegistry } = await import(
+          "@atlas/api/lib/tools/registry"
+        );
+        toolRegistry = await buildRegistry({ includeSalesforce, includeActions });
+      } catch (err) {
+        log.error(
+          { err: err instanceof Error ? err : new Error(String(err)) },
+          "Failed to build tool registry — falling back to default tools",
+        );
+      }
+    }
+
+    const result = await runAgent({
+      messages,
+      ...(toolRegistry && { tools: toolRegistry }),
+    });
+
+    const [text, steps, totalUsage] = await Promise.all([
+      result.text,
+      result.steps,
+      result.totalUsage,
+    ]);
+
+    // Collect SQL queries and their data from tool results
+    const sqlQueries: string[] = [];
+    const dataResults: { columns: string[]; rows: Record<string, unknown>[] }[] = [];
+    const pendingActions: PendingAction[] = [];
+    const answer = text;
+
+    for (const step of steps) {
+      // No tool results in text-only steps
+      if (!step.toolResults) continue;
+      for (const tr of step.toolResults) {
+        if (tr.toolName === "executeSQL" && tr.output) {
+          const r = tr.output as {
+            success?: boolean;
+            columns?: string[];
+            rows?: Record<string, unknown>[];
+          };
+          const inp = tr.input as { sql?: string };
+          if (inp.sql) {
+            sqlQueries.push(inp.sql);
+          }
+          if (r.success && r.columns && r.rows) {
+            dataResults.push({ columns: r.columns, rows: r.rows });
+          } else if (r.success) {
+            log.warn(
+              { requestId: id, toolName: "executeSQL", hasColumns: !!r.columns, hasRows: !!r.rows },
+              "executeSQL returned success but missing columns or rows",
+            );
+          }
+        }
+        // Detect pending action approvals from any action tool
+        if (tr.output && typeof tr.output === "object") {
+          const out = tr.output as Record<string, unknown>;
+          if (out.status === "pending_approval") {
+            if (typeof out.actionId !== "string" || !out.actionId) {
+              log.warn(
+                { toolName: tr.toolName, outputKeys: Object.keys(out) },
+                "Tool returned pending_approval but missing or invalid actionId — skipping",
+              );
+            } else {
+              const actionType = typeof (tr.input as Record<string, unknown>)?.actionType === "string"
+                ? (tr.input as Record<string, unknown>).actionType as string
+                : tr.toolName;
+              pendingActions.push({
+                id: out.actionId,
+                type: actionType,
+                target: typeof out.target === "string" ? out.target : "",
+                summary: typeof out.summary === "string" ? out.summary : "",
+              });
+            }
+          }
+        }
+      }
+    }
+
+    if (!answer && dataResults.length > 0) {
+      log.warn(
+        { requestId: id, steps: steps.length, sqlCount: sqlQueries.length },
+        "Agent produced data but no text answer — model may have hit step limit before responding",
+      );
+    }
+
+    return {
+      answer,
+      sql: sqlQueries,
+      data: dataResults,
+      steps: steps.length,
+      usage: {
+        totalTokens:
+          (totalUsage?.inputTokens ?? 0) + (totalUsage?.outputTokens ?? 0),
+      },
+      ...(pendingActions.length > 0 && { pendingActions }),
+    };
+  });
+}

package/templates/nextjs-standalone/src/lib/agent.ts

@@ -0,0 +1,505 @@
+/**
+ * The Atlas agent.
+ *
+ * Runs a single-agent loop driven by a ToolRegistry (default: explore,
+ * executeSQL). The loop runs until the step limit (25) is reached or
+ * the model stops issuing tool calls.
+ */
+
+import {
+  convertToModelMessages,
+  stepCountIs,
+  streamText,
+  type ModelMessage,
+  type SystemModelMessage,
+  type UIMessage,
+} from "ai";
+import { getModel, getProviderType, type ProviderType } from "./providers";
+import { defaultRegistry, type ToolRegistry } from "./tools/registry";
+import { getContextFragments, getDialectHints } from "./plugins/tools";
+import { connections, detectDBType, type ConnectionMetadata, type DBType } from "./db/connection";
+import { getCrossSourceJoins, type CrossSourceJoin } from "./semantic";
+import { getSemanticIndex } from "./semantic-index";
+import { createLogger } from "./logger";
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+
+const log = createLogger("agent");
+const tracer = trace.getTracer("atlas");
+
+const SYSTEM_PROMPT_PREFIX = `You are Atlas, an expert data analyst AI. You answer questions about data by exploring a semantic layer, writing SQL, and interpreting results.
+
+## Your Workflow
+
+Follow these steps for every question:
+
+### 1. Understand the Question
+Parse what the user is really asking. Check the Ambiguous Terms section below if the question uses terms that could have multiple meanings.`;
+
+const SYSTEM_PROMPT_SUFFIX = `## Rules
+- Use the Semantic Layer Reference below to identify tables and columns — write SQL directly when the reference has enough detail
+- Use the explore tool only when you need information not in the reference (e.g., sample values, complex join SQL, query pattern SQL)
+- NEVER guess table or column names — verify them against the reference or via explore
+- NEVER modify data — only SELECT queries are allowed
+- If you cannot answer a question with the available data, say so clearly
+- Be concise but thorough in your interpretations
+
+## Follow-up Questions
+When the user asks a follow-up question:
+- Reference previous query results — don't re-explore the semantic layer if you already know the schema
+- However, if the follow-up involves a different table or entity than the previous query, check the reference or re-explore the relevant entity schema
+- Build on prior SQL — reuse CTEs, table aliases, and filters from earlier queries when relevant
+- If the user says "break that down by X" or "now filter to Y", modify the previous query rather than starting from scratch
+- Refer back to specific numbers from your previous analysis when interpreting new results
+
+## Ambiguous Terms
+Before writing SQL, check if the user's question contains terms from the glossary that need clarification:
+- If a term has status "ambiguous", ASK the user to clarify which meaning they intend before proceeding
+- If a term has a "disambiguation" field (even if status is "defined"), follow its guidance — it may tell you to ask a clarifying question
+- Example: if the glossary lists multiple possible_mappings for a term like "size", ask which meaning the user intends
+- Only ask ONE clarifying question at a time — don't barrage the user
+- If the glossary provides a default interpretation, mention it: "By 'revenue' I'll use companies.revenue (annual company revenue). Would you prefer subscription MRR from accounts.monthly_value?"
+
+## Error Recovery
+When a SQL query fails, read the error carefully before retrying:
+- **Column not found** — The error often suggests the correct name (e.g., "column 'revnue' does not exist — did you mean 'revenue'?"). Go back to the entity schema to verify the exact column name.
+- **Table not found** — Re-read catalog.yml to find the correct table name. The table may use a different name than you expected.
+- **Syntax error** — Check the error position hint. Common issues: missing commas, unmatched parentheses, incorrect JOIN syntax.
+- **Type mismatch** — You may need to CAST a column (e.g., CAST(value AS numeric)). Check the column type in the entity schema.
+- **Timeout** — Simplify the query: remove unnecessary JOINs, add WHERE filters to reduce the dataset, or break into smaller queries.
+- Never retry the exact same SQL. Always fix the identified issue first.
+- Max 2 retries per question — if the query still fails, explain the issue to the user.`;
+
+const MYSQL_DIALECT_GUIDE = `
+
+## SQL Dialect: MySQL
+This database uses MySQL. Key differences from PostgreSQL:
+- Use \`YEAR(col)\` and \`MONTH(col)\` (preferred) or \`EXTRACT(YEAR FROM col)\` — both work
+- Use \`DATE_FORMAT(col, '%Y-%m')\` instead of \`TO_CHAR(col, 'YYYY-MM')\`
+- Use \`IFNULL(col, default)\` or \`COALESCE(col, default)\` — both work
+- Use backtick quoting for identifiers: \`\\\`column\\\`\` instead of \`"column"\`
+- Use \`CONCAT(a, b)\` for string concatenation — \`||\` is logical OR in MySQL
+- No \`ILIKE\` — use \`WHERE col COLLATE utf8mb4_bin LIKE 'pattern'\` for case-sensitive matching
+- \`GROUP_CONCAT(col SEPARATOR ', ')\` instead of \`STRING_AGG(col, ', ')\`
+- No \`::type\` casting — use \`CAST(x AS SIGNED)\`, \`CAST(x AS DECIMAL)\`
+- \`LIMIT offset, count\` or \`LIMIT count OFFSET offset\` — both forms work
+- \`COALESCE\`, \`CASE\`, \`NULLIF\`, \`COUNT\`, \`SUM\`, \`AVG\`, \`MIN\`, \`MAX\` work identically`;
+
+const CLICKHOUSE_DIALECT_GUIDE = `
+
+## SQL Dialect: ClickHouse
+This database uses ClickHouse. Key differences from PostgreSQL:
+- Use \`toYear(col)\` and \`toMonth(col)\` instead of \`EXTRACT(YEAR FROM col)\`
+- Use \`formatDateTime(col, '%Y-%m')\` instead of \`TO_CHAR(col, 'YYYY-MM')\`
+- Use \`toString(col)\` for explicit string casts — no \`::text\` casting
+- Use \`toInt32(col)\`, \`toFloat64(col)\` for numeric casts — no \`::integer\` casting
+- Use \`ifNull(col, default)\` or \`COALESCE(col, default)\` — both work
+- \`arrayJoin(arr)\` unnests array columns into rows
+- No \`UPDATE\` or \`DELETE\` — ClickHouse is append-only OLAP
+- No foreign keys — joins are supported but there are no referential integrity constraints
+- \`count()\` instead of \`COUNT(*)\` — both work but \`count()\` is idiomatic
+- Use single quotes for strings, double quotes or backticks for identifiers
+- \`argMax(col, ordering_col)\` / \`argMin\` for "latest value" queries
+- Date arithmetic: \`today()\`, \`yesterday()\`, \`now()\`, \`toStartOfMonth(col)\`, \`toStartOfWeek(col)\`
+- \`COALESCE\`, \`CASE\`, \`COUNT\`, \`SUM\`, \`AVG\`, \`MIN\`, \`MAX\` work identically
+- Note: Atlas SQL validation uses PostgreSQL-compatible parsing. Avoid ClickHouse-only syntax (PREWHERE, LIMIT BY, WITH TOTALS) — use standard SQL equivalents instead
+- \`EXPLAIN\`, \`SHOW\`, and \`DESCRIBE\` are not available — use the explore tool to read entity schema files instead`;
+
+const SOQL_DIALECT_GUIDE = `
+
+## Query Language: Salesforce SOQL
+This datasource uses Salesforce Object Query Language (SOQL). Key differences from SQL:
+- **No JOINs** — use relationship queries instead:
+  - Child-to-parent: \`SELECT Account.Name FROM Contact\`
+  - Parent-to-child: \`SELECT Name, (SELECT LastName FROM Contacts) FROM Account\`
+- **Object names** instead of table names (e.g. \`Account\`, \`Contact\`, \`Opportunity\`)
+- **Field API names** — always use the API name (e.g. \`FirstName\`), not the label
+- **No wildcards** — \`SELECT *\` is not supported; list fields explicitly
+- **Date literals**: \`TODAY\`, \`YESTERDAY\`, \`LAST_WEEK\`, \`THIS_MONTH\`, \`LAST_N_DAYS:30\`, \`NEXT_N_DAYS:7\`
+- **Date functions**: \`CALENDAR_YEAR(CloseDate)\`, \`CALENDAR_MONTH(CloseDate)\`, \`DAY_IN_MONTH(CloseDate)\`
+- **Aggregate functions**: \`COUNT()\`, \`COUNT(Id)\`, \`SUM(Amount)\`, \`AVG(Amount)\`, \`MIN(Amount)\`, \`MAX(Amount)\`
+- **GROUP BY** works similarly to SQL: \`SELECT StageName, COUNT(Id) FROM Opportunity GROUP BY StageName\`
+- **HAVING** clause is supported for filtering aggregates
+- **LIMIT** and \`OFFSET\` are supported
+- **No subqueries in FROM** — subqueries only in WHERE (semi-joins): \`WHERE AccountId IN (SELECT Id FROM Account WHERE ...)\`
+- **No UNION, INTERSECT, EXCEPT**
+- Use the \`querySalesforce\` tool (not \`executeSQL\`) for all Salesforce queries`;
+
+const SNOWFLAKE_DIALECT_GUIDE = `
+
+## SQL Dialect: Snowflake
+This database uses Snowflake. Key differences from PostgreSQL:
+- \`ILIKE\` works for case-insensitive matching (same as PostgreSQL)
+- \`::type\` casting works (e.g. \`col::VARCHAR\`), plus \`TRY_CAST(col AS type)\` for safe casting that returns NULL on failure
+- Identifiers are case-insensitive by default; double-quoted identifiers are case-sensitive
+- Use \`FLATTEN()\` / \`LATERAL FLATTEN(input => col)\` to unnest semi-structured (VARIANT/ARRAY/OBJECT) data
+- \`QUALIFY\` clause filters window function results directly (e.g. \`QUALIFY ROW_NUMBER() OVER (...) = 1\`)
+- \`DATE_TRUNC('month', col)\` syntax (same as PostgreSQL)
+- No \`LIMIT offset, count\` — use \`LIMIT count OFFSET offset\`
+- Use \`LISTAGG(col, ', ')\` instead of \`STRING_AGG(col, ', ')\` or \`ARRAY_AGG(col)\` for aggregation
+- \`COALESCE\`, \`CASE\`, \`NULLIF\`, \`COUNT\`, \`SUM\`, \`AVG\`, \`MIN\`, \`MAX\` work identically`;
+
+const DUCKDB_DIALECT_GUIDE = `
+
+## SQL Dialect: DuckDB
+This database uses DuckDB, an in-process analytical engine. DuckDB's SQL is PostgreSQL-compatible with extensions:
+- \`::type\` casting works (e.g. \`col::INTEGER\`, \`col::VARCHAR\`) — same as PostgreSQL
+- \`ILIKE\` works for case-insensitive matching (same as PostgreSQL)
+- \`EXTRACT(YEAR FROM col)\`, \`DATE_TRUNC('month', col)\`, \`TO_CHAR(col, 'YYYY-MM')\` — same as PostgreSQL
+- \`STRING_AGG(col, ', ')\` works (same as PostgreSQL)
+- \`PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY col)\` works for percentile calculations
+- \`LIST_AGG\`, \`ARRAY_AGG\`, \`LIST()\` for array aggregation
+- \`UNNEST(list_col)\` to expand list/array columns into rows
+- Note: Atlas SQL validation uses PostgreSQL-compatible parsing. Avoid DuckDB-only syntax (QUALIFY, EXCLUDE, REPLACE, STRUCT_PACK, COLUMNS(*), COLUMNS(regex), STRUCT literals with curly braces) — use standard SQL equivalents instead
+- \`COALESCE\`, \`CASE\`, \`NULLIF\`, \`COUNT\`, \`SUM\`, \`AVG\`, \`MIN\`, \`MAX\` work identically`;
+
+function dialectName(dbType: DBType): string {
+  switch (dbType) {
+    case "postgres": return "PostgreSQL";
+    case "mysql": return "MySQL";
+    case "clickhouse": return "ClickHouse";
+    case "snowflake": return "Snowflake";
+    case "duckdb": return "DuckDB";
+    case "salesforce": return "Salesforce (SOQL)";
+    default: { const _: never = dbType; return _; }
+  }
+}
+
+function buildMultiSourceSection(
+  sources: ConnectionMetadata[],
+): string {
+  const lines = sources.map((s) => {
+    const dialect = dialectName(s.dbType);
+    const desc = s.description ? ` — ${s.description}` : "";
+    const healthNote = s.health?.status === "unhealthy"
+      ? " (**UNAVAILABLE** — skip queries to this source)"
+      : s.health?.status === "degraded"
+        ? " (currently degraded — queries may fail)"
+        : "";
+    return `- **${s.id}** (${dialect})${desc}${healthNote}`;
+  });
+  let section = `## Available Data Sources
+
+This environment has ${sources.length} database connections. Use the \`connectionId\` parameter in executeSQL to target the correct database.
+
+${lines.join("\n")}
+
+**Important:**
+- Always specify \`connectionId\` when querying a non-default source
+- Check entity YAML files for the \`connection\` field to see which tables belong to which source
+- Tables are scoped to their connection — a table on "warehouse" cannot be queried via "default"
+
+**Semantic layer navigation:**
+- Default connection entities are in \`entities/\` at the root
+- Other sources have their own subdirectory: \`{connectionId}/entities/\`
+- Start by running \`ls\` to see all available source directories
+- Each source may also have its own \`metrics/\` and \`glossary.yml\``;
+
+  // Surface cross-source relationships in the system prompt so the agent
+  // knows upfront which tables span sources and avoids impossible cross-DB JOINs.
+  let crossJoins: readonly CrossSourceJoin[];
+  try {
+    crossJoins = getCrossSourceJoins();
+  } catch (err) {
+    log.warn({ err: err instanceof Error ? err.message : String(err) }, "Failed to load cross-source joins — continuing without hints");
+    crossJoins = [];
+  }
+  if (crossJoins.length > 0) {
+    const joinLines = crossJoins.map((j) => {
+      const desc = j.description ? `${j.description} ` : "";
+      return `- **${j.fromSource}.${j.fromTable}** → **${j.toSource}.${j.toTable}**: ${desc}(${j.relationship}, on: ${j.on})`;
+    });
+    section += `\n\n## Cross-Source Relationships\n\n${joinLines.join("\n")}\n\nCross-source joins cannot be done in a single SQL query. Query each source separately and combine results in your analysis.`;
+  }
+
+  return section;
+}
+
+/**
+ * Collect Salesforce source metadata via dynamic import to avoid a hard
+ * dependency on the salesforce module (it may not be installed).
+ */
+function getSfSourceMeta(): ConnectionMetadata[] {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { describeSalesforceSources } = require("./db/salesforce") as {
+      describeSalesforceSources: () => ConnectionMetadata[];
+    };
+    return describeSalesforceSources();
+  } catch (err) {
+    // jsforce not installed — expected, don't log
+    if (err instanceof Error && err.message.includes("Cannot find module")) return [];
+    log.warn({ err: err instanceof Error ? err.message : String(err) }, "Failed to describe Salesforce sources");
+    return [];
+  }
+}
+
+function appendDialectHints(prompt: string): string {
+  const hints = getDialectHints();
+  if (hints.length === 0) return prompt;
+  return prompt + "\n\n## Additional SQL Dialect Notes\n\n" + hints.map((h) => h.dialect).join("\n\n");
+}
+
+function buildSystemPrompt(registry: ToolRegistry): string {
+  let base = SYSTEM_PROMPT_PREFIX + "\n\n" + registry.describe() + "\n\n" + SYSTEM_PROMPT_SUFFIX;
+
+  // Append the pre-indexed semantic layer summary
+  const semanticIndex = getSemanticIndex();
+  if (semanticIndex) {
+    base += "\n\n" + semanticIndex;
+  }
+
+  // Append plugin context fragments (if any)
+  const fragments = getContextFragments();
+  if (fragments.length > 0) {
+    base += "\n\n" + fragments.join("\n\n");
+  }
+  const connectionMeta = connections.describe();
+  const sfMeta = getSfSourceMeta();
+  const meta = [...connectionMeta, ...sfMeta];
+
+  // Single-connection: identical to pre-v0.7 behavior
+  if (meta.length <= 1) {
+    let dbType: DBType;
+    try {
+      dbType = meta.length === 1
+        ? meta[0].dbType
+        : detectDBType();
+    } catch (err) {
+      log.debug({ err: err instanceof Error ? err.message : String(err) }, "Could not detect DB type — omitting dialect guide");
+      return appendDialectHints(base);
+    }
+    switch (dbType) {
+      case "postgres": return appendDialectHints(base);
+      case "mysql": return appendDialectHints(base + MYSQL_DIALECT_GUIDE);
+      case "clickhouse": return appendDialectHints(base + CLICKHOUSE_DIALECT_GUIDE);
+      case "snowflake": return appendDialectHints(base + SNOWFLAKE_DIALECT_GUIDE);
+      case "duckdb": return appendDialectHints(base + DUCKDB_DIALECT_GUIDE);
+      case "salesforce": return appendDialectHints(base + SOQL_DIALECT_GUIDE);
+      default: { const _exhaustive: never = dbType; throw new Error(`Unknown: ${_exhaustive}`); }
+    }
+  }
+
+  // Multi-connection: list sources + include all relevant dialect guides
+  let prompt = base + "\n\n" + buildMultiSourceSection(meta);
+
+  const dbTypes = new Set(meta.map((m) => m.dbType));
+  if (dbTypes.has("mysql")) prompt += MYSQL_DIALECT_GUIDE;
+  if (dbTypes.has("clickhouse")) prompt += CLICKHOUSE_DIALECT_GUIDE;
+  if (dbTypes.has("snowflake")) prompt += SNOWFLAKE_DIALECT_GUIDE;
+  if (dbTypes.has("duckdb")) prompt += DUCKDB_DIALECT_GUIDE;
+  if (dbTypes.has("salesforce")) prompt += SOQL_DIALECT_GUIDE;
+
+  return appendDialectHints(prompt);
+}
+
+/**
+ * Build the system prompt with provider-appropriate cache control.
+ *
+ * The prompt body is composed from the registry's tool descriptions via
+ * `registry.describe()`, sandwiched between the standard prefix and suffix.
+ *
+ * - Anthropic / Bedrock-Anthropic: returns a SystemModelMessage with
+ *   `providerOptions.anthropic.cacheControl` (~80% savings on steps 2+).
+ * - Bedrock (non-Anthropic): returns a SystemModelMessage with
+ *   `providerOptions.bedrock.cachePoint`.
+ * - OpenAI / Ollama / Gateway: returns a plain string (OpenAI caches
+ *   automatically for prompts >= 1024 tokens; others have no caching).
+ */
+export function buildSystemParam(
+  providerType: ProviderType,
+  registry: ToolRegistry = defaultRegistry,
+): string | SystemModelMessage {
+  const content = buildSystemPrompt(registry);
+
+  switch (providerType) {
+    case "anthropic":
+    case "bedrock-anthropic":
+      return {
+        role: "system",
+        content,
+        providerOptions: {
+          anthropic: { cacheControl: { type: "ephemeral" } },
+        },
+      };
+    case "bedrock":
+      return {
+        role: "system",
+        content,
+        providerOptions: {
+          bedrock: { cachePoint: { type: "default" } },
+        },
+      };
+    case "openai":
+    case "ollama":
+    case "gateway":
+      return content;
+    default: {
+      const _exhaustive: never = providerType;
+      throw new Error(`Unknown provider type: ${_exhaustive}`);
+    }
+  }
+}
+
+/**
+ * Apply prompt caching to the last message in the conversation.
+ *
+ * This marks the last message with provider-specific cache control so that
+ * all preceding context (system prompt + earlier messages) can be cached
+ * by the LLM provider on subsequent steps.
+ *
+ * - Anthropic / Bedrock-Anthropic: `providerOptions.anthropic.cacheControl`
+ * - Bedrock (non-Anthropic): `providerOptions.bedrock.cachePoint`
+ * - OpenAI / Ollama / Gateway: no-op (OpenAI caches automatically)
+ */
+export function applyCacheControl(
+  messages: ModelMessage[],
+  providerType: ProviderType,
+): ModelMessage[] {
+  if (messages.length === 0) return messages;
+
+  // Only Anthropic-family and Bedrock need explicit cache markers
+  const lastIndex = messages.length - 1;
+
+  switch (providerType) {
+    case "anthropic":
+    case "bedrock-anthropic": {
+      return messages.map((message, index) => {
+        if (index !== lastIndex) return message;
+        return {
+          ...message,
+          providerOptions: {
+            ...message.providerOptions,
+            anthropic: { cacheControl: { type: "ephemeral" as const } },
+          },
+        } as typeof message;
+      });
+    }
+    case "bedrock": {
+      return messages.map((message, index) => {
+        if (index !== lastIndex) return message;
+        return {
+          ...message,
+          providerOptions: {
+            ...message.providerOptions,
+            bedrock: { cachePoint: { type: "default" as const } },
+          },
+        } as typeof message;
+      });
+    }
+    case "openai":
+    case "ollama":
+    case "gateway":
+      return messages;
+    default: {
+      const _exhaustive: never = providerType;
+      throw new Error(`Unknown provider type: ${_exhaustive}`);
+    }
+  }
+}
+
+/**
+ * Run the Atlas agent loop.
+ *
+ * @param messages - The conversation history from the chat UI.
+ * @param tools - Optional custom {@link ToolRegistry}. Defaults to
+ *   {@link defaultRegistry} (explore + executeSQL). The loop terminates
+ *   when the step limit (25) is reached or the model stops issuing tool calls.
+ */
+export async function runAgent({
+  messages,
+  tools: toolRegistry = defaultRegistry,
+}: {
+  messages: UIMessage[];
+  tools?: ToolRegistry;
+}) {
+  const model = getModel();
+  const providerType = getProviderType();
+
+  const span = tracer.startSpan("atlas.agent", {
+    attributes: { provider: providerType, messageCount: messages.length },
+  });
+
+  let spanEnded = false;
+  function endSpan(code: SpanStatusCode, message?: string) {
+    if (spanEnded) return;
+    spanEnded = true;
+    span.setStatus({ code, ...(message && { message }) });
+    span.end();
+  }
+
+  let result;
+  try {
+    result = streamText({
+      model,
+      system: buildSystemParam(providerType, toolRegistry),
+      messages: await convertToModelMessages(messages),
+      tools: toolRegistry.getAll(),
+      temperature: 0.2,
+      maxOutputTokens: 4096,
+      stopWhen: stepCountIs(25),
+      // totalMs: 180s for self-hosted (full agent loop budget).
+      // On Vercel, maxDuration caps the serverless function at 60s.
+      timeout: { totalMs: 180_000, stepMs: 30_000, chunkMs: 5_000 },
+
+      onError: ({ error }) => {
+        log.error(
+          { err: error instanceof Error ? error : new Error(String(error)) },
+          "stream error",
+        );
+        endSpan(
+          SpanStatusCode.ERROR,
+          error instanceof Error ? error.message : String(error),
+        );
+      },
+
+      prepareStep: ({ messages: stepMessages }) => {
+        return {
+          messages: applyCacheControl(stepMessages, providerType),
+        };
+      },
+
+      onStepFinish: ({ stepNumber, finishReason, usage }) => {
+        log.info(
+          {
+            step: stepNumber,
+            finishReason,
+            inputTokens: usage?.inputTokens,
+            outputTokens: usage?.outputTokens,
+            cacheRead: usage?.inputTokenDetails?.cacheReadTokens,
+            cacheWrite: usage?.inputTokenDetails?.cacheWriteTokens,
+          },
+          "step complete",
+        );
+      },
+
+      onFinish: ({ finishReason, totalUsage, steps }) => {
+        log.info(
+          {
+            finishReason,
+            totalSteps: steps.length,
+            totalInput: totalUsage?.inputTokens,
+            totalOutput: totalUsage?.outputTokens,
+            totalCacheRead: totalUsage?.inputTokenDetails?.cacheReadTokens,
+            totalCacheWrite: totalUsage?.inputTokenDetails?.cacheWriteTokens,
+          },
+          "agent finished",
+        );
+        span.setAttributes({
+          finishReason: finishReason ?? "",
+          totalSteps: steps.length,
+          totalInputTokens: totalUsage?.inputTokens ?? 0,
+          totalOutputTokens: totalUsage?.outputTokens ?? 0,
+        });
+        endSpan(SpanStatusCode.OK);
+      },
+    });
+  } catch (err) {
+    endSpan(
+      SpanStatusCode.ERROR,
+      err instanceof Error ? err.message : String(err),
+    );
+    throw err;
+  }
+
+  return result;
+}

package/templates/nextjs-standalone/src/lib/api-url.ts

@@ -0,0 +1,3 @@
+// Simplified: API is embedded via catch-all route — always same-origin.
+export const API_URL = "";
+export const IS_CROSS_ORIGIN = false;