Architecture

This page describes the technical design of the Interactive Interview system. Most platform users only need the Running an Interview and Configuration pages - this page is for operators, developers, and anyone debugging the interview infrastructure.

Overview

An interview is an in-pool interactive run of the donmai runtime in a mode that exposes a streaming chat API instead of a code-execution session. The runner runs inside the same capacity-pool sandbox as code-authoring agents - the only difference is the run mode flag (interactive) that swaps the agent's tool set and disables repository access.

Browser (participant)
    ↕  SSE + POST (AI SDK streaming)
Platform API  /api/interview/*
    ↕  relay
donmai runtime (in-pool sandbox, interactive mode)
    ↓  User-Spec on completion
Platform  (issue creation, trigger dispatch)

Token streaming

The chat interface uses the Vercel AI SDK streaming format. The platform's /api/interview/stream route acts as a relay:

1. The browser sends a POST with the participant's message.
2. The relay forwards it to the donmai runtime's POST /session/prompt endpoint inside the sandbox.
3. The runner's response is a chunked SSE stream of AI SDK text-delta and tool-call events.
4. The relay pipes the stream directly to the browser response without buffering.

This architecture keeps the model's tokens flowing at wire speed - the participant sees the agent typing in real time, with no artificial delay from an intermediate response assembly step.

Stream format

The relay emits standard AI SDK stream events:

data: {"type":"text-delta","textDelta":"What "}
data: {"type":"text-delta","textDelta":"does "}
data: {"type":"text-delta","textDelta":"your "}
...
data: {"type":"finish","finishReason":"stop"}

Phase advancement events are emitted as tool-call events on the stream so the browser can update the live spec panel in sync with the agent's output:

data: {"type":"tool-call","toolName":"phase.advance","args":{"phase":2,"summary":"..."}}

The rensei.wait gate handoff

At the end of each interview phase the runner emits a rensei.wait gate signal to pause execution and wait for the participant's acknowledgment before advancing. This is the same gate mechanism used in workflow approvals, applied here to drive the phase-by-phase conversation flow:

The gate timeout for interview phases is configurable (default: 30 minutes). If the participant does not advance within the timeout window, the interview is paused and the runner suspends cleanly. The participant can resume from the same URL within the session retention window (24 hours by default).

Sandbox lifecycle

Startup

When a participant opens the interview page, the platform:

1. Checks the access grant for the participant + project combination.
2. Resolves the org's interview model profile.
3. Claims a worker from the capacity pool matched to the profile's auth mode.
4. Starts the donmai runtime in interactive mode inside the sandbox, passing the project context and the org's model profile credentials.
5. Returns the interview session ID to the browser.

The startup sequence typically completes in 2-5 seconds depending on the capacity pool and auth mode. A loading indicator is shown until the first token arrives.

Extended timeout

Standard agent sessions have a default inactivity timeout. Interview sandboxes use an extended timeout to accommodate the natural pauses in a human conversation - a participant might step away to check notes or consult a colleague between phases. The extended timeout is set at sandbox allocation time and is not configurable per interview.

Pause and resume

When a participant closes the browser tab, the runner enters a paused state at the current rensei.wait gate. The sandbox is kept alive for the session retention window. When the participant returns:

1. The browser sends a resume request to /api/interview/resume.
2. The platform re-establishes the SSE stream to the paused runner.
3. The runner replays the last phase summary card and prompts the participant to continue.

If the sandbox has been reclaimed (e.g. the retention window expired or the pool was exhausted), the platform starts a new runner and replays the completed phases from the saved state before prompting for continuation.

Shutdown

After the participant clicks Send to Rensei:

1. The runner emits the final spec.complete event with the full User-Spec.
2. The relay writes the spec to the platform database.
3. The runner exits cleanly, releasing the sandbox back to the pool.
4. The platform creates the issue and triggers the interview-v1 template.

Observability

Health endpoint

The /api/interview/health endpoint returns the current state of the interview infrastructure:

curl https://app.rensei.ai/api/interview/health

{
  "status": "ok",
  "poolAvailable": true,
  "activeInterviews": 3,
  "relayLatencyMs": 12
}

Logs and traces

Interview events are written to audit_events with entityType = 'interview'. Each phase transition, spec submission, and participant action is a distinct audit event row. Use the Vercel runtime logs for the relay latency and stream error details.

List interview audit events via the org-scoped audit API (the rensei audit CLI covers attestations and the audit chain, not entity-filtered event listing):

curl "https://rensei.ai/api/audit?entityType=interview" \
  -H "Authorization: Bearer rsk_live_..."

Session activities

Interview runs do not produce session_activities rows (those are for code-authoring sessions). The authoritative activity record for an interview is the sequence of audit_events rows.

Security model

• The relay authenticates the participant via the platform session cookie or rsk_* Bearer token before forwarding any request to the runner.
• The runner operates with read-only access to the project context; it cannot write to repositories or create issues (issue creation is handled by the platform after spec completion, not by the runner).
• The spec content is stored encrypted at rest. It is never written to the platform's external-facing logs.

Related Pages

• Overview - end-to-end feature overview
• Running an Interview - participant experience
• Configuration - model profile and auth mode selection
• Capacity Pools - how the platform resolves and manages worker capacity
• Session Detail - the equivalent observability surface for code-authoring sessions