@crossworks/client-types 0.232.82 → 0.232.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossworks/client-types",
-  "version": "0.232.82",
+  "version": "0.232.85",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/index.ts

@@ -260,7 +260,12 @@ export interface AgentAvatarDTO {
   seed: string;
   /** Avatar-builder component choices layered over the seed: component name →
    *  pinned variant, or null to hide an optional component. Stale entries
-   *  (from another style) are ignored at render time. Absent = seed only. */
+   *  (from another style) are ignored at render time.
+   *
+   *  READ: absent = seed only. WRITE protocol (agents create/patch): an
+   *  ABSENT parts key means "keep what's stored" — so a parts-unaware client
+   *  can never wipe pins — `{}` is the explicit clear, and a non-empty map
+   *  replaces. Every client that writes avatars must send `{}` to clear. */
   parts?: Record<string, string | null>;
 }
 
@@ -321,6 +326,36 @@ export interface PersonaNoteDTO {
   supersededBy?: string;
 }
 
+/** Raw counters behind an agent's experience level — always shipped next to
+ *  the level so the UI can show WHY it is level N. All are lifetime counts for
+ *  THIS brain (experience is per-brain, display-only — never a trust gate). */
+export interface AgentExperienceComponentsDTO {
+  /** Completed conversation turns this agent answered on the assistant
+   *  stream (web, Telegram, mobile). Team/forum turns live in a different
+   *  store and are not counted (yet). */
+  turns: number;
+  /** Tool calls that succeeded across those turns. */
+  toolSuccesses: number;
+  /** Delegated runs this agent completed for other agents. */
+  delegations: number;
+  /** Heartbeat fires this agent completed. */
+  heartbeats: number;
+}
+
+/** An agent's experience readout — a soft-capped level derived from real
+ *  accumulated usage (see `agent-experience.ts` server-side for the weights
+ *  and curve). Computed at read time; nothing is stored. */
+export interface AgentExperienceDTO {
+  level: number;
+  /** Total XP earned. */
+  xp: number;
+  /** Cumulative XP at which the current level began. */
+  levelXp: number;
+  /** Cumulative XP needed to reach the next level. */
+  nextLevelXp: number;
+  components: AgentExperienceComponentsDTO;
+}
+
 /** An agent as returned by `GET /api/agents` (and `…/[id]`). Dates are ISO
  *  strings. The server aliases its `AgentSummary` to this so the wire shape and
  *  the consuming client can't drift. */
@@ -366,6 +401,11 @@ export interface AgentDTO {
   manifestManaged: boolean;
   lastUsedAt: string | null;
   usageCount: number;
+  /** Experience readout (level + raw counters). Optional: filled on the list
+   *  reads the agent screens use (`GET /api/agents`, the assistant thread
+   *  bundle); absent on single-row CRUD echoes where computing it would cost
+   *  extra queries for nothing. */
+  experience?: AgentExperienceDTO;
   createdAt: string;
   updatedAt: string;
 }
@@ -930,16 +970,18 @@ export type ProfilePreferences = {
    *  so an avatar still renders. Personal — two admins share the brain's style
    *  but never the same avatar. */
   avatarSeed?: string;
-  /** Avatar-builder component choices for THIS user's avatar, layered over the
-   *  seed: component name → pinned variant, or null to hide an optional
-   *  component. Personal, like avatarSeed. Stale entries (saved under another
-   *  brain style) are ignored at render time. Absent/empty = seed only. */
+  /** Avatar-builder component choices for THIS login's avatar, layered over
+   *  the seed: component name → pinned variant, or null to hide an optional
+   *  component. Per-login (the profile routes address the ACTOR's row). Stale
+   *  entries (saved under another brain style) are ignored at render time.
+   *  READ: absent/empty = seed only. WRITE (profile PUT): applied only when
+   *  SENT; `{}` clears. */
   avatarParts?: Record<string, string | null>;
-  /** Content-addressed storage key of THIS user's uploaded profile PHOTO —
+  /** Content-addressed storage key of THIS login's uploaded profile PHOTO —
    *  when set, clients show the photo instead of the generated avatar
-   *  (photo → generated seed → initials). Personal, like avatarSeed; set only
-   *  from Settings → Profile, never for agents. Served privately by
-   *  GET /api/profile/photo (cookie or asset token). */
+   *  (photo → generated seed → initials). Per-login (the photo routes address
+   *  the ACTOR's row); set only from Settings → Profile, never for agents.
+   *  Served privately by GET /api/profile/photo (cookie or asset token). */
   avatarPhotoKey?: string;
   /** Content-Type of the photo bytes (png/jpeg/webp — never SVG). */
   avatarPhotoType?: string;

package/src/journey-format.ts

@@ -247,6 +247,20 @@ export type ActivityItem = ActionPresentation & {
   factCount: number;
   mentionCount: number;
   relationCount: number;
+  /** Who performed the action. Null for pipeline traces that carry no agent
+   *  (extractor/summarizer runs identify via workerSlug instead; ingest and
+   *  federation traces have neither). */
+  agentId: string | null;
+  agentName: string | null;
+  agentSlug: string | null;
+  /** Seed for GeneratedAvatar: the agent's stored avatar seed, falling back
+   *  to its slug (same convention the settings screens use). */
+  avatarSeed: string | null;
+  /** ai-worker identity for worker-driven traces (extractor, summarizer). */
+  workerSlug: string | null;
+  /** Set on delegated child runs (invoke_agent) — the parent trace's id, so
+   *  the UI can nest fan-out under the delegating turn. */
+  parentTraceId: string | null;
 };
 
 export type JourneyDetail = TraceDetail & { landed: LandedLayers | null };