Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

39.6 KB
Raw Blame
"""Conversational company setup — the interview loop behind ``/onboard``.

The user describes their business in their own words; this module asks
a few quick questions (each with suggested answers to tap) until it can draft
a company profile, the people, this year's goals with an owner on each, and
departments when the user's own words already list people by department. Nothing is written anywhere: ``advance``
returns either a ``Question`` or a ``CompanyDraft``, and the route owns both
the session state and the single write (see ``onboarding/commit.py``).

Shape notes for anyone changing this file:

* **The tool array is CONSTANT.** Both tools are present on every call, sorted
  by name. Adding a tool partway through a conversation invalidates the cached
  tool prefix on every subsequent turn — the same invariant
  ``orchestrator/form_tools.py`` documents. ``tool_choice={"type": "any"}``
  lets the model pick which one to call without varying the array.

* **``tool_choice`` flips exactly once**, on the turn where the question budget
  is spent or the caller forces a draft. That single call misses the tools
  cache; one miss per onboarding session is the price of a bounded interview.
  This is deliberate — do not "fix" it by making the tools conditional.

* **The system block is a constant**, never f-stringed. An existing profile is
  rendered into the first USER turn via ``to_prompt_block()``, never into the
  cached system block — and so is the solo hint (``solo_hint``: one constant
  per role kind) when the workspace is in solo mode. This module does not touch ``prompts/cache_manager.py``,
  so the "exactly 2 cache_control blocks" budget there is unaffected.

* **Errors never echo model or user input.** A ``ValidationError``'s ``str()``
  embeds the offending values, which here are the user's ARR, burn, and
  runway. ``InterviewError`` messages are fixed strings; the detail goes to the
  log as a type name only. (``fixtures/generator.py`` interpolates the
  exception into its ``GenerationError`` — do not copy that here.)
"""
from __future__ import annotations

import asyncio
import json
import logging
from dataclasses import dataclass
from typing import Any

from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator

from openexecutive.agents.onboarding_interviewer import (
    ONBOARDING_INTERVIEWER_AGENT_ID,
    OnboardingInterviewerAgent,
)
from openexecutive.config import get_settings
from openexecutive.departments.models import AuthorityLevel
from openexecutive.memory.company_profile import CompanyProfile
from openexecutive.utils.slug import DEPARTMENT_SLUG_FALLBACK, slugify

logger = logging.getLogger(__name__)

# Budgets. The user can always short-circuit with force_draft, so these only
# bound a runaway model. Setup asks two to four quick questions.
MAX_QUESTIONS = 4
# Must stay above what a single legal /start can produce — a 20k description
# plus 8 attachments at 15k extracted chars each is ~140k. A lower ceiling
# locked the user out of the conversation on turn one for doing exactly what
# the UI invites ("you can also attach a deck").
MAX_TRANSCRIPT_CHARS = 250_000

# Field bounds. Enforced here rather than with Field(max_length=...) so a
# rejection reports a fixed string instead of echoing the offending value
# back in FastAPI's 422 body — these drafts carry the company's financials.
MAX_NAME_CHARS = 200
MAX_ROLE_CHARS = 200
MAX_MISSION_CHARS = 2000
# The profile is rendered into the CACHED system prompt on every Executive
# turn (see CLAUDE.md), so an unbounded field here is a permanent cost on
# every request, not just one big row.
MAX_PROFILE_TEXT_CHARS = 10_000

_MAX_TOKENS = 8000
# Truncation for the repair turn that echoes the model's own bad output back at
# it. Same value fixtures/generator.py uses inline; the two are independent, so
# changing this one does not change that one.
_REPAIR_ECHO_CHARS = 2000

_MAX_PROSE_QUESTION_CHARS = 1000

# Suggested answers shown under a question as buttons to tap.
MAX_OPTIONS = 4
MAX_OPTION_CHARS = 120
# This year's goals in a draft. More than this is a plan, not setup.
MAX_GOALS = 12
MAX_GOAL_CHARS = 300

ASK_TOOL_NAME = "ask_clarifying_question"
EMIT_TOOL_NAME = "emit_company_draft"

# The first thing the user sees. A constant, so /onboard/interview/start costs
# no model call and cannot fail.
# Sent when the transcript would otherwise end on an assistant turn.
_CONTINUE_PROMPT = (
    "Continue from what you already have: ask the next question, or draft "
    "the profile if you have enough."
)

OPENING_PROMPT = (
    "Tell me about your company — what you do, who you sell to, roughly how "
    "big you are, and what you're focused on this year. Write it however you "
    "like; I'll ask about anything I'm missing. You can also attach a deck, "
    "a one-pager, or anything else that describes the business."
)


class InterviewError(RuntimeError):
    """Interview could not produce a question or a draft.

    The message is always a fixed, input-free string safe to return to the
    client — see the module docstring.
    """


class InterviewTimeout(InterviewError):
    """The provider did not respond within the configured wall clock."""


class Turn(BaseModel):
    """One stored conversation turn.

    Stored as plain text rather than raw API blocks: the history is replayed
    as ordinary user/assistant text turns, so there are no tool_use /
    tool_result pairs to keep consistent across a restart or a repair retry.
    """

    role: str  # "user" | "assistant"
    text: str


class PersonDraft(BaseModel):
    # extra="ignore" is load-bearing: it drops any email address or chat handle
    # the model emits despite the system prompt forbidding them, so a contact
    # can never be auto-imported. Same invariant fixture/engagement drafts hold.
    model_config = ConfigDict(extra="ignore")

    full_name: str
    role: str = ""
    is_principal: bool = False


class DepartmentDraft(BaseModel):
    model_config = ConfigDict(extra="ignore")

    title: str
    mission: str = ""
    head_person_name: str = ""
    authority_level: AuthorityLevel = AuthorityLevel.PROPOSE_ONLY


class GoalDraft(BaseModel):
    """One of this year's goals. Saved with an owner and, only when the
    draft has departments, optionally inside one (see commit.py)."""

    model_config = ConfigDict(extra="ignore")

    title: str
    target: str = ""
    # A person's full_name from the draft; empty = the principal.
    owner_name: str = ""
    # A drafted department's title; empty = no department.
    department_title: str = ""

    @field_validator("target", "owner_name", "department_title", mode="before")
    @classmethod
    def _no_null(cls, value: Any) -> Any:
        return "" if value is None else value


class CompanyDraft(BaseModel):
    profile: CompanyProfile
    people: list[PersonDraft] = Field(default_factory=list)
    departments: list[DepartmentDraft] = Field(default_factory=list)
    goals: list[GoalDraft] = Field(default_factory=list)
    confidence_notes: list[str] = Field(default_factory=list)
    summary: str = ""


class Question(BaseModel):
    question: str
    hint: str = ""
    # Suggested answers the user can tap instead of typing.
    options: list[str] = Field(default_factory=list)

    @field_validator("hint", mode="before")
    @classmethod
    def _no_null_hint(cls, value: Any) -> Any:
        # Models sometimes send "hint": null for "no example"; that is not a
        # reason to throw the whole question away.
        return "" if value is None else value

    @field_validator("options", mode="before")
    @classmethod
    def _tidy_options(cls, value: Any) -> Any:
        # Lenient like the hint: a bad option list costs the buttons, never
        # the question. Blank, overlong and repeated options are dropped.
        if not isinstance(value, list):
            return []
        out: list[str] = []
        for item in value:
            text = item.strip() if isinstance(item, str) else ""
            if text and len(text) <= MAX_OPTION_CHARS and text not in out:
                out.append(text)
        return out[:MAX_OPTIONS]


@dataclass(frozen=True)
class DraftError:
    """One validation failure, in two renderings.

    ``detail`` quotes the offending value — useful to the model in the repair
    turn, and NEVER safe in an HTTP body, because a rejected name or head
    reference is client-supplied text sitting next to the company's
    financials. ``safe`` is the fixed string the route returns.
    """

    safe: str
    detail: str


_ASK_TOOL: dict[str, Any] = {
    "name": ASK_TOOL_NAME,
    "description": (
        "Ask the user ONE quick question about their company, with suggested "
        "answers they can tap. Use this only while something material is "
        "still missing — the user reviews and edits the draft before it is "
        "saved, so an early draft beats a long interview."
    ),
    "input_schema": {
        "type": "object",
        "required": ["question"],
        "properties": {
            "question": {
                "type": "string",
                "description": "One question, in plain language, to the user.",
            },
            "hint": {
                "type": "string",
                "description": (
                    "Optional one-line nudge shown under the question — why "
                    "you're asking, or an example answer."
                ),
            },
            "options": {
                "type": "array",
                "items": {"type": "string"},
                "maxItems": MAX_OPTIONS,
                "description": (
                    "Two to four short suggested answers, shown as buttons to "
                    "tap. Base them on what the user already said. The user "
                    "can always type their own answer or skip."
                ),
            },
        },
    },
}

_EMIT_TOOL: dict[str, Any] = {
    "name": EMIT_TOOL_NAME,
    "description": (
        "Emit the draft company profile, people, this year's goals and (only "
        "when the user listed people by department) departments for the user "
        "to review and edit. Exactly one person must have is_principal=true "
        "(the user). Every head_person_name and owner_name must exactly match "
        "a person's full_name or be empty. Leave anything the user did not "
        "state null or empty — never guess a number."
    ),
    "input_schema": {
        "type": "object",
        "required": ["profile", "people", "summary"],
        "properties": {
            "profile": {
                "type": "object",
                "description": "The company profile that grounds every answer the Executive gives.",
                "required": ["name"],
                "properties": {
                    "name": {"type": "string"},
                    "industry": {"type": "string"},
                    "stage": {
                        "type": "string",
                        "description": "e.g. 'Bootstrapped', 'Seed', 'Series B', 'Private / PE-backed'.",
                    },
                    "founding_year": {"type": "integer"},
                    "headcount": {"type": "integer"},
                    "annual_revenue_arr": {
                        "type": "number",
                        "description": "Annual revenue / ARR in USD (a number, not a string). Omit if not stated.",
                    },
                    "mission": {"type": "string"},
                    "vision": {"type": "string"},
                    "target_customer": {
                        "type": "object",
                        "properties": {
                            "profile": {"type": "string"},
                            "pain_points": {"type": "array", "items": {"type": "string"}},
                        },
                    },
                    "competitive_landscape": {
                        "type": "object",
                        "properties": {
                            "primary_competitors": {"type": "array", "items": {"type": "string"}},
                            "competitive_advantages": {"type": "array", "items": {"type": "string"}},
                        },
                    },
                    "strategic_priorities": {
                        "type": "object",
                        "properties": {
                            "current_year": {"type": "array", "items": {"type": "string"}},
                            "north_star_metric": {"type": "string"},
                        },
                    },
                    "culture": {
                        "type": "object",
                        "properties": {
                            "values": {"type": "array", "items": {"type": "string"}},
                            "operating_principles": {"type": "array", "items": {"type": "string"}},
                        },
                    },
                    "financials": {
                        "type": "object",
                        "properties": {
                            "burn_rate_monthly": {"type": "number"},
                            "runway_months": {"type": "number"},
                            "key_metrics": {
                                "type": "object",
                                "description": "Flat map of metric name -> value.",
                            },
                        },
                    },
                    "org_structure": {
                        "type": "object",
                        "description": (
                            "Narrative org summary. Leave empty — it is derived "
                            "from `people` and `departments` when the user saves."
                        ),
                        "properties": {
                            "departments": {"type": "array", "items": {"type": "string"}},
                            "leadership_team": {"type": "array", "items": {"type": "string"}},
                        },
                    },
                    "vendors": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": (
                            "External vendors/suppliers the company depends on. Listing "
                            "one authorizes the Executive to watch its public status and "
                            "news without asking, so include only real dependencies."
                        ),
                    },
                    "tickers": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": (
                            "Public company ticker symbols that matter to this business "
                            "(a listed competitor, customer, or supplier). Same watch "
                            "semantics as `vendors`."
                        ),
                    },
                },
            },
            "people": {
                "type": "array",
                "description": (
                    "The leadership team as named by the user. EXACTLY ONE must have "
                    "is_principal=true — the user themselves. Do NOT include email "
                    "addresses or chat handles."
                ),
                "items": {
                    "type": "object",
                    "required": ["full_name"],
                    "properties": {
                        "full_name": {"type": "string"},
                        "role": {"type": "string", "description": "e.g. 'CEO', 'Head of Sales'."},
                        "is_principal": {
                            "type": "boolean",
                            "description": "True for the user who is setting this up. Exactly one person.",
                        },
                    },
                },
            },
            "departments": {
                "type": "array",
                "description": (
                    "Only when the user's own words or files already list people "
                    "by department; otherwise empty. Titles must be distinct. "
                    "head_person_name must match a person's full_name exactly, or be empty."
                ),
                "items": {
                    "type": "object",
                    "required": ["title"],
                    "properties": {
                        "title": {"type": "string", "description": "e.g. 'Finance', 'Customer Success'."},
                        "mission": {"type": "string", "description": "One sentence on what this function owns."},
                        "head_person_name": {"type": "string"},
                        "authority_level": {
                            "type": "string",
                            "enum": [level.value for level in AuthorityLevel],
                            "description": "Default 'propose_only' unless the user says otherwise.",
                        },
                    },
                },
            },
            "goals": {
                "type": "array",
                "maxItems": MAX_GOALS,
                "description": (
                    "What the user wants to achieve this year, one goal per item, "
                    "in their words. Also list them in "
                    "profile.strategic_priorities.current_year."
                ),
                "items": {
                    "type": "object",
                    "required": ["title"],
                    "properties": {
                        "title": {"type": "string", "description": "e.g. 'Launch the hosted version'."},
                        "target": {
                            "type": "string",
                            "description": "How they will know it is done, if they said. Else empty.",
                        },
                        "owner_name": {
                            "type": "string",
                            "description": (
                                "The person's full_name who owns it. Empty means the "
                                "user. Name someone else only when the user did."
                            ),
                        },
                        "department_title": {
                            "type": "string",
                            "description": (
                                "A drafted department's title when the goal clearly "
                                "belongs to it. Else empty."
                            ),
                        },
                    },
                },
            },
            "confidence_notes": {
                "type": "array",
                "items": {"type": "string"},
                "description": (
                    "Things the user should check after reading the draft, one plain "
                    "sentence each (e.g. 'I guessed your main competitors from your "
                    "site.'). Never use field names. Leave out anything the user chose "
                    "not to share."
                ),
            },
            "summary": {
                "type": "string",
                "description": "One short paragraph reading the company back to the user in plain language.",
            },
        },
    },
}

# Sorted by name so the cached tool prefix is stable. ask_ < emit_.
TOOLS: list[dict[str, Any]] = sorted([_ASK_TOOL, _EMIT_TOOL], key=lambda t: str(t["name"]))


def validate_draft(draft: CompanyDraft) -> list[DraftError]:
    """Referential-integrity and bounds errors (empty list = OK).

    Field-level validation already happened in ``model_validate``; this is the
    cross-object layer the commit step relies on, mirroring
    ``fixtures.generator.validate_bundle``. Every error carries both a
    model-facing ``detail`` and a client-facing ``safe`` string — see
    ``DraftError``.
    """
    errors: list[DraftError] = []

    def add(safe: str, detail: str | None = None) -> None:
        errors.append(DraftError(safe=safe, detail=detail or safe))

    if not draft.profile.name.strip():
        add("Your company needs a name.", "profile.name is required")
    if not draft.people:
        add(
            "Add at least one person, and mark which one is you.",
            "at least one person is required",
        )

    all_names = [p.full_name.strip() for p in draft.people]
    if any(not n for n in all_names):
        add("Every person needs a name.", "every person needs a non-empty full_name")
    # Case-INSENSITIVE, matching the key save_onboarding_people upserts on.
    # A case-sensitive check let "JANE DOE" and "Jane Doe" both through, and the
    # upsert then collapsed them onto one row — last write wins, which could
    # land on the non-principal spelling and leave the company with NO principal.
    folded = [n.lower() for n in all_names]
    if len(set(folded)) != len(folded):
        dupes = sorted({n for n in all_names if folded.count(n.lower()) > 1})
        add(
            "Two people have the same name — give them distinct names.",
            f"duplicate full_name(s) in roster: {dupes}",
        )

    principals = [p for p in draft.people if p.is_principal]
    if len(principals) != 1:
        # find_principal_person() backs caller resolution, alert routing, and
        # the scheduler's principal brief. Zero or two is a real breakage.
        add(
            "Mark exactly one person as you.",
            f"exactly one person must have is_principal=true (got {len(principals)})",
        )

    if any(len(n) > MAX_NAME_CHARS for n in all_names):
        add(f"A person's name is too long (limit {MAX_NAME_CHARS} characters).")
    if any(len(p.role) > MAX_ROLE_CHARS for p in draft.people):
        add(f"A person's role is too long (limit {MAX_ROLE_CHARS} characters).")

    # The profile lands in the cached system prompt on every Executive turn, so
    # an unbounded field here is a permanent per-request cost.
    for label, value in (
        ("name", draft.profile.name),
        ("mission", draft.profile.mission),
        ("vision", draft.profile.vision),
        ("industry", draft.profile.industry),
        ("stage", draft.profile.stage),
    ):
        if len(value) > MAX_PROFILE_TEXT_CHARS:
            add(
                f"The company {label} is too long "
                f"(limit {MAX_PROFILE_TEXT_CHARS:,} characters)."
            )

    names = {n.lower() for n in all_names}
    titles = {d.title.strip().lower() for d in draft.departments if d.title.strip()}
    if len(draft.goals) > MAX_GOALS:
        add(f"That's a lot of goals for setup (limit {MAX_GOALS}). Keep the main ones.")
    for g in draft.goals:
        if not g.title.strip():
            add("Every goal needs a name.", "every goal needs a non-empty title")
        if len(g.title) > MAX_GOAL_CHARS or len(g.target) > MAX_GOAL_CHARS:
            add(f"A goal is too long (limit {MAX_GOAL_CHARS} characters).")
        if g.owner_name.strip() and g.owner_name.strip().lower() not in names:
            add(
                "A goal is owned by someone who isn't on the team list.",
                f"goal '{g.title}' owner_name '{g.owner_name}' is not in the roster",
            )
        if g.department_title.strip() and g.department_title.strip().lower() not in titles:
            add(
                "A goal is in a department that isn't on the list.",
                f"goal '{g.title}' department_title '{g.department_title}' "
                "is not a drafted department",
            )
    for d in draft.departments:
        if not d.title.strip():
            add("Every department needs a name.", "every department needs a non-empty title")
        if len(d.title) > MAX_NAME_CHARS:
            add(f"A department name is too long (limit {MAX_NAME_CHARS} characters).")
        if len(d.mission) > MAX_MISSION_CHARS:
            add(
                f"A department description is too long "
                f"(limit {MAX_MISSION_CHARS:,} characters)."
            )
        if d.head_person_name and d.head_person_name.strip().lower() not in names:
            add(
                "A department is led by someone who isn't on the team list.",
                f"department '{d.title}' head_person_name "
                f"'{d.head_person_name}' is not in the roster",
            )
    # Same fallback the store uses, so two titles that both slugify to
    # nothing collide here exactly as they would on insert.
    slugs = [
        slugify(d.title, fallback=DEPARTMENT_SLUG_FALLBACK)
        for d in draft.departments
        if d.title.strip()
    ]
    if len(set(slugs)) != len(slugs):
        dupes = sorted({s for s in slugs if slugs.count(s) > 1})
        add(
            "Two departments have the same name.",
            f"duplicate department title(s): {dupes}",
        )

    return errors


def _extract_tool_call(response: Any) -> tuple[str, dict[str, Any]]:
    """Pull (tool_name, tool_input) out of an Anthropic messages response."""
    for block in getattr(response, "content", []) or []:
        if getattr(block, "type", None) != "tool_use":
            continue
        name = getattr(block, "name", None)
        data = getattr(block, "input", None)
        if name in (ASK_TOOL_NAME, EMIT_TOOL_NAME) and isinstance(data, dict):
            return name, data
    raise InterviewError("The setup assistant did not return a usable response.")


def _prose(response: Any) -> str:
    """The text blocks of a response, joined; empty when there are none."""
    parts = [
        str(getattr(b, "text", "") or "").strip()
        for b in getattr(response, "content", []) or []
        if getattr(b, "type", None) == "text"
    ]
    return "\n\n".join(p for p in parts if p)


def replay_transcript(
    transcript: list[Turn], continue_prompt: str
) -> list[dict[str, Any]]:
    """Replay stored turns as alternating plain-text Messages API turns.

    Shared by every interview-style loop (this one and
    ``workflows/designer.py``). Returns an empty list when nothing is left to
    send; the caller decides what that means.
    """
    # Coalesce consecutive same-role turns. The Anthropic API rejects a
    # non-alternating sequence, and two user turns in a row are reachable in
    # practice — a draft adds no assistant turn on its own, and a turn whose
    # text is blank drops out of the replay below.
    messages: list[dict[str, Any]] = []
    for t in transcript:
        if not t.text.strip():
            continue
        if messages and messages[-1]["role"] == t.role:
            messages[-1]["content"] = f"{messages[-1]['content']}\n\n{t.text}"
            continue
        messages.append({"role": t.role, "content": t.text})
    # A draft records itself as an assistant turn, so the transcript can end on
    # one — e.g. "ask me more questions" then "draft again" without typing.
    # Sending that as a trailing assistant message is a prefill, which the API
    # rejects alongside a forced tool_choice, and semantically asks the model to
    # continue its own summary rather than act.
    if messages and messages[-1]["role"] == "assistant":
        messages.append({"role": "user", "content": continue_prompt})
    return messages


# Prepended to the FIRST user turn when the workspace is in solo mode (one
# person using Open Executive just for themselves — whatever their role).
# User-turn hints rather than a second system prompt, so the cached system
# block stays one constant for both modes. One static constant per role kind
# (the workspace's role_kind, from the role step): no user text is ever
# interpolated into them.
_SOLO_DRAFT_RULE = (
    "In the draft, `people` must hold only them — exactly one person, with "
    "is_principal true — `departments` must be empty, and every goal's "
    "owner_name is empty (theirs)."
)

# No role given (or "other"): find out which kind of principal this is.
SOLO_HINT = (
    "This person is setting up Open Executive just for themselves: only they "
    "will use it. They may run their own business, lead a function inside a "
    "larger organisation, or work independently as an advisor or fractional "
    "executive — if their words do not make it clear, ask. "
    + _SOLO_DRAFT_RULE
    + " The company profile describes the organisation they work in: their "
    "own business or practice, or their employer. Do not ask about a "
    "leadership team or departments; ask instead about their role and what "
    "they are responsible for, that organisation, and their top goals."
)

SOLO_ROLE_HINTS: dict[str, str] = {
    "owner": (
        "This person is setting up Open Executive just for themselves, and "
        "they own and run the business. "
        + _SOLO_DRAFT_RULE
        + " Do not ask about a leadership team or departments; ask instead "
        "about what they offer, who their customers are, their pricing, and "
        "their top goals."
    ),
    "in_house": (
        "This person is setting up Open Executive just for themselves. They "
        "are an executive inside an organisation they do not own, so the "
        "company is their employer: draft the company profile for that "
        "organisation. "
        + _SOLO_DRAFT_RULE
        + " Do not add their manager, peers or team as people. Do not ask "
        "about the company's leadership team or departments, and do not ask "
        "about cash, runway or fundraising as if the business were theirs. "
        "Ask instead about their organisation (what it does, its industry "
        "and size), the function they lead and what they are responsible "
        "for, who they report to, how big their team is (as context, not a "
        "roster), what they are measured on, and their top goals."
    ),
    "independent": (
        "This person is setting up Open Executive just for themselves. They "
        "work independently — an advisor, consultant or fractional executive "
        "who serves clients — so the company is their own practice. "
        + _SOLO_DRAFT_RULE
        + " Clients are not people in the draft. Do not ask about a "
        "leadership team or departments; ask instead about their practice "
        "and what they offer, who their clients are and how they work with "
        "them, how they price their work, and their top goals."
    ),
}


def solo_hint(role_kind: str | None) -> str:
    """The solo hint for the principal's role kind: the tailored one, else
    the role-neutral ``SOLO_HINT`` (no kind, or ``other``)."""
    return SOLO_ROLE_HINTS.get(role_kind or "", SOLO_HINT)


def _build_messages(
    transcript: list[Turn],
    existing_profile: CompanyProfile | None,
    *,
    solo: bool = False,
    role_kind: str | None = None,
) -> list[dict[str, Any]]:
    """Replay the transcript as plain text turns.

    The solo hint (when ``solo``; tailored to ``role_kind``) and an existing
    profile are prepended to the FIRST user turn, never put in the cached
    system block (see module docstring).
    """
    messages = replay_transcript(transcript, _CONTINUE_PROMPT)
    if not messages:
        raise InterviewError("The setup session has no conversation yet.")
    preamble: list[str] = []
    if solo:
        preamble.append(solo_hint(role_kind))
    if existing_profile is not None and not existing_profile.is_empty():
        block = existing_profile.to_prompt_block()
        if block:
            preamble.append(
                "The user is re-running setup. Their current saved profile "
                "is below — confirm or update it rather than starting over, "
                "and do not re-ask what it already answers.\n\n"
                f"{block}"
            )
    if preamble:
        messages[0] = {
            "role": messages[0]["role"],
            "content": "\n\n".join(preamble) + f"\n\n---\n\n{messages[0]['content']}",
        }
    return messages


def transcript_chars(transcript: list[Turn]) -> int:
    return sum(len(t.text) for t in transcript)


async def advance(
    transcript: list[Turn],
    *,
    existing_profile: CompanyProfile | None = None,
    force_draft: bool = False,
    questions_asked: int = 0,
    model: str | None = None,
) -> Question | CompanyDraft:
    """Run one interview turn.

    Returns a ``Question`` to put to the user, or a ``CompanyDraft`` to review.
    Raises ``InterviewError`` / ``InterviewTimeout`` — both with fixed,
    input-free messages.
    """
    from openexecutive.audit.usage import log_model_usage
    from openexecutive.providers.registry import get_provider

    settings = get_settings()
    agent = OnboardingInterviewerAgent()
    resolved_model = model if model is not None else agent.effective_model()
    system_text = agent.effective_system_prompt()
    provider = get_provider(resolved_model)

    from openexecutive.memory.workspace_settings import get_workspace

    workspace = get_workspace()
    messages = _build_messages(
        transcript,
        existing_profile,
        solo=workspace.mode == "solo",
        role_kind=workspace.role_kind,
    )

    # The one place tool_choice varies — see the module docstring.
    must_draft = (
        force_draft
        or questions_asked >= MAX_QUESTIONS
        or transcript_chars(transcript) >= MAX_TRANSCRIPT_CHARS
    )
    tool_choice: dict[str, Any] = (
        {"type": "tool", "name": EMIT_TOOL_NAME} if must_draft else {"type": "any"}
    )

    async def _call() -> Any:
        return await provider.messages_create(
            model=resolved_model,
            max_tokens=_MAX_TOKENS,
            system=[
                {
                    "type": "text",
                    "text": system_text,
                    "cache_control": {"type": "ephemeral"},
                }
            ],
            tools=TOOLS,
            tool_choice=tool_choice,
            messages=messages,
        )

    for attempt in range(2):
        try:
            response = await asyncio.wait_for(
                _call(), timeout=settings.interview_timeout_s
            )
        except TimeoutError as exc:  # asyncio.TimeoutError is an alias since 3.11
            raise InterviewTimeout(
                "The setup assistant took too long to respond. Try again."
            ) from exc
        except InterviewError:
            raise
        except Exception as exc:
            # Type name only: a provider error can quote the request body,
            # which carries the user's financials.
            logger.error("onboarding interview: provider call failed (%s)", type(exc).__name__)
            raise InterviewError(
                "The setup assistant is unavailable right now. Try again."
            ) from exc

        log_model_usage(
            response,
            model=resolved_model,
            actor=ONBOARDING_INTERVIEWER_AGENT_ID,
            iteration=attempt,
        )

        try:
            name, raw = _extract_tool_call(response)
        except InterviewError:
            # No usable tool call (the model answered in prose, or named another
            # tool). Block types only in the log: the text can hold the user's
            # financials.
            logger.error(
                "onboarding interview: no tool call (stop_reason=%s, blocks=%s)",
                getattr(response, "stop_reason", None),
                [getattr(b, "type", None) for b in getattr(response, "content", []) or []],
            )
            prose = _prose(response)
            if attempt == 0:
                messages = [
                    *messages,
                    {"role": "assistant", "content": prose or "(no answer)"},
                    {
                        "role": "user",
                        "content": (
                            "Call exactly one tool: "
                            + (EMIT_TOOL_NAME if must_draft else f"{ASK_TOOL_NAME} or {EMIT_TOOL_NAME}")
                            + ", now."
                        ),
                    },
                ]
                continue
            if (
                prose
                and not must_draft
                and len(prose) <= _MAX_PROSE_QUESTION_CHARS
                and prose.endswith("?")
            ):
                # The model asked in plain words twice running: the person can
                # still answer it, so show it rather than a dead end. A long
                # reply, or one that does not end in a question mark, is
                # reasoning or a half-made draft: it is never shown.
                return Question(question=prose)
            raise

        if name == ASK_TOOL_NAME:
            if must_draft:
                # tool_choice forced the emit tool; a question here means the
                # provider ignored it. Retry once WITH feedback — replaying the
                # identical request would just reproduce the same output.
                if attempt == 0:
                    messages = [
                        *messages,
                        {"role": "assistant", "content": raw.get("question", "")},
                        {
                            "role": "user",
                            "content": (
                                "No more questions — draft from what you have "
                                "and leave anything you don't know empty. Call "
                                f"{EMIT_TOOL_NAME} now."
                            ),
                        },
                    ]
                    continue
                raise InterviewError(
                    "The setup assistant could not produce a draft. "
                    "Try adding a bit more detail, or use the step-by-step form."
                )
            try:
                question = Question.model_validate(raw)
                if not question.question.strip():
                    # An empty question would store a blank assistant turn that
                    # drops out of the replay, breaking role alternation.
                    raise ValueError("empty question")
                return question
            except (ValidationError, ValueError) as exc:
                logger.error(
                    "onboarding interview: malformed question (%s, fields=%s)",
                    type(exc).__name__,
                    [".".join(map(str, e["loc"])) for e in exc.errors()]
                    if isinstance(exc, ValidationError)
                    else [],
                )
                if attempt == 0:
                    continue
                raise InterviewError(
                    "The setup assistant did not return a usable response."
                ) from exc

        errors: list[str]
        try:
            draft = CompanyDraft.model_validate(raw)
        except ValidationError as exc:
            # exc is NOT interpolated into any raised message — it embeds the
            # offending values, which include the user's financials.
            logger.error(
                "onboarding interview: draft failed schema validation (%s)",
                type(exc).__name__,
            )
            errors = [str(exc)]
        else:
            draft_errors = validate_draft(draft)
            if not draft_errors:
                return draft
            errors = [e.detail for e in draft_errors]
            logger.info("onboarding interview: draft has %d consistency error(s)", len(errors))

        if attempt == 0:
            messages = [
                *messages,
                {"role": "assistant", "content": json.dumps(raw)[:_REPAIR_ECHO_CHARS]},
                {
                    "role": "user",
                    "content": (
                        "That draft was not usable:\n- "
                        + "\n- ".join(errors)
                        + f"\n\nFix them and call {EMIT_TOOL_NAME} again."
                    ),
                },
            ]
            tool_choice = {"type": "tool", "name": EMIT_TOOL_NAME}
            must_draft = True
            continue

        raise InterviewError(
            "The setup assistant could not produce a valid draft. "
            "Try rephrasing, or use the step-by-step form instead."
        )

    # Unreachable: every branch above returns or raises on attempt 1. Kept
    # so the function has a provable return type.
    raise InterviewError("The setup assistant could not produce a valid draft.")