@volter/supercode-terminal 0.2.30

package/index.d.ts

@@ -0,0 +1,195 @@
+import type { TerminalAttachment } from './substrate/tmux-stream.js';
+import type { NativeSessionIdleProof } from './substrate/native-host.js';
+import type { TerminalInputDelivery, TmuxCommand, TmuxWindowSize } from './substrate/tmux.js';
+import type { SessionDescriptor } from '@volter/supercode-harness-sdk';
+
+export type TerminalAttachmentGrant = Readonly<{
+  expiresAt: number;
+  id: string;
+  mode: 'observe' | 'control';
+}>;
+
+export type EmbeddedTerminalAttachmentGrant = TerminalAttachmentGrant & Readonly<{
+  baseUrl: string;
+}>;
+
+export type TerminalSession = Readonly<{
+  activeCommand: string | null;
+  /** Opaque application context association; never a native harness or tmux handle. */
+  contextKey: string | null;
+  cwd: string | null;
+  id: string;
+  label: string;
+  owned: boolean;
+  /** The pane's root process (its shell), for finding what runs beneath it. */
+  rootPid: number | null;
+  size: Readonly<{ columns: number; rows: number }> | null;
+}>;
+
+export type StructuredLaunch = Readonly<{
+  arguments: string[];
+  env: Readonly<Record<string, string>>;
+  program: string;
+}>;
+
+export type TmuxTerminalHostOptions = {
+  allowUnownedControl?: boolean;
+  attachmentTtlMs?: number;
+  contextOption?: string;
+  ownerId?: string;
+  ownerOption?: string;
+  openLocalTerminal?: (launch: StructuredLaunch) => Promise<void>;
+  socket?: string;
+};
+
+export class TmuxTerminalHost {
+  constructor(options?: TmuxTerminalHostOptions);
+  listSessions(): Promise<TerminalSession[]>;
+  createSession(input: {
+    command: TmuxCommand;
+    contextKey?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    name?: string;
+  }): Promise<TerminalSession>;
+  capture(sessionId: string, options?: { lines?: number; preserveEscapes?: boolean }): string;
+  sendInput(
+    sessionId: string,
+    data: string,
+    options?: { deadlineMs?: number; submitMode?: 'retry' | 'single' },
+  ): Promise<TerminalInputDelivery>;
+  /** Persist an opaque application context association on a session owned by this host. */
+  bindContext(sessionId: string, contextKey: string): Promise<TerminalSession>;
+  issueAttachment(sessionId: string, options?: { mode?: 'observe' | 'control' }): TerminalAttachmentGrant;
+  attachSocket(
+    attachmentId: string,
+    socket: unknown,
+    size?: { cols?: number; rows?: number },
+  ): Promise<TerminalAttachment>;
+  localAttachLaunch(sessionId: string): StructuredLaunch;
+  openLocalTerminal(sessionId: string): Promise<void>;
+  closeSession(sessionId: string): void;
+  dispose(): void;
+}
+
+export class TerminalWebSocketBridge {
+  constructor(options: {
+    host: Pick<TmuxTerminalHost, 'issueAttachment' | 'attachSocket'>;
+    allowedOrigins: string | readonly string[];
+  });
+  readonly baseUrl: string;
+  start(): Promise<string>;
+  issueAttachment(sessionId: string, options?: { mode?: 'observe' | 'control' }): EmbeddedTerminalAttachmentGrant;
+  stop(): Promise<void>;
+}
+
+export type SupercodeTerminalHarness = 'claude-code' | 'codex' | 'gemini' | 'grok';
+
+export type SupercodeTerminalLaunch = Readonly<{
+  arguments?: readonly string[];
+  cwd: string;
+  env?: Readonly<Record<string, string>>;
+  program: string;
+}>;
+
+export type SupercodeTerminalAttachment = EmbeddedTerminalAttachmentGrant & Readonly<{
+  conversationKey: string | null;
+  sessionId: string;
+}>;
+
+export type SupercodeTerminalSnapshot = Readonly<{
+  attachment: SupercodeTerminalAttachment | null;
+  available: boolean;
+  bindings: readonly Readonly<{ conversationKey: string; sessionId: string }>[];
+  canOpenLocal: boolean;
+  error: string | null;
+  sessions: readonly TerminalSession[];
+}>;
+
+export type SupercodeTerminalControllerOptions = Readonly<{
+  allowedOrigins: string | readonly string[];
+  formatCwd?: (cwd: string) => string | null | undefined;
+  host?: TmuxTerminalHostOptions;
+  nativeHost?: { socket?: string; home?: string; claudeConfigDir?: string };
+  sessionNamePrefix?: string;
+}>;
+
+export class SupercodeTerminalController {
+  constructor(options: SupercodeTerminalControllerOptions);
+  start(): Promise<void>;
+  snapshot(): Promise<SupercodeTerminalSnapshot>;
+  create(harness: SupercodeTerminalHarness, cwd: string): Promise<SupercodeTerminalSnapshot>;
+  launchSession(
+    harness: string,
+    launch: SupercodeTerminalLaunch,
+    conversationKey?: string | null,
+    initialInput?: string,
+    options?: Readonly<{
+      conversationDiscovery?: Readonly<{
+        knownConversationKeys: readonly string[];
+        prompt: string;
+        startedAtMs?: number;
+      }>;
+    }>,
+  ): Promise<SupercodeTerminalSnapshot>;
+  attach(sessionId: string, mode: 'observe' | 'control'): Promise<SupercodeTerminalSnapshot>;
+  bindContext(sessionId: string, conversationKey: string): Promise<SupercodeTerminalSnapshot>;
+  reconcileConversationBindings(
+    descriptors: readonly SessionDescriptor[],
+    keyForDescriptor: (descriptor: SessionDescriptor) => string,
+    options?: Readonly<{ now?: number }>,
+  ): Promise<Readonly<{
+    bindings: readonly Readonly<{ conversationKey: string; sessionId: string }>[];
+    snapshot: SupercodeTerminalSnapshot;
+  }>>;
+  close(sessionId: string): Promise<SupercodeTerminalSnapshot>;
+  openLocal(sessionId: string): Promise<SupercodeTerminalSnapshot>;
+  dismiss(): Promise<SupercodeTerminalSnapshot>;
+  refreshNativeSessions(): Promise<void>;
+  canMoveSession(harness: string, sessionId: string, cwd: string): boolean;
+  prepareMoveSession(
+    harness: string,
+    sessionId: string,
+    cwd: string,
+    proof: NativeSessionIdleProof | null,
+  ): Promise<NativeSessionIdleProof | null>;
+  moveSession(
+    harness: string,
+    sessionId: string,
+    launch: SupercodeTerminalLaunch,
+    conversationKey: string,
+    proof: NativeSessionIdleProof,
+  ): Promise<SupercodeTerminalSnapshot>;
+  stop(): Promise<void>;
+}
+
+export class TerminalHostError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+
+/**
+ * Is the program of this kind showing its idle composer on this captured screen?
+ * `null` means this package has no composer pattern for that kind — never read
+ * it as "not ready yet".
+ */
+export function composerReadyForInput(kind: string, screen: string | undefined): boolean | null;
+/** Does the composer hold a typed draft? `screen` is a capture with escapes; null when no composer is on screen. */
+export function composerHoldsDraft(kind: string, screen: string | undefined): boolean | null;
+
+export { classifyAttentionSignal, observeLifecycle, gatherLifecycleObservation, createLifecycleStore, snapshotProcessTree, snapshotProcessTreeAsync } from './substrate/session-lifecycle.js';
+export type {
+  LifecycleSnapshot,
+  LifecycleStore,
+  PaneLifecycle,
+  PaneProcessLifecycle,
+  PaneProcessObservation,
+  SessionAttentionSignal,
+  SessionDerivation,
+  DerivationConfidence,
+  DerivationSource,
+  SessionLifecycle,
+  SessionLifecycleState,
+} from './substrate/session-lifecycle.js';
+
+export type { TerminalInputDelivery, TmuxCommand, TmuxWindowSize };