Persist AgentOptions in session metadata for full lifecycle management

[ulivz]

Problem

Currently, AgentOptions passed to createSession are only used for one-time agent initialization and are not persisted. This creates limitations:

1. No visibility: Users cannot see what AgentOptions were used to create a session
2. No reproduction: Cannot recreate sessions with identical AgentOptions
3. No debugging: Difficult to troubleshoot issues related to specific AgentOptions
4. Inconsistent state: AgentOptions are lost after session creation, breaking the full lifecycle management

Goal

Persist AgentOptions in session metadata alongside runtimeSettings, enabling full lifecycle management and visibility.

Complete Storage & Consumption Chain

1. Storage Chain (数据存储链路)

1.1 Frontend: Session Creation Request

File: multimodal/tarko/agent-ui/src/common/services/apiService.ts

async createSession(
  runtimeSettings?: Record<string, any>,
  agentOptions?: Record<string, any>,
): Promise<SessionInfo> {
  const response = await fetch(`${API_BASE_URL}${API_ENDPOINTS.CREATE_SESSION}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ 
      runtimeSettings,  // ✅ Already persisted
      agentOptions      // ❌ Currently not persisted
    }),
  });
  // ...
}

1.2 Backend: Session Controller

File: multimodal/tarko/agent-server/src/api/controllers/sessions.ts

export async function createSession(req: Request, res: Response) {
  const { runtimeSettings, agentOptions } = req.body;
  
  // CURRENT: Only runtimeSettings persisted
  const sessionInfo = await server.storageProvider.createSession({
    metadata: {
      runtimeSettings: runtimeSettings || {},
      // TODO: Add agentOptions persistence
      agentOptions: agentOptions || {},  // ⭐ NEW: Persist agentOptions
    }
  });

  // Agent initialization (unchanged)
  const combinedOptions = {
    ...server.appConfig,
    ...runtimeSettings,
    ...agentOptions
  };
  
  const agentSession = await AgentSessionFactory.create(
    sessionInfo.id,
    combinedOptions,
    server
  );
}

1.3 Storage Provider: Database Persistence

File: multimodal/tarko/agent-server/src/core/storage/StorageProvider.ts

interface SessionMetadata {
  runtimeSettings?: Record<string, any>;  // ✅ Already exists
  agentOptions?: Record<string, any>;     // ⭐ NEW: Add to interface
  modelConfig?: AgentModel;
  // ... other metadata
}

async createSession(sessionData: {
  metadata: SessionMetadata;
}): Promise<SessionInfo> {
  // Storage implementation persists both runtimeSettings AND agentOptions
  // to session metadata in database/file system
}

2. Consumption Chain (数据消费链路)

2.1 Session Retrieval: API Endpoint

File: multimodal/tarko/agent-server/src/api/controllers/sessions.ts

export async function getSessionDetails(req: Request, res: Response) {
  const sessionId = req.query.sessionId as string;
  const sessionInfo = await server.storageProvider.getSessionInfo(sessionId);
  
  // Response includes both runtimeSettings AND agentOptions
  res.json({
    session: {
      ...sessionInfo,
      metadata: {
        runtimeSettings: sessionInfo.metadata?.runtimeSettings || {},
        agentOptions: sessionInfo.metadata?.agentOptions || {},    // ⭐ NEW: Return agentOptions
        // ... other metadata
      }
    }
  });
}

2.2 Frontend: Session State Management

File: multimodal/tarko/agent-ui/src/common/state/actions/sessionActions.ts

export const loadSessionAction = atom(null, async (get, set, sessionId: string) => {
  const sessionInfo = await apiService.getSessionDetails(sessionId);
  
  // Store complete session metadata including agentOptions
  set(sessionMetadataAtom, {
    [sessionId]: {
      runtimeSettings: sessionInfo.metadata?.runtimeSettings || {},
      agentOptions: sessionInfo.metadata?.agentOptions || {},      // ⭐ NEW: Store agentOptions
      // ... other metadata
    }
  });
});

2.3 UI Display: Session Information Panel

File: multimodal/tarko/agent-ui/src/standalone/workspace/SessionInfoPanel.tsx (NEW)

const SessionInfoPanel: React.FC<{ sessionId: string }> = ({ sessionId }) => {
  const sessionMetadata = useAtomValue(sessionMetadataAtom);
  const metadata = sessionMetadata[sessionId];
  
  return (
    <div className="session-info-panel">
      <h3>Session Configuration</h3>
      
      {/* Runtime Settings (persistent) */}
      <section>
        <h4>Runtime Settings</h4>
        <pre>{JSON.stringify(metadata?.runtimeSettings, null, 2)}</pre>
      </section>
      
      {/* Agent Options (creation-time) */}
      <section>
        <h4>Agent Options (Creation)</h4>                           {/* ⭐ NEW: Display agentOptions */}
        <pre>{JSON.stringify(metadata?.agentOptions, null, 2)}</pre>
      </section>
    </div>
  );
};

2.4 Session Recreation: Clone Functionality

File: multimodal/tarko/agent-ui/src/standalone/chat/components/SessionActions.tsx

const handleCloneSession = async () => {
  const sessionMetadata = useAtomValue(sessionMetadataAtom);
  const currentMetadata = sessionMetadata[sessionId];
  
  // Clone session with BOTH runtimeSettings AND agentOptions
  const newSessionId = await createSession(
    currentMetadata?.runtimeSettings,
    currentMetadata?.agentOptions  // ⭐ NEW: Clone with original agentOptions
  );
  
  navigate(`/${newSessionId}`);
};

2.5 Session Restoration: Agent Recreation

File: multimodal/tarko/agent-server/src/services/session/AgentSessionFactory.ts

static async restoreSession(
  sessionId: string,
  sessionInfo: SessionInfo,
  server: AgentServer
): Promise<AgentSession> {
  
  // Combine all configuration sources for agent restoration
  const combinedOptions = {
    ...server.appConfig,                                    // Base config
    ...sessionInfo.metadata?.runtimeSettings,              // ✅ Already used
    ...sessionInfo.metadata?.agentOptions                  // ⭐ NEW: Use persisted agentOptions
  };
  
  return await this.create(sessionId, combinedOptions, server);
}

3. Data Flow Diagram (数据流图)

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Home Page     │    │  Creating Page  │    │  Session Page   │
│ agentOptions ───┼───▶│ agentOptions ───┼───▶│ agentOptions    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
                                ▼                       ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │ createSession() │    │ Session Metadata│
                       │ + agentOptions  │───▶│ + agentOptions  │
                       └─────────────────┘    └─────────────────┘
                                                       │
                                                       ▼
                                              ┌─────────────────┐
                                              │ Storage Provider│
                                              │ (Database/File) │
                                              └─────────────────┘
                                                       │
                                                       ▼
                                              ┌─────────────────┐
                                              │ Session Restore │
                                              │ + agentOptions  │
                                              └─────────────────┘

Implementation Tasks

Backend Changes

1. Update Session Metadata Interface

   • Add agentOptions field to SessionMetadata type
   • Update storage provider interfaces

2. Modify Session Creation

   • Persist agentOptions in session metadata
   • Update createSession controller

3. Update Session Retrieval

   • Return agentOptions in session details API
   • Include in session list responses

4. Session Restoration

   • Use persisted agentOptions when recreating agents
   • Update AgentSessionFactory.restoreSession()

Frontend Changes

1. Update State Management

   • Add agentOptions to session metadata atoms
   • Update session loading actions

2. UI Components

   • Create session info panel showing both settings types
   • Add agent options display in session details
   • Update session clone functionality

3. API Service

   • Handle agentOptions in session responses
   • Update type definitions

Database Schema (if applicable)

-- Update sessions table metadata column to include agentOptions
-- Example for JSON column:
ALTER TABLE sessions 
MODIFY COLUMN metadata JSON COMMENT 'Contains runtimeSettings, agentOptions, and other session metadata';

Benefits

1. Full Lifecycle Visibility: See complete session configuration
2. Reproducible Sessions: Clone sessions with identical AgentOptions
3. Better Debugging: Understand how sessions were configured
4. Audit Trail: Track what options were used for each session
5. Consistent State: No loss of configuration data

Acceptance Criteria

• agentOptions persisted in session metadata during creation
• agentOptions returned in session details API
• UI displays both runtimeSettings and agentOptions
• Session cloning preserves original agentOptions
• Session restoration uses persisted agentOptions
• No breaking changes to existing functionality
• Type safety maintained throughout the chain

Related

• Issue Support RuntimeSettings configuration in home page before session creation #1644: Support RuntimeSettings configuration in home page before session creation
• PR feat(tarko-agent-server, agent-ui): refine arch of agent options and settings from home to session #1645: feat(tarko-agent-server, agent-ui): refine arch of agent options and settings from home to session