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:

  • Auth context is pushed via diosc('auth', context) — this connects and starts a session
  • A new session is explicitly requested via diosc('startNewSession')

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
  6. Returns a session token (held in-memory only, never persisted to browser storage)

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)
  • Files can be uploaded and referenced in conversation

Session End​

A session ends when:

  • Auth is cleared via diosc('auth', null)
  • WebSocket disconnects and doesn't reconnect
  • Session timeout is reached (configurable)
  • User explicitly starts a new 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​

{
  path: "/orders/12345",
  search: "?status=pending",
  hash: ""
}

The AI knows which page the user is on and can tailor responses accordingly. Page context is updated via a navigation observer:

diosc('observe', 'navigation', (notify) => {
  notify({
    path: window.location.pathname,
    search: window.location.search,
    hash: window.location.hash
  });
});

Conversation History​

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

The AI remembers the conversation and can reference previous messages.

Session Persistence​

Session Tokens​

Sessions use in-memory tokens for security. The token is generated by the backend on session start and held only in JavaScript memory — never persisted to localStorage or sessionStorage.

Resuming Sessions​

Users can resume previous sessions from the session history:

// Load a previous session by ID
diosc('loadSession', 'sess_abc123');

This loads the full conversation history from the server.

Session History​

The <diosc-chat> component includes built-in session history with search, pinning, and renaming. You can also manage sessions programmatically:

// Fetch session list
diosc('fetchSessionList', { limit: 20 });

// Search sessions semantically
diosc('searchSessions', { query: 'billing issue' });

// Pin important sessions
diosc('pinSession', 'sess_abc123', true);

// Rename for easier identification
diosc('renameSession', 'sess_abc123', 'Q2 Billing Discussion');

// Start fresh
diosc('startNewSession');

Session Events​

Listen to session lifecycle events:

// New session created
diosc('on', 'session:started', ({ session, token }) => {
  console.log('Session ID:', session.id);
});

// Joined existing session
diosc('on', 'session:joined', ({ session, messages }) => {
  console.log('Loaded', messages?.length, 'previous messages');
});

// Session restored from token
diosc('on', 'session:restored', ({ session, messages, files }) => {
  console.log('Restored session with', messages?.length, 'messages');
});

// Session restore failed (e.g., expired token)
diosc('on', 'session:restore_failed', ({ code, message }) => {
  console.log('Could not restore:', message);
  // Engine will start a new session automatically
});

// Session error
diosc('on', 'session:error', ({ code, message, recoverable }) => {
  console.error(`[${code}]`, message);
});

// Session renamed
diosc('on', 'session:renamed', ({ sessionId, name }) => {
  console.log(`Session renamed to: ${name}`);
});

Session Configuration​

Timeout​

Session timeout is configured in the admin portal per assistant. When a session is idle beyond the timeout, the server ends it.

Context Limits​

The AI model's context window determines how many messages can be included. When the conversation exceeds the limit, older messages are automatically summarized or truncated.

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​

// Register a navigation observer for your SPA
diosc('observe', 'navigation', (notify) => {
  // React Router, Vue Router, etc. — notify on route change
  notify({
    path: window.location.pathname,
    search: window.location.search
  });
});

3. Clean Up on Logout​

// Push null to cleanly disconnect
diosc('auth', null);

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

// Bad - sensitive data in context
diosc('observe', 'navigation', (notify) => {
  notify({ path: '/payments', creditCard: '4111...' }); // Don't do this
});

// Good - reference IDs only, let the AI fetch details via tools
diosc('observe', 'navigation', (notify) => {
  notify({ path: '/payments/pm_123' });
});

Next Steps​

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