@aigne/core 1.72.0-beta.2 → 1.72.0-beta.3

package/lib/cjs/prompt/template.d.ts

@@ -27,35 +27,38 @@ export declare class ChatMessageTemplate {
     content?: ChatModelInputMessage["content"];
     name?: string | undefined;
     options?: FormatOptions | undefined;
-    constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined, options?: FormatOptions | undefined);
+    cacheControl?: ChatModelInputMessage["cacheControl"];
+    constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined, options?: FormatOptions | undefined, cacheControl?: ChatModelInputMessage["cacheControl"]);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage>;
 }
 export declare class SystemMessageTemplate extends ChatMessageTemplate {
-    static from(content: string, name?: string, options?: FormatOptions): SystemMessageTemplate;
+    static from(content: string, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): SystemMessageTemplate;
 }
 export declare class UserMessageTemplate extends ChatMessageTemplate {
-    static from(template: ChatModelInputMessageContent, name?: string, options?: FormatOptions): UserMessageTemplate;
+    static from(template: ChatModelInputMessageContent, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): UserMessageTemplate;
 }
 export declare class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls?: ChatModelOutputToolCall[] | undefined;
-    static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string, options?: FormatOptions): AgentMessageTemplate;
-    constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string, options?: FormatOptions);
+    static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): AgentMessageTemplate;
+    constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]);
     format(_variables?: Record<string, unknown>, _options?: FormatOptions): Promise<{
         role: "agent" | "system" | "user" | "tool";
         name: string | undefined;
         content: ChatModelInputMessageContent | undefined;
         toolCalls: ChatModelOutputToolCall[] | undefined;
+        cacheControl: import("../agents/chat-model.js").CacheControl | undefined;
     }>;
 }
 export declare class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId: string;
-    static from(content: object | string, toolCallId: string, name?: string, options?: FormatOptions): ToolMessageTemplate;
-    constructor(content: object | string, toolCallId: string, name?: string, options?: FormatOptions);
+    static from(content: object | string, toolCallId: string, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): ToolMessageTemplate;
+    constructor(content: object | string, toolCallId: string, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]);
     format(_variables?: Record<string, unknown>, _options?: FormatOptions): Promise<{
         role: "agent" | "system" | "user" | "tool";
         name: string | undefined;
         content: ChatModelInputMessageContent | undefined;
         toolCallId: string;
+        cacheControl: import("../agents/chat-model.js").CacheControl | undefined;
     }>;
 }
 export declare class ChatMessagesTemplate {
@@ -69,26 +72,62 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
     role: z.ZodLiteral<"system">;
     content: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "system";
     content: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     role: "system";
     content: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>, z.ZodObject<{
     role: z.ZodLiteral<"user">;
     content: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "user";
     content: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     role: "user";
     content: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>, z.ZodObject<{
     role: z.ZodLiteral<"agent">;
     content: z.ZodOptional<z.ZodString>;
@@ -121,6 +160,16 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         id: string;
     }>, "many">>;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "agent";
     name?: string | undefined;
@@ -133,6 +182,10 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         type: "function";
         id: string;
     }[] | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     role: "agent";
     name?: string | undefined;
@@ -145,21 +198,43 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         type: "function";
         id: string;
     }[] | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>, z.ZodObject<{
     role: z.ZodLiteral<"tool">;
     content: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, string, string | Record<string, unknown>>;
     toolCallId: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "tool";
     content: string;
     toolCallId: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     role: "tool";
     content: string | Record<string, unknown>;
     toolCallId: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>]>;
 export declare function safeParseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;
 export declare function parseChatMessages(messages: (z.infer<typeof chatMessageSchema> & {

package/lib/cjs/prompt/template.js

@@ -80,11 +80,13 @@ class ChatMessageTemplate {
     content;
     name;
     options;
-    constructor(role, content, name, options) {
+    cacheControl;
+    constructor(role, content, name, options, cacheControl) {
         this.role = role;
         this.content = content;
         this.name = name;
         this.options = options;
+        this.cacheControl = cacheControl;
     }
     async format(variables, options) {
         options = { ...this.options, ...(0, type_utils_js_1.omitBy)(options ?? {}, (v) => (0, type_utils_js_1.isNil)(v)) };
@@ -103,29 +105,30 @@ class ChatMessageTemplate {
             role: this.role,
             content,
             name: this.name,
+            cacheControl: this.cacheControl,
         };
     }
 }
 exports.ChatMessageTemplate = ChatMessageTemplate;
 class SystemMessageTemplate extends ChatMessageTemplate {
-    static from(content, name, options) {
-        return new SystemMessageTemplate("system", content, name, options);
+    static from(content, name, options, cacheControl) {
+        return new SystemMessageTemplate("system", content, name, options, cacheControl);
     }
 }
 exports.SystemMessageTemplate = SystemMessageTemplate;
 class UserMessageTemplate extends ChatMessageTemplate {
-    static from(template, name, options) {
-        return new UserMessageTemplate("user", template, name, options);
+    static from(template, name, options, cacheControl) {
+        return new UserMessageTemplate("user", template, name, options, cacheControl);
     }
 }
 exports.UserMessageTemplate = UserMessageTemplate;
 class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls;
-    static from(template, toolCalls, name, options) {
-        return new AgentMessageTemplate(template, toolCalls, name, options);
+    static from(template, toolCalls, name, options, cacheControl) {
+        return new AgentMessageTemplate(template, toolCalls, name, options, cacheControl);
     }
-    constructor(content, toolCalls, name, options) {
-        super("agent", content, name, options);
+    constructor(content, toolCalls, name, options, cacheControl) {
+        super("agent", content, name, options, cacheControl);
         this.toolCalls = toolCalls;
     }
     async format(_variables, _options) {
@@ -135,17 +138,18 @@ class AgentMessageTemplate extends ChatMessageTemplate {
             // NOTE: agent message should not rendered by template
             content: this.content,
             toolCalls: this.toolCalls,
+            cacheControl: this.cacheControl,
         };
     }
 }
 exports.AgentMessageTemplate = AgentMessageTemplate;
 class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId;
-    static from(content, toolCallId, name, options) {
-        return new ToolMessageTemplate(content, toolCallId, name, options);
+    static from(content, toolCallId, name, options, cacheControl) {
+        return new ToolMessageTemplate(content, toolCallId, name, options, cacheControl);
     }
-    constructor(content, toolCallId, name, options) {
-        super("tool", typeof content === "string" ? content : (0, yaml_1.stringify)(content), name, options);
+    constructor(content, toolCallId, name, options, cacheControl) {
+        super("tool", typeof content === "string" ? content : (0, yaml_1.stringify)(content), name, options, cacheControl);
         this.toolCallId = toolCallId;
     }
     async format(_variables, _options) {
@@ -155,6 +159,7 @@ class ToolMessageTemplate extends ChatMessageTemplate {
             // NOTE: tool result should not rendered by template
             content: this.content,
             toolCallId: this.toolCallId,
+            cacheControl: this.cacheControl,
         };
     }
 }
@@ -179,11 +184,23 @@ const systemChatMessageSchema = zod_1.z.object({
     role: zod_1.z.literal("system"),
     content: zod_1.z.string(),
     name: zod_1.z.string().optional(),
+    cacheControl: zod_1.z
+        .object({
+        type: zod_1.z.literal("ephemeral"),
+        ttl: zod_1.z.union([zod_1.z.literal("5m"), zod_1.z.literal("1h")]).optional(),
+    })
+        .optional(),
 });
 const userChatMessageSchema = zod_1.z.object({
     role: zod_1.z.literal("user"),
     content: zod_1.z.string(),
     name: zod_1.z.string().optional(),
+    cacheControl: zod_1.z
+        .object({
+        type: zod_1.z.literal("ephemeral"),
+        ttl: zod_1.z.union([zod_1.z.literal("5m"), zod_1.z.literal("1h")]).optional(),
+    })
+        .optional(),
 });
 const chatModelOutputToolCallSchema = zod_1.z.object({
     id: zod_1.z.string(),
@@ -198,6 +215,12 @@ const agentChatMessageSchema = zod_1.z.object({
     content: zod_1.z.string().optional(),
     toolCalls: zod_1.z.array(chatModelOutputToolCallSchema).optional(),
     name: zod_1.z.string().optional(),
+    cacheControl: zod_1.z
+        .object({
+        type: zod_1.z.literal("ephemeral"),
+        ttl: zod_1.z.union([zod_1.z.literal("5m"), zod_1.z.literal("1h")]).optional(),
+    })
+        .optional(),
 });
 const toolChatMessageSchema = zod_1.z.object({
     role: zod_1.z.literal("tool"),
@@ -206,6 +229,12 @@ const toolChatMessageSchema = zod_1.z.object({
         .transform((val) => (typeof val !== "string" ? JSON.stringify(val) : val)),
     toolCallId: zod_1.z.string(),
     name: zod_1.z.string().optional(),
+    cacheControl: zod_1.z
+        .object({
+        type: zod_1.z.literal("ephemeral"),
+        ttl: zod_1.z.union([zod_1.z.literal("5m"), zod_1.z.literal("1h")]).optional(),
+    })
+        .optional(),
 });
 const chatMessageSchema = zod_1.z.union([
     systemChatMessageSchema,
@@ -224,13 +253,13 @@ function parseChatMessages(messages) {
     return messages.map((message) => {
         switch (message.role) {
             case "system":
-                return SystemMessageTemplate.from(message.content, message.name, message.options);
+                return SystemMessageTemplate.from(message.content, message.name, message.options, message.cacheControl);
             case "user":
-                return UserMessageTemplate.from(message.content, message.name, message.options);
+                return UserMessageTemplate.from(message.content, message.name, message.options, message.cacheControl);
             case "agent":
-                return AgentMessageTemplate.from(message.content, message.toolCalls, message.name, message.options);
+                return AgentMessageTemplate.from(message.content, message.toolCalls, message.name, message.options, message.cacheControl);
             case "tool":
-                return ToolMessageTemplate.from(message.content, message.toolCallId, message.name, message.options);
+                return ToolMessageTemplate.from(message.content, message.toolCallId, message.name, message.options, message.cacheControl);
         }
     });
 }

package/lib/dts/agents/chat-model.d.ts

@@ -203,6 +203,13 @@ export interface ChatModelInputMessage {
      * Name of the message sender (for multi-agent scenarios)
      */
     name?: string;
+    /**
+     * Cache control marker for the entire message (only supported by Claude)
+     *
+     * This is syntactic sugar that applies cacheControl to the last content block
+     * of the message. See {@link CacheControl} for details.
+     */
+    cacheControl?: CacheControl;
 }
 /**
  * Type of input message content
@@ -218,27 +225,64 @@ export type ChatModelInputMessageContent = string | UnionContent[];
 export type TextContent = {
     type: "text";
     text: string;
+    /**
+     * Cache control marker (only supported by Claude)
+     *
+     * When set, this content block will be marked as a cache breakpoint.
+     * See {@link CacheControl} for details.
+     */
+    cacheControl?: CacheControl;
 };
 export declare const textContentSchema: z.ZodObject<{
     type: z.ZodLiteral<"text">;
     text: z.ZodString;
+    cacheControl: ZodType<{
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined, z.ZodTypeDef, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined>;
 }, "strip", z.ZodTypeAny, {
     type: "text";
     text: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     type: "text";
     text: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>;
 export type UnionContent = TextContent | FileUnionContent;
 export declare const unionContentSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"text">;
     text: z.ZodString;
+    cacheControl: ZodType<{
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined, z.ZodTypeDef, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined>;
 }, "strip", z.ZodTypeAny, {
     type: "text";
     text: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     type: "text";
     text: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>, z.ZodObject<{
     filename: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
     mimeType: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
@@ -340,6 +384,14 @@ export interface ChatModelInputTool {
      * For example, Gemini's thought_signature
      */
     metadata?: Record<string, any>;
+    /**
+     * Cache control marker (only supported by Claude)
+     *
+     * When set, this tool definition will be marked as a cache breakpoint.
+     * Typically applied to the last tool in the tools array.
+     * See {@link CacheControl} for details.
+     */
+    cacheControl?: CacheControl;
 }
 /**
  * Tool selection strategy
@@ -362,6 +414,82 @@ export type ChatModelInputToolChoice = "auto" | "none" | "required" | {
     };
 };
 export type Modality = "text" | "image" | "audio";
+/**
+ * Cache control marker for prompt caching
+ *
+ * Used to mark content blocks, messages, or tools for caching.
+ * Currently only supported by Anthropic (Claude) models.
+ */
+export interface CacheControl {
+    /**
+     * Cache type (currently only "ephemeral" is supported)
+     */
+    type: "ephemeral";
+    /**
+     * Cache TTL (Time To Live)
+     * - "5m": 5 minutes (default)
+     * - "1h": 1 hour
+     */
+    ttl?: "5m" | "1h";
+}
+/**
+ * Cache configuration options
+ *
+ * Controls how prompt caching is used for supported providers.
+ * Prompt caching can significantly reduce costs and latency by reusing
+ * previously processed prompts (system messages, tool definitions, etc.).
+ */
+export interface CacheConfig {
+    /**
+     * Whether to enable prompt caching
+     *
+     * - OpenAI: Ignored (always enabled automatically)
+     * - Gemini: Controls explicit caching
+     * - Claude: Controls whether to add cache_control markers
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Cache TTL (Time To Live)
+     *
+     * - OpenAI: Ignored (automatic)
+     * - Gemini: Supports custom seconds
+     * - Claude: Only supports "5m" or "1h"
+     *
+     * @default "5m"
+     */
+    ttl?: "5m" | "1h" | number;
+    /**
+     * Caching strategy
+     *
+     * - "auto": Automatically add cache breakpoints at optimal locations
+     * - "manual": Require explicit cacheControl markers on messages/tools
+     *
+     * @default "auto"
+     */
+    strategy?: "auto" | "manual";
+    /**
+     * Auto cache breakpoint locations (only effective when strategy="auto")
+     *
+     * @default { tools: true, system: true, lastMessage: false }
+     */
+    autoBreakpoints?: {
+        /** Cache tool definitions */
+        tools?: boolean;
+        /** Cache system messages */
+        system?: boolean;
+        /** Cache last message in conversation history */
+        lastMessage?: boolean;
+    };
+}
+/**
+ * Default cache configuration
+ *
+ * Enables automatic caching for system messages and tool definitions,
+ * which typically provides the best cost/performance tradeoff.
+ */
+export declare const DEFAULT_CACHE_CONFIG: CacheConfig;
 /**
  * Model-specific configuration options
  *
@@ -395,6 +523,15 @@ export interface ChatModelInputOptions extends Record<string, unknown> {
     modalities?: Modality[];
     preferInputFileType?: "file" | "url";
     reasoningEffort?: number | "minimal" | "low" | "medium" | "high";
+    /**
+     * Cache configuration for prompt caching
+     *
+     * Enables caching of system messages, tool definitions, and conversation history
+     * to reduce costs and latency. See {@link CacheConfig} for details.
+     *
+     * @default DEFAULT_CACHE_CONFIG (enabled with auto strategy)
+     */
+    cacheConfig?: CacheConfig;
 }
 export type ChatModelInputOptionsWithGetter = GetterSchema<ChatModelInputOptions>;
 /**
@@ -492,6 +629,16 @@ export interface ChatModelOutputUsage {
      * AIGNE Hub credit usage
      */
     aigneHubCredits?: number;
+    /**
+     * Number of tokens written to cache (first time caching)
+     * Only applicable for providers that support explicit cache creation (e.g., Anthropic)
+     */
+    cacheCreationInputTokens?: number;
+    /**
+     * Number of tokens read from cache (cache hit)
+     * Supported by OpenAI, Anthropic, and Gemini
+     */
+    cacheReadInputTokens?: number;
     /**
      * Credit prefix
      */
@@ -501,15 +648,21 @@ export declare const chatModelOutputUsageSchema: z.ZodObject<{
     inputTokens: z.ZodNumber;
     outputTokens: z.ZodNumber;
     aigneHubCredits: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+    cacheCreationInputTokens: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+    cacheReadInputTokens: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
     creditPrefix: ZodType<"$" | "€" | "¥" | undefined, z.ZodTypeDef, "$" | "€" | "¥" | undefined>;
 }, "strip", z.ZodTypeAny, {
     inputTokens: number;
     outputTokens: number;
     aigneHubCredits?: number | undefined;
+    cacheCreationInputTokens?: number | undefined;
+    cacheReadInputTokens?: number | undefined;
     creditPrefix?: "$" | "€" | "¥" | undefined;
 }, {
     inputTokens: number;
     outputTokens: number;
     aigneHubCredits?: number | undefined;
+    cacheCreationInputTokens?: number | undefined;
+    cacheReadInputTokens?: number | undefined;
     creditPrefix?: "$" | "€" | "¥" | undefined;
 }>;

package/lib/dts/agents/image-model.d.ts

@@ -196,16 +196,22 @@ export declare const imageModelOutputSchema: z.ZodObject<{
         inputTokens: z.ZodNumber;
         outputTokens: z.ZodNumber;
         aigneHubCredits: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+        cacheCreationInputTokens: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+        cacheReadInputTokens: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
         creditPrefix: ZodType<"$" | "€" | "¥" | undefined, z.ZodTypeDef, "$" | "€" | "¥" | undefined>;
     }, "strip", z.ZodTypeAny, {
         inputTokens: number;
         outputTokens: number;
         aigneHubCredits?: number | undefined;
+        cacheCreationInputTokens?: number | undefined;
+        cacheReadInputTokens?: number | undefined;
         creditPrefix?: "$" | "€" | "¥" | undefined;
     }, {
         inputTokens: number;
         outputTokens: number;
         aigneHubCredits?: number | undefined;
+        cacheCreationInputTokens?: number | undefined;
+        cacheReadInputTokens?: number | undefined;
         creditPrefix?: "$" | "€" | "¥" | undefined;
     }>>;
     model: z.ZodOptional<z.ZodString>;
@@ -231,6 +237,8 @@ export declare const imageModelOutputSchema: z.ZodObject<{
         inputTokens: number;
         outputTokens: number;
         aigneHubCredits?: number | undefined;
+        cacheCreationInputTokens?: number | undefined;
+        cacheReadInputTokens?: number | undefined;
         creditPrefix?: "$" | "€" | "¥" | undefined;
     } | undefined;
 }, {
@@ -255,6 +263,8 @@ export declare const imageModelOutputSchema: z.ZodObject<{
         inputTokens: number;
         outputTokens: number;
         aigneHubCredits?: number | undefined;
+        cacheCreationInputTokens?: number | undefined;
+        cacheReadInputTokens?: number | undefined;
         creditPrefix?: "$" | "€" | "¥" | undefined;
     } | undefined;
 }>;

package/lib/dts/agents/video-model.d.ts

@@ -203,16 +203,22 @@ export declare const videoModelOutputSchema: z.ZodObject<{
         inputTokens: z.ZodNumber;
         outputTokens: z.ZodNumber;
         aigneHubCredits: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+        cacheCreationInputTokens: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+        cacheReadInputTokens: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
         creditPrefix: ZodType<"$" | "€" | "¥" | undefined, z.ZodTypeDef, "$" | "€" | "¥" | undefined>;
     }, "strip", z.ZodTypeAny, {
         inputTokens: number;
         outputTokens: number;
         aigneHubCredits?: number | undefined;
+        cacheCreationInputTokens?: number | undefined;
+        cacheReadInputTokens?: number | undefined;
         creditPrefix?: "$" | "€" | "¥" | undefined;
     }, {
         inputTokens: number;
         outputTokens: number;
         aigneHubCredits?: number | undefined;
+        cacheCreationInputTokens?: number | undefined;
+        cacheReadInputTokens?: number | undefined;
         creditPrefix?: "$" | "€" | "¥" | undefined;
     }>>;
     model: z.ZodOptional<z.ZodString>;
@@ -239,6 +245,8 @@ export declare const videoModelOutputSchema: z.ZodObject<{
         inputTokens: number;
         outputTokens: number;
         aigneHubCredits?: number | undefined;
+        cacheCreationInputTokens?: number | undefined;
+        cacheReadInputTokens?: number | undefined;
         creditPrefix?: "$" | "€" | "¥" | undefined;
     } | undefined;
     seconds?: number | undefined;
@@ -264,6 +272,8 @@ export declare const videoModelOutputSchema: z.ZodObject<{
         inputTokens: number;
         outputTokens: number;
         aigneHubCredits?: number | undefined;
+        cacheCreationInputTokens?: number | undefined;
+        cacheReadInputTokens?: number | undefined;
         creditPrefix?: "$" | "€" | "¥" | undefined;
     } | undefined;
     seconds?: number | undefined;

package/lib/dts/aigne/usage.d.ts

@@ -8,6 +8,10 @@ export interface ContextUsage {
     creditPrefix?: "$" | "€" | "¥";
     agentCalls: number;
     duration: number;
+    /** Number of tokens written to cache (first time caching) */
+    cacheCreationInputTokens: number;
+    /** Number of tokens read from cache (cache hit) */
+    cacheReadInputTokens: number;
 }
 /**
  * @hidden

package/lib/dts/loader/agent-yaml.d.ts

@@ -72,6 +72,10 @@ export type Instructions = {
     role: Exclude<Role, "tool">;
     content: string;
     path: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h";
+    };
 }[];
 export interface AIAgentSchema extends BaseAgentSchema {
     type: "ai";