@agent-native/core 0.6.1 → 0.7.1

package/dist/vite/agents-bundle-plugin.js

@@ -13,16 +13,35 @@
  */
 import path from "path";
 import fs from "fs";
-import { readAgentsBundleFromFs } from "../server/agents-bundle.js";
+import { readAgentsBundleFromFs, } from "../server/agents-bundle.js";
+import { getWorkspaceCoreExports } from "../deploy/workspace-core.js";
 const VIRTUAL_ID = "virtual:agents-bundle";
 const RESOLVED_ID = "\0" + VIRTUAL_ID;
-function emitBundleModule(projectRoot) {
-    const bundle = readAgentsBundleFromFs(projectRoot);
+async function emitBundleModule(projectRoot) {
+    // If the project is inside an enterprise monorepo with a workspace core,
+    // merge in its AGENTS.md + skills. Template skills override workspace
+    // core skills on name collision.
+    let workspaceSource = null;
+    try {
+        const ws = await getWorkspaceCoreExports(projectRoot);
+        if (ws) {
+            workspaceSource = {
+                skillsDir: ws.skillsDir,
+                agentsMdPath: ws.agentsMdPath,
+                rootDir: ws.packageDir,
+            };
+        }
+    }
+    catch {
+        // fall back to template-only
+    }
+    const bundle = readAgentsBundleFromFs(projectRoot, workspaceSource);
     // Serialize as JSON and wrap in `export default` — this produces a valid
     // ES module that any bundler (Rollup, esbuild, Rolldown) can statically
     // analyze and tree-shake if nothing imports it.
     return `// AUTO-GENERATED by @agent-native/core/vite/agents-bundle-plugin
-// Contains the inlined AGENTS.md + .agents/skills/ content from the template.
+// Contains the inlined AGENTS.md + .agents/skills/ content from the template,
+// merged with any workspace-core AGENTS.md + skills/ when present.
 const bundle = ${JSON.stringify(bundle)};
 export default bundle;
 `;
@@ -39,26 +58,51 @@ export function agentsBundlePlugin() {
                 return RESOLVED_ID;
             return null;
         },
-        load(id) {
+        async load(id) {
             if (id !== RESOLVED_ID)
                 return null;
             if (!projectRoot)
                 projectRoot = process.cwd();
-            return emitBundleModule(projectRoot);
+            return await emitBundleModule(projectRoot);
         },
-        configureServer(server) {
+        async configureServer(server) {
             // Watch AGENTS.md + any SKILL.md changes and invalidate the virtual
-            // module so the next request picks up fresh content.
+            // module so the next request picks up fresh content. Also watches
+            // the workspace core's AGENTS.md + skills/ directory (if present)
+            // so edits to the enterprise mid-layer propagate to every app.
             const watcher = server.watcher;
+            // Resolve the workspace core up front so we can tell which files
+            // outside projectRoot should trigger invalidation.
+            let workspaceAgentsMdPath = null;
+            let workspaceSkillsDir = null;
+            try {
+                const ws = await getWorkspaceCoreExports(projectRoot);
+                if (ws) {
+                    workspaceAgentsMdPath = ws.agentsMdPath;
+                    workspaceSkillsDir = ws.skillsDir;
+                }
+            }
+            catch {
+                // ignore
+            }
             const shouldInvalidate = (file) => {
                 const rel = path.relative(projectRoot, file);
-                if (rel.startsWith(".."))
-                    return false;
-                if (rel === "AGENTS.md")
+                if (!rel.startsWith("..")) {
+                    if (rel === "AGENTS.md")
+                        return true;
+                    if (rel.startsWith(".agents" + path.sep + "skills") &&
+                        rel.endsWith("SKILL.md"))
+                        return true;
+                }
+                // Workspace-core files
+                if (workspaceAgentsMdPath && file === workspaceAgentsMdPath) {
                     return true;
-                if (rel.startsWith(".agents" + path.sep + "skills") &&
-                    rel.endsWith("SKILL.md"))
+                }
+                if (workspaceSkillsDir &&
+                    file.startsWith(workspaceSkillsDir + path.sep) &&
+                    file.endsWith("SKILL.md")) {
                     return true;
+                }
                 return false;
             };
             const invalidate = (file) => {
@@ -70,14 +114,20 @@ export function agentsBundlePlugin() {
                     server.ws.send({ type: "full-reload" });
                 }
             };
-            // Also explicitly watch AGENTS.md and the skills directory so edits to
-            // files outside the normal Vite watch set still trigger invalidation.
+            // Explicitly add template + workspace-core paths to the watcher so
+            // edits outside the normal Vite watch set still trigger invalidation.
             const agentsMdPath = path.join(projectRoot, "AGENTS.md");
             const skillsDir = path.join(projectRoot, ".agents", "skills");
             if (fs.existsSync(agentsMdPath))
                 watcher.add(agentsMdPath);
             if (fs.existsSync(skillsDir))
                 watcher.add(skillsDir);
+            if (workspaceAgentsMdPath && fs.existsSync(workspaceAgentsMdPath)) {
+                watcher.add(workspaceAgentsMdPath);
+            }
+            if (workspaceSkillsDir && fs.existsSync(workspaceSkillsDir)) {
+                watcher.add(workspaceSkillsDir);
+            }
             watcher.on("change", invalidate);
             watcher.on("add", invalidate);
             watcher.on("unlink", invalidate);

package/dist/vite/agents-bundle-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"agents-bundle-plugin.js","sourceRoot":"","sources":["../../src/vite/agents-bundle-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,MAAM,UAAU,GAAG,uBAAuB,CAAC;AAC3C,MAAM,WAAW,GAAG,IAAI,GAAG,UAAU,CAAC;AAEtC,SAAS,gBAAgB,CAAC,WAAmB;IAC3C,MAAM,MAAM,GAAG,sBAAsB,CAAC,WAAW,CAAC,CAAC;IACnD,yEAAyE;IACzE,wEAAwE;IACxE,gDAAgD;IAChD,OAAO;;iBAEQ,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;;CAEtC,CAAC;AACF,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,IAAI,WAAW,GAAG,EAAE,CAAC;IAErB,OAAO;QACL,IAAI,EAAE,4BAA4B;QAElC,cAAc,CAAC,MAAM;YACnB,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC;QAC5B,CAAC;QAED,SAAS,CAAC,EAAE;YACV,IAAI,EAAE,KAAK,UAAU;gBAAE,OAAO,WAAW,CAAC;YAC1C,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC,EAAE;YACL,IAAI,EAAE,KAAK,WAAW;gBAAE,OAAO,IAAI,CAAC;YACpC,IAAI,CAAC,WAAW;gBAAE,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;YAC9C,OAAO,gBAAgB,CAAC,WAAW,CAAC,CAAC;QACvC,CAAC;QAED,eAAe,CAAC,MAAM;YACpB,oEAAoE;YACpE,qDAAqD;YACrD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;YAE/B,MAAM,gBAAgB,GAAG,CAAC,IAAY,EAAW,EAAE;gBACjD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;gBAC7C,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;oBAAE,OAAO,KAAK,CAAC;gBACvC,IAAI,GAAG,KAAK,WAAW;oBAAE,OAAO,IAAI,CAAC;gBACrC,IACE,GAAG,CAAC,UAAU,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,GAAG,QAAQ,CAAC;oBAC/C,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC;oBAExB,OAAO,IAAI,CAAC;gBACd,OAAO,KAAK,CAAC;YACf,CAAC,CAAC;YAEF,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,EAAE;gBAClC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;oBAAE,OAAO;gBACpC,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;gBAC1D,IAAI,GAAG,EAAE,CAAC;oBACR,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;oBACzC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC1C,CAAC;YACH,CAAC,CAAC;YAEF,uEAAuE;YACvE,sEAAsE;YACtE,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YACzD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC9D,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAC3D,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAErD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YACjC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;YAC9B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACnC,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"agents-bundle-plugin.js","sourceRoot":"","sources":["../../src/vite/agents-bundle-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,OAAO,EACL,sBAAsB,GAEvB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,MAAM,UAAU,GAAG,uBAAuB,CAAC;AAC3C,MAAM,WAAW,GAAG,IAAI,GAAG,UAAU,CAAC;AAEtC,KAAK,UAAU,gBAAgB,CAAC,WAAmB;IACjD,yEAAyE;IACzE,sEAAsE;IACtE,iCAAiC;IACjC,IAAI,eAAe,GAAiC,IAAI,CAAC;IACzD,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,uBAAuB,CAAC,WAAW,CAAC,CAAC;QACtD,IAAI,EAAE,EAAE,CAAC;YACP,eAAe,GAAG;gBAChB,SAAS,EAAE,EAAE,CAAC,SAAS;gBACvB,YAAY,EAAE,EAAE,CAAC,YAAY;gBAC7B,OAAO,EAAE,EAAE,CAAC,UAAU;aACvB,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,6BAA6B;IAC/B,CAAC;IAED,MAAM,MAAM,GAAG,sBAAsB,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;IACpE,yEAAyE;IACzE,wEAAwE;IACxE,gDAAgD;IAChD,OAAO;;;iBAGQ,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;;CAEtC,CAAC;AACF,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,IAAI,WAAW,GAAG,EAAE,CAAC;IAErB,OAAO;QACL,IAAI,EAAE,4BAA4B;QAElC,cAAc,CAAC,MAAM;YACnB,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC;QAC5B,CAAC;QAED,SAAS,CAAC,EAAE;YACV,IAAI,EAAE,KAAK,UAAU;gBAAE,OAAO,WAAW,CAAC;YAC1C,OAAO,IAAI,CAAC;QACd,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE;YACX,IAAI,EAAE,KAAK,WAAW;gBAAE,OAAO,IAAI,CAAC;YACpC,IAAI,CAAC,WAAW;gBAAE,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;YAC9C,OAAO,MAAM,gBAAgB,CAAC,WAAW,CAAC,CAAC;QAC7C,CAAC;QAED,KAAK,CAAC,eAAe,CAAC,MAAM;YAC1B,oEAAoE;YACpE,kEAAkE;YAClE,kEAAkE;YAClE,+DAA+D;YAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;YAE/B,iEAAiE;YACjE,mDAAmD;YACnD,IAAI,qBAAqB,GAAkB,IAAI,CAAC;YAChD,IAAI,kBAAkB,GAAkB,IAAI,CAAC;YAC7C,IAAI,CAAC;gBACH,MAAM,EAAE,GAAG,MAAM,uBAAuB,CAAC,WAAW,CAAC,CAAC;gBACtD,IAAI,EAAE,EAAE,CAAC;oBACP,qBAAqB,GAAG,EAAE,CAAC,YAAY,CAAC;oBACxC,kBAAkB,GAAG,EAAE,CAAC,SAAS,CAAC;gBACpC,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;YAED,MAAM,gBAAgB,GAAG,CAAC,IAAY,EAAW,EAAE;gBACjD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;gBAC7C,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC1B,IAAI,GAAG,KAAK,WAAW;wBAAE,OAAO,IAAI,CAAC;oBACrC,IACE,GAAG,CAAC,UAAU,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,GAAG,QAAQ,CAAC;wBAC/C,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC;wBAExB,OAAO,IAAI,CAAC;gBAChB,CAAC;gBACD,uBAAuB;gBACvB,IAAI,qBAAqB,IAAI,IAAI,KAAK,qBAAqB,EAAE,CAAC;oBAC5D,OAAO,IAAI,CAAC;gBACd,CAAC;gBACD,IACE,kBAAkB;oBAClB,IAAI,CAAC,UAAU,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC;oBAC9C,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EACzB,CAAC;oBACD,OAAO,IAAI,CAAC;gBACd,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC,CAAC;YAEF,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,EAAE;gBAClC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;oBAAE,OAAO;gBACpC,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;gBAC1D,IAAI,GAAG,EAAE,CAAC;oBACR,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;oBACzC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC1C,CAAC;YACH,CAAC,CAAC;YAEF,mEAAmE;YACnE,sEAAsE;YACtE,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YACzD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC9D,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAC3D,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACrD,IAAI,qBAAqB,IAAI,EAAE,CAAC,UAAU,CAAC,qBAAqB,CAAC,EAAE,CAAC;gBAClE,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;YACrC,CAAC;YACD,IAAI,kBAAkB,IAAI,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;gBAC5D,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;YAClC,CAAC;YAED,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YACjC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;YAC9B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACnC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/vite/client.d.ts

@@ -29,6 +29,22 @@ export interface ClientConfigOptions {
         include?: string[];
         exclude?: string[];
     };
+    /**
+     * Package names to stub in the SSR bundle with an empty proxy object.
+     *
+     * Use this for dependencies that only run in the browser (canvas / diagram
+     * libraries, editors, WebGL) but would otherwise get pulled into the
+     * server bundle via SSR's noExternal policy — pushing the CF Pages
+     * Functions bundle over the 25 MiB limit.
+     *
+     * Only add packages that are provably never called during SSR. If the
+     * server imports one, it will receive a Proxy that throws on any real
+     * use (which is better than bundling a 10 MiB dep the worker never calls).
+     *
+     * @example
+     * ssrStubs: ["mermaid", "@excalidraw/excalidraw"]
+     */
+    ssrStubs?: string[];
     /**
      * @deprecated Pass `reactRouter()` directly in the `plugins` array instead.
      * Previously used to auto-load the React Router Vite plugin via require(),

package/dist/vite/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/vite/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAU,UAAU,EAAE,MAAM,MAAM,CAAC;AAoG/C,MAAM,WAAW,YAAY;IAC3B,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;IAChB,iDAAiD;IACjD,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iDAAiD;IACjD,YAAY,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC1D;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjD;AAqPD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,UAAU,CAoG1E"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/vite/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAU,UAAU,EAAE,MAAM,MAAM,CAAC;AAqG/C,MAAM,WAAW,YAAY;IAC3B,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;IAChB,iDAAiD;IACjD,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iDAAiD;IACjD,YAAY,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC1D;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjD;AAgSD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,UAAU,CAqI1E"}

package/dist/vite/client.js

@@ -4,6 +4,7 @@ import { createRequire } from "module";
 import { nitro as nitroVitePlugin } from "nitro/vite";
 import { actionTypesPlugin } from "./action-types-plugin.js";
 import { agentsBundlePlugin } from "./agents-bundle-plugin.js";
+import { findWorkspaceRoot } from "../scripts/utils.js";
 import { fileURLToPath } from "url";
 const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -294,6 +295,50 @@ function rolldownInputFix() {
  * in-process scripts (which use localFetch → http://localhost:${PORT}/api/...)
  * hit the right address even when Vite auto-increments the port.
  */
+/**
+ * Replace caller-specified packages with an empty proxy stub during SSR
+ * builds. For apps whose heavy browser-only deps would otherwise bloat the
+ * edge worker past CF Pages' 25 MiB Functions limit.
+ *
+ * The template lists the packages in its `defineConfig({ ssrStubs })` call —
+ * the framework never hardcodes package names.
+ */
+function ssrStubPlugin(packages) {
+    if (!packages.length)
+        return null;
+    const stubbed = new Set(packages);
+    const STUB_ID = "\0agent-native-ssr-stub";
+    return {
+        name: "agent-native-ssr-stub-heavy-libs",
+        enforce: "pre",
+        resolveId(id, _importer, opts) {
+            if (!opts?.ssr)
+                return null;
+            // Match the bare package name or any subpath
+            const pkg = id
+                .split("/")
+                .slice(0, id.startsWith("@") ? 2 : 1)
+                .join("/");
+            if (stubbed.has(pkg))
+                return STUB_ID;
+            return null;
+        },
+        load(id) {
+            if (id !== STUB_ID)
+                return null;
+            // Proxy that answers any property access with itself — lets dead
+            // import/re-export chains parse without blowing up, and still throws
+            // if code actually tries to call any of it on the server.
+            return ("const handler = { get(_, p) { " +
+                "if (p === Symbol.toPrimitive) return () => ''; " +
+                "if (p === 'then') return undefined; " +
+                "return new Proxy(() => {}, handler); " +
+                "} };" +
+                "const stub = new Proxy(() => {}, handler);" +
+                "export default stub;");
+        },
+    };
+}
 function portExposer() {
     return {
         name: "agent-native-port-exposer",
@@ -333,9 +378,32 @@ export function defineConfig(options = {}) {
         }
     }
     const cwd = process.cwd();
+    // Workspace env fallback. If this app is inside a workspace, tell Vite to
+    // also look for .env files at the workspace root. Per-app .env still wins
+    // (Vite's loadEnv merges in precedence order — app dir is loaded after).
+    const workspaceRoot = findWorkspaceRoot(cwd);
+    const envDir = workspaceRoot && workspaceRoot !== cwd ? workspaceRoot : cwd;
+    // Preload workspace-root .env into process.env so Nitro server code sees
+    // shared keys during dev (Nitro reads process.env, not vite's envDir).
+    if (workspaceRoot && workspaceRoot !== cwd) {
+        try {
+            const dotenv = require("dotenv");
+            dotenv.config({
+                path: path.join(workspaceRoot, ".env"),
+                override: false,
+            });
+        }
+        catch { }
+    }
     // Build the React transform plugin (only for legacy SPA mode)
     const reactPluginInstance = reactTransformPlugin?.();
+    // APP_BASE_PATH lets this app be mounted under a prefix (e.g. "/mail") as
+    // part of a unified workspace deploy. Defaults to "/" for standalone apps.
+    const appBasePath = process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH || "/";
+    const base = appBasePath.endsWith("/") ? appBasePath : `${appBasePath}/`;
     return {
+        envDir,
+        base,
         server: {
             host: "::",
             port: options.port ?? 8080,
@@ -362,6 +430,13 @@ export function defineConfig(options = {}) {
             noExternal: /^(?!node:)/,
         },
         plugins: [
+            // Stub packages from `options.ssrStubs` in the SSR bundle so they
+            // don't bloat the edge worker. Opt-in per template — the framework
+            // hardcodes nothing.
+            ...(() => {
+                const p = ssrStubPlugin(options.ssrStubs ?? []);
+                return p ? [p] : [];
+            })(),
             actionTypesPlugin(),
             agentsBundlePlugin(),
             autoReloadOnOptimizeDep(),

package/dist/vite/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/vite/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/vite/client.ts"],"names":[],"mappings":"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"}

package/docs/content/a2a-protocol.md

@@ -0,0 +1,223 @@
+---
+title: "A2A Protocol"
+description: "Agent-to-agent communication via JSON-RPC: discovery, messaging, streaming, and task management."
+---
+
+# A2A Protocol
+
+Agent-to-agent communication over HTTP. Agents discover each other, send messages, and receive structured results.
+
+## Overview {#overview}
+
+A2A (agent-to-agent) is a JSON-RPC protocol for inter-agent communication. A mail agent can ask an analytics agent to run a query. A calendar agent can search issues in a project management agent. Each agent exposes its capabilities via an agent card and accepts work via a standard JSON-RPC endpoint.
+
+Key concepts:
+
+- **Agent card** — public metadata at `/.well-known/agent-card.json` describing skills and capabilities
+- **JSON-RPC** — all communication goes through `POST /a2a` with standard JSON-RPC 2.0
+- **Tasks** — each message creates a task with a lifecycle (submitted, working, completed, failed, canceled)
+- **Bearer auth** — optional API key authentication via environment variable
+
+## Server setup {#server-setup}
+
+Call `mountA2A()` in a server plugin to expose the A2A endpoints:
+
+```ts
+// server/plugins/a2a.ts
+import { mountA2A } from "@agent-native/core/a2a";
+
+export default defineNitroPlugin((nitro) => {
+  mountA2A(nitro.h3App, {
+    name: "Analytics Agent",
+    description: "Runs analytics queries and returns chart data",
+    skills: [
+      {
+        id: "run-query",
+        name: "Run Query",
+        description: "Execute a SQL query against the analytics database",
+        tags: ["analytics", "sql"],
+        examples: ["Show me signups by source this month"],
+      },
+    ],
+    apiKeyEnv: "A2A_API_KEY", // env var name for bearer token
+    streaming: true, // enable message/stream
+  });
+});
+```
+
+This mounts two endpoints: `GET /.well-known/agent-card.json` (public, no auth) and `POST /a2a` (authenticated JSON-RPC).
+
+## Agent card {#agent-card}
+
+The agent card is auto-generated from your config and served at `/.well-known/agent-card.json`. Other agents fetch it to discover your agent's skills.
+
+```json
+{
+  "name": "Analytics Agent",
+  "description": "Runs analytics queries and returns chart data",
+  "url": "https://analytics.example.com",
+  "version": "1.0.0",
+  "protocolVersion": "0.3",
+  "capabilities": {
+    "streaming": true,
+    "pushNotifications": false,
+    "stateTransitionHistory": true
+  },
+  "skills": [
+    {
+      "id": "run-query",
+      "name": "Run Query",
+      "description": "Execute a SQL query against the analytics database",
+      "tags": ["analytics", "sql"],
+      "examples": ["Show me signups by source this month"]
+    }
+  ],
+  "securitySchemes": {
+    "apiKey": { "type": "http", "scheme": "bearer" }
+  },
+  "security": [{ "apiKey": [] }]
+}
+```
+
+## JSON-RPC methods {#json-rpc-methods}
+
+All methods are called via `POST /a2a` with JSON-RPC 2.0 format:
+
+| Method           | Description                               | Key params            |
+| ---------------- | ----------------------------------------- | --------------------- |
+| `message/send`   | Send a message, get a completed task back | `message, contextId?` |
+| `message/stream` | Send a message, receive SSE task updates  | `message, contextId?` |
+| `tasks/get`      | Fetch a task by ID                        | `id`                  |
+| `tasks/cancel`   | Cancel a running task                     | `id`                  |
+
+Messages contain typed parts:
+
+```json
+{
+  "role": "user",
+  "parts": [
+    { "type": "text", "text": "Show signups by source" },
+    { "type": "data", "data": { "dateRange": "last-30d" } },
+    {
+      "type": "file",
+      "file": { "name": "report.csv", "mimeType": "text/csv", "bytes": "..." }
+    }
+  ]
+}
+```
+
+## Client {#client}
+
+The `A2AClient` class handles discovery, messaging, and streaming:
+
+```ts
+import { A2AClient } from "@agent-native/core/a2a";
+
+const client = new A2AClient("https://analytics.example.com", "my-api-key");
+
+// Discover agent capabilities
+const card = await client.getAgentCard();
+console.log(card.skills);
+
+// Send a message and get a completed task
+const task = await client.send({
+  role: "user",
+  parts: [{ type: "text", text: "Show signups by source this month" }],
+});
+console.log(task.status.state); // "completed"
+console.log(task.status.message); // agent's response
+
+// Stream responses for long-running work
+for await (const update of client.stream({
+  role: "user",
+  parts: [{ type: "text", text: "Generate a full quarterly report" }],
+})) {
+  console.log(update.status.state, update.status.message);
+}
+```
+
+## Convenience helper {#convenience-helper}
+
+For simple text-in/text-out calls, use `callAgent()`:
+
+```ts
+import { callAgent } from "@agent-native/core/a2a";
+
+// One-shot: send text, get text back
+const response = await callAgent(
+  "https://analytics.example.com",
+  "How many signups last week?",
+  { apiKey: process.env.ANALYTICS_API_KEY },
+);
+console.log(response); // "There were 1,247 signups last week..."
+```
+
+## Task lifecycle {#task-lifecycle}
+
+Each message creates a task that moves through these states:
+
+`submitted` → `working` → `completed` | `failed` | `canceled`
+
+| State            | Meaning                                        |
+| ---------------- | ---------------------------------------------- |
+| `submitted`      | Task created, queued for processing            |
+| `working`        | Handler is processing the message              |
+| `completed`      | Handler finished successfully                  |
+| `failed`         | Handler threw an error                         |
+| `canceled`       | Task was canceled via tasks/cancel             |
+| `input-required` | Handler needs more information from the caller |
+
+Tasks persist in the `a2a_tasks` SQL table and can be retrieved later via `tasks/get`.
+
+## Security {#security}
+
+Set `apiKeyEnv` in your config to the name of an environment variable containing the expected bearer token:
+
+```ts
+// Config
+mountA2A(app, {
+  // ...
+  apiKeyEnv: "A2A_API_KEY", // reads process.env.A2A_API_KEY
+});
+
+// Client calls with the matching key
+const client = new A2AClient(url, process.env.A2A_API_KEY);
+```
+
+The agent card endpoint is always public (no auth) so other agents can discover capabilities. The `/a2a` JSON-RPC endpoint requires a valid bearer token when `apiKeyEnv` is set. In dev mode (no env var configured), auth is skipped.
+
+## Agent mentions {#agent-mentions}
+
+You can `@`-mention agents directly in the chat composer. Connected agents use A2A: when you mention a connected agent, the server makes an A2A call to that agent and weaves the response into your conversation context.
+
+Custom workspace agents are different: they run locally inside the current app/runtime rather than over A2A.
+
+See [Agent Mentions](/docs/agent-mentions) for details on how mentions work, how to add agents, and how to create custom mention providers.
+
+## Messaging integrations {#messaging-integrations}
+
+Agents can also be reached from external messaging platforms like Slack, Telegram, and WhatsApp. Users send messages on those platforms and the agent responds in the same thread, using the same tools and actions as the web chat.
+
+See [Integrations](/docs/integrations) for setup details on each platform.
+
+## Example: cross-agent query {#example}
+
+A mail agent needs analytics data. The analytics agent exposes a "run-query" skill via A2A:
+
+```ts
+// In the mail agent's actions/get-analytics.ts
+import { callAgent } from "@agent-native/core/a2a";
+
+export default async function (args: string[]) {
+  const response = await callAgent(
+    "https://analytics.example.com",
+    "How many emails were sent last week by category?",
+    { apiKey: process.env.ANALYTICS_API_KEY },
+  );
+
+  console.log(response);
+  // The mail agent can now use this data in its response
+}
+```
+
+The analytics agent receives the message, runs the query via its handler, and returns the result. The mail agent's script gets the text response back. No shared database, no direct API calls — just agent-to-agent communication.

package/docs/content/actions.md

@@ -0,0 +1,129 @@
+---
+title: "Actions"
+description: "Action dispatcher, parseArgs, standard actions, and utility functions for agent-callable operations."
+---
+
+# Actions
+
+`@agent-native/core` provides an action dispatcher and utilities for building agent-callable actions.
+
+## Action Dispatcher {#action-dispatcher}
+
+The action system lets you create actions that agents can invoke via `pnpm action <name>`. Each action is a TypeScript file that exports a default async function.
+
+```ts
+// actions/run.ts — dispatcher (one-time setup)
+import { runScript } from "@agent-native/core";
+runScript();
+```
+
+```ts
+// actions/hello.ts — example action
+import { parseArgs } from "@agent-native/core";
+
+export default async function hello(args: string[]) {
+  const { name } = parseArgs(args);
+  console.log(`Hello, ${name ?? "world"}!`);
+}
+```
+
+```bash
+# Run it
+pnpm action hello --name Steve
+```
+
+## parseArgs(args) {#parseargs}
+
+Parse CLI arguments in `--key value` or `--key=value` format:
+
+```ts
+import { parseArgs } from "@agent-native/core";
+
+const args = parseArgs(["--name", "Steve", "--verbose", "--count=3"]);
+// { name: "Steve", verbose: "true", count: "3" }
+```
+
+## Standard actions {#standard-actions}
+
+Every template should include these two actions for [context awareness](/docs/context-awareness):
+
+### view-screen {#view-screen}
+
+Reads the current navigation state, fetches contextual data, and returns a snapshot of what the user sees. The agent should always call this before acting.
+
+```ts
+// actions/view-screen.ts
+import { readAppState } from "@agent-native/core/application-state";
+
+export default async function main() {
+  const navigation = await readAppState("navigation");
+  const screen: Record<string, unknown> = { navigation };
+
+  if (navigation?.view === "inbox") {
+    const res = await fetch(
+      "http://localhost:3000/api/emails?label=" + navigation.label,
+    );
+    screen.emailList = await res.json();
+  }
+
+  console.log(JSON.stringify(screen, null, 2));
+}
+```
+
+```bash
+pnpm action view-screen
+```
+
+### navigate {#navigate}
+
+Writes a one-shot navigation command to application-state. The UI reads it, navigates, and deletes the entry.
+
+```ts
+// actions/navigate.ts
+import { parseArgs } from "@agent-native/core";
+import { writeAppState } from "@agent-native/core/application-state";
+
+export default async function main(args: string[]) {
+  const parsed = parseArgs(args);
+  await writeAppState("navigate", parsed);
+  console.log("Navigate command written:", parsed);
+}
+```
+
+```bash
+pnpm action navigate --view inbox --threadId thread-123
+```
+
+## Shared Agent Chat {#shared-agent-chat}
+
+`@agent-native/core` provides an isomorphic chat bridge that works in both browser and Node.js:
+
+```ts
+import { agentChat } from "@agent-native/core";
+
+// Auto-submit a message
+agentChat.submit("Generate a report for Q4");
+
+// Prefill without submitting
+agentChat.prefill("Draft an email to...", contextData);
+
+// Full control
+agentChat.send({
+  message: "Process this data",
+  context: JSON.stringify(data),
+  submit: true,
+});
+```
+
+In the browser, messages are sent via `window.postMessage()`. In Node.js (actions), they use the `BUILDER_PARENT_MESSAGE:` stdout format that the Electron host translates to postMessage.
+
+## Utility Functions {#utility-functions}
+
+| Function                | Returns   | Description                                        |
+| ----------------------- | --------- | -------------------------------------------------- |
+| `loadEnv(path?)`        | `void`    | Load .env from project root (or custom path)       |
+| `camelCaseArgs(args)`   | `Record`  | Convert kebab-case keys to camelCase               |
+| `isValidPath(p)`        | `boolean` | Validate relative path (no traversal, no absolute) |
+| `isValidProjectPath(p)` | `boolean` | Validate project slug (e.g. "my-project")          |
+| `ensureDir(dir)`        | `void`    | mkdir -p helper                                    |
+| `fail(message)`         | `never`   | Print error to stderr and exit(1)                  |