Sessions

// src/config/sessions/types.ts
export type SessionEntry = {
  key: string;                    // Session identifier
  agentId: string;                // Which agent owns this session
  channel?: string;               // Messaging channel
  lastChannel?: string;           // Last active channel
  lastTo?: string;                // Last recipient
  lastAccountId?: string;         // Last bot account used
  lastThreadId?: string;          // Last thread ID
  deliveryContext?: DeliveryContext;  // Current delivery target
  createdAt?: string;             // ISO timestamp
  updatedAt?: string;             // ISO timestamp
  messageCount?: number;          // Total messages in session
  model?: string | ModelConfig;   // Model override
  origin?: Origin;                // Original message context
};

~/.simpleclaw/sessions/
├── sessions.json              # Session metadata index
└── transcripts/
    ├── agent_main_main.jsonl  # Main session transcript
    ├── agent_main_discord_default_channel_123.jsonl
    └── agent_support_telegram_default_direct_456.jsonl

// src/config/sessions/store.ts
const SESSION_STORE_CACHE = new Map<string, SessionStoreCacheEntry>();
const DEFAULT_SESSION_STORE_TTL_MS = 45_000; // 45 seconds

type SessionStoreCacheEntry = {
  store: Record<string, SessionEntry>;
  loadedAt: number;
  storePath: string;
  mtimeMs?: number;
};

# List all sessions
simpleclaw sessions list

# List sessions for specific agent
simpleclaw sessions list --agent main

# Show detailed session info
simpleclaw sessions list --verbose

# Get session info
simpleclaw sessions get agent:main:discord:default:channel:123

# View conversation history
simpleclaw sessions history agent:main:main

# Clear conversation history
simpleclaw sessions reset agent:main:main

# Reset all sessions for an agent
simpleclaw sessions reset --agent support --all

export type DeliveryContext = {
  channel?: string;      // "discord", "telegram", etc.
  to?: string;          // Recipient ID
  accountId?: string;   // Bot account to use
  threadId?: string;    // Thread/conversation ID
  replyToId?: string;   // Message ID to reply to
};

# Normalize and merge delivery context
deliveryContext:
  channel: discord
  to: "123456789"
  accountId: default
  threadId: "thread-abc-123"

session:
  maintenance:
    mode: auto
    diskBudget: 10GB  # Maximum total session storage
    archiveOldest: true

// src/config/sessions/disk-budget.ts
export async function enforceSessionDiskBudget(params: {
  storeDir: string;
  budgetBytes: number;
  dryRun?: boolean;
}): Promise<SessionDiskBudgetSweepResult> {
  // Calculate current usage
  const usage = await calculateSessionStorageUsage(params.storeDir);
  
  if (usage.totalBytes <= params.budgetBytes) {
    return { swept: [], bytesFreed: 0 };
  }
  
  // Archive oldest transcripts until under budget
  const toSweep = selectTranscriptsForSweep(usage, params.budgetBytes);
  return archiveTranscripts(toSweep);
}

session:
  maintenance:
    mode: auto
    retention:
      maxAge: 90d        # Delete sessions older than 90 days
      maxInactive: 30d   # Delete sessions inactive for 30 days
      keepMinimum: 10    # Always keep at least 10 most recent sessions

# Archive old transcripts
simpleclaw sessions archive --older-than 30d

# Cleanup archived sessions
simpleclaw sessions cleanup --archived

# Prune sessions by criteria
simpleclaw sessions prune --inactive 60d --keep 5

// src/agents/session-write-lock.ts
import { acquireSessionWriteLock } from "./session-write-lock.js";

const release = await acquireSessionWriteLock(sessionKey);
try {
  // Perform writes to session
  await updateSessionEntry(sessionKey, updates);
  await appendToTranscript(sessionKey, message);
} finally {
  release();  // Always release lock
}

// src/config/sessions/metadata.ts
export function deriveSessionMetaPatch(
  entry: SessionEntry
): Partial<SessionEntry> {
  return {
    updatedAt: new Date().toISOString(),
    messageCount: (entry.messageCount ?? 0) + 1,
    // ... additional computed fields
  };
}

# In session entry
sessions:
  "agent:main:discord:123":
    model:
      primary: gpt-4o
      fallbacks:
        - claude-3-7-sonnet-20250219

# Set session model
simpleclaw sessions update agent:main:main --model claude-3-7-sonnet-20250219

# Clear model override (use agent's default)
simpleclaw sessions update agent:main:main --model default

{"role":"user","content":"Hello!","timestamp":"2026-03-03T10:00:00Z"}
{"role":"assistant","content":"Hi! How can I help?","timestamp":"2026-03-03T10:00:02Z"}
{"role":"user","content":"What's the weather?","timestamp":"2026-03-03T10:00:10Z"}
{"role":"tool","tool":"web-search","args":{"query":"weather"},"timestamp":"2026-03-03T10:00:11Z"}
{"role":"tool-result","result":"Sunny, 72°F","timestamp":"2026-03-03T10:00:12Z"}
{"role":"assistant","content":"It's sunny and 72°F!","timestamp":"2026-03-03T10:00:13Z"}

const sessions = await gateway.call("sessions.list", {
  agentId: "main",  // Optional: filter by agent
  limit: 50,        // Optional: max results
  offset: 0         // Optional: pagination
});

const session = await gateway.call("sessions.get", {
  sessionKey: "agent:main:main"
});

await gateway.call("sessions.reset", {
  sessionKey: "agent:main:discord:default:channel:123"
});

await gateway.call("sessions.send", {
  sessionKey: "agent:support:telegram:default:direct:456",
  message: "Following up on your ticket..."
});