@adhdev/session-host-core 0.7.12

package/src/index.ts

@@ -0,0 +1,49 @@
+export type {
+  AcquireWritePayload,
+  AttachSessionPayload,
+  ClearSessionBufferPayload,
+  CreateSessionPayload,
+  DetachSessionPayload,
+  GetSnapshotPayload,
+  ReleaseWritePayload,
+  ResumeSessionPayload,
+  ResizeSessionPayload,
+  SendInputPayload,
+  SessionAttachedClient,
+  SessionBufferSnapshot,
+  SessionClientType,
+  SessionHostCategory,
+  SessionHostEvent,
+  SessionHostEventEnvelope,
+  SessionHostRecord,
+  SessionHostRequest,
+  SessionHostRequestEnvelope,
+  SessionHostResponse,
+  SessionHostResponseEnvelope,
+  SessionLaunchCommand,
+  SessionLifecycle,
+  SessionOwnerType,
+  SessionTransport,
+  SessionHostWireEnvelope,
+  SessionWriteOwner,
+  StopSessionPayload,
+} from './types.js';
+
+export { SessionRingBuffer } from './buffer.js';
+export type { SessionRingBufferOptions } from './buffer.js';
+export { SessionHostRegistry } from './registry.js';
+export {
+  buildRuntimeDisplayName,
+  buildRuntimeKey,
+  formatRuntimeOwner,
+  getWorkspaceLabel,
+  resolveRuntimeRecord,
+} from './runtime-labels.js';
+export {
+  SessionHostClient,
+  createLineParser,
+  createResponseEnvelope,
+  getDefaultSessionHostEndpoint,
+  writeEnvelope,
+} from './ipc.js';
+export type { SessionHostClientOptions, SessionHostEndpoint } from './ipc.js';

package/src/ipc.ts

@@ -0,0 +1,164 @@
+import * as os from 'os';
+import * as path from 'path';
+import * as net from 'net';
+import { randomUUID } from 'crypto';
+import type {
+  SessionHostEvent,
+  SessionHostRequest,
+  SessionHostRequestEnvelope,
+  SessionHostResponse,
+  SessionHostResponseEnvelope,
+  SessionHostWireEnvelope,
+} from './types.js';
+
+export interface SessionHostEndpoint {
+  kind: 'unix' | 'pipe';
+  path: string;
+}
+
+export function getDefaultSessionHostEndpoint(appName = 'adhdev'): SessionHostEndpoint {
+  if (process.platform === 'win32') {
+    return {
+      kind: 'pipe',
+      path: `\\\\.\\pipe\\${appName}-session-host`,
+    };
+  }
+
+  return {
+    kind: 'unix',
+    path: path.join(os.tmpdir(), `${appName}-session-host.sock`),
+  };
+}
+
+function serializeEnvelope(envelope: SessionHostWireEnvelope): string {
+  return `${JSON.stringify(envelope)}\n`;
+}
+
+function createLineParser(onEnvelope: (envelope: SessionHostWireEnvelope) => void) {
+  let buffer = '';
+  return (chunk: Buffer | string) => {
+    buffer += chunk.toString();
+    let newlineIndex = buffer.indexOf('\n');
+    while (newlineIndex >= 0) {
+      const rawLine = buffer.slice(0, newlineIndex).trim();
+      buffer = buffer.slice(newlineIndex + 1);
+      if (rawLine) {
+        onEnvelope(JSON.parse(rawLine) as SessionHostWireEnvelope);
+      }
+      newlineIndex = buffer.indexOf('\n');
+    }
+  };
+}
+
+export interface SessionHostClientOptions {
+  endpoint?: SessionHostEndpoint;
+  appName?: string;
+}
+
+export class SessionHostClient {
+  readonly endpoint: SessionHostEndpoint;
+
+  private socket: net.Socket | null = null;
+  private requestWaiters = new Map<string, { resolve: (value: SessionHostResponse) => void; reject: (error: Error) => void }>();
+  private eventListeners = new Set<(event: SessionHostEvent) => void>();
+
+  constructor(options: SessionHostClientOptions = {}) {
+    this.endpoint = options.endpoint || getDefaultSessionHostEndpoint(options.appName || 'adhdev');
+  }
+
+  async connect(): Promise<void> {
+    if (this.socket && !this.socket.destroyed) return;
+
+    const socket = net.createConnection(this.endpoint.path);
+    this.socket = socket;
+
+    socket.on('data', createLineParser((envelope) => {
+      if (envelope.kind === 'response') {
+        const waiter = this.requestWaiters.get(envelope.requestId);
+        if (waiter) {
+          this.requestWaiters.delete(envelope.requestId);
+          waiter.resolve(envelope.response);
+        }
+        return;
+      }
+
+      if (envelope.kind === 'event') {
+        for (const listener of this.eventListeners) listener(envelope.event);
+      }
+    }));
+
+    socket.on('error', (error) => {
+      for (const waiter of this.requestWaiters.values()) {
+        waiter.reject(error);
+      }
+      this.requestWaiters.clear();
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      socket.once('connect', () => resolve());
+      socket.once('error', reject);
+    });
+  }
+
+  onEvent(listener: (event: SessionHostEvent) => void): () => void {
+    this.eventListeners.add(listener);
+    return () => {
+      this.eventListeners.delete(listener);
+    };
+  }
+
+  async request<T = unknown>(request: SessionHostRequest): Promise<SessionHostResponse<T>> {
+    await this.connect();
+    if (!this.socket) throw new Error('Session host socket unavailable');
+
+    const requestId = randomUUID();
+    const envelope: SessionHostRequestEnvelope = {
+      kind: 'request',
+      requestId,
+      request,
+    };
+
+    const response = await new Promise<SessionHostResponse>((resolve, reject) => {
+      this.requestWaiters.set(requestId, { resolve, reject });
+      this.socket?.write(serializeEnvelope(envelope));
+    });
+
+    return response as SessionHostResponse<T>;
+  }
+
+  async close(): Promise<void> {
+    if (!this.socket) return;
+    const socket = this.socket;
+    this.socket = null;
+    for (const waiter of this.requestWaiters.values()) {
+      waiter.reject(new Error('Session host client closed'));
+    }
+    this.requestWaiters.clear();
+    await new Promise<void>((resolve) => {
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        resolve();
+      };
+      socket.once('close', done);
+      socket.end();
+      socket.destroy();
+      setTimeout(done, 50);
+    });
+  }
+}
+
+export function createResponseEnvelope(requestId: string, response: SessionHostResponse): SessionHostResponseEnvelope {
+  return {
+    kind: 'response',
+    requestId,
+    response,
+  };
+}
+
+export function writeEnvelope(socket: Pick<net.Socket, 'write'>, envelope: SessionHostWireEnvelope): void {
+  socket.write(serializeEnvelope(envelope));
+}
+
+export { createLineParser };

package/src/registry.ts

@@ -0,0 +1,252 @@
+import { randomUUID } from 'crypto';
+import type {
+  AcquireWritePayload,
+  AttachSessionPayload,
+  CreateSessionPayload,
+  DetachSessionPayload,
+  ReleaseWritePayload,
+  SessionAttachedClient,
+  SessionHostRecord,
+} from './types.js';
+import { SessionRingBuffer } from './buffer.js';
+import { buildRuntimeDisplayName, buildRuntimeKey, getWorkspaceLabel } from './runtime-labels.js';
+
+interface SessionRuntimeState {
+  record: SessionHostRecord;
+  buffer: SessionRingBuffer;
+}
+
+export class SessionHostRegistry {
+  private sessions = new Map<string, SessionRuntimeState>();
+
+  createSession(payload: CreateSessionPayload): SessionHostRecord {
+    const sessionId = payload.sessionId || randomUUID();
+    if (this.sessions.has(sessionId)) {
+      throw new Error(`Session already exists: ${sessionId}`);
+    }
+    const now = Date.now();
+    const initialClient = payload.clientId
+      ? [{
+          clientId: payload.clientId,
+          type: payload.clientType || 'daemon',
+          readOnly: false,
+          attachedAt: now,
+          lastSeenAt: now,
+        } satisfies SessionAttachedClient]
+      : [];
+
+    const record: SessionHostRecord = {
+      sessionId,
+      runtimeKey: buildRuntimeKey(
+        payload,
+        Array.from(this.sessions.values(), (state) => state.record.runtimeKey),
+      ),
+      displayName: buildRuntimeDisplayName(payload),
+      workspaceLabel: getWorkspaceLabel(payload.workspace),
+      transport: 'pty',
+      providerType: payload.providerType,
+      category: payload.category,
+      workspace: payload.workspace,
+      launchCommand: payload.launchCommand,
+      createdAt: now,
+      lastActivityAt: now,
+      lifecycle: 'starting',
+      writeOwner: null,
+      attachedClients: initialClient,
+      buffer: {
+        scrollbackBytes: 0,
+        snapshotSeq: 0,
+      },
+      meta: payload.meta || {},
+    };
+
+    record.meta = {
+      sessionHostCols: payload.cols || 120,
+      sessionHostRows: payload.rows || 40,
+      ...record.meta,
+    };
+
+    this.sessions.set(sessionId, {
+      record,
+      buffer: new SessionRingBuffer(),
+    });
+
+    return this.cloneRecord(record);
+  }
+
+  restoreSession(record: SessionHostRecord, snapshot?: { seq: number; text: string } | null): SessionHostRecord {
+    const cloned = this.cloneRecord(record);
+    this.sessions.set(cloned.sessionId, {
+      record: cloned,
+      buffer: (() => {
+        const buffer = new SessionRingBuffer();
+        if (snapshot) buffer.restore(snapshot);
+        return buffer;
+      })(),
+    });
+    return this.cloneRecord(cloned);
+  }
+
+  listSessions(): SessionHostRecord[] {
+    return Array.from(this.sessions.values())
+      .map(state => this.cloneRecord(state.record))
+      .sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+  }
+
+  getSession(sessionId: string): SessionHostRecord | null {
+    const state = this.sessions.get(sessionId);
+    return state ? this.cloneRecord(state.record) : null;
+  }
+
+  attachClient(payload: AttachSessionPayload): SessionHostRecord {
+    const state = this.requireSession(payload.sessionId);
+    const now = Date.now();
+    let removedDaemonOwner = false;
+
+    if (payload.clientType === 'daemon') {
+      const staleDaemonClientIds = state.record.attachedClients
+        .filter(client => client.type === 'daemon' && client.clientId !== payload.clientId)
+        .map(client => client.clientId);
+      if (staleDaemonClientIds.length > 0) {
+        state.record.attachedClients = state.record.attachedClients.filter(
+          client => !(client.type === 'daemon' && client.clientId !== payload.clientId),
+        );
+        if (state.record.writeOwner && staleDaemonClientIds.includes(state.record.writeOwner.clientId)) {
+          removedDaemonOwner = true;
+        }
+      }
+    }
+
+    const existing = state.record.attachedClients.find(client => client.clientId === payload.clientId);
+
+    if (existing) {
+      existing.type = payload.clientType;
+      existing.readOnly = !!payload.readOnly;
+      existing.lastSeenAt = now;
+    } else {
+      state.record.attachedClients.push({
+        clientId: payload.clientId,
+        type: payload.clientType,
+        readOnly: !!payload.readOnly,
+        attachedAt: now,
+        lastSeenAt: now,
+      });
+    }
+
+    if (removedDaemonOwner) {
+      state.record.writeOwner = null;
+    }
+
+    state.record.lastActivityAt = now;
+    return this.cloneRecord(state.record);
+  }
+
+  detachClient(payload: DetachSessionPayload): SessionHostRecord {
+    const state = this.requireSession(payload.sessionId);
+    state.record.attachedClients = state.record.attachedClients.filter(client => client.clientId !== payload.clientId);
+    if (state.record.writeOwner?.clientId === payload.clientId) {
+      state.record.writeOwner = null;
+    }
+    state.record.lastActivityAt = Date.now();
+    return this.cloneRecord(state.record);
+  }
+
+  acquireWrite(payload: AcquireWritePayload): SessionHostRecord {
+    const state = this.requireSession(payload.sessionId);
+    if (state.record.writeOwner && state.record.writeOwner.clientId !== payload.clientId && !payload.force) {
+      throw new Error(`Write owned by ${state.record.writeOwner.clientId}`);
+    }
+    const attachedClient = state.record.attachedClients.find(client => client.clientId === payload.clientId);
+    if (attachedClient) {
+      attachedClient.readOnly = false;
+      attachedClient.lastSeenAt = Date.now();
+    }
+    state.record.writeOwner = {
+      clientId: payload.clientId,
+      ownerType: payload.ownerType,
+      acquiredAt: Date.now(),
+    };
+    state.record.lastActivityAt = Date.now();
+    return this.cloneRecord(state.record);
+  }
+
+  releaseWrite(payload: ReleaseWritePayload): SessionHostRecord {
+    const state = this.requireSession(payload.sessionId);
+    const attachedClient = state.record.attachedClients.find(client => client.clientId === payload.clientId);
+    if (attachedClient) {
+      attachedClient.readOnly = false;
+      attachedClient.lastSeenAt = Date.now();
+    }
+    if (state.record.writeOwner?.clientId === payload.clientId) {
+      state.record.writeOwner = null;
+    }
+    state.record.lastActivityAt = Date.now();
+    return this.cloneRecord(state.record);
+  }
+
+  appendOutput(sessionId: string, data: string): { record: SessionHostRecord; seq: number } {
+    const state = this.requireSession(sessionId);
+    const seq = state.buffer.append(data);
+    state.record.buffer = state.buffer.getState();
+    state.record.lastActivityAt = Date.now();
+    return { record: this.cloneRecord(state.record), seq };
+  }
+
+  getSnapshot(sessionId: string, sinceSeq?: number) {
+    const state = this.requireSession(sessionId);
+    state.record.buffer = state.buffer.getState();
+    return state.buffer.snapshot(sinceSeq);
+  }
+
+  clearBuffer(sessionId: string): SessionHostRecord {
+    const state = this.requireSession(sessionId);
+    state.buffer.clear();
+    state.record.buffer = state.buffer.getState();
+    state.record.lastActivityAt = Date.now();
+    return this.cloneRecord(state.record);
+  }
+
+  markStarted(sessionId: string, pid?: number): SessionHostRecord {
+    const state = this.requireSession(sessionId);
+    state.record.lifecycle = 'running';
+    state.record.startedAt = state.record.startedAt || Date.now();
+    if (typeof pid === 'number') state.record.osPid = pid;
+    state.record.lastActivityAt = Date.now();
+    return this.cloneRecord(state.record);
+  }
+
+  markStopped(sessionId: string, lifecycle: 'stopped' | 'failed' = 'stopped'): SessionHostRecord {
+    const state = this.requireSession(sessionId);
+    state.record.lifecycle = lifecycle;
+    state.record.lastActivityAt = Date.now();
+    return this.cloneRecord(state.record);
+  }
+
+  setLifecycle(sessionId: string, lifecycle: 'starting' | 'running' | 'stopping' | 'stopped' | 'failed' | 'interrupted'): SessionHostRecord {
+    const state = this.requireSession(sessionId);
+    state.record.lifecycle = lifecycle;
+    state.record.lastActivityAt = Date.now();
+    return this.cloneRecord(state.record);
+  }
+
+  private requireSession(sessionId: string): SessionRuntimeState {
+    const state = this.sessions.get(sessionId);
+    if (!state) throw new Error(`Unknown session: ${sessionId}`);
+    return state;
+  }
+
+  private cloneRecord(record: SessionHostRecord): SessionHostRecord {
+    return {
+      ...record,
+      launchCommand: {
+        ...record.launchCommand,
+        args: [...record.launchCommand.args],
+        env: record.launchCommand.env ? { ...record.launchCommand.env } : undefined,
+      },
+      writeOwner: record.writeOwner ? { ...record.writeOwner } : null,
+      attachedClients: record.attachedClients.map(client => ({ ...client })),
+      buffer: { ...record.buffer },
+      meta: { ...record.meta },
+    };
+  }
+}

package/src/runtime-labels.ts

@@ -0,0 +1,85 @@
+import * as path from 'path';
+import type { CreateSessionPayload, SessionHostRecord } from './types.js';
+
+function normalizeSlug(input: string): string {
+  return input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48);
+}
+
+function normalizeValue(input: string): string {
+  return input.trim().toLowerCase();
+}
+
+export function getWorkspaceLabel(workspace: string): string {
+  const trimmed = workspace.trim();
+  if (!trimmed) return 'workspace';
+  const normalized = trimmed.replace(/[\\/]+$/, '');
+  const base = path.basename(normalized);
+  return base || normalized;
+}
+
+export function buildRuntimeDisplayName(payload: Pick<CreateSessionPayload, 'displayName' | 'providerType' | 'workspace'>): string {
+  const explicit = payload.displayName?.trim();
+  if (explicit) return explicit;
+  const workspaceLabel = getWorkspaceLabel(payload.workspace);
+  const providerLabel = payload.providerType.trim() || 'runtime';
+  return `${providerLabel} @ ${workspaceLabel}`;
+}
+
+export function buildRuntimeKey(
+  payload: Pick<CreateSessionPayload, 'runtimeKey' | 'displayName' | 'providerType' | 'workspace'>,
+  existingKeys: Iterable<string>,
+): string {
+  const requested = payload.runtimeKey?.trim();
+  const existing = new Set(Array.from(existingKeys, (key) => key.toLowerCase()));
+  const displayName = buildRuntimeDisplayName(payload);
+  const baseKey = normalizeSlug(requested || displayName || getWorkspaceLabel(payload.workspace) || payload.providerType || 'runtime') || 'runtime';
+  if (!existing.has(baseKey)) return baseKey;
+
+  let suffix = 2;
+  let candidate = `${baseKey}-${suffix}`;
+  while (existing.has(candidate)) {
+    suffix += 1;
+    candidate = `${baseKey}-${suffix}`;
+  }
+  return candidate;
+}
+
+function uniqueMatch(records: SessionHostRecord[], predicate: (record: SessionHostRecord) => boolean): SessionHostRecord | null {
+  const matches = records.filter(predicate);
+  if (matches.length === 1) return matches[0] || null;
+  if (matches.length === 0) return null;
+  const labels = matches.map((record) => `${record.runtimeKey} (${record.sessionId})`).join(', ');
+  throw new Error(`Ambiguous runtime target. Matches: ${labels}`);
+}
+
+export function resolveRuntimeRecord(records: SessionHostRecord[], identifier: string): SessionHostRecord {
+  const target = identifier.trim();
+  if (!target) {
+    throw new Error('Runtime target is required');
+  }
+
+  const exact = uniqueMatch(records, (record) =>
+    record.sessionId === target ||
+    normalizeValue(record.runtimeKey) === normalizeValue(target) ||
+    normalizeValue(record.displayName) === normalizeValue(target),
+  );
+  if (exact) return exact;
+
+  const prefix = uniqueMatch(records, (record) =>
+    record.sessionId.startsWith(target) ||
+    normalizeValue(record.runtimeKey).startsWith(normalizeValue(target)),
+  );
+  if (prefix) return prefix;
+
+  throw new Error(`Unknown runtime target: ${target}`);
+}
+
+export function formatRuntimeOwner(record: Pick<SessionHostRecord, 'writeOwner'>): string {
+  if (!record.writeOwner) return 'none';
+  return `${record.writeOwner.ownerType}:${record.writeOwner.clientId}`;
+}