Skip to content

Feature: distinguish human vs. scheduled turns on the wire (turn trigger) #724

Description

@akandola

Problem

Consumers of the event stream can't tell whether a turn was human-initiated or
scheduled/event-driven. Both paths converge on the same runtime route — the scheduled
path (ProxyChannel.fireTurn) POSTs to /conversations/:id/messages, the same route a human
message uses — with no marker distinguishing them. acting-user doesn't cleanly separate
them (single-player humans have none; legacy routines lack acting-user). So there's
currently no way, on the wire, to know a turn's origin.

Why it matters

For observability/analytics consumers, distinguishing autonomous (scheduled/event-driven)
runs from human-initiated ones matters — e.g. reasoning about how much an agent does
unattended. Today that's invisible downstream.

Proposed approach (open to your preference)

Introduce an internal turn-source signal and surface it on the wire. One option: a
x-houston-turn-source: human | scheduled header set by each channel profile (the
scheduled path → scheduled; the human path → human), threaded through start-turn /
TurnRequest.source, and emitted — e.g. as a third field on the turn_start event we're
adding in the PR below, or its own frame.

This touches ~6 files across host + runtime and introduces a new internal convention, so
per CONTRIBUTING we're raising it as an issue first before implementing. Happy to build it
whichever way fits best — a header, a request-body field, a TurnRequest.source, etc. What
mechanism aligns with how you think about the turn path?

Pairs with the PR we're opening now that adds turn_start with provider + model; trigger
is the natural third field but needs this cross-layer plumbing, so we split it out.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions