@agent-native/core 0.72.3 → 0.73.0

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);