@agent-native/core 0.145.4 → 0.145.6

package/dist/shared/runtime-config.js

@@ -0,0 +1,284 @@
+/**
+ * Production configuration diagnostics.
+ *
+ * This module deliberately accepts an env-like record instead of reading
+ * process.env so the same rules can run during a Vite build, on the server,
+ * and in focused tests without ever exposing secret values to the browser.
+ */
+const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const RUNTIME_CONFIG_ISSUE_CODES = new Set([
+    "auth-disabled-in-production",
+    "missing-auth-secret",
+    "weak-auth-secret",
+    "missing-a2a-secret",
+    "weak-a2a-secret",
+    "invalid-auth-url",
+    "missing-database-url",
+    "local-database-in-production",
+    "missing-required-env",
+]);
+export function runtimeConfigRequirementsFromSearchParams(searchParams) {
+    const requiredEnv = (searchParams.get("requiredEnv") ?? "")
+        .split(",")
+        .map((key) => key.trim())
+        .filter((key) => ENV_KEY_PATTERN.test(key))
+        .slice(0, 50);
+    return {
+        ...(searchParams.get("auth") === "0" ? { authEnabled: false } : {}),
+        ...(searchParams.get("database") === "0"
+            ? { databaseRequired: false }
+            : {}),
+        requiredEnv,
+    };
+}
+function valueOf(env, key) {
+    const value = env[key]?.trim();
+    return value || undefined;
+}
+function truthy(value) {
+    return value === "1" || value?.toLowerCase() === "true";
+}
+function isProductionEnvironment(env) {
+    return (valueOf(env, "NODE_ENV") === "production" ||
+        valueOf(env, "CONTEXT") === "production" ||
+        valueOf(env, "VERCEL_ENV") === "production");
+}
+function isWorkspaceRuntime(env) {
+    return (valueOf(env, "AGENT_NATIVE_WORKSPACE") === "1" ||
+        valueOf(env, "VITE_AGENT_NATIVE_WORKSPACE") === "1");
+}
+function appEnvPrefix(env, appName) {
+    const raw = appName ?? valueOf(env, "APP_NAME");
+    const prefix = raw?.toUpperCase().replace(/-/g, "_");
+    return prefix && ENV_KEY_PATTERN.test(prefix) ? prefix : undefined;
+}
+function databaseEnvKeys(env, appName) {
+    const keys = [];
+    const prefix = appEnvPrefix(env, appName);
+    if (prefix)
+        keys.push(`${prefix}_DATABASE_URL`);
+    keys.push("DATABASE_URL", "NETLIFY_DATABASE_URL");
+    return keys;
+}
+function configuredKey(env, keys) {
+    return keys.find((key) => valueOf(env, key));
+}
+function isLocalDatabaseUrl(url) {
+    return (url === "" ||
+        url.startsWith("file:") ||
+        url.startsWith("pglite:") ||
+        !url.includes("://"));
+}
+function isLoopbackUrl(url) {
+    try {
+        const hostname = new URL(url).hostname.toLowerCase();
+        return (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1");
+    }
+    catch {
+        // coercion-ok: malformed URLs are not loopback; validation reports the config issue.
+        return false;
+    }
+}
+function addIssue(issues, issue, environment) {
+    issues.push({
+        ...issue,
+        severity: issue.severity ?? (environment === "production" ? "error" : "warning"),
+    });
+}
+export function buildRuntimeConfigPrompt(report, appName) {
+    const appLine = appName ? `\nApp: ${appName}` : "";
+    const issueLines = report.issues
+        .map((issue) => `- ${issue.severity.toUpperCase()}: ${issue.title}. ${issue.message}`)
+        .join("\n");
+    return [
+        "Fix this Agent-Native deployment configuration issue.",
+        `Environment: ${report.environment}`,
+        `Phase: ${report.phase}${appLine}`,
+        "",
+        "Detected issues:",
+        issueLines || "- No issues were reported.",
+        "",
+        "Inspect the app's agent-native.json or agent-native.ts, its deployment configuration, and the framework defaults. Make the smallest safe fix. Keep secrets out of source control. Do not print secret values in your response. Tell me exactly which deploy settings still need to be set, then verify the production build and runtime health check.",
+    ].join("\n");
+}
+export function getRuntimeConfigReport(env, requirements = {}, options = {}) {
+    const environment = options.environment ??
+        (isProductionEnvironment(env) ? "production" : "development");
+    const phase = options.phase ?? "runtime";
+    const authEnabled = requirements.authEnabled ?? true;
+    const databaseRequired = requirements.databaseRequired ?? true;
+    const issues = [];
+    if (environment === "production") {
+        if (authEnabled) {
+            if (truthy(valueOf(env, "AUTH_DISABLED"))) {
+                addIssue(issues, {
+                    code: "auth-disabled-in-production",
+                    title: "Authentication is disabled in production",
+                    message: "AUTH_DISABLED is enabled. Unset it for a public deployment. Auth is enabled by default, so AUTH_DISABLED=false does not need to be added.",
+                    envKeys: ["AUTH_DISABLED"],
+                }, environment);
+            }
+            const authSecret = valueOf(env, "BETTER_AUTH_SECRET");
+            const workspaceSecret = valueOf(env, "A2A_SECRET");
+            const hasAuthSecret = Boolean(authSecret);
+            const hasWorkspaceSecret = Boolean(workspaceSecret);
+            if (!hasAuthSecret && !(isWorkspaceRuntime(env) && hasWorkspaceSecret)) {
+                addIssue(issues, {
+                    code: "missing-auth-secret",
+                    title: "BETTER_AUTH_SECRET is not set for production",
+                    message: "Set BETTER_AUTH_SECRET in the deployment environment, using a fresh value from `openssl rand -hex 32`. The public auth URL is inferred from APP_URL, known template or request context, and platform metadata such as Netlify or Vercel; AUTH_DISABLED defaults to false, so neither URL nor bypass flag needs to be prefilled.",
+                    envKeys: ["BETTER_AUTH_SECRET"],
+                }, environment);
+            }
+            if (authSecret && authSecret.length < 32) {
+                addIssue(issues, {
+                    code: "weak-auth-secret",
+                    title: "BETTER_AUTH_SECRET is too short",
+                    message: "Use a fresh random BETTER_AUTH_SECRET with at least 32 characters, such as the output of `openssl rand -hex 32`.",
+                    envKeys: ["BETTER_AUTH_SECRET"],
+                }, environment);
+            }
+            const explicitAuthUrl = valueOf(env, "APP_URL") ?? valueOf(env, "BETTER_AUTH_URL");
+            if (explicitAuthUrl) {
+                let invalid = false;
+                try {
+                    const parsed = new URL(explicitAuthUrl);
+                    invalid = !["http:", "https:"].includes(parsed.protocol);
+                }
+                catch {
+                    invalid = true;
+                }
+                if (isLoopbackUrl(explicitAuthUrl))
+                    invalid = true;
+                if (invalid) {
+                    addIssue(issues, {
+                        code: "invalid-auth-url",
+                        title: "The public auth URL is not deployable",
+                        message: "APP_URL or BETTER_AUTH_URL must be an absolute public http(s) URL. Leave them unset when the platform URL should be inferred.",
+                        envKeys: ["APP_URL", "BETTER_AUTH_URL"],
+                    }, environment);
+                }
+            }
+        }
+        const workspaceSecret = valueOf(env, "A2A_SECRET");
+        if (isWorkspaceRuntime(env) && !workspaceSecret) {
+            addIssue(issues, {
+                code: "missing-a2a-secret",
+                title: "The workspace runtime needs A2A_SECRET",
+                message: "Set A2A_SECRET for trusted internal calls and the workspace's derived auth and OAuth secrets.",
+                envKeys: ["A2A_SECRET"],
+            }, environment);
+        }
+        if (isWorkspaceRuntime(env) &&
+            workspaceSecret &&
+            workspaceSecret.length < 32) {
+            addIssue(issues, {
+                code: "weak-a2a-secret",
+                title: "A2A_SECRET is too short",
+                message: "Use a fresh random A2A_SECRET with at least 32 characters, such as the output of `openssl rand -hex 32`.",
+                envKeys: ["A2A_SECRET"],
+            }, environment);
+        }
+        if (databaseRequired) {
+            const dbKeys = databaseEnvKeys(env, options.appName);
+            const dbKey = configuredKey(env, dbKeys);
+            const dbUrl = dbKey ? valueOf(env, dbKey) : undefined;
+            if (!dbUrl) {
+                addIssue(issues, {
+                    code: "missing-database-url",
+                    title: "Production has no persistent database URL",
+                    message: `Set ${dbKeys.join(", ")} to a persistent SQL database. Local SQLite is a development fallback and is not safe for a serverless production deploy.`,
+                    envKeys: dbKeys,
+                }, environment);
+            }
+            else if (dbKey && isLocalDatabaseUrl(dbUrl)) {
+                addIssue(issues, {
+                    code: "local-database-in-production",
+                    title: "Production is using a local database",
+                    message: `${dbKey} resolves to a local database. Use a persistent remote SQL URL for deploys so auth and app state survive new instances.`,
+                    envKeys: [dbKey],
+                }, environment);
+            }
+        }
+    }
+    for (const key of requirements.requiredEnv ?? []) {
+        if (!ENV_KEY_PATTERN.test(key) || valueOf(env, key))
+            continue;
+        addIssue(issues, {
+            code: "missing-required-env",
+            title: `${key} is not configured`,
+            message: `The app declares ${key} as required. Set it in the local or deployment environment, or remove it from the app configuration if the feature is not used.`,
+            envKeys: [key],
+        }, environment);
+    }
+    const status = issues.some((issue) => issue.severity === "error")
+        ? "error"
+        : issues.length > 0
+            ? "warning"
+            : "ok";
+    const report = {
+        ok: issues.length === 0,
+        status,
+        environment,
+        phase,
+        issues,
+        prompt: "",
+    };
+    report.prompt = buildRuntimeConfigPrompt(report, options.appName);
+    return report;
+}
+export function formatRuntimeConfigReport(report) {
+    if (report.issues.length === 0) {
+        return `[agent-native] ${report.environment} runtime configuration is ready.`;
+    }
+    const heading = report.status === "error"
+        ? "configuration errors"
+        : "configuration warnings";
+    const issueLines = report.issues
+        .map((issue) => `  - ${issue.severity.toUpperCase()}: ${issue.title}. ${issue.message}`)
+        .join("\n");
+    return [
+        `[agent-native] ${report.environment} ${heading}:`,
+        issueLines,
+        "",
+        "Copy the prompt below to an AI coding agent for guided remediation:",
+        report.prompt,
+    ].join("\n");
+}
+export function parseRuntimeConfigReport(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const report = value;
+    if ((report.status !== "ok" &&
+        report.status !== "warning" &&
+        report.status !== "error") ||
+        (report.environment !== "development" &&
+            report.environment !== "production") ||
+        (report.phase !== "build" && report.phase !== "runtime") ||
+        !Array.isArray(report.issues) ||
+        typeof report.prompt !== "string") {
+        return null;
+    }
+    const issues = report.issues;
+    if (typeof report.ok !== "boolean" ||
+        !issues.every((issue) => !!issue &&
+            typeof issue === "object" &&
+            RUNTIME_CONFIG_ISSUE_CODES.has(issue.code) &&
+            (issue.severity === "warning" ||
+                issue.severity === "error") &&
+            typeof issue.title === "string" &&
+            typeof issue.message === "string" &&
+            Array.isArray(issue.envKeys) &&
+            issue.envKeys.every((key) => typeof key === "string"))) {
+        return null;
+    }
+    const expectedStatus = issues.some((issue) => issue.severity === "error")
+        ? "error"
+        : issues.length > 0
+            ? "warning"
+            : "ok";
+    if (report.ok !== (issues.length === 0) || report.status !== expectedStatus) {
+        return null;
+    }
+    return report;
+}

package/dist/styles/agent-native.css

@@ -179,6 +179,12 @@
   background: transparent;
 }
 
+.agent-sidebar-drawer-placeholder {
+  height: 100%;
+  min-width: 0;
+  pointer-events: none;
+}
+
 .agent-layout-main-surface,
 .agent-sidebar-main-surface {
   position: relative;
@@ -297,6 +303,26 @@
   transition: transform 260ms var(--ease-drawer);
 }
 
+/* The wide preset keeps the normal sidebar slot in flow while its panel
+   overlays the page as a fixed drawer. View Transitions morph the geometry
+   when available; these transforms provide the fallback and exit motion. */
+.agent-sidebar-panel[data-agent-sidebar-animation="drawer"] {
+  overflow: clip;
+  will-change: transform;
+  box-shadow: -12px 0 30px hsl(var(--foreground) / 0.08);
+  transition:
+    transform 260ms var(--ease-drawer),
+    width 260ms var(--ease-drawer);
+}
+
+.agent-sidebar-panel[data-agent-sidebar-animation="drawer"][data-agent-sidebar-state="closed"][data-agent-sidebar-position="right"] {
+  transform: translateX(100%);
+}
+
+.agent-sidebar-panel[data-agent-sidebar-animation="drawer"][data-agent-sidebar-state="closed"][data-agent-sidebar-position="left"] {
+  transform: translateX(-100%);
+}
+
 .agent-sidebar-panel[data-agent-sidebar-animation="desktop"][data-agent-sidebar-state="open"]
   > .agent-sidebar-panel-inner {
   transform: translateX(0);
@@ -364,6 +390,7 @@
   .agent-sidebar-panel[data-agent-sidebar-animation],
   .agent-sidebar-panel[data-agent-sidebar-animation="desktop"]
     > .agent-sidebar-panel-inner,
+  .agent-sidebar-panel[data-agent-sidebar-animation="drawer"],
   .agent-sidebar-backdrop[data-agent-sidebar-animation] {
     transition: none;
   }
@@ -935,6 +962,21 @@
   width: 100%;
 }
 
+/* Tool-call rows are rendered in several disclosure/grouping shapes as the
+   stream grows. Keep the motion wrapper layout-transparent, while its short
+   lived exit clones can travel from the visible stack into the summary row. */
+.agent-tool-call-stack {
+  display: contents;
+}
+
+.agent-tool-call-stack__exit {
+  box-sizing: border-box;
+  position: fixed;
+  z-index: 2;
+  pointer-events: none;
+  margin: 0 !important;
+}
+
 [data-agent-empty-state="centered"] {
   justify-content: center;
   padding-bottom: clamp(3rem, 8vh, 6rem);
@@ -978,10 +1020,15 @@
 }
 
 @media (prefers-reduced-motion: no-preference) {
-  .agent-tool-call--entering {
+  .agent-tool-call--entering > .agent-tool-call__content,
+  .agent-tool-call--stack-entering > .agent-tool-call__content {
     animation: agent-tool-call-enter 220ms var(--ease-out-strong) both;
   }
 
+  .agent-tool-summary__label {
+    display: inline-block;
+  }
+
   @supports ((background-clip: text) or (-webkit-background-clip: text)) {
     .agent-thinking-indicator__text,
     .agent-running-shimmer {

package/dist/templates/chat/.agents/skills/actions/SKILL.md

@@ -20,6 +20,24 @@ Before creating any custom REST/API route for app data, inspect `actions/` and t
 
 **Stop trigger:** the moment you are about to create a file under `server/routes/api/` — or add server middleware to guard one — stop and check it against the exception list in *When You Still Need Custom `/api/` Routes* below. If it is not on that list, write a `defineAction` instead. This applies even when you already started the route; abandoning a half-written action to hand-roll routes is the exact failure this rule exists to prevent.
 
+## Keep actions deterministic and composable
+
+An action may call a provider API, validate or normalize data, and persist
+records without being an AI feature. Keep those operations deterministic,
+focused, and independently useful to the agent. Do not put LLM calls or a
+second model runtime in ordinary actions. The only narrow exception is the
+`completeText()` text-in/text-out escape hatch described in
+`delegate-to-agent`; it must not own tools, chat history, run state, side
+effects, or user steering.
+
+When a workflow is framed as research, analysis, generation, recommendation,
+or synthesis, or spans several provider calls and writes, route the user into
+the AgentSidebar and let the agent orchestrate focused actions. Do not hide an
+AI-shaped workflow behind one opaque `generate-*` or `create-*` action just
+because its implementation is deterministic. A visible user-initiated run
+should use `sendToAgentChat({ openSidebar: true })`, and its follow-ups should
+continue in the same thread rather than a separate freeform input.
+
 ## Why
 
 Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.

package/dist/templates/chat/.agents/skills/agent-native-toolkit/SKILL.md

@@ -56,6 +56,11 @@ The repeated app shell has two distinct navigation surfaces:
   labeled as local, preview, or analyze. For original/generated review, stack
   the source above the result by default and use side-by-side only for short,
   highly scannable content.
+- Deterministic implementation does not make an AI-shaped experience
+  deterministic. If the user expects research, analysis, generation,
+  recommendation, synthesis, visible progress, or steering, route the button
+  to the AgentSidebar and let the agent call focused actions. Keep revisions in
+  the same thread instead of adding a second freeform prompt box.
 - Standalone apps with `AgentSidebar` must resolve one assistant-ui runtime
   context. Match direct assistant-ui pins to the installed core/toolkit peer
   graph, use Vite dedupe/aliases when linked dependencies can split contexts,

package/dist/templates/chat/.agents/skills/delegate-to-agent/SKILL.md

@@ -14,11 +14,21 @@ metadata:
 
 ## Rule
 
-The UI never calls an LLM directly. Product workflows are delegated to the
-agent through the chat bridge so users can see, steer, and audit the work.
-Server-side one-shot model calls are an explicit escape hatch for narrow text
-transforms only; use `completeText()` from `@agent-native/core/server` when the
-work intentionally does not need tools, chat history, or run state.
+The app's default AI surface is the agent chat. Any user-facing work that asks
+the model to research, analyze, generate, recommend, synthesize, or reason over
+multiple steps must start or continue in the AgentSidebar so users can see,
+steer, and audit the work. UI buttons use `sendToAgentChat()` with
+`openSidebar: true`, and follow-up or revision text belongs in that same thread
+instead of a second app-local textbox.
+
+Actions are tools, not alternate AI runtimes. Keep them deterministic and
+focused: provider reads, validation, deterministic transforms, CRUD, and
+persistence are good action work. Let the agent orchestrate several such tools
+when the workflow is AI-shaped or user-steerable. Server-side one-shot model
+calls are a rare escape hatch for narrow text transforms only; use
+`completeText()` from `@agent-native/core/server` only when the work
+intentionally does not need tools, chat history, run state, side effects, or
+user steering.
 
 ## Why
 
@@ -35,6 +45,7 @@ sendToAgentChat({
   message: "Generate a summary of this document",
   context: documentContent, // optional hidden context (not shown in chat UI)
   submit: true, // auto-submit to the agent
+  openSidebar: true,
 });
 ```
 
@@ -56,6 +67,10 @@ sendToAgentChat({
 This is still a full agent run: tools, actions, thread state, and run tracking
 all remain active. It simply does not focus or open the sidebar.
 
+Use this silent form only for explicitly background or system-initiated work.
+It is not the default for a user clicking an AI-labeled button; visible work
+should open the sidebar so the user can follow and redirect the run.
+
 **From scripts (Node):**
 
 ```ts
@@ -77,8 +92,9 @@ const result = await completeText({
 });
 ```
 
-Wrap user-facing uses in actions so the UI and agent share the same operation.
-Do not call provider SDKs directly.
+If the narrow exception is exposed to the UI, wrap it in an action so the UI
+and agent share the same operation. Keep it clearly non-conversational and do
+not call provider SDKs directly.
 
 **From the UI, detecting when agent is done:**
 
@@ -97,9 +113,9 @@ The `submit` option controls whether the message is sent automatically or placed
 
 | `submit` value | Behavior                                | Use when                                                                            |
 | -------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
-| `true`         | Auto-submits to the agent immediately   | Routine operations the user has already approved                                    |
-| `false`        | Prefills the chat input for user review | High-stakes operations (deleting data, modifying code, API calls with side effects) |
-| omitted        | Uses the project's default setting      | General-purpose delegation                                                          |
+| `true`         | Auto-submits to the agent immediately   | Routine operations with clear intent; keep `openSidebar: true` for visible work |
+| `false`        | Prefills the AgentSidebar composer      | Review, edit, or add detail before the run; use the existing sidebar thread   |
+| omitted        | Uses the project's default setting      | General-purpose delegation                                                       |
 
 ```ts
 // Auto-submit: routine operation
@@ -109,61 +125,43 @@ sendToAgentChat({ message: "Update the project summary", submit: true });
 sendToAgentChat({
   message: "Delete all projects older than 30 days",
   submit: false,
+  openSidebar: true,
 });
 ```
 
-## Capture user input first when generating from a prompt
-
-Buttons that produce new content ("New Design", "Create Dashboard", "Make Deck", "Generate Form") need the user's prompt as input. **Never hardcode a generic message** — the result will be a generic generation the user didn't actually ask for.
+## Capture user input in the sidebar
 
-**Bad** — auto-submits a placeholder message; the user never said what they wanted:
+The AgentSidebar composer is the default prompt surface. When a button needs
+the user to describe what to create, prefill that same composer and let the
+user edit or complete it:
 
 ```tsx
 <Button
   onClick={() =>
-    sendToAgentChat({ message: "make a design", submit: true })
+    sendToAgentChat({
+      message: "Help me create a research report from this brief:",
+      context: researchBrief,
+      submit: false,
+      openSidebar: true,
+    })
   }
 >
-  New Design
+  Start in agent
 </Button>
 ```
 
-**Good** — Popover anchored to the button captures the prompt, then submits it:
-
-```tsx
-<Popover open={open} onOpenChange={setOpen}>
-  <PopoverTrigger asChild>
-    <Button>New Design</Button>
-  </PopoverTrigger>
-  <PopoverContent className="w-96">
-    <Textarea
-      autoFocus
-      value={prompt}
-      onChange={(e) => setPrompt(e.target.value)}
-      placeholder="What do you want to design?"
-    />
-    <Button
-      onClick={() => {
-        sendToAgentChat({ message: prompt, submit: true });
-        setOpen(false);
-        setPrompt("");
-      }}
-    >
-      Create
-    </Button>
-  </PopoverContent>
-</Popover>
-```
-
-**Always ask for input first when** the output depends on a prompt the user must provide — "design what?", "deck about what?", "dashboard for which metric?", "form for which use case?".
-
-**Auto-submit without input is fine when intent is unambiguous:**
+Never auto-submit a generic creative prompt when the user has not said what
+they want. Auto-submit without additional input is fine when intent is
+unambiguous:
 
 - "Try to fix" on a tool error — submits the error details with a clear fix instruction
 - "Retry the last operation" after a transient failure
 - Single-purpose buttons where there is nothing meaningful for the user to add
 
-If you find yourself writing `submit: true` with a hardcoded creative verb (`"design a..."`, `"write a..."`, `"build a..."`), stop and add a Popover.
+Use a Popover only for compact, structured parameters the UI must validate,
+such as a date range, target, or approval choice. Do not add a second freeform
+prompt or follow-up textbox for an AI workflow; keep the conversation and
+revisions in the AgentSidebar thread.
 
 ## Delegating to a Sub-Agent (Agent Teams)
 

package/dist/templates/chat/.agents/skills/frontend-design/SKILL.md

@@ -130,6 +130,7 @@ passed this requirement yet.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
 - Custom styles belong in Tailwind classes, component CSS, or the existing global CSS theme file; avoid inline styles.