@agent-native/core 0.118.0 → 0.119.0

package/src/server/agent-chat-plugin.ts

@@ -13,6 +13,11 @@ import {
   type H3Event,
 } from "h3";
 
+import {
+  applyA2AAgentActivityEvent,
+  buildA2AAgentActivityPart,
+  createA2AAgentActivityState,
+} from "../a2a/activity.js";
 import {
   appendA2AArtifactLinks,
   buildA2ARecoverableArtifactMessage,
@@ -400,6 +405,8 @@ export function createSerializedA2ATaskStatusWriter(
   };
 }
 
+const A2A_ACTIVITY_CHECKPOINT_MIN_INTERVAL_MS = 2_000;
+
 export async function resolveA2ARecoverableArtifactSecret(
   orgId: string | null | undefined = getRequestOrgId(),
 ): Promise<string | undefined> {
@@ -1656,10 +1663,36 @@ export function createAgentChatPlugin(
           const a2aEvents: AgentChatEvent[] = [];
           const a2aToolResults: A2AToolResultSummary[] = [];
           let lastRecoverableArtifactText = "";
+          let activityState = createA2AAgentActivityState();
+          let lastActivityCheckpointAt = 0;
           const recoverableArtifactSecret =
             await resolveA2ARecoverableArtifactSecret();
           const recoverableArtifactStatusWriter =
             createSerializedA2ATaskStatusWriter(context.taskId);
+          const activityStatusMessage = (): A2AMessage => ({
+            role: "agent",
+            ...(lastRecoverableArtifactText
+              ? { metadata: { agentNativeRecoverableArtifacts: true } }
+              : {}),
+            parts: [
+              buildA2AAgentActivityPart(activityState),
+              ...(lastRecoverableArtifactText
+                ? [{ type: "text" as const, text: lastRecoverableArtifactText }]
+                : []),
+            ],
+          });
+          const checkpointActivity = (force = false) => {
+            const now = Date.now();
+            if (
+              !force &&
+              now - lastActivityCheckpointAt <
+                A2A_ACTIVITY_CHECKPOINT_MIN_INTERVAL_MS
+            ) {
+              return;
+            }
+            lastActivityCheckpointAt = now;
+            recoverableArtifactStatusWriter.enqueue(activityStatusMessage());
+          };
           const controller = new AbortController();
           const correlation = sanitizeA2ACorrelationMetadata(context.metadata);
           const telemetryThreadId =
@@ -1697,6 +1730,12 @@ export function createAgentChatPlugin(
               turnId: context.taskId,
               send: (event) => {
                 a2aEvents.push(event);
+                const nextActivityState = applyA2AAgentActivityEvent(
+                  activityState,
+                  event,
+                );
+                const activityChanged = nextActivityState !== activityState;
+                activityState = nextActivityState;
                 if (event.type === "tool_start") {
                   console.log(`[A2A] Tool call: ${event.tool}`);
                 } else if (event.type === "tool_done") {
@@ -1727,22 +1766,20 @@ export function createAgentChatPlugin(
                     recoverableArtifactText !== lastRecoverableArtifactText
                   ) {
                     lastRecoverableArtifactText = recoverableArtifactText;
-                    recoverableArtifactStatusWriter.enqueue({
-                      role: "agent",
-                      metadata: { agentNativeRecoverableArtifacts: true },
-                      parts: [
-                        {
-                          type: "text",
-                          text: recoverableArtifactText,
-                        },
-                      ],
-                    });
                   }
                 } else if (event.type === "error") {
                   console.error(`[A2A] Error: ${event.error}`);
                 } else if (event.type === "done") {
                   console.log(`[A2A] Done. Events: ${a2aEvents.length}`);
                 }
+                if (activityChanged) {
+                  checkpointActivity(
+                    event.type === "tool_start" ||
+                      event.type === "tool_done" ||
+                      event.type === "error" ||
+                      event.type === "done",
+                  );
+                }
               },
               signal: controller.signal,
             },
@@ -1779,6 +1816,7 @@ export function createAgentChatPlugin(
 
           // The continuation can observe terminal output immediately, so make
           // its latest mutation checkpoint durable first.
+          checkpointActivity(true);
           await recoverableArtifactStatusWriter.flush();
 
           const approval = [...a2aEvents]
@@ -1817,6 +1855,7 @@ export function createAgentChatPlugin(
                 },
               },
               parts: [
+                buildA2AAgentActivityPart(activityState),
                 {
                   type: "text" as const,
                   text:
@@ -1851,6 +1890,7 @@ export function createAgentChatPlugin(
           yield {
             role: "agent" as const,
             parts: [
+              buildA2AAgentActivityPart(activityState),
               {
                 type: "text" as const,
                 text: finalText || "(no response)",

package/src/server/realtime-voice.ts

@@ -201,7 +201,10 @@ export function resolveRealtimeVoiceReasoningEffort(
 ): "minimal" | "low" | "medium" {
   const normalized = value?.trim().toLowerCase();
   return normalized &&
-    Object.hasOwn(REALTIME_VOICE_REASONING_EFFORT, normalized)
+    Object.prototype.hasOwnProperty.call(
+      REALTIME_VOICE_REASONING_EFFORT,
+      normalized,
+    )
     ? REALTIME_VOICE_REASONING_EFFORT[
         normalized as keyof typeof REALTIME_VOICE_REASONING_EFFORT
       ]

package/src/templates/workspace-core/.agents/skills/a2a-protocol/SKILL.md

@@ -195,6 +195,22 @@ for await (const update of client.stream({
 }
 ```
 
+### Agent activity in delegated chat
+
+Agent Native peers attach a bounded `data` part with
+`kind: "agent-native/agent-activity"` to in-progress and terminal task status
+messages. It contains the same user-visible reasoning summaries shown in the
+receiving app, tool names and completion states, elapsed time, and progressive
+response text. It never includes tool inputs, tool results, credentials, or
+hidden provider reasoning.
+
+`call-agent` reads this optional part while it polls an asynchronous task and
+renders the remote work as a nested agent run. Unknown A2A peers do not need to
+implement the extension: their ordinary status and final text still render in
+the same nested block. Treat activity data as untrusted presentation content;
+never use it for identity, authorization, approval, routing, or artifact
+validation.
+
 ### Carrying explicit chat authorization
 
 When the authenticated caller has an exact consequential action that the user

package/src/templates/workspace-core/.agents/skills/voice-transcription/SKILL.md

@@ -57,11 +57,13 @@ action before requesting microphone permission.
   controls contain only settings and the separate end-session action.
 - The orb's compact waveform stays visible for the full session and reflects
   actual microphone or assistant audio activity. At silence it rests at its
-  baseline instead of turning into a loading spinner. While connecting, show a
-  distinct compact spinner; when the session becomes live, the assistant gives
-  one brief spoken greeting so readiness is unambiguous. Do not apply a
-  text-sized `max_output_tokens` cap to that audio greeting because audio tokens
-  can truncate it mid-sentence.
+  baseline instead of turning into a loading spinner. Once connected, a soft,
+  slowly rotating blue glow marks the live session; brighten and speed up the
+  glow while the agent is working, and keep it static under reduced motion.
+  While connecting, show a distinct compact spinner; when the session becomes
+  live, the assistant gives one brief spoken greeting so readiness is
+  unambiguous. Do not apply a text-sized `max_output_tokens` cap to that audio
+  greeting because audio tokens can truncate it mid-sentence.
 - The orb settings cog opens in place without ending voice mode or navigating
   away. Nested pickers must not dismiss the settings popover. Language and
   intelligence update the active Realtime session; the microphone picker swaps

package/src/terminal/cli-registry.ts

@@ -42,7 +42,7 @@ export const CLI_REGISTRY: Record<string, CliEntry> = {
 
 /** Check if a command name is in the CLI_REGISTRY allowlist */
 export function isAllowedCommand(cmd: string): boolean {
-  return Object.hasOwn(CLI_REGISTRY, cmd);
+  return Object.prototype.hasOwnProperty.call(CLI_REGISTRY, cmd);
 }
 
 /** Check if a CLI command exists on PATH (safe — no shell interpolation) */

package/src/vite/client.ts

@@ -732,7 +732,6 @@ function findCorePackageRoot(cwd: string): string | null {
   const candidates = [
     path.resolve(cwd, "../../packages/core"), // templates/<name>/
     path.resolve(cwd, "../core"), // packages/<name>/
-    path.resolve(cwd, "node_modules/@agent-native/core"),
   ];
   for (const candidate of candidates) {
     try {
@@ -2315,6 +2314,165 @@ function portExposer(): Plugin {
   };
 }
 
+function isNitroEnvironmentUnavailable(error: unknown): boolean {
+  const candidate = error as {
+    name?: unknown;
+    status?: unknown;
+    statusCode?: unknown;
+    message?: unknown;
+  };
+  return (
+    candidate?.name === "NitroViteError" &&
+    (candidate.status === 503 || candidate.statusCode === 503) &&
+    typeof candidate.message === "string" &&
+    /Vite environment .+ is unavailable/.test(candidate.message)
+  );
+}
+
+type NitroModuleNode = {
+  id: string | null;
+  ssrError?: Error | null;
+  transformResult: unknown | null;
+};
+
+type NitroModuleGraph = {
+  idToModuleMap: Map<string, NitroModuleNode>;
+};
+
+const NITRO_STARTUP_SETTLE_MS = 1_000;
+const NITRO_STARTUP_TIMEOUT_MS = 30_000;
+
+function nitroModuleGraphSignature(environment: unknown): string | null {
+  const graph = (environment as { moduleGraph?: NitroModuleGraph } | undefined)
+    ?.moduleGraph;
+  if (!graph) return null;
+
+  const modules = [...graph.idToModuleMap.values()];
+  const entry = modules.find((module) =>
+    module.id
+      ?.replaceAll("\\", "/")
+      .endsWith("/nitro/dist/runtime/internal/vite/dev-entry.mjs"),
+  );
+  if (!entry?.transformResult && !entry?.ssrError) return null;
+
+  let transformed = 0;
+  let errors = 0;
+  for (const module of modules) {
+    if (module.transformResult) transformed += 1;
+    if (module.ssrError) errors += 1;
+  }
+  return `${modules.length}:${transformed}:${errors}`;
+}
+
+function isHtmlDocumentRequest(req: IncomingMessage): boolean {
+  return (
+    (req.method === "GET" || req.method === "HEAD") &&
+    (req.headers.accept ?? "").includes("text/html")
+  );
+}
+
+function sendNitroStartingResponse(
+  req: IncomingMessage,
+  res: ServerResponse,
+): void {
+  res.statusCode = 503;
+  res.setHeader("cache-control", "no-store");
+  res.setHeader("content-type", "text/html; charset=utf-8");
+  res.setHeader("retry-after", "1");
+  if (req.method === "HEAD") {
+    res.end();
+    return;
+  }
+  res.end(
+    '<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0.25"><title>Starting…</title></head><body></body></html>',
+  );
+}
+
+function nitroStartupGate(
+  options: {
+    now?: () => number;
+    settleMs?: number;
+    timeoutMs?: number;
+  } = {},
+): Plugin {
+  return {
+    name: "agent-native-nitro-startup-gate",
+    apply: "serve",
+    enforce: "pre",
+    configureServer(server) {
+      const now = options.now ?? Date.now;
+      const settleMs = options.settleMs ?? NITRO_STARTUP_SETTLE_MS;
+      const timeoutMs = options.timeoutMs ?? NITRO_STARTUP_TIMEOUT_MS;
+      const startedAt = now();
+      let graphSignature: string | null = null;
+      let graphStableAt: number | undefined;
+      let startupComplete = false;
+
+      server.middlewares.use((req, res, next) => {
+        if (startupComplete || !isHtmlDocumentRequest(req)) {
+          next();
+          return;
+        }
+
+        const timestamp = now();
+        if (timestamp - startedAt >= timeoutMs) {
+          startupComplete = true;
+          next();
+          return;
+        }
+
+        const nextGraphSignature = nitroModuleGraphSignature(
+          server.environments?.nitro,
+        );
+        if (nextGraphSignature) {
+          if (nextGraphSignature !== graphSignature) {
+            graphSignature = nextGraphSignature;
+            graphStableAt = timestamp;
+          } else if (
+            graphStableAt !== undefined &&
+            timestamp - graphStableAt >= settleMs
+          ) {
+            startupComplete = true;
+            next();
+            return;
+          }
+        } else {
+          graphSignature = null;
+          graphStableAt = undefined;
+        }
+
+        sendNitroStartingResponse(req, res);
+      });
+    },
+  };
+}
+
+function nitroStartupRecovery(): Plugin {
+  return {
+    name: "agent-native-nitro-startup-recovery",
+    apply: "serve",
+    configureServer(server) {
+      server.middlewares.use(function nitroStartupErrorRecovery(
+        error: unknown,
+        req: IncomingMessage,
+        res: ServerResponse,
+        next: (error?: unknown) => void,
+      ) {
+        if (
+          !isNitroEnvironmentUnavailable(error) ||
+          !isHtmlDocumentRequest(req) ||
+          res.headersSent
+        ) {
+          next(error);
+          return;
+        }
+
+        sendNitroStartingResponse(req, res);
+      });
+    },
+  };
+}
+
 /**
  * Silence benign connection-reset noise from Vite's dev middleware.
  * Fires when a browser closes/reloads/navigates mid-request — the peer has
@@ -2693,6 +2851,7 @@ function createAgentNativePlugins(
     embedDevFrameHeaders(),
     baseRedirectGuard(),
     portExposer(),
+    nitroStartupGate(),
     silenceConnectionResets(),
     rolldownInputFix(),
     // Nitro Vite plugin for dev-mode API route serving and HMR.
@@ -2702,6 +2861,9 @@ function createAgentNativePlugins(
       : includeNitro
         ? [nitroPlugin]
         : []),
+    // Nitro can reject the first document request while its Vite environment
+    // is still importing. This error handler must follow Nitro's middleware.
+    nitroStartupRecovery(),
     includeReactTransform ? createReactTransformPlugin() : null,
     createDesignSystemThemePlugin(options.designSystemTheme),
     createTailwindPlugin(options),
@@ -3096,5 +3258,8 @@ export {
   getDefaultOptimizeDeps as _getDefaultOptimizeDeps,
   findCorePackageRoot as _findCorePackageRoot,
   getReactRouterAliases as _getReactRouterAliases,
+  nitroStartupGate as _nitroStartupGate,
+  nitroStartupRecovery as _nitroStartupRecovery,
+  nitroModuleGraphSignature as _nitroModuleGraphSignature,
   debounceNitroFullReloadHotUpdate as _debounceNitroFullReloadHotUpdate,
 };

package/corpus/core/src/observability/hosted-model-experiment.ts

@@ -1,118 +0,0 @@
-export const HOSTED_DEFAULT_MODEL_EXPERIMENT_ID =
-  "hosted-default-model-sonnet-5-vs-gpt-5-6-luna-2026-07";
-
-export const HOSTED_DEFAULT_MODEL_CONTROL = {
-  id: "sonnet-5",
-  model: "claude-sonnet-5",
-  weight: 80,
-} as const;
-
-export const HOSTED_DEFAULT_MODEL_TREATMENT = {
-  id: "gpt-5-6-luna",
-  model: "gpt-5-6-luna",
-  weight: 20,
-} as const;
-
-export interface HostedDefaultModelExperimentAssignment {
-  experimentId: string;
-  variantId: string;
-}
-
-export interface HostedDefaultModelExperimentResolution {
-  model: string;
-  assignment: HostedDefaultModelExperimentAssignment;
-}
-
-type HostedExperimentEnv = Record<string, string | undefined>;
-
-const FIRST_PARTY_HOST_SUFFIX = ".agent-native.com";
-const ENABLED_VALUES = new Set(["1", "true", "on", "yes"]);
-const DISABLED_VALUES = new Set(["0", "false", "off", "no"]);
-
-function hostnameFromUrl(value: string | undefined): string | null {
-  const trimmed = value?.trim();
-  if (!trimmed) return null;
-  try {
-    const url = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)
-      ? new URL(trimmed)
-      : new URL(`https://${trimmed}`);
-    return url.hostname.toLowerCase();
-  } catch {
-    return null;
-  }
-}
-
-/**
- * The rollout is automatic only on first-party hosted app domains. Operators
- * can explicitly enable or disable it for preview and emergency rollback.
- */
-export function isHostedDefaultModelExperimentEnabled(
-  env: HostedExperimentEnv = process.env,
-): boolean {
-  const override =
-    env.AGENT_NATIVE_HOSTED_MODEL_EXPERIMENT?.trim().toLowerCase();
-  if (override && DISABLED_VALUES.has(override)) return false;
-  if (override && ENABLED_VALUES.has(override)) return true;
-
-  const hostnames = [
-    env.APP_URL,
-    env.BETTER_AUTH_URL,
-    env.URL,
-    env.DEPLOY_URL,
-    env.VERCEL_PROJECT_PRODUCTION_URL,
-    env.VERCEL_URL,
-  ]
-    .map(hostnameFromUrl)
-    .filter((hostname): hostname is string => Boolean(hostname));
-
-  return hostnames.some(
-    (hostname) =>
-      hostname === "agent-native.com" ||
-      hostname.endsWith(FIRST_PARTY_HOST_SUFFIX),
-  );
-}
-
-/**
- * Stable cross-app bucket: the same authenticated user receives the same
- * variant in every hosted template for the life of this experiment id.
- */
-export function hostedDefaultModelExperimentBucket(userId: string): number {
-  const input = `${HOSTED_DEFAULT_MODEL_EXPERIMENT_ID}:${userId.trim().toLowerCase()}`;
-  let hash = 0x811c9dc5;
-  for (let index = 0; index < input.length; index++) {
-    hash ^= input.charCodeAt(index);
-    hash = Math.imul(hash, 0x01000193);
-  }
-  return (hash >>> 0) % 100;
-}
-
-export function resolveHostedDefaultModelExperiment(args: {
-  userId: string | null | undefined;
-  engineName: string;
-  isDefaultModelSelection: boolean;
-  supportedModels?: readonly string[];
-  env?: HostedExperimentEnv;
-}): HostedDefaultModelExperimentResolution | null {
-  const userId = args.userId?.trim();
-  if (!userId) return null;
-  if (args.engineName !== "builder") return null;
-  if (!args.isDefaultModelSelection) return null;
-  if (!isHostedDefaultModelExperimentEnabled(args.env)) return null;
-
-  const variant =
-    hostedDefaultModelExperimentBucket(userId) <
-    HOSTED_DEFAULT_MODEL_TREATMENT.weight
-      ? HOSTED_DEFAULT_MODEL_TREATMENT
-      : HOSTED_DEFAULT_MODEL_CONTROL;
-  if (args.supportedModels && !args.supportedModels.includes(variant.model)) {
-    return null;
-  }
-
-  return {
-    model: variant.model,
-    assignment: {
-      experimentId: HOSTED_DEFAULT_MODEL_EXPERIMENT_ID,
-      variantId: variant.id,
-    },
-  };
-}

package/corpus/templates/crm/.agents/skills/agent-native-docs/SKILL.md

@@ -1,115 +0,0 @@
----
-name: agent-native-docs
-description: >-
-  How to find version-matched Agent Native framework docs and source bundled in
-  node_modules. Use before implementing or answering questions about
-  @agent-native/core APIs, generated apps, workspaces, templates, or advanced
-  features.
-scope: dev
-metadata:
-  internal: true
----
-
-# Agent Native Docs Lookup
-
-## Rule
-
-Before implementing or explaining non-trivial Agent Native behavior, read the
-version-matched docs installed with `@agent-native/core`. When examples,
-imports, or implementation details matter, inspect the packaged source corpus
-too.
-
-## Why
-
-Generated apps and workspaces may be on a different framework version than the
-public docs or model memory. The installed package is the source that matches
-the app in front of you. It also includes a source-only corpus of core and
-first-party templates so agents can replicate current best-practice patterns
-without needing the framework monorepo checkout.
-
-## How
-
-From a generated app directory:
-
-```bash
-pnpm action docs-search --query "<feature>"
-pnpm action docs-search --slug <slug>
-pnpm action docs-search --list
-pnpm action source-search --query "<pattern>"
-pnpm action source-search --path templates/plan/AGENTS.md
-pnpm action source-search --path toolkit/src/index.ts
-pnpm action source-search --list
-```
-
-The headless `pnpm agent` loop and built-in app agent also expose a read-only
-`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
-read-only `source-search` tool with `query`, `path`, and `list`.
-
-If the action runner is unavailable, search the package directly:
-
-```bash
-rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
-rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
-```
-
-Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
-under `node_modules/@agent-native/core/docs/content/`. For source examples,
-read files under `node_modules/@agent-native/core/corpus/core/` or
-`node_modules/@agent-native/core/corpus/templates/`.
-
-Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
-readable TypeScript under `node_modules/@agent-native/toolkit/src/`. Read
-`customizing-agent-native` before taking ownership of a shared component: inspect package
-source as a read-only reference, then configure, compose, or eject the smallest
-supported unit into app-owned source. Preserve public actions, application
-state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
-deep-import its private source. Manual copying is only the fallback described by
-an unknown third-party package's add-style blueprint.
-
-## Reuse Proven Patterns (rg + cp)
-
-Version-matched installed source outranks web docs or memory: it is the exact
-code shipping with this app. `node_modules/@agent-native/core/corpus/templates/`
-holds source for every first-party template, not just the one this app started
-from, so a pattern from the mail template is fair game for a tasks app. Grep
-across it, then copy a whole file as a starting point instead of writing the
-pattern from scratch:
-
-```bash
-# Find how other templates solved a similar problem
-rg -n "drag.*drop|reorder" node_modules/@agent-native/core/corpus/templates
-
-# Grab a proven action file as a starting point, then adapt names/schema
-cp node_modules/@agent-native/core/corpus/templates/mail/actions/archive-email.ts \
-   actions/archive-item.ts
-
-# Read the full framework source behind an API, not just the corpus copy
-rg -n "defineAction" node_modules/@agent-native/core/src/action.ts
-```
-
-Copying template-level app code (actions, components, skill files) is the
-expected reuse path — templates exist to be forked. This is different from
-copying `core`/`toolkit` **runtime internals**: for those, follow
-`customizing-agent-native`'s configure/compose/eject ladder instead of
-hand-duplicating framework logic.
-
-## Useful Slugs
-
-| Need                           | Slugs                                                         |
-| ------------------------------ | ------------------------------------------------------------- |
-| Actions and typed client calls | `actions`, `client`                                           |
-| SQL, auth, access, sharing     | `database`, `authentication`, `security`, `sharing`           |
-| UI state visible to the agent  | `context-awareness`                                           |
-| Headless and chat-first apps   | `pure-agent-apps`, `agent-surfaces`, `using-your-agent`       |
-| Automations and schedules      | `automations`, `recurring-jobs`                               |
-| Cross-app and external agents  | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
-| Skills and instructions        | `skills-guide`, `writing-agent-instructions`                  |
-
-## Don't
-
-- Do not rely on memory for framework APIs when package docs are present.
-- Do not add custom REST wrappers for app data before reading `actions`.
-- Do not add inline LLM calls before reading `using-your-agent` and
-  `agent-surfaces`.
-- Do not copy framework runtime internals when a public API or narrow UI copy
-  will do; read `customizing-agent-native` for the supported override ladder.