@adecore/agent-contracts 0.31.12 → 0.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/dist/chat.d.ts +26 -0
  2. package/dist/chat.js +5 -1
  3. package/dist/index.d.ts +1 -1
  4. package/dist/index.js +1 -1
  5. package/dist/protocol.d.ts +22 -0
  6. package/dist/usage.d.ts +6 -0
  7. package/dist/usage.js +9 -0
  8. package/package.json +2 -2
  9. package/src/chat.ts +5 -1
  10. package/src/index.ts +3 -0
  11. package/src/usage.ts +19 -0
package/dist/chat.d.ts CHANGED
@@ -19,6 +19,8 @@ export declare const ChatUsageSchema: z.ZodObject<{
19
19
  conversation: z.ZodNumber;
20
20
  system: z.ZodNumber;
21
21
  }, z.core.$strip>>;
22
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
23
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
22
24
  }, z.core.$strip>;
23
25
  export type ChatUsage = z.infer<typeof ChatUsageSchema>;
24
26
  export declare const CHAT_ATTACHMENTS_MAX_BYTES: number;
@@ -330,6 +332,8 @@ export declare const ChatInfoSchema: z.ZodObject<{
330
332
  conversation: z.ZodNumber;
331
333
  system: z.ZodNumber;
332
334
  }, z.core.$strip>>;
335
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
336
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
333
337
  }, z.core.$strip>;
334
338
  suggestedTitle: z.ZodOptional<z.ZodString>;
335
339
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -1890,6 +1894,8 @@ export declare const ChatEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1890
1894
  conversation: z.ZodNumber;
1891
1895
  system: z.ZodNumber;
1892
1896
  }, z.core.$strip>>;
1897
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
1898
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
1893
1899
  }, z.core.$strip>;
1894
1900
  suggestedTitle: z.ZodOptional<z.ZodString>;
1895
1901
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -2054,6 +2060,8 @@ export declare const ChatEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
2054
2060
  conversation: z.ZodNumber;
2055
2061
  system: z.ZodNumber;
2056
2062
  }, z.core.$strip>>;
2063
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
2064
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
2057
2065
  }, z.core.$strip>;
2058
2066
  suggestedTitle: z.ZodOptional<z.ZodString>;
2059
2067
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -2965,6 +2973,8 @@ export declare const ChatEventEnvelopeSchema: z.ZodObject<{
2965
2973
  conversation: z.ZodNumber;
2966
2974
  system: z.ZodNumber;
2967
2975
  }, z.core.$strip>>;
2976
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
2977
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
2968
2978
  }, z.core.$strip>;
2969
2979
  suggestedTitle: z.ZodOptional<z.ZodString>;
2970
2980
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -3129,6 +3139,8 @@ export declare const ChatEventEnvelopeSchema: z.ZodObject<{
3129
3139
  conversation: z.ZodNumber;
3130
3140
  system: z.ZodNumber;
3131
3141
  }, z.core.$strip>>;
3142
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
3143
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
3132
3144
  }, z.core.$strip>;
3133
3145
  suggestedTitle: z.ZodOptional<z.ZodString>;
3134
3146
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -4504,6 +4516,8 @@ export declare const ChatStatusEventSchema: z.ZodObject<{
4504
4516
  conversation: z.ZodNumber;
4505
4517
  system: z.ZodNumber;
4506
4518
  }, z.core.$strip>>;
4519
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
4520
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
4507
4521
  }, z.core.$strip>;
4508
4522
  suggestedTitle: z.ZodOptional<z.ZodString>;
4509
4523
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -4766,6 +4780,8 @@ export declare const ChatAttachResultSchema: z.ZodObject<{
4766
4780
  conversation: z.ZodNumber;
4767
4781
  system: z.ZodNumber;
4768
4782
  }, z.core.$strip>>;
4783
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
4784
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
4769
4785
  }, z.core.$strip>;
4770
4786
  suggestedTitle: z.ZodOptional<z.ZodString>;
4771
4787
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -6015,6 +6031,8 @@ export declare const ChatAttachResultSchema: z.ZodObject<{
6015
6031
  conversation: z.ZodNumber;
6016
6032
  system: z.ZodNumber;
6017
6033
  }, z.core.$strip>>;
6034
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
6035
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
6018
6036
  }, z.core.$strip>;
6019
6037
  suggestedTitle: z.ZodOptional<z.ZodString>;
6020
6038
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -6179,6 +6197,8 @@ export declare const ChatAttachResultSchema: z.ZodObject<{
6179
6197
  conversation: z.ZodNumber;
6180
6198
  system: z.ZodNumber;
6181
6199
  }, z.core.$strip>>;
6200
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
6201
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
6182
6202
  }, z.core.$strip>;
6183
6203
  suggestedTitle: z.ZodOptional<z.ZodString>;
6184
6204
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -6906,6 +6926,8 @@ export declare const ChatForkResultSchema: z.ZodObject<{
6906
6926
  conversation: z.ZodNumber;
6907
6927
  system: z.ZodNumber;
6908
6928
  }, z.core.$strip>>;
6929
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
6930
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
6909
6931
  }, z.core.$strip>;
6910
6932
  suggestedTitle: z.ZodOptional<z.ZodString>;
6911
6933
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -7101,6 +7123,8 @@ export declare const ChatContinueOnResultSchema: z.ZodObject<{
7101
7123
  conversation: z.ZodNumber;
7102
7124
  system: z.ZodNumber;
7103
7125
  }, z.core.$strip>>;
7126
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
7127
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
7104
7128
  }, z.core.$strip>;
7105
7129
  suggestedTitle: z.ZodOptional<z.ZodString>;
7106
7130
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -7310,6 +7334,8 @@ export declare const ChatListResultSchema: z.ZodObject<{
7310
7334
  conversation: z.ZodNumber;
7311
7335
  system: z.ZodNumber;
7312
7336
  }, z.core.$strip>>;
7337
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
7338
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
7313
7339
  }, z.core.$strip>;
7314
7340
  suggestedTitle: z.ZodOptional<z.ZodString>;
7315
7341
  hidden: z.ZodOptional<z.ZodBoolean>;
package/dist/chat.js CHANGED
@@ -22,7 +22,11 @@ export const ChatUsageSchema = z.object({
22
22
  costUsd: z.number().nonnegative(),
23
23
  turns: z.number().int().nonnegative(),
24
24
  // Absent while nothing is in the context yet, and from a daemon that does not estimate.
25
- breakdown: ChatContextBreakdownSchema.optional()
25
+ breakdown: ChatContextBreakdownSchema.optional(),
26
+ // How long the prompt cache of the main agent's last request lives, in milliseconds; absent while the CLI names no lifetime.
27
+ cacheTtlMs: z.number().int().positive().optional(),
28
+ // When that cache goes cold, in milliseconds since the epoch: its lifetime from the moment that request started.
29
+ cacheExpiresAt: z.number().optional()
26
30
  });
27
31
  // Base64 for 10 MiB leaves room for the prompt and envelope inside the 16 MiB transport frame.
28
32
  export const CHAT_ATTACHMENTS_MAX_BYTES = 10 * 1024 * 1024;
package/dist/index.d.ts CHANGED
@@ -9,6 +9,6 @@ export { ProviderAccountIdSchema, type ProviderAccountId, ProviderAccountVariabl
9
9
  export { isRecord } from './record.ts';
10
10
  export { TaskStatusSchema, type TaskStatus, TaskResultSchema, type TaskResult, TaskSchema, type Task, TaskChangedEventSchema, type TaskChangedEvent } from './task.ts';
11
11
  export { clipText, TOOL_OUTPUT_TAIL, appendToolOutput } from './text.ts';
12
- export { UsageProviderSchema, type UsageProvider, USAGE_PROVIDERS, UsageResolutionSchema, type UsageResolution, UsageTotalsSchema, type UsageTotals, EMPTY_TOTALS, totalTokensOf, addTotals, UsageAccountSchema, type UsageAccount, UsageBucketSchema, type UsageBucket, UsagePriceBasisSchema, type UsagePriceBasis, UsageModelSchema, type UsageModel, UsageProjectSchema, type UsageProject, UsageSummaryPayloadSchema, type UsageSummaryPayload, UsageScanSchema, type UsageScan, UsagePricingSchema, type UsagePricing, UsageRootSchema, type UsageRoot, UsageRateSchema, type UsageRate, UsageSummaryResultSchema, type UsageSummaryResult, UsageChangedEventSchema, type UsageChangedEvent, UsageWindowSchema, type UsageWindow, UsageLimitsProviderSchema, type UsageLimitsProvider, UsageLimitsSnapshotSchema, type UsageLimitsSnapshot } from './usage.ts';
12
+ export { UsageProviderSchema, type UsageProvider, USAGE_PROVIDERS, UsageResolutionSchema, type UsageResolution, UsageTotalsSchema, type UsageTotals, EMPTY_TOTALS, totalTokensOf, addTotals, UsageAccountSchema, type UsageAccount, UsageBucketSchema, type UsageBucket, UsagePriceBasisSchema, type UsagePriceBasis, UsageModelSchema, type UsageModel, UsageProjectSchema, type UsageProject, UsageSummaryPayloadSchema, type UsageSummaryPayload, UsageScanSchema, type UsageScan, UsagePricingSchema, type UsagePricing, UsageRootSchema, type UsageRoot, UsageRateSchema, type UsageRate, UsageSummaryResultSchema, type UsageSummaryResult, UsageChangedEventSchema, type UsageChangedEvent, UsageWindowSchema, type UsageWindow, type PaceStanding, type EvenPace, evenPace, UsageLimitsProviderSchema, type UsageLimitsProvider, UsageLimitsSnapshotSchema, type UsageLimitsSnapshot } from './usage.ts';
13
13
  export { VISUAL_LIMITS, VISUAL_MEASURE_WIDTHS, VisualHeightSchema, type VisualHeight, VisualLayoutSchema, type VisualLayout, ChatVisualSchema, type ChatVisual, ChatVisualsSchema, visualFrameHeight, VISUAL_BRIDGE_METHODS, type VisualAppearance, type VisualTheme, type VisualRequestId, type VisualViewport, type VisualScrollRequest, visualViewportMessage, visualScrollMessage, type VisualMessage, visualProxyReadyMessage, visualResourceReadyMessage, visualHostContextMessage, visualSizeChangedMessage, visualOpenLinkRequest, visualOpenLinkResult, parseVisualMessage, VISUAL_THEME_VARIABLES, type VisualThemeVariable, VISUAL_LIGHT_THEME, VISUAL_DARK_THEME, cleanVisualVariables, visualThemeFragment, VISUAL_PAGE_RULES, VISUAL_LAYOUT_GUIDE, VISUAL_THEME_GUIDE, injectVisualBootstrap, VISUAL_HOST_PAGE } from './visual.ts';
14
14
  export { WorktreeWorkSchema, type WorktreeWork, WorktreeSchema, type Worktree } from './worktree.ts';
package/dist/index.js CHANGED
@@ -9,6 +9,6 @@ export { ProviderAccountIdSchema, ProviderAccountVariableSchema, ProviderAccount
9
9
  export { isRecord } from './record.js';
10
10
  export { TaskStatusSchema, TaskResultSchema, TaskSchema, TaskChangedEventSchema } from './task.js';
11
11
  export { clipText, TOOL_OUTPUT_TAIL, appendToolOutput } from './text.js';
12
- export { UsageProviderSchema, USAGE_PROVIDERS, UsageResolutionSchema, UsageTotalsSchema, EMPTY_TOTALS, totalTokensOf, addTotals, UsageAccountSchema, UsageBucketSchema, UsagePriceBasisSchema, UsageModelSchema, UsageProjectSchema, UsageSummaryPayloadSchema, UsageScanSchema, UsagePricingSchema, UsageRootSchema, UsageRateSchema, UsageSummaryResultSchema, UsageChangedEventSchema, UsageWindowSchema, UsageLimitsProviderSchema, UsageLimitsSnapshotSchema } from './usage.js';
12
+ export { UsageProviderSchema, USAGE_PROVIDERS, UsageResolutionSchema, UsageTotalsSchema, EMPTY_TOTALS, totalTokensOf, addTotals, UsageAccountSchema, UsageBucketSchema, UsagePriceBasisSchema, UsageModelSchema, UsageProjectSchema, UsageSummaryPayloadSchema, UsageScanSchema, UsagePricingSchema, UsageRootSchema, UsageRateSchema, UsageSummaryResultSchema, UsageChangedEventSchema, UsageWindowSchema, evenPace, UsageLimitsProviderSchema, UsageLimitsSnapshotSchema } from './usage.js';
13
13
  export { VISUAL_LIMITS, VISUAL_MEASURE_WIDTHS, VisualHeightSchema, VisualLayoutSchema, ChatVisualSchema, ChatVisualsSchema, visualFrameHeight, VISUAL_BRIDGE_METHODS, visualViewportMessage, visualScrollMessage, visualProxyReadyMessage, visualResourceReadyMessage, visualHostContextMessage, visualSizeChangedMessage, visualOpenLinkRequest, visualOpenLinkResult, parseVisualMessage, VISUAL_THEME_VARIABLES, VISUAL_LIGHT_THEME, VISUAL_DARK_THEME, cleanVisualVariables, visualThemeFragment, VISUAL_PAGE_RULES, VISUAL_LAYOUT_GUIDE, VISUAL_THEME_GUIDE, injectVisualBootstrap, VISUAL_HOST_PAGE } from './visual.js';
14
14
  export { WorktreeWorkSchema, WorktreeSchema } from './worktree.js';
package/dist/protocol.d.ts CHANGED
@@ -109,6 +109,8 @@ export declare const AGENT_REQUEST_SCHEMAS: {
109
109
  conversation: z.ZodNumber;
110
110
  system: z.ZodNumber;
111
111
  }, z.core.$strip>>;
112
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
113
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
112
114
  }, z.core.$strip>;
113
115
  suggestedTitle: z.ZodOptional<z.ZodString>;
114
116
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -629,6 +631,8 @@ export declare const AGENT_REQUEST_SCHEMAS: {
629
631
  conversation: z.ZodNumber;
630
632
  system: z.ZodNumber;
631
633
  }, z.core.$strip>>;
634
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
635
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
632
636
  }, z.core.$strip>;
633
637
  suggestedTitle: z.ZodOptional<z.ZodString>;
634
638
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -1878,6 +1882,8 @@ export declare const AGENT_REQUEST_SCHEMAS: {
1878
1882
  conversation: z.ZodNumber;
1879
1883
  system: z.ZodNumber;
1880
1884
  }, z.core.$strip>>;
1885
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
1886
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
1881
1887
  }, z.core.$strip>;
1882
1888
  suggestedTitle: z.ZodOptional<z.ZodString>;
1883
1889
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -2042,6 +2048,8 @@ export declare const AGENT_REQUEST_SCHEMAS: {
2042
2048
  conversation: z.ZodNumber;
2043
2049
  system: z.ZodNumber;
2044
2050
  }, z.core.$strip>>;
2051
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
2052
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
2045
2053
  }, z.core.$strip>;
2046
2054
  suggestedTitle: z.ZodOptional<z.ZodString>;
2047
2055
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -2808,6 +2816,8 @@ export declare const AGENT_REQUEST_SCHEMAS: {
2808
2816
  conversation: z.ZodNumber;
2809
2817
  system: z.ZodNumber;
2810
2818
  }, z.core.$strip>>;
2819
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
2820
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
2811
2821
  }, z.core.$strip>;
2812
2822
  suggestedTitle: z.ZodOptional<z.ZodString>;
2813
2823
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -3052,6 +3062,8 @@ export declare const AGENT_REQUEST_SCHEMAS: {
3052
3062
  conversation: z.ZodNumber;
3053
3063
  system: z.ZodNumber;
3054
3064
  }, z.core.$strip>>;
3065
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
3066
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
3055
3067
  }, z.core.$strip>;
3056
3068
  suggestedTitle: z.ZodOptional<z.ZodString>;
3057
3069
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -3247,6 +3259,8 @@ export declare const AGENT_REQUEST_SCHEMAS: {
3247
3259
  conversation: z.ZodNumber;
3248
3260
  system: z.ZodNumber;
3249
3261
  }, z.core.$strip>>;
3262
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
3263
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
3250
3264
  }, z.core.$strip>;
3251
3265
  suggestedTitle: z.ZodOptional<z.ZodString>;
3252
3266
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -4531,6 +4545,8 @@ export declare const AGENT_REQUEST_SCHEMAS: {
4531
4545
  conversation: z.ZodNumber;
4532
4546
  system: z.ZodNumber;
4533
4547
  }, z.core.$strip>>;
4548
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
4549
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
4534
4550
  }, z.core.$strip>;
4535
4551
  suggestedTitle: z.ZodOptional<z.ZodString>;
4536
4552
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -5107,6 +5123,8 @@ export declare const AGENT_EVENT_SCHEMAS: {
5107
5123
  conversation: z.ZodNumber;
5108
5124
  system: z.ZodNumber;
5109
5125
  }, z.core.$strip>>;
5126
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
5127
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
5110
5128
  }, z.core.$strip>;
5111
5129
  suggestedTitle: z.ZodOptional<z.ZodString>;
5112
5130
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -5271,6 +5289,8 @@ export declare const AGENT_EVENT_SCHEMAS: {
5271
5289
  conversation: z.ZodNumber;
5272
5290
  system: z.ZodNumber;
5273
5291
  }, z.core.$strip>>;
5292
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
5293
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
5274
5294
  }, z.core.$strip>;
5275
5295
  suggestedTitle: z.ZodOptional<z.ZodString>;
5276
5296
  hidden: z.ZodOptional<z.ZodBoolean>;
@@ -5775,6 +5795,8 @@ export declare const AGENT_EVENT_SCHEMAS: {
5775
5795
  conversation: z.ZodNumber;
5776
5796
  system: z.ZodNumber;
5777
5797
  }, z.core.$strip>>;
5798
+ cacheTtlMs: z.ZodOptional<z.ZodNumber>;
5799
+ cacheExpiresAt: z.ZodOptional<z.ZodNumber>;
5778
5800
  }, z.core.$strip>;
5779
5801
  suggestedTitle: z.ZodOptional<z.ZodString>;
5780
5802
  hidden: z.ZodOptional<z.ZodBoolean>;
package/dist/usage.d.ts CHANGED
@@ -337,6 +337,12 @@ export declare const UsageWindowSchema: z.ZodObject<{
337
337
  durationMs: z.ZodNullable<z.ZodNumber>;
338
338
  }, z.core.$strip>;
339
339
  export type UsageWindow = z.infer<typeof UsageWindowSchema>;
340
+ export type PaceStanding = 'ahead' | 'behind' | 'even';
341
+ export interface EvenPace {
342
+ percent: number;
343
+ standing: PaceStanding;
344
+ }
345
+ export declare function evenPace(window: UsageWindow, now: number): EvenPace | null;
340
346
  export declare const UsageLimitsProviderSchema: z.ZodObject<{
341
347
  kind: z.ZodEnum<{
342
348
  claude: "claude";
package/dist/usage.js CHANGED
@@ -144,6 +144,15 @@ export const UsageWindowSchema = z.object({
144
144
  resetsAt: z.number().int().nullable(),
145
145
  durationMs: z.number().int().nullable()
146
146
  });
147
+ /* Where an evenly spent window would stand by now, or null when the provider named no reset or no length to measure from. */
148
+ export function evenPace(window, now) {
149
+ if (window.resetsAt === null || window.durationMs === null || window.durationMs <= 0) {
150
+ return null;
151
+ }
152
+ const percent = Math.round(Math.min(1, Math.max(0, 1 - (window.resetsAt - now) / window.durationMs)) * 100);
153
+ const used = Math.round(window.used * 100);
154
+ return { percent, standing: used > percent ? 'ahead' : used < percent ? 'behind' : 'even' };
155
+ }
147
156
  export const UsageLimitsProviderSchema = z.object({
148
157
  kind: UsageProviderSchema,
149
158
  /* The account these numbers are of. The default account of a kind comes first, in the shape an entry had before accounts. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adecore/agent-contracts",
3
- "version": "0.31.12",
3
+ "version": "0.32.0",
4
4
  "description": "Schemas and port contracts for agent chats, provider accounts, models and usage.",
5
5
  "type": "module",
6
6
  "exports": {
@@ -86,7 +86,7 @@
86
86
  "test": "bun --conditions=source test"
87
87
  },
88
88
  "dependencies": {
89
- "@adecore/intelligent-ui": "0.31.12",
89
+ "@adecore/intelligent-ui": "0.32.0",
90
90
  "zod": "^4.6.5"
91
91
  },
92
92
  "devDependencies": {
package/src/chat.ts CHANGED
@@ -27,7 +27,11 @@ export const ChatUsageSchema = z.object({
27
27
  costUsd: z.number().nonnegative(),
28
28
  turns: z.number().int().nonnegative(),
29
29
  // Absent while nothing is in the context yet, and from a daemon that does not estimate.
30
- breakdown: ChatContextBreakdownSchema.optional()
30
+ breakdown: ChatContextBreakdownSchema.optional(),
31
+ // How long the prompt cache of the main agent's last request lives, in milliseconds; absent while the CLI names no lifetime.
32
+ cacheTtlMs: z.number().int().positive().optional(),
33
+ // When that cache goes cold, in milliseconds since the epoch: its lifetime from the moment that request started.
34
+ cacheExpiresAt: z.number().optional()
31
35
  });
32
36
  export type ChatUsage = z.infer<typeof ChatUsageSchema>;
33
37
 
package/src/index.ts CHANGED
@@ -381,6 +381,9 @@ export {
381
381
  type UsageChangedEvent,
382
382
  UsageWindowSchema,
383
383
  type UsageWindow,
384
+ type PaceStanding,
385
+ type EvenPace,
386
+ evenPace,
384
387
  UsageLimitsProviderSchema,
385
388
  type UsageLimitsProvider,
386
389
  UsageLimitsSnapshotSchema,
package/src/usage.ts CHANGED
@@ -180,6 +180,25 @@ export const UsageWindowSchema = z.object({
180
180
  });
181
181
  export type UsageWindow = z.infer<typeof UsageWindowSchema>;
182
182
 
183
+ /* `ahead` has used more than an even spread over the window would by now, `behind` less. */
184
+ export type PaceStanding = 'ahead' | 'behind' | 'even';
185
+
186
+ export interface EvenPace {
187
+ /* Where the usage would stand had the window been spent evenly from its start, in whole percent. */
188
+ percent: number;
189
+ standing: PaceStanding;
190
+ }
191
+
192
+ /* Where an evenly spent window would stand by now, or null when the provider named no reset or no length to measure from. */
193
+ export function evenPace(window: UsageWindow, now: number): EvenPace | null {
194
+ if (window.resetsAt === null || window.durationMs === null || window.durationMs <= 0) {
195
+ return null;
196
+ }
197
+ const percent = Math.round(Math.min(1, Math.max(0, 1 - (window.resetsAt - now) / window.durationMs)) * 100);
198
+ const used = Math.round(window.used * 100);
199
+ return { percent, standing: used > percent ? 'ahead' : used < percent ? 'behind' : 'even' };
200
+ }
201
+
183
202
  export const UsageLimitsProviderSchema = z.object({
184
203
  kind: UsageProviderSchema,
185
204
  /* The account these numbers are of. The default account of a kind comes first, in the shape an entry had before accounts. */