@agent-native/core 0.176.4 → 0.176.5-nightly-20260902205402

package/corpus/templates/calendar/shared/google-calendar-sources.ts

@@ -0,0 +1,46 @@
+export interface GoogleCalendarSourceIdentity {
+  accountEmail: string;
+  calendarId: string;
+}
+
+/**
+ * Calendar ids are provider data and may contain separators, so encode the
+ * complete identity rather than joining two user-controlled strings.
+ */
+export function createGoogleCalendarSourceKey({
+  accountEmail,
+  calendarId,
+}: GoogleCalendarSourceIdentity): string {
+  return `google-calendar:${Buffer.from(
+    JSON.stringify([accountEmail.trim().toLowerCase(), calendarId]),
+  ).toString("base64url")}`;
+}
+
+export function parseGoogleCalendarSourceKey(
+  sourceKey: string,
+): GoogleCalendarSourceIdentity | null {
+  const prefix = "google-calendar:";
+  if (!sourceKey.startsWith(prefix)) return null;
+  try {
+    const parsed: unknown = JSON.parse(
+      Buffer.from(sourceKey.slice(prefix.length), "base64url").toString("utf8"),
+    );
+    if (
+      !Array.isArray(parsed) ||
+      parsed.length !== 2 ||
+      typeof parsed[0] !== "string" ||
+      typeof parsed[1] !== "string" ||
+      !parsed[0].trim() ||
+      !parsed[1]
+    ) {
+      return null;
+    }
+    return {
+      accountEmail: parsed[0].trim().toLowerCase(),
+      calendarId: parsed[1],
+    };
+  } catch {
+    // coercion-ok: malformed opaque input is a typed invalid-key result.
+    return null;
+  }
+}

package/corpus/templates/factory/.env.example

@@ -22,6 +22,11 @@ FACTORY_PUBLIC_URL=https://agent-native-factory.netlify.app
 # or vault row exists. Hosted Factory ignores them.
 # SLACK_BOT_TOKEN=
 # GITHUB_TOKEN=
+# Local-only GitHub App fallback during migration. Hosted Factory reads these
+# from the shared vault, not deployment environment variables.
+# GITHUB_APP_ID=
+# GITHUB_APP_INSTALLATION_ID=
+# GITHUB_APP_PRIVATE_KEY=
 # SENTRY_AUTH_TOKEN=
 
 # Skip login/signup (local dev / preview only)

package/corpus/templates/factory/README.md

@@ -49,6 +49,15 @@ env-only read in a provider client.
 
 ### GitHub token permissions
 
+Factory prefers the new Agent-Native GitHub App. Configure `GITHUB_APP_ID`,
+`GITHUB_APP_INSTALLATION_ID`, and `GITHUB_APP_PRIVATE_KEY` together. The App
+needs repository `Pull requests: Read and write`, `Issues: Read and write`,
+and `Checks: Read`, plus organization `Members: Read` for governance. Hosted
+Factory stores the private key in the shared vault and generates short-lived
+installation tokens server-side. Do not send a static token or private key to
+developers. During migration, an existing `GITHUB_TOKEN` remains supported
+when no App keys are configured.
+
 For Factory pull-request polling and babysitting, scope a fine-grained token to
 the target repository and grant these repository permissions:
 

package/corpus/templates/factory/server/connectors/credentials.ts

@@ -20,8 +20,14 @@ const WORKSPACE_PROVIDER_BY_KEY: Record<string, string> = {
   SLACK_BOT_TOKEN: "slack",
   SLACK_BOT_TOKEN_2: "slack",
 };
+const GITHUB_APP_KEYS = [
+  "GITHUB_APP_ID",
+  "GITHUB_APP_INSTALLATION_ID",
+  "GITHUB_APP_PRIVATE_KEY",
+] as const;
 const VAULT_ONLY_KEYS = new Set([
   ...Object.keys(WORKSPACE_PROVIDER_BY_KEY),
+  ...GITHUB_APP_KEYS,
   "SENTRY_ORG_SLUG",
 ]);
 
@@ -235,6 +241,19 @@ export async function hasConnectorSecret(
   return false;
 }
 
+async function hasGitHubConnectorSecret(
+  ownerEmail: string,
+  options: ResolveConnectorSecretOptions,
+): Promise<boolean> {
+  if (await hasConnectorSecret("GITHUB_TOKEN", ownerEmail, options)) {
+    return true;
+  }
+  const appSecrets = await Promise.all(
+    GITHUB_APP_KEYS.map((key) => hasConnectorSecret(key, ownerEmail, options)),
+  );
+  return appSecrets.every(Boolean);
+}
+
 export async function resolveFactoryConnectorReadiness(
   ownerEmail: string,
   options: ResolveConnectorSecretOptions = {},
@@ -248,7 +267,7 @@ export async function resolveFactoryConnectorReadiness(
   const [slack, slackSecondary, github, sentry] = await Promise.all([
     hasConnectorSecret("SLACK_BOT_TOKEN", ownerEmail, readinessOptions),
     hasConnectorSecret("SLACK_BOT_TOKEN_2", ownerEmail, readinessOptions),
-    hasConnectorSecret("GITHUB_TOKEN", ownerEmail, readinessOptions),
+    hasGitHubConnectorSecret(ownerEmail, readinessOptions),
     hasConnectorSecret(
       ["SENTRY_SERVER_TOKEN", "SENTRY_AUTH_TOKEN"],
       ownerEmail,
@@ -269,11 +288,14 @@ export async function assertFactoryConnectorReady(
   const verb = options.verb ?? "creating";
   const label =
     source === "slack" ? "Slack" : source === "github" ? "GitHub" : "Sentry";
-  const ready = await hasConnectorSecret(
-    connectorKeysForSource(source, options.slackWorkspace),
-    ownerEmail,
-    options,
-  );
+  const ready =
+    source === "github"
+      ? await hasGitHubConnectorSecret(ownerEmail, options)
+      : await hasConnectorSecret(
+          connectorKeysForSource(source, options.slackWorkspace),
+          ownerEmail,
+          options,
+        );
   if (!ready) {
     throw new Error(
       `Connect ${label} in Dispatch or add a vault token before ${verb} this job.`,

package/corpus/templates/factory/server/triage/github-client.ts

@@ -1,3 +1,5 @@
+import { createSign } from "node:crypto";
+
 import { resolveConnectorSecret } from "../connectors/credentials.js";
 import type { TriageCoverage } from "./contracts.js";
 import type { ReviewCommentObservation } from "./pr-babysit.js";
@@ -21,6 +23,45 @@ export interface GitHubClientOptions extends GitHubClientIdentity {
   fetchImpl?: FetchLike;
 }
 
+const GITHUB_APP_KEYS = [
+  "GITHUB_APP_ID",
+  "GITHUB_APP_INSTALLATION_ID",
+  "GITHUB_APP_PRIVATE_KEY",
+] as const;
+const INSTALLATION_TOKEN_CACHE_BUFFER_MS = 60_000;
+
+interface GitHubAppConfig {
+  appId: string;
+  installationId: string;
+  privateKey: string;
+}
+
+function base64Url(value: string): string {
+  return Buffer.from(value).toString("base64url");
+}
+
+function positiveIntegerString(value: string | undefined, key: string): string {
+  if (!value || !/^[1-9]\d*$/.test(value)) {
+    throw new Error(`${key} must be a positive integer string`);
+  }
+  return value;
+}
+
+function normalizePrivateKey(value: string): string {
+  return value.trim().replace(/\\n/g, "\n");
+}
+
+function createGitHubAppJwt(config: GitHubAppConfig): string {
+  const now = Math.floor(Date.now() / 1000);
+  const header = base64Url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const payload = base64Url(
+    JSON.stringify({ iat: now - 60, exp: now + 540, iss: config.appId }),
+  );
+  const signer = createSign("RSA-SHA256");
+  signer.update(`${header}.${payload}`);
+  return `${header}.${payload}.${signer.sign(config.privateKey, "base64url")}`;
+}
+
 export interface GitHubRepositoryRef {
   owner: string;
   repo: string;
@@ -368,14 +409,83 @@ export function createGitHubClient(options: GitHubClientOptions) {
   const fetchImpl = options.fetchImpl ?? fetch;
   const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
 
-  async function token(): Promise<string> {
-    const value = await resolveConnectorSecret(
-      "GITHUB_TOKEN",
-      options.ownerEmail,
-      {
-        orgId: options.orgId,
-      },
+  let cachedAppConfig: GitHubAppConfig | null | undefined;
+  let cachedInstallationToken: { value: string; expiresAt: number } | undefined;
+  let cachedAppBotIdentity: { login: string; id: number } | undefined;
+
+  async function connectorSecret(key: string): Promise<string | undefined> {
+    return resolveConnectorSecret(key, options.ownerEmail, {
+      orgId: options.orgId,
+    });
+  }
+
+  async function appConfig(): Promise<GitHubAppConfig | null> {
+    if (cachedAppConfig !== undefined) return cachedAppConfig;
+    const [appId, installationId, privateKey] = await Promise.all(
+      GITHUB_APP_KEYS.map((key) => connectorSecret(key)),
     );
+    const configured = [appId, installationId, privateKey].filter(
+      Boolean,
+    ).length;
+    if (configured === 0) {
+      cachedAppConfig = null;
+      return cachedAppConfig;
+    }
+    if (configured !== GITHUB_APP_KEYS.length) {
+      throw new Error(
+        "GitHub App configuration is incomplete; configure GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, and GITHUB_APP_PRIVATE_KEY",
+      );
+    }
+    cachedAppConfig = {
+      appId: positiveIntegerString(appId, "GITHUB_APP_ID"),
+      installationId: positiveIntegerString(
+        installationId,
+        "GITHUB_APP_INSTALLATION_ID",
+      ),
+      privateKey: normalizePrivateKey(privateKey as string),
+    };
+    return cachedAppConfig;
+  }
+
+  async function token(): Promise<string> {
+    const app = await appConfig();
+    if (app) {
+      const now = Math.floor(Date.now() / 1000);
+      if (
+        cachedInstallationToken &&
+        cachedInstallationToken.expiresAt >
+          now * 1000 + INSTALLATION_TOKEN_CACHE_BUFFER_MS
+      ) {
+        return cachedInstallationToken.value;
+      }
+      const jwt = createGitHubAppJwt(app);
+      const response = (await fetchImpl(
+        `${baseUrl}/app/installations/${app.installationId}/access_tokens`,
+        {
+          method: "POST",
+          headers: {
+            Accept: "application/vnd.github+json",
+            Authorization: `Bearer ${jwt}`,
+            "X-GitHub-Api-Version": "2022-11-28",
+          },
+        },
+      )) as JsonResponse;
+      if (!response.ok) {
+        throw new Error(
+          `GitHub App installation token request failed: HTTP ${response.status}`,
+        );
+      }
+      const body = record(await response.json());
+      const value = requiredString(body.token, "GitHub App installation token");
+      const expiresAt = Date.parse(
+        requiredString(body.expires_at, "GitHub App token expiry"),
+      );
+      if (!Number.isFinite(expiresAt))
+        throw new Error("GitHub App token expiry is invalid");
+      cachedInstallationToken = { value, expiresAt };
+      return value;
+    }
+    const value = await connectorSecret("GITHUB_TOKEN");
     if (!value)
       throw new Error("GITHUB_TOKEN is not configured for this workspace");
     return value;
@@ -603,6 +713,33 @@ export function createGitHubClient(options: GitHubClientOptions) {
     },
 
     async getAuthenticatedUser() {
+      const app = await appConfig();
+      if (app) {
+        if (!cachedAppBotIdentity) {
+          const response = (await fetchImpl(`${baseUrl}/app`, {
+            headers: {
+              Accept: "application/vnd.github+json",
+              Authorization: `Bearer ${createGitHubAppJwt(app)}`,
+              "X-GitHub-Api-Version": "2022-11-28",
+            },
+          })) as JsonResponse;
+          if (!response.ok) {
+            throw new Error(
+              `GitHub App metadata request failed: HTTP ${response.status}`,
+            );
+          }
+          const metadata = record(await response.json());
+          const login = `${requiredString(metadata.slug, "GitHub App slug")}[bot]`;
+          const bot = record(
+            await request<unknown>(`/users/${encodeURIComponent(login)}`),
+          );
+          cachedAppBotIdentity = {
+            login: requiredString(bot.login, "GitHub App bot login"),
+            id: requiredNumber(bot.id, "GitHub App bot id"),
+          };
+        }
+        return cachedAppBotIdentity;
+      }
       const item = record(await request<unknown>("/user"));
       return {
         login: requiredString(item.login, "authenticated GitHub user login"),

package/corpus/templates/forms/server/lib/form-og-image.ts

@@ -13,21 +13,19 @@ interface FormOgRenderOptions {
 
 const WIDTH = 1200;
 const HEIGHT = 630;
-const BRAND_BLUE = "#00B5FF";
-const BRAND_MINT = "#48FFE4";
-const BG = "#000000";
+const BG = "#0A0A0A";
 const SURFACE = "#0a0a0a";
 const BORDER = "#1f1f1f";
-const FG = "#ededed";
-const MUTED = "#a0a0a0";
+const FG = "#FAF9F5";
+const MUTED = "#9A9997";
 const FONT_FAMILY = "Liberation Sans, Arial, system-ui, sans-serif";
 
 const BADGE_CX = 996;
 const BADGE_CY = 170;
 
 const LOGO_MARK = `
-  <path d="M24.5537 65.7695H0L15.0859 39.4619L37.708 0L60.4912 39.4619H39.6396L24.5537 65.7695Z" fill="white"/>
-  <path d="M89.446 0H114L76.2921 65.7704H51.7383L89.446 0Z" fill="url(#brand)"/>
+  <path d="M26.8789 71.999H0L16.5146 43.1992L41.2793 0L66.2197 43.1992H43.3945L26.8789 71.999Z" fill="white"/>
+  <path d="M97.914 0H124.794L83.5143 72H56.6348L97.914 0Z" fill="white"/>
 `;
 
 const AVATAR_DATA_URL_RE =
@@ -182,28 +180,20 @@ export function renderFormOgImageSvg(input: FormOgImageInput = {}): string {
   );
   const avatarContent = profileImageDataUrl
     ? `<image x="${BADGE_CX - 86}" y="${BADGE_CY - 86}" width="172" height="172" href="${escapeSvg(profileImageDataUrl)}" preserveAspectRatio="xMidYMid slice" mask="url(#avatarMask)"/>`
-    : `<circle cx="${BADGE_CX}" cy="${BADGE_CY}" r="72" fill="url(#brand)" fill-opacity="0.2"/>
+    : `<circle cx="${BADGE_CX}" cy="${BADGE_CY}" r="72" fill="${FG}" fill-opacity="0.12"/>
        <text x="${BADGE_CX}" y="${BADGE_CY + 20}" text-anchor="middle" font-family="${FONT_FAMILY}" font-size="56" font-weight="800" fill="${FG}">${escapeSvg(initials)}</text>`;
 
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${WIDTH}" height="${HEIGHT}" viewBox="0 0 ${WIDTH} ${HEIGHT}">
   <title>${escapeSvg(title)} - Agent-Native Forms preview</title>
   <defs>
-    <linearGradient id="brand" x1="101.702" y1="67.4791" x2="113.672" y2="-37.4275" gradientUnits="userSpaceOnUse">
-      <stop stop-color="${BRAND_BLUE}"/>
-      <stop offset="1" stop-color="${BRAND_MINT}"/>
-    </linearGradient>
-    <pattern id="grid" width="48" height="48" patternUnits="userSpaceOnUse">
-      <path d="M 48 0 L 0 0 0 48" fill="none" stroke="#ffffff" stroke-opacity="0.07" stroke-width="1"/>
-    </pattern>
     <mask id="avatarMask">
       <rect width="${WIDTH}" height="${HEIGHT}" fill="black"/>
       <circle cx="${BADGE_CX}" cy="${BADGE_CY}" r="78" fill="white"/>
     </mask>
   </defs>
   <rect width="${WIDTH}" height="${HEIGHT}" fill="${BG}"/>
-  <rect width="${WIDTH}" height="${HEIGHT}" fill="url(#grid)"/>
   <g transform="translate(80 86)">
-    <g transform="scale(0.62)">
+    <g transform="translate(0 14) scale(0.62)">
       ${LOGO_MARK}
     </g>
     <text x="90" y="31" font-family="${FONT_FAMILY}" font-size="28" font-weight="800" fill="${FG}">Agent-Native</text>

package/corpus/templates/slides/actions/add-slide.ts

@@ -98,6 +98,7 @@ function deckCreativeContext(value: unknown): DeckCreativeContext | null {
 }
 
 export default defineAction({
+  title: "Add slide to deck",
   description:
     "Add a single slide to the real editable Agent-Native Slides deck. This is the primary Slides MCP edit action: use it after create-deck instead of creating or publishing a standalone HTML artifact. " +
     "Build decks slide-by-slide — " +

package/corpus/templates/slides/actions/create-deck.ts

@@ -101,6 +101,7 @@ function deckDeepLink(deckId: string): string {
 }
 
 export default defineAction({
+  title: "Create Slides deck",
   description:
     "Create the real editable Agent-Native Slides deck, optionally already populated with slides, or atomically replace all slides in an existing deck. This is the primary Slides MCP write action: use it instead of creating or publishing a standalone HTML artifact with the host's file tools. Put slide markup in `slides[].content`; this action persists it and returns an Open in Slides link. " +
     "For short AI-generated decks in MCP app hosts, pass all generated slides in this call so the real deck editor opens inline already populated. " +

package/corpus/templates/slides/actions/get-deck.ts

@@ -145,6 +145,7 @@ function deckDeepLink(deckId: string): string {
 }
 
 export default defineAction({
+  title: "Read Slides deck",
   description:
     "Get a specific deck. Pass slideId to return only that slide; targeted agent reads include full HTML by default. In-app agent calls without slideId return compact slide metadata by default; set compact=false when full deck HTML is needed. Frontend and CLI reads remain full unless compact=true. For any continuation or follow-up, call this first and use generationContext as the canonical original brief, references, theme, and target slide count. For source-preserving work, the compact result includes sourceCoverage; do not claim completion until sourceCoverage.complete is true and its expectedSlideIds and actualSlideIds match in order. User-visible slide numbers are 1-based and match the UI: slide 1 is the first slide. Use slideId for edits.",
   timeoutMs: 60_000,

package/corpus/templates/slides/actions/navigate.ts

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { writeAppStateForCurrentTab } from "./_tab-state.js";
 
 export default defineAction({
+  title: "Navigate Slides",
   description:
     "Navigate the UI to a specific deck, slide, or view. Writes a navigate command to application state which the UI reads and auto-deletes.",
   schema: z.object({

package/corpus/templates/slides/actions/patch-deck.ts

@@ -610,6 +610,7 @@ export function isAgentPatchCaller(caller: string | undefined): boolean {
 // ---------------------------------------------------------------------------
 
 export default defineAction({
+  title: "Patch Slides deck",
   description:
     "Granular deck patch used by the browser editor for concurrent-safe writes. " +
     "Each operation touches only the target slide or field — concurrent writers " +

package/corpus/templates/slides/actions/update-slide.ts

@@ -278,6 +278,7 @@ function assertStyleOnlyEdit(
 }
 
 export default defineAction({
+  title: "Edit one Slides slide",
   description:
     "Atomically patch a slide's HTML like a code editor: send several exact edits against the current source, optionally format it with Prettier, and sync the result live to open editors. Use exactly one input mode: edits, legacy find/replace, or fullContent. Mixed modes are rejected and write nothing. Prefer edits over fullContent so unrelated markup is not regenerated, especially for style-only requests, reorders, or changes that must stay consistent across lists, tables, or other representations. For style-only requests, set styleOnly=true and use edits that change only the requested CSS declarations and preserve text and layout properties; the action rejects text or markup changes and fullContent in that mode. Never use unresolved placeholder markers as stand-ins for preserved content. Use baseContentHash from get-deck to reject stale patches, then re-read the targeted slide to verify every affected representation and the requested scope. Content edits clear existing click-reveal metadata; style-only CSS edits preserve it because the HTML structure remains stable. Use patch-deck with the complete animations list when a content edit intentionally changes both content and reveals. Source-imported slides preserve their original images and factual copy by default. The action returns immediately after persistence; layoutFit.status=pending means the open editor will measure the new content asynchronously, and get-layout-overflows can check the returned contentHash plus layoutFitRevision later.",
   schema: z.object({

package/corpus/templates/slides/actions/view-screen.ts

@@ -86,6 +86,7 @@ function getCurrentSlideFitMeasurement(
 }
 
 export default defineAction({
+  title: "Inspect current Slides screen",
   description:
     "See what the user is currently looking at. Returns the CURRENT deck ID, current slide ID, and the full list of slide IDs in the open deck (or the deck list if the user is on the home page). Call this before any slide operation to get the exact IDs you need for add-slide / update-slide / create-deck.",
   schema: z.object({}),

package/corpus/templates/slides/server/plugins/agent-chat.ts

@@ -132,6 +132,8 @@ export default createAgentChatPlugin({
   initialToolNames: INITIAL_TOOL_NAMES,
   mcp: {
     connectorCatalog: INITIAL_TOOL_NAMES,
+    instructions:
+      "For deck edits, call view-screen first when the active deck or slide ID is unknown. Use get-deck to read the target, update-slide for one-slide edits, and patch-deck for deck-wide or multi-slide changes. Read back with get-deck after writing.",
   },
   durableBackgroundRuns: true,
   runSoftTimeoutMs: SLIDES_BACKGROUND_RUN_SOFT_TIMEOUT_MS,

package/dist/action.d.ts

@@ -390,6 +390,8 @@ type InferParams<T extends Record<string, ParameterSchema> | undefined> = T exte
  */
 export type ActionOutputErrorStrategy = "strict" | "warn" | "fallback";
 interface DefineActionWithSchema<TSchema extends StandardSchemaV1, TReturn = any, TOutputSchema extends StandardSchemaV1 | undefined = undefined> {
+    /** Optional human-facing tool title used by WebMCP and MCP hosts. */
+    title?: string;
     description: string;
     /** Standard Schema-compatible schema (Zod, Valibot, ArkType). Provides runtime
      *  validation and full TypeScript type inference for `run()` args. The schema is
@@ -616,6 +618,8 @@ interface DefineActionWithSchema<TSchema extends StandardSchemaV1, TReturn = any
     audit?: ActionAuditConfig;
 }
 interface DefineActionWithParams<TParams extends Record<string, ParameterSchema> | undefined = Record<string, ParameterSchema> | undefined, TReturn = any> {
+    /** Optional human-facing tool title used by WebMCP and MCP hosts. */
+    title?: string;
     description: string;
     /** Flat map of parameter names to their schema. Automatically wrapped in
      *  `{ type: "object", properties: ... }` for the Claude API. */

package/dist/action.js

@@ -214,6 +214,9 @@ export function defineAction(options) {
     const chatUI = normalizeActionChatUIConfig(options.chatUI);
     return {
         tool: {
+            ...(typeof options.title === "string" && options.title.trim()
+                ? { title: options.title.trim() }
+                : {}),
             description: options.description,
             parameters: toolParameters,
         },

package/dist/agent/types.d.ts

@@ -25,6 +25,7 @@ export interface AgentNativeJsonSchema {
     maxItems?: number;
 }
 export interface ActionTool {
+    title?: string;
     description: string;
     parameters?: AgentNativeJsonSchema & {
         type: "object";

package/dist/automation/index.d.ts

@@ -186,8 +186,8 @@ export declare function createAutomationCallbackHandler(runtime: AutomationRunti
     duplicate?: undefined;
     eventId?: undefined;
 } | {
-    error?: undefined;
     accepted: boolean;
     duplicate: boolean;
     eventId: string;
+    error?: undefined;
 }>;

package/dist/client/webmcp.js

@@ -1,3 +1,4 @@
+import { agentNativeToolTitle } from "../shared/agent-mcp-metadata.js";
 export class AgentNativeWebMcpUnsupportedError extends Error {
     constructor() {
         super("WebMCP is not supported by this browser or document");
@@ -254,6 +255,7 @@ export function createAgentNativeServerActionWebMcpRegistration(options) {
             }
             return manifest.map((action) => ({
                 name: action.name,
+                title: agentNativeToolTitle(action.name, action.title),
                 description: action.description,
                 ...(action.inputSchema ? { schema: action.inputSchema } : {}),
                 ...(action.readOnly ? { readOnly: true } : {}),
@@ -310,7 +312,10 @@ function sensitiveAction(action) {
         Boolean(action.approval));
 }
 function actionManifest(action) {
-    const manifest = { ...action };
+    const manifest = {
+        ...action,
+        title: agentNativeToolTitle(action.name, action.title),
+    };
     delete manifest.run;
     return manifest;
 }
@@ -418,7 +423,7 @@ export function createAgentNativeWebMcpRegistration(options) {
                 }
                 await modelContext.registerTool({
                     name: action.name,
-                    ...(action.title ? { title: action.title } : {}),
+                    title: agentNativeToolTitle(action.name, action.title),
                     description: action.description,
                     inputSchema,
                     annotations: {

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
-    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
+    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
-    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
+    error?: undefined;
 }>>;

package/dist/mcp/build-server.d.ts

@@ -35,6 +35,8 @@ export interface MCPConfig {
     appId?: string;
     /** App description */
     description: string;
+    /** Additional host-facing guidance included in the MCP initialize response. */
+    instructions?: string;
     /** Optional canonical website URL for hosts that surface MCP app details. */
     websiteUrl?: string;
     /** Optional app icons for MCP hosts that render server branding. */

package/dist/mcp/build-server.js

@@ -25,6 +25,7 @@ import { writeActionChangeMarker } from "../server/action-change-marker-write.js
 import { getConfiguredAppBasePath } from "../server/app-base-path.js";
 import { buildDeepLink, toAbsoluteOpenUrl, toDesktopOpenUrl, toVsCodeOpenUrl, } from "../server/deep-link.js";
 import { getRequestContext, getRequestOrgId, getRequestUserEmail, runWithRequestContext, } from "../server/request-context.js";
+import { agentNativeMcpInstructions, agentNativeToolTitle, } from "../shared/agent-mcp-metadata.js";
 import { isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "../shared/agent-sidebar-url.js";
 import { MCP_APP_CHAT_BRIDGE_QUERY_PARAM } from "../shared/embed-auth.js";
 import { describeMcpError, readClientInfoFromRequest, trackMcpResourceRead, trackMcpResourcesList, trackMcpToolCall, trackMcpToolsList, } from "./analytics.js";
@@ -1315,6 +1316,7 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
     const supportsMcpApps = compactMcpAppCatalog ||
         Object.values(advertisedActions).some((entry) => Boolean(entry.mcpApp?.resource));
     const server = new Server(mcpServerInfo(config, requestMeta), {
+        instructions: agentNativeMcpInstructions(config.instructions),
         capabilities: {
             tools: {},
             ...(supportsMcpApps
@@ -1486,7 +1488,9 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                         : {}),
                 };
                 const baseDescription = entry.tool.description ?? name;
+                const title = agentNativeToolTitle(name, entry.tool.title);
                 const annotations = {
+                    title,
                     readOnlyHint: entry.readOnly === true,
                     destructiveHint: entry.publicAgent?.isConsequential === true ||
                         entry.needsApproval !== undefined,

package/dist/notifications/routes.d.ts

@@ -11,14 +11,14 @@
  *   DELETE /_agent-native/notifications/:id         — delete
  */
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
-    error?: undefined;
     count: number;
     updated?: undefined;
+    error?: undefined;
     ok?: undefined;
 } | {
-    error?: undefined;
     count?: undefined;
     updated: number;
+    error?: undefined;
     ok?: undefined;
 } | {
     count?: undefined;
@@ -26,8 +26,8 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     count?: undefined;
     updated?: undefined;
+    error?: undefined;
     ok: boolean;
 }>>;

package/dist/observability/routes.d.ts

@@ -41,27 +41,27 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    error?: undefined;
-    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
+    ok?: undefined;
+    error?: undefined;
     id?: undefined;
 } | {
-    error?: undefined;
-    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
-} | {
     ok?: undefined;
+    error?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     error: any;
+    ok?: undefined;
     id?: undefined;
 } | {
-    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     ok: boolean;
+    error?: undefined;
     id?: undefined;
 }>>;