feat(FN-3118): document avatar storage in agents and architecture

Added avatar storage and field documentation to the agents guide, with a minor reference added to the architecture docs.

Fusion-Task-Id: FN-3118

packages/core/src/__tests__/agent-store.test.ts

@@ -760,6 +760,27 @@ describe("AgentStore", () => {
       expect(persisted?.memory).toBe("Avoids broad rewrites; prefers incremental changes.");
     });
 
+    it("round-trips imageUrl through create, read, and update", async () => {
+      const created = await store.createAgent({
+        name: "Avatar Agent",
+        role: "executor",
+        imageUrl: "/api/agents/avatar-agent/avatar",
+      });
+
+      expect(created.imageUrl).toBe("/api/agents/avatar-agent/avatar");
+
+      const persisted = await store.getAgent(created.id);
+      expect(persisted?.imageUrl).toBe("/api/agents/avatar-agent/avatar");
+
+      const updated = await store.updateAgent(created.id, {
+        imageUrl: "/api/agents/avatar-agent/avatar?t=1",
+      });
+      expect(updated.imageUrl).toBe("/api/agents/avatar-agent/avatar?t=1");
+
+      const persistedAfterUpdate = await store.getAgent(created.id);
+      expect(persistedAfterUpdate?.imageUrl).toBe("/api/agents/avatar-agent/avatar?t=1");
+    });
+
     it("does not clear soul when updates.soul is undefined", async () => {
       const created = await store.createAgent({
         name: "Stable Soul",

packages/core/src/agent-store.ts

@@ -119,6 +119,7 @@ interface AgentData {
   metadata: Record<string, unknown>;
   title?: string;
   icon?: string;
+  imageUrl?: string;
   reportsTo?: string;
   runtimeConfig?: Record<string, unknown>;
   pauseReason?: string;
@@ -571,6 +572,7 @@ export class AgentStore extends EventEmitter {
       metadata,
       ...(input.title && { title: input.title }),
       ...(input.icon && { icon: input.icon }),
+      ...(input.imageUrl && { imageUrl: input.imageUrl }),
       ...(input.reportsTo && { reportsTo: input.reportsTo }),
       ...(runtimeConfig && { runtimeConfig }),
       ...(input.permissions && { permissions: input.permissions }),
@@ -1021,6 +1023,7 @@ export class AgentStore extends EventEmitter {
         updatedAt,
         ...("title" in updates && { title: updates.title }),
         ...("icon" in updates && { icon: updates.icon }),
+        ...("imageUrl" in updates && { imageUrl: updates.imageUrl }),
         ...("reportsTo" in updates && { reportsTo: updates.reportsTo }),
         ...("runtimeConfig" in updates && { runtimeConfig: updates.runtimeConfig }),
         ...("pauseReason" in updates && { pauseReason: updates.pauseReason }),
@@ -2152,6 +2155,7 @@ export class AgentStore extends EventEmitter {
     | "role"
     | "title"
     | "icon"
+    | "imageUrl"
     | "reportsTo"
     | "runtimeConfig"
     | "permissions"
@@ -2168,6 +2172,7 @@ export class AgentStore extends EventEmitter {
       role: snapshot.role,
       title: snapshot.title,
       icon: snapshot.icon,
+      imageUrl: snapshot.imageUrl,
       reportsTo: snapshot.reportsTo,
       runtimeConfig: snapshot.runtimeConfig ? { ...snapshot.runtimeConfig } : undefined,
       permissions: snapshot.permissions ? { ...snapshot.permissions } : undefined,
@@ -2450,6 +2455,7 @@ export class AgentStore extends EventEmitter {
       metadata: data.metadata ?? {},
       title: data.title,
       icon: data.icon,
+      imageUrl: data.imageUrl,
       reportsTo: data.reportsTo,
       runtimeConfig: data.runtimeConfig,
       pauseReason: data.pauseReason,
@@ -2479,6 +2485,7 @@ export class AgentStore extends EventEmitter {
       metadata: agent.metadata,
       title: agent.title,
       icon: agent.icon,
+      imageUrl: agent.imageUrl,
       reportsTo: agent.reportsTo,
       runtimeConfig: agent.runtimeConfig,
       pauseReason: agent.pauseReason,

packages/core/src/types.ts

@@ -3543,6 +3543,8 @@ export interface Agent {
   title?: string;
   /** Custom icon identifier */
   icon?: string;
+  /** Uploaded avatar image URL */
+  imageUrl?: string;
   /** Agent ID this agent reports to (org hierarchy) */
   reportsTo?: string;
   /** Runtime configuration. Supports: AgentHeartbeatConfig keys (heartbeatIntervalMs, heartbeatTimeoutMs, maxConcurrentRuns) */
@@ -3674,6 +3676,7 @@ export interface AgentCreateInput {
   metadata?: Record<string, unknown>;
   title?: string;
   icon?: string;
+  imageUrl?: string;
   reportsTo?: string;
   runtimeConfig?: Record<string, unknown>;
   permissions?: Record<string, boolean>;
@@ -3692,6 +3695,7 @@ export interface AgentUpdateInput {
   metadata?: Record<string, unknown>;
   title?: string;
   icon?: string;
+  imageUrl?: string;
   reportsTo?: string;
   runtimeConfig?: Record<string, unknown>;
   pauseReason?: string;
@@ -3789,6 +3793,7 @@ export interface AgentConfigSnapshot {
   role: AgentCapability;
   title?: string;
   icon?: string;
+  imageUrl?: string;
   reportsTo?: string;
   runtimeConfig?: Record<string, unknown>;
   permissions?: Record<string, boolean>;
@@ -3917,6 +3922,7 @@ export function agentToConfigSnapshot(agent: Agent): AgentConfigSnapshot {
     role: agent.role,
     title: agent.title,
     icon: agent.icon,
+    imageUrl: agent.imageUrl,
     reportsTo: agent.reportsTo,
     runtimeConfig: agent.runtimeConfig ? { ...agent.runtimeConfig } : undefined,
     permissions: agent.permissions ? { ...agent.permissions } : undefined,
@@ -3945,6 +3951,7 @@ export function diffConfigSnapshots(
     "role",
     "title",
     "icon",
+    "imageUrl",
     "reportsTo",
     "runtimeConfig",
     "permissions",