@agent-native/core 0.75.4 → 0.76.0

package/corpus/core/src/agent/durable-background.ts

@@ -63,45 +63,79 @@ export const AGENT_CHAT_PROCESS_RUN_PATH =
 export const AGENT_BACKGROUND_FUNCTION_NAME = "server-agent-background";
 
 /**
- * Default function URL of the background function on Netlify, kept for
- * diagnostics/tests. Every Netlify function is ALSO reachable at
- * `/.netlify/functions/<name>` unless a custom `config.path` removes the default
- * url. The emitted background function declares `config.path =
- * AGENT_CHAT_PROCESS_RUN_PATH`, which means Netlify routes the process-run path
- * to it directly AND (per Netlify docs) removes this default url — so the
- * foreground does NOT dispatch here; it dispatches to the framework route (see
- * `resolveAgentChatProcessRunDispatchPath`). This constant is retained only so
- * the name/url shape stays asserted and discoverable.
+ * Default function URL of the background function on Netlify. Every Netlify
+ * function is reachable at `/.netlify/functions/<name>` BY DEFAULT; that default
+ * url is removed ONLY if the function declares a custom `config.path`. The
+ * emitted background function declares NO custom `config.path` (it sets
+ * `background: true` and nothing else routing-related), so it KEEPS this default
+ * url — and the Nitro `server` function already excludes `/.netlify/*` from its
+ * `/*` catch-all, so this namespace is never shadowed. The foreground therefore
+ * dispatches HERE on hosted Netlify (see `resolveAgentChatProcessRunDispatchPath`).
  */
 export const AGENT_BACKGROUND_FUNCTION_URL_PATH = `/.netlify/functions/${AGENT_BACKGROUND_FUNCTION_NAME}`;
 
+/**
+ * The per-app workspace background function URL path. Workspace deploy emits one
+ * background function per app named `<app>-agent-background`, reachable at its
+ * DEFAULT url `/.netlify/functions/<app>-agent-background` (no custom
+ * `config.path`). The foreground resolves the current workspace app id from
+ * `AGENT_NATIVE_WORKSPACE_APP_ID` (set by the workspace function entry) so it can
+ * dispatch to the right per-app function url. Returns `null` when no workspace
+ * app id is configured (single-template deploy).
+ */
+function resolveWorkspaceBackgroundFunctionUrlPath(): string | null {
+  const raw = process.env.AGENT_NATIVE_WORKSPACE_APP_ID;
+  if (typeof raw !== "string") return null;
+  // Mirror the workspace app-id normalization (resources/store.ts): take the
+  // first path segment and accept only the safe slug shape used for function
+  // names. Anything else falls back to the single-template name.
+  const candidate = raw.trim().replace(/^\/+/, "").split("/")[0] ?? "";
+  if (!/^[a-z0-9][a-z0-9-]{0,127}$/.test(candidate)) return null;
+  return `/.netlify/functions/${candidate}-agent-background`;
+}
+
 /**
  * Resolve the path the foreground POST should self-dispatch the chat background
  * worker to.
  *
- * GROUNDED IN THE REAL NETLIFY BUILD OUTPUT: the background function is emitted
- * INTO the scanned dir (`.netlify/functions-internal/server-agent-background`)
- * with `export const config = { background: true, path:
- * AGENT_CHAT_PROCESS_RUN_PATH }`. Netlify evaluates serverless functions BEFORE
- * redirects (request-chain step 10 vs 11), and the build excludes this exact path
- * from the `server` `/*` catch-all — so a POST to `AGENT_CHAT_PROCESS_RUN_PATH`
- * matches ONLY the async background function (immediate 202, 15-min budget),
- * never the synchronous `server` catch-all.
+ * GROUNDED IN THE REAL NETLIFY BUILD OUTPUT + THE NETLIFY DOCS DEFAULT-URL RULE:
+ * the background function is emitted INTO the scanned dir
+ * (`.netlify/functions-internal/server-agent-background`, or per-app
+ * `<app>-agent-background` for workspaces) with `export const config = {
+ * background: true, ... }` and NO custom `config.path`. Because it has no custom
+ * path, Netlify keeps its DEFAULT function url `/.netlify/functions/<name>`, and
+ * `background: true` makes any invocation of that url ASYNC (immediate 202,
+ * 15-min budget). The Nitro `server` function already excludes `/.netlify/*`
+ * from its `/*` catch-all, so the default-url namespace is NEVER shadowed by the
+ * synchronous function.
  *
- * So the dispatch path is the SAME framework route on every host. On hosted
- * Netlify it lands on the async function (because of the exclude + the
- * background function's `config.path`); everywhere else (local dev, `netlify
- * dev`, non-Netlify hosts where no second function exists) the same in-process
- * catch-all handles it inline. The HMAC token (signed over the runId) is
- * unchanged.
+ * Therefore on hosted Netlify the foreground dispatches to the function's DEFAULT
+ * url (`/.netlify/functions/<name>`); the function entry then rewrites the
+ * incoming pathname to `AGENT_CHAT_PROCESS_RUN_PATH` (base-path-prefixed for
+ * workspaces) before delegating to the Nitro router, so the `_process-run`
+ * plugin runs with the async 15-min budget. Everywhere else (local dev, `netlify
+ * dev`, non-Netlify hosts where no second function exists) there is no second
+ * function, so the foreground dispatches to the framework route
+ * `AGENT_CHAT_PROCESS_RUN_PATH` and the same in-process catch-all handles it
+ * inline. The HMAC token (signed over the runId) is unchanged either way.
  *
- * NOTE: this is a deliberate change from the earlier "dispatch to the direct
- * `/.netlify/functions/<name>` url" attempt, which only worked if the function
- * was reachable at its default url. With a custom `config.path` the default url
- * is removed, and there is no shadowing to bypass anyway, so dispatching to the
- * framework route is both correct and simpler.
+ * NOTE: this is the DOC-CORRECT approach. An earlier attempt gave the function a
+ * custom `config.path` + a catch-all `excludedPath` patch; the custom path was
+ * NOT honored as a route in prod (probe → 404). Using the default function url
+ * (no custom path) is what Netlify documents and is simpler — there is nothing
+ * to shadow because `/.netlify/*` is already excluded from the `server` catch-all.
  */
 export function resolveAgentChatProcessRunDispatchPath(): string {
+  if (
+    process.env.NETLIFY &&
+    process.env.NETLIFY !== "false" &&
+    process.env.NETLIFY_LOCAL !== "true"
+  ) {
+    return (
+      resolveWorkspaceBackgroundFunctionUrlPath() ??
+      AGENT_BACKGROUND_FUNCTION_URL_PATH
+    );
+  }
   return AGENT_CHAT_PROCESS_RUN_PATH;
 }
 

package/corpus/core/src/agent/production-agent.ts

@@ -4394,13 +4394,16 @@ export function createProductionAgentHandler(
       try {
         await fireInternalDispatch({
           event,
-          // The framework `_process-run` route on every host. On hosted Netlify
-          // the build emits an async background function (in the scanned dir)
-          // that CLAIMS this exact path via `config.path` AND excludes it from
-          // the `server` /* catch-all, so this POST matches ONLY the async
-          // function (immediate 202, 15-min budget) — Netlify matches functions
-          // before redirects. Off-Netlify the same in-process catch-all handles
-          // it. The Authorization Bearer HMAC is preserved either way.
+          // On hosted Netlify this resolves to the background function's DEFAULT
+          // url (/.netlify/functions/<name>, or per-app <app>-agent-background for
+          // workspaces) — the function declares NO custom config.path, so it keeps
+          // its default url, and `background: true` makes that url async (202,
+          // 15-min budget). The `server` /* catch-all already excludes /.netlify/*
+          // so it never shadows it. Off-Netlify this resolves to the framework
+          // `_process-run` route and the same in-process catch-all handles it
+          // inline. `fireInternalDispatch` strips the app base path for
+          // /.netlify/* targets so the request reaches the host-root function url;
+          // the Authorization Bearer HMAC is preserved either way.
           path: resolveAgentChatProcessRunDispatchPath(),
           taskId: runId,
           body: {
@@ -4643,11 +4646,12 @@ export function createProductionAgentHandler(
                 try {
                   await fireInternalDispatch({
                     event,
-                    // Continuation chunks dispatch to the same framework
-                    // `_process-run` route; on hosted Netlify it matches the
-                    // async background function (config.path + excluded from the
-                    // /* catch-all) so each chunk keeps the 15-min budget. Same
-                    // path-resolution as the initial dispatch.
+                    // Continuation chunks use the same path resolution as the
+                    // initial dispatch: on hosted Netlify the background
+                    // function's DEFAULT url (no custom config.path; async via
+                    // background:true; never shadowed because /.netlify/* is
+                    // excluded from the /* catch-all) so each chunk keeps the
+                    // 15-min budget; off-Netlify the in-process framework route.
                     path: resolveAgentChatProcessRunDispatchPath(),
                     taskId: nextRunId,
                     body: {

package/corpus/core/src/cli/skills.ts

@@ -526,6 +526,13 @@ themes. For any inline border, background, or text color, reference a token:
 and \`--wf-radius\`. Never hard-code a hex color and never set \`font-family\` — the
 renderer owns the sketch/clean font.
 
+**Use literal CSS lengths for spacing.** The \`--wf-*\` tokens are for colors and
+renderer-owned visual styling, not layout spacing. Do not use guessed spacing
+tokens such as \`var(--wf-space-4)\`, Tailwind spacing classes, or theme spacing
+variables inside wireframe HTML; if a token is unavailable in the Plan renderer,
+padding collapses and content hugs the border. Use explicit CSS lengths for
+layout: \`padding:16px\`, \`gap:12px\`, \`margin-top:18px\`, \`minmax(0,1fr)\`.
+
 **Lay out with inline \`style\` flex/grid.** You write the real layout —
 \`display:flex; flex-direction:column; gap:10px; padding:16px\` and so on — and the
 renderer never repositions anything. Compose the actual product: reproduce the
@@ -610,10 +617,21 @@ check/serve or verify command for \`<plan-dir>\`.
 **Treat the wireframe border as part of the visible design.** Always wrap HTML
 wireframe content in a root container with real inner padding before drawing
 cards, fields, pills, labels, or controls. Use at least 14-16px of padding,
-\`box-sizing: border-box\`, \`height: 100%\`, and \`gap\` between child rows so the
-first row never sits flush against the screen border. Keep text away from
-borders: every container, field, button, menu item, and annotation needs enough
-padding and line-height to read cleanly in the rendered Plan view.
+\`box-sizing: border-box\`, \`height: 100%\`, and \`gap\` between child rows on the
+root node itself so the first row never sits flush against the screen border. Do
+not rely on padding on a nested page section as the first visible inset; the
+outermost element must create the breathing room. Keep text away from borders:
+every container, field, button, menu item, and annotation needs enough padding
+and line-height to read cleanly in the rendered Plan view.
+
+**For feature-cloud or abundance visuals, optimize the composition over line-by-line
+reading.** Some marketing/product sections need to feel like a large surface area
+of capability rather than a precise app workflow. In those cases, use one padded
+root with a short headline and a dense, aesthetic cloud of short feature labels,
+chips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,
+and let many labels be glanceable rather than individually essential. Do not
+force dozens of features into equal cards with long wrapped sentences; that
+usually creates a messy unreadable mockup.
 
 **Lay out children safely so they never collide.** Use HTML flex/grid with
 \`gap\`, \`min-width: 0\`, and sensible overflow. Avoid negative margins, absolute

package/corpus/core/src/client/CommandMenu.tsx

@@ -63,6 +63,22 @@ export function openAgentSidebar() {
   window.dispatchEvent(new Event("agent-panel:open"));
 }
 
+export function openAgentSettings(
+  section?: string | { section?: string | null },
+) {
+  if (typeof window === "undefined") return;
+
+  const normalizedSection =
+    typeof section === "string" ? section : section?.section;
+
+  openAgentSidebar();
+  window.dispatchEvent(
+    new CustomEvent("agent-panel:open-settings", {
+      detail: normalizedSection ? { section: normalizedSection } : undefined,
+    }),
+  );
+}
+
 export function focusAgentChat() {
   window.dispatchEvent(
     new CustomEvent("agent-panel:set-mode", {

package/corpus/core/src/client/app-providers.tsx

@@ -53,6 +53,10 @@ import { TooltipProvider } from "@radix-ui/react-tooltip";
 import { Toaster } from "sonner";
 import { ClientOnly } from "./ClientOnly.js";
 import { DefaultSpinner } from "./DefaultSpinner.js";
+import {
+  AgentNativeI18nProvider,
+  type AgentNativeI18nProviderProps,
+} from "./i18n.js";
 
 export interface AppProvidersProps {
   /** QueryClient instance — create with `createAgentNativeQueryClient()`. */
@@ -94,6 +98,13 @@ export interface AppProvidersProps {
    */
   disableThemeTransitions?: boolean;
 
+  /**
+   * Optional localization runtime configuration. When omitted, AppProviders
+   * still mounts the i18n provider with an English fallback so templates can
+   * call useT/useLocale before they add catalogs. Pass false to opt out.
+   */
+  i18n?: Omit<AgentNativeI18nProviderProps, "children"> | false;
+
   /**
    * When true the providers render without a `<ClientOnly>` gate so SSR
    * streams real markup for public/unauthenticated paths.
@@ -119,6 +130,7 @@ function ProvidersInner({
   tooltipDelayDuration,
   toaster = DEFAULT_TOASTER,
   disableThemeTransitions = true,
+  i18n,
   children,
 }: {
   queryClient: QueryClient;
@@ -127,8 +139,18 @@ function ProvidersInner({
   tooltipDelayDuration?: number;
   toaster?: React.ReactNode | null;
   disableThemeTransitions?: boolean;
+  i18n?: Omit<AgentNativeI18nProviderProps, "children"> | false;
   children: React.ReactNode;
 }) {
+  const localizedChildren =
+    i18n === false ? (
+      children
+    ) : (
+      <AgentNativeI18nProvider {...(i18n ?? {})}>
+        {children}
+      </AgentNativeI18nProvider>
+    );
+
   return (
     <QueryClientProvider client={queryClient}>
       <ThemeProvider
@@ -138,7 +160,7 @@ function ProvidersInner({
         disableTransitionOnChange={disableThemeTransitions}
       >
         <TooltipProvider delayDuration={tooltipDelayDuration}>
-          {children}
+          {localizedChildren}
           {toaster}
         </TooltipProvider>
       </ThemeProvider>
@@ -155,6 +177,7 @@ export function AppProviders({
   tooltipDelayDuration,
   toaster,
   disableThemeTransitions,
+  i18n,
   children,
 }: AppProvidersProps) {
   const fallback = clientOnlyFallback ?? <DefaultSpinner />;
@@ -168,6 +191,7 @@ export function AppProviders({
         tooltipDelayDuration={tooltipDelayDuration}
         toaster={toaster}
         disableThemeTransitions={disableThemeTransitions}
+        i18n={i18n}
       >
         {children}
       </ProvidersInner>
@@ -183,6 +207,7 @@ export function AppProviders({
         tooltipDelayDuration={tooltipDelayDuration}
         toaster={toaster}
         disableThemeTransitions={disableThemeTransitions}
+        i18n={i18n}
       >
         {children}
       </ProvidersInner>