@vibesdotdev/session 1.0.0-rc.1 → 1.0.0-rc.2

package/dist/manager.js

@@ -13,7 +13,7 @@
  */
 import * as z from 'zod/v4';
 import { sha256Hex } from '@vibesdotdev/shared/hashing';
-import { CapabilityError, CaughtFailureSchema, valueFreeFailure } from '@vibesdotdev/kernel';
+import { CapabilityError, CaughtFailureSchema, settle, valueFreeFailure } from '@vibesdotdev/kernel';
 import { getVibesClient } from '@vibesdotdev/kernel/client';
 import { JsonValueSchema as JsonSchema } from '@vibesdotdev/kernel/schemas/json';
 import { getLogger } from '@vibesdotdev/logging';
@@ -21,7 +21,7 @@ import { StorageRecord } from '@vibesdotdev/storage/record';
 import { storageFailureCondition } from '@vibesdotdev/storage/record/failure-condition';
 import { ScratchpadContentTypeSchema } from "./schemas/index.js";
 import { HarnessSeatRegistrationSchema, HarnessSeatSchema, harnessSeatParticipantId, harnessSeatSlug } from "./schemas/harness-seat.js";
-import { ensureSessionContextWithManager, getOrCreateMCPParticipant, resolveParticipantReference } from "./mcp/utils/participant.js";
+import { ensureSessionContextWithManager, getOrCreateMCPParticipant, resolveParticipantReference, sanitizeSlugCandidate, scanParticipantsBySlug } from "./mcp/utils/participant.js";
 import { emitSessionBound } from "./events/session.bound.event.descriptor.js";
 const SESSION_STATE_LEGACY_KEY = 'session-state';
 const SESSION_STATE_DEFAULT_KEY = 'default';
@@ -510,6 +510,10 @@ export class SessionManager {
     }
     async close() {
         await this.persistMappingsTail;
+        // Instances this host kept open stop heartbeating and expire on their TTL.
+        // Closing writes nothing: storage refuses new work while its runtime ends.
+        this.stopInstanceHeartbeat();
+        this.hostedInstances.clear();
         // Storage descriptors handle their own cleanup
         this.initialized = false;
         this.participantSessions.clear();
@@ -596,11 +600,45 @@ export class SessionManager {
     }
     async updateSession(id, updates) {
         await this.ensureStorage();
+        const { parentSessionId, ...rest } = updates;
+        if (parentSessionId !== undefined)
+            await this.setSessionParent(id, parentSessionId);
         await this.sessionsStorage.update(id, {
-            ...updates,
+            ...rest,
             updatedAt: new Date()
         });
     }
+    /**
+     * Place a session under a parent session (a subsession), or make it top
+     * level with `null`. The parent must exist, and may not be the session itself
+     * or any of its descendants: a cycle is refused `INVALID_INPUT
+     * session-parent-cycle`.
+     */
+    async setSessionParent(sessionId, parentSessionId) {
+        await this.ensureStorage();
+        if (parentSessionId !== null) {
+            const seen = new Set();
+            for (let ancestor = parentSessionId; ancestor;) {
+                if (ancestor === sessionId || seen.has(ancestor)) {
+                    throw new CapabilityError('A session cannot be placed under itself or one of its own subsessions.', 'INVALID_INPUT', {
+                        reason: 'session-parent-cycle',
+                        details: { sessionId, parentSessionId }
+                    });
+                }
+                seen.add(ancestor);
+                const node = await this.sessionsStorage.get(ancestor);
+                if (!node && ancestor === parentSessionId) {
+                    throw new CapabilityError('The parent session does not exist.', 'NOT_FOUND', {
+                        reason: 'session-parent-not-found',
+                        details: { parentSessionId }
+                    });
+                }
+                // A dangling ancestor further up ends the chain; only the parent must exist.
+                ancestor = node?.parentSessionId;
+            }
+        }
+        await this.sessionsStorage.update(sessionId, { parentSessionId, updatedAt: new Date() });
+    }
     /**
      * Bump a session's activity clock to reflect real traffic (messages), so
      * `lastActivityAt` tracks when the session was last USED — not merely when its
@@ -1765,6 +1803,328 @@ export class SessionManager {
             disconnectedAt: new Date()
         });
     }
+    // INSTANCES
+    //
+    // One `session.connections` row per running instance, whatever surface it
+    // came through. Live = not disconnected and `expiresAt` in the future. Every
+    // admitted call touches its instance; a host that keeps a seat open while
+    // idle registers it `hosted`, and this manager heartbeats hosted instances
+    // until it closes them. A crashed host's instances simply expire.
+    static INSTANCE_TTL_MS = 10 * 60 * 1000;
+    static INSTANCE_HEARTBEAT_MS = 60 * 1000;
+    /** Touches inside this window are not rewritten: one write per instance per window. */
+    static INSTANCE_TOUCH_MIN_MS = 30 * 1000;
+    static INSTANCE_HANDLE_ATTEMPTS = 6;
+    /** This host's own key: distinguishes its in-process seats from another host's. */
+    hostKey = crypto.randomUUID();
+    hostedInstances = new Set();
+    instanceTouchedAt = new Map();
+    /** Handles of instances this host registered, so a touch need not reread them. */
+    instanceHandles = new Map();
+    /** (instance, session, participant) triples this host has already leased. */
+    instanceMemberships = new Set();
+    instanceHeartbeat;
+    static isLiveInstance(row, nowIso) {
+        const expiresAt = row.expiresAt instanceof Date ? row.expiresAt.toISOString() : row.expiresAt;
+        return !row.disconnectedAt && expiresAt != null && String(expiresAt) >= nowIso;
+    }
+    static randomHandle(base) {
+        const alphabet = 'abcdefghjkmnpqrstuvwxyz23456789';
+        const bytes = crypto.getRandomValues(new Uint8Array(4));
+        const suffix = Array.from(bytes, (byte) => alphabet[byte % alphabet.length]).join('');
+        return `${sanitizeSlugCandidate(base).slice(0, 48)}-${suffix}`;
+    }
+    /**
+     * Register (or re-register) a running instance and give it a handle. A
+     * chosen handle held by another LIVE instance is refused `CONFLICT
+     * instance-handle-taken` naming the holder; one held by an expired or closed
+     * instance is reclaimed. With no choice the instance keeps its live handle,
+     * else gets a random `<agent>-<4>` handle. Uniqueness is the storage index
+     * on `activeHandle`, not this check: a lost race is retried (random) or
+     * refused (chosen).
+     */
+    async registerInstance(input) {
+        await this.ensureStorage();
+        const storage = this.connectionsStorage;
+        const now = Date.now();
+        const nowAt = new Date(now);
+        const nowIso = nowAt.toISOString();
+        const expiresAt = new Date(now + SessionManager.INSTANCE_TTL_MS);
+        const existing = await storage.get(input.instanceId);
+        const chosen = input.handle?.trim() ? sanitizeSlugCandidate(input.handle) : undefined;
+        // A live handle resolves ahead of participant slugs, so a chosen handle may
+        // not be another participant's name: that would capture its messages.
+        if (chosen) {
+            const named = (await scanParticipantsBySlug(this, chosen)).match;
+            const actsAs = input.participantId ?? existing?.participantId;
+            if (named && named.participantId !== actsAs) {
+                throw new CapabilityError(`The handle "${chosen}" is another participant's name.`, 'CONFLICT', {
+                    reason: 'instance-handle-names-participant',
+                    details: { handle: chosen, participantId: named.participantId },
+                    recoveryHint: 'Choose a handle that is not an existing participant\'s name.'
+                });
+            }
+        }
+        const kept = existing && SessionManager.isLiveInstance(existing, nowIso) ? existing.activeHandle ?? undefined : undefined;
+        const base = input.agentId ?? input.harness ?? input.clientName;
+        const fields = {
+            participantId: input.participantId ?? existing?.participantId,
+            clientName: input.clientName,
+            clientVersion: input.clientVersion,
+            hostname: input.hostname,
+            platform: input.platform,
+            workingDirectory: input.workingDirectory,
+            transport: input.transport,
+            agentId: input.agentId,
+            harness: input.harness,
+            harnessSessionId: input.harnessSessionId,
+            lastHeartbeatAt: nowAt,
+            expiresAt,
+            disconnectedAt: null
+        };
+        for (let attempt = 0; attempt < SessionManager.INSTANCE_HANDLE_ATTEMPTS; attempt++) {
+            const handle = chosen ?? (attempt === 0 && kept ? kept : SessionManager.randomHandle(base));
+            if (handle !== existing?.activeHandle)
+                await this.releaseExpiredHandle(handle, input.instanceId, nowIso);
+            const row = { ...fields, handle, activeHandle: handle };
+            const written = await settle(() => existing
+                ? storage.update(input.instanceId, row)
+                : storage.create({ connectionId: input.instanceId, connectedAt: nowAt, ...row }));
+            if (written.ok) {
+                if (input.hosted)
+                    this.hostInstance(input.instanceId);
+                this.instanceTouchedAt.set(input.instanceId, now);
+                return { ...existing, connectionId: input.instanceId, connectedAt: existing?.connectedAt ?? nowAt, ...row };
+            }
+            if (!isUniqueConstraintError(written.cause))
+                throw written.cause;
+            if (chosen) {
+                const holder = await this.liveInstanceByHandle(chosen);
+                throw new CapabilityError(`The handle "${chosen}" is held by another live instance.`, 'CONFLICT', {
+                    reason: 'instance-handle-taken',
+                    details: { handle: chosen, holder: holder?.connectionId ?? null, agentId: holder?.agentId ?? null },
+                    recoveryHint: 'Choose another handle, or omit it to be given a random one.'
+                });
+            }
+        }
+        throw new CapabilityError('Could not allocate a unique instance handle.', 'UNAVAILABLE', {
+            reason: 'instance-handle-exhausted'
+        });
+    }
+    /** Free `handle` when its holder is no longer live, so a new instance can take it. */
+    async releaseExpiredHandle(handle, claimant, nowIso) {
+        const held = await this.connectionsStorage.list({
+            where: { activeHandle: handle },
+            limit: 1
+        });
+        const holder = held.items[0];
+        if (!holder || holder.connectionId === claimant)
+            return;
+        if (SessionManager.isLiveInstance(holder, nowIso))
+            return;
+        await this.connectionsStorage.update(holder.connectionId, { activeHandle: null });
+    }
+    /** The live instance holding `handle`, if any. */
+    async liveInstanceByHandle(handle) {
+        await this.ensureStorage();
+        const held = await this.connectionsStorage.list({
+            where: { activeHandle: sanitizeSlugCandidate(handle) },
+            limit: 1
+        });
+        const holder = held.items[0];
+        return holder && SessionManager.isLiveInstance(holder, new Date().toISOString()) ? holder : null;
+    }
+    /**
+     * Mark an instance alive now and renew the membership leases it holds.
+     * Writes at most once per touch window per instance.
+     */
+    async touchInstance(instanceId, options = {}) {
+        const now = Date.now();
+        const last = this.instanceTouchedAt.get(instanceId);
+        if (!options.force && last !== undefined && now - last < SessionManager.INSTANCE_TOUCH_MIN_MS)
+            return true;
+        await this.ensureStorage();
+        const nowAt = new Date(now);
+        const expiresAt = new Date(now + SessionManager.INSTANCE_TTL_MS);
+        const row = await this.connectionsStorage.get(instanceId);
+        if (!row || row.disconnectedAt) {
+            this.forgetInstance(instanceId);
+            return false;
+        }
+        await this.connectionsStorage.update(instanceId, { lastHeartbeatAt: nowAt, expiresAt });
+        this.instanceTouchedAt.set(instanceId, now);
+        for (const lease of await this.unreleasedLeasesOf(instanceId)) {
+            await this.membershipLeasesStorage.update(lease.id, {
+                lastHeartbeatAt: nowAt.toISOString(),
+                expiresAt: expiresAt.toISOString()
+            });
+        }
+        return true;
+    }
+    /**
+     * Keep an admitted caller's instance live: register it the first time this
+     * host sees it (or after it was closed), otherwise touch it.
+     */
+    async ensureInstance(input) {
+        const known = this.instanceHandles.get(input.instanceId);
+        if (known !== undefined && (await this.touchInstance(input.instanceId)))
+            return { handle: known };
+        const row = await this.registerInstance(input);
+        this.instanceHandles.set(input.instanceId, row.activeHandle ?? row.handle ?? '');
+        return { handle: row.activeHandle ?? row.handle ?? undefined };
+    }
+    /**
+     * Make an instance a member of the session it calls with: one lease keyed
+     * on the instance, taken the first time this host sees the pair and renewed
+     * by every touch after. An archived or missing session takes no member.
+     */
+    async ensureInstanceMembership(input) {
+        const key = `${input.instanceId}|${input.sessionId}|${input.participantId}`;
+        if (this.instanceMemberships.has(key))
+            return;
+        const session = await this.getSession(input.sessionId);
+        if (!session || session.status === 'archived')
+            return;
+        await this.acquireMembershipLease({
+            sessionId: input.sessionId,
+            participantId: input.participantId,
+            connectionKey: input.instanceId
+        });
+        this.instanceMemberships.add(key);
+    }
+    /**
+     * Give a live instance the handle it chose. The registry's uniqueness rule
+     * applies: a handle another live instance holds is refused naming its holder.
+     */
+    async chooseInstanceHandle(instanceId, handle) {
+        await this.ensureStorage();
+        const row = await this.connectionsStorage.get(instanceId);
+        if (!row) {
+            throw new CapabilityError('This caller has no registered instance to name.', 'NOT_FOUND', {
+                reason: 'instance-unregistered',
+                details: { instanceId }
+            });
+        }
+        const named = await this.registerInstance({
+            instanceId,
+            handle,
+            transport: row.transport ?? 'unknown',
+            clientName: row.clientName,
+            clientVersion: row.clientVersion,
+            participantId: row.participantId,
+            agentId: row.agentId,
+            harness: row.harness,
+            harnessSessionId: row.harnessSessionId,
+            hosted: this.hostedInstances.has(instanceId)
+        });
+        this.instanceHandles.set(instanceId, named.activeHandle ?? named.handle ?? '');
+        return named;
+    }
+    /** One instance's registry row. */
+    async getInstance(instanceId) {
+        await this.ensureStorage();
+        return this.connectionsStorage.get(instanceId);
+    }
+    /** Record the session an instance is working in (its bind, or its first write). */
+    async setInstanceSession(instanceId, sessionId) {
+        await this.ensureStorage();
+        const row = await this.connectionsStorage.get(instanceId);
+        if (!row || row.sessionId === sessionId)
+            return;
+        await this.connectionsStorage.update(instanceId, { sessionId });
+    }
+    /** The session an instance is working in, while that session is still open. */
+    async instanceSession(instanceId) {
+        await this.ensureStorage();
+        const sessionId = (await this.connectionsStorage.get(instanceId))?.sessionId;
+        if (!sessionId)
+            return undefined;
+        const session = await this.getSession(sessionId);
+        return session && session.status !== 'archived' ? session.id : undefined;
+    }
+    /** Close an instance: it stops being live, frees its handle and releases its leases. */
+    async closeInstance(instanceId) {
+        await this.ensureStorage();
+        this.hostedInstances.delete(instanceId);
+        this.forgetInstance(instanceId);
+        const nowAt = new Date();
+        const row = await this.connectionsStorage.get(instanceId);
+        if (row && !row.disconnectedAt) {
+            await this.connectionsStorage.update(instanceId, { disconnectedAt: nowAt, activeHandle: null });
+        }
+        for (const lease of await this.unreleasedLeasesOf(instanceId)) {
+            await this.membershipLeasesStorage.update(lease.id, {
+                releasedAt: nowAt.toISOString(),
+                activeConnectionKey: null
+            });
+        }
+        if (this.hostedInstances.size === 0)
+            this.stopInstanceHeartbeat();
+    }
+    /** Every live instance in this store: who is here, however they arrived. */
+    async listLiveInstances() {
+        await this.ensureStorage();
+        const nowAt = new Date();
+        const nowIso = nowAt.toISOString();
+        const live = [];
+        const pageSize = 500;
+        for (let offset = 0;; offset += pageSize) {
+            const page = await this.connectionsStorage.list({
+                where: { expiresAt: { gte: nowAt } },
+                orderBy: { connectionId: 'asc' },
+                limit: pageSize,
+                offset
+            });
+            live.push(...page.items.filter((row) => SessionManager.isLiveInstance(row, nowIso)));
+            if (page.items.length < pageSize)
+                return live;
+        }
+    }
+    forgetInstance(instanceId) {
+        this.instanceTouchedAt.delete(instanceId);
+        this.instanceHandles.delete(instanceId);
+        for (const key of Array.from(this.instanceMemberships)) {
+            if (key.startsWith(`${instanceId}|`))
+                this.instanceMemberships.delete(key);
+        }
+    }
+    async unreleasedLeasesOf(instanceId) {
+        const result = await this.membershipLeasesStorage.list({
+            where: {
+                activeConnectionKey: instanceId,
+                releasedAt: { isNull: true }
+            },
+            limit: 500
+        });
+        return result.items;
+    }
+    /**
+     * Heartbeat hosted instances on this runtime's lifecycle interval, so the
+     * kernel stops it at disposal. A finite host (a one-shot command) runs no
+     * interval: its instance lives by activity and closes with the manager.
+     */
+    hostInstance(instanceId) {
+        this.hostedInstances.add(instanceId);
+        if (this.instanceHeartbeat)
+            return;
+        const runtime = this.hostRuntime;
+        if (runtime.declaredScope.lifecycle === 'finite' || runtime.lifecycle.signal.aborted)
+            return;
+        this.instanceHeartbeat = runtime.lifecycle.interval(() => {
+            for (const id of this.hostedInstances) {
+                void settle(() => this.touchInstance(id, { force: true })).then((touched) => {
+                    if (touched.ok)
+                        return;
+                    this.logger.warn('Instance heartbeat failed', { instanceId: id, error: valueFreeFailure(touched.cause) });
+                });
+            }
+        }, SessionManager.INSTANCE_HEARTBEAT_MS);
+    }
+    stopInstanceHeartbeat() {
+        const stop = this.instanceHeartbeat;
+        this.instanceHeartbeat = undefined;
+        stop?.();
+    }
     async getConnectionHistory(participantId, limit) {
         await this.ensureStorage();
         const where = {};