Skip to main content

Sessions

A session is a conversation between a user and the AI assistant. Sessions maintain context, remember previous messages, and carry the user's authentication throughout the interaction.

Session Lifecycle​

Session Creation​

A session is created when:

  • User opens the chat interface
  • diosc('connect') is called programmatically
  • An action button triggers a new conversation

At creation, Diosc:

  1. Establishes a WebSocket connection
  2. Calls the user resolver to identify the user
  3. Loads the assistant configuration
  4. Fetches available MCP tools
  5. Applies role-based prompts

Active Session​

During an active session:

  • Messages are exchanged via WebSocket
  • Conversation history is maintained
  • User authentication is forwarded with each tool call
  • Context accumulates (AI remembers previous messages)

Session End​

A session ends when:

  • User closes the chat or navigates away
  • WebSocket disconnects and doesn't reconnect
  • Session timeout is reached (configurable)
  • User explicitly ends the session

Session Context​

Each session carries context that influences AI behavior:

User Context​

{
  userId: "user_123",
  displayName: "John Doe",
  email: "john@example.com",
  roles: ["admin", "sales"],
  tenantId: "acme-corp",
  metadata: {
    department: "Sales",
    region: "APAC"
  }
}

This comes from your User Resolver webhook.

Page Context​

{
  currentPath: "/orders/12345",
  pageType: "order-details",
  pageData: {
    orderId: "12345",
    status: "pending"
  }
}

The AI knows which page the user is on and can tailor responses accordingly.

Conversation History​

[
  { role: "user", content: "Show me pending orders" },
  { role: "assistant", content: "You have 5 pending orders..." },
  { role: "user", content: "Approve the first one" }
]

The AI remembers the conversation and can reference previous messages.

Session Persistence​

Within a Page Session​

By default, sessions persist while the user stays on the page:

  • Refreshing the page creates a new session
  • Navigating away ends the session

Across Page Navigations​

Enable session resumption for single-page applications:

diosc('config', {
  sessionPersistence: 'localStorage',  // or 'sessionStorage'
  resumeOnReconnect: true
});

This stores the session ID and resumes the conversation if the user returns.

Server-Side Sessions​

For longer persistence, sessions are stored server-side:

// Resume a specific session
diosc('resume', { sessionId: 'sess_abc123' });

This loads the full conversation history from the server.

Session Events​

Listen to session lifecycle events:

// Session started
diosc('on', 'session_started', (session) => {
  console.log('Session ID:', session.id);
  console.log('User:', session.user.displayName);
});

// Session ended
diosc('on', 'session_ended', (reason) => {
  console.log('Session ended:', reason);
  // 'user_closed', 'timeout', 'error', 'disconnected'
});

// Session resumed
diosc('on', 'session_resumed', (session) => {
  console.log('Resumed session with', session.messageCount, 'messages');
});

Session Configuration​

Timeout​

// Admin Portal configuration
{
  sessionTimeoutMinutes: 30,  // End session after 30 min of inactivity
  maxSessionDurationHours: 8  // Hard limit on session duration
}

Context Limits​

{
  maxConversationTokens: 100000,  // Truncate old messages if exceeded
  contextWindowStrategy: 'sliding'  // 'sliding' or 'summarize'
}

Tool Loading​

{
  toolLoadingStrategy: 'eager',  // Load all tools at session start
  // or 'lazy' - Load tools when first needed
}

Multi-Tab Behavior​

When users have multiple browser tabs:

Shared Session (Default)​

All tabs share the same session:

diosc('config', {
  sessionScope: 'shared'  // Default
});
  • Messages appear in all tabs
  • Useful for consistent experience

Isolated Sessions​

Each tab has its own session:

diosc('config', {
  sessionScope: 'tab'
});
  • Independent conversations per tab
  • Useful when context differs per tab

Session Data Flow​

Best Practices​

1. Handle Disconnections Gracefully​

diosc('on', 'disconnected', () => {
  showNotification('Connection lost. Reconnecting...');
});

diosc('on', 'reconnected', () => {
  showNotification('Connection restored.');
});

2. Provide Page Context​

// When page changes in SPA
router.afterEach((to) => {
  diosc('pageContext', {
    path: to.path,
    pageType: to.meta.pageType,
    pageData: extractPageData(to)
  });
});

3. Clean Up on Unmount​

// React example
useEffect(() => {
  return () => {
    diosc('disconnect');
  };
}, []);

4. Don't Store Sensitive Data in Page Context​

// ❌ Bad - sensitive data in context
diosc('pageContext', {
  creditCardNumber: '4111...'
});

// ✅ Good - reference IDs only
diosc('pageContext', {
  paymentMethodId: 'pm_123'
});

Next Steps​

  • BYOA - How authentication flows through sessions
  • MCP - Tools available during sessions
  • Roles - Role-based session behavior