@agent-assistant/sessions 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createSessionStore, defaultAffinityResolver, InMemorySessionStoreAdapter, resolveSession, } from './sessions.js';
+export { SessionConflictError, SessionNotFoundError, SessionStateError, } from './types.js';
+export type { AffinityResolver, CreateSessionInput, Session, SessionQuery, SessionResolvableMessage, SessionState, SessionStore, SessionStoreAdapter, SessionStoreConfig, } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createSessionStore, defaultAffinityResolver, InMemorySessionStoreAdapter, resolveSession, } from './sessions.js';
+export { SessionConflictError, SessionNotFoundError, SessionStateError, } from './types.js';

package/dist/sessions.d.ts

@@ -0,0 +1,12 @@
+import type { AffinityResolver, Session, SessionQuery, SessionResolvableMessage, SessionStore, SessionStoreAdapter, SessionStoreConfig } from './types.js';
+export declare function createSessionStore(config: SessionStoreConfig): SessionStore;
+export declare class InMemorySessionStoreAdapter implements SessionStoreAdapter {
+    private readonly sessions;
+    insert(session: Session): Promise<void>;
+    fetchById(sessionId: string): Promise<Session | null>;
+    fetchMany(query: SessionQuery): Promise<Session[]>;
+    update(sessionId: string, patch: Partial<Session>): Promise<Session>;
+    delete(sessionId: string): Promise<void>;
+}
+export declare function resolveSession(message: SessionResolvableMessage, store: SessionStore, resolver: AffinityResolver): Promise<Session>;
+export declare function defaultAffinityResolver(store: SessionStore): AffinityResolver;

package/dist/sessions.js

@@ -0,0 +1,217 @@
+import { SessionConflictError, SessionNotFoundError, SessionStateError, } from './types.js';
+const DEFAULT_TTL_MS = 3_600_000;
+const DEFAULT_FIND_LIMIT = 50;
+function cloneSession(value) {
+    return structuredClone(value);
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function normalizeLimit(limit) {
+    return limit ?? DEFAULT_FIND_LIMIT;
+}
+function normalizeStateFilter(state) {
+    if (!state) {
+        return undefined;
+    }
+    return Array.isArray(state) ? state : [state];
+}
+function sortByRecentActivity(sessions) {
+    return [...sessions].sort((left, right) => {
+        return (Date.parse(right.lastActivityAt) - Date.parse(left.lastActivityAt) ||
+            Date.parse(right.createdAt) - Date.parse(left.createdAt));
+    });
+}
+async function getRequiredSession(adapter, sessionId) {
+    const session = await adapter.fetchById(sessionId);
+    if (!session) {
+        throw new SessionNotFoundError(sessionId);
+    }
+    return session;
+}
+export function createSessionStore(config) {
+    const { adapter } = config;
+    const defaultTtlMs = config.defaultTtlMs ?? DEFAULT_TTL_MS;
+    return {
+        async create(input) {
+            const existing = await adapter.fetchById(input.id);
+            if (existing) {
+                throw new SessionConflictError(input.id);
+            }
+            const timestamp = nowIso();
+            const session = {
+                id: input.id,
+                userId: input.userId,
+                workspaceId: input.workspaceId,
+                state: 'created',
+                createdAt: timestamp,
+                lastActivityAt: timestamp,
+                attachedSurfaces: input.initialSurfaceId ? [input.initialSurfaceId] : [],
+                metadata: { ...(input.metadata ?? {}) },
+            };
+            await adapter.insert(session);
+            return cloneSession(session);
+        },
+        async get(sessionId) {
+            return adapter.fetchById(sessionId);
+        },
+        async find(query) {
+            return adapter.fetchMany({
+                ...query,
+                limit: normalizeLimit(query.limit),
+            });
+        },
+        async touch(sessionId) {
+            const session = await getRequiredSession(adapter, sessionId);
+            if (session.state === 'expired') {
+                throw new SessionStateError(sessionId, session.state, 'touch');
+            }
+            const timestamp = nowIso();
+            const patch = {
+                lastActivityAt: timestamp,
+            };
+            if (session.state === 'created' || session.state === 'suspended') {
+                patch.state = 'active';
+                patch.stateChangedAt = timestamp;
+            }
+            return adapter.update(sessionId, patch);
+        },
+        async attachSurface(sessionId, surfaceId) {
+            const session = await getRequiredSession(adapter, sessionId);
+            if (session.attachedSurfaces.includes(surfaceId)) {
+                return session;
+            }
+            return adapter.update(sessionId, {
+                attachedSurfaces: [...session.attachedSurfaces, surfaceId],
+            });
+        },
+        async detachSurface(sessionId, surfaceId) {
+            const session = await getRequiredSession(adapter, sessionId);
+            if (!session.attachedSurfaces.includes(surfaceId)) {
+                return session;
+            }
+            return adapter.update(sessionId, {
+                attachedSurfaces: session.attachedSurfaces.filter((value) => value !== surfaceId),
+            });
+        },
+        async expire(sessionId) {
+            const session = await getRequiredSession(adapter, sessionId);
+            if (session.state === 'expired') {
+                return session;
+            }
+            return adapter.update(sessionId, {
+                state: 'expired',
+                stateChangedAt: nowIso(),
+            });
+        },
+        async sweepStale(ttlMs) {
+            const effectiveTtlMs = ttlMs ?? defaultTtlMs;
+            const cutoff = Date.now() - effectiveTtlMs;
+            const activeSessions = await adapter.fetchMany({
+                state: 'active',
+                limit: Number.MAX_SAFE_INTEGER,
+            });
+            const staleSessions = activeSessions.filter((session) => {
+                return Date.parse(session.lastActivityAt) < cutoff;
+            });
+            const transitioned = [];
+            for (const session of staleSessions) {
+                transitioned.push(await adapter.update(session.id, {
+                    state: 'suspended',
+                    stateChangedAt: nowIso(),
+                }));
+            }
+            return transitioned;
+        },
+        async updateMetadata(sessionId, metadata) {
+            const session = await getRequiredSession(adapter, sessionId);
+            return adapter.update(sessionId, {
+                metadata: {
+                    ...session.metadata,
+                    ...metadata,
+                },
+            });
+        },
+    };
+}
+export class InMemorySessionStoreAdapter {
+    sessions = new Map();
+    async insert(session) {
+        if (this.sessions.has(session.id)) {
+            throw new SessionConflictError(session.id);
+        }
+        this.sessions.set(session.id, cloneSession(session));
+    }
+    async fetchById(sessionId) {
+        const session = this.sessions.get(sessionId);
+        return session ? cloneSession(session) : null;
+    }
+    async fetchMany(query) {
+        const states = normalizeStateFilter(query.state);
+        const limit = normalizeLimit(query.limit);
+        const matches = [...this.sessions.values()].filter((session) => {
+            if (query.userId && session.userId !== query.userId) {
+                return false;
+            }
+            if (query.workspaceId && session.workspaceId !== query.workspaceId) {
+                return false;
+            }
+            if (states && !states.includes(session.state)) {
+                return false;
+            }
+            if (query.surfaceId && !session.attachedSurfaces.includes(query.surfaceId)) {
+                return false;
+            }
+            if (query.activeAfter && Date.parse(session.lastActivityAt) <= Date.parse(query.activeAfter)) {
+                return false;
+            }
+            return true;
+        });
+        return matches.slice(0, limit).map((session) => cloneSession(session));
+    }
+    async update(sessionId, patch) {
+        const existing = this.sessions.get(sessionId);
+        if (!existing) {
+            throw new SessionNotFoundError(sessionId);
+        }
+        const next = cloneSession({
+            ...existing,
+            ...patch,
+        });
+        this.sessions.set(sessionId, next);
+        return cloneSession(next);
+    }
+    async delete(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+}
+export async function resolveSession(message, store, resolver) {
+    const existing = await resolver.resolve(message.userId, message.surfaceId);
+    if (existing) {
+        return store.touch(existing.id);
+    }
+    return store.create({
+        id: globalThis.crypto.randomUUID(),
+        userId: message.userId,
+        workspaceId: message.workspaceId,
+        initialSurfaceId: message.surfaceId,
+    });
+}
+export function defaultAffinityResolver(store) {
+    return {
+        async resolve(userId, surfaceId) {
+            const sessions = sortByRecentActivity(await store.find({
+                userId,
+                state: ['active', 'suspended'],
+                limit: DEFAULT_FIND_LIMIT,
+            }));
+            if (surfaceId) {
+                const attached = sessions.find((session) => session.attachedSurfaces.includes(surfaceId));
+                if (attached) {
+                    return attached;
+                }
+            }
+            return sessions[0] ?? null;
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+export interface Session {
+    id: string;
+    userId: string;
+    workspaceId?: string;
+    state: SessionState;
+    createdAt: string;
+    lastActivityAt: string;
+    stateChangedAt?: string;
+    attachedSurfaces: string[];
+    metadata: Record<string, unknown>;
+}
+export type SessionState = 'created' | 'active' | 'suspended' | 'expired';
+export interface SessionStore {
+    create(input: CreateSessionInput): Promise<Session>;
+    get(sessionId: string): Promise<Session | null>;
+    find(query: SessionQuery): Promise<Session[]>;
+    touch(sessionId: string): Promise<Session>;
+    attachSurface(sessionId: string, surfaceId: string): Promise<Session>;
+    detachSurface(sessionId: string, surfaceId: string): Promise<Session>;
+    expire(sessionId: string): Promise<Session>;
+    sweepStale(ttlMs: number): Promise<Session[]>;
+    updateMetadata(sessionId: string, metadata: Record<string, unknown>): Promise<Session>;
+}
+export interface CreateSessionInput {
+    id: string;
+    userId: string;
+    workspaceId?: string;
+    initialSurfaceId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SessionQuery {
+    userId?: string;
+    workspaceId?: string;
+    state?: SessionState | SessionState[];
+    surfaceId?: string;
+    activeAfter?: string;
+    limit?: number;
+}
+export interface SessionStoreAdapter {
+    insert(session: Session): Promise<void>;
+    fetchById(sessionId: string): Promise<Session | null>;
+    fetchMany(query: SessionQuery): Promise<Session[]>;
+    update(sessionId: string, patch: Partial<Session>): Promise<Session>;
+    delete(sessionId: string): Promise<void>;
+}
+export interface AffinityResolver {
+    resolve(userId: string, surfaceId?: string): Promise<Session | null>;
+}
+export interface SessionStoreConfig {
+    adapter: SessionStoreAdapter;
+    defaultTtlMs?: number;
+}
+export interface SessionResolvableMessage {
+    userId: string;
+    workspaceId?: string;
+    surfaceId: string;
+}
+export declare class SessionNotFoundError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+export declare class SessionConflictError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+export declare class SessionStateError extends Error {
+    readonly sessionId: string;
+    readonly currentState: SessionState;
+    readonly attemptedTransition: string;
+    constructor(sessionId: string, currentState: SessionState, attemptedTransition: string);
+}

package/dist/types.js

@@ -0,0 +1,28 @@
+export class SessionNotFoundError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`Session not found: ${sessionId}`);
+        this.sessionId = sessionId;
+        this.name = 'SessionNotFoundError';
+    }
+}
+export class SessionConflictError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`Session already exists: ${sessionId}`);
+        this.sessionId = sessionId;
+        this.name = 'SessionConflictError';
+    }
+}
+export class SessionStateError extends Error {
+    sessionId;
+    currentState;
+    attemptedTransition;
+    constructor(sessionId, currentState, attemptedTransition) {
+        super(`Invalid transition '${attemptedTransition}' from state '${currentState}' for session ${sessionId}`);
+        this.sessionId = sessionId;
+        this.currentState = currentState;
+        this.attemptedTransition = attemptedTransition;
+        this.name = 'SessionStateError';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-assistant/sessions",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Session lifecycle, storage, and affinity for Agent Assistant SDK",
   "type": "module",
   "main": "dist/index.js",