@hiper2d/ai-agents 0.36.1 → 0.38.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.
package/dist/index.d.mts CHANGED
@@ -1401,7 +1401,14 @@ declare abstract class AbstractAgent {
1401
1401
  * invalidResponseRetries policy. Subclasses implement doAskWithZodSchema/doAskText and
1402
1402
  * must NOT override these.
1403
1403
  */
1404
- askWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
1404
+ /**
1405
+ * `reject` is the host's own check on a schema-valid answer: return why it is unusable
1406
+ * (a required field left as an empty string, say) and the answer is treated exactly like
1407
+ * a malformed one: a ModelInvalidResponseError, re-sent under invalidResponseRetries.
1408
+ * It exists because a check written into the zod schema would change the JSON schema
1409
+ * the provider sees.
1410
+ */
1411
+ askWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[], reject?: (answer: T) => string | null | undefined): Promise<[T, string, TokenUsage$1?, string?]>;
1405
1412
  askText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
1406
1413
  /**
1407
1414
  * One attempt per loop; an empty or malformed answer (ModelInvalidResponseError, not
@@ -1468,6 +1475,15 @@ declare class ClaudeAgent extends AbstractAgent {
1468
1475
  * requires 1h entries to precede 5m ones, and a single TTL keeps that trivially true.
1469
1476
  */
1470
1477
  cacheTtl: ClaudeCacheMode;
1478
+ /**
1479
+ * Which message carries the message breakpoint (see applyCacheBreakpoint).
1480
+ * 'previous' (default): the second-to-last message, for hosts whose final message carries
1481
+ * content they never send again (an unsaved reminder) - a breakpoint there would only pay
1482
+ * the write. 'last': the final message, for hosts that replay every request in full on the
1483
+ * next one (Werewolf since 2026-11-15 stores its turn tail and replays it), so the whole
1484
+ * request is written and the next call reads all of it.
1485
+ */
1486
+ cacheAnchor: 'previous' | 'last';
1471
1487
  /** The cache_control to attach to a breakpoint, or none when caching is off. */
1472
1488
  private get cacheControl();
1473
1489
  private get defaultParams();
@@ -1497,6 +1513,9 @@ declare class ClaudeAgent extends AbstractAgent {
1497
1513
  * reply, or an earlier flushed block) reappears verbatim next turn, where the moved-
1498
1514
  * forward breakpoint finds it via the 20-block lookback.
1499
1515
  *
1516
+ * With `cacheAnchor = 'last'` the host says its final message IS replayed, and the
1517
+ * breakpoint goes on the last message instead.
1518
+ *
1500
1519
  * NOT the top-level auto-caching mode: that mode targets the LAST cacheable block,
1501
1520
  * which for us is exactly the never-repeated tail — every entry it wrote would be dead.
1502
1521
  */
package/dist/index.d.ts CHANGED
@@ -1401,7 +1401,14 @@ declare abstract class AbstractAgent {
1401
1401
  * invalidResponseRetries policy. Subclasses implement doAskWithZodSchema/doAskText and
1402
1402
  * must NOT override these.
1403
1403
  */
1404
- askWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
1404
+ /**
1405
+ * `reject` is the host's own check on a schema-valid answer: return why it is unusable
1406
+ * (a required field left as an empty string, say) and the answer is treated exactly like
1407
+ * a malformed one: a ModelInvalidResponseError, re-sent under invalidResponseRetries.
1408
+ * It exists because a check written into the zod schema would change the JSON schema
1409
+ * the provider sees.
1410
+ */
1411
+ askWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[], reject?: (answer: T) => string | null | undefined): Promise<[T, string, TokenUsage$1?, string?]>;
1405
1412
  askText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
1406
1413
  /**
1407
1414
  * One attempt per loop; an empty or malformed answer (ModelInvalidResponseError, not
@@ -1468,6 +1475,15 @@ declare class ClaudeAgent extends AbstractAgent {
1468
1475
  * requires 1h entries to precede 5m ones, and a single TTL keeps that trivially true.
1469
1476
  */
1470
1477
  cacheTtl: ClaudeCacheMode;
1478
+ /**
1479
+ * Which message carries the message breakpoint (see applyCacheBreakpoint).
1480
+ * 'previous' (default): the second-to-last message, for hosts whose final message carries
1481
+ * content they never send again (an unsaved reminder) - a breakpoint there would only pay
1482
+ * the write. 'last': the final message, for hosts that replay every request in full on the
1483
+ * next one (Werewolf since 2026-11-15 stores its turn tail and replays it), so the whole
1484
+ * request is written and the next call reads all of it.
1485
+ */
1486
+ cacheAnchor: 'previous' | 'last';
1471
1487
  /** The cache_control to attach to a breakpoint, or none when caching is off. */
1472
1488
  private get cacheControl();
1473
1489
  private get defaultParams();
@@ -1497,6 +1513,9 @@ declare class ClaudeAgent extends AbstractAgent {
1497
1513
  * reply, or an earlier flushed block) reappears verbatim next turn, where the moved-
1498
1514
  * forward breakpoint finds it via the 20-block lookback.
1499
1515
  *
1516
+ * With `cacheAnchor = 'last'` the host says its final message IS replayed, and the
1517
+ * breakpoint goes on the last message instead.
1518
+ *
1500
1519
  * NOT the top-level auto-caching mode: that mode targets the LAST cacheable block,
1501
1520
  * which for us is exactly the never-repeated tail — every entry it wrote would be dead.
1502
1521
  */
package/dist/index.js CHANGED
@@ -2669,8 +2669,20 @@ var AbstractAgent = class {
2669
2669
  * invalidResponseRetries policy. Subclasses implement doAskWithZodSchema/doAskText and
2670
2670
  * must NOT override these.
2671
2671
  */
2672
- async askWithZodSchema(zodSchema, messages) {
2673
- return this.askWithRetries(() => this.doAskWithZodSchema(zodSchema, messages));
2672
+ /**
2673
+ * `reject` is the host's own check on a schema-valid answer: return why it is unusable
2674
+ * (a required field left as an empty string, say) and the answer is treated exactly like
2675
+ * a malformed one: a ModelInvalidResponseError, re-sent under invalidResponseRetries.
2676
+ * It exists because a check written into the zod schema would change the JSON schema
2677
+ * the provider sees.
2678
+ */
2679
+ async askWithZodSchema(zodSchema, messages, reject) {
2680
+ return this.askWithRetries(async () => {
2681
+ const result = await this.doAskWithZodSchema(zodSchema, messages);
2682
+ const reason = reject?.(result[0]);
2683
+ if (reason) throw new ModelInvalidResponseError(this.model, reason);
2684
+ return result;
2685
+ });
2674
2686
  }
2675
2687
  async askText(messages) {
2676
2688
  return this.askWithRetries(() => this.doAskText(messages));
@@ -3101,6 +3113,15 @@ var ClaudeAgent = class extends AbstractAgent {
3101
3113
  * requires 1h entries to precede 5m ones, and a single TTL keeps that trivially true.
3102
3114
  */
3103
3115
  cacheTtl = "1h";
3116
+ /**
3117
+ * Which message carries the message breakpoint (see applyCacheBreakpoint).
3118
+ * 'previous' (default): the second-to-last message, for hosts whose final message carries
3119
+ * content they never send again (an unsaved reminder) - a breakpoint there would only pay
3120
+ * the write. 'last': the final message, for hosts that replay every request in full on the
3121
+ * next one (Werewolf since 2026-11-15 stores its turn tail and replays it), so the whole
3122
+ * request is written and the next call reads all of it.
3123
+ */
3124
+ cacheAnchor = "previous";
3104
3125
  /** The cache_control to attach to a breakpoint, or none when caching is off. */
3105
3126
  get cacheControl() {
3106
3127
  return this.cacheTtl === "off" ? {} : { cache_control: { type: "ephemeral", ttl: this.cacheTtl } };
@@ -3215,6 +3236,9 @@ var ClaudeAgent = class extends AbstractAgent {
3215
3236
  * reply, or an earlier flushed block) reappears verbatim next turn, where the moved-
3216
3237
  * forward breakpoint finds it via the 20-block lookback.
3217
3238
  *
3239
+ * With `cacheAnchor = 'last'` the host says its final message IS replayed, and the
3240
+ * breakpoint goes on the last message instead.
3241
+ *
3218
3242
  * NOT the top-level auto-caching mode: that mode targets the LAST cacheable block,
3219
3243
  * which for us is exactly the never-repeated tail — every entry it wrote would be dead.
3220
3244
  */
@@ -3222,10 +3246,11 @@ var ClaudeAgent = class extends AbstractAgent {
3222
3246
  if (this.cacheTtl === "off") {
3223
3247
  return;
3224
3248
  }
3225
- if (messages.length < 2) {
3249
+ const back = this.cacheAnchor === "last" ? 1 : 2;
3250
+ if (messages.length < back) {
3226
3251
  return;
3227
3252
  }
3228
- const anchor = messages[messages.length - 2];
3253
+ const anchor = messages[messages.length - back];
3229
3254
  if (typeof anchor.content === "string") {
3230
3255
  if (anchor.content.length > 0) {
3231
3256
  anchor.content = [{ type: "text", text: anchor.content, cache_control: { type: "ephemeral", ttl: this.cacheTtl } }];