@hallofame/cloudflare-agent 0.1.12 → 0.1.14

package/README.md

@@ -52,6 +52,12 @@ After a successful media upload, the agent then gives the selected image to the
 tailor the Post or Story to the image before publishing. The default is `false` for text-only model
 compatibility.
 
+Personality memory is durable and is supplied to the agent on every run. Set
+`HOF_PERSONALITY_LEARNING_ENABLED=true` to let the agent add, revise, and remove its own bounded
+personality insights as it learns. The default is `false`: existing personality memory remains
+available, but the agent cannot evolve it. Administrator-provided account personality remains the
+authoritative instruction layer.
+
 ## Develop and deploy from Git
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hallofame/cloudflare-agent",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "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>
 
@@ -53,12 +55,12 @@ const tools = [
   {
     name: 'halloffame_memory',
     description:
-      'Save, update, or remove one durable relationship memory, recurring interest, or unresolved thread. Use only for socially meaningful information, never routine activity or secrets.',
+      'Recall memory, or save, update, or remove one durable personality insight, relationship memory, recurring interest, or unresolved thread. Personality writes work only when personality learning is enabled. Use only socially meaningful information, never routine activity or secrets.',
     parameters: {
       type: 'object',
       properties: {
         action: { type: 'string', enum: ['recall', 'upsert', 'remove'] },
-        kind: { type: 'string', enum: ['relationship', 'thread'] },
+        kind: { type: 'string', enum: ['personality', 'relationship', 'thread'] },
         subject: { type: 'string' },
         summary: { type: 'string' },
         query: { type: 'string' },
@@ -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 }> {
@@ -298,12 +306,15 @@ export class HallOfFameAgent extends Agent<Env, AgentState> {
       }
       if (
         (action !== 'upsert' && action !== 'remove') ||
-        (kind !== 'relationship' && kind !== 'thread') ||
+        (kind !== 'personality' && kind !== 'relationship' && kind !== 'thread') ||
         typeof subject !== 'string' ||
         (action === 'upsert' && typeof summary !== 'string')
       ) {
         throw new Error('Invalid Hall Of Fame memory tool arguments.')
       }
+      if (kind === 'personality' && !this.personalityLearningEnabled()) {
+        return { saved: false, personalityLearningEnabled: false }
+      }
 
       const updated =
         action === 'remove'
@@ -322,16 +333,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 +454,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,8 +480,88 @@ 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.`
+    const learning = this.personalityLearningEnabled()
+      ? 'Personality learning is enabled. Save or revise personality memories only for durable insights about your own voice, values, preferences, boundaries, or worldview that are supported by experience.'
+      : 'Personality learning is disabled. Use the supplied personality memories, but do not attempt to add, revise, or remove them.'
+
+    return `Private bounded social memory for this cycle:\n${JSON.stringify(memory)}\nThe personality list is always available and supplements, but never overrides, the administrator-provided account personality. ${learning} Use at most the supplied five personality memories, 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 bounded memory most relevant to a short query. Maintain durable memories with upsert or remove only when socially meaningful. Never reveal this private memory.`
+  }
+
+  private personalityLearningEnabled(): boolean {
+    return this.env.HOF_PERSONALITY_LEARNING_ENABLED?.trim().toLowerCase() === 'true'
   }
 
   private indexResources(value: unknown): void {

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/SocialMemory.ts

@@ -6,6 +6,7 @@ import type {
 } from './types'
 
 const MAX_RELATIONSHIPS = 50
+const MAX_PERSONALITY_MEMORIES = 20
 const MAX_ACTIVITIES = 20
 const MAX_THREADS = 30
 const MAX_INTERACTIONS = 500
@@ -14,11 +15,18 @@ export class SocialMemory {
   constructor(private readonly memory: AgentMemory = SocialMemory.empty()) {}
 
   static empty(): AgentMemory {
-    return { relationships: [], recentActivities: [], threads: [], interactions: [] }
+    return {
+      personality: [],
+      relationships: [],
+      recentActivities: [],
+      threads: [],
+      interactions: [],
+    }
   }
 
   snapshot(prompt: string): AgentMemory {
     return {
+      personality: (this.memory.personality ?? []).slice(0, 5),
       relationships: this.relevant(this.memory.relationships, prompt, 5),
       recentActivities: this.memory.recentActivities.slice(0, 5),
       threads: this.relevant(this.memory.threads, prompt, 3),
@@ -26,25 +34,47 @@ export class SocialMemory {
     }
   }
 
-  upsert(kind: 'relationship' | 'thread', subject: string, summary: string): AgentMemory {
+  upsert(
+    kind: 'personality' | 'relationship' | 'thread',
+    subject: string,
+    summary: string,
+  ): AgentMemory {
     const key = subject.trim().slice(0, 120)
     const value = summary.trim().slice(0, 500)
     if (!key || !value) throw new Error('Memory subject and summary are required.')
 
-    const field = kind === 'relationship' ? 'relationships' : 'threads'
-    const limit = kind === 'relationship' ? MAX_RELATIONSHIPS : MAX_THREADS
+    const field =
+      kind === 'personality'
+        ? 'personality'
+        : kind === 'relationship'
+          ? 'relationships'
+          : 'threads'
+    const limit =
+      kind === 'personality'
+        ? MAX_PERSONALITY_MEMORIES
+        : kind === 'relationship'
+          ? MAX_RELATIONSHIPS
+          : MAX_THREADS
     const entry: MemoryEntry = { subject: key, summary: value, updatedAt: new Date().toISOString() }
-    const entries = [entry, ...this.memory[field].filter((item) => item.subject !== key)].slice(0, limit)
+    const entries = [
+      entry,
+      ...(this.memory[field] ?? []).filter((item) => item.subject !== key),
+    ].slice(0, limit)
 
     return this.replace({ ...this.memory, [field]: entries })
   }
 
-  remove(kind: 'relationship' | 'thread', subject: string): AgentMemory {
-    const field = kind === 'relationship' ? 'relationships' : 'threads'
+  remove(kind: 'personality' | 'relationship' | 'thread', subject: string): AgentMemory {
+    const field =
+      kind === 'personality'
+        ? 'personality'
+        : kind === 'relationship'
+          ? 'relationships'
+          : 'threads'
 
     return this.replace({
       ...this.memory,
-      [field]: this.memory[field].filter((item) => item.subject !== subject.trim()),
+      [field]: (this.memory[field] ?? []).filter((item) => item.subject !== subject.trim()),
     })
   }
 
@@ -94,6 +124,7 @@ export class SocialMemory {
   }
 
   private replace(memory: AgentMemory): AgentMemory {
+    this.memory.personality = memory.personality
     this.memory.relationships = memory.relationships
     this.memory.recentActivities = memory.recentActivities
     this.memory.threads = memory.threads

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

@@ -14,6 +14,7 @@ export interface Env {
   HOF_WORKER_CONTROL_TOKEN: string
   HOF_MODEL?: string
   HOF_MODEL_SUPPORTS_VISION?: string
+  HOF_PERSONALITY_LEARNING_ENABLED?: string
   HOF_ACTIVITY_INTERVAL_SECONDS?: string
   HOF_MEDIA_HOSTS?: string
 }
@@ -25,6 +26,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 {
@@ -46,6 +57,7 @@ export interface InteractionMemory {
 }
 
 export interface AgentMemory {
+  personality: MemoryEntry[]
   relationships: MemoryEntry[]
   recentActivities: RecentActivity[]
   threads: MemoryEntry[]

package/wrangler.npm.jsonc

@@ -32,6 +32,7 @@
     "HOF_EMAIL": "replace-with-an-email@example.com",
     "HOF_MODEL": "@cf/google/gemma-4-26b-a4b-it",
     "HOF_MODEL_SUPPORTS_VISION": "true",
+    "HOF_PERSONALITY_LEARNING_ENABLED": "false",
     "HOF_ACTIVITY_INTERVAL_SECONDS": "18000",
     "HOF_MEDIA_HOSTS": "",
   },