Advisor sessions

Full diagnosis path: classify → agent tool loop → diagnosis (or pause for manager answers).

Redoc: Advisor tag.
Worked example: Live test run.

Start

POST /api/advisor/sessions

{ "problem_statement": "sales are down across the board" }

201 body (data):

Field	Meaning
session_id	Opaque id
status	diagnosing | awaiting_manager | concluded | …
playbook_ids	Selected playbooks
hypothesis_board	Live board (hypothesis_id, status, evidence_note)
pending_questions	Present when status is awaiting_manager
diagnosis	Present when concluded
verify_after	YYYY-MM-DD verification date
query_count / ask_count	Caps usage
stop	Why the loop returned: concluded | awaiting_manager | max_turns | model_stop
classify	{ playbook_ids, source } from the classifier

Diagnosis object

{
  "finding": "…",
  "confidence": "confirmed | likely_unconfirmed",
  "evidence": ["…"],
  "actions": [
    {
      "rec_id": "lapsed-customer-winback",
      "summary": "…",
      "effort": "low",
      "expected_impact": "…"
    }
  ],
  "verification": {
    "check_after_days": 14,
    "probe_ids": ["dd-01"]
  }
}

Get

GET /api/advisor/sessions/{id} — snapshot only (does not re-run the agent).

Resume (after ask_manager)

When status === "awaiting_manager":

POST /api/advisor/sessions/{id}/answers

{
  "answers": [
    { "probe_id": "q1", "answer": "We ran a DoorDash promo last month" }
  ]
}

Returns the same session view after the loop continues.

409 if the session is not awaiting answers.

Status lifecycle

intake → diagnosing ─┬─► awaiting_manager ─(answers)─► diagnosing ─► …
                   └─► concluded (+ diagnosis, verify_after)

Caps (defaults)

Cap	Default	File
query_data calls	8	src/application/agent/constants.ts
ask_manager calls	3	same
LLM turns / run	24	same

Mock vs live behavior

Adapter set	Typical start result
All mock	Often concluded in one request (scripted tools)
OpenAI investigate	May ask manager; use resume
QueryCraft query	Real SQL/rows inside query_data

Not built yet

• Scheduled verification job (~14 days)
• Notify webhook when verification is due
• SSE streaming of tool events (sync JSON only today)