Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

18.7 KB
Raw Blame
import type {
  AvailableCommand,
  ContentBlock,
  PermissionOption,
  PromptCapabilities,
  SessionConfigOption,
  SessionModeState,
  SessionUpdate,
  StopReason,
  ToolCallUpdate,
} from '@agentclientprotocol/sdk';

export type ThreadStatus =
  | 'installing'
  | 'spawning'
  | 'ready'
  | 'auth_required'
  | 'authenticating'
  | 'running'
  | 'awaiting_permission'
  | 'exited'
  | 'error';

export type ManagedRuntimeKind = 'node' | 'uv';

export type PiBridgeWriteAction =
  | 'unchanged'
  | 'written'
  | 'refreshed'
  | 'refused-foreign'
  | 'refused-unreadable'
  | 'refused-project-path'
  | 'failed';

export type PiTrustWriteAction =
  | 'already-trusted'
  | 'added'
  | 'skipped'
  | 'refused-unreadable'
  | 'failed';

export const THREAD_REOPEN_OP_TIMEOUT_MS = 90_000;

export type PiBridgeThreadState =
  | 'ready'
  | 'foreign-file'
  | 'unreadable-file'
  | 'project-path-unavailable'
  | 'bridge-failed'
  | 'trust-failed';

export interface ThreadAuthTerminalLaunch {
  executable: string;
  args: string[];
  env: Record<string, string>;
  pathPrepend: string[];
}

export interface ThreadAuthMethod {
  id: string;
  name: string;
  description?: string;
  kind?: string;
  terminalLaunchAvailable?: true;
}

export type ThreadExitCause =
  | 'killed'
  | 'stopped'
  | 'signal'
  | 'out-of-memory'
  | 'command-not-found'
  | 'not-executable'
  | 'missing-module'
  | 'clean'
  | 'unknown';

export interface ThreadExitDiagnosis {
  exitCode: number | null;
  signal: string | null;
  cause: ThreadExitCause;
}

export interface ThreadFailureDetail {
  reason: 'auth-required' | 'connect' | 'session-setup' | 'prompt' | 'exited';
  agentMessage?: string;
  machineDetail?: string;
  authMethods?: ThreadAuthMethod[];
  exit?: ThreadExitDiagnosis;
}

export const THREAD_EXIT_STDERR_WINDOW_LINES = 10;

export function exitStderrWindow(tail: string): string {
  return tail.split('\n').slice(-THREAD_EXIT_STDERR_WINDOW_LINES).join('\n');
}

export interface ThreadAgentInfo {
  id: string;
  name: string;
  iconUrl?: string;
  source: 'registry' | 'custom';
  version?: string;
}

export function isTextishMime(mimeType: string | null): boolean {
  if (mimeType === null) return false;
  if (mimeType.startsWith('text/')) return true;
  return (
    mimeType === 'application/json' ||
    mimeType === 'application/xml' ||
    mimeType === 'application/x-yaml' ||
    mimeType === 'application/yaml' ||
    mimeType === 'application/javascript' ||
    mimeType === 'application/typescript' ||
    mimeType === 'application/toml' ||
    mimeType === 'application/x-sh' ||
    mimeType === 'application/sql'
  );
}

export type AttachmentPart =
  | {
      readonly kind: 'file';
      readonly path: string;
      readonly name: string;
    }
  | {
      readonly kind: 'folder';
      readonly path: string;
      readonly name: string;
    }
  | {
      readonly kind: 'image';
      readonly data: string;
      readonly mimeType: string;
      readonly name: string;
      readonly sizeBytes?: number;
    }
  | {
      readonly kind: 'blob';
      readonly data: string;
      readonly textPayload: boolean;
      readonly mimeType: string;
      readonly name: string;
      readonly sizeBytes?: number;
    };

export interface QueuedMessage {
  id: string;
  content: string;
  attachments?: readonly AttachmentPart[];
  ts: number;
  held?: boolean;
}

export interface SteerMessage {
  content: string;
  attachments?: readonly AttachmentPart[];
  ts: number;
}

export type ThreadChatGrant = 'read_only_shell';

export interface ThreadInfo {
  threadId: string;
  agent: ThreadAgentInfo;
  title: string;
  status: ThreadStatus;
  createdAt: number;
  lastActivityAt: number;
  promptCapabilities?: PromptCapabilities | null;
  modes?: SessionModeState | null;
  configOptions?: SessionConfigOption[] | null;
  contextWindow?: number | null;
  availableCommands?: AvailableCommand[] | null;
  lastSeq: number;
  archived?: boolean;
  resumable?: boolean;
  queue?: QueuedMessage[];
  steer?: SteerMessage;
  stalledSince?: number;
  signInOutput?: string[];
  chatGrants?: readonly ThreadChatGrant[];
}

export type BrowserUnavailableReason = 'no-node' | 'failed';

export type ThreadEvent =
  | {
      kind: 'user_message';
      content: string;
      attachments?: readonly AttachmentPart[];
      ts: number;
    }
  | { kind: 'session_update'; update: SessionUpdate; ts: number }
  | {
      kind: 'permission_request';
      requestId: string;
      toolCall: ToolCallUpdate;
      options: PermissionOption[];
      readOnlyShell?: boolean;
      ts: number;
    }
  | {
      kind: 'permission_resolved';
      requestId: string;
      optionId: string | null;
      auto: boolean;
      ts: number;
    }
  | { kind: 'turn_started'; ts: number }
  | { kind: 'turn_ended'; stopReason: StopReason; ts: number }
  | {
      kind: 'status';
      status: ThreadStatus;
      detail?: string;
      failure?: ThreadFailureDetail;
      ts: number;
    }
  | { kind: 'title_changed'; title: string; ts: number }
  | { kind: 'agent_stderr'; line: string; ts: number }
  | { kind: 'browser_unavailable'; reason: BrowserUnavailableReason; ts: number }
  | {
      kind: 'runtime_consent_request';
      requestId: string;
      runtime: ManagedRuntimeKind;
      displayName: string;
      provides: string;
      version: string;
      approxSizeMB: number;
      sourceHost: string;
      agentName: string;
      reason?: 'missing' | 'broken' | 'damaged';
      ts: number;
    }
  | {
      kind: 'runtime_consent_resolved';
      requestId: string;
      decision: 'granted' | 'declined' | 'timeout';
      ts: number;
    }
  | {
      kind: 'pi_bridge_consent_request';
      requestId: string;
      agentName: string;
      bridgePath: string;
      cwd: string;
      otherExtensions?: readonly string[];
      ts: number;
    }
  | {
      kind: 'pi_bridge_consent_resolved';
      requestId: string;
      decision: 'granted' | 'declined' | 'timeout';
      ts: number;
    }
  | {
      kind: 'pi_bridge_status';
      requestId?: string;
      state: PiBridgeThreadState;
      bridgePath: string;
      bridge?: PiBridgeWriteAction;
      trust?: PiTrustWriteAction;
      detail?: string;
      ts: number;
    }
  | {
      kind: 'runtime_install_progress';
      runtime: ManagedRuntimeKind;
      phase: 'downloading' | 'verifying' | 'extracting';
      receivedBytes?: number;
      totalBytes?: number;
      ts: number;
    }
  | {
      kind: 'terminal_created';
      terminalId: string;
      command: string;
      args: string[];
      ts: number;
    }
  | {
      kind: 'terminal_output';
      terminalId: string;
      chunk: string;
      ts: number;
    }
  | {
      kind: 'terminal_exit';
      terminalId: string;
      exitCode: number | null;
      signal: string | null;
      ts: number;
    };

export type ThreadClientFrame =
  | {
      op: 'create';
      reqId: string;
      agent: { source: 'registry' | 'custom'; id: string };
      prompt?: string;
      attachments?: readonly AttachmentPart[];
      docName?: string;
      titleHint?: string;
      settings?: { config?: Record<string, string | boolean>; modeId?: string };
    }
  | { op: 'subscribe'; threadId: string; sinceSeq?: number }
  | { op: 'unsubscribe'; threadId: string }
  | {
      op: 'prompt';
      threadId: string;
      reqId: string;
      content: string;
      attachments?: readonly AttachmentPart[];
    }
  | {
      op: 'steer';
      threadId: string;
      reqId: string;
      content: string;
      attachments?: readonly AttachmentPart[];
    }
  | {
      op: 'queue_edit';
      threadId: string;
      id: string;
      content: string;
      reqId?: string;
    }
  | {
      op: 'queue_hold';
      threadId: string;
      id: string;
      held: boolean;
    }
  | {
      op: 'queue_remove';
      threadId: string;
      id: string;
    }
  | {
      op: 'queue_send_now';
      threadId: string;
      id: string;
    }
  | {
      op: 'set_chat_grant';
      threadId: string;
      grant: ThreadChatGrant;
      enabled: boolean;
    }
  | {
      op: 'permission_response';
      threadId: string;
      requestId: string;
      outcome: { kind: 'selected'; optionId: string } | { kind: 'cancelled' };
    }
  | { op: 'cancel'; threadId: string }
  | {
      op: 'runtime_consent_response';
      threadId: string;
      requestId: string;
      outcome: { kind: 'granted' } | { kind: 'declined' };
    }
  | {
      op: 'pi_bridge_consent_response';
      threadId: string;
      requestId: string;
      outcome: { kind: 'granted' } | { kind: 'declined' };
    }
  | { op: 'set_mode'; threadId: string; modeId: string }
  | {
      op: 'set_config_option';
      threadId: string;
      configId: string;
      value: string | boolean;
    }
  | { op: 'set_context_window'; threadId: string; reqId: string; tokens: number }
  | { op: 'close'; threadId: string }
  | {
      op: 'rename';
      threadId: string;
      title: string;
    }
  | {
      op: 'resume';
      threadId: string;
      reqId: string;
      prompt?: string;
      attachments?: readonly AttachmentPart[];
    }
  | {
      op: 'retry';
      threadId: string;
      reqId: string;
    }
  | {
      op: 'terminal_auth_launch';
      threadId: string;
      reqId: string;
      methodId: string;
    }
  | {
      op: 'authenticate';
      threadId: string;
      reqId: string;
      methodId: string;
    }
  | {
      op: 'delete';
      threadId: string;
    }
  | { op: 'list' };

export type ThreadServerFrame =
  | { op: 'created'; reqId: string; info: ThreadInfo }
  | { op: 'resumed'; reqId: string; info: ThreadInfo }
  | { op: 'retried'; reqId: string; info: ThreadInfo }
  | { op: 'terminal_auth_launch_ready'; reqId: string; launch: ThreadAuthTerminalLaunch }
  | { op: 'context_window_set'; reqId: string; info: ThreadInfo }
  | { op: 'authenticated'; reqId: string; info: ThreadInfo }
  | { op: 'subscribed'; threadId: string; fromSeq: number; info: ThreadInfo }
  | { op: 'event'; threadId: string; seq: number; event: ThreadEvent }
  | {
      op: 'events';
      threadId: string;
      fromSeq: number;
      events: ThreadEvent[];
    }
  | {
      op: 'queue_edited';
      reqId: string;
      threadId: string;
    }
  | { op: 'info'; info: ThreadInfo }
  | { op: 'threads'; threads: ThreadInfo[] }
  | {
      op: 'error';
      code: ThreadErrorCode;
      message: string;
      reqId?: string;
      threadId?: string;
    };

export type ThreadErrorCode =
  | 'bad-frame'
  | 'unknown-thread'
  | 'unknown-agent'
  | 'capacity'
  | 'spawn-failed'
  | 'install-failed'
  | 'agent-error'
  | 'not-ready'
  | 'resume-unsupported'
  | 'agent-exited'
  | 'internal';

const CLIENT_OPS = new Set([
  'create',
  'subscribe',
  'unsubscribe',
  'prompt',
  'steer',
  'queue_edit',
  'queue_hold',
  'queue_remove',
  'queue_send_now',
  'set_chat_grant',
  'permission_response',
  'runtime_consent_response',
  'pi_bridge_consent_response',
  'cancel',
  'set_mode',
  'set_config_option',
  'set_context_window',
  'close',
  'rename',
  'resume',
  'retry',
  'terminal_auth_launch',
  'authenticate',
  'delete',
  'list',
]);

function isValidAttachmentPartArray(value: unknown): value is readonly AttachmentPart[] {
  if (value === undefined) return true;
  if (!Array.isArray(value)) return false;
  for (const part of value) {
    if (typeof part !== 'object' || part === null) return false;
    const p = part as Record<string, unknown>;
    if (p.kind === 'file' || p.kind === 'folder') {
      if (typeof p.path !== 'string' || typeof p.name !== 'string') return false;
    } else if (p.kind === 'image') {
      if (
        typeof p.data !== 'string' ||
        typeof p.mimeType !== 'string' ||
        typeof p.name !== 'string'
      )
        return false;
      if (p.sizeBytes !== undefined && typeof p.sizeBytes !== 'number') return false;
    } else if (p.kind === 'blob') {
      if (
        typeof p.data !== 'string' ||
        typeof p.textPayload !== 'boolean' ||
        typeof p.mimeType !== 'string' ||
        typeof p.name !== 'string'
      ) {
        return false;
      }
      if (p.sizeBytes !== undefined && typeof p.sizeBytes !== 'number') return false;
    } else {
      return false;
    }
  }
  return true;
}

export function parseThreadClientFrame(raw: string): ThreadClientFrame | null {
  let value: unknown;
  try {
    value = JSON.parse(raw);
  } catch {
    return null;
  }
  if (typeof value !== 'object' || value === null) return null;
  const frame = value as Record<string, unknown>;
  if (typeof frame.op !== 'string' || !CLIENT_OPS.has(frame.op)) return null;
  const str = (k: string): boolean => typeof frame[k] === 'string' && frame[k] !== '';
  switch (frame.op) {
    case 'create': {
      if (!str('reqId')) return null;
      const agent = frame.agent as Record<string, unknown> | undefined;
      if (
        typeof agent !== 'object' ||
        agent === null ||
        (agent.source !== 'registry' && agent.source !== 'custom') ||
        typeof agent.id !== 'string' ||
        agent.id === ''
      ) {
        return null;
      }
      if (frame.prompt !== undefined && typeof frame.prompt !== 'string') return null;
      if (frame.docName !== undefined && typeof frame.docName !== 'string') return null;
      if (frame.settings !== undefined) {
        const settings = frame.settings as Record<string, unknown> | null;
        if (typeof settings !== 'object' || settings === null) return null;
        if (settings.config !== undefined) {
          const config = settings.config as Record<string, unknown> | null;
          if (typeof config !== 'object' || config === null || Array.isArray(config)) return null;
          for (const v of Object.values(config)) {
            if (typeof v !== 'string' && typeof v !== 'boolean') return null;
          }
        }
        if (settings.modeId !== undefined && typeof settings.modeId !== 'string') return null;
      }
      if (!isValidAttachmentPartArray(frame.attachments)) return null;
      return frame as unknown as ThreadClientFrame;
    }
    case 'subscribe':
      if (!str('threadId')) return null;
      if (frame.sinceSeq !== undefined && typeof frame.sinceSeq !== 'number') return null;
      return frame as unknown as ThreadClientFrame;
    case 'prompt':
      if (!str('threadId') || !str('reqId') || typeof frame.content !== 'string') return null;
      if (!isValidAttachmentPartArray(frame.attachments)) return null;
      return frame as unknown as ThreadClientFrame;
    case 'steer': {
      if (!str('threadId') || !str('reqId')) return null;
      if (typeof frame.content !== 'string') return null;
      if (!isValidAttachmentPartArray(frame.attachments)) return null;
      const hasAttachments = Array.isArray(frame.attachments) && frame.attachments.length > 0;
      if (frame.content === '' && !hasAttachments) return null;
      return frame as unknown as ThreadClientFrame;
    }
    case 'queue_edit':
      if (!str('threadId') || !str('id') || !str('content')) return null;
      if (frame.reqId !== undefined && !str('reqId')) return null;
      return frame as unknown as ThreadClientFrame;
    case 'queue_hold':
      if (!str('threadId') || !str('id') || typeof frame.held !== 'boolean') return null;
      return frame as unknown as ThreadClientFrame;
    case 'set_chat_grant':
      if (
        !str('threadId') ||
        frame.grant !== 'read_only_shell' ||
        typeof frame.enabled !== 'boolean'
      ) {
        return null;
      }
      return frame as unknown as ThreadClientFrame;
    case 'queue_remove':
    case 'queue_send_now':
      if (!str('threadId') || !str('id')) return null;
      return frame as unknown as ThreadClientFrame;
    case 'permission_response': {
      if (!str('threadId') || !str('requestId')) return null;
      const outcome = frame.outcome as Record<string, unknown> | undefined;
      if (typeof outcome !== 'object' || outcome === null) return null;
      if (outcome.kind === 'selected') {
        if (typeof outcome.optionId !== 'string' || outcome.optionId === '') return null;
      } else if (outcome.kind !== 'cancelled') {
        return null;
      }
      return frame as unknown as ThreadClientFrame;
    }
    case 'runtime_consent_response': {
      if (!str('threadId') || !str('requestId')) return null;
      const outcome = frame.outcome as Record<string, unknown> | undefined;
      if (typeof outcome !== 'object' || outcome === null) return null;
      if (outcome.kind !== 'granted' && outcome.kind !== 'declined') return null;
      return frame as unknown as ThreadClientFrame;
    }
    case 'pi_bridge_consent_response': {
      if (!str('threadId') || !str('requestId')) return null;
      const outcome = frame.outcome as Record<string, unknown> | undefined;
      if (typeof outcome !== 'object' || outcome === null) return null;
      if (outcome.kind !== 'granted' && outcome.kind !== 'declined') return null;
      return frame as unknown as ThreadClientFrame;
    }
    case 'set_mode':
      if (!str('threadId') || !str('modeId')) return null;
      return frame as unknown as ThreadClientFrame;
    case 'rename':
      if (!str('threadId') || !str('title')) return null;
      return frame as unknown as ThreadClientFrame;
    case 'set_config_option':
      if (!str('threadId') || !str('configId')) return null;
      if (typeof frame.value !== 'string' && typeof frame.value !== 'boolean') return null;
      if (frame.value === '') return null;
      return frame as unknown as ThreadClientFrame;
    case 'set_context_window':
      if (!str('threadId') || !str('reqId')) return null;
      if (typeof frame.tokens !== 'number' || !Number.isFinite(frame.tokens)) return null;
      if (frame.tokens <= 0) return null;
      return frame as unknown as ThreadClientFrame;
    case 'resume':
      if (!str('threadId') || !str('reqId')) return null;
      if (frame.prompt !== undefined && typeof frame.prompt !== 'string') return null;
      if (!isValidAttachmentPartArray(frame.attachments)) return null;
      return frame as unknown as ThreadClientFrame;
    case 'retry':
      if (!str('threadId') || !str('reqId')) return null;
      return frame as unknown as ThreadClientFrame;
    case 'terminal_auth_launch':
      if (!str('threadId') || !str('reqId') || !str('methodId')) return null;
      return frame as unknown as ThreadClientFrame;
    case 'authenticate':
      if (!str('threadId') || !str('reqId') || !str('methodId')) return null;
      return frame as unknown as ThreadClientFrame;
    case 'unsubscribe':
    case 'cancel':
    case 'close':
    case 'delete':
      if (!str('threadId')) return null;
      return frame as unknown as ThreadClientFrame;
    case 'list':
      return frame as unknown as ThreadClientFrame;
    default:
      return null;
  }
}

export type {
  AvailableCommand,
  ContentBlock,
  PermissionOption,
  PromptCapabilities,
  SessionConfigOption,
  SessionModeState,
  SessionUpdate,
  StopReason,
  ToolCallUpdate,
};