feat(tui_gateway): client-identity source so desktop/dashboard/mobile aren't all "tui"

[Kyzcreig]

Problem

The desktop app, the in-browser dashboard chat, and the Ink stdio TUI all drive the same tui_gateway JSON-RPC server, which hardcoded platform="tui" on every agent it built. So every desktop-app turn records platform="tui" in blackbox (turns.platform) — the source dimension on the token/cost dashboard can't tell the desktop client from the terminal, and a future mobile app would fold in too.

Verified against a live install: api_server/desktop never appear in any blackbox DB; desktop chat rides /api/ws → tui_gateway.dispatch (same path as Ink over stdio), so it inherits the "tui" label.

Fix

• A client self-declares a source on session.create/session.resume.
• Thread it through _make_agent → AIAgent(platform=...) (which already feeds the blackbox on_session_end hook) and store it on the session dict so the deferred/lazy build, /new reset, resume, and branch paths all preserve it (they previously reset to "tui").
• source is untrusted client input feeding a persisted DB dimension, so it's sanitized to a conservative slug (^[a-z][a-z0-9_-]{0,23}$) with a tui fallback. The label stays open-ended (new clients name themselves; no central enum — per the existing "fixed set of platform names goes stale" note in this file).
• Desktop app: stamp source:'desktop' once, centrally, in the requestGateway wrapper for the session-originating methods — never overriding an explicit caller source (e.g. the dashboard sidecar's 'tool').

No schema/blackbox change (the platform pipe already existed). Stdio Ink and internal rebuilds keep the historical "tui" default, so nothing regresses. Cache-safe: the label is fixed per session, set before agent creation, never mutated mid-conversation.

No backfill possible: historical desktop turns are indistinguishable from real TUI turns, so the clean split starts at deploy.

Tests

• tests/tui_gateway/test_client_source_platform.py — sanitizer table (case/trim/reject-hostile) + _make_agent platform derivation (declared → platform; None → tui; hostile → tui).
• apps/desktop/src/app/gateway/hooks/use-gateway-request.test.tsx — injection contract: stamps create/resume, skips other methods, never overrides an explicit source.
• Updated test_protocol.py fakes to accept the new _make_agent(source=...) kwarg.
• 125/125 green across every touched tui_gateway suite (deterministic run); desktop vitest 4/4; tsc --noEmit clean.

[greptile-apps]

Greptile Summary

This PR adds a source field to session.create/session.resume so that the desktop app, dashboard SPA, and Ink stdio TUI — all sharing the same tui_gateway JSON-RPC server — are individually attributed in the blackbox turns.platform dimension instead of all recording as "tui".

• tui_gateway/server.py: Introduces _sanitize_client_source (slug regex + isinstance guard) and threads the sanitized value through _make_agent, _init_session, _reset_session_agent, deferred builds, resume, and branch handlers.
• apps/desktop/…/use-gateway-request.ts: Stamps source:'desktop' on session-originating RPCs only, without overriding an explicit caller-supplied value.
• Tests: New test_client_source_platform.py covers the sanitizer table (including the boolean/integer edge cases flagged in the previous review) and _make_agent platform derivation; desktop vitest covers the injection contract.

Confidence Score: 5/5

Safe to merge. The change is additive: existing sessions fall back to tui, no schema changes, and the sanitizer is conservative with proper type-guarding.

The sanitizer correctly uses isinstance(raw, str) instead of the old falsy-coercion pattern, closing the boolean edge case flagged in the prior review. All session-lifecycle paths consistently propagate the label. Tests cover the hostile inputs exhaustively.

No files require special attention.

Important Files Changed

Filename	Overview
tui_gateway/server.py	Core change: adds _sanitize_client_source with a proper isinstance guard, threads source through all session-lifecycle paths (create, deferred build, resume, /new reset, branch). Logic is sound and edge cases are well-covered.
apps/desktop/src/app/gateway/hooks/use-gateway-request.ts	Adds CLIENT_SOURCE constant and SESSION_ORIGIN_METHODS set; injects source:'desktop' on create/resume only, preserving explicit caller values. The outbound variable is correctly shared between the primary and recovery request paths.
tests/tui_gateway/test_client_source_platform.py	New test file covering the sanitizer table (including True and 0 edge cases from the previous review thread) and _make_agent platform derivation. Test coverage is thorough.
apps/desktop/src/app/gateway/hooks/use-gateway-request.test.tsx	New tests for the injection contract: stamps on create/resume, skips other methods, never overrides an explicit caller source. Contract is well-pinned.
tests/tui_gateway/test_protocol.py	Existing fakes updated with **_kw to accept the new source= keyword argument — mechanical, correct.
tests/test_tui_gateway_server.py	Three monkeypatched _make_agent lambdas updated with **_kw — mechanical, correct.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client as Client (desktop/dashboard/Ink)
    participant Hook as useGatewayRequest
    participant GW as tui_gateway/server.py
    participant San as _sanitize_client_source
    participant Agent as AIAgent(platform=...)

    Client->>Hook: "session.create({ cols:96 })"
    Hook->>Hook: SESSION_ORIGIN_METHODS has method AND no explicit source?
    Hook->>GW: "session.create({ cols:96, source:"desktop" })"
    GW->>San: _sanitize_client_source("desktop")
    San-->>GW: "desktop"
    GW->>GW: "_sessions[sid]["source"] = "desktop""
    GW->>GW: _schedule_agent_build(sid)
    GW-->>Client: "{ session_id, stored_session_id }"

    Note over GW: Deferred build (lazy)
    GW->>San: _session_source(current) returns desktop
    GW->>Agent: "_make_agent(sid, key, source=desktop)"
    Agent-->>GW: "AIAgent(platform=desktop)"

    Client->>Hook: "session.resume({ session_id:s1 })"
    Hook->>GW: "session.resume({ session_id:s1, source:desktop })"
    GW->>San: _sanitize_client_source(params source or found source)
    San-->>GW: desktop
    GW->>Agent: "_make_agent with source=desktop"
    GW->>GW: "_init_session with source=desktop"

    Client->>GW: /new reset_session_agent
    GW->>San: _session_source(session) returns desktop
    GW->>Agent: "_make_agent with source=desktop"

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Client as Client (desktop/dashboard/Ink)
    participant Hook as useGatewayRequest
    participant GW as tui_gateway/server.py
    participant San as _sanitize_client_source
    participant Agent as AIAgent(platform=...)

    Client->>Hook: "session.create({ cols:96 })"
    Hook->>Hook: SESSION_ORIGIN_METHODS has method AND no explicit source?
    Hook->>GW: "session.create({ cols:96, source:"desktop" })"
    GW->>San: _sanitize_client_source("desktop")
    San-->>GW: "desktop"
    GW->>GW: "_sessions[sid]["source"] = "desktop""
    GW->>GW: _schedule_agent_build(sid)
    GW-->>Client: "{ session_id, stored_session_id }"

    Note over GW: Deferred build (lazy)
    GW->>San: _session_source(current) returns desktop
    GW->>Agent: "_make_agent(sid, key, source=desktop)"
    Agent-->>GW: "AIAgent(platform=desktop)"

    Client->>Hook: "session.resume({ session_id:s1 })"
    Hook->>GW: "session.resume({ session_id:s1, source:desktop })"
    GW->>San: _sanitize_client_source(params source or found source)
    San-->>GW: desktop
    GW->>Agent: "_make_agent with source=desktop"
    GW->>GW: "_init_session with source=desktop"

    Client->>GW: /new reset_session_agent
    GW->>San: _session_source(session) returns desktop
    GW->>Agent: "_make_agent with source=desktop"

Loading

_{Reviews (3): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}