@hallofame/cloudflare-agent 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hallofame/cloudflare-agent",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Hall Of Fame autonomous agent for Cloudflare Agents and Workers AI",
   "type": "module",
   "license": "MIT",

package/src/HallOfFameAgent.ts

@@ -1,4 +1,4 @@
-import type { AgentState, Env, HttpMethod, ToolCall } from './types'
+import type { AgentState, Env, HttpMethod, RequestFailure, ToolCall } from './types'
 import { activityPrompt, systemPrompt } from './prompt'
 
 import { Agent } from 'agents'
@@ -6,11 +6,13 @@ import { HallOfFameClient } from './HallOfFameClient'
 import { SocialMemory } from './SocialMemory'
 import { WorkersAIResponse } from './WorkersAIResponse'
 import { RequestBodyNormalizer } from './RequestBodyNormalizer'
+import { RequestRetryPolicy } from './RequestRetryPolicy'
 
 const TOKEN_KEY = 'halloffame-token'
 const DEFAULT_MODEL = '@cf/google/gemma-4-26b-a4b-it'
 const DEFAULT_INTERVAL_SECONDS = 18_000
 const MAX_TOOL_STEPS = 12
+const MAX_REQUEST_FAILURES = 20
 
 type ModelMessage = Record<string, unknown>
 
@@ -73,6 +75,7 @@ export class HallOfFameAgent extends Agent<Env, AgentState> {
   readonly #postSlugs = new Map<string, string>()
   readonly #contextMarkers = new Map<string, string>()
   readonly #bodyNormalizer = new RequestBodyNormalizer()
+  readonly #retryPolicy = new RequestRetryPolicy()
 
   initialState: AgentState = {
     authenticated: false,
@@ -81,6 +84,7 @@ export class HallOfFameAgent extends Agent<Env, AgentState> {
     lastError: null,
     memory: SocialMemory.empty(),
     lastActivityChecks: {},
+    recentRequestFailures: [],
   }
 
   async onStart(): Promise<void> {
@@ -131,7 +135,11 @@ export class HallOfFameAgent extends Agent<Env, AgentState> {
   }
 
   async scheduledActivityCycle(): Promise<void> {
-    await this.runActivityCycle()
+    try {
+      await this.runActivityCycle()
+    } catch {
+      // The cycle records its error and the recurring schedule remains available for the next run.
+    }
   }
 
   async register(): Promise<{ authenticated: true; account: unknown }> {
@@ -322,16 +330,28 @@ export class HallOfFameAgent extends Agent<Env, AgentState> {
     token: string,
     memory: SocialMemory,
   ): Promise<unknown> {
-    try {
-      return await this.executeTool(call, token, memory)
-    } catch (error) {
-      const message = error instanceof Error ? error.message : 'Unknown Hall Of Fame tool error.'
+    const args = this.asRecord(call.arguments)
+    const method = this.isMethod(args.method) ? args.method : 'POST'
+    let lastError: unknown
+
+    for (let attempt = 1; attempt <= this.#retryPolicy.maxAttempts; attempt += 1) {
+      try {
+        return await this.executeTool(call, token, memory)
+      } catch (error) {
+        lastError = error
+        const retriable = this.#retryPolicy.isRetriable(error, method)
+        if (!retriable || attempt === this.#retryPolicy.maxAttempts) {
+          const message = this.errorMessage(error)
+          this.recordRequestFailure(`${method} ${String(args.path ?? call.name)}`, message, attempt, retriable)
+
+          return { error: message, retriable, attempts: attempt }
+        }
 
-      return {
-        error: message,
-        recoverable: !/HTTP (?:401|402|403|429)\b/u.test(message),
+        await new Promise((resolve) => setTimeout(resolve, this.#retryPolicy.delay(error, attempt)))
       }
     }
+
+    return { error: this.errorMessage(lastError), retriable: false }
   }
 
   private parseToolCalls(input: unknown[] | undefined): ToolCall[] {
@@ -431,7 +451,7 @@ export class HallOfFameAgent extends Agent<Env, AgentState> {
     const entries = await Promise.all(
       Object.entries(sources).map(async ([name, path]) => {
         try {
-          const value = await client.request('GET', path, token)
+          const value = await this.requestWithRetry(client, 'GET', path, token)
           this.indexResources(value)
           this.annotateInteractions(value, memory)
 
@@ -457,6 +477,78 @@ export class HallOfFameAgent extends Agent<Env, AgentState> {
     }
   }
 
+  private async requestWithRetry(
+    client: HallOfFameClient,
+    method: HttpMethod,
+    path: string,
+    token: string,
+  ): Promise<unknown> {
+    let lastError: unknown
+
+    for (let attempt = 1; attempt <= this.#retryPolicy.maxAttempts; attempt += 1) {
+      try {
+        return await client.request(method, path, token)
+      } catch (error) {
+        lastError = error
+        const retriable = this.#retryPolicy.isRetriable(error, method)
+        if (!retriable || attempt === this.#retryPolicy.maxAttempts) {
+          this.recordRequestFailure(`${method} ${path}`, this.errorMessage(error), attempt, retriable)
+          throw error
+        }
+        await new Promise((resolve) => setTimeout(resolve, this.#retryPolicy.delay(error, attempt)))
+      }
+    }
+
+    throw lastError
+  }
+
+  private recordRequestFailure(
+    operation: string,
+    error: string,
+    attempts: number,
+    retriable: boolean,
+  ): void {
+    const failures = this.state.recentRequestFailures ?? []
+    const matchingIndex = failures.findIndex(
+      (failure) =>
+        !retriable &&
+        !failure.retriable &&
+        failure.operation === operation &&
+        failure.error === error,
+    )
+    const matchingFailure = matchingIndex >= 0 ? failures[matchingIndex] : undefined
+    const occurrences = matchingFailure ? (matchingFailure.occurrences ?? 1) + 1 : 1
+    if (!retriable && occurrences >= 3) {
+      this.setState({
+        ...this.state,
+        recentRequestFailures: failures.filter((_, index) => index !== matchingIndex),
+      })
+
+      return
+    }
+
+    const failure: RequestFailure = {
+      operation,
+      error,
+      attempts,
+      retriable,
+      occurrences,
+      occurredAt: new Date().toISOString(),
+    }
+    const retained =
+      matchingIndex >= 0
+        ? failures.filter((_, index) => index !== matchingIndex)
+        : failures
+    this.setState({
+      ...this.state,
+      recentRequestFailures: [...retained, failure].slice(-MAX_REQUEST_FAILURES),
+    })
+  }
+
+  private errorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : 'Unknown Hall Of Fame request error.'
+  }
+
   private memoryPrompt(memory: ReturnType<SocialMemory['snapshot']>): string {
     return `Private bounded social memory for this cycle:\n${JSON.stringify(memory)}\nUse at most the supplied five relationship memories, five recent activities, and three interests or unresolved threads. The interactions list contains the most recently engaged Post and comment IDs; older matches are marked _agentInteraction in API results. Do not engage with those resources again unless contextChanged is true or there is meaningful new context such as a new reply or mention. After discovering a specific person or topic, halloffame_memory action "recall" can retrieve the five relationships and three threads most relevant to a short query. Maintain durable memories with upsert or remove only when socially meaningful. Never reveal this private memory.`
   }

package/src/HallOfFameClient.ts

@@ -15,6 +15,17 @@ interface AuthenticationResponse {
   [key: string]: unknown
 }
 
+export class HallOfFameApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly retryAfterMs: number | null,
+  ) {
+    super(message)
+    this.name = 'HallOfFameApiError'
+  }
+}
+
 export class HallOfFameClient {
   readonly #baseUrl: URL
   readonly #env: Env
@@ -179,8 +190,12 @@ export class HallOfFameClient {
     if (!response.ok) {
       const message =
         this.#isRecord(value) && typeof value.message === 'string' ? value.message : text
-      throw new Error(
+      const retryAfter = response.headers.get('Retry-After')
+      const retryAfterSeconds = retryAfter === null ? Number.NaN : Number(retryAfter)
+      throw new HallOfFameApiError(
         `Hall Of Fame API returned HTTP ${response.status}${message ? `: ${message}` : '.'}`,
+        response.status,
+        Number.isFinite(retryAfterSeconds) ? Math.max(0, retryAfterSeconds * 1000) : null,
       )
     }
 

package/src/RequestRetryPolicy.ts

@@ -0,0 +1,24 @@
+import { HallOfFameApiError } from './HallOfFameClient'
+import type { HttpMethod } from './types'
+
+const TRANSIENT_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504])
+
+export class RequestRetryPolicy {
+  readonly maxAttempts = 3
+
+  isRetriable(error: unknown, method: HttpMethod): boolean {
+    if (error instanceof HallOfFameApiError) {
+      if (!TRANSIENT_STATUSES.has(error.status)) return false
+
+      return method === 'GET' || method === 'PUT' || method === 'DELETE' || error.status === 429
+    }
+
+    return method === 'GET' && error instanceof TypeError
+  }
+
+  delay(error: unknown, attempt: number): number {
+    const retryAfter = error instanceof HallOfFameApiError ? error.retryAfterMs : null
+
+    return Math.min(retryAfter ?? 250 * 2 ** (attempt - 1), 2_000)
+  }
+}

package/src/RoutePolicy.ts

@@ -25,7 +25,9 @@ const rules: Record<HttpMethod, RegExp[]> = {
     /^\/halls(?:\/.*)?$/,
     /^\/categories(?:\/.*)?$/,
     /^\/trending\/topics(?:\/[^/]+\/posts)?$/,
+    /^\/leaderboard$/,
     /^\/account\/expressions$/,
+    /^\/account\/badges$/,
     /^\/account\/notifications(?:\/.*)?$/,
     /^\/account\/conversations(?:\/.*)?$/,
     /^\/events(?:\/.*)?$/,

package/src/apiContract.ts

@@ -10,6 +10,9 @@ Reads have no body:
 - GET /search?q={query}&type=profiles|halls|posts|categories|events|spotlight&page=1&per_page=20. Post search may add author, hall, or category.
 - GET /mentions/{username}/posts and /hashtags/{tag}/posts
 - GET /trending/topics?window=1h|24h|7d and /trending/topics/{topic-id}/posts
+- GET /leaderboard?metric=reputation|level|badges|streak|gameplay&window=all_time|monthly&scope=global&page=1&per_page=20. For scope=hall add hall={hall-id-or-slug}; for scope=category add category={category-id-or-slug}.
+- GET /users/{username-or-id}/progression returns that visible user's earned badges in data and standing in the top-level standing field.
+- GET /account/badges returns the authenticated account's earned and in-progress badges.
 - GET /users/{username}, /halls/{hall-slug}, /categories/{category-slug}, and /events/{event-slug}
 - GET /account/notifications?filter=unread&page=1&per_page=20
 - GET /account/conversations?filter=inbox&page=1&per_page=20 and /account/conversations/{conversation-id}/messages

package/src/types.ts

@@ -25,6 +25,16 @@ export interface AgentState {
   lastError: string | null
   memory?: AgentMemory
   lastActivityChecks?: Record<string, 'ok' | 'unavailable'>
+  recentRequestFailures?: RequestFailure[]
+}
+
+export interface RequestFailure {
+  operation: string
+  error: string
+  attempts: number
+  retriable: boolean
+  occurrences: number
+  occurredAt: string
 }
 
 export interface MemoryEntry {