Configure Replay URL

https://abc123.ngrok-free.app

https://abc123.ngrok-free.app/replay

You are making this Langfuse-instrumented agent replayable for Kindred.

Goal:
Add or verify a POST /replay endpoint that Kindred can call to rerun a selected agent turn, then run it locally, expose it with a public HTTPS URL (tunnel or deployed endpoint), and report the exact URL to paste into the Kindred console.

Mental model:
Kindred calls POST /replay with the original input and replay metadata. The replay uses the existing agent execution path, creates a new Langfuse trace, and preserves kindred_replay_run_id so Kindred can find that replay trace.

Hard constraints:
- Make the smallest working patch.
- Do not refactor the app.
- Do not create fake agents.
- Do not create eval harnesses.
- Do not create demo-only paths.
- Do not add unrelated tests or features.
- Reuse the existing agent execution path.
- Keep Langfuse instrumentation attached to replay runs.
- Do not hardcode secrets.

Tasks:

1. Find the real agent entrypoint.

Identify the existing function, route, graph, chain, or handler that runs one user turn. Prefer the production path already used by the app.

2. Add or verify POST /replay.

The endpoint must:
- accept JSON
- support either messages or input
- prefer messages when both are present
- call the same agent execution path used for normal turns
- return JSON

Do not implement replay with a mock response or a separate demo agent.

3. Preserve replay metadata.

When a replay request includes these body fields, preserve them in Langfuse metadata for the replay trace:
- kindred_replay_run_id
- kindred_original_session_id
- kindred_include_prior_context
- kindred_turn_trace_id
- is_replay

Also accept these headers and map them into the same metadata:
- X-Kindred-Replay
- X-Kindred-Replay-Run-Id
- X-Kindred-Original-Session-Id
- X-Kindred-Turn-Trace-Id
- X-Kindred-Include-Prior-Context

The replay trace must include kindred_replay_run_id.
Put replay metadata on the Langfuse trace or propagated attributes, not only on an HTTP response, because Kindred finds the replay by polling Langfuse traces for kindred_replay_run_id.

4. Preserve normal Kindred metadata too.

The replay trace should still include:
- agent_id: the value of KINDRED_AGENT_ID
- session_id: a stable replay session id
- run_id: a unique id for this replay turn

5. Return useful replay JSON.

Return the agent result as JSON. Include these fields if available:
- session_id
- run_id
- kindred_replay_run_id
- output or assistant response

6. Flush Langfuse if needed.

If the app runs in a short-lived serverless function, job, script, or local process, flush Langfuse before returning the replay response.

7. Verify the smallest replay path.

Run the relevant formatter, typecheck, tests, or a local smoke test if this repo supports them.

8. Start the local server.

Start the app or agent server locally if dependencies and required environment variables are available.
If the app already has a dev or server command, use it.
If there is no obvious command, identify the command the user should run.

Confirm the local POST /replay endpoint returns JSON before moving on.

9. Expose the replay endpoint with a public HTTPS URL.

If a tunnel tool is installed, expose the local server port. Options include ngrok and Cloudflare Tunnel.
Use the actual local port used by the app.

Example:

ngrok http <PORT>

If your preferred tunnel tool is not installed or cannot run in this environment, say that clearly and give the exact command the user should run.

When the tunnel is running, report the public HTTPS replay URL to paste into Kindred as Target URL (replay_url). Include /replay if the endpoint uses that path.

Example:

https://abc123.ngrok-free.app/replay

After patching, report:
- files changed
- command to run the local server
- the replay URL path
- a curl command for POST /replay with is_replay and kindred_replay_run_id
- whether the replay endpoint returned JSON
- how to verify the replay trace includes kindred_replay_run_id
- whether the tunnel is running
- the exact public HTTPS replay URL to paste into the Kindred console

Do the code changes directly. Do not stop at a plan.

kindred_replay_run_id
kindred_original_session_id
kindred_include_prior_context
kindred_turn_trace_id
is_replay

X-Kindred-Replay
X-Kindred-Replay-Run-Id
X-Kindred-Original-Session-Id
X-Kindred-Turn-Trace-Id
X-Kindred-Include-Prior-Context

{
  "session_id": "replay-session-id",
  "run_id": "replay-run-id",
  "kindred_replay_run_id": "kindred-replay-run-id"
}