# Instagit SSE Streaming Architecture: How It Handles Real-Time Response Events

> Explore Instagit's SSE streaming architecture connecting fetch API and eventsource-parser to handle real-time response events for reasoning, output text, and completion. Learn how it works.

- Repository: [Instalabs AI/instagit](https://github.com/instalabsai/instagit)
- Tags: architecture
- Published: 2026-02-16

---

**Instagit uses a Server-Sent Events (SSE) streaming architecture built on the native `fetch` API and the `eventsource-parser` library to process real-time reasoning, output text, and completion events from its `/v1/responses` endpoint.**

The SSE streaming architecture in **instalabsAI/instagit** enables low-latency, incremental delivery of AI-generated responses. By leveraging standard web streams and a robust retry mechanism, the client maintains persistent connections while providing live progress updates to the user interface.

## Core SSE Streaming Implementation in [`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts)

The primary entry point for SSE communication is the `analyzeRepoStreaming` function located in **[`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts)**. This function orchestrates the request lifecycle, from initial connection to final event parsing.

### Initializing the Stream with `analyzeRepoStreaming`

The function constructs a POST request to the `/v1/responses` endpoint with a JSON body containing `model`, `input`, and `stream: true`. The model string follows the format `repo@ref`, combining the repository identifier with an optional Git reference.

```typescript
// From src/api.ts
const response = await fetchWithRetries(() => 
  fetch(`${baseUrl}/v1/responses`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      model: `${repo}@${ref}`,
      input: prompt,
      stream: true
    })
  })
);

```

The request utilizes a **30-minute timeout** defined as `FETCH_TIMEOUT` in **[`src/retry.ts`](https://github.com/instalabsAI/instagit/blob/main/src/retry.ts)**, ensuring long-running analyses do not prematurely terminate.

### Parsing Events with `eventsource-parser`

Once the connection establishes, the response body is processed as a stream. Instagit employs the **`eventsource-parser`** library to handle low-level SSE protocol details. The `createParser` function instantiates a stateful parser that emits structured `EventSourceMessage` objects via its `onEvent` callback.

```typescript
// Conceptual flow from src/api.ts
import { createParser } from 'eventsource-parser';

const parser = createParser({
  onEvent: (event) => {
    // Handle SSEEventData types
    handleEvent(event);
  }
});

// Reading the stream
const reader = response.body.getReader();
while (!done) {
  const { value, done } = await reader.read();
  if (done) break;
  parser.feed(decoder.decode(value));
}

```

The parser continues until it encounters the `[DONE]` sentinel, signaling the end of the stream.

## Event Types and Response Handling

The SSE streaming architecture distinguishes between three primary event types defined in **[`src/types.ts`](https://github.com/instalabsAI/instagit/blob/main/src/types.ts)** as `SSEEventData`. Each event updates the internal `ProgressTracker` state and drives UI feedback.

### Reasoning Events (`response.reasoning.delta`)

When the model engages in chain-of-thought reasoning, the backend emits `response.reasoning.delta` events. These contain incremental token counts and status updates. The handler in [`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts) updates the tracker’s status text to indicate the model is "thinking" and accumulates input token estimates.

### Output Text Events (`response.output_text.delta`)

As the model generates the final response, `response.output_text.delta` events stream partial content. The handler appends each `delta` to `collectedText`, estimates output tokens based on character count, and updates the status to "Writing response…". This provides the primary content visible to the end user.

### Completion Events (`response.completed`)

The `response.completed` event signals the end of generation. It carries the final `response.usage` payload containing precise `input_tokens` and `output_tokens` counts. The handler captures these metrics to populate the final `AnalysisResult` returned to the caller.

## Resilience and Retry Mechanisms

Instagit’s SSE streaming architecture incorporates robust error handling to manage transient network failures and server errors without losing context.

### Transport Timeouts and Heartbeats

The connection respects the `FETCH_TIMEOUT` of 30 minutes defined in **[`src/retry.ts`](https://github.com/instalabsAI/instagit/blob/main/src/retry.ts)**. Additionally, if a `progressCallback` is provided, a 250ms heartbeat interval fires independently of the SSE stream. This interval queries the `ProgressTracker` state (managed in **[`src/kitt.ts`](https://github.com/instalabsAI/instagit/blob/main/src/kitt.ts)**) and invokes the callback with formatted status messages, ensuring the UI remains responsive even during model processing gaps.

### Retry Logic for Transient Failures

The outer retry loop (up to `MAX_RETRIES` = 3) in `analyzeRepoStreaming` reissues requests upon specific conditions defined in **[`src/retry.ts`](https://github.com/instalabsAI/instagit/blob/main/src/retry.ts)**:

- **Retryable HTTP status codes**: 303, 502, 503, and 504.
- **Transport-level errors**: Detected by the `isTransportError` helper.
- **Empty responses**: Treated as transient failures.

Permanent failures, specifically **security rejections** detected by `isSecurityRejection`, abort the retry loop immediately to prevent unnecessary load.

## Practical Implementation Example

The following example demonstrates how to invoke the SSE streaming architecture with live progress tracking:

```typescript
import { analyzeRepoStreaming } from "./src/api.js";

/**
 * Run an analysis with live console progress.
 */
async function run() {
  const repo = "instalabsAI/instagit";
  const prompt = "Summarize the architecture of the repository.";
  const token = process.env.INSTAGIT_API_KEY; // optional

  // Optional progress UI – here we just log to the console.
  const progressCallback = async (msg: string) => {
    console.clear();
    console.log(msg);
  };

  const result = await analyzeRepoStreaming({
    repo,
    prompt,
    token,
    progressCallback,
  });

  console.log("\n=== RESULT ===");
  console.log(result.text);
}
run().catch(console.error);

```

This implementation leverages the `ProgressTracker` from **[`src/kitt.ts`](https://github.com/instalabsAI/instagit/blob/main/src/kitt.ts)** to provide real-time feedback while the SSE streaming architecture handles the underlying event parsing and retry logic.

## Summary

- Instagit’s **SSE streaming architecture** centers on the `analyzeRepoStreaming` function in **[`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts)**, which manages the full lifecycle of Server-Sent Events connections.
- The system uses **`eventsource-parser`** to decode raw SSE chunks into structured `EventSourceMessage` objects, handling three distinct event types: `response.reasoning.delta`, `response.output_text.delta`, and `response.completed`.
- A **30-minute timeout** and **250ms heartbeat interval** ensure the connection remains stable while providing live UI updates via the `ProgressTracker` in **[`src/kitt.ts`](https://github.com/instalabsAI/instagit/blob/main/src/kitt.ts)**.
- Robust **retry logic** (up to 3 attempts) handles transient HTTP errors (303, 502-504) and transport failures, while permanent security rejections trigger immediate termination.

## Frequently Asked Questions

### What is the SSE streaming architecture in Instagit?

The SSE streaming architecture in Instagit is a client-side implementation that uses the native `fetch` API to establish a persistent connection to the `/v1/responses` endpoint. It leverages the `eventsource-parser` library to parse incoming Server-Sent Events and processes three specific event types—reasoning deltas, output text deltas, and completion signals—to stream incremental results back to the user interface.

### How does Instagit handle different response event types?

Instagit distinguishes between event types defined in [`src/types.ts`](https://github.com/instalabsAI/instagit/blob/main/src/types.ts) as `SSEEventData`. For `response.reasoning.delta` events, it updates the internal status to indicate the model is processing. `response.output_text.delta` events append incremental content to the accumulated response text. Finally, `response.completed` events capture final token usage statistics and signal the stream to terminate upon receiving the `[DONE]` sentinel.

### What retry mechanisms exist for failed SSE connections?

The retry mechanism is implemented in [`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts) with support for up to three attempts defined by `MAX_RETRIES` in [`src/retry.ts`](https://github.com/instalabsAI/instagit/blob/main/src/retry.ts). It automatically reissues requests for HTTP status codes 303, 502, 503, and 504, as well as transport-level errors detected by `isTransportError`. Empty responses are treated as transient failures, while permanent security rejections identified by `isSecurityRejection` abort the retry loop immediately.

### How can I implement progress tracking in my Instagit integration?

To implement progress tracking, provide a `progressCallback` function when calling `analyzeRepoStreaming`. This callback receives formatted status strings generated by the `ProgressTracker` class in [`src/kitt.ts`](https://github.com/instalabsAI/instagit/blob/main/src/kitt.ts). The system fires a 250ms heartbeat interval that queries the tracker state during streaming, allowing you to display real-time updates such as "Thinking…" or "Writing response…" while the SSE connection remains active.