Function handleListCreatives

server/src/training-agent/task-handlers.ts:2153–2238

(args: ToolArgs, ctx: TrainingContext)

}

export async function handleListCreatives(args: ToolArgs, ctx: TrainingContext) {
  const req = args as unknown as ListCreativesRequest & ToolArgs & { creative_ids?: string[]; include_pricing?: boolean; include_snapshot?: boolean };
  const session = await getSession(sessionKeyFromArgs(req, ctx.mode, ctx.userId, ctx.moduleId));
  const filterIds = req.creative_ids || req.filters?.creative_ids;

  let creatives = Array.from(session.creatives.values());
  if (filterIds?.length) {
    creatives = creatives.filter(c => filterIds.includes(c.creativeId));
  } else if (creatives.length === 0) {
    // Empty session falls back to compliance fixtures so storyboards that
    // reference stable IDs (e.g., campaign_hero_video in creative_ad_server)
    // resolve without the SDK's controller_seeding auto-fire. Sessions that
    // have synced their own creatives return only those — no mixing.
    creatives = getComplianceCreatives();
  }

  const totalMatching = creatives.length;
  // Schema declares max_results min=1, max=100, default=50. Honor the cap;
  // do not silently lift sub-1 values — those should surface as schema
  // violations through the SDK's request validator, not be quietly corrected.
  const requestedMax = req.pagination?.max_results;
  const maxResults = Math.min(typeof requestedMax === 'number' ? requestedMax : 50, 100);
  const offset = decodeCreativeCursor(req.pagination?.cursor);
  if (offset === null) {
    return {
      errors: [{ code: 'INVALID_REQUEST', message: 'pagination.cursor is malformed' }] as TaskError[],
    };
  }
  const pageEnd = Math.min(offset + maxResults, totalMatching);
  const pageCreatives = creatives.slice(offset, pageEnd);
  const hasMore = pageEnd < totalMatching;

  // Ad-server-capable sellers (creative.has_creative_library) quote per-
  // creative pricing whenever an account is present, independent of the
  // buyer setting include_pricing. Explicit `include_pricing: false` still
  // suppresses — matches the spec wording while letting callers that omit
  // the flag (e.g., SDK request builders that drop it) still receive pricing.
  // Spec today says "When false or omitted, pricing is not computed"; the
  // emission-on-omit behaviour here is deliberate per the has_creative_library
  // gate in #2847 and tracks the spec-side clarification referenced there.
  const emitPricing = Boolean(req.account) && req.include_pricing !== false;
  const agentUrl = getAgentUrl();

  return {
    query_summary: {
      total_matching: totalMatching,
      returned: pageCreatives.length,
    },
    pagination: {
      has_more: hasMore,
      total_count: totalMatching,
      // Cursor MUST be present iff has_more is true — see
      // static/schemas/source/core/pagination-response.json. Carrying a stale
      // cursor on a terminal page invites callers to follow it past the end
      // (caught by universal/pagination-integrity.yaml).
      ...(hasMore && { cursor: encodeCreativeCursor(pageEnd) }),
    },
    creatives: pageCreatives.map(c => {