@agent-native/core 0.37.3 → 0.39.0

package/dist/templates/workspace-core/.agents/skills/writing-agent-instructions/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: writing-agent-instructions
+description: >-
+  How to write great agent instructions for an agent-native app or template:
+  AGENTS.md, skills, and tool/action descriptions. Use when authoring or
+  reviewing AGENTS.md, writing a SKILL.md, wording action descriptions, or
+  deciding what belongs in instructions vs skills vs memory.
+metadata:
+  internal: true
+---
+
+# Writing Agent Instructions & Skills
+
+This is a creator-facing guide. When you build an agent-native app or template,
+the agent's behavior is only as good as the instructions you give it. Three
+surfaces carry that guidance: `AGENTS.md` (the map), skills (the deep dives),
+and action/tool descriptions (how the agent picks the right tool). Write each
+one for fast retrieval, not for prose.
+
+## Keep AGENTS.md small and skimmable
+
+`AGENTS.md` is loaded as orientation. It should be the smallest thing that lets
+the agent act correctly, with everything deep pushed into skills. Aim for these
+sections and little else:
+
+- **Purpose line** — one sentence on what the app is and the primary workflow.
+- **Core rules** — the handful of invariants that must always hold (data in SQL,
+  operations go through actions, AI goes through the agent chat, schema changes
+  are additive). Short, imperative bullets.
+- **Application-state keys** — the `navigation`/selection/focus keys the agent
+  reads to know what the user is looking at, with their shape.
+- **Action table** — a compact table of action name -> purpose (see below).
+- **Skills index** — a list of the skills that exist and when to read each one.
+
+If a section is growing past a screen, it belongs in a skill. `AGENTS.md`
+answers "what is this app and what can I do," not "how exactly do I do the hard
+thing."
+
+```markdown
+# Projects App
+
+One workspace for projects, tasks, and notes. Agent and UI share the same SQL
+data and the same actions.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes.
+- All AI work goes through the agent chat; never call an LLM inline.
+- Schema changes are additive only.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                     |
+| ---------------- | --------------------------- |
+| `list-projects`  | List accessible projects    |
+| `create-project` | Create a project            |
+| `update-project` | Rename or archive a project |
+
+## Skills
+
+- `project-imports` — read before importing legacy CSV exports.
+- `sharing` — read before exposing a project to other users.
+```
+
+## Single-source AGENTS.md (CLAUDE.md is a symlink)
+
+Keep one canonical instructions file: `AGENTS.md`. If a client expects
+`CLAUDE.md`, make it a symlink to `AGENTS.md` rather than a second copy. Two
+hand-maintained files drift, and the agent ends up with contradictory rules.
+One source of truth, linked where needed.
+
+## SKILL.md frontmatter must say what AND when
+
+The `description` is the only thing the agent sees when deciding whether to read
+a skill. It must answer two questions: what the skill covers, and when to
+trigger it. A description that only describes the topic will not fire.
+
+```markdown
+---
+name: project-imports
+description: >-
+  How to import projects from the legacy CSV export. Use when the user uploads
+  a project CSV or asks to migrate projects from the old system.
+---
+```
+
+- Lead with the capability, then add an explicit **"Use when…"** clause.
+- Be slightly pushy — over-triggering beats a skill that never loads.
+- Keep it under ~40 words; it is loaded into context on every conversation.
+
+### Scope a skill to runtime vs dev
+
+An optional `scope` field decides which agent loads the skill:
+
+- `both` (default when omitted) and `runtime` — loaded by the in-app runtime
+  agent.
+- `dev` — for the human's coding agent (e.g. Claude Code) only. A `scope: dev`
+  skill is invisible to the runtime agent everywhere (system-prompt skills block
+  and `docs-search`).
+
+```markdown
+---
+name: release-checklist
+description: >-
+  Steps for cutting a release. Use when preparing or publishing a new version.
+scope: dev
+---
+```
+
+Omit `scope` for normal skills (the default `both` keeps them loading at
+runtime — fully backward compatible). For a dev-only skill, mark it `scope: dev`
+and optionally mirror it under `.claude/skills/<name>/SKILL.md` so Claude Code
+picks it up while the runtime agent skips it.
+
+## Progressive disclosure: lean SKILL.md, depth in references/
+
+Write the SKILL.md as the lean, must-know layer: the rule, how to do it, the
+do/don't list, and pointers. Push long examples, exhaustive field references,
+API quirks, and edge-case tables into `references/` files the agent reads only
+when it needs them.
+
+```
+.agents/skills/project-imports/
+├── SKILL.md            # rule + happy path + do/don't
+└── references/
+    └── csv-format.md   # full column spec, encodings, edge cases
+```
+
+This keeps the always-loaded surface small and lets depth scale without bloating
+context. See the **create-skill** skill for the full skill format.
+
+## Write action-oriented tables
+
+The agent scans tables faster than prose. Prefer a table of name -> purpose over
+paragraphs describing each operation. The same applies to state keys, field
+types, and any enumerable set. Tables are skimmable, diffable, and easy to keep
+in sync when you add an action.
+
+## Write clear tool/action descriptions
+
+Action descriptions are tool descriptions — they drive tool selection. Make each
+one a precise, single-purpose sentence:
+
+- Say what it does and what it returns, not how it's implemented.
+- Describe each parameter in its `.describe()` so the agent fills it correctly.
+- One responsibility per action. If a description needs "and also…", split it.
+- Mark read-only actions (`readOnly: true` / `http: { method: "GET" }`) so the
+  agent knows they're safe to call freely.
+- For provider-backed shortcuts, make clear they are convenience paths, not
+  capability ceilings. If arbitrary provider endpoints/filters may matter,
+  point instructions to `provider-api-catalog`, `provider-api-docs`, and
+  `provider-api-request` instead of implying the shortcut is all the agent can
+  do.
+
+```ts
+defineAction({
+  description: "Create a project. Returns the new project id and title.",
+  schema: z.object({
+    title: z.string().min(1).describe("Project title shown in the sidebar"),
+  }),
+  // ...
+});
+```
+
+## Bake in anti-fabrication and verify-before-done
+
+App instructions should make honesty and verification the default behavior:
+
+- **Never fabricate.** If data isn't found or an action fails, say so and recover
+  — don't invent results or claim success. Read the real value via an action or
+  query before reporting it.
+- **Verify before declaring done.** After a change, confirm it with a read-back
+  (re-query the row, re-read the screen via `view-screen`) instead of assuming
+  the write worked.
+- **Recover, don't give up.** On a recoverable error (a failed query, a transient
+  fetch), retry or fix the input rather than abandoning the task. Keep this
+  separate from the anti-fabrication rule — don't conflate "don't make things up"
+  with "stop at the first error."
+
+Put these as core rules in `AGENTS.md` so they apply to every turn.
+
+## Bake in secrets hygiene
+
+Instruction authors must make credential handling explicit anywhere an app,
+skill, action, webhook, integration, or extension touches external services.
+Write the rule in terms of values, not just files: never hardcode real API keys,
+tokens, webhook URLs, signing secrets, OAuth refresh tokens, private
+Builder/internal data, or customer data in source, docs, tests, fixtures,
+prompts, screenshots, or generated content.
+
+Examples may name credential keys such as `OPENAI_API_KEY` or `SLACK_WEBHOOK`,
+but values must be placeholders (`<OPENAI_API_KEY>`, `${keys.SLACK_WEBHOOK}`) or
+clearly fake test data. Tell agents which approved channel to use instead:
+deployment env vars for deploy-level secrets, `app_secrets` /
+`saveCredential` / `resolveCredential` for scoped API keys, `oauth_tokens` for
+OAuth, and `${keys.NAME}` substitution for extension/automation outbound HTTP.
+
+## What goes where
+
+- **AGENTS.md** — applies to the whole app, every turn: purpose, core rules,
+  state keys, action index, skills index.
+- **Skills** — reusable how-to for a specific pattern, loaded on demand. Applies
+  to everyone working in the app.
+- **Memory (`memory/MEMORY.md`)** — per-user preferences and corrections, not
+  authored guidance. See **capture-learnings**.
+
+## Do
+
+- Keep `AGENTS.md` to roughly one screen of orientation; link out for depth.
+- Update the action table and skills index whenever you add an action or skill.
+- Write every SKILL.md description with an explicit "Use when…".
+- Use tables for any enumerable set (actions, state keys, field types).
+
+## Don't
+
+- Don't duplicate skill content inside `AGENTS.md` — point to the skill.
+- Don't maintain two instruction files; symlink `CLAUDE.md` to `AGENTS.md`.
+- Don't write vague descriptions ("helps with projects") — they won't trigger.
+- Don't document niche/buried UI behaviors in instructions; let code and UI
+  carry those.
+- Don't paste real credentials, credential-looking dummy strings, private
+  Builder/internal data, or customer data into examples. Use placeholders.
+
+## Related Skills
+
+- **create-skill** — The skill format and templates this guide refers to.
+- **adding-a-feature** — The four-area model (UI, actions, skills/instructions,
+  application state) every feature must satisfy.
+- **actions** — How action descriptions become agent tools.
+- **context-awareness** — Application-state keys and the `view-screen` pattern.
+- **capture-learnings** — Where per-user learnings go instead of AGENTS.md.

package/dist/templates/workspace-core/AGENTS.md

@@ -23,7 +23,11 @@ agent should know.
 - Put shared code in `packages/shared` only when multiple apps need it.
 - Keep app-specific screens, actions, state, and skills inside `apps/<app>`.
 - Store shared runtime configuration in the workspace root `.env`; use
-  `apps/<app>/.env` only for app-specific overrides.
+  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  tokens, webhook URLs, signing secrets, private Builder/internal data, customer
+  data, or credential-looking literals in source, docs, prompts, fixtures,
+  application state, action responses, or generated app content. Use
+  secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Prefer framework defaults until the workspace has a real custom rule,
   component, plugin, action, or skill to share.
 - Keep the Workspace files view for user-authored or user-requested resources.

package/dist/templates/workspace-root/AGENTS.md

@@ -43,8 +43,11 @@ coding agents can discover the same workspace-wide guidance from the root.
 - Keep application routes, actions, server plugins, and app state inside the
   relevant `apps/<app>` directory unless multiple apps need the same behavior.
 - Put reusable code in `packages/shared` only after at least two apps need it.
-- Never copy live credentials, personal email addresses, customer data, or
-  company-specific placeholder values into source files.
+- Never copy live credentials, API keys, tokens, webhook URLs, signing secrets,
+  personal email addresses, customer data, private Builder/internal data, or
+  company-specific placeholder values into source files, docs, prompts,
+  fixtures, application state, action responses, or generated app content. Use
+  secrets/OAuth/runtime configuration and obvious placeholders in examples.
 
 ## New Workspace Apps
 

package/dist/tracking/route.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Server route handler for client-originated tracking events.
+ *
+ * The browser-side `track()` helper (see `client/track.ts`) POSTs
+ * `{ name, properties }` to `/_agent-native/track`. This handler validates the
+ * payload, resolves the caller's identity, and forwards the event to the same
+ * server-side provider registry that server code reaches through `track()`.
+ *
+ * It is deliberately best-effort: a malformed body is rejected with a 400, but
+ * provider delivery never throws back to the browser (the server `track()`
+ * already swallows provider errors). On success it returns 204 with no body.
+ *
+ * Security: this is an authenticated, first-party-only endpoint. It is mounted
+ * behind the framework CSRF middleware (which requires the
+ * `X-Agent-Native-CSRF` header / JSON content type / same-origin marker that
+ * the client helper always sends) and it requires a resolved session so it
+ * cannot be used as an open analytics relay. Events are attributed to the
+ * resolved `userId` (and `orgId` when the request has an active org), never to
+ * a client-supplied identity.
+ */
+/** Max length of an event name. Mirrors typical provider limits. */
+export declare const MAX_TRACK_EVENT_NAME_LENGTH = 200;
+/** Max serialized size of the `properties` object, in bytes. */
+export declare const MAX_TRACK_PROPERTIES_BYTES: number;
+export interface TrackRouteValidationResult {
+    ok: boolean;
+    /** Present when `ok` is true. */
+    name?: string;
+    properties?: Record<string, unknown>;
+    /** Present when `ok` is false — a short, client-safe reason. */
+    error?: string;
+}
+/**
+ * Validate a client tracking payload. Pure and synchronous so it can be unit
+ * tested without standing up an h3 event.
+ *
+ *   - `name` must be a non-empty string no longer than
+ *     `MAX_TRACK_EVENT_NAME_LENGTH` characters.
+ *   - `properties`, when present, must be a plain JSON object whose serialized
+ *     size is at most `MAX_TRACK_PROPERTIES_BYTES` bytes.
+ */
+export declare function validateTrackPayload(body: unknown): TrackRouteValidationResult;
+//# sourceMappingURL=route.d.ts.map

package/dist/tracking/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/tracking/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,oEAAoE;AACpE,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,gEAAgE;AAChE,eAAO,MAAM,0BAA0B,QAAY,CAAC;AAEpD,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,OAAO,CAAC;IACZ,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAUD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,OAAO,GACZ,0BAA0B,CAoD5B"}

package/dist/tracking/route.js

@@ -0,0 +1,85 @@
+/**
+ * Server route handler for client-originated tracking events.
+ *
+ * The browser-side `track()` helper (see `client/track.ts`) POSTs
+ * `{ name, properties }` to `/_agent-native/track`. This handler validates the
+ * payload, resolves the caller's identity, and forwards the event to the same
+ * server-side provider registry that server code reaches through `track()`.
+ *
+ * It is deliberately best-effort: a malformed body is rejected with a 400, but
+ * provider delivery never throws back to the browser (the server `track()`
+ * already swallows provider errors). On success it returns 204 with no body.
+ *
+ * Security: this is an authenticated, first-party-only endpoint. It is mounted
+ * behind the framework CSRF middleware (which requires the
+ * `X-Agent-Native-CSRF` header / JSON content type / same-origin marker that
+ * the client helper always sends) and it requires a resolved session so it
+ * cannot be used as an open analytics relay. Events are attributed to the
+ * resolved `userId` (and `orgId` when the request has an active org), never to
+ * a client-supplied identity.
+ */
+/** Max length of an event name. Mirrors typical provider limits. */
+export const MAX_TRACK_EVENT_NAME_LENGTH = 200;
+/** Max serialized size of the `properties` object, in bytes. */
+export const MAX_TRACK_PROPERTIES_BYTES = 16 * 1024;
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Validate a client tracking payload. Pure and synchronous so it can be unit
+ * tested without standing up an h3 event.
+ *
+ *   - `name` must be a non-empty string no longer than
+ *     `MAX_TRACK_EVENT_NAME_LENGTH` characters.
+ *   - `properties`, when present, must be a plain JSON object whose serialized
+ *     size is at most `MAX_TRACK_PROPERTIES_BYTES` bytes.
+ */
+export function validateTrackPayload(body) {
+    if (!isPlainObject(body)) {
+        return { ok: false, error: "Request body must be a JSON object." };
+    }
+    const { name, properties } = body;
+    if (typeof name !== "string") {
+        return { ok: false, error: "`name` must be a string." };
+    }
+    const trimmed = name.trim();
+    if (!trimmed) {
+        return { ok: false, error: "`name` must be a non-empty string." };
+    }
+    if (trimmed.length > MAX_TRACK_EVENT_NAME_LENGTH) {
+        return {
+            ok: false,
+            error: `\`name\` must be at most ${MAX_TRACK_EVENT_NAME_LENGTH} characters.`,
+        };
+    }
+    if (properties !== undefined && !isPlainObject(properties)) {
+        return { ok: false, error: "`properties` must be a plain JSON object." };
+    }
+    let serializedProperties;
+    if (properties !== undefined) {
+        try {
+            serializedProperties = JSON.stringify(properties);
+        }
+        catch {
+            return { ok: false, error: "`properties` must be JSON-serializable." };
+        }
+        if (serializedProperties !== undefined &&
+            Buffer.byteLength(serializedProperties, "utf8") >
+                MAX_TRACK_PROPERTIES_BYTES) {
+            return {
+                ok: false,
+                error: `\`properties\` must serialize to at most ${MAX_TRACK_PROPERTIES_BYTES} bytes.`,
+            };
+        }
+    }
+    return {
+        ok: true,
+        name: trimmed,
+        properties: properties,
+    };
+}
+//# sourceMappingURL=route.js.map

package/dist/tracking/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../src/tracking/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,oEAAoE;AACpE,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAE/C,gEAAgE;AAChE,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,GAAG,IAAI,CAAC;AAWpD,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAa;IAEb,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,qCAAqC,EAAE,CAAC;IACrE,CAAC;IAED,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,IAG5B,CAAC;IAEF,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,0BAA0B,EAAE,CAAC;IAC1D,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC;IACpE,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,2BAA2B,EAAE,CAAC;QACjD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,4BAA4B,2BAA2B,cAAc;SAC7E,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,2CAA2C,EAAE,CAAC;IAC3E,CAAC;IAED,IAAI,oBAAwC,CAAC;IAC7C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,oBAAoB,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QACpD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,yCAAyC,EAAE,CAAC;QACzE,CAAC;QACD,IACE,oBAAoB,KAAK,SAAS;YAClC,MAAM,CAAC,UAAU,CAAC,oBAAoB,EAAE,MAAM,CAAC;gBAC7C,0BAA0B,EAC5B,CAAC;YACD,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,4CAA4C,0BAA0B,SAAS;aACvF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,IAAI,EAAE,OAAO;QACb,UAAU,EAAE,UAAiD;KAC9D,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Server route handler for client-originated tracking events.\n *\n * The browser-side `track()` helper (see `client/track.ts`) POSTs\n * `{ name, properties }` to `/_agent-native/track`. This handler validates the\n * payload, resolves the caller's identity, and forwards the event to the same\n * server-side provider registry that server code reaches through `track()`.\n *\n * It is deliberately best-effort: a malformed body is rejected with a 400, but\n * provider delivery never throws back to the browser (the server `track()`\n * already swallows provider errors). On success it returns 204 with no body.\n *\n * Security: this is an authenticated, first-party-only endpoint. It is mounted\n * behind the framework CSRF middleware (which requires the\n * `X-Agent-Native-CSRF` header / JSON content type / same-origin marker that\n * the client helper always sends) and it requires a resolved session so it\n * cannot be used as an open analytics relay. Events are attributed to the\n * resolved `userId` (and `orgId` when the request has an active org), never to\n * a client-supplied identity.\n */\n\n/** Max length of an event name. Mirrors typical provider limits. */\nexport const MAX_TRACK_EVENT_NAME_LENGTH = 200;\n\n/** Max serialized size of the `properties` object, in bytes. */\nexport const MAX_TRACK_PROPERTIES_BYTES = 16 * 1024;\n\nexport interface TrackRouteValidationResult {\n  ok: boolean;\n  /** Present when `ok` is true. */\n  name?: string;\n  properties?: Record<string, unknown>;\n  /** Present when `ok` is false — a short, client-safe reason. */\n  error?: string;\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n    return false;\n  }\n  const proto = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n}\n\n/**\n * Validate a client tracking payload. Pure and synchronous so it can be unit\n * tested without standing up an h3 event.\n *\n *   - `name` must be a non-empty string no longer than\n *     `MAX_TRACK_EVENT_NAME_LENGTH` characters.\n *   - `properties`, when present, must be a plain JSON object whose serialized\n *     size is at most `MAX_TRACK_PROPERTIES_BYTES` bytes.\n */\nexport function validateTrackPayload(\n  body: unknown,\n): TrackRouteValidationResult {\n  if (!isPlainObject(body)) {\n    return { ok: false, error: \"Request body must be a JSON object.\" };\n  }\n\n  const { name, properties } = body as {\n    name?: unknown;\n    properties?: unknown;\n  };\n\n  if (typeof name !== \"string\") {\n    return { ok: false, error: \"`name` must be a string.\" };\n  }\n  const trimmed = name.trim();\n  if (!trimmed) {\n    return { ok: false, error: \"`name` must be a non-empty string.\" };\n  }\n  if (trimmed.length > MAX_TRACK_EVENT_NAME_LENGTH) {\n    return {\n      ok: false,\n      error: `\\`name\\` must be at most ${MAX_TRACK_EVENT_NAME_LENGTH} characters.`,\n    };\n  }\n\n  if (properties !== undefined && !isPlainObject(properties)) {\n    return { ok: false, error: \"`properties` must be a plain JSON object.\" };\n  }\n\n  let serializedProperties: string | undefined;\n  if (properties !== undefined) {\n    try {\n      serializedProperties = JSON.stringify(properties);\n    } catch {\n      return { ok: false, error: \"`properties` must be JSON-serializable.\" };\n    }\n    if (\n      serializedProperties !== undefined &&\n      Buffer.byteLength(serializedProperties, \"utf8\") >\n        MAX_TRACK_PROPERTIES_BYTES\n    ) {\n      return {\n        ok: false,\n        error: `\\`properties\\` must serialize to at most ${MAX_TRACK_PROPERTIES_BYTES} bytes.`,\n      };\n    }\n  }\n\n  return {\n    ok: true,\n    name: trimmed,\n    properties: properties as Record<string, unknown> | undefined,\n  };\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/vite/client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAU,UAAU,EAAE,MAAM,MAAM,CAAC;AAmB/C,OAAO,EAEL,KAAK,iCAAiC,EACvC,MAAM,kCAAkC,CAAC;AA2Z1C,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,6DAA6D;IAC7D,YAAY,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC;IAC9E,oGAAoG;IACpG,QAAQ,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IAClC,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,WAAW,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC;IACvD,wCAAwC;IACxC,MAAM,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC9B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,iCAAiC,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjD;AA+dD,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,MAAM,GAAG,SAAS,CAMpB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAWT;AAoMD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,UAAU,CA4Q1E"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/vite/client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAU,UAAU,EAAE,MAAM,MAAM,CAAC;AAmB/C,OAAO,EAEL,KAAK,iCAAiC,EACvC,MAAM,kCAAkC,CAAC;AAka1C,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,6DAA6D;IAC7D,YAAY,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC;IAC9E,oGAAoG;IACpG,QAAQ,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IAClC,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,WAAW,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC;IACvD,wCAAwC;IACxC,MAAM,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC9B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,iCAAiC,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjD;AA+dD,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,MAAM,GAAG,SAAS,CAMpB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAWT;AAoMD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,UAAU,CAuR1E"}

package/dist/vite/client.js

@@ -191,6 +191,8 @@ function findCoreSrcDir(cwd) {
 const CORE_CLIENT_SUBPATHS = [
     "@agent-native/core",
     "@agent-native/core/client",
+    "@agent-native/core/blocks",
+    "@agent-native/core/blocks/server",
     "@agent-native/core/client/extensions",
     "@agent-native/core/client/tools", // legacy alias
     "@agent-native/core/client/org",
@@ -295,6 +297,8 @@ function getCoreSourceAliases(cwd) {
         "@agent-native/core": path.join(coreSrc, "index.browser.ts"),
         "@agent-native/core/server": path.join(coreSrc, "server/index.ts"),
         "@agent-native/core/client": path.join(coreSrc, "client/index.ts"),
+        "@agent-native/core/blocks": path.join(coreSrc, "client/blocks/index.ts"),
+        "@agent-native/core/blocks/server": path.join(coreSrc, "client/blocks/server.ts"),
         "@agent-native/core/client/extensions": path.join(coreSrc, "client/extensions/index.ts"),
         // Legacy alias — see exports map note above.
         "@agent-native/core/client/tools": path.join(coreSrc, "client/extensions/index.ts"),
@@ -1175,6 +1179,17 @@ export function defineConfig(options = {}) {
                     nitroVitePlugin({
                         serverDir: "./server",
                         ...(options.nitro ?? {}),
+                        // Never auto-load test files as server handlers/plugins/middleware.
+                        // Nitro scans server/{plugins,middleware,routes,api}/*; a co-located
+                        // *.spec.ts would otherwise be loaded at runtime and crash the server
+                        // (its top-level vitest calls throw). Keep tests next to their source safely.
+                        ignore: [
+                            ...(options.nitro?.ignore ?? []),
+                            "**/*.spec.ts",
+                            "**/*.spec.tsx",
+                            "**/*.test.ts",
+                            "**/*.test.tsx",
+                        ],
                         routeRules: {
                             ...mcpEmbedStaticAssetRouteRules(appBasePath),
                             ...(options.nitro