Class SessionManager

constructor

• new SessionManager(config: Config, store?: StateStore): SessionManager

  Parameters

  • config: Config
  • Optionalstore: StateStore

  Returns SessionManager

Static ReadonlyDEFAULT_STALL_THRESHOLD_MS

Static ReadonlyDEFAULT_PERMISSION_STALL_MS

Static ReadonlyDEFAULT_PROMPT_TIMEOUT_MS

Static ReadonlyDEFAULT_PROMPT_MAX_RETRIES

load

• load(): Promise<void>

  Load state from disk or the configured store (Issue #1937).

  Returns Promise<void>

save

• save(): Promise<void>

  Save state to disk atomically (write to temp, then rename). #218: Uses a write queue to serialize concurrent saves and prevent corruption.

  Returns Promise<void>

debouncedSave

• debouncedSave(): void

  #357: Debounced save — skips immediate save for offset-only changes. Coalesces rapid successive reads into a single disk write.

  Returns void

setAcpEventStore

• setAcpEventStore(store: AcpEventStore): void

  Issue #3143: Wire ACP event store into transcript reader.

  Parameters

  • store: AcpEventStore

  Returns void

setEncryptionKey

• setEncryptionKey(masterToken: string): void

  Parameters

  • masterToken: string

  Returns void

createSession

• createSession(
      opts: {
          id?: string;
          workDir: string;
          name?: string;
          prd?: string;
          resumeSessionId?: string;
          claudeCommand?: string;
          env?: Record<string, string>;
          stallThresholdMs?: number;
          permissionStallMs?: number;
          permissionMode?: string;
          autoApprove?: boolean;
          parentId?: string;
          ownerKeyId?: string | null;
          tenantId?: string;
          initialStatus?: UIState;
          model?: string;
      },
  ): Promise<SessionInfo>

  Wait for CC idle prompt, then send. Single attempt.

  Parameters

  • opts: {
        id?: string;
        workDir: string;
        name?: string;
        prd?: string;
        resumeSessionId?: string;
        claudeCommand?: string;
        env?: Record<string, string>;
        stallThresholdMs?: number;
        permissionStallMs?: number;
        permissionMode?: string;
        autoApprove?: boolean;
        parentId?: string;
        ownerKeyId?: string | null;
        tenantId?: string;
        initialStatus?: UIState;
        model?: string;
    }

    • Optionalid?: string

    • workDir: string

    • Optionalname?: string

    • Optionalprd?: string

    • OptionalresumeSessionId?: string

    • OptionalclaudeCommand?: string

    • Optionalenv?: Record<string, string>

    • OptionalstallThresholdMs?: number

    • OptionalpermissionStallMs?: number

    • OptionalpermissionMode?: string

    • OptionalautoApprove?: boolean

      Deprecated

      Use permissionMode instead. Maps true→bypassPermissions, false→default.

    • OptionalparentId?: string

      Issue #702: Parent session ID for sub-agent hierarchy

    • OptionalownerKeyId?: string | null

      Issue #1429: API key ID that owns this session

    • OptionaltenantId?: string

      Issue #1944: Tenant ID inherited from the creating API key.

    • OptionalinitialStatus?: UIState

      Issue #3135: Override initial status when creating from ACP result.

    • Optionalmodel?: string

  Returns Promise<SessionInfo>

getSession

• getSession(id: string): SessionInfo | null

  Get a session by ID.

  Parameters

  • id: string

  Returns SessionInfo | null

updateStatusFromHook

• updateStatusFromHook(
      id: string,
      hookEvent: string,
      hookTimestamp?: number,
  ): UIState | null

  Issue #169 Phase 3: Update session status from a hook event. Returns the previous status for change detection. Issue #87: Also records hook latency timestamps.

  Parameters

  • id: string
  • hookEvent: string
  • OptionalhookTimestamp: number

  Returns UIState | null

sendInitialPrompt

• sendInitialPrompt(
      _id: string,
      _prompt: string,
  ): Promise<{ delivered: boolean; attempts: number }>

  Send initial prompt (ACP stub — prompts sent via JSON-RPC).

  Parameters

  • _id: string
  • _prompt: string

  Returns Promise<{ delivered: boolean; attempts: number }>

findIdleSessionByWorkDir

• findIdleSessionByWorkDir(workDir: string): Promise<SessionInfo | null>

  Find an idle session by workDir (ACP mode: state-based lookup with acquisition). Atomically acquires the session under a mutex to prevent TOCTOU race (Issue #840/#880). Supports fault injection for testing (Issue #901).

  Parameters

  • workDir: string

  Returns Promise<SessionInfo | null>

getHealth

• getHealth(
      id: string,
  ): Promise<
      {
          alive: boolean;
          claudeRunning: boolean;
          status: UIState;
          hasTranscript: boolean;
          lastActivity: number;
          lastActivityAgo: number;
          sessionAge: number;
          details: string;
          actionHints?: Record<
              string,
              { method: string; url: string; description: string },
          >;
      },
  >

  Get health info (ACP stub — basic status without window checks).

  Parameters

  • id: string

  Returns Promise<
      {
          alive: boolean;
          claudeRunning: boolean;
          status: UIState;
          hasTranscript: boolean;
          lastActivity: number;
          lastActivityAgo: number;
          sessionAge: number;
          details: string;
          actionHints?: Record<
              string,
              { method: string; url: string; description: string },
          >;
      },
  >

sendMessage

• sendMessage(
      _id: string,
      _text: string,
  ): Promise<{ delivered: boolean; attempts: number; error?: string }>

  Send message (ACP stub — use JSON-RPC).

  Parameters

  • _id: string
  • _text: string

  Returns Promise<{ delivered: boolean; attempts: number; error?: string }>

approve

• approve(id: string): Promise<void>

  Approve permission (ACP stub — handled by hooks).

  Parameters

  • id: string

  Returns Promise<void>

reject

• reject(id: string): Promise<void>

  Reject permission (ACP stub — handled by hooks).

  Parameters

  • id: string

  Returns Promise<void>

escape

• escape(_id: string): Promise<void>

  Escape session (ACP stub).

  Parameters

  • _id: string

  Returns Promise<void>

interrupt

• interrupt(_id: string): Promise<void>

  Interrupt session (ACP stub — use JSON-RPC cancel).

  Parameters

  • _id: string

  Returns Promise<void>

isWindowAlive

• isWindowAlive(_id: string): Promise<boolean>

  Window alive check (ACP stub — always true).

  Parameters

  • _id: string

  Returns Promise<boolean>

detectWaitingForInput

• detectWaitingForInput(id: string): Promise<boolean>

  Parameters

  • id: string

  Returns Promise<boolean>

addSubagent

• addSubagent(id: string, name: string): void

  Issue #88: Add an active subagent to a session.

  Parameters

  • id: string
  • name: string

  Returns void

removeSubagent

• removeSubagent(id: string, name: string): void

  Issue #88: Remove an active subagent from a session.

  Parameters

  • id: string
  • name: string

  Returns void

recordHookFailure

• recordHookFailure(id: string): void

  Issue #2518: Record a StopFailure hook event for circuit breaker tracking.

  Parameters

  • id: string

  Returns void

recordHookSuccess

• recordHookSuccess(id: string): void

  Issue #2518: Record a Stop (success) event — resets circuit breaker state.

  Parameters

  • id: string

  Returns void

checkHookCircuitBreaker

• checkHookCircuitBreaker(
      id: string,
      maxFailures: number,
      windowMs: number,
  ): boolean

  Issue #2518: Check whether the circuit breaker should trip. Prunes stale timestamps outside the sliding window, then trips if the failure count meets or exceeds maxFailures. Once tripped, always returns true.

  Parameters

  • id: string
  • maxFailures: number
  • windowMs: number

  Returns boolean

updateSessionModel

• updateSessionModel(id: string, model: string): void

  Issue #89 L25: Update the model field on a session from hook payload.

  Parameters

  • id: string
  • model: string

  Returns void

getLatencyMetrics

• getLatencyMetrics(
      id: string,
  ):
      | {
          hook_latency_ms: number
          | null;
          state_change_detection_ms: number | null;
          permission_response_ms: number | null;
      }
      | null

  Issue #87: Get latency metrics for a session.

  Parameters

  • id: string

  Returns
      | {
          hook_latency_ms: number
          | null;
          state_change_detection_ms: number | null;
          permission_response_ms: number | null;
      }
      | null

listSessions

• listSessions(): SessionInfo[]

  List all sessions.

  Returns SessionInfo[]

releaseSessionClaim

• releaseSessionClaim(id: string): void

  Release a session claim after the reuse path completes (success or failure).

  Parameters

  • id: string

  Returns void

recordPermissionPrompt

• recordPermissionPrompt(id: string): void

  Record that a permission prompt was detected for this session.

  Parameters

  • id: string

  Returns void

waitForPermissionDecision

• waitForPermissionDecision(
      sessionId: string,
      timeoutMs?: number,
      toolName?: string,
      prompt?: string,
  ): Promise<PermissionDecision>

  Issue #284: Store a pending permission request and return a promise that resolves when the client approves/rejects via the API.

  Parameters

  • sessionId: string

    Aegis session ID

  • timeoutMs: number = 10_000

    Timeout before auto-rejecting (default 10_000ms, matching CC's hook timeout)

  • OptionaltoolName: string

    Optional tool name from the hook payload

  • Optionalprompt: string

    Optional permission prompt text

  Returns Promise<PermissionDecision>

  Promise that resolves with the client's decision

hasPendingPermission

• hasPendingPermission(sessionId: string): boolean

  Check if a session has a pending permission request.

  Parameters

  • sessionId: string

  Returns boolean

getPendingPermissionInfo

• getPendingPermissionInfo(sessionId: string): PendingPermissionInfo | null

  Get info about a pending permission (for API responses).

  Parameters

  • sessionId: string

  Returns PendingPermissionInfo | null

cleanupPendingPermission

• cleanupPendingPermission(sessionId: string): void

  Clean up any pending permission for a session (e.g. on session delete).

  Parameters

  • sessionId: string

  Returns void

waitForAnswer

• waitForAnswer(
      sessionId: string,
      toolUseId: string,
      question: string,
      timeoutMs?: number,
  ): Promise<string | null>

  Issue #336: Store a pending AskUserQuestion and return a promise that resolves when the external client provides an answer via POST /answer.

  Parameters

  • sessionId: string
  • toolUseId: string
  • question: string
  • timeoutMs: number = 30_000

  Returns Promise<string | null>

submitAnswer

• submitAnswer(sessionId: string, questionId: string, answer: string): boolean

  Issue #336: Submit an answer to a pending question. Returns true if resolved.

  Parameters

  • sessionId: string
  • questionId: string
  • answer: string

  Returns boolean

hasPendingQuestion

• hasPendingQuestion(sessionId: string): boolean

  Issue #336: Check if a session has a pending question.

  Parameters

  • sessionId: string

  Returns boolean

getPendingQuestionInfo

• getPendingQuestionInfo(
      sessionId: string,
  ): { toolUseId: string; question: string; timestamp: number } | null

  Issue #336: Get info about a pending question.

  Parameters

  • sessionId: string

  Returns { toolUseId: string; question: string; timestamp: number } | null

cleanupPendingQuestion

• cleanupPendingQuestion(sessionId: string): void

  Issue #336: Clean up any pending question for a session.

  Parameters

  • sessionId: string

  Returns void

readMessages

• readMessages(
      id: string,
  ): Promise<
      {
          messages: ParsedEntry[];
          status: UIState;
          statusText: string
          | null;
          interactiveContent: string | null;
      },
  >

  Read new messages from a session.

  Parameters

  • id: string

  Returns Promise<
      {
          messages: ParsedEntry[];
          status: UIState;
          statusText: string
          | null;
          interactiveContent: string | null;
      },
  >

readMessagesFromSession

• readMessagesFromSession(
      session: SessionInfo,
  ): Promise<
      {
          messages: ParsedEntry[];
          status: UIState;
          statusText: string
          | null;
          interactiveContent: string | null;
      },
  >

  Issue #2539: Read new messages from an already-resolved SessionInfo. Avoids the double lookup that readMessages(id) performs, eliminating the TOCTOU race between ownership check and transcript read.

  Parameters

  • session: SessionInfo

  Returns Promise<
      {
          messages: ParsedEntry[];
          status: UIState;
          statusText: string
          | null;
          interactiveContent: string | null;
      },
  >

readMessagesForMonitor

• readMessagesForMonitor(
      id: string,
  ): Promise<
      {
          messages: ParsedEntry[];
          status: UIState;
          statusText: string
          | null;
          interactiveContent: string | null;
      },
  >

  Read new messages for the monitor (separate offset from API reads).

  Parameters

  • id: string

  Returns Promise<
      {
          messages: ParsedEntry[];
          status: UIState;
          statusText: string
          | null;
          interactiveContent: string | null;
      },
  >

getSummary

• getSummary(
      id: string,
      maxMessages?: number,
  ): Promise<
      {
          sessionId: string;
          displayName: string;
          status: UIState;
          totalMessages: number;
          messages: { role: string; contentType: string; text: string }[];
          createdAt: number;
          lastActivity: number;
          permissionMode: string;
          prd?: string;
      },
  >

  Issue #35: Get a condensed summary of a session's transcript.

  Parameters

  • id: string
  • maxMessages: number = 20

  Returns Promise<
      {
          sessionId: string;
          displayName: string;
          status: UIState;
          totalMessages: number;
          messages: { role: string; contentType: string; text: string }[];
          createdAt: number;
          lastActivity: number;
          permissionMode: string;
          prd?: string;
      },
  >

readTranscript

• readTranscript(
      id: string,
      page?: number,
      limit?: number,
      roleFilter?: "assistant" | "system" | "user",
  ): Promise<
      {
          messages: ParsedEntry[];
          total: number;
          page: number;
          limit: number;
          hasMore: boolean;
      },
  >

  Paginated transcript read — does NOT advance the session's byteOffset.

  Parameters

  • id: string
  • page: number = 1
  • limit: number = 50
  • OptionalroleFilter: "assistant" | "system" | "user"

  Returns Promise<
      {
          messages: ParsedEntry[];
          total: number;
          page: number;
          limit: number;
          hasMore: boolean;
      },
  >

readTranscriptCursor

• readTranscriptCursor(
      id: string,
      beforeId?: number,
      limit?: number,
      roleFilter?: "assistant" | "system" | "user",
  ): Promise<
      {
          messages: (ParsedEntry & { _cursor_id: number })[];
          has_more: boolean;
          oldest_id: number | null;
          newest_id: number | null;
      },
  >

  Cursor-based transcript read — stable under concurrent appends.

  Parameters

  • id: string
  • OptionalbeforeId: number
  • limit: number = 50
  • OptionalroleFilter: "assistant" | "system" | "user"

  Returns Promise<
      {
          messages: (ParsedEntry & { _cursor_id: number })[];
          has_more: boolean;
          oldest_id: number | null;
          newest_id: number | null;
      },
  >

killSession

• killSession(id: string): Promise<void>

  Kill a session.

  Parameters

  • id: string

  Returns Promise<void>