adhdev 0.8.50 → 0.8.52

package/vendor/terminal-mux-cli/node_modules/@adhdev/session-host-core/index.d.mts

@@ -0,0 +1,427 @@
+import * as net from 'net';
+
+type SessionTransport = 'pty';
+type SessionHostCategory = 'cli' | 'acp' | 'shell';
+type SessionLifecycle = 'starting' | 'running' | 'stopping' | 'stopped' | 'failed' | 'interrupted';
+type SessionClientType = 'daemon' | 'web' | 'local-terminal';
+type SessionOwnerType = 'agent' | 'user';
+interface SessionLaunchCommand {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+interface SessionWriteOwner {
+    clientId: string;
+    ownerType: SessionOwnerType;
+    acquiredAt: number;
+}
+interface SessionAttachedClient {
+    clientId: string;
+    type: SessionClientType;
+    readOnly: boolean;
+    attachedAt: number;
+    lastSeenAt: number;
+}
+interface SessionBufferSnapshot {
+    seq: number;
+    text: string;
+    truncated: boolean;
+    cols?: number;
+    rows?: number;
+}
+interface SessionBufferState {
+    scrollbackBytes: number;
+    snapshotSeq: number;
+}
+interface SessionHostRecord {
+    sessionId: string;
+    runtimeKey: string;
+    displayName: string;
+    workspaceLabel: string;
+    transport: SessionTransport;
+    providerType: string;
+    category: SessionHostCategory;
+    workspace: string;
+    launchCommand: SessionLaunchCommand;
+    osPid?: number;
+    createdAt: number;
+    startedAt?: number;
+    lastActivityAt: number;
+    lifecycle: SessionLifecycle;
+    writeOwner: SessionWriteOwner | null;
+    attachedClients: SessionAttachedClient[];
+    buffer: SessionBufferState;
+    meta: Record<string, unknown>;
+}
+interface CreateSessionPayload {
+    sessionId?: string;
+    runtimeKey?: string;
+    displayName?: string;
+    providerType: string;
+    category: SessionHostCategory;
+    workspace: string;
+    launchCommand: SessionLaunchCommand;
+    cols?: number;
+    rows?: number;
+    clientId?: string;
+    clientType?: SessionClientType;
+    meta?: Record<string, unknown>;
+}
+interface AttachSessionPayload {
+    sessionId: string;
+    clientId: string;
+    clientType: SessionClientType;
+    readOnly?: boolean;
+}
+interface DetachSessionPayload {
+    sessionId: string;
+    clientId: string;
+}
+interface SendInputPayload {
+    sessionId: string;
+    clientId: string;
+    data: string;
+}
+interface ResizeSessionPayload {
+    sessionId: string;
+    cols: number;
+    rows: number;
+}
+interface StopSessionPayload {
+    sessionId: string;
+}
+interface ResumeSessionPayload {
+    sessionId: string;
+}
+interface AcquireWritePayload {
+    sessionId: string;
+    clientId: string;
+    ownerType: SessionOwnerType;
+    force?: boolean;
+}
+interface ReleaseWritePayload {
+    sessionId: string;
+    clientId: string;
+}
+interface GetSnapshotPayload {
+    sessionId: string;
+    sinceSeq?: number;
+}
+interface ClearSessionBufferPayload {
+    sessionId: string;
+}
+interface UpdateSessionMetaPayload {
+    sessionId: string;
+    meta: Record<string, unknown>;
+    replace?: boolean;
+}
+interface GetHostDiagnosticsPayload {
+    includeSessions?: boolean;
+    limit?: number;
+}
+interface ForceDetachClientPayload {
+    sessionId: string;
+    clientId: string;
+}
+interface SendSignalPayload {
+    sessionId: string;
+    signal: string;
+}
+interface RestartSessionPayload {
+    sessionId: string;
+}
+interface PruneDuplicateSessionsPayload {
+    providerType?: string;
+    workspace?: string;
+    dryRun?: boolean;
+}
+interface SessionHostDuplicateSessionGroup {
+    bindingKey: string;
+    providerType: string;
+    workspace: string;
+    providerSessionId: string;
+    keptSessionId: string;
+    prunedSessionIds: string[];
+}
+interface SessionHostPruneDuplicatesResult {
+    duplicateGroupCount: number;
+    keptSessionIds: string[];
+    prunedSessionIds: string[];
+    groups: SessionHostDuplicateSessionGroup[];
+}
+interface SessionHostLogEntry {
+    timestamp: number;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    sessionId?: string;
+    data?: Record<string, unknown>;
+}
+interface SessionHostRequestTrace {
+    timestamp: number;
+    requestId: string;
+    type: SessionHostRequest['type'];
+    sessionId?: string;
+    clientId?: string;
+    success: boolean;
+    durationMs: number;
+    error?: string;
+}
+interface SessionHostRuntimeTransition {
+    timestamp: number;
+    sessionId: string;
+    action: string;
+    lifecycle?: SessionLifecycle;
+    detail?: string;
+    success?: boolean;
+    error?: string;
+}
+interface SessionHostDiagnostics {
+    hostStartedAt: number;
+    endpoint: string;
+    runtimeCount: number;
+    sessions?: SessionHostRecord[];
+    recentLogs: SessionHostLogEntry[];
+    recentRequests: SessionHostRequestTrace[];
+    recentTransitions: SessionHostRuntimeTransition[];
+}
+type SessionHostRequest = {
+    type: 'create_session';
+    payload: CreateSessionPayload;
+} | {
+    type: 'attach_session';
+    payload: AttachSessionPayload;
+} | {
+    type: 'detach_session';
+    payload: DetachSessionPayload;
+} | {
+    type: 'send_input';
+    payload: SendInputPayload;
+} | {
+    type: 'resize_session';
+    payload: ResizeSessionPayload;
+} | {
+    type: 'stop_session';
+    payload: StopSessionPayload;
+} | {
+    type: 'resume_session';
+    payload: ResumeSessionPayload;
+} | {
+    type: 'acquire_write';
+    payload: AcquireWritePayload;
+} | {
+    type: 'release_write';
+    payload: ReleaseWritePayload;
+} | {
+    type: 'get_snapshot';
+    payload: GetSnapshotPayload;
+} | {
+    type: 'clear_session_buffer';
+    payload: ClearSessionBufferPayload;
+} | {
+    type: 'update_session_meta';
+    payload: UpdateSessionMetaPayload;
+} | {
+    type: 'get_host_diagnostics';
+    payload?: GetHostDiagnosticsPayload;
+} | {
+    type: 'force_detach_client';
+    payload: ForceDetachClientPayload;
+} | {
+    type: 'send_signal';
+    payload: SendSignalPayload;
+} | {
+    type: 'restart_session';
+    payload: RestartSessionPayload;
+} | {
+    type: 'prune_duplicate_sessions';
+    payload?: PruneDuplicateSessionsPayload;
+} | {
+    type: 'list_sessions';
+    payload?: {};
+};
+interface SessionHostResponse<T = unknown> {
+    success: boolean;
+    result?: T;
+    error?: string;
+}
+type SessionHostEvent = {
+    type: 'session_created';
+    sessionId: string;
+    record: SessionHostRecord;
+} | {
+    type: 'session_started';
+    sessionId: string;
+    pid?: number;
+} | {
+    type: 'session_resumed';
+    sessionId: string;
+    pid?: number;
+} | {
+    type: 'session_output';
+    sessionId: string;
+    seq: number;
+    data: string;
+} | {
+    type: 'session_cleared';
+    sessionId: string;
+} | {
+    type: 'session_exit';
+    sessionId: string;
+    exitCode: number | null;
+} | {
+    type: 'session_stopped';
+    sessionId: string;
+} | {
+    type: 'session_resized';
+    sessionId: string;
+    cols: number;
+    rows: number;
+} | {
+    type: 'write_owner_changed';
+    sessionId: string;
+    owner: SessionWriteOwner | null;
+} | {
+    type: 'client_attached';
+    sessionId: string;
+    client: SessionAttachedClient;
+} | {
+    type: 'client_detached';
+    sessionId: string;
+    clientId: string;
+} | {
+    type: 'host_log';
+    entry: SessionHostLogEntry;
+} | {
+    type: 'request_trace';
+    trace: SessionHostRequestTrace;
+} | {
+    type: 'runtime_transition';
+    transition: SessionHostRuntimeTransition;
+};
+interface SessionHostRequestEnvelope {
+    kind: 'request';
+    requestId: string;
+    request: SessionHostRequest;
+}
+interface SessionHostResponseEnvelope {
+    kind: 'response';
+    requestId: string;
+    response: SessionHostResponse;
+}
+interface SessionHostEventEnvelope {
+    kind: 'event';
+    event: SessionHostEvent;
+}
+type SessionHostWireEnvelope = SessionHostRequestEnvelope | SessionHostResponseEnvelope | SessionHostEventEnvelope;
+
+interface SessionRingBufferOptions {
+    maxBytes?: number;
+}
+declare class SessionRingBuffer {
+    private maxBytes;
+    private chunks;
+    private nextSeq;
+    private totalBytes;
+    constructor(options?: SessionRingBufferOptions);
+    append(data: string): number;
+    snapshot(sinceSeq?: number): SessionBufferSnapshot;
+    getState(): {
+        scrollbackBytes: number;
+        snapshotSeq: number;
+    };
+    clear(): void;
+    restore(snapshot: {
+        seq: number;
+        text: string;
+    }): void;
+    private trim;
+}
+
+declare class SessionHostRegistry {
+    private sessions;
+    createSession(payload: CreateSessionPayload): SessionHostRecord;
+    restoreSession(record: SessionHostRecord, snapshot?: {
+        seq: number;
+        text: string;
+    } | null): SessionHostRecord;
+    listSessions(): SessionHostRecord[];
+    getSession(sessionId: string): SessionHostRecord | null;
+    attachClient(payload: AttachSessionPayload): SessionHostRecord;
+    detachClient(payload: DetachSessionPayload): SessionHostRecord;
+    acquireWrite(payload: AcquireWritePayload): SessionHostRecord;
+    releaseWrite(payload: ReleaseWritePayload): SessionHostRecord;
+    appendOutput(sessionId: string, data: string): {
+        record: SessionHostRecord;
+        seq: number;
+    };
+    getSnapshot(sessionId: string, sinceSeq?: number): SessionBufferSnapshot;
+    clearBuffer(sessionId: string): SessionHostRecord;
+    updateSessionMeta(sessionId: string, meta: Record<string, unknown>, replace?: boolean): SessionHostRecord;
+    markStarted(sessionId: string, pid?: number): SessionHostRecord;
+    markStopped(sessionId: string, lifecycle?: 'stopped' | 'failed'): SessionHostRecord;
+    setLifecycle(sessionId: string, lifecycle: 'starting' | 'running' | 'stopping' | 'stopped' | 'failed' | 'interrupted'): SessionHostRecord;
+    deleteSession(sessionId: string): boolean;
+    private requireSession;
+    private cloneRecord;
+}
+
+declare function getWorkspaceLabel(workspace: string): string;
+declare function buildRuntimeDisplayName(payload: Pick<CreateSessionPayload, 'displayName' | 'providerType' | 'workspace'>): string;
+declare function buildRuntimeKey(payload: Pick<CreateSessionPayload, 'runtimeKey' | 'displayName' | 'providerType' | 'workspace'>, existingKeys: Iterable<string>): string;
+declare function resolveRuntimeRecord(records: SessionHostRecord[], identifier: string): SessionHostRecord;
+declare function formatRuntimeOwner(record: Pick<SessionHostRecord, 'writeOwner'>): string;
+
+interface SessionHostEndpoint {
+    kind: 'unix' | 'pipe';
+    path: string;
+}
+declare function getDefaultSessionHostEndpoint(appName?: string): SessionHostEndpoint;
+declare function createLineParser(onEnvelope: (envelope: SessionHostWireEnvelope) => void): (chunk: Buffer | string) => void;
+interface SessionHostClientOptions {
+    endpoint?: SessionHostEndpoint;
+    appName?: string;
+}
+declare class SessionHostClient {
+    readonly endpoint: SessionHostEndpoint;
+    private socket;
+    private requestWaiters;
+    private eventListeners;
+    constructor(options?: SessionHostClientOptions);
+    connect(): Promise<void>;
+    onEvent(listener: (event: SessionHostEvent) => void): () => void;
+    request<T = unknown>(request: SessionHostRequest): Promise<SessionHostResponse<T>>;
+    close(): Promise<void>;
+}
+declare function createResponseEnvelope(requestId: string, response: SessionHostResponse): SessionHostResponseEnvelope;
+declare function writeEnvelope(socket: Pick<net.Socket, 'write'>, envelope: SessionHostWireEnvelope): void;
+
+/**
+ * Shared PTY spawn environment utilities.
+ *
+ * Centralises npm/pnpm/yarn env variable stripping, terminal colour env
+ * injection, and node-pty spawn-helper permission fixing.
+ *
+ * Used by daemon-core (provider-cli-adapter), session-host-daemon (runtime),
+ * and daemon-cloud (session-host).
+ */
+/**
+ * Strip package-manager injected environment variables that can interfere
+ * with child CLI processes and apply terminal colour defaults.
+ */
+declare function sanitizeSpawnEnv(baseEnv: NodeJS.ProcessEnv, overrides?: Record<string, string>): Record<string, string>;
+/**
+ * Apply preferred terminal colour environment variables.
+ * Ensures TERM is set to xterm-256color and enables colour on Windows.
+ */
+declare function applyTerminalColorEnv(env: Record<string, string>): void;
+/**
+ * Ensure node-pty's spawn-helper binary has execute permissions.
+ *
+ * npm's default umask can strip +x from the prebuilt spawn-helper on macOS/Linux,
+ * causing EACCES when node-pty tries to fork. Best-effort fix.
+ *
+ * @param logFn Optional log callback for reporting the fix.
+ */
+declare function ensureNodePtySpawnHelperPermissions(logFn?: (msg: string) => void): void;
+
+export { type AcquireWritePayload, type AttachSessionPayload, type ClearSessionBufferPayload, type CreateSessionPayload, type DetachSessionPayload, type ForceDetachClientPayload, type GetHostDiagnosticsPayload, type GetSnapshotPayload, type PruneDuplicateSessionsPayload, type ReleaseWritePayload, type ResizeSessionPayload, type RestartSessionPayload, type ResumeSessionPayload, type SendInputPayload, type SendSignalPayload, type SessionAttachedClient, type SessionBufferSnapshot, type SessionClientType, type SessionHostCategory, SessionHostClient, type SessionHostClientOptions, type SessionHostDiagnostics, type SessionHostDuplicateSessionGroup, type SessionHostEndpoint, type SessionHostEvent, type SessionHostEventEnvelope, type SessionHostLogEntry, type SessionHostPruneDuplicatesResult, type SessionHostRecord, SessionHostRegistry, type SessionHostRequest, type SessionHostRequestEnvelope, type SessionHostRequestTrace, type SessionHostResponse, type SessionHostResponseEnvelope, type SessionHostRuntimeTransition, type SessionHostWireEnvelope, type SessionLaunchCommand, type SessionLifecycle, type SessionOwnerType, SessionRingBuffer, type SessionRingBufferOptions, type SessionTransport, type SessionWriteOwner, type StopSessionPayload, type UpdateSessionMetaPayload, applyTerminalColorEnv, buildRuntimeDisplayName, buildRuntimeKey, createLineParser, createResponseEnvelope, ensureNodePtySpawnHelperPermissions, formatRuntimeOwner, getDefaultSessionHostEndpoint, getWorkspaceLabel, resolveRuntimeRecord, sanitizeSpawnEnv, writeEnvelope };