@agent-native/core 0.72.3 → 0.72.4

package/corpus/templates/assets/.agents/skills/a2a-assets/SKILL.md

@@ -1,20 +1,26 @@
 ---
 name: a2a-assets
-description: Call the Assets agent from other agent-native apps to generate, refine, export, and insert brand images or videos.
+description: Use Assets from other apps or MCP hosts to generate, refine, export, and insert brand images or videos.
 ---
 
-# A2A Assets
+# Assets MCP Tool
 
-Use A2A when another app needs brand imagery, video, or reusable source media and Assets owns the library.
+Use the Assets MCP tool surface when another app or external host needs brand
+imagery, video, or reusable source media and Assets owns the library. Prefer the
+pure MCP `generate-asset` flow for human-in-the-loop generation because it can
+return the inline picker. A2A remains useful for unattended cross-app
+delegation, but A2A replies cannot render MCP App pickers.
 
 ## Caller Flow
 
-1. Call `match-library` or `list-libraries` on the Assets agent when the library
-   is ambiguous.
-2. Call `generate-image-batch` with one slot per destination, such as one hero
-   per slide. Always pass `source: "a2a"` and `callerAppId` with the calling
-   app id (`slides`, `design`, `content`, `mail`) so the Assets audit log can
-   group cross-agent generations.
+1. For human selection, call `generate-asset` with the brief, `callerAppId`, and
+   `libraryId` when known. It will match the library, generate candidates, and
+   return the Assets picker filtered to the new run IDs.
+2. For unattended A2A-style work, call `match-library` or `list-libraries` when
+   the library is ambiguous, then call `generate-image-batch` with one slot per
+   destination, such as one hero per slide. Pass `source: "a2a"` and
+   `callerAppId` with the calling app id (`slides`, `design`, `content`,
+   `mail`) so the Assets audit log can group cross-agent generations.
 3. Treat image batches as complete when the action returns. Use returned
    successful `images` entries directly; only regenerate slots that returned
    `ok: false`.
@@ -25,7 +31,8 @@ Use A2A when another app needs brand imagery, video, or reusable source media an
 6. For video, call `generate-video` and then `refresh-generation-run` until the run completes.
 7. Preserve returned `assetId`, `runId`, `previewUrl`, `downloadUrl`, and
    `embedPath` exactly.
-8. Insert exported URLs into the caller's artifact.
+8. Insert chosen/exported URLs into the caller's artifact. Design callers should
+   call `insert-asset` after the picker returns a selected asset.
 9. On feedback, call `refine-image` with the prior `assetId`, `source: "a2a"`,
    and the same `callerAppId`, then replace only the affected destination.
 

package/corpus/templates/assets/.agents/skills/asset-generation/SKILL.md

@@ -16,9 +16,14 @@ or generated image/video assets that another app can reference by ID and URL.
 
 ## Choose The Path
 
-- Use `open-asset-picker` when a person should browse, search, generate, and
-  select an asset in UI. Pass `mediaType: "image"` by default, or
-  `mediaType: "video"` for video libraries.
+- Use `generate-asset` when a person should get newly generated, on-brand image
+  candidates and choose the winner in the inline picker. It matches a library
+  when `libraryId` is omitted, generates candidates, returns the picker filtered
+  to those run IDs, and works in in-app chat plus external MCP hosts.
+- Use `open-asset-picker` when a person should browse, search, or select an
+  existing asset in UI, or when you want the picker to handle generation itself.
+  Pass `mediaType: "image"` by default, or `mediaType: "video"` for video
+  libraries.
 - Use unattended actions when the agent already knows what to do:
   `search-assets`, `list-assets`, `generate-image`, `generate-image-batch`,
   `generate-video`, `refresh-generation-run`, and `export-asset`.
@@ -41,7 +46,9 @@ or generated image/video assets that another app can reference by ID and URL.
 
 ## Image Workflows
 
-1. Pick or match the library with `list-libraries` or `match-library`.
+1. For human-in-the-loop generation, call `generate-asset` first and preserve
+   the returned picker/candidate metadata. For unattended generation, pick or
+   match the library with `list-libraries` or `match-library`.
    If the user wants a default look rather than a brand library, call
    `list-library-presets` and then `create-library-from-preset`; the resulting
    library is editable and reusable like any other library.
@@ -85,8 +92,10 @@ deferred.
   Do not put shared secrets in skill files.
 - Local customization: run `npx @agent-native/core@latest app-skill launch --local` from the
   Assets app-skill manifest, or pass `--into <path>` for editable source.
-- For A2A or MCP callers, include exact `assetId`, `runId`, media type, and
-  URLs in the final response so the caller can attach or embed the media.
+- For MCP callers, `generate-asset` is the portable first choice because the
+  same MCP App picker renders inline in Agent-Native chat, ChatGPT, and Claude
+  when the host supports MCP Apps. Include exact `assetId`, `runId`, media type,
+  and URLs in the final response so the caller can attach or embed the media.
   Include `presetId` and `sessionId` when present.
 
 ## Don't

package/corpus/templates/assets/AGENTS.md

@@ -1,8 +1,9 @@
 # Assets — Agent Guide
 
 Assets is an agent-native asset library and generation workspace. The agent
-manages libraries, images, generated assets, inline embeds, notifications,
-collaboration, and A2A asset requests through actions and SQL state.
+manages libraries, images, generated assets, inline MCP App pickers,
+notifications, collaboration, and portable asset requests through actions and
+SQL state.
 
 Detailed library, generation, image, embed, and engine rules live in
 `.agents/skills/`.
@@ -61,9 +62,10 @@ Read the relevant skill before deeper work:
   plain image-generation requests. Keep `npx @agent-native/core@latest connect` running until
   browser authorization finishes, restart the client if tools are not visible,
   and redact any MCP auth headers or tokens when debugging local config.
-- For human-in-the-loop image creation, call `open-asset-picker` with `prompt`,
-  `autoGenerate: true`, and `count: 3` so the picker opens with candidates to
-  preview, tweak by preset/aspect/count, and choose.
+- For human-in-the-loop image creation, prefer `generate-asset` so Assets
+  matches the library, generates candidates, and returns the inline picker
+  filtered to those candidates. Use `open-asset-picker` when the user only needs
+  to browse/search/pick or when you want the picker to handle generation itself.
 - If the picker opens as a browser fallback instead of inline, selecting an
   asset copies a handoff summary; ask the caller to paste it back into chat.
 - Treat Codex, Claude Code, and Claude Desktop Code as link-out hosts for MCP

package/corpus/templates/assets/actions/generate-asset.ts

@@ -0,0 +1,161 @@
+import { defineAction, embedApp } from "@agent-native/core";
+import { z } from "zod";
+import openAssetPicker from "./open-asset-picker.js";
+import {
+  ASPECT_RATIOS,
+  IMAGE_QUALITY_TIERS,
+  STYLE_STRENGTHS,
+} from "../shared/api.js";
+
+const booleanParam = z.preprocess((value) => {
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") return value;
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["", "0", "false", "no", "off"].includes(normalized)) return false;
+  return value;
+}, z.boolean());
+
+const schema = z.object({
+  mediaType: z.enum(["image", "video"]).default("image"),
+  prompt: z
+    .string()
+    .min(1)
+    .describe("The asset brief to generate or prepare in the picker."),
+  libraryId: z
+    .string()
+    .optional()
+    .describe("Known Assets library ID. Omit to match the best library."),
+  libraryHint: z
+    .string()
+    .optional()
+    .describe(
+      "Brand, campaign, or use-case hint used when matching a library.",
+    ),
+  aspectRatio: z.enum(ASPECT_RATIOS).default("16:9"),
+  presetId: z
+    .string()
+    .optional()
+    .describe("Optional generation preset ID from the selected library."),
+  count: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(6)
+    .default(3)
+    .describe("Number of image candidates to generate in the picker."),
+  tier: z.enum(IMAGE_QUALITY_TIERS).optional(),
+  styleStrength: z.enum(STYLE_STRENGTHS).default("balanced"),
+  includeLogo: booleanParam.default(false),
+  callerAppId: z
+    .string()
+    .optional()
+    .describe("Calling app id, for audit grouping, e.g. design."),
+});
+
+type ActionWithToolParameters = {
+  tool: { parameters?: { properties?: Record<string, any> } };
+};
+
+function allowStringifiedCountInToolSchema<T extends ActionWithToolParameters>(
+  action: T,
+): T {
+  const parameters = action.tool.parameters;
+  const count = parameters?.properties?.count;
+  if (count && typeof count === "object" && !Array.isArray(count)) {
+    parameters!.properties!.count = {
+      description: count.description,
+      default: count.default,
+      anyOf: [
+        count,
+        {
+          type: "string",
+          pattern: "^[1-6]$",
+          description: count.description,
+        },
+      ],
+    };
+  }
+  return action;
+}
+
+const action = defineAction({
+  description:
+    "Open the real Assets picker and start on-brand image generation there so the tool returns immediately and the user can choose the final image/video. Use this for human-in-the-loop brand media requests from Design, Slides, ChatGPT, Claude, or Codex. Preserve returned asset IDs and URLs exactly after the user picks.",
+  schema,
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    title: "Generate an on-brand asset",
+    description:
+      "Start brand-consistent image generation in the Assets picker.",
+  },
+  mcpApp: {
+    compactCatalog: true,
+    resource: embedApp({
+      title: "Generate Assets",
+      description:
+        "Generate image candidates and choose the final asset in the real Assets Library picker.",
+      iframeTitle: "Agent-Native Assets",
+      openLabel: "Open Assets picker",
+      height: 760,
+      connectDomains: ["https://cdn.builder.io"],
+      resourceDomains: ["https://cdn.builder.io"],
+    }),
+  },
+  link: ({ result }) => {
+    const url =
+      result && typeof result === "object"
+        ? (result as { url?: unknown }).url
+        : null;
+    return {
+      url: typeof url === "string" && url ? url : "/library",
+      label: "Open Assets picker",
+      view: "picker",
+    };
+  },
+  run: async (args) => {
+    if (args.mediaType === "video") {
+      const picker = (await openAssetPicker.run({
+        mediaType: "video",
+        prompt: args.prompt,
+        libraryId: args.libraryId,
+        libraryHint: args.libraryHint,
+        count: args.count,
+        callerAppId: args.callerAppId,
+      })) as Record<string, unknown>;
+      return {
+        ...picker,
+        generated: false,
+        message:
+          "Assets video picker is ready. Generate or select the video in the picker, then choose the asset to send it back.",
+      };
+    }
+
+    const picker = (await openAssetPicker.run({
+      mediaType: "image",
+      prompt: args.prompt,
+      libraryId: args.libraryId,
+      libraryHint: args.libraryHint,
+      aspectRatio: args.aspectRatio,
+      presetId: args.presetId,
+      count: args.count,
+      autoGenerate: true,
+      tier: args.tier,
+      styleStrength: args.styleStrength,
+      includeLogo: args.includeLogo,
+      callerAppId: args.callerAppId,
+    })) as Record<string, unknown>;
+    return {
+      ...picker,
+      generated: false,
+      generationStarted: false,
+      generationMode: "picker-auto-generate",
+      message:
+        "Assets picker is ready and will start image generation inside the picker. If this org has no libraries yet, the picker will create a starter library first. Ask the user to pick one candidate; preserve the chosen assetId, runId, and URLs exactly.",
+    };
+  },
+});
+
+export default allowStringifiedCountInToolSchema(action);

package/corpus/templates/assets/actions/list-assets.ts

@@ -95,13 +95,15 @@ export default defineAction({
       .filter((asset) =>
         shouldIncludeAssetInLibraryResults(
           asset,
-          includeCandidates || status === "candidate",
+          includeCandidates ||
+            status === "candidate" ||
+            candidateRunIdSet.size > 0,
         ),
       )
       .filter((asset) => {
         if (!candidateRunIdSet.size) return true;
         if (!(asset.role === "generated" && asset.status === "candidate")) {
-          return true;
+          return false;
         }
         return Boolean(
           asset.generationRunId && candidateRunIdSet.has(asset.generationRunId),

package/corpus/templates/assets/actions/open-asset-picker.ts

@@ -1,7 +1,16 @@
 import { defineAction, embedApp } from "@agent-native/core";
 import { z } from "zod";
+import { IMAGE_QUALITY_TIERS, STYLE_STRENGTHS } from "../shared/api.js";
 
 const mediaTypeSchema = z.enum(["image", "video"]);
+const booleanParam = z.preprocess((value) => {
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") return value;
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["", "0", "false", "no", "off"].includes(normalized)) return false;
+  return value;
+}, z.boolean());
 
 const schema = z.object({
   mediaType: mediaTypeSchema.default("image"),
@@ -17,6 +26,12 @@ const schema = z.object({
     .string()
     .optional()
     .describe("Optional asset library to open in the picker."),
+  libraryHint: z
+    .string()
+    .optional()
+    .describe(
+      "Brand, campaign, or use-case hint used to preselect the best-matching library when libraryId is omitted.",
+    ),
   aspectRatio: z
     .string()
     .optional()
@@ -32,16 +47,62 @@ const schema = z.object({
     .max(6)
     .default(3)
     .describe("Number of image candidates to generate in the picker."),
-  autoGenerate: z.coerce
-    .boolean()
+  candidateRunIds: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Generation run IDs to show as the candidate set when returning from a tool-generated batch.",
+    ),
+  autoGenerate: booleanParam
     .default(false)
     .describe(
       "When true and prompt is provided, generate candidates as soon as the picker opens.",
     ),
+  tier: z
+    .enum(IMAGE_QUALITY_TIERS)
+    .optional()
+    .describe("Optional image quality tier to use for auto-generation."),
+  styleStrength: z
+    .enum(STYLE_STRENGTHS)
+    .default("balanced")
+    .describe("How strongly to follow the library style during generation."),
+  includeLogo: booleanParam
+    .default(false)
+    .describe("Whether auto-generation should include the library logo."),
+  callerAppId: z
+    .string()
+    .optional()
+    .describe("Calling app id, for audit grouping, e.g. design."),
 });
 
 type OpenAssetPickerArgs = z.infer<typeof schema>;
 
+type ActionWithToolParameters = {
+  tool: { parameters?: { properties?: Record<string, any> } };
+};
+
+function allowStringifiedCountInToolSchema<T extends ActionWithToolParameters>(
+  action: T,
+): T {
+  const parameters = action.tool.parameters;
+  const count = parameters?.properties?.count;
+  if (count && typeof count === "object" && !Array.isArray(count)) {
+    parameters!.properties!.count = {
+      description: count.description,
+      default: count.default,
+      anyOf: [
+        count,
+        {
+          type: "string",
+          pattern: "^[1-6]$",
+          description: count.description,
+        },
+      ],
+    };
+  }
+  return action;
+}
+
 const FALLBACK_INSTRUCTIONS =
   'If the picker opens in a normal browser tab instead of inline, the user has two ways to choose: (1) click an asset — the picker auto-copies a short handoff summary they paste back into chat, or (2) just tell you which one in words (e.g. "use the second image"). Either way, continue with the chosen asset. In Codex, Claude Code, and other code-editor chats, do not expect MCP Apps to render inline; provide the asset link, and if the final answer needs an inline image preview, download the selected image URL locally and embed the absolute local file path because remote CDN markdown previews may not render there.';
 
@@ -51,16 +112,28 @@ function pickerPath(args: Partial<OpenAssetPickerArgs>): string {
   if (args.prompt?.trim()) params.set("prompt", args.prompt.trim());
   if (args.query?.trim()) params.set("q", args.query.trim());
   if (args.libraryId?.trim()) params.set("libraryId", args.libraryId.trim());
+  if (args.libraryHint?.trim()) {
+    params.set("libraryHint", args.libraryHint.trim());
+  }
   if (args.aspectRatio?.trim()) {
     params.set("aspectRatio", args.aspectRatio.trim());
   }
   if (args.presetId?.trim()) params.set("presetId", args.presetId.trim());
   if (args.count && args.count !== 3) params.set("count", String(args.count));
+  if (args.tier) params.set("tier", args.tier);
+  if (args.styleStrength && args.styleStrength !== "balanced") {
+    params.set("styleStrength", args.styleStrength);
+  }
+  if (args.includeLogo) params.set("includeLogo", "1");
+  if (args.callerAppId?.trim()) params.set("callerAppId", args.callerAppId);
+  for (const runId of args.candidateRunIds ?? []) {
+    if (runId.trim()) params.append("candidateRunIds", runId.trim());
+  }
   if (args.autoGenerate) params.set("autoGenerate", "1");
   return `/library?${params.toString()}`;
 }
 
-export default defineAction({
+const action = defineAction({
   description:
     'Open the image Library picker inline so a person can browse, search, generate, and select an image or video asset. When the user asks to create a specific image and choose the best one, pass prompt, autoGenerate: true, and count: 3 so the Library opens with generated candidates. If the host can only open a browser link (e.g. a CLI or code editor), surface that link: after the user picks, the page auto-copies a short paste-back summary — or the user can simply tell you which candidate they want (e.g. "use image A"). Use search-assets, generate-image, generate-video, and export-asset for unattended flows.',
   schema,
@@ -122,10 +195,18 @@ export default defineAction({
       query: args.query ?? null,
       prompt: args.prompt ?? null,
       libraryId: args.libraryId ?? null,
+      libraryHint: args.libraryHint ?? null,
       aspectRatio: args.aspectRatio ?? null,
       presetId: args.presetId ?? null,
       count: args.count,
+      tier: args.tier ?? null,
+      styleStrength: args.styleStrength,
+      includeLogo: args.includeLogo,
+      callerAppId: args.callerAppId ?? null,
+      candidateRunIds: args.candidateRunIds ?? [],
       autoGenerate: args.autoGenerate,
     };
   },
 });
+
+export default allowStringifiedCountInToolSchema(action);