niche_session_state

com.nicheangle/niche · Verify this server

Universal poll endpoint: read the full current state of a session. Returns status, ranked stories, picked story_id, generated angles, picked angle_id, draft outputs (with trust fields), and an elicitation hint for whatever decision is next. Call this whenever you need to check progress; it's safe and cheap. Each story includes title, summary, headline_candidate (the post-shaped headline distinct from the cluster title), recency_score, relevance_score, freshness_label, and the publication_breakdown of contributing outlets (provenance). Each story also carries a recommended_story_id plus recommendation_reason before a pick. Each draft output's trust data lives under `outputs[i].trust.*` (verifier_blocked_reason, source_faithfulness_score, source_ungrounded_claims, source_diversity_passed, source_recency_passed, source_distinct_count, plus a flags[] array with explicit severity and source_grounding_map). The output top level does not mirror these; read them from `.trust`. Response also includes `phase` (high-level: scanning / drafting / filed / spiked / awaiting), `phase_message` (a rotating gerund, e.g. 'Reading 337 signals'), and `phase_hint` (a one-line agent-facing tooltip with a typical timing band, e.g. 'Clustering, usually 8-15s, no action needed'). The full 17-status state machine is enumerated under `status_glossary` so you can introspect what every state means without discovering it experimentally. For a terminal run, read `outcome` (complete / expired / interrupted / cancelled / failed) rather than the raw `status`: a `failed` status is usually an expired walk-away (a slate was produced) or a refunded interruption, not a real error. Recommended loop: kick off work, then one niche_session_state(wait:30, wait_until:'checkpoint') per stage. It sleeps through the noisy transient statuses (clustering, ranking, generating_*) and wakes only at the next actionable stop (cpN_awaiting_* / complete / failed), or when an async render settles. So a full run is one wait per checkpoint, not several wakes per stage. (`wait_for` is an accepted alias for `wait_until`.) The `wait` plus `since_status` long-poll (wait_until:'change', wakes on any status change) is also supported; prefer 'checkpoint'. Each status' `actionable` flag in `status_glossary[]` indicates which states a 'checkpoint' wait wakes for. Avoid polling every few seconds without `wait`, which may be rate-limited (HTTP 429). niche_story_search is an accepted alias for this tool. Response shape is sparse by default: after a story is picked, only the picked story is returned (not all candidates); same for angles. Set include_unpicked=true to get the full candidate set, useful when revising to a different story or angle. A `sparse_mode` field in the response reports how many items were dropped.